Introduction

• Initial Operation is performed after installation of the JS7 Controller, Agent and JOC Cockpit - the procedure is described in the JS7 - Initial Operation article.
• If there are issues while registering the Agents then the Workflow will not be executed as the Agent is the product in JS7 which executes workflows, stores information about execution results and order state transitions in its journal and passes results to the Controller.

Troubleshooting

After registering an Agent its status can be checked from the JS7 - Dashboard and from the Resources->Agents sub-view. When registering Agents a number of misconfigurations can occur.

Operations to register Agents are performed from the JOC Cockpit "Manage Controllers/Agents" page which is available from the user menu in the upper right-hand corner of the GUI. Administrative permissions are required to be able to see and to use this page.

User Errors

Specifying the wrong Agent URL

• Problem: The JOC Cockpit requires that Agents are registered by their URL, e.g. http://<host>:<port> or https://<host>:<port>. If the wrong URL is specified when registering an Agent, e.g. if the port is wrong or if the hostname is wrong, then the Agent status "Coupling failed" will be reported. When hovering the Agent Status with the mouse then the full error message will be displayed. For example, when using the wrong hostname an error will be displayed such as.
  • akka.stream.StreamTcpException: Tcp command [Connect(localhst:5674,None,List(),Some(10 seconds),true)] failed because of java.net.UnknownHostException: localhst [suppressed: TCP Connect localhst:5674: java.net.UnknownHostException: localhst]
    
  • This error message will also be shown in the Controller's log file, e.g. in the JS7_CONTROLLER_DATA/logs/controller.log file - see the JS7 - Log Files and Locations article.
    
    
    
    
• Solution: To resolve this error click the "Edit" action menu item for the respective Agent and enter the correct URL for the Agent.

Specifying an HTTPS protocol while the Agent is running for HTTP or vice versa

• Problem: When adding the URL for an Agent frequent misconfigurations include
  • use of the wrong URL protocol:
    • the protocol for the URL is added as HTTP when the Agent is operated with HTTPS or
    • the URL is added as HTTPS when the Agent is operated with HTTP.
  • The JOC Cockpit will report the Agent status as "Coupling failed". When hovering the Agent Status with the mouse then the full error message will be displayed, for example:
    • java.net.ssl.SSLException: Unrecognized SSL message
    • This error message will also be shown in the Controller's log file, e.g. in the JS7_CONTROLLER_DATA/logs/controller.log file - see the JS7 - Log Files and Locations article.
      
      
      
      
• Solution: To resolve this error click the "Edit" action menu item for the respective Agent and modify the protocol for the Agent.

Two Agents use the same URL and a different Agent ID

• Problem: When an Agent is already registered with the JOC Cockpit and the same URL is used for the registration of another Agent with a new Agent ID then an error will occur.
  •  The term "same URL" can include literally different URLs that point to the same host and network address.
    • As the JOC Cockpit is not directly connected to Agents (for the purpose of optionally being operated in a different network zone) but refers to Agents through a Controller, the host name resolution (DNS) as available for the Controller applies.
    • If a proxy service is in place when using the Agent URL then the proxy could route different URLs to the same Agent.
  • The JOC Cockpit will report the Agent status as being "Reset". When hovering the Agent Status with the mouse then the full error message will be displayed, for example:
    • AgentPathMismatch: This is the 'primary_agent' agent, not: secondary_agent
    • The error message indicates that the Agent has been registered with the Agent ID primary_agent and that the user is trying to register a second Agent with the same URL and the Agent ID secondary_agent.
    • This error message will also be shown in the Controller's log file, e.g. in the JS7_CONTROLLER_DATA/logs/controller.log file - see the JS7 - Log Files and Locations article.
      
      
      
      
• Solution: To resolve this error assign the correct URL for the Agent secondary_agent. If the intention is to replace the Agent primary_agent by the Agent secondary_agent then first delete the Agent primary_agent and then register the Agent secondary_agent with the JOC Cockpit.

Other Causes of Errors

Dropping an Agent's journal after successful registration

• Problem: If, due to some weird reason the Agent's journal is deleted/damaged after initial operation for an Agent has been successfully completed, the coupling between Controller and Agent may fail.
  • 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 restarting the Agent, 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 submitting the same settings for the Agent.

Restarting an Agent with a different port

• Problem: If an Agent is started with a changed port, it will not possible for the Controller to connect to the Agent as long as it is not aware of this port. This will fail the coupling of the Agent.
• Solution: To couple the Agent with its Controller after a change of the Agent's port, re-register the Agent from the JOC Cockpit using the Agent's "Edit" action menu and specify the new port with the Agent URL. 

Dropping a Controller's journal after successful registration of Controller and Agents

• Problem: If due to some weird reason the Controller's journal is deleted/damaged after successfully completing initial operation of Controller and Agents, the coupling with Agents may fail.
  • 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 Controller. At the point in time of restarting the Controller, the JOC Cockpit and Agents have to be up and running. In case the problem with coupling the Agents persists, then re-register the Agents with the JOC Cockpit using the Agents' "Edit" action menu.
  • Note that loss of a Controller's journal means that:
    • any scheduling objects such as workflows have to be re-deployed,
    • any orders of the Daily Plan have to be re-submitted,
    • any currently running orders are lost.
  • Use of a Controller cluster will leverage such a situation as the Secondary Controller instance operates a synchronized copy of the journal and will pick up operations immediately during fail-over (3-5s). The failed Primary Controller instance can be started at a later time and will automatically synchronize with the Secondary Controller instance's journal.

Further Information

For troubleshooting during ongoing operation see the JS7 - How to troubleshoot Agent journals article.