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

To trigger a workflow manually:

1. Get a list of devices or users using an NQL query.

2. Configure one or more workflows using an NQL query.

3. Grant Trigger manually all workflows permissions or share a workflow with trigger permissions.

The system does not support Device View and Amplify for manual triggers.

To manually trigger a workflow:

1. Select Investigations from the main menu.

2. Click the New button to run your NQL query. The Visual editor tab opens by default.

3. Switch to the NQL editor tab and write an NQL query to list all devices or users.

4. Click the Run button to show the query results.

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

2. Once you select the first item, an action bar appears with the total number of entries chosen, along with the Execute action button.

1. Click the Execute action button. An action modal appears.

2. 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:

1. Select Workflows from the main menu.

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

3. In the General tab, select Schedule.

1. Click the Add Schedule button to open the schedule modal.

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

2. 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:

1. Select Workflows from the main menu.

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

3. In the General tab, click the Events > Add Event button to open the event modal.

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

2. 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:

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

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.

A workflow execution achieves success when it has reached a configured End block in the workflow design.

Click on the status_detail attribute to view more detailed information—when available— regarding the status.