A distributed Queue Agent registers with a name and a unique identifier. The name is typically a hostname and must conform to the hostname standard. The identifier can be any string, but is by default set to the MAC-address of the network interface of the Queue Agent.
When a Queue Agent registers for the first time, the Agent Profile currently deployed is unknown. It is only when an Agent Profile is deployed from central Orchestra, that the profile is known.
There are, however, some cases, described below, where the Agent Profile can change directly on the Queue Agent and where the deployed profile should be set to unknown again.
When replacing or switching out a Branch Hub, or Hub, the MAC-address of the Branch Hub/Hub is generally also changed, which means that the Queue Agent on the Branch Hub/Hub will re-register with central Orchestra. In most cases, one does however keep the name of the Queue Agent, thus two Queue Agents with the same name will appear in the list of Queue Agents, in the System Administration application.
It is safe to remove a Queue Agent from the list using the Delete icon, since any active Queue Agents will re-register, upon connect. However, by de-registering a Queue Agent, one will also clear out the information about the deployed Agent Profile.
Upgrading the Branch Hub/Hub firmware
When upgrading the entire Branch Hub/Hub firmware, the Agent Profile, e.g. the binaries, libraries, configuration and resources of the Queue Agent, is also replaced. In this case, an undetectable error may occur. The Queue Agent will register with the same id and name, but central Orchestra will not be able to detect the changes on the Queue Agent, and it will falsely continue to state the currently applied Agent Profile.
To avoid this, it is important to remove the upgraded Branch Hub/Hub Queue Agent from the list of Queue Agents, thus clearing out the stated deployed Agent Profile.
In the Queue Agents tab there are two sub tabs: Agents and Agent Profiles:
In the Agents sub tab, you can see information about available Queue Agents.
It is possible to sort each column by clicking on the column header. The Queue Agent list is not paginated. However, if you have a long list and need to find a certain Queue Agent, you can use Ctrl + F.
If you decide to sort the list on Connection status and have many Queue Agents that change their connection status often, it may take up to 10 seconds before the sorting is correct.
Name
Name of the Queue Agent.
Id
Id of the Queue Agent.
Host
The IP address of the Queue Agent.
Version
Version number.
Profile
Name of Queue Agent Profile.
Status
Status of the Queue Agent. Possible values are: Started, Starting, Stopping, Unknown, Stopped, Resetting Queue Agent, Resetting Queue Agent Media and Resetting Database.
Connection
Status of Connection. Possible values are: Disconnected and Connected.
Latest activity
Shows the latest activity of the Queue Agent.
If you select Queue Agents by marking the check boxes to the far left in the list of Queue Agents, the action buttons at the top will light up or get greyed out, depending on if that particular action is possible for at least one of the selected Queue Agents, or not.
If testing fails the failure should be investigated and a re-deployment could be done, if the failure is considered to be related to the deployment. If roll back should be done, it should be decided if all Queue Agents should be rolled back.
Roll back can be done by synchronizing the Queue Agent Profile that was previously deployed and then deploying this Profile on the Queue Agent.
Handling a Single Queue Agent
To see more detailed information about a Queue Agent, simply click its row in the list and the following information window will be displayed:
In this page you can find general Information about the Queue Agent, information about Connections, an Activity History, Logs, Security, as well as Upgrade handling.
It is possible to retrieve and download (as a zip file) a number of log files in the Logs area, by clicking on the Retrieve/Download links:
Here, you can also Update the Queue Agent with unit logs.
You can also perform the following action:
• Start the Queue Agent.
• Stop the Queue Agent.
• Reset the Database.
• Reset the Queue Agent.
• Reset the Queue Agent Media.
• Prepare profile. Click the button next to the wanted Profile in the Available Profiles area.
• Force synchronization.
• Upgrade
Example, stopping a selected (single) Queue Agent
1. Select a Queue Agent in the list of available Queue Agents, either by marking the check box to the left, or by clicking on it to open up the detailed information page.
2. Click the Stop button.
3. Click Ok in the confirmation window:
4. Check the Activity History and make sure that the Queue Agent is properly stopped:
Handling Multiple Queue Agents
Select the wanted Queue Agents by marking the check boxes to the left in the list of available Queue Agents. Click one of the highlighted buttons at the top of the window, depending on which action you want to perform.
These actions are only possible for distributed Queue Agents.
Here, you can perform the following action:
• Start the Queue Agents.
• Stop the Queue Agents.
• Reset the Database.
• Reset the Queue Agents.
• Reset the Queue Agent Media.
• Prepare profile. Select from drop-down list. Click the button next to the wanted Profile in the Available Profiles area.
Example, stopping a number of Queue Agents:
1. You select (by marking the check boxes) five (5) Queue Agents in the list of available Queue Agents, because you want to stop them.
When selecting them, however, you did not notice that one of the selected Queue Agents was already stopped.
2. You click the Stop button. A Confirmation window, making you aware of the fact that only four (4) Queue Agents will be stopped, is opened.
3. When Clicking Ok in the Confirmation window, the Queue Agents that were not already stopped, will be stopped.
In the Queue Agents tab, you can also open the Agent Profiles sub tab:
Here, you can find a list of all Agent Profiles that are present in the system. The list can be sorted, by clicking on the column headers.
You can see whether or not they are used and you can also delete profiles that are not used. Also, you can create new Agent Profiles.
After deleting an Agent Profile, please make sure that you refresh the browser.
At install and upgrade, there are three pre-installed Agent Profiles in the system, in the <installation_directory>/media/agentProfiles folder:
• A default Agent Profile for the current Orchestra version. The name of this Agent Profile is the same as the version name in the footer.
• A default Branch Hub Agent Profile for the current Orchestra version. The name of this Agent Profile is the same as the version name in the footer followed by -branchhub.
• A default Hub Agent Profile for the current Orchestra version. The name of this Agent Profile is the same as the version name in the footer followed by -hub.
These default Agent Profiles fetch their settings for host ip, protocol,httpand websocketfrom the central configuration.
An Agent Profile consists of configuration parameters (stored in database) and a zipped file. The Agent Profile zip file typically contains the Workstation Terminal, the Reception Terminal, and other applications that should be upgraded.
When uploading, the expected library files should be included in the lib directory of the Agent Profile that was created to be run with the latest version of the Queue Agent. The contents of the directory is validated and If something is missing in the file, this is presented in the Upload window.
It is possible to upload a new file for an Agent Profile. In that case, the existing uploaded file will be replaced by the new file.
We recommend that you think twice before uploading a new file for an already existing Agent Profile, since it may be hard to keep track of the contents of the different file versions. In many cases it may be a better idea to create a completely new Agent Profile instead of uploading a new file for an existing Agent Profile.
The file structure of the uploaded file is displayed, once the Agent Profile has been successfully created:
Time Zone Considerations - Configuring your Branch Hub / Hub
In order for the time stamps to be correct in your log files (qagent.log and daemon.log), you need to make sure that you have configured the time zone correctly in your Branch Hub / Hub in the Agent Profile that is then sent out to the Branch Hub / Hub.
This is done as described below.
Offset
The offset is controlled by the logback configuration files. For the Queue Agent, the file is <installation_directory>/media/agentProfiles/<agent_profile_name>/conf/logbackJetty.xml.
By default, the log file configuration is set to UTC time.
The section for the file appender can be changed so the correct time zone is used for the printouts (this should match what has been configured for the Branch Hub / Hub).
To set the time zone Europe/Stockholm, for example, in the log file for the Branch Hub, open the file logbackJetty.xml in the correct Agent Profile and locate the startupDailyRolloverAppender. Then change the line:
<!-- In order to DEBUG change this filter level, along with required components below -->
<level>INFO</level>
</filter>
</appender>
After this change, update the Queue Agent Profile on the Branch Hub / Hub.
Without Offset
To get time stamps without offset to UTC time in daemon.log, modify the file <installation_directory>/media/agentProfiles/<agent_profile_name>/conf/logbackDaemon.xml in the same way as described for logbackJetty.xml, above.
Creating an Agent Profile Zip File
Below is the Agent Profile zip file structure, where you can see mandatory and optional files. Those that are not marked are mandatory:
/agent/<jiql_war>
/agent/preDeploy.groovy [Optional]
/agent/postDeploy.groovy [Optional]
/agent/lib/<required_libs> [Not validated during upload but required to run jiql.war]
required_libs = This folder needs to contain the libs (jar files etc) required by the version of jiql.war included in the profile.
Files placed in the folder /app/<application> and any subfolders are automatically synchronized with the corresponding folder on a distributed Queue Agent. It can be used to automatically distribute files, e.g. third party applications and binaries to a distributed Queue Agent.
Procedure for creating the Agent Profile zip file
1. Copy the template profile from the Central server <central install dir>/media/agentProfiles/<version>.
Each new Orchestra release comes with a new default profile that contains correct versions of all mandatory files.
If you want to create a new profile for a Branch Hub, then please copy a template profile ending with -branchhub and if you want to create a new profile for Hub, please copy a template profile ending with -hub.
2. Mandatory: /agent/jiql.war
If the default profile is used as template, the jiql.war SHOULD NOT be changed.
If updating the zip file for an existing profile (in an upgraded system), the jiql.war MUST be changed.
3. Optional : /agent/preDeploy.groovy/
If required, add a preDeploy.groovy script.
4. Optional : /agent/postDeploy.groovy/
If required, add a postDeploy.groovy script.
5. Mandatory: /agent/lib
If the default profile is used as template, the content in the lib directory SHOULD NOT be changed.
If updating the zip file for an existing profile (in an upgraded system), the content in the lib directory MUST be changed.
The default profile contains four default web applications: reception, workstationterminal, wookie and jiql-admin-web.
7. Mandatory: /conf/<required_conf_content>
For information about what content is required, please refer to the list above that defines <required_conf_content>
Make necessary changes to the agent.conf file, e.g. set correct ports, ip addresses and ensure that settings for correct database type are made.
8. Optional: /conf/db
9. Optional: /conf/css
10. Optional: /conf/images
11. Mandatory: /conf/lang/<required_lang_content>
If the default profile is used as template, the content in the /conf/lang directory contains the latest language property files.
If additional languages are used on branches on a Queue Agent, those should be added here.
If updating the zip file for an existing profile (in an upgraded system), it is highly recommended to go through the existing language property files, since new parameters might have been added.
If the default profile is used as template the <required_security_content> SHOULD NOT be changed.
If updating the zip file for an existing profile (in an upgraded system), the <required_security_content>MUST be changed.
14. Optional:/conf/scripts
16. When all updates have been made, the zip file can be created. The zip is created by zipping the following directories:
• agent
• conf
• webapp
It is recommended to give the zip file a name that describes the content.
Creating an Agent Profile
To create a Queue Agent Profile:
1. Click the Create Profile button. The following window will be opened (note that not all of the window is displayed here):
2. Enter a unique Namefor the Agent Profile.
3. Browse for and upload the required zip file and enter a unique Folder Name.
4. For each Agent Profile, it is possible to override the Global Parameter values that have been configured in the Parameters tab. This is why all the parameters that can be overridden are also listed in the Queue Agent Profile window, as can be seen above.
5. Save the Agent Profile.
Assigning an Agent Profile
1. In the list of Queue Agents on the Agents sub tab, select the Queue Agent that you want to assign the Agent Profile to.
2. In the Available Profiles section, click the Prepare Profile button next to the name of the wanted Agent Profile:
Synchronization can be started by three different events:
• At reconnect to the central system
• At a scheduled time, triggered by a spring cron job
• When you force start synchronization in the GUI.
The latter is described below:
1. In the list of Queue Agents on the Agents sub tab, select the Queue Agent that you want to synchronize, by marking the check box to the left in the list. Alternatively, open up the detailed information page for the Queue Agent.
2. After having prepared the profile, as described above, click the Synchronize button, either in the Queue Agent list view, or in the detailed information page, as in the picture below:
During synchronization, you will be able to see the status (Synchronizing, Synchronized and Synchronization interrupted. The latter simply means that an ongoing synchronization for some reason was interrupted, for example by stopping the Queue Agent).
If you decide to sort the list on Connection status and have many Queue Agents that change their connection status often, it may take up to 10 seconds before the sorting is correct.
