Triggering remote actions via their API

Contents

Triggering remote actions via their API

Overview

The API of remote actions makes possible to trigger remote actions programmatically, enabling their integration with third-party products such as self-service portals or ticketing systems.

The API of remote actions is exposed by the Portal as a REST API.

Applies to platforms: PlatformWindows.png

Prerequisites

For a remote action to be triggered through the API, the following prerequisites apply:

  • The remote action must allow manual triggering.
  • The remote action must be triggered on behalf of a user whose profile includes Finder access with the option Allow API of remote actions ticked.

Calling the API

The Portal exposes the API of remote actions as a REST API under the URL:

https://[portal.company.com]/api/remoteaction/v1/run

In the URL, substitute [portal.company.com] for the external DNS name of your Portal.

To trigger a remote action, submit a POST request to the URL of the API (note that GET requests are not supported, returning a 404 error) with a JSON payload containing two parameters:

Name Description
RemoteActionUid Identifier of the remote action
DeviceUids List of device identifiers

Example of the JSON payload of a request to the API of remote actions:

{
  "RemoteActionUid": "b21b9377-3624-4046-8378-76244657d2d4",
  "DeviceUids" : ["da581fd269e0bc4c03b767a345fbf5d3","fa623653cd663e19a58d69519471bbef"]
}


The call is dispatched to all the Engines connected to the Portal and executed asynchronously, meaning that it returns immediately after the request has been validated. A successful response from the Portal does not guarantee the execution of the remote action on the selected devices. For unsuccessful responses, see the list of error conditions below.

Obtaining the UIDs of remote actions and devices

To get the UID of a remote action:

  1. Log in to the Finder as a user with the permission to edit remote actions.
  2. Locate the desired remote action in the Remote actions section of the left-hand side panel.
  3. Right-click the remote action name.
  4. Select Export > Remote action to clipboard.
  5. Open your favorite XML or plain text editor.
  6. Press Ctrl+V to paste the contents of the clipboard on the editor.
  7. Find the UID attribute of the Action element in the XML of the remote action.

Find the UIDs of the devices through either:

  • The Finder: Display field UID of the device object.
  • NXQL: Retrieve the device_uid field of the device objects, for instance:
    (select device_uid (from device))

HTTP Headers

Send your POST request to the API of remote actions with the following HTTP headers to specify JSON content and basic authentication:

Content-type: application/json
Authorization: Basic [base-64(user:password)]

Replace [base-64(user:password)] with the credentials (in base-64 encoding) of a Nexthink user that has the right to access the API of remote actions.

Error conditions

In response to a request, the Portal may send one of the following answers when something is wrong with the request:

Error type HTTP code Cause
Access Denied Unauthorized 401
  • Authentication error
Forbidden 403
  • User with insufficient permissions to run the specified remote action
Validation error Bad request 400
  • Invalid JSON
  • Invalid encoding
  • Invalid Content-type
  • Invalid or missing UID of remote action
  • Invalid or missing UIDs of devices
  • Unknown or disabled remote action
  • Manual execution of remote action not allowed
  • Too many device UIDs specified (limit of 12 000)
Unknown error Internal server error 500
  • Undefined internal error