Expression Examples

Expression	Description
$(FieldName)	Refers to the field of the current business object. See Constructing Expressions.
$(CurrentLoginID())	Invokes a built-in function. See Built-in Functions.
$("9"+[link:ProfileLink]Phone1)	Returns a phone number from a related object prefixed by a number 9. See Constructing Expressions for more information.
$(Prompt("Enter Customer Notes", ""))	Invokes a built-in function, $prompt ("prompt message", validation_list_name) (message), with literal constants as arguments. See Built-in Functions.
$(GetNextCounter("IncidentNumberCounter"))	In an initialization business rule, this expression adds a counter, incrementing the incident number. See Built-in Functions.
$(HopTargetDate("9 to 5", CreatedDateTime, "7"))	Invokes a built-in function with a mix of literal constants ("9 to 5" and 7) and field references (CreatedDateTime) as arguments. See Constructing Expressions and Constructing Expressions for more information.
$([Profile#Employee.]FirstName + [Profile#Employee.]LastName)	Returns the first and last name from the employee profile. See Constructing Expressions for more information.   If there is no additional field name after the period in [Profile#Employee.], there is a one to one relationship. If there is a field name, there is a one to many relationship. See Constructing Expressions for more information.
$(SearchHierarchy("OrganizationalUnit", "ServiceAgreement", OrgUnitLink_RecID, "$((ServiceLink == [OtherObject]Service_Valid)&& (Status == \"Published\"))", Service_Valid))
$([OtherObject]PrimaryEmail)	Returns a pick list, OtherObject, in reference to the PrimaryEmail object.   The editing business rule: AlternateContactEmail = $([OtherObject]PrimaryEmail) makes use of this expression. In both examples, OtherObject is the object in the named pick list used in the editing rule (in this case, Profile.Employee).
$(iif((Status == "Closed"), CurrentUserDisplay Name(), null ))	This conditional expression states that if a status is closed, the CurrentLoginID value is returned. For example, this editing business rule can be applied to record the user who set an incident status to Closed. null is a reserved keyword that can be used in expressions along with literal constants, fields, and functions.

To reference a field within a business object, such as an incident, enclose the name of the field using the HEAT expression syntax.

$(<FieldName>)

For example, to reference the Service field in an incident, use the syntax:

$(Service)

You can use this syntax in the following rule that sets the ActualService field to the value of the Service field in an incident whenever the latter field is changed, as shown in the following example:

Referencing a Field within a Business Object Example

To access a field that is referenced by a link in a business object, use the following syntax:

$([link:<LinkField>]<FieldName>)

For example, the OrgUnitLink field in the incident business object points to a corresponding organizational unit record. To reference the value of the Name field of the organizational unit record by means of the OrgUnitLink field, use the following expression:

$([link:OrgUnitLink]Name)

You can use this syntax in the following editing rule, to set the organization unit ID of the incident:

Accessing a Field Referenced by a Link Example

When creating editing rules, to access a field from a validated business object whenever the current validated field is updated, use the following syntax:

$([OtherObject]<FieldName>)

For example, if you are in an incident and want to access the TeamEmail value for the OwnerTeam currently set for the incident record, ensure that the OwnerTeam field in the incident is configured to be validated. In this example, the OwnerTeam field in the incident is validated using the named validation list Team of StandardUserTeam used in Incident.

Accessing a Field from a Validated Business Object Example 1

With the OwnerTeam field validation in place, you can then define an editing rule against the OwnerTeam field in the incident, so that when this field is changed, the rule returns the field value of the validated business object (that is, the OtherObject). See the following example:

Accessing a Field from a Validated Business Object Example 2

Use the following syntax to reference a related business object:

$([TableRef#.]<FieldName>)

$([TableRef#InternalReferenceName.]<FieldName>)

You can only use this type of expression for one-to-one or many-to-one relationships. That is, the expression expects to find at the most one matching child record for the corresponding relationship.

Instead of referencing the relationship by name, use the TableRef for the child business object instead.

• For regular business objects, the TableRef is of the form [<BusinessObject>#.], for example, [Problem#.].
• For group member business objects, the TableRef is of the form [GroupObject#MemberObject.], for example, [Profile#Employee.].

Notice the "#" and "." characters. The "#" character separates the name of the group object from the member object.

Use this type of syntax in the form editor to bring in values from the related business object (for example, the EmployeeLocation field, from the Profile.Employee business object):

Accessing a Value from a Related Business Object Example 1

In this example, the field name is represented as

$([Profile#Employee.]EmployeeLocation)

There are times however, when there is more than one relationship between the same parent and child business objects (for example, incident to employee). In such cases, the Internal Reference Name property of the relationship is used to distinguish between the relationships. This parameter is then specified after the "." character, as shown in the example expression.

For example, the Reported By information in an incident comes from the IncidentAssociatedByAlternateContact relationship, which has an Internal Reference Name value of Reverse:

Accessing a Value from a Related Business Object Example 2

To reference a field in Profile.Employee using this alternate relationship, use the following syntax:

$([Profile#Employee.Reverse]PrimaryEmail)

Notice that Reverse (the internal reference name for the relationship) is specified after the "." character, immediately after the TableRef (Profile#Employee).

To define a constrained validation list, use the following syntax within the context of the named validation list definition:

$([ValidationList]<FieldName>)

Typically the values from one validated field are constrained based on the value of another field in the same object. For example, the JobTitle field in the Profile.Employee business object is constrained based on the value of the department selected for the employee.

To define such a validation list, in the Constraints area, enter the following syntax:

ValidationObject.FieldName Equal to $([ValidationList]<FieldName>)

Defining a Constrained Validation List Example

In this example, the fields on the left come from the validation business object. The object is JobTitle (as indicated in the Get list data from drop-down menu).

The $([ValidationList]Department) expression references the field from the business object, which utilizes this named validation list. In this case, the named validation list is employee business object.

With this configuration, the job titles that can be selected for the employee are based on the department value that was previously selected. The department value from the employee is then used to determine the job title records with the same department name and return the constrained results accordingly.

To share the named validation list across other business objects, use the $([ValidationList]FieldName) syntax (instead of $(FieldName)). For example, if there is a new customer business object that needs to implement the same constrained validation list, use the same named validation list for that object.

 

 

For more information about the Prompt() function, see Built-in Functions.

You can use the Prompt() function in the context of the update quick action to ask the user to fill out a value for a field in the business object. This is typically used when the underlying field is also validated.

$(Prompt(<Title in prompt>, ""))

$(Prompt(<Title in prompt>, <Named validation list>))

There are two variations of the Prompt() function:

• If the second parameter is an empty string, you can enter any value for the field.
• If the second parameter is a text value, the system assumes that this value is the named validation list and uses it to constrain the allowable values that you can enter for the field.

 

Prompt to Update the Owner Team of an Incident Record

The following Prompt() function updates the owner team of the incident record:

$(Prompt("Incident Owner Team", "Team of StandardUserTeam used in Incident"))

The following example shows the syntax in the existing Reassign Owner Team quick action in incident:

Prompting for a Value in a Quick Action Example

Prompt to Create a Business Object

The following Prompt() function is used in the Social Board workspace to create a business object from the Social Board.

$(Prompt("Summary", "", 350, 25, "", "", "_ConversationTitle_"))

$(Prompt("Description", "", 400, 200, "", "", "_ConversationContent_"))

 

• The first parameter, "_ConversationTitle_", includes the original post in the Summary field.
• The second parameter, "_ConversationContent_", includes the original post along with all the comments in the Description field.
• A prompt for a summary and description are displayed, with an empty text area 340 pixels in width and 25 pixels in height, for the Summary field and an empty text area 400 pixels in width and 200 pixels in height for the Description field.

 

Like most programming languages, the HEAT system supports conditional expressions using the iif expression. (Note that there are two "i" characters in iif). The syntax is:

$(iif(<condition>, <value when condition is true>, <value when condition is false>))

This expression has three parameters: the first is the condition, the second parameter is the value to return if the condition is true,and the third parameter is value to return if the condition is false.

This conditional expression is used in various locations in HEAT. For example, the following expression return false if the incident status has a value of Logged. Otherwise, it returns a value of true:

$(iif((Status == "Logged"), false, true))

The return value of this conditional expression can then be used, for example, to determine when the owner field in incident is mandatory (that is, when the status has a value other than logged):

Owner is required when $(iif((Status == "Logged"), false, true ))

You can nest iif expressions within one another, so that the return value of one iif expression feeds into another expression.

In such cases, note that the HEAT expression syntax $() applies to the outermost expression.  You do not need to use the $() syntax anywhere within the nested expression.

 

 

 

Applying a read-only control is a common use of conditional expressions. Another example is in the default change approval form, with this expression applied to the read-only expression control:

iif( ((Status == "Closed") || (Status == "Denied")), true, )

If the status is closed, the item becomes read-only.

The following is a more complex example of a conditional expression. It is in a default incident editing rule and specifies the priority change to make when the urgency and impact fields are changed:

$(iif(((Urgency == "High") && (Impact == "High")),

"1",

iif((((Urgency == "High") && (Impact == "Medium")) || ((Urgency == "Medium") && (Impact == "High"))),

"2",

iif(((((Urgency == "High") && (Impact == "Low")) || ((Urgency == "Medium") && (Impact == "Medium"))) || ((Urgency == "Low") && (Impact == "High"))),

"3",

iif((((Urgency == "Medium") && (Impact == "Low")) || ((Urgency == "Low") && (Impact == "Medium"))),

"4",

"5"

             )

         )

     )

))

In this case, each combination of urgency and impact field values specifies the priority level from 1 to 5.