Establishing Business Rules

Business Rules are pieces of custom logic, used to enhance the FSM solution for customer-specific cases. The standard logic in FSM is described as "monolith" and can't be changed. Business rules can therefore only run in addition to, or on top of, the FSM standard logic. Business Rules are created on Company level and run within that context.

Before a business rule is executed, it needs to be triggered by something. That trigger can either be a specific event, or a pre-defined schedule. The specific events can -for example- refer to changes on the company database, inputs from an integrated system, or events published by FSM microservices.

After the business rule has been triggered, data is collected, conditions are checked, and actions are executed.

Business Rules can help to automate business processes. Specific examples of use cases for business rules include:

• Send notifications, SMS, or email
• assign a Workflow to an Activity
• attach Smartforms to Activities
• generate Reports
• create follow-up activities
• invoke Autoscheduling

Every FSM company comes with several embedded and sample/demo business rules. Embedded rules can be enabled as-is, or serve as examples for your own enhancements.

Business Rules (BRs) can be found under the corresponding tab on the Company page. The Business Rules list can be searched, sorted, and filtered. From here, BRs can be enabled or disabled, created or deleted, and uploaded or downloaded.

You can either modify a sample business rule by editing one of the existing rules or create one from scratch using the Create button. It is recommended to use the sample business rule as a base to start customizing FSM for your business case.

The primary parts of a business rule are the main settings, the trigger section and the action section. These parts can be described as follows:

Main settings: This section contains the code, name, and description of the business rule. It also holds flags to enable the business rule and whether skipped executions should be logged. Finally, it contains information about the health status of the business rule, and the technical contact person(s), who should be informed if the business rule is in a critical health state.

Trigger: It is in this section that you define the event that activates the business rule. It includes the data object type, the variables, conditions, and other parameters for the business rule. When the conditions are met, the application will respond by executing the action specified in the action section.

Action: It is in this section that you define the application response to the event specified in the trigger section. For instance, if you have specified in the trigger 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.

The main settings for business rules are described below.

• Code: This is optional. It can be used as an identifier of the business rule. The best practice is to keep this short.
• Name: The name of the business rule.
• Description: A description of the business rule. Simple markup can be coded manually, for example, for line breaks, bold font, or bullet points.
• Enabled: A yes or no option. If yes, the business rule will be active.
• Technical Contact: This will include e-mail addresses of the contact persons for technical questions on the definition/execution of the business rule. It is recommended that you add multiple technical contacts. The listed person, or persons, will also be the point of contact for SAP Support in case the business rule is causing excessive resource usage or other server problems.
• Error Threshold Percent: This field allows a user to adjust the threshold, in percentage, at which the technical contacts of a business rule are informed of business rules with failed executions. If the field is left empty, a default of 50% will be applied.
• Log Skipped Executions: A yes or no option. If yes, then skipped executions will be shown in the execution log, which can be accessed in the maintenance view. The number of skipped execution logs is limited to the latest 100 skipped log entries per business rule. Older ones are deleted automatically via the SAP.FSM.BusinessRules.MaxSkippedLogsToKeep company setting. In this setting, you can define another limit - but with an absolute maximum of 1000.
• Type: There are currently two types of supported business rules:
  • Type Two: This type of business rule offers full Javascript support.
  • Type Three: This type of business rule is based on the new microservice architecture and supports several different variable-, event-, and action types when compared to Type Two Business Rules. Where possible, it is advised to use Type Three. For details, please refer to the latest documentation.

• Events: The event that triggers the business rule. Options for objects include the following:
  • CRUD-based events for a given data object (create, update, delete, or a combination thereof). Triggers of this kind:
    • 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 (for example, business partner) is uploaded using the Proaxia ECC Connector.
  • Scheduled: If selected, the business rule will be set to run at the specified times and intervals.
  • FSM Events: Field Service Management events are business events, which are published by services of SAP Field Service Management in case a related occurrence happened.
• Object Type: The data transfer object (DTOs) associated with the event. For a closer look at these DTOs, refer to the data model.
• Order: The order in which business rules are executed when triggered by the same event.
• Execution:
  • Asynchronous (occurs after synchronization with client application).
  • Synchronous (occurs during synchronization with client application). Synchronous business rules are used in combination with a validation action and can cause delays in synchronization with client apps (for example, mobile).
• Delay Execution (Sec): You can define a business rule to be executed with a delay of up to 600 seconds. Only business rules with the execution type "asynchronous" can be delayed, excluding scheduled business rules. Please consider the following before using a delay:
  • A business rule will only be executed once the duration of a delay is reached.
  • As the delay only defines the minimum duration that needs to be reached, it can be that the asynchronous execution of a business rule is further delayed than defined.
  • If there are business rules triggered by the same event (that is, the update of an activity) and defined with different delays, it is not guaranteed that the order of execution will be based on the duration of the delays defined.
  • To ensure that business rules are executed in a specific order, a better alternative is to use the order field.
  • If you combine using a delay and order in business rules triggered by the same event, the order will only be considered for those rules defined with the same delay. This ensures these rules are triggered at the same point in time and then the correct order of the rules can be considered. The system is not able to consider the order of rules triggered at different times due to different delays.
  • In general it is recommend to use delays cautiously. Delayed executions put an additional load on the system, which can have an impact on system performance.
• CoreSQL WHERE Clause: This field will appear when the event type is "scheduled". It is recommended to use this field to determine the objects for which the rule should be executed for. For each object record found, the variables and conditions will be resolved and the actions executed accordingly.
• Frequency: This field will appear when the event type is "scheduled". Here, you can enter the frequency at which the business rule should be triggered when the conditions are met.

Time of triggered action: The system allows you to trigger a scheduled business rule up to 4 times an hour (XX:00, XX:15, XX:30, XX:45).

The execution of business rules is optimized to best preserve the server's resources (CPU, Memory, and so on).

Frequency and execution time: Depending on the subset of data to be processed and the actions defined in a business rule, the execution time varies from one rule to another. In order to protect the resources of the cloud system, the execution of a business rule 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 business rule schedule must be configured so that the [TriggerTime]+[ExecutionTime] does not meet the next [TriggerTime].

To avoid the defined actions not being executed because of a skipped business rule, it is strongly recommend to define the trigger conditions in such a way that the trigger conditions cannot 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 business rules are not executed.

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

Variables are used to read data that is needed for the proper execution of the business rule. Data in variables can be used in subsequent Variables, Conditions, and Actions.

A variable consists of a query in CoreSQL (same as Query API), Javascript functions, or a combination thereof. The values of the variables are resolved during rule validation and execution. After a variable has been defined resolved, the variable and its properties can be referred to by using javascript. For example ${activity.code} refers to the "code" field of a previously defined variable called "activity".

Some variables come predefined and refer to the following:

• The relevant triggering object
• ‘Old’ vs. ‘new’ object data
• The current user, Company, and Account

The company settings and the user settings are accessed through the variables ${company.settings} and ${user.settings}. For example, to retrieve the language that the user set in the web application, use ${user.settings.Cockpit_SelectedLanguage.data} .

Custom variables can be defined as the following:

• Object: a single record of a given type
• Array: allows the selection of many individual objects by using a complex query
• Value: usually consisting of a hard coded value/text string or otherwise defined by a javascript function that is resolved during execution.

Object- and Array Variables are specified by the following:

• Object (DTO) Type
• Object Version
• CoreSQL WHERE clause or a complete CoreSQL query.

In advanced query mode, complex CoreSQL queries can be defined. To access advanced mode, press the wrench icon. When using advanced mode, all object types and their versions have to be explicitly defined, for example Activity.40;ServiceCall.26. All defined queries can be inspected and executed in the Query API interface by using the triangle icon.

The CoreSQL query or -WHERE clause can contain javascript code snippets, contained between brackets: ${ ... }

Value Variables can hold, for example a text string, a Javascript code snippet, or similar.

Custom objects and fields (also known as user-defined objects and fields) are supported. They can be referenced in variables (using the WHERE clause), conditions, and actions for all available objects.

Conditions are defined with built-in relational- and logical Operators and can compare the following:

• Variables and their properties
• Text strings
• Numbers
• Boolean values
• JavaScript functions

Conditions are evaluated after resolution of the Variables. Then, if all the Conditions are met, the Actions get executed. If, however, one of the Conditions is not met, the execution of the business rule is skipped.

Skipping a lot of business rule executions still costs system resources, because the BR still reacted to the event/trigger, resolved the variables, and checked the conditions.

A business rule can execute up to 100 actions which are executed in sequence if the business rule conditions are met. There are many different types of actions, each with their own specific input parameters. The input parameters are filled with data from the variables, JavaScript functions, hard coded values, and so on.

Some action examples are listed below.

• Webhook/FSM webhook: These actions return a response variable, which can be used in subsequent actions.
• Execute Conditional Operation: Consists of a condition that determines whether the subsequent action gets executed or skipped.
• Create/Update/Delete Object: Custom objects are supported and referenced in the object type field.
• Build Checklist Report: For every closed checklist instance on the selected activity, the application will generate a report and attach it to the activity.
• Validate: Used in synchronous business rules to block something from happening before committing the corresponding data to the database. For example, a mobile/web client synchronizing some new or changed data.

FSM webhook actions are limited to APIs that require FSM authentication. An advantage of this action is that you no longer need to define an explicit webhook action for determining an authorization token for OAuth2. You only need to enter the client ID and secret to ensure the proper credentials are used.

In the Variable section, the code will consist mainly of CoreSQL, in order to gather the relevant data. Throughout the business rule, including inside the CoreSQL queries, Javascript can be used: either independently or to reference and manipulate data contained in previously-defined Variables. Everything between a dollar-sign and brackets is interpreted as JavaScript ${..}. The JavaScript functions should be based on the ECMAScript 6.0 standard.

After having completed the trigger and action sections of the business rule, you can choose Save. The application only validates for required fields, so a successfully-saved business rule does not automatically indicate that 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 help ensure that the business rule will work as expected, it is necessary to validate it. The validation function allows you to simulate the business rule execution and see how the variables are being resolved. Also, the validation function checks whether the basic syntax of your rule is correct. However, any API calls are not executed and results are not committed to the database.

To go to the Validation screen, choose Validate. On the validation screen, you need to specify any necessary input data. Usually, this means selecting a relevant object record from the database. A pop-up supports the user in selecting an object by showing a list of possible object IDs. However, it is usually necessary to first find a relevant object with Query API, so that the relevant properties are known and the business rule behavior can be simulated accordingly. The person field can be used to assess the impact of the user's permissions, or when the user's settings and other data are relevant.

When the necessary data has been entered, choose Validate. During validation, all variables in the business rule will be resolved and will be shown on screen. The JavaScript snippets will be executed and replaced by their results/output. Errors lead to an interruption of the process and will be shown at the top of the screen.

After successful validation, the next step is to execute the business rule manually, in a test environment. To go to the manual execution screen, choose Execute.

As during validation, you need to select the relevant input data. When this is done, choose Execute.

Contrary to validation, the manual execution function doesn't show the resolved variables. In addition, all actions are effectively executed and results are committed to the database. Depending on your specific business rule, the execution can be evaluated by checking the execution log, the database, or on the web UI.

After the business rule was successfully tested in manual mode, you can enable the business rule. This makes the business rule run completely automatically, according to the trigger settings.