ARS Bound List Boxes

18/08/14 5:54 PM

ARS Bound List Boxes

                Bound list boxes in the ARS web interface have always been a challenge.  There are ARS Add-Ons available to facilitate bound list boxes within the ARS Web Interface up and including ARS 6.8.  Did you know that bound list box functionality is now included with ARS 6.9?  This has always been a sought after feature within ARS, and now that it is built into the product, we will go over how to utilize bound list boxes, but first, what are bound list boxes?

Bound list boxes are essentially multiple drop down list boxes on a web interface that are dependent.  What this means is, list box one contains a list of items, list box two is bound to list box one.  Whenever a selection is made from list box one has been selected, the available choices in list box two changes based upon the selection in list box one.

Now for the example.  A global organization has sites in multiple cities, but not all departments are in all cities. We have a web interface form that we want to allow the admin to select a city, and the selection of the city changes the available departments.

There are multiple parts to this solution to make the bound list box perform what we want it to do.

We need to have the list of cities and the departments that fall into each city.  For this example, we will use the following:

New York

Human Resources

Finance

Help Desk

London

Human Resources

Help Desk

Network Support

Tokyo

Human Resources

Research & Development

Instructional Development

Beijing

Human Resources

Manufacturing

Software Development

 

All of these items have to be stored somewhere, so the cities will be stored in a property and validation rule within an administration template.  That brings us to the second item needed, an Administration Template.  This template will be linked to all OUs that require use of the bound list box.  The template will contain the aforementioned property and validation rule and a script module that contains the code that allows the list box to function.

The script module required will be utilizing the function onGetEffectivePolicy.  This function allows us to inject code at page load time and affect how the page reacts to selections and we can even inject custom error messages/responses.

Building the solution:

First, let’s create the administration policy.

  1. Connect to the ARS MMC with a user that has permissions to create Administration Policies and Script Modules
  2. Expand Configuration->Policies->Administration
  3. Right click on the container you want to create your new policy within, move down to New, and click Provisioning Policy
  4. Enter a name for the Policy and click Next, in this example I named my policy Bound List Box.
  5. Select Property Generation and Validation, click Next
  6. Click Select and locate City (l) and click ok to select this attribute. Click Next
  7. Check City must be specified and City must be <value> (generates Default Value)
  8. In the bottom pane, click on <click to add value>
  9. Enter the first city name and click OK
  10. Click <click to add value> and add each of the other city names
  11. Click Next
  12. Click Next to accept the policy name
  13. Click Add and enter an OU to attach this policy to.
  14. Click Next
  15. Click Finish

Let test this policy to ensure we will see these cities.

  1. Connect to the ARS Admin Web Interface.
  2. Navigate to the OU in which you attached the Admin Policy
  3. Click on one of the users located in that OU to view its properties
  4. Click on the Address Tab
  5. The City field should be a drop down with the city names we just entered into the Admin Policy

1

Now that we have the drop down for the City created and working, let’s work on the Script Module that will connect the data in the Department field to what is selected in the City field.

First let’s create a script module

  1. in the ARS MMC, expand Configuration->Script Modules
  2. Right click on a container where the module will be created, move to new, and click Script Module
  3. Name the Script Module, I named this BLB – CityDepartment for the example
  4. Leave the language PowerShell
  5. Click Next
  6. Select Policy Script and Click Next
  7. Check onGetEffectivePolicy and click Next
  8. Click Finish

Now that the module has been created, let’s break down the code needed for this module:

$listNYC = @(‘Human Resources’,’Finance’,’Help Desk’)$listLON = @(‘Human Resources’,’Help Desk’,’Network Support’)

$listTOK = @(‘Human Resources’,’Research & Development’,’Instructional Development’)

$listBEJ = @(‘Human Resources’,’Manufacturing’,’Software Development’)

$listDefault = @(‘Select a City’,’to change this dropdown’)

 

This first section builds each list that the Department drop down will display when the city has been selected.  Each variable is named for the city and contains an array of the departments assigned to that city.

NOTE:  The $listDefault is required, if a default set of values are not defined for the drop down, the web form field will not appear as a drop down and will not cycle when the city is selected.

function onGetEffectivePolicy($Request){

if($Request.Class -eq “user”)

{

 

The next code snipped creates the function for onGetEffectivePolicy and then verifies that the class of object that exists in the request is user.  Any other classes will not execute any code in the script other than verifying the class.

         $Request.SetEffectivePolicyInfo(‘department’, $Constants.EDS_EPI_UI_RELOAD_EPI_BY_RULE, ‘l’)

 

This next line tells the page to reload the ‘department’ field when the City field (‘l’ attribute) is changed.

       $UserCity = GetCurrentValue -Request $Request -AttributeName ‘l’

 

Now, we must get the current value of the City drop down.  This line calls the function GetCurrentValue.

function GetCurrentValue($Request, [string]$AttributeName){

trap {continue}

$value = $Request.Get($AttributeName)

if($value -eq $null)

{

$DirObj.GetInfoEx(@($AttributeName),0) | Out-Null

$value = $DirObj.Get($AttributeName)

}

$value

}

 

The function get current value is used to acquire the current value of the department attribute from the request.  If the request does not contain a value for the department attribute, it attempts to get the value from the actual directory object.

       switch($UserCity){

‘New York’          {$possibleValues = $listNYC}

‘London’                        {$possibleValues = $listLON}

‘Tokyo’              {$possibleValues = $listTOK}

‘Bejing’              {$possibleValues = $listBEJ}

default              {$possibleValues = $listDefault}

}

 

 

This section uses the value attained from the request to switch the values for the $possibleValues attribute.  This variable becomes populated with the city specific department data depending on the city found during the GetCurrentValue function execution.

         $Request.SetEffectivePolicyInfo(‘department’, $Constants.EDS_EPI_UI_POSSIBLE_VALUES, [string[]]$possibleValues)}

}

Lastly, this line places the $possibleValues variable into the department field in the Web Interface form.  Since this is a multi-valued array, the department field on the form is represented as a drop down list in the Web Interface.

Putting it all together, the entire script module appears as follows:

$listNYC = @(‘Human Resources’,’Finance’,’Help Desk’)$listLON = @(‘Human Resources’,’Help Desk’,’Network Support’)

$listTOK = @(‘Human Resources’,’Research & Development’,’Instructional Development’)

$listBEJ = @(‘Human Resources’,’Manufacturing’,’Software Development’)

$listDefault = @(‘Select a City’,’to change this dropdown’)

 

function onGetEffectivePolicy($Request)

{

if($Request.Class -eq “user”)

{

$Request.SetEffectivePolicyInfo(‘department’, $Constants.EDS_EPI_UI_RELOAD_EPI_BY_RULE, ‘l’)

$UserCity = GetCurrentValue -Request $Request -AttributeName ‘l’

switch($UserCity)

{

‘New York’   {$possibleValues = $listNYC}

‘London’     {$possibleValues = $listLON}

‘Tokyo’       {$possibleValues = $listTOK}

‘Bejing’     {$possibleValues = $listBEJ}

default       {$possibleValues = $listDefault}

}

$Request.SetEffectivePolicyInfo(‘department’, $Constants.EDS_EPI_UI_POSSIBLE_VALUES, [string[]]$possibleValues)

}

}

 

function GetCurrentValue($Request, [string]$AttributeName)

{

trap {continue}

$value = $Request.Get($AttributeName)

if($value -eq $null)

{

$DirObj.GetInfoEx(@($AttributeName),0) | Out-Null

$value = $DirObj.Get($AttributeName)

}

$value

}

 

Now, we need to add the script module to the Admin Policy so that this script takes effect when the form has been loaded.

  1. In the MMC, expand Configuration->Policies->Administrative
  2. Double click or Right click and select properties on the Admin Policy that was created earlier in this example.
  3. Click on the policies tab, and click Add
  4. Click next
  5. Select Script Execution and click Next
  6. Select the script module created in the previous steps and click Next
  7. Click Next
  8. Click Finish
  9. Click Ok to exit the Admin Policy dialog

Lastly, we either need to create a web form or modify an existing form.  For this example, we will modify the existing user create form.

  1. Login to the Admin portal as an ARS Admin user, http://<server>/ARServerAdmin
  2. Click on Directory Management
  3. Click on the domain the managed OU exists within
  4. Navigate and click on the OU the Admin Policy was applied to
  5. Select New User from the drop down menu at the top of the page
  6. Click on Customize this form and the bottom right of the page
  7. Hover over Add Entry, and click on Select
  8. Check City and Department and click save
  9. Click save
  10. Click Reload
  11. Click Exit

Now, all we have to do is test the web form.

After clicking exit from the previous steps, the Web Interface should return to the New User form and as you can see, New York is selected as the default for City and if the drop down for department is clicked, Human Resources, Finance, and Help Desk are present.

2

Selecting Tokyo from the list, Human Resources, Research & Development, and Instructional Development appear in the Department list.

3

When Beijing is selected, the departments Human Resources, Manufacturing, and Software Development are viable departments for that city.

4

Lastly, Selecting London from the list shows Human Resources, Help Desk, and Network Support as selectable options.

5

Now, we can see that the drop down works as expected, the creation of a new account is needed to see that the values are set.  I used the new user form to create a new user completely and once created, I opened up the properties of that user to verify the values that were set.

Selecting the Address Tab shows Tokyo for the City.

6

And clicking on the Organization Tab shows Research & Development assigned as the users Department

7

There are many other uses for Bound List Boxes, just use the fundamentals from this article to apply this functionality to your scenarios.

 

Author: Russ Burden, Technical Architect, LeadThem Consulting

Posted by LeadThem Consulting | in ARS | Comments Off on ARS Bound List Boxes

Comments are closed.

logos

LeadThem Consulting
20418 SE Hwy 212
Damascus, OR 97089