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, generate queries. Rules can be added, edited, and deleted throughout the study.

Create Rules

The Condition Builder or SQL Editor can be used to build the conditions.

1. Access a study.
2. Select Orchestrator from the module drop-down.
3. Click the Add Rule icon in the master header. By default, the Add Rule window opens with the Step 1: Build tab and Condition Builder tab displaying.

Step 1: Build

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

Condition Builder

Use the Condition Builder to create a rule. 

1. When: The first condition defaults to When instead of AND or OR. No action is required.
2. Data Store: Select the Data Mart or Staging Area from the drop-down.
3. Domain: Enter or select the domain from the drop-down or use a wildcard / character substitution.
4. Field: Enter 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. Select Exclude Selection if appropriate. Options include Equal To, Greater Than, Greater Than or Equal To, Less Than, Less Than or Equal To, Between, Null/Empty, Contains, or Exists.
6. Value: Enter a value or select Add Token. See Add and Manage Tokens for details.
7. Optionally, click the Add icon and select Add Condition or Add Group.

Add Condition: 

8. AND or OR: Select the checkbox, then select AND or OR.
9. Repeat the steps above.

Add Group:

1. Two rows are added as a group.
2. AND or OR: Select AND or OR from the drop-down in the group header.
3. Repeat the steps above.
4. Optionally, ungroup or delete a group of rules. 
   1. Click the Ungroup button to remove the grouping.
   2. Click the Delete Group button. A confirmation window opens. Click Delete to continue, or click Cancel to close the window without deleting the group.
5. Optionally, delete a row. Select the checkbox next to the row and click the Delete icon. Click Yes to continue, or No to keep the row.
6. Optionally, reorder the conditions by clicking the 6-dot icon and dragging the condition to a new position.
7. Click Preview. This triggers a validation check, and provides a success or error message. An error message displays if required fields are incomplete.
8. A separate window opens and lists 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 and the run-time output of the validation.
9. Click Close or the Close icon to close the window.
10. Click Save.

Use 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 automatically transform into SQL statements. 

Tip: Use the SQL Editor only when needed. Enabling the SQL Editor disables the visual Condition Builder for the rule.

1. Click the Enable SQL Editor button. A warning message displays.
2. Click Enable to continue, or Cancel to close the warning message.
3. Build the rule using the SQL Editor.
4. Click Preview. This triggers a validation check and displays a success or error message. An error message displays if required fields are incomplete.
5. 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 and the run-time output of the validation.
6. Click the Close button or the Close icon to close the window.
7. Click Save.

Add and Manage Tokens

Add a Token

1. In the Add Rule 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 display the following validation messages:
      • Error (red text): Displays when the entered SQL does not have proper syntax, 'Invalid SQL statement: Syntax error in token.'
      • 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 as needed. 

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

9. Click Save.

Tip: Use Value tokens for fixed constants and SQL tokens for dynamic sets.

Edit a Token

1. In the Add / Edit Rule window, click in the Value field.
2. Hover over the token name.
3. Click the Edit Token icon. The Edit Token window opens.
4. Make changes as needed.
5. Click the Validate button. 
6. Click Save.

Delete a Token

1. In the Add / Edit Rule window, click in the Value field.
2. Hover over the token name.
3. Click the Delete Token icon. A Delete Token confirmation window opens.
4. Click OK to delete, or click Cancel to close the window without deleting the token.

Step 2: Information

In 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, the rule automatically runs 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 are included for reference only and do not affect rule execution.
   Tip: Use clear naming and tagging conventions. Keep the rule name short and meaningful. Apply relevant tags and add a concise description that explains the rule intent and expected outcome.

Issue Information

7. Primary Field: Select the field from the drop-down where the issue is 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 the user, role, or user group 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: Select the checkbox, then select Send Immediately or Send in Batch. If Send in Batch is selected, the study must be configured to send issues in batch.
13. Issue Text: Enter the issue text. Enter an opening curly bracket ({) to display available replacement fields. Selecting a field inserts it automatically.
14. Click Preview. This triggers a validation check and displays a success or error message. An error message displays if required fields are incomplete.

15. A separate window opens and lists 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 and the run-time output of the validation.

    Tip: Use Preview frequently to validate the condition logic before saving the rule.

16. Click Close or the Close icon to close the window.
17. Click Save.

Step 3: Action

For studies configured for bidirectional queries with the EDC system, users can enable automatic query creation. When a rule creates an issue, the rule also creates a related query.

1. In the Create / Edit Rule window, click the 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. Enter an opening curly bracket ({) to display available replacement fields.
8. Click Preview. This triggers a validation check and displays a success or error message. An error message displays if required fields are incomplete.
9. A separate window opens and lists 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 and the run-time output of the validation.
10. Click Close or the Close icon to close the window.
11. Click Save.

Edit Rules

1. Select the rule to edit.
2. Click the Edit icon in the master header, or click the rule name hyperlink. The Edit Rule window opens.
3. Make the updates.
4. Click Preview. 
5. Confirm the updates in the Preview window.
6. Click Close to close the Preview window.
7. Click Save.