Defining the scope of activity

This article describes how to define the activity scope of business rules, scheduled tasks, property patterns, and password self-service policies.

The following code sample adds all objects located directly in the organizational unit named Sales into the activity scope of a business rule.

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 rule.
$container = $service.Backend.GetConfigurationContainerPath("BusinessRules")
$rulesPathObj = New-Object "Softerra.Adaxes.Adsi.AdsPath" $container
$rulePath = $rulesPathObj.CreateChildPath("CN=My Rule")
$rule = $service.OpenObject($rulePath.ToString(), $null, $null, 0)

# Bind to the organizational unit.
$ouDN = "OU=Sales,DC=example,DC=com"
$ou = $service.OpenObject("Adaxes://$ouDN", $null, $null, 0)

# Create an activity scope item.
$scopeItem = $rule.ActivityScopeItems.Create()
$scopeItem.BaseObject = $ou
$scopeItem.Type = "ADM_SCOPEBASEOBJECTTYPE_CONTAINER"
$scopeItem.Inheritance = "ADS_SCOPE_ONELEVEL"
$scopeItem.Exclude = $false

# Save the item and add it to the activity scope.
$scopeItem.SetInfo()
$rule.ActivityScopeItems.Add($scopeItem)
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 rule.
        string container = service.Backend.GetConfigurationContainerPath("BusinessRules");
        AdsPath rulesPathObj = new AdsPath(container);
        AdsPath rulePath = rulesPathObj.CreateChildPath("CN=My Rule");
        IAdmBusinessRule rule = (IAdmBusinessRule)service.OpenObject(
            rulePath.ToString(), null, null, 0);

        // Bind to the organizational unit.
        const string ouDN = "OU=Sales,DC=example,DC=com";
        IAdmTop ou = (IAdmTop)service.OpenObject($"Adaxes://{ouDN}", null, null, 0);

        // Create an activity scope item.           
        IAdmActivityScopeItem scopeItem = (IAdmActivityScopeItem)rule.ActivityScopeItems.Create();
        scopeItem.BaseObject = ou;
        scopeItem.Type = ADM_SCOPEBASEOBJECTTYPE_ENUM.ADM_SCOPEBASEOBJECTTYPE_CONTAINER;
        scopeItem.Inheritance = ADS_SCOPEENUM.ADS_SCOPE_ONELEVEL;
        scopeItem.Exclude = false;

        // Save the item and add it to the activity scope.
        scopeItem.SetInfo();
        rule.ActivityScopeItems.Add(scopeItem);
    }
}

Details

To access the activity scope of a business rule, scheduled task, property pattern, or password self-service policy, first you need to bind to the corresponding rule, task, pattern, or policy.

After binding to the object, use the ActivityScopeItems property to view or modify the activity scope. Note that different configuration objects expose this property via different interfaces.

Configuration object Interface
Business rule, scheduled task IAdmBusinessRule
Property pattern IAdmPropertyPattern
Password self-service policy IAdmPasswordSelfServicePolicy

Activity scope is a collection of activity scope items. It implements the IAdmCollection interface. Each item in the collection either includes or excludes certain directory objects from the scope.

Call IAdmCollection::Create to create a new activity scope item. The item returned by Create will implement the IAdmActivityScopeItem interface whose properties you need to use to configure the item.

Item properties

  • Type – the scope item type. Determines whether the item will include a specific object, objects located in an organizational unit or container, members of a group, etc. For a list of activity scope item types, see ADM_SCOPEBASEOBJECTTYPE_ENUM.

  • Inheritance – depends on the scope item type. For example, if Type is set to ADM_SCOPEBASEOBJECTTYPE_GROUP, the value of Ineritance controls whether all group members or only direct members will be included to the activity scope. For a list of available inheritance types, see ADS_SCOPEENUM.

  • BaseObject – the base object of the scope. For example, if you want to include all objects located in a specific organizational unit, set that OU as the base object. If you want to include all members of a group, set that group as the base object.

  • Exclude – if set to true, objects included in this scope item will be excluded from the activity scope of the business rule, scheduled task, property pattern, or password self-service policy.

The following table contains all the possible property combinations for different activity scope items.

 Activity scope item property combinations

  • Activity scope

  • Type, Inheritance, and BaseObject

  • All objects

    • ADM_SCOPEBASEOBJECTTYPE_ALL_DIRECTORY
    • ADS_SCOPE_SUBTREE
    • null

  • All objects in a domain

  • All objects in an OU, including nested objects

    • ADM_SCOPEBASEOBJECTTYPE_CONTAINER
    • ADS_SCOPE_SUBTREE
    • An ADSI object representing the OU.

  • Objects located directly in an OU

    • ADM_SCOPEBASEOBJECTTYPE_CONTAINER
    • ADS_SCOPE_ONELEVEL
    • An ADSI object representing the OU.

  • All members of a group, including nested members

    • ADM_SCOPEBASEOBJECTTYPE_GROUP
    • ADS_SCOPE_SUBTREE
    • An ADSI object representing the group.

  • Direct members of a group

    • ADM_SCOPEBASEOBJECTTYPE_GROUP
    • ADS_SCOPE_ONELEVEL
    • An ADSI object representing the group.

  • Members of a business unit

  • Specific object

    • ADM_SCOPEBASEOBJECTTYPE_CONTAINER
    • ADS_SCOPE_BASE
    • An ADSI object.

  • Adaxes Configuration Objects

    • ADM_SCOPEBASEOBJECTTYPE_CONFIGURATION
    • ADS_SCOPE_SUBTREE
    • null

Once you have set the item properties, save it by calling SetInfo and add it to the collection of activity scope items using IAdmCollection::Add.

Examples

 Example 1 – Include all objects

The following code sample includes All objects into the activity scope.

PowerShell
# The $obj variable refers to a business rule, scheduled task,
# property pattern or password self-service policy.

# Create the activity scope item.
$scopeItem = $obj.ActivityScopeItems.Create()
$scopeItem.BaseObject = $null
$scopeItem.Type = "ADM_SCOPEBASEOBJECTTYPE_ALL_DIRECTORY"
$scopeItem.Inheritance = "ADS_SCOPE_SUBTREE"
$scopeItem.Exclude = $false

# Save the changes.
$scopeItem.SetInfo()
$obj.ActivityScopeItems.Add($scopeItem)
C#
// The $obj variable refers to a business rule, scheduled task,
// property pattern or password self-service policy.

Create the activity scope item
IAdmActivityScopeItem scopeItem = (IAdmActivityScopeItem)obj.ActivityScopeItems.Create();
scopeItem.BaseObject = null;
scopeItem.Type = ADM_SCOPEBASEOBJECTTYPE_ENUM.ADM_SCOPEBASEOBJECTTYPE_ALL_DIRECTORY;
scopeItem.Inheritance = ADS_SCOPEENUM.ADS_SCOPE_SUBTREE;
scopeItem.Exclude = false;

// Save the changes.
scopeItem.SetInfo();
obj.ActivityScopeItems.Add(scopeItem);
 Example 2 – Include a specific group object (not members of the group)

The following code sample includes the group named My Group into the activity scope. Members of the group are not included.

PowerShell
# The obj variable refers to a business rule, scheduled task,
# property pattern or password self-service policy.

# Bind to the group.
$groupDN = "CN=My Group,DC=example,DC=com"
$group = $service.OpenObject("Adaxes://$groupDN" ,$null, $null, 0)

# Create the activity scope item.
$scopeItem = $obj.ActivityScopeItems.Create()
$scopeItem.BaseObject = $group
$scopeItem.Type = "ADM_SCOPEBASEOBJECTTYPE_CONTAINER"
$scopeItem.Inheritance = "ADS_SCOPE_BASE"
$scopeItem.Exclude = $false

# Save the changes.
$scopeItem.SetInfo()
$obj.ActivityScopeItems.Add($scopeItem)
C#
// The obj variable refers to a business rule, scheduled task,
// property pattern or password self-service policy.

// Bind to the group.
const string groupDN = "CN=My Group,DC=example,DC=com";
IAdmTop group = (IAdmTop)service.OpenObject($"Adaxes://{groupDN}", null, null, 0);

// Create the activity scope item.
IAdmActivityScopeItem scopeItem = (IAdmActivityScopeItem)obj.ActivityScopeItems.Create();
scopeItem.BaseObject = group;
scopeItem.Type = ADM_SCOPEBASEOBJECTTYPE_ENUM.ADM_SCOPEBASEOBJECTTYPE_CONTAINER;
scopeItem.Inheritance = ADS_SCOPEENUM.ADS_SCOPE_BASE;
scopeItem.Exclude = false;

// Save the changes.
scopeItem.SetInfo();
obj.ActivityScopeItems.Add(scopeItem);
 Example 3 – Include members of a business unit

The following code sample includes all members of the business unit named My Unit into the activity scope.

PowerShell
# The obj variable refers to a business rule, scheduled task,
# property pattern or password self-service policy.

# Bind to the business unit.
$containerPath = $service.Backend.GetConfigurationContainerPath("BusinessUnits")
$pathObj = New-Object "Softerra.Adaxes.Adsi.AdsPath" $containerPath
$unitPath = $pathObj.CreateChildPath("CN=My Unit")
$unit = $service.OpenObject($unitPath.ToString(), $null, $null, 0)

# Create the activity scope item.
$scopeItem = $obj.ActivityScopeItems.Create()
$scopeItem.BaseObject = $unit
$scopeItem.Type = "ADM_SCOPEBASEOBJECTTYPE_BUSINESSUNIT"
$scopeItem.Inheritance = "ADS_SCOPE_SUBTREE"
$scopeItem.Exclude = $false

# Save the changes.
$scopeItem.SetInfo()
$obj.ActivityScopeItems.Add($scopeItem)
C#
// The obj variable refers to a business rule, scheduled task,
// property pattern or password self-service policy.

// Bind to the business unit.
string containerPath = service.Backend.GetConfigurationContainerPath("BusinessUnits");
AdsPath pathObj = new AdsPath(containerPath);
AdsPath unitPath = pathObj.CreateChildPath("CN=My Unit");
IAdmBusinessUnit unit = (IAdmBusinessUnit)service.OpenObject(unitPath.ToString(), null, null, 0);

// Create the activity scope item.
IAdmActivityScopeItem scopeItem = (IAdmActivityScopeItem)obj.ActivityScopeItems.Create();
scopeItem.BaseObject = unit;
scopeItem.Type = ADM_SCOPEBASEOBJECTTYPE_ENUM.ADM_SCOPEBASEOBJECTTYPE_BUSINESSUNIT;
scopeItem.Inheritance = ADS_SCOPEENUM.ADS_SCOPE_SUBTREE;
scopeItem.Exclude = false;

// Save the changes.
scopeItem.SetInfo();
obj.ActivityScopeItems.Add(scopeItem);
 Example 4 – Include all objects in a specific domain and exclude members of a group

The following code sample includes all objects located in the example.com domain and excludes all members of the IT Staff group from the activity scope.

PowerShell
# The obj variable refers to a business rule, scheduled task,
# property pattern or password self-service policy.

# Include all objects in the example.com domain.
# Bind to the domain.
$domain = "example.com"
$domain = $service.OpenObject("Adaxes://$domain", $null, $null, 0)

# Create the activity scope item.
$scopeItem = $obj.ActivityScopeItems.Create()
$scopeItem.BaseObject = $domain
$scopeItem.Type = "ADM_SCOPEBASEOBJECTTYPE_CONTAINER"
$scopeItem.Inheritance = "ADS_SCOPE_SUBTREE"
$scopeItem.Exclude = $false
$scopeItem.SetInfo()
$obj.ActivityScopeItems.Add($scopeItem)

# Exclude members of the IT Staff group.
# Bind to the group.
$groupDN = "CN=IT Staff,DC=example,DC=com"
$group = $service.OpenObject("Adaxes://$groupDN", $null, $null, 0)

# Create the activity scope item.
$scopeItem = $obj.ActivityScopeItems.Create()
$scopeItem.BaseObject = $group
$scopeItem.Type = "ADM_SCOPEBASEOBJECTTYPE_GROUP"
$scopeItem.Inheritance = "ADS_SCOPE_SUBTREE"
$scopeItem.Exclude = $true

# Save the changes.
$scopeItem.SetInfo()
$obj.ActivityScopeItems.Add($scopeItem)
C#
// The obj variable refers to a business rule, scheduled task,
// property pattern or password self-service policy.

// Include all objects in the example.com domain.
// Bind to the domain object
const string domain = "example.com";
IAdmTop domain = (IAdmTop)service.OpenObject($"Adaxes://{domain}", null, null, 0);
            
// Create the activity scope item.
IAdmActivityScopeItem scopeItem = (IAdmActivityScopeItem)obj.ActivityScopeItems.Create();
scopeItem.BaseObject = domain;
scopeItem.Type = ADM_SCOPEBASEOBJECTTYPE_ENUM.ADM_SCOPEBASEOBJECTTYPE_CONTAINER;
scopeItem.Inheritance = ADS_SCOPEENUM.ADS_SCOPE_SUBTREE;
scopeItem.Exclude = false;

// Save the changes.
scopeItem.SetInfo();
obj.ActivityScopeItems.Add(scopeItem);

// Exclude members of the IT Staff group.
// Bind to the group.
const string groupDN = "CN=IT Staff,DC=example,DC=com";
IAdmTop group = (IAdmTop)service.OpenObject($"Adaxes://{groupDN}", null, null, 0);

// Create the activity scope item.
scopeItem = (IAdmActivityScopeItem)obj.ActivityScopeItems.Create();
scopeItem.BaseObject = group;
scopeItem.Type = ADM_SCOPEBASEOBJECTTYPE_ENUM.ADM_SCOPEBASEOBJECTTYPE_GROUP;
scopeItem.Inheritance = ADS_SCOPEENUM.ADS_SCOPE_SUBTREE;
scopeItem.Exclude = true;

// Save the changes.
scopeItem.SetInfo();
obj.ActivityScopeItems.Add(scopeItem);

See also

© Softerra 2022. All rights reserved.
Send feedback