Skip to main content

Mobile Ticket

Craig Weir
Updated
Mobile Ticket Deployment Guide

Mobile Ticket Deployment Guide

Document: 224.06B — Qmatic

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 cannot assume any responsibility for any errors and their consequences. This manual is copyrighted and all rights are reserved. Reproduction is not allowed without written permission from Q-MATIC AB.

COPYRIGHT © Q-MATIC AB, 2025. Feedback and questions: documentation@qmatic.com.

1. What’s New

Version Chapter Change
05.A Installation and configuration; Upgrade Branding moved to new chapter; changes to Additional data parameter; new Upgrade chapter
05.B Branding More customization options added
05.C Installation and configuration Security and HTTPS configuration parameter added
05.D Installation and configuration Enable visit delay re-added
05.E Installation and configuration Branch selection URL and Mobile Ticket URL added to Enable additional data
05.F Installation and configuration first_name and last_name parameters added
05.G Installation and configuration Reschedule link and dynamic URL added
05.I Installation and configuration Language picker added
05.J Installation and configuration Configuration option to enable message box with link to form or website added
05.K Installation and configuration; Requirements and preparation URL with external ID as appointment check-in URL; custom fields below ticket; QR code for visit identification; queue poll retry attempts; accessibility statement option. Removed references to Teams as sole communication platform.
05.L Installation and Configuration Information about display language added in Localisation section
06.A General; Configuration Updated manual to new template; restructured chapters; added section about estimated waiting time configuration
06.B Configuration Settings for polling intervals and retry attempts added

2. Introduction

2.1 Overview

With the Mobile Ticket application, customers can get in line for a service from their mobile device via a web page/web application, using a direct URL or QR code. They can wait to be called wherever they want, monitoring their position in line on their device.

Main Features

  • Seamless entry with QR codes and URLs
  • Possibility for customers to enter personal data such as phone number
  • Can be combined with SMS notifications and Customer Feedback
  • Check-in for appointments
  • Can be linked to Google Analytics
  • Support for multi-language and RTL
  • Branding for colors and logo
  • One-time password and other security features that prevent misuse and hacker attacks
  • Integrations with communication platforms for remote serving
  • Estimated waiting time

2.2 System Requirements

  • Orchestra 7.0 update 12 or later. Some features may require a specific module version.
  • Notification Admin 4.0.0.49 or later to allow customers to add a phone number to the visit.
  • Counter and Qmatic Web Booking for remote service delivery.
  • General Admin application if service groups are enabled.
  • General Admin 1.6.1 for translations of service and branch names.
  • HTTPS required for location detection (listing branches based on user position).
  • Orchestra build 4.4.0.290 required for branches to be greyed out when no services are available (Service Scheduler).

2.3 Architecture

Mobile Ticket runs as a node.js web server that communicates with Orchestra via API Gateway. The customer accesses Mobile Ticket via a browser on their mobile device using a URL or QR code. Mobile Ticket communicates with API Gateway, which in turn communicates with Orchestra Central.

2.4 Limitations

  • When mobile user credentials are needed, the Superadmin user cannot be used.
  • Multi-service visits cannot be created in Mobile Ticket. However, a multi-service visit can be created in a kiosk or Qmatic Web Booking and then tracked in Mobile Ticket.
  • When using distributed operations and Mobile Ticket, stable connectivity to Central is required.

2.5 Browsers and Cookies

Supported Browsers

Mobile Ticket is tested and supported on: Safari, Chrome, Opera, Firefox (PC), Edge (PC). Users on unsupported browsers will be notified.

Cookies

By default, Mobile Ticket uses local storage rather than cookies. If Google Analytics is enabled, cookie consent may need to be enabled to comply with GDPR or similar regulations.

2.6 Software Deliverables

See README.md for full details. Key contents of the Mobile Ticket package:

File / Folder Sub-folder Description
sslcert Contains create_cert.sh script and the certificate Global.cer. Place your SSL certificate here (referenced in proxy-config.json).
node_modules iconv-lite, http-proxy, express, express-http-proxy, raw-body, unpipe Parsers, proxy libraries, and dependencies.
proxy-config.json API Gateway host address, local webserver port, and other proxy settings. See section 5.1.2.
server.js Main script file to start the solution.
src/app config config.json — branch radius, version number, and all configuration settings. See section 6.
locale Contains en.json (default). Place translated language files here.
resources Graphical resources (fonts, images, buttons), and notification.mp3 sound file.
src/zip bundle.min.css.gz, bundle.min.js.gz, favicon.ico, index.html.

3. Requirements and Preparations

3.1 Orchestra Preparations

  1. In System Administration > Unit Types, add the VisitApp unit type.
  2. In System Administration > Settings > Parameters, configure mobile user credentials in the Mobile API (Central) section. Note the password for later use in configuration.
    The default mobile user password is ulan. It is strongly recommended to change this.
  3. On the Parameters page, enter the Mobile Ticket Base URL if using SMS and email notifications. This URL is used as a variable in Notification Admin for sending personal links to Mobile Ticket or appointment check-in.
  4. In User Management, create a user called mobile with the same credentials as configured in System Administration. Required if using appointment check-in, open hours per service, or the one-time password feature.
    • From Orchestra 7.4 update 3: assign the pre-configured role Mobile User, which includes all required access modules.
    • For Orchestra 7.4 update 2 and earlier, assign a role with the following access modules: Service point connector, Entry point connector, Appointment connector.
    Ensure the mobile user has access to all branches.
  5. In Business Configuration > Operation Profiles, add the VisitApp unit type to the required equipment profiles.
  6. In Business Configuration > Services / Branches, enable the Mobile enabled setting for all services and branches that should be visible in Mobile Ticket.
  7. Enter the branch position (latitude and longitude) and address for all branches.
  8. Save and publish the required branches after making changes in Business Configuration.

3.2 URLs for Notifications and QR Codes

URLs can be used to launch Mobile Ticket, create visits for a specific branch and service, or provide appointment check-in. They can be sent via SMS/email or turned into QR codes for paper tickets or signs.

Ensure the Mobile Ticket Base URL is configured in System Administration parameters.

Use Case URL Format
Launch Mobile Ticket start page https://<mobile_ticket_server>:<port>/ticket
Create visit with predefined branch and service https://<mobile_ticket_server>:<port>/branches/{branchId}/services/{serviceId}
Show service list for predefined branch https://<mobile_ticket_server>:<port>/branches/{branchId}
Show service list for predefined branch and service group https://<mobile_ticket_server>:<port>/branches/{branchId}/{serviceGroupId}
Appointment check-in (public ID) https://<mobile_ticket_server>/appointment?appId={{appointmentPublicId}}
Appointment check-in (external ID, for Qmatic Experience Cloud) https://<mobile_ticket_server>/appointment?external={{externalId}}

QR Codes

To place a QR code on paper tickets:

  1. In the Surface Editor application, create a new ticket layout.
  2. Drag and drop the barcode component onto the surface.
  3. As barcode type, select QR Code.
  4. In the System information drop-down, select Mobile Ticket URL.

Notifications

Notification Admin 4.0.0.49 or later is required for phone numbers added from the Mobile Ticket UI. Use cases include:

  • Visit create — Send a link to open a specific ticket using the {{mobileFullURL}} parameter.
  • Visit update — Add a phone number to an existing visit and send SMS with the Mobile Ticket link (requires Orchestra 7.1 or later).
  • Appointment confirmation / reminder — Send a check-in link using the appointmentPublicId parameter.

4. Installation — API Gateway

4.1 Install API Gateway

Open port 9090 in the firewall on the machine where API Gateway is installed. Install API Gateway version 1.3.2.0 or later. Installation files and the API Gateway Manual are available in Xtend.

4.2 Configure API Gateway for Mobile Ticket

  1. In application.yml, update the url to point to your Orchestra server.
  2. Generate an API token by running api-token-generator.bat (located in the bin folder of QP_APIGateway_win64-<number>.zip).
  3. Enter the generated API token for the mobile user in application.yml.
  4. Create an encrypted password for the mobile user by running password-encoder.bat, using the password entered in the Orchestra preparations.
  5. Enter the encoded password for the mobile user in application.yml.

5. Installation and Upgrade

5.1 Install Mobile Ticket

Step 1: Install node.js

Download and install node.js from http://www.nodejs.org. Select the LTS version.

Step 2: Configure the Proxy/Webserver

  1. In the Mobile Ticket folder, open proxy-config.json.
  2. Configure the following settings:
    • apigw_ip_port — API Gateway host address (IP and port).
    • local_webserver_port — Local webserver port.
    • auth-token — Mobile API User authentication token. Do not use Superadmin.
    • embed_iFrame — Set to true to allow iFrame embedding (blocked by default to prevent clickjacking).

Step 3: Install Mobile Ticket

  1. Navigate to the upgrade-helper folder inside the source folder: 
    cd <installation_path>\mobile-ticket-1.9.2\upgrade-helper
  2. Run npm install to install all dependencies (one-time execution).
  3. Execute the install command (replace paths accordingly):

    Windows:

    gulp install --src <installation_path>\mobile-ticket-1.10.0 --dest <installation_path>\mobile-ticket-1.9.2

    Linux:

    gulp install --src <installation_path>/mobile-ticket-1.10.0 --dest <installation_path>/mobile-ticket-1.9.2
    All content in the destination folder will be replaced.
  4. Open a browser and navigate to the configured IP and port (e.g. http://localhost:81) to verify Mobile Ticket is working.
The application needs internet access on first start-up to fetch dependencies.

5.2 Enable HTTPS / SSL

5.2.1 Export Certificate and Private Key from Keystore

Mobile Ticket uses X.509 certificate format. Use a tool such as Keystore Explorer to manage keystores and certificates.

Export X.509 certificate from a p12 keystore:

  1. Open the keystore file in Keystore Explorer.
  2. Right-click and select Export Certificate Chain.
  3. Select X.509 in the popup, keep PEM checked.
  4. Name the file server.crt and click Export.
  5. Copy server.crt to the sslcert folder in your Mobile Ticket installation.

Export private key from a p12 keystore:

  1. Open the keystore in Keystore Explorer, right-click and select Export Private Key.
  2. Select OpenSSL and click OK.
  3. Deselect the Encrypt option, keep PEM checked.
  4. Name the file server.key and click Export.
  5. Copy server.key to the sslcert folder in your Mobile Ticket installation.

5.2.2 Configure HTTPS for API Gateway

In application.yml, uncomment the following parameters in the server section:

server:
  port: 9090
  ssl:
    key-store: classpath:keystore.jks
    key-store-password: secret
    key-password: password

5.2.3 Configure HTTPS for node.js / Mobile Ticket

In proxy-config.json, configure the following SSL/HTTPS parameters:

  • local_webserver_ssl_port — Local webserver HTTPS port.
  • support_ssl — Set to true to enable SSL (requires valid server.crt and server.key in the sslcert folder).
  • gateway_has_certificate — Set to true if API Gateway is configured for HTTPS.
  • gateway_certificate_is_valid — Set to true for a valid SSL certificate; set to false for a self-signed certificate. Only active when gateway_has_certificate is true.
  • tls_ — Only configure if using a TLS version other than the latest; otherwise leave empty.
  • cipher_set — Cipher set to use, e.g. ['ECDHE-RSA-AES128-SHA256', 'DHE-RSA-AES128-SHA256', 'AES128-GCM-SHA256']. Leave empty to use defaults.
  • hsts_expire_time — HSTS (HTTP Strict-Transport-Security) expiry time.
  • allow_origin — Whitelist of allowed origins, e.g. ['https://www.origin1.com', 'https://www.origin2.com']. Leave empty to allow only the same origin.

5.3 Install Mobile Ticket as a Service

Windows

  1. After verifying that Mobile Ticket works (npm start), exit the command prompt.
  2. Go to <mobileticket_installation_directory>/bin and run install-mt-service.bat (as administrator). This creates a Windows service named “Qmatic Mobile Ticket”.

To uninstall: run uninstall-mt-service.bat.

Linux — CentOS 7

  1. After verifying that Mobile Ticket works, exit the command prompt.
  2. Install pm2: sudo npm install -g pm2
  3. Start Mobile Ticket with pm2: 
    pm2 start /<mobileticket_installation_directory>/server.js --name="mobile-ticket"
  4. Run pm2 startup
  5. Install: npm install -g pm2 && pm2 update

Verify: pm2 list. To uninstall: pm2 delete "mobile-ticket".

5.4 Database Configuration

Some features (one-time password, replay attack prevention) require a MongoDB database. Options: on-premise, cloud-hosted (e.g. AWS), MongoDB Atlas, or Docker container.

5.4.1 Configure Database Settings

  1. Go to <mobileticket>/mt-service/src/config and open config.json.
  2. Set db_connection_string to a valid MongoDB connection URL: 
    mongodb://YourUsername:YourPassword@host:port/YourDatabaseName[?options]
  3. For shared database deployments (multiple Mobile Ticket instances), set a unique tenant_id (e.g. "b14f3c08" or "client-0001").

5.4.2 Set Up MongoDB on Docker

  1. Pull the MongoDB image: docker pull mongo:latest
  2. Copy the docker compose file and DB script to a directory.
  3. Run: docker-compose up -d

5.4.3 Connection Strings

  • Root user: mongodb://root:adminhe11@127.0.0.1:27017/mt?authSource=admin
  • DB user: mongodb://mobileticket:nsavip@127.0.0.1:27017/mt?authSource=mt

5.5 Upgrade Mobile Ticket

Use the upgrade helper to upgrade without losing current configuration data.

Upgrade is not supported when upgrading from a version with old branding to a version with new branding settings. Also, any configuration and customization must be reapplied manually if installing a fresh version.
  1. Navigate to the upgrade-helper folder in the new source: 
    cd <installation_path>\mobile-ticket-1.10.0\upgrade-helper
  2. Run npm install (one-time execution).
  3. Execute the upgrade command:

    Windows:

    gulp upgrade --src <installation_path>\mobile-ticket-1.10.0 --dest <installation_path>\mobile-ticket-1.9.2

    Linux:

    gulp upgrade --src <installation_path>/mobile-ticket-1.10.0 --dest <installation_path>/mobile-ticket-1.9.2

The following files and folders are preserved (compared and updated with new items only):

  • ./proxy-config.json
  • ./mt-service/src/config/config.json
  • ./src/app/config/config.json
  • /src/app/locale/en.json
  • /src/app/resources

6. Configuration

Most settings are in config.json, located in MobileTicket\src\app\config. Changes take effect immediately — no restart is needed.

6.1 Change Which Information Is Displayed

6.1.1 Show Queue Position / Appointment Time

In config.json, configure:

  • show_queue_position — Show or hide queue position above the ticket.
  • show_appointment_time — Show or hide appointment time for appointment visits.

Logic for which is shown (both cannot be shown simultaneously):

  • Both enabled + drop-in visit → Queue position shown.
  • Both enabled + appointment → Appointment time shown.
  • Only queue position enabled + drop-in → Queue position shown.
  • Only queue position enabled + appointment → Queue position shown.
  • Only appointment time enabled + appointment → Appointment time shown.
  • Only appointment time enabled + drop-in → Nothing shown.
  • Neither enabled → Nothing shown.

6.1.2 Show or Hide Number of Waiting Customers

In config.json, set show_number_of_waiting_customers to show or hide the number of waiting customers in the service list.

6.1.3 Show Estimated Waiting Time

Estimated waiting time is calculated per individual customer based on: number of open service points, work profiles of logged-in users, estimated service duration, and number of people waiting. It displays as 0 until a counter opens.

Prerequisites:

  • Customer Journey Management premium license.
  • In Business Configuration > Services, all Mobile Ticket services must have a serving time set.
  • Queue Simulation application installed with unit type added to the required operation profiles (available in Xtend).
  • API Gateway version 1.5.4.0 or later.

Step 1 — Enable in config.json:

  • show_waiting_time_ticket — Show estimated waiting time above the ticket card. Also changes queue position to simulation-based.
  • show_waiting_time_service — Show estimated waiting time in the service list.

Step 2 (optional) — Change settings:

  • refresh_interval — How often (in seconds) estimated waiting time is updated. Default: 5 seconds.
  • information_alert — Show a popup when estimated waiting time changes significantly. Default: enabled.
  • alert_time_difference_threshold — Minutes of change that trigger the alert. Default: 5 minutes.

6.1.4 Show Accessibility Statement

In config.json, set the wcag_statement value to enabled to allow customers to view the accessibility statement.

6.1.5 Show Custom Field

In config.json, set display_custom_field value to the name of the custom field (e.g. custom3) to display it below the ticket number. Leave empty to hide.

6.2 Change Functional Settings

6.2.1 Enable Service Groups

Service groups must be configured in the General Admin extension first.

  1. In config.json, locate service_group and set the availability value to enable.
  2. Use single_selection to control whether the user can expand one service group at a time (enable) or all of them (disable).

6.2.2 Link to External Web Page or Form

A pop-up box can be shown in Mobile Ticket linking to an external web page or form.

  1. In config.json, set dynamic_url to the target URL. Use {{branchId}} and {{visitId}} placeholders to pass contextual values: 
    "dynamic_url": { "value": "http://www.yourdomain.com/form/{{branchId}}/{{visitId}}" }
  2. Edit the pop-up text in the language file (e.g. en.json).

6.2.3 Prevent Taking a New Ticket

In config.json, set create_new_ticket to disable to hide the Get new ticket button and block access to branch and service pages via URL.

6.2.4 Enable Visit Delay

Allows customers to get in line remotely, estimate an arrival time, and be called at their estimated arrival time. A countdown timer is shown; the customer can extend the arrival time further.

This feature does not work for Orchestra builds 4.3.0.93, 4.3.0.161, or 4.3.0.163.
  1. In config.json, locate delay_visit and set availability to enable.
  2. Define available time slots in minutes as a comma-separated list in the time_slot parameter.

6.2.5 Manage Geofencing Settings

In config.json, configure:

  • geo_fencing — enable, disable, or mandatory. Requires HTTPS. When mandatory, users must share location to continue.
  • branch_radius — Radius in meters to include branches on the Branch Selection page.
  • appointment_arrive_radius — Radius in meters for geofence enforcement during appointment check-in.

6.2.6 Redirect to Customer Feedback

In config.json, set customer_feedback to the Customer Feedback URL: https://cf.qmatic.cloud/xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxx/index.html

6.2.7 Show QR Code

In config.json, set show_QR to enable to allow customers to display a QR code containing their ticket number. The QR code can be scanned in Concierge.

6.3 Change Appointment Settings

6.3.1 Enable Rescheduling Link

To link customers from Mobile Ticket to the Qmatic Web Booking rescheduling page:

  1. In config.json, locate reschedule_link.
  2. Enter the Qmatic Web Booking URL, e.g.: 
    "reschedule_link": { "value": "http://localhost:8090/qmaticwebbooking/" }
    The Reschedule/Cancel button will appear below the Arrive button. Leave empty to hide the button.

6.3.2 Configure Appointment Check-In

  1. Ensure the mobile user in User Management has access to all branches and is assigned to a role with the Appointment and Connector Entrypoint access modules.
  2. In config.json, configure:
    • appointment_late — Minutes a customer is allowed to arrive late.
    • appointment_early — Minutes a customer is allowed to arrive early.
    • appointment_time_API — Enable to get the current time at the appointment timezone (uses https://timeapi.io/).
    • timeFormat — Time format for the check-in page.
    • dateFormat — Date format for the check-in page.

6.4 Allow Personal Information

Ensure Orchestra preparations are complete (section 3.1). Configure in config.json:

  • phone_number — enable, mandatory, or disable.
  • first_name — enable, mandatory, or disable.
  • last_name — enable, mandatory, or disable.
  • customer_id — Enable to allow entering a customer ID or token. Saved to custom field 2 (can be shown in Counter).
  • privacy_policy — Enable or disable showing the privacy policy. If enabled, either link to an external policy via privacy_policy_link or leave the link empty and edit the text in the translation file (en.json). Inline CSS can be used.
  • active_consent — Require customers to actively agree to the privacy policy.
  • country_code — Country code to prepopulate the phone number field. Use ISO alpha-2 or international phone number format.
  • preferred_country_list — Comma-separated ISO alpha-2 country codes to show at the top of the country code dropdown.
  • additional_data — Enable by setting a comma-separated string of up to two values matching URL query parameters. Values are saved to custom fields 3 and 4 respectively. Example URL: 
    http://<baseURL>:81/branches/[branchId]/services/[serviceId]?value1=xxx&value2=yyy

6.5 Configure Open Hours

Open hours can be configured in two mutually exclusive ways:

Option 1: Open Hours Per Service (Service Scheduler)

  1. Install Service Scheduler (available in Xtend).
  2. Ensure the mobile user has access to all branches and the Connector ServicePoint access module.
  3. In config.json, set branch_schedule to enable. When enabled, all values from branch_open_hours are ignored. Branches with no open services will be greyed out.

Option 2: Open Hours for All Branches (config.json)

Configure opening hours in branch_open_hours in config.json. Use open_hours.week_day1 etc. for actual opening hours, and display_from / display_to to control when Mobile Ticket shows as open (e.g. allow ticket-taking 10 minutes before doors open).

  • If a day’s time values are left empty, “Closed” is displayed (text can be changed in the language file).
  • To appear closed at 14:00, set close time to 13:59.
  • All branches and devices must be in the same time zone.
  • If a user has the branch or service page open when close time is reached, they can still create visits.

6.6 Localize Mobile Ticket

Mobile Ticket supports multiple languages simultaneously, including RTL. Language selection logic:

  1. If opened from an appointment link with a language parameter, that language is used.
  2. If recently used in the same browser, the previous language is used. Otherwise, the default browser language is used.
  3. The user can also select from the language picker (if enabled).

If no matching language file exists, Mobile Ticket displays in English (default). The en.json file must never be removed.

The language used when a visit is created is saved and passes through the customer journey, and can be used for queue segmentation and to inform Counter staff of the customer’s language.

6.6.1 Translate Mobile Ticket UI

  1. Copy en.json from MobileTicket\src\app\locale to the same folder.
  2. Rename the copy to your language code (e.g. fr.json).
  3. Translate all phrases. Validate the JSON format using a JSON validator. Missing phrases fall back to en.json.
After changing the locale in Chrome, restart your computer for settings to apply properly.

6.6.2 Enable Language Picker

In config.json, set language_picker to enable. Available languages are determined by language files in the locale folder.

6.6.3 Translate Service and Branch Names

Requires General Admin. In config.json, set service_translation to enable. In application.yml for API Gateway, add under routes::

translations:
  path: /MobileTicket/translations/*
  url: ${orchestra.central.url}/calendar-backend/api/v1

Translate all service and branch names in General Admin.

6.6.4 Configure Unit of Distance

In config.json, set system_of_units to metrics, imperial, or auto (auto uses browser locale).

6.7 Manage Notification Sound

  1. Add your sound file to MobileTicket\src\app\resources (default: notification.mp3).
  2. In config.json, set notification_sound to the new file name.

6.8 Enable Google Analytics

  1. In config.json, set ga_track_id to your Google Measurement ID.
  2. To enable active cookie consent, set cookie_consent to enable. A popup is displayed until the user accepts or declines.
  3. To change the cookies information page, edit locale/cookie-consent-files/cookie-<LANG>.html. The browser picks the language file based on browser language.

6.9 Configure Security Settings

6.9.1 Prevent Opening in Another Device

In config.json, set block_other_browsers to enable to prevent a mobile ticket from being opened on a different device than the one it was created on.

6.9.2 Use One-Time Passwords

Sends a PIN to users before they can create a mobile ticket (phone number → PIN sent → user enters PIN).

Prerequisites: Database must be configured (section 5.4). The mobile user must have the Notification Service access module.

  1. In application.yml, add the SMS API mapping: 
    sms_api:
  path: /rest/notification/**
  url: ${orchestra.central.url}/notification/
  2. In src/app/config/config.json, set otp_service to enable.
  3. Restart the server: npm start.

6.9.3 Prevent Replay Attacks

Prerequisites: Database must be configured (section 5.4).

In config.json, set create_ticket_token to enable, then restart the server with npm start.

6.10 Manage Polling and Retry Settings

Configure the following in config.json:

6.10.1 Service Fetch Interval

service_fetch_interval — Interval at which service information is refreshed. Default: 15 seconds. Only used if “Show number of waiting customers” is enabled.

6.10.2 Screen Timeout for Service Page

service_screen_timeout — How long the app stays on the services screen without creating a ticket (minutes). Default: 10 minutes.

6.10.3 Queue Poll Settings

  • queue_poll_retry — Number of times the queue poll request is retried. Default: 2.
  • queue_retry_timeout — Timeout in seconds for queue poll retry when communication fails. Default: 4.

6.10.4 Polling Intervals for Ticket Status

"ticket_status_poll": {
  "value": {
    "over_five": { "value": "5" },   // interval (seconds) if position is 5 or beyond
    "under_five": { "value": "1" }   // interval (seconds) if position is 4 or closer
  }
}

6.10.5 Branch and Service Request Retries

Set set_retry_limit to enable and configure:

  • retry_limit — Maximum number of retries for an API request. Default: 10.
  • retry_interval — Interval in seconds between retries. Default: 5.

7. Branding

7.1 Introduction

Mobile Ticket can be adapted to match your brand guidelines by including your own logo and color scheme. Colors and logo are configured in theme-styles.css.

7.2 Accessibility Guidelines

We strongly recommend that color combinations pass the WCAG Level AA contrast requirements. The contrast ratio between text color and background color must be greater than 4.5. White or black text colors are recommended. Use online tools to evaluate contrast. If colors do not pass contrast requirements, the provided accessibility statement is no longer valid.

7.3 Color Reference

Element Name CSS Property Description
Header brand logo background color brand-logo-background Background color of the logo in the header.
Application background color app-bg-primary-color Background color of the application. Ensure good contrast with other UI components.
Primary background color primary-bg-color Background for inactive (unselected) services, branches, delay time, appointment arrival, and ticket in the waiting page. Default: light blue.
Primary text color primary-text-color Text for inactive services, branches, delay time, appointment arrival, ticket in waiting page. Use a light color with dark backgrounds and vice versa.
Secondary background color secondary-bg-color Background for active (selected) services, branches, delay time, and ticket in calling page. Default: blue.
Secondary text color secondary-text-color Text for active (selected) services, branches, delay time, and ticket in calling page.
Service group text color service-group-text-color Text color of displayed service groups.
Service group line color service-group-line-color Color of the line separating service groups.
General text color general-text-color Text color throughout the application not specific to any component.
Footer text color footer-text-color Color of text near the footer logo.
Popup button text color pop-up-button-text-color Text color of the consent button in privacy and cookie popups.
Get in line button background color get-in-line-btn-bg-color Background color of the “Get in line” button.
Get in line button text color get-in-line-btn-bg-text-color Text color of the “Get in line” button.
Leave button text color leave-button-text-color Text color of the “Leave the line” button.
Secondary button text color secondary-btn-text-color Text color of secondary buttons such as “Estimate arrival time”, “Send information”, and “Skip this”.

7.4 Customize Colors

  1. Open mobile-ticket-<version>/src/app/theme/theme-styles.css.
  2. Change the CSS properties to your color scheme.
  3. Save the file. Changes are applied immediately.

7.5 Customize Logo

Recommended logo size: 1000 px wide or 500 px high (whichever is greater). No padding around the logo. Ensure the logo renders sharply on high-resolution smartphone displays.

7.5.1 Set a Top Logo

  1. Place the logo image in mobile-ticket-<version>/src/app/resources.
  2. In src/app/theme/theme-styles.css, enter the logo filename in the brand-logo property.

7.5.2 Customize the Footer

By default, the footer shows “Powered by Qmatic” with the Qmatic logo. Customize in config.json:

  • logo — Enable or disable the brand logo in the footer (requires a configured brand logo).
  • custom_text — Set a plain text company name to appear after “Powered by” instead of an image logo (“Powered by” text can be edited in the language file). Note: if both logo and custom_text are set, the logo takes precedence.

8. Troubleshooting

8.1 Troubleshooting Guide

Use a tool such as Advanced REST client or Postman to perform REST calls during troubleshooting.

  1. Verify connection to Orchestra Central (port 8080) — Replace serviceId and branchId with valid IDs. Use Basic Authorization with the mobile user credentials. 
    /qsystem/mobile/rest/v2/services/serviceId/branches/branchId/ticket/issue
    If successful, Orchestra is configured correctly. If it fails, check Orchestra configuration.
  2. Verify connection through API Gateway — Replace [serviceId] and [branchId] with valid IDs and use your auth-token. 
    /MobileTicket/services/[serviceId]/branches/[branchId]/ticket/issue
    If it fails, check API Gateway configuration (section 4.2).
  3. Start the node.js server: 
    npm start
  4. Verify the web UI: Go to https://<your-ip-address>:4443 in a browser.

8.2 Frequently Asked Questions

Question Answer
Why are my branches not available in the branch selection list? In Orchestra, ensure the Mobile enabled checkbox is checked for all branches you want listed.
Why are my services not available in the service selection list? In Orchestra, ensure the Mobile enabled checkbox is checked for all services you want listed.
Why can I not create a mobile ticket? In Orchestra, ensure the VisitApp unit type is installed. Also verify that API Gateway is configured correctly.
Why is my connection to Orchestra/API Gateway not working properly? Ensure port 9090 is open in your firewall (section 4.1.1). Verify that API Gateway is configured correctly.

9. Walk-Through

9.1 Use Cases

  • Customer takes a paper ticket with a QR code at a branch. Information directs them to scan the code. They scan it and follow the queue on their phone.
  • Customer sees a URL/QR code in the branch or online, scans it, takes a ticket, and monitors the queue on their device.
  • Customer enters their phone number at a kiosk or gives it to a receptionist. When the visit is created, a notification is sent with a link to their ticket in Mobile Ticket.
  • Customer books an appointment and receives a reminder with an appointment check-in link to track their ticket.

9.2 End-User Walk-Through

This describes a typical flow when a user opens Mobile Ticket via URL or QR code with no services or branches preselected.

9.2.1 Selecting a Language and Location

The user can select a language by clicking the More icon (available throughout Mobile Ticket) and can access the accessibility statement from this menu. The user then selects a branch from the location list. Branches within the defined radius are shown, sorted by distance. Branches without a defined position are sorted alphabetically. If only one branch is in range, it is auto-selected.

Location detection requires HTTPS. If positioning is off, all branches are listed alphabetically.

9.2.2 Cookies

If active cookie consent is enabled, a popup is shown until the user accepts or declines.

9.2.3 Selecting a Service

Services are listed alphabetically and can be sorted into service groups. Estimated waiting time (if enabled) and the number of waiting customers are shown per service. If only one service is available, it is auto-selected, but the user still clicks Get in line to generate a ticket. If one-time password is enabled, the user is prompted to enter their phone number for a PIN.

9.2.4 Alternative Entry — Appointment Check-In

If the user opens a check-in link, they can check in for an appointment, after which the normal visit flow continues.

9.2.5 Add Phone Number

If the phone number feature is enabled, the user is prompted before the ticket is shown. If the privacy policy is enabled, the user must agree to it before adding their phone number.

9.2.6 Waiting to Be Called

The ticket number is displayed and the user can monitor their queue position or appointment time. They can leave the line at any time (redirected to a Thank You page). If a visit is transferred, the new service name is shown. If recycled, the message “You will be called shortly” is displayed.

9.2.7 Called to a Counter

When called, the ticket number flashes and a sound plays (desktop browsers only, first call only). The user is shown which service point and staff member to go to. If remote service is used, a button to open the virtual meeting is shown. An SMS notification can also be configured.

9.2.8 When the Visit Is Over

Depending on configuration, one of the following occurs:

  • A Thank You page is displayed. If enabled, the user can take a new ticket with Get new ticket (not available if opened via a URL).
  • The user is redirected to a Customer Feedback survey.

9.2.9 Landscape Mode

Portrait mode is recommended for demo purposes, but landscape mode is also supported.

Q-MATIC AB, Box 198, SE-431 23 Mölndal, Sweden. Phone: +46 31 756 46 00. Email: info@qmatic.com. Web: www.qmatic.com