Set up rules

You can set up rules that trigger actions in ALM Octane when certain conditions are met.

Overview

Rules contain an action and usually one or more conditions.

You set the action that should occur when the conditions are true.

Actions Examples of actions include making fields required, making fields read-only, setting a default value for a field, and so on.
Conditions

When conditions are met, the rule's action is performed. For example, a rule can make the Fixed in Release field required if the Status field is changed to Fixed. Status=Fixed is the condition.

If you don't specify a condition, the rule's action is always performed. For example, you may want a field to always be required.

Rules are created per entity type.

For certain entity types, ALM Octane provides pre-defined rules. These control basic behaviors, such as assigning tests to their owners.

Sharing rules between spaces

Rules can be defined on the shared space level and on the workspace level.

In isolated spaces, you cannot define rules on the space level, only on its individual workspaces.

Rule created in the shared space run in its associated workspaces. Rules created in a workspace are applied in that individual workspace only.

You can define rules for individual workspaces. The rules are applied in that individual workspace only.

Which rules run first?

Individual workspace rules run first, and then shared space rules. For details, see Do shared space rules or workspace rules take precedence?

Back to top

Plan

Plan out the rules you need and their order.

  • You can combine several actions into one rule, if the actions all share the same condition. This can improve performance.

    Example: Using just one rule, you can set several fields to read-only. Similarly, using a different rule, you can make several fields required.

  • Maybe several rules are needed. For example, to set different lookup lists based on a field value, you need a rule for each lookup list.

  • The order in which the rules appear in the rule list is important. Later rules override the actions of earlier rules.

  • Enterprise Edition: Determine if the rule should be defined on the space level (shared) or on the workspace level.

  • Depending on the rule you are defining, there may be some preliminary steps to take before starting. For example, if you are creating a rule with the Trigger Webhook action, you may want to define credentials before creating the rule.

Back to top

Define rules

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

Create a rule

  1. Plan ahead.

    Depending on the rule you are defining, there may be some preliminary steps to take before starting.

    For example, if you are creating a rule with the Trigger Webhook action, you may want to define credentials before creating the rule.

    For details, see Plan .

  2. In Settings >  Spaces, select a space or a workspace.

  3. Click Entities and select the item for which you want to create a rule.

  4. Click Rules.

  5. You can create a new rule or use an existing one as a basis:

    • Click + to create a new rule.

    • Select a rule and click Duplicate Rule.

Define an action

Click Action and choose the action for the rule to perform.

Enter the relevant values for that action.

For details, see Rule actions.

Define a condition

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

  1. Click Condition to start creating the condition.

    Only one condition can be defined for each rule. But the condition can be a complex condition: This means that you can have one condition with several parts, separated by And and Or operators.

  2. Select a field.

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

    Special circumstances include: 

    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: Not(Edit mode = New) 

    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.

  3. 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 (=, <, >, and so on), some fields support special operators, such as:

    contains

    Checks if the field contains the values you select from a list.

    include

    Checks if the current user role includes the roles you select from a list.

    Available only for the circumstance Current User Role.

    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.

  4. 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.

  5. 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 Understand rule activation and performance.

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

Back to top

Rule actions

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

Action Description
Make
Required

Make fields mandatory.

Example: Making fields required

Make Read-only

Make fields read-only.

Modify Lookup List

Change the values for lists to:

  • Be a subset of the current list.

  • Include the values of a different lookup list, in addition to the current list's values.

  • Include a subset of the values of a different lookup list, in addition to the current list's values.

Enter the name of the list you want to use. For details on creating lists, see Set up lists.

Examples: 

Use Form

Enable users to select different form layouts for adding and editing entities.

The form layout must be predefined in Customization > Forms.

Example: Switching forms

Set Field Value

You can either: 

  • Set a default value for a field when creating or changing an entity.

  • Set a value for a field if the value of another field changes.

Timing is the trigger that causes a value to be set. The timing can be:

  • When the entity is created.

  • When the entity field is changed.

  • When a related entity is changed.

The value can be a new value, empty, or a copy of another field's value.

Examples:

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 will receive 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 will include 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 Set up 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:

    Triggering webhooks (calling a URL)

    For details, see Understand the webhook request payload format.

For end-to-end instructions on working with Trigger Webhook rules, review Trigger webhooks for other applications.

Send Email

Send an email if an entity is created, changed, or deleted.

Submission mode is the trigger that causes the email to be sent.

Email recipients can be users defined in the project or users whose names appear in fields' lookup lists.

Tip: If an integration using an API access key will be sending out emails, you can define the email address that should be used for this purpose. Set the value of the SMTP_NOTIFICATION_SENDER_EMAIL configuration parameter to the email address. For details, see SMTP_NOTIFICATION_SENDER_EMAIL.

The body of the email is generated automatically by ALM Octane.

Alert User

If an entity 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 a item's attributes are updated

Add Comment

Add a comment to the entity when an entity is created or updated.

Submission mode is the trigger that causes the comment to be added.

Assign to Users Adds an item in the My Work module for the user assigned to the selected type (author, detected by, owner, QA owner).
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.

Back to top

Next steps: