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 locations:

• Unix: /var/sos-berlin.com/js7/agent_<port>/state
• Windows: C:\ProgramData\sos-berlin.com\js7\agent_<port>\state
• Note that a different location may have been specified when setting up the Agent.

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

• If a Controller was connected to the Agent then the Controller will know the respective orders and status information.
• If a Controller has not been 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 loss of the connection with the Controller and the 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 JS7_AGENT_DATA/work/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

Issues occurring during initial operation are described in 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 for an Agent has been completed successfully and due to some weird reason the Agent's journal is deleted later on, then this may cause coupling between Controller and Agent to be lost.
  • 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 at which the Agent is restarted the JOC Cockpit and Controller have to be active and connected. If the problem with coupling 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 as before.
• Implication: This operation does not recover 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 cause coupling between Controller and Agent to be lost.
  
  • 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 JS7_AGENT_DATA/state directory. At the point in time at which the Agent is restarted the JOC Cockpit and the Controller have to be active and connected. If the problem with coupling 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 does not recover 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 a status, such as "Coupling failed", "Shutdown".

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 effectively means that the Controller hijacks the Agent and drops any journal information for 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 the JOC Cockpit and from the Controller the Agent can be restarted and can be registered with the same steps as described for initial operation.