Business Rules


In a Nutshell

Note: This tab is only available to users with account holder credentials.

It is here where you can create event-based business rules. When the predefined conditions have been met, the application will respond by completing the specified action.

The primary ingredients of a business rule is the Trigger/Action argument, which can be summarized as follows:

Trigger

It is in this section that you define the data object type, the conditions, variables, and constraints for the business rule. When these conditions are met, the application will respond by generating the output and action specified in the Action section.

Action

It is in this section that you define the application response to the conditions specified in the Trigger section.

Example

For instance, if you have specified in the When section an Event occurring On Object Create for a Service Call, in the Action section you can then select Action and Send SMS and have the notification sent to a specific recipient.


Sample Business Rules

The Admin module comes with sample business rules. These can be copied and modified as needed.

The main purpose for these sample business rules is to show how business rules are constructed, how variables and conditions can be structured to direct behavior (Trigger), and how to shape the action triggered when the conditions are met, such as in a Checklist Attachment, Email Notification, ERP Synchronization Approval, or SMS Notification (Action).

It is recommended that you acquaint yourself with these sample business rules in order to more quickly begin creating business rules of your own.

A Closer Look

When you navigate to the Business Rules tab, you will see the following information:


Creating Business Rules

There are currently two types of supported business rules:

Type Description
Type One Existing business rules are Type One business rules. This type of business rule supports multi-level business object reference (example: activity.businessPartner.name). However, this type of business rule does NOT support JavaScript functions.
Type Two Type Two business rules offer full JavaScript support.

When creating a new business rule you will enter the following information:


Event

This aspect occurs during the Trigger of the business rule, and refers to the CRUD-based (Create, Update, Delete) events that impact an Object (for more information on the supported Data Objects, refer to the Data Object Table section below).

You can select from the following events that triggers the business rule:



Event Description
On Object Create If selected, the business rule will be triggered on the creation of a new object.
On Object Create or Update* If selected, the business rule will be triggered on either the creation of a new object or the update/modification of an existing object.
On Object Update* If selected, the business rule will be triggered on the update/modification of an existing object.
On Object Update or Delete* If selected, the business rule will be triggered when an existing object is updated or deleted.
On Object Delete If selected, the business rule will be triggered when an existing object is deleted.
On Object Upload from ERP Connector If selected, the business rule will be triggered when object data (Business Partner, etc) is uploaded using an ERP Connector.
On Object Upload Create from ERP Connector If selected, the business rule will be triggered when object data (Business Partner, etc) is uploaded/created using an ERP Connector.
On Object Upload Update from ERP Connector If selected, the business rule will be triggered when object data (Business Partner, etc) is uploaded/updated using an ERP Connector.
On Object Upload Update from Crowd If selected, the business rule will be triggered when object data (Business Partner, etc) is uploaded/updated from the SAP Field Service Management Crowd platform.
Scheduled If selected, the business rule will be set to run at the specified time.
On FSM Event On FSM Event is related to a new event-based infrastructure which is currently under development. The idea is that every service can publish events and a businss rule can be triggered by it.
  • Please note that in case an activity update is triggered by a service assignment modification, the business rule linked to the activity will not be triggered.

Note on FSM Event Trigger for ChecklistInstanceChanged

After a checklist is completed the checklistInstanceElements are generated - but this happens asynchronously and therefore after the checklistInstance was updated. To trigger a business rule only after all checklistInstanceElements are generated you can use the trigger FSM Event with the event ChecklistInstanceChanged. A predefined variable fsmEvent holds the information about the checklistInstance e.g. ${fsmEvent.checklistInstanceId}.




Variables

Next is the Variables aspect is used to provide additional information related to the selected object.

By selecting the Variables option, the application will then show you predefined variables and allow you to define new ones.


Access User and Company Settings as Variables in Business Rules

It is possible to access the company or a users settings within a business rule.

The settings are accessed through the variables ${company.settings} and ${user.settings}.

The company settings can be found in Admin by navigating to Account > Company > Company Settings.



The user settings are displayed in Admin navigating to Account >User > User Settings.



Example for retrieving the language of the user set in the web application:

${user.settings.Cockpit_SelectedLanguage.data}


Using a Value for Counting with Variable

A value can be used to create a count by using the variable type Value and writing the query in “Advanced Mode” () as in the following example:

Note Only variable-type array can be used in advanced mode.



The following query could then be used to return a count:

SELECT COUNT(DISTINCT p.id)  FROM ServiceCall sc JOIN ServiceAssignment sa ON sa.object.objectId = sc.id JOIN Person p ON p.id = sa.technician WHERE  sc.id = ${sc.id}
ServiceCall.21;Person.19;ServiceAssignment.24

Conditions

Next, in the Conditions aspect you can then set additional conditions required to trigger the business rule. These can be selected from the dropdown menu or entered manually.

The following is an example of a condition created using the built-in operators:


Scheduled Business Rules

Business rules allow you to extend the Field Service Management with basically any logic required to optimize customer specific business processes. Currently there are nearly no limitations given to what an administrator can do with business rules. That brings a great deal of opportunities and possibilities to the system, but it brings dangers as well. This is especially true when huge amounts of data are processed or when the actions are resource intensive . Whatever you configure, please keep in mind that you configure your business rules so that the subset of data to be processed is as small as possible and the actions are of the minimum required complexity.

When it comes to scheduled BusinessRules we’d like to clarify the two most important topics:

  Description
Time of triggered action The system allows you to trigger a Scheduled BusinessRule 4 times an hour (XX:00, XX:15, XX:30, XX:45). Please note, that the rule is triggered at the exact given time, however the execution might be delayed by several minutes. The execution of BusinessRules is optimized to best preserve the machine’s resources (CPU, Memory…).
Frequency and execution time: Depending on the subset of data to be processed and the actions defined in a BusinessRule, the execution time varies from one rule to another. In order to protect the resources of the Cloud system, the execution of a BusinessRule might get skipped. This can happen when the same rule is triggered for execution while the previous rule execution is still running. To avoid this, the BusinessRule schedule must be configured so that the [TriggerTime]+[ExecutionTime] does not meet the next [TriggerTime].

Note the following scheduled business rule examples and their impacts:

Example Impact
[TriggerTime] XX:00 + [ExecutionTime] 00:25 The execution of XX:15 would be skipped.
[TriggerTime] XX:00 + [ExecutionTime] 00:10 The execution of XX:15 would NOT be skipped.

To avoid the situation that the defined actions are not executed because of skipped BusinessRule executions we strongly recommend defining the trigger conditions in such a way that the trigger conditions can’t be influenced by another process. In other words, the trigger conditions must be met at any given time as long as the desired actions of the BusinessRules are not executed.


Scheduled Rule with Condition

In case you specify a particular object type within the trigger, please consider the following:

In order to determine which objects a scheduled rule should be executed for, it is recommended to use the CoreSQL Where Clause field to specify the conditions. If you do not specify a CoreSQL Where Clause or use just the Conditions section below the variables, a full table scan is done against the system and the rule will be executed separately for all objects of the object type defined in the rule, which could lead to over consumption of the systems resources (CPU, Memory…) and performance degradation. The Conditions section below the variables is used only to determine if the actions of a rule will be executed or not for an object. Below is a good and bad example of specifying Scheduled Rule conditions.

Good Example using the CoreSQL Where Clause:



Bad Example using the Conditions section:



If a frequency is set for a business rule with a condition, it will run at the stated frequency when the rule is triggered.

For example, the following business rule will poll the database every hour and send a notification to the dispatcher if there is a Service Call that is due within 24 hours. This rule also includes a DATEDIFF Function in the CoreSQL Where Clause, which helps reduce the number of objects the rule is executed for and it is recommended to use this function when possible.

Trigger

Field Value
Event Scheduled
Object Type ServiceCall
CoreSQL WHERE Clause DATEDIFF(mi, NOW(), serviceCall.dueDateTime) = 1440 AND serviceCall.statusName = 'Ready to plan'
Frequency Every hour




Business Rules with Status Triggers

Activity Execution Stages

Stage Description
IN PLANNING This execution stage indicates that the activity record has been created and is currently in the Activity List.
IN DISPATCHING This execution stage indicates that the activity is currently on the Planning Board, but has not yet been released to the technician.
IN EXECUTION This execution stage indicates that the activity has been released to the technician and can now be viewed and completed on the mobile application.
CLOSED This execution stage indicates that the activity has been completed and closed by the assigned technician. Activities can also be closed for other reasons.
CANCELLED This execution stage indicates that the activity has been cancelled.

Activity Released Business rule performed based on comparison in serviceAssignment.released column.

Activity Cancelled

Please note that Unassign and Cancellation use the same Activity.executionStage.

  • Cancellation of Assigned Activity
    • Business rule performed based on comparison activity.executionStage. Additional validation - checked that Service Call cancelled as well, value mast be set based on Cancelled value in Service Call Mappings.
    • Business rule performed based on comparison activity.executionStage.
    • Additional validation - checked that Service Call cancelled as well, value mast be set based on Cancelled value in Service Call Mappings.

Activity Unassigned

Please note that both of the following unassign scenarios use the same activity.executionStage. For testing, it is recommended to create a business rule that creates a Service Call with a single activity, to determine if the status has changed following an unassign action. If the activity.executionStage = Cancelled it means that activity was simply unassigned.

  • Unassign of Released Activity
    • Business rule performed based on comparison activity.executionStage.
    • Additional validation - to check that the Service Call is not cancelled, the value must be set based on the Cancelled value in Service Call Mappings.
  • Unassign of Assigned Activity
    • Currently there is no explicit way to check this, since the application must validate that Activity.Responsible IS NULL.

Actions

Next, you can select from one to three Actions. This is the Action component of the argument that drives each business rule.

Based on your selection in this dropdown list, the application will display additional fields. Select the Action you would like to learn more about from the header row below:


Build Checklist Report


For every closed checklist instance on the selected activity, the application will generate a report and attach it to activity when the conditions have been met.

If you select this option, you will then enter the following information:


Field Description
Execution Count The execution count for the query in the stored procedure. Enter a valid JavaScript expression or a number, up to 1000. A valid JavaScript expression for execution count is ${ JS expression }. For example, ${activities.length} is valid whereas expressions like ${activities}.length, or activities.length are invalid.
Report Template Name Enter the name you would like to give the report.

Build Report


By selecting this option, the selected object, variables, and conditions will result in the application generating a report and sending it to specified recipients.


Field Description
Execution Count The execution count for the query in the stored procedure. Enter a valid JavaScript expression or a number, up to 1000. A valid JavaScript expression for execution count is ${ JS expression }. For example, ${activities.length} is valid whereas expressions like ${activities}.length, or activities.length are invalid.
Report Template Name Text entry. The name of the report template.
Language Dropdown. If applicable, the languages the report will be available in.
Name Text entry. Here you can define the name of used for the email attachment of the report generated by the business rule.
Type Dropdown. The report format. Options include: PDF; DOCX; XLS
Send Empty Yes or No. Here you can select whether or not you want to send an empty report.
To Here you can enter the recipient email address.
Subject Here you can enter a subject line describing the business rule, event, etc.
Content Here you can specify the content to be included, such as report description.

Build Service Checkout Report


If the service checkout contains a closed activity, this option will generate a report and attach it to the activity.

Note: Only one checklist report per checklist instance can be generated.

If you select this option, you will then enter the following information:


Field Description
Execution Count The execution count for the query in the stored procedure. Enter a valid JavaScript expression or a number, up to 1000. A valid JavaScript expression for execution count is ${ JS expression }. For example, ${activities.length} is valid whereas expressions like ${activities}.length, or activities.length are invalid.
Report Template Name Enter the name you would like to give the report.

Create Object


If you select this option, the business rule you've created will trigger the creation of an object when the conditions are met.

Note: Custom objects are also supported in the Create Object action. The custom object is referenced in the Object Type field. For more details, refer to the Custom Objects topic.

Field Description
Execution Count The execution count for the query in the stored procedure. Enter a valid JavaScript expression or a number, up to 1000. A valid JavaScript expression for execution count is ${ JS expression }. For example, ${activities.length} is valid whereas expressions like ${activities}.length, or activities.length are invalid.
Object Type Dropdown. The data object to be created by the business rule.
Object Version The Data Object version. For more information on Data Object versions, refer to the Data Transfer Object table below.
Field Name The name of the field. You can add additional field name rows as needed.
Field Value The information to be contained in the field. You can add additional field value rows as needed.

Create Requirement


By selecting this option, the application will create a requirement when the conditions have been met.

Note: Requirements become Skills in the Workforce Management module. These can then be assigned to technicians and used as filters for improved service call outcomes.

Here you will enter the following information:


Field Description
Execution Count The execut