Managing business rules

This article describes how to manage business rules 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 business rule

To create a business rule, 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 business rule, you need to call the Create method of the interface and pass "adm-BusinessRule" as the first parameter of the method, and the relative distinguished name (RDN) of the rule as the second parameter. The object returned by the IADsContainer::Create method will support the IAdmBusinessRule interface, using which you can specify the parameters of the new business rule.

1. Use the IAdmBusinessRule::ExecutionMoment property to specify whether the business rule will be executed before or after an event. The ADM_BUSINESSRULEEXECMOMENT_ENUM enumeration defines the values you can use when setting this property.

2. Use the IAdmBusinessRule::ObjectType property to specify the type of directory objects, to which the business rule will be applied. The property must be set to a string that contains the name of an object class as defined in the directory schema (e.g. user, group, computer, organizationalUnit).
   Using the IAdmBusinessRule::AdditionalObjectType property, you can specify an additional type of objects to which the business rule will be applied.

3. Use the IAdmBusinessRule::OperationType property to indicate the operation that will trigger execution of the business rule. The following table contains possible values for the OperationType property.

   OperationType	Operation
   "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
   "copy move"	Copying or moving an object
   "copy"	Copying an object
   "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
   "exchange task"	Performing an Exchange-related operation
   "mailbox-enable"	Creating an Exchange mailbox for a user
   "create move mailbox request"	Moving the Exchange mailbox of a user
   "export mailbox"	Exporting the Exchange mailbox of a user
   "mailbox-disable"	Deleting the Exchange mailbox of a user
   "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
   "archive home directory"	Archiving the user's home directory
   "restore deleted object"	Restoring a deleted object
   "self-schedule report"	Self-scheduling a report
   "self-unschedule report"	Self-unscheduling a report
   "generate report start"	Starting report generation
   "generate report finish"	Finishing report generation
   "create report document"	Creating a report document
   "deliver report document"	Delivering a report document
   "build report overview start"	Start building a report overview
   "build report overview finish"	Finish building a report overview
   "cancel meetings"	Cancelling calendar meetings
   "sign in"	Sign in
   "sign in to webui"	Sign in to Web interface
   "unlock account"	Unlock user account

To save the new business rule, you need to call IADs::SetInfo.

The following code sample creates a business rule to be triggered after creation of user accounts.

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 'business rules' container and bind to the container. The type of the $Context variable is ExecuteScriptContext.

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

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

# Triggering Operation: Before updating a group
$rule.ExecutionMoment = "ADM_BUSINESSRULEEXECMOMENT_BEFORE"
$rule.ObjectType = "group"
$rule.OperationType = "set properties"

$rule.Description = "My description"
$rule.Disabled = $false

# Save the business rule
$rule.SetInfo()

 How to create a business rule in a specific container

The following code sample creates a business rule in the container called 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
$businessRulesPath = $service.Backend.GetConfigurationContainerPath(
"BusinessRules")
# Build the ADS path of the child container 'My Container'
$businessRulesPathObj = New-Object "Softerra.Adaxes.Adsi.AdsPath"`
$businessRulesPath
$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 System;
using Interop.Adsi;
using Interop.Adsi.BusinessRules;
using Softerra.Adaxes.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 'business rules' container
    string businessRulesPath = service.Backend.GetConfigurationContainerPath(
        "BusinessRules");
    // Build the ADS path of the child container 'My Container'
    AdsPath businessRulesPathObj = new AdsPath(businessRulesPath);
    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();
}
}

On how to create containers for business rules, see Creating business rule containers.

Defining actions and conditions

To define business rule actions and conditions, 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 that determine what should happen when a business rule is triggered.

For information on how to manage business rule actions and conditions, see Defining actions and conditions.

Defining the scope of activity

The activity scope of a business rule determines the objects affected by the business rule. A business rule is executed only if the triggering operation is performed on an object that is included in the scope of activity of the business rule. Activity scope can include whole domains, members of groups and business units, objects located in specific Organizational Units, etc.

To define the scope of activity of a business rule, you need to use the ActivityScopeItems property of the IAdmBusinessRule interface.

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

After you've bound to a business rule object, you can use ADSI interfaces like IAdmBusinessRule and IADs to modify the business rule. To save the changes, you need to call IADs::SetInfo.

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

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 'business rules' container and bind to the business rule.

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

$rule.ObjectType = "inetOrgPerson"
$rule.Disabled = $true

# Save the changes
$rule.SetInfo()

The following code sample clears the activity scope and deletes all actions and conditions from 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

---