Design business rules

You can define business rules that trigger actions in ALM Octane when certain conditions are met.

For an introduction to business rules and their principles, see Business rules.

Overview

A business rule is made up of two main components: an action and a condition. The action is performed automatically when the condition is met. You can define business rules with only an action and no condition. This can be useful, for example, for setting fields as always required.

Space-level rules: When defining business rules at the space level, you can use fields that might have workspace-specific values. In the business rule, the available values and operators for such fields are generic, such as '[current user]', 'is empty', 'is modified'.

Such fields include: User fields, Tags, Team, Environment, and reference fields (such as Feature and User stories).

Create a rule

When you create a rule, you must define the action that it triggers, and then set the conditions (optional).

To create a rule:

In Settings > Spaces, select a space or a workspace.
Click Entities and select the item for which you want to create a rule.
Click Rules.
Create a new rule in one of the following ways:
- Create a brand new rule: Click Add Business Rule . Choose an action and condition. For details, see Rule actions and Define a condition.
- Create a new rule, based on an existing rule: Select an existing rule and click Duplicate in the bottom toolbar. Click Edit in the bottom toolbar, and modify the rule as required.

Rule actions

The following table includes the actions that you can define for a rule.

Action	Description
Add comment	Add a comment to the item when the item is created or updated. Submission mode is the trigger that causes the comment to be added.
Add to stakeholder's My Work area	Adds an item to a user's My Work area. A user can be any of the stakeholder fields defined in the item, such as Author or Owner.
Alert user	If an item matches the rule condition, an error dialog is opened with a message you define. The entity cannot be saved until the user modifies the entity and the entity no longer matches the rule condition. Note: The condition should contain criteria that are not desirable. We want the rule to alert users with an error dialog box only if there is a problem. The condition specifies a problematic scenario, not a legitimate one. You can have the rule alert users when an entity is created, changed, or deleted. Submission mode is the trigger that causes the rule to run. Tip: You can use this rule action to prevent a user with a certain role from performing an action under certain circumstances. For example, if a rule action for creating a user story is Alert User, and the rule condition indicates the release that the user is not allowed to work in, if the condition is true, the user cannot work in that specific release—even if generally, the user has permissions to do so for other releases. Example: Send an email when an item is updated
Block transition	Prevent users from transitioning from one phase to a specific phase, even though the transition is generally permitted in the workflow for the entity. Tip: To define phase-dependent rules, click the Workflow tab, select a phase or transition for which you want to create a rule, and click the Rules tab.
Make read-only	Make fields read-only.
Make required	Make fields mandatory. Example: Make fields required
Modify lookup list	Change the available values for a list field in one of the following ways: Use a subset of a list. Combine lists. Use different lists under different conditions. Select the field and the list of values you want to use. If relevant, select a subset of values from the list in the Sublist field. For details on creating lists, see Lists. Examples: Set a subset of a lookup list Combine lookup lists Use different lookup lists
Send email	Send an email if an entity is created, updated, or deleted. The body of the email is automatically generated by ALM Octane. Submission mode is the trigger that causes the email to be sent. Email recipients can be specific users defined in the workspace, or users whose names appear in the user fields of the entity for which the email is sent. You can also define an entity's team as the recipient. ALM Octane then sends an email to all members of the team. Or, you can add stakeholders, such as team leads or team members of the teams set for the entity. To send an email to stakeholders who are not subscribed users of the workspace, add them manually in the text box in the Send to section. Use a semicolon (;) as a delimiter between email addresses. To enable this feature, admins must enter the allowed email domains as values for the ALLOWED_EXTERNAL_EMAIL_DOMAINS parameter. For details, see Configuration parameters. Tip: Use this capability to send emails to a channel, such as in Slack or Microsoft Teams. In your application, obtain the channel's email address and enter it in the Send to section.
Set field value	A rule can change a field's value in one of the following ways: Set a certain value for a field. Copy a value from another field. Clear a field's value. Increment an integer or date field by a certain amount (works with the 'When saving an entity' timing). Timing is the trigger that causes a value to be set. The timing can be: When creating an entity, as soon as the Add dialog box is opened and when duplicating or splitting an entity. When changing a value, upon any change to the fields. When saving an entity, upon submitting a new entity, editing an existing one, duplicating an entity, or splitting an entity. When related entity changed, whenever related entitles mentioned in the conditions are modified. The value can be a new value, empty, or a copy of another field's value. Examples: Count the number of times defects are re-opened Record the Last Modifier of a manual test Set default field values (Set Field Value) Set a value when a related item changes (Set Field Value)
Trigger webhook	ALM Octane supports webhooks for integrating with other applications. Configure the webhooks by creating a rule with the Trigger Webhook action. Configure the following: The events that call the URL Events trigger the Trigger Webhook mechanism to send HTTP or HTTPS requests. Specify the events using the Submission mode field. Valid events are: New, Update, Delete. The connection to the URL The URL of the service application that receives the webhook. Enter a valid, accessible URL. Click Test Connection to verify the connection is successful. Credentials Trigger Webhook rules support basic authentication. You can set credentials in the Trigger Webhook rule and each Trigger Webhook request includes the basic authentication header. Credentials is the user name and password that ALM Octane can use to authenticate the request, typically using basic authentication. For details, see Credentials. Click Test Connection to verify the connection is successful. The request payload By default, ALM Octane POSTS the following fields in the payload: ID Type Modified fields, including the original and changed values Use Fields to select additional fields to send in the request payload. Example: Trigger webhooks (call a URL) For details, see About the webhook request payload format. For end-to-end instructions on working with Trigger Webhook rules, review Trigger webhooks for other applications.
Use form	Enable users to select different form layouts for adding and editing entities. The form layout must be predefined in Customization > Forms. Example: Switch forms

Define a condition

A condition is made up of a field, an operator, and a value.

You can formulate complex conditions for rules that include several conditions separated by AND or OR operators.

Click the Condition tab to begin.

Select a field

Select a field on which to base the condition, or a special circumstance.

Special circumstances include:

Circumstance	Details
Edit Mode	The condition is based on whether the current entity existed already and is now being edited, or if the current entity is new. To check if new: Edit mode = New To check if existing: (Edit mode ≠ New) You can further refine the rule by specifying a value such as Duplicate or Split. For example, you can create a rule to clear certain fields when an entity is duplicated or split.
Current User Role	The condition is based on whether a user is assigned a specific role.
< entity count	The condition is based on how many related items of a certain type exist. Examples Counts Find features not associated with any application modules: Select the feature entity. Select Application module count for the Field value. Select the = operator. Enter the value 0. Click OK. Counts of items related to other entities Find features with tags that I created: Select the feature entity. Select Tags count for the Field value. Click and then Add Filter. Select Author > Equal to > Me. Select the > operator. Enter the value 0. Click OK twice. Update an item based on counts of related items You can set field values when a related entity changes by creating a condition based on the counts of a related entity in a Set Field Value rule. The following counts are particularly useful: children count (for features) child task count (for user stories) Update the phase of a user story to Done if all its tasks are completed: Select the user story entity. Select Child task count for the Field value. Select the Filter operator. For details, see Design business rules. Select Phase > = > In Progress, New. Select the = operator. Enter the value 0. Click OK twice.

Circumstance

Details

Edit Mode

The condition is based on whether the current entity existed already and is now being edited, or if the current entity is new.

To check if new: Edit mode = New

To check if existing: (Edit mode ≠ New)

You can further refine the rule by specifying a value such as Duplicate or Split. For example, you can create a rule to clear certain fields when an entity is duplicated or split.

Current User Role

The condition is based on whether a user is assigned a specific role.

< entity count

The condition is based on how many related items of a certain type exist.

Examples

Counts

Find features not associated with any application modules:
1. Select the feature entity.
2. Select Application module count for the Field value.
3. Select the = operator.
4. Enter the value 0.
5. Click OK.

Counts of items related to other entities

Find features with tags that I created:
1. Select the feature entity.
2. Select Tags count for the Field value.
3. Click and then Add Filter.
4. Select Author > Equal to > Me.
5. Select the > operator.
6. Enter the value 0.
7. Click OK twice.

Update an item based on counts of related items

You can set field values when a related entity changes by creating a condition based on the counts of a related entity in a Set Field Value rule. The following counts are particularly useful:
- children count (for features)
- child task count (for user stories)
Update the phase of a user story to Done if all its tasks are completed:
1. Select the user story entity.
2. Select Child task count for the Field value.
3. Select the Filter operator. For details, see Design business rules.
4. Select Phase > = > In Progress, New.
5. Select the = operator.
6. Enter the value 0.
7. Click OK twice.

Cross-field conditions

Certain fields allow you to apply a cross-field condition to a business rule based on a field with a relation to the entity. Entities with these capabilities are indicated by the cross-field icon . You set a cross-field condition just as you would set a cross-field filter.

In the following example, the condition was set to any release preceding 06/11/2020.

Note: The cross-field condition only applies to single reference fields, such as release, owner, and phase; it does not apply to multiple reference fields, such as application modules and tags.

Select an operator

Depending on the selected field or special circumstance, different operators are available. For example, date fields display different operators than text fields.

In addition to typical operators (=, <, >), some fields support special operators, such as:

Operator	Details
contains	Checks if the field contains the value you select from a list. The operator checks many:one relationships.
include	Available for: Current User Role field. Checks if the user is assigned to one of the selected roles. The operator checks 1:1 and Equals relationships.
contains any/includes	Available for: Current User Teams, system fields, and any single-selection Team UDF. The contains any operator checks many:many relationships. The includes operator checks 1:many relationships. If you choose contains any or includes, the next operand choice should either be Current User Teams and/or actual team names. These conditions can be useful when you want to make different permissions for users within specific teams.
is empty	Checks if the field is empty.
is modified	Checks if the field is modified from its original value. This operator is not available for new entities.
Current and Original operators	You can set conditions that assess the original value of a field (when the entity was first accessed) or the current value of a field (because you may have changed the field value since the entity was initially accessed). To base the condition on the original value, select an operator under the heading Original in the operator drop-down list. To base the condition on the current value, select an operator under the heading Current in the operator drop-down list.

Set a value

In the next box, enter a value. You can enter a value or select one or more values from a list. If you select multiple values, they are connected with an Or statement.

For user fields, you can enter [Current User] as a value. If necessary, add AND/OR expressions to the condition.

Note: If you are using an Enterprise license, you cannot set the user field for all workspaces in a shared space. This capability is blocked since each workspace may have different users.

If necessary, add AND/OR expressions to the condition.

As you build the condition, a textual representation of the condition is displayed in the Description box.

Note: Conditions can evaluate to false if ALM Octane encounters a field in a rule definition that it cannot process because the field does not exist. Sometimes this is because a field was removed from the project. There are situations where this is not an error, but part of the logic necessary to implement your organization's policy.

By default, rules are activated. For details, see Business rules.

After you save the rules, ALM Octane automatically runs them.

Activating and deactivating rules

By default, rules are activated when they are defined. To deactivate a rule after it is defined, select the rule in the Rule list and click OFF.

When creating rules that determine if a field is required or read-only, only one rule can be activated for a specific field.

For example, you cannot activate two rules on the field Priority, one making the field Priority mandatory and the other making the field Priority optional, at the same time. Both rules can exist, but they cannot both be activated.

Rules for manual test runs

Consider the following when designing rules for manual test runs:

Rules triggered by manual test run creation

Rules that are defined to be triggered when manual test runs are created, are not triggered in cases where runs are created in bulk. This applies when either running or planning a group of tests or a test suite.

To ensure that the rules are triggered in these cases, define the rules to run also when the entities are updated. This way, the rule actions are activated when the testers update the runs, and they receive relevant alerts and required fields.

Rules for Gherkin test runs

A manual run entity can represent either a manual test run or a manual run of a Gherkin test.

To make sure both types are covered in a rule for a manual run, define the conditions in a way that refers to both types. For example, show an alert in case:

Phase[Manual]=not_reviewed OR Phase[Gherkin]=not_ready

Next steps: