Skip to main content

Qmatic Web Booking

Craig Weir
Updated
Qmatic Web Booking Manual

Qmatic Web Booking Manual

Document: 238.02N — 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 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, 2025. Please send feedback or questions to documentation@qmatic.com.

1. What’s New

Version Chapter Change
01.A General New manual for Qwebbook
01.B Configuration How restriction settings work; which changes require a restart of Orchestra central; adjusted links for preselection of services and branches
01.C Configuration New section about enforcing SSL communication
01.D / 01.E General New name Qmatic Web Booking
Installation + Configuration Instructions for how to install and configure service groups; new appendix with upgrade instructions
01.F Configuration New settings for prices; how to configure custom fields
01.G API Gateway Addition to application.yml for SMS verification to work
01.H General / Configuration References to Service Groups admin UI removed; how to configure custom flag; how to add service information using a service template
01.I Introduction / Configuration Added General Admin UI as a system requirement; how to modify branch address order; how to enable and configure the footer
01.J Configuration Setting to select QR code type; Back to start URL parameter; new search field: Booking Reference; new language properties for confirmation email when customer information is changed
01.L Configuration / Deployment Options Auto-select branch if only one available; show region before branch group; restrict URL to preselected branch/service; countdown timer settings; limit number of people per service
02.A All Configuration chapter divided into basic and advanced sections; section about allowing iFrame integration added
02.B Basic / Advanced Configuration Possibility to link to external privacy policy; Google Tag Manager Integration
02.C Basic Configuration Show service groups based on custom field values
02.D Advanced Configuration Section about running on HTTP
02.E Basic Configuration / Deployment Options for Branch/Service and General UI; updated iFrame integration instructions
02.G Deployment Options URLs for preselecting number of adults and children
02.H Advanced Configuration Updated custom properties section
02.I Installation & Upgrade Removed Calendar and Calendar Admin access modules from Qmatic Web Booking roles
02.J Introduction Added minimum system requirements; API Gateway changed from Optional to Mandatory
02.K Advanced Configuration Updated Google Tag Manager Integration section
02.L Advanced Configuration Information about Customizing the Content Security Policy (CSP)
02.M Basic / Advanced Configuration Added missing settings for General UI; new “Show Font Size Button” setting; instructions for disabling Google Fonts; Appendix B on bot mitigation strategies
02.N Advanced Configuration New parameter type (Checkbox) and new option for single-selection field in Custom Properties

2. Introduction

2.1 Overview

Qmatic Web Booking is an application for online appointment booking. This document describes how to install and configure Qmatic Web Booking and gives an overview of the deployment structure, explaining how to integrate it into an existing home page.

The full solution includes two components:

  • Qmatic Web Booking application
  • Qmatic Web Booking Admin

Qmatic Web Booking runs in a separate Tomcat web server for security and performance reasons (Orchestra should not be published directly on the Internet). It communicates with Orchestra using the public and private calendar REST API. Qmatic Web Booking is a pure HTML and JavaScript application that communicates with its backend using REST web service calls through AJAX. It is distributed as a package including a JDK and a Tomcat web server, pre-configured to support up to 300 branches with appointments.

2.2 Requirements

2.2.1 System Requirements

Recommended minimum system requirements:

  • 2 CPU (> 1.6 GHz)
  • 2 GB of RAM
  • 40 GB of disk space
  • Windows Server 64 bit operating system

2.2.2 Platform Requirements

The following prerequisites are required:

  • Orchestra 6.2 or later
  • Orchestra Calendar 6.2 or later
  • Required licenses (see Licensing documentation)
  • API Gateway (mandatory)

Optional: General Admin UI (needed for service groups and service templates).

2.2.3 Orchestra Configuration

The following must be configured in Orchestra for Qmatic Web Booking to work:

  • Branches and Branch groups (branch hierarchy)
  • Services, Resources, Resource Groups
  • Week Schedules and Appointment Profiles
  • Custom slot length must be enabled in Calendar Admin > System Settings > Enable custom slot length (required for multi-service support)

3. Installation & Upgrade

3.1 Required Software Files

The following software files are required:

  • QmaticWebBooking_x.x.x.zip
  • qmaticwebbookingadmin.war
  • sql_queries.zip
  • add_to_commonMessages.txt
  • qmaticWebBookingAdminMessages.properties (can be extracted from qmaticwebbookingadmin.war)

3.2 Installing Qmatic Web Booking Admin

See section 2.2 Requirements before you begin.

  1. Copy qmaticwebbookingadmin.war to <Orchestra_install_dir>\system\custdeploy.
  2. Add qmaticWebBookingAdminMessages.properties to <Orchestra_install_dir>\system\conf\lang.
  3. Add the content from add_to_commonMessages.txt to commonMessages.properties in <Orchestra_install_dir>\system\conf\lang.
  4. Execute update_central.sql (from the SQL zip file) to make required changes to the qp_central database.
  5. Restart Orchestra Central.
  6. In User Management > Roles, create a Qmatic Web Booking Admin role with access to the following modules:
    • System administration
    • Qmatic Web Booking Admin
    • Connector EntryPoint
    • Connector ServicePoint
  7. Create a user (or select an existing one) and assign it the Qmatic Web Booking Admin role. This user must have access to all branches.
  8. Log in to Orchestra with the Qmatic Web Booking Admin user to verify the Qmatic Web Booking Admin menu item appears on the start page.
  9. Before using Qmatic Web Booking, click all Save buttons in the admin interface.

3.3 Installing Qmatic Web Booking (Application)

Note: Uninstall any previous Qmatic Web Booking Windows service before beginning.
  1. Extract the Qmatic Web Booking zip file (e.g. QmaticWebBooking-1.0.0.zip) to a desired location. Recommended location: C:\Qmatic, creating a folder at C:\Qmatic\QmaticWebBooking (referred to as <Qmatic Web Booking home>).
  2. Install as a Windows service by running (as administrator): <Qmatic Web Booking home>\Bin\Install.bat. This creates a service named “QmaticWebBooking” with display name “Qmatic Web Booking”.
  3. In User Management > Roles, create a role for Qmatic Web Booking with access to:
    • Appointment
    • Connector Customer
    • Connector EntryPoint
    • System Administration
  4. Create a new user, assign it the role above, and ensure it has access to all branches. The username and password will be used in configuration.properties.
  5. Configure settings in configuration.properties and save. See section 4.1.
  6. Start the service. It is configured to start automatically on boot; this step is only needed immediately after installation. To uninstall the service: <Qmatic Web Booking home>\Bin\Uninstall.bat.
  7. Optionally, start as a console application using <Qmatic Web Booking home>\Bin\Run.bat (not recommended for production).
  8. By default, Qmatic Web Booking listens on port 8090. To change this, edit the port attribute on the <Connector> element in <Qmatic Web Booking home>\Tomcat\conf\server.xml.

3.4 Upgrading Qmatic Web Booking Admin

  1. Copy the new qmaticwebbookingadmin.war into the Orchestra Central custdeploy folder, replacing the old file.
  2. Empty the browser cache.
  3. Open the Qmatic Web Booking Admin application in Orchestra.
  4. Review all tabs and click Save in each one in case new settings have been added (previous settings are retained).

3.5 Upgrading Qmatic Web Booking (Application)

  1. Copy the conf folder from the current installation to a temporary location.
  2. Remove the directory <Qmatic Web Booking home> altogether.
  3. Extract the new zip file at the same location (e.g. C:\Qmatic).
  4. Copy the files you want to keep from the temporary conf folder into the new <Qmatic Web Booking home>\conf folder. Do not overwrite language files. Customized language files should be named e.g. uiMessages_custom_en.properties so they are not overwritten on upgrade.
  5. Check the release notes for any new properties in language files, and add them to your customized files as needed.

4. Basic Configuration

Note: All changes in Qmatic Web Booking Admin require a restart of the Qmatic Web Booking server. Changes to services or branches in Orchestra require a restart of Orchestra Central.

4.1 Initial Settings in Configuration File

Configure the API Gateway URL and authentication token in <Qmatic Web Booking home>\Conf\configuration.properties. Only connecting via the API Gateway is supported.

Setting Description
APIGatewayURL URL for the API Gateway, e.g. http://localhost:9090
AUTH-TOKEN Authentication token for the API Gateway

4.2 Branch and Service Settings

Go to Qmatic Web Booking Admin > Options > Branch/Service Options to configure:

  • Order of Steps — Select the order in which steps appear on the booking page. If showing service groups based on custom field values, Contact must be the first step.
  • Show the Branch step if only one branch available (first step only) — If checked and only one branch is selected, the select branch step will be shown. If unchecked, the branch is automatically selected without displaying the step.
  • Auto select the Branch if only one branch available (first step only) — When checked and only one branch is selected, the branch is automatically selected in the UI.
  • Show the Service step if only one service selected — Show or hide the Service dropdown when a service has been preselected via URL.
  • Enable BranchGroups (Regions) — Sort branches into branch groups (configured in Business Configuration).
  • Use full name for BranchGroups — If checked, the region name precedes the branch group name.
  • Show first available Appointment for Branches — Show the next available time for each branch in the branch selection step (only available if service is selected before branch).
  • Enable Service Groups — Enable service groups configured in General Admin UI.
  • Enable Multiple Services — Allow users to select more than one service.
  • Add the services multiple times if multiple people selected — Save the service for each person selected.
  • Only show these branches / services — Select specific branches or services to display. If not “All”, new branches/services must be added manually.

4.2.1 Show Service Groups Based on Custom Field Values

To show different service groups depending on a value entered in the Contact step (e.g. postcode → service group):

  1. In Branch/Service Options, select an Order of Steps where Contact is the first step.
  2. Create a custom field with the step set to Contact Step. (Fields used for service mappings cannot be restricted to certain services.)
  3. In the Custom Properties tab, under Mappings of Values to Service Groups, click Add to create a mapping. Only one custom parameter can be mapped at a time. Select the custom field and the default service group(s) to show when no mapping matches.
  4. Click Add under Value to add available values, then select service group(s) for each value.

4.3 General Booking Page Options

Go to Qmatic Web Booking Admin > Options > General UI to configure:

  • Restrict URL to preselected branch or service only — If checked, the URL must contain a valid preselection or an error page is shown.
  • Time Format — How to display time.
  • Min Length for QmaticWebBookingId — Minimum length, padded with leading zeros.
  • Show Additional Service Info on Result page — Show a JSON string field value as additional info on the booking confirmation page.
  • Show QR code on Result page — Show a QR code on the confirmation page. Optionally use Concierge booking ID instead of Qmatic Web Booking ID.
  • Show Booking Reference on Result page — Display the Booking Reference in the confirmation page.
  • Show Print Button on Result page — Show a print button in the confirmation page.
  • Show Find appointment on Start page — Show a selection page where users can create a new appointment or search for an existing one to remove or reschedule.
  • On Find appointment only return appointments for selected services — Limit the search to specific services.
  • Disable Cancellation of appointments — Prevent customers from cancelling appointments.
  • Show Notification Type Selection — Allow users to select notification type.
  • Show Footer — Show the page footer.
  • Show Countdown Popup — Show a countdown popup X seconds before the reservation expires. The booking can be extended once; after the timer expires the booking is cancelled.
  • Show Reservation Time Countdown — Show a countdown timer once a date and time have been selected (reservation expiry from Calendar Admin > System Settings).
  • Show Country Code for phone numbers — Show a field for the phone country code.
  • Default Country for phone — Default country code. Mandatory if Show Country Code is disabled.
  • Show Flag with Country Code — Display country flag next to the country code field (requires Show Country Code to be enabled).
  • Show current Month only in date selection — Restrict date selection to the current month only.
  • Include leading Zero for Phone number — Automatically add a leading zero to phone numbers that begin without one.
  • Enable Mobile Ticket arrival — Add a button to the reschedule/cancel link allowing customers to arrive via Mobile Ticket. Enter the base URL for the Mobile Ticket service.
  • Hide agreement — Do not display the checkbox for accepting Terms & Conditions and Privacy Policy.
  • Show Font Size Button — Show an “AA” icon in the header to toggle between standard and large font size.

4.3.1 Configure Footer

  1. Enable Show Footer in Qmatic Web Booking Admin UI > General UI.
  2. To replace the default Qmatic logo, go to Tomcat\webapps\qmaticwebbooking\img and replace the logo file (recommended similar size to the default: 158×45 px).
  3. To link to social media, add URLs in uiMessages_xx.properties, e.g.: 
    footerFacebookLink = https://www.facebook.com/MyCompanyPage
    Replace default social media icons by substituting files in the /img folder (same file names).
  4. Add up to 6 page links using properties: 
    footerLink1 = https://qmaticwebbooking.com/terms
footerLink1Label = Terms and Conditions
footerLink2 = https://qmaticwebbooking.com/privacypolicy
footerLink2Label = Privacy Policy
footerLink3 = https://qmaticwebbooking.com/accessibility
footerLink3Label = Accessibility

4.3.2 Personal Information Form

Go to Qmatic Web Booking Admin > Options > UI Fields to select which fields appear in the Contact details step, whether they are mandatory, and maximum character limits. Available fields: Appointment Reference, Customer Reference, Last Name, First Name, Date of Birth, Email, Confirm Email, Phone, Confirm Phone, Notes.

Note: Booking Reference can only be selected as a search field, not as an input field. If using Customer Reference, select it as the only match field.

Privacy policy options:

  • To embed terms/privacy text within the app, edit dialog1Text, dialog1Title, dialog2Text, dialog2Title, etc. in uiMessages_xx.properties.
  • To link to external pages, change the agreement properties to use <a href="URL"> tags instead of <link> tags. The linked pages will be shown in an iFrame within the dialog.

4.3.3 Validation of Email Address and Phone Number

Go to Qmatic Web Booking Admin > Options > Regular Expressions to configure regular expressions for phone numbers, email addresses, and customer references.

4.3.4 Match Customers

Go to Qmatic Web Booking Admin > Options > Customer to configure:

  • Match Customer — Search for matching customers, or create a new customer object every time.
  • Match fields — Fields used to find existing customer objects. Note: if email or phone is used as a match field, it cannot be changed during booking.

4.4 Booking Restrictions

4.4.1 Multiple Future Bookings

Go to Qmatic Web Booking Admin > Booking Restrictions > Multiple future bookings:

  • Set booking limits at Global, Branch, Service, and/or Time levels.
  • Restrictions are cumulative: e.g. 3 bookings per branch and 1 per service means a user can book up to 3 per branch but only 1 per service.
  • Set whether the check applies only to the same day.
  • Multiple Bookings Identified by — Email address, phone number, or both.

4.4.2 Reschedule Restrictions

Go to Qmatic Web Booking Admin > Booking Restrictions > Reschedule restrictions:

  • Reschedule is only allowed until X minutes before the original appointment time.
  • Cancellation is only allowed until X minutes before the original appointment time.
  • Max X reschedules/cancellations within the last X days.
  • When max reschedules is reached: either no further reschedule is allowed, or only bookings X days from now are allowed.
When using reschedule restrictions, update the corresponding error messages in uiMessages.properties to match your settings.

4.4.3 People Restrictions

Go to Qmatic Web Booking Admin > Booking Restrictions > People Restrictions:

  • Set whether multiple people can be booked and the maximum number of adults, children, and total people per booking.
  • Set per-service people limits.
  • Leave the field empty to impose no limit.

To treat all people as the same type (no adult/children distinction): set the Adults field to the max total, set Total to the same number, and update the labels in uiMessages_xx.properties (e.g. commonAdultText, commonAdultsText, chooseServiceContentAdults, infoMessageNumberOfAdultsReached).

To allow multiple people only for certain services:

  1. Check Hide multiple people if no additional service duration in Qmatic Web Booking Admin.
  2. In Calendar Admin > Services, set Additional service duration to 0 for services where multiple people selection should not appear.

4.5 Add Information to Services

To add descriptive information to a service (details, preparation instructions, etc.), create a service template in General Admin UI (an Orchestra package available from Provisioning Tool). Service template content is shown in:

  • The Select service step (via the info button).
  • The confirmation page.
  • The appointment reschedule confirmation.

To remove information from Qmatic Web Booking, remove the text from service templates in General Admin UI for each language.

Customizable text properties in uiMessages_xx.properties:

  • serviceTemplateHeader — Name of the information dialog box on service expansion panel.
  • confirmationTemplate — Section name for additional service information on the confirmation page.

5. Advanced Configuration

5.1 Colors and Logo

To change the color scheme, edit <Qmatic Web Booking home>\Tomcat\webapps\qmaticwebbooking\css\theme-style.css.

To change the logo, replace company_logo_header.png in <Qmatic Web Booking home>\Tomcat\webapps\qmaticwebbooking\img. Recommended size: 158×45 pixels.

5.1.1 Disabling Google Fonts

If your organization blocks Google domains or prefers locally hosted fonts:

  1. Open <Qmatic Web Booking home>\Tomcat\webapps\qmaticwebbooking\css\custom.css.
  2. Comment out the Google Fonts import line and uncomment the local fonts import: 
    /* @import url("https://fonts.googleapis.com/css2?family=Roboto:wght@100;300;400;500;700;900&display=swap"); */
@import url("localgooglefonts.css");
  3. Save the file and restart the Qmatic Web Booking service.
The localgooglefonts.css file must exist on the internal web server and reference locally hosted Roboto font files.

5.2 Logging Settings

Log settings are in <Qmatic Web Booking home>\Conf\log4j.properties. By default, up to 200 log files are created, each up to 20 MB. Main log file: <Qmatic Web Booking home>\Tomcat\logs\qmaticwebbooking.log.

Start with debug level logging until everything is stable, then reduce to info:

log4j.logger.com.qmatic.qmaticwebbooking=info

5.3 Security and HTTPS

5.3.1 Running on HTTP

Running on HTTP is not recommended. To fix the secure cookie issue on HTTP (when not using localhost), change secure to false in Tomcat\conf\web.xml:

<session-config>
  <session-timeout>30</session-timeout>
  <cookie-config>
    <secure>false</secure>
    <http-only>true</http-only>
    <same-site>strict</same-site>
  </cookie-config>
</session-config>

5.3.2 Activating HTTPS

Step 1: Import the certificate in Keystore

  1. Run Keystore Explorer and select Open an existing Keystore.
  2. Browse to <Qmatic Web Booking home>\Conf\security\keystore.jks.
  3. Enter the Keystore password (default: changeit) and click OK.
  4. In the menu bar, go to Tools > Import Key Pair.
  5. Select the key pair type (e.g. PKCS #12).
  6. Specify the certificate password, browse to the certificate file, and click Import.
  7. Enter an alias for the key pair.
  8. Enter the key pair password — this must match the Keystore password (default: changeit).
  9. Save the updated Keystore.

Step 2: Activate the HTTPS listener

  1. Open <install_dir>\qmatic\QmaticWebBooking\Tomcat\conf\server.xml in a text editor.
  2. Uncomment the HTTPS connector section (remove <!-- and --> on lines 99 and 103): 
    <Connector port="8445"
  protocol="org.apache.coyote.http11.Http11NioProtocol"
  maxThreads="150" SSLEnabled="true" scheme="https"
  secure="true" clientAuth="false" sslProtocol="TLS"
  keystoreFile="C:\qmatic\qmaticwebbooking\Conf\security\keystore.jks"
  keystorePass="changeit" keyAlias="orchestra"/>
  3. Change port 8445 to your desired port (e.g. 443).
  4. For a secure Orchestra or API Gateway:
    • In <install_dir>\qmatic\QmaticWebBooking\Bin\install.bat, line 9: remove rem to activate the truststore setting.
    • Uninstall existing services (uninstall.bat as administrator), then re-run install.bat as administrator.
  5. Access Qmatic Web Booking on HTTPS.

Force SSL Communication (optional)

  1. Open <install_dir>\qmatic\QmaticWebBooking\Tomcat\conf\web.xml.
  2. Add the following security constraint: 
    <security-constraint>
  <web-resource-collection>
    <web-resource-name>Protected Context</web-resource-name>
    <url-pattern>/*</url-pattern>
  </web-resource-collection>
  <user-data-constraint>
    <transport-guarantee>CONFIDENTIAL</transport-guarantee>
  </user-data-constraint>
</security-constraint>
  3. Save and restart the Qmatic Web Booking server.

5.3.3 Using ReCaptcha

Qmatic Web Booking supports invisible ReCaptcha v2. To configure:

  1. Create a Google account and go to https://www.google.com/recaptcha/admin to set up your secret. Use invisible ReCaptcha (v2).
  2. Copy the site key and secret key.
  3. Go to Qmatic Web Booking Admin > Security > ReCaptcha and enter both keys.
Even invisible ReCaptcha may prompt users to solve a captcha if traffic appears suspicious. Adjust site security preferences under Advanced settings in the Google reCaptcha admin.

5.3.4 Disable Use of QmaticWebBookingId in URL

Go to Qmatic Web Booking Admin > Security > URL and check the checkbox to hide the QmaticWebBookingId from the URL. A service public ID can be used instead.

5.3.5 Phone Number Confirmation

Go to Qmatic Web Booking Admin > Security > Mobile Number Confirmation:

  • Send confirmation code to phone number — Recommended. Sends a verification code via SMS.
  • Confirmation Code expires after X minutes — Set code expiry time.
  • Confirmation Code Number of Digits — Select number of digits in the code.

5.3.6 Google Tag Manager Integration

Go to Qmatic Web Booking Admin > Security > Google Tag Manager Integration, check Enable, and enter the container ID.

With the latest GA4 events, a URL like region1.google-analytics.com (region-dependent) must be added to allowed sources. If not using Google Tag Manager, remove www.googletagmanager.com from the scriptUrls parameter in WEB-INF\web.xml or via the Custom Content Security Policy admin UI.

GA4 events sent by Qmatic Web Booking (create matching Custom Events in Google Tag Manager):

  • Appointment Cancelled, Appointment confirmed, Appointment rescheduled
  • Branch Selected, Service Selected, Date Selected, Time Selected
  • Cancel Appointment Clicked, Confirm clicked, Reschedule clicked
  • Customer added, Search clicked, Search page entered, Reschedule page entered

5.3.7 Security Configuration Against Cross-Scripting

A content security policy filter is configured in Tomcat\conf\web.xml. To add additional allowed URLs, append them comma-separated to the allowedUrls parameter:

<init-param>
  <param-name>allowedUrls</param-name>
  <param-value>https://fonts.googleapis.com/,https://www.google.com/,
    www.gstatic.com,https://fonts.gstatic.com</param-value>
</init-param>

5.3.8 Customizing the Content Security Policy (CSP)

Go to Qmatic Web Booking Admin > Security > Custom Content Security Policy to manage CSP settings from the admin UI (an alternative to editing web.xml directly).

  1. Check Enable to activate custom CSP rules.
  2. For each directive (script-src, style-src, img-src, etc.), enter allowed values separated by a space. Default values are listed under each field — keep defaults and append custom values.
  3. Click Save to apply.

Example:

script-src: www.googletagmanager.com www.google-analytics.com 'self'
font-src: fonts.googleapis.com fonts.gstatic.com 'self' data:
These policies are enforced by the browser. If a required script or style is blocked, it may break parts of the application.

5.4 Prices

Go to Qmatic Web Booking Admin > Prices:

  • Enable Prices — Enable pricing functionality.
  • Show Prices — Display prices to users when booking.
  • Price calculation method:
    • Services Price — Prices calculated per selected service and number of people (adults and children). Prices defined in the price editor.
    • Conditional Price — Price calculated from global variable qw_conditional_prices in JSON format. Contact Professional Services for details.
  • Prices for services — Enter prices per service, with separate rates for adults and children. Currency name is set in uiMessages_xx.properties.

5.5 Custom Properties

Custom properties allow you to gather additional information about the customer or appointment by adding custom fields to the booking form.

5.5.1 Set Up Custom Properties

Go to Qmatic Web Booking Admin > Custom Properties > Add and configure:

  • Parameter Name — Saved to the appointment table, custom field in qp_calendar database.
  • Parameter Type:
    • Single selection — One option (dropdown or radio buttons via Display style setting).
    • Multiple selection — Multiple options.
    • Text field — Single-line free text.
    • Text area — Multi-line free text.
    • Checkbox — Checked or unchecked. Requires defining true and false values with labels. Can be used as a consent checkbox. If Mandatory is enabled, the user must check the box to proceed.
  • Save Parameter on — Appointment or customer object.
  • Show in step — Contact step or Confirmation step.
  • Active — Whether the field is visible.
  • Mandatory — User cannot proceed without completing this field.
  • Copy to notes — Copy the field name and value to the appointment notes field.
  • Show count — Show max length and character count (text fields and text areas only).
  • Labels — Field name shown to the user, translated to all supported languages. Add a “Custom field description” to explain the field’s purpose below it.
  • Values — Predefined options for Single selection, Multiple selection, or Checkbox types. Translate values by clicking Edit. Images can be uploaded for values.

After configuring, select the branches and services for which to show the field, then click Save.

5.5.2 Configure Custom Field Dependencies

Show fields conditionally based on the value selected in a previous single-selection field:

  1. In Custom Properties > Custom properties options, click Edit dependencies.
  2. Click Add.
  3. Select the source field (must be Single selection type).
  4. Select the conditional value(s) that trigger the dependent field.
  5. Select the field to display when the condition is met.
  6. Save.

5.6 Languages and Translation

5.6.1 Add Languages

Go to Qmatic Web Booking Admin > Languages to add languages. Each language requires a corresponding uiMessages.properties file. Configure the following per language:

  • Language code — ISO 639-1 code used for notifications, branch/service names, and the properties file.
  • Language name — Displayed in the language dropdown list.
  • Country code (Country) — ISO 3166-1 Alpha-2 code for default phone country code and flag.
  • Country code (Language) — ISO 3166-1 Alpha-2 code (lowercase) for the language flag and properties file lookup.
  • Custom Flag — Upload a custom flag image (jpg or png).
  • Date Format and Time Format — Use moment.js formatting. Default Time Format: HH:mm.

Example — Canadian English: language code en, language name Canadian English, Country Code (Country) ca, Country code (Language) ca, properties file named uiMessages_custom_en_ca.properties.

5.6.2 Translate Qmatic Web Booking Admin

All admin phrases are in qmaticWebBookingAdminMessages.properties. See the Localisation chapter in the Orchestra Reference manual.

5.6.3 Translate Qmatic Web Booking Application

Default language files: <Qmatic Web Booking home>\Conf\uiMessages_en.properties. Default files available for English (en), French (fr), Swedish (sv), Dutch (nl), and German (de).

To customize, copy the original file and name it uiMessages_custom_en.properties (or equivalent). Custom files will not be overwritten on upgrade. Qmatic Web Booking reads custom files first; if a property is missing, it falls back to the original.

Set the direction property to ltr or rtl in each properties file. Restart the Qmatic Web Booking service after changes.

Key configurable properties:

  • contactDetailsContentAgreementText1 / contactDetailsContentAgreementText2 — Agreement checkbox text. Use <link></link> tags for dialog links, or <a href="..."> for external pages.
  • verificationMessage — SMS message for phone verification. Use %1 for the PIN code. Default: This is your verification code: %1.
  • emailChangeSubject / emailChangeMessage — Confirmation email when customer email changes during booking.
  • branchFullAddress, branchShortAddress, branchSelected — Branch address display format.
  • branchSeparator — Comma or line break between address components.

6. Deployment Options

6.1 Deployment Scenarios

Scenario 1 — Separate servers: The existing homepage and Qmatic Web Booking run on different servers, both on port 80.

  • Homepage: http://www.myhomepageserver.com
  • Qmatic Web Booking: http://www.myqmaticwebbookingserver.com/qmaticwebbooking/index.html#/

Scenario 2 — Same server, different port: Qmatic Web Booking is deployed on the same server as the existing homepage but listens on a different port (e.g. 8080).

  • Homepage: http://www.myhomepageserver.com
  • Qmatic Web Booking: http://www.myhomepageserver.com:8080/qmaticwebbooking/index.html#/

6.2 Allow Integration with iFrame

To allow Qmatic Web Booking to run inside an iFrame on your website:

  1. In <install_dir>\Tomcat\webapps\qmaticwebbooking\WEB-INF\web.xml, add the hosting server as an allowed frameAncestor: 
    <init-param>
  <param-name>frameAncestors</param-name>
  <param-value>http://yourServer:yourPort</param-value>
</init-param>
    If using HTTPS, the parent website must also be on HTTPS.
  2. To allow cross-site cookies, set sameSiteCookies="none" in <install_dir>\Tomcat\webapps\qmaticwebbooking\META-INF\context.xml: 
    <Context>
  <CookieProcessor sameSiteCookies="none"/>
</Context>
Note: Qmatic Web Booking does not support Safari when used in an iFrame. This affects all iOS devices, as other browsers on iOS also use Safari’s WebKit engine.

6.3 Preselect Branches and Services

Use the following URL patterns to preselect branches and services. Replace {variables} with actual IDs (found in Calendar Admin in Orchestra).

Preselection URL Pattern
One service http://host:8090/qmaticwebbooking/#/preselect/services/{servicePublicId}
Multiple services .../#/preselect/services/{id1},{id2}
One branch .../#/preselect/branch/{branchPublicId}
Branch + service .../#/preselect/branch/{branchPublicId}/services/{servicePublicId}
One service group .../#/preselect/servicegroups/{serviceGroupId}
Multiple service groups .../#/preselect/servicegroups/{id1},{id2}
Branch + service group .../#/preselect/branch/{branchPublicId}/servicegroups/{serviceGroupId}

Preselect number of people:

  • Adults only: append ?adult=x
  • Adults and children: append ?adult=x&children=y (children cannot be used alone)
  • Example: .../#/preselect/services/{servicePublicId}?adult=2&children=1
  • Multiple services: use comma-separated values: ?adult=x1,x2&children=y1,y2

To hide the branch/service selection step when using preselection, disable Show the Branch/Service drop-down list in the UI if only one branch/service selected in Qmatic Web Booking Admin.

6.4 Preselection of a Language

Append a lang parameter to the URL to force a specific language:

http://host:8090/qmaticwebbooking/#/?lang=en_gb

Where en is the language code and gb is the country code. If the value doesn’t match a configured language, the default language is used. Language preselection can be combined with branch/service preselection.

6.5 Passing in an Encrypted Customer

To pre-populate customer details, pass an AES-encrypted JSON customer object in the URL:

  1. Go to Qmatic Web Booking Admin > Security > Security settings for passing in customer details and click Create secure Encryption key.
  2. Use the key to encrypt the customer object in JavaScript (using CryptoJS): 
    var customer = { firstName: "Test", lastName: "Customer",
  phone: "123456", email: "test.customer@gmail.com",
  dob: "2000-01-01", custref: "MyCustomerReference" };
customer.created = Date.now();
var value = JSON.stringify(customer);
var SECRET_KEY = "<your-generated-key>";
var SALT_KEY = "QMATIC"; // Always use "QMATIC"
var key256Bits = CryptoJS.PBKDF2(SECRET_KEY, SALT_KEY,
  { iterations: 65536, keySize: 256/32, hasher: CryptoJS.algo.SHA256.create() });
var encrypted = CryptoJS.AES.encrypt(value, key256Bits,
  { mode: CryptoJS.mode.ECB }).toString(CryptoJS.format.Hex);
  3. Redirect to Qmatic Web Booking with the encrypted customer: 
    location.href = "http://localhost:8090/qmaticwebbooking?customer=" + encrypted;

6.6 Changing Appointments with Email Links

Confirmation and reminder emails contain links to cancel or reschedule. For best user experience, the existing homepage should accept a URL with the appointment ID and load Qmatic Web Booking in an iFrame with the correct URL.

  • New appointment URL: http://host/qmaticwebbooking/index.html#/
  • Cancel/reschedule URL: http://host/qmaticwebbooking/index.html#/{appointmentId}

The appointment ID is typically a 64-character alphanumeric string. If the ID passed is shorter than 64 characters, Qmatic Web Booking treats it as a booking reference and searches by that number.

Example homepage URL: http://www.myhomepageserver.com/appointments/changeAppointment?appointmentId=xxx

6.7 Using the API Gateway

Configure the API Gateway according to its manual, then enter the authentication token in configuration.properties under AUTH_TOKEN and set useAPIGateway=true.

The API Gateway role requires access to System Administration to display all branch groups.

6.7.1 Needed Modification of application.yml

This is only required if using API Gateway version earlier than 1.4.8.0.

Under routes: in application.yml, add:

branchgroups_api:
  path: /rest/config/branchGroups/**
  url: ${orchestra.central.url}/qsystem/rest/config/branchGroups

sms_api:
  path: /rest/notification/**
  url: ${orchestra.central.url}/notification/

7. End-User UI Walk-Through

The following describes a typical Qmatic Web Booking use case. Functionality and appearance may vary depending on configuration.

  1. Landing page — The first page displayed when the user navigates to Qmatic Web Booking.
  2. Select a language — If multiple languages are configured, the user selects their language. If only one language is defined, the dropdown is not shown.
  3. Select a branch — Branches are shown, optionally sorted into branch groups/regions.
  4. Select a service — Services are listed. If prices and multiple people are enabled, clicking a service expands it with options. Total cost is updated on each change. A warning is shown if more people than allowed are selected.
  5. Select a date and time — The current date is selected by default. Unavailable dates are greyed out. A notification appears if no timeslots are available on a selected date.
  6. Enter contact details — Fill in personal information. The country code is populated automatically based on the selected language and can be changed manually. If mobile verification is enabled, the user clicks Send code to receive a verification SMS, then enters the code to verify. Verified fields are then locked.
  7. Create appointment — Press Create appointment to finalise the reservation. Mandatory fields are validated before submission.
  8. Booking confirmation — A confirmation page is displayed with booking details.
  9. Confirmation email — The email contains a link to reschedule or cancel. Following the link loads the page in the language stored in the appointment. Rescheduling shows a new date/time selection. Cancellation requires confirmation.
  10. If the customer’s email or phone is changed during booking, a confirmation email is sent to the old address.

8. Troubleshooting

Problem Solution
Qmatic Web Booking server isn’t starting Run Run.bat in Qmatic Web Booking\Bin to see startup errors in the Command Prompt. Old log files are in Qmatic Web Booking\Tomcat\logs. Do not close the Command Prompt window while troubleshooting.
Command Prompt log doesn’t display errors Enable debug logging (see section 5.2) and restart the server.
400 error — Bad Request Check API Gateway configuration. Verify that AUTH-TOKEN and APIGatewayURL are correct in configuration.properties. Try setting useAPIGateway=false temporarily to test without the gateway.
500 error — Internal Server Error The Qmatic Web Booking server is likely down.
No data displayed (only loading bar) The request to the server is pending or has not yet failed. If a request fails, Qmatic Web Booking will always display an error.
Changes in uiMessages properties not reflected Restart the Qmatic Web Booking service. A restart is required after any property file change.
Changes in Qmatic Web Booking Admin not reflected Restart the Qmatic Web Booking server. All Admin changes require a restart.
New branches or services not displayed If not showing “All”, add the new branch/service in Qmatic Web Booking Admin, then restart Qmatic Web Booking.
No verification code sent to phone If no errors in the Qmatic Web Booking log, check qp_server.log (in qmatic\orchestra\system\logs) for Notification Admin SMS issues.
Create appointment button shows loading spinner and nothing happens Likely a reCaptcha issue. Check that the site key and secret key are correct in Qmatic Web Booking Admin. Verify the reCaptcha icon appears in the browser’s bottom-right corner.
reCaptcha icon displays an error The domain configured in https://www.google.com/recaptcha/admin does not match the Qmatic Web Booking server’s domain.

Appendix A — Upgrade from 1.3.x to 1.4.x or Later

1. Remove Qwebbook Admin

  1. Log in to Wildfly.
  2. Remove the qwebbookadmin.war file.

2. Remove Access Module from Orchestra

  1. Note users with the Qwebbook Admin Role and roles with the Qwebbook Admin Access Module using these SQL queries on qp_central: 
    -- Find users with Qwebbook admin roles:
SELECT * FROM users WHERE id IN (
  SELECT user_id FROM users_roles WHERE role_id IN (
    SELECT role_id FROM role_modules WHERE module_id = 'qwebbookadmin'));

-- Find roles with Qwebbook Admin Access Module:
SELECT name FROM sys_roles WHERE id IN (
  SELECT role_id FROM role_modules WHERE module_id = 'qwebbookadmin');
  2. Remove the module mapping: 
    DELETE FROM qp_central.role_modules WHERE module_id = 'qwebbookadmin';
  3. Remove the Qwebbook Admin application: 
    DELETE FROM qp_central.application_modules WHERE id = 'qwebbookadmin';
DELETE FROM qp_central.applications WHERE id = 'qwebbookadmin';

3. Install Qmatic Web Booking Admin

  1. Insert the new application module (PostgreSQL example): 
    INSERT INTO applications
  (id,branch_app,is_distributed,enabled,icon_url,url,version,view_index)
  VALUES('qmaticwebbookingadmin',true,false,1,
  'images/icons/application.png','qmaticwebbookingadmin',1,110);

INSERT INTO application_modules
  (id,is_distributed,enabled,icon_url,privilege_level,url,view_index,application_id)
  VALUES('qmaticwebbookingadmin',1,1,NULL,20,NULL,110,'qmaticwebbookingadmin');

COMMIT;
  2. Restart Orchestra.
  3. Copy qmaticwebbookingadmin.war to \qmatic\orchestra\system\custdeploy.
  4. In commonMessages.properties and commonMessages_en.properties (in \qmatic\orchestra\system\conf\lang), replace: 
    application.qwebbookadmin = QWebBook Admin
    with: 
    application.qmaticwebbookingadmin = Qmatic Web Booking Admin
application.qmaticwebbookingadmin.description = Administration for Qmatic Web Booking
module.qmaticwebbookingadmin = Qmatic Web Booking Admin
  5. Empty the browser cache.
  6. Add the access module to the required roles, and assign those roles to the required users.

Appendix B — Bot Mitigation Strategies for On-Premises Installations

Automated bot traffic can generate unwanted requests against Qmatic Web Booking. Apply multiple layers of defense at the application and network level.

Booking Restrictions

Limit the number of appointments per customer. Even when multiple bookings across services or branches are allowed, enforce a reasonable upper limit (e.g. 10 bookings). See section 4.4.

reCAPTCHA Integration

Enable Google reCAPTCHA to block most automated submissions. This significantly reduces automated appointment creation though it cannot completely eliminate bot traffic. See section 5.3.3.

Rate Limiting

Configure rate limiting on the network layer using a reverse proxy or API gateway (NGINX, HAProxy, Envoy, F5). This prevents brute-force, enumeration, and scraping attacks.

Web Application Firewall (WAF)

Deploy a WAF to filter and block known malicious IPs and abnormal request patterns. Can be implemented as an on-premises appliance or cloud service (AWS WAF, Azure Front Door, load balancer with built-in WAF).

Geo-Fencing

Restrict access to your booking application by region. Blocking traffic from countries not relevant to your operations reduces exposure to automated traffic and targeted attacks.

IP Reputation Lists

Integrate IP reputation feeds (e.g. Spamhaus DROP/EDROP, AbuseIPDB, FireHOL) into your network firewall or proxy to automatically block known bad actors.

CDN with Bot Mitigation

Consider a CDN with built-in bot mitigation features such as Cloudflare, Akamai, or AWS CloudFront with AWS Shield. These services identify and filter malicious traffic using device fingerprinting, behavioral analysis, and machine learning.

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