Skip to content

Managing Custom Commands

This article describes how to manage Custom Commands using PowerShell scripts and C# code. The code samples included in this article can be used in stand-alone scripts and applications as well as in PowerShell scripts executed by Business Rules, Custom Commands, and Scheduled Tasks.

Creating a Custom Command

To create a Custom Command, first you need to bind to the container where you want to create it. All container objects support the IADsContainer interface, which provides methods and properties that manage the creation, deletion, and enumeration of child objects. To create a new Custom Command, you need to call the Create method of the interface and pass “adm-CustomCommand” as the first parameter of the method, and the relative distinguished name (RDN) of the command as the second parameter. The object returned by the IADsContainer::Create method will support the IAdmCustomCommand interface, using which you can specify the parameters of the new Custom Command. The IAdmCustomCommand interface is inherited from the IAdmBusinessRule interface, and some Custom Command parameters must be set via the properties of the IAdmBusinessRule interface.

  1. Use the IAdmBusinessRule::ObjectType property to specify the type of directory objects on which the Custom Command will be executed. The property must be set to a string that contains the name of an object class as defined in the Active Directory schema (e.g. “user”, “group”, “computer”, “organizationalUnit”).

    Using the IAdmBusinessRule2::AdditionalObjectType property, you can specify an additional type of objects on which the Custom Command can be executed.

  2. Use the IAdmCustomCommand::Confirmation property to specify the confirmation text that will be displayed to the user before executing the command. If you don’t want any confirmation to be displayed, leave this property blank.

  3. Use the IAdmCustomCommand::CommandIcon property to specify 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).

  4. Always set the IAdmBusinessRule::ExecutionMoment property of Custom Command objects to ADM_BUSINESSRULEEXECMOMENT_BEFORE.

  5. Always set the IAdmBusinessRule::OperationType property of Custom Command objects to “none”.

To save the new Custom Command, call IADs::SetInfo.

The following code sample creates a Custom Command to be executed on users.

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

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

# Bind to the 'Custom Commands' container
$customCommandsPath = $admService.Backend.GetConfigurationContainerPath(
    "CustomCommands")
$customCommandsContainer = $admService.OpenObject($customCommandsPath,
     $NULL, $NULL, 0)

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

$command.ObjectType = "user"
$command.Confirmation = "Are you sure?"
$command.CommandIcon = 5

$command.Description = "My description"
$command.Disabled = $False

$command.ExecutionMoment = "ADM_BUSINESSRULEEXECMOMENT_BEFORE"
$command.OperationType = "none"

# Save the Custom Command
$command.SetInfo()
using System;
using Interop.Adsi;
using Interop.Adsi.BusinessRules;
using Interop.Adsi.CustomCommands;
using Softerra.Adaxes.Adsi;
using Softerra.Adaxes.Interop.Adsi.PersistentObjects;
class Program
{
    static void Main(string[] args)
    {
        // Connect to the Adaxes service
        AdmNamespace adsNS = new AdmNamespace();
        IAdmService admService = adsNS.GetServiceDirectly("localhost");

        // Bind to the 'Custom Commands' container
        String customCommandsPath = admService.Backend.GetConfigurationContainerPath(
            "CustomCommands");
        IADsContainer customCommandsContainer = (IADsContainer)admService.OpenObject(
            customCommandsPath, null, null, 0);

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

        command.ObjectType = "user";
        command.Confirmation = "Are you sure?";
        command.CommandIcon = 5;

        command.Description = "My description";
        command.Disabled = false;

        command.ExecutionMoment =
            ADM_BUSINESSRULEEXECMOMENT_ENUM.ADM_BUSINESSRULEEXECMOMENT_BEFORE;
        command.OperationType = "none";

        // Save the Custom Command
        command.SetInfo();
    }
}

If your script is executed by a Business Rule, Scheduled Task, or Custom Command, you can use a predefined PowerShell variable $Context to get the ADS path of the Custom Commands container and bind to the container. The type of the $Context variable is ExecuteScriptContext.

# Bind to the 'Custom Commands' container
$customCommandsPath = $Context.GetWellKnownContainerPath("CustomCommands")
$customCommandsContainer = $Context.BindToObject($customCommandsPath)

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

$command.ObjectType = "user"
$command.Confirmation = "Are you sure?"
$command.CommandIcon = 5

$command.Description = "My description"
$command.Disabled = $False

$command.ExecutionMoment = "ADM_BUSINESSRULEEXECMOMENT_BEFORE"
$command.OperationType = "none"

# Save the Custom Command
$command.SetInfo()
How to create a Custom Command in a specific container

The following code sample creates a Custom Command in the container called My Container. The custom command will apply to Group objects.

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

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

# Bind to the 'Custom Commands' container
$customCommandsPath = $admService.Backend.GetConfigurationContainerPath(
    "CustomCommands")
# Build the ADS path of the child container 'My Container'
$customCommandsPathObj = New-Object "Softerra.Adaxes.Adsi.AdsPath"`
    $customCommandsPath
$myContainerAdsPath = $customCommandsPathObj.CreateChildPath("CN=My Container")

$myContainer = $admService.OpenObject($myContainerAdsPath, $NULL, $NULL, 0)

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

$command.ObjectType = "group"
$command.Confirmation = "Are you sure?"
$command.CommandIcon = 10

$command.Description = "My description"
$command.Disabled = $False

$command.ExecutionMoment = "ADM_BUSINESSRULEEXECMOMENT_BEFORE"
$command.OperationType = "none"

# Save the Custom Command
$command.SetInfo()
using System;
using Interop.Adsi;
using Interop.Adsi.BusinessRules;
using Interop.Adsi.CustomCommands;
using Softerra.Adaxes.Adsi;
using Softerra.Adaxes.Interop.Adsi.PersistentObjects;
class Program
{
    static void Main(string[] args)
    {
        // Connect to the Adaxes service
        AdmNamespace adsNS = new AdmNamespace();
        IAdmService admService = adsNS.GetServiceDirectly("localhost");

        // Bind to the 'Custom Commands' container
        String customCommandsPath = admService.Backend.GetConfigurationContainerPath(
            "CustomCommands");
        // Build the ADS path of the child container 'My Container'
        AdsPath customCommandsPathObj = new AdsPath(customCommandsPath);
        AdsPath myContainerAdsPath = customCommandsPathObj.CreateChildPath(
            "CN=My Container");

        IADsContainer myContainer = (IADsContainer)admService.OpenObject(
            myContainerAdsPath.ToString(), null, null, 0);

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

        command.ObjectType = "group";
        command.Confirmation = "Are you sure?";
        command.CommandIcon = 10;

        command.Description = "My description";
        command.Disabled = false;

        command.ExecutionMoment =
            ADM_BUSINESSRULEEXECMOMENT_ENUM.ADM_BUSINESSRULEEXECMOMENT_BEFORE;
        command.OperationType = "none";

        // Save the Custom Command
        command.SetInfo();
    }
}

Tip

For information on how to create containers for Custom Commands, see Creating Custom Command containers.

Defining actions and conditions

To define actions and conditions for a Custom Command, you need to use the ConditionedActions property of the IAdmBusinessRule interface. The ConditionedActions property is a collection that supports the IAdmCollection interface. Each item in the collection represents a set of conditions and actions.

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, first you need to bind to the directory object representing the Custom Command. For more information on how to bind to Adaxes-specific objects, see Binding to Adaxes-specific objects.

After you’ve bound to a Custom Command object, you can use ADSI interfaces like IAdmCustomCommand, IAdmBusinessRule and IADs to modify the Custom Command. To save the changes, call IADs::SetInfo.

The following code sample disables a Custom Command and changes the type of directory objects to which the Custom Command applies.

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

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

$commandsPath = $admService.Backend.GetConfigurationContainerPath(
    "CustomCommands")
$commandsPathObj = New-Object "Softerra.Adaxes.Adsi.AdsPath" $commandsPath
$commandPath = $commandsPathObj.CreateChildPath("CN=My Command")
$command = $admService.OpenObject($commandPath.ToString(), $NULL, $NULL, 0)

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

# Save the changes
$command.SetInfo()
using System;
using Interop.Adsi.CustomCommands;
using Softerra.Adaxes.Adsi;
using Softerra.Adaxes.Interop.Adsi.PersistentObjects;
class Program
{
    static void Main(string[] args)
    {
        AdmNamespace adsNS = new AdmNamespace();
        IAdmService admService = adsNS.GetServiceDirectly("localhost");

        String commandsPath = admService.Backend.GetConfigurationContainerPath(
            "CustomCommands");
        AdsPath commandsPathObj = new AdsPath(commandsPath);
        AdsPath commandPath = commandsPathObj.CreateChildPath("CN=My Command");
        IAdmCustomCommand command =
            (IAdmCustomCommand)admService.OpenObject(commandPath.ToString(), null, null, 0);

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

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

If your script is executed by a Business Rule, Scheduled Task, or Custom Command, you can use a predefined PowerShell variable $Context to get the ADS path of the Custom Commands container and bind to the Custom Command.

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

$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.

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

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

$commandsPath = $admService.Backend.GetConfigurationContainerPath(
    "CustomCommands")
$commandsPathObj = New-Object "Softerra.Adaxes.Adsi.AdsPath" $commandsPath
$containerPathObj = $commandsPathObj.CreateChildPath("CN=My Container")
$commandPath = $containerPathObj.CreateChildPath("CN=My Command")
$command = $admService.OpenObject($commandPath.ToString(), $NULL, $NULL, 0)

$command.ConditionedActions.Clear()
using System;
using Interop.Adsi.CustomCommands;
using Interop.Adsi.BusinessRules;
using Softerra.Adaxes.Adsi;
using Softerra.Adaxes.Interop.Adsi.PersistentObjects;
class Program
{
    static void Main(string[] args)
    {
        AdmNamespace adsNS = new AdmNamespace();
        IAdmService admService = adsNS.GetServiceDirectly("localhost");

        String commandsPath = admService.Backend.GetConfigurationContainerPath(
            "CustomCommands");
        AdsPath commandsPathObj = new AdsPath(commandsPath);
        AdsPath containerPathObj = commandsPathObj.CreateChildPath("CN=My Container");
        AdsPath commandPath = containerPathObj.CreateChildPath("CN=My Command");
        IAdmCustomCommand command =
            (IAdmCustomCommand)admService.OpenObject(commandPath.ToString(),
            null, null, 0);

        command.ConditionedActions.Clear();
    }
}

Executing a Custom Command

In order to execute a Custom Command, first you need to bind to the directory object on which you want to execute it. All directory objects implement the IAdmTop3 interface. Call the ExecuteCustomCommand method of the interface to execute a Custom Command. The method gets the ID of the Custom Command as an input parameter.

Tip

For information on how to get the ID of a Custom Command, see Get the ID of a Custom Command.

The following code sample executes the built-in Custom Command called Deprovision on a user object.

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

$admNS = New-Object "Softerra.Adaxes.Adsi.AdmNamespace"
$admService = $admNS.GetServiceDirectly("localhost")

$userDN = "CN=John Smith,CN=Users,DC=company,DC=com"
$user = $admService.OpenObject("Adaxes://$userDN", $NULL, $NULL, 0)

$commandID = "{9DB88EC3-1241-4AB1-9612-C7C982BAA49F}" # Deprovision
$user.ExecuteCustomCommand($commandID)
using System;
using Interop.Adsi;
using Softerra.Adaxes.Adsi;
using Softerra.Adaxes.Interop.Adsi.PersistentObjects;
class Program
{
    static void Main(string[] args)
    {
        AdmNamespace adsNS = new AdmNamespace();
        IAdmService admService = adsNS.GetServiceDirectly("localhost");

        const String userDN = "CN=John Smith,CN=Users,DC=company,DC=com";
        IAdmTop3 user = (IAdmTop3)admService.OpenObject("Adaxes://" + userDN,
            null, null, 0);
        const String commandID = "{9DB88EC3-1241-4AB1-9612-C7C982BAA49F}"; // Deprovision
        user.ExecuteCustomCommand(commandID);
    }
}

See also