Run Remediation Actions with REST API

Remediation Settings in Aternity

You can run remediation actions on end-user devices using REST API. You can do that from outside Aternity. For example, use this API to trigger remediation actions from your ticketing system or use it in mass healing flows.

Note

This functionality applies only to Windows end-user devices with Agent 12 or later. Install the Agent for End User Devices locally on a Windows desktop or laptop.

To run remediation actions using REST API, you need its URL, as well as user name and password for authentication. To get them, do the following:

  1. Open a browser and sign in to Aternity.
  2. Go to the the Gear Icon > and select Remediation.
  3. Click Settings.
  4. Enable the functionality by toggling ON and Save. By default, it is disabled.
    Get URL user and password for your script

In this screen, see the user name and password you need to include in the API call for authentication of the API. By clicking Generate New Password you can get a new password to include in scripts, and the previous one will not longer be valid.

URL Format for Remediation API

https://<domain_name>/component/remediation/external/executeCommand?accountId=<account Id>&actionName=<action name>&deviceName=<device name>&triggerBy=<user>

To trigger a remote action, submit a POST request to the URL of the API with a JSON payload containing username and password from the Remediation Settings screen that API uses for authentication.
Note

GET requests are not supported.

Send your POST request to the API with basic authentication: Authorization: Basic [base-64(user:password)]

Replace [base-64(user:password)] with the credentials from the Remediation Settings screen in base-64 encoding.

For example:
curl -X POST \
  'http://my-demo.aternity.com/component/remediation/external/executeCommand?accountId=21&actionName= Empty+Recycle+Bin&deviceName= PC0K98WS-PC&triggerBy=julia' \
  -H 'authorization: Basic U0NBdGVybml0eVJlbWVkaWF0aW9uXzIxOjNfMTY5NzE0YjA2Mjlfa0hDNEQwQmpNTHpPSnQwSkp5ZFJjeXdIYkZkb3FV'

Parameters

The link should include the following parameters:

Name Description
domain name

Enter the domain name (for example my-demo.aternity.com

accountId=

Enter the account ID for your Aternity. You can find this in the URL when you access Aternity, where the last few characters are ?BACCT=21, where the value (in this example 21) is your account ID.

actionName=

Enter the action name as defined in Remediation screen in Aternity. For example, Empty+Recycle+Bin

deviceName=

Enter the host name on which you intend to run this remediation action.

triggerBy=

Enter the name or any other identifier of a person who executed the remediation action.

It is highly recommended to fill this field accurately for auditing purposes.

runDescription=

(Optional) Enter as a free text a description or any additional information for the action.

parameterValue1=

Enter the parameter. An input parameter allows using general scripts. Whoever triggers the action run is prompted to enter the input parameter.

For example, in the action stop service, the parameter is the service name, or in the action clean disk, the parameter is the directory.

For example, https://my-demo.aternity.com/component/remediation/external/executeCommand?accountId=21&actionName=Empty+Recycle+Bin&deviceName=PC0K98WS-PC&triggerBy=julia

Output

200 is a standard response for successful HTTP requests. If your request has succeeded, the returned response is 200 and includes a message that describes the result of an action:
"API return data: { ""successful"": true, ""referenceId"": <trigger id>, ""message"": ""triggered successfully"" }"

successful:true means that the action was successfully triggered and successful:false that it failed; referenceID is a unique identifier of the action run and included only if the action was successful; and message will optionally include additional information (especially in case of a failure).

Error Definitions

Here is the list of possible errors. The parameters are explained in the above table.

errorCode Message Description
Forbidden 403

This error means that a web server forbids you from accessing the requested URL (probably due to insufficient permissions to run the specified remote action).

""errorCode"": 1 "API return data: { ""successful"": false, ""errorCode"": 1, ""message"": ""Cannot run action <Action Name>, missing required parameter"" }"

The action cannot be carried out because some mandatory parameter is missing.

""errorCode"": 2 "API return data: { ""successful"": false, ""errorCode"": 2, ""message"": ""Cannot run a disabled action <Action Name>"" }"

The action that users try to run is disabled.

""errorCode"": 3 "API return data: { ""successful"": false, ""errorCode"": 3, ""message"": ""Action <Action Name> does not exist"" }"

The action name is incorrect, the system returns Action [actionName] does not exist

""errorCode"": 4 "API return data: { ""successful"": false, ""errorCode"": 4, ""message"": ""Action <Action Name> is currently in progress on device <Device Name>"" }"

The same action is currently in progress on another device.

""errorCode"": 6 "API return data: { ""successful"": false, ""errorCode"": 6, ""message"": ""Device <Device Name> is not recognized as a monitored device"" }"

If a hostname is incorrect, the system returns Device [deviceName] is not recognized as a monitored device.

""errorCode"": 7 "API return data: { ""successful"": false, ""errorCode"": 7, ""message"": ""Device <Device Name> does not support remediation actions"" }"

The Agent installed on a monitored device that does not support remediation actions.

""errorCode"": 9 "API return data: { ""successful"": false, ""errorCode"": 9, ""message"": ""General error, please check the log"" }"

A general error occurred. It is recommended to check log files.