Skip to main content

Unit Types Developer's Tutorial

Overview​

In Orchestra, hardware devices and software clients that belong to a single Unit are grouped into Unit Types. For example, for an Intro 17 Generation 2, you will in Orchestra add one Intro 17 Generation 2 Unit Type to the system and configure all devices that the Unit Type consists of in the instance of that Unit Type.

Full Documentation

The complete Unit Types Developer's Tutorial with all XML examples and detailed configurations is available as a downloadable reference document.

History​

In previous Qmatic systems, each hardware device was added and configured separately and then linked to other devices, creating a cumbersome task for administrators to set up and manage the system. The Unit Type concept was introduced to simplify this process.

Key Benefits​

Shorter Time to Delivery​

The overarching goal with the Unit Type feature has been to shorten the time between a customer request until Qmatic could deliver a solution.

Flexibility​

The separation of the Queue logic from the communication to devices and the possibility to "plug in" functionality in the form of commonly known standards like XML and Groovy scripts makes the feature extremely flexible. Because of this flexibility, it is possible to add new hardware and software devices much faster than before and without the need of a new release of the software.

User Friendly​

Orchestra is built to be more user friendly than previous systems when it comes to configuration. Unit Types separate and hide the complexity of scripting and core functionality from the GUI interface.

Configuration Hierarchy​

The configuration model is designed as a tree structure hierarchy:

  • Template Library: Unit Types are stored as zip files with the suffix .utt
  • Global Level: Configuration affects all Equipment Profiles and all Branches
  • Profile Level: Configuration affects only Units on Branches connected to the Equipment Profile
  • Branch Level: Configuration affects only the Unit on the Branch

Unit Type Categories​

There are 5 categories of Unit Types:

  1. Entry Points - Kiosks, ticket dispensers
  2. Service Points - Workstations, counters
  3. Presentation Points - Displays, signage
  4. Device Controllers - Hardware controllers
  5. Custom Unit Templates - Custom implementations

Communication​

Unit Types use WebSocket Secure (WSS) for real-time bidirectional communication with the Queue Agent (QA).

Creating a Unit Type​

A Unit Type package (.utt file) contains:

  • unit.xml - Main configuration file
  • messages.properties - Localization strings
  • scripts/ - Groovy scripts for business logic
  • resources/ - Images, icons, and other assets

Basic Unit XML Structure​

<?xml version="1.0" encoding="UTF-8"?>
<unit xmlns="http://www.qmatic.com/orchestra/utt/1.0"
      name="MyCustomUnit"
      version="1.0.0"
      category="ENTRY_POINT">
    
    <parameters>
        <!-- Configuration parameters -->
    </parameters>
    
    <scripts>
        <!-- Groovy script references -->
    </scripts>
    
    <devices>
        <!-- Hardware device definitions -->
    </devices>
    
</unit>

Parameter Types​

Unit Types support various parameter types:

TypeDescription
StringText input
IntegerWhole number input
BooleanTrue/false toggle
OptionsDropdown selection
PasswordMasked text input
MultiLineTextMulti-line text area

Example Parameter​

<parameter type="Options"
           name="startDay"
           defaultValue="1"
           isMultiSelect="false"
           label="First day of week">
    <options>
        <option label="Monday">1</option>
        <option label="Tuesday">2</option>
        <option label="Wednesday">3</option>
        <option label="Thursday">4</option>
        <option label="Friday">5</option>
        <option label="Saturday">6</option>
        <option label="Sunday">7</option>
    </options>
</parameter>

Scripting with Groovy​

Unit Types use Groovy scripts to implement business logic. Scripts can:

  • Handle device events
  • Process visitor data
  • Communicate with external systems
  • Control device behavior

Script Context​

Scripts have access to:

  • unit - The current unit instance
  • branch - The current branch
  • visitor - The current visitor object
  • parameters - Configuration parameters
  • logger - Logging interface

Example Script​

// Handle ticket print event
def onPrintTicket(visitor) {
    def ticketNumber = visitor.ticketNumber
    def serviceName = visitor.serviceName
    
    logger.info("Printing ticket ${ticketNumber} for ${serviceName}")
    
    // Send to printer device
    unit.getDevice("printer").print(ticketNumber, serviceName)
}

Device Integration​

Unit Types can integrate with various hardware devices:

  • Printers - Ticket and receipt printers
  • Displays - LED and LCD displays
  • Card Readers - NFC, magnetic stripe, barcode
  • Audio - Voice announcements
  • Sensors - Motion, presence detection

Deployment​

To deploy a Unit Type:

  1. Package your files into a .utt ZIP archive
  2. Upload to the Unit Type Template Library in Orchestra
  3. Configure at Global, Profile, or Branch level
  4. Assign to Units in the Branch configuration

Further Reading​