Skip to content

Active Directory Construct File

The construct.xml file allows you to set up rules when creating users, computers, and groups in Active Directory.

Users and computers use the construct.xml file located in:

  • C:\Program Files\Zipper\ZervicePoint\Provider extensions\Active Directory\Activities\Activity.ActiveDirectory\constructs.xml
  • C:\Program Files\Zipper\ZervicePoint\Provider extensions\Active Directory\Activities\Activity.ActiveDirectory\blacklist.txt

Groups use version 2.0 of the construct file and is located here:

  • C:\Program Files\Zipper\ZervicePoint\Provider extensions\Active Directory\Shared modules\ActiveDirectory\constructs.xml
  • C:\Program Files\Zipper\ZervicePoint\Provider extensions\Active Directory\Shared modules\ActiveDirectory\blacklist.txt

Example Users and Computers

The construct rules for users control how SamaccountName, Name, and DisplayName are generated. For computers, the rules define how Name and DisplayName are generated. You can change the rules to match your organizations naming conventions. It is also possible to add additional attributes such as Department.

<?xml version="1.0" encoding="utf-8"?>
<constructs>
    <activity name="New-ZPADUser" constructname="default">
        <construct name="SamaccountName" blacklistpath="blacklist.txt">
            <configuration>
                <add key="rule" value="if ($givenName.Length -ge 3 -and $surName.Length -ge 3) { [string]$givenName.Substring(0,3).ToLower() + [string]$surName.Substring(0,3).ToLower() }" />
                <add key="rule" value="if ($givenName.Length -ge 4 -and $surName.Length -ge 2) { [string]$givenName.Substring(0,4).ToLower() + [string]$surName.Substring(0,2).ToLower() }" />
                <add key="rule" value="if ($givenName.Length -ge 2 -and $surName.Length -ge 4) { [string]$givenName.Substring(0,2).ToLower() + [string]$surName.Substring(0,4).ToLower() }" />
                <add key="rule" value="if ($givenName.Length -ge 5 -and $surName.Length -ge 1) { [string]$givenName.Substring(0,5).ToLower() + [string]$surName.Substring(0,1).ToLower() }" />
                <add key="rule" value="foreach($i in 1..10000) { 'F25{0:D3}' -f $i }" />
            </configuration>
        </construct>
        <construct name="Name">
            <configuration>
                <add key="rule" value="[string]$givenName + ' ' + [string]$surName" />
                <add key="rule" value="[string]$givenName + ' ' + [string]$surName + ' ' + [string]$samaccountName" />
            </configuration>
        </construct>
        <construct name="DisplayName">
            <configuration>
                <add key="rule" value="[string]$givenName + ' ' + [string]$surName" />
            </configuration>
        </construct>
    </activity>
    <activity name="New-ZPADComputer" constructname="default">
        <construct name="Name">
            <configuration>
                <add key="rule" value="foreach($i in 1..10000) { 'D{0:D3}' -f $i }" />
            </configuration>
        </construct>
        <construct name="DisplayName">
            <configuration>
                <add key="rule" value="[string]$Name" />
            </configuration>
        </construct>
    </activity>
</constructs>

Elements

SamaccountName

The SamaccountName configuration generates a samaccountname based on the rules defined on the configuration. If the first rule fails, the second rule is applied instead and if the second rule fails the next one is applied. The configuration contains the following rules:

  • First 3 characters in the users GivenName + First 3 characters in the users SurName.
  • First 4 characters in the users GivenName + First 2 characters in the users SurName.
  • First 2 characters in the users GivenName + First 4 characters in the users SurName.
  • First 5 characters in the users GivenName + First 1 characters in the users SurName.
  • F25XXX (Where XXX is replaced with a number between 1 and 10000)

Name

User

The Name configuration sets the users CN name. If the first rule fails, the second rule is applied. The configuration contains the following rules:

  • GivenName SurName
  • GivenName SurName SamaccountName
Computer

The Name configuration sets the computers CN name.

  • DXXX (Where XXX is replaced with a number between 1 and 10000)

DisplayName

User

The DisplayName configuration for users contains the following rule:

  • GivenName SurName
Computer

The DisplayName configuration for computers contains the following rule:

  • Name (meaning it will be identical to the computers CN name)

Adding additional attributes

You can add additional constructs for common attributes such as Department. The example below demonstrates how to set the department to My Department.

<construct name="Department">
    <configuration>
        <add key="rule" value="'My Department'" />
    </configuration>
</construct>

Example Groups

Groups use an updated version (2.0) of the constructs concept and is located here:

  • C:\Program Files\Zipper\ZervicePoint\Provider extensions\Active Directory\Shared modules\ActiveDirectory\constructs.xml
  • C:\Program Files\Zipper\ZervicePoint\Provider extensions\Active Directory\Shared modules\ActiveDirectory\blacklist.txt

The example below shows the construct rules for two different constructnames:

  • default (which is fallback if none is specified)
  • distributiongroup

The 'default' constructname will generate the name based on displayNamePrintable and a three letter location, if that name already exists in active directory it will instead generate samaccountname and name based on the value of displayNamePrintable and location and add a sequence number.

<?xml version="1.0" encoding="utf-8"?>
<constructs>
  <activity function="New-ZPADGroup" constructname="default">
    <configuration>
      <path value="OU=Groups,OU=Test,DC=DEV,DC=LOCAL" />
    </configuration>
    <construct attribute="name" unique="true">
      <rule>('grp-{0}-{1}' -f ($Parameters.location).substring(0,3),$(Convertto-PFFriendlyCharacter -string $Parameters.displayNamePrintable)).tolower()</rule>
      <rule>foreach ($i in 1..100) { ('grp-{0}-{1}-{2}' -f ($Parameters.location).substring(0,3),$(Convertto-PFFriendlyCharacter -string $Parameters.displayNamePrintable),$i.tolower() }</rule>
    </construct>
  </activity>
  <activity function="New-ZPADGroup" constructname="distributiongroup">
    <configuration>
      <path value="OU=Groups,OU=Test,DC=DEV,DC=LOCAL" />
    </configuration>
    <construct attribute="name" unique="true">
      <rule>('dl-{0}-{1}' -f ($Parameters.location).substring(0,3),$(Convertto-PFFriendlyCharacter -string $Parameters.displayNamePrintable)).tolower()</rule>
      <rule>foreach ($i in 1..100) { ('dl-{0}-{1}-{2}' -f ($Parameters.location).substring(0,3),$(Convertto-PFFriendlyCharacter -string $Parameters.displayNamePrintable),$i).tolower() }</rule>
    </construct>
    <construct attribute="mail" unique="true">
      <rule>('dl-{0}-{1}@example.com' -f ($Parameters.location).substring(0,3),$(Convertto-PFFriendlyCharacter -string $Parameters.displayNamePrintable)).tolower()"</rule>
      <rule>foreach ($i in 1..100) { ('dl-{0}-{1}-{2}@example.com' -f ($Parameters.location).substring(0,3),$(Convertto-PFFriendlyCharacter -string $Parameters.displayNamePrintable),$i).tolower() }</rule>
    </construct>
  </activity>
</constructs>

Examples PowerShell

The first example demonstrates how to use the 'default' construct name.

  New-ZPADGroup `
      -Config $config `
      -Description "A Test Group" `
      -DisplayName "Test Group" `
      -GroupCategory Security `
      -GroupScope Global `
      -HomePage www.testgroup.local `
      -Parameters @{displayNamePrintable="Cotonso";location="Florida"} `
      -ConstructName default

The second example demonstrates how to use the 'distributiongroup' construct name.

  New-ZPADGroup `
      -Config $config `
      -Description "A Test Group" `
      -DisplayName "Test Group" `
      -GroupCategory Distribution `
      -GroupScope Univeral `
      -HomePage www.testgroup.local `
      -Parameters @{displayNamePrintable="Contoso";location="Florida"} `
      -ConstructName distributiongroup

Function and Construct Name (activity attributes)

Function currently supports New-ZPADGroup, but in the future it may be usable on additional functions. Constructname could be any string, but should preferably describe usage. (For example distributionlist, software)

<activity function="New-ZPADGroup" constructname="distributiongroup">

Configuration (activity child element)

Configuration only supports path. The path is overwritten if the path is supplied as an input parameter to the PowerShell command (activity).

<configuration>
    <path value="OU=Groups,OU=Test,DC=DEV,DC=LOCAL" />
</configuration>

Construct (activity child element)

Construct consist of three attributes (attribute, unique and blacklistpath) and one child element (rule)

<construct attribute="name" unique="true" blacklistpath="blacklist.txt">
  • attribute - Specifies the attribute to construct, such as: Name, SamaccountName.
  • unique - Specifies whether or not to check if the attribute needs to be domain-unique. It is also possible to specify "ou" which will only verify the attribute does not exist in specified PATH. Possible values: true, or ou.
  • blacklistpath - Path to the blacklist file. possible values: blacklist.txt, or C:\Path\blacklist.txt

Blacklist

The blacklist file prevents certain words and combination of words from being generated. It is possible to add this key to every attribute. The blacklist file can be placed in the module directory or on a specific location where the backend account has read access. Use one blacklist-word per line. Wildcards are supported.

Example blacklisting words

*inappropriate*
obscene*