Triggering workflows

Workflows allow you to trigger a workflow with different execution options. There are four mechanisms to execute a workflow:

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

Triggering a workflow manually

Trigger workflows manually using the Nexthink graphical interface. Users can initiate workflows based on specific needs or insights. For example, workflows can be launched from the following:

Investigations: Start a workflow for one or multiple users or devices after analyzing data in an investigation.
Device View: Trigger a workflow for a particular device to, for example troubleshoot or resolve an issue.
Amplify: Initiate workflows directly from Nexthink Amplify for targeted diagnostics and remediation actions.

This manual triggering option allows users to address immediate or unique scenarios without relying on automated triggers. Before triggering a workflow manually, ensure:

Workflow configuration:
- One or more workflows are set up to allow manual triggers.
- Targeting: Specify whether the workflow targets Devices, Users, or both.
Permissions:
- Grant users the Trigger manually all workflows permission or share the workflow with trigger-specific permissions.

To trigger a workflow manually:

Select Investigations from the main menu.
Click the New button to run your NQL query. The Visual editor tab opens by default.
Switch to the NQL editor tab and write an NQL query to list all devices or users.
Click the Run button to show the query results.

Select one or more devices to execute the action on or select all of them using the checkbox at the top of the first column.
Once you select the first item, an action bar appears with the total number of entries chosen, along with the Execute action button.

Click the Execute action button. An action modal appears.
Select the relevant action and click the Run devices or Run users button, depending on the outcome of the investigation.

Triggering a workflow via API

To trigger a workflow using the Nexthink API, refer to the Workflows API documentation for more information.

Triggering a scheduled workflow

Trigger a workflow at specific recurring periods and define the workflow targets using an NQL query. To trigger a scheduled workflow:

Select Workflows from the main menu.
To access a workflow, you have two options:
- Select Manage workflows to edit an existing workflow.
- Click the New button to create a new workflow.
In the General tab, select Schedule.

Click the Add Schedule button to open the schedule modal.

Fill in the following 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 timing and recurrence of the schedule.
- Workflow parameters: Use parameters to schedule the workflow. Define the parameters in Designer or with a NEAL script. Refer to the Designer documentation for more information.
  - Set parameters with:
    A predefined list of values in Designer.
    Custom free text values.
    Defined attributes in the list statement of the NQL query.
Click the Add to trigger the workflow.

Triggering an event workflow

The system only triggers one event per workflow.

Trigger a real-time event workflow defined using an NQL query. The system triggers the workflow when Nexthink receives the event.

To trigger an event workflow:

Select Workflows from the main menu.
To access a workflow, there are two options:
- Select Manage workflows to edit an existing workflow.
- Click the New button to create a new workflow.
In the General tab, click the Events > Add Event button to open the event modal.

Fill in the following 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.
  - See the Supported Events section for a list of events that you can use and the Event Limitations section for more information about supported query elements.
- Parameters: Use parameters to set the values when the workflow is triggered. Define the parameters in Designer or with a NEAL script. Refer to the Designer documentation for more information.
  - 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.
Click the Add button to trigger a workflow.

NQL examples for event triggering

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

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

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

Supported 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

Event Limitations

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

Workflow statuseside

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.

The list below outlines possible workflow statuses and what they commonly mean.

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 the following reasons: • The workflow has been disabled. • An execution with the same targets and parameters is already running and current workflow is considered a duplicate.
Expired: Thinklet or flow control within the workflow exceeded the configured timeout period. • The most common scenario is a remote action Thinklet attempting to execute on a device that is currently offline.