Skip to main content
Matrix42 Self-Service Help Center

Email Descriptors: Literals

Configuring text, date, currency and links data in the e-mail templates.

Overview

E-mail Descriptor literals are intended for representing a fixed value from the defined in the email template data sources.

Literals are configured in the Layout Designer and include the following controls that can be added to the e-mail templates:

  • text
  • date
  • currency
  • link

email_literals_order1.png

 

Literals are added to the e-mail template via the following path:

Administration application → Services & Processes → E-Mails → E-Mail Descriptors → Customize e-mail template in the Layout Designer → Toolbox → Literals:

email_literals_layout_designer2.png

Properties & settings

Property group Settings Text Currency Date Link Description
Model Value ✔️ ✔️ ✔️ data model property serving as a source of the displayed in the e-mail data
Format ✔️

the date and time displaying options

Object ID ✔️

link-specific settings defining the data source for the generated link, link text and text to display if the link cannot be generated.

Configuration Item ✔️
Value Label ✔️
Link Text ✔️
Appearance Label ✔️ ✔️ ✔️ ✔️ the caption of a displayed item
Label Position ✔️ ✔️ ✔️ ✔️

position of the caption:

  1. left: the label is placed on the left of the row, the item is placed after the label;
  2. top: the label is placed above the displayed item:

literal_label_position1.png

Label Width ✔️ ✔️ ✔️ ✔️

allows assigning fixed width of the label in pixels, e.g. 100:

  1. label width for each row is set to 100px, content is aligned 
  2. label width is not set

label_width1.png

Visibility ✔️ ✔️ ✔️ ✔️

the literal displaying settings. Allows restricting the entire literal displaying according to the visibility value. 

Boolean values from the following sources:

  • Model: select value from the suggested in the data model properties;
  • Static value: 
    • true: the optionally configured label and the value of the literal are displayed in the e-mail even if the value if the item to display is empty;
    • false:  the entire row including label and the value are not retrieved to the email.

Literal displaying in the e-mail depends on the combination of Visibility and Hide on empty value properties.

Hide on empty value ✔️ ✔️ ✔️ ✔️

check-box options:

  • disabled (False): default option, the entire email literal is displayed if there is a configured label but no value to show. Without value and label there is no data to show, so there would be blank space in the area where the literal is supposed to be;
  • selected (True): the entire row including optionally configured label is not shown if the value of the item to display is empty.
Common  Name ✔️ ✔️ ✔️ ✔️ the auto-generated internal name of the control used in the layout
Navigation Navigate To ✔️ link-specific settings
Navigation Item ✔️
Application ✔️
Run Action ✔️
Custom URL (legacy) ✔️

 

Text literal

Text literal allows retrieving to the e-mail template the data of the following types:

  • string
  • boolean
  • integer
  • float
  • text
  • object reference
  • enums

Currency literal

Currency literal is intended specifically for the currency data type. 

Displayed in the e-mail currency literal data is retrieved as is from the database and depends on the currency and amounts that were initially set in the services catalog:

order_email.png

Default currency from the user profile settings are not taken into account when generating an e-mail content and require additional e-mail template configuration and data processing by an appropriate web service.

 

Date literal

Date literal is used to configure date and time structure displayed in the sent e-mails. 

Date literal options

The following table describes various date and time patterns and provides their displaying examples.

The format options imply the content of the date literal such as how and whether to show the date, month, year and time with or without seconds.

The date and time format may vary based on the locale settings and impact the separation signs used in the date (slash or hyphen), as well as 12-hour or 24-hour clock.

Format options

en-US locale

(example)

de-DE locale

(example)

Not set

M/d/yyyy h:mm:ss  tt

(6/14/2019 2:33:44  PM)

dd.MM.yyyy HH:mm:ss

14.06.2019 14:33:44

Short

M/d/y, h:mm tt

(6/7/19, 2:33 PM)

M.d.y, HH:mm

(6.07.19, 14:33)

Medium

MMM d, y, h:mm:ss tt

(Jun 7, 19, 2:03:05 PM)

MMM d, y, HH:mm:ss

(Jun 7, 19, 14:03:05)

FullDate

dddd, MMMM d, y

(Friday, June 7, 19)

dddd, MMMM d, y

(Freitag, Juni 7, 19)

LongDate

MMMM d, y

(June 7, 19)

MMMM d, y

(Juni 7, 19)

MediumDate

MMM d, y

(Jun 7, 19)

MMM d, y

(Jun 7, 19)

MediumTime

h:mm:ss tt

(2:33:44 PM)

HH:mm:ss

(14:33:44)

ShortTime

h:mm tt

(2:00 PM)

HH:mm

(14:00)

Date format legend

  • dddd: full name of the day
  • d: the day of the month as a number from 1 through 31
  • dd: the day of the month as a number from 01 through 31
  • M: month number without leading zero (e.g. 6)
  • MM Month number with leading zero
  • MMM: abbreviated month name (e.g. Aug)
  • MMMM: full month name (August)
  • y: year, no leading zero (e.g. 2019 would be 19)
  • yyyy: year, (e.g. 2019)
  • h 12-hour clock hour (e.g. 3)
  • HH 24-hour clock hour, with a leading 0 (e.g. 22)
  • mm: minutes with a leading zero
  • ss: seconds with leading zero
  • tt:  AM / PM (e.g. AM or PM)

 

The date and time format is defined by the Locale of the default E-mail Language selected by the user in the Profile settings:

profile_settings_email_language.png

 

The time zone used in the e-mail is defined by the user's Location settings:
time_zone_settings1.png

 

Link 

The control allows to easily embed a link to an email which directly opens the application artifacts, like a specific Management area, specified object Preview or directly the edit page of a data object or runs a specific action. 

Model

Model section defines the data source for the generated link, link text and text to display if the link cannot be generated: 

  • Object Id: identifier of the referenced in the link data object. Select data model property of a GuId type. 
  • Configuration Item:  this option is used when there is more than one source of the referenced data objects and the type (Configuration Item) of the Object ID cannot be defined automatically (e.g. manually created property or ambiguous Configuration Item type). For example, selected Object ID is used in different types of tickets such as Problem, Change Request, Incident, etc. If the e-mail template is created specifically for an incident, explicitly set the Configuration Item of an incident.
    • not set: the System will try to recognize the type according to the data from the Object ID field.
    • set: the link will be generated for the specified type of object. 
  • Value Label: allows overwriting the text of the link. 
    • not set: text for the link is automatically detected from the referenced resource (e.g. based on the "Display expression" property of the explicitly stated Configuration Item or from the automatically detected Configuration Item the specified Object ID belongs to). See also: Configuration Item settings.
    • set manually: the specified text is always rendered for a link (e.g. localizable text in English is set to Click here to open the Incident in your web browser). Value label data sources: data model property, localizable value or static value.
  • Link Text: text which is displayed instead of the link, when the System does not recognize the referenced resource (e.g. Id of the Object is not set, no longer exists or was not found). 
    • not set: the link is not shown in the e-mail if the Object ID was not found; 
    • set:  if the link cannot be generated, the system retrieves to the e-mail the Link Text from one of the following data sources: data model property, localizable value or static value.

Appearance

Appearance section defines the optional caption, preceding the link, and the link displaying conditions in the sent e-mail. All types of e-mail literals have generic appearance settings.

  • Label: the control can be displayed with a caption. This property defines the text for the label.
  • Label Position: relevant only if the Label is set. Regulates the position of the label and its positioning in the email relatively to the link (before the link or on top of the link.
  • Label Width: fixed placeholder for the link text.
  • Visibility: allows dynamically show/hide a control depending on some dynamic data.

Navigation

All settings, except for the Custom URL, are relevant for the new user interface of the Matrix42 platform also referred to as UUX.

  • Navigate To: specifies the kind of Application resource the anchor in the email should navigate to. The System supports the following types:
    • Search Page: direct the user to the specified Management area (Dataset View). On picking this option, the Email Designer requests to provide the reference to Navigation Item which needs to open on click;
    • Object Preview (default): opens Preview of the specified Object. If this option is selected, the Id of the Object needs to be set to property "Object Id". To solve the ambiguity, when the Preview for defined Object is available in multiple UUX applications,  the Navigation Item can be specified where the preview needs to be opened;
    • Object Dialog directly opens the edit dialog for a specified object. Depends on the "Object Id" field value.
  • Navigation Item: select a Navigation Item from the list of available in the system items. Specified Navigation Item also defines the Application where the generated link will be opened: Incidents (Service Desk).
  • Application: 
    • not set: by default, the system will try to generate the e-mail link for the Self Service Portal application.
    • set: select an application name from the suggested dropdown-list. In case of conflicting settings for the Application and a Navigation Item, the Navigation Item overrides the manually set Application.
  • Run Action: reference to the Action which needs to be initiated on opening the link. The action is started in the context of the opened page. E.g. if the link follows to object Preview, then the action is activated for the specified object.
  • Custom Url (legacy): specify a relative URL path to the Matrix42 platform with the legacy user interface. The specified URL path should not include the scheme (e.g. http / https) and the hostname (e.g. yourdomain.com) as they will be added automatically to the generated in the e-mail link. Optional parameter. Defines custom URL leading to the legacy portal. You may use variables in curly braces which will be replaced with actual values. Defined variables:
    • {id} object ID
    • {typeId} Configuration Item ID
    • {ci} Configuration Item Name.
    • Also, you can use data model path in curly braces. Example: {Parameters.SVCApprovalTaskType.ID} 

       Custom Url example with variables in the relative path:

      /Portal/Pages/Workspace.aspx?ObjectID={id}&query_parameter=value&param={Parameters.SVCApprovalTaskType.ID}

 

  • Was this article helpful?