Qmatic Orchestra 7.4 – Reference Manual

Version 211.01F — COPYRIGHT © Q-MATIC AB, 2026

Send feedback or questions about this manual to documentation@qmatic.com.

Table of Contents

1. What's New
2. Introduction
3. Installation
4. Upgrade
5. System Administration
6. Auditing
7. Stat Aggregation
8. Localisation
9. Xtend
10. Network Connectivity
11. Secure Communication
12. SSO Setup
13. HA Setup
14. Appendix A – Tuning Database Parameters
15. Appendix B – Logging
16. Appendix C – Security
17. Appendix D – Open LDAP Setup
18. Appendix E – Set up SAML

1. What's New

2. Introduction

Welcome!

Welcome to Qmatic Orchestra, an advanced system for Customer Journey Management. Qmatic Orchestra is an enterprise-grade platform designed for large, centralized installations, while also supporting distributed deployments. The platform is highly flexible and can be adapted to meet different customer requirements.

Customer Journey Management

To connect people to services and make sure that customers are served in a fair and efficient manner is Qmatic Orchestra's most important task. Setting up your customer journey solution starts by defining your services. Services represent the choices customers can make when they enter the premises. A service choice results in a visit number being generated and usually printed on a ticket. Visit numbers are selected from queues depending on profiles when a staff member gives the Next command.

System description

The Home page of Qmatic Orchestra shows which components of the system are installed. Available components include:

• Appointment Booking – used by staff at a call centre to book and handle Appointments.
• Appointment Reception – application for arriving appointments.
• Business Configuration – branch configuration, Operation Profiles, Services, etc.
• Concierge – meet-and-greet application for creating visits and arriving appointments.
• Connect – call and serve visits on a mobile device (native app).
• Context Marketing – manage messages and playlists.
• Counter – call and serve visits.
• Calendar Admin – configure appointment profiles, resources and similar.
• Calendar Client – manage and get an overview of appointment bookings.
• Operations Panel – branch live information.
• Notification Admin – SMS and email administration.
• Personal data management – handling customer information and retention policies.
• Reception – create visits and print tickets.
• Surface Editor – surface application designer.
• System Administration – parameter settings, LDAP/SAML settings, import/export, license management, unit type templates, widget handling, etc.
• User Management – manage users, roles, and LDAP/SAML integration.
• Xtend – install and update extensions.

Branch Agnosticism

By default, if a user is assigned a role that is branch agnostic, the user will see all branches, even if all the other assigned applications are branch aware. To change this default behavior, set the branch_app variable to true/false for the applicable application(s) in the applications table.

Distributed Operations

Distributed Operations 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 customers' needs even if the connection to the central server is lost.

When do you need distributed operations?

Distributed Operation is needed when:

• Available WAN bandwidth is poor or the WAN connectivity is not 100% reliable and suffers from high latency.
• Several business critical systems are competing for WAN bandwidth at peak times.

How does it work?

• Central stat server handles persistence of all statistical data.
• Branches are configured to operate on distributed queue agent instances.
• Distributed queue agent connects outbound to central Orchestra instance across WAN; communication is bi-directional once established.
• Upon connectivity failure, local users continue to operate as usual.
• The distributed queue agent keeps a local copy of all runtime data and configuration.
• The distributed queue agent sends event data for statistical data handling to the central stat server when a network connection is present.
• Appointments for the current day are synchronized directly; appointments for the next day are synchronized nightly.
• Qmatic Orchestra upgrades can be applied centrally, then applied to all branches using remote update.

Deployment Scenarios

The most common deployment scenarios are: Fully Central, Fully Distributed, Central & Distributed, and Distributed on Region Servers.

Supported Environments

For more information about supported Operating Systems, Application Servers, Databases and Web Browsers, please refer to the Qmatic Orchestra Data Sheet on Qmatic World.

Cloud Bridge

Cloud Bridge is a full duplex communication module that enables communication between Orchestra and cloud services. Events sent to the cloud: CFM, QUEUE, BRANCH. Orchestra commands it can call: service point and entry point. Communication uses MQTT protocol (port 443). For installation, check the Cloud Bridge component in the installation wizard or set application.cloud.bridge = true in install.properties.

Accessibility

Qmatic Orchestra has implemented accessibility features according to WCAG 2.1 for the following applications: Concierge, Counter, Mobile Ticket. Accessibility has been primarily optimized for NVDA on Chrome, Firefox and IE 11.

3. Installation

Introduction

Preinstalled User

When Qmatic Orchestra is installed, it comes with a preinstalled user:

• Username: superadmin
• Password: ulan

Note: The first time you log in with superadmin, you will be prompted to change the password. The password must contain at least 8 characters, 1 digit and both lower case and upper case letters. Changes may take around a minute to take effect.

Port Numbers

Central Orchestra Server: HTTP: 8080, HTTPS: 8443, Queue Agent communication: 8787, Device communication: 8888

Standalone Queue Agent: HTTP: 18080, HTTPS: 18443* (not enabled by default), Device communication: 18888

Connect Agent ports: 9797, 4443, 1434, 9009, 5445, 5432, 443

HA Setup ports: 40010, 40020

Changing Port Numbers

To change the default HTTP port (example: 8080 to 15050):

1. Change the port in the Wildfly Admin console (http://localhost:9990, User: admin, Password: ulan).
2. Change the port in the Configuration Files (standalone-full.xml).
3. Change the port in the Startup Files (standalone.conf.bat).
4. Change the port in shiro.ini.
5. Restart Orchestra.
6. Change the Central HTTP Port in Orchestra System Parameters.
7. Restart Orchestra.
8. Publish all central branches.

Prerequisites - Checklist

Installation Scenarios

Two main scenarios:

• Orchestra and Stat on the same server – run the installation wizard once.
• Orchestra and Stat on separate servers – run the installation wizard twice (once for Orchestra on Server A, once for Stat on Server B).

Installation – Windows

1. Unpack QP_Central__win_<type>-<version>.zip to a suitable directory (no spaces in path).
2. Prepare the database by running the scripts for your database type (Microsoft SQL, Oracle, or PostgreSQL).
3. Open Windows Task Manager and ensure no application called "Services" is running.
4. Run install.bat and follow the wizard steps: select Install, enter installation path and External IP, select components, configure database, review summary, and click Finish.
5. When complete, open http://<ORCHESTRA_IP>:8080, log in with superadmin/ulan.

Installation – Linux

1. Transfer and unpack the QP_Central_linux64-<version>.tgz file.
2. Create a qmatic user, Orchestra directory, and set appropriate permissions.
3. Run the database scripts as appropriate.
4. Run install.sh (or ./install.sh -s for silent mode).
5. Add startup scripts: sudo ./install-services-systemd.sh (SystemD) or sudo ./install-services.sh (SystemV).

Installation Notes

CentOS: Increase "max user processes" to 2048 and "max open files" by 30000. Make sure hostname is resolvable. Install additional fonts for headless servers. Increase kernel semaphore settings.

TLS Security: TLS security settings are automatically enabled during installation. To mitigate LOGJAM, Diffie-Hellman key-size is automatically increased from 1024 to 2048.

Windows Authentication (SQL Server): Grant Logon as service access, create databases using integrated scripts, then run installation in silent mode with mssql.integrated.security = true.

IPv6: Use install_ipv6.bat/.sh when installing with IPv6. Short localhost is [::1].

Orchestra Queue Agent

Install Distributed Queue Agent on Windows

1. Unzip QP_Qagent_win_<type>-<version>.zip.
2. Run <install_dir>/bin/win-install-service.bat as administrator.
3. Modify agent.conf.
4. Run the database scripts.
5. Start the service.
6. In System Administration, update the Statistics Settings: enable, set Host Address and Port.

Install Distributed Queue Agent on Linux

1. Create a qmatic user and Orchestra directory for the Queue Agent.
2. Unpack the QP_Qagent_linux<type>-<version>.tgz file.
3. Run database scripts.
4. Copy startup script and set appropriate rights.
5. Modify agent.conf.
6. Start Queue Agent.

Configure Queue Agent (agent.conf)

Configuration before using Personal Data Management

If using Orchestra with stat on a separate server, before using Personal Data Management:

1. In Orchestra, go to System Administration > Parameters > Statistics Settings.
2. Fill in the correct IP address or FQDN and port for your stat server.
3. Configure retention policy parameters.
4. Open stat.conf on the Stat server and set stat.personaldata.ip.filter to the Central Orchestra server IP or FQDN.

Gateway 1745

Gateway 1745 manages all Qmatic hardware at the Branch and communicates with the central/distributed Queue Agent. For installation instructions, refer to the Gateway 1745 Manual.

Redeploying Applications

1. In the Wildfly Admin console (http://localhost:9990, admin/ulan), undeploy the application in the Deployments tab.
2. Delete the applicable war-file from <install_dir>\deploy.
3. Copy the new war-file to <install_dir>\deploy.
4. Deploy the new version in the Wildfly admin console.

4. Upgrade

Introduction

Read the Upgrade Note sections and Release Notes before starting the upgrade process.

Possible Upgrade Path

Upgrade directly from Orchestra 5.4 to Orchestra 7.x is not supported. You must first upgrade to Orchestra 6.x, then to 7.x. You can upgrade to any minor version within the same major version.

Important Upgrade Notes

• Shiro Environment Class for Web Components: Web components deployed on Orchestra 7.1 or later must explicitly set a context parameter: shiroEnvironmentClass = com.qmatic.qp.core.aaa.shiro.QPIniWebEnvironment.
• Undeploying Jiql.war: If stuck when undeploying jiql.war, use Wildfly Admin console to En/Disable it first.
• Stat Aggregation Jobs Active: If upgrade gets stuck, wait until jobs are done and try again.
• Blocking Websocket Port: Block port 8787 during upgrade to prevent connected Queue Agents causing problems, then remove the block after upgrade.
• Language Files: Existing language files will be automatically backed up. Compare with installation package files after upgrade and update any changed strings.

Suggested Upgrade Order

1. Upgrade central and stat at the same time.
2. Upgrade distributed queue agents.
3. When upgrading QEP-based products, also upgrade the QEP firmware.
4. Upgrade unit types and widgets (either automatically during upgrade or manually afterwards).

Remote Upgrade Overview

To upgrade a distributed Queue Agent remotely:

1. Create a new agent profile zip file with the new Queue Agent version.
2. Create a new agent profile in Orchestra (System Administration > Queue Agents > Agent Profile).
3. Assign the profile to a Queue Agent (Prepare Profile).
4. Click Synchronize to start synchronization.
5. When synchronization is done, click Upgrade to deploy.
6. After remote upgrade, manually publish each branch on the Queue Agent.

Unit Types

To upgrade unit types manually:

1. In System Administration, select the Unit Types tab.
2. Click Add Unit Type and browse for new unit types in <Orchestra install dir>/conf/unittemplates/R7.
3. Click Upload.
4. Save and publish the Branch(es).

Widgets

To upgrade widgets manually:

1. In System Administration, select the Widgets tab.
2. Browse for new widget files in <Orchestra install dir>/conf/defaultwidgets/R7.
3. Click Upload.
4. Verify surfaces are correctly configured to use the new widget.
5. Save and publish the branch(es).

5. System Administration

Unit Types

Available Unit Types: Entry Points, Service Points, Presentation Points, Device Controllers. To add a new Unit Type, click Add Unit Type, select a template from the list or upload a .utt file.

Licensing

Activating a license

Two ways to activate:

• Online: Enter the License Key in the field and click Activate Online (internet access required; not available via Proxy).
• Offline: Enter the License Key, click Activate by File, download the generated file, upload to Qmatic World Licensing tab, download the licence file, then upload and activate in Orchestra. Must be completed within 14 days.

Licensed information displayed

After activation you can see: License State, Licensed Product, Expiry Date, License Key, Licensed Customer, Licensed packages, and Licensed Components (with License limit and Current usage).

Third-party hardware licensing

Software licenses are required for third-party hardware devices. License types: Kiosk, Display, Printer. The Edit branch page shows hardware license information. Hardware licenses for Qmatic-manufactured hardware are free.

Import and Export

An Orchestra system configuration can be saved to a zip file and imported into another system. The importing system must be newly installed with no configuration done.

Included in export: CJM Global configuration, Branches, System settings, General Parameters, Branch Hierarchy, AAA (Authentication, Authorisation, Audit), Context Marketing Messages, Touch screen applications, Playlists, Appointments (Central only), Unit Types and Unit Templates, Surface Applications, Queue Agents, Queue Agent profiles, stat-jobs.xml.

Note: Only import/export from and to the same version of Orchestra is supported. Only Appointments in Central are included. Statistics tables and data are not included. Import must be performed directly after installation, before any configuration is done.

Widget Administration

Web Widgets are small applications inserted on web pages for Touch Screens, Media Displays and Positional Displays. To upload a widget: click Choose File, browse for the .wgt file, click Upload, then map it to the applicable Surface Types. The Widget Whitelist defines URLs that Widgets are allowed to access.

Queue Agents

In the Queue Agents tab you can see: Name, Id, Host, Version, Profile, Status, Connection, and Latest activity for each Queue Agent.

Actions available per Queue Agent: Start, Stop, Reset Database, Reset Queue Agent, Reset Queue Agent Media, Prepare Profile, Force synchronization, Upgrade, and Retrieve/Download log files.

Agent Profiles

An agent profile consists of configuration parameters and a zipped file typically containing Counter, Reception, Concierge, and other applications. Pre-installed profiles at install/upgrade: default, hub, and hub_first_gen.

To create an agent profile: click Create Profile, enter a unique name, upload the zip file, enter a folder name, optionally override Global Parameter values, and save.

Parameters

Key parameter sections in System Administration > Settings > Parameters:

General Parameters

Central Access Parameters (HTTP Settings)

HTTPS Parameters

Central WebSocket Server Settings

Application Parameters (selected)

LDAP Settings (key parameters)

SAML v2 Web Single Sign On Settings (key parameters)

TrustStore Management

All truststore certificates are listed in System Administration > Settings > TrustStore Management. To upload a new certificate: enter an alias, click Choose file (valid formats: .cer, .crt, .pem, .der), click Upload. To delete a certificate, click the trash can icon.

Mark Types

Mark Types are used for Customer Feedback Units (CFU) and Service Outcomes. Default Mark Types: Outcome (cannot be deleted) and NPS (values 0–10 and skip). To create a new Mark Type: click Create Mark Type, enter a Name, optional Description, check Codes enabled and Visible in configuration as needed, and click Save.

6. Auditing

Introduction

Auditing tracks and stores information about who does what in the system.

What is logged?

Login/logout events: Successful login, unsuccessful login, logout (Central only).

Configuration changes: Branch publish, branch/service/work profile/segmentation/context marketing/unit type/surface/mark type/user management configuration (system activities triggered by Queue Agent are not logged).

Customer object: Create, Update and Delete events (actual Customer information is not stored due to GDPR; only username and timestamp are stored).

Queue Agent: Configuration changes (Agent Profile synchronization, Upgrade), starting and stopping a Queue Agent.

Calendar: Who booked/deleted/confirmed/updated the Appointment and at what time.

Where is it stored?

Central: Stored in the qp_auditing database, events table.

Calendar: Stored in the qp_calendar database, calendar_audit table. Entries with entity_type APPOINTMENT older than 365 days (default) are removed nightly at 03:30.

Enabling/disabling auditing

If Auditing is installed and licensed, it is enabled automatically. The qp_auditing database is created by default during a fresh installation. During upgrade, the database is NOT automatically created — enabling auditing requires running the appropriate database scripts and setting application.auditing = true in install.properties, then running the upgrade in silent mode.

7. Stat Aggregation

Introduction

Pentaho Data Integration (PDI) is used for creating jobs/transformations for data aggregation. The stat-jobs.xml file in <orchestra installation directory>/conf/stat-jobs is where events and jobs/transformations are configured.

Note: Do not install PDI on production servers — only for development of transformations. The qmatic folder contains internal Orchestra jobs that must NOT be altered. Custom jobs go in the custom folder.

Job configuration attributes:

• filename – path to the .ktr or .kjb file, relative to conf/stat-jobs/
• max-events-before-processing – how many events must pass before the job executes
• max-time-before-processing – maximum time to wait before triggering job execution (minutes)
• batch-limit – how many events the job should process in one execution

Failed events and jobs REST endpoints

• List failed events: GET <host:port>/stat/rest/events/listFailedEvents
• Process failed events: POST <host:port>/stat/rest/events/processFailedEvents
• List failed jobs: GET <host:port>/stat/rest/kettleJobs/failed
• Replay failed jobs: POST <host:port>/stat/rest/kettleJobs/replay

8. Localisation

Orchestra system GUI

Language files must use character encoding UTF-8. You need the 2-character language code (ISO 639-1) for the new language.

Central and Central Queue Agent

1. Copy all original files in <Orchestra central installation directory>\conf\lang and rename with _temp suffix.
2. Translate all strings.
3. Run native2ascii if necessary, renaming files to the language code (e.g. businessConfigMessages_fr.properties).
4. Add the language to the LANGUAGES table in the database (including left-to-right/right-to-left setting).
5. Place the new files in the language folder alongside the original files.
6. Restart Orchestra (or the queue agent if lang files changed there).

Distributed Queue Agent

Properties files for distributed Queue Agents are placed in the Queue Agent profile. Create a new Agent profile or update an existing one. During deploy, the Queue Agent is restarted.

9. Xtend

Introduction

Xtend is an application within Qmatic Orchestra where you can find extensions that add value to your solution (Counter, Concierge, Notification Admin, etc.). From Xtend, you can install and deploy extensions directly, or download and install manually. Xtend is installed with Qmatic Orchestra by default.

Requirements

Open firewall: Xtend needs to connect to https://xtend.qmatic.cloud. Open https traffic for this domain.

Configure proxy settings: If using a proxy, add proxy settings to standalone.conf.bat (Windows) or standalone.conf (Linux). Xtend needs the https settings: -Dhttps.proxyHost and -Dhttps.proxyPort.

10. Network Connectivity

Orchestra Bandwidth Requirements

For an Orchestra not using special integrations, Calendar, global variables, or media sync, the only data sent between central and distributed Queue Agent are stat messages and a keep-alive message every 30 seconds.

Stat messages for a Visit are less than 3 KB; Service Point sessions are less than 5 KB. Internal tests have been performed with bandwidth as poor as 250 kbit/s and 4% packet loss — profile and media synchronization still works, but higher bandwidth is recommended.

11. Secure Communication

Introduction

Qmatic highly recommends configuring Orchestra to use HTTPS/SSL/WSS for all communication.

• HTTPS: Secure version of HTTP where all communications are encrypted.
• SSL: Standard security protocol for establishing encrypted links between a web server and browser.
• WSS: WebSocket Secure — full-duplex communication channels over a single TCP connection.

Keystore vs Truststore

The truststore is used to verify credentials (stores certificates from trusted CAs). The keystore is used to provide credentials (stores private key and own identity certificates). Both files are located in <installation directory>/conf/security.

Note: TP3115, TP Touch and Intro 8 do not support encrypted communication. Those units need to use HTTP.

Enable HTTPS for Orchestra Central

Certificate Generated by Orchestra (1a – used as is)

1. In System Administration > Parameters > HTTPS Parameters, set: KeyStore alias, Distinguished name (CN = server hostname), Subject alternate name.
2. Set (Re)generate certificate to true and Save.
3. In HTTPS server settings, set HTTPS port (default 8443) and KeyStore alias, set HTTPS enabled to true, and Save.
4. Restart the Orchestra service.
5. Test: open https://<orchestra_ip>:8443.

Certificate Generated by Orchestra, sent to a CA Authority (1b)

1. In Keystore Explorer, open keystore.jks (password: changeit), right-click and select Generate CSR.
2. Send the CSR to your certificate authority.
3. Import the CA response certificates into the keystore (Import Trusted Certificate).
4. Enable HTTPS in Orchestra Parameters and restart.

Certificate from outside Orchestra signed by Public CA (2b)

1. In Keystore Explorer, select Import Key Pair (PKCS #12 format), enter alias orchestra.
2. Save the updated keystore.
3. Enable HTTPS in Orchestra Parameters, set the KeyStore alias to orchestra, and restart.

Secure communication between Central and distributed Queue Agent

To enable Websocket Secure (WSS) between Central and distributed Queue Agents:

1. Export Central certificate from keystore, import it into the agent profile truststore.
2. In agent.conf, set central.websocket.secure = true and central.websocket.secure.port to the desired port (default 9150).
3. In Orchestra Parameters, set Secure WebSocket enabled and Secure WebSocket port.
4. Prepare, synchronize, and upgrade the Agent Profile.
5. Save and restart Orchestra.

Secure Communication for a Queue Agent

Configuration of secure WebSocket and HTTPS for Queue Agents is handled centrally. Distributed Queue Agents have their own certificates stored and provisioned from the central server. Navigate to System Administration > Queue Agents > Agents, select the Queue Agent, and use the Security section to manage certificates and enable WebSocket Secure.

Disabling HTTP and Running HTTPS Only

HTTP cannot be strictly disabled. It can be set to listen only on localhost (127.0.0.1) so no external parties can use it. To do so, in the Wildfly configuration file standalone-full.xml, change the HTTP socket binding to add interface="unsecure":

<socket-binding name="http" interface="unsecure" port="${jboss.http.port:8080}"/>

Enable cookie secure flag

For the SSO Cookie: edit conf/shiro.ini and add cookie.secure = true in the [main] section, then restart Orchestra.

For the BAYEUX_BROWSER cookie: in System Administration > Parameters > Browser Settings, check "Secure cookie flag enabled", save, and restart.

Changing the password for keystore

1. Run: keytool -keystore keystore.jks -storepass changeit -storepasswd
2. Run: keytool -keystore keystore.jks -storepass <new storepass> -keypasswd -alias orchestra
3. Update the password in standalone-full.xml and standalone.conf / standalone.conf.bat.

12. SSO Setup

Introduction

Qmatic Orchestra supports Single Sign-On (SSO) using either Integrated Kerberos or SAML 2.0 Web SSO.

SSO Setup Using Integrated Kerberos

Client Area

Set the client browser to identify the Orchestra server as an intranet site. For Internet Explorer: Tools > Internet Options > Security > Local Intranet > Sites > Advanced, add the Orchestra server IP or hostname. For Firefox: set network.automatic-ntlm-auth.trusted-uris, network.negotiate-auth.delegation-uris, network.negotiate-auth.trusted-uris and signon.autologin.proxy = true.

Server Area

1. Register the Orchestra hostname in DNS as an A-record (not CNAME).
2. Create a user for Kerberos/SSO configuration with a pre-set, non-expiring password. Check "This account supports Kerberos AES 128 bit encryption".
3. Register the SPN: setspn -A HTTP/<hostname> <username>
4. Edit conf/krb5.conf: replace YOUR.DOMAIN (uppercase) with your domain, set kdc to your domain controller, and set domain_realm mapping.
5. In Orchestra System Administration > Parameters > SSO Settings, enable SSO and enter the Pre-authentication username and password.
6. Save and restart Orchestra.

SSO Setup Using SAML 2.0 Web SSO

SAML 2.0 Web SSO enables users defined in an external directory (IdP such as Entra ID or ADFS) to log in to Orchestra without configuring them beforehand. Prerequisites: HTTPS must be enabled; LDAP, SSO (Kerberos) and PreAuth must be disabled.

Three steps to configure: configure trust between Orchestra and the identity provider, assign different access rights, configure single logout. For detailed instructions see Appendix E.

13. HA Setup

Introduction

Supported HA configurations:

• Hot/Cold – both servers running but Orchestra service started on only one. Supported for all scenarios.
• Hot standby – Orchestra service started on both servers, all traffic directed to one. Only supported when all Queue Agents are distributed (no central branches).

Deployment architecture

HA setup requires: multiple application servers, shared storage and RDBMS between application servers, a Load Balancer that supports WebSocket communication, and a Hot/Cold configuration with failover.

Load balancer

The Load Balancer must be configured with Orchestra application servers in a hot/cold setup. It must support WebSocket protocol. Recommended HTTP headers to send to Orchestra: X-Forwarded-Proto: https (when offloading SSL), X-Forwarded-For, Proxy-IP.

Shared storage

Recommended directories to synchronize between application servers: /conf, /media, /custdeploy, /deploy/wookie.war/wservices. Use NAS with symbolic links, or DFS replication on Windows.

Deployment procedure

1. Open firewall ports 40010 and 40020.
2. Setup databases using scripts provided with Orchestra installation.
3. Install Orchestra on one application server.
4. Enable HA sections in ehcache-central.xml and ehcache-calendar.xml.
5. Test installation.
6. Adjust JMS bridge configuration.
7. Clone or install Orchestra on second server pointing to same databases (same path).
8. Install and configure Load Balancer.
9. Configure both Orchestra systems with the Load Balancer address.
10. Test failover.

Note: If Orchestra is deployed in a clustered environment, set org.quartz.jobStore.isClustered = true in the notificationQuartz.properties file.

14. Appendix A – Tuning Database Parameters

Tuning of Oracle Parameters

The most commonly tuned parameters are PROCESSES, SESSIONS (Oracle recommends PROCESSES × 1.1 + 5), and TRANSACTIONS (Oracle recommends SESSIONS × 1.1).

Example:

ALTER SYSTEM SET PROCESSES=1200 SCOPE=SPFILE;
ALTER SYSTEM SET TRANSACTIONS=1458 SCOPE=SPFILE;
ALTER SYSTEM SET SESSIONS=1325 SCOPE=SPFILE;

Also consider tuning MEMORY_TARGET, MEMORY_MAX_TARGET, and disabling adaptive log file sync: ALTER SYSTEM SET "_use_adaptive_log_file_sync"= false;

Cursor sharing: ALTER SYSTEM SET CURSOR_SHARING='SIMILAR' SCOPE=SPFILE;

Tuning of PostgreSQL Parameters

PostgreSQL is delivered with conservative baseline settings. Key parameters to adjust (based on 13 GB RAM, 1692 max connections, OLTP, SSD):

Connection counts per component: Central: 596, Calendar: 64, Statistics: 1000, Auditing: 32. Total (all components): 1692.

After modifying postgresql.conf, restart the PostgreSQL service. Verify with SHOW ALL;.

15. Appendix B – Logging

Enabling Customer Journey Management Logging

In <orchestra install dir>/conf/logback.xml, add a new cfmAppender file appender and replace the existing logger entry:

<logger name="com.qmatic.qp.jiql.core.cfm" level="DEBUG" additivity="false">
  <appender-ref ref="cfmAppender"/>
</logger>

Enabling Publish Logging

In <orchestra install dir>/conf/logback.xml, add a new publishAppender file appender and replace the existing logger entry:

<logger name="com.qmatic.qp.jiql.core.cm" level="DEBUG" additivity="false">
  <appender-ref ref="publishAppender"/>
</logger>

Save the file — changes take effect within a minute without restart.

16. Appendix C – Security

The following HTTP response headers are set by default in Orchestra:

Modifying HTTP Response Headers

Edit <Orchestra>/system/app/wildfly-x.y.z.Final/standalone/configuration/standalone-full.xml. Locate the <filters> section and modify the header-value attributes. Save and restart Orchestra to apply changes.

17. Appendix D – Open LDAP Setup

Introduction

This appendix describes how to install and configure an OpenLDAP server on an Ubuntu 14.04 server, including a phpLDAPadmin interface.

Install LDAP and Helper Utilities

sudo apt-get update
sudo apt-get install slapd ldap-utils

Reconfigure slapd

sudo dpkg-reconfigure slapd

Answer: Omit OpenLDAP server configuration? No. DNS domain name? your domain. Organization name? your organization. Administrator password? your password. Database backend? HDB. Remove database when slapd is purged? No. Move old database? Yes. Allow LDAPv2 protocol? No.

Install and Configure phpLDAPadmin

sudo apt-get install phpldapadmin

Edit /etc/phpldapadmin/config.php: set server host to your server IP, set base and bind_id to use your domain (e.g. dc=test,dc=com), set hide_template_warning = true.

Create SSL Certificate, Password File, and Secure Apache

sudo mkdir /etc/apache2/ssl
sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout /etc/apache2/ssl/apache.key -out /etc/apache2/ssl/apache.crt
sudo apt-get install apache2-utils
sudo htpasswd -c /etc/apache2/htpasswd demo_user
sudo a2enmod ssl
sudo a2ensite default-ssl.conf

Adding Nodes, Users, and Groups

# Add nodes
ldapadd -x -D cn=admin,dc=test,dc=com -W -f add_nodes.ldif

# Enable MemberOf
sudo ldapadd -Q -Y EXTERNAL -H ldapi:/// -f memberof_config.ldif

# Add user
ldapadd -x -D cn=admin,dc=test,dc=com -W -f add_user.ldif

# Add group
ldapadd -x -D cn=admin,dc=test,dc=com -W -f add_group.ldif

Troubleshooting

Orchestra fails to find users in OpenLDAP (MSSQL): Run: UPDATE [qp_central].[qp_central].[system_parameter] SET value = 'cn' WHERE parameter_definition_id = 'aaa.ldap.roleAttributeIdName'

Cannot enter LDAP server with hyphen in DNS name: Run: UPDATE qp_central.system_parameter_definitions SET validation '' WHERE id = 'aaa.ldap.urls'

18. Appendix E – Set up SAML

Introduction

This appendix contains detailed instructions for setting up SAML 2.0 Web SSO. Prerequisites: an identity provider (Entra ID, ADFS, etc.) must be ready; Orchestra (including distributed agents) must be configured for HTTPS.

Note: Orchestra SAML parameters are found in System Administration > Parameters > SAML v2 Web Single Sign On Settings. Make sure SAML is enabled there.

Configure trust between Orchestra and the identity provider

Configure Orchestra and Entra ID to trust each other

1. In Entra ID, select Entra ID > Enterprise Applications > New application (Non-gallery) > Single Sign On > SAML.
2. Set Identifier (Entity ID) — must match the Service Provider Entity ID in Orchestra System Administration > Parameters.
3. Set Reply URL: https://<host:port>/callback?client_name=SAML2Client for each Orchestra agent.
4. Handle Federation Metadata: either use Option A (delegate to Federation Metadata URL — set in Orchestra Parameters > Identity Provider Metadata URL) or Option B (download metadata XML, rename to saml-integration.xml, place in orchestra/system/conf).
5. Verify the SAML flow by creating a test user in Entra ID (no roles assigned) and attempting to log in to Orchestra — you should see "User has no applications".

Configure Orchestra and ADFS to trust each other

1. Use the "Add Relying Party Trust" wizard in AD FS Management.
2. Configure claim issuance rules (Surname, SAM-AccountName, Member-Of as Role, Given-Name).
3. In Orchestra, configure Service provider entity ID to match the callback URL, and handle Federation Metadata.

Assign users different access rights

Configure attribute identifiers

In Orchestra System Administration > Parameters > SAML v2 Web Single Sign On Settings, ensure all attribute identifiers match those in your identity provider. Default values are selected to match Entra ID.

Configure role and branch mapping

In Orchestra, go to User Management > LDAP/SAML. Click Create New Mapping. For each mapping, enter:

• Name – name of the role/group as spelled in the identity provider.
• Type – Role, Branch, or Branch Group.
• Mapping – the corresponding Orchestra role, branch, or branch group.

Click Save. Test by logging in with a test user that has roles assigned in the identity provider.

Configure single logout

1. In Entra ID, open the enterprise application > Set up single sign on and copy the Logout URL.
2. In Orchestra, go to System Administration > Settings > Parameters > Orchestrated Logout Settings and paste the URL into Logout URLs.
3. Save.

Troubleshooting

SAML flow not working

Enable debug logs in Orchestra by setting DEBUG level for SAML loggers in orchestra/system/conf/logback.xml (no restart required). Check for: audience mismatch (entity ID mismatch), missing/incorrect attribute values (inspect role attribute values in log), decryption errors (certificate exchange issue — ensure the public key from Orchestra HTTPS certificate is used, not the load balancer certificate).

Common error messages

• "User has no roles assigned" – Misspelling of role mapping name in User Management > LDAP/SAML.
• "User has no branches assigned" – Misspelling of branch mapping name in User Management > LDAP/SAML.
• "User has no applications" – Misspelling of role or branch mapping, or misspelling of Role attribute identifier in Parameters.
• AADSTS50105 error – Users not assigned to the enterprise application in Entra ID. Either assign users/groups explicitly or set User assignment required = false.
• SSLHandshakeException when fetching metadata URL – Import the root/CA certificate used by the identity provider into Orchestra's trust store.