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.

Refer to the Creating workflows documentation to learn more about workflow design and configuration.

Triggering a workflow manually

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.

• Trigger a workflow for a specific device, for example, to resolve an issue from Device view.

• Trigger a workflow for targeted diagnostics and remediation actions directly from Nexthink Amplify.

Grant users the Trigger manually all workflows permission or share the workflow with trigger-specific permissions.

Refer to theRoles documentation for permission management.

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.

Manually triggering workflows on VDI sessions requires Nexthink VDI experience.

Only workflows configured for VDI can run on sessions.

Triggering a workflow via API

From the workflow visual designer, select the API trigger and validate the workflow logic to trigger a workflow using the Nexthink Workflows API.

Refer to the Creating workflows documentation to learn more about workflow design and configuration.

Triggering a scheduled workflow

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.

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, vdi_sessions 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 in Designer.

    • Custom free text values.

    • Defined attributes in the list statement of the NQL query.

Refer to the Add workflow parameters documentation for parameter configuration.

Scheduling workflows on VDI sessions requires Nexthink VDI experience.

Triggering a workflow by events

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.

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 Designer.

    • Custom free text values.

    • Defined attributes in the list statement of the NQL query.

Refer to the Add workflow parameters documentation for parameter configuration.

List of supported real-time events for NQL queries

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

Events limitations for NQL queries

• 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.*

NQL examples for Event triggering

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

The system only triggers one workflow per event.

Triggering workflows by events on VDI sessions requires Nexthink VDI experience.

---

Workflow status: determining the outcome

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 Using the Workflow execution timeline for troubleshooting documentation.

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

A workflow execution is considered successful when it reaches a configured End block in the workflow design.

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	Workflow stopped executing for one of the following reasons: - The workflow has been disabled. - An execution with the same targets and parameters is already running, and the current workflow is considered a duplicate.
Expired	A Thinklet or flow control step within the workflow exceeded the configured timeout period. Most commonly, this happens when a remote action Thinklet tries to execute on a device that is offline. Refer to the Handling expirations in workflows documentation.