Permissions: Users must have the Study Configure privilege to create, manage, run, export, and import 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

Access Orchestrator

1. Access a study.
2. Click the module drop-down and select Orchestrator.
3. Click the Add Rule icon in the toolbar. The Add Rule window opens on Step 1: Build. 

Step 1: Build

Basic Information

1. Name: Enter the name of the rule.
2. Tag: Select the tag from the drop-down. Tags are managed in Configuration. 
3. Description: Enter a description of the rule.
4. Status: Select Active or Inactive. When Active is selected, the rule automatically runs when data are imported. When Inactive is selected, users with the Study Configure privilege can manually run the rule.

Tip: Use clear naming and tagging conventions. Keep the rule name short and meaningful, as it displays in the Opened By column in the Issues listing. Apply relevant Tags and add a concise Description that states the rule intent, tokens used, and expected outcome.

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

Use the Condition Builder

Create a Simple Rule With One or Two Conditions

1. When: The first condition defaults to When rather than AND or OR. No action is required.
2. Data Store: Enter or 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. 

6. Value: Enter the value for the field, or select Add Token. Refer to the Add and Manage Tokens section in this article.

    

   Tip: Use tokens instead of hard-coded values when possible.

   Create Value tokens for fixed constants and SQL tokens for dynamic sets. Use clear token names and ensure the token output type matches the filtered field.

    

7. To add another condition, click the Add (+) icon and select Add Condition. Select AND or OR from the drop-down on the left of the new row. To add three or more conditions, refer to the Create an Advanced Rule With Grouping section in this article.
8. Repeat steps 1 through 6 to complete the second condition if needed. 

9. Optionally, reorder the conditions by clicking the 6-dot icon to the left and dragging above or below other conditions.

   Tip: Use Preview frequently to validate the condition logic, review the result set, and inspect the generated SQL before saving the rule.

10. Click Preview. This triggers a validation check and displays a success or error message. An error message displays if any required field is incomplete.

    The Rule Preview window opens and displays records that meet the rule conditions, along with any related fields included in the preview results. The SQL Preview section displays the SQL statements used to generate the results, along with the validation status and run time.

    To close the window, click Close or the Close icon.

11. To delete a condition, select the checkbox next to the condition and click Delete.
12. Click Save.

Create an Advanced Rule With Grouping

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

Tip: In a condition, AND is evaluated before OR. Use a Group to control the evaluation order when the rule includes mixed logic.

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 next to 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.

Use the SQL Editor

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

Tip: Use the SQL Editor only when needed. Enabling the SQL Editor disables the visual Condition Builder for the rule. Consider duplicating the rule first to preserve a visual version.

1. Select the SQL Editor tab.
2. 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.
3. Click Enable to continue, or Cancel to dismiss.
4. Build the rule using the SQL Editor.

5. Click Preview. This triggers a validation check, providing a success or error message. An error message displays if any required field is incomplete.

   A separate window opens, listing the records that meet the rule conditions 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 Close or the Close icon.

6. Click Save.

Add and Manage Tokens

Add a Token

1. In a condition row, click in the Value field.

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

   

3. Name: Enter the name of the token. The token name begins with @.
4. Description: Enter a description of the token.
5. Value / SQL: Select either Value or SQL.
6. Value: If Value is selected, enter the value.

7. SQL: If SQL is selected, enter the SQL query.

   Tip: Use Value tokens for fixed constants and SQL tokens for dynamic sets. Ensure the token output type matches the filtered field to avoid unexpected results.

   1. Click the Validate button. The token editor may display the following validation messages:
      • Error (red text): Displays when the entered SQL does not contain proper syntax. Example: 'Invalid Sql statement: Syntax error in token.'
      • Warning (yellow text): Displays when the entered SQL has proper syntax but references to tables or columns do not exist in the data. Example: 'Invalid object name' or 'Invalid column name.' 

      • Update the SQL if needed. 

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

8. Click Save.

Edit a Token

1. In a condition row, 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. If the token uses SQL, click the Validate button. 
6. Click Save.

Delete a Token

1. In a condition row, 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 the token, or click Cancel to close the window without deleting the token.

Step 2: Action

Specify actions to take when the rule completes. Users can configure issue and query creation independently based on the rule requirements. 

Tip: Configure only the actions needed for the rule purpose. A rule can create an issue, create a query, do both, or be used only for monitoring and reporting.

Issues

1. In the Add / Edit Rule window, click the Step 2: Action tab. 
2. Use the toggle to Enable issue creation.
3. Primary Field: Select the field from the drop-down where the issue will be created.
4. Priority: Select the priority from the drop-down. Issue priorities are configured in Platform Administration > Configuration > Issue Priority.
5. Assign To: Select User, Role, or User Group.
6. User / Role / User Group: Select from the drop-down.
7. Due in Days: Enter the number of days, or use the up / down arrows.
8. Send Notification to: Select how and when notifications are sent for issues created by the rule.
   • None: No notification is sent.
   • Immediately: Notifications are sent as soon as the issue is created.
   • In Batch: Notifications are sent in batches. This option requires the study to be configured to send issue notifications in batch via a scheduled task. 
   • Defer Notification: Notifications are not sent automatically. Users can manually send deferred notifications later from Global Issues.

9. Issue Text: Enter the issue text.

   To use replacement values, enter an opening curly bracket ({) to display a list of available fields. Select a field to insert {FIELD_NAME} automatically.

10. Related Fields: Select related fields from the drop-down list. These fields are included for reference only and do not impact rule execution. They display in the Issue Details panel to provide additional context for the issue.

    

Queries

For studies configured for bidirectional queries with the EDC system, users can enable automatic query creation.

1. Use the toggle to Enable query creation.
2. Category: Select the category from the drop-down. Query Categories are managed in Configuration.
3. Domain: Select the domain from the drop-down.
4. Field: Select the field from the drop-down where the query will be created.
5. Notification Group: Select the notification group from the drop-down.

6. Query Text: Enter the query text.

   To use replacement values, enter an opening curly bracket ({) to display a list of available fields. Select a field to insert {FIELD_NAME} automatically.

Note: Rules can be configured to create an issue, a query, or both. Each action is optional and can be turned on independently, depending on the rule's purpose. A rule can also exist just for monitoring or reporting without triggering any automated actions. 

Preview and Save

1. Click Preview. This triggers a validation check, displaying a success or error message. An error message displays if required fields are incomplete. 

   The Rule Preview window opens and displays records that meet the rule conditions, along with any related fields included in the preview results. The SQL Preview section displays the SQL statements used to generate the results, along with the validation status and run time.

   To close the window, click Close or the Close icon.

2. Click Save.

Manage Rules

Tip: Reuse rules by exporting them from one study and importing them into another study or URL. Before import, maintain consistent naming, tagging, and token conventions to support compatibility with the target study configuration. Refer to the Export and Import Rules in Orchestrator article for details.

Edit Rules

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

Deactivate or Activate Rules

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

1. Select the rule row(s) to deactivate or activate.
2. Click the Deactivate button in the toolbar. The checkmark in the Active column is removed, and the rule does not run until it is reactivated.
3. To activate the rule, select the rule row.
4. Click the Activate button in the toolbar. The checkmark displays in the Active column, and the rule runs again.

Delete Rules

1. Select the rule row(s) to delete. 
2. Click the Delete Rule(s) icon in the toolbar.
3. Click Confirm to delete the rule(s), or Cancel to close the window without deleting the rule(s).

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-coded values when possible. 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 grouped conditions are evaluated first. 
  Example:
  AESER='Y' AND (AEREL='RELATED' OR AEREL='POSSIBLY RELATED')
  Returns records where AESER='Y' and AEREL equals RELATED or POSSIBLY RELATED.
  AESER='Y' AND AEREL='RELATED' OR AEREL='POSSIBLY RELATED'
  Without grouping, the condition is interpreted as:
  (AESER='Y' AND AEREL='RELATED') OR (AEREL='POSSIBLY RELATED')
  This condition also returns all POSSIBLY RELATED records regardless of AESER.
• Use clear naming and tagging conventions. When naming rules, use meaningful names. 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.
• Reuse rules by exporting them from one study and importing them into another study or URL. For example, export rules from a study on an elluminate test URL and import them into the corresponding study on the production URL. Maintain consistent naming, tagging, and token conventions before import to ensure compatibility with the target study configuration.