Business Rules

Source: This article refers to 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 businss 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 occuring 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 Rule

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:


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.


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 Rule with Condition

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

For example, the following business rule will poll the database every minute and send a notification to the dispatcher if there Service Call that is due within 24 hours:

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 minute




Business Rules with Status Triggers

Activity Execution Stages

Stage Description
IN PLANNING This execution stage inidicates that the activity record has been created and is currently in the Activity List.
IN DISPATCHING This excecution 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, value mast be set based on 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 Action/s. This is the Action component of the argument that drives each business rule.

Based on your selection in this dropdown, 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.
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.
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.

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.
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.
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 technicans and used as filters for improved service call outcomes.

Here you will enter the following information:


Field Description
Execution Count The execution count for the query in the stored procedure.
Mandatory Yes or No.
Service Call ID Here you can enter the pre-defined Service Call ID
Tag Name Here you can enter the tag name associated with the new requirement.

Request Approval


When this option is selected, every new object that gets created according to the business rule conditions has to be manually approved/confirmed before it gets synchronized and saved to the ERP. Once approval has been given, the objects impacted by this business rule can then be synced with the ERP.


Send Email


By selecting this option, the application will generate and send an email when the conditions of the business rule have been met.


Field Description
Execution Count The execution count for the query in the stored procedure.
To The recipient/s of the email
Subject The subject of the email. Example: item low in stock.
Content The content to be included in the email

Send HTTPS Request


By selecting this option, the application will complete a GET, POST, PUT, or DELETE request to the specified endpoint when the conditions have been met. All communication to and from the Cloud is secured by SSL.

If you select this option, you will be prompted to enter the following information:


Field Description
Execution Count The execution count for the query in the stored procedure.
Method The HTTP method used in the request (see table below).
URL The API endpoint.
Header Name The name of the header.
Header Value The application supports General, Request, Response, and Entity headers.
Body The body of the request. The HTTP Request action supports all content-types, including text, script, image, audio, video, and sound file formats.
Response Variable The response variable returned by the request that can be used in subsequent actions. Response variables could, for example, the suggested route and/or ETA data returned from a GET request made to the Google API, which could then be used in a Send Email or Send SMS action for the technician or customer.

In order to utilize a response variable in a business rule, it must be

  1. Defined in the variables section Example: etaByPublicTrain set as object-type Value
  2. Referenced in the HTTPS Request. Example: etaByPublicTrain entered in the response variable field
  3. And then used in a subsequent action. Example: the etaByPublicTrain response variable referenced in a Send SMS action

The Send HTTP Request action supports the following request types:


Method Description
GET This method will return a resource to be read.
POST This method will create a new resource.
PUT This method will update an existing resource.
DELETE This method will delete an existing resource.

Send SMS


Note: Additional costs for the service to send an SMS as action for a business rule apply. Contact Coresystems Sales for further details.

By selecting this option, the application will send an SMS message to a mobile phone number when the conditions of the business rule are met.

You will then be prompted to enter the following information:


Field Description
Execution Count The execution count for the query in the stored procedure.
To The recipient mobile phone number
Body The body of the SMS message. Example: "Service Call scheduled."

Update Object


By selecting this option, the application will select a Data Transfer Object (DTO) when the conditions of the business rules are met.

You will be prompted to enter the following information:


Field Description
Execution Count The execution count for the query in the stored procedure.
Object Type Dropdown. The data object to be updated 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 value to be included in the field. You can add additional field value rows as needed.

Run JavaScript


By selecting this option, you can run a JavaScript function for an email notification.


Field Description
Execution Count The execution count for the query in the stored procedure.
Code Here you can enter the JavaScript function to be excuted.
From Dropdown. The sender email address.
To The recipient of the email.
CC The email address to be included as a CC (carbon copy).
BCC The email address to be included as a BCC (blind carbon copy). This email recipient will not display in the email recipient data.
Subject The subject of the email.
Content The content of the email.

Delete Object


By selecting this option, the application will delete an object when the conditions of the business rules are met.

You will be prompted to enter the following information:


Field Description
Execution Count The execution count for the query in the stored procedure.
Object ID The ID of the data object to be deleted by the business rule.
Object Type Dropdown. The type of data object to be delete by the business rule.

Calculate Distance


By selecting this option, the application will calculate the distance and duration between origin and destination.

For an example of a business rule that uses this action, view the Notify customer with expected time of technician's arrival (ETA) sample rule.

You will be prompted to enter the following information:


Field Description
Execution Count The execution count for the query in the stored procedure.
Origin The origin or starting point of the technician (example: $(technician.location).
Destination The destination/location of the activity (example: $(address.location)).
Distance (in km) Variable Name The name of the variable used to represent distance (example: Distance).
Duration (in seconds) Variable Name The name of the variable used to represent duration (example: Duration).

Validate


By selecting this action, the application will return an error with the corresponding contraint names if any of the constraint values evaluate to false. This action would in effect block the creation or update of an object when the conditions of the business rule are met.

Notes:

  • This action type only works if the trigger execution rule is set to Synchronous.
  • If the trigger execution is set to Asynchronous the action will not have any impact
  • If any of the constraint return as false, the event that triggered the rule will be blocked.
  • Please note that support for error messages is not available in all clients.

You will be prompted to enter the following information for this action:


Field Description
Execution Count The execution count for the query in the stored procedure.
Constraints
Constraint Name The name of the constraint used in the validation action.
Constraint Value The value of the constraint used in the validation action.

Rule Created

After completing the Trigger and Action sections of the business rule, you can then click Save.

Note: The application only validates for required fields, so a successfully-saved business rule does not automatically indicate the business rule is valid. However, the record will be saved and you can modify the business rule as needed until it is valid.

To validate the new business rule, select the Validate option after creating or modifying the rule.


JavaScript Functions in Business Rules

In general any JavaScript function can be used in business rules and conditions.

In order to use a JavaScript function inside a business rule, the business rule must be set to Type Two:



This will allow for full JavaScript support inside expressions.


Moment Functions

Date Format

The following example demonstrates how moment.js functions can be used to change the date format used for activities:

Date Format Business Rule
01/25/2017 ${moment(activity.startDateTime).format('MM/DD/YYYY')}
January 25, 2017 ${moment(activity.startDateTime).format('LL')}
Jan 25, 2017 ${moment(activity.startDateTime).format('ll')}

The following is an example of a moment.js function in a business rule:




Time Zone

The following demonstrates how moment-timezone.js functions can be used:

If

activity.startDateTime = "2017-02-17T13:36:00+00:00"

Then

Date Format Business Rule
5AM PST ${moment(activity.startDateTime).tz('America/Los_Angeles').format('ha z')}
2PM CET ${moment(activity.startDateTime).tz('Europe/Rome').format('ha z')}
2017-02-17T13:36:00+00:00 ${moment(activity.startDateTime).format()}
+01:00 ${moment(activity.startDateTime).tz('Europe/Berlin').format('Z')}
-07:00 MST ${moment(activity.startDateTime).tz('America/Denver').format('Z z')}
MST ${moment(activity.startDateTime).tz('America/Denver').zoneAbbr()}
MST ${moment(activity.startDateTime).tz('America/Denver').zoneName()}
Feb 17th 2017 5AM ${moment(activity.startDateTime).tz('America/Los_Angeles').format('MMM Do YYYY hA')}

The following is an example of a moment-timezone.js function in a business rule for an SMS notification:




Validating Null Values

To verify if a value is null in the condition of a business rule, a JavaScript function can be used on the Length property, as demonstrated in the following example:

${serviceCall.equipments}.length != 0




Using Array in Action

The following is an example of how an array can be used in an action:

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



The above example would update the responsible person of all checklists linked to an activity when releasing the activity to technician (please note that this example is available as a Sample business rule).

The rule will be executed as many times as there are checklist instances linked to a specific activity. This is accomplished specifically using:

Execution Count: ${checklistInstance.length}

The correct checklist instance id can then be retrieved with the following syntax:

Object Id: ${checklistInstance[i].id}

The following can be used to check if an object that is joined under variables does NOT give any results in the join:

  • Variable type Array: ${object.length} == 0
  • Variable type Object: $object == NULL

Additional Resources

Custom Fields in Business Rules

Custom Fields (also known as User-defined Fields) can be referenced in variables (using the WHERE clause), conditions, and actions for all available objects.

The following syntax is used when referencing a custom field in a business rule:

Structure ${<variable name>.udf.<custom field name>}
Example ${material.udf.materialaction}

When updating a custom field using the Update Action you will need to enter the following in the field column:

Structure udf.<custom field name>
Example udf.materialaction

Appendix

Data Object Table

The following table describes the Data Objects and fields used in Coresystems Field Service Management. You can use this table to view data object and version information in detail.

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

Comments

0 comments

Article is closed for comments.