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

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 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 Portal (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 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:

Log in to the Finder as a user with the 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.

CODE

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

CODE

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

CODE

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