Customizing Parameters

The topics in this section describe how to:

  • Create a new proposal list

  • Add new permission parameters

  • Add new role parameters

  • Create dependent proposal lists

Creating a New Proposal List

To create a new proposal list:

  • In the Domain Configuration view, use DirX Identity Manager to create a new proposal list entry in the Domain → Customer Extensions → Proposal Lists folder.

  • You can fill the proposal list in two ways: Define the values as a simple list or search for the list entries in the directory.

  • Select String as Type and enter the possible values in the Item List tab of the new proposal list.

  • Select DN as Type if you intend to search for the entries, and then define the search parameters.You can add more list items if you enter values into the list.

  • You can choose between two formats:
    storedValue
    storedValue;Description

    The storedValue part is the value that is stored at an object when you select it from the list.If you add the Description part, then this description is displayed, but the stored value is stored in the directory.This makes your proposal lists more readable and allows adding comments for users.

    If you selected DN as Type, you must specify the Display and Storage attributes of which the list shall be composed.

    Example:
    DE - in this case 'DE' is displayed at the user interface and stored in the directory.
    DE;Germany - in this case 'Germany' is displayed at the user interface but 'DE' is stored in the directory.

  • If the list is mastered in another database, consider defining a DirX Identity batch workflow that feeds the list regularly into the dxrProposedValues attribute of the proposal list entry.

  • Enter the reference to this list in the object descriptions of all objects where you need it.Use the XML element "tagprovider" with XML attribute "dn=…​".

If the proposal list is only valid for one target system, you can choose to place it in the target system subtree’s Proposal Lists folder.

Adding a New Permission Parameter

To make a user attribute a permission parameter:

  • In the Domain Configuration view, use DirX Identity Manager to add the user attribute to the list of user attributes that can be used as permission parameters.If the attribute is not in the list, extend your user.xml object description accordingly (Provisioning → Domain Configuration → Customer Extensions → user.xml).

  • Define the matching rules that use the permission parameter in the permission objects.

  • Check that the new permission parameter attribute is visible in the DirX Identity user object.

  • Ensure that the permission parameter values are set for the users (fill in default or specific values).

  • Extend the object description of target system groups to contain the new permission parameter: specify the new permission parameter as a new specific attribute "dxrRPValues(<property name>)", where the property name is exactly the same as for the user object.
    Note: Place these definitions into the group.xml files of the individual target systems of your domain ("Target Systems → targetSystem → Configuration → Object Descriptions").Otherwise the next upgrade or update overwrites this definition.
    Note: You can define a single value attribute at the user object and a multi-value attribute at the group object.If the group object definition is missing, the user object definition is inherited automatically.

  • Extend the property page description of the target system groups to display the new permission parameter.

  • Supply permission parameter values in the target system groups.

The definition and use of permission parameter attributes in the user.xml and group.xml files must be consistent in your application.If not, incorrect display in the DirX Identity Manager, non-functional login into the DirX Identity Web Center or incomplete privilege resolution could be the result.

Adding a New Role Parameter

Role parameters allow you to define generic roles that become specific on assignment to a user.For example, the My-Company sample domain defines a generic role Project Member (in DirX Identity Manager’s Provisioning view, see Privileges → Roles → Corporate Roles → Project Specific → Project Member).This role is linked to the Project role parameter (see the Role Parameters tab in the Project role, and then see Domain Configuration → Customer Extensions → My-Company → Role Parameters → Project) which controls the specific project that a particular user is to become a member of when the Project Member role is assigned to him.The user assigning the role selects or supplies the right value for the role parameter; in this case, the project name (MoreCustomers, HighPerformance, and OptimizeIT).

There are five ways to define a role parameter (which are controlled by the Type: field in the role parameter definition):

  • As strings,either using specified values, using a proposal list, or using both.You can specify string values such as "Project A" or "Project B" - these values become selections in a drop-down list at the Web Center interface on user-role assignment.Alternatively, you can use a proposal list for the selections that will be displayed.For example, the Project role specifies a Projects proposal list (see Domain Configuration → Customer Extensions → My-Company → Proposal Lists → Projects).The items in this list (see the Item List tab) will be displayed for selection on user-role assignment.You can also combine both proposal list and specific values within the same role parameter.

  • As text that is to be entered at the Web Center interface; for example, to resolve a parking space assignment in a company lot - the user enters his auto identification number (license plate number) and this value is a role parameter that is added to the role assignment.

  • As integer parameters (either within a range or with specific values, like 0 or 1)

  • As a distinguished name (DN).If this definition is selected, a simple ordered list is presented for selection.

  • As a hierarchical list of DNs; for example, the Cost Locations role parameter (see Domain Configuration → Customer Extensions → My-Company → Role Parameters → Cost Locations) specifies a tree of cost locations that is presented for selection when the Cost Location Manager role (see Privileges → Corporate Roles→ General → Cost Location Manager) is assigned to a user.

To set up a role parameter:

  • In the Domain Configuration view, use DirX Identity Manager to create or maintain role parameter definitions (Provisioning → Domain Configuration → Customer Extensions → Role Parameters).

  • If you use proposal lists for role parameter definitions, set up these objects (Provisioning → Domain Configuration → Customer Extensions → Proposal Lists).

  • If you intend to use an object structure or object hierarchy for role parameter objects, set up the corresponding definitions (for example, you can use an existing Business Object structure).

  • Define the matching rules that use the role parameter in the role objects.

  • Supply the necessary role parameter values in the target system groups (add the possible parameters to the groups or create new groups for these parameters).

Adding Dependent Proposal Lists

This feature allows you to interdependent build drop-down lists in Web Center that are displayed on a single page.The feature is available in the context of creating a new object or modifying an existing object.When a Web Center user selects an item in the first list, the second list becomes populated with choices that are only relevant to the context of the item selected from the first list.When an item in the second list is selected, the corresponding choices in the third list become available, and so on.

The feature is not available within DirX Identity Manager or in Web pages generated automatically from request workflows.

The feature makes use of proposal lists of type Dependent DN.Within this type, attributes selected in the related master proposal lists are dynamically replaced in the search filter or the search base defined for that list.

A dependent proposal list is configured by search base, filter, and scope of the search.Furthermore, the attributes containing the value for display and the value to be stored with the managed object are to be configured (Display Attribute and Storage Attribute).An extra feature is the possibility to define a Link Attribute with the proposal list.If you specify such a Link Attribute, this attribute is expected to hold DN links to other objects.The result is that the proposal list data are read from the linked objects rather than from the objects being returned by the search.

Configuring Dependent Proposal Lists

Perform these configuration steps to add a dependent proposal list:

  • In Identity Manager, define a proposal list of type Dependent DN.

  • Filter and / or search base of the proposal list have to be expressed in terms of the storage attribute $(<master_attribute>) whose value is used as master for the related list.

  • In the object description, define a tag provider for the dependent property. Set the provider’s class name to siemens.dxr.service.tags.DependentProposal, and its dn to the distinguished name of the proposal list created in the preceding step.

  • Reference the master attribute from the description of the dependent attribute in Web Center’s forms-config.xml. Assure that the renderersProperties attribute of the actual form-property contains the expression "master:form___attribute" where form is the name of the form holding the master attribute and attribute contains the master attribute’s name.
    Example: rendererProperties="master:modificationForm_c".

Example Configuration

In this section, we describe how to configure a three-level dependency between proposal lists; that is, drop-down lists in Web Center. The samples use the My-Company sample scenario.

The hierarchy of proposal list is:

Countries → Locations → Rooms

A user first selects a country. Now the list of locations displays only the locations of this country. If the user selects a location, the list of rooms displays only the available rooms of this location.

Defining a Dependent Proposal in DirX Identity Manager

We define three new proposal lists and assign them to properties of the user object.

Sample List for Countries

The top-level of our hierarchy is the proposal list for countries defined under Business Objects → Countries. Perform these steps:

  • Select the view Domain Configuration.

  • Select Customer Extensions → Proposal Lists and then New Proposal from the context menu.

  • Create the new proposal list with this data:
    Name: Business Countries
    Description: List of countries derived from business objects
    Type: DN
    Searchbase: cn=Countries,cn=BusinessObjects,cn=My-Company
    Searchfilter: objectclass=”dxrCountry”
    Searchscope: one level
    Display attribute: description (for example “Germany”)
    Storage attribute: c (for example “DE”)
    Link attribute: <empty>

To assign the proposal list to the corresponding object property in the object description, perform these steps:

  • Select the view Domain Configuration.

  • Select Customer Extensions → Object Descriptions → UserCommon.xml

  • Click Edit and add the following code:

    <property name="c"
label="Country"
editor="siemens.dxr.manager.controls.MetaRoleJnbComboBox"
type="java.lang.String"
incremental="false">
<tagprovider class="siemens.dxr.service.tags.Proposal"
  dn="cn=Business Countries,cn=Proposal Lists,cn=Customer Extensions,cn=Configuration,$(rootDN)"
  proposals="dxrProposedValues"/>
</property>

Sample List for Locality

The second level of our hierarchy is a proposal list of company locations assigned to a country. So the list of available locations depends on the selected country.

  • Select the view Domain Configuration.

  • Select Customer Extensions → Proposal Lists and then New Proposal from the context menu.

  • Create the new proposal list with this data:
    Name: Dependent Localities
    Description: List of localities derived from business objects and dependent on the 'Business Countries" list
    Type: Dependent DN
    Searchbase: c=$(c),cn=Countries,cn=BusinessObjects,cn=My-Company
    Searchfilter: objectclass=”dxrLocation”
    Searchscope: subtree
    Display attribute: l (for example “My-Company Berlin”)
    Storage attribute: dn (for example “l=My-Company London, c=GB,cn=Countries,cn=BusinessObjects,cn=My-Company”)

The searchbase contains a placeholder c=$(c) for the selected country. This placeholder will be replaced with the actual value during runtime. The storage attribute is the DN of the selected dxrLocation-object (for example “l=My-Company London, c=GB,cn=Countries,cn=BusinessObjects,cn=My-Company”).

Note that the “c” in $(c) is the name of the user attribute holding the country, not the naming attribute of the country object. If the country is stored in a user attribute with the name userCountry, the search base starts with c=$(userCountry).

To assign the proposal list to the according object-property process these steps:

  • Select the view Domain Configuration.

  • Select Customer Extensions → Object Descriptions → User.xml

  • Click Edit and add the following code (this overloads the existing definition in Object Descriptions → User.xml):

    <property name="dxrLocationLink"
type="java.lang.String"
label="Location Link"
multivalue="false"
incremental="false"
editor="siemens.dxr.manager.controls.MetaRoleJnbComboBox"
editorparams="editable=true">
<tagprovider class="siemens.dxr.service.tags.DependentProposal"
 dn="cn=Dependent Localities,cn=Proposal Lists,cn=Customer Extensions,cn=Configuration,$(rootDN)"
 proposals="dxrProposedValues"/>
</property>

Sample List for Rooms

The third level of our hierarchy is a proposal list of room numbers assigned to a location. In our sample data the room objects are created as context objects to a location.

  • Select the view Domain Configuration.

  • Select Customer Extensions → Proposal Lists and then New Proposal from the context menu.

  • Create the new proposal list with this data:
    Name: Dependent Rooms
    Description: List of rooms derived from business objects and dependent on the 'Dependent Localities" list
    Type: Dependent DN
    Searchbase: $(dxrLocationLink)
    Searchfilter: objectclass=”dxrContext”
    Searchscope: base object
    Display attribute: cn
    Storage attribute: cn
    Link attribute: dxrContextLink

The main difference in this example is the usage of the link attribute. In this case the actual values for the proposal list are read from the dxrContextLink. In our sample you need to set from each location the links to the relevant room objects.

To assign the proposal list to the according object-property process these steps:

  • Select the view Domain Configuration.

  • Select Customer Extensions → Object Descriptions → UserCommon.xml

  • Click Edit and add the following code:

    <property name="roomNumber"
label="Room"
editor="siemens.dxr.manager.controls.MetaRoleJnbComboBox"
type="java.lang.String"
incremental="false">
<tagprovider class="siemens.dxr.service.tags.DependentProposal"
 dn="cn=Dependent Rooms,cn=Proposal Lists,cn=Customer Extensions,cn=Configuration,$(rootDN)"
 proposals="dxrProposedValues"/>
</property>

Changes in the Web Center Configuration Files

To test the dependent proposal list we modify and add some code in the file:

installation_path\web\webCenter\WEB-INF\config\identity\forms-config.xml

In our sample data we replace the existing definition for “c” (country) with this code:

<form-property name="c"
type="java.lang.String"
fieldRenderer="combobox"
label="ldap.attribute.c"
width="100%" y="3" x="0"/>

We replace the existing definition of the property dxrLocationLink with this code:

<form-property name="dxrLocationLink"
type="java.lang.String"
fieldRenderer="combobox"
rendererProperties="master:modificationForm_c"
label="ldap.attribute.l"
width="100%" y="3" x="1"/>

A new definition is added for room number:

<form-property name="roomNumber"
type="java.lang.String"
fieldRenderer="combobox"
rendererProperties="master:modificationForm_dxrLocationLink"
label="Room"
width="100%" y="6" x="1"/>

The most important change in the code is the reference to the master field (master:..). If a master is defined then the dependent combo listens to changes in the master combo and refreshes itself according to the proposal list definition.

After performing the above described modifications restart the Tomcat Service.

In the user modification page you can see the three combo box fields for country, locality and room. After a country is selected the combo for locality is filled according to the new value of the master combo and set to an empty value. After a new locality is selected the combo for room number is filled.