MessageTemplates

Overview

VQ Conference Manager raises an Alert after an event has occured within VQ Conference Manager (System Started, System Stopped, Call Booked, MCU state change etc). This Alert can be viewed from the UI and an email can also be sent.

The text contained within the email is controlled by Message Templates.

The software checks the UX Profile Alert Configuration settings of all users and, if configured to either send an email or to generate text for injection into an Outlook Calendar, uses the Message Template provided to generate the text (or HTML) that will form the message body of the email or Calendar item.

MessageTemplates consist of text/html and text substitution values in the form {class.property name} - the system uses the names between the curly braces "{" and "}" to call back into VQ Conference Manager and extract the value of the property name and replace the {call.property name} text in the template with the value returned from VQ Conference Manager.

This technique provides great flexibility and, essentially, allows the template "script" to access any value available within VQ Conference Manager in Calls, Participants, McuUriReservations (coSpaces) and Call Bridges to be referenced and used within Emails.

In addition to accessing property values from VQ Conference Manager, the Template scripts can also perform simple logical functions (if and ifnot) and also perform loops (foreach).

The support of conditional and foreach states means that template scripts can generate blocks of text per (for example) participant or generate different text results depending on certain conditions (for example, display the PIN if a call has a PIN).

The system includes a default set of templates in both HTML and text formats; these can be viewed and edited the MessageTemplate coApp.

Please see Changes to MessageTemplates from VQCM 3.x for more details of the scripting syntax and examples. The set of predefined message templates also contain examples of scripting that can be used.

Configuring whether an email will be sent after an alert has occurred is done from the Alert coApp. This is navigated to from System>UX Profile>Alerts. Against the various types of Alert events, you can select whether the alert should result in an email being generated or the text injected into outlook calendar entries (normally this would be call booked or call updated.) If either email or outlook are selected, the template selection panel appears and you can specify which message template will be used when the alert occurs.

Note: Please be aware that txt emails have relatively poor formatting; HTML is better but cannot be used for injection into Outlook Calendars when using the VQ Conference Manager Outlook Add-in.

Note: Please also be aware that when using HTML, images are accessed via HTTP URIs and should therefore be saved on web servers that are accessible by all intended recipients.

There is an Access Control Tag associated with each Message Templates. This controls who can see the Message Template.

Creating a New MessageTemplate

Note: Only user type "Administrator" can perform this function.

In the System view select Message Template
Select New MessageTemplate
Give the Template a name
Select the Access Control, Resource Type and Preferred Message Type from the drop down list
Message Templates can be duplicated and then amended as necessary

Note: A default Message Template can be duplicated to create a new one, but the original cannot be changed. This is to avoid them becoming corrupted.

Note: For additional information regarding Outlook plugin Email Scripting, please refer to the Outlook Plugin Email Scripting chapter.

Changes to MessageTemplates from VQCM 3.x

VQ Conference Manager 3.x introduces a number of changes to improve the creation and maintainability of message templates. These include:

a new message template rendering engine based on the open source library Handlebars (https://github.com/rexm/Handlebars.Net). The Handlebars built-in Helpers (if, each, unless etc.) are defined here: http://handlebarsjs.com/builtin_helpers.html
a re-organization of the data passed into the email rendering engine

Switching to the Handlebars rendering engine provides users a more open, consistent and performant library but allows VQ to extend it’s capabilities such that it can support the functionality provided by the existing rendering engine. The changes made to the structure of the data passed into the rendering engine aim to remove redundant information and re-organize the data to make it more consistent and understandable. In turn this will make it easier to customize the messages generated by VQ Conference Manager.

Note that the new MessageTemplate rendering code uses the VQ naming convention and differs in a few instances from the CMS naming convention. In particular the following VQ names relate to the given CMS terms:

VQ Name	CMS Name
MCU	Call Bridge
Customer	Tenant
UriReservation	Space/coSpace
Pin	Passcode

Handlebar Expressions

MessageTemplates can be thought of as a section of text (or html) that includes a set of Handlebars expressions that insert the relevant data provided by VQ Conference Manager. This can be seen in the following message template definition that provides some relevant information about a user’s Space:

Space Details:

Name: {{UriReservation.Name}}

Uri: {{UriReservation.Uri}}

CallId: {{UriReservation.CallId}}

Name: {{Name}} {{#is Name 'Host'}}(This is the host role){{/is}}

PIN: {{#is Pin '' }}No Pin{{else}}{{Pin}}{{/is}}

Lync:

To join from a Microsoft Lync client click: sip:{{UriReservation.CallId}}@yourdomain.com

Telephone dial-in:

Dial: 1-503-666-7777 (replace with gateway DDI #) and enter {{UriReservation.CallId}}# when

prompted for a Call Identifier.

Address: {{UriReservation.Uri}}

{{#if UriReservation.SecondaryUri}}Alternative Address: {{UriReservation.SecondaryUri}} {{/if}}

Note the use of the handlebars expressions {{...}} that allows VQ Conference Manager to insert the appropriate text for the space into the document, for example the expression Name: {{UriReservation.Name}} tells VQ to insert the name of the space into the text. It is this mechanism that enables customers to customize the message with information that is relevant for the recipient of the message.

Note that although the example above is a plain text message by including the relevant HTML tags an HTML message can be easily generated. The standard email templates that are provided by VQ Conference Manager provide a good starting point for how to achieve this.

As well as the in-built expressions provided by Handlebars.Net VQ Conference Manager provides extensions to the standard Handlebars functionality. Currently the following extensions are provided (with the expectation that others will be added over time):

Expression	Description
#is x ’value’	Outputs the following text if the property x is equal to the specified value.

Also note the “#if”, “#is”, #unless and “#each” expressions are, like HTML, terminated with {{/if}}, {{/is}}, {{/unless}} and {{/each}}.

Predefined Message Templates can be found in System>MessageTemplates when signed in as an Administrator or SuperUser. If you cannot find examples that match your requirements or need help producing updated Message Templates, please contact support@vqcomms.com who will be delighted to create or update MessageTemplates for you.

Supported VQ Conference Manager Events

VQ Conference Manager allows message templates to be assigned to events that occur on the system. Examples include booking a call, starting the VQ Conference Manager server, stopping the VQ Conference Manager server and creating a Space. In each case the information provided for each event is specific to that event and, as such, the properties supported will be different. To allow this flexibility VQ Conference Manager passes a single data structure and relies on the message template definition to select the correct values for that event. For example, the message template will allow a VQ Conference Manager state change event to reference a call but, as there is no call available, it’s values cannot be presented.

The following properties are available in the data structure provided to the rendering engine, as described above, only a selection are valid for certain events:

Recipient: This property contains information about the recipient of the message and is available for all events.

Call: For Call events (call booked, call updated, call deleted) this property contains information about the call, including the call participants. Note that if there are no participants specified when the call is booked then the participant entry will be empty.

UriReservation: For UriReservation and Call alerts, this property contains information about the Space the event occurred on, including information on the roles available on the UriReservation.

Mcu: For Mcu events, this property contains information about the MCU that created the event. Typically this event is generated when an MCU is set online or offline.

CalendarEntry: This property contains information about the role when generating calendar entries. When processing a call booked or call updated event VQ can be configured (via the call owner’s UxProfile) to add attachments to the email sent to the call owner. It does this by repeatedly processing the callBooked email template for each role available in the call and adds the resultant message as an attachment to the call booked email message. In this scenario it is this property that controls the role that is currently being processed.

Recipient Properties

The following properties are available on the Recipient property of the message.

Id: The identifier of the recipient in VQ
Name: The recipient’s full name
FirstName: The recipient’s first name
LastName: The recipient’s last name
IsParticipant: Is the recipient a participant in the call? This can only be true for a call based event
IsOwner: Does the recipient “own” the resource that the alert relates to?
IsManager: Does the recipient “manage” the resource that the alert relates to? A manager is the owner of the resource or an operator/admin who has access to the resource from the VQ user interface. This property is relevant for Call, UriReservation and Mcu events
Locale: The recipient’s locale. The locale controls how certain information is presented in different locations around the world. At the moment, VQ Conference Manager 3.0 supports 2 locales: ‘en-US’ and ‘en-GB’. En-US presents dates as MM/DD/YYYY and times as AM/PM whereas en-GB presents dates in the European format of DD/MM/YYYY and times in the 24 hour format
TimeZone: The recipient’s time zone
Role: For a call event, and if the recipient is a participant, contains information about the recipient’s role. For a Space description event, and the recipient is a member, contains the recipient’s role

Call Properties

The following properties are available for Call events:

Id: The id of the call in VQ Conference Manager. You can use this to generate a web link to the call in VQ Conference Manager, e.g. https://XX.XX.XX.XX/#/schedule/Id
Name: The name of the call
Customer: This property contains information about the Customer that call is assigned to
ReferenceNo: The call reference number, a unique value for each call
UtcStartTime: The start time of the call in UTC
UtcStopTime: The end time of the call in UTC
TimeZone: The time zone the call was booked in
StartTime: The start time of the call, converted to the recipient’s timezone and formatted for the recipient’s locale
StopTime: The end time of the call, converted to the recipient’s timezone and formatted for the recipient’s locale
SetupMinutes: The setup period (in minutes) before the meeting starts, converted to the recipient’s timezone and formatted for the recipient’s locale
TearDownMinutes: The tear down period (in minutes) before the meeting ends, converted to the recipient’s timezone and formatted for the recipient’s locale
RequestedBy: The name of the person who requested the call
RequestedByEmail: The email address of the person who requested the call
RequestedByTelephone: The telephone number of the person who requested the call
Duration: The duration of the call
Participants: The call participants

Participant Properties

The following properties are available for Call participants:

Id: The id of the participant in VQ Conference Manager
Name: The full name of the call participant
PrimaryNumber: The primary number of the endpoint the participant will use
PrimaryProtocol: The protocol used by the endpoint that the participant will use
SecondaryNumber: The secondary number of the endpoint the participant will use
SecondaryProtocol: The secondary protocol used by the endpoint that the participant will use
Role: The participant’s role in the call

Role Properties

The following properties are available on a role (the current recipients role, the UriReservation role or the CalendarEntry role):

Name: The name of the role
Pin: The assigned pin for the role
Uri: The URI for this role (if different to the space URI)
CallId: The CallId for this role (if different to the Space CallId)

UriReservation Properties

The following properties are available for UriReservation and Call events:

Id: The identifier of the space in VQ Conference Manager. You can use this to generate a web link to the space in VQ Conference Manager, e.g. https://XX.XX.XX.XX/#/activity-simple/coapps/Id
Name: The name of the UriReservation
URI: The URI for the URIReservation
CallId: The CallId for the UriReservation
SecondaryUri: The SecondaryURI for the UriReservation
Customer: The customer the UriReservation has been assigned to
Temporary: Is this a temporary UriReservation? These are typically created when users create ad-hoc calls
Pin Returns: The Pin of the first role in the UriReservation
Secret Returns: The secret value of the first role in the UriReservation
SecondarySecret Returns: The secondary secret value of the first role in the UriReservation
Template: The template that describes the configuration of the UriReservation

Template Properties

The following properties are available for the Template property of the UriReservation:

Name: The name of the Template
Roles: The roles contained within the UriReservation

Customer Properties

The following properties are available for Customers:

Id: The identifier of the Mcu in VQ Conference Manager
Name: The name of the Customer

MCU Properties

The following properties are available for MCU settings:

Id: The identifier of the MCU in VQ Conference Manager
Name: The name of the MCU
State: Contains the current state of the MCU. The values can be online, offline, or error
LastError: Contains the last error encountered when attempting to communicate with the MCU