Triggering remote actions via their API

Contents

Triggering remote actions via their API

Overview

The API of Nexthink Act 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. The present article documents Act API v2.

Applies to platforms: PlatformWindows.png PlatformMac.png

Prerequisites

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

  • The remote action can be manually triggered.
  • The remote action is triggered on behalf of a user whose profile includes Finder access with the option Allow API of remote actions ticked.

Calling the Act API

The Portal exposes the Act API as a REST API under the URL:

https://[portal.company.com]/api/remoteaction/v2/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
requestUid (Optional) Identifier of the request.
remoteActionUid Identifier of the remote action.
deviceUids List of device identifiers to target.
engineDatabaseUids (Optional) List of Engine identifiers to target.
timeoutSeconds (Optional) Request timeout in seconds. Overrides default timeout configured in the Portal (60 s).

The call is dispatched either to all the Engines connected to the Portal or to the indicated Engines only and returns either when the Portal receives the answer from the targeted Engines or after the specified timeout is elapsed. A successful response from the Portal does not guarantee the execution of the remote action on the selected devices (see the list of codes for Engine responses below).

Obtaining the UIDs of remote actions, devices and Engines

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 under the Remote actions section of the left-hand side menu.
  3. Right-click the remote action name.
  4. Select Export > Remote action Uid to clipboard.
  5. In your request editor, press Ctrl+V to paste the UID into the JSON payload.

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

To target specific Engines, get the UID of the database on each Engine via the List Engines API.

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 who has the right to access the API of remote actions.

Response

Successful response

When successful, a call to the Act API v2 returns a list of responses from each targeted Engine with HTTP code 200.

Name Description
databaseUid The identifier of the targeted Engine
code
  • ok
  • timeout
  • engine_error
  • not_connected
  • excluded
    Unknown databaseUid
  • no_permission
    User has no permission on the Engine
message Possible additional message from the Engine

Error response

When unsuccessful, a call to the Act API v2 returns an error response with HTTP code depending on the type of error.

Name Description
code Error code, one of: HTTP code
INVALID_REQUEST_JSON 400
INVALID_REQUEST_CONTENT 400
INTERNAL_ERROR 500
CONTENT_TYPE 400
ENCODING 400
NO_REMOTE_ACTION_UID 400
NO_DEVICES 400
TOO_MANY_DEVICES 400
INVALID_ACTION_UID 400
INVALID_DEVICE_UID 400
NO_PERMISSION 403
UNKNOWN_OR_DISABLED_REMOTE_ACTION 400
NO_MANUAL_EXECUTION 400
NO_ENGINES_TO_TARGET 403
error Description of the error code.

Examples

Target all Engines

Example of a request that targets all Engines and its response in JSON format.

// request
{
    "requestUid": "123",
    "remoteActionUid": "07844969-1889-4de3-9026-020af94be855",
    "deviceUids": ["da2add909a144e8235453f88dc45172f","4423e4c059b2c72ee9382e135888bef7",
                   "13ea2b236e6833ffe6045a7715968cba","3537e2f2eb0d5f2152da59e7cbcb505b"]
}


// response
// Status 200
// Body:
[
    {
        "databaseUid": "86acc8511251ec444d3a75bac33a23c7",
        "code": "ok",
        "message": ""
    },
    {
        "databaseUid": "a4690014774dcc32b919c27d616166f7",
        "code": "ok",
        "message": ""
    },
    {
        "databaseUid": "ce80dddfdb7a5c2346c4ac184b7d6a54",
        "code": "engine_error",
        "message": "Error in request to engine [172.16.5.177:999]: no license"
    }
]

Target one Engine

Example of a request that targets one Engine and its response in JSON format.

// request
{
     
    "requestUid": "123",
    "remoteActionUid": "07844969-1889-4de3-9026-020af94be855",
    "deviceUids": ["da2add909a144e8235453f88dc45172f","4423e4c059b2c72ee9382e135888bef7",
                   "13ea2b236e6833ffe6045a7715968cba","3537e2f2eb0d5f2152da59e7cbcb505b"],
    "engineDatabaseUids" : ["a4690014774dcc32b919c27d616166f7"]
}
 
// response
// Status 200
// Body:
[
    {
        "databaseUid": "a4690014774dcc32b919c27d616166f7",
        "code": "ok",
        "message": ""
    }
]

Error response

Example of a request that returns an error because the remote action disabled manual execution.

// request
{
    "requestUid": "123",
    "remoteActionUid": "e6bb97be-0957-49e0-9922-1a684d093858",
    "deviceUids": ["da2add909a144e8235453f88dc45172f","4423e4c059b2c72ee9382e135888bef7",
                   "13ea2b236e6833ffe6045a7715968cba","3537e2f2eb0d5f2152da59e7cbcb505b"]
}
 
 
// response
// Status 400
// Body:
{
    "code": "NO_MANUAL_EXECUTION",
    "error": "Remote action not configured for manual execution"
}


Related references