Managing custom commands

Custom commands can be created, edited, deleted, and executed programmatically via the dedicated ADSI interfaces. You can apply the principles outlined in this article to write standalone scripts and programs or build custom integrations with third-party software. PowerShell scripts that manage custom commands can also be executed from within Adaxes, for instance, from other custom commands, business rules, and scheduled tasks.

Creating a custom command

The following code sample creates a custom command targeted at the User object type.

PowerShell
[Reflection.Assembly]::LoadWithPartialName("Softerra.Adaxes.Adsi")

# Connect to the Adaxes service.
$ns = New-Object "Softerra.Adaxes.Adsi.AdmNamespace"
$service = $ns.GetServiceDirectly("localhost")

# Bind to the custom commands container.
$containerPath = $service.Backend.GetConfigurationContainerPath(
    "CustomCommands")
$container = $service.OpenObject($containerPath,
    $null, $null, 0)

# Create a new custom command.
$command = $container.Create("adm-CustomCommand", "CN=My Command")

$command.OperationType = "none"
$command.ExecutionMoment = "ADM_BUSINESSRULEEXECMOMENT_BEFORE"
$command.ObjectType = "user"
$command.CommandIcon = 5

$command.Description = "My description"
$command.Confirmation = "Are you sure?"
$command.Disabled = $false

# Save the custom command.
$command.SetInfo()
C#
using Softerra.Adaxes.Adsi;
using Softerra.Adaxes.Interop.Adsi;
using Softerra.Adaxes.Interop.Adsi.BusinessRules;
using Softerra.Adaxes.Interop.Adsi.CustomCommands;
using Softerra.Adaxes.Interop.Adsi.PersistentObjects;

class Program
{
    static void Main(string[] args)
    {
        // Connect to the Adaxes service.
        AdmNamespace ns = new AdmNamespace();
        IAdmService service = ns.GetServiceDirectly("localhost");

        // Bind to the custom commands container.
        string containerPath = service.Backend.GetConfigurationContainerPath("CustomCommands");
        IADsContainer container = (IADsContainer)service.OpenObject(
            containerPath, null, null, 0);

        // Create a new custom command.
        IAdmCustomCommand command = (IAdmCustomCommand)container.Create(
            "adm-CustomCommand", "CN=My Command");

        command.OperationType = "none";
        command.ExecutionMoment = ADM_BUSINESSRULEEXECMOMENT_ENUM.ADM_BUSINESSRULEEXECMOMENT_BEFORE;
        command.ObjectType = "user";
        command.CommandIcon = 5;

        command.Description = "My description";
        command.Confirmation = "Are you sure?";
        command.Disabled = false;

        // Save the custom command.
        command.SetInfo();
    }
}

Details

To create a custom command, you need to connect to your Adaxes service and bind to the container where you want to create the command – for example, the root container for custom commands also known as the CustomCommands container.

If your script will be executed inside Adaxes, it becomes even simpler. You don't have to explicitly connect to your Adaxes service. Instead, you can use a predefined PowerShell variable $Context to get the ADS path of the CustomCommands container and bind to it.

# Bind to the custom commands container.
$containerPath = $Context.GetWellKnownContainerPath("CustomCommands")
$container = $Context.BindToObject($containerPath)
 How to create a custom command in a specific container

To create a custom command in a specific container, you need to build the ADS path of that container and bind to it just like you would bind to the CustomCommands container. The AdsPath class contains methods that simplify manipulating ADS paths.

The following code sample creates a custom command in the container called My Container. The custom command will target Group objects.

PowerShell
[Reflection.Assembly]::LoadWithPartialName("Softerra.Adaxes.Adsi")

# Connect to the Adaxes service.
$ns = New-Object "Softerra.Adaxes.Adsi.AdmNamespace"
$service = $ns.GetServiceDirectly("localhost")

# Build the ADS path of the nested container 'My Container' and bind to it.
$containerPath = $service.Backend.GetConfigurationContainerPath("CustomCommands")
$containerAdsPath = New-Object "Softerra.Adaxes.Adsi.AdsPath" $containerPath
$myContainerPath = $containerAdsPath.CreateChildPath("CN=My Container")
$myContainer = $service.OpenObject($myContainerPath, $null, $null, 0)

# Create a new custom command.
$command = $myContainer.Create("adm-CustomCommand", "CN=My Command")

$command.OperationType = "none"
$command.ExecutionMoment = "ADM_BUSINESSRULEEXECMOMENT_BEFORE"
$command.ObjectType = "group"
$command.CommandIcon = 10

$command.Description = "My description"
$command.Confirmation = "Are you sure?"
$command.Disabled = $false

# Save the custom command.
$command.SetInfo()
C#
using Softerra.Adaxes.Adsi;
using Softerra.Adaxes.Interop.Adsi;
using Softerra.Adaxes.Interop.Adsi.BusinessRules;
using Softerra.Adaxes.Interop.Adsi.CustomCommands;
using Softerra.Adaxes.Interop.Adsi.PersistentObjects;

class Program
{
    static void Main(string[] args)
    {
        // Connect to the Adaxes service.
        AdmNamespace ns = new AdmNamespace();
        IAdmService service = ns.GetServiceDirectly("localhost");

        // Build the ADS path of the nested container 'My Container' and bind to it.
        string containerPath = service.Backend.GetConfigurationContainerPath("CustomCommands");
        AdsPath containerAdsPath = new AdsPath(containerPath);
        AdsPath myContainerPath = containerAdsPath.CreateChildPath("CN=My Container");

        IADsContainer myContainer = (IADsContainer)service.OpenObject(
            myContainerPath.ToString(), null, null, 0);

        // Create a new custom command.
        IAdmCustomCommand command = (IAdmCustomCommand)myContainer.Create(
            "adm-CustomCommand", "CN=My Command");

        command.OperationType = "none";
        command.ExecutionMoment = ADM_BUSINESSRULEEXECMOMENT_ENUM.ADM_BUSINESSRULEEXECMOMENT_BEFORE;
        command.ObjectType = "group";
        command.CommandIcon = 10;

        command.Description = "My description";
        command.Confirmation = "Are you sure?";
        command.Disabled = false;

        // Save the custom command.
        command.SetInfo();
    }
}

For information on how to create containers for custom commands, see Creating custom command containers.

After binding to the container, call the Create method of the IADsContainer interface supported by all containers.

The method takes two parameters. The first one is the object type, "adm-CustomCommand" in our case. The second one is a relative distinguished name of the new command.

Mandatory properties

The object returned by Create implements the IAdmCustomCommand interface inherited from the IAdmBusinessRule interface. Using these interfaces, you need to specify mandatory custom command properties before you will be able to save it.

  • OperationType – must always be set to none.

  • ExecutionMoment – must always be set to ADM_BUSINESSRULEEXECMOMENT_BEFORE.

  • ObjectType – determines the type of objects the custom command will be able to target. The object type name must be specified exactly as it is defined in your directory schema e.g. user, organizationalUnit.

  • CommandIcon – the index of the icon that will be associated with the custom command. If you don't want any icon to be associated with a command, set this property to 0 (zero).

Optional properties

You can specify optional custom command properties before saving it.

  • Description – the command description.

  • Confirmation – the confirmation text that will be displayed to the user before executing the command.

  • Disabled – if set to true, the custom command will be created in a disabled state.

Finally, save the custom command by calling SetInfo.

Specifying actions and conditions

Use the ConditionedActions property of the IAdmBusinessRule interface to specify the actions and conditions of a custom command. This property is a collection that supports the IAdmCollection interface. Each item in the collection represents an action set – a block of conditions and actions that should be executed when the conditions are met.

For information on how to manage custom command actions and conditions, see Defining actions and conditions.

Modifying a custom command

To modify an existing custom command, you need to connect to your Adaxes service and bind to the directory object representing the command.

If your script will be executed inside Adaxes, it is even simpler. You don't have to explicitly connect to your Adaxes service. Instead, you can get the ADS path of the CustomCommands container and bind to a command using a predefined PowerShell variable $Context.

$containerPath = $Context.GetWellKnownContainerPath("CustomCommands")
$containerAdsPath = New-Object "Softerra.Adaxes.Adsi.AdsPath" $containerPath
$commandPath = $containerAdsPath.CreateChildPath("CN=My command")
$command = $Context.BindToObject($commandPath)

After binding to the command, you can use the IAdmCustomCommand, IAdmBusinessRule, and IADs interfaces to modify the command. To save the changes, call SetInfo.

Examples

The following code sample disables a custom command and changes the type of directory objects the command can target.

PowerShell
[Reflection.Assembly]::LoadWithPartialName("Softerra.Adaxes.Adsi")

# Connect to the Adaxes service.
$ns = New-Object "Softerra.Adaxes.Adsi.AdmNamespace"
$service = $ns.GetServiceDirectly("localhost")

# Bind to the custom command.
$containerPath = $service.Backend.GetConfigurationContainerPath("CustomCommands")
$containerAdsPath = New-Object "Softerra.Adaxes.Adsi.AdsPath" $containerPath
$commandPath = $containerAdsPath.CreateChildPath("CN=My Command")
$command = $service.OpenObject($commandPath.ToString(), $null, $null, 0)

$command.ObjectType = "contact"
$command.Disabled = $true

# Save the changes.
$command.SetInfo()
C#
using Softerra.Adaxes.Adsi;
using Softerra.Adaxes.Interop.Adsi.CustomCommands;
using Softerra.Adaxes.Interop.Adsi.PersistentObjects;

class Program
{
    static void Main(string[] args)
    {
        // Connect to the Adaxes service.
        AdmNamespace ns = new AdmNamespace();
        IAdmService service = ns.GetServiceDirectly("localhost");

        // Bind to the custom command.
        string containerPath = service.Backend.GetConfigurationContainerPath("CustomCommands");
        AdsPath containerAdsPath = new AdsPath(containerPath);
        AdsPath commandPath = containerAdsPath.CreateChildPath("CN=My Command");
        IAdmCustomCommand command =
            (IAdmCustomCommand)service.OpenObject(commandPath.ToString(), null, null, 0);

        command.ObjectType = "contact";
        command.Disabled = true;

        // Save the changes.
        command.SetInfo();
    }
}

The following code sample deletes all actions and conditions from a custom command located in the container named My Container.

PowerShell
[Reflection.Assembly]::LoadWithPartialName("Softerra.Adaxes.Adsi")

# Connect to the Adaxes service.
$ns = New-Object "Softerra.Adaxes.Adsi.AdmNamespace"
$service = $ns.GetServiceDirectly("localhost")

# Bind to the custom command.
$containerPath = $service.Backend.GetConfigurationContainerPath("CustomCommands")
$containerAdsPath = New-Object "Softerra.Adaxes.Adsi.AdsPath" $containerPath
$myContainerPath = $containerAdsPath.CreateChildPath("CN=My Container")
$commandPath = $myContainerPath.CreateChildPath("CN=My Command")
$command = $service.OpenObject($commandPath.ToString(), $null, $null, 0)

$command.ConditionedActions.Clear()
C#
using Softerra.Adaxes.Adsi;
using Softerra.Adaxes.Interop.Adsi.PersistentObjects;
using Softerra.Adaxes.Interop.Adsi.CustomCommands;

class Program
{
    static void Main(string[] args)
    {
        // Connect to the Adaxes service.
        AdmNamespace ns = new AdmNamespace();
        IAdmService service = ns.GetServiceDirectly("localhost");

        // Bind to the custom command.
        string containerPath = service.Backend.GetConfigurationContainerPath("CustomCommands");
        AdsPath containerAdsPath = new AdsPath(containerPath);
        AdsPath myContainerPath = containerAdsPath.CreateChildPath("CN=My Container");
        AdsPath commandPath = myContainerPath.CreateChildPath("CN=My Command");
        IAdmCustomCommand command = (IAdmCustomCommand)service.OpenObject(commandPath.ToString(),
            null, null, 0);

        command.ConditionedActions.Clear();
    }
}

Adding parameters to a custom command

To add a parameter to a custom command, you need to first create it using the CreateParameter method of the IAdmCustomCommand interface. The possible parameter types are listed in the ADM_PARAMETERTYPE_ENUM enumerator.

The object returned by CreateParameter implements a specific interface, depending on the parameter type you have created. Use it to set the parameter properties.

 Parameter types and corresponding interfaces

All interfaces inherit from the IAdmParameter interface.

Once the parameter is ready, add it to the command using the Parameters property of the IAdmCustomCommand interface and then call SetInfo to save the changes.

Examples

 Example 1 – Checkbox parameter

The following code sample adds a checkbox parameter to a custom command.

PowerShell
# The $command variable refers to a custom command.

# Create a checkbox parameter.
$paramCheckBox = $command.CreateParameter("ADM_PARAMETERTYPE_CHECK")
$paramCheckBox.Name = "MyCheckbox"
$paramCheckBox.ValueWhenChecked = "Yes"
$paramCheckBox.ValueWhenUnchecked = "No"

# Add the parameter to the command and save it.
$command.Parameters += $paramCheckBox
$command.SetInfo()
C#
// The command variable refers to a custom command.

// Get current command parameters.
List<IAdmParameter> listOfParameters = new(
    command.Parameters ?? Enumerable.Empty<IAdmParameter>());

// Create a checkbox parameter.
IAdmParameterCheck paramCheckBox = (IAdmParameterCheck)command.CreateParameter(
    ADM_PARAMETERTYPE_ENUM.ADM_PARAMETERTYPE_CHECK);
paramCheckBox.Name = "MyCheckBox";
paramCheckBox.ValueWhenChecked = "Yes";
paramCheckBox.ValueWhenUnchecked = "No";

// Add the parameter to the command and save it.
listOfParameters.Add(paramCheckBox);
command.Parameters = listOfParameters.ToArray();
command.SetInfo();
 Example 2 – Drop-down list parameter

The following code sample adds a drop-down list parameter to a custom command.

PowerShell
# The $command variable refers to a custom command.

# Create a drop-down list parameter.
$paramDropDown = $command.CreateParameter("ADM_PARAMETERTYPE_LIST")
$paramDropDown.Name = "MyDropDownList"

## Create a list of predefined values.
$value1 = $paramDropDown.CreateValue()
$value1.DisplayName = "Sales department"
$value1.Value = "sales"

$value2 = $paramDropDown.CreateValue()
$value2.DisplayName = "HR department"
$value2.Value = "hr"
$value2.IsDefault = $true

$paramDropDown.Values = @($value1,$value2)
$paramDropDown.AllowCustomValue = $false

# Add the parameter to the command and save it.
$command.Parameters += $paramDropDown
$command.SetInfo()
C#
// The command variable refers to a custom command.

// Get current command parameters.
List<IAdmParameter> listOfParameters = new(
    command.Parameters ?? Enumerable.Empty<IAdmParameter>());

// Create a drop-down list parameter.
IAdmParameterListOfValues paramDropDown = (IAdmParameterListOfValues)command.CreateParameter(
    ADM_PARAMETERTYPE_ENUM.ADM_PARAMETERTYPE_LIST);
paramDropDown.Name = "MyDropDownList";

// Create a list of predefined values.
IAdmParameterPredefinedValue value1 = paramDropDown.CreateValue();
value1.DisplayName = "Sales department";
value1.Value = "sales";

IAdmParameterPredefinedValue value2 = paramDropDown.CreateValue();
value2.DisplayName = "HR department";
value2.Value = "hr";
value2.IsDefault = true;

paramDropDown.Values = new IAdmParameterPredefinedValue[] { value1, value2 };
paramDropDown.AllowCustomValue = false;

// Add the parameter to the command and save it.
listOfParameters.Add(paramDropDown);
command.Parameters = listOfParameters.ToArray();
command.SetInfo();
 Example 3 – Checkbox list parameter

The following code sample adds a checkbox list parameter to a custom command.

PowerShell
# The $command variable refers to a custom commandю

# Create a checkbox list parameter.
$paramCheckBoxList = $command.CreateParameter("ADM_PARAMETERTYPE_CHECKLIST")
$paramCheckBoxList.Name = "MyCheckBoxList"
$paramCheckBoxList.Separator = ";"

# Create a list of predefined items.
$item1 = $paramCheckBoxList.CreateItem()
$item1.Name = "Remote employee"
$item1.DisplayName = "Remote employee"
$item1.ValueWhenChecked = "true"
$item1.ValueWhenUnchecked = "false"

$item2 = $paramCheckBoxList.CreateItem()
$item2.Name = "Privileged access required"
$item2.DisplayName = "Privileged access required"
$item2.ValueWhenChecked = "true"
$item2.ValueWhenUnchecked = "false"

$paramCheckBoxList.Items = @($item1,$item2)
$paramCheckBoxList.MinimumSelectedItems = 0

# Add the parameter to the command and save it.
$command.Parameters += $paramCheckBoxList
$command.SetInfo()
C#
// The command variable refers to a custom command.

// Get current command parameters.
List<IAdmParameter> listOfParameters = new(
    command.Parameters ?? Enumerable.Empty<IAdmParameter>());

// Create a checkbox list parameter.
IAdmParameterCheckList paramCheckBoxList = (IAdmParameterCheckList)command.CreateParameter(
    ADM_PARAMETERTYPE_ENUM.ADM_PARAMETERTYPE_CHECKLIST);
paramCheckBoxList.Name = "MyCheckBoxList";

// Create a list of predefined items.
IAdmParameterCheck item1 = paramCheckBoxList.CreateItem();
item1.Name = "Remote employee";
item1.DisplayName = "Remote employee";
item1.ValueWhenChecked = "true";
item1.ValueWhenUnchecked = "false";

IAdmParameterCheck item2 = paramCheckBoxList.CreateItem();
item2.Name = "Privileged access required";
item2.DisplayName = "Privileged access required";
item2.ValueWhenChecked = "true";
item2.ValueWhenUnchecked = "false";

paramCheckBoxList.Items = new IAdmParameterCheck[] { item1, item2 };
paramCheckBoxList.MinimumSelectedItems = 0;

// Add the parameter to the command and save it.
listOfParameters.Add(paramCheckBoxList);
command.Parameters = listOfParameters.ToArray();
command.SetInfo();
 Example 4 – Edit box and date/time picker parameters

The following code sample adds an edit box and a date/time parameter to a custom command.

PowerShell
# The $command variable refers to a custom command.

# Create an edit box parameter.
$paramEditBox = $command.CreateParameter("ADM_PARAMETERTYPE_TEXT")
$paramEditBox.Name = "MyEditBox"

# Create a date/time picker parameter.
$paramDateTime = $command.CreateParameter("ADM_PARAMETERTYPE_DATETIME")
$paramDateTime.Name = "MyDateTimePicker"
$paramDateTime.AllowChangeTime = $false

# Add the parameters to the command and save it.
$command.Parameters += $paramEditBox
$command.Parameters += $paramDateTime
$command.SetInfo()
C#
// The command variable refers to a custom command.

// Get current command parameters.
List<IAdmParameter> listOfParameters = new(
    command.Parameters ?? Enumerable.Empty<IAdmParameter>());

// Create an edit box parameter.
IAdmParameterText paramEditBox = (IAdmParameterText)command.CreateParameter(
    ADM_PARAMETERTYPE_ENUM.ADM_PARAMETERTYPE_TEXT);
paramEditBox.Name = "MyEditBox";

// Create a date/time picker parameter.
IAdmParameterDateTime paramDateTime = (IAdmParameterDateTime)command.CreateParameter(
        ADM_PARAMETERTYPE_ENUM.ADM_PARAMETERTYPE_DATETIME);
paramDateTime.Name = "MyDateTimePicker";
paramDateTime.AllowChangeTime = false;


// Add the parameters to the command and save it.
listOfParameters.Add(paramEditBox);
listOfParameters.Add(paramDateTime);
command.Parameters = listOfParameters.ToArray();
command.SetInfo();
 Example 5 – Object picker parameter

The following code sample adds an object picker parameter to a custom command.

PowerShell
# The $command variable refers to a custom command.

# Create an object picker parameter.
$paramObjectPicker = $command.CreateParameter("ADM_PARAMETERTYPE_DIRECTORYOBJECT")
$paramObjectPicker.Name = "MyObjectPicker"

# Add a predefined object to parameter configuration.
$objectReference = [Softerra.Adaxes.Adsi.AdmObjectReference]::CreateFromDN(
    "CN=John Smith,OU=My OU,DC=example,DC=com")
$predefinedObject = $paramObjectPicker.CreatePredefinedObject()
$predefinedObject.ObjectReference = $objectReference
$paramObjectPicker.PredefinedObjects += $predefinedObject

# Configure object selection limitations.
$selectObjectParameters = $paramObjectPicker.SelectObjectParameters

## Base object
$baseObjectReference = [Softerra.Adaxes.Adsi.AdmObjectReference]::CreateFromDN(
    "OU=My OU,DC=example,DC=com")
$selectObjectParameters.BaseObject = $baseObjectReference
$selectObjectParameters.Scope = "ADS_SCOPE_SUBTREE"

## Criteria - only users from the sales department
$criteria = New-AdmCriteria -Type "user" -Expression {department -eq "Sales"}
$selectObjectParameters.SetCriteria($criteria)

$paramObjectPicker.SelectObjectParameters = $selectObjectParameters

# Add the parameter to the command and save it.
$command.Parameters += $paramObjectPicker
$command.SetInfo()
C#
// The command variable refers to a custom command.

// Get current command parameters.
List<IAdmParameter> paramList = new(
    command.Parameters ?? Enumerable.Empty<IAdmParameter>());

// Create an object picker parameter.
IAdmParameterDirectoryObject paramObjectPicker = (IAdmParameterDirectoryObject)command.CreateParameter(
    ADM_PARAMETERTYPE_ENUM.ADM_PARAMETERTYPE_DIRECTORYOBJECT);
paramObjectPicker.Name = "MyObjectPicker";

// Add a predefined object to parameter configuration.
IAdmObjectReference objectReference = AdmObjectReference.CreateFromDN(
    "CN=John Smith,OU=My OU,DC=example,DC=com");
IAdmPredefinedObject predefinedObject = paramObjectPicker.CreatePredefinedObject();
predefinedObject.ObjectReference = objectReference;

paramObjectPicker.PredefinedObjects = new IAdmPredefinedObject[] { predefinedObject };

// Configure object selection limitations.
IAdmSelectObjectParameters selectObjectParameters = paramObjectPicker.SelectObjectParameters;

// Base object
IAdmObjectReference baseObjectReference = AdmObjectReference.CreateFromDN(
    "OU=My OU,DC=example,DC=com");
selectObjectParameters.BaseObject = baseObjectReference;
selectObjectParameters.Scope = ADS_SCOPEENUM.ADS_SCOPE_SUBTREE;

// Criteria - only users from the sales department
Criteria criteria = new();
IAdmSimpleCriteriaItem item = new SimpleCriteriaItem()
{
    Property = "department",
    Operator = "eq",
    Values = { "Sales" }
};
criteria.AddType("user", (CriteriaItem)item);
selectObjectParameters.SetCriteria(criteria);

paramObjectPicker.SelectObjectParameters = selectObjectParameters;

// Add the parameter to the command and save it.
paramList.Add(paramObjectPicker);
command.Parameters = paramList.ToArray();
command.SetInfo();
 Example 6 – Property name picker parameter

The following code sample adds a property name picker parameter to a custom command.

PowerShell
# The $command variable refers to a custom command.

# Create a property name picker parameter.
$paramPropertyName = $command.CreateParameter("ADM_PARAMETERTYPE_PROPERTYNAME")
$paramPropertyName.Name = "MyPropertyNamePicker"
$paramPropertyName.AllowEmptyValue = $false

# Configure properties available for selection.
$paramPropertyName.AvailableProperties = "ADM_AVAILABLEPROPERTIES_SPECIFICPROPERTIES"
$paramPropertyName.SpecificProperties = @(
    "department",
    "title",
    "description"
)

# Add the parameter to the command and save it.
$command.Parameters += $paramPropertyName
$command.SetInfo()
C#
// The command variable refers to a custom command.

// Get current command parameters.
List<IAdmParameter> listOfParameters = new(
    command.Parameters ?? Enumerable.Empty<IAdmParameter>());

// Create a property name picker parameter.
IAdmParameterPropertyName paramPropertyName = (IAdmParameterPropertyName)command.CreateParameter(
    ADM_PARAMETERTYPE_ENUM.ADM_PARAMETERTYPE_PROPERTYNAME);
paramPropertyName.Name = "MyPropertyNamePicker";
paramPropertyName.AllowEmptyValue = false;

// Configure properties available for selection.
paramPropertyName.AvailableProperties = 
    ADM_AVAILABLEPROPERTIES_ENUM.ADM_AVAILABLEPROPERTIES_SPECIFICPROPERTIES;
paramPropertyName.SpecificProperties = new string[]
{
    "department",
    "title",
    "description"
};

// Add the parameter to the command and save it.
listOfParameters.Add(paramPropertyName);
command.Parameters = listOfParameters.ToArray();
command.SetInfo();

Executing a custom command

To execute a custom command, you need to bind to the directory object you want to execute the command on. After binding to the directory object, call the ExecuteCustomCommand method of the IAdmTop interface implemented by all directory objects.

The method takes two input parameters.

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

  • arguments – an instance of the IAdmCustomCommandArguments interface that represents the custom command parameter values. To execute a command without parameters or using the default values, specify $null.

Examples

 Example 1 – Execute a command with no parameters

The following code sample executes the built-in custom command named Deprovision on a user object.

PowerShell
[Reflection.Assembly]::LoadWithPartialName("Softerra.Adaxes.Adsi")

# Connect to the Adaxes service.
$ns = New-Object "Softerra.Adaxes.Adsi.AdmNamespace"
$service = $ns.GetServiceDirectly("localhost")

# Bind to the target user.
$userDN = "CN=John Smith,OU=My OU,DC=example,DC=com"
$user = $service.OpenObject("Adaxes://$userDN", $null, $null, 0)

# Execute the command.
$commandId = "{9DB88EC3-1241-4AB1-9612-C7C982BAA49F}" # Deprovision
$user.ExecuteCustomCommand($commandId, $null)
C#
using Softerra.Adaxes.Adsi;
using Softerra.Adaxes.Interop.Adsi;
using Softerra.Adaxes.Interop.Adsi.PersistentObjects;

class Program
{
    static void Main(string[] args)
    {
        // Connect to the Adaxes service.
        AdmNamespace ns = new AdmNamespace();
        IAdmService service = ns.GetServiceDirectly("localhost");

        // Bind to the target user.
        const string userDN = "CN=John Smith,OU=My OU,DC=example,DC=com";
        IAdmTop user = (IAdmTop)service.OpenObject($"Adaxes://{userDN}", null, null, 0);

        // Execute the command.
        const string commandId = "{9DB88EC3-1241-4AB1-9612-C7C982BAA49F}"; // Deprovision
        user.ExecuteCustomCommand(commandId, null);
    }
}
 Example 2 – Execute a command with a checkbox parameter

The following code sample executes a custom command with a checkbox parameter on a user object. The checkbox value is set to Enabled.

PowerShell
[Reflection.Assembly]::LoadWithPartialName("Softerra.Adaxes.Adsi")

# Connect to the Adaxes service.
$ns = New-Object "Softerra.Adaxes.Adsi.AdmNamespace"
$service = $ns.GetServiceDirectly("localhost")

# Bind to the custom command.
$commandId = "{AC209B5D-042F-4165-B9F6-F73393FCBA1C}"
$command = $service.OpenObject("Adaxes://<GUID=$commandId>", $null, $null, 0)

# Create custom command arguments.
$arguments = $command.CreateArguments()

# Specify parameter value.
$arguments.SetParameterValue("param-MyCheckbox", 1)

# Bind to the user.
$userDN = "CN=John Smith,OU=My OU,DC=example,DC=com"
$user = $service.OpenObject("Adaxes://$userDN", $null, $null, 0)

# Execute the custom command.
$user.ExecuteCustomCommand($command.commandId, $arguments)
C#
using Softerra.Adaxes.Adsi;
using Softerra.Adaxes.Interop.Adsi;
using Softerra.Adaxes.Interop.Adsi.CustomCommands;
using Softerra.Adaxes.Interop.Adsi.PersistentObjects;

class Program
{
    static void Main(string[] args)
    {
        // Connect to the Adaxes service.
        AdmNamespace ns = new AdmNamespace();
        IAdmService service = ns.GetServiceDirectly("localhost");

        // Bind to the custom command.
        const string commandId = "{AC209B5D-042F-4165-B9F6-F73393FCBA1C}";
        IAdmCustomCommand command = (IAdmCustomCommand)service.OpenObject(
            $"Adaxes://<GUID={commandId}>", null, null, 0);

        // Create custom command arguments.
        IAdmCustomCommandArguments arguments = command.CreateArguments();

        // Specify parameter value.
        arguments.SetParameterValue("param-MyCheckbox", 1);

        // Bind to the target user.
        const string userDN = "CN=John Smith,OU=My OU,DC=example,DC=com";
        IAdmTop user = (IAdmTop)service.OpenObject($"Adaxes://{userDN}", null, null, 0);

        // Execute the custom command.
        user.ExecuteCustomCommand(command.CommandID, arguments);
    }
}
 Example 3 – Execute a command with a drop-down list parameter

The following code sample executes a custom command with a drop-down list parameter on a user object. The value selected in the drop-down list is Option One.

PowerShell
[Reflection.Assembly]::LoadWithPartialName("Softerra.Adaxes.Adsi")

# Connect to the Adaxes service.
$ns = New-Object "Softerra.Adaxes.Adsi.AdmNamespace"
$service = $ns.GetServiceDirectly("localhost")

# Bind to the custom command.
$commandId = "{AC209B5D-042F-4165-B9F6-F73393FCBA1C}"
$command = $service.OpenObject("Adaxes://<GUID=$commandId>", $null, $null, 0)

# Create custom command arguments.
$arguments = $command.CreateArguments()

# Get the identifier of the desired value.
$desiredValue = "Option One"
$parameter = $command.Parameters.Where({$_.Name -eq "param-MyDropDownList"}, 0, $null)
$valueId = ($parameter.Values.Where({$_.Value -eq $desiredValue}, 0, $null)).ID

# Specify parameter value.
$arguments.SetParameterValue("param-MyDropDownList", $valueId)

# Bind to the target user.
$userDN = "CN=John Smith,OU=My OU,DC=example,DC=com"
$user = $service.OpenObject("Adaxes://$userDN", $null, $null, 0)

# Execute the custom command.
$user.ExecuteCustomCommand($command.CommandID, $arguments)
C#
using System;
using Softerra.Adaxes.Adsi;
using Softerra.Adaxes.Interop.Adsi;
using Softerra.Adaxes.Interop.Adsi.CustomCommands;
using Softerra.Adaxes.Interop.Adsi.Parameters;
using Softerra.Adaxes.Interop.Adsi.PersistentObjects;

class Program
{
    static void Main(string[] args)
    {
        // Connect to the Adaxes service.
        AdmNamespace ns = new AdmNamespace();
        IAdmService service = ns.GetServiceDirectly("localhost");

        // Bind to the custom command.
        const string commandId = "{AC209B5D-042F-4165-B9F6-F73393FCBA1C}";
        IAdmCustomCommand command = (IAdmCustomCommand)service.OpenObject(
            $"Adaxes://<GUID={commandId}>", null, null, 0);

        // Create custom command arguments.
        IAdmCustomCommandArguments arguments = command.CreateArguments();

        // Get the identifier of the desired value.
        const string desiredValue = "Option One";
        IAdmParameterListOfValues parameter = (IAdmParameterListOfValues)Array.Find(
            command.Parameters, param => param.Name == "param-MyDropDownList");
        string valueId = Array.Find(parameter.Values, value => value.Value == desiredValue).ID;

        // Specify parameter value.
        arguments.SetParameterValue("param-MyDropDownList", valueId);

        // Bind to the target user.
        const string userDN = "CN=John Smith,OU=My OU,DC=example,DC=com";
        IAdmTop user = (IAdmTop)service.OpenObject($"Adaxes://{userDN}", null, null, 0);

        // Execute the custom command.
        user.ExecuteCustomCommand(command.CommandID, arguments);
    }
}

Note how you need to select the desired value from the drop-down list via its value identifier. This principle applies to drop-down list and checkbox list parameters. In the above code sample, the value identifier is obtained by searching through all parameter values and selecting the desired one.

Alternatively, you can hardcode the value identifier if you know it beforehand. For information on how to get the identifiers, see Viewing parameters of a custom command.

For more examples on how to execute custom commands, see Executing custom commands.

See also

© Softerra 2022. All rights reserved.
Send feedback