📘

NOTE

To see links to other release notes, see Tetra Agent and Tetra Data Release Notes.

v4.2.4

Release Date: 23 February 2023 (Last updated: 2 April 2024)

📘

NOTE

• Empower Agent v4.2.4 will cause upload of historical data from 3D channels which likely will cause an increase in upload activity and potentially affect latency of live instruments. If you have questions or concerns, contact your TetraScience Customer Service Manager.
• For any customers using empower-message-center and Agent v4.x should update the protocol to 1.0.1 to have correct parsing of the project name

🚧

DISCLAIMER

New Protocol versions may be released by TetraScience that are also compatible with the existing Agent version. For latest protocol compatibility, refer to the Protocol Readme or contact your TetraScience Customer Service Manager.

Versions Supported in Release

• Empower Agent v4.2.4
• Empower-raw-to-ids Protocol 3.10.4
  • Task Script v9.1.4
  • IDS v10.0.0
• Empower-message-center Protocol 1.0.1
• Empower-audit-trail Protocol 1.0.0
• Empower-project-user Protocol 1.0.0

What's New?

TetraScience has released its next version of the Empower Agent version 4.2.4 and Protocol version 3.10.4. The changes include bug fixes to the Empower Agent and Task Script.

We have also made changes to the Empower Agent Release Notes as it will now include the recommended Protocol version (TaskScript and IDS) that is compatible with the Empower Agent.

Enhancements

Protocol

Empower-raw-to-ids

• IDS
  • Add datacubes[*].scale_to_uv to IDS from Channels[*].ScaletouV.
  • Add results[*].users[*].name and results[*].users[*].type to hold user information from results user.name | AcquiredBy.

Bug Fixes

Protocol

Empower-raw-to-ids

• Task Script
  • Added a warning when datacubes[*].measures[*].unit is null
  • Now allows the task script to complete when datacubes[*].measures[*].unit is null
  • Fixes a defect for spectrophotometers and other light-based detectors when measured units are AU
  • Fixes a defect that populated the following IDS fields' values incorrectly to false when the RAW data value is null or non-existent in the primary data:
    • method.setups[*].bubble_detect
    • method.setups[*].enable_sample_temp
    • method.setups[*].enable_column_temp
    • method.setups[*].inst_on_status
    • method.setups[*].monitor_parameter_1
    • method.setups[*].monitor_parameter_2
    • method.setups[*].needle_wash
    • method.setups[*].use_events
    • method.setups[*].use_channel_monitor_1
    • method.setups[*].use_channel_monitor_2
    • method.processing[*].parameter.system_suitability.calculate_peak_statistical_moments
    • method.processing[*].parameter.system_suitability.calculate_suitability
    • method.processing[*].parameter.system_suitability.calculate_unknowns
    • method.processing[*].parameter.system_suitability.calculate_usp_ep_and_jp_signal_to_noise
    • method.processing[*].parameter.system_suitability.flag_outside
    • method.processing[*].parameter.system_suitability.use_noise_centered_on_peak_region_in_blank_injection
  • Added the following string to boolean conversion rules:
    • Convert '1' and 'pass' to true
    • Convert '0' and 'fail' to false
    • Added case-insensitive conversion (for example, 'FALSE' and 'false' will convert to false)
    • These boolean conversion rules apply to the following fields:
      • results[*].faults
      • results[*].processing_locked
      • results[*].processing_method.manual
      • method.setups[*].bubble_detect
      • method.setups[*].enable_sample_temp
      • method.setups[*].enable_column_temp
      • method.setups[*].inst_on_status
      • method.setups[*].monitor_parameter_1
      • method.setups[*].monitor_parameter_2
      • method.setups[*].needle_wash
      • method.setups[*].use_events
      • method.setups[*].use_channel_monitor_1
      • method.setups[*].use_channel_monitor_2
      • method.processing[*].parameter.system_suitability.calculate_peak_statistical_moments
      • method.processing[*].parameter.system_suitability.calculate_suitability
      • method.processing[*].parameter.system_suitability.calculate_unknowns
      • method.processing[*].parameter.system_suitability.calculate_usp_ep_and_jp_signal_to_noise
      • method.processing[*].parameter.system_suitability.flag_outside
      • method.processing[*].parameter.system_suitability.use_noise_centered_on_peak_region_in_blank_injection

Empower-message-center-raw-to-ids

• Task script
  • Update to use task script common/empower-message-center-raw-to-ids:v1.0.1, which fixes an issue for parsing Project Name when the project name is either a top-level field in RAW JSON or when it is in the Message Center array.

Empower Agent

• AG-2608: v4.2.2 fixes a bug where the agent does not extract channel values for the last time point and last wavelength for 3D channels. This bug fix includes the remediation logic in v4.2.4 to automatically re-upload the injections which have been uploaded to TDP and the injection contains 3D Channel Type, including both 3D PDA and 3D MS. After an upgrade, remediation will kick off automatically, all injections with 3D channels will be re-uploaded. The normal operation of the agent should not be impacted.
• AG-2641: If Empower returns error code 105 or 208 while trying to connect and access a particular project, which may be because of an unhandled internal error, the agent will not try to connect immediately. The agent will attempt to connect progressively after 2 seconds (maximum 2 retries), allowing Empower to recover from the error. The agent will move to the next project scan if error code 105 or 208 persists for a particular project after maximum retries. The agent will again try to login and access that project which produced the error code, during the next scan iteration.
• AG-2663/AG-2629: While scanning projects with large number of injections, there may be out of memory errors. In agent v4.2.4, the memory usage while fetching injections have been optimized to avoid out of memory errors. (Issue #2147, Issue #2257)
• AG-2674: The agent may miss injections when Empower is still acquiring data from a live, connected instrument. In agent v4.2.4, the agent will look for all injections for a project, if the time between last audit change for the project and current scanning time is less than Max Acquisition Hours setting. As part of remediation of data acquired using previous version of the agent, v4.2.4 agent will query the injections from projects again to ensure no injections are missed. (Issue #2174)
• AG-2694: In Empower 3 pre SR3 versions, Message Center has a date/time field called “Time”. In Empower 3 SR3 and later versions, the field has been renamed “Date”. The agent can now persist either of these fields based on the Empower version it is connecting to. The RAW JSON in v4.2.4 contains Time and Date fields for data from pre Empower 3 SR3 and contains Date field for data from Empower 3 SR3 and above.
• AG-2695: In earlier agent versions Method.ModifiedBy for Instrument Method, Processing Method and SampleSet Method may have been extracted inconsistently. This is fixed in v4.2.4.
• AG-2708: The Empower toolkit login call may get hung, making the agent unresponsive for a period of time. The agent now has a timeout of 300 seconds for each login attempt and will abort the login call if it does not get a response within this time. The agent will retry the login in the next attempt.
• AG-2720: Due to Empower internal error some Empower project audit trail action entries may have blank details. If the agent encountered such an audit record during scan in previous versions, the scan would raise error and not detect changes for that particular project. In agent v4.2.4, if the scan finds an audit in Empower with no details, it will skip that audit, log a warning message and continue to fetch the next entry without erroring out.
• AG-2751: This fixes a bug, where when the Empower Agent is scanning projects in Empower, acquiring data from a live instrument, the Agent doesn’t defer the generating till the injection is completed. The fix generates the injection when the injection is completed or the Max Acquisition Hours have passed after the last data acquisition project audit trail recorded for that project. (Issue #2284, Issue #2289)
• AG-2760: The agent uses child executor processes spawned from the host process (main process for the agent software) to handle generation of RAW JSONs. In certain race conditions in earlier versions of agents, when the host process was terminated, child executor processes may still continue to run in the background. In v4.2.4, this is fixed to always terminate child executor processes when the host process is stopped. Any generation being processed by the halted executor processes will be taken up and generated when the agent is started again.

Known and Possible Issues

Protocol Known and Possible Issues

Empower-raw-to-ids

• Task Script
  • Units are not sent from the Empower toolkit and are mapped as constants in the IDS .json data based on the values from the software. Two fields, results[*].peaks[*].amount.unit and results[*].peaks[*].concentration.unit, are set by the user in the Empower Software and are assumed to be mg/ml in the mapping.
  • Assignment of the following fields is dependent on the value in the raw file location Channels[*].DetUnits:
    • datacubes[*].measures[0].name
    • datacubes[*].dimensions[0].name
    • datacubes[*].dimensions[0].unit
  • There is a limited set of units that are currently expected in the Channels[*].DetUnits field. If an unexpected unit is found then the above fields will be populated with null. The supported units follow:
    • LSU
    • Intensity
    • PSI
    • psi
    • psi [a]
    • °C
    • °C
    • °F
    • °F
    • V
    • kV
    • uV
    • MV
    • mV
    • mV(uS)
    • pA
    • uA
    • µA
    • nC
    • counts
    • bar
    • mAU
    • AU
    • au

Empower-message-center-raw-to-ids

• Task Script
  • For versions 1.0.0 and 1.0.1 of the empower-message-center-raw-to-ids task script assumes that the RAW JSON will be generated per project. In Agent v4.2.2 and above RAW JSONs are generated per project, in Agent v4.2.1 and below RAW JSONs can be generated for multiple projects.

Empower Agent Known and Possible Issues

• When the agent generates RAW JSONs, the agent uses the Sample Set Method name to include the Sample set method information in the RAW JSON. This is the only toolkit method available. Potentially user might have changed the Sample Set Method. If you are using the Sample Set Method in the RAW JSON or IDS JSON, we recommend you compare the SampleSet.SampleSetMethodDate in the RAW JSON and the sample.set.method.created_at in the IDS JSON with the time of the injection to confirm which Sample Set Method is referred to.
• Empower Agent v4.x defined these 3 fields with data type based on sample data TetraScience has, however, sometimes, these data types may not apply to your Empower data. In these cases, Empower agent will put null in the RAW JSON (starting from v5.x of the Empower agent, all values from Empower will be extracted as string, thus avoiding possible issues related to data variation).
  i. Peaks.PeakLevel
  1. Based on sample data, Empower Agent v4.x defined it as float, however, sometimes, this field can contain string-like information.
  ii. Peaks.CorrectArea
  1. Based on sample data, Empower Agent v4.x defined it as float, however, sometimes, this field can contain string like information.
  iii. InstrumentMethod.InstrumentMethodSetup[*].NeedleWash
  1. Based on sample data, Empower Agent v4.x defined it as boolean, however, sometimes, this field can contain string like information.
• For some data fields, the trailing zeroes may be dropped in RAW JSON (non-zero digits will not be dropped). This may happen for following fields (starting from v5.x of the Empower agent, all values from Empower will be extracted as string, thus avoiding possible issues related to data variation)
  i. Peaks.RetentionTime
  ii. Peaks.KPrime
  iii. Peaks.AreaPercent
• The agent management console may become unresponsive due to toolkit login hanging when accessing Empower. During that time, close the management console from Windows task manager Ts.Link.Empower.Agent.WinApp (32-bit) and restart the management console again.
• If there are a large number of results with an injection (in the order of several thousands), the RAW JSON generation of that injection may hang. TetraScience is working on addressing this in a future version of the agent.
• Sample Set Method information for an Injection through the toolkit provides the Sample Set Method name of the approved Sample Set Method version instead of the Sample Set Method ID of the version used to setup the Sample Set. This may or may not be the Sample Set Method version that was actually used for the Sample Set in the Injection.
• If agent is configured to use S3 direct upload and GDC together, the agent upload job may hang, when maximum allowed value of 25 processors is configured in the agent. In this scenario, it is recommended to turn off S3 direct upload option. TetraScience is working on addressing this in a future version of the agent.
• If the Empower project name has non-ASCII characters (e.g. accents, dieresis etc.), the order of projects displayed in Empower project browser and Agent management console may not be same.
• Empower 3 pre SR3 versions do not have Injection or Channel status for the agent to understand when the data acquisition from live instrument is complete. To ensure that incomplete data is not uploaded to TDP when the agent is generating data for injection acquired from a live instrument by Empower 3 pre SR3, or an injection whose data is modified as part of processing after data acquisition, the agent will defer the data generation for the time specified in the Max Acquisition Hours setting from the latest project audit trail.
• When the Agent fetches Channel data and gets a non-Toolkit exception such as an Out of Memory error, the Injection RAW file it generates has an empty Channel data cube.

Operating Suggestions

Empower Agent

• If you are not interacting with the agent management console UI frequently, we suggest to start the agent, close the management console UI and let it run in the background.
• If Empower server or client is under maintenance, we suggest to stop the Empower agent. Remember to start the agent when Empower is back online. The unfinished tasks will be resumed by the agent once it is started again.

Upgrade Considerations

To upgrade this Agent, see this document.

Other Release Notes

• To update the protocol refer to the edit pipeline page
• Release notes for other Tetra components are here.