Managing business rules

Business rules can be created, edited, and deleted 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 business rules can also be executed from within Adaxes, for instance, from other business rules, custom commands, and scheduled tasks.

Creating a business rule

The following code sample creates a business rule that triggers after creating user accounts.

Details

To create a business rule, you need to connect to your Adaxes service and bind to the container where you want to create the rule – for example, the root container for business rules also known as the BusinessRules 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 BusinessRules container and bind to it.

# Bind to the business rules container.
$containerPath = $Context.GetWellKnownContainerPath("BusinessRules")
$container = $Context.BindToObject($containerPath)

 How to create a business rule in a different container

To create a business rule 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 BusinessRules container. The AdsPath class contains methods that simplify manipulating ADS paths.

The following code sample creates a business rule in the container named My Container. The rule will be triggered before adding a member to a group.

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 business rules container.
$containerPath = $service.Backend.GetConfigurationContainerPath("BusinessRules")

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

# Create a new business rule.
$rule = $myContainer.Create("adm-BusinessRule", "CN=My Rule")

$rule.ExecutionMoment = "ADM_BUSINESSRULEEXECMOMENT_BEFORE"
$rule.ObjectType = "group"
$rule.OperationType = "add group members"

# Save the business rule.
$rule.SetInfo()

C#

using Softerra.Adaxes.Adsi;
using Softerra.Adaxes.Interop.Adsi;
using Softerra.Adaxes.Interop.Adsi.BusinessRules;
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 business rules container.
        string containerPath = service.Backend.GetConfigurationContainerPath("BusinessRules");

        // Build the ADS path of the nested container 'My Container' and bind to it.
        AdsPath businessRulesPathObj = new AdsPath(containerPath);
        AdsPath myContainerAdsPath = businessRulesPathObj.CreateChildPath("CN=My Container");

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

        // Create a new business rule.
        IAdmBusinessRule rule = (IAdmBusinessRule)myContainer.Create(
            "adm-BusinessRule", "CN=My Rule");

        rule.ExecutionMoment = ADM_BUSINESSRULEEXECMOMENT_ENUM.ADM_BUSINESSRULEEXECMOMENT_BEFORE;
        rule.ObjectType = "group";
        rule.OperationType = "add group members";

        // Save the business rule.
        rule.SetInfo();
    }
}

For details about how to create containers for business rules, see Creating business rule 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-BusinessRule" in our case. The second one is a relative distinguished name of the new rule.

Mandatory properties

The object returned by Create implements the IAdmBusinessRule interface. Using this interface, you need to specify mandatory business rule properties before you will be able to save it.

• OperationType – determines the type of operations that will trigger the business rule.

   Possible operation types {id=businessRuleOperationTypes}

  • Operation type

  • Operation description

  • "create"

  • Creating an object

  • "delete"

  • Deleting an object

  • "set properties"

  • Updating an object

  • "rename"

  • Renaming an object

  • "manage group members"

  • Adding or removing a member from a group

  • "add group members"

  • Adding a member to a group

  • "remove group members"

  • Removing a member from a group

  • "move"

  • Moving an object

  • "manage account state"

  • Enabling or disabling a user or computer

  • "enable account"

  • Enabling a user or computer

  • "disable account"

  • Disabling a user or computer

  • "change logon name"

  • Changing the logon name of a user or computer

  • "modify password"

  • Changing or resetting the password of a user

  • "change password"

  • Changing the password of a user

  • "reset password"

  • Resetting the password of a user

  • "self password reset"

  • Self-resetting password

  • "mailbox-enable"

  • Creating an Exchange mailbox for a user

  • "create move mailbox request"

  • Moving the Exchange mailbox of a user

  • "mailbox-disable"

  • Deleting the Exchange mailbox of a user

  • "modify O365 properties"

  • Modifying Microsoft 365 properties

  • "mail-enable"

  • Establishing an email address for a recipient in Exchange

  • "mail-disable"

  • Deleting email addresses established in Exchange for a recipient

  • "set exchange mail params"

  • Modifying Exchange properties

  • "pwd self-service enroll"

  • Enrolling for Password Self-Service

  • "pwd self-service disenroll"

  • Disenrolling from Password Self-Service

  • "restore deleted object"

  • Restoring a deleted object

  • "unlock account"

  • Unlocking user account

• ExecutionMoment – determines whether a business rule is executed before or after an operation. The ADM_BUSINESSRULEEXECMOMENT_ENUM enumeration defines the possible values.

• ObjectType – determines the type of objects the business rule applies to. The object type name must be specified exactly as it is defined in your directory schema e.g. user, organizationalUnit.

  Pay attention that not all object types are compatible with certain operation types. For example, you cannot have a business rule that triggers when a member is added to a user. You will be able to save such a rule without errors, but it will not make any sense.

Optional properties

You can specify optional business rule properties before saving it.

• Description – the rule description.

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

Finally, save the business rule save by calling SetInfo.

Specifying actions and conditions

Use the ConditionedActions property of the IAdmBusinessRule interface to specify the actions and conditions of a business rule. 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 business rule actions and conditions, see Defining actions and conditions.

Setting activity scope

Use the ActivityScopeItems property of the IAdmBusinessRule interface to define the activity scope for a business rule. A business rule is executed only if the triggering operation is performed on an object within the scope. Activity scope can include domains, members of groups, business units, objects located in specific organizational units, etc.

For information on how to define the activity scope of a business rule, see Defining the scope of activity.

Modifying a business rule

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

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 BusinessRules container and bind to a rule using a predefined PowerShell variable $Context.

$container = $Context.GetWellKnownContainerPath("BusinessRules")
$rulesPathObj = New-Object "Softerra.Adaxes.Adsi.AdsPath" $container
$rulePath = $rulesPathObj.CreateChildPath("CN=My Rule")
$rule = $Context.BindToObject($rulePath)

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

Examples

The following code sample disables a business rule and makes the rule apply to groups.

The following code sample clears the activity scope of a business rule located directly in the BusinessRules container.

The following code sample deletes all actions and conditions of a business rule located in the container named My Container.

See also

• Defining actions and conditions
• Defining the scope of activity
• Creating business rule containers
• Replacing actions and conditions of a business rule
• Deleting business rules

---