Configuring rules for activities

Create and maintain rules that determine which activities to implement based on conditions you specify.

Understanding rules and when they run

A rule is a set of conditional statements that, when satisfied, run pre-defined activities. An activity is the operation that the rule runs when the appropriate conditions are satisfied. A condition is a statement that includes a field, an equation, and a value. The condition is met when the statement evaluates to true.

Rules run only in the following situations:

When an entity is created or deleted, for example, when an incident is created.
When a condition in the rule changed in an entity update event.

For example, if you have an incident with address Paris, France, and a rule with the condition Address contains Paris, France, if you update any other field in the incident, the rule does not run. That is because address wasn't changed in this particular incident update event.

There are two types of rules, Automatic and Menu Item. An automatic rule runs without user involvement when its conditions are satisfied. A menu item rule displays as an action in the designated object’s Actions menu and runs only when a user selects it.

Rules have three types of activities, ordered, workflow, and message destination. Use ordered activities to set incident field values and add tasks into the task list. You can run internal scripts as an ordered activity.

You can use workflow activities to call predefined workflows. A workflow is a graphically designed set of activities that you can use to create a more complex set of instructions than ordered activities.

A message destination is the location where the message is stored and made accessible to external scripts and programs. You can have a rule, workflow, or function send information to a message destination. You specify a message destination to provide information to such a script or program. For performance reasons, do not use a message destination with a rule if the rule includes a workflow that contains a function. The function defines the message destination.

When a rule starts, it runs the ordered activities first, and in the order listed in the rule. Afterward, it runs the workflows. Workflows are not order dependent and might take different lengths of time to complete depending on their complexity. Finally, it posts to any message destination specified.

You can view, edit, and create rules in the Rules tab. The tab provides the following information:

Order. Automatic rules have numbers, which denote the order in which the rules run when a condition runs multiple rules. The ordering can be important especially when different rules affect the same fields, or changes made by one rule impact another rule. You can change the order by dragging the rules. Menu Item rules do not have numbers since they run only when a user runs them.
Rule Name. Click the name of a rule to view its details or edit the rule. When you edit or create a rule, enter a name that is descriptive of the rule’s purpose.
Process Type. Type of rule, which can be Automatic or Menu Item.
Object Type. You assign a rule to one type of object, such as incident, note, milestone, task, attachment, artifact, data table, or email message.
Conditions. A statement that checks a field for a value by using an operator such as equal to. Conditions are used to determine when to run the rule. The Rules tab lists the conditions, if any, attached to the rule.
Note: A condition in red indicates an invalid condition. The reason might be that a selected object or field is disabled or hidden.
Enabled. By default, each rule is enabled. You can disable a rule in the Rules page and on the individual rule page. You can choose to disable a rule if it is experimental, under development, or an example rule imported from an app. When a rule is disabled, it appears in red when listed as an associated rule with scripts, phases and tasks, and workflows.

Note: Rules are not used with playbooks that are created with the Playbook designer.

Define rule conditions

When you create or edit a rule, you define the conditions that run the rule.

You must first select the rule’s object type before you can specify any conditions as the object type determines which fields are available as conditions. You can use some object types to select fields from their parent object; for example, you can select incident fields for a rule that has a Task or Note object type.

A rule is evaluated only when an instance of the object type selected in the rule changes. The conditions selected, whether from the object type or parent object type, do not affect when the system evaluates the rule.

If you do not specify any conditions, then the rule runs every time an object of the associated type is created or updated. If you select the “is deleted” or “is created” condition, the rule runs every time an object of the associated type is created, deleted, or updated. (The “is created” and “is deleted” conditions produce the same result.)

If you select the Email Message object type, you can specify a condition based on the email's properties. Properties include the subject, from address, sent or received date, and when an email message is received or deleted. The ID field is the number that is assigned to the email message, which is shown on the Email tab of an incident. The Inbound Mailbox field prompts you to select one of the existing configured Mailboxes.

To add conditions, click the Add New link. The following example shows a new rule with an object type of incident and the Address field.

Click in the first box to select a field. Click in the second box to select the operator. Click in the last box to select or enter a value. The rule runs when this condition becomes a true statement (unless other conditions exist).

You can add conditions to define more precisely when the rule runs.

For more information, see Conditions. The topic includes adding conditions and a description of the operators.

View ordered activities

An ordered activity runs when the rule conditions are satisfied. You can view the ordered activities for a rule by editing the rule.

When creating a rule, click the Add New link under the Ordered Activities heading. It brings up a default Set Field activity. You can change the activity type by clicking Set Field and choosing the activity type from the menu. For example,

You can add an activity by clicking the plus (+) icon. You delete an activity by clicking the Delete icon.

Ordered activities are organized by the following types.

Add Tasks. Select the tasks that start rule. Select Add Tasks then click in the field to list the tasks, which are listed by incident phase and in order of priority. You can choose one or more tasks. You can also create a new task. See the procedure in Configure Phases & Tasks for details.
Note: If you edit a rule, any task that is shown in red denotes that the task was deleted.
Run Script. Starts a script. Select Run Script then click in the field to list the scripts.
Set Field. You can select one of the object’s fields and set a value. You can use some object types to specify fields from their parent object; for example, task rules can set incident fields. You can clear a field by setting it to no value.

When a rule has multiple activities, the rule runs each activity serially. You can determine the order.

Workflow activities in playbooks

A workflow that is included in a rule’s workflow activities is started when the rule conditions are satisfied and after the rule runs any and all ordered activities.

You can view a rule’s workflow activities by editing the rule.

Workflows are not order dependent and depending on their complexity, might not complete within the transaction that initiated it.

When you create or edit a rule, click in the Workflows field under the Activities heading to see a list of available workflows. Select a workflow to add it to the rule. For example,

You can add more workflows by clicking in the field again. You delete a workflow by clicking the X icon.

Specifying message destinations

A rule can send information in a message to a message destination, which is the location where the message is stored and made accessible to external scripts and programs.

As described in Configure Message Destinations, a rule can send information in a message to a message destination, which is the location where the message is stored and made accessible to external scripts and programs. You specify a destination to provide information to such a script or program only. You can select one or more message destinations.

You do not normally use message destinations at the rule level if the rule includes a workflow that contains a function. In this case, the function defines the message destination.

For menu item rules only, you can also configure activity fields. You can use the fields to create a dialog box to collect information from the user, where this information is also sent to the message destination. Users see the dialog box after they select the action from the Actions menu. For example, you can require users to select a ticket queue and specify a priority when they generate an IT ticket from a task note.

To create a dialog box, click the Show Activity Fields link when you create or edit a menu item rule. You can drag fields and insert headers and HTML markup on the layout area to organize the dialog box. In addition, you can create new fields by clicking Add Field then configuring the following values.

Type of Field. Select the type of the field that best matches its purpose.
When you create a field of the type Select, you can set a default value. When creating a field of the type Multiselect, you can set a default value; however, that is relevant only for the new incident wizard. When the field is used in other places, the default value is not shown.
Label for the Field. Enter the display name for the field.
API Access Name. The platform automatically generates the API access name, based on the display name. App developers use this name to interact with this field from the API.
Placeholder. If you enter a placeholder, this value is automatically displayed in the field to provide a hint to the user.
Requirement. Enter Always to make it a required field, where the user cannot run the rule (as an action) without specifying a value for the field. Select On Close to make it required when closing an incident. Select Optional if the user is not required to enter or select a value.
Tooltip. You can enter descriptive text or a helpful hint. It displays an information icon next to the field. Your text displays when a user hovers over the icon.

Rule evaluations in playbooks

A rule is created against a specific type of object. When a change occurs to an object, the rules that are created against that object type are evaluated. If the rule conditions are satisfied, the rule is started.

If a rule creates a new object or changes the state of an object, all rules against that same object type are reevaluated, and the rule might be started again.

Consider the following information when you plan the behavior for rule evaluations:

Multiple automatic rules

If a change to an object triggers multiple automatic rules, all of the rules must run before any of the rules can be reevaluated.

In a scenario where an automatic rule modifies an object, a follow-on rule does not see that modification until all of the rules are completed and then reevaluated. However, if an automatic rule runs a workflow that modifies the object, after the workflow completes, a follow-on rule can act upon that change.

Infinite loops

To guard against infinite loops, the SOAR Platform limits the rule from creating more than 500 new objects while rules are being processed.

Messages that state that the number of rule evaluations in a single session were exceeded might indicate that a rule created an infinite loop.

Auto-activated task

When an automatic rule creates a task, the task is considered an "auto-activated" task. If the rule is reevaluated and the rule condition is false, its tasks are deactivated and hidden.

This behavior is useful in many situations. For example, consider an automatic rule that creates tasks in response to a malware event. Upon reevaluation, if it is not malware, the tasks that were previously created are deactivated.

However, this behavior might be confusing to a user when the conditions reference a state, such as when an incident is created. For example, an incident creation event might start an automatic rule that creates one or more tasks. If a user modifies the incident, the rule is reevaluated, but because the incident was already created the rule evaluates to false. In this situation, any tasks that were created by the rule are deactivated.

Considerations for creating a rule

Review the important considerations before creating a rule.

Consider the following before you write a rule:

Determine the object type and the purpose of the rule. The object type determines the context of the data that is provided to the rule.
Determine the ordered activities. When you have multiple activities, determine the order of those activities.
Consider designing workflows especially if you have repeatable processes that can be used in various situations. For example, you can schedule a task (A) to be created after the completion of a specific task (B) and depending on the outcome yet another task (C).
Determine whether the rule is to be started automatically or by a user from a menu item.
Determine the conditions, if any, which must be satisfied before it starts the rule. If the rule has multiple conditions, determine whether any one or all conditions must be satisfied.
Determine the order of the automatic rules. When conditions start multiple rules, they are started serially and in order.
To communicate information to other processes, make sure to choose one or more destinations.
To run a script, make sure to choose the appropriate script. You create and manage scripts in the Scripts tab.

Important: When you develop and test your rules, you can include a condition to make sure that the rules do not run on production incidents. For example, you can include a clause in the rule conditions such as "Simulation Equals True" or the equivalent. In this way, the rule would run against simulations only and not open incidents.