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. You can use:

 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

customCommandId string

The identifier of the custom command to execute.

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
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,  // Directory object picker
PropertyName   = 6,  // Property name picker

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

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.

 Directory 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. You can use:

 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 name of the required property as the parameter value e.g. givenName or manager.

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
$baseUrl = "https://host.example.com/restApi"
$endpoint = "/api/directoryObjects/executeCustomCommand"

# Request parameters
$requestUrl = $baseUrl + $endpoint
$requestHeaders = @{"Adm-Authorization" = YOUR-SECURITY-TOKEN}
$requestBody = ConvertTo-Json @{
    "directoryObject" = "CN=John Smith,CN=Users,DC=example,DC=com";
    "customCommandId" = "200778bf-8e3d-4de6-b452-24116a77fde5"
}

# 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";
        
        // 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(jsonRequest, Encoding.UTF8, "application/json");

        // Initialize HTTP client
        using HttpClient client = new();
        client.DefaultRequestHeaders.Add("Adm-Authorization", YOUR-SECURITY-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: YOUR-SECURITY-TOKEN' \
--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
var options = {
    'method': 'POST',
    'hostname': 'host.example.com',
    'path': '/restapi/api/directoryObjects/executeCustomCommand',
    'headers': {
        'Adm-Authorization': 'YOUR-SECURITY-TOKEN',
        '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, res => {
    var data = [];

    res.on("data", chunk => {
        data.push(chunk);
    });

    res.on("end", () => {
        var body = Buffer.concat(data);
        console.log(body.toString());
    });

    res.on("error", error => {
        console.error(error);
    });
});
req.write(postData);

req.end();
Python
import requests
import json

baseUrl = "https://host.example.com/restApi"
endpoint = "/api/directoryObjects/executeCustomCommand"

# Request parameters
requestUrl = baseUrl + endpoint
requestHeaders = {"Adm-Authorization": YOUR-SECURITY-TOKEN}
requestBody = {
    "directoryObject": "CN=John Smith,CN=Users,DC=example,DC=com",
    "customCommandId": "200778bf-8e3d-4de6-b452-24116a77fde5"
}

# Make request
request = requests.post(requestUrl, headers=requestHeaders, json=requestBody)
response = json.loads(request.content)
print(response)

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
$baseUrl = "https://host.example.com/restApi"
$endpoint = "/api/directoryObjects/executeCustomCommand"

# Request parameters
$requestUrl = $baseUrl + $endpoint
$requestHeaders = @{"Adm-Authorization" = YOUR-SECURITY-TOKEN}
$requestBody = ConvertTo-Json -Depth 3 @{
    "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
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";
        
        // 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(jsonRequest, Encoding.UTF8, "application/json");

        // Initialize HTTP client
        using HttpClient client = new();
        client.DefaultRequestHeaders.Add("Adm-Authorization", YOUR-SECURITY-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: YOUR-SECURITY-TOKEN' \
--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
var options = {
    'method': 'POST',
    'hostname': 'host.example.com',
    'path': '/restapi/api/directoryObjects/executeCustomCommand',
    'headers': {
        'Adm-Authorization': 'YOUR-SECURITY-TOKEN',
        '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, res => {
    var data = [];

    res.on("data", chunk => {
        data.push(chunk);
    });

    res.on("end", () => {
        var body = Buffer.concat(data);
        console.log(body.toString());
    });

    res.on("error", error => {
        console.error(error);
    });
});
req.write(postData);

req.end();
Python
import requests
import json

baseUrl = "https://host.example.com/restApi"
endpoint = "/api/directoryObjects/executeCustomCommand"

# Request parameters
requestUrl = baseUrl + endpoint
requestHeaders = {"Adm-Authorization": YOUR-SECURITY-TOKEN}
requestBody = {
    "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
request = requests.post(requestUrl, headers=requestHeaders, json=requestBody)
response = json.loads(request.content)
print(response)

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 Directory object picker parameters

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

Request

PowerShell
$baseUrl = "https://host.example.com/restApi"
$endpoint = "/api/directoryObjects/executeCustomCommand"

# Request parameters
$requestUrl = $baseUrl + $endpoint
$requestHeaders = @{"Adm-Authorization" = YOUR-SECURITY-TOKEN}
$requestBody = ConvertTo-Json -Depth 4 @{
    "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
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";
        
        // 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(jsonRequest, Encoding.UTF8, "application/json");

        // Initialize HTTP client
        using HttpClient client = new();
        client.DefaultRequestHeaders.Add("Adm-Authorization", YOUR-SECURITY-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: YOUR-SECURITY-TOKEN' \
--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
var options = {
    'method': 'POST',
    'hostname': 'host.example.com',
    'path': '/restapi/api/directoryObjects/executeCustomCommand',
    'headers': {
        'Adm-Authorization': 'YOUR-SECURITY-TOKEN',
        '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, res => {
    var data = [];

    res.on("data", chunk => {
        data.push(chunk);
    });

    res.on("end", () => {
        var body = Buffer.concat(data);
        console.log(body.toString());
    });

    res.on("error", error => {
        console.error(error);
    });
});
req.write(postData);

req.end();
Python
import requests
import json

baseUrl = "https://host.example.com/restApi"
endpoint = "/api/directoryObjects/executeCustomCommand"

# Request parameters
requestUrl = baseUrl + endpoint
requestHeaders = {"Adm-Authorization": YOUR-SECURITY-TOKEN}
requestBody = {
    "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
request = requests.post(requestUrl, headers=requestHeaders, json=requestBody)
response = json.loads(request.content)
print(response)

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": {}
}
© Softerra 2022. All rights reserved.
Send feedback