Introduction

The Agent's journal holds information about scheduling objects such as workflows, jobs and orders:

• scheduling objects are deployed from JOC Cockpit via a Controller.
• orders are submitted to indicate the start time of workflows.

The Agent's journal is available from a number of files in the following location:

• Unix: /var/sos-berlin.com/js7/agent_<port>/state
• Windows: C:\ProgramData\sos-berlin.com\js7\agent_<port>\state
• Users can choose different locations when setting up an Agent.

When an Agent's journal is deleted or damaged then this indicates severe loss:

• If a Controller was connected to the Agent then the Controller will know the respective orders and status information.
• If no Controller was connected to the Agent for some time then there is no way in knowing what jobs have been executed by the Agent for the time between the connection loss with the Controller and loss of the Agent's journal.
  • The Agent's agent.log file holds information about orders and jobs being processed.
  • For each job a pair of temporary files for output to the stdout and stderr channels is created in the Agent's tmp directory. These files are dropped after job execution if the Agent can report back execution results to a Controller and otherwise remain in place.

Initial Operation

Find information from the JS7 - How to troubleshoot Agent Initial Operation article.

Ongoing Operation

Scenarios in this section apply after an Agent has been successfully registered with a Controller during JS7 - Initial Operation.

Loss of Agent Journal

• Problem: If initial operation is successfully completed for an Agent and due to some weird reason the Agent's journal later on is deleted then this may fail the coupling between Controller and Agent.
  • The JOC Cockpit will report the Agent status "Shutdown". When hovering the Agent status with the mouse then the full error message will be displayed, for example
    • AgentNotDedicated: This Agent has not been created yet.
• Solution: This problem can be resolved by restarting the Agent. At the point in time of Agent restart the JOC Cockpit and Controller have to be active and connected. In case that the problem to couple the Agent persists, then re-register the Agent from the JOC Cockpit using the "Edit" action menu and submit the same settings for the Agent.
• Implication: This operation includes to loose information about past job executions that have not yet been added to the JOC Cockpit history.

Damage to Agent Journal

• Problem: Assume that initial operation is successfully completed for an Agent and due to some weird reason the Agent's journal later on is damaged. This may fail the coupling between Controller and Agent.
  • The JOC Cockpit will report the Agent status "Coupling failed" or "Shutdown". When hovering the Agent status with the mouse then the full error message will be displayed, for example
    • AgentNotDedicated: This Agent has not been created yet.
• Solution: This problem can be resolved by removing any files in the Agent's ./state directory. At the point in time of Agent restart the JOC Cockpit and the Controller have to be active and connected. In case that the problem to couple the Agent persists, then re-register the Agent from the JOC Cockpit using the "Edit" action menu and submitting the same settings for the Agent.
• Implication: This operation includes to loose information about past job executions that have not yet been added to the JOC Cockpit history.

Troubleshooting Measures

Resetting Agents

If an Agent can be accessed by the Controller but cannot be coupled then the JOC Cockpit will display this status, for example indicating "Coupling failed", "Shutdown" or similar status information.

Reset

Using the "Reset" operation from the Agent's action menu in the JOC Cockpit "Manage Controllers/Agents" page performs the following operations:

• The Controller will try to revoke any orders running with that Agent. Tasks running for orders with the Agent will be killed.
• The Controller will try to revoke any scheduling objects form the Agent, for example workflows, file order sources etc.
• The Agent will refresh its journal, however, the registration with a Controller is maintained.
• The Agent will restart.
• The Agent will receive scheduling objects such as workflows and orders from the Controller to synchronize its journal.

Note: This operation will be successful if the Agent is registered with the same Controller. If the Agent previously was registered with a different Controller then the Agent will deny this operation.

Forced Reset

Using the "Reset Forced" operation from the Agent's action menu in the JOC Cockpit "Manage Controllers/Agents" page performs the following operations:

• The Agent will delete its journal.
• The Agent will restart.
• The Agent will accept registration by the current Controller.
• The Agent will receive scheduling objects such as workflows and orders from the Controller to synchronize its journal.

Note: This operation includes the danger of unintentionally choosing an Agent that is registered with a different Controller, for example if different Controllers for production and non-production environments are used. This operation includes that the Controller hijacks the Agent and drops any journal information of that Agent. This operation can safely be used if no workflows and tasks are present with an Agent and for example the Controller ID should be changed.

Recreating Agents

Agents can be permanently deleted from a Controller, for example in case of de-commissioning.

Using the "Delete" operation from the Agent's action menu in the JOC Cockpit "Manage Controllers/Agents" page performs the following operations:

• The Agent will delete its journal.
• The Agent will shutdown.
• The Controller removes any information about registration of the Agent.
• The JOC Cockpit removes the Agent entry from the list of Agents with the given Controller.

After deleting the Agent from JOC Cockpit and from the Controller the Agent can be restarted and can be registered with the same steps as for initial operation.