Managing business units

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

Creating a business unit

The following code sample creates a business unit.

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 units container.
$containerPath = $service.Backend.GetConfigurationContainerPath("BusinessUnits")
$container = $service.OpenObject($containerPath, $null, $null, 0)

# Create a new business unit.
$unit = $container.Create("adm-BusinessUnit", "CN=My Unit")
$unit.Description = "My description"

$rules = $unit.GetMembershipRules()

# [TODO] define membership rules

# Save the business unit.
$unit.SetMembershipRules($rules)
$unit.SetInfo()
C#
using Softerra.Adaxes.Adsi;
using Softerra.Adaxes.Interop.Adsi;
using Softerra.Adaxes.Interop.Adsi.BusinessUnits;
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 Units' container
        string containerPath = service.Backend.GetConfigurationContainerPath("BusinessUnits");
        IADsContainer container = (IADsContainer)service.OpenObject(
            containerPath, null, null, 0);

        // Create a new business unit.
        IAdmBusinessUnit unit = (IAdmBusinessUnit)container.Create("adm-BusinessUnit", "CN=My Unit");
        unit.Description = "My description";

        IAdmBusinessUnitMembershipRules rules = unit.GetMembershipRules();

        // [TODO] define membership rules

        // Save the business unit.
        unit.SetMembershipRules(rules);
        unit.SetInfo();
    }
}

Details

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

# Bind to the business units container.
$containerPath = $Context.GetWellKnownContainerPath("BusinessUnits")
$container = $Context.BindToObject($containerPath)
 How to create a business unit in a different container

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

The following code sample creates a business unit 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 business units container.
$containerPath = $service.Backend.GetConfigurationContainerPath("BusinessUnits")

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

# Create a new business unit.
$unit = $myContainer.Create("adm-BusinessUnit", "CN=My Unit")
$unit.Description = "My description"

$rules = $unit.GetMembershipRules()

# [TODO] define membership rules

# Save the business unit.
$unit.SetMembershipRules($rules)
$unit.SetInfo()
C#
using Softerra.Adaxes.Adsi;
using Softerra.Adaxes.Interop.Adsi;
using Softerra.Adaxes.Interop.Adsi.BusinessUnits;
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 units container.
        string containerPath = service.Backend.GetConfigurationContainerPath("BusinessUnits");
        
        // Build the ADS path of the nested container 'My Container' and bind to it.
        AdsPath businessUnitsPath = new AdsPath(containerPath);
        AdsPath myContainerPath = businessUnitsPath.CreateChildPath("CN=My Container");
        IADsContainer myContainer = (IADsContainer)service.OpenObject(
            myContainerPath.ToString(), null, null, 0);

        // Create a new business unit.
        IAdmBusinessUnit unit = (IAdmBusinessUnit)myContainer.Create("adm-BusinessUnit", "CN=My Unit");
        unit.Description = "My description";

        IAdmBusinessUnitMembershipRules rules = unit.GetMembershipRules();
        
        // [TODO] define membership rules

        // Save the business unit.
        unit.SetMembershipRules(rules);
        unit.SetInfo();
    }
}

For information on how to create containers for business units, see Creating business unit 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-BusinessUnit" in our case. The second one is a relative distinguished name of the new unit.

The object returned by Create implements the IAdmBusinessUnit interface. You can use it to specify the business unit description by setting the Description property.

Column settings

By default, business unit members are displayed with a single column – Name, and are not sorted or grouped in any way. Adaxes users can configure personal column/grouping/sorting settings when they view a business unit, but you can also configure how members will be displayed for everyone by default.

To access the default column settings of a business unit, call IAdmBusinessUnit::GetColumnSettings. The object returned by GetColumnSettings implements the IAdmColumnSettings interface. Use its properties to configure the default columns, sorting, and grouping.

  • Columns – an array of directory object property names that designate the columns visible by default. Property names must be specified exactly as they are defined in your directory schema.

    Besides the standard directory object properties, you can specify the names of Adaxes virtual columns. The values of these columns are not stored anywhere and are calculated or derived on the go. For a full list of virtual columns, see Virtual columns.

  • EnableSorting – set to true to sort the business unit members by default. The SortBy property must also be specified for the sorting to take effect.

  • SortBy – the name of the directory object property to sort the business unit members by. This property is ignored if EnableSorting is set to false.

  • SortDescending – set to true to sort the business unit members in the descending order or set to false to sort them in the ascending order. This property is ignored if EnableSorting is set to false.

  • EnableGrouping – set to true to group the business unit members by default. The GroupBy property must also be specified for the grouping to take effect.

  • GroupBy – the name of the directory object property to group the business unit members by. This property is ignored if EnableGrouping is set to false.

    Besides the standard directory object properties, you can specify the name of an Adaxes virtual column. The values of these columns are not stored anywhere and are calculated or derived on the go. For a full list of virtual columns, see Virtual columns.

To apply the default column settings to a business unit, call IAdmBusinessUnit::SetColumnSettings and pass the object that represents the column settings as a parameter.

Finally, save the business unit by calling SetInfo.

Examples

 Example 1 – Set three default columns and sort members by name

The following code sample sets three default columns – Name, Department, Account Expires and sorts the business unit members by name in the ascending order.

PowerShell
# The $unit variable refers to a business unit.
$columnSettings = $unit.GetColumnSettings()

# Set default columns.
$columnSettings.Columns = @(
    "name",
    "department",
    "accountExpires"
)

# Sort by name.
$columnSettings.EnableSorting = $true
$columnSettings.SortBy = "name"
$columnSettings.SortDescending = $false

# Save the changes.
$unit.SetColumnSettings($columnSettings)
$unit.SetInfo()
C#
// The unit variable refers to a business unit
IAdmColumnSettings columnSettings = unit.GetColumnSettings();

// Set default columns.
columnSettings.Columns = new string[]
{
    "name",
    "department",
    "accountExpires"
};

// Sort by name.
columnSettings.EnableSorting = true;
columnSettings.SortBy = "name";
columnSettings.SortDescending = false;

// Save the changes.
unit.SetColumnSettings(columnSettings);
unit.SetInfo();
 Example 2 – Set two default columns and group members by object type

The following code sample sets two default columns – Name and Description, and groups the business unit members by object type.

PowerShell
# The $unit variable refers to a business unit.
$columnSettings = $unit.GetColumnSettings()

# Set default columns.
$columnSettings.Columns = @(
    "name",
    "description"
)

# Group by object type.
$columnSettings.EnableGrouping = $true
$columnSettings.GroupBy = "adm-VirtualColumnType" # Virtual column - Type

# Save the changes.
$unit.SetColumnSettings($columnSettings)
$unit.SetInfo()
C#
// The unit variable refers to a business unit
IAdmColumnSettings columnSettings = unit.GetColumnSettings();

// Set default columns.
columnSettings.Columns = new string[]
{
    "name",
    "description"
};

// Group by object type.
columnSettings.EnableGrouping = true;
columnSettings.GroupBy = "adm-VirtualColumnType"; // Virtual column - Type

// Save the changes.
unit.SetColumnSettings(columnSettings);
unit.SetInfo();

Defining membership rules

Membership in a business unit is determined using rules. To get the membership rules of a particular business unit, call IAdmBusinessUnit::GetMembershipRules. The object returned by GetMembershipRules is a collection of membership rules that implements the IAdmBusinessUnitMembershipRules interface.

To create a new membership rule, call IAdmBusinessUnitMembershipRules::Create and pass the desired membership rule type as a parameter. For a list of possible membership rule types, see ADM_BUSINESSUNITMEMBERSHIPTYPE_ENUM.

The object returned by Create will implement IAdmBusinessUnitMembershipRule and an additional interface specific to the rule type. Use the methods and properties of that interface to configure the rule.

To add your new rule to the collection, call IAdmBusinessUnitMembershipRules::Add and pass the rule object as a parameter. You can create and add more membership rules at this point.

To apply the rules to the business unit, call IAdmBusinessUnit::SetMembershipRules and pass the collection of rules as a parameter.

Finally, save the business unit by calling SetInfo.

Examples

 Example 1 – Include user John Smith and exclude user Bob Jones

The following code sample adds two membership rules to a business unit. The first rule includes the user named John Smith and the second rule excludes the user named Bob Jones.

PowerShell
# The $unit variable refers to a business unit.
$rules = $unit.GetMembershipRules()

# Include John Smith.
$jsmithDN = "CN=John Smith,CN=Users,DC=company,DC=com"
$jsmith = $service.OpenObject("Adaxes://$jsmithDN", $null, $null, 0)
$includeRule = $rules.Create("ADM_BUSINESSUNITMEMBERSHIPTYPE_SPECIFIC")
$includeRule.Exclude = $false
$includeRule.Object = $jsmith
$rules.Add($includeRule)

# Exclude Bob Jones.
$bjonesDN = "CN=Bob Jones,CN=Users,DC=company,DC=com"
$bjones = $service.OpenObject("Adaxes://$bjonesDN", $null, $null, 0)
$excludeRule = $rules.Create("ADM_BUSINESSUNITMEMBERSHIPTYPE_SPECIFIC")
$excludeRule.Exclude = $true
$excludeRule.Object = $bjones
$rules.Add($excludeRule)

# Save the changes.
$unit.SetMembershipRules($rules)
$unit.SetInfo()
C#
// The unit variable refers to a business unit
IAdmBusinessUnitMembershipRules rules = unit.GetMembershipRules();

// Include John Smith.
const string jsmithDN = "CN=John Smith,CN=Users,DC=company,DC=com";
IAdmTop jsmith = (IAdmTop)service.OpenObject($"Adaxes://{jsmithDN}", null, null, 0);

IAdmBusinessUnitSpecificObjectRule includeRule = (IAdmBusinessUnitSpecificObjectRule)rules.Create(
    ADM_BUSINESSUNITMEMBERSHIPTYPE_ENUM.ADM_BUSINESSUNITMEMBERSHIPTYPE_SPECIFIC);
includeRule.Exclude = false;
includeRule.Object = jsmith;
rules.Add(includeRule);

// Exclude Bob Jones.
const string bjonesDN = "CN=Bob Jones,CN=Users,DC=company,DC=com";
IAdmTop bjones = (IAdmTop)service.OpenObject($"Adaxes://{bjonesDN}", null, null, 0);

IAdmBusinessUnitSpecificObjectRule excludeRule = (IAdmBusinessUnitSpecificObjectRule)rules.Create(
    ADM_BUSINESSUNITMEMBERSHIPTYPE_ENUM.ADM_BUSINESSUNITMEMBERSHIPTYPE_SPECIFIC);
excludeRule.Exclude = true;
excludeRule.Object = bjones;
rules.Add(excludeRule);

// Save the changes.
unit.SetMembershipRules(rules);
unit.SetInfo();
 Example 2 – Include members of the group named My Group

The following code sample adds a membership rule that includes all members (direct members and members due to group nesting) of a group named My Group.

PowerShell
# The $unit variable refers to a business unit.
$rules = $unit.GetMembershipRules()

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

# Create the rule.
$rule = $rules.Create("ADM_BUSINESSUNITMEMBERSHIPTYPE_GROUP")
$rule.Exclude = $false
$rule.Group = $group
$rule.IncludeDirectMembersOnly = $false
$rules.Add($rule)

# Save the changes.
$unit.SetMembershipRules($rules)
$unit.SetInfo()
C#
// The unit variable refers to a business unit.
IAdmBusinessUnitMembershipRules rules = unit.GetMembershipRules();

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

// Create the rule.
IAdmBusinessUnitGroupRule rule = (IAdmBusinessUnitGroupRule)rules.Create(
    ADM_BUSINESSUNITMEMBERSHIPTYPE_ENUM.ADM_BUSINESSUNITMEMBERSHIPTYPE_GROUP);
rule.Exclude = false;
rule.Group = group;
rule.IncludeDirectMembersOnly = false;
rules.Add(rule);

// Save the changes.
unit.SetMembershipRules(rules);
unit.SetInfo();
 Example 3 – Include objects located in the organizational unit named My Unit

The following code sample adds a membership rule that includes all objects located directly in the organizational unit named My Unit.

PowerShell
# The $unit variable refers to a business unit.
$rules = $unit.GetMembershipRules()

# Bind to the OU.
$ouDN = "OU=My Unit,DC=company,DC=com"
$ou = $service.OpenObject("Adaxes://$ouDN", $null, $null, 0)

# Create the rule.
$rule = $rules.Create("ADM_BUSINESSUNITMEMBERSHIPTYPE_CONTAINER")
$rule.Exclude = $false
$rule.Container = $ou
$rule.Scope = "ADS_SCOPE_ONELEVEL"
$rules.Add($rule)

# Save the changes.
$unit.SetMembershipRules($rules)
$unit.SetInfo()
C#
// The unit variable refers to a business unit.
IAdmBusinessUnitMembershipRules rules = unit.GetMembershipRules();

// Bind to the OU.
const string ouDN = "OU=My Unit,DC=company,DC=com";
IADsContainer ou = (IADsContainer)service.OpenObject($"Adaxes://{ouDN}", null, null, 0);

// Create the rule.
IAdmBusinessUnitContainerRule rule = (IAdmBusinessUnitContainerRule)rules.Create(
    ADM_BUSINESSUNITMEMBERSHIPTYPE_ENUM.ADM_BUSINESSUNITMEMBERSHIPTYPE_CONTAINER);
rule.Exclude = false;
rule.Container = ou;
rule.Scope = ADS_SCOPEENUM.ADS_SCOPE_ONELEVEL;
rules.Add(rule);

// Save the changes.
unit.SetMembershipRules(rules);
unit.SetInfo();
 Example 4 – Include all users whose department is Sales

The following code sample adds a membership rule that includes all users whose department property is Sales.

PowerShell
# The $unit variable refers to a business unit.
$rules = $unit.GetMembershipRules()

# Create the rule.
$rule = $rules.Create("ADM_BUSINESSUNITMEMBERSHIPTYPE_QUERY")
$rule.Exclude = $false
$rule.BaseObjectPath = $null # search in all managed domains
$rule.Scope = "ADS_SCOPE_SUBTREE"

$criteria = New-AdmCriteria "user" {department -eq "Sales"}
$rule.SetCriteria($criteria)
$rules.Add($rule)

# Save the changes.
$unit.SetMembershipRules($rules)
$unit.SetInfo()
C#
// The unit variable refers to a business unit.
IAdmBusinessUnitMembershipRules rules = unit.GetMembershipRules();

// Create the rule.
IAdmBusinessUnitQueryRule rule = (IAdmBusinessUnitQueryRule)rules.Create(
    ADM_BUSINESSUNITMEMBERSHIPTYPE_ENUM.ADM_BUSINESSUNITMEMBERSHIPTYPE_QUERY);
rule.BaseObjectPath = null; // search in all managed domains
rule.Exclude = false;
rule.Scope = ADS_SCOPEENUM.ADS_SCOPE_SUBTREE;

Criteria criteria = new();
criteria.AddType("user", new SimpleCriteriaItem()
{
    Property = "department",
    Operator = "eq",
    Values = { "Sales" }
});
rule.SetCriteria(criteria);
rules.Add(rule);

// Save the changes.
unit.SetMembershipRules(rules);
unit.SetInfo();

Defining dynamic membership rules using templates

You can create dynamic business units that will include different members depending on who is viewing the business unit. A membership rule become dynamic when it includes value references. When a user views a dynamic business unit, Adaxes replaces value references in the rules with the property values of the viewer before generating the list of unit members.

Value references in business units are processed only when viewing business unit members and in security role assignments.

Examples

 Example 1 – Include the user's manager

The following code sample adds a dynamic membership rule that includes the manager of the user viewing the business unit.

PowerShell
# The $unit variable refers to a business unit.
$rules = $unit.GetMembershipRules()

# Create the rule.
$includeRule = $rules.Create("ADM_BUSINESSUNITMEMBERSHIPTYPE_SPECIFIC")
$includeRule.ObjectDnTemplate = "%manager%"
$includeRule.Exclude = $false
$rules.Add($includeRule)

# Save the changes.
$unit.SetMembershipRules($rules)
$unit.SetInfo()
C#
// The unit variable refers to a business unit.
IAdmBusinessUnitMembershipRules rules = unit.GetMembershipRules();

// Create the rule.
IAdmBusinessUnitSpecificObjectRule includeRule = (IAdmBusinessUnitSpecificObjectRule)rules.Create(
    ADM_BUSINESSUNITMEMBERSHIPTYPE_ENUM.ADM_BUSINESSUNITMEMBERSHIPTYPE_SPECIFIC);
includeRule.ObjectDnTemplate = "%manager%";
includeRule.Exclude = false;
rules.Add(includeRule);

// Save the changes.
unit.SetMembershipRules(rules);
unit.SetInfo();
 Example 2 – Include members of a group named Managers located in the same OU as the user

The following code sample adds a dynamic membership rule that includes direct members of a group named Managers located in the same OU as the user viewing the business unit.

PowerShell
# The $unit variable refers to a business unit
$rules = $unit.GetMembershipRules()

# Create the rule.
$rule = $rules.Create("ADM_BUSINESSUNITMEMBERSHIPTYPE_GROUP")
$rule.GroupDnTemplate = "CN=Managers,%adm-ParentDN%"
$rule.Exclude = $false
$rule.IncludeDirectMembersOnly = $true
$rules.Add($rule)

# Save the changes.
$unit.SetMembershipRules($rules)
$unit.SetInfo()
C#
// The unit variable refers to a business unit.
IAdmBusinessUnitMembershipRules rules = unit.GetMembershipRules();

// Create the rule.
IAdmBusinessUnitGroupRule rule = (IAdmBusinessUnitGroupRule)rules.Create(
    ADM_BUSINESSUNITMEMBERSHIPTYPE_ENUM.ADM_BUSINESSUNITMEMBERSHIPTYPE_GROUP);
rule.GroupDnTemplate = "CN=Managers,%adm-ParentDN%";
rule.Exclude = false;
rule.IncludeDirectMembersOnly = true;
rules.Add(rule);

// Save the changes.
unit.SetMembershipRules(rules);
unit.SetInfo();
 Example 3 – Include all groups managed by the user

The following code sample adds a dynamic membership rule that includes all groups managed by the user viewing the business unit.

PowerShell
# The $unit variable refers to a business unit.
$rules = $unit.GetMembershipRules()

# Create the rule.
$rule = $rules.Create("ADM_BUSINESSUNITMEMBERSHIPTYPE_QUERY")
$rule.Exclude = $false
$rule.BaseObjectPath = $null # search in all managed domains
$rule.Scope = "ADS_SCOPE_SUBTREE"

$criteria = New-AdmCriteria "group" {owners -eq "%distinguishedName%"}
$rule.SetCriteria($criteria)
$rules.Add($rule)

# Save the changes.
$unit.SetMembershipRules($rules)
$unit.SetInfo()
C#
// The unit variable refers to a business unit.
IAdmBusinessUnitMembershipRules rules = unit.GetMembershipRules();

// Create the rule.
IAdmBusinessUnitQueryRule rule = (IAdmBusinessUnitQueryRule)rules.Create(
    ADM_BUSINESSUNITMEMBERSHIPTYPE_ENUM.ADM_BUSINESSUNITMEMBERSHIPTYPE_QUERY);
rule.BaseObjectPath = null; // search in all managed domains
rule.Exclude = false;
rule.Scope = ADS_SCOPEENUM.ADS_SCOPE_SUBTREE;

Criteria criteria = new();
criteria.AddType("group", new SimpleCriteriaItem()
{
    Property = "adm-SearchAttrOwners",
    Operator = "eq",
    Values = { "%distinguishedName%" }
});
rule.SetCriteria(criteria);
rules.Add(rule);

// Save the changes.
unit.SetMembershipRules(rules);
unit.SetInfo();
 Example 4 – Include users from the same domain and the same department

The following code sample adds a dynamic membership rule that includes all users from the same domain and the same department as the user viewing the business unit.

PowerShell
# The $unit variable refers to a business unit.
$rules = $unit.GetMembershipRules()

# Create the rule.
$rule = $rules.Create("ADM_BUSINESSUNITMEMBERSHIPTYPE_QUERY")
$rule.BaseObjectDnTemplate = "%adm-DomainDN%" # from the same domain
$rule.Exclude = $false
$rule.Scope = "ADS_SCOPE_SUBTREE"

$criteria = New-AdmCriteria "user" {department -eq "%department%"} # from the same department
$rule.SetCriteria($criteria)
$rules.Add($rule)

# Save the changes.
$unit.SetMembershipRules($rules)
$unit.SetInfo()
C#
// The unit variable refers to a business unit.
IAdmBusinessUnitMembershipRules rules = unit.GetMembershipRules();

// Create the rule.
IAdmBusinessUnitQueryRule rule = (IAdmBusinessUnitQueryRule)rules.Create(
    ADM_BUSINESSUNITMEMBERSHIPTYPE_ENUM.ADM_BUSINESSUNITMEMBERSHIPTYPE_QUERY);
rule.BaseObjectDnTemplate = "%adm-DomainDN%"; // from the same domain
rule.Exclude = false;
rule.Scope = ADS_SCOPEENUM.ADS_SCOPE_SUBTREE;

Criteria criteria = new();
criteria.AddType("user", new SimpleCriteriaItem() // from the same department
{
    Property = "department",
    Operator = "eq",
    Values = { "%department%" }
}); 
rule.SetCriteria(criteria);
rules.Add(rule);

// Save the changes.
unit.SetMembershipRules(rules);
unit.SetInfo();

Modifying a business unit

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

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

$container = $Context.GetWellKnownContainerPath("BusinessUnits")
$unitsPathObj = New-Object "Softerra.Adaxes.Adsi.AdsPath" $container
$unitPath = $unitsPathObj.CreateChildPath("CN=My Pattern")
$unit = $Context.BindToObject($unitPath)

After binding to the unit, you can use the IAdmBusinessUnit and IADs interfaces to modify it. To save the changes, call SetInfo.

Example

The following code sample binds to an existing business unit located in a container named My Container and deletes all membership rules of that business unit.

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 unit.
$businessUnitsPath = $service.Backend.GetConfigurationContainerPath("BusinessUnits")
$unitsPathObj = New-Object "Softerra.Adaxes.Adsi.AdsPath" $businessUnitsPath
$containerPathObj = $unitsPathObj.CreateChildPath("CN=My Container")
$unitPath = $containerPathObj.CreateChildPath("CN=My Unit")
$unit = $service.OpenObject($unitPath.ToString(), $null, $null, 0)

# Delete membership rules.
$rules = $unit.GetMembershipRules()
$rules.Clear()
$unit.SetMembershipRules($rules)

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

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

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

        // Delete membership rules.
        IAdmBusinessUnitMembershipRules rules = unit.GetMembershipRules();
        rules.Clear();
        unit.SetMembershipRules(rules);

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

Getting business unit members

To access business unit members, you need to bind to the business unit and call IAdmBusinessUnit::Members. The object returned by Members is a collection that implements IAdmBusinessUnitMembers.

If the business unit is dynamic, you can view its members as any user in your environment. To do this, set the IAdmBusinessUnit::UserToResolveValueReferences property to a user object that should act as a viewer before calling IAdmBusinessUnit::Members. By default, dynamic business units are viewed as the user connected to the Adaxes service.

To quickly determine whether an object is a member of the business unit, call IAdmBusinessUnit::IsMember and pass that object as a parameter.

To access a specific member by index, call IAdmBusinessUnitMembers::GetObject and pass the index as a parameter. The object returned by GetObject will implement an interface specific to its object type. For example, user objects implement the IADsUser interface, group objects implement the IADsGroup interface, and so on. For more information, see Interfaces supported by directory objects.

Hardcoding member indexes in your scripts or applications and expecting them to always match the same objects is unreliable. Indexes can change every time the business unit membership is recalculated.

Example

The following code sample outputs information about users that are members of a business unit named My Unit from the point of view of the user named Albert Ricks.

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 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)

# Specify the user to view as.
$userDN = "CN=Albert Ricks,OU=London Office,DC=example,DC=com"
$user = $service.OpenObject("Adaxes://$userDN", $null, $null, 0)
$unit.UserToResolveValueReferences = $user

# Get business unit members.
$members = $unit.Members()
for ($i = 0; $i -lt $members.Count; $i++)
{
    $member = $members.GetObject($i)
    if (-not($member.Class -ieq "user"))
    {
        continue # output user accounts only
    }

    $name = $member.Get("name")
    $username = $member.Get("userPrincipalName")
    $dn = $member.Get("distinguishedName")

    $info = "
    Name: $name
    Username: $username
    DN: $dn"

    Write-Host $info
}
C#
using System;
using Softerra.Adaxes.Adsi;
using Softerra.Adaxes.Interop.Adsi;
using Softerra.Adaxes.Interop.Adsi.BusinessUnits;
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 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);

        // Specify the user to view as.
        const string userDN = "CN=Albert Ricks,OU=London Office,DC=example,DC=com";
        IAdmTop user = (IAdmTop)service.OpenObject($"Adaxes://{userDN}", null, null, 0);
        unit.UserToResolveValueReferences = user;

        // Get business unit members.
        IAdmBusinessUnitMembers members = unit.Members();
        for (int i = 0; i < members.Count; i++)
        {
            IADs member = members.GetObject(i);
            if (!StringComparer.OrdinalIgnoreCase.Equals(member.Class, "user"))
            {
                continue; // output user accounts only
            }

            string name = (string)member.Get("name");
            string username = (string)member.Get("userPrincipalName");
            string dn = (string)member.Get("distinguishedName");

            string info = string.Format(
                "Name: {0}\n" +
                "Username: {1}\n" +
                "DN: {2}\n",
                name, username, dn);
            Console.WriteLine(info);
        }
    }
}

See also

© Softerra 2022. All rights reserved.
Send feedback