211 03 K Orchestra Ref Man

Reference Manual
Orchestra 6.2
211.03K
Copyright notice
The information in this document is subject to change without prior notice and does
not represent a commitment on the part of Q-MATIC AB.
All efforts have been made to ensure the accuracy of this manual, but Q-MATIC
AB can not assume any responsibility for any errors and their consequences.
This manual is copyrighted and all rights are reserved.
Qmatic and Qmatic Orchestra are registered trademarks or trademarks of Q-
MATIC AB.
Reproduction of any part of this manual, in any form, is not allowed, unless written
permission is given by Q-MATIC AB.
COPYRIGHT © Q-MATIC AB, 2017.
Please send any feedback or questions about this manual to

documentation@qmatic.com.
211.03K Qmatic i
Qmatic Orchestra - Reference Manual
ii Qmatic 211.03K
Contents
1. What’s New ...............................................................vii

2. Presentation................................................................1
Customer Journey Management ........................................................... 2
System description ................................................................................ 7
Distributed Operations........................................................................... 9
Deployment Scenarios ........................................................................ 11
Supported Environments..................................................................... 13
3. Installation.................................................................15
Introduction.......................................................................................... 16
Prerequisites ....................................................................................... 17
Installation Note - Mobile Connect ...................................................... 18
Installation Note - CentOS................................................................... 19
Orchestra Business Intelligence.......................................................... 21
Deploying Business Intelligence on a Separate Server ...................... 26
Orchestra Central ................................................................................ 33
Orchestra Queue Agent ...................................................................... 39
Gateway 1745 ..................................................................................... 43
Installation Wizard and Properties File ................................................ 45
Installing and configuring Qmatic Branch Hubs and Qmatic Hub ....... 62
Redeploying Applications .................................................................... 62
4. Upgrade .....................................................................63
Upgrade Note - Undeploying Jiql.war.................................................. 64
Upgrade Note - Enabling Auditing....................................................... 64
Upgrade Note - Blocking Websocket Port ........................................... 64
Upgrade Note - Mobile Connect .......................................................... 65
Upgrade Note - Language Files .......................................................... 65
Adding/removing Applications ............................................................. 66
Upgrade Methodology ......................................................................... 68
Orchestra Business Intelligence.......................................................... 71
Orchestra Business Intelligence on a Separate Server....................... 84
Distributed Queue Agent (both Linux and Windows) .......................... 89
Unit Types ........................................................................................... 89
Widgets ............................................................................................... 92
Upgrade Wizard and Properties File ................................................... 92
211.03K Qmatic iii

5. System Administration.............................................95
Unit Types ........................................................................................... 96
Licensing ............................................................................................. 98
Import and Export.............................................................................. 101
Widget Administration ....................................................................... 104
Remote Update Overview ................................................................. 108
Queue Agents ................................................................................... 110
Parameters........................................................................................ 126
Mark Types ....................................................................................... 144
6. HW Monitoring ........................................................147
Introduction ....................................................................................... 148
Installation and Configuration............................................................ 148
Device Controller (GW1745) - Connect/Disconnect.......................... 154
Queue Agent - Connect/Disconnect.................................................. 155
Printer - Stat Messages..................................................................... 155
7. Auditing ...................................................................157
Introduction ....................................................................................... 158
What is logged? ................................................................................ 158
Where is it stored? ............................................................................ 159
Enabling/disabling the functionality ................................................... 161
8. Stat Aggregation .....................................................165

Introduction ....................................................................................... 166
Stat PDI Jobs/Transformations - Example Configuration.................. 166
Hardware Monitoring - Data Integration ............................................ 172
9. Localisation .............................................................173
The System GUI, Connect Concierge and Mobile Connect Application lan-
guage ........................................................................................................... 174
Translation of Calendar modules ...................................................... 179
Translation of Orchestra Business Intelligence................................. 188
10. Network Connectivity ............................................205

Orchestra Bandwidth Requirements ................................................. 206
Connect Counter - Connectivity and Network Loss .......................... 206
Connect Concierge - Connectivity and Network Loss....................... 211
11. Secure Communication.........................................217

Introduction ....................................................................................... 218
Orchestra Central.............................................................................. 222
Secure WebSocket Between Distributed Queue Agent and Central 229
Secure Communication for a Queue Agent ...................................... 233
Disabling HTTP and Running HTTPS Only ...................................... 250
Encryption of HornetQ JMS connections .......................................... 252
Bandwidth Requirements .................................................................. 257
iv Qmatic 211.03K
12. SSO setup...............................................................259
SSO Setup Using Integrated Kerberos ............................................. 260
SSO Setup Using Custom Pre-Authentication Proxy........................ 264
13. HA setup .................................................................267

Deployment Architecture................................................................... 268
Load Balancer ................................................................................... 269
Shared Storage ................................................................................. 270
RDBMS ............................................................................................. 270
Deployment Procedure ..................................................................... 270
HA Proxy Example ............................................................................ 271
14. Appendix A - Tuning Database Parameters ........275

Tuning of Oracle Parameters ............................................................ 276
Tuning of PostgreSQL Parameters ................................................... 277
15. Appendix B - Logging............................................281

Enabling Customer Journey Management Logging .......................... 282
Enabling Publish Logging.................................................................. 283
16. Appendix C - Security............................................285

Content-Security-Policy..................................................................... 286
X-Frame-Options............................................................................... 286
X-Content-Type-Options ................................................................... 287
X-XSS-Protection .............................................................................. 287
Strict-Transport-Security ................................................................... 288
Modifying HTTP Response Headers................................................. 288
17. Index.............................................................................i
211.03K Qmatic v
vi Qmatic 211.03K
1. What’s New
This section describes what is new in this manual, since the latest major release
of Orchestra.
General
• Added Appendix C - Security.
• HTTPS Setup chapter renamed Secure Communication.
• Updated the way PostgreSQL scripts should be run.
Installation chapter
• Updated the Installation Note - CentOS section.
• Updated Installation Wizard and Properties File section.
• Replaced all screen dumps of the Installation Wizard.
• Updated the Deploying Business Intelligence on a Separate Server section.
Upgrade chapter
• Updated Adding/Removing Applications section.
• Updated Upgrade Wizard and Properties File section.
• Replaced all screen dumps of the Installation Wizard.
• Added a note about MS SQL Server 2008.
• Added section Upgrade Note - Undeploying Jiql.war
211.03K Qmatic vii

System Administration chapter

• Added the Parameter Mobile Ticket Base URL.
• Added HTTPS Parameters section.
• Added five new parameters to the Central WebSocket Server
Settings section.
• Improved descriptions of Parameters.
Localisation chapter
• Added Translate Admin Plugin Parameters section.
• Added “Connect Concierge” to the heading “The System GUI and Mobile Con-
nect Application language”
Secure Communication chapter

• Chapter completely rewritten.
• WebSocket configuration information added, etc.
SSO setup
• Added SSO Setup Using Custom Pre-Authentication Proxy section.
viii Qmatic 211.03K

2. Presentation
Topics in this chapter
Customer Journey Management ........................... 2

Customer Journey Management Terminology ....... 3
System description ................................................ 7
Distributed Operations ........................................... 9
Deployment Scenarios ......................................... 11
Supported Environments ..................................... 13
211.03K Qmatic 1
Welcome to Qmatic Orchestra - an advanced system for Customer Journey

Management. Orchestra is an enterprise size system, intended for large,
centralized installations, but also offering the possibility of distributed operation.
Orchestra is a collection of high quality components that can help you create a
wide range of Customer Journey Management solutions.
Orchestra is extremely flexible and can be adapted to suit your customers needs.
This Reference Manual describes a neutral standard system not adapted to any
specific customer or market segment.
The manual presupposes that the reader is familiar with other Qmatic hardware,
for example displays and hardware terminals.
Customer Journey Management
Optimising customer journeys improves customer service and creates a more

relaxed atmosphere for both customers and staff. It also optimises staffing costs,
increases revenues and gives the organisation added value by maximising
profitability.
We call this overall process Customer Journey Management.
“Customer Journey Management is all about managing the journeys of your
customers and their experiences from their initial contact with your company,
through to service delivery. It also includes capturing their opinion after they have
received the service”.
A system for Customer Journey Management makes it possible to find the most
effective way of serving people. It also makes it possible for people waiting to do
something meaningful while they wait. They can fill in forms, read newspapers,
drink coffee, shop, for example.
How is this possible?
Knowledge is always the first step when you want to solve a problem. Orchestra
stores information about every waiting person: arrival time, selected service,
waiting time, and so on. By utilizing this information it is possible to find the best
way of serving customers. You will know exactly when and where a service must
be improved and the historic information can be used to check the result of
improvements.
Serving customers
To see to it that customers are served in a fair and efficient manner is Orchestra’s
most important task.
In the Orchestra system first the services needs to be defined. Services represent
the choices customers can make when they enter the premises. Service are linked
to so called ticket printer buttons which represent the services they see on these
devices. A service choice therefore are made on, for example, touch screens or at
2 Qmatic 211.03K
Presentation
receptions equipped with a printer. A service choice results in a visit number being
generated and usually printed on a ticket.
The queue specifies the visit number sequence. A service always belongs to a
queue. Two or more services that belong to the same queue also share the same
number sequence.
Visit numbers are selected from queues depending on profiles when a staff
member gives the Next command.
Customer Journey Management Terminology

Below you can find a description of the most common terms used in this manual.
Table 1: Customer Journey Management Terminology
Term Description
Appointment An agreed intention to a Visit.
The Appointment may include multiple Ser-
vices (and by that multiple Transactions) but it
only has one Appointment time.
Arrived Used, for Appointments, when a Customer has

started a Visit, i.e.when the Customer gets a
ticket number.
Branch An office or department carrying out one or

more Services in a geographical location.
Called When the ticket number was called, no matter

if the Customer responded or not. A Transac-
tion that started without the Customer entering
the Queue was never called.
Calling Rule A set of rules that decide from which Queue

the next Customer should be called.
Customer A Customer is a person visiting a Branch.
Customer Journey Manage- The setup of Services, and Queues, Calling

ment Rules and Segmentation Rules.
Delivered Service A kind of Mark about what Service that the

Customer got. Not necessarily the Service they
chose at the Entry Point
Display Generic display that can change view, e.g.

LED or monitor display.
211.03K Qmatic 3
Entered Queue Every time a Customer is placed in a Queue

during a Visit, even if the waiting time is 0.
There is a possibility to have a transaction
without entering any Queue and that is when a
Service is added when a Customer is served
without being placed in any Queue (Multi Ser-
vice without any waiting between Services).
Entry Point A Display that allows a Customer to choose a

Service and be assigned to a Queue.
Information Display A LED or a graphical Display that shows sys-

tem information.
Journey A Journey includes all activities (Visits,

Transactions, Appointments, etc.) that are
required to deliver one end result. The exact
definition depends on the client but it must be
possible to link two activities to place them in
the same Journey. For example in one
Appointment, you book the next Appointment,
belonging to the same Journey.
Mark A User defined value that can be added to a

Service Transaction. See Outcome and
Delivered Service.
Main Display A LED or a graphical Display in the waiting

area that shows the Ticket Id that is called, the
Position that is calling and the direction to the
Position.
No Show A Customer that does not respond to a call.
Outcome A Mark object that can be added to a Service

or a Delivered Service to specify the result of
the Transaction.
Positional Display Display above a Workstation Service Point.
Presentation Point A Unit that can display information, for exam-

ple main displays and positional displays.
Queue A first in first out list of customers.
Queuing Profile A part of the Branch Operation Profile that

defines the Queuing Logic of the Branch Oper-
ation Profile.
4 Qmatic 211.03K
Presentation
Reception Where the Visit (sometimes) starts, once inside

the building.
Served When there has been at least some interaction

between the Staff member and the Customer
during a Transaction. This is usually when a
Customer has responded to a call but it is also
when a Customer is given a Service without
being called (Multi Services). A Customer that
does not respond to a call (No Show) is never
served.
Service A Service is what our client delivers. A task

performed by the company for the customer.
See also Delivered Service and Outcome.
Service Point A unit where the Staff member is handling the

requested service for the customer. For exam-
ple a Workstation or Counter.
Service Transaction The process of attending a Service.
Staff member A Person delivering a Service.
Terminal A hardware Workstation Service Point. See

also Workstation.
Ticket Most commonly a physical note with the queue

number for a Customer. May however also be
in the form of for example an SMS or email.
Ticket Id The reference to the Visit. For example a ticket

number or booking reference.
Time zones All events, in Stat, are saved with the local
Branch time.
211.03K Qmatic 5
Transaction A Transaction is the waiting and deliverance of

one Service. A Transaction must always
include a Service (even if the Service never
was delivered) and usually includes waiting in
a Queue. There are two special cases:
• Transactions that are interrupted before the
Customer has been called are still Transac-
tions, but they do not include any Transac-
tion time.
• When a Service Point delivers Multiple Ser-
vices without transferring the Customer to
Queue, each Service is a Transaction but
without any Queue or Waiting time.
Visit A Visit is the part of a Customer Journey where

the Customer has been assigned a ticket num-
ber. The Visit continues until the end of the last
Transaction on the same ticket number.
Work Profile A Work Profile calls Customers from a speci-

fied number of Queues with some kind of prior-
ity (Calling Rule).
Workstation A Counter where a user handles the errand of

the Customer. A Software based service point.
See also Terminal, Service Point and Entry
Point.
6 Qmatic 211.03K
Presentation
System description
Components
The Home page of Orchestra shows which components of the system are installed
and available. Here is an example of what the Home page may look like:
211.03K Qmatic 7
Below, the available components of Orchestra are listed:

• Counter Workstation. For more information, see the User’s Guide.
• Calendar Client. Here Appointments can be managed. For more information,
see the User’s Guide.
• Reception. Reception Workstation, for more information see the User’s Guide.
• User Management - Users, Roles, and LDAP integration. For more informa-
tion, see “User Management” on page 25.
• Business Configuration - Branch configuration, Operation Profiles, Services,
etc. For more information , see the Administrator’s Guide.
• System Administration - Parameter settings, LDAP settings, Import / export,
License management, Unit Templates, Widget handling, etc. For more infor-
mation, see “System Administration” on page 95.
• Calendar Admin. Here you can configure Appointment Profiles, Resources
and similar. See the Administrator’s Guide..
• Surface Editor - surface application designer. For more information, see the
Administrator’s Guide.
• Context Marketing - manage Messages and Playlists. For more information,
see the Administrator’s Guide.
• Hardware Monitoring - Analysis dashboards for Hardware monitoring. For
more information, see the Administrator’s Guide.
• Central Operations Panel. If this application is installed you can see Branch
Live Information.
• Appointment reception - reception for arriving Appointments. For more infor-
mation, see the User’s Guide.
• Business Intelligence. Use this application to manage statistics, analysis and
reports. For more information, see the Orchestra Business Intelligence User’s
Guide, found on Qmatic World.
• Connect Counter. The Connect Counter application gives you the possibility to
run a Counter Terminal on a mobile device. For more information, see the
User’s Guide.
This application is not available as a component on the Home page.

Instead, it is available as a webapp, by entering the url <ip address>:8080/con-
nectcounter.
• Connect Concierge. The Connect Concierge application gives you the possi-
bility to run an app with Concierge functionality, on a mobile device. For more
information, see the User’s Guide.
8 Qmatic 211.03K
Presentation
This application is not available as a component on the Home page.

Instead, it is available as a webapp, by entering the url <ip address>:8080/con-
nectconcierge.
• Notification Admin - SMS and Email Administration. For more information, see
the Administrator’s Guide.
Branch Agnosticism
By default, Orchestra is set up so that if a user is assigned an application that is
Branch agnostic, the user will see all Branches, even if all the other assigned
applications are Branch aware.
So, for example, if the user has access to both the Counter Workstation (Branch
aware) and the Central Operations Panel (Branch agnostic), the user will see all
available Branches in the Counter Workstation.
If you want to change this default behavior, you need to set the branch_app
variable to true/false for the used application(s), in the applications table,
accordingly.
Distributed Operations
Distributed Operations is a unique Orchestra feature, which allows you to configure

and manage your Customer Journey platform centrally, while the actual workload
is distributed among all your Branches.
This also enables your Branches to attend to your Customers’ needs, even if the
connection to the central server is lost. Poor network conditions, high latency and
low bandwidth will thus no longer be a problem.
When do you need it?

Distributed Operation is needed when at least one of the following applies:
• Available WAN bandwidth is poor or the WAN connectivity is not 100% reliable
and suffers from high latency.
• If there are several business critical systems, Orchestra being one of them,
competing for WAN bandwidth, at peak times.
211.03K Qmatic 9
How does it work?

Distributed Operation is handled in the following way:
• Central Stat server handling persistence of all statistical data.
• Branches are configured to operate on remote Queue Agent instances.
• Distributed Queue Agent connects outbound to central Orchestra instance
across WAN, communication is bi-directional, once connection is established.
• If the central server, or database, needs planned maintenance, or if there is an
unexpected connectivity failure between remote Queue Agent and central
Orchestra, local users continue to operate as usual, during the outage.
• The Distributed Queue Agent keeps a local copy of all runtime data and con-
figuration.
• The Distributed Queue Agent sends event data for statistical data handling to
the central Stat server, when a network connection is present.
• The Distributed Queue Agent provides connector interfaces and web termi-
nals for local clients.
• Appointments for the current day are synchronized directly, so long as there is
a network connection. Appointments for the next day, however, are synchro-
nized nightly.
• Orchestra upgrades can be applied centrally, then applied to all Branches,
using Remote Update. For more information, see “Remote Update Overview”
on page 108.
10 Qmatic 211.03K
Presentation
Deployment Scenarios
The following pictures show a few examples of deployment scenarios for

Orchestra.
There are more deployment options than specified, but these are the most
common ones.
Fully Central vs Fully Distributed
211.03K Qmatic 11
Central and Distributed
12 Qmatic 211.03K
Presentation
Distributed on Region Servers
Supported Environments
For more information about supported Operating Systems, Application Servers,

Databases and Web Browsers, please refer to the Orchestra Platform Overview
document, which can be found on Qmatic World.
211.03K Qmatic 13
14 Qmatic 211.03K
3. Installation
Introduction ...................................................................................... 16
Prerequisites .................................................................................... 17
Installation Note - Mobile Connect ................................................... 18
Installation Note - CentOS ............................................................... 19
Orchestra Business Intelligence ...................................................... 21
Deploying Business Intelligence on a Separate Server ................... 26
Orchestra Central ............................................................................. 33
Orchestra Queue Agent ................................................................... 39
Gateway 1745 .................................................................................. 43
Installation Wizard and Properties File ............................................ 45
Installing and configuring Qmatic Branch Hubs and Qmatic Hub .... 62
Redeploying Applications ................................................................. 62
211.03K Qmatic 15
Introduction
Preinstalled User
When Qmatic Orchestra is installed, it comes with a preinstalled user:
Username: superadmin
Password: ulan
This user should only be used when doing the installation and performing setup. It
has access to the complete system, and is normally used only by a Qmatic
representative.
See the Orchestra Platform Overview document, found on Qmatic World, for
requirements regarding versions of: Hardware Operating Systems, Browsers,
Databases, Java and the like.
Port Numbers
In a default set up of Orchestra, the ports listed below are used.
Central Orchestra Server

HTTP: 8080
HTTPS: 8443
Queue Agent communication: 8787
Device communication: 8888
Standalone Queue Agent

HTTP: 18080
HTTPS: 18443*
Device communication 18888
* HTTPS listener is not enabled by default.
For more information about HTTPS and port/protocol handling, please see “Secure
Communication” on page 217.
Also, see “Ports and Protocols” on page 221.
16 Qmatic 211.03K
Installation
Prerequisites
It is important that the following prerequisites have been fulfilled before installation:
• The hardware and software that is used are of versions supported by the soft-
ware to be installed. For information about supported versions of Operating
Systems, Browsers, Databases, Java and hardware requirements, please
refer to the Orchestra Data Sheet, found on Qmatic World. Also, see “Sup-
ported Platforms” on page 18.
• All necessary hardware is installed with a supported version of the OS and
database (if needed).
• All cabling is in place.
• The software to be installed is available.
• A network of suitable capacity must be in place.
For more information, see “Distributed Operations” on page 9.
• If you are using CentOS, please read through “Installation Note - CentOS” on
page 19 before starting.
• If you will be installing Orchestra Business Intelligence, see“Orchestra Busi-
ness Intelligence” on page 21.
• If you will be installing Mobile Connect, please see “Installation Note - Mobile
Connect” on page 18.
• If Oracle or Microsoft SQL Server is used as database, database must be up
and running.
For more information about Oracle parameters, that might need tuning,
please read “Tuning of Oracle Parameters” on page 276 and for PostgreSQL
parameters that might need tuning, please read “Tuning of PostgreSQL
Parameters” on page 277.
• If you are to install a distributed setup and will be using Stat, you must open up
port 5445 in your firewall.
• If you are using Microsoft SQL Server, the following settings must be applied
to the installation:
• the TCP/IP protocol (and port number)
• SQL Server and Windows Authentication mode must be enabled.
• If you will be using named instances, you need to run the installation in silent
mode, using the command install.bat -s for Windows, or install.sh -s for Linux.
211.03K Qmatic 17
Supported Platforms
The following matrix shows which platforms that are currently supported. For more
information, please see the Orchestra Platform Overview document, on Qmatic
World.
Installation Note - Mobile Connect
If you want to install Mobile Connect, the following port needs to be enabled in the
firewall:
• 443
This is done in the Windows Control Panel:
1. In the Windows Control Panel, open Windows Firewall.
2. Go to Advanced settings and click on Outbound Rules.
3. Click New Rule, select Port, then click Next.
4. In the Specific local ports field, enter 443, then click Next.
5. Select Allow the connection and click Next, then click Next again and give the
rule a suitable name.
18 Qmatic 211.03K
Installation
Installation Note - CentOS
Before running the Orchestra installer on CentOS there are a few steps you need
to go through:
1. Settings for “max user processes” and setting for “max open files”.
We recommend increasing the setting of “max user processes” to 2048 and
increasing “max open files” by 30000.
If running other processes on the Orchestra server, these settings might have
to be increased further.
Current max user processes limit can be verified by running:
ulimit -u
Current max open files limit can be verified by running:

ulimit -n
We suggest increasing this by adding the following lines to the end of the file
/etc/security/limits.conf.
In this example “orchestra” is the username of the user that will run the installer
and the user that Orchestra will run as.
After modifying this file, the system will require a reboot. Verify the settings
again after reboot.
# Limits for orchestra installer
orchestra hard nofile 30000
orchestra soft nofile 30000
orchestra hard nproc 8192
orchestra soft nproc 8192
2. Make sure host name is resolvable.

Orchestra installer requires that host name of the machine is resolvable. You
can check host name in the file /etc/sysconfig/network.
You can verify that it is possible to resolve this by running:
ping HOSTNAME
If you get a response “ping: unknown host HOSTNAME” you will have to add
the HOSTNAME to the file /etc/hosts.
Add the following line to the end of the hosts file:
127.0.0.1 HOSTNAME
When running the installation using the embedded PostgreSQL database, a

default Linux system sometimes has too low memory settings. The PostgreSQL
211.03K Qmatic 19
process requires larger settings for shared memory, compared to the usual default
of 32 MB.
3. Verify the current memory setting (ignore the lines beginning with “error:
permission denied”):
sysctl -A|grep shmmax
This should output a line like this:

kernel.shmmax = 33554432
4. If the value is less than 268435456 (256MB), perform the following action to set
the value:
sudo sysctl -w kernel.shmmax=268435456
5. Edit the file /etc/sysctl.conf and add this line to the end of it (to make the change
apply when the machine is restarted):
kernel.shmmax = 268435456
6. Update the Semaphore parameters. First, verify the Semaphore parameters, by

running the command:
lpcs -ls
This should output something like:

max number of arrays = 128
max semaphores per array = 250
max semaphores system wide = 32000
max ops per semap call = 32
semaphore max value = 32767
Update the parameters, by running the command:

echo 512 32000 256 256 > /proc/sys/kernel/sem
Finally, verify the parameters by running the command:

lpcs -ls
7. To make the change permanent, add or change the following line in the file /etc/
sysctl.conf:
echo “kernel.sem=512 32000 256 256”>>/etc/sysctl.conf
20 Qmatic 211.03K
Installation
Orchestra Business Intelligence
Orchestra Business Intelligence installation is run as part of an Orchestra Central

installation. However, there are a few preparations and prerequisites that need to
be taken into consideration, before going ahead with a Central installation,
containing Orchestra Business Intelligence. This chapter describes those
preparations, prerequisites and special considerations.
The Orchestra Business Intelligence solution is based on the third party product
Pentaho Business Analytics. This means that to be able to use Orchestra Business
Intelligence, you need to install a database for the Business Analytics Repository,
which contains solution content, scheduling, and audit tables needed for the
Business Analytics Server to operate.
Business Analytics Repository, General Info
When running the Installation Wizard, see “Installation Wizard and Properties
File” on page 45, if you select that PostgreSQL should be installed, the steps below
are not applicable. However, if you are using an already installed PostgreSQL
database, or another database (SQL Server or Oracle), then please follow the
steps in this section.
The Business Analytics Repository consists of three repositories:
• Jackrabbit contains the solution repository, examples, security data, and con-
tent data from reports that you use Orchestra Business Intelligence to create.
• Quartz holds data that is related to scheduling reports and jobs.
Hibernate holds data that is related to audit logging.
Set up Business Analytics Repository for an already installed Post-

greSQL database
If you want to install PostgreSQL as part of the installation procedure, these

steps can be skipped! If you are using SQL Server or Oracle, see the instructions
for those databases, here: “Set up Business Analytics Repository, SQL Server” on
page 24 and “Set up Business Analytics Repository, Oracle” on page 25.
To create the Jackrabbit, Quartz and Hibernate databases, you can do one of the
following:
• Automatic procedure:
1. Run the <full path to orchestra installation package>/db/postgres-scripts.bat
file.
2. Follow the instructions in the actual script.
211.03K Qmatic 21
For example, if PostgreSQL is not installed in the default folder, you will be
asked to enter the path to your PostgreSQL installation.
You may also be prompted for “Password for user postgres”, which is the pass-
word that you stated when installing PostgreSQL.
Finally, when prompted for “Password for user pentaho_user”, enter password.
Make sure that you enter the correct password(s) while running the script,
according to the instructions above!
3. When done, follow the instructions in “Verify that databases and user roles have
been created” on page 23. If something goes wrong, follow the Manual
procedure below instead.
• Manual procedure:
Initialise the database, by running DDL:s that contain SQL commands that create
the Jackrabbit, Quartz and Hibernate databases. This procedure is described
below, for both Windows and Linux users.
Windows
1. Open an SQL Shell window.
The SQL Shell window is installed with PostgreSQL. After installation, it

can be found in the Start menu, under All Programs\PostgreSQL<version_-
number>.
2. When prompted for the server enter the name of the server, unless you are
using the default (localhost). If you are using the default, do not type anything
and click Enter.
3. When prompted for the database, enter the name of the database, unless you
are using the default (postgres). If you are using the default, do not type
anything and click Enter.
4. When prompted for the port, enter the name of the port if you are not using the
default (5432). If you are using the default port, do not type anything and click
Enter.
5. When prompted for the username, accept the default, then click Enter.
6. When prompted for the password, enter the password that you indicated when
you installed PostgreSQL.
7. Run the script to create the Jackrabbit database by typing this:
\i <full path to orchestra installation package>/db/bi-jcr-
postgres.sql
In the SQL Shell window, it is important that you use forward slashes (/) in
the full path name (non-Windows standard)!
22 Qmatic 211.03K
Installation
8. Run the script to create the hibernate database by typing this:

\i <full path to orchestra installation package>/db/bi-repository-
postgres.sql
9. Run the script to create the Quartz database by typing this

\i <full path to orchestra installation package>/db/bi-quartz-
postgres.sql
10. Enter the password at the prompt. The default is password.

11. Exit from the window by clicking Ctrl + C.
12. When done, follow the instructions in “Verify that databases and user roles
have been created” on page 23.
Linux
To run the SQL scripts on a Linux system, do this:
1. Open a Terminal window.
2. Sign into PostgreSQL by typing psql -U postgres -h localhost at the prompt.
3. Run the script to create the Jackrabbit database by typing this:
\i <Full path to orchestra install package>/db/bi-jcr-postgres.sql
4. Run the script to create the hibernate database by typing this:

\i <Full path to orchestra install package>/db/bi-repository-
postgres.sql
5. Run the script to create the Quartz database by typing this:

\i <Full path to orchestra> install package/db/bi-quartz-
postgres.sql.
6. Exit from the window by clicking Ctrl + C.
Verify that databases and user roles have been created

1. Open the PGAdminIII tool, which is bundled with both the Windows and Linux
versions of PostgreSQL.
2. In the Object Browser, click the PostgreSQL folder and enter the password
when prompted.
3. Click the Databases folder. The Jackrabbit, Postgres, Hibernate and Quartz
databases should appear.
4. Click the Login Roles folder. The jcr_user, pentaho_user, hibuser, and postgres
user accounts should appear.
If the databases and login roles do not appear, try to run the scripts, as
described above, again.
211.03K Qmatic 23
5. Select File->Exit to exit from PGAdminIII.
Set up Business Analytics Repository, SQL Server

The following instruction describes how to configure Orchestra Business
Intelligence to run towards a repository in SQL Server and should be performed
after the normal installation.
Initialize SQL Server Repository Database

To initialize SQL Server so it serves as the BA Repository, run SQL scripts to
create the Hibernate, Quartz and Jackrabbit (also known as the JCR) databases.
<Orchestra install package>/db/bi-jcr-mssql.sql
<Orchestra install package>/db/bi-quartz-mssql.sql
<Orchestra install package>/db/bi-repository-mssql.sql
To make the databases that you create more secure, we recommend that you
change the default passwords in the SQL script files to ones that you specify.
If you do decide to make the databases more secure, use a text editor to change
the passwords in these files:
parameter default value configured in

password for user password bi-repository-mssql.sql
hibuser
password for user password bi-quartz-mssql.sql
pentaho_user
password for user password bi-jcr-mssql.sql
jcr_user
a. Although there are several different methods for running SQL scripts, these
instructions explain how to run SQL*Plus from a Terminal or Command Prompt
window.
1. Open a Terminal or Command Prompt window, start the SQL*Plus and log in.
2. Run the script to create the Jackrabbit database by typing START bi-jcr-mssql.
If necessary, append the path to the bi-jcr-mssql.sql path in the command.
3. Run the script to create the repository database by typing START bi-repository-
mssql. If necessary, append the path to the bi-repository-mssql.sql path in the
command.
4. Run the script to create the Quartz database and users by typing START bi-
quartz-mssql. If necessary, append the path to the bi-quartz-mssql.sql path in
the command.
24 Qmatic 211.03K
Installation
Set up Business Analytics Repository, Oracle

The following instruction describes how to configure Orchestra Business
Intelligence to run towards a repository in Oracle and should be performed after
the normal installation.
Initialize Oracle Repository Database

To initialize Oracle so it serves as the BA Repository, run SQL scripts to create the
Hibernate, Quartz and Jackrabbit (also known as the JCR) databases.
<Orchestra install package>/db/bi-jcr-ora.sql
<Orchestra install package>/db/bi-quartz-ora.sql
<Orchestra install package>/db/bi-repository-ora.sql
The scripts will create a tablespace named pentaho_tablespace.
To make the databases that you create more secure, Pentaho recommends that
you change the default passwords in the SQL script files to ones that you specify.
If you do decide to make the databases more secure, use a text editor to change
the passwords in these files:
parameter default value configured in

password for user password bi-repository-ora.sql
hibuser
password for user password bi-quartz-ora.sql
pentaho_user
password for user password bi-jcr-ora.sql
jcr_user
a. Although there are several different methods for running SQL scripts, these
instructions explain how to run SQL*Plus from a Terminal or Command Prompt
window.
These instructions are the same for both Windows and Linux. If you prefer to
run SQL scripts using another method, modify instructions accordingly.
1. Open a Terminal or Command Prompt window, start the SQL*Plus and log in.
2. Run the script to create the Jackrabbit database by typing START bi-jcr-ora. If
necessary, append the path to the bi-jcr-ora.sql path in the command.
3. Run the script to create the repository database by typing START bi-repository-
ora. If necessary, append the path to the bi-repository-ora.sql path in the
command.
Run the script to create the Quartz database and users by typing START bi-quartz-
ora. If necessary, append the path to the bi-quartz-ora.sql path in the command.
211.03K Qmatic 25
Start the Orchestra Installation

Now, you are ready to install Orchestra Central, according to the instructions in
“Orchestra Central” on page 33.
In the Installation Wizard/Properties File, you need to specify host and port where
the PostgreSQL database is running, If passwords for Postgres database users
were changed in the create scripts, you need to update the information to match
that.
For more information, please see “Installation Wizard and Properties File” on
page 45.
Deploying Business Intelligence on a Separate Server
Orchestra Business Intelligence is typically deployed on the same application

server as the main Orchestra application. However, due to performance and
scalability reasons it is also possible to deploy Business Intelligence on a separate
server. This section provides installation and setup instructions to accomplish this.
Prerequisites
Two IP addresses, on the same LAN subnet.
Example:
Orchestra Server: 192.168.1.100

Business Intelligence Server: 192.168.1.101
Orchestra SSO login prerequisites

The default option from Orchestra 5.4 and later is to use Orchestra Single sign-on
authentication and authorization. That means that you only need to log in to
Orchestra in order to access the Orchestra Business Intelligence application from
the Home page of Orchestra.
Alternatively, it is possible to modify the Orchestra Business Intelligence
installation and use the Business Intelligence application's native login page
instead of the Orchestra one. This is, however, not recommended.
In order to share the user session token across different servers, the main
Orchestra server and the Business Intelligence server must appear to originate
from the same domain from the user browser's point of view, otherwise the cookie
same-origin policy of web browsers will prohibit sharing of required session
information. There are two supported ways to configure this: same-domain or
reverse-proxy. These are explained below.
26 Qmatic 211.03K
Installation
Same-domain
If each server is mapped to a sub-domain of a common parent domain name, the
cookie same-origin policy is not violated and session information can be shared.
For same-domain policy installs, each IP must be mapped to a sub-domain of your
main domain name in the DNS server your users use to connect to Orchestra.
Reverse-proxy
Another option is use a reverse-proxy / load balancer in front of both servers that
has the capability to route requests to different back-ends depending on the
context path of the request. In this scenario, the user browser only sees
proxy.yourdomain.com and thus the same-origin policy is not violated. Session info
is safely shared.
After installation, you will need to manually add the Data Sources for Business
Intelligence again. This procedure is described in the Administrator’s Guide, found
on Qmatic World.
Detailed instruction regarding each approach is present further down.
Installation
Deployment architecture
211.03K Qmatic 27
Orchestra Server
When installing the main Orchestra Server, take the following bullet into
consideration:
• Do not check the Business Intelligence option and the Stat option, in the instal-
lation wizard.
Database Server
For the server where the database is run, please take the following bullet into
consideration:
• You will need to update the qp_central and qp_agent databases, so the Home
page shows an "Orchestra Business Intelligence" entry with the appropriate
URL to the Business Intelligence server.
UPDATE qp_central.applications SET enabled = 1, url =
'http://your.domain.name:8080/businessintelligence' WHERE id='bi'
UPDATE qp_central.application_modules SET enabled = 1 WHERE id='bi'
UPDATE qp_agent.applications SET enabled = 1, url =

'http://your.domain.name:8080/businessintelligence' WHERE id='bi'
UPDATE qp_agent.application_modules SET enabled = 1 WHERE id='bi'
Make sure you replace the URL in the example above with the URL that matches
your environment.
IMPORTANT: If you are planning to use the reverse-proxy strategy for sharing
session information across hosts, please specify the path to the proxy-server as
URL in the queries above, e.g:
UPDATE … SET url = 'http://proxy.yourdomain.com:8080/
businessintelligence' WHERE …
You may need to modify the SQL above slightly to be compliant with your particular
database vendor (e.g. add schema prefixing on table names or similar). Also,
some databases may require the use of true or false instead of 1 or 0 for boolean
values such as 'is_distributed' or 'enabled'.
• After installation is complete and your Orchestra is up and running, open the
System Administration application and the Parameters tab and find the "Stat
Server Address" and “Stat Server Port” parameters, in the "Statistics Settings"
group. Change their values to the protocol, host name and port of your Busi-
ness Intelligence server. For more information, see “Parameters” on
page 126.
If you are using Branch Hub or Hub, this parameter must be set to the IP
address.
28 Qmatic 211.03K
Installation
Example
Stat Server Address: http://bi.your.domain
Stat Server Port: 8080
This, so the statistics data can reach the separately deployed Business
Intelligence server.
Business Intelligence Server

When installing the Business Intelligence server, take the following into
consideration:
• Check both the Business Intelligence and the Stat options in the installation
wizard. Do not install any of the other applications.
• Make sure that you enter the appropriate domain name to the main Orchestra
server, when the installer asks for it. Remember, the address you enter here
must be accessible for end users as the address is used for login redirects,
logout redirects and the Home button in the Business Intelligence application.
If you are planning to use the reverse-proxy strategy for sharing session
information across hosts, please specify the path to the proxy-server instead of
directly referencing the Orchestra server.
If you need to modify the value entered in the bullet above later, the value is written
to:
[install dir]/pentaho-solutions/system/security.properties
You can modify the central.orchestra.url property later if the central Orchestra
server changes host name. This requires restart of the Business Intelligence
server to take effect.
Post-install configuration options for session sharing

This section describes the two options for accomplishing session sharing between
the Orchestra and the Business Intelligence server.
For both same-domain installations and reverse-proxy installations the file

conf/shiro.ini needs to be updated on the central server.
Locate the section that looks like this:
/qsystem/rest/security/account/** = noSessionCreation,
ipFilter[127.0.0.1,0:0:0:0:0:0:0:1]
Inside the brackets, add the proxy server IP address that the BI server will use
when communicating with Orchestra. For networks that use both IPv4 and IPv6
you should add both addresses.
211.03K Qmatic 29
A Fully Qualified Domain Name (FQDN), for example proxy.yourdomain.com,

can be used instead of IP address. Also, IPv6 address can be omitted, if not used.
Example:
ipFilter[127.0.0.1,0:0:0:0:0:0:0:1,192.168.1.101,fe80::31e0:772:61
ab:c832:31e0:31e0]
1. Same-domain installation
If each server is mapped to a subdomain of a common parent domain name, the
cookie same-origin policy is not violated and session information can be shared.
For same-domain policy installations, each IP must be mapped to a subdomain of
your main domain name in the DNS server your users use to connect to Orchestra.
Example:
Orchestra Server: orchestra.yourdomain.com
Business Intelligence Server: bi.yourdomain.com
The cookie domain setting needs to be forced. This is done, by editing the file
[install dir]/conf/shiro.ini on the Orchestra host and adding the cookie.domain
property, as in the following example:
# Cookie for single sign on
cookie = org.apache.shiro.web.servlet.SimpleCookie
cookie.name = SSOcookie
cookie.path = /
cookie.domain = yourdomain.com
Please note that there have been reports of Internet Explorer users having to add
the two full domain names to the browser's list of Trusted Sites in order for the
cookie to be passed to both hosts.
Important: After adding the 'cookie.domain' property above, please note that
this change makes it impossible to log on to Orchestra unless accessed through
the DNS domain name, e.g. http://orchestra.yourdomain.com. While the system is
still reachable using its IP address, no login attempts will succeed since the
browser will not accept the issued cookie if the domain names does not match.
2. Reverse-proxy installation
An alternative is to use a reverse proxy / load balancer in front of both servers that
has the capability to route requests to different backends depending on the context
path of the request.
30 Qmatic 211.03K
Installation
Mapped path Internal server
proxy.yourdomain.com/busi- => bi.yourdomain.com

nessintelligence/**
proxy.yourdomain.com/** => orchestra.yourdomain.com
In this scenario, the user browser only sees proxy.yourdomain.com and thus the
same-origin policy is not violated. Session info is safely shared.
Qmatic does not provide or support reverse-proxy or load-balancing software.
However, for convenience a sample configuration for HAProxy is provided below.
HAProxy is a free load-balancing software available for major Linux and Unix
operating systems.
http://www.haproxy.org/
The following snippet from a sample HAProxy configuration routes requests to two
different backends depending on the request path:
frontend http-in
# bind port 8080 on all interfaces
bind *:8080
# add the Proxy-ip header Glassfish uses for X-Fowarded-For
option forwardfor header Proxy-ip
##### ACL rules to determine where to route incoming traffic #####
# bi - this tells HAProxy to use acl rule 'is_bi' for

# the path /businessintelligence
acl is_bi path_beg /businessintelligence
#### route to appropriate backend ###
# bi - if using acl rule 'is_bi', route requests to backend 'bi'

use_backend bi if is_bi
# default to orchestra backend, e.g. everything else

default_backend orchestra
######### ORCHESTRA BACKEND ##########

backend orchestra
# configure health check URL. Load balancer will return HTTP 503 if
this
# check fails. Uses /ping.html in Orchestra
option httpchk GET /ping.html HTTP/1.1\r\nHost:\ www
211.03K Qmatic 31
# Defines a server named 'orchestra1' on the given IP:PORT for this

backend
server orchestra1 192.168.1.100:8080 check
######### BI BACKEND ###########

backend bi
# configure health check URL. Uses the / context-root on the BI
server
option httpchk GET / HTTP/1.1\r\nHost:\ www
# Defines a server named 'bi1' on the given IP:PORT for this backend
server bi1 192.168.1.101:8080 check
This sample would naturally need to be updated with IP's, port numbers, host
names etc. applicable to the customer's infrastructure as well as other required
elements of a functional HAProxy configuration. The snippet above only deals with
the routing part relevant to the reverse-proxying mechanism and should be.
Configuration updates for reverse-proxy

When using the reverse-proxy approach we need to change a few of the
configuration settings we make sure that URL's to the Orchestra and Business
Intelligence servers point to the IP or host name of the reverse-proxy and not
directly at the servers.
This needs to be updated in two locations:
• On the Orchestra Server update the URL to the Business Intelligence applica-
tion in the qp_central.applications and qp_agent.applications tables:
UPDATE qp_central.applications SET url = 'http://
proxy.yourdomain.com:8080/businessintelligence' WHERE id='bi'
UPDATE qp_agent.applications SET url = 'http://

proxy.yourdomain.com:8080/businessintelligence' WHERE id='bi'
E.g. make sure that the URL in the Orchestra Home page uses the reverse-proxy
address instead of the direct IP or host name to the Business Intelligence server.
• On the Business Intelligence server, open the [install dir]/pentaho-solutions/
system/security.properties file and change the central.orchestra.url property to
the host name/ip address of the reverse proxy, e.g:
central.orchestra.url = http://proxy.yourdomain.com:8080
Adjust protocol, host name/ip and port according to your setup.
If you have previously used configuration option 1 (same-domain) and have

added a "cookie.domain" entry to the shiro.ini file, you either need to remove this
entry again and restart the Orchestra server or you need to map the IP address of
the load balancer to a DNS entry on the same domain specified for the
"cookie.domain" property. Otherwise you will not be able to log in to Orchestra.
32 Qmatic 211.03K
Installation
After installation, you will need to manually add the Data Sources for Business
on Qmatic World.
Orchestra Central
A schematic picture of the Fully Central deployment scenario (Customer Journey

Management deployed at the central server).
App Download, Installation and Upgrade

If you are going to use the Connect Counter and/or Connect Concierge
applications, you will need to download and install (and later upgrade) the native
app from either Apple App Store©, or Google Play.
To easily find the application, we recommend that you search for “Qmatic”.
211.03K Qmatic 33
Install Orchestra Central on Windows
Preparation:
If you want to install Orchestra Business Intelligence, as part of your Central

installation, please read through “Orchestra Business Intelligence” on page 21,
before you go ahead!
1. Copy the QP_Central__win_<type>-<version_number>.zip file and unpack the
files to a suitable directory, such as tmp.
It is recommended that path names containing spaces should not be used.
Configuration - Database
Prepare your database by running the scripts corresponding to your database
(Oracle Database / Microsoft SQL / PostgreSQL).
1. Open a database tool that allows you to run a database script (e.g. SQL
Developer for Oracle Database, or SQL Server Management Studio for
Microsoft SQL). For PostgreSQL see special instructions below.
2. Run the script corresponding to your database in a tool that can execute the
script:
Microsoft SQL Server:
<tmp_dir>/db/central-mssql.sql
<tmp_dir>/db/stat-mssql.sql
Oracle Database:
<tmp_dir>/db/central-oracle.sql
<tmp_dir>/db/stat-oracle.sql
PostgreSQL:
1. Make sure the PostgreSQL bin folder is added to environment variables.
2. Open the command prompt in the <tmp_dir>/db/ directory.
3. Run the commands:
psql -U postgres -f central-postgres.sql
and:
psql -U postgres -f stat-postgres.sql
34 Qmatic 211.03K
Installation
Installation
1. Open the Windows Task Manager and ensure that there is no application called
“Services” running, see the picture below. If there is, close the Services
application. This is done, to not cause any problems with starting and stopping
the Orchestra service, during the installation procedure.
2. Run the Installation Wizard, install.bat.

/<tmp_dir>/install.bat
For more information about the settings that are selected, see “Installation Wiz-
ard and Properties File” on page 45.
3. Wait for the installation to finish. Orchestra is now started.
4. Open the URL and start configuring the system. Please refer to the
Administrator’s Guide, that can be found on Qmatic World.
http://<ORCHESTRA_IP>:8080
User: superadmin
Password: ulan
Once you have successfully managed to log in to Orchestra, you will know that
the installation is complete!
If you want to import a system configuration, we recommend that you do

this before any other configuration is done.
For more information, see “Import and Export” on page 101.
211.03K Qmatic 35
Install Orchestra Central on Linux
Preparation:
If you want to install Orchestra Business Intelligence, as part of your Central

installation, please read through “Orchestra Business Intelligence” on page 21,
before you go ahead!
1. Transfer the QP_Central_linux64-<version>.tgz file to the server, preferably to
a tmp directory. Use for example scp to transfer the file.
It is recommended that path names containing spaces should not be used.

2. Login to the Orchestra Central server with a user with superuser rights.
3. Create a qmatic user:
#sudo adduser qmatic
4. Create Orchestra directory:

#sudo mkdir -p /opt/qmatic/orchestra/system
5. Grant rights for Orchestra directory to qmatic user:

#sudo chown -R qmatic:qmatic /opt/qmatic
6. Switch to qmatic user:

#sudo su - qmatic
7. Unpack Orchestra tgz file, to a tmp directory:

$ cd /<tmp_dir>
$ tar zxvf QP_Central_linux64-<version>.tgz
(Oracle Database/Microsoft SQL/PostgreSQL).
The scripts are designed for a rudimentary base installation of Orchestra, and
should be reviewed and tuned by the database administrator to match the
installation size and performance requirements.
Microsoft SQL). For PostgreSQL see special instructions below.
36 Qmatic 211.03K
Installation
script:
<tmp_dir>/db/central-mssql.sql
<tmp_dir>/db/stat-mssql.sql
Oracle Database:
<tmp_dir>/db/central-oracle.sql
<tmp_dir>/db/stat-oracle.sql
The Oracle scripts will create required schemas in default user table-space.
Please review the scripts and assign appropriate table-spaces for the schemas.
Larger installations may require tuning of some Oracle instance parameters.
For more information, see “Tuning of Oracle Parameters” on page 276.
PostgreSQL:
1. Make sure the PostgreSQL bin folder is added to environment variables.
3. Run the commands:
psql -U postgres -f central-postgres.sql
and:
psql -U postgres -f stat-postgres.sql
Larger installations may require tuning of some PostgreSQL parameters.

For more information, see “Tuning of PostgreSQL Parameters” on page 277.
Installation
#sudo su - qmatic
2. Make sure that the Orchestra installation directory is empty and that there is no
space in the path name.
3. Run the Installation Wizard, install.sh.
For more information see “Installation Wizard and Properties File” on page 45:
$ /<install_dir>/install.sh
To run the installation in silent mode:

$./install.sh -s
211.03K Qmatic 37
4. When the installation has finished, switch to user with super user rights:
$ exit
5. Change directory:
#cd /opt/qmatic/orchestra/system/bin
6. Add startup scripts to operating system:

#sudo ./install-services.sh
7. Open the URL and start configuring the system. Please refer to the
Administrator’s Guide, that can be found on Qmatic World.
http://<ORCHESTRA_IP>:8080
User: superadmin
Password: ulan
Once you have successfully managed to log in to Orchestra, you will know that
the installation is complete!
If you want to import a system configuration, we recommend that you do

this before any other configuration is done.
38 Qmatic 211.03K
Installation
Orchestra Queue Agent
A schematic picture of the Central and Distributed deployment scenario.
211.03K Qmatic 39
Install Distributed Queue Agent on Windows
Preparation
1. Transfer and unzip the QP_Qagent_win_<type>-<version_number>.zip file to a
suitable directory.
Installation
1. Install the service by running the following file:
<install_dir>/bin/win-install-service.bat
You need to run the installation as an administrator. Right-click on the file win-
install-service.bat and select Run as administrator.
2. Modify the file agent.conf, located in the conf folder.
For more information see “Configure Queue Agent” on page 41.
3. Run the database scripts, as described in section “Database Configuration” on
page 40.
4. Start the service created in step one.
5. Centrally, in the System Administration application in Orchestra, update the
Statistics Settings section of the Parameters tab, so that the Enabled check box
is checked, Host Address is set to http://<ip-address-to-stat-server> (normally
the Orchestra central server) and Address Port is set to 8080.
See “Statistics Settings” on page 136.
Database Configuration
Run the scripts corresponding to your database.
Microsoft SQL) For PostgreSQL see special instructions below.
40 Qmatic 211.03K
Installation
script:
<Queue Agent_install_dir>/conf/db/qagent-mssql.sql
Oracle Database:
<Queue Agent_install_dir>/conf/db/qagent-oracle.sql
PostgreSQL:
1. Make sure that the PostgreSQL bin folder is added to environment variables.
2. Open the command prompt in <Queue Agent_install_dir>/conf/db/ directory.
3. Run the command:
psql -U postgres -f qagent-postgres.sql
Configure Queue Agent

This section is applicable to both Linux and Windows and for all Queue Agents.
1. Skip this step, if having a central Queue Agent.

In the <Queue Agent_install_dir>/conf/agent.conf file, add or remove rows,
depending on which database you want to use.
2. Update the values below in <Queue Agent_install_dir>/conf/agent.conf:
Parameter Default value Description
agent.http.port 18080 Web Server on Queue Agent
central.host <ip-address-to- Location of Central
central-server>
central.web- 8787 Fixed, do not change!
socket.port
device.deviceCon- 18888 Port for Gateway to connect
troller.web-
socket.port
agent.https.ena- false Used for changing the start protocol (http/
bled https) of the start url for surfaces.
Optionally, set the agent name to something else than hostname, by opening
the file run.bat/run.sh and uncommenting the row:
:: SET AGENT_NAME=auto
211.03K Qmatic 41
To set the agent public ip/host address to something else than the default, open
the file run.bat/run.sh and uncomment the row:
:: SET AGENT_HOST_ADDRESS=auto
For example, the ip/host parameter needs to be updated when using an external
router. If the above parameters are not updated, their default values will be used.
3. Optionally, uncomment and configure the heartbeat interval property:
#central.heartbeat.intervalMillis = 30000
The default value is 30000 ms and the maximum value is 120000 ms.
4. For advanced Queue Agent configuration, when it comes to Business
Intelligence, the Statistics Settings can be updated in the Parameters tab in the
System Administration application.
For more information, see “Statistics Settings” on page 136.
Install Distributed Queue Agent on Linux
Preparation
1. Transfer the QP_Qagent_linux<type>-<version>.tgz file to the server.
Preferably to a tmp directory. Use for example scp to transfer the file.
2. Log in to the Queue Agent server with a user with superuser rights.
3. Create a qmatic user:
#sudo adduser qmatic
4. Create Orchestra directory:

#sudo mkdir -p /opt/qmatic/orchestra/qagent
5. Grant rights for Orchestra directory to qmatic user:

#sudo chown -R qmatic:qmatic /opt/qmatic/orchestra/qagent

#sudo su - qmatic
7. Unpack Orchestra tgz file:

$ tar zxvf QP_Qagent_linux<type>-<version>.tgz -C /opt/qmatic/
orchestra/qagent
42 Qmatic 211.03K
Installation
Installation
1. Switch to user with superuser rights:
$ exit
2. Change directory
#cd /opt/qmatic/orchestra/qagent/bin
3. Copy startup script to /etc/init.d

#sudo cp qagent /etc/init.d/
4. Set appropriate rights:

#sudo chmod 755 /etc/init.d/qagent
5. Orchestra to be started/stopped at default runlevel:

#sudo update-rc.d qagent defaults 92
6. Modify the file agent.conf, located in the conf folder.

For more information, see “Configure Queue Agent” on page 41.
7. Run the database scripts, as described in section “Database Configuration” on
page 40.
8. Start Queue Agent:
#sudo /etc/init.d/qagent start
9. Centrally, in the System Administration application in Orchestra, update the

Statistics section of the Parameters tab, so that the Enabled check box is
checked, Host Address is set to http://<ip-address-to-stat-server> (normally the
Orchestra central server) and Address Port is set to 8080.
See “Statistics Settings” on page 136.
Gateway 1745
Gateway 1745 manages all the Qmatic hardware at the Branch and communicates
with the central/distributed Queue Agent.
When there are no Qmatic 1745 devices in Branches, the Gateway 1745 software
can be installed on the central server. To install the Gateway follow this procedure:
1. Copy the files in the gw1745_* zip file to a suitable directory, for example:
C:\QMATIC\Gateway1745. The files are:
• gw1745.exe
• mingwm10dll
• qwebsockets.dll
211.03K Qmatic 43
• gw1745.cfg
• installGWService.bat
• uninstallGWService.bat
2. For each instance of Gateway 1745 that should run on the branch, install a
service by executing installGWService.bat. The batch file will create a sub folder
for each service named <branchPrefix>_<UnitId> (for example GBG_GW1745)
and create a gw1745.cfg file in the folder that the service will use.
installGWService.bat will prompt for the following parameters:
• Branch prefix - should be the same as branch prefix in the Orchestra
branch administration GUI, as seen below:
Parameter Default value Description

Unit id GW1745 Unit id of the Gateway.
Queue Agent ip Ip address or hostname of the Queue Agent
address server.
Queue Agent Configured in agent.conf for the Queue
device server web- Agent, parameter device.deviceControl-
socket port ler.websocket.port.
Com port For example COM1, COM2, or NONE, if no
1745 equipment is used.
Event port The UDP port TP printers will use to commu-
nicate with gw1745. Must be unique for
each1745, if several gw1745 run on the
same machine.
3. Installation Done!
4. Restart the machine (or start the services, using the Services explorer, see
below). The GW1745 should start and keep running.
The status of the GW1745 service can be checked by using the Services explorer:
start/run/services.msc
44 Qmatic 211.03K
Installation
On the displayed list, all services running on the machine will be listed with their
Service name.
Installation Wizard and Properties File
Configuration of Orchestra Central to use Oracle, SQL Server or PostgreSQL

database is performed with the use of an Installation Wizard, in combination with
a properties file.
The Installation Wizard, install.bat (Windows) or install.sh (Linux), or properties

file, is run as a part of the complete installation process, described in “Orchestra
Central” on page 33. Also, the Installation Wizard, or properties file, is used during
Upgrade.
See “Upgrade” on page 63 and “Upgrade Wizard and Properties File” on page 92.
If you want to use a mixed setup, i.e. multiple databases, this can only be setup
in the properties file, not in the Installation Wizard.
It is possible to start the installer in silent mode (install.bat -s for Windows /

install.sh -s for Linux), i.e without a graphical user interface and with no user
interaction needed. This is recommended, if you want to use named instances.
Since the “Qmatic Platform” script is automatically started by the Installation

Wizard, it is important to keep the Services window closed during this process.
Settings in the Properties File

The file install.properties is included in the installation package, next to the
install.bat / install.sh file.
In this file, you can go into the details (that are not totally covered by the Installation
Wizard) of your wanted configuration, when installing Orchestra.
If you want to use a mixed setup, i.e. multiple databases, this can only be setup
in the properties file, not in the Installation Wizard.
For information about which platforms that are supported, please see “Supported
Platforms” on page 18.
The settings configured in the properties file are read by the Installation Wizard.
Also, when changing the settings in the Installation Wizard, the properties file is
updated, in the background, and can therefore be saved and used again for
installations with the same or similar configuration settings.
211.03K Qmatic 45
In the file install.properties you uncomment/comment the various settings, until it

conforms to the way you want your installation to look. The settings are described
in more detail below:
Installation
• operation - choose between installation and upgrade - in this case, of course,
you should select installation.
• install.path - enter the path where you want Orchestra to be installed.
Please specify double backslash characters when using Windows paths

(or use a single front slash instead: "c:/qmatic").
If you try to install to, for example, c:/qmatic/orchestra/system, or another

folder that is not empty, you will get an error message and the installation will
be aborted.
We recommend that you always install to a path that does not contain a
space in the path name.
Application Server
• heap.size - default is 4096.
• external.ip - default is localhost.
• application.server - default is wildfly, other alternative is jboss.
• jboss.zip.path - enter the path to where the jboss-eap-6.3.0.zip is located.
(Only applcable if jboss was selected as application server.)
The only supported version is 6.3.0.
Orchestra
• orchestra.configuration - decide if you want Orchestra to be installed with or
without a basic configuration. For more information about the basic configura-
tion, please see “Basic configuration” on page 59.
• application.* - in this section enter true for the applications that you want to
install and false for the applications that you do not want to install.
The following applications will be installed, by default:
• Central
• Workstation
• Reception
• Stat
• Connect Counter
• Help
46 Qmatic 211.03K
Installation
• Notification
• Auditing - can only be enabled/disabled using the silent installer.
Optional applications are:
• Business Intelligence
• SDK
• Calendar
• Connect Concierge
• Hardware Monitoring
API Gateway
• api.gateway.install - decide whether or not API Gateway should be installed
Postgres
This setting will install Postgres 9.2 as a separate service.

• postgres.install - decide whether or not PostgreSQL should be installed.
• postgres.port - enter the PostgreSQL port number. Default is 5432.
Database settings
If you want to use a mixed setup, i.e. multiple databases, this can only be set
up here, in the properties file, not in the Installation Wizard.
Enter which database (postgres, mssql, or oracle) you want to use for Central,
Queue Agent, Queue Widgets, Calendar, Statistics, Business Intelligence, and
Auditing.
In the SQL Server/Oracle/Postgres sections, make sure that all the settings, such
as port, user name and password, are correct.
Host names used by Orchestra should follow the RFC952 specifications. For
more information, see https://tools.ietf.org/html/rfc952.
The port setting for SQL Server databases should be left empty if named
instances are used.
Example: *.db.port =
If the port has to be specified, use a regular host name, or IP. The URL must be
appended with the instance name, separated by two backslash signs, as in the
following example: central.sqlserver.db.host = 127.0.0.1\\MYDBINSTANCE.
If you want to use named instances, you should also run the installation in
silent mode!
211.03K Qmatic 47
Here, you also find (and update, if needed) the specific settings for the Business
Intelligence Repository (audit, hibernate, quartz, and jackrabbit), for each
database.
Once you have gone through and updated the Properties file, you are ready to start
the installation, either as a headless installer, or using the Installation Wizard.
Settings in the Installation Wizard

When the Installation Wizard, install.bat (install.sh for Linux), is started, you first
click Start, to start the configuration procedure:
The following choices need to be made:

• Is this an Installation, an Upgrade (either an Update, or an upgrade from a
previous Orchestra version), or are you adding and/or removing applications?
For Upgrade, please see “Upgrade Wizard and Properties File” on page 92.
For adding and/or removing applications, please see “Adding/removing Appli-
cations” on page 66.
48 Qmatic 211.03K
Installation
• Where, i.e in which folder, to install Orchestra:
Here, you also enter the External IP of your central installation. Default is localhost.
211.03K Qmatic 49
It is also possible to enter a valid domain name, for example qmatic.com, or a host
name, such as GOT-JOHSTA-001.
This can also be updated post installation in the file agent.conf.
Host names used by Orchestra should follow the RFC952 specifications. For
more information, see https://tools.ietf.org/html/rfc952.
• Which Orchestra applications you want to install:
Central Orchestra
The software of central Orchestra.
Counter
The software of the Counter terminal.
Reception
The software of the Reception terminal.
Connect Counter
The software of the Connect Counter application.
Connect Concierge
The software of the Connect Concierge application.
50 Qmatic 211.03K
Installation
Business Intelligence
The software of Orchestra Business Intelligence. For more information, please see
the Orchestra Business Intelligence User’s Guide, which can be found on Qmatic
World.
Auditing
Auditing functionality. For more information, see “Auditing” on page 157.
Stat
Statistics.
Calendar
The software of the calendar.
Notification
The software of the Notification application.
SDK
Software development kit for Orchestra. Useful when developing custom
applications.
Not suitable for production deployments.

The url to use to access the SDK, after it has been installed, is:
http://<ORCHESTRA_IP>:8080/sdk
Help
The Orchestra On-line Help. If you decide not to install it, the text “Not installed”
will be displayed if the Help icon, , is clicked.
Hardware Monitoring
Used for easy access to the Hardware Monitoring Dashboards.
211.03K Qmatic 51
• The wanted application server:

For JBoss, please also enter the path to the JBoss zip-file:
52 Qmatic 211.03K
Installation
For Wildfly, however, no further input is needed:
• Whether or not you already have an existing database server that you want to
use:
211.03K Qmatic 53
If you select Yes, you will need to enter the settings for your wanted database
server in the following pages.
As you can see, in the image above, Oracle is not supported, if you selected Wildfly
as application server in a previous step. For more information about supported
platforms, see “Supported Platforms” on page 18.
If you select No, we will install PostgreSQL for you.
54 Qmatic 211.03K
Installation
If you select Yes, then PostgreSQL, the Database settings page looks like this:
If you select SQL Server, the Database settings page looks like this:
211.03K Qmatic 55
If you select Oracle, the Database settings page looks like this:
• Choose whether or not you want to install Orchestra with a system pre-config-
uration:
56 Qmatic 211.03K
Installation
It is only possible to select a pre-configuration, if Central was selected as an

application earlier in the installation.
If you select the Basic Configuration, Orchestra will be installed with a
configuration containing one Branch, three Services, three Queues and other basic
settings, to help you get started with your system. To read more about the available
pre-configuration(s), and needed post-installation set-up, please see “Chosing a
system pre-configuration” on page 59.
When all choices have been made, you will get a summary of what will be installed
and where:
From here, it is also possible to click on Save Properties File, to select a location
that you want to save the updated properties file to.
It is possible to go back and change settings, before starting the actual installation.
Start the installation by clicking Next.
211.03K Qmatic 57
On the following page you can follow the progress:
You will get a message that the installation has been completed successfully. Click
Next.
From this page, it is also possible to open and view the installation Log file.
58 Qmatic 211.03K
Installation
When done, click Finish to end the installation and close the wizard.
The “Qmatic Platform” service is automatically started by the Installation Wizard.
Chosing a system pre-configuration

During the installation procedure, you are offered the possibility to choose a
system pre-configuration. This could be useful, if you for example are planning to
use a standard system set-up.
You will start Orchestra with a working default configuration. After installation,
however, you need to change a few settings to get a fully working system.
For more information, please see “Mandatory Site Specific Settings” on page 61
and “Optional Site Specific Settings” on page 61.
Below is a description of the available system pre-configuration.
Basic configuration
This configuration, in short, contains 5 Counters, 3 Services, 3 Queues, 3
Workprofiles, 3 printers, LCD Main and counter displays, and Software terminals.
Below is a more detailed list of the contents of this configuration:
• Unit Types:
• WebReception
• WebServicePoint_PositionalDisplay
• Cinematic
• Intro5
• Intro8
• Intro17
• GW1745
• Widgets
• Ticket Call - mapped to applicable surfaces
• Ticket Call History - mapped to applicable surfaces
• Scrolling Text - mapped to applicable surfaces
• Services
• Service 1 - Serving time 5 min, setting Booking enabled is enabled
• Operation Profiles
• Operation profile 1 - Service 1->Queue 1; Service 2->Queue 2; Service 3-
>Queue 3
211.03K Qmatic 59
• Queues
• Queue 1 - No. series 001-199, Service Level 5 min.
• Work Profiles
• Queue 1 - Call Queue 1, based on waiting time (WT)
• Longest waiting time all queues - Call from all Queues, based on waiting
time (WT)
• Surface Applications
• Intro8 - Intro 8 touch surface
• Intro17 - Intro 17 touch surface
• Main Cinematic Display - Generic Media display
• Counter Display 1280x720 - Generic Positional display
• Default Ticket - Ticket layout
• Equipment Profiles
• Default Profile - Default Equipment Profile
• Branch
• Branch 1 - REGIONS
• Service Points
• Counter 1
• Counter 2
• Counter 3
• Counter 4
• Counter 5
• Users
• superadmin - Password: ulan
• bm - Password: bm
• staff - Password: staff
60 Qmatic 211.03K
Installation
• Users and Roles

• superadmin - all Roles
• bm - BranchManager; CounterUser; MarketingAdministration; Recep-
tionUser; BIUser
• staff - CounterUser; ReceptionUser
Mandatory Site Specific Settings

After installation, you need to follow these steps:
1. Activate a licence.
For more information, see “Licensing” on page 98.
2. Install GW1745, in order to make your printers and other hardware work as they
should.
For more information, see “Gateway 1745” on page 43.
3. Change the IP address setting for all of your printers (in this case Intro 5, Intro
8 and Intro 17), to IP addresses used at your site. This is done in the Business
Configuration application, in the Branches tab. Open the Branch(es), scroll
down to the Equipment Configuration section and change the IP addresses for
each printer. For more information, see the Administrator’s Guide, found on
Qmatic World.
4. Save and publish the Branch(es), regardless if you have hardware or not
connected to it. Publishing can be performed either in the Branches tab, or in
the Publishing tab of the Business Configuration application.
When the Branch(es) has been published, the Counter and Reception applica-
tions will be available for the Users that are connected to those Roles. Also, if
applicable, the Appointment reception application will be available.
Optional Site Specific Settings

To make the configuration better suit your needs, you can customize the names of
Services, the Operation Profile, Queues, Work Profiles, Surface Applications,
Equipment Profile and Branch. This is done in the Business Configuration and
Surface Editor applications.
For your Queues you may want to change the Service Levels and for your Services
you may want to change the serving time. The serving time is used for estimated
waiting time calculations. This is done in the Business Configuration application.
You can, naturally, also add Users with other or the same Roles as the already
existing Users. This is done in the User Management application.
For more information about how to perform all these changes, please see the
Administrator’s Guide, found on Qmatic World.
211.03K Qmatic 61
Installing and configuring Qmatic Branch Hubs and Qmatic

Hub
For more information about how to install and configure a Branch Hub, a Branch
Hub Basic, or a Hub, please refer to the manual for each Branch Hub/Hub, which
can be found on Qmatic World.
Redeploying Applications
If you, for some reason, need to redeploy one of your deployed applications, it is
important that you make sure that you are using the wanted version of the
application artefact (war-file).
The reason for redeploying an application may for example be if you have received
a later version of the Mobile Connect Counter application, or if you have translated
your Calendar Admin and Calendar View applications.
For Mobile Connect, it is possible to check the version of the deployed application,
by going to one of the following url:s:
• connect.war: http://<ip>:<port>/connect/config.properties
• connectcounter.war: http://<ip>:<port>/connectcounter/config.properties
A file called config.properties will be downloaded and this file contains a parameter
called app_version that states the version of the application.
Follow these manual steps, to make sure that you are really using the wanted
application version:
1. In the JBoss/Wildfly admin console (http://localhost:9990, username: admin,
password: ulan), in the Deployments tab, undeploy the application that you
need to redeploy.
2. Delete the applicable war-file from the <install_dir>\deploy folder.
3. Copy the new war-file to the <install_dir>\deploy folder.
4. Deploy the new version of the application in the JBoss/Wildfly admin console,
by clicking Add, looking up the new file, then clicking Next and making sure that
the application is correctly enabled.
62 Qmatic 211.03K
4. Upgrade
Upgrade Note - Undeploying Jiql.war .............................................. 64

Upgrade Note - Enabling Auditing ................................................... 64
Upgrade Note - Blocking Websocket Port ....................................... 64
Upgrade Note - Mobile Connect ...................................................... 65
Upgrade Note - Language Files ....................................................... 65
Adding/removing Applications ......................................................... 66
Upgrade Methodology ..................................................................... 68
Orchestra Business Intelligence ...................................................... 71
Orchestra Business Intelligence on a Separate Server ................... 84
Orchestra Central ............................................................................ 85
Distributed Queue Agent (both Linux and Windows) ....................... 89
Unit Types ........................................................................................ 89
Widgets ............................................................................................ 92
Upgrade Wizard and Properties File ................................................ 92
211.03K Qmatic 63
This chapter describes the prerequisites, dependencies and recommended

methodology on how to upgrade both Orchestra Central system and distributed
Queue Agents as well as detailed descriptions of the upgrade scenarios.
We recommend that you read the Upgrade Note sections below, the section
“Upgrade Methodology” on page 68, as well as the Release Notes, before the
Upgrade process is started.
Upgrade Note - Undeploying Jiql.war
If you experience problems that the Upgrade gets stuck when undeploying jiql.war,
please follow these steps to work around these problems:
1. Open the Wildfly Admin console (http://localhost:9990, username: admin,
password: ulan).
2. Go to Deployments and select jiql.war. Click En/Disable and then Confirm.
3. Run the Upgrade again.
Upgrade Note - Enabling Auditing
For instructions on how to enable auditing when upgrading, please see “Upgrade”
on page 161.
Upgrade Note - Blocking Websocket Port
If running a distributed system with one, or more, distributed Queue Agents, there
is a possibility that the connected Queue Agents can cause problems as they
reconnect during the upgrade procedure.
To work around this, block the port 8787 on the computer running the central
system during upgrade.
This can be done in the Windows Control Panel -> Windows Firewall -> Advanced
Settings:
1. Right-click Inbound Rules and select New Rule.
2. Select Port and click Next.
3. Select TCP and specify port 8787. Click Next.
4. Select Block the connection, click Next.
5. Select all available networks and click Next.
6. Give a name to the new rule, e.g. "Orchestra upgrade 8787 block" and click
Finish.
64 Qmatic 211.03K
Upgrade
Once the upgrade of the central system is complete, the port block must be
removed. This is done in the Windows Control Panel -> Windows Firewall ->
Advanced Settings.
Select Inbound Rules, right click the rule created (e.g. "Orchestra upgrade 8787
block") and click Delete.
Upgrade Note - Mobile Connect
If you are upgrading from Orchestra version 5.4 to Orchestra version 6.2, or later
and have made changes to the Mobile Connect language properties files,
connect.properties and connectCounter.properties, you need to manually add
these changes, to the Orchestra 6.2 properties files, connectMessages.properties
and connectCounterMessages.properties, after the upgrade.
Simply renaming your old, changed files to connectMessages.properties and

connectCounterMessages.properties is not a good enough solution, because
strings may have been added or deleted in the files since Orchestra 5.4.
Also, if you added language specific properties files in Orchestra 5.4, do the
following: copy the default new files, connectMessages.properties and
connectCounterMessages.properties, add a language code suffix to them, for
example *_fr then translate the contents again, after upgrading to Orchestra 6.2.
Here too, it is not a good idea to simply rename the old files, since strings may
have been added or deleted.
Make sure that you translate any strings in the new files that have not yet been
translated, if applicable.
When upgrading from 5.4 and using Mobile Connect applications with old
names, you may get error messages in the log saying “Custom application
encountered which has not been deployed”. Note that these messages can be
ignored, there is no need to manually deploy your applications!
Upgrade Note - Language Files
When upgrading from Orchestra version 5.4 to version 6.2, or later, or to an Update
(previously known as Hotfix), there are a couple of things that you need to keep in
mind, when it comes to the handling of language files:
• The existing language property files will automatically be backed up to the
folder upgrade_backup, during upgrade. This way, you can easily restore
them, if the encoding somehow fails, during upgrade.
• All non-latin characters need to be Unicode-encoded, using the program
native2ascii, before the upgrade procedure is initiated. For example the Swed-
211.03K Qmatic 65
ish character Ä should be encoded as \u00C4 and the cyrillic character Ф

should be encoded as \u0424. For more information, please see “The System
GUI, Connect Concierge and Mobile Connect Application language” on
page 174.
Adding/removing Applications
If you want to add/remove one or several application(s), this is possible by using

the Upgrade Wizard. For more information, see “Upgrade Wizard and Properties
File” on page 92.
This procedure can be useful if your business changes so that you, for example
will start using the Connect Counter application, or if you installed an application
by mistake.
The following matrix shows which applications it is possible to undeploy/deploy.
It is never possible to add/remove Central.
If Central is not selected, it is only possible to select Business Intelligence and

Stat Orchestra. This due to the fact that it is possible to install Business Intelligence
on a separate server. For more information, “Deploying Business Intelligence on a
Separate Server” on page 26 and “Orchestra Business Intelligence on a Separate
Server” on page 84.
It is not possible to add the Calendar application using this method.
Application Deploy Undeploy Comment

possible possible
Business Intelligence X* X *Only if data sources are availa-
ble in the application server (stat
plus 3 bi)
Stat X* X *Only if data sources are availa-
ble in the application server
(stat)
Reception X X
Counter X X
Calendar X* X *Only if data sources are availa-
ble in the application server
(qp_calendar)
SDK X X
Help X X
Connect Counter X X
Connect Concierge X X
66 Qmatic 211.03K
Upgrade
Notification X X
Hardware Monitoring X X
Follow these steps:
1. In the Upgrade Wizard, select Add and/or remove applications:
2. Then, select the path to your already installed Orchestra system.
211.03K Qmatic 67
3. The next page shows the applications that are already installed in your system:
Here, make sure that all of the applications that you want in your system are
selected.
The applications that can not be removed are greyed out.

4. Run the rest of the Upgrade Wizard, in the normal way.
Upgrade Methodology
Before you begin (Test and Production environment)

1. Make sure that you have read through the Release Notes document, since it
contains important information that needs to be considered before Upgrade
commences!
2. Make sure that you have your license details in place.
You can not use the same license key as for your current Orchestra ver-
sion, if that version is Orchestra 5.x, since the Licensing model has been com-
pletely updated for Orchestra 6.x. For more information, see “Licensing” on
page 98.
3. Obtain / download all software artefacts to be upgraded.
68 Qmatic 211.03K
Upgrade
4. Backup installation folder:
If you use the normal Windows operation of copying and pasting the folder,
or dragging and dropping it, you may encounter problems with file names being
too long. This means that some files will not be copied and you will be
prompted about this problem. If this happens, cancel the copy operation and
remove anything that was already copied to the target folder. Then, try using
robocopy command line tool, instead. Entering “robocopy system backup /E”
on the command line, for example, will copy the folder named “system” and
make a copy named “backup”. Change these names as desired!
5. Backup databases.
6. Backup media content files. Optionally snapshot VM if using virtual machine
technology for host.
Media content is all media files, such as images and videos, that are running
on Media Displays (via Cinematic) and similar surfaces.
7. Prepare Regression Tests.
See “Regression Test” on page 110.
8. Prepare Performance Tests.
See “Performance Test” on page 110.
Suggested Upgrade Order

Naturally, depending on how your system is set up and configured, another
upgrade order may be applicable for you. However, the following can be seen as
a suggested guideline, with references to the applicable sections of this document:
1. Upgrade Central
See “Orchestra Central on Linux, MS SQL Server/Oracle Database” on
page 87, “Distributed Queue Agent (both Linux and Windows)” on page 89, or
“Orchestra Central on Windows” on page 86.
2. Upgrade Distributed Queue Agent
See “Distributed Queue Agent (both Linux and Windows)” on page 89.
3. Upgrade Unit Types
See “Unit Types” on page 89.
4. Upgrade Widgets
See “Widgets” on page 92.
211.03K Qmatic 69
Test / Staging Environments

1. Upgrade central.
See “Orchestra Central” on page 85.
2. Regression test.
3. Distributed setup only: Upgrade a set number of Queue Agents (not all, the
environment should present a mix of Queue Agents on the latest and the
second latest versions).
4. Upgrade Unit Type Files and Widgets, if needed.
See “Unit Types” on page 89 and “Widgets” on page 92.
5. Distributed setup only: Regression test.
6. Performance test.
See “Performance Test” on page 110.
If testing passes, proceed to production upgrade.
If testing fails, at any point in the process, restore the environment from backups,
address the problem, and repeat the process.
Production Environment
Tasks to be performed sequentially within the same period:
1. Upgrade central.
2. Regression test.
If testing fails, restore the environment from backups and repeat the process.
3. Upgrade any distributed Queue Agents based on rolling upgrade plan.
4. Regression test after each upgrade step.
If testing fails, restore the Queue Agent to previous version, address the problem,
and repeat the process.
Rollout of distributed Queue Agent instances will be controlled by customer,

depending on the number of Queue Agents deployed in their environment and the
resourcing at their disposal to perform the upgrade.
70 Qmatic 211.03K
Upgrade
Orchestra Business Intelligence
Orchestra Business Intelligence is normally upgraded as part of an Orchestra

Central upgrade. However, there are a few things that need to be taken into
consideration, before going ahead with a Central upgrade, containing Orchestra
Business Intelligence.
When Upgrading from Orchestra 5.4

When upgrading from Orchestra 5.4 to a later version, there are a few things that
you need to consider:
• Since all of Business Intelligence is completely reinstalled during the Upgrade
process, please make a backup of the <Orchestra home>/pentaho-solutions/
system/ folder, before upgrade.
• Language packs from the Pentaho market place and Language Packs created
using the languagePackInstaller will no longer work, after the upgrade. You
need to follow the instructions in “Translation of Orchestra Business Intelli-
gence” on page 188, to manually introduce a new language to the Business
Intelligence application.
• If you want to move your Business Analytics Repository from another data-
base to MS SQL, see “Business Analytics Repository, MS SQL” on page 72
• If you want to move your Business Analytics Repository from another data-
base to Oracle, see “Business Analytics Repository, Oracle” on page 77.
• Follow the steps in “JBoss Related Configuration, MS SQL” on page 82, or
“JBoss Related Configuration, Oracle” on page 83, depending on which data-
base you want to use.
• If you are using a customised mondrian file, or have performed other changes
to your data sources, these will not be transferred automatically, during the
upgrade. You need to manually import your customised mondrian file and per-
form these updates again. For more information, please see the Business
Intelligence chapter of the Administrator’s Guide.
211.03K Qmatic 71
• After the upgrade, you need to edit the QMATIC data source in the following
way:
a) Select the QMATIC data source and click the cog wheel icon, , then
Edit. Existing parameters of the QMATIC data source will be shown.
b) Click on the plus icon, , and add the following new parameter:
Name: DynamicSchemaProcessor
Value: mondrian.i18n.LocalizingDynamicSchemaProcessor
Business Analytics Repository, MS SQL

If you have upgraded from Orchestra 5.4 to a later version and want to move your
Business Analytics Repository to MS SQL, follow these steps:
1. Configure Quartz on MS SQL BA Repository Database

When you use Orchestra Business Intelligence to schedule an event, such as a
report to be run every Sunday at 1:00 a.m. EST, event information is stored in the
Quartz JobStore.
Modify the file quartz.properties to indicate where the JobStore for scheduling is
located.
1. Open the <Orchestra home>/pentaho-solutions/system/quartz/
quartz.properties file in the text editor of your choice.
2. In the #_replace_jobstore_properties section of the file, set the following:
org.quartz.jobStore.driverDelegateClass =
org.quartz.impl.jdbcjobstore.MSSQLDelegate
3. In the # Configure Datasources section, set the following:

org.quartz.datasource.myDS.jndiURL = Quartz
4. Save the file and close the text editor.
72 Qmatic 211.03K
Upgrade
2. Configure Hibernate settings for SQL Server

Modify the hibernate settings file to specify where Business Intelligence will find the
BA Repository’s hibernate configuration file.
The hibernate configuration file specifies driver and connection information, as well
as dialects and how to handle connection closes and timeouts.
1. Open <Orchestra home>/pentaho-solutions/system/hibernate/hibernate-
settings.xml in a text editor.
2. By default, the system indicates the location of the PostgreSQL hibernate
configuration file.
<config-file>system/hibernate/postgresql.hibernate.cfg.xml</config-file>
Change this to point to the SQL Server configuration file:
<config-file>system/hibernate/sqlserver.hibernate.cfg.xml</config-file>
3. Save and close the file.
4. Open the file <Orchestra home>/pentaho-solutions//system/hibernate/
sqlserver.hibernate.cfg.xml in a text editor.
5. Make sure that the password and port number match the ones you specified in
your configuration. Make changes, as necessary, then save and close the file.
3. Replace Default Version of Audit Log File with SQL Server Version
The default audit_sql.xml file that is in the pentaho-solutions/system directory is
configured for the PostgreSQL database.
Since you are using SQL Server to host the BA Repository, you need to replace
the audit_sql.xml file with one that is configured for SQL Server.
To do this, copy the <Orchestra home>/pentaho-solutions/system/dialects/
sqlserver/audit_sql.xml file to the <Orchestra home>/pentaho-solutions/system
directory. Update the JNDI tag as <JNDI>Audit</JNDI>.
4. Modify Jackrabbit Repository Information for SQL Server

You must indicate which database is used as the BA Repository as well as the port,
url, username, and password.
All of the information needed to configure the repository for the PostgreSQL, SQL
Server, and Oracle BA Repository databases appear.
By default, the PostgreSQL sections are not commented out, but the SQL Server
and Oracle sections are.
Modify this file so that it works for your BA Repository:
1. Use a text editor to open the <Orchestra home>/pentaho-solutions/system/
jackrabbit/repository.xml file.
211.03K Qmatic 73
2. In the Repository part of the code, change the code so that the SQL Server lines
of code are not commented out, but the PostgreSQL and Oracle lines are.
Make sure that the <param name="url" value="jdbc:sqlserver://local-

host:1433:DatabaseName=jackrabbit"/> parameter indicates the correct server
and database name.
If the password for the jcr_user was modified during the preparation step,
the correct value must be inserted here.

<appender name="startupDailyRolloverAppender"
class="com.qmatic.qp.logging.QPRollingFileAppender">
<file>$
{AGENT_HOME}/logs/qagent.log</file>
<rollingPolicy
class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
<fileNamePattern>${AGENT_HOME}
/logs/qagent-%d
{yyyy-MM-dd}
_%d
{HHmmss}
.%i.log</fileNamePattern>
<timeBasedFileNamingAndTriggeringPolicy
class="com.qmatic.qp.logging.StartupTimeAndSizeBasedTriggeringPoli
cy">
<maxFileSize>10MB</maxFileSize>
<maxBackupIndex>10</maxBackupIndex>
</timeBasedFileNamingAndTriggeringPolicy>
</rollingPolicy>
<encoder>
<pattern>%d
{yyyy-MM-dd HH:mm:ss.SSS,Europe/Stockholm}
[%thread] %-5level %logger
{36}
- %msg%n</pattern>
</encoder>
<filter class="ch.qos.logback.classic.filter.ThresholdFilter">

<level>INFO</level>
120 Qmatic 211.03K

</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]
/app/<application>/<application_package> [Optional]
/webapp/<web_application>/<war_file> [Optional]
/webapp/<web_application>/preDeploy.groovy [Optional]
/webapp/<web_application>/postDeploy.groovy [Optional]
/conf/<required_conf_content>
/conf/db/[Optional]
/conf/css/ [Optional]
/conf/images/ [Optional]
/conf/lang/<required_lang_content>
/conf/lib [E.g. java segmentation rules] [Optional]
/conf/security/<required_security_content>
/conf/scripts/ [Optional]
Folder content lists
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_security_content = keystore.jks
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.
211.03K Qmatic 121

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.
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, work-
stationterminal, wookie and jiql-admin-web.
7. Mandatory: /conf/<required_conf_content>
122 Qmatic 211.03K

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.
12. Optional:/conf/lib [E.g. java segmentation rules]
13. Mandatory: /conf/security/<required_security_content>
If the default profile is used as template the <required_security_content>

SHOULD NOT be changed.
<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.
211.03K Qmatic 123

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):
124 Qmatic 211.03K

2. Enter a unique Name for 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:
3. Click Ok in the confirmation window:
4. Force start the synchronization of the selected Queue Agent, see

“Synchronizing the Queue Agent” on page 126.
211.03K Qmatic 125

Synchronizing the Queue Agent

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, Syn-
chronized and Synchronization interrupted. The latter simply means that an
ongoing synchronization for some reason was interrupted, for example by
stopping the Queue Agent).
Parameters
In the Parameters tab of the System Administration application, you can change
the following types of parameters. For each Parameter, you see the Parameter
name and its value and it is also possible to restore the default value, by clicking
the Restore Defaults, , button.
• General Parameters
• System
• Connectors
• Cloud Services
• Weekend Settings
• Agent Parameters
• Queue Agent Settings
• HTTPS Parameters
• Certificate and key store Settings
• HTTPS server settings
126 Qmatic 211.03K

• Central WebSocket Server Settings

• Application Parameters
• Appointment Management Settings
• Recycle Settings
• Fault Manager Settings
• Mobile API (Central)
• Browser Settings
• User Settings
• Event Manager Settings
• Sorting Policy Settings
• Queue Agent Media Settings
• Statistics Settings
• SSO Settings
• LDAP Settings
• Pre Authentication and Authorization Settings
General Parameters
Parameter Description Default value
System General parameter, regarding the

whole system.
System Locale Language code for language used en

in the system.
For more information, see “Localisa-
tion” on page 173.
Connectors General parameters regarding con-

nectors.
Date Time Format Date and time format. HH:mm
Customer External Customer External JNDI Name java:global/

JNDI Name customCus-
tomerDb/cus-
tomerdbintegr
ation/Custom-
erCentralMan-
agerBean
211.03K Qmatic 127


Cloud Services Qmatic Cloud Services offers an
app that allows the customer to take
a ticket for a service offered by our
client as a complement to the tradi-
tional way of taking a ticket at the
Branch. The app will recommend
those Branches that offer the ser-
vice the customer is interested in
and gives the waiting time for each
Branch. It provides information
about the customer’s geographical
location and helps them navigate to
the Branch.
Enabled Whether or not Cloud Services is Not enabled

enabled.
Weekend Settings Parameter regarding scheduling of

Context Marketing Messages.
Weekend days Select which days of the week that Saturday

should be regarded as weekend Sunday
days. Default is Saturday and Sun-
day. This is used when scheduling
Context Marketing Messages.
For more information, see the
Administrator’s Guide.
Agent Parameters
Queue Agent Set- Parameters connected to the Queue

tings Agent.
Central HTTP Port Enter the port number that should 8080 for http
be used as the Central Orchestra and 8443 for
Server port. https.
Central HTTP Proto- Select either http or https from the http or https
col drop-down list.
128 Qmatic 211.03K

HTTPS Parameters
Certificate and key For more information, see “Secure

store Settings Communication” on page 217.
(Re)generate certifi- Enabling this check box and saving

cate the parameter list will cause the cer-
tificate to be generated in the key
store.
If a certificate with the same

alias already exists, it will be over-
written, so be careful!
KeyStore alias The alias of the certificate key entry, orchestra

in key store.
Distinguished name The distinguished name of the cer- CN=local-

tificate. The first (CN) section is the host,OU=orgU
host name of the server and the nit, O=org,
subsequent sections describe the L=city,
organization. S=state,
C=country-
Code
Subject alternate This field needs to be set to both IP localhost

name address and host name of the
server if both are going to be used
for HTTPS communication. Sepa-
rate each entry with a comma.
Example: myhost.com, 10.0.10.0.
HTTPS server set- For more information, see “Secure

tings Communication” on page 217.
HTTPS enabled Controls whether HTTPS should be disabled

enabled or not in JBoss/Wildfly.
Requires an Orchestra restart to

take effect.
KeyStore alias Determines which key entry in the

key store to use as a server certifi-
cate.
211.03K Qmatic 129


HTTPS port Decides which port to use for 8443
HTTPS communication.
Central WebSocket Settings connected to the Central

Server Settings Websocket server, heartbeat, etc.
WebSocket enabled If this check box is checked, Web Enabled

socket communication over unen-
crypted channels is allowed.
WARNING! Disabling this will cause
any distributed Queue Agent con-
nected over unencrypted Web-
Socket to stop functioning!
WebSocket port The port to use for unencrypted 8787

WebSocket communication.
WARNING! Changing this will
cause any distributed Queue Agent
connected over unencrypted Web-
Sockets to stop functioning, until
they are re-configured!
Secure WebSocket Enabling this parameter will cause Disabled

enabled the WebSocket server on Central to
support WebSocket secure. Make
sure that the certificate setting is
properly configured.
WARNING! Disabling this setting
will cause any Queue Agents that
are currently connected using
secure WebSocket to stop functio-
ning!
Secure WebSocket The port to use for secure Web- 9150

port Socket communication.
WARNING! Changing this parame-
ter will cause any Queueu Agents
that are currently connected using
secure WebSocket to stop functio-
ning, until they are re-configured!
Netty worker thread The number of worker threads avai- 100

pool size lable to handle web socket traffic.
Minimum 5, maximum 1000.
130 Qmatic 211.03K


Init commands thread The number of threads available to 5
pool size handle init commands from the
Queue Agents. Minimum 1, maxi-
mum 500.
Non-init commands The number of threads available to 5

thread pool size handle all non-init commands from
the Queue Agents. Minimum 1,
maximum 500.
Event thread pool The number of threads available to 5

size handle events from the Queue
Agents. Minimum 1, maximum 500.
Command pool size The number of threads tasked with 20

notification of results to commands.
Minimum 5, maximum 1000.
Command timeout The time in milliseconds to wait for a 60000

(milliseconds) response from a command sent to a
Queue Agent. Minimum 500, maxi-
mum180000.
Client connection The time, in milliseconds, to wait 120000

timeout (milliseconds) before a connection to a Queue
Agent is considered lost. Minimum
1000, maximum 600000.
Heartbeat interval The maximum time, in milliseconds, 30000

(milliseconds) before a heartbeat message is sent
to a Queue Agent if nothing else is
sent. Minimum 5000, maximum
120000.
Enable IP-address fil- This check box determines whether Not enabled
tering the web socket server should only
allow connections from certain IP-
addresses. If enabled, only addres-
ses specified in the definition
clause, below, will be allowed to
connect.
211.03K Qmatic 131


Allowed IP-addresses A comma-separated list of allowed
IP-addresses. Wildcards are
allowed. Localhost (127.0.0.1) is
always allowed.
Example:
192.168.2.2*,192.168.1.100 will
allow 192.168.2.2, a range from
192.168.2.20 to 192.168.2.29, a
range from 192.168.2.200 to
192.168.2.255, 192.168.1.100 as
well as 127.0.0.1.
Send extended heart- If this check box is checked, times- Not enabled
beat message tamps are included in the heartbeat
message. This is combined with
trace logging both centrally and on
selected Queue Agent(s) that have
the agent.conf property central.web-
socket.heartbeat.extended set to
true.
Delay start of web Increasing this value will delay the 0

socket server (sec- start of the web socket server and
onds) prevent any Queue Agent connec-
tions, until the web socket server is
started. This can, for example, be
used for a central system with many
distributed Queue Agents.
Application Parameters
Appointment Man- Parameters regarding Appointment

agement Settings management.
Delete appointments Applicable to Central. Number of 1

where endtime days that should pass, since the end
passed by (days) time of an appointment, before that
appointment is deleted.
Delete appointments Applicable to Central. Time when 02:00

at (hh:mm) appointments are deleted.
132 Qmatic 211.03K


Cron trigger for syn- Cron job trigger indicating when 000***
chronizing appoint- appointments should be synchro-
ments nized.
Cron trigger for delet- Cron job trigger indicating when 002***
ing old appointments appointments should be deleted.
Appointment Status Enable callbacks to certain URLs Enabled

callbacks enabled when appointments are updated
(HTTP PUT).
Appointment Status Comma separated list of URLs to /calendar-

update callback URLs which a HTTP PUT call will be sent backend/pub-
(comma-separated). when appointments are updated. lic/api/v1/
appointments/
callback
Appointment life cycle Enable or disable sending of events Not enabled

events enabled when appointments created,
updated, or deleted.
Block early appoint- Specify the number of minutes

ments (minutes) before the appointment start time,
that it is possible to call an appoint-
ment visit. Note that it is possible to
have a different number for different
Agent Profiles, here.
Recycle Settings Parameters regarding recycling of

tickets.
Recycle Max no The maximum number of times a 3

Recycles ticket can be recycled.
Recycle Insert Delay Number of seconds after which a 60

ticket can be recycled and placed
back into the queue at the first posi-
tion.
211.03K Qmatic 133


Fault Manager Set- Parameters regarding fault manage-
tings ment.
Upload Level Send faults of this severity and WARN

higher to central. Possible choices
are: INFO, WARN, ERROR;
FATAL).
Resend Interval (min- Interval in minutes between each 60

utes) attempt to send faults to central.
Upload Schedule JSON definition of allowed time [{“days”:[“Mon

slots for fault sending. ”,
“Tue”,”Wed”,”
Thu”,”Fri”,”Sat
”,”Sun”],”time”:
”00:00-
23:59”}]
Fault Manager ena- Whether or not the Fault Manager is Not enabled
bled enabled.
Mobile API (Central) Parameters regarding username

and password for the Mobile API.
Username Username used to access the mobile

Mobile API.
Password Password used to access the

Mobile API.
Mobile Ticket Base Base URL used when generating http://

URL URLs in e.g. barcodes, SMS mes- MobileTicket/
sages and other mobile ticket imple- MyVisit/Cur-
mentations. rentStatus
Browser Settings Chrome Frame is designed to

expand Internet Explorer’s function-
ality, by adding support for open
web technologies and Google
Chrome’s fast rendering engine.
Allow Browser When this check box is checked, Not enabled

Chrome Frame Chrome Frame is enabled.
134 Qmatic 211.03K


User Settings Parameters regarding User settings.
Min Login Code Lowest valid login code number. 1000
Max Login Code Highest valid login code number. 9999

Default is set to 9999.
UserName validation Regular expression used for user ^[a-z]+[a-z,0-

Pattern name validation. 9]*$
Password Validation Regular expression used for pass- ^.*(?=.{8,}(?=.*

Pattern word validation. \d)(?=.*[a-
z])(?=.*[A-
Z]).*$
Event Manager Set- Parameter regarding events.

tings
Upload Events to Whether or not events should be Events are

Central uploaded to Central (yes/no). uploaded.
Sorting Policy Set- Settings regarding sorting policy for

tings visits.
Multi service visit sort This setting affects how the visit is SORTED
policy transferred to the Queue of the next
Service in a multi-service Visit.
From the drop-down list, select the
wanted sorting policy; SORTED,
FIRST, or LAST.
Queue Agent Media Parameters regarding handling of

Settings media on Queue Agents.
Cron trigger for delet- Cron job trigger indicating when old 0 0 23 * * *
ing old media media will be deleted.
Allowed Download Time period when download is 00:00-23:59

Interval allowed.
Download media in Number of days in advance that 5

advance (days) media is downloaded.
211.03K Qmatic 135


Cron trigger for down- Cron job trigger indicating when 003***
loading media. media will be downloaded.
Statistics Settings Parameters regarding the handling

of statistics.
Enable Stat Mes- Whether or not sending of Stat mes- Enabled.

sages sages should be enabled.
Changing this value requires a

restart of both central and all Queue
Agents.
Stat Server Address IP v4 address to the stat resource http://
server. 127.0.0.1
Stat Server Port Port number where the stat 8080

resource is configured.
Stat Server Resource Application name for the stat /stat/message/

resource.
Queue Agent Res- Resend interval (minutes). 10

end Interval (minutes)
Queue Agent Upload JSON definition of allowed time [{“days”:[“Mon

schedule. slots for stat sending. ”,
“Tue”,”Wed”,”
Thu”,”Fri”,”Sat
”,”Sun”],”time”:
”00:00-
23:59”}]
SSO Settings For more information about the SSO

Settings, see “SSO setup” on
page 259.
Enabled Mark this check box to enable SSO. Not enabled

By default it is not enabled.
Allow basic authenti- Indicates if basic authentication is Not allowed

cation allowed.
Allow localhost Indicates if authentication is skipped Allowed

when the request comes from local-
host.
136 Qmatic 211.03K


Allow unsecure basic Only relevant if basic authentication Not allowed
is allowed. Specifies if HTTPS is
required when using basic authenti-
cation.
Client module Client module class name. spnego-client

Pre-authentication User name used for pre-authentica- preauthuser
user name tion, tied to an LDAP account.
Pre-authentication Password used with user name for

password pre-authentication.
Login server module Login server module class name. spnego-server
Prompt ntlm NTLM is not supported. Set this Not enabled.

value to true if clients who wish to
authenticate via NTLM should be
offered Basic Authentication
(assuming basic authentication is
allowed).
Allow delegation Indicates whether the filter for dele- Enabled

gation is enabled.
Logger level Valid values are 1 (finest) through 7 1

(severe), set to 1 for debugging/ver-
bose logging.
211.03K Qmatic 137


LDAP Settings LDAP configuration in Orchestra
consists of two tasks:
• Server configuration
• System parameters - found in
this table.
• Certificate handling - see
“LDAP Certificate Handling”
on page 141.
• LDAP/AD Group Mappings, e.g
how LDAP objects, groups are
mapped to Orchestra entities
(Roles, Branches/Branch
Groups). For more information,
see the Administrator’s Guide.
Each Orchestra attribute has a cor-
responding LDAP field attribute. For
more LDAP information, see “LDAP
Hosts/Urls” on page 141.
The user superadmin will

always log in locally. It is also possi-
ble to create users that are not
authenticated towards the Active
Directory.
Enabled When the check box is checked, all Not enabled.

users are authenticated towards the
configured LDAP server, that is the
Active Directory.
This parameter needs to be set

to true, in order to be able to per-
form LDAP mappings in the User
Management application.
Validate settings Validate settings against LDAP Enabled

server, when enabling LDAP. Disa-
bling allows settings to be saved,
even if LDAP server is not available.
Server URL(s) Space separated list of full LDAP ldap://local-

URL:s, e.g. ldap://somehost:somehost:389
Port
See “LDAP Hosts/Urls” on
page 141.
138 Qmatic 211.03K


Bind user Dn Bind user name, either account- addEntry-
Name@domain.foo or full DN. User@domain
Name.se
Bind user password Bind user password.
Base search context Defines the root context, from which CN=Users,DC
DN searches will origin. =your_do-
main,DC=com
Account search filter Defines how a user account DN (&(object-

should be searched for. Class=user)(s
AMAccount-
Name={0}))
Search timeout (mil- Defines the timeout for an LDAP 1000

lis) query in milliseconds.
User groups attribute User attribute that defines the memberOf

name groups of the user.
Mapped user attrib- Defines what user attributes that account-

utes should be returned when searching Name,first-
for a user. Name,lastNa
me,locale,rtl,lo
The values from the fields below ginCode
should be used in this string.
Account name Defines the user attribute mapped sAMAccount

mapped attribute to the account name. Name
First name mapped Defines the user attribute mapped givenName

attribute to the first name of the user.
Last name mapped Defines the user attribute mapped sn

attribute to the last name of the user.
Locale mapped attrib- Defines the user attribute mapped msExchUser-

ute to the locale of the user. Culture
RTL mapped attribute Defines the user attribute mapped rtl

to the right-to-left setting of the user.
Should be evaluated to true/false.
Login code mapped Defines the user attribute mapped loginCode

attribute to the login code of the user.
211.03K Qmatic 139


Pre Authentication For more information, see “SSO
and Authorization Setup Using Custom Pre-Authenti-
Settings cation Proxy” on page 264
Enabled Enable/disable Pre Authentication Disabled

and Authorization. This will also
enable the Pre Authorization tab in
the User Management application.
User name header Name of the HTTP header for user iv-user
name.
Group mapping IDs Name of the HTTP header for map- iv-groups
header ping name for role access.
Branch/branch group Name of the HTTP header for map- office_id

mapping IDs header ping name for branch access.
Given name header Name of the HTTP header for user’s givenname
given name.
Surname header Name of the HTTP header for user’s sn

surname.
140 Qmatic 211.03K

LDAP Hosts/Urls
The LDAP Hosts/Urls define what Active Directory hosts that should be used for
authentication.
Orchestra will try to connect to the first one in the list, if Orchestra establishes a
connection, the authentication will be performed towards that server. If the
connection fails because the server is unavailable/down, Orchestra will
automatically try the next server in the list.
Authentication will only be performed once, using the first available connection.
It is possible to specify the LDAP server port, if the server does not use the default
port, 389.
If the Active Directory server uses encrypted communication, that is LDAP over
SSL (Secure Sockets Layer), one must import the appropriate server certificates
in order to secure the connection.
For more information, see “Example:” on page 142.
Note that the server url is different in this case, ldaps://server:636. The default
secure port is 636.
LDAP Certificate Handling
You must export the CA certificate from the Active Directory server to enable
Secure Sockets Layer (SSL) security.
Different Corporate organizations have different methods and processes to create
a CA root certificate. The procedure below provides information on creating a
personal CA for Active Directory 2003.
211.03K Qmatic 141

Procedure
1. Log on as a domain administrator on the Active Directory domain server.
2. Install the certificate authority (CA) on the Microsoft Windows Server, which
installs the server certificate on the Active Directory server. To do so, complete
the following steps:
a Click Start > Control Panel > Administrative Tools > Certificate Authority to
open the CA Microsoft Management Console (MMC) GUI.
b Highlight the CA computer, and right-click to select CA Properties.
c From General menu, click View Certificate.
d Select the Details view, and click Copy to File on the lower-right corner of
the window.
e Use the Certificate Export wizard to save the CA certificate in a file.
You can save the CA certificate in either DER Encoded Binary X-509 format
or Based-64 Encoded X-509 format.
Adding AD/LDAP server certificate to Orchestra Central

The Active Directory/LDAP server certificate must be added to the trusted store of
certificates on Orchestra.
Preparation:
1. Copy the Active Directory Server certificate to a temporary location, for
example:
C:\TEMP\myADcert.cer
SSL Certificate import:

1. In Orchestra conf/security folder, execute the following:
keytool -import -keystore truststore -file <cert-file> -storepass
changeit
2. Edit app/<jboss-eap-6.3 or wildfly-8.2.0.Final>/bin/standalone.conf.bat.
Make sure that the password entered above matches the following param-
eter value:
javax.net.ssl.trustStorePassword=changeit
Example:
Owner: CN=elkcertificate, DC=elk, DC=se
Issuer: CN=elkcertificate, DC=elk, DC=se
Serial number: 423e55f0dff557b24ffe5e41a7df65c8
142 Qmatic 211.03K

Valid from: Thu Nov 13 11:02:53 CET 2008 until: Wed Nov 13 11:10:07
CET 2013
Certificate fingerprints:
MD5: 36:C0:35:A0:FA:4B:81:B4:F2:35:F2:F3:13:CF:73:92
SHA1:
C3:F6:56:A5:F0:49:65:DE:DA:D5:64:94:FD:88:8D:32:8E:95:8F:87
SHA256:
76:6A:02:FF:6C:A3:3C:74:BC:CF:C8:A6:23:F1:13:3F:69:6E:F0:BE:53:6E:
AB:AF:78:2A:6F:22:F1:73:A9:9A
Signature algorithm name: SHA1withRSA
Version: 3
Extensions:
#1: ObjectId: 1.3.6.1.4.1.311.21.1 Criticality=false

0000: 02 01 00 ...
#2: ObjectId: 2.5.29.19 Criticality=true

BasicConstraints:[
CA:true
PathLen:2147483647
]
#3: ObjectId: 2.5.29.31 Criticality=false

CRLDistributionPoints [
[DistributionPoint:
[URIName: ldap:///
CN=elkcertificate,CN=testpc2,CN=CDP,CN=Public%20Key%20Services,CN=
Services,CN=Configuration,DC=elk,DC=se?certificateRevocationList?b
ase?objectClass=cRLDistributionPoint, URIName: http://
testpc2.elk.se/CertEnroll/elkcertificate.crl]
]]

KeyUsage [
DigitalSignature
Key_CertSign
Crl_Sign
]

SubjectKeyIdentifier [
KeyIdentifier [
0000: 39 C9 64 7C 58 79 86 A2 62 01 80 FF 09 1E F5 43
9.d.Xy..b......C
0010: 5C 23 14 DD \#..
]
]
Trust this certificate? [no]: yes

Certificate was added to keystore
211.03K Qmatic 143

3. Orchestra can now use SSL for communicating with the Active Directory.
If either of the SSL parameters in the configuration file was changed, for
example trust store file name or trust store password, the Orchestra must be
restarted in order to commit the changes.
Adding AD/LDAP server certificate to Distributed Queue Agent

1. Copy the Active Directory server certificate to a temporary location, e.g.
C:\TEMP\fooAD-DER.cer, /tmp/fooAD-DER.cer
2. Go to the profile template for the distributed Queue Agent, e.g.
*nix:
<install_dir>/media/agentProfiles/2.3-master-custom/conf/security
Windows:
<install_dir>\media\agentProfiles\2.3-master-custom\conf\security
3. Import the certificate using the standard Java command key tool:
keytool -import -keystore truststore.jks -file C:\TEMP\fooAD-DER.cer
-storepass changeit
Mark Types
Mark Types are typically used for when a Customer Feedback Unit (CFU) of some
kind (either an Expressia, or a CFU tablet) is part of your system. Before those
units can be set up, Mark Types must be created, in this tab and Marks must be
created in the Business Configuration application.
Mark Types and Marks are also used to define the Outcomes that can be
connected to Services. For this, there is a pre-installed Mark Type available in
Orchestra.
For more information, see the Administrator’s Guide, found on Qmatic World.
Another possible way to use Mark Types and Marks is for NPS® scoring. NPS1
stands for Net Promoter Score. For more information, see http://en.wikipedia.org/
wiki/Net_Promoter. NPS scoring can, for example, be used in the Mobile Connect
app.
1. Net Promoter, NPS, and the NPS-related emoticons are registered service
marks, and Net Promoter Score and Net Promoter System are service marks, of
Bain & Company, Inc., Satmetrix Systems, Inc. and Fred Reichheld.
144 Qmatic 211.03K

There is a pre-installed, default NPS Mark Type available in Orchestra. For this
Mark Type, the following marks are available: 0-10 and skip. By default, Codes
enabled is disabled and Visible in configuration is enabled for this Mark Type.
When the Mark Types tab is opened, all available Mark Types are listed:
In this tab, it is also possible to delete existing Mark Types.
The pre-installed Outcome Mark Type can, however, not be deleted. Also, it is
not possible to update its Id.
To create a new Mark Type, click the Create Mark Type button. The following
window is opened:
Here, you enter a Name of the Mark Type. Optionally, enter a Description. Also,
decide if Codes should be enabled for the Mark Type and if it should be Visible in
the configuration, by checking the applicable check boxes.
When a new Mark Type has been created, it is possible to add Marks to it. This is
done in the Business Configuration application.
211.03K Qmatic 145

146 Qmatic 211.03K

6. HW Monitoring
Introduction ......................................................................... 148

Installation and Configuration .............................................. 148
Device Controller (GW1745) - Connect/Disconnect ............ 154
Queue Agent - Connect/Disconnect .................................... 155
Printer - Stat Messages ....................................................... 155
211.03K Qmatic 147

Introduction
Orchestra comes with a feature called Hardware Monitoring. It is used to keep

track of the status of many different parts of the system. It monitors the current
status of Queue Agents, Device Controllers and some devices, as well as keeping
statistics and raw data about their status in the stat database. This way, it allows
for organizations to act on events in real time, by adding custom logic to the event
system.
For more information about the Hardware Monitoring application, please see the
Administrator’s Guide, found on Qmatic World.
Installation and Configuration
Prerequisite:
For distributed systems, port 5445 needs to be opened in the firewall.
Data Integration
For more information about Data Integration, please refer to “Hardware Monitoring
- Data Integration” on page 172.
Installation - Separate BI Server
Wildfly
Follow these steps on the BI Server:
1. Open the application server configuration file. <installation directory>/app/
wildfly-8.2.0.Final/standalone/configuration/standalone-full.xml, in your
preferred text editor.
2. Locate the existing section:
<response-header name="xFrameOptions" header-name="X-Frame-Options"
header-value="SAMEORIGIN"/>
3. Change the header-value, to allow frames on the Central Orchestra server:
<response-header name="xFrameOptions" header-name="X-Frame-Options"
header-value="ALLOW-FROM http://{orchestra-server}"/>
where {orchestra-server} is the IP-address or domain name of the Central
Orchestra server.
4. Restart the BI application server.
148 Qmatic 211.03K

HW Monitoring
JBoss
Follow these steps on the BI Server:
1. Open the application server configuration file, <installation directory>/app/
jboss-eap-6.3/standalone/configuration/standalone-full.xml, in your preferred
text editor.
2. Locate the existing section:
<valve name="xFrameOptions" module="qmatic-valve-lib" class-
name="com.qmatic.jboss.web.valve.HttpResponseHeaderValve">
<param param-name="responseHeaderName" param-value="X-Frame-
Options"/>
<param param-name="responseHeaderValue" param-value="SAMEORI-
GIN"/>
</valve>
3. Change the header-value to allow frames on the Central Orchestra Server:
name="com.qmatic.jboss.web.valve.HttpResponseHeaderValve">
Options"/>
<param param-name="responseHeaderValue" param-value="ALLOW-
FROM http://{orchestra-server}"/>
</valve>
where {orchestra-server} is the IP-address or domain name of the Central
Orchestra Server.
4. Restart the BI application server.
Configuration - Stat on a Separate Server
Configuration of Standalone Stat Server on Wildfly

If stat.war is deployed in a different application server than qSystem.ear, it is
necessary to do a number of changes to the JMS configuration in order to get
events forwarded from the Central server to the Stat server.
JMS queues and bridges are defined in the configuration file <ORCHESTRA>/app/
wildfly-8.2.0.Final/standalone/configuration/standalone-full.xml, which is present
in both installations.
1. On the server where Orchestra stat (stat.war) is deployed, create a user. In this
example we use username="jms" and password="password", for the lookup of
Queues, by running the script add-user, <ORCHESTRA>/app/wildfly-
8.2.0.Final/bin/add-user.bat, on Windows, or <ORCHESTRA>/app/wildfly-
8.2.0.Final/bin/add-user.sh, on Linux.
211.03K Qmatic 149

When running the script, supply the following input when prompted:
• b (application user)
• username you selected
• password you selected
• password again
• (blank) - simply press enter to indicate that the user should not belong to a
particular group
• yes (validate the input settings)
• no (indicate that the user is not going to connect from another AS process,
for e.g. EJB remoting)
If you enter a weak/short password, for example password, as in this

example, you might get a warning such as “JBAS015264: Password is not
strong enough, it is 'MODERATE'. It should be at least 'MEDIUM'. Are you sure
you want to use the password entered yes/no?” or “JBAS015269: Password
must have at least 4 characters! Are you sure you want to use the password
entered yes/no?”. If this is the case, enter “no” and the script will prompt you for
user/password again, or enter “yes” to use the password anyway.
Example execution:
What type of user do you wish to add?
a) Management User (mgmt-users.properties)
b) Application User (application-users.properties)
(a): b
Enter the details of the new user to add.

Using realm 'ApplicationRealm' as discovered from the existing
property files.
Username : jms
Password recommendations are listed below. To modify these
restrictions edit the add-user.properties configuration file.
- The password should not be one of the following restricted values
{root, admin, administrator}
- The password should contain at least 4 characters, 1 alphabetic
character(s)
- The password should be different from the username
Password :
Re-enter Password :
What groups do you want this user to belong to? (Please enter a comma
separated list, or leave blank for none)[ ]:
About to add user 'jms' for realm 'ApplicationRealm'
Is this correct yes/no? yes
Added user 'jms' to file 'C:\qmatic\orchestra\61evtpsql\app\wildfly-
8.2.0.Final\standalone\configuration\application-users.properties'
Added user 'jms' to file 'C:\qmatic\orchestra\61evtpsql\app\wildfly-
8.2.0.Final\domain\configuration\application-users.properties'
150 Qmatic 211.03K

HW Monitoring
Added user 'jms' with groups to file

'C:\qmatic\orchestra\61evtpsql\app\wildfly-
8.2.0.Final\standalone\configuration\application-roles.properties'
Added user 'jms' with groups to file
'C:\qmatic\orchestra\61evtpsql\app\wildfly-
8.2.0.Final\domain\configuration\application-roles.properties'
Is this new user going to be used for one AS process to connect to
another AS process?
e.g. for a slave host controller connecting to the master or for a
Remoting connection for server to server EJB calls.
yes/no? no
2. On the server where Orchestra Central (qSystem.ear) is deployed, open the file
<ORCHESTRA>/app/wildfly-8.2.0.Final/standalone/configuration/standalone-
full.xml and locate the section:
<jms-bridge name="centralAgentEventBridge">
<source>
<connection-factory name="ConnectionFactory"/>
<destination name="queue/centralAgentEventQueue"/>
</source>
<target>
<destination name="queue/statAgentEventQueue"/>
</target>
<quality-of-service>AT_MOST_ONCE</quality-of-service>
<failure-retry-interval>10000</failure-retry-interval>
<max-retries>-1</max-retries>
<max-batch-size>10</max-batch-size>
<max-batch-time>100</max-batch-time>
</jms-bridge>
3. Then, replace the <target> sections with the following, where the
java.naming.provider.url should contain the IP-address of the application server
where stat.war is deployed:
There are two instances of the <target> section!

<target>
<connection-factory name="jms/RemoteConnectionFactory"/>
<destination name="queue/statAgentEventQueue"/>
<context>
<property key="java.naming.factory.initial"
value="org.jboss.naming.remote.client.InitialContextFactory"/>
<property key="java.naming.provider.url" value="http-remoting:/
/192.168.1.1:8080"/>
<property key="java.naming.security.principal" value="jms"/>
<property key="java.naming.security.credentials"
value="password"/>
</context>
</target>
211.03K Qmatic 151

If Central has trouble connecting to the remote stat server, make sure that
firewall rules allow connections to port 8080.
If Orchestra Central still experiences JMS connection errors, such as:
WARN [org.hornetq.jms.server] (pool-3-thread-3) HQ122010: Failed to
connect JMS Bridge: javax.naming.CommunicationException: Failed to
connect to any server. Servers tried: [http-remoting://
192.168.1.2:8080 (Operation failed with status WAITING after 5000
MILLISECONDS)] [Root exception is java.net.ConnectException:
Operation failed with status WAITING after 5000 MILLISECONDS]
Or the following error in the stat server’s Wildfly server.log:

INFO [org.jboss.as.naming] (default task-16) JBAS011806: Channel end
notification received, closing channel Channel ID 1362678f
(inbound) of Remoting connection 02b0b61f to /192.168.1.2:55380
This combination of messages means that the remote stat Wildfly installation has
trouble making an internal JMS connection which it may be trying to perform
against address 0.0.0.0 by default, which must be changed. It is changed by editing
the remote stat’s Orchestra run.bat / run.sh script, which resides in the <remote
stat install dir>/bin folder.
For Linux installations, change the last line to this (change IP as needed):
"$QP_HOME"/app/wildfly-8.2.0.Final/bin/standalone.sh -b=192.168.1.2
--server-config=standalone-full.xml
For Windows installations, change the following line:

CALL standalone.bat --server-config=standalone-full.xml
to this:
CALL standalone.bat -b=192.168.1.2 --server-config=standalone-
full.xml
Configuration of Standalone Stat Server on JBoss

Follow these steps:
1. Open the file <ORCHESTRA>/app/jboss-eap-6.3-8.2.0.Final/standalone/
configuration/standalone-full.xml on the Central server.
2. Locate the section socket-binding-group entry remote-jms and change the
remote-destination host from "localhost" to the address of the stat server:
<socket-binding-group name="standard-sockets" default-
interface="public" port-offset="${jboss.socket.binding.port-
offset:0}">
152 Qmatic 211.03K

HW Monitoring
<socket-binding name="management-native"
interface="management"
port="${jboss.management.native.port:9999}"/>
<socket-binding name="management-http" interface="management"
port="${jboss.management.http.port:9990}"/>
<socket-binding name="management-https"
interface="management" port="${jboss.management.https.port:9443}"/
>
<socket-binding name="ajp" port="8009"/>
<socket-binding name="http" port="8080"/>
<socket-binding name="https" port="8443"/>
<socket-binding name="jacorb" interface="unsecure"
port="3528"/>
<socket-binding name="jacorb-ssl" interface="unsecure"
port="3529"/>
<socket-binding name="messaging" port="5445"/>
<socket-binding name="messaging-group" port="0" multicast-
address="${jboss.messaging.group.address:231.7.7.7}" multicast-
port="${jboss.messaging.group.port:9876}"/>
<socket-binding name="messaging-throughput" port="5455"/>
<socket-binding name="remoting" port="4447"/>
<socket-binding name="txn-recovery-environment" port="4712"/>
<socket-binding name="txn-status-manager" port="4713"/>
<outbound-socket-binding name="mail-smtp">
<remote-destination host="localhost" port="25"/>
</outbound-socket-binding>
<outbound-socket-binding name="remote-jms">
<remote-destination host="statServerHost" port="5445"/>
</outbound-socket-binding>
</socket-binding-group>
3. Then, modify the jms-bridge to use the connection-factory

"QPStatEventConnectionFactory" instead of "ConnectionFactory":
<jms-bridge name="qpStatEventBridge">
<source>
<destination name="queue/qpCentralEventQueue"/>
</source>
<target>
<connection-factory
name="QPStatEventConnectionFactory"/>
<destination name="queue/qpStatEventQueue"/>
</target>
<quality-of-service>AT_MOST_ONCE</quality-of-service>
<failure-retry-interval>10000</failure-retry-interval>
<max-retries>-1</max-retries>
<max-batch-size>10</max-batch-size>
<max-batch-time>100</max-batch-time>
</jms-bridge>
4. Restart the Central server
211.03K Qmatic 153

Device Controller (GW1745) - Connect/Disconnect
The following image shows JMS Queues, bridges and configuration files for HW
monitoring:
It is logged in stat when a GW1745 connects and disconnects. It is also possible

to see information such as version and IP address for each connected GW1745.
Allowed time slots for stat sending are defined in the Queue Agent Upload
schedule parameter, in the Statistics Settings section of the Parameters tab in the
System Administration application.
The scheduler will only use the first value found in the Queue Agent Upload
schedule parameter.
154 Qmatic 211.03K

HW Monitoring
Queue Agent - Connect/Disconnect
It is logged in stat when your Queue Agent(s) and Daemon(s) connects and
disconnects.
Also, it is possible to see information such as version of the Queue Agent /
Daemon, IP address, MAC address, current profile, etc.
Printer - Stat Messages
Connect Event
A Connect event is sent to Stat when:
• Any status message (except for NET_ERROR) while previously being in dis-
connected state is received.
• The Queue Agent holds current connection status, due to printers not having a
proper Connect event.
Disconnect Event
A Disconnect event is sent to Stat when:
• GW1745 is disconnected.
• A status event, containing NET_ERROR is received for printer device (sent
from Device Controller, when unable to reach printer).
Other Events
Except for the above, the following Stat messages are available for the printer:
• LOW_ON_PAPER
• OUT_OF_PAPER
• PAPER_JAM - sensors only on TP Button Hardware.
• THERMAL_HEAD_RELEASED
• NO_KNOWN_ISSUES
Multiple statuses can occur at the same time from the printer. The
NO_KNOWN_ISSUES event is sent when the printer goes from having a warning
state, which is being resolved.
211.03K Qmatic 155

156 Qmatic 211.03K

7. Auditing
Introduction ......................................................................... 158

What is logged? .................................................................. 158
Where is it stored? .............................................................. 159
Enabling/disabling the functionality ..................................... 161
211.03K Qmatic 157

Introduction
As of Orchestra 6.2, we have introduced auditing functionality to Orchestra.

As businesses grow, we see a larger and larger need to track and store information
about who does what in the system.
Below is a description of how auditing events are captured and stored in Orchestra
as well as how to enable/disable the auditing functionality.
What is logged?
The Business Intelligence and Calendar applications have their own auditing
functionality.
Below is a description of the different areas where audit information is logged.
Login/logout events
The following is logged:
• Successful login
• Unsuccessful login
• Logout
Only login/logout attempts towards Central are logged.
Configuration changes
Database changes (CUD) in qp_central are logged.
For example:
• Branch publish.
System activities, triggered by the Queue Agent, are not logged.

• Branch configuration.
• Service configuration.
• Work Profile configuration.
• Segmentation Rule configuration and Queue handling.
• Context Marketing configuration.
• Unit Type configuration.
• Surface Application configuration.
• Mark Types and Marks.
158 Qmatic 211.03K

Auditing
• User management.
No auditing events are stored for handling of widgets (for example uploading
or deleting widgets).
Some tables are filtered, i.e not logged to auditing.
Queue Agent
• Configuration changes, such as Agent Profile synchronization and Upgrade.
Updates triggered by the Queue Agent are not logged.

• Starting and stopping a Queue Agent
Calendar
• Who (which User) booked/deleted/confirmed/updated the Appointment and at
what time?
Where is it stored?
Central
Auditing is stored in the qp_auditing database, in the events table. This table
contains the following columns:
• id (integer)
• event_date_time (timestamp without time zone)
• category (text) - example: login
• old_value (text)
• new_value (text)
• principal (text) - Describes the User in the local custom fashion.
• remote_host (text)
• server_host (text)
• origin_code (text) - The source code location for the place where the action of
the event audited is taking place.
• entity_name (text)
• entity_id (text) - For example the Branch Id.
211.03K Qmatic 159

• description (text) - May only be null if either of the columns old_value or

new_value have content. Example “A failed login attempt occurred.”
For CREATE events, old_value is stored as null and new_value is stored as a
shallow JSON string of the created object.
For UPDATE events, old_value contains the detected updated parameters with
the value before the change and new_value is stored as a shallow JSON string of
the updated object.
For DELETE events, the old value is a shallow JSON string of the deleted object
and the new_value is stored as null.
A shallow JSON string means that referenced objects will be presented as a list of
id:s.
Calendar
Auditing is stored in the database qp_calendar, in the calendar_audit table. This
table contains the following columns:
• id (bigint)
• branch_id (bigint)
• change (text)
• entity_id (bigint)
• entity_type (character varying, 255)
• audit_operation (character varying, 255)
• time_stamp (character varying, 255)
• user_name (character varying, 255) - the name of the logged in User. QP_-
PUBLIC means that no User was logged in when the event took place.
160 Qmatic 211.03K

Auditing
Enabling/disabling the functionality
Installation - Orchestra Central

The auditing database, qp_auditing is created by default during a fresh installation
of Orchestra 6.2.
In the install.properties file, you can find the application called application.auditing,
which by default is set to true. The properties for the qp_auditing database can also
be found in the install.properties file.
Auditing can also be found as one of the applications in the Installation Wizard.
Upgrade
The auditing database, qp_auditing, is not automatically created during upgrade.
Enabling auditing in an upgrade requires setting up the required user and table, as
well as modifying the install.properties file.
To enable auditing, follow the steps described in Configuration - Database, below.
(Oracle Database / Microsoft SQL / PostgreSQL).
Microsoft SQL). For PostgreSQL, see special instructions below.
script:
<tmp_dir>/db/auditing-mssql.sql
Oracle Database:
<tmp_dir>/db/auditing-oracle.sql
PostgreSQL:
1. Make sure that the PostgreSQL bin folder is added to environment varia-
bles.
3. Run the command:
psql -U postgres -f auditing-postgres.sql
211.03K Qmatic 161

Configuration - Installation Wizard

It is possible to select Auditing in the wizard, when upgrading. However, you will,
in that case, be notified that the database scripts described above need to be run
before you proceed.
If you select Auditing as an application when upgrading, you will first need to select
the wanted database:
Note that Oracle is not supported when running the Wildfly Application Server.
162 Qmatic 211.03K

Auditing
Next, you need to fill in Hostname and Port for your database, as in the following
example for PotgreSQL:
211.03K Qmatic 163

Configuration - install.properties file

Set application.auditing = true.
Modify the audit db settings for the database picked in the previous step to match
those of your db.
Example for PostgreSQL:
auditing.db = postgres
auditing.postgres.db.host = localhost
auditing.postgres.db.user = qp_auditing_insert
auditing.postgres.db.password = qp_auditing_insert
auditing.postgres.db.port = 5432
auditing.postgres.db.name = qp_auditing
Run the upgrade in silent mode, using the command install.bat -s for Windows, or
install.sh -s for Linux.
164 Qmatic 211.03K

8. Stat Aggregation
Introduction ......................................................................... 166

Stat PDI Jobs/Transformations - Example Configuration .... 166
Hardware Monitoring - Data Integration .............................. 172
211.03K Qmatic 165

Introduction
Pentaho Data Integration (PDI)

Pentaho Data Integration (PDI), also referred to as Kettle/Spoon, is a tool that can
be used for creating jobs/transformations that are used for data aggregation.
To be able to create your own, customized, data aggregations, you need to install
PDI. The installation file can be found on Qmatic World. Unzip the installation file
to a suitable location and run the Spoon.bat file.
For more information about PDI, please refer to http://www.pentaho.com/product/
data-integration.
Do not install PDI on production servers, only for development of

transformations!
Disclaimer
Pentaho Data Integration (PDI) is a third party tool. Qmatic is in no way responsible
for support, maintenance, or translation of this tool.
Existing Jobs/Transformations in Orchestra

Orchestra Stat supports running PDI jobs/transformations by triggering them for
configured events. Any event sent to Stat can be configured to trigger jobs.
There is a file called stat-jobs.xml, located in <orchestra installation directory>/
conf/stat-jobs, where events and jobs/transformations are configured. The
following section explains how to configure them.
Stat PDI Jobs/Transformations - Example Configuration

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<kettle-jobs>
<job filename="qmatic/visit-transaction.ktr" max-events-
before-processing="10000" batch-limit="10000" max-time-before-
processing="10" >
<event name="VISIT_END" />
<event name="VISIT_END_TRANSACTION" />
<event name="VISIT_REMOVE" />
<event name="END_SERVICE" />
<event name="VISIT_TRANSFER_FROM_QUEUE" />
<event name="VISIT_NOSHOW" />
</job>
<job filename="qmatic/service-point-session.ktr" max-events-
before-processing="10000" batch-limit="10000" max-time-before-
processing="10" >
<event name="SERVICE_POINT_CLOSE" />
</job>
166 Qmatic 211.03K

Stat Aggregation
<job filename="qmatic/staff.ktr" max-events-before-

processing="10000" batch-limit="10000" max-time-before-
processing="10" >
<event name="USER_SESSION_END" />
</job>
</kettle-jobs>
The root element <kettle-jobs> contains all configurations. This element contains
a list of <job> elements that define which type of jobs and transformations are con-
figured in the system. Job definitions can be either kettle jobs (.kjb files) or kettle
transformations (.ktr files). Each job definition also contains settings for how often
the job is supposed to run, and optionally a list of <event> sub-elements which de-
fine which events that trigger the particular job.
The transformation file to process when the event arrives is configured with attrib-
ute filename that expects the file to exist relative to Orchestra’s conf/stat-jobs fold-
er. Here filename is qmatic/visit-transaction.ktr which means the file must be in
folder conf/stat-jobs/qmatic. If any configured file is missing at Orchestra start up,
stat will fail with an error message.
Attribute max-events-before-processing controls how many events should pass
through the system before the job is executed. If this is set to 1, or left out entirely,
the job will execute for every event (this is not advisable for events with a high
throughput). All events defined for the job are counted towards this max-events-
before-processing setting.
The attribute max-time-before-processing controls the maximum amount of time
the system should wait before triggering the job execution.
The job will be executed when the configured (max-events-before-processing set-
ting) number of events have passed through the system, or when the configured
time (max-time-before-processing) has passed. Each time the job is triggered, the
counter for max-events-before-processing is reset.
The setting batch-size is a setting that will be sent to the job as a parameter, which
will indicate to the job how many events it should process in one execution.
Qmatic and Custom jobs/transformations

There are two separate folders in the conf/stat-jobs directory. These are qmatic
and custom. The qmatic folder contains all internal Orchestra jobs/transformations
that are required by Stat, to get correct system functionality.
These (or their configuration) must not be altered in any way.

Any custom requirements are met by creating custom jobs/transformations that
shall be added to the custom directory. Custom jobs/transformations are
referenced in stat-jobs.xml by prepending the job filename with the “custom/”
folder.
211.03K Qmatic 167

Example:
<job filename=”custom/test.ktr”/>
Processing events
The following example illustrates how event and job/transformation processing is
handled:
<kettle-jobs>
<job filename="qmatic/visit-transaction.ktr" max-events-
before-processing="10" batch-limit="1+" max-time-before-
processing="10" >
<event name="VISIT_END" />
<event name="VISIT_END_TRANSACTION" />
</job>
<job filename="custom/myJob.ktr" max-events-before-
processing="1" max-time-before-processing="10" >
<event name="VISIT_NOSHOW" />
</job>
<job filename="custom/myOtherJob.ktr" max-time-before-
processing="10" />
</kettle-jobs>
In this example, every time a visit is completed (VISIT_END) or a multi-service-visit

has a service completed (VISIT_END_TRANSACTION), the counter for the visit-
transaction.ktr is incremented. When this counter reaches 10, (configured by max-
events-before-processing) the job will be executed.
If no (or fewer than 10) events are processed in a 10 minute interval (configured
by max-time-before-processing), the job will be executed anyway. Each time the
job executes the counter and timer is reset.
Here is a timing example:
00:00 – system initializes – timer is started for job to run at 00:10.
00:08 – 10 events have been processed, job is started. Counter is reset to 0 and
timer is reset to start at 00:18.
00:18 – 5 events have been processed. Job is started by timer, counter is reset to
0 and timer is reset to start at 00:28.
The job custom/myJob.ktr in this example has max-events-before-processing set

to 1, meaning it will trigger on all events with name VISIT_NOSHOW. It is not
recommended to use this setup with an event that is very common, as it could
severely impact performance.
The job custom/myOtherJob.ktr does not have any events configured for it,
meaning the job will be run on schedule only. In this configuration, the job will run
168 Qmatic 211.03K

Stat Aggregation
once every 10 minutes. This type of configuration is suitable when no reasonable

event exists that could trigger the job, and certain calculations / actions need to be
done periodically.
Jobs that fail due to errors in the job/transformation itself are logged but not
processed further. They will be stored in the failed_jobs table in the database. For
more information, see Stat REST API in the connector SDK for the rest endpoint
to replay failed aggregations. Also, see “Failed jobs” on page 171.
Filtering on event type

Certain events are common across multiple domains, an example of this is the
CONNECT event, which is sent both when Queue Agents connect and when
devices (printers) and device controllers (gw1745) connect.
In order to be able to separate these events, one can use the event-type attribute
to separate between these different types of event domains.
The defined event-types are:
• AGENT_DAEMON
• AGENT_JIQL
• DEVICE_CONTROLLER
• DEVICE
• STAFF
• SERVICE_POINT
• VISIT
• APPOINTMENT
An example configuration could be:
<event name="CONNECT">
<job filename="custom/device-connect.ktr" event-type="DEVICE" />
<job filename="custom/agent-connect.ktr" event-type="AGENT_JIQL" />
</event>
The different event types are used in the following scenarios:

• DEVICE: Printer connect and disconnect events. Printer status events (e.g.
OUT_OF_PAPER)
• DEVICE_CONTROLLER: Device controller (gw1745) connect and disconnect
events
• AGENT_JIQL: Publish events. End-of-day events sent from Queue Agents.
Branch events sent from central (at e.g. Branch update or delete). Queue
Agent connect / disconnect events.
211.03K Qmatic 169

• AGENT_DAEMON: End-of-day events sent from central. Retire events sent

from central (when Queue Agent is deleted). Daemon connect / disconnect
events.
• STAFF: Staff events (session start / end etc).
• SERVICE_POINT: Service point events (service point open / close).
• VISIT: Visit events (create, call, end etc).
• APPOINTMENT: Appointment events sent from central (create, update, can-
cel).
Transaction validation
The transaction count validation performed before running a job/transformation
whenever the attribute validate-transaction-count-before-execution is set to true
does the following:
1. Count the number of entries in fact_visit_transaction for the Staff/Service Point
transaction in question.
2. Count the number of entries in failed_events for the same transaction.
3. If the sum of these two totals are the same as the number of transactions that
the Staff/Service Point has served during the session, then the validation will
succeed.
If the validation fails (e.g. an event belonging to the transaction has not yet arrived
to Stat), the following steps will occur:
1. The job will be rescheduled for execution 10 seconds later (default value, can
be configured).
2. The job will be rescheduled as long as the validation fails, up to 5 times before
giving up (default value, can be configured).
3. If the validation has failed the maximum number of times, an entry will be added
to the failed_jobs table.
The following stat-jobs.xml entry gives an example on how to reconfigure the
rescheduling values mentioned above:
<event name="USER_SESSION_END">
<job filename="qmatic/test_user_end_session.ktr" validate-
transaction-count-before-execution="true" maximum-validation-
failure-retry-count="1" validation-failure-retry-interval-
seconds="20"/>
</event>
170 Qmatic 211.03K

Stat Aggregation
Failed events
To list events that have failed for some reason:
GET <host:port>/stat/rest/events/listFailedEvents
To process failed events (using the result of the above REST call as input):
POST <host:port>/stat/rest/events/processFailedEvents
Failed jobs
To return a list of failed jobs:
GET <host:port>/stat/rest/kettleJobs/failed
To take a list of failed jobs as input to replay - this command is preferrably
combined with the above REST call:
POST <host:port>/stat/rest/kettleJobs/replay
Example of how this can be used:

GET localhost:8080/stat/rest/kettleJobs/failed
Answer: [1,3,4]
POST localhost:8080/stat/rest/kettleJobs/replay
Body: [1,3,4]
Outcome: Will try to replay jobs 1,3 and 4.
Failover Behaviour
If a message cannot be processed, it will get saved to the failed_events table, with
some information that enables the message to be re-played in the future.
In the case of a serious system error, e.g. the database cannot be reached, the
message will not be able to be saved to the failed_events table.
In this scenario, the following will happen:
• The message listener will stop processing messages for a while (default 5
minutes).
• The failed message will be put back on the queue and will be processed later.
• In the case that the event(s) in the message has been successfully saved to
the database, and only the aggregation is missing, the message will only be
re-sent 10 times.
• After 10 times, the message will end up in a "dead letter" queue, e.g. statVis-
itEventQueueDeadLetterQueue for visit events.
• Messages that have not had their event(s) saved to the relevant event table(s)
will not be put on the dead letter queue, however if there are multiple failures
211.03K Qmatic 171

where a new instance of the message cannot be re-sent to the queue the
message might end up in the dead letter queue eventually.
Settings to control the behaviour are defined in stat.conf, except for the limit of 10
consecutive retries, which is in standalone-full.xml (as it is a hornetq setting).
Hardware Monitoring - Data Integration
The flexible plug in architecture implemented in Orchestra, where plug ins are
written as transformation jobs, as described in “Stat PDI Jobs/Transformations -
Example Configuration” on page 166, makes it possible to react to events from the
Hardware Monitoring functionality. For more information, see “HW Monitoring” on
page 147.
The default installation does not come with any plug ins activated, but the process
of activating your own plug ins is simple. It is described below:
1. Create and test your transformation in Pentaho PDI.
Pentaho PDI contains a visual editor for developing jobs. You can also use or
customize the official job examples, found on Qmatic’s official github account.
2. Deploy the resulting .ktr file
The .ktr file is the definition of the transformation/job into the Orchestra deploy-
ment.
The standard location for jobs are at <installation_directory>/conf/stat-jobs/
qmatic but you can also use the <installation_directory>/conf/stat-jobs/custom
folder.
3. Define which events the job should trigger on.
This is done by adding a few lines at the end of the file <installation_directory>/
system/conf/stat-jobs.xml.
Below is an example which triggers the job on all printer-related events (you
need to replace the filename with your .ktr-file location):
```
<job filename="qmatic/alert-on-disconnect-rest.ktr">
<event name="DISCONNECT"/>
<event name="PAPER_JAM"/>
<event name="OUT_OF_PAPER"/>
</job>
```
4. Restart Orchestra central.

After the job has been registered, you can change the content in the kettle-job-
file, during runtime. The stat-jobs.xml, however, always needs a restart to reg-
ister changes.
172 Qmatic 211.03K

9. Localisation
The System GUI, Connect Concierge and Mobile Connect Application

language ................................................................................. 174
Translation of Calendar modules ............................................ 179
Translation of Orchestra Business Intelligence ....................... 188
211.03K Qmatic 173

This chapter describes the procedures to follow to make localised versions of

Qmatic Orchestra.
The System GUI, Connect Concierge and Mobile Connect

Application language
This section is applicable for Connect Concierge and Mobile Connect, as well
as for the Central parts of Orchestra. For Business Intelligence, see “Translation
of Orchestra Business Intelligence” on page 188 and for Calendar see “Translation
of Calendar modules” on page 179.
Orchestra uses the Unicode character encoding (\udddd notation). Files which
contain other character encodings must be converted into files containing Latin-1
and/or Unicode-encoded characters.
You need to know the 2-character language code for the new language, it is the
code that will show up in Orchestra; it is sv for Swedish, for example. See the
standard ISO 639-1.
The language property handling procedures can be seen as three different parts:
• Central and Central Queue Agent

• Distributed Queue Agent
• Unit Type Templates and Widgets handling
Central and Central Queue Agent

To make a language specific version of Orchestra, including Connect Counter and
Connect Concierge applications, do the following:
1. Make copies of all the original files in the <Orchestra central installation
directory>\conf\lang folder (they are in English):
businessConfigMessages.properties
commonMessages.properties
and so on...
and rename them like this (for example): businessConfigMessag-
es_temp.properties
The corresponding original file will be used when a specific language file
can not be found for some reason.
2. Translate all strings in all the files.
174 Qmatic 211.03K

Localisation
3. The characters in the file must be Unicode. A tool for converting to Unicode is
included with the JDK from Oracle: native2ascii. The program converts a file
with native-encoded characters (characters which are non-Latin-1 and non-
Unicode) to one with Unicode-encoded characters. Information is available on
the Internet about this program.
Remember to keep the translated files before they are changed with the pro-
gram native2ascii; it will be much easier to make new files in case there are
strings added to the original files in later versions of Orchestra.
If necessary for your language, run the program native2ascii on all the files, at
the same time renaming them by changing temp to the language code (the
code for Arabic in this example):
native2ascii -encoding utf-8 businessConfigMessages_temp.properties

businessConfigMessages_ar.properties
To find out the encoding used in a file, open it in a text editor or MS-Word,
most programs will show the encoding. Word displays a list of suggested
encodings, use trial and error to find the correct one.
4. All available languages must be entered, manually into the database table
LANGUAGES. This is also where the left-to-right (ltr) and right-to-left (rtl) setting
is set for each language.
You must, yourself, make sure that you add your language correctly to this
table!
5. If not already done so in the previous step, rename all the files by changing temp
to the language code, like this: businessConfigMessages_sv.properties.
6. Place the new files in the language folder along with the original files.
A restart is needed for the changes to take place. If lang files have changed on
the Queue Agent, then the Queue Agent needs to be restarted. If, however, lang
files have changed on central, then central needs to be restarted.
As each new User is added in Orchestra, you select which should be the preferred
language for that user, from a drop-down list.
211.03K Qmatic 175

Browser Specific Settings

Please note that a few items in the GUI depend on the specific language settings
of your browser.
For example, the buttons used to upload files, as illustrated in the following picture,
depend on the language used in your browser:
Distributed Queue Agent

Properties files for distributed Queue Agents are placed in the Queue Agent
Profile. If you want to edit the files, you either need to create a new Agent Profile,
or update an old one.
For more information see “Creating an Agent Profile Zip File” on page 121 and
“Creating an Agent Profile” on page 124.
During deploy, the Queue Agent is restarted.
For more information about this, please refer to “Queue Agents” on page 110.
176 Qmatic 211.03K

Localisation
Unit Type Templates

When it comes to Unit Type Templates (utt files), there are a couple of things to
consider:
• Each Unit Type Template (utt) that is to be used in your system needs to be
edited and translated one by one.
• The Name and Description of the Unit Type can be translated in the actual
fields of the GUI, marked in the following picture:
You can change the Name and Description to whatever you want. For more
information, please see the Standard Unit Types Guide, found on Qmatic World.
Widgets
When it comes to Widgets, the Name and Description (displayed in the GUI) are
translated in the file config.xml, as in the following example for widget callhistory,
where you can see both the Swedish (sv) and the English (en) version of the name:
<name>callhistory</name>
<name xml:lang="sv">Biljetthistorik</name>
<name xml:lang="en">Ticket call history</name>
<description>Keeps track of latest called tickets to allow customers
to see what tickets have been called where</description>
Mobile Connect
If you are upgrading from Orchestra version 5.4 to Orchestra version 6.0, or later
and have made changes to the Mobile Connect language properties files,
connect.properties and connectCounter.properties, you need to manually add
these changes, to the Orchestra 6.0 properties files, connectMessages.properties
and connectCounterMessages.properties, after the upgrade.
Simply renaming your old, changed files to connectMessages.properties and

connectCounterMessages.properties is not a good enough solution, because
strings may have been added or deleted in the files since Orchestra 5.4. Instead,
make the same changes in the new files that you did in the old. Then, delete the
old files.
211.03K Qmatic 177

Also, if you added language specific properties files in Orchestra 5.4, do the
following: copy the default new files, connectMessages.properties and
connectCounterMessages.properties, add a language code suffix to them, for
example *_fr for French, then translate the contents of the new files, using the old
files as reference. Make sure that you translate any strings in the new files that
have not yet been translated, if applicable.
Here too, it is not a good idea to simply rename the old files, since strings may
have been added or deleted.
The Native App

The Mobile Connect Native app (the System Settings and User Settings pages) is
available in the following languages, by default:
• English
• Arabic
• Swedish
• Danish
• Norwegian
• Finish
• German
• Spanish
• Italian
• French
• Russian
• Japanese
• Chinese (Mandarin)
• Thai
• Malay
• Philipino (Tagalo)
• Vietnamese
The same languages apply to the Connect Concierge native app.
178 Qmatic 211.03K

Localisation
Translation of Calendar modules
Calendar Admin and Calendar View

The Calendar Admin and Calendar View correspond to the calendar-admin.war
and calendar-client.war artefacts.
These two modules use the RequireJS i18n framework, for handling translatable
GUI elements. This framework can be found at http://github.com/requirejs/i18n and
is available under both the MIT and new BSD licenses.
This section describes how to add new translations to these modules. It will not
cover the actual usage patterns of the require.i18n framework in javascript code,
as that is out of scope for this section. For more information on that topic, please
consult the require.i18n documentation.
General structure of require.js translations

Translations in the calendar-admin and calendar-client modules are based on
language files bundled into the compressed ".war" artefacts. In the root of the war
archive there is a 'nls' folder which contains a number of folders and a single
strings.js file:
All sub-folders except the 'root' folder contains the .js file for a particular language
as specified by the name of the folder using the standard 2-letter language code,
e.g. ar = Arabic, de = German, sv = Swedish etc.
The 'root' folder contains the default translation, in the context of these calendar
modules, we use English as the 'root' language.
211.03K Qmatic 179

The strings.js file is used to declare all translated languages:
Inside each language-specific folder, the actual translation file is placed, always
named strings.js. Please note that these translated files are NOT the standard
message-bundle property format with simple key-value pairs. Instead, require.js
uses JSON (JavaScript Object Notation) structured files in order to be able to
group translation key-value pairs into hierarchical groupings:
The document starts with a require.js define(..) function call whose single
argument is a JSON document. As seen above, this JSON document has a root
element named 'calendar' with a number of sub-elements both being other JSON
objects but also plain key-value pairs. For example, we see the 'button' sub group
of translated values where translated button names have been grouped together.
We also see usage of arrays such as the 'dayNames':[…] array where a translated
name for each day of the week can be specified for a given weekday index.
180 Qmatic 211.03K

Localisation
The isRTL and firstDay properties

The calendar.isRTL and calendar.firstDay properties have a special meaning in
the context of the calendar-admin and calendar-client applications.
• isRTL: [true|false] is used to determine whether the web application should be
rendered from left-to-right or right-to-left. So, for an Arabic translation, one
would set 'isRTL':true, while Swedish, for example, would use 'isRTL':false
• firstDay: [0-6] is used to denote which day of the week that is the first day of
the week. 0 == Sunday, 1== Monday … 6 = Saturday. This affects the calen-
dar-admin Week Schedule and the calendar-client weekly view where one
manages appointments. You do not need to change the 'dayNames', 'day-
NamesShort' etc. array indexing if you change firstDay.
Step by step guide for adding a new translation

Given the general information stated in the previous section, a step-by-step
instruction to add a new language to either of the calendar-admin.war or calendar-
client.war could be (using calendar-admin.war as example):
1. On the file system of the Orchestra server, find the 'calendar-admin.war' file.
The calendar-installer will place this file in %QP_HOME%/deploy.
2. Copy the .war file to a temporary location such as c:\qmatic\temp and extract
the .war file using 7-zip, WinRAR, or similar. To unzip or jar xvf calendar-
admin.war on a Linux command shell. You should see something similar to the
screen shot below:
211.03K Qmatic 181

3. Open the 'nls' folder
4. Create a new folder named as the 2-letter code of the language you want to add,
for example 'sv' for Swedish.
5. Open the root folder and copy the strings.js file into your new sv folder.
6. Open the strings.js file in the nls folder with your favourite text editor and add an
entry for 'sv'
7. Open the strings.js file you previously copied into the new 'sv' folder.
182 Qmatic 211.03K

Localisation
This way, you have the full structure laid out with the default English transla-
tions in place.
8. Now you can just go ahead and start to translate each value one-by-one.
9. When you are satisfied with your translations, please make a copy of your new
strings.js so you do not lose it.
211.03K Qmatic 183

10. Now it is time to repackage the calendar-admin.war with the new translation
added. You can do this in several ways:
a One could use a utility like 7-zip to just copy the full 'nls' folder into the orig-
inal calendar-admin.war which would add or overwrite the necessary files:
b Another method is to use the c:\qmatic\temp folder created in step 2 of this

guide, which contains all the content of the original calendar-admin.war
plus the original calendar-admin.war archive file. Select all files except the
calendar-admin.war and use 7-zip (or similar) to create a new calendar-
admin.war archive. (Remember that a Java.war/.jar/.ear is just a standard
zip file with another suffix).
184 Qmatic 211.03K

Localisation
c One can also use a command-line tool such as the Java jar program to cre-
ate a new calendar-admin.war. Remember to not include the original calen-
dar-admin.war in the new archive:
11. In the final step, it is time to redeploy your updated calendar-admin.war artefact
into Orchestra. For more information, see “Redeploying Applications” on
page 62.
12. After the artefact has been redeployed, you can test your new translation. You
may need to make sure that you set your web browser's preferred language at
the top of the languages list, example from Internet Explorer 11 (Swedish):
Contrary to other Orchestra modules, the calendar-admin.war and calendar-cli-

ent.war do not use the language set on a user in Orchestra, they solely use the
browser's language preferences.
211.03K Qmatic 185

Appointment Terminal
The Appointment Terminal language support is very similar to the standard
solution used in Orchestra modules, the only difference actually being where the
language bundle file is stored. Normal Orchestra modules always read language
files from %QP_HOME%/conf/lang, see below:
However, the appointment-terminal.war archive bundles its own language file in a

folder named bundle:
By default, the bundle folder contains a single file named

appointmentTerminalMessages.properties, which is a translation for the default
language.
186 Qmatic 211.03K

Localisation
Step by step guide for adding a language to the Appointment Terminal

1. To create a new translation for the Appointment Terminal, follow steps 1 and 2
from the calendar admin / calendar-client guide, “Step by step guide for adding
a new translation” on page 181, extracting the appointmentterminal.war file into
a temporary folder.
2. Make a copy of the bundle/appointmentTerminalMessages.properties file and
name it with the language suffix of your desired language such as
appointmentTerminalMessages_sv.properties for Swedish.
3. Open the new _sv file in your favourite text editor.
4. Now start replacing the default English translations with the ones for your own
language.
5.Finish by following the steps 9-12 from the calendar admin / calendar-client
guide, “Step by step guide for adding a new translation” on page 181, to repackage
and redeploy the appointmentterminal.war artefact. Remember to make a backup
copy of your new translation file, as a later upgrade of Orchestra with new versions
of .war artefacts would overwrite your own translations.
211.03K Qmatic 187

Translation of Orchestra Business Intelligence
Orchestra Business Intelligence is based on the third party product Pentaho Busi-
ness Analytics.
The sections below describe which properties files that need to be updated, in the
different parts of the system, in order to manually introduce a new language to the
Business Intelligence application.
In short, the steps are as follows:
1. Copy the businessintelligence.war file to a suitable location, where you can
work with it, without interrupting the running Orchestra system.
2. Locate and copy a number of properties files, described in the sections below.
3. Rename the files so that the file name includes your language’s language code,
for example message_es.properties, for a Spanish file.
4. Translate all the parameters (text strings), in the file that you created, to your
language, making sure that you use Unicode, where needed, for example
\u00e9 for é. Save the file.
5. Open the corresponding *_supported_languages.properties file, located in the
same folder as the property file that you updated in the previous steps, and add
an entry for your language in the file. Save the file.
6. When all parts described below are translated, zip the updated
businessintelligence.war file and redeploy the businessintelligence.war
application. See “Redeploying Applications” on page 57.
7. Restart the Qmatic Platform service. Log in as superadmin and open the
Business Intelligence application. You should find a new menu entry for your
language in the View->Languages menu.
Translating the BI Console
In the description below, xx should be replaced by the two letters in your

language code, for example es for Spanish.
1. Locate, copy, rename (with your language code) and translate the following
property files, in:
<temporary_directory>\businessintelligence\mantle\messages:
• filechooser_messages_xx.properties
• MantleLoginMessages_xx.properties
• mantleMessages_xx.properties
• WidgetsMessages_xx.properties
188 Qmatic 211.03K

Localisation
2. Add an entry for your language to the following property files, in:
<temporary_directory>\businessintelligence\mantle\messages:
• WidgetsMessages_supported_languages.properties
• mantleMessages_supported_languages.properties
• MantleLoginMessages_supported_languages.properties
• filechooser_messages_supported_languages.properties
Example, adding Spanish:
en=English
fr=Fran\u00E7ais
de=Deutsch
ja=\u65E5\u672C\u8A9E
es=Espa\u00f1ol
Special characters must be entered in Unicode.
property file, in:
<temporary_directory>\businessintelligence\mantle\browser:
• messages_xx.properties
4. Add an entry for your language to the following property file, in:
<temporary_directory>\businessintelligence\mantle\browser:
• messages_supported_languages.properties
property file, in:
<temporary_directory>\businessintelligence.war\mantle\home\properties:
<temporary_directory>\businessintelligence.war\mantle\home\properties:
211.03K Qmatic 189

property file, in:
<orchestra_installation_directory>\pentaho-solutions\system\default-plu-
gin\resources\messages:
<orchestra_installation_directory>\pentaho-solutions\system\default-plu-
Translate Admin Plugin Parameters

This section concerns translation of the phrases found in the Administration page.

property file, in:
<orchestra_installation_directory>\pentaho-solutions\system\admin-plu-
190 Qmatic 211.03K

Localisation
3. Add supported language entry (xx : true) to the following file in:
gin\resources\nls:
• messages.js
Make sure that you separate each new language with a comma (,).
Example of what it may look like in the messages.js file:
en : true,
de : true,
fr : true,
ja : true
4. Create a folder named xx in the <orchestra_installation_directory>\pentaho-

solutions\system\admin-plugin\resources\nls folder.
5. Copy the messages.js file from the <orchestra_installation_directory>\pentaho-
solutions\system\admin-plugin\resources\nls\en folder to the folder you just
created and translate the contents of the file to the language in question.
Translating Analyzer Parameters

property file, in:
<orchestra_installation_directory>\pentaho-solutions\system\analyzer\resour-
ces:
<orchestra_installation_directory>\pentaho-solutions\system\analyzer\resour-
ces:
property files, in:
211.03K Qmatic 191

<orchestra_installation_directory>\pentaho-solutions\system\analy-
zer\scripts\filechooser\messages:
zer\scripts\filechooser\messages:
property files, in:
zer\scripts\schedulingdialogs\messages:
zer\scripts\schedulingdialogs\messages:
Analyzer data from databases

Most names from the databases can currently not be modified using localisation.
They are defined in the following files:
• locale_mondrian.properties - for more information about how to locate and
modify this file, please see “locale_mondrian.properties” on page 193.
• qmatic.mondrian.xml - for more information about how to modify this file,
please see “locale_mondrian.properties” on page 193.
192 Qmatic 211.03K

Localisation
locale_mondrian.properties
This is the preferred way of modifying or translating names and phrases from the
databases.
To locate and then modify this file, please follow these steps:
1. Extract the file <orchestra_home>\system\deploy\businessintelligence.war to a
suitable directory.
2. In the folder businessintelligence\WEB-INF\classes, open the file
locale_mondrian.properties.
3. Translate, or update (if you just want to change the English wording, for
example), the phrases in the file and save it. If you have translated it, add a
suffix, such as *_fr (for French) to the file name, in this case
locale_mondrian_fr.properties.
4. Make a zip-file of the businessintelligence folder containing the file that you just
updated or translated and rename the zip-file businessintelligence.war.
5. Redeploy the Business Intelligence application, see “Redeploying Applications”
on page 57.
qmatic.mondrian.xml
It is possible to modify and translate the metrics in the
qmatic.mondrian.xml.<database> file. However, we recommend that you use the
locale_mondrian.properties file for that purpose (see above).
The qmatic.mondrian.xml.<database> file is found here: pentaho-
solutions\qmaticbi\platform\. Make sure that you select the one that corresponds to
your used database.
This file is used to query the database and should be modified with great
caution. Make a backup of the existing file before attempting to localize it.
The localised names should be entered in the caption and description properties
of the XML tags for Dimensions, Levels and Measures.
Example:
Locate the wanted text. In this example, the measure Arrived:
<Measure name="arrived" datatype="Numeric" aggregator="count"
caption="%{qmatic.measure.visit.arrived.caption}" visible="true"
description="%{qmatic.measure.visit.arrived.description}">
And change to, in this example, French:
<Measure name="arrived" datatype="Numeric" aggregator="count"
caption="Arrivée" visible="true" description="Arrivée">
211.03K Qmatic 193

Translating Dashboard Parameters

property files, in:
<orchestra_installation_directory>\pentaho-solutions\system\dashbo-
ards\resources\gwt\chartDesigner\messages:
• ChartDesignerMessages_xx.properties
• LoginMessages_xx.properties
ards\resources\gwt\chartDesigner\messages:
• ChartDesignerMessages_supported_languages.properties
• LoginMessages_supported_languages.properties
property files, in:
ards\resources\gwt\dashboarddesigner\messages:
• filterdialog_xx.properties
• dashboards_xx.properties
ards\resources\gwt\dashboarddesigner\messages:
194 Qmatic 211.03K

Localisation
• filterdialog_supported_languages.properties
• dashboards_supported_languages.properties
property files, in:
ards\resources\gwt\dashboardviewer\messages:
• dashboards_xx.properties
ards\resources\gwt\dashboardviewer\messages:
• dashboards_supported_languages.properties
property files, in:
ards\resources\gwt\filterdialog\messages:
ards\resources\gwt\filterdialog\messages:
211.03K Qmatic 195

property files, in:
ards\resources\gwt\resourceBundle\messages:
ards\resources\gwt\resourceBundle\messages:
property files, in:
ards\resources\gwt\schedulingdialogs\messages:
ards\resources\gwt\schedulingdialogs\messages:
196 Qmatic 211.03K

Localisation
property file, in:
ards\resources\messages:
ards\resources\messages:
Translating Interactive Report Parameters

property file, in:
<orchestra_installation_directory>\pentaho-solutions\system\pentaho-interac-
tive-reporting\resources\help:
property files, in:
tive-reporting\resources\messages:
• launchermessages_xx.properties
tive-reporting\resources\messages:
• launchermessages_supported_languages.properties
211.03K Qmatic 197

property files, in:
tive-reporting\resources\web\filterdialog\messages:
tive-reporting\resources\web\filterdialog\messages:
property files, in:
tive-reporting\resources\schedulingdialogs\messages:
tive-reporting\resources\schedulingdialogs\messages:
198 Qmatic 211.03K

Localisation
Translating Common UI Properties

1. Locate, copy and rename (with your language code) the following property file,
in:
<orchestra_installation_directory>\pentaho-solutions\system\common-
ui\resources\messages:
The entry in this file should not be localized!
property file, in:
<orchestra_installation_directory>\pentaho-solutions\system\common-
ui\resources\web\dataapi\nls\messages:
Translating Data Access Properties

property files, in:
<orchestra_installation_directory>\pentaho-solutions\system\data-
access\resources\gwt\messages:
211.03K Qmatic 199

access\resources\gwt\messages:
property file, in:
access\resources\messages:
access\resources\messages:
property files, in:
access\resources\gwt:
• biserverconfig_xx.properties
• cubeForms_xx.properties
• databasedialog_xx.properties
• datasourceAdminDialog_xx.properties
• importDialog_xx.properties
• main_wizard_panel_xx.properties
• measuresForm_xx.properties
• datasourceSelectionDialog_xx.properties
• modeler_xx.properties
• publish_xx.properties
• reportingForms_xx.properties
200 Qmatic 211.03K

Localisation
access\resources\gwt:
• databasedialog_supported_languages.properties
• datasourceAdminDialog_supported_languages.properties
• datasourceSelectionDialog_supported_languages.properties
• importDialog_supported_languages.properties
• main_wizard_panel_supported_languages.properties
• modeler_supported_languages.properties
Translating General Reporting Folder Properties

property file, in:
<orchestra_installation_directory>\pentaho-solutions\sys-
tem\reporting\reportviewer\messages:
Translating Hardware Monitoring Overview Page

property file, in:
<orchestra_installation_directory>\pentaho-solutions\qmaticbi\Orchestra Hard-
ware Content\Dashboards:
2. Open the Business Intelligence application in Orchestra and select Show
Hidden Files in the View menu.
3. Select Browse Files and browse to public\Orchestra Hardware
Content\Dashboards.
211.03K Qmatic 201

4. Click Upload and upload the messages_xx.properties file that you created in
step 1.
5. Introduce the following JSON property file to
<orchestra_installation_directory>\system\pentaho-solutions\system\pentaho-
cdf-dd\lang\qmatic folder, to localize Jquery database table labels:
• messagesTable_xx.json
Localization files used in the Overview page will be cached in

<orchestra_installation_directory>\system\pentaho-solutions\system\penaho-cdf-
dd\tmp\.cache. Delete this after updating the localized text.
Jquery datatable localization files can be downloaded from http://

cdn.datatables.net/plug-ins/1.10.7/i18n/.
Canned Reports
The canned reports are translated with a properties file, located in the *.prpt file for
the report. You use report designer to translate the report. If you need assistance,
please contact Professional Services or the Support organization.
If you want to translate the name of a canned report to a language, such as Arabic,
or a language using Cyrillic characters, follow these steps:
1. Download the canned report from Orchestra Business Intelligence.
You will get a zip-file called <report_name>.prpt.zip. This zip-file contains three
files:
• <report_name>.prpt
• <report_name>.prpt.locale
• exportManifest.xml
202 Qmatic 211.03K

Localisation
2. Open the file <report_name>.prpt.locale and edit the parameter file.title, as in

the following example (this example is for the canned report Service Summary):
#Locale = default
#Thu Dec 10 11:50:45 IST 2015
file.title=\u0645\u0644\u062e\u0635
\u0627\u0644\u062e\u062f\u0645\u0629
title=service_summary
file.description=
Note that the file.title must be written in Unicode! A useful tool for convert-
ing your language to Unicode can be found here:
https://www.branah.com/unicode-converter.
3. Zip the files and upload the report to Orchestra Business Intelligence again.
Special Characters when using JBoss

If you are using Application Server JBoss, and are translating to a language that
uses special characters, you need to follow these steps:
1. Stop the JBoss Application Server.
2. Locate the following file:
<Orchestra_installation_directory>\system\app\jboss-eap-6.3\standalone\con-
figuration\standalone-full.xml
3. Add the following property to the file:
<system-properties>
<property name="org.apache.catalina.connector.URI_ENCODING"
value="UTF-8"/>
</system-properties>
4. Restart the Jboss Application Server.
211.03K Qmatic 203

204 Qmatic 211.03K

10. Network
Connectivity
Orchestra Bandwidth Requirements .............................. 206

Connect Counter - Connectivity and Network Loss ....... 206
Connect Concierge - Connectivity and Network Loss ... 211
211.03K Qmatic 205

Orchestra Bandwidth Requirements
The bandwidth need is very different, depending on how you configure and run
Orchestra.
For an Orchestra not using any special integrations, or for example Calendar,
global variables, or media sync, the only data sent between the central and
distributed Queue Agent are stat messages, as well as a keep alive message sent
every 30 seconds.
Stat messages for a Visit are less than 3 kb in size and Service Point sessions are
less than 5 kb in size. The needed bandwidth is thus depending on how many
Visits and Service Point Sessions you have in your system.
However, when synchronizing a new Agent Profile or media, the bandwidth
requirement is much larger.
Internal tests have been performed, with bandwidth as poor as 250 kbit/s as well
as 4% packet loss. Profile and media synchronization still works under those
conditions, but it is recommended to have higher bandwidth available.
Connect Counter - Connectivity and Network Loss
Note that even if it seems like you have good signal strength for Wi-Fi, 3G or
4G, you may still experience network loss or bad connectivity, due to high load.
If the users are often experiencing network problems, you should consider
whether your network signal strength be improved in any way.
We suggest that you review the following:
• Can the layout of your facilities be improved?
• Do you need more or better routers?
• Can the router placement be improved?
• Can you prevent interference from other networks?
• etc.
206 Qmatic 211.03K

Network Connectivity
When connectivity is limited, or you have network loss, this will be handled by
Connect Counter in the following way:
Step 1:
When a REST command executes and there is no response after 1 second, the
following message will be displayed:
211.03K Qmatic 207

Step 2:
After 10 seconds (default setting) of no response, the REST call times out and the
At this time, a procedure is initialized, to see if it is possible to establish a

connection with the server. It will time out after 3 attempts, waiting 5 seconds
between each attempt (default settings).
208 Qmatic 211.03K

Step 3:
If even the third attempt fails, due to unavailability of the network, the following
message is displayed:
However, the connection attempts will continue, in the background, until

connection has been re-established, or until the default time entered for the
Reconnect Timer, in the unit type(s), has passed.
When connection has been re-established, an additional REST call is executed, to
get the User status and direct the User to the correct page, which means that he/
she can continue working.
211.03K Qmatic 209

When the automatic reconnect attempts stop, without connection being re-
established, you will get the following messages:
Tap Reconnect to keep trying to reconnect.
210 Qmatic 211.03K

Connect Concierge - Connectivity and Network Loss
Note that even if it seems like you have good signal strength for Wi-Fi, 3G or
4G, you may still experience network loss or bad connectivity, due to high load.
If the users are often experiencing network problems, you should consider
whether your network signal strength be improved in any way.
We suggest that you review the following:
• Can the layout of your facilities be improved?
• Do you need more or better routers?
• Can the router placement be improved?
• Can you prevent interference from other networks?
• etc.
When connectivity is limited, or you have network loss, this will be handled by
Connect Concierge in the following way:
211.03K Qmatic 211

Step 1:
When a REST command executes and there is no response after 1 second, the
212 Qmatic 211.03K

Step 2:
After 10 seconds (default setting) of no response, the REST call times out and the
At this time, a procedure is initialized, to see if it is possible to establish a

connection with the server. It will time out after 3 attempts, waiting 5 seconds
between each attempt (default settings).
211.03K Qmatic 213

Step 3:
If even the third attempt fails, due to unavailability of the network, the following
message is displayed:
However, the connection attempts will continue, in the background, until

connection has been re-established, or until the default time entered for the
Reconnect Timer, in the unit type(s), has passed.
When connection has been re-established, an additional REST call is executed, to
get the User status and direct the User to the correct page, which means that he/
she can continue working.
214 Qmatic 211.03K

When the automatic reconnect attempts stop, without connection being re-
established, you will get the following messages:
Tap Reconnect to keep trying to reconnect.
211.03K Qmatic 215

216 Qmatic 211.03K

11. Secure
Communication
Introduction .......................................................................................... 218

Secure WebSocket Between Distributed Queue Agent and Central ... 229
Secure Communication for a Queue Agent ......................................... 233
Disabling HTTP and Running HTTPS Only ......................................... 250
Encryption of HornetQ JMS connections ............................................. 252
Bandwidth Requirements ..................................................................... 257
211.03K Qmatic 217

Introduction
Why security?
As our dependency on the internet has grown, the risks have also grown.
Unencrypted HTTP requests reveal information about a user’s behavior, and the
interception and tracking of unencrypted browsing has become commonplace.
When properly configured, HTTPS can provide a fast, secure connection that
offers the level of privacy and reliability that users should expect.
Therefore, we highly recommend that you configure Orchestra to use HTTPS /
SSL / WSS for all communication.
First, let’s go through the basics.
What is HTTPS?
Hyper Text Transfer Protocol Secure (HTTPS) is the secure version of HTTP, the
protocol over which data is sent between your browser and the website that you
are connected to. The 'S' at the end of HTTPS stands for 'Secure'. It means all
communications between your browser and the website are encrypted.
What is SSL?
Secure Sockets Layer (SSL) is a standard security protocol for establishing
encrypted links between a web server and a browser in an online communication.
The usage of SSL technology ensures that all data transmitted between the web
server and browser remains encrypted.
What is WSS?
WebSocket Secure (WSS) is a computer communications protocol, providing full-
duplex communication channels over a single TCP connection. WebSocket is
designed to be implemented in web browsers and web servers, but it can be used
by any client or server application.
Why do you need a certificate?

When you request a HTTPS connection to a web page, the website will initially
send its SSL certificate to your browser. This certificate contains the public key
needed to begin the secure session. Based on this initial exchange, your browser
and the website then initiate the 'SSL handshake'. The SSL handshake involves
the generation of shared secrets to establish a uniquely secure connection
between yourself and the website.
Notes on certificate host names and IP addresses:

When creating a certificate, the certificate is only valid for the actual host name that
it is created for (the "CN" attribute).
This should be the only host name which is used when communicating securely
with an Orchestra system.
218 Qmatic 211.03K

Secure Communication
For example, if the host orchestra-central.company.com is used when setting up

SSL for the Central system (on JBoss / Wildfly), all distributed Queue Agents
should be configured (in agent.conf) to communicate towards that hostname and
not the IP-address of the host.
If a mix of hostnames and IP-address needs to be used for self-signed certificates,
the "-ext san=..." flag should be used when creating the certificate.
Different kinds of certificates

In this manual, we distinguish between the following kinds of certificates:
1. A certificate generated by Orchestra, this can be:
a) A certificate that can be used as it is - this should only be used for demo
and test purposes, not for production environments!
b) A certificate that needs to be sent off to a well-known CA authority, such as
Verisign or Thawte, to be signed
2. An existing certificate, created outside Orchestra, this can be:
a) A certificate signed by a Private CA Body
b) A certificate already signed by a well-known CA authority, such as Verisign
or Thawte.
For both a)-versions above, the truststore needs to be updated. For both b)-
versions above, the Queue Agent already trusts the certificate, so no changes are
needed on the Queue Agent.
The instructions below describe what to do, depending on what kind of certificate
you are using.
You need to only follow the instructions for your certificate. Make sure that you
follow the right set of instructions!
211.03K Qmatic 219

What is the difference between a Truststore and a Keystore?

The purpose of the truststore is to verify credentials and the purpose of the
keystore is to provide credential.
In other words, the main difference between a truststore and a keystore is that
truststore is used to store certificates from trusted Certificate Authorities (CA)
which are used to verify certificates presented by the Server in SSL Connection,
while keystore is used to store private key and own identity certificates which a
program should present to other parties (Server or client) to verify its identity.
Orchestra is installed with a default keystore and a default truststore. The
truststore is a copy of the Java Runtime Environment (JRE) truststore and the
keystore is empty.
Both files are located in the folder <installation directory>/conf/security.
Keystore files for standalone Queue Agents also follow the same structure and the
files are included in the default Queue Agent profiles.
In order to use another keystore or truststore, the settings are located in the
following files:
• Central Orchestra: <installation directory>/app/<jboss or wildfly>/bin/stan-
dalone.conf.bat (standalone.conf for Linux).
• Standalone Queue Agent: <Queue Agent installation directory>/conf/
agent.conf
The values that affect keystore and truststore settings:

-Djavax.net.ssl.trustStore
-Djavax.net.ssl.trustStorePassword
-Djavax.net.ssl.keyStore
-Djavax.net.ssl.keyStorePassword
Central Orchestra and Queue Agents must run the same protocol, i.e. a mixed
setup is not supported.
If upgrading from Orchestra 5.4, it will be required to import any certificates

previously used when running Glassfish, as they will not be included in the upgrade
to JBoss/Wildfly.
TP3115, TP Touch and Intro 8 do not support encrypted communication at all.

Those units need to go through HTTP.
220 Qmatic 211.03K

Ports and Protocols

The following image illustrates the ports and protocols used in Orchestra:
In the instructions below, we will go through the image above and how to set up
secure communication for each part.
211.03K Qmatic 221

Orchestra Central
In this first scenario, we will secure the communication for Orchestra Central, high-
lighted in the following picture:
222 Qmatic 211.03K

The following flow chart illustrates the steps that need to be taken to set up HTTPS
for Central. Each number (1a, etc) refers to a certificate type (see See “Different
kinds of certificates” on page 219.), described by a corresponding section below.
211.03K Qmatic 223

1a: Certificate Generated by Orchestra, used as is
We recommend using a tool such as Keystore Explorer, http://keystore-

explorer.org/, for managing your keystores and truststore.
1. First, a private key pair must be generated.
a) Navigate to the Parameters section of the System Administration applica-
tion and locate the HTTPS Parameters section.
b) In the Certificate and key store Settings section, adjust the values below:
• KeyStore alias - The name of the certificate entry in the key store. This can
normally be left as is (default: orchestra).
• Distinguished name - The distinguished name of the certificate. The "CN"
part should be the host name of the Orchestra server, the other parts, i.e
which organization, country etc need to be filled in, so they match the cus-
tomer’s organization.
• Subject alternate name - This needs to be filled in, if the certificate should
be valid for more than just one host name. For example, both host name
and IP-address. Separate each entry with a comma.
Example: testrd.q-matic.net, 192.168.8.206
Once all settings have been set properly, Save the configuration.
2. Set the value for (Re)generate certificate to true and Save the configuration
again.
This will generate a key entry in the keystore.
Do not enable this setting once the HTTPS setup is complete, as it will
overwrite any certificate using the same alias in the key store, potentially
destroying the HTTPS setup.
3. Navigate to the Parameters section of the System Administration application
and locate the HTTPS Parameters section.
224 Qmatic 211.03K

4. In the HTTPS server settings section, adjust the values below:
• HTTPS port - This is the port you want to use when running HTTPS, default
is 8443.
• KeyStore alias - This should match the alias in the key store, used when
creating / importing the alias, default is orchestra.
When both these settings are set correctly, set the value for HTTPS enabled to
true and click Save.
This will enable HTTPS in the underlying server (JBoss / Wildfly).
5. Next, restart the Orchestra service.
6. Test your https connection by entering the url https://<orchestra_ip>:<https
port>, in your browser and making sure that everything works as expected.
1b: Certificate Generated by Orchestra, to be sent to a CA Authority

The certificate needs to be sent to a certificate authority to be properly signed.

Follow these steps:
1. In Keystore Explorer open the keystore. This should be the default keystore for
Orchestra. This file is located in <installation directory>\conf\security and is
called keystore.jks.
2. Right-click and select Generate CSR. The default password is changeit.
3. In the Generate CSR window, click Ok.
4. Send the certificate request (server-2048.csr) to your certificate authority (for
example Verisign or Thawte).
5. Once the certificate response has been received, it must be imported into the
keystore.
The certificate response normally consists of 3 parts:
• The certificate authority’s signer certificate, example: symantec-ca.cer
• The certificate authority’s root certificate, example: symantec-root.cer
211.03K Qmatic 225

• Your signed certificate, example: server-2048.cer

All these certificates must be imported into the keystore in the correct order
(the one defined above).
Open Keystore Explorer and select Import Trusted Certificate, select the
wanted files and import them.
Enter yes when prompted if the certificate(s) should be trusted.
is 8443.
226 Qmatic 211.03K

2a: Certificate Generated outside Orchestra, Signed / Created by Pri-

vate CA Body
If your enterprise/company uses a certificate already created and signed by a
Private Certificate Authority (CA) body, this certificate needs to be imported to your
truststore, before you can use it.
is 8443.
Your private CA certificate should be available in this drop-down.

2b: Certificate Generated outside Orchestra, already signed by CA

authority
If your enterprise/company uses an already signed Certificate Authority (CA)
certificate, this certificate needs to be imported to your truststore, before you can
use it.

211.03K Qmatic 227

Follow these steps:

1. In Keystore Explorer, select Open an exisiting KeyStore, browse for and open
the keystore. which is located in <installation directory>\conf\security and is
called keystore.jks. Enter the password for the keystore (the default password
is changeit).
2. In the Tools menu, select Import Key Pair.
3. Select the wanted type of key pair, for example PKCS #12.
The format supported by Orchestra is pkcs12 files (i.e *.p12 and *.pfx files).
4. Specify the password for the certificate, then browse for and select the
certificate file, and click Import.
5. Enter the Alias. This will be displayed in the Orchestra GUI.
6. Enter the Key Pair password. This must be the same as the password you
entered in 1. Default is changeit.
7. Make sure that the key pair is imported correctly and save the updated keystore.
is 8443.
• KeyStore alias - This should match the alias specified in 5. Default is
orchestra.
Your private CA certificate should be available in this drop-down.

228 Qmatic 211.03K

Secure WebSocket Between Distributed Queue Agent and

Central
This section is only applicable if using a distributed Queue Agent!

In this scenario, we will secure the communication between a distributed Queue
Agent and Orchestra central, as highlighted in the following picture:
Securing the Communication between the Daemon and Central
Make sure that the Daemon is version 6.2.xx.

Since the Daemon component in a distributed Queue Agent cannot be upgraded
as part of a remote upgrade, special considerations are required:
• If running on Hub or BranchHub, a firmware patch is required to make the
Daemon able to communicate securely with Central.
The Daemon will use the settings configured in agent.conf for this purpose,
more precisely the following settings: "central.websocket.secure", "cen-
tral.websocket.secure.port" and "jetty.jvm.args".
• If running the distributed Queue Agent on a PC or similar, the easiest way is to
replace the entire Queue Agent distribution with a newer version.
211.03K Qmatic 229

Apply the necessary upgrades and then continue with the configuration steps
below for the distributed Queue Agents, which will enable secure communications
for both Daemon and jiql.
The flow chart below illustrates the steps needed to enable Websocket Secure
between a distributed Queue Agent and Central. These steps are described in
more detail below.
230 Qmatic 211.03K

1b & 2b: Certificate Verified by a Public CA
Preconditions:
• The steps outlined in the section “Orchestra Central” on page 222 have been
performed.
• Section “Disabling Unencrypted WebSocket Communications” on page 233
should have been read through and considered.
1. Copy the existing Agent Profile to a separate folder, such as tmp.
2. Open the conf/agent.conf file and edit the following:
• Change the setting for "central.websocket.secure" to "true".
• Change the port setting "central.websocket.secure.port" if the default port
(9150) is not used.
3. Prepare, synchronize and publish the new Agent Profile.
4. In the System Administration application, open the Parameters tab and locate
the Central WebSocket Server Settings section.
Change these parameters:
• Secure WebSocket enabled - true

• Secure WebSocket port - the wanted port (default 9150).
The Secure WebSocket port can not be the same as the Unencrypted
WebSocket port (default: 8787).
5. Click Save to save the parameters.
6. Restart Orchestra.
7. Verify that the Queue Agent connects.
1a & 2a: Certificate NOT Verified by a Public CA
Preconditions:
• The steps outlined in the section “Orchestra Central” on page 222 have been
performed.
• Section “Disabling Unencrypted WebSocket Communications” on page 233
should have been read through and considered.

211.03K Qmatic 231

1. In Keystore Explorer, open the file keystore.jks, located in <installation

directory>\conf\security\. The default password is changeit.
2. Right-click and select Export -> Export Certificate Chain. Click Export.
3. In Keystore Explorer, open the file truststore.jks, located in <installation
directory>\media\agentProfiles\<your_agent_profile>\conf\security\.
The default password is changeit.
4. Select Tools -> Import Trusted Certificate and import the *.cer file that you
exported above.
Do not forget to click Save!

6. Open the conf/agent.conf file and edit the following:
• Change the setting for "central.websocket.secure" to "true".
• Change the port setting "central.websocket.secure.port" if the default port
(9150) is not used.
Change these parameters:
• Secure WebSocket enabled - true

• Secure WebSocket port - the wanted port (default 9150).
The Secure WebSocket port can not be the same as the Unencrypted
WebSocket port (default: 8787).
9. Click Save to save the parameters.
232 Qmatic 211.03K

Disabling Unencrypted WebSocket Communications
Make sure that your Queue Agent is successfully connected before you
disable unencrypted WebSocket communications.
2. Uncheck the check box for the parameter WebSocket enabled.
3. Click Save to save the changes.
If there are distributed Queue Agents in the setup that have not yet been
configured to use secure WebSocket communication, they will stop working
properly and it will not be able to e.g. remote upgrade them to support secure
communications.
This is especially important for distributed Queue Agents that run on Hub or
BranchHub, as they require a firmware patch to add support for secure WebSocket
communication to the Daemon component. See Disabling Unencrypted
WebSocket Communications above.
Disabling unencrypted WebSocket will make it impossible for software running

on other machines to communicate with the Central system using unencrypted
communication.
However, the unencrypted channel will not be 100% disabled, it will simply start to
listen on the localhost / 127.0.0.1 network interface only.
The reason for this is that the Central Queue Agent still uses unencrypted
communication to Central.
Secure Communication for a Queue Agent
Configuration of secure WebSocket and HTTPS for Queue Agents is handled

centrally and the necessary runtime configuration and certificates are published to
each Queue Agent.
The central Queue Agent will always use the same certificate as that configured
for the central WebSocket server (see “Secure WebSocket Between Distributed
Queue Agent and Central” on page 229).
This requires secure WebSocket to be configured on the central server before

configuring it on the central Queue Agent.
Distributed Queue Agents each have their own set of certificates, which are stored
and provisioned from the central server.
211.03K Qmatic 233

The same certificate will be used for both secure WebSocket and HTTPS, on
distributed Queue Agents.
Enabling HTTPS for HTTP communication between Queue Agents

and Central
The following flow chart illustrates the steps needed to enable HTTPS for HTTP
communication between Queue Agents and Central. The steps are described in
more detail below:
234 Qmatic 211.03K

Precondition:
• Section “Secure WebSocket Between Distributed Queue Agent and Central”
on page 229 must be completed before this step.
the Agent Parameters section:
2. Select https as Central HTTP Protocol and Central HTTP Port to 8443.
3. Save the Parameters and restart the Orchestra service.
211.03K Qmatic 235

Enabling secure WebSocket on a Central Queue Agent
This step is only necessary if you have hardware devices, such as a printer or
a GW1745 connected to your Central Queue Agent.
In this scenario, we will secure the communication for a central Queue Agent, as
highlighted in the following picture:
236 Qmatic 211.03K

The following flow chart illustrates the steps needed to enable Web Socket Secure
between a Central Queue Agent and all connected devices, such as GW1745 /
Hub:
1. First, set up HTTPS and secure WebSocket for Central (see “Secure
WebSocket Between Distributed Queue Agent and Central” on page 229).
2. Navigate to System Administration -> Queue Agents -> Agents. Select the
Central Queue Agent.
211.03K Qmatic 237

3. In the Security section, under Prepared security configuration, enable the

checkbox for WebSocket Secure enabled and select a port for WebSocket
Secure port (default: 8989):
4. Click Save to stage the configuration.

5. Click Publish to enable secure WebSocket.
This action will cause the device controller ports (8888 and 8989) to be
restarted on the central Queue Agent, causing all connected devices (e.g. gw1745,
Cinematic, HubMedia, Intro17 etc) to reconnect.
This might cause an interruption for ongoing business and should therefore be
done outside business hours.
6. Log in to the applicable device, for example Hub, in the Device Controller tab,
enable SSL and set the WSS port to 8989. For more information, please read
the applicable hardware manual, found on Qmatic World.
238 Qmatic 211.03K

Enabling secure WebSocket on a Distributed Queue Agent
This step is only necessary if you have hardware devices, such as a printer,
Hub or a GW1745 connected to a distributed Queue Agent.
In this scenario, we will secure the communication for a distributed Queue Agent,
as highlighted in the following picture:
211.03K Qmatic 239

The following flow chart illustrates the steps needed to enable Web Socket Secure
between a Distributed Queue Agent and all connected devices, such as Hub /
GW1745. Each number (1a, etc) refers to a certificate type, described by a corre-
sponding section below.
240 Qmatic 211.03K

The Queue Agent will keep the previously configured keystore during the
Agent Profile synchronization part of the remote upgrade. The file keystore.jks will
not match the one in the Agent Profile, centrally. Thus, the keystore must be
managed through the Security section, as described in this section.
1a: Certificate Generated by Orchestra, used as is

wanted Queue Agent.
2. In the Security -> Key pairs section, click the Create new button.
3. A new window, Create new key pair, will be shown. Below is an example of what
it may look like when filled in:
Enter the necessary fields:

• Keystore alias: The name the alias/certificate will be referenced in the con-
figuration. (Mandatory)
• Common name: This is the host name or IP address of the Queue Agent.
(Mandatory)
• Organization unit: The organizational unit (e.g. a department name).
(Optional)
• Organization name: The organizational name (e.g. the company name).
(Optional)
• Locality name: The locality (e.g. city). (Optional)
• State name: The state/region. (Optional).
211.03K Qmatic 241

• Country: The country. (Optional)

• Subject alternate name: additional host names / IP addresses the certifi-
cate should be valid for, separated by a comma. (Mandatory).
Click Generate key pair when the fields are filled in.
These fields will be combined to form the fully distinguished name of the certificate.
Example, using these values :
Key store alias: myAgentAlias
Common name: 127.0.0.1
Organization unit: RnD
Organization name: Qmatic
Locality name: Molndal
State name: VGR
Country: SE
Subject alternate name: 127.0.0.1, localhost
This will generate a certificate entry with the distinguished name "cn=127.0.0.1,
ou=RnD, o=Qmatic, l=Molndal, s=VGR, c=Sweden. This certificate will be valid for
host names 127.0.0.1, localhost.
When the certificate is stored, the alias name will be suffixed with a timestamp
(e.g. myAgentAlias-2017-04-10T13:37:00). This is to avoid conflicts and
overwriting previously used certificates.
wanted Queue Agent.
242 Qmatic 211.03K

5. In the Security -> Prepared security configuration section, enable the check box
for WebSocket secure enabled and select a port for WebSocket Secure port
(default: 18989 for Distributed Queue Agents:
It is also possible to enter Agent hostname here. This is the hostname of

the Queue Agent and it must be resolvable by DNS. A Branch publish is
needed for a hostname change to take effect.
6. Ensure that the selected alias in the WebSocket Secure key pair setting is
correct. If not, select a different alias in the drop-down list in the Key pairs
section and click Select to choose it as the active alias/certificate.
restarted on the Queue Agent, causing all connected devices (e.g. gw1745,
211.03K Qmatic 243

1b: Certificate Generated by Orchestra, to be sent to a CA Authority

for signing
wanted Queue Agent.
2. In the Security -> Key pairs section, click the Create new button.
3. A new window, Create new key pair, will be shown. Below is an example of what
it may look like when filled in:
Enter the necessary fields:

• Keystore alias: The name the alias/certificate will be referenced in the con-
figuration. (Mandatory)
• Common name: This is the host name or IP address of the Queue Agent.
(Mandatory)
• Organization unit: The organizational unit (e.g. a department name).
(Optional)
• Organization name: The organizational name (e.g. the company name).
(Optional)
• Locality name: The locality (e.g. city). (Optional)
• State name: The state/region. (Optional).
• Country: The country. (Optional)
• Subject alternate name: additional host names / IP addresses the certifi-
cate should be valid for, separated by a comma. (Mandatory).
Click Generate key pair when the fields are filled in.
244 Qmatic 211.03K

These fields will be combined to form the fully distinguished name of the certificate.
Example, using these values :
Key store alias: myAgentAlias
Common name: 127.0.0.1
Organization unit: RnD
Organization name: Qmatic
Locality name: Molndal
State name: VGR
Country: SE
Subject alternate name: 127.0.0.1, localhost
This will generate a certificate entry with the distinguished name "cn=127.0.0.1,
ou=RnD, o=Qmatic, l=Molndal, s=VGR, c=Sweden. This certificate will be valid for
host names 127.0.0.1, localhost.
When the certificate is stored, the alias name will be suffixed with a timestamp
(e.g. myAgentAlias-2017-04-10T13:37:00). This is to avoid conflicts and
overwriting previously used certificates.
4. In the Key pairs section, in the drop-down list, select the certificate and click
Manage signing, the following window will be opened:
Click the Download button. This will generate a Certificate Signer Request that
will be downloaded in your browser.
211.03K Qmatic 245

5. Send the Certificate Signing Request file to the desired Certificate Authority to
get it signed.
The response should be one file for the signer response as well as a number of
files describing the trust chain of the Certificate Authority.
Supported file formats are .cer, .der and .crt.
wanted Queue Agent.
7. In the Security -> Key pairs section, select the correct alias in the drop-down box
and click the Manage signing button. The following window will be opened:
8. Click the Choose Files button. Select the certificate signer response, as well as
the files containing the trust chain of the Certificate Authority.
9. Click the Upload button.
10. The certificate is now fully signed and can be properly used.
wanted Queue Agent.
12. In the Security -> Prepared security configuration section, enable the check
box for WebSocket secure enabled and select a port for WebSocket Secure port
246 Qmatic 211.03K


2a & 2b: Already existing Certificate, signed by public CA or Private

Body
Similar to a response from a Certificate Authority, a pre-signed certificate will
contain one file with the key-pair and more files making up the trust chain of the
Certificate Authority.
Supported file formats for the key-pair are .pfx and .p12.
Supported file formats for the trust chain are .cer, .der and .crt.
wanted Queue Agent.
211.03K Qmatic 247

2. In the Security -> Key pairs section click the Upload new button. The following
window will be opened:
3. Enter a new KeyStore alias name.

4. Click the Choose Files button and select the key-pair file as well as the files
containing the trust chain of the Certificate Authority.
5. Enter the Key pair password for the key-pair file.
6. Click Upload.
7. The certificate and trust chain should now be imported and can be properly
used.
wanted Queue Agent.
9. In the Security -> Prepared security configuration section, enable the check box
for WebSocket secure enabled and select a port for WebSocket Secure port

248 Qmatic 211.03K

Secure HTTPS communication for a Distributed Queue Agent.

To enable HTTPS for a distributed Queue Agent, first enable WebSocket Secure
communication for the distributed Queue Agent.
Once that is done, the only thing that is needed is to restart the Queue Agent.
The HTTPS connector in Jetty will use the same certificate that was used when
configuring WebSocket Secure.
Enabling HTTP to HTTPS redirect

To enable HTTP to HTTPS redirect:
wanted Queue Agent.
2. In the Security section check the HTTP to HTTPS redirect enabled check box.
Save the settings.
3. Restart the Queue Agent.
Selecting HTTPS protocol strength

By default, only the TLSv1.2 HTTPS protocol is enabled.
Depending on the client environment, connected hardware, browsers etc, it might
be necessary to enable weaker HTTPS protocols.
The protocols that can be enabled are:
• SSLv3
• TLSv1
• TLSv1.1
• TLSv1.2
SSLv3 is necessary if a Vision unit is going to be connected to the system. If no
such units are going to be connected to the Central Queue Agent, this protocol
should not be enabled.
211.03K Qmatic 249

TLS versions prior to 1.2 might be needed for older types of browsers, this would
depend on the client environment.
Wildfly
Edit the app\wildfly-8.2.0.Final\standalone\configuration\standalone-full.xml file.
Locate the https-listener configuration tag, change the enabled-protocols attribute,
so that it matches the requirements, example:
enabled-protocols="TLSv1,TLSv1.1,TLSv1.2"
Save the file and restart Orchestra.
JBoss
Edit the app\jboss-eap-6.3\standalone\configuration\standalone-full.xml file.
Locate the <ssl configuration tag (located inside tag: connector name="https"), and
edit the protocol attribute, example:
protocol="TLSv1,TLSv1.1,TLSv1.2"
Save the file and restart Orchestra.
Disabling HTTP and Running HTTPS Only
This section should not be followed until you have made sure that your HTTPS
communication is working properly.
You can configure Orchestra so that it exposes only HTTPS to connecting
systems.
In order to do this, a few preconditions must be met:
Some hardware cannot use HTTPS at all, so if you have these types of
hardware connected to the Central Queue Agent disabling HTTP is not an option:
• TP3115
• Intro8
• Cinematic
HTTP cannot strictly be disabled, since some components use it for internal
communication.
However, it can be set to listen only to localhost (127.0.0.1) so no one outside of
the Orchestra machine can use it.
To disable HTTP:
1. First configure HTTPS properly and ensure that it works.
250 Qmatic 211.03K

2. Open the System Administration application and the Parameters page and
change the system parameters Central HTTP Port and Central HTTP Protocol.
The port setting should be the port of the Central HTTPS port, default is 8443.
The protocol setting should be https.
3. Stop Orchestra.
4. Edit the server configuration file to set address 127.0.0.1 for HTTP traffic.
Wildfly:
File: app\wildfly-8.2.0.Final\standalone\configuration\standalone-full.xml
Change this line:
<socket-binding name="http" port="${jboss.http.port:8080}"/>
To this:
<socket-binding name="http" interface="unsecure" port="${jboss.http.port:8080}"/
>
JBoss:
File: app\jboss-eap-6.3\standalone\configuration\standalone-full.xml
Change this line:
<socket-binding name="http" port="8080"/>
To this:
<socket-binding name="http" interface="unsecure" port="8080"/>
5. Start Orchestra.
Removing HTTPS Warnings in Browsers

To remove HTTPS warnings in your browser:
1. Go to your browser’s Settings page and locate the section where certificates are
managed. Import the *.cer file that you exported in the flows above.
2. Place the certificate on Trusted Root Certification Authorities and make sure
that it is located there.
3. Restart your browser for the settings to take place.
211.03K Qmatic 251

Encryption of HornetQ JMS connections
JMS is used to transfer statistical events from Central and Distributed Queue
Agents to the Stat server (where the application stat.war is deployed).
The Stat server can be deployed together with Orchestra Central or on a
standalone server.
To be able to use SSL for encryption of stat messages, it is necessary to configure
matching certificates in a keystore on the stat server and a truststore on the Queue
Agent. The process of setting up certificates and using remote upgrade to transfer
them to remote Queue Agents is described earlier in this chapter.
Prerequisite
In the example below, tcp port 5446 will be used for encrypted JMS traffic. This port
needs to be open in the firewall.
Application Server Configuration - Wildfly 8.2
Add missing dependency for netty module

The version of Wildfly used in Orchestra 6.2 misses a dependency needed to
enable JMS sending over SSL.
1. Open the file <Orchestra installation>/app/wildfly-8.2.0.Final/modules/system/
layers/base/io/netty/main/module.xml in a text editor.
2. Edit the section <dependencies> and add a dependency to the module
javax.api.
The file should look like the below example after editing:
--------------------------------------
<?xml version="1.0" encoding="UTF-8"?>

<module xmlns="urn:jboss:module:1.3" name="io.netty">

<resources>
<resource-root path="netty-all-4.0.15.Final.jar"/>
</resources>
<dependencies>
<module name="javax.api"/>
</dependencies>
</module>
--------------------------------------
Configure Wildfly Application Server to allow encrypted JMS communication

The configuration of JMS transport on the server side is done in the Application
Server configuration file, standalone-full.xml, where we need to add a JMS
acceptor that will use the certificate in the keystore to handle the encrypted data.
In the example below we use the default keystore <installation>/conf/security/
keystore.jks, with the default password, to encrypt JMS traffic on port 5446.
1. On the stat server, open the configuration file <installation>/app/wildfly-
8.2.0.Final/standalone/configuration/standalone-full.xml in a text editor.
2. In the subsystem labelled <subsystem
xmlns="urn:jboss:domain:messaging:2.0">, locate the section <acceptors> and
add a new acceptor named netty-ssl with the following properties:
--------------------------------------
<acceptor name="netty-ssl">
<factory-
class>org.hornetq.core.remoting.impl.netty.NettyAcceptorFactory</
factory-class>
<param key="host" value="0.0.0.0"/>
<param key="port" value="5446"/>
<param key="ssl-enabled" value="true"/>
<param key="key-store-path" value="conf/security/keystore.jks"/>
<param key="key-store-password" value="changeit"/>
</acceptor>
--------------------------------------
3. Save the file.

4. Restart the Application Server.
211.03K Qmatic 253

Application Server Configuration - JBoss 6.3
Configure JBoss EAP Application Server to allow encrypted JMS communi-

cation
The configuration of JMS transport on the server side is done in the Application
Server configuration file, standalone-full.xml, where we need to add a JMS
acceptor that will use the certificate in the keystore to handle the encrypted data.
In the example below we use the default keystore <installation>/conf/security/
keystore.jks, with the default password, to encrypt JMS traffic on port 5446.
1. On the stat server, open the configuration file <installation>/app/jboss-eap-6.3/
standalone/configuration/standalone-full.xml in a text editor.
2. Locate the section where socket-bindings are defined and add a new socket-
binding for encrypted communication:
--------------------------------------
<socket-binding name="messaging-ssl" port="5446"/>
--------------------------------------
3. Locate the scetion where jms acceptors are defined and add a new acceptor for
ssl encrypted traffic:
--------------------------------------
<netty-acceptor name="netty-ssl" socket-binding="messaging-ssl">
<param key="key-store-path" value="conf/security/
keystore.jks"/>
<param key="key-store-password" value="changeit"/>
</netty-acceptor>
--------------------------------------
4. Save the file.
5. Restart the Application Server.
Configure Distributed Queue Agent to use encrypted JMS communication

To enable encrypted JMS communication we need to update the configuration file
<agent>/conf/hornetq-configuration.xml on the Queue Agent.
In the example below a valid certificate exists in the default truststore on the
Distributed Queue Agent in <agent>/conf/security/truststore.jks, with the default
password.
2. Open the conf/hornetq-communication.xml file and locate the section
<connectors>.
3. Change both configured connectors to use encrypted communication to port
5446
--------------------------------------
254 Qmatic 211.03K

<connectors>
<connector name="stat-remote-connector">
<factory-
class>org.hornetq.core.remoting.impl.netty.NettyConnectorFactory</factory-
class>


<param key="trust-store-path" value="conf/security/truststore.jks"/>
<param key="trust-store-password" value="changeit"/>
</connector>
<connector name="audit-remote-connector">
<factory-
class>

</connector>
</connectors>
--------------------------------------
4. Save the file

Configure central agent to use encrypted JMS communication
211.03K Qmatic 255

To enable encrypted JMS communication between a central agent and a

standalone stat server we need to update configuration file <Orchestra central>/
conf/hornetq-configuration.xml.
We also need to add a valid certificate in a truststore on the central Orchestra
server that corresponds to the configured keystore on the standalone stat server.
In teh example below we use the default truststore <Orchestra central/conf/
security/truststore.jks
1. Open the file <Orchestra central>/conf/hornetq-communication.xml file and

locate the section <connectors>
2. Change both configured connectors to use encrypted communication to port
5446
--------------------------------------
<connectors>
<connector name="stat-remote-connector">
<factory-
class>

</connector>
<connector name="audit-remote-connector">
<factory-
class>

256 Qmatic 211.03K

</connector>
</connectors>
--------------------------------------
4. Save the file

5. Restart Orchestra
Bandwidth Requirements
When HTTPS is used, the browser will disable some of its caching, which will
cause higher bandwidth requirements as follows:
• The link between the web browser and the Orchestra web server requires
0.03 Mbit/s per concurrent user.
• This is about 150% higher bandwidth requirements compared to accessing
the system with HTTP.
211.03K Qmatic 257

258 Qmatic 211.03K

12. SSO setup
SSO Setup Using Integrated Kerberos ............................... 260

SSO Setup Using Custom Pre-Authentication Proxy ......... 264
211.03K Qmatic 259

Qmatic Orchestra supports Single Sign-On (SSO). SSO means in this context that
when a user is authenticated in a Windows domain, that is has logged in to the
domain with a Windows Active Directory (AD) account, Orchestra will not ask for
user name and password. The user will be logged in to Orchestra automatically.
Some setup is required to enable SSO in Orchestra. A basic requirement is that
there is a Microsoft Windows Active Directory server controlling a Windows
domain. Both the host of the Orchestra server and the host(s) of the Orchestra
client(s) need to be members of this domain.
The remaining setup can then be divided in two areas, the Orchestra server area
and the Orchestra client (or Orchestra terminal user) area.
Useful information can be found in the official SPNEGO documentation. The
documentation includes complete descriptions of parameters and a thorough
example of how to set up SSO on JBOSS. At the time of writing, the documentation
can be found at http://spnego.sourceforge.net/
SSO Setup Using Integrated Kerberos
Client Area
Only one procedure is required to configure the Orchestra client(s). Set the client
browser (Microsoft Internet Explorer) to identify the Orchestra server as an intranet
site. Please follow the steps below:
1. Login to the Windows domain using the Windows account of the Orchestra
terminal user.
2. Start Internet Explorer.
3. Open the tab: Tools -> Internet Options -> Security.
4. Select Local Intranet.
5. Set the Security Level to Low.
6. Click Sites.
7. Click Advanced.
8. Fill in the IP address or the host name of your Orchestra server and click Add.
9. Close this window.
10. Click OK.
11. Click Advanced.
12. In the Security section, make sure that Enable Integrated Windows
Authentication is checked. If not, check the check box, and click Apply.
13. Close the Internet Options window by clicking OK.
260 Qmatic 211.03K

SSO setup
14. Close the browser.

The browser is now be configured to support SPNEGO.
Server Area
On the Active Directory domain controller, perform the following steps:
1. Register the host name of the Orchestra service in DNS.
This hostname should be in the same domain as the AD domain and MUST
BE a DNS A-record, i.e. NOT a CNAME record.
E.g. if your AD domain is test.q-matic.net, then the host name could be
testrd.test.q-matic.net.
2. Create a user that will hold the kerberos / SSO configuration. Alternatively re-
use another user.
The user should have a pre-set password that should not be possible to
change, and the password should never expire.
Example is a user named "kerberos" in the AD domain "test.q-matic.net".
To edit the properties of the user, right-click on its name in the Active Directory
Users and Computers window. The following window is opened:
211.03K Qmatic 261

In the Account options area of the Account tab, make sure that you check the
check box next to This account supports Kerberos AES 128 bit encryption, as
shown in the picture above.
3. Register the SPN (Service Principal Name, i.e. the servername) with the user.
This is done via the "setspn" command.
The command should be executed like this:
setspn -A HTTP/<hostname> <username>
Using the examples above the command would look like this:
setspn -A HTTP/testrd.test.q-matic.net kerberos
Note that setspn is not available in all versions of Windows 2003 server. You
can, however, download the Windows server 2003 support tools from the Microsoft
Web site.
The Orchestra server requires a few things in order to enable SSO.
Start by editing the <install_dir>/conf/krb5.conf file or <agent_profile_dir>/conf/
krb5.conf file, if the configuration is part of a configuration change in a remote
upgrade. Change the following entries in the file to match what is correct for your
domain:
• default_realm
• realms
• kdc
• default_domain
• domain_realm
In our example, the file looks like this:
[libdefaults]
default_realm = TEST.Q-MATIC.NET
default_tkt_enctypes = aes128-cts rc4-hmac des3-cbc-sha1 des-cbc-
md5 des-cbc-crc
default_tgs_enctypes = aes128-cts rc4-hmac des3-cbc-sha1 des-cbc-
md5 des-cbc-crc
permitted_enctypes = aes128-cts rc4-hmac des3-cbc-sha1 des-cbc-
md5 des-cbc-crc
[realms]
TEST.Q-MATIC.NET = {
kdc = testrd4.q-matic.net
default_domain = TEST.Q-MATIC.NET
}
[domain_realm]
.test.q-matic.net = TEST.Q-MATIC.NET
262 Qmatic 211.03K

SSO setup
The kdc field should be the server name, or IP adress, of your domain
controller, i.e. Active Directory.
Next, in Orchestra, navigate to the System Administration application and the
Parameters tab. In the SSO section, mark the enabled check box as active.
Enter the user created in AD as Pre-authentication username, e.g. "kerberos" and
enter the password for the user as Pre-authentication password.
Save the changes and restart Orchestra.
For any distributed QueueAgent instances the configuration made in the UI will
be enabled upon restart. However, the krb5.conf file must be modified for each
QueueAgent, or modified in an agent profile and sent to the Queue Agent via
remote upgrade. It should be identical to the one defined for the central installation,
unless the agent profile configuration has been overridden via remote upgrade.
Once configuration is complete, restart the Orchestra server.
If a misconfiguration is made, SSO can be disabled by editing the database.
Change the table qp_central.system_parameter. The field value should be set to
"false" for the row with ID "aaa.sso.enabled". This can also be done in the
Parameters tab of the System Administration application.
E.g. UPDATE qp_central.application_parameters SET value = 'false' WHERE id =
'aaa.sso.enabled';
SSO can also be disabled for an Agent Profile by remote upgade. Changing the
setting Enabled to false in System Administration -> Queue Agents -> Agent
Profiles -> Override Global Parameters values -> SSO and performing a remote
upgrade disables SSO for every Queue Agent that is currently assigned that
profile.
Once the setup is complete, SSO should work.
Once SSO is enabled, there can be issues logging in as superadmin, if using

a client that is a member of the domain.
The reason is that the client will attempt to log in automatically, not giving the user
the option to log in as superadmin.
211.03K Qmatic 263

A workaround exists:
1. Restart the browser to clear any login information.
2. Manually enter the URL into the browser address field: http://<orchestra
host>:<orchestra port>/login.jsp?failMessage=error.login.noApplications
Example:
http://testrd.test.q-matic.net:8080/
login.jsp?failMessage=error.login.noApplications
An error message is shown "User has no applications.", this can be disregarded
and log on as superadmin should be possible.
SSO Setup Using Custom Pre-Authentication Proxy
Prerequisites
Authentication and authorization is only supported on Orchestra Central. No
support exists for using a Pre-Authentication solution on Distributed Queue
Agents.
Authentication and authorization is based on HTTP header values set by the
authenticating proxy server.
Headers for username, roles, branches, and user first and last name are
supported.
Orchestra Central Configuration

1. First, determine which header values the authentication proxy will send.
Mandatory headers are for username and roles.
2. Navigate to System Administration -> Parameters -> Pre Authentication and
Authorization Settings.
3. Modify the default values so they fit the used authentication proxy:
Enabled - set to true
User name header - set to the HTTP header for user name
Group mapping IDs header - set to the HTTP header for roles
Branch mapping IDs header - (Optional) set to the HTTP header that contains
branch IDs / names
Given name header - set to the HTTP header that contains user’s given name
Surname header - set to the HTTP header that contains the user’s surname
4. Next, navigate to User Management -> Pre Authorization.
264 Qmatic 211.03K

SSO setup
5. Add the mappings corresponding to the roles and branch headers configured
above.
All role names in the received values for the HTTP header configured for
Group mapping IDs header should be entered in the name field for type Role.
All branch names in the received values for the HTTP header configured for
Branch mapping IDs header should be entered in the name field for type
Branch.
For example, if the HTTP header Group mapping IDs is configured with value
iv-groups and if reception-user is transmitted in the HTTP request for the HTTP
header iv-groups, then a role mapping is needed between reception-user and
the Orchestra role ReceptionUser.
6. Open the configuration file <orchestra_install_dir>\conf\shiro.ini. Change the
following lines, accordingly:
```
#preAuthSessionListener =
com.qmatic.qp.core.aaa.shiro.preauth.SessionListener
#securityManager.sessionManager.sessionListeners =
$preAuthSessionListener
```
7. If the shiro.ini file contains the following line, make sure that you remove it!
#preAuthRealm.authorizationCachingEnabled = false
8. Change the securityManager.realms section so that the preAuthRealm is

enabled:
```
#securityManager.realms = $ssoRealm, $ldapRealm, $agentRealm
# Change line above this to the one below to use pre-authentication
via an authenticating proxy
securityManager.realms = $ssoRealm, $ldapRealm, $agentRealm,
$preAuthRealm
```
9. Enable the preAuthFilter:

```
preAuthFilter = com.qmatic.qp.core.aaa.shiro.preauth.Filter
preAuthFilter.agentDataSource = $agentDS
```
10. Add the preAuthFilter to all URL:s that need to be exposed to the pre-
authentication proxy. In general, all URL:s defined in shiro.ini EXCEPT those
defined as “anon”, “/login.jsp”, “logout.jsp”, “/qsystem/rest/security/account/**”
can be enabled.
211.03K Qmatic 265

Example (not complete, more URL:s might apply in your Orchestra installa-
tion):
```
/ping.html = anon
/pages/* = preAuthFilter, qpAuthc
/home.html = preAuthFilter, qpAuthc
/login.jsp = qpAuthc
/logout.jsp = logout
# Central applications
/qsystem/system-web/** = preAuthFilter, qpAuthc, modules[cfm]
/ qsystem/aaaconfig-web/** = preAuthFilter, qpAuthc, modules[user]
/qsystem/surfaceeditor/rest/** = anon
/qsystem/surfaceeditor/** = preAuthFilter, qpAuthc, modules[surface]
/qsystem/administration/** = preAuthFilter, qpAuthc,
modules[unitType,license,widget,backup,parameter]
/qsystem/surfaceexplorer/** = preAuthFilter, qpAuthc,
modules[journeySchedule,journeyCreator,journeyPlayList]
...
/qsystem/rest/security/login = preAuthFilter, qpBasicAuthc
ipFilter[127.0.0.1,0:0:0:0:0:0:0:1]
/qsystem/rest/dm/** = preAuthFilter, qpBasicAuthc,
noSessionCreation, modules[adminConnect]
...
```
11. Finally, restart Orchestra.
Vendor-specific Configuration
WebSEAL
Integrations using WebSEAL need to have the “-j” flag set for junctions
connecting to Orchestra, to get junction cookies, so that WebSEAL handles server-
relative paths properly.
266 Qmatic 211.03K

13. HA setup
Deployment Architecture ................................... 268

Load Balancer .................................................... 269
Shared Storage .................................................. 270
RDBMS .............................................................. 270
Deployment Procedure ...................................... 270
HA Proxy Example ............................................. 271
211.03K Qmatic 267

This chapter details architecture and deployment for implementing Orchestra in an

HA (High Availability) configuration.
Deployment Architecture
• Multiple application servers

• Shared storage and RDBMS between application servers
• Load Balancer that supports websocket communication
268 Qmatic 211.03K

HA setup
• Active/Passive configuration with all traffic directed to primary, failover to sec-

ondary
Load Balancer
A Load Balancer / reverse proxy is installed in front of the application servers and
serves, as the main connection point for all communication to Orchestra.
The Load Balancer must be configured with the Orchestra application servers in
an active / passive setup. Whereby all traffic is directed to the primary instance and
the secondary is used a s a backup in case the primary fails.
It is recommended to use the same ports (e.g. 8080 for http traffic) in the Load
Balancer frontend as in the Orchestra backend.
To support Qmatic hardware devices that communicate with the Queue Agent
directly (e.g. GW1745, Intro 17), the Load Balancer will need to support the
websocket protocol and be capable of directing websocket traffic to the backend
instances, either at layer 7 or at least layer 4 TCP.
To prevent a SPOF (single point of failure) in the architecture, the Load Balancer /
reverse proxy should be deployed in an HA configuration also. The setup of this
configuration is specific for the selected HA solution and is not in the scope of this
manual.
If HTTPS is required, it is advised that SSL be terminated at the Load Balancer and
proxy HTTP to the application servers to offload the SSL processing.
The following HTTP headers should be configured at the Load Balancer to send to
Orchestra application servers:
Header Value Comments

X-Forwarded-Proto https Use only when offloading
SSL at Load Balancer.
X-Forwarded-For <default> Identifies the source client IP
address.
Proxy-IP Same as X-Forwarded-For Used by Glassfish instead of
‘X-Forwarded-For’ in some
places.
See “HA Proxy Example” on page 271, for an example configuration with a popular
open source Load Balancer. In the example configuration for HAProxy is included
a frontend for terminating SSL traffic at the Load Balancer.
211.03K Qmatic 269

Shared Storage
It is recommended that the following directories are synchronised between the

application servers:
/conf
/media
/custdeploy
/deploy/wookie.war/wservices
Synchronisation can be either a manual process, or automatic, by way of shared

storage mechanisms. This will be a design choice, based on the requirements and
system usage. For example, the contents of the /conf folder may never (or rarely)
be touched on a production system, once deployed, and can be copied manually.
If widgets or custom applications are not utilised then the /deploy/wookie.war/
wservices and /custdeploy directories do not need to be synchronised.
To utilise shared storage on the application server instances, NAS (Network
Attached Storage) should be mounted to the same location on both servers and
symbolically link the required folders to this mount point (using mklink to create
symbolic links on Windows file systems).
Symbolic links on Windows for the directory /media are only supported on
Orchestra 6, Hotfix1, and later.
Alternatively, on Windows, DFS replication can be used to synchronise the
directories.
RDBMS
Both application servers use the same database instance.

To prevent a SPOF in the architecture, the RDBMS should be deployed in an HA
configuration also as per the vendors specifications (e.g. Oracle RAC, MSSQL
Clustering).
Deployment Procedure
1. Setup databases using scripts provided with Orchestra installation.
2. Install Orchestra on one application server.
3. Test installation.
4. Either clone existing application server, or install Orchestra again on second
server, pointing to the same databases. The second installation must be made
to the exact same path as the first.
5. Test second installation.
270 Qmatic 211.03K

HA setup
6. Install and configure Load Balancer / reverse proxy.

7. Configure both Orchestra systems with the address to the Load Balancer /
reverse proxy, where necessary:
• The JVM parameter agent.ipAddress in the startscript (stan-
dalone.conf.bat on Windows and standalone.conf on Linux) for the JBoss/
Wildfly application server is used to configure certain hardware, e.g. Cine-
matic, and should be the address to the Load Balancer /reverse proxy. This
file is located in <Orchestra install>\app\<application server>\bin\ .
• The address configured in the file <Orchestra install>\pentaho-solu-
tions\system\security.properties is used for browser navigation between
Business Intelligence and Orchestra. The parameter central.orchestra.url
needs to be changed to the Load Balancer address.
• The address configured in the file <Orchestra install>\pentaho-solu-
tions\system\score.properties is used by Business Intelligence to perform
authorization towards Orchestra. If Business Intelligence is setup on a sep-
arate server, the parameter security.url needs to be changed to the Load
Balancer address.
• All connected hardware should connect to the Load Balancer. If hardware
was connected to the system before the Load Balancer was set up, it is
necessary to change that configuration both in the hardware and in
Orchestra
• Test access via Load Balancer from browser.
8. Test access via Load Balancer for hardware.
9. Test failover, stop Orchestra service on primary, confirm users re-directed to
secondary. (Users will have to re-login, as session data is not replicated.
Hardware should loose connection and re-connect automatically).
HA Proxy Example
global
daemon
nbproc 1
user haproxy
group haproxy
log 127.0.0.1:514 local0
pidfile /var/run/haproxy.pid
stats socket /var/run/haproxy.stat mode 777
tune.comp.maxlevel 5
maxcompcpuusage 98
maxconn 30000
spread-checks 5
defaults
mode http
211.03K Qmatic 271

log global
option httplog
option http-server-close
option dontlognull
option redispatch
option splice-auto
option clitcpka
option srvtcpka
option tcp-smart-accept
option tcp-smart-connect
option contstats
retries 3
timeout http-request 5s
timeout http-keep-alive 5s
timeout connect 5s
timeout client 25s
timeout client-fin 30s
timeout tunnel 1h
timeout server 25s
timeout queue 10s
timeout tarpit 15s
backlog 10000
compression algo gzip

compression type text/html text/html;charset=utf-8 text/
html;charset=ISO-8859-1 text/plain text/css text/javascript
application/x-javascript application/javascript application/
ecmascript application/rss+xml application/atomsvc+xml
application/atom+xml application/atom+xml;type=entry application/
atom+xml;type=feed application/cmisquery+xml application/
cmisallowableactions+xml application/cmisatom+xml application/
cmistree+xml application/cmisacl+xml application/msword
application/vnd.ms-excel application/vnd.ms-powerpoint
errorfile 408 /dev/null # workaround Chrome pre-connect bug
frontend http
bind *:80
maxconn 1000
http-request set-header X-Forwarded-For %[src]

option forwardfor header Proxy-ip
rspidel ^Server:.*
rspidel ^X-Powered-By:.*
acl is_ws path_beg /wsdc hdr(Upgrade) -i websocket
272 Qmatic 211.03K

HA setup
acl is_comet path_beg /cometd/
use_backend bk_comet if is_comet

use_backend bk_ws if is_ws
default_backend bk_web
#Optional example frontend for terminating SSL at the load balancer

frontend https
mode http
option forwardfor
bind *:8443 ssl crt <path_to_pem_file>
reqadd X-Forwarded-Proto:\ https
rspiprep ^Location:\ http:(.*) Location:\ https:\1
acl is_ws path_beg /wsdc hdr(Upgrade) –i websocket

acl is_comet path beg /cometd/
use_backend bk_comet if is_comet

use_backend bk_ws if is_ws
default_backend bk_web
backend bk_web
acl is_static capture.req.uri -m end .css .png .jpg .gif .js

.favicon.ico
rspadd Cache-Control:\ public if is_static
server oas1 10.0.41.172:8080 check

server oas2 10.0.47.106:8080 check backup
backend bk_comet
timeout server 120s
cookie comet insert
server oas1 10.0.41.172:8080 check

backend bk_ws
server oas1 10.0.41.172:8888 check on-marked-up shutdown-backup-

sessions
listen stats :9090

mode http
no log
211.03K Qmatic 273

stats enable
stats refresh 15s
stats uri /stats
274 Qmatic 211.03K

Appendix A - Tuning
Database
Parameters
Topics in this Appendix
Tuning of Oracle Parameters ................................................... 276

Tuning of PostgreSQL Parameters .......................................... 277
211.03K Qmatic 275

Tuning of Oracle Parameters
Depending on the size of the Orchestra installation and the number of database
connections set in the different database connection pools in the Orchestra
application server, Oracle parameters may have to be tuned.
The database must be able to cope with the sum of all database connection pools
in Orchestra.
The three most commonly tuned parameters are:
• PROCESSES
• SESSIONS
Should match number of configured connections in the Orchestra database
connection pools.
Oracle recommend setting it to PROCESSES x 1.1 + 5
• TRANSACTIONS
Oracle recommends setting it to SESSIONS x 1.1
Example:
ALTER SYSTEM SET PROCESSES=1200 SCOPE=SPFILE;
ALTER SYSTEM SET TRANSACTIONS=1458 SCOPE=SPFILE;
ALTER SYSTEM SET SESSIONS=1325 SCOPE=SPFILE;
Additional parameters to review
Oracle memory
• MEMORY_TARGET
• MEMORY_MAX_TARGET
Example:
ALTER SYSTEM SET MEMORY_TARGET=8000M SCOPE=SPFILE;
ALTER SYSTEM SET MEMORY_MAX_TARGET=10000M SCOPE=SPFILE;
Adaptive log file sync

Oracle 11 introduced an new mechanism to communicate with the log writer, a part
of the commit-process. Several Oracle database administrators have experienced
a considerable performance gain when they have disabled this new "adaptive log
file synchronization".
ALTER SYSTEM SET "_use_adaptive_log_file_sync"= false;
276 Qmatic 211.03K

Appendix A - Tuning Database Parame-
Cursor sharing
Qmatic Orchestra gains additional performance if cursor sharing is set to
ALTER SYSTEM SET CURSOR_SHARING='SIMILAR' SCOPE=SPFILE;
Tuning of PostgreSQL Parameters
PostgreSQL comes with default values that work across different systems with
varying resource availability so they are really the lowest common denominator to
get it running everywhere. This section contains some values to tweak when there
is more memory to play with.
Make sure that you know what the setting does, before changing it. Do not just
increase some memory values, thinking that it will magically fix everything. Consult
the manual, found on http://www.postgresql.org/docs/9.4/static/runtime-config-
resource.html and http://www.postgresql.org/docs/9.4/static/runtime-config-
query.html, before changing any settings.
On http://pgtune.leopard.in.ua/ you can find a calculator that gives some sense of
what to tweak. It will calculate values for some recommended settings, based on
how much total RAM your machine has. Set max_connections to 100, as that is
what is the default value is for a PostgreSQL installation, and should be enough for
small to mid-sized installations. Consider increasing the number of connections, if
you have a large installation with only a central Queue Agent.
211.03K Qmatic 277

These are the main settings to tweak (values are for a machine with 13GB of
memory). Note however that the changes to memory values and cache sizes do
not mean that that much will be consumed by PostgreSQL at all times.
Table 1: Changes to postgresql.conf.
New value
Setting Description
(Default)
max_connections 100 (100) Do not change this without

consulting the manual! This works in
conjunction with work_mem and
some other stuff and can lead to
excessive memory usage if not
changed appropriately. If you
increase this to say 200, make sure
to lower work_mem.
shared_buffers 256MB (128MB) Keep this low. Recommendation is

to use 25% of available memory but
some say this value doesn't provide
much benefit. effective_cache_size
seems to give more value.
effective_cache_- 8GB (4GB) See memory values in performance

size tab in Task Manager (Windows) for
the system's "Cache" value and
compare that to available free RAM
and use a value that is somewhere in
that vicinity. This seems to have
most potential for improving
performance. High values favor use
of indexes in the DB. Some just set
this value to the amount of available
free RAM.
work_mem 16MB (4MB) This can be tricky to set as it can

cause excessive memory use for
complex queries if many clients run
the same queries at the same time.
So the worst case scenario can be
high (luckily Orchestra doesn't have
many overly complex queries).
autovacu- 512MB (-1 i.e. The amount of memory that the auto
um_work_mem uses mainte- vacuum process is allowed to
nance_work_me consume the most. Setting this high
m value) can speed up vacuum work.
278 Qmatic 211.03K

Appendix A - Tuning Database Parame-
Table 1: Changes to postgresql.conf.
New value
Setting Description
(Default)
checkpoint_seg- 32 (3)
ments
checkpoint_com- 0.7 (0.5)

pletion_target
wal_buffers 16MB (4MB)
random_page_- 3 (4) If there is lots of memory for the

cost database i.e. lots of it is cached
(Available memory higher than size
of DB), and/or the DB machine uses
SSD disks for the DB, then lowering
this value can provide some
performance gains.
Make sure to restart PostgreSQL when done. A reload will not be sufficient, as
some settings require a restart.
To see what settings the PostgreSQL installation currently has, use the following
query:
SHOW ALL
211.03K Qmatic 279

280 Qmatic 211.03K

Appendix B - Logging
Enabling Customer Journey Management Logging ................. 282

Enabling Publish Logging ........................................................ 283
211.03K Qmatic 281

Enabling Customer Journey Management Logging
Add a new file appender for the Customer Journey Management logging.
In <orchestra install dir>/conf/logback.xml, add the following element just above
the line with "<logger name="com.sun.enterprise.server.logging.GFFileHandler"
level="INFO"/>":
<appender name="cfmAppender"
<file>${com.sun.aas.instanceRoot}/../../../../../logs/
cfm.log</file>
<rollingPolicy
<fileNamePattern>${com.sun.aas.instanceRoot}/../../../
../../logs/cfm-%d{yyyy-MM-dd}_%d{HHmmss}.%i.log</fileNamePattern>
cy">
</rollingPolicy>
<encoder>
<pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level
%logger{36} - %msg%n</pattern>
</encoder>
<filter
class="ch.qos.logback.classic.filter.ThresholdFilter">

<level>DEBUG</level>
</filter>
</appender>
Around line 160, replace the line:

<logger name="com.qmatic.qp.jiql.core.cfm" level="INFO"/>
with these lines:

<logger name="com.qmatic.qp.jiql.core.cfm" level="DEBUG"
additivity="false">
<appender-ref ref="cfmAppender"/>
</logger>
Save the file, it will take effect within a minute.
282 Qmatic 211.03K

Appendix B - Logging
Enabling Publish Logging
Add a new file appender for the publish logging.

In <orchestra install dir>/conf/logback.xml, add the following element just above
the line with "<logger name="com.sun.enterprise.server.logging.GFFileHandler"
level="INFO"/>":
<appender name="publishAppender"
<file>${com.sun.aas.instanceRoot}/../../../../../logs/
publish.log</file>
<rollingPolicy
<fileNamePattern>${com.sun.aas.instanceRoot}/../../../
../../logs/publish-%d{yyyy-MM-dd}_%d{HHmmss}.%i.log</
fileNamePattern>
cy">
</rollingPolicy>
<encoder>
<pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level
%logger{36} - %msg%n</pattern>
</encoder>
<filter
class="ch.qos.logback.classic.filter.ThresholdFilter">

<level>DEBUG</level>
</filter>
</appender>
Around line 150, replace the this line:

<logger name="com.qmatic.qp.jiql.core.cm" level="INFO"/>
with these lines:

<logger name="com.qmatic.qp.jiql.core.cm" level="DEBUG"
additivity="false">
<appender-ref ref="publishAppender"/>
</logger>
Save the file, it will take effect within a minute.
211.03K Qmatic 283

284 Qmatic 211.03K

Appendix C - Security
Content-Security-Policy ........................................................... 286

X-Frame-Options ..................................................................... 286
X-Content-Type-Options .......................................................... 287
X-XSS-Protection ..................................................................... 287
Strict-Transport-Security .......................................................... 288
Modifying HTTP Response Headers ....................................... 288
211.03K Qmatic 285

The following HTTP response headers are set by default in Orchestra.
Content-Security-Policy
The HTTP Content-Security-Policy response header allows web site

administrators to control resources the user agent is allowed to load for a given
page. With a few exceptions, policies mostly involve specifying server origins and
script endpoints. This helps guard against cross-site scripting attacks (XSS).
Syntax
Content-Security-Policy: <policy-directive>; <policy-directive>
Orchestra default configuration

Content-Security-Policy: *
X-Frame-Options
The X-Frame-Options HTTP response header can be used to indicate whether or

not a browser should be allowed to render a page in a <frame>, <iframe> or
<object>. Sites can use this to avoid clickjacking attacks, by ensuring that their
content is not embedded into other sites.
The added security is only provided if the user accessing the document is using a
browser supporting X-Frame-Options.
Syntax
There are three possible directives for X-Frame-Options:
X-Frame-Options: DENY
X-Frame-Options: SAMEORIGIN
X-Frame-Options: ALLOW-FROM https://example.com/

X-Frame-Options: SAMEORIGIN
286 Qmatic 211.03K

X-Content-Type-Options
The X-Content-Type-Options response HTTP header is a marker used by the

server to indicate that the MIME types advertised in the Content-Type headers
should not be changed and be followed. This allows to opt-out of MIME type
sniffing.
Syntax
X-Content-Type-Options: nosniff

X-Content-Type-Options: nosniff
X-XSS-Protection
The HTTP X-XSS-Protection response header is a feature of Internet Explorer,

Chrome and Safari that stops pages from loading when they detect reflected cross-
site scripting (XSS) attacks. Although these protections are largely unnecessary in
modern browsers when sites implement a strong Content-Security-Policy that
disables the use of inline JavaScript ('unsafe-inline'), they can still provide
protections for users of older web browsers that don't yet support CSP.
Syntax
X-XSS-Protection: 0
X-XSS-Protection: 1
X-XSS-Protection: 1; mode=block
X-XSS-Protection: 1; report=<reporting-uri>

X-XSS-Protection: 1
Explanation: Enables XSS filtering (usually default in browsers). If a cross-site

scripting attack is detected, the browser will sanitize the page (remove the unsafe
parts).
211.03K Qmatic 287

Strict-Transport-Security
The HTTP Strict-Transport-Security response header (often abbreviated as HSTS)

is a security feature that lets a web site tell browsers that it should only be
communicated with using HTTPS, instead of using HTTP.
Syntax
Strict-Transport-Security: max-age=<expire-time>
Strict-Transport-Security: max-age=<expire-time>; includeSubDomains
Strict-Transport-Security: max-age=<expire-time>; preload

Strict-Transport-Security: max-age=31536000; includeSubDomains
Explanation: All present and future subdomains will be HTTPS for a max-age of 1
year. This blocks access to pages or sub domains that can only be served over
HTTP.
Modifying HTTP Response Headers
The default response headers are configured in the application server

configuration file and can be modified.
JBoss EAP
On JBoss EAP application servers, the configuration file is <Orchestra>/system/
app/jboss-eap-6.3/standalone/configuration/standalone-full.xml.
Locate the following section and modify the responseHeaderValue parameters (in
bold below).
To disable a response-header, comment out or remove the entire <valve> tag
Save the file and restart Orchestra to apply the changes.
….
<valve name="xContentTypeOptions" module="qmatic-valve-lib" class-
name="com.qmatic.httpresponse.HttpResponseHeaderValve">
<param param-name="responseHeaderName" param-value="X-Content-
Type-Options"/>
<param param-name="responseHeaderValue" param-value="nosniff"/
>
</valve>
<valve name="contentSecurityPolicy" module="qmatic-valve-lib" class-
<param param-name="responseHeaderName" param-value="Content-
Security-Policy"/>
<param param-name="responseHeaderValue" param-value="*"/>
288 Qmatic 211.03K

</valve>
<valve name="xXssProtection" module="qmatic-valve-lib" class-
<param param-name="responseHeaderName" param-value="X-XSS-
Protection"/>
<param param-name="responseHeaderValue" param-value="1"/>
</valve>
<valve name="strictTransportSecurity" module="qmatic-valve-lib"
class-name="com.qmatic.httpresponse.HttpResponseHeaderValve">
<param param-name="responseHeaderName" param-value="Strict-
Transport-Security"/>
<param param-name="responseHeaderValue" param-value="max-
age=31536000; includeSubDomains"/>
</valve>
Options"/>
<param param-name="responseHeaderValue" param-
value="SAMEORIGIN"/>
</valve>
….
Wildfly
On Wildfly application servers, the configuration file is <Orchestra>/system/app/
wildfly-8.2.0.Final/standalone/configuration/standalone-full.xml
Locate the following section and modify the responseHeaderValue parameters (in
bold below).
To disable a response-header, comment out or remove the entire <response-
header> tag together with the corresponding <filter-ref> tag found a few lines
above the <response-header>.
Save the file and restart Orchestra to apply the changes.
<filters>
<response-header name="server-header" header-name="Server"
header-value="WildFly/8"/>
<response-header name="x-powered-by-header" header-name="X-
Powered-By" header-value="Undertow/1"/>
<response-header name="xContentTypeOptions" header-name="X-
Content-Type-Options" header-value="nosniff"/>
<response-header name="contentSecurityPolicy" header-
name="Content-Security-Policy" header-value="*"/>
<response-header name="xXssProtection" header-name="X-XSS-
Protection" header-value="1"/>
<response-header name="strictTransportSecurity" header-
name="Strict-Transport-Security" header-value="max-age=31536000;
includeSubDomains"/>
211.03K Qmatic 289

<response-header name="xFrameOptions" header-name="X-Frame-

Options" header-value="SAMEORIGIN"/>
<filter name="qmatic-http-method-white-list" class-
name="com.qmatic.httpfilter.UndertowWhiteList" module="qmatic-
httpfilter-lib"/>
</filters>
290 Qmatic 211.03K

Index
A Distributed operation 9
AD/LDAP server certificate 142, 144 Distributed Queue Agent 109, 176
Agent Parameters 128
Agent Profile 109, 118, 124, 125 E
Agent Profile Synchronization 109 Entered Queue 4
Agent Profile Zip File 121 Entry Point 4
Application Parameters 132 Export 101
Application Server 46 export 102
Appointment 3
Appointment Terminal 186 F
Arrived 3 Failed events 171
B G
Bandwidth Requirements 9 Gateway 1745 43
Basic configuration 59 General Parameters 127
Blocking Websocket Port 64 GUI language viii, 174
Branch 3
Branch Agnosticism 9 H
Branch Hub 62, 110 Home 7
Browser Specific Settings 176 Hub 62, 110
Business Intelligence 21, 71, 188
I
C Import 101
Calendar 51 import 103
Calendar Admin 179 Information Display 4
Calendar View 179 Installation 27
Called 3 Installation Wizard 45, 48
Calling Rule 3
Central 33, 85, 174 J
Central Orchestra 50 Jboss Related Configuration 25
Central Queue Agent 174 Journey 4
Client Area 260
Customer 3 K
Customer Journey Management 2, 3 Keystore Explorer 224, 225, 227, 231
D L
Database settings 47 LDAP 141
default keystore 220 LDAP Certificate Handling 141
default truststore 220 Licensing 98
Delivered Service 3 Linux 36, 42, 87, 89
Deployment Scenarios 11
Display 3
211.03K Qmatic i
M SQL Server 24
Main Display 4 SSO 26
Mark 4 Staff 5
Mark Types 144 Staff member 5
Mobile Connect 52, 65 Suggested Upgrade Order 69
Multiple Queue Agents 116 Supported Environments 13
Synchronizing 126
N Synchronizing of Queue Agent 108
No Show 4
T
O Terminal 5
Off-line activation 100 Ticket 5
On-line activation 99 Ticket Id 5
Oracle 25 Time zones 5
Outcome 4 Transaction 6
Translation of Calendar 179
P Tuning of Oracle Parameters 276, 282,
Parameters 126 286
Performance Test 110 Tuning of PostgreSQL Parameters 277,
Port and Protocol Handling 221 283
Port Numbers 16
Positional Display 4 U
pre-configuration 59 Unit Type Files 91
Presentation Point 4 Unit Type Templates 177
Properties File 45, 92 Unit Types 89, 96
Upgrade Wizard 92, 93
Q utt 177
Queue 4
Queue Agent 39, 89, 110, 114, 126 V
Queuing Profile 4 Visit 6
R W
Reception 5 Widget Administration 104
Reception Terminal 50 Widget Mapping 107
Redeploying Applications 62 Widget Whitelist 106
Regression Test 110 Widgets 92, 177
Remote Update 108 Windows 86, 89
Remote Upgrade 112 Work Profile 6
Reverse-proxy 27 Workstation 6
Reverse-proxy installation 30
S
Same-domain 27
Same-domain installation 30
SDK 52
Separate Server 26, 84
Served 5
Server Area 261
Service 5
Service Point 5
Service Transaction 5
session sharing 29
ii Qmatic 211.03K
Q-MATIC AB
Box 198
SE-431 23 Mölndal
Sweden
VAT No SE556212749701
Phone: +46 31 756 46 00

Fax: +46 31 756 46 99
Email: info@qmatic.com
Web: www.qmatic.com

211 03 K Orchestra Ref Man

Загружено:

Сведения о документе

Авторское право

Доступные форматы

Поделиться этим документом

Поделиться или встроить документ

Параметры публикации

Этот документ был вам полезен?

Это неприемлемый материал?

Авторское право:

Доступные форматы

211 03 K Orchestra Ref Man

Загружено:

Авторское право:

Доступные форматы

Reference Manual

Please send any feedback or questions about this manual to

1. What’s New ...............................................................vii

211.03K Qmatic iii

8. Stat Aggregation .....................................................165

10. Network Connectivity ............................................205

11. Secure Communication.........................................217

13. HA setup .................................................................267

14. Appendix A - Tuning Database Parameters ........275

15. Appendix B - Logging............................................281

16. Appendix C - Security............................................285

211.03K Qmatic vii

System Administration chapter

Secure Communication chapter

viii Qmatic 211.03K

Topics in this chapter

Customer Journey Management ........................... 2

Welcome to Qmatic Orchestra - an advanced system for Customer Journey

Customer Journey Management

Optimising customer journeys improves customer service and creates a more

Customer Journey Management Terminology

Table 1: Customer Journey Management Terminology

Arrived Used, for Appointments, when a Customer has

Branch An office or department carrying out one or

Called When the ticket number was called, no matter

Calling Rule A set of rules that decide from which Queue

Customer A Customer is a person visiting a Branch.

Customer Journey Manage- The setup of Services, and Queues, Calling

Delivered Service A kind of Mark about what Service that the

Display Generic display that can change view, e.g.

Table 1: Customer Journey Management Terminology

Entered Queue Every time a Customer is placed in a Queue

Entry Point A Display that allows a Customer to choose a

Information Display A LED or a graphical Display that shows sys-

Journey A Journey includes all activities (Visits,

Mark A User defined value that can be added to a

Main Display A LED or a graphical Display in the waiting

No Show A Customer that does not respond to a call.

Outcome A Mark object that can be added to a Service

Positional Display Display above a Workstation Service Point.

Presentation Point A Unit that can display information, for exam-

Queue A first in first out list of customers.

Queuing Profile A part of the Branch Operation Profile that

Table 1: Customer Journey Management Terminology

Reception Where the Visit (sometimes) starts, once inside

Served When there has been at least some interaction

Service A Service is what our client delivers. A task

Service Point A unit where the Staff member is handling the

Service Transaction The process of attending a Service.

Staff member A Person delivering a Service.

Terminal A hardware Workstation Service Point. See

Ticket Most commonly a physical note with the queue

Ticket Id The reference to the Visit. For example a ticket

Table 1: Customer Journey Management Terminology

Transaction A Transaction is the waiting and deliverance of

Visit A Visit is the part of a Customer Journey where

Work Profile A Work Profile calls Customers from a speci-

Workstation A Counter where a user handles the errand of

Below, the available components of Orchestra are listed:

This application is not available as a component on the Home page.

This application is not available as a component on the Home page.

Distributed Operations is a unique Orchestra feature, which allows you to configure

When do you need it?

How does it work?