Permissions: Users must have the Study Configure privilege to create, manage, and run rules.

A rule in Orchestrator is a saved set of conditions, created with the Condition Builder or the SQL Editor, that examines imported study data to find records that match the specified criteria. When triggered during import or by manual execution, a rule can generate issues and, for bidirectional EDC setups, open related queries. Rules can be added, edited, and deleted throughout the study.

Create Rule(s)

Access Orchestrator

1. Click the 9-dot icon to open the Platform Menu.
2. Select Study Management → Orchestrator on the left, then choose the study on the right to open Orchestrator.
3. Click the Add Rule (plus sign) icon in the master header. The Add Rule window opens on Step 1: Build with the Condition Builder tab selected.

Step 1: Build

Use the Condition Builder tab or SQL Editor tab to build the conditions. 

Using the Condition Builder

Create a Simple Rule (1 or 2 conditions)

1. When: The first condition is defaulted to When rather than AND or OR. There is no action to take here.
2. Data Store: Type or select the Data Mart or Staging Area from the drop-down.
3. Domain: Type or select the Domain from the drop-down or use a wildcard / character substitution.
4. Field: Type or select the Field from the drop-down or use a wildcard / character substitution.
5. Operator: Select the Operator from the drop-down. By default, Include Selection is selected. Click the Exclude Selection if appropriate. 
6. Value: Type in the value for the field, or select Add Token. See the Add and Manage Tokens in this article. 
7. To add another condition, click the Add (+) icon and choose Add Condition. Select AND or OR from the dropdown on the left of the new row. (To add three or more conditions, see the section below to create an advanced rule.)
8. Repeat steps 1 through 6 to complete the second condition. 
9. Optionally, reorder the conditions by clicking the 6-dot icon to the left and dragging above or below other conditions.

10. Click the Preview button at the bottom left. This triggers a validation check, displaying a success or error message. An error message displays if any field is not filled in. 

    A separate window opens, showing the records that meet the rule conditions and the related fields in the Rule Preview table. The SQL Preview section displays the SQL statements used to generate the results, along with the validation output.

    To close the window, click the Close button at the bottom or the X at the top right.

11. If you need to delete a condition, click the checkbox at the left of the condition and then click the Delete button.
12. Click Save.

Create an Advanced Rule (3 or more conditions / with Grouping)

In Orchestrator, the AND operator is evaluated before the OR operator when using three or more conditions. Users can use the Add Group feature to control the evaluation order, ensuring that the logic aligns with the rule's intent.  

1. Build the first condition(s) as in steps 1–7 above.
2. When two or more conditions must be evaluated together, click Add (+) and choose Add Group. Two rows are added inside a blue block. The first row begins with When; additional rows begin with AND or OR. Complete steps 2–6 above for each row.
3. Group header operator: In the blue header, choose AND or OR to control how the entire group connects to the condition above.
4. To create a group from existing rows, select the checkboxes at the left for the desired rows and click the Group button.
5. To remove a group and retain the conditions, click Ungroup. Note: removing a group can change results when mixing AND and OR.
6. Click the Delete Group button to remove the entire group; confirm Delete or Cancel.
7. Finish building the condition for the rule by following steps 9-11 above.

Using the SQL Editor

Use this option to build the rule directly in the SQL Editor.

Tip: When switching to the SQL Editor, any conditions previously added using the Condition Builder will be automatically transformed into SQL statements. 

1. Click the Enable SQL Editor button. 
   A warning message displays, 'Are you sure you want to enable SQL Editor? If you enable SQL Editor, you will disable the Condition Builder and any changes you made.'
2. Click Enable to continue, or Cancel to dismiss.
3. Build the rule using the SQL Editor.

4. Click the Preview button at the bottom left. This triggers a validation check, providing a success or error message. An error message displays if any field is not filled in.

   A separate window opens, listing the records that meet the rule conditions and the defined related fields in the Rule Preview table. The SQL Preview section displays the SQL statements used to generate the results, as well as the run-time output of the validation.

   Click the Close button at the bottom or the x at the top right to close the window.

5. Click Save.

Add and Manage Tokens

To Add a Token:

1. Within the Add / Edit Advanced Filter window, click in the Value field.

2. Click Add Token from the drop-down. The Add Token window opens.

   

3. Name: Enter the name of the token (notice it begins with @).
4. Description: Enter a description of the token.
5. Value / SQL: Select either Value or SQL.
6. Value: If Value was selected, enter the value.
7. SQL: If SQL was selected, enter the SQL Query.
8. Click the Validate button.
   1. The token editor may throw errors:
      1. Error (red text): if entered SQL does not have proper syntax, 'Invalid Sql statement: Syntax error in token.'
      2. Warning (yellow text): if the entered SQL has proper syntax but references to tables or columns do not exist in the data, 'Invalid object name' or 'Invalid column name.' 

   2. Update the SQL if needed. 

      Note: A token can be saved with warnings, but not with errors.

9. Click the Save button.

To Edit a Token:

1. Within the Add / Edit Advanced Filter window, click in the Value field.

2. Hover over the name of the Token to edit.

   

3. Click the Edit Token icon. The Edit Token window opens.
4. Make changes as needed.
5. Click the Validate button. 
6. Click the Save button.

To Delete a Token:

1. Within the Add / Edit Advanced Filter window, click in the Value field.

2. Hover over the name of the Token to delete.

   

3. Click the Delete Token icon. A Delete Token confirmation window opens.
4. Click OK to confirm, or Cancel to dismiss.

Step 2: Information

Within the Add / Edit window, define the Basic Information and Issue Information.

1. In the Create / Edit Rule window, click Step 2: Information.
   Basic Information
2. Name: Enter the name of the rule.
3. Tag: Select the tag from the drop-down. (Tags are managed in Configuration.)
4. Description: Enter a description of the rule.
5. Status: Select Active or Inactive. When Active is selected, the rule will automatically run when data are imported. When Inactive is selected, a user with the Study Configuration privilege can manually run the rule.
6. Related Fields: Select related fields from the drop-down. These fields will be for reference only and do not impact the rule.
   Issue Information
7. Primary Field: Select the field from the drop-down where the issue will be created.
8. Priority: Select the priority from the drop-down.
9. Assign To: Select User, Role, or User Group.
10. User / Role / User Group: Select from the drop-down.
11. Due in Days: Enter the number of days, or use the up/down arrows.
12. Send Notification to the User / Role / Group: Check the box and select either Send immediately or Send in Batch. (If Send in Batch is selected, be sure the study is configured to send issues in batch.)
13. Issue Text: Enter the issue text. The left curly bracket can be used to enter replacer values.
14. Click the Preview button at the bottom left.
    This triggers a validation check, and provides a success or error message. An error message displays if not all fields are filled in.
    A separate window opens, listing the records that meet the rule conditions and the defined related fields in the Rule Preview table. The SQL Preview section displays the SQL statements used to generate the results, as well as the run-time output of the validation.
    
    Click the Close button at the bottom or the x at the top right to close the window.
15. Click Save.

Step 3: Action

For studies configured for bidirectional queries with the EDC system, users can enable automatic query creation. When an issue is created as a result of a rule, a related query will also be created.

1. In the Create / Edit Rule window, click Step 3: Action tab.
2. Use the toggle to Enable query creation.
3. Category: Select the category from the drop-down.
4. Domain: Select the domain from the drop-down.
5. Field: Select the field from the drop-down.
6. Notification Group: Select the notification group from the drop-down.
7. Query Text: Enter the query text. The left curly bracket can be used to enter replacer values.
8. Click the Preview button at the bottom left.
   This triggers a validation check, and provides a success or error message. An error message displays if not all fields are filled in.
   A separate window opens, listing the records that meet the rule conditions and the defined related fields in the Rule Preview table. The SQL Preview section displays the SQL statements used to generate the results, as well as the run-time output of the validation.
    
   Click the Close button at the bottom or the x at the top right to close the window.
9. Click Save.

Manage Rule(s)

Edit Rules

1. Click the checkbox to the left of the rule to edit. 
2. Click the Edit icon in the master header, or click the rule name (blue hypertext). The Edit Rule window opens.
3. Make the appropriate updates in the Edit Rule window.
4. Click the Preview button. 
5. Confirm the updates in the Preview window.
6. Close the Preview window.
7. Click Save.

Deactivate / Activate Rules

By default, rules are active when first created and will be included in the Orchestrator evaluations and actions. Deactivate a rule to suspend it, and it will be skipped on all runs until reactivated. Deactivation does not retroactively remove prior outputs.

1. Click the checkbox to the left of the rule to deactivate / activate.
2. Click the Deactivate button in the master header. Notice the checkmark in the Active column is removed. This rule will not run until it is reactivated.
3. To Activate the rule, click the checkbox to the left to highlight the row.
4. Click the Activate button in the master header. The checkmark in the Active column displays and the rule will run again.

Delete Rules

1. Click the checkbox to the left of the rule to delete. 
2. Click the Delete icon in the master header.
3. Click Confirm to confirm the deletion.

Best Practices for Rule Creation

• When using the Condition Builder, use Preview frequently to validate and review the result set and the generated SQL. Switch to the SQL Editor only when necessary; enabling the SQL Editor disables the visual Condition Builder for the rule. Consider duplicating the rule first to preserve a visual version.
• Use Tokens instead of hard-coding. Create Value tokens for fixed constants (for example, a specific country or site) and SQL tokens for dynamic sets (for example, a subject cohort). Assign clear names to tokens (e.g., @subjects_with_fatigue), and ensure the token output type matches the filtered field. For example, do not use @site = '101 - University Hospital' (string) against DM.SITEID (numeric), because such a mismatch may return no rows.

• In a condition, AND is evaluated before OR. Use a Group (blue block) to control the execution order, so that grouped conditions run first. Example:

  AESER='Y' AND (AEREL='RELATED' OR AEREL='POSSIBLY RELATED') returns records with AESER='Y' and AEREL equal to RELATED or POSSIBLY RELATED.

  AESER='Y' AND AEREL='RELATED' OR AEREL='POSSIBLY RELATED' without the grouping is interpreted as (AESER='Y' AND AEREL='RELATED') OR (AEREL='POSSIBLY RELATED'), which also returns all POSSIBLY RELATED records regardless of AESER.

• Use clear naming and tagging conventions. When naming rules, make it meaningful. Keep the name short, as it is displayed in the Opened By column in the Issues listing. Apply relevant Tags and add a concise Description specifying intent, the tokens used, and the expected outcome.