Execute custom command

Executes a custom command on the specified directory object.

POST ~/api/directoryObjects/executeCustomCommand

Request parameters

This request has no parameters.

Request headers

  • Name

  • Required

  • Description

  • Adm-Authorization

  • True

  • Specify the security token obtained during authentication.

  • Content-Type

  • True

  • Use application/json as the value of this header.

Request body

The request body is a JSON object with the following data structure:

{
    "directoryObject": "<objectId>",
    "customCommandId": "<commandId>",
    "parameters": [
        {
            "type": "<parameterType>",
            "name": "<parameterName>",
            "value": "<parameterValues>"
        },
        ...
    ],
    "allowValueReference": <true|false>
}

directoryObject string
The identifier of the directory object on which the custom command should be executed. An object can be identified by:

 Distinguished name (DN) {.black}
# Example
CN=John Smith,CN=Users,DC=example,DC=com
 Globally unique identifier (GUID) {.black}
# Example
7a4267ce-d354-44e7-8bd6-c681f1284a41
 Security identifier (SID) {.black}
# Example
S-1-5-21-3635565734-1729062999-1822655016-1627

customCommandId string
The identifier of the custom command to execute.

Tip

For information on how to get the identifier of a custom command, see Get custom command identifier.


parameters array, optional
An array of custom command parameters.

Show attributes

parameters.type enum
The parameter type.

 Show possible enum values {.black}
Check          = 0,  // Check box
Text           = 1,  // Edit box
DateTime       = 2,  // Date/Time picker
List           = 3,  // Drop-down list
CheckList      = 4,  // Check box list
ADObject       = 5,  // AD object picker
PropertyName   = 6,  // Property name picker
LDAPFilter     = 7   // LDAP filter editor

parameters.name string
The parameter name e.g. param-MyParameter.


parameters.value
The parameter value. This attribute has to be specified in a unique way for each custom command parameter type:

 Check box {id=checkbox}

Example:

"parameters": [
    {
        "type": "Check",
        "name": "param-MyParameter",
        "value": true
    }
]

Specify one of the following values to select a checkbox state:

  • Checked — true, "True", "1"
  • Unchecked — false, "False", "0"
  • Undetermined — null
 Edit box {id=editbox}

Example:

"parameters": [
    {
        "type": "Text",
        "name": "param-MyParameter",
        "value": "My parameter value"
    }
]
 Date/Time picker {id=datetime-picker}

Example:

"parameters": [
    {
        "type": "DateTime",
        "name": "param-MyParameter",
        "value": "2020-10-06T14:00:00Z"
    }
]

It is recommended to specify the date in the ISO 8601 format:

  • 2020-10-22T06:00:00+03:00

However, many other formats will also be accepted, for example:

  • 2020-10-22 06:00 +3
  • 06.00 22/10/2020 +3:00
  • 6AM 22.10.2020 +3

Important

Always specify the time zone when setting a date. Otherwise, Adaxes service will assume time component is in the time zone of the computer where Adaxes service is installed.

 Check box list {id=checkbox-list}

Example:

"parameters": [
    {
        "type": "CheckList",
        "name": "param-MyParameter",
        "value": [
            "ADAXESPARAMID:{60863420-0af4-4dda-a0ba-5d8962de2d7f}",
            "ADAXESPARAMID:{2ac1863b-8555-4daf-992f-0ee185c1f26b}"
        ]
    }
]

Specify an array of checkbox identifiers that correspond to the selected checkboxes. For details on how to get the checkbox identifiers, see Viewing the parameters of a custom command. To leave all checkboxes empty, specify an empty array.

 AD object picker {id=ad-object-picker}

Specify a directory object reference, which has the following data structure:

{
    "referenceType": 0,
    "key": "<objectId>",
    "template": "<template>"
}

referenceType int
Specify 0 to refer to a directory object by its identifier, or specify 1 to refer to an object using a template.


key string
This attribute must be included only if referenceType is 0. Specify the identifier of a directory object. An object can be identified by:

Distinguished name (DN)

# Example
CN=John Smith,CN=Users,DC=example,DC=com

Globally unique identifier (GUID)

# Example
7a4267ce-d354-44e7-8bd6-c681f1284a41

Security identifier (SID)

# Example
S-1-5-21-3635565734-1729062999-1822655016-1627

template string
This attribute must be included only if referenceType is 1. Specify the template to generate the distinguished name (DN) of an object. Value references can be used in the template, for example, %department%. They will resolve into corresponding property values of the object on which the custom command is executed.


Examples:

Object identifier
 "parameters": [
     {
         "type": "ADObject",
         "name": "param-MyParameter",
         "value": [
             {
                 "referenceType": 0,
                 "key": "OU=Marketing,DC=example,DC=com"
             }
         ]
     }
 ]
Template
 "parameters": [
     {
         "type": "ADObject",
         "name": "param-MyParameter",
         "value": [
             {
                 "referenceType": 1,
                 "template": "OU=%department%,DC=example,DC=com"
             }
         ]
     }
 ]
 Property name picker {id=property-picker}

Example:

"parameters": [
    {
        "type": "PropertyName",
        "name": "param-MyParameter",
        "value": "givenName"
    }
]

Specify the LDAP name of the required property as the parameter value e.g. givenName or managedBy.

 LDAP filter editor {id=ldap-editor}

Example:

"parameters": [
    {
        "type": "LDAPFilter",
        "name": "param-MyParameter",
        "value": "(&(sAMAccountType=805306368)(department=Sales))"
    }
]

Specify an LDAP filter.


allowValueReference bool, optional
If set to true, value references can be used to set parameter values e.g. %fullname%. They will resolve into corresponding property values of the object on which the custom command is executed.

If set to true, % characters in parameter values must be escaped using %%.


Responses

If successful, returns 200 OK status code and an operation result in the response body. Otherwise, returns one of the common HTTP error codes and an error description in the response body.

Examples

 Example 1: Execute a custom command with no parameters

The following code sample executes a custom command with no parameters.

Request

PowerShell
$userIdentifier = "CN=John Smith,CN=Users,DC=example,DC=com"
$customCommandIdentifier = "200778bf-8e3d-4de6-b452-24116a77fde5"

$baseUrl = "https://host.example.com/restApi"
$endpoint = "/api/directoryObjects/executeCustomCommand"
$requestUrl = $baseUrl + $endpoint
$requestHeaders = @{"Adm-Authorization" = "HxtdAPz73OFfae7....w7lQvxjJHIbVqgkCtPtLD"}
$requestBody = ConvertTo-Json @{
    "directoryObject" = $userIdentifier;
    "customCommandId" = $customCommandIdentifier
}

# Make request
Invoke-RestMethod -Method POST -Headers $requestHeaders -Uri $requestUrl `
    -Body $requestBody -ContentType "application/json"
C#
using System;
using System.Text;
using System.Net.Http;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        const string baseUrl = "https://host.example.com/restApi";
        const string endpoint = "/api/directoryObjects/executeCustomCommand";
        const string token = "HxtdAPz73OFfae7....w7lQvxjJHIbVqgkCtPtLD";
        
        // Create JSON request body
        string jsonRequest = @"
        {
            'directoryObject': 'CN=John Smith,CN=Users,DC=example,DC=com',
            'customCommandId': '200778bf-8e3d-4de6-b452-24116a77fde5'
        }";
        StringContent requestBody = new StringContent(
            jsonRequest, Encoding.UTF8, "application/json");

        // Initialize HTTP client
        using (HttpClient client = new HttpClient())
        {
            client.DefaultRequestHeaders.Add("Adm-Authorization", token);

            // Make request
            HttpResponseMessage response = await client.PostAsync(
                baseUrl + endpoint, requestBody);
            string responseBody = response.Content.ReadAsStringAsync().Result;
            Console.WriteLine(responseBody);
        }
    }
}
cURL
curl  --header 'Adm-Authorization: HxtdAPz73OFfae7....w7lQvxjJHIbVqgkCtPtLD' \
--header 'Content-Type: application/json' \
--request POST 'https://host.example.com/restApi/api/directoryObjects/executeCustomCommand' \
--data-raw '{
    "directoryObject": "CN=John Smith,CN=Users,DC=example,DC=com",
    "customCommandId": "200778bf-8e3d-4de6-b452-24116a77fde5"
}'
node.js
var https = require('https');

// Request parameters and headers
var options = {
    'method': 'POST',
    'hostname': 'host.example.com',
    'path': '/restapi/api/directoryObjects/executeCustomCommand',
    'headers': {
        'Adm-Authorization': 'HxtdAPz73OFfae7....w7lQvxjJHIbVqgkCtPtLD',
        'Content-Type': 'application/json'
    }
};

// Create JSON request body
var postData = `
{
    "directoryObject": "CN=John Smith,CN=Users,DC=example,DC=com",
    "customCommandId": "200778bf-8e3d-4de6-b452-24116a77fde5"
}`;

// Make request
var req = https.request(options, function (res) {
    var chunks = [];

    res.on("data", function (chunk) {
        chunks.push(chunk);
    });

    res.on("end", function (chunk) {
        var body = Buffer.concat(chunks);
        console.log(body.toString());
    });

    res.on("error", function (error) {
        console.error(error);
    });
});

req.write(postData);

req.end();

Response

HTTP Status code: 200 OK
Response body:

{
    "resultType": 0,
    "exception": null,
    "innerMessages": [
        {
            "source": "My custom command",
            "text": "1 operation executed",
            "messageType": 2,
            "innerMessages": [
                {
                    "source": '',
                    "text": "Run PowerShell script 'My Script' for the user",
                    "messageType": 3,
                    "innerMessages": []
                }
            ]
        }
    ],
    "actualObjectDN": "CN=John Smith,CN=Users,DC=example,DC=com",
    "extraInfo": {}
}
 Example 2: Execute a custom command with edit box and drop-down list parameters

The following code sample executes a custom command with an Edit box and a Drop-down list parameter.

Request

PowerShell
$userIdentifier = "CN=John Smith,CN=Users,DC=example,DC=com"
$customCommandIdentifier = "200778bf-8e3d-4de6-b452-24116a77fde5"

$baseUrl = "https://host.example.com/restApi"
$endpoint = "/api/directoryObjects/executeCustomCommand"
$requestUrl = $baseUrl + $endpoint
$requestHeaders = @{"Adm-Authorization" = "HxtdAPz73OFfae7....w7lQvxjJHIbVqgkCtPtLD"}
$requestBody = ConvertTo-Json -Depth 3 @{
    "directoryObject" = $userIdentifier;
    "customCommandId" = $customCommandIdentifier;
    "parameters" = @(
        @{
            "type" = "Text";
            "name" = "param-MyEditBoxParam";
            "value" = "My value"
        },
        @{
            "type" = "List";
            "name" = "param-MyDropDownListParam";
            "value" = "ADAXESVALUEID:{1a33167e-3ba5-4c6f-baa2-b7f8904d0acd}" 
        }
    )
}

# Make request
Invoke-RestMethod -Method POST -Headers $requestHeaders -Uri $requestUrl `
    -Body $requestBody -ContentType "application/json"
C#
using System;
using System.Text;
using System.Net.Http;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        const string baseUrl = "https://host.example.com/restApi";
        const string endpoint = "/api/directoryObjects/executeCustomCommand";
        const string token = "HxtdAPz73OFfae7....w7lQvxjJHIbVqgkCtPtLD";
        
        // Create JSON request body
        string jsonRequest = @"
        {
            'directoryObject': 'CN=John Smith,CN=Users,DC=example,DC=com',
            'customCommandId': '200778bf-8e3d-4de6-b452-24116a77fde5',
            'parameters': [
                {
                    'type': 'Text',
                    'name': 'param-MyEditBoxParam',
                    'value': 'My value'
                },
                {
                    'type': 'List',
                    'name': 'param-MyDropDownListParam',
                    'value': 'ADAXESVALUEID:{1a33167e-3ba5-4c6f-baa2-b7f8904d0acd}'
                }
            ]
        }";
        StringContent requestBody = new StringContent(
            jsonRequest, Encoding.UTF8, "application/json");

        // Initialize HTTP client
        using (HttpClient client = new HttpClient())
        {
            client.DefaultRequestHeaders.Add("Adm-Authorization", token);

            // Make request
            HttpResponseMessage response = await client.PostAsync(
                baseUrl + endpoint, requestBody);
            string responseBody = response.Content.ReadAsStringAsync().Result;
            Console.WriteLine(responseBody);
        }
    }
}
cURL
curl  --header 'Adm-Authorization: HxtdAPz73OFfae7....w7lQvxjJHIbVqgkCtPtLD' \
--header 'Content-Type: application/json' \
--request POST 'https://host.example.com/restApi/api/directoryObjects/executeCustomCommand' \
--data-raw '{
    "directoryObject": "CN=John Smith,CN=Users,DC=example,DC=com",
    "customCommandId": "200778bf-8e3d-4de6-b452-24116a77fde5",
    "parameters": [
        {
            "type": "Text",
            "name": "param-MyEditBoxParam",
            "value": "My value"
        },
        {
            "type": "List",
            "name": "param-MyDropDownListParam",
            "value": "ADAXESVALUEID:{1a33167e-3ba5-4c6f-baa2-b7f8904d0acd}"
        }
    ]
}'
node.js
var https = require('https');

// Request parameters and headers
var options = {
    'method': 'POST',
    'hostname': 'host.example.com',
    'path': '/restapi/api/directoryObjects/executeCustomCommand',
    'headers': {
        'Adm-Authorization': 'HxtdAPz73OFfae7....w7lQvxjJHIbVqgkCtPtLD',
        'Content-Type': 'application/json'
    }
};

// Create JSON request body
var postData = `
{
    "directoryObject": "CN=John Smith,CN=Users,DC=example,DC=com",
    "customCommandId": "200778bf-8e3d-4de6-b452-24116a77fde5",
    "parameters": [
        {
            "type": "Text",
            "name": "param-MyEditBoxParam",
            "value": "My value"
        },
        {
            "type": "List",
            "name": "param-MyDropDownListParam",
            "value": "ADAXESVALUEID:{1a33167e-3ba5-4c6f-baa2-b7f8904d0acd}"
        }
    ]
}`;

// Make request
var req = https.request(options, function (res) {
    var chunks = [];

    res.on("data", function (chunk) {
        chunks.push(chunk);
    });

    res.on("end", function (chunk) {
        var body = Buffer.concat(chunks);
        console.log(body.toString());
    });

    res.on("error", function (error) {
        console.error(error);
    });
});

req.write(postData);

req.end();

Tip

For details on how to get the drop-down list value identifiers, see Viewing the parameters of a custom command.

Response

HTTP Status code: 200 OK
Response body:

{
    "resultType": 0,
    "exception": null,
    "innerMessages": [
        {
            "source": "My custom command",
            "text": "1 operation executed",
            "messageType": 2,
            "innerMessages": [
                {
                    "source": '',
                    "text": "Modify the user: set Job Title to 'My value', 
                        set Department to 'Accounting'",
                    "messageType": 3,
                    "innerMessages": []
                }
            ]
        }
    ],
    "actualObjectDN": "CN=John Smith,CN=Users,DC=example,DC=com",
    "extraInfo": {}
}
 Example 3: Execute a custom command with check box list and AD object picker parameters

The following code sample executes a custom command with a Checkbox list and an AD object picker parameter.

Request

PowerShell
$userIdentifier = "CN=John Smith,CN=Users,DC=example,DC=com"
$customCommandIdentifier = "200778bf-8e3d-4de6-b452-24116a77fde5"

$baseUrl = "https://host.example.com/restApi"
$endpoint = "/api/directoryObjects/executeCustomCommand"
$requestUrl = $baseUrl + $endpoint
$requestHeaders = @{"Adm-Authorization" = "HxtdAPz73OFfae7....w7lQvxjJHIbVqgkCtPtLD"}
$requestBody = ConvertTo-Json -Depth 4 @{
    "directoryObject" = $userIdentifier;
    "customCommandId" = $customCommandIdentifier;
    "parameters" = @(
        @{
            "type" = "CheckList";
            "name" = "param-MyCheckboxListParam";
            "value" = @(
                "ADAXESPARAMID:{60863420-0af4-4dda-a0ba-5d8962de2d7f}",
                "ADAXESPARAMID:{2ac1863b-8555-4daf-992f-0ee185c1f26b}"
            )
        },
        @{
            "type" = "ADObject";
            "name" = "param-MyAdObjectPickerParam";
            "value" = @(
                @{
                    "referenceType" = 1;
                    "template" = "OU=%department%,DC=example,DC=com"
                }
            ) 
        }
    )
}

# Make request
Invoke-RestMethod -Method POST -Headers $requestHeaders -Uri $requestUrl `
    -Body $requestBody -ContentType "application/json"
C#
using System;
using System.Text;
using System.Net.Http;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        const string baseUrl = "https://host.example.com/restApi";
        const string endpoint = "/api/directoryObjects/executeCustomCommand";
        const string token = "HxtdAPz73OFfae7....w7lQvxjJHIbVqgkCtPtLD";
        
        // Create JSON request body
        string jsonRequest = @"
        {
            'directoryObject': 'CN=John Smith,CN=Users,DC=example,DC=com',
            'customCommandId': '200778bf-8e3d-4de6-b452-24116a77fde5',
            'parameters': [
                {
                    'type': 'CheckList',
                    'name': 'param-MyCheckboxListParam',
                    'value': [
                        'ADAXESPARAMID:{60863420-0af4-4dda-a0ba-5d8962de2d7f}',
                        'ADAXESPARAMID:{2ac1863b-8555-4daf-992f-0ee185c1f26b}'
                    ]
                },
                {
                    'type': 'ADObject',
                    'name': 'param-MyAdObjectPickerParam',
                    'value': [
                        {
                            'referenceType': 1,
                            'template': 'OU=%department%,DC=example,DC=com'
                        }
                    ]
                }
            ]
        }";
        StringContent requestBody = new StringContent(
            jsonRequest, Encoding.UTF8, "application/json");

        // Initialize HTTP client
        using (HttpClient client = new HttpClient())
        {
            client.DefaultRequestHeaders.Add("Adm-Authorization", token);

            // Make request
            HttpResponseMessage response = await client.PostAsync(
                baseUrl + endpoint, requestBody);
            string responseBody = response.Content.ReadAsStringAsync().Result;
            Console.WriteLine(responseBody);
        }
    }
}
cURL
curl  --header 'Adm-Authorization: HxtdAPz73OFfae7....w7lQvxjJHIbVqgkCtPtLD' \
--header 'Content-Type: application/json' \
--request POST 'https://host.example.com/restApi/api/directoryObjects/executeCustomCommand' \
--data-raw '{
    "directoryObject": "CN=John Smith,CN=Users,DC=example,DC=com",
    "customCommandId": "200778bf-8e3d-4de6-b452-24116a77fde5",
    "parameters": [
        {
            "type": "CheckList",
            "name": "param-MyCheckboxListParam",
            "value": [
                "ADAXESPARAMID:{60863420-0af4-4dda-a0ba-5d8962de2d7f}",
                "ADAXESPARAMID:{2ac1863b-8555-4daf-992f-0ee185c1f26b}"
            ]
        },
        {
            "type": "ADObject",
            "name": "param-MyAdObjectPickerParam",
            "value": [
                {
                    "referenceType": 1,
                    "template": "OU=%department%,DC=example,DC=com"
                }
            ]
        }
    ]
}'
node.js
var https = require('https');

// Request parameters and headers
var options = {
    'method': 'POST',
    'hostname': 'host.example.com',
    'path': '/restapi/api/directoryObjects/executeCustomCommand',
    'headers': {
        'Adm-Authorization': 'HxtdAPz73OFfae7....w7lQvxjJHIbVqgkCtPtLD',
        'Content-Type': 'application/json'
    }
};

// Create JSON request body
var postData = `
{
    "directoryObject": "CN=John Smith,CN=Users,DC=example,DC=com",
    "customCommandId": "200778bf-8e3d-4de6-b452-24116a77fde5",
    "parameters": [
        {
            "type": "CheckList",
            "name": "param-MyCheckboxListParam",
            "value": [
                "ADAXESPARAMID:{60863420-0af4-4dda-a0ba-5d8962de2d7f}",
                "ADAXESPARAMID:{2ac1863b-8555-4daf-992f-0ee185c1f26b}"
            ]
        },
        {
            "type": "ADObject",
            "name": "param-MyAdObjectPickerParam",
            "value": [
                {
                    "referenceType": 1,
                    "template": "OU=%department%,DC=example,DC=com"
                }
            ]
        }
    ]
}`;

// Make request
var req = https.request(options, function (res) {
    var chunks = [];

    res.on("data", function (chunk) {
        chunks.push(chunk);
    });

    res.on("end", function (chunk) {
        var body = Buffer.concat(chunks);
        console.log(body.toString());
    });

    res.on("error", function (error) {
        console.error(error);
    });
});

req.write(postData);

req.end();    

Tip

For details on how to get the checkbox identifiers, see Viewing the parameters of a custom command.

Response

HTTP Status code: 200 OK
Response body:

{
    "resultType": 0,
    "exception": null,
    "innerMessages": [
        {
            "source": "My custom command",
            "text": "1 operation executed",
            "messageType": 2,
            "innerMessages": [
                {
                    "source": '',
                    "text": "Run PowerShell script 'My Script' for the user",
                    "messageType": 3,
                    "innerMessages": []
                }
            ]
        }
    ],
    "actualObjectDN": "CN=John Smith,CN=Users,DC=example,DC=com",
    "extraInfo": {}
}