# Triggering workflows

From the workflow visual designer, on the **Workflow details** tab in the right-side panel, you can configure a workflow **Trigger** mechanism with different execution options:

* **Manual** trigger enables you to execute a workflow manually against one or multiple targets simultaneously.
* **API** Trigger enables you to execute a workflow using the Workflows API.
* **Scheduled** trigger enables you to execute a workflow within the defined timeframe and target devices/users defined by an NQL query.
* **Events** trigger enables you to execute a real-time event workflow defined by an NQL query.

Define these trigger mechanisms to activate workflow executions. After triggering a workflow, you can check its status to identify its outcome.

{% hint style="info" %}
Depending on your license, when configuring a workflow, you can enable Nexthink **Spark** to run the workflow for real-time support requests. Refer to [Creating workflows](https://docs.nexthink.com/platform/user-guide/creating-workflows#optionally-make-the-workflow-available-in-nexthink-spark) for more information.
{% endhint %}

<figure><img src="https://268444917-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxJSUDk9NTtCHYPG5EWs3%2Fuploads%2Fgit-blob-ff54d0addb304b7e717eafdf746d61f078b85284%2Fimage%20(925).png?alt=media" alt=""><figcaption></figcaption></figure>

## How do workflows identify the `user` and `device` when triggered?

Workflow automations always require both `user` and `device` context to start execution. When only one is provide, the system runs the following logic:

* If only a `user` is provided, the workflow automatically identifies the most recently used device for that user.
* If only a `device` is provided, the workflow automatically identifies the last logged-in user for that device.

This ensures that every workflow starts with a valid user–device pair.

{% hint style="warning" %}
If a workflow cannot determine the missing information—for example, no recent `device` or `user` is found—the workflow may not start and its execution ends in the *Expired* state.
{% endhint %}

***

## Triggering a workflow manually <a href="#triggeringworkflows-triggeringaworkflowmanually" id="triggeringworkflows-triggeringaworkflowmanually"></a>

From the workflow visual designer, select the **Manual** trigger, define the workflow **Targets** and validate the workflow logic to manually trigger workflows within Nexthink features:

* Trigger a workflow for one or multiple users or devices after analyzing data in an [investigation](https://docs.nexthink.com/platform/user-guide/investigations).
* Trigger a workflow for a specific device, for example, to resolve an issue from [Device view](https://docs.nexthink.com/platform/device-view#deviceview-usingthedeviceviewright-sidepanelright-sidepanel).
* Trigger a workflow for targeted diagnostics and remediation actions directly from Nexthink [Amplify](https://docs.nexthink.com/platform/amplify/using-amplify#amplify-amplifytabsamplifytabs).

{% hint style="info" %}
Grant users the **Trigger manually all workflows** permission or share the workflow with trigger-specific permissions.

Refer to the[roles](https://docs.nexthink.com/platform/user-guide/administration/account-management/roles "mention") documentation for permission management.
{% endhint %}

To trigger a workflow manually, from the **Investigations** module:

1. Use NQL editor or Visual editor to query a list of the **Devices** or **VDI sessions.** See the image below.
2. Select one or multiple **Devices** or **VDI sessions** and **Execute action**—using the action bar.
3. Select the workflow of interest, identifiable by a crane icon, and run on the selected sessions/devices.

{% hint style="warning" %}
Manually triggering workflows on VDI sessions requires [Nexthink VDI experience](https://docs.nexthink.com/platform/user-guide/vdi-experience).

Only workflows configured for VDI can run on sessions.
{% endhint %}

<figure><img src="https://268444917-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxJSUDk9NTtCHYPG5EWs3%2Fuploads%2Fgit-blob-2a4c07c082cd04b1d25ea5a3c16ce5b0b2781788%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
Refer to the [creating-workflows](https://docs.nexthink.com/platform/user-guide/workflows/creating-workflows "mention") documentation to learn more about workflow design and configuration.
{% endhint %}

## Triggering a workflow via API <a href="#triggeringworkflows-triggeringaworkflowviaapi" id="triggeringworkflows-triggeringaworkflowviaapi"></a>

From the workflow visual designer, select the **API** trigger and validate the workflow logic to trigger a workflow using the Nexthink [Workflows API](https://nexthink.stoplight.io/docs/api/workflows-api-overview).

<figure><img src="https://268444917-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxJSUDk9NTtCHYPG5EWs3%2Fuploads%2Fgit-blob-17a44361ecd3f1c13bfa937f3318c8b513ce1c21%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
Refer to the [creating-workflows](https://docs.nexthink.com/platform/user-guide/workflows/creating-workflows "mention") documentation to learn more about workflow design and configuration.
{% endhint %}

## Triggering a scheduled workflow <a href="#triggeringworkflows-triggeringascheduledworkflow" id="triggeringworkflows-triggeringascheduledworkflow"></a>

From the workflow visual designer, select the **Schedule** trigger and validate the workflow logic to trigger a workflow at specific recurring periods using an NQL query.&#x20;

{% hint style="warning" %}
The system automatically staggers large schedules to ensure stable execution and favor scalability. This may delay workflow execution for some targets during peak hours, even though the workflow schedule remains valid.
{% endhint %}

<figure><img src="https://268444917-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxJSUDk9NTtCHYPG5EWs3%2Fuploads%2Fgit-blob-5ed3db14f903020aaf88ba9278bdce024d695045%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

**Add a schedule** with a query for workflow triggering. Fill in the fields:

* **Name**: Enter a unique name for the schedule.
* **NQL**: Enter an NQL query for the workflow targets, which can either be `devices` or `users`.
* **Recurrence**: Configure the time and recurrence of the schedule. Executions start at the scheduled time and can be distributed evenly over the hour.
* **Workflow parameters**: Use parameters to schedule the workflow.
  * Set parameters with:
    * A predefined list of values configured in the workflow designer.
    * Custom free text values.
    * Defined attributes in the `list` statement of the NQL query.

Refer to the [#add-workflow-parameters](https://docs.nexthink.com/platform/user-guide/creating-workflows#add-workflow-parameters "mention") documentation for parameter configuration.

## Triggering a workflow by events <a href="#triggeringworkflows-triggeringaneventworkflow" id="triggeringworkflows-triggeringaneventworkflow"></a>

From the workflow visual designer, select the **Event** trigger and validate the workflow logic to trigger a workflow by a real-time event workflow defined using an NQL query.&#x20;

{% hint style="info" %}
Audit logs are also available as event triggers for workflows. Refer to [#audittrailcodes-usingaudittrailcodesininfinitynqlqueries](https://docs.nexthink.com/platform/security/exporting-audit-logs#audittrailcodes-usingaudittrailcodesininfinitynqlqueries "mention").
{% endhint %}

<figure><img src="https://268444917-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FxJSUDk9NTtCHYPG5EWs3%2Fuploads%2Fgit-blob-fb1c8aacafde22e4ab82c74d441ae6d3885f78af%2Fimage.png?alt=media" alt=""><figcaption></figcaption></figure>

**Add a event trigger** with a query for workflow activation. Fill in the fields:

* **Name**: Enter a unique name for the event.
* **NQL**: Enter an NQL query to capture the event triggering the workflow.
  * For the query to be valid, it must contain at least one:
    * Supported **event**.
    * `where` statement in cases where the object can be filtered on.
    * `list` statement.
  * Use supported real-time events and adhere to their limitations. See expandables below.
* **Parameters**: Use parameters to schedule the workflow.
  * Set parameters with:
    * A predefined list of values configured in the workflow designer.
    * Custom free text values.
    * Defined attributes in the `list` statement of the NQL query.

Refer to the [#add-workflow-parameters](https://docs.nexthink.com/platform/user-guide/creating-workflows#add-workflow-parameters "mention") documentation for parameter configuration.

{% hint style="warning" %}
Only real-time events associated with a `device` or `user` can trigger workflows.

Queries such as `alerts.alerts` events do not trigger workflows if they are not linked to a device. This occurs because the **Device** field column is empty when queried from the **Investigations** module.

The system only triggers one workflow per event.
{% endhint %}

<details>

<summary>List of supported real-time events for NQL queries</summary>

Below is a list of supported real-time events:

* `alert.alerts`
* `device_performance.boots`
* `device_performance.hard_resets`
* `device_performance.system_crashes`
* `execution.crashes`
* `remote_action.executions`
* `session.connects`
* `session.disconnects`
* `session.locks`
* `session.logins`
* `session.logouts`
* `session.unlocks`
* `web.events`
* `web.transactions`
* `web.errors`
* `web.page_views`

</details>

<details>

<summary>Events limitations for NQL queries</summary>

* The system does not support filtering using date or time attributes.
* The following limits apply to event trigger configuration:
  * One event trigger per workflow.
  * The use of ratings is not supported.
  * `last_seen` attributes are not supported on any object.
* The system does not support using the following fields in the query from the device object:
  * `last_seen`
  * `login.last_login_user_name`
  * `boot.days_since_last_full_boot`
  * `boot.last_full_boot_duration`
  * `boot.last_full_boot_time`
  * `connectivity.last_connectivity_type`
  * `connectivity.last_local_ip`
* The system does not support the use of the following custom fields:
  * Query-based fields
  * Rule-based fields
* The system does not support the use of the following dimensions in the query:
  * context.\*
  * device.public\_ip.\*
* The system does not support `field`-to-`field` comparisons. For example: `user.upn != device.#last_user_upn`

</details>

<details>

<summary>NQL examples for Event triggering</summary>

The examples below show the NQL queries that you can use with events:

**Slow login event**

Use the following query to identify high login times for a device, including the affected user's username.

```
session.logins
| where time_until_desktop_is_ready > 1s
| list user.ad.username
```

**Driver or storage-related blue screen of death (BSoD)**

Use the following query to respond to a Windows device that experienced a BSoD due to a driver or storage-related issue.

```
device_performance.system_crashes
| where label == 'IRQ_NOT_LESS_OR_EQUAL'
| list error_code
```

**Anti-virus software disabled**

Use the following query when the anti-virus software is disabled and detected remotely.

Use the following query when a disabled anti-virus is detected remotely.This ensures compliance and allows you to perform additional checks on the compliance state of the device.

```
remote_action.#AVCheck.executions
| where outputs.AVActive == 'false'
| list outputs.AVDefinitionVersion
```

</details>

***

## Workflow status: determining the outcome <a href="#workflow-statuses" id="workflow-statuses"></a>

When triggering a workflow, use the status to understand whether it is still running and how it ended.

Review the workflow status by:

* Viewing the workflow execution details page.
* Running an NQL query, including the `status` attribute in the where statement. Additionally, use the `status_detail` attribute to view more detailed information—when available.

Refer to the [#troubleshootingworkflows-usingtheworkflowtimeline](https://docs.nexthink.com/platform/user-guide/monitoring-workflows-dashboard/troubleshooting-workflows#troubleshootingworkflows-usingtheworkflowtimeline "mention") documentation.

The table below outlines the possible workflow statuses and their common meanings.

{% hint style="success" %}
A workflow execution is considered successful when it reaches a configured End block in the workflow design.
{% endhint %}

| Workflow status | Status meaning                                                                                                                                                                                                                                                                                                                                         |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **In Progress** | The workflow has been triggered and is currently working through the logic-configured design.                                                                                                                                                                                                                                                          |
| **Success**     | Successful completion of the workflow.                                                                                                                                                                                                                                                                                                                 |
| **Failed**      | Workflow failed to run due to an unexpected issue.                                                                                                                                                                                                                                                                                                     |
| **Canceled**    | <p>Workflow stopped executing for one of the following reasons:<br>- The workflow has been disabled.<br>- An execution with the same targets and parameters is already running, and the current workflow is considered a duplicate.</p>                                                                                                                |
| **Expired**     | <p>A Thinklet or flow control step within the workflow exceeded the configured timeout period.<br><br>Most commonly, this happens when a remote action Thinklet tries to execute on a device that is offline.<br><br>Refer to the <a data-mention href="../creating-workflows#adaptive-wait-behaviors">#adaptive-wait-behaviors</a> documentation.</p> |