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 end-user devices with Agent 12 or later.

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.

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:
{
    "referenceId": 365,
    "message": "triggered successfully",
    "successful": true
}

Where successful:true appears when the action was successfully triggered and successful:false if 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).

Here is the list of possible errors. The parameters are explained in the above table.
Status Code Message Description
403 Forbidden

If the functionality is disabled or there is a problem with user name/password or authentication of a user/password has failed.

200

The response includes successful=false

Since server does not reject the command, the status is 200 OK.

Action [actionName] does not exist: " + actionName + " for account id: " + accountId

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

200

The response includes successful=false

Since server does not reject the command, the status is 200 OK.

Device [deviceName] is not recognized as a monitored device: " + hostName + ", account id: " + accountId

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

200

The response includes successful=false

Since server does not reject the command, the status is 200 OK.

Cannot run a disabled action [actionName] " + action.getName() + "(" + actionId + ")"

Device [deviceName] does not support remediation actions

Action " + action.getName() + " is currently in progress on device " + deviceName

Some other cases for error messages:

  • When an action that users try to run is disabled.

  • When the Agent installed on amonitored device does not support remediation actions.

  • If the action is currently running on another device.