Create a trigger

Create triggers to automate your company's workflow by defining a set of actions that automatically execute when a specific change occurs. Triggers are associated with individual tables and can be configured for record changes or metrics thresholds.

Create a trigger on records

Define a set of actions that automatically execute when changes to records occur. You must create the table that contains the records before defining the trigger.

Navigate to the trigger configuration window

1. Open the Results app.
2. Navigate to the collection and analysis that contains the table you want to update.
3. For the table you want to automate, click the number in the Triggers column.
4. Optional. To edit the order of execution for multiple existing triggers, drag each trigger to the appropriate place in the list. Triggers execute from top to bottom in the order specified.
5. Click New in the Automate dialog box. The trigger configuration window opens.
   Note

   To edit a trigger you previously created, click the trigger name.

Define the trigger

1. Enter the name for the trigger in the text box. The character limit is 255.
2. In the Conditions area, select Record.
3. Define the options that will cause the trigger to execute:

   Option	Description
   Condition	Executes the trigger when a defined condition or set of conditions is met. You can trigger on idle records by selecting the Updated field and using a relative date such as 1 day ago. Idle records are records that have not been changed in the system for at least the specified period of time. Note Trigger conditions based on datetime fields evaluate using the timezone you have set in your user profile. Do not specify a timezone offset.
   Status	Executes the trigger when a record is assigned a particular status. You can specify multiple statuses. You cannot combine status conditions with real-time new record frequencies. Note Results Admin can select from any status available. All other users can select from any status available in the collection, which is determined by the workflow assigned to the collection.
   Priority	Executes the trigger when a record is assigned a particular priority. You can specify multiple priorities. You cannot combine priority conditions with real-time new record frequencies.

4. Optional. To define multiple conditions within a group, click + Add and select the appropriate condition(s) to define. To remove a condition, click the trash bin .
5. Optional. If you have defined multiple conditions, select ALL only run the trigger if all of the conditions in the group evaluate to true, or select ANY to run the trigger if at least one of the conditions in the group evaluates to true. A single logical operator ALL (AND) or ANY (OR) applies to all conditional expressions inside the group. ALL is the default.
6. Optional. To define conditional expressions using multiple groups, click + Add Group, specify the logical operator (AND or OR), and select the appropriate condition(s) to define. All logical operators outside of the group must be the same (either all AND or all OR). AND is the default. To remove a group, click Delete Group.
7. In the Actions area, define the actions that will occur when the trigger is executed:

   Setting	Description	Notes
   Assign > Users > Workflow group	Controls the visibility of the record	Only members of the assigned workflow group can review the record. If no workflow group is assigned, then all Collection members with sufficient permissions can see the record.
   Assign > Users > Assignee	Identifies the individual who is responsible for the record	Only users that have been identified as Collection members are available for selection in the dropdown list. If a workflow group is assigned, then the assignee must be a member of the workflow group. Note Use the Enable notification switch to control whether the assignee should receive an email when this trigger assigns a record to them.
   Assign > Email from field	Assigns the records to an email from a field in the table if the email address belongs to a Diligent One user	The records are not assigned if the email address from the field: belongs to a Results app user that does not have a role in the Collection that allows record editing is invalid Note Diligent One Platform does not support email addresses with accents or non-Latin characters. Note Use the Enable notification switch to control whether the assignee should receive an email when this trigger assigns a record to them.   To assign records, the email address needs to belong to a Diligent One user.
   Assign > Workflow group from field	Searches the selected table field for a workflow group name, and if a valid workflow group name is identified, the record is assigned to that particular workflow group. Only imported data fields and questionnaire fields with character data type are available for selection. Other fields with any other data type are unavailable.	Only members of the assigned workflow group can review the record. If no workflow group is assigned, then all Collection members with sufficient permissions can see the record. Note Use the Enable notification switch to control whether the assigned workflow group members should receive an email when this trigger assigns a record to them.
   Notify	Sends an email notification to one or more users	When you notify a user, the user receives an email with a link to a table that displays all records (not exclusively the records they have been notified about).
   Questionnaire	Assigns a questionnaire to one of the following: an individual user a specified email address an email address from a column in the table Note Diligent One Platform does not support email addresses with accents or non-Latin characters.	There are two lists of questionnaires to choose from: Linked questionnaires already linked to the table (response columns exist) Unlinked questionnaires that are not linked to the table (response columns added when the first response is submitted) Select Use one questionnaire to respond to all records to send one questionnaire to the recipient and apply response to all records included in the trigger action. Do not select this option to record a distinct response per record. Note Respondents with an associated Diligent One account who are members of the organization must authenticate when clicking the link to complete the survey. Note If you combine Questionnaire actions with the record Updated trigger frequency, respondents receive multiple invitations to answer the questionnaire as the initial response causes an update. You can avoid this situation by including a condition in the trigger that tests whether or not a required question from the questionnaire is blank.
   Status	Changes the status of specified records	Results Admin can select from all statuses available in the collection. Professional Managers and Professional Users are only able to select from statuses they have access to. Access to statuses are defined by workflows. For more information, see Creating workflows in the Results app.
   Priority	Changes the priority of specified records

8. In the Frequency area, define when the trigger will execute:

   Setting	Description	Notes
   Real-time > Record	Evaluates trigger conditions any time a record is created or updated. Select Only for new records to run the trigger against new records only. If you leave this setting unselected, the trigger is run against new and updated records that match the trigger conditions. When is a record considered new? The trigger executes when a new record is published to a data analytic, event report, or survey in the Results app. When is a record considered updated? The trigger executes when any changes to the information or data columns in the table occur. For example, a record status is changed or a questionnaire response is submitted.	By default, the new and updated records are selected. However, you can choose to execute triggers on new records exclusively. You cannot combine status, priority, assignee, or workflow group conditions with real-time new record frequencies.
   Real-time > Questionnaire	Evaluates trigger conditions any time Diligent One receives a response to the selected questionnaire for this trigger's table.	You cannot combine real-time record and questionnaire frequencies.
   Schedule	Evaluates the trigger conditions on a specified frequency (daily, weekly, monthly, quarterly, or on a custom schedule). You can also specify the time to run the trigger. When scheduling a new trigger, the default time zone is the one set in your Launchpad user profile. For more information, see Update your profile.	Time changes due to daylight savings time can cause overnight triggers to execute in ways you did not expect. For more information, see How daylight savings time affects scheduled triggers.

   Note

   Be careful not to match conditions to frequencies in a way that a trigger can never execute. For example, if your conditions require records to have been updated more than one day ago, but you set the set the frequency to real time > records, the trigger will never execute. This is because any time a record is created or modified, it was updated less than one day ago.

Save or run the trigger

1. Do one of the following:
   • To save the trigger configuration, select Save.

     The trigger is saved and listed in the Automate dialog box.

   • To save and preview the trigger configuration, and have the option to immediately execute the trigger, select Save & Preview.

     A dialog box displays listing a sample of records the trigger will run against and perform the defined actions. Up to 200 records are shown in the sample, however, the trigger will run against the total number of records affected. Click Run to execute the trigger.

     Note

     The gap time between an action happening and a trigger executing depends on the size of the table. Small tables (approximately 1000 records in size) normally take a few seconds. Larger tables may take up to several minutes.

2. Click Exit to close the trigger configuration window.

Create a trigger on a metric

Automatically notify a Results app user when a metric reaches a threshold. You must create the metric before defining the trigger.

Navigate to the trigger configuration window

1. Open the Results app.
2. Do one of the following:
   • From the Results home page:
     1. Navigate to the collection and analysis that contains the table you want to update.
     2. For the table you want to automate, click the number in the Triggers column.
   • From the Configure Metric panel, click Manage Triggers.
3. Optional. To edit the order of execution for multiple existing triggers, drag each trigger to the appropriate place in the list. Triggers execute from top to bottom in the order specified.
4. Click New in the dialog box. The trigger configuration window opens.
   Note

   To edit a trigger you previously created, click the trigger name.

Define the trigger

1. Enter the name for the trigger in the text box.

   The character limit is 255.

2. In the Conditions area, select Metric.

   If you navigated to the trigger configuration window from the Configure Metric panel, this option is pre-selected automatically.

   Note

   You can only select a metric that is associated with the Data Analytic, Event Report, or Survey.

3. Select the appropriate metric and define the condition and value that will cause the trigger to execute.

   If you navigated to the trigger configuration window from the Configure Metric panel, the metric is pre-selected automatically.

4. Optional. Define the color of the threshold.
5. In the Actions area, specify which user(s) should be notified if the metric reaches the defined threshold.

   The Notify option is automatically selected. When you notify a user, the user receives an email with a link to the metric.

   Note

   If you don't receive the email notification, check your spam or junk folder.

6. In the Frequency area, define when the trigger will execute:

Setting	Description
Real-time > Record	Evaluates trigger conditions any time a record is created or updated. The Only for new records checkbox is disabled when you create triggers based on metrics. These types of triggers execute when data exceeds the threshold you defined in the condition.
Schedule	Evaluates the trigger conditions on a specified frequency (daily, weekly, monthly, quarterly, or on a custom schedule). You can also specify the time to run the trigger. When scheduling a new trigger, the default time zone is the one set in your Launchpad user profile. For more information, see Update your profile. When editing an existing trigger, the Results app remembers the time zone set previously. Time changes due to daylight savings time can cause overnight triggers to execute in ways you did not expect. For more information, see How daylight savings time affects scheduled triggers.

Save the trigger

1. To save the trigger configuration, select Save. The trigger is saved and listed in the Automate dialog box.
   Note

   The gap time between an action happening and a trigger executing depends on the size of the table. Small tables (approximately 1000 records in size) normally take a few seconds. Larger tables may take up to several minutes.

2. Click Exit to close the trigger configuration window.