--- layout: page weight: 190 title: Unit Types Developer's Tutorial seo: title: Unit Types Developer's Tutorial description: When your email has been blocked by an ISP or your IP is on a blacklist. keywords: blocks, bounces, hard bounces, blacklists, ISP Blocks, Mail provider blocks navigation: show: true --- ### 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. As an example, to set up a Vision in the previous system, you had to add a TP Printer device, a Touch Screen device, a Card Reader device and optionally a Voice Unit device to the system. Then, you configured all devices in different places and linked them together. The configuration staff also often needed knowledge, not only of the basics of Customer Journey Management and the system itself, but of Qmatic's own scripting language. Qmatic's scripting language has been very powerful, but it had its limitations which have had a negative effect on the flexibility. Porting a solution from one customer's system to another customer's system has also been a cumbersome task to do, when all configuration and scripts that define how devices function have been spread out in one and the same configuration file together with Customer Journey Management logic. Adding new hardware products has not been possible without Qmatic also releasing a new version of the software that could support the hardware. The time between a request from the customer, of a new or customized hardware, until Qmatic could deliver has been very long. ## 1. General knowledge ### The Unit Type concept **The concept**

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 Intro 17 Generation 2 Unit Type consists of in the instance of that Unit Type. One important note to make is that a device can be a software application, like for example a Web based workstation. It is therefore possible to have a Unit Type that consists of all devices needed for each workstation. A LED counter display can be combined with a software workstation and a customer feedback unit. **Key Benefits** **Shorter time to delivery** There are several benefits with the Unit Type concept compared with previous systems, but the overarching goal with the feature has been to shorten the time between a customer request until Qmatic could deliver a solution to it. **Flexibility** The separation of the Queue logic from the communication to devices and the possibility to "plug in" functionality in a form of commonly known standard 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. This means that even if Qmatic release new hardware, it could be added to an existing system, even without an upgrade of the software.

**User Friendly** Orchestra is built to be more user friendly than previous systems, when it comes to configuration of a system. A Qmatic salesman or a customer should not need to be familiar with the core functionality, device communication or any scripting language to be able to set up a system. Unit Types separate and hide the complexity of scripting and core functionality from the GUI interface. ### Configuration hierarchy For an enterprise system, it is crucial to have the possibility to manage configuration of hundreds or thousands of Branches, including all software and hardware devices, in a fast, structured, and controlled way. The configuration model is therefore designed as a tree structure hierarchy, where Branches are grouped into profiles with different configuration. Configuration can be made on Global, Profile, and Branch level but one parameter can only be set on one of the levels. I.e. Configuration cannot be overridden on a lower level in the hierarchy. You decide on which level the parameter should be writeable when you develop the unit type and it is important when designing a Unit Type that configuration of a parameter is placed on the most effective level. For example, an IP address parameter is unique for each printer on each Branch and that configuration should be placed on Branch level. A parameter that has one value for half of all Branches and another for the rest is most effectively placed on a Profile level, because then the configuration only has to be done for two profiles instead of for each Branch. A parameter that is the same for many Profiles could be placed on Global level. **Template library**

The Unit Types are stored as zip files with the suffix .utt. To be able to use a Unit Type at all in a system, you first must add it to the database. This is done by uploading it to the Unit Type Template library. There are no configurations to be made on a Unit Type in the library. **Global Level** Configuration made on a Unit Type on a global level will affect all Equipment Profiles on profile level and all Branches connected to these Profiles. **Profile** Configuration made on a Unit Type in an Equipment Profile will affect only the Units on the Branches connected to the Equipment Profile **Branch** Configuration made on Branch level will only affect the Unit on the Branch ### Unit Type Categories There are 5 categories of Unit Types. These are mainly used to make it easier to get a better overview of the Unit Types, in the configuration GUI. A Unit Type can only belong to one category and it is specified in the XML file of the Unit Type. - Entry Points - Service Points - Presentation Points - Device Controllers - Custom Unit Templates ### Communication A simple communications diagram. Devices connect to a distributed Queue Agent or the central Queue Agent, depending on how the system is deployed. The GW1745 application is needed for all Qmatic hardware that communicates through the 1745 protocol. All new IP based hardware will connect directly to the Device Controller Server within the Queue Agent.

**Addressing Devices** The model to identify and connect Units and devices is designed to make it simple to configure and manage many unique units and devices. UnitIds are specified on the Profile level and are therefore used for every unit on every Branch that uses that Equipment profile. For example: Branch A and Branch B use Equipment Profile 1 that has a Intro 17 with UnitId=Intro171 The Intro 17 on Branch A and Branch B will have the same UnitId. i.e. Intro171 **Branch Prefix** To make a unique identifier for each Unit, a three-character Branch Prefix is set in the configuration of each Branch and the combination of Branch Prefix and UnitId will create a unique identifier. For example: Branch A has prefix=AAA and Branch B has prefix=BBB The Intro 17's will now have a unique identifier. Intro 17 on Branch A = AAA:Intro17 Intro 17 on Branch B = BBB:Intro17 **Device Type** To make it possible to identify Devices within a Unit Type, it is not enough to know only the Unit's identity. We need to know for example which device that should get a specific event. The identifying string for each device therefore contains a Device Type identifier. For example, when Printer of a Intro 17 Unit, with UnitId=Intro17 and Branch Prefix AAA connects, the framework needs to know that it is the Printer device and not the Touch Screen device that is connecting. The Device Type identifier is a String that is decided by the developer of the device software. For example: Branch A has a branch prefix=AAA and a Intro 17 Unit with UnitId=Intro17. The Printer Device within the Intro 17 has an identification string as follows: AAA:Intro17:TP311X Note! A Device Type is never shown in the GUI configuration. It is defined by the developer of the device software and used by the Unit Type developer. **Device Id** The fourth part of the connection string is rarely used but was added to make it possible to have several devices of the same type within a Unit Type. For example, if someone wants to have two touch screens in a Unit Type it is possible to let the touch screens connect as the same device type but separate ids. For example: Branch A has a branch prefix=AAA and a Special Intro 17 Unit with UnitId=Intro17. This special Intro 17 Unit has two Touch Screens A and B with two different layouts. Touch A = AAA:Intro17:SW_INTRO17_TOUCH:1 Touch A = AAA:Intro171:SW_INTRO17_TOUCH:2 **Note! ** A Device id is never shown in the GUI configuration. It is defined by the developer of the device software and used by the Unit Type developer. **Identification string** To summarise the identification string: BranchPrefix : UnitId : DeviceType : DeviceId Note! As the device ID section states, the fourth segment for 'device id' is rarely used and can be omitted as long as there aren't two devices of the same deviceType in a given Unit. **Identification process**

### The *.utt file content The .utt file is a normal .zip file that could be opened and zipped back by for example winzip or 7-zip. Note: If you use winrar while creating your utt file, make sure that you select Archive format ZIP **Icon (unit.png)** The icon should be a 64*64 pixels .png file and it will be shown as the icon for the Unit Type. **XML file (unit.xml)** The unit.xml file defines the whole unit type. See separate chapters about the content of the xml file. **Other data** The utt file can also contain other files the Unit Type or its devices needs. For example, a Unit Type with LED Display devices can have a font folder inside that the system uploads to the device at initialization. Other Data Example:

The .utt file structure The XML file. A GUI parameter is used to decide what font file that should be used and a Device Parameter is referencing the GUI parameter value to initialize the display devices with the correct font file in the .utt. See Replacement Language for detailed information about how variables are referenced. ``` ... GUI parameter to select a font file ... ... Device parameter to tell the display that it should ask for a font file {"BSID": + ${BSID} +, "refreshInterval":5, "fonts":[{"fontId":"A", "fileName":"+${fontA}+"}]} ... A command handler that returns the font file when display asks for it ``` ## 2. Explaining the unit.xml file ### Overview The logic of a Unit Type and what parameter you can set in the GUI are all defined in one XML file called unit.xml. The XML file is structured as the picture below and all elements and attributes are described in detail in the following chapters. Parameters defines what parameters will be shown and changeable in the GUI. The parameters are then referenced and used to alter the init parameters of devices or the behaviour of script functions. Devices defines what devices the Unit Type consists of and the behaviour of each. The devices specify what should happen when events are received and the possibility to send commands to the external device. The script functions can use the API functions of the core platform through connector functions (resources). unitCommands and unitEvents are event handlers that execute some logic when a defined event is received from the core platform, for example when a visit is called.

* element* The unit element is the top node of the unit.xml ``` ... ... ``` **Attributes for element**

Attribute	Description
name	The name of the Unit Type Template We recommend the name to be max 15 characters (a -Z0-9) Example: UnitType Template name is TP3115
frameworkVersion	Example: 2
unitVersion	The version of the Unit Type Template itself. This field will be used by the developers of the unit xml files to be able to see which version a customer is using. Note! When uploading a Unit Type Template that already exists in the system, the existing one will only be replaced if the unitVersion is higher. Note! The version number of the unit type template (utt) has the format X.Y.Z.n, for example 6.2.0.0, where: X.Y stands for the Orchestra version, e.g. 6.2, 6.1, etc. First version of an utt for Orchestra 6.2 has version 6.2.0.0. Z stands for fix version, incremented for each update. First version of an utt that is 6.2.0.0 gets version 6.2.1.0 when it is updated. n is the serial number that should be updated as soon as the utt has been adapted/customised to better suit your needs. Customising an utt that has version 6.2.1.0 receives version 6.2.1.1, then 6.2.1.2, etc. When several versions of Orchestra are updated with the same utt, the lowest version number should be used. If, for example, a new utt is added to version 6.0, 6.1 and 6.2 of Orchestra, it should have version number 6.0.0.0 in all Orchestra versions.
type	The type of a Unit Type determines in what category it will be showed in, in the GUI. DEVICE_CONTROLLER ENTRY_POINT SERVICE_POINT DISPLAY_POINT CUSTOM
defaultNoUnits	If the Unit Type Template should represent a group of Units, this is the number of Units it will contain when added to an Equipment profile.
maxNoUnits	If the Unit Type Template should represent a group of Units this is the maximum number of Units of the group that can be configured. If omitted, defaults to 1. If maxNoOfUnits is more than one, the GUI will allow the user to specify how many units that shall be created.
description	A short description of the Unit Type Template.

### element Each parameter element defines a parameter that should be shown in the GUI All elements are encapsulated in the element. ``` ... ... ... ... ... ... ``` **Attributes for element**

Attribute	Description
type	The attribute type defines the parameter type of GUI control that should be displayed and used by the user to set one or multiple parameter values. See table below for possible types.
name	Name is used as a variable name when the parameter value is retrieved in, for example, an event script. Example: String valueOfParameter = unit.getConfiguration().get("*name*")
label	The label of the parameter. The label is the string that ends up in the GUI
description	The tool-tip message that will be show when someone hovers the label or the value.
size	Specifies the width of an <input> element, in characters, in the GUI. Overrides the default width of 200px
sortOrder	The order of the parameter in the list of parameters in the GUI. Ascending from 1.
mandatory	Specifies if a value must be set before saving the Unit Type settings. Possible values "true" or "false".
readLevel	Specifies in which GUIs the parameter value is visible. Possible values "global", "profile", "branch". Combination of values is allowed, as example “global,branch” (if readLevel is not specified it the parameter will be hidden)
writeLevel	Specifies in which GUIs the parameter value can be edited and changed. Possible values "global", "profile", "branch". Combination of values is not allowed.
defaultValue	The default value of the parameter.
priviledge	ACCESS RIGHT NOT IMPLEMENTED YET
regExp	A regular expression that evaluates the value when the Unit is saved. Example: regExp="\b\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}\b" will do a simple check that the value has the form of an IP address.
multiSelection	(true/false) multiSelection can be used with list parameters and if set to true lets the user select multiple options from the list. As an example, selection of one or more Queues could define what ticket numbers should be display on a specific main display when customers are called.

**name** attribute is required List of possible Parameter Types that can be used in a .

type	GUI control	GUI Validation	Range (validated when publish is performed)
Integer	Input field	by using the regExp attribute	Integer (JAVA)
Double	Input field	by using the regExp attribute	Double (JAVA)
String	Input field	by using the regExp attribute	none
Boolean	checkbox (checked value=true)	None	true/false
Options	A drop down box if multiSelection=false. A list box where multiple options can be selected if multiSelection=true. Options must be defined in <option> tags in the pararameter.	If attribute mandatory=”true”, a selection has to be done	None or multiple of the defined options
IdCode	Input field	by using the regExp attribute	1-127
SubIdCode,	Input field	by using the regExp attribute	1-127
Service	A drop down box if multiSelection=false. A list box where multiple options can be selected if multiSelection=true. Options are all Service of the Operation Profile	If attribute mandatory=”true”, at least one selection has to be done	None, one or multiple of the listed Services
Queue	A drop down box if multiSelection=false. A list box where multiple options can be selected if multiSelection=true. Options are all Queues of the Operation Profile	If attribute mandatory=”true”, at least one selection has to be done	None or multiple of the listed Queues
ServicePoint	A drop down box that lists all ServicePoint units added to current equipment profile.	At least one selection has to be done
PresentationPoint	A drop down box that lists all PresentationPoint units added to current equipment profile. Starts with “please select”	If attribute mandatory=”true”, at least one selection has to be done	None or multiple of the listed Queues
EntryPoint	A drop down box that lists all EntryPoint units added to current equipment profil.	At least one selection has to be done
SurfaceApplication	A drop down box that lists all SurfaceApplications of the current Operations profile. <filter> can be used to filter out a specific Surface Type to be listed. Starts with “please select”	If attribute mandatory=”true”, at least one selection has to be done	One of the listed SurfaceApplications
UnitId	Input field	Must be a unique string
UnitName	Input field
DeviceController	A drop down box that lists all DeviceControllers added to current equipment profile.	At least one selection has to be done
WorkProfile	A drop down box that lists all Work Profiles of current operations profile. Starts with “please select”	If attribute mandatory=”true”, at least one selection has to be done	None or multiple of the listed Work Profiles
TicketTemplate	A drop down box that lists all Ticket Templates of current operations profile. Starts with “please select”	If attribute mandatory=”true”, at least one selection has to be done	None or multiple of the listed Ticket Templates

**** Options can only be used together with Parameter Type Options. Options should contain an _ Example of a drop down control that lists different days ... ** ** ... ... **** Can be used with type SurfaceApplication to filter out surface application for a specific device type. Example of a drop down control that lists all surface application of the type Qmatic TP-3115/Intro8 ... ... ** 62 ** ... ... ... ... List of possible devices that can be used with

id	Internal name	Surface Group	Device Type	Resolution
62	SW_TP3115_TOUCH	Touch Screen	Qmatic TP-3115/Intro 8	480*800
63	SW_VISION15_TOUCH	Touch Screen	Qmatic Vision 15	1024*768
64	SW_VISION17_TOUCH	Touch Screen	Qmatic Vision 17	1280*1024
65	SW_MEDIA_HD_POSITIONAL_DISPLAY_POINT	Positional display	Positional Display HD 720	720*1280
66	SW_MEDIA_HD_DISPLAY_POINT	Media Display	Media Display HD 720	720*1280
67	SW_MEDIA_FULL_HD_DISPLAY_POINT	Media Display	Media Display FULL HD 1080	1920*1080
68	RESERVED
69	SW_MEDIA_HD_POSITIONAL_DISPLAY_POINT_PORTRAIT	Positional display	Positional Display HD 720 Portrait	720*1280
70	SW_MEDIA_HD_DISPLAY_POINT_PORTRAIT	Media Display	Media Display HD 720 Portrait	720*1280
71	SW_MEDIA_FULL_HD_DISPLAY_POINT_PORTRAIT	Media Display	Media Display FULL HD 1080 Portrait	1080*1920
72	SW_INTRO17_TOUCH	Touch Screen	Qmatic Intro 17	1280*1024
73	PAD_PORTRAIT	Positional display	Positional Display 600*1024	600*1024
74	PAD_LANDSCAPE	Positional display	Positional Display 1024*600	1024*600
75	IPAD_PORTRAIT	Positional display	Positional Display 768*1024	768*1024
76	IPAD_LANDSCAPE	Positional display	Positional Display 1024*768	1024*768
77	IPAD3_PORTRAIT	Positional display	Positional Display 1536*2048	1536*2048
78	IPAD3_LANDSCAPE	Positional display	Positional Display 2048*1536	2048*1536
79	TOUCH	Touch Screen	Generic Touch Surface
80	MEDIA	Media Display	Generic Media Display
81	POSITIONAL	Positional Display	Generic Positional Display

**Relationship between Parameter Types, Attributes and Levels** There is no validation between Parameter Type, Attributes, additional Elements or configuration Level implemented yet. This means that the system will, for example, not complain if multiSelection is set to true on a Boolean. The attribute will just be ignored. If a Service attribute with writeLevel="global" is specified, the drop down box will appear in System Administration, but as there are no connections to an Operation Profile on this level, there will be no Services listed or the wrong data will be listed. Below is a matrix of the combination of Parameter Types and Attributes that can be combined with effect and on what configuration level it could be used.

Attributes

name

label

description

size

sortOrder

mandatory

readLevel

writeLevel

defaultValue

regExp

multiSelection

Elements

Level

global

profile

branch

Type

Integer

Double

String

Boolean

Options

IdCode

SubIdCode

Service

Queue

ServicePoint

PresentationPoint

EntryPoint

SurfaceApplication

UnitId

UnitName

DeviceController

WorkProfile

TicketTemplate

### element Each device is defined in a separate device element All elements are encapsulated in the element. Example of a TP3115 device ``` ... ... ${integer} ${integer} ... ... // groovy scripts // JAVA code ... ... ... ... ... ... ``` **Attributes for element**

Attribute	Description
id	If two or more devices of the same type are defined in a Unit, the device id is used to separate these devices. The id of a device is therefore usually set to 1. See also communication and identification string
name	The variable name of the device to be used when referencing the device internally from scripts.
type	The definition of the device type. The device type is a string that is used when devices connects and identify themselves. The developer of the device defines what string is used as a device type. See table below for Device Type Strings of Qmatic Standard software devices. See Appendix for Device Type Strings of Qmatic Hardware.
controllerId	The controllerId defines which device controller server that should be used when sending and receiving commands and events to a hardware device.
resources	The resources specify what API functions the devices want to use in its scripts. See Resource chapter

Device Type String of Qmatic standard software devices:

String	Description
SW_SERVICE_POINT	QMATIC Standard counter workstation web application
SW_RECEPTION	QMATIC Standard reception workstation web application
SW_TP3115_TOUCH	QMATIC TP3115 Touch web application
SW_VISION15_TOUCH	QMATIC Vision15 Touch web application
SW_VISION17_TOUCH	QMATIC Vision17 Touch web application
SW_POSITIONAL_DISPLAY	HD 720 positional display web application
SW_MEDIA_HD_DISPLAY_POINT	HD 720 main display web application
SW_MEDIA_FULL_HD_DISPLAY_POINT	Full HD 1080 Media main display
SW_POSITIONAL_DISPLAY_PORTRAIT	HD 720 positional display web application portrait mode
SW_MEDIA_HD_DISPLAY_POINT_PORTRAIT	HD 720 main display web application portrait mode
SW_MEDIA_FULL_HD_DISPLAY_POINT_PORTRAIT	Full HD 1080 Media main display portrait mode
SW_INTRO17_TOUCH	QMATIC Intro product series Touch web application, successor to Vision17
PAD_PORTRAIT
PAD_LANDSCAPE
IPAD_PORTRAIT
IPAD_LANDSCAPE
IPAD3_PORTRAIT
IPAD3_LANDSCAPE
TOUCH	Generic Touch Surface
MEDIA	Generic Media Display
POSITIONAL	Generic Positional Display

**** All elements are encapsulated in the element in each . When the system starts up or when a device connects to the system, each device will be initialized and at that moment the parameters specified in a device will be sent to it. The value can be replaced by referencing a GUI parameter. See Replacement Language See Appendix for parameters that are mandatory and optional for each Qmatic hardware device. ``` ... ... ${integer} ${integer}+100 ... ... ... ... ... ... ... ... ``` **Attributes for element**

Attribute	Description
name	The name of the parameter See Appendix for parameter names for each Qmatic hardware device.
type	Defines the type of parameter. Possible values are Integer, String See Appendix for parameter names for each Qmatic hardware device.
evaluate	Evaluate must be set to true if the parameter value needs to be calculated before use For example: <parameter type="Integer" name="id" evaluate="true">${idCode}+${unit:index}-1</parameter> See also replacement language

**Surface Application parameter** A device that uses a Surface Application must have a parameter that is called surfaceApplication and you need to reference it to the correct value of the GUI parameter as described above. The Surface Application Device will use the value to make a correct redirection to the Surface Application selected in the configuration GUI. ``` ... ... ... ... ... ${integer} ${tpTouchLayout} ... ... ... ... ... ... ... ... ``` **** All elements are encapsulated in the element in each . Many of the Qmatic hardware devices send events when something occurs. For example, a TP printer sends a BUTTON event when a button is pressed on the printer. For each event, it is possible to define an event handler that will perform some kind of action when the event is received. An Event does not require a return value. See Appendix for Events that is sent from each Qmatic hardware device. ``` ... ... ... ... // groovy scripts ... ... ... ... ... ... ``` **Attributes for element**

Attribute	Description
name	The name of the Event that should be handled.
handlerType	The type action that should be invoked when an Event is received. The most common and recommended way is to run a Groovy script but it is also possible to invoke a Java class.

**** All elements are encapsulated in the element in each . Works as deviceEventHandler except for that a Command needs a return value from the script or java code. See Appendix for Commands that are sent from each Qmatic hardware device. ### A unit event is an event generated within the Customer Journey Management core and sent to the unit in the device manager. For each unit event, it is possible to specify one or more event handlers that shall be executed. The event handlers are executed in the order they are listed within the unit xml file. A unit event does not require a return result. See Customer Journey Management Events and Commands for more information about events. ``` ... // // Groovy script with no return value // ... ... ``` ### A unit command is a command generated within the Customer Journey Management core and sent to the unit in the device manager. For each unit command, it is possible to specify one or more command handlers that shall be executed. The command handlers are executed in the order they are listed within the unit xml file. A unit command requires a return result. See Customer Journey Management Events and Commands for more information about command. ``` ... // // Groovy script with a return value // ... ... ``` ## 3. Customer Journey Management core relationships ### Customer Journey Management Parameters The core Customer Journey Management logic is dependent on some of the information often found in some of the Units. For example, it is the minimum time a called number should be shown on a display, in the waiting area, controlling the pace of how fast customers can be called to counters. The pace is controlled by the core Customer Journey Management logic, but can be set in Unit Types. Therefore, there are some pre-defined Customer Journey Management Parameters that can be set in the Unit Type for each type of Customer Journey Management object.

Customer Journey Management Parameters have pre-defined static names and are used by the logical objects of the Customer Journey Management logic. They can be omitted, if default values are acceptable. If needed, they can also be referenced and used by the internal scripts of the Unit Type. Example of a static CFM Parameter of a SERVICE_POINT Unit Type ``` ... ... ... ``` Different Customer Journey Management Parameters are available based on the type of Customer Journey Management Object/Unit Type. Following parameters are available for the Unit Types. **SERVICE_POINT**

Customer Journey Management parameter	type	default value	Description
storeNext	Boolean	false	Should a next call be on hold until next visit arrives.
minTimeBetweenCalls	Integer	0	Minimum time in seconds between the service point can call next visit
confirmNeeded	Boolean	false	If confirm must be done before calling next visit
singleSession	Boolean	true	Are multiple user sessions allowed on the same service point.

**DISPLAY_POINT**

Customer Journey Management parameter	type	default value	description
minVisitDisplayTime	Integer	3	The minimum time each number must be shown on the display before next can be called in seconds
queues	Comma separated string of Queue orig Ids	“”	Parameter defines for which queues the unit will receive a VISIT_CALL unitCommand
servicePoints	NOT FULLY WORKING	NOT FULLY WORKING	NOT FULLY WORKING

### CFM Events and Commands The main difference between Events and Commands is that the system waits for a Command to return a result. For an example, the system will wait for the PRINT unit command to return, and remove the Visit that was created, if the result is not ok. **Device Events and Commands** Events and Commands coming from the Devices are defined in the Appendix and how to use them in the section describing element. See Appendix for more information. **Unit Commands** There is currently only one Unit command and that is the PRINT command **List of Unit Commands** ``` Command Description PRINT A print command is sent when a Visit is created ``` **Parameters in Unit Commands**

Parameter	PRINT	Type	Description
appointmentId	x	Integer	The appointment id
appointmentStartTime	x	String	The start time (TimeStamp) of the appointment.
branchId	x	Integer	The id of the current Branch
eventTime	x	TimeStamp	The TimeStamp of when the command was triggered
firstName	x	String	The first name of the current User
lastName	x	String	The last name of the current User
queueId	x	Integer	The id of the current Queue.
queueName	x	String	The name of the current Queue
queueServiceLevel	x	Integer	The service level of the Queue configured in the Operation Profile
service	x	Long	The id of the current Service the Visit is in queue for
serviceExtDesc	x	String	The external description specified in the configuration of the Service
serviceExtName	x	String	The external name specified in the configuration of the Service
serviceIntDesc	x	String	The internal description specified in the configuration of the Service
serviceIntName	x	String	The internal name specified in the configuration of the Service
serviceOrigId	x	Integer	The id of the service on global level
serviceTargetTransTime	x	Integer	The target transaction time specified in the configuration of the current Service
ticket	x	String	The ticket number the current Visit
type	x	enum	The type of current Unit. Possible values are: DEVICE_CONTROLLER, ENTRY_POINT, SERVICE_POINT, DISPLAY_POINT, DETECTION_POINT, CUSTOM
unitName	x	String	The name of the Unit specified in the Equipment profile
user	x	String	The username of the User that was logged in on the Unit that triggered the event
userId	x	Integer	The id of the User that was logged in on the Unit that triggered the event
visitId	x	Long	The id of the current Visit

Note: TimeStamp has the ISO-8601 format [YYYY]-[MM]-[DD]T[HH]:[MM]:[SS].[sss][+-]hh:mm] For example: 2014 - 01 - 22 T12:00:00.000+0100 **Unit Events** Unit Events are events generated within the Customer Journey Management core functionality when for example a Visit is created or called. Unit events are sent to the Unit that triggered the event. For example, if a Visit is generated on a Intro 17 Generation 2 Unit, a VISIT_CREATE event is sent to that Unit. It is possible to get events triggered by other Units within a branch by using the PUBLIC. Statement in front of the event name. See Public events. **List of Unit Events**

Event	Description
RESET	Triggered by nightly reset and when a configuration is published
SERVICE_POINT_CLOSE	Triggered when a Service Point is opened
SERVICE_POINT_OPEN	Triggered when a Service Point is closed
USER_SERVICE_POINT_SESSION_END	Triggered when a User close a Service Point
USER_SERVICE_POINT_SESSION_START	Triggered when a User opens a Service Point
USER_SERVICE_POINT_WORK_PROFILE_SET	Triggered when a Work Profile is changed on a Service Point
USER_SESSION_END	Triggered when a User logout
USER_SESSION_START	Triggered when a User login
VISIT_CALL	Triggered when a Visit is called to a Service Point from a Queue or a Pool
VISIT_CONFIRM	Triggered when a Visit, that was called, is confirmed at the Service Point
VISIT_CREATE	Triggered when a Visit is created
VISIT_END	Triggered when the transaction, of the last Service for the Visit, is ended
VISIT_NEXT	Triggered when a Visit is called by the next function. Not when a Visit is called from a Pool or cherry picked out of a Queue
VISIT_NOSHOW	Triggered when a Visit is set to No Show
VISIT_RECYCLE	Triggered when a Visit is recycled back into Queue
VISIT_REMOVE	Triggered when a Visit is Removed
VISIT_TRANSFER_TO_QUEUE	Triggered when a Visit is transferred to a Queue
VISIT_TRANSFER_TO_SERVICE_POINT_POOL	Triggered when a Visit is transferred to a Service Point Pool.
VISIT_TRANSFER_TO_USER_POOL	Triggered when a Visit is transferred to a User Pool.

**Parameters in Unit Events**

Events

Parameters

RESET

SERVICE_POINT_CLOSE

SERVICE_POINT_OPEN

USER_SERVICE_POINT_SESSION_END

USER_SERVICE_POINT_SESSION_START

USER_SERVICE_POINT_WORK_PROFILE_SET

USER_SESSION_END

USER_SESSION_START

VISIT_CALL

VISIT_CONFIRM

VISIT_CREATE

VISIT_END

VISIT_NEXT

VISIT_NOSHOW

VISIT_RECYCLE

VISIT_REMOVE

VISIT_TRANSFER_TO_QUEUE

VISIT_TRANSFER_TO_SERVICE_POINT_POOL

VISIT_TRANSFER_TO_USER_POOL

appointmentId

appointmentStartTime

branchId

branchName

callTime

confirmNeeded

customers

firstName

isConfirmed

lastName

pool

queueId

queueName

queueServiceLevel

queueType

service

serviceExtDesc

serviceExtName

serviceIntDesc

serviceIntName

serviceOrigId

servicePointId

servicePointLogicId

servicePointName

serviceTargetTransTime

ticket

totWaitTime

type

unitName

user

userId

waitingTime

visitId

workProfile

workProfileName

workProfileOrigId

**Description of Parameters in Unit Events** **Parameter Type Description**

Parameter	Type	Description
appointmentId	Integer	The appointment id
appointmentStartTime	TimeStamp	The start time of the appointment.
branchId	Integer	The id of the current Branch
branchName	String	The name of the current Branch
callTime	TimeStamp	The TimeStamp of when the current Service of the Visit was called to a ServicePoint.
confirmNeeded	Boolean	A flag that states if the Call of the Visit has to be confirmed at the ServicePoint before transaction starts.
customers	Long,long,…	A comma separated list of customer Ids (Long)
firstName	String	The first name of the current User
isConfirmed	Boolean	A flag that determines if the Visit has been confirmed after it was called
lastName	String	The last name of the current User
pool	Long	The id of the Pool a Visit is transferred to.
queueId	Integer	The id of the current Queue.
queueName	String	The name of the current Queue
queueServiceLevel	Integer	The service level of the Queue configured in the Operation Profile
queueType	enum	Possible values are: QUEUE, USER_QUEUE, SERVICE_POINT_POOL, USER_POOL, MATCHMAKER_QUEUE, DELAY_QUEUE, LINEAR, APPOINTMENT_QUEUE
service	Long	The id of the current Service the Visit is in queue for
serviceExtDesc	String	The external description specified in the configuration of the Service
serviceExtName	String	The external name specified in the configuration of the Service
serviceIntDesc	String	The internal description specified in the configuration of the Service
serviceIntName	String	The internal name specified in the configuration of the Service
serviceOrigId	Integer	The id of the service on global level
servicePointId	Long	The id of the Service Point that triggered the event
servicePointLogicId	Integer	The logical id of the Service Point that triggered the event. The logical id is the index number of all Service Points listed in the Equipment Profile
servicePointName	String	The name of the Unit specified in the Equipment Profile
serviceTargetTransTime	Integer	The target transaction time specified in the configuration of the current Service
ticket	String	The ticket number the current Visit
totWaitTime		The sum of all waiting times of the current Visit
type	enum	The type of current Unit. Possible values are: DEVICE_CONTROLLER, ENTRY_POINT, SERVICE_POINT, DISPLAY_POINT, DETECTION_POINT, CUSTOM
unitName	String	The name of the Unit specified in the Equipment profile
user	String	The username of the User that was logged in on the Unit that triggered the event
userId	Integer	The id of the User that was logged in on the Unit that triggered the event
waitingTime	Integer	The time the Visit has been waiting for the current Service
visitId	Long	The id of the current Visit
workProfile	Integer	The id of the current Work Profile.
workProfileName	String	The name of the current Work Profile, set in the Operation Profile
workProfileOrigId	Integer	The id of the current Work Profile on global level

Note: TimeStamp has the ISO-8601 format [YYYY]-[MM]-[DD]T[HH]:[MM]:[SS].[sss][+-]hh:mm] For example: 2014 - 01 - 22 T12:00:00.000+0100 **PUBLIC events** To receive events that are triggered by other Units, one must declare the event name as PUBLIC. In the example below, the Unit will receive the VISIT_CREATE events triggered by itself but receive all VISIT_CALL events triggered by any Unit on the branch. ``` ... // this event will only listen to events created by this unit // // Groovy script with no return value // ... ... // this event will listen to events created by all units // // Groovy script with no return value // ... ``` ## 4. Development ### Tools **jiqlAdmin** The jiqlAdmin application lets you change the currently loaded configuration of a Branch, including the scripts and attributes of a Unit Type. Changes are active when changed and saved. This means that you do not have to upload an update of your Unit Type every time you have made a change to it, while developing. The jiqlAdmin application is installed with the Queue Agent and you access it by typing in the correct path in your browser. You can access the JiqlAdmin on both a central and a distributed Queue Agent. Log in as superadmin. Path to jiqlAdmin: http://"qagent-server":"port"/jiqlAdmin Example for a default central install of Orchestra on your local computer: http://localhost:8080/jiqlAdmin Note: when you are done with the code changes, you need to take the code and place it in your original unit.xml. A publish will overwrite all changes you made in the jiqlAdmin.

### Replacement language The evaluation and replacement will be executed when a Branch configuration is published. The replacement language cannot be used with GUI parameters, except for the pre-defined Customer Journey Management parameter "unitName". If the Unit Type has a maxNoUnits value over 1, the replacement language is used to create a unique unit name for each unit. See Understanding the index of a Unit Type for more info about unit:index. Example of the only usage possible in GUI parameters ``` ... ... ... ... ... ``` Except for the usage above, the replacement language is used in the device parameters that are sent to each device at initialization of the device. **Referencing parameters** To use the parameter value set in the GUI to initialize the device, you have the possibility to do that by referencing the parameter. Referencing a parameter and retrieving its value is done by the $ sign followed by the parameter name in brackets {}. **Referencing system variables** You can also retrieve values from the environment (cfg), the Branch (branch), the unit name and the unit index by system references. ``` ... ... ${someParameterName} ${aSystemReference} ... ... ... ... ``` **cfg:xxx** cfg:xxx cfg is used to get values from environmental parameters as the Queue Agent's config file or the jvm parameters. Example of retrieving the value of the orchestra host, specified in the agent.conf file ${cfg:agent.https.enabled } **branch:xxx** branch is used to get values from the branch parameters. There are 3 pre-defined parameters but it is also possible to retrieve values from all existing branch variables. ** Pre-defined:** - branch:name Will be replaced with the current branch name - branch:timeZone Will be replaced with the timezone of the branch - branch:prefix Will be replaced with the 3 character branch prefix - branch:"branchParameter" Will be replaced with the value of branchParameter of the branch. **unit:xxx** There only exist two pre-defined unit variables Pre-defined: - unit:name Will be replaced with the Unit Type Template name - unit:index Will be replaced with index of the Unit Type instance See below. **Understanding the index of a Unit Type** To understand the unit:index you have to understand what happens when the branch configuration is published. If the Unit Type has a maxNoUnits value that is above 1, the system will create as many instances of the Unit Type as the value of maxNoUnits before it is published. The first created instance will have an unit:index equal to 1. After that, the references to unit:index will be replaced with the unit:index of each instance. **Evaluations** Simple addition and subtraction expressions can be defined for integer device parameter values. These are evaluated when the evaluation attribute is set to true. Integer example ${someGuiParameter}+${unit:index}-1 String example "Half of a string " + ${someGuiParameter} ### Event Handler Scripting **Handler Types** There are two supported handlerTypes that can be used in any event or command handler, GROOVY and JAVA. The handler type must be specified for each handler function. ``` ... // this event will only listen to events created by this unit // // Groovy script with no return value // ... ``` **Groovy Scripting** It is possible to use GROOVY scripting in all event and command handlers in a Unit Type. How to write GROOVY scripts is not described in this document. **Java code** **Logging** All log records are written to the qagent.log file if the Queue Agent is distributed and to the qp_server.log if Queue Agent is central. A tip is to use a log-tail software that displays the log file and updates it when a new log entry is added. Log records could be written within your scripts as following example. device.log("INFO", "this is a log message") See the Java Doc API documentation for more info about the logging API ### API Resources The API to the Customer Journey Management core are reachable through a Resources. Resources are comparable with the REST connectors used when developing web applications, like a custom Workstation. To be able to use the API functions of a Resource, you must define that you want to use it, and that is done in the element. See element. If you, for example, define a SYSTEM resource to be used with your printer Device, you will be able to get that Resource and call any of its methods by using the getResource function of the device object. Example of a TP3115 device ``` ... ... ... ... ... device = unit.getDevice("TP3115") licenseText = device.getResource(“SYSTEM”) .getSystemInformation() device.log(“INFO”, licenseText) ... ... ... ``` **Resources in API documentation**

Resource	Class in API documentation
BRANCH	BranchDeviceResource
CMS	CmsDeviceResource
CUSTOMER_JOURNEY	CustomerJourneyDeviceResource
DIGITAL_SIGNAGE	DigitalSignageDeviceResource
EVENT_SCHEDULER	EventSchedulerDeviceResource
IDENTIFICATION	IdentificationDeviceResource
PRINTER	PrinterDeviceResource
TP311x	Tp311xDeviceResource
SERVICE_POINT	ServicePointDeviceResource
SYSTEM	SystemDeviceResource
SURFACE	SurfaceApplicationDeviceResource

All functions of the Resources are described in the Java Doc API documentation.