Queue Agents

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.

Import a configuration

See “Import and Export” .

Replacing a Branch Hub or Hub

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 of the Queue Agent.

Host

The IP address of the Queue Agent.

Version

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.

Suggested Working Order, Remote Upgrade

For an overview of the concept of Remote Upgrade, see “Remote Update Overview” .

The following is a suggested working order, when it comes to Queue Agent and Agent Profile handling during Remote Upgrade.

The profile defines what to upgrade and the required System Parameters. If none are defined, default values are used.

Each new Orchestra release comes with a default profile with a default tree structure available.

Create a new Agent Profile with the new Queue Agent version, any required pre and post deployment script.

For information regarding Agent Profile creation refer to “Creating an Agent Profile” .

For information about assigning profiles to Queue Agents refer to “Assigning an Agent Profile” .

For information about synchronizing profiles to Queue Agents refer to “Synchronizing the Queue Agent” .

When the Queue Agent synchronization is done, the profile can be deployed (the Queue Agent can be upgraded).

For information about deployment of profiles to Queue Agents refer to “Handling a Single Queue Agent” and “Handling Multiple Queue Agents” .

5. After the Remote Upgrade has been completed, you need to perform a manual publish for each Branch on the Queue Agent.

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:

• Prepare profile. Click the button next to the wanted Profile in the Available Profiles area.

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.

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.

Here, you can perform the following action:

• 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.

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, http port and websocket port from the central configuration.

For more information, see “Agent Profile”.

Agent Profile

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.

For more information, see “Creating an Agent Profile Zip File” .

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:

Example of the section, after the change:

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/lib/<required_libs> [Not validated during upload but required to run jiql.war]

required_conf_content = agent.conf, ehcache.xml, hazelcast.xml (only for 5.4 Queue Agents and below), hornetq-configuration.xml (new in 6.1), krb5.conf, logbackDaemon.xml, logbackJetty.xml, login.conf, shiro.ini

required_lang_content = commonMessages.properties, graphicalDisplayMessages.properties

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.

If updating the zip file for an existing profile (in an upgraded system), the jiql.war MUST be changed.

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.

6. Optional: /webapp/<web application>/<war file>, /webapp/<web application>/preDeploy.groovy, /webapp/<web application>/postDeploy.groovy

The default profile contains four default web applications: reception, workstationterminal, wookie and jiql-admin-web.

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.

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.

16. When all updates have been made, the zip file can be created. The zip is created by zipping the following directories:

Creating an Agent Profile

1. Click the Create Profile button. The following window will be opened (note that not all of the window is displayed here):

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.

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:

4. Force start the synchronization of the selected Queue Agent, see “Synchronizing the Queue Agent” .

Synchronizing the Queue Agent

Synchronization can be started by three different events:

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).