Triggering Remote Actions Via Their API (classic)

Some functionality described in this article refers to Finder (classic)

Nexthink Finder is a Windows-only desktop application whose functionality is now available within the Nexthink web interface. Nexthink can now be used directly from a browser and most functions no longer require an additional desktop application.

The API of Nexthink Act makes it 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 Nexthink web interface as a REST API. The present article documents Act API v2.

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 Nexthink web interface 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 Nexthink web interface.

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 for logging purposes.

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 the Nexthink web interface (60 s).

params

(Optional) List of parameter inputs and values. Unknown parameter names are ignored.

The call is dispatched either to all the Engines connected to the Nexthink web interface or to the indicated Engines only and returns either when the Nexthink web interface receives the answer from the targeted Engines or after the specified timeout is elapsed. A successful response from the Nexthink web interface 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 from Finder (classic)

To get the UID of a remote action:

Log in to Finder as a user with permission to edit remote actions.
Locate the desired remote action under the Remote actions section of the left-hand side menu.
Right-click the remote action name.
Select Export > Remote action Uid to clipboard.
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
excludedUnknown databaseUid
no_permissionUser 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 TASK

Triggering a remote action manually

RELATED REFERENCE

List Engines API

Last updated 6 months ago