You are here: Advanced > Expression Language > Expression Language functions and syntax

Expression Language functions and syntax

The following is a reference of all functions and operations used by the Expression Language, divided into categories. For a thorough description of the Expression Language syntax with examples, see Expression Language.

Expression Language functions are categorized by their functionality. If you know the category of the function that you are looking for, go directly to that section.

Tip You can also search the page by pressing Ctrl+F, and entering the first few letters of a function or a word that describes what you are looking for. Use the Next and Previous buttons to move from one occurrence to the another. Open all drop-down links on the page before performing the search.

ClosedGeneral functions
Function Description
concat(Object...args)

Concatenate all arguments into a single string.

Example: Return a string indicating the old and new values of the change model on which a change record is based:

concat('Change Model replaced from \"',current_update.BasedOnChangeModel.OldValue.DisplayLabel,'\" to \"',current_update.BasedOnChangeModel.NewValue.DisplayLabel,'\"')

union(Object...args)

Returns a set of the values. The arguments can be of different data types, such as strings, numeric values, and boolean values. If any of the arguments are collections, the collection elements are merged with the set of values.

Example:union('string1', 5, true) returns (string1, 5, true).
union_with_null(Object...args)

Returns a set of the values. If any of the arguments are collections, the collection elements are merged with the set of values. If one of the arguments is a null value, the null value is included in the returned set.

Note This is an exception to the rules for null values, as defined in Null values and collections in Expression Language.
intersection(Object...args) Returns a new collection which contains only the elements contained in all of the collections entered.
first_non_empty_value(Object...args) Returns the first argument that has a non-null value.
contain(collection arg1, Object arg2) Returns true if arg2 is contained within arg1.
is_empty_collection(collection arg1) Returns true if arg1 is an empty collection.
ClosedMathematical functions
Function Description
avg(Number...args)

Returns an average of the given numbers.

Example: The expression avg(5, 10, 12) returns 9.
power(Number arg1, Number arg2) Returns arg1^arg2
round_down(arg1, num_digits) Rounds arg1 downward using num_digit as the number of digits to round the number.
sqrt(Number arg)

Returns the square root of arg.
max(Number arg1, Number arg2) Returns the higher of the two numbers.
min(Number arg1, Number arg2) Returns the lower of the two numbers.
ClosedDate functions
Function Description
now()

Returns the current time in milliseconds since January 1, 1970. You can indicate a date in the past or future by adding to or subtracting from the now() function. Add or subtract the required time in milliseconds.

Example: The expression now() + 259200000 returns the date 3 days from now, because 259200000 represents the number of milliseconds in 3 days.
days(long date1, long date2)

Returns the number of days between date1 and date2. If date1 is later than date2, the number is negative.

Example: The expression days(entity.CreateTime, now()) returns the number of days between the date when the current record was created until today.
months(long date1, long date2) Returns the number of months between date1 and date2. If date1 is later than date2, the number is negative.
hours(long date1, long date2) Returns the number of hours between date1 and date2. If date1 is later than date2, the number is negative.
minutes(long date1, long date2) Returns the number of minutes between date1 and date2. If date1 is later than date2, the number is negative.
format(long time, string format, locale locale, string, timezone)

Returns the formatted date according to the time and format entered. The following options are available for the format:

  • 'long'. Displays the date and time as follows: May 28, 2014 10:30:54 AM EDT
  • 'short'. Displays the date and time as follows: 5/28/14 10:29 AM

  • 'long_date'. Displays the date only as 28 May 2014

  • 'short_date'. Displays the date only as 28/5/2014

The locale and timezone parameters are optional.

  • You need to specify the locale before specifying the time zone.

  • To specify a time zone, enter timezone. to get a list of supported timezones.

Note: The date is calculated using the time zone defined in the Time zone definition field in Application Settings if you do not specify the timezone parameter.
to_date_time(date source, format, time zone)

Converts a date in string format to a long value. Returns the specified date and time in milliseconds since January 1, 1970.

The date source parameter is the string containing the date.

The format parameter defines the format of the string. The string in the date source parameter must match this format. For example, if the date source parameter contains the string '2000-01-01' and the format is ’yyyy/MM/dd’, the function will fail.

The time zone parameter defines the time zone for the value. This parameter is optional (if not entered, time zone is GMT+0).

Example: to_date_time(source.expiredDate,’yyyy/MM/dd’,GMT+8)
working_hours.EffectiveDuration(start time, end time, work schedule ID)

Returns the business duration of an issue based on the work schedule in milliseconds.

The start time and end time parameters represent the beginning and ending times. The start time parameter cannot be more than 3 months ago and the difference between the start time and end time cannot be greater than 3 months.

The work schedule ID parameter specifies the relevant work schedule.

Example: working_hours.EffectiveDuration(entity.ImpactStart, entity.ImpactEnd, entity.OwnedByPerson.WorkSchedule)

Note This function should be used only in fields and parameters that accept a value in milliseconds (for example, DOUBLE).
working_hours.EffectiveEndTime(start time, duration, work schedule ID)

Returns the ending time of an issue based on the work schedule and the business duration.

The start time parameter represents the beginning time. The duration parameter represents the business duration in milliseconds (it can be a numeric value or a field containing a numeric value). The start time parameter cannot be more than 3 months ago and the duration parameter cannot be greater than 3 months.

The work schedule ID parameter specifies the relevant work schedule.

Example: working_hours.EffectiveEndTime(entity.ImpactStart, 7500000, entity.OwnedByPerson.WorkSchedule)

Note This function should be used only in fields and parameters that accept a date value in milliseconds (for example, DATE_TIME).
ClosedText functions
Function Description
substitute(text, old_text, new_text) Substitutes new_text for old_text in a text string.
length(text)

Returns the text length.

Example: The expression length('Hello world') returns 11.
substring(text, startldx, [length]) Returns the characters from the text beginning with startldx for the number of characters specified in [length]. If [length] is not entered, it returns all the characters until the end of the text.
match_pattern(text, pattern)

Returns true if the text matches the pattern. The pattern syntax is as follows:

? represents a single character

* represents any number of characters
split(text, [delimiter])

Returns a list of strings in the text separated by the delimiters. The default delimiter is a semicolon (;).

You can override the default by adding an additional optional delimiter parameter.

Example: The expression split('Alpha%Beta%Gamma', '%') returns Alpha, Beta, and Gamma.
ClosedPerson and group functions
Function Description
is_in_group(person_id, group_id) Returns true if the user entered exists in the group entered.
is_manager_of(person_id, employee_id, depth) Returns true if person_id is the manager of employee_id. Depth indicates the number of levels to search.
is_employee_of(person_id, manager_id, depth) Returns true if manager_id is the manager of person_id. Depth indicates the number of levels to search.
group_id_by_upn(upn)

Returns the ID of the group with the specified UPN.

Example: Return the group ID for the group with UPN Change_Manager_Group:

group_id_by_upn('Change_Manager_Group')

group_by_upn(upn) Returns the group object with the specified UPN.
filter_group_by_domains(group, domain list) Returns a collection of users from the group entered who have permission to view at least one of the domains in the data domain list.
filter_users_by_domains(user list, domain list) Returns a collection of users from the user list entered that are permitted to view at least one of the domains in the data domain list.
active_delegates_of_user(person_id)

Returns all users who are authorized to approve the tasks assigned to the person entered, related to parent records of any record type. The parameter must be a person ID.

Example: Return all the users authorized to approve the tasks of the assignee of the current record:

${active_delegates_of_user(entity.Assignee.Id)}

Any field of type person can be used for the parameter: entity.<person field>.Id.
on_call.<identifier>(group)

Returns the current on-call person or persons conforming to the identifier and group selection. The identifier may be one of:

  • Primary - Primary on-call person.

  • Backup1 - First backup on-call person.

  • Backup2 - Second backup on-call person.

  • AllUsers - Primary, first backup, and second backup on-call persons.

Example: The following returns the current Primary, first backup, and second backup on-call persons of the Service desk group.

${on_call.AllUsers(entity.ServiceDeskGroup)}

ClosedComments functions

The following table lists functions that are useful when working with comments of a record:

Function Description
comments_filtered(comments, filters)

Returns a collection of all comments which match the filters entered. The filters are key-value pairs such as ’PrivacyType’, ‘PUBLIC’. If no comments match the filters, an empty collection is returned.

Example: Return a collection of all PUBLIC comments added in this update:

comments_filtered(comments_added(current_update.Comments.OldValue, current_update.Comments.NewValue), 'PrivacyType', 'PUBLIC')

filter_comments(comments, filters, offset)

Returns the last comment which matches the filters entered. The filters are key-value pairs such as ’PrivacyType’, ‘PUBLIC’. If the record has no comments, returns null. If there are comments, but none of them match the filters, returns an empty collection.

The offset parameter is optional and refers to the index of the comment from the last one (e.g. 2 indicates the second to last comment). Default is 1.

Example: From the comments added in this update, return the last comment with Purpose equal to Request more information and To equal to User:

filter_comments(comments_added(current_update.Comments.OldValue, current_update.Comments.NewValue), 'FunctionalPurpose', 'RequestMoreInformation', 'CommentTo', 'User')

count(comments)

Returns the number of comments in the collection.

Example: Count the number of all comments added in this update:

count(comments_added(current_update.Comments.OldValue, current_update.Comments.NewValue))

extract_property(comment, property_name)

Returns the specified property of the comment. The comment parameter is a comment returned by a different function (e.g. filter_comments).

Example: Return the body of the last comment of this record:

extract_property (filter_comments (entity.Comments), ‘CommentBody’)

comments_added(current_update.Comments.OldValue, current_update.Comments.NewValue) Returns a list of the comments added in this update.
existing_comments_modified(current_update.Comments.OldValue, current_update.Comments.NewValue, oldCommentsNeeded, filters)

Returns a list of the comments that have been changed in this update.

Returns the old comments if oldCommentsNeeded is true; returns the new comments otherwise. Default is true.

The filters are the properties to ignore in the comparison.
ClosedIdentification functions for LDAP integration
Function Description

Identification.findBy(record type, field, data source)

or

Identification.identify(record type, field, data source)

Returns a record of the specified type that matches the field specified.

Example: To return a location record with the name Boston, enter the following phrase, where source.co contains the string Boston:

identification.findBy('Location', 'Name', source.co)

If the data source is a Service Management record, you can enter the value directly for the data source.

Example: To return a person record with the Upn test@hpe.com, enter the following phrase:

identification.identify('Person', 'Upn', 'test@hpe.com')

It is also possible to enter multiple sets of parameters.

Example: The phrase:

identification.identify('Person', 'Upn', 'test@hpe.com', 'Email', 'testEmail@hpe.com')

returns the person with the Upn field value of test@hpe.com and the Email field value testEmail@hpe.com.

Both functions take the same parameters and return the same results.

external://<external record type>/<external record ID>

This format can be used to refer to a record from external imported data. Both parameters can be either an Expression Language phrase or a string. Strings must be enclosed within single quote marks to comply with the Expression Language syntax.

Example: To refer to a person record from the LDAP server, enter the following phrase:

external://'ldapPerson'/source.manager

where source.manager contains the external ID of the record in the LDAP server.
ClosedLogical and mathematical expressions

The following table lists the available logical and mathematical operations in the Expression Language. The expressions constructed with these operations evaluate to a numeric or boolean value.

Operation Symbol
Or ||
And &&
Not !
Addition +
Subtraction -
Multiplication *
Division /
Modulo

%

Example: 15%4 returns 3 (15 modulo 4 equals 3)
Equal = or ==
Not Equal != or <>
Less Than <
Less Than or Equal <=
Greater Than >
Greater Than or Equal >=
ClosedObject property expressions

An object property expression is composed of an object, such as a record, followed by a property of the object.The expression can also include an additional property of the first property. The expression must conform to the following format:

object.property1.property2

For example, entity.Owner.Name would return the name property of the owner property of the given record.

The following table lists the available object property expressions in the Expression Language:

Syntax Output
entity Returns the record itself
entity.attribute_name

Returns the value of the specified attribute. The value can be a primitive or a record.

Examples:

  • entity.Urgency returns the value of the Urgency field of the current record.
  • entity.Status == 'Suspended' || entity.Status == 'Pending' returns a boolean value (true if the Status field of the current record equals either Suspended or Pending; false otherwise).
entity.relation_attribute_name.attribute_name

Returns the value of the specified attribute of the specified related record. The value can be a primitive or a record.

The relation_attribute_name is a property of the record, defined in its metadata.

Examples:

  • entity.OwnedByPerson.Id returns the ID of the set of people identified by the relationship OwnedByPerson (a one-to-many relationship) for the current record.
  • entity.OwnedByGroup.Upn returns the UPN of the owner group of the current record.
entity.relation_attribute_name.special_field

Returns the value of the specified field of the specified related record.

The relation_attribute_name is a property of the record, defined in its metadata.
entity.association_name Returns the collection of records related to the specified record by the specified relationship.
entity.association_name.attribute_name Returns the collection of values of the specified attribute for each of the related records, related by the specified relationship.
entity.association_name.special_field Returns the collection of values of the specified field for each of the related records, related by the specified relationship.
entity.path_name Returns the collection of records included on the specified path defined to a related record.
entity.path_name_attribute_name Returns the value of the specified attribute of the related record at the end of the specified path.
entity.path_name.special_field Returns the value of the specified field of the related record at the end of the specified path.

For records of type person, the following functions are available:

Syntax Output
<person>.IsPermitted(permissions, roles)

Returns true if the specified person has the specified permissions. (<person> represents a record of type person.)

  • The following examples use the IsPermitted function for specific permissions:

    • ${current_user.IsPermitted('EMS-View-Template(entityType= Request)')} returns true if the current user has permission to view records of type request; otherwise it returns false.
    • ${current_user.IsPermitted('EMS-Create-Template(entityType= Request)') returns true if the current user has permission to create records of type request; otherwise it returns false.
    • ${current_user.IsPermitted('EMS-Update-Template(entityType= Request)') returns true if the current user has permission to update records of type request; otherwise it returns false.

    You can combine multiple permissions in a single expression:

    ${current_user.IsPermitted('EMS- View -Template(entityType= Request), EMS- Update -Template(entityType= Request)') returns true if the current user has permission to view and to update records of type request. It returns false if he is lacking either of the permissions.

  • The following example uses the IsPermitted function for a specific role:

    ${current_user.IsPermitted(null, 'Service Portal Administrator')} returns true if the current user is assigned the Service Portal Administrator role; otherwise it returns false.

    Note When using the roles parameter only, make sure to enter null for the permissions parameter.
<person>.EntitlementRules

Returns a collection of the entitlement rule ID numbers for the entitlement rules that apply to the person.

For example:

    • current_user.EntitlementRules returns the ID numbers of the entitlement rules that apply to the current user.
    • entity.AssignedToPerson.EntitlementRules returns the ID numbers of the entitlement rules that apply to the assignee of the selected record.
<person>.EntitledServices

Returns a collection of the ID numbers for the service definitions that are available to the person, according to the entitlement rules defined for the service definition and its category.

For example: current_user.entitledServices returns the ID numbers of the service definitions that are available to the current user.

The following table lists some of the special fields available for the records:

Syntax Output
Id Returns the record's ID as a string.
Link Returns the link to the record as a string.
Type Returns the record type as a string.
PhaseId Returns the current phase of the record as a string.
MetaPhase Returns the current metaphase of the record as a string.
AllStakeholders Returns all the stakeholders of the record as a collection.
ActiveStakeholders Returns the active stakeholders of the record as a collection.

Related Topics Link IconRelated Topics