PSD1073 – MultiList

Fact

• PhenixID Identity Manager 5.2.2 or later.
• Some parameters have been added in later versions and not might be supported in the version you are using. Make sure to upgrade to latest version for all parameters.

Situation

Use the custom control se.nordicedge.controls.lists.MultiListControl to manage two different LDAP objects that are linked together. For example group membership  between a group object and a user object.
In Active Directory the relationship between a user and its manager (manager and directReports) is another example.

If you like to create the list based on LDAP objects instead and store the values as string, please read PSD1132.

If you like to create a list of values created by you, please read PSD1133.

Solution

Use the custom control se.nordicedge.controls.lists.MultiList

1. Open IM configurator and Tab Designer
2. Open or add a new form, for example a View Edit form/tab
3. Click button for “Create a Custom Control” and drag it to the workspace of the form.
4. Click “Options for Custom Control”
5. Paste se.nordicedge.controls.lists.MultiList to Class Name: and then click “Query Custom Control Class”
6. Configure the Custom Control (see parameters below) and add an attribute to the control where the values should be stored.
7. Save and test the control.

Below are the configurable parameters for the control.
(Some are explained a little more in detail.)

Side by side mode (true/false). Default is true.
The control has one grid for the search result and one for the current result. Set this option to true to show the grids side by side. Set this option to false to show the search result grid above the current result grid.

Search base (TOP for default BaseDN). Default is TOP.
The search base for the search result. Set to TOP to use the logged in user’s BaseDN.

Search attributes (e.g. cn,givenName)
The attributes to use in the search field.

Search scope (BASE/ONE/SUB). Default is SUB.
The search scope for the search field.

Optional search filter
An optional search filter that will be added to the search from the search field.

Run optional search filter on current state (true/false). Default is false.
Set to true if the optional search filter should also be applied to the value in the current state grid. Any values that are filtered will not be affected in the directory.

Search type (Contains/Equals/Starts). Default is Starts.
The search typ for the search field. If set to Starts a * will de added to the end of the entered value. If set to Contains a * will be added in both the beginning and the end of the entered value. If set to Equals, the entered value will be used as it is.

Search result attributes (attribute1|label1,attribute2|label2)
The attributes to show for the objects in the search result. To set a display name for the attribute in the grid column title, use the | character.

Current state attributes (attribute1|label1,attribute2|label2)
The attributes to show for the objects in the current state grid. To set a display name for the attribute in the grid column title, use the | character.

Read only mode (true/false). Default is false.
If the control only should be used to show the current state, set this option to true. The control will then consist of only the current state grid.

Update current attribute (true/false). Default is true.
Set to true if the attribute for the control should be updated with the values from the current state at saving. Set to false to not update the attribute.

A typical use for setting this option to false is when the attribute is set to ‘memberOf’ to use the control to handle group membership for at user in Active Directory. The attribute ‘memberOf’ should not be updated by the control, it is at backlink attribute that will be updated by the directory when the attribute ‘member’ is updated at the group object.

Backlink attribute. Leave blank to not update any backlink attribute.
The backlink attribute to update. If using the control on a user object this would be the member attribute in the group. If using a group object this would be the membership attribute at the user object. If no backlink attribute is used or if the directory handles the backlink attribute, leave this blank.

Show checkbox for Select All in current state (true/false). Default is true.
In the current state grid, a checkbox will be shown in the column title bar to select all rows in the grid. Set this to false to hide the checkbox.

Show object icons (true/false). Default is true.
Set this option to false to not show the column with object icons.
NOTE: If you run large searches, the result is 500 or more, removing the icon from the UI will increase the performance for the end user a lot.

Hoover attribute for search result. Use dn for distinguished name. Leave blank to disable.
A hoover text, containing the value from a given attribute, can be shown for each object in the search result.

Hoover attribute for current state. Use dn for distinguished name. Leave blank to disable.
A hoover text, containing the value from a given attribute, can be shown for each object in the current state grid.

Label -> Search result (Search result)
The label for the search result grid. Default is ‘Search result’.

Label -> Current state (Members)
The label for the current state grid. Default is ‘Members’.

Label -> Search result total (Total)
The label for the search result total number of hits. Default is ‘Total’.

Label -> Current state total (Total)
The label for the current state total members. Default is ‘Total’.

Label -> Search button (Search)
The text on the search button. Default is ‘Search’.

Label -> Add button (Add)
The text on the add button. Default is ‘Add’.

Label -> Remove button (Remove)
The text on the remove button. Default is ‘Remove’.

Max no of search results. Default is 50.
The maximum number of hits that will be shown in the search result.
If you put value 0 (zero) there will be no limit.

Jsp file to use. Default is /jsp/CustomControls/MultiListCC.jsp
The default jsp-file to use for this custom control is /jsp/CustomControls/MultiListCC.jsp but you may use another jsp-file of your choice. In this option the file path is the URL, starting at the IM web app directory.

Width (%) for search result at side by side mode. Default is 50.
By default, the grid for the search result and the grid for the current state have the same width at side by side mode. In this option you can change the width of the search result, in percent.

Escape * in search string (true/false). Default is false.
To prevent wildcard searches, set this option to true to escape any * entered in the search string.

Hide current members from search result (true/false). Default is false.
By default in the left pane, you will see all the objects that are matching the search, including those who are already members of the group. If you do not like to present the existing members in the search result, this is the parameter to use.

Trim search string (true/false). Default is false.
In searches where you might make copy and paste the query from another source and get the query with spaces, these spaces can be trimmed away.
For example you type: “Query with spaces” would become “Querywithspaces”

Initial, predisplay search query.
If you like to run an LDAP search to pre-populate available objects to add from you can use this parameter. This option will keep the search dialog box if the user like to run another search.

Hide visible search. Default is false.
This parameter will work with above parameter but hide the search dialog box from the user. The only objects available to show from are the objects from the search above.

Use multidb for LDAP access. Set to string MULTIDB_x, x=1..9 (MULTIDB_1). Default is empty
Note, this is only used if you are searching objects in another user store. Add as value the multidb you like to use.

Ignore backlink errors when saving (true/false). Default is false.

If an object has a broken backlink and you try to delete that object you will get an error. If you set this parameter to “true” then there will be no error and the object will be removed.

Collapse filter function
In the grid you can filter if you have a large result set. By default the filter function is expanded.

Prefix for ADD values (No prefix by default, only used with PIPFilter)
PIM can add a prefix infront of objects added and objects removed.
Instead of PIM sending for Group1 and Group2, PIM can now send for example ADD_Group1 and REM_Group2. This is to make it easier to figure out for an PIP admin what objects are added and what objects are removed.
This parameter was added to PIM 5.6.4

Prefix for REMOVE values (No prefix by default, only used with PIPFilter)
See parameter explanation above.

Development

If any customer specific functionality is desired, the MultiListControl can be extended. These are the methods that may be overloaded.

public String[] getCurrentObjectsAllowedToShow(String[] currentAttributeValue)
This method is used for filtering the objects that are shown in the current state grid. The input is the current value and the method should return the objects that are allowed to show. Any values that are filtered by this method will not be affected by this control.

public IMSearchResult getObjectsAllowedToShow(IMSearchResult searchResult)
This method is used for filtering the objects that are shown in the search result grid. The input is the result from the search and the method should return the search result containing the objects that are allowed to show. Any values that are filtered by this method will not be affected by this control.

public boolean getPreSaveVeto()
This method is used for making checks in presave. The dn for the objects that are about to be added to the attribute are found in the List addObjects. The dn for the objects that are about to be removed from the attribute are found in the List deleteObjects. This method should return DO_SAVE to make the saving continue or DO_NOT_SAVE if the saving should be aborted by a veto. If raising a veto, an error message should be set using the method setErrorMessage.

Protected IMSearchResult search(String searchFilter, String[] attributes) 

This method is used to find records to display on the left side (or top if configured for vertical display) and it receives two parameters. The first parameter, searchFilter, is a string that contains the search filter that the standard MultiListControl would use to find records at this stage and it comes from the configuration of the control. The other parameter, attributes, contains the attributes the control expects to get in return for each record.
The method should return an IMSearchResult object that contains any records that should be displayed. The result can be empty but should not be null.

Protected boolean displayExistingValue(String val, String optionalSearch)

This method is used to filter any existing value that is presented to the right in the UI (or in the bottom if using vertical display). This method has two arguments. First the records distinguished name and then the optional search filter that can be configured for the control.
It will run for each value and the component will only display a value if this method returns true.