> For the complete documentation index, see [llms.txt](https://docs.docontrol.io/docontrol-user-guide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.docontrol.io/docontrol-user-guide/workflows/define-workflow-settings/trigger-settings.md). # Trigger settings A trigger is usually a SaaS event, an alert, or an inventory action. When the defined event occurs, the workflow is set into motion. A trigger consists of: * **Event** - A specific action in a SaaS application (such as file downloaded), or a DoControl inventory action. * **Conditions** - A subset of the event, including an input value, a comparator, and an input value to check against. {% hint style="success" %} Workflow settings are now **simplified**. DoControl gives you a range of [predefined triggers](#to-define-the-trigger-settings) to choose from, that already include events and pre-populated conditions. {% endhint %} ## Who can initiate a trigger? Both actors and admin users can initiate a trigger by their actions: * **Actor** - A trigger can be initiated by a specific actor involved in the SaaS event. For example, an internal user triggers a workflow by sharing sensitive files with collaborators from non-trusted domains. * **Admin user** - Alternatively, a trigger can be initiated by an admin user in the DoControl interface. For example, a CISO triggers a workflow by clicking the Remediate > Inventory action button to remove external collaborators. #### How are inventory actions different from event-based workflows? Inventory actions are triggered by a DoControl user according to demand, while event-based workflows are triggered every time a specific SaaS event occurs in a specific app.

Workflow type	Trigger	Frequency
Inventory action	DoControl user	On-demand
Event-based workflow	SaaS event	Whenever a specific event occurs

Trigger settings include these parameters: * [Trigger events](#to-define-the-trigger-settings) * [Conditions](#conditions) * [Comparators](#comparators) * [Date comparators](#date-comparators) * [Condition values](#condition-values) * [Condition logic](#condition-logic) ## Trigger events An event is a specific action that occurs in a SaaS application, or a DoControl inventory action. {% hint style="info" %} * Workflow settings are now simplified. DoControl gives you a range of [predefined triggers](#to-define-the-trigger-settings) to choose from, that already include events and pre-populated conditions. * **For existing workflows**: If you change the **app** that triggers the workflow, then the canvas will be reset and all workflow steps will be deleted. {% endhint %} #### To define a trigger event: 1. From the top-left ribbon, enter the workflow name (required) and description (optional). 2. From the **App** drop-down list, select the SaaS app to trigger the workflow.

3. Predefined triggers are displayed according to the app you selected:

4. From the **Trigger** dropdown list, select an event to trigger the workflow: * **Predefined trigger** - Includes a specific event already populated with predefined conditions. * **Event** - Select either an event specific to the SaaS app, or a DoControl event (inventory action).

5. If you select a predefined trigger, the event and some conditions are already populated:

6. Add recommended conditions, or create a custom condition. ## Conditions The conditions are based on data from the specific event you selected in the **Event** field. Each condition includes an input value, a comparator, and an input value to check against. You can define as many conditions as needed by clicking **+And** or **+Or** . You can enter an array of values (using a valid JSON array), and define a condition on **All** array elements or on **At least one**. For more information, see [condition logic](#condition-logic).

#### To define custom event conditions: 1. From the first condition field, enter the [condition value](#condition-values). 2. From the comparator dropdown list, select the [comparator](#comparators). 3. From the second condition field, enter the [condition value ](#condition-values)to check against. 4. You can also select a group of conditions from a [predefined keyword list](/docontrol-user-guide/system-management/settings/lexical-lists.md).

#### To define a workflow condition based on a Google organizational unit: You can define workflow conditions based on a specific Google organizational unit that the actor triggering the workflow belongs to. 1. In your workflow, add a custom condition. 2. Enter the `event.enriched.actorInfo.orgUnitPath` string. 3. Define the organizational path, for example:

## Comparators You can use different comparator types to define your workflow conditions. Each condition automatically determines the relevant input type: * **String** - compares between 2 condition values. * **Boolean** - true or false condition. * **Numeric** - uses mathematical operators to compare 2 condition values. * **Date** - gives a specific date, or compares a date range. The granularity of the date picker includes hours, minutes and seconds. Dates are converted to Coordinated Universal Time (UTC) and compared without timezones. {% hint style="info" %} Only fields that are in ISO 8601 date string format are recognized. {% endhint %} {% tabs %} {% tab title="String" %}

Comparator	Description
Equals	The first condition value is the same as the second condition value.
Doesn't equal	The first condition value is not the same as the second condition value.
Contains	The first condition value includes the second condition value(s).
Doesn't contain	The first condition value does not include the second condition value(s).
Exists in	The first condition value can be found in an array of values of the second condition value(s).
Doesn't exist in	The first condition value cannot be found in an array of values of the second condition value(s).
In group(s)	The first condition value is included in the defined group(s) in the second condition value. See groups.
Not in group(s)	The first condition value is not included in the defined group(s) in the second condition value. See groups.
In trusted domains	The first condition value is included in a predefined set of trusted organization domains. See trusted domains.
Not in trusted domains	The first condition value is not included in a predefined set of trusted organization domains. See trusted domains.
In keyword list	The first condition value is taken from a list of predefined keywords specified in the second condition value: Contains - Includes the specified value from the keyword list Exact match - Contains the exact value from the keyword list Starts with - Value in keyword list begins with this string Ends with - Value in keyword list ends with this string For more information, see lexical lists.
Not in keyword list	The first condition value is taken from a list of predefined keywords specified in the second condition value: Contains - Everything that does not include the values in the keyword list. Exact match - Does not contain the exact value from the keyword list Starts with - Value in keyword list does not begin with this string Ends with - Value in keyword list does not end with this string For more information, see lexical lists.

{% endtab %} {% tab title="Boolean" %}

Comparator	Description
is	True or false

{% endtab %} {% tab title="Numeric" %}

Comparator	Description
=	Equals
!=	Does not equal
>	Greater than
<	Less than
>=	Greater than or equal to
<=	Less than or equal to

{% endtab %} {% tab title="Date" %}

Comparator	Description
is on	Specific day and time (h, min, s) when event occurred.
is not on	Specific day and time (h, min, s) when event did not occur.
is on or before	The event occurred on the specified date and time (h, min, s) or before it.
is on or after	The event occurred on the specified date and time (h, min, s) or after it.
is between	The event occurred in the date range between the `from date` (inclusive) and the `to date`(exclusive).
is not between	The event did not occur in the date range between the `from date` (inclusive) and the `to date`(exclusive).

{% endtab %} {% endtabs %} {% hint style="success" %} Use square brackets \[ ] to include only a subset of dynamic values related to the comparator. {% endhint %} ## Date comparators You can use dynamic date comparators in workflow conditions to compare relative timeframes against runtime dates. This allows you to run a recurring cleanup workflow that evaluates relative dates, and remove sharing based on date conditions. #### Example use cases: * Was this file modified during the last 60 days? * Is the sharing expiration date after the next 30 days? * Is the file share date between 1 January 2023 and 1 May 2023? #### To use dynamic date comparators: 1. Select the `Get event date` macro. 2. Select one of these comparators: * Before * After * In between

3. Select a default time interval, or click **Custom** to define a custom timeframe.

4. For a custom timeframe, select a relative or absolute timeframe: * **Relative** - Enter a past or future number of time units (minutes, hours, days, weeks, months)

* **Absolute** - In the calendar picker, select a start date and time, and an end date and time.

5. Click **Save**. ## Condition values There are a number of ways to input values in the condition fields: * **Select from event** (default) - Select an event field from the dropdown list. * **Use macros -** Select a [macro](/docontrol-user-guide/workflows/define-workflow-settings/trigger-settings.md#macros) from the condition builder. Relevant macros are displayed according to the SaaS application, and the selected event. * **Use query -** Enter the query expression using the **Query event fields** window, containing details from the event in JSONata. The event values in the query are sample values coming from the last event registered in the system. ### Macros You can use query macros from the condition builder to create your workflow. The condition builder displays macro conditions by name instead of the JSONata expression. For example, you can get the names of a file's collaborators by selecting the macro called: Get collaborators. This makes it easier to understand what the condition is trying to achieve. You can also access macros from the Query event fields (JSONata view). {% hint style="info" %} Macros appear according to the SaaS app and the selected triggering event. {% endhint %}

Using query macros from the condition builder to create a workflow

Using macros from the Query event window

## Condition logic The workflow condition builder for both trigger and conditional actions constructs a set of sub-conditions using Boolean arithmetic logic. Boolean operators include **AND** and **OR** and the construction paradigm is as follows: * Sub-conditions are X, Y, Z: ``` (X AND Y) OR (Z) OR (K AND L AND M) ``` * **AND** operator constructs sub-condition groups * **OR** operator is used between groups These examples illustrate a variety of conditions constructed with the workflow condition builder: #### (A) OR (B)

#### (A AND B) OR (C)

#### (A) OR (B AND C AND D)

--- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.docontrol.io/docontrol-user-guide/workflows/define-workflow-settings/trigger-settings.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.