Action rule examples

The following examples demonstrate how to formulate rules for each of the action rule templates:

Add comment

1. For the comment parameter, select one of the following options:

   • Simple Mode. Enter the required text in the text box.
   • Expression Language. Enter an Expression Language phrase that returns the required text.

   Click the Expression Language button to toggle between these options. When the button is selected (green), the field is in Expression Language mode. When it is not selected (white), the field is in Simple mode. For a full list of Expression Language functions, see Expression Language functions and syntax.

2. For the System parameter, select current user to record the comment in the name of the current user or System to record the comment as a system comment.

3. For the visibility parameter, select public to make the comment available to all users on the Service Portal. Select internal to restrict the comment to Service Management users only. The default value is public.

4. For the purpose parameter, select a value from the drop-down list. This defines the purpose of the comment. The default value is StatusUpdate. This parameter is optional.

5. When the rule runs, the comment is added in the name of the selected user.

Example: There is a rule in Service Request Management under the After change process event, which adds a comment if the request was assigned to a person. The condition is defined by the following Expression Language phrase:

${current_update.AssignedToPerson.IsChanged == true && entity.AssignedToPerson != null}

It checks if the AssignedToPerson property has been changed and that the value is not null. If the condition is true, it adds the comment "Request has been assigned" as a system comment.

Add comment on related record

1. For the comment parameter, select one of the following options:

   • Simple Mode. Enter the required text in the text box.
   • Expression Language. Enter an Expression Language phrase that returns the required text.

   Click the Expression Language button to toggle between these options. When the button is selected (green), the field is in Expression Language mode. When it is not selected (white), the field is in Simple mode. For a full list of Expression Language functions, see Expression Language functions and syntax.

2. For the System parameter, select current user to record the comment in the name of the current user or System to record the comment as a system comment.

3. For the Record type parameter, select the record type of a related record from the drop-down list.

4. For the record ID parameter, select one of the following options:

   • Simple Mode. Select the required related records from the drop-down list.
   • Expression Language. Enter an Expression Language phrase that returns the required related records.

   Click the Expression Language button to toggle between these options. When the button is selected (green), the field is in Expression Language mode. When it is not selected (white), the field is in Simple mode. For a full list of Expression Language functions, see Expression Language functions and syntax.

5. For the from and to parameters, select Agent or User as appropriate. These parameters are optional and are only available if current user was selected for the System parameter.
6. For the visibility parameter, select public to make the comment available to all users on the Service Portal. Select internal to restrict the comment to Service Management users only. The default value is public. This parameter is optional.
7. For the purpose parameter, select a value from the drop-down list. This defines the purpose of the comment. The default value is StatusUpdate. This parameter is optional.

8. When the rule runs, the comment is added to the selected related records in the name of the selected user.

Append or Remove values in a multi-value field

1. For the action parameter, select the required action from the drop-down list. The available options are:

   • Append to. Add an additional value to a multi-value field.
   • Remove from. Remove a value from a multi-value field.
2. For the field parameter, select the required multi-value field from the drop-down list.

3. For the values parameter, select one of the following options:

   • Simple Mode. Select the required value from the drop-down list.
   • Expression Language. Enter an Expression Language phrase that returns the required value.

   Click the Expression Language button to toggle between these options. When the button is selected (green), the field is in Expression Language mode. When it is not selected (white), the field is in Simple mode. For a full list of Expression Language functions, see Expression Language functions and syntax.

4. When the rule runs, it adds the additional value to the field or removes the selected value from the field as specified.

Example: There is a rule in Service Request Management which adds the Primary data domain of the request's Service desk group to the Data domains field of the request. The expression parameter checks if the Service Desk Group field of the request has been changed and verifies that the Primary data domain property of the Service Desk Group field is not null. The action parameter is Append to and the field parameter is Data domains. For the values parameter the Primary data domain property of the Service Desk Group field is denoted by the following Expression Language phrase:

${entity.ServiceDeskGroup.PrimaryDataDomain}.

Create record

1. For the Record type parameter, select the required type of record from the drop-down list.

2. For the fields values parameter, click the Add Item button, which displays two boxes, one for a field name and one for its value. In the first box, select the required field name from the drop-down list. In the second box, select one of the following options:

   • Simple Mode. Enter the value for the selected record field manually or select it from a drop-down list, according to the value type.
   • Expression Language. Enter an Expression Language phrase that returns the value for the selected record field.

   Click the Expression Language button to toggle between these options. When the button is selected (green), the field is in Expression Language mode. When it is not selected (white), the field is in Simple mode. For a full list of Expression Language functions, see Expression Language functions and syntax.

   Click Add Item again to add another row and select or enter the required record field and value. Repeat this for all required record fields.

3. When the rule runs, it creates a record of the selected type and fills the parameters with the specified values.

Example: In Incident Management, you can define a rule called CreateIncident which creates a new incident record. For the Record type parameter, select Incident. For the fields values parameter, enter the following pairs of field names and values (select the field name from the drop-down list and enter the text or Expression Language phrase in the value box):

• Description, ${concat('Automatically created incident for', entity.Description)}
• DisplayLabel, ${concat('Automatically created incident for', entity.DisplayLabel)}
• ImpactScope, SingleUser
• Urgency, SlightDisruption
• RegisteredForActualService, ${entity.Id}

When the rule runs, it creates a new incident record and populates these fields with the respective values.

Create record and relationship

1. For the fields values parameter, click the Add Item button, which displays two boxes, one for a field name and one for its value. In the first box, select the required field name from the drop-down list. In the second box, select one of the following options:

   • Simple Mode. Enter the value for the selected record field manually or select it from a drop-down list, according to the value type.
   • Expression Language. Enter an Expression Language phrase that returns the value for the selected record field.

   Click the Expression Language button to toggle between these options. When the button is selected (green), the field is in Expression Language mode. When it is not selected (white), the field is in Simple mode. For a full list of Expression Language functions, see Expression Language functions and syntax.

   Click Add Item again to add another row and select or enter the required record field and value. Repeat this for all required record fields.

2. For the relationship type parameter, select the required field from the drop-down list.

3. When the rule runs, it creates a new record and fills the parameters with the specified values (the record type depends on the relationship selected). It also creates the selected type of relationship between the new record and the specified existing record.

Create relationship

1. For the relationship type parameter, select the required field from the drop-down list.

2. For the from record and to record parameters, select one of the following options:

   • Simple Mode. Select the required record from the drop-down list.
   • Expression Language. Enter an Expression Language phrase that returns the required record.

   Click the Expression Language button to toggle between these options. When the button is selected (green), the field is in Expression Language mode. When it is not selected (white), the field is in Simple mode. For a full list of Expression Language functions, see Expression Language functions and syntax.

3. When the rule runs, it creates the specified relationship between the specified records.

Example: You can define a rule called AddUserToUsedByList which adds the current user to the Used by list. For the relationship type parameter, enter DeviceUsedByPerson. For the from record parameter, enter ${entity.Id} and for the to record parameter, enter ${current_user.Id}.

Delete relationship

1. For the relationship type parameter, select the required field from the drop-down list.

2. For the from record and to record parameters, select one of the following options:

   • Simple Mode. Select the required record from the drop-down list.
   • Expression Language. Enter an Expression Language phrase that returns the required record.

   Click the Expression Language button to toggle between these options. When the button is selected (green), the field is in Expression Language mode. When it is not selected (white), the field is in Simple mode. For a full list of Expression Language functions, see Expression Language functions and syntax.

3. When the rule runs, it deletes the specified relationship between the specified records.

Example: You can define a rule called DeleteUserFromUsedByList which deletes the current user from the Used by list. For the relationship type parameter, enter DeviceUsedByPerson. For the from record parameter, enter ${entity.Id} and for the to record parameter, enter ${current_user.Id}.

Delete all relationships of one type

The only parameter in this rule is relationship type. Select the required field from the drop-down list. When the rule runs, the many-to-many relationships of the selected type are deleted.

Example: In Service Asset and Configuration Management, for a device, you could select User list as the relationship type to be deleted. This deletes all the relationships between the device and associated users.

Notify users in Service Portal

1. For the recipients parameter, click Add item and select one of the following options:

   • Simple Mode. Select the required recipient from the drop-down list.
   • Expression Language. Enter an Expression Language phrase that returns the required recipient.

   Click the Expression Language button to toggle between these options. When the button is selected (green), the field is in Expression Language mode. When it is not selected (white), the field is in Simple mode. For a full list of Expression Language functions, see Expression Language functions and syntax.

   If you are entering multiple recipients, click Add item to add another recipient box.

2. For the notificationBody parameter, enter the text of the message in the text box.

3. When the rule runs, a popup message appears in the Service Portal for the specified recipients.

Example: There is a global rule in Service Request Management that notifies the people defined as the requested for and requested by parties for a request when the request solution or completion code is changed. The message that pops up in the Service Portal states that a new solution was added.

Reset task plan

The only parameter in this rule template is record field. Select the required field from the drop-down list. The execution for the task plan stored in the selected field is reset. When the workflow enters the phase, the task plan runs from the beginning.

Example: In Change Management, select the TasksExecutionPlanApproveDeployment field. The task plan contained in that field is reset and the task can run again when the workflow re-enters the phase.

Save approval plan to record

1. For the approval plan parameter, enter the name of the required out-of-the-box fulfillment plan, as defined in Service Catalog Management.

2. For the field parameter, select the required field from the drop-down list.

3. When the rule runs, the task flows contained in the selected fulfillment plan are stored in the specified field of the current record.

Example: There is a rule in Change Management called GLAForEmergencyGenerateExecutionPlan which stores the task flows contained in the ECAB fulfillment plan in the TasksExecutionPlanECAB field of the current change record.

Send notification

1. For the recipients parameter, select one of the following options:

   • Simple Mode. Select the required recipient from the drop-down list.
   • Expression Language. Enter an Expression Language phrase that returns the required recipient.

   Click the Expression Language button to toggle between these options. When the button is selected (green), the field is in Expression Language mode. When it is not selected (white), the field is in Simple mode. For a full list of Expression Language functions, see Expression Language functions and syntax.

   If you are entering multiple recipients, click Add item to add another recipient box.

   You can also add external email addresses for recipients who are not in the system. Follow these steps:

   1. Define a new field in the Fields tab, for example ExternalEmail.
   2. Add the field to a form in the Forms tab and enter an external email address in the field. If you enter multiple addresses, they must be separated by semicolons.
   3. In the business rule recipients parameter, select Expression Language and enter: ${split(entity.ExternalEmail_c)}. (The split function is required to parse the semicolon separated email addresses.)

2. For the template parameter, select a notification template from the drop-down list.

3. For the parameters parameter, for each parameter, select one of the following options:

   • Simple Mode. Enter the template parameter value manually.
   • Expression Language. Enter an Expression Language phrase that returns the required template parameter value.

   Click the Expression Language button to toggle between these options. When the button is selected (green), the field is in Expression Language mode. When it is not selected (white), the field is in Simple mode. For a full list of Expression Language functions, see Expression Language functions and syntax.

   This parameter is optional.

4. When the rule runs, a notification based on the specified template with the specified parameters is sent to the specified recipients.

Example: There is a rule in Change Management called SendNotificationToServiceOwner, which sends a notification based on the ChangeHasBeenOpened template (with no parameters) to the record owners denoted by the following Expression Language phrase:

${entity.AffectsService.Owner}, ${entity.IsOwnedByPerson}

Send notification to all reviewers

1. For the template parameter, select a notification template from the drop-down list.

2. For the parameters parameter, for each parameter, select one of the following options:

   • Simple Mode. Enter the template parameter value manually.
   • Expression Language. Enter an Expression Language phrase that returns the required template parameter value.

   Click the Expression Language button to toggle between these options. When the button is selected (green), the field is in Expression Language mode. When it is not selected (white), the field is in Simple mode. For a full list of Expression Language functions, see Expression Language functions and syntax.

3. This rule is similar to the Send notification business rule, but the list of recipients is not editable. When the rule runs, a notification based on the specified template with the specified parameters is sent to all the reviewers.

   This rule is relevant in Knowledge Management. The reviewers are defined in Service Request Management.

Send notification to related people

1. For the template parameter, select a notification template from the drop-down list.

2. This rule is similar to the Send notification business rule, but the list of recipients is not editable. When the rule runs, a notification based on the specified template is sent to all the related people.

   This rule is relevant for Idea records. The related people are determined by matching keywords in their Service Portal profile with words in the Idea record content.

Send notification to release owner

1. For the template parameter, select a notification template from the drop-down list.

2. For the phase parameter, select a phase from the drop-down list.

3. This rule is similar to the Send notification business rule, but the list of recipients is not editable. The rule sends a notification based on the specified template to the release owner when the record workflow reaches the specified phase.

Send comment notification

1. For the recipients parameter, select one of the following options:

   • Simple Mode. Select the required recipient from the drop-down list.
   • Expression Language. Enter an Expression Language phrase that returns the required recipient.

   Click the Expression Language button to toggle between these options. When the button is selected (green), the field is in Expression Language mode. When it is not selected (white), the field is in Simple mode. For a full list of Expression Language functions, see Expression Language functions and syntax.

   If you are entering multiple recipients, click Add item to add another recipient box.

   When you select a recipient, the parameter is represented by an avatar icon .

   If you do not enter a value, the notification will be sent to all stakeholders and previous comment submitters.

2. For the template parameter, select a notification template from the drop-down list.

3. For the parameters parameter, for each parameter, select one of the following options:

   • Simple Mode. Enter the template parameter value manually.
   • Expression Language. Enter an Expression Language phrase that returns the required template parameter value.

   Click the Expression Language button to toggle between these options. When the button is selected (green), the field is in Expression Language mode. When it is not selected (white), the field is in Simple mode. For a full list of Expression Language functions, see Expression Language functions and syntax.

   This parameter is optional, depending on the selected template.

4. When the rule runs, a notification based on the specified template with the specified parameters is sent to the specified recipients. The comments from the relevant record are inserted into the notification.

Send meeting invitation

1. For the recipients parameter, click Add item and select one of the following options:

   • Simple Mode. Select the required recipient from the drop-down list.

   • Expression Language. Enter an Expression Language phrase that returns the required recipient.

   Click the Expression Language button to toggle between these options. When the button is selected (green), the field is in Expression Language mode. When it is not selected (white), the field is in Simple mode. For a full list of Expression Language functions, see Expression Language functions and syntax.

   If you are entering multiple recipients, click Add item to add another recipient box.

2. For the canceled recipients parameter, click Add item and select one of the following options:

   • Simple Mode. Select the required recipient from the drop-down list.

   • Expression Language. Enter an Expression Language phrase that returns the required recipient.

   If you are entering multiple recipients, click Add item to add another recipient box.

   Note The recipients and canceled recipients parameters are optional parameters, but one of them must be defined.

3. For the start parameter, select one of the following options:

   • Simple Mode. Select a record field from the drop-down list to indicate the start date and time of the meeting.

   • Expression Language. Enter an Expression Language phrase that returns the start date and time of the meeting.

4. For the end parameter, select one of the following options:

   • Simple Mode. Select a record field from the drop-down list to indicate the end date and time of the meeting.

   • Expression Language. Enter an Expression Language phrase that returns the end date and time of the meeting.

5. For the Busy parameter, select a value from the drop-down list. The available options are Busy and Free.

6. When the rule runs, it sends a meeting invitation to the designated recipients and a cancellation to the canceled recipients. The meeting appears in their Outlook calendar at the specified date and time with the specified status.

Set field

1. For the field parameter, select the required field from the drop-down list.

2. For the value parameter, select one of the following options:

   • Simple Mode. Enter or select the required value.
   • Expression Language. Enter an Expression Language phrase that returns the required value.

   Click the Expression Language button to toggle between these options. When the button is selected (green), the field is in Expression Language mode. When it is not selected (white), the field is in Simple mode. For a full list of Expression Language functions, see Expression Language functions and syntax.

3. When the rule runs, the selected field is assigned the entered value.

Example 1: There is a rule in Change Management called SetHighPriority which assigns the value High Priority to the Priority field.

Example 2: There is a rule in Change Management called SetIsRequestedByPerson, with IsRequestedByPerson as the field and the Expression language phrase ${current_user} as the value. The rule assigns the person returned by current_user to the IsRequestedByPerson field.

Set field based on routing definition

1. For the field parameter, select the required group type field from the drop-down list.

2. For the routing definition name parameter, select the required routing definition from the drop-down list.

3. For the parameters parameter, there is one parameter for each lane of the routing definition. For each parameter, enter an Expression Language phrase that returns the required value. For a full list of Expression Language functions, see Expression Language functions and syntax.

4. When the rule runs, the selected group field is assigned the value calculated based on the path defined in the selected routing definition.

For an example of the business rule, see Routing definition use case - setting a field value.

Set fields on related records

1. For the record type parameter, select the required type of record from the drop-down list.

2. For the record names parameter, click the Add Item button, and select one of the following options:

   • Simple Mode. Select the required record from the drop-down list of related records.
   • Expression Language. Enter an Expression Language phrase that returns a related record of the selected type.

   Click Add item to add a box for another record.

3. For the fields values parameter, click the Add Item button, which displays two boxes, one for a field name and one for its value. In the first box, select the required field name from the drop-down list. In the second box, select one of the following options:

   • Simple Mode. Enter or select the required values according to the type of field.
   • Expression Language. Enter an Expression Language phrase that returns a value of the required type.

   Click the Expression Language button to toggle between these options. When the button is selected (green), the field is in Expression Language mode. When it is not selected (white), the field is in Simple mode. For a full list of Expression Language functions, see Expression Language functions and syntax.

   Click Add item to add a box for another field.

4. When the rule runs, the specified fields of the related records are assigned the entered values.

Example: There is a rule in Change Management called updateSubcategoriesLevel1ParentName, with ITProcessRecordCategory as the record type. The record ids are given by the Expression Language phrase ${entity.CategoryHasLevel1Children.Id} and the record values are given by the phrase ${entity.DisplayLabel}. The rule assigns the values returned by the latter Expression Language phrase to the fields of the record returned by the former phrase.

Set multiple fields

1. For the fields values parameter, click the Add Item button, which displays two boxes, one for a field name and one for its value. In the first box, select the required field name from the drop-down list. In the second box, select one of the following options:

   • Simple Mode. Enter the value for the selected record field manually or select it from a drop-down list, according to the value type.
   • Expression Language. Enter an Expression Language phrase that returns the value for the selected record field.

   Click the Expression Language button to toggle between these options. When the button is selected (green), the field is in Expression Language mode. When it is not selected (white), the field is in Simple mode. For a full list of Expression Language functions, see Expression Language functions and syntax.

   Click Add Item again to add another row and select or enter the required record field and value. Repeat this for all required record fields.

2. When the rule runs, the selected fields are assigned the specified values.

Survey notification

1. For the Survey name parameter, select a survey from the drop-down list.

2. For the recipients and groups parameters, click Add item to add a row and select one of the following options:

   • Simple Mode. Select the required recipient or group from the drop-down list.

   • Expression Language. Enter an Expression Language phrase that returns a value of the required type.

   Click the Expression Language button to toggle between these options. When the button is selected (green), the field is in Expression Language mode. When it is not selected (white), the field is in Simple mode. For a full list of Expression Language functions, see Expression Language functions and syntax.

   Click Add item to add a box for another field.

   Note It is not necessary to enter a value for both parameters. Enter or select a value for at least one recipient or at least one group.

3. For the number of times parameter, enter an integer.

4. For the template parameter, select a survey notification template from the drop-down list.

5. For the parameters parameter, for each parameter, select one of the following options:

   • Simple Mode. Enter or select the required values according to the type of field.

   • Expression Language. Enter an Expression Language phrase that returns a value of the required type.

   Click the Expression Language button to toggle between these options. When the button is selected (green), the field is in Expression Language mode. When it is not selected (white), the field is in Simple mode. For a full list of Expression Language functions, see Expression Language functions and syntax.

   Some templates have no parameters.

6. When the rule runs, the selected survey is sent to the selected recipients and groups using the selected survey notification template.

Example: If there is a survey called User satisfaction survey, you can define a rule in Service Request Management to send a notification to the Requested for user when a request is closed. You can configure the rule to send a survey once every 5 times it runs to reduce the number of mails sent to users. The rule sends the user a notification every 5 times the rule runs, using the Survey default template (with no parameters) with a link to the User satisfaction survey.

Execute REST

For information on this business rule, see REST Execution.

Send ChatOps notification

Per schedule rules

For the Per schedule process event, all the available rules have additional parameters related to the scheduling of the rule. Furthermore, only the Simple rule option is available. However the rule template includes an Execution condition parameter which enables you to define a conditional rule.

Select one of the following options to define a Per Schedule rule:

• Calculated timer schedule. Define a rule to run at a specific time.

  Follow these steps to define the rule:

  1. For the Execution date parameter, enter an Expression language phrase specifying a date and time.

  2. For the Execution condition parameter, enter an Expression Language phrase that returns a boolean value. This serves as the condition for scheduling the rule. If you want to define a simple rule (with no condition), enter an expression that is always true (for example, ${true}).

  3. For the Runtime condition parameter, enter an Expression Language phrase that returns a boolean value. This serves as the condition for running the rule.

  4. If the Execution condition is satisfied, the rule is scheduled to run at the time specified in the Execution date. If the Runtime condition is satisfied at the specified time, the rule is run. If no value is entered for the Runtime condition, the Execution condition is verified again; if it is satisfied, the rule is run.

  Note  

  • If the Execution date parameter returns a negative value, the business rule is not scheduled to run.
  • After the rule has run once at the specified time, it continues to run at the next specified time according to the Expression language phrase, when the workflow is executed.

  Example: You can define a Per schedule rule in Contract Management as follows:

  If ${entity.EndDate != null} is true, schedule execution at ${first_non_empty_value(entity.EndDate,0) + 24*60*60*1000} Set PhaseId to Close.

  If the EndDate field of the contract is not empty, the execution is scheduled to take place 24 hours after the end of the contract. (No runtime condition is defined for this rule.)

  Example: You can define a rule with the following execution condition:

  ${current_update.EmployeeStatus.IsChanged && (current_update.EmployeeStatus.NewValue == 'Inactive' || current_update.EmployeeStatus.NewValue == 'Retired' || current_update.EmployeeStatus.NewValue == 'Terminated')}

  and the following runtime condition:

  ${entity.EmployeeStatus == 'Inactive' || entity.EmployeeStatus == 'Retired' || entity.EmployeeStatus == 'Terminated'}

  If the Employee status is changed to Inactive, Retired, or Terminated, the rule is scheduled to run at the execution time. The runtime condition checks the Employee status again at the execution time; if it is still one of those values, the rule runs. This provides an additional status check before executing the rule.

• Fixed timer schedule. Define a rule to run on a recurring basis.

  Follow these steps to define the rule:

  1. For the Initial timeout parameter, enter a numeric value.

  2. For the Initial timeout units parameter, enter a time unit (hours or days).

  3. For the Recurrence time parameter, enter a numeric value.

  4. For the Recurrence time units parameter, enter a time unit (hours or days).

  5. For the Execution condition parameter, enter an Expression Language phrase that returns a boolean value. This serves as the condition for a conditional rule. If you want to define a simple rule (with no condition), enter an expression that is always true (for example, ${true}).

  6. When the rule is enabled, the rule is implemented every x recurrence time units from the time that the entity has been in the current phase/metaphase/process for time specified in the initial timeout parameter.

  Note In out-of-the-box rules, the Initial timeout units and Recurrence time units parameters can be in minutes or seconds in addition to hours or days.

  Example: The following rule in Tasks is defined as Per schedule:

  After the record is in this phase for 48 hours, then every 48 hours, if ${(entity.ActualStartTime != null) && (entity.PhaseId != 'Completed' && entity.PhaseId != 'Cancel')} Send notification to ${entity.Assignee.Id}

  The Initial timeout parameter is 48. The Initial timeout units parameter is hours. The Recurrence time parameter is 48 and the Recurrence time units parameter is hours. The Execution condition parameter is ${(entity.ActualStartTime != null) && (entity.PhaseId != 'Completed' && entity.PhaseId != 'Cancel')}.

  After an initial wait of 48 hours (2 days), if the condition is satisfied, the rule sends a notification to the record's assignees every 48 hours.

Related topics

• Processes and Rules

• Record Management business rules

• Business rule descriptions and tags

• Validation rule examples

• Rendering rule examples

• Field selection rule examples

• REST Execution

• Record Management - use case

• How to add a business rule

• How to edit, remove, or disable a business rule

• Enrichment rules