Business rule actions

Following are the actions that business rules can perform.

Add comment

Adds a comment to the item when the item is either created or updated.

Back to top

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.

Back to top

Alert user

If an item matches the rule condition, an alert displays 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:

Prevent testers from opening defects on previous releases

Back to top

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, open the Workflow tab, select a phase or transition for which you want to create a rule, and click the Rules tab.

Example:

Prevent developers from closing a defect

Back to top

Make read-only

Makes fields read-only. If the rule is triggered, the selected fields cannot be updated.

Back to top

Make required

Makes fields mandatory. If the rule is triggered, the selected fields must be filled before the item can be saved.

Example: Make fields required

Back to top

Modify lookup list

Change the available values for a list field or reference field.

List field

Change the available values for a list field in one of the following ways:

  • Use a subset of a list.

  • 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: 

Reference field

Change the available values for a reference field to include only the items that match a specified filter. For details on reference fields, see Reference fields.

Select the reference field and define the filter. For details, see Advanced filters.

Caution: The modified lookup list for reference fields is not enforced in server operations, such as API calls and bulk updates in the UI.

Example:

Back to top

Send email

Send an email upon the occurrence of selected events.

Submission mode: Select one or more triggers that cause an email to be sent. Available triggers:

  • An item is created

  • An item is updated

  • An item is deleted

  • A comment is added or edited

The body of the email is generated automatically.

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. An email is then send 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 add external email addresses to the Send to list, admins must enter the allowed email domains as values for the ALLOWED_EXTERNAL_EMAIL_DOMAINS parameter. The distribution list should also be configured to accept emails from outside of their domain. 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.

Example:

Send an email when an item is updated

Back to top

Set field value

Updates a field's value in one of the following ways. 

Method Details
Set a fixed value Assigns a fixed value to the field.
Set a value using a formula Assigns a value dynamically based on other field values using JavaScript expressions. For details, see Value formulas.

Copy a value from another field

 Copies the value from another field.
Clear a field's value Empties the fields value.

Timing

The trigger that causes the field value to be set. Select one of the following timings:

Timing Description
When creating an entity The field value is set when the Add dialog box is opened, or when duplicating or splitting an item.
When updating a field

The field value is set when another field is updated. To add a validation for API operations, see Business rule actions.

Note: the action triggers as the field is being edited. There is no validation that the new field value is different than the old field value. To force a validation that the field value has changed when updated by an API operation, in the Condition tab, add a condition on the selected field using the is modified operator. For details see Business rule actions.
When saving an entity
  • The field value is set when a new item is saved, an existing item is edited, or an item is duplicated or split.
    		•
    When a related entity in the condition is added or removed In the rule condition, use the Children count field. The business rule triggers when the Children count value changes, upon a related item being added or removed.

    Special field values

    There are some special field values that you can set:

    • If the action sets a user field, you can select the [Current User] to set the field to the currently logged-in user.

    • Increment an integer or date field by a certain amount. Available only with the When saving an entity timing.

    Examples

    Back to top

    Show/Hide fields in form

    Adds or removes fields from a form in different scenarios.

    Select which fields to show or hide in entity forms based on workspace-specific needs. This enables you to use shared forms in each workspace, while providing the means to customize the form to meet your team's unique requirements.

    You can choose where a field is displayed in relation to other fields on the form: before, after, or in the default position. If you choose to show a field that is not displayed by default, it is displayed in the More section of the form.

    Fields are displayed in the form according to the order of selection.

    • If fields are already placed in the form due to other business rules, their position is changed according to the Show/Hide field rule. This means that the Show/Hide field in form business rules are always triggered after the Use form business rules, regardless of the order in which they were created.

    • If a user modifies the form affected by the Show/Hide field rule, the next time the user opens the form, the fields are displayed according to the user's changes, rather than following the business rule.

    You can select up to 10 fields to show or hide in the same business rule.

    Examples: 

    Back to top

    Trigger webhook

    Webhooks are supported 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 are used 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, the following fields are sent 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.

    Back to top

    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

    Back to top