Triggering workflows

Workflows allows 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 with the Nexthink API.

• Scheduled: Enables you to execute a workflow within the timeframe defined by the NQL query.

• Events: Enables you to execute a real-time event workflow defined by the NQL query.

Triggering a workflow manually

To trigger a workflow manually, you must:

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.

Device view and Amplify are not supported 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.

5. Select the checkboxes of the items that you wish to trigger.

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

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

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

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

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

6. Click the Add button 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.

4. 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 the 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.

5. Click the Add button to trigger a workflow.

Examples

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 disabled

Use the following query when the anti-virus is disabled and 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

• Manual custom fields are supported.

• Below is a list of supported query 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.lockouts

Event Limitations

• Filtering using date or time attributes is not supported.

• 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 following fields are not supported for use 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 use of the following custom fields is not supported:

  • Query-based fields

  • Rule-based fields

• The use of dimensions in the query is not supported:

  • context.*

  • device.public_ip.*

Workflow statuses

When a workflow is triggered, the status can be used to understand whether it is still running and, ultimately, how it ended.

This status can be reviewed by:

• Using 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 works through the logic-configured design.

• Success: The workflow has been completed successfully.

• Failed: The workflow has failed to run due to an unexpected issue.

• Canceled: The workflow execution has been stopped for the following reasons:

  • The workflow has been disabled.

  • An execution with the same targets and parameters is already running and is considered a duplicate.

• Expired: A Thinklet or Flow Control within the workflow has exceeded the configured timeout period.

  • The most common scenario is a remote action Thinklet attempting to execute on a device that is currently offline.

Note that a workflow execution success status is defined by the fact that it has reached a configured End block in the workflow design.

Where more detailed information is available for one of the statuses, this will be available in the status_details attribute.