Connections Configuration & Maintenance

Maintaining Agents

Clicking on an Agent in the Ganymede web app UI opens up a page displaying the Agent's configuration. This page allows you to view the Agent's configuration, logs, and build history, as well as update the configuration of Connections associated with the Agent.

Updating Agents

To modify Agent settings after creation, select the desired Agent in the Ganymede web app UI to update the Agent. Upon clicking

Save

, the Agent will be built and then made available for download.

Agents can also be archived or disabled.

Archived Agents cannot be updated, but the Agent's connections can still communicate with Ganymede Cloud. All associated connections for these Agents will continue to run, but the Agent can no longer be modified. Archived agents can be restored to an active state by selecting the desired Agent and clicking on the Restore Agent link.

Disabled Agents cannot be updated and its connections can no longer communicate with Ganymede Cloud.

Updating Connections

To update a Connection, select the desired Connection in the Connections tab and click the

Edit Connections

button. You can update the following fields on a connection from the Ganymede UI:

 

Updating existing Connections

Every time the Connection contacts Ganymede with a health check-in, Ganymede responds with any changes that the Connection needs to incorporate. There are three level of changes that can occur.

• Core Version Update: The core version corresponds to the underlying Agent code developed by Ganymede. These changes are new features or patches applied across all Agents, but each Agent manages which core version it is pinned to.
• Agent Configuration Update: Updated through the Agent page or the Agent's processor notebook. This configuration applies to all Connections for that Agent. For example, if an Agent that runs flow upon file capture is updated to run a new flow, then all compatible Connections will begin to run the new flow.
• Connection Configuration Update: Updates made to the Connection's configuration will only update a single Connection, rather than the Agent that it was generated from. Different Connection-level variables and labels can be configured for Connections associated with the same Agent.

There are two types of remote updates that occur based on the type of update - full update or runtime update.

Full Update

Compatibility

• Agents installed with core v4.8.0 or later.
• The core version of the installed connection must align with the major version of the core version of the agent Ganymede's UI. Otherwise, a breaking change requires reinstallation.
• Auto-update is enabled for the agent.

How full updates are initiated

A full update is only triggered for a "Core Version Update." The remote update is not initiated without user intervention.

note

In the Ganymede UI, an Agent's core version is listed on the right side of the page in a section called "Core Agent Infrastructure." If the agent is not up to date to the latest available core version, an "Upgrade" button will appear. The text will inform users what version is available and what version the agent is currently pinned to.

Once a user clicks to Upgrade an agent, all connections will be told of the new version on their next status ping.

Update Process

A full update requires reinstalling the executable, but Ganymede now handles this installation seamlessly; as such, after the full update is requested, it is performed for existing Connections after the executable builds. When a Connection receives a command to perform a full update, it continues to operate normally while attempting to start the new version in parallel after verifying the validity of the command and the executable. Once the new version registers with Ganymede as operational, the old Connection stops. The new executable also cleans up the artifacts of the old executable and its dependencies.

There may be a disruption to any ongoing processing on the Agent during the update, so it is safest to request it when no activity occurs on the instruments where the Agent Connections are running.

If the new Connection fails to start, the old Connection will resume, and the system will not attempt a full update again on that version to avoid putting the Connection in a precarious state.

Runtime Update

Compatibility

• Agents installed with core v1.0.0 or later
• The core version of the installed connection must match the core version of the agent Ganymede's UI
• Auto-update is enabled for the agent

How runtime updates are initiated

Changes in the Agent configuration, including the Agent user-defined code, or Connection configuration, will be sent to the Connection on its next status ping as soon as they are saved.

Update Process

A runtime update does not require any process restart or executable reinstallation. As a result, the Connection can accept changes to configuration while continuing normal operations. The update is validated for integrity and the information is stored locally for access if the Connection restarts for any reason.

Viewing Agent History

Viewing Build History

Each iteration of Agent build can be viewed in the History tab of the Agent. This view provides context for each change, either as a log of the configuration change or through a custom commit message from the Agent notebook.

 

Configuration differences between two Agent builds can be viewed for audit or debugging purposes by clicking

button.

 

Viewing Historical Code

The code corresponding to historical commits can be viewed by clicking the

View Code

button. This opens up a modal which allows you to copy the code from the historical commit to the clipboard if desired.

Maintaining Agent Connections

Connection status updates and logs can be accessed in the Ganymede web app UI.

 

Connection data can be viewed by clicking on the appropriate connection card in the Connections tab.

 

This opens up a page displaying parameters associated with the Connection:

Connection Details

Field Name	Description
Status	Current running status of the installed Connection
Recent Activity	Provides links to associated Flows and Files
Agent	Agent associated with the Connection
Connection Version	The version of the Connection configuration currently running, updated when the Connection configuration is modified
Agent Version	The version of the Agent configuration from which the Connection is running, updated when the Agent configuration or processor code changes
Core Version	The version of the core Agent infrastructure from which the Connection is running; requires a reinstall to update
Started At	UTC Time when the Connection was first registered in Ganymede
Last Status Ping	Time when last status ping was received from the Connection by Ganymede
PC Name	Hostname of the machine hosting the connection
MAC Address	MAC address of the machine hosting the connection
Machine IP	IP address that Ganymede sees from the machine hosting the connection
Install Path	Directory path on the hosting machine where the executable was installed on
Service Name	Windows service name for the Connection on the hosting machine

Below the Connection Details box, you'll find Connection-specific configurations:

• Name: Name of the Agent associated with the Connection
• Connection File Tags: Tags placed on files uploaded by the Connection
• Variables: Key-value pairs that can be referenced in user-defined code. These are also used to specify reserved keywords for the Connection, if applicable.
• Labels: Strings that can be used to group Connections in the Ganymede UI
• Emails: Email addresses to notify when the Connection encounters an error or has an update in its Connection status. These email addresses are also used by the notify function found in the agent_sdk.
  • Send Connection Status Email Notifications: When enabled, Ganymede will send an email notification to the specified email addresses when the Connection status changes.
  • Connection Offline Alert Timeout (min): The number of minutes that the Connection must be offline before an email notification is sent.
  • Send Email Notification on Connection Shutdown: When enabled, Ganymede will send an email notification to the specified email addresses when the Connection enters a shutdown state.

Connection Status

Agents send a heartbeat message to Ganymede Cloud every 30 seconds to inform their status. The status of an Agent can be one of the following:

• Live: The Agent is currently running and communicating with Ganymede Cloud
• Disconnected: Ganymede Cloud has not received a status update from the Agent in the last 65 seconds
• Shutdown: The Agent was intentionally shut down, possibly due to a user shutting down the computer, manually stopping the Agent service, or encountering a known exception.
• Deprecated: The Agent has been disabled in Ganymede UI as described in the Updating Agents section.

Connection Notifications

For Agents v5.1.7+, you can create send email notifications to all subscribers by using the agent_sdk.notify method in your user-defined processor code. For example:

import agent_sdk

def execute(**kwargs) -> Optional[TriggerFlowParams]:  # type: ignore
     # ... code here that checks for some condition
    if(some_condition):
        agent_sdk.notify(f"The file {file_name} is missing an experiment ID")

Viewing Logs

Logs can be found on the Logs tab for each Agent and Connection, and filtered on by both log severity and date. For Agents v4.9+, user-defined log messages can be added by referencing the corresponding agent_sdk method for logging. Descriptions of log messages can be found on the Agent Logs page.

The Instrument tab within the Connection logs page contains downloadable text files for the Connection's logs, enabling you to search over logs locally if desired.

Uninstalling Agent Connections

Windows

A Connection can be uninstalled and its associated service removed through the “Add or Remove Programs” panel from the Control Panel.

 

After uninstalling the Agent, the Ganymede folder will remain in the Program Files directory. You can also run the unins000.exe file in the installation folder to remove the Connection and all other previously installed versions.

warning

By default, the installation directory of the Connection is retained, so that logs associated with Connection are kept on the instrument PC. Removing the Ganymede folder will also remove these logs.

info

If the Connection service continues to appear in the Services panel after uninstalling the Connection, you can remove it by running the following command in the Command Prompt:

sc delete <service_name>

Linux

To uninstall the Agent, stop the systemd service associated with the Agent and remove the service file from /etc/systemd/system/.

# to stop the Agent Connection service
sudo systemctl stop ganymede_example_agent.service

# remove the service file
sudo rm /etc/systemd/system/ganymede_example_agent.service