Customizing the search controls in the Request Access wizard

The third step in the Request Access wizard is used to provide required information for accesses that are being requested. The forms for this required information might contain fields that are defined as Search Control or Search Match Control. You can customize the appearance of the search controls to meet your organizational requirements.

Before you begin

You must have read and write access to the customizable files and the directories where they are maintained. See Location of Identity Service Center customizable files and Customization of Identity Service Center files for specific details about where these files are located. Contact your system administrator if you do not have the necessary permissions.

About this task

Use the following sections to work with the configuration files or the configuration properties from the IBM Security Identity Manager virtual appliance console:

For some access requests, the user provides required information by completing fields of the form that is associated with the access. Some fields of the form might have a search control that enables the user to search the IBM Security Identity Manager Server for the appropriate value.

Each search field on a form is configured to search for a specific category of object, such as a Person, Account, or Organizational Unit. Search controls on forms can be used in two modes:

The object attributes in the drop-down list of cards and in the columns of the Advanced Search table can be customized to suit your needs. The information is arranged into several areas, and you can choose which object attribute is displayed in each area.

The primary area of the card displays the most important attribute, such as the object name. The information in this area is displayed at the top of the card and in the largest font. Only one attribute can be assigned to the primary area. But you can choose a different attribute for each of the object profiles defined in your environment. The attribute that is assigned to this area of the card is displayed as the first column in the Advanced Search table.

The secondary area of the card displays the next most important attribute, such as the object description. The information in this area is displayed just under the primary area and in a smaller font than the primary area. Only one attribute can be assigned to the secondary area. But you can choose a different attribute for each of the object profiles defined in your environment. The attribute that is assigned to this area of the card is displayed as the second column in the Advanced Search table.

The tertiary area of the card displays extra information about the object, such as the user title. The information in this area is displayed just under the secondary area and in a smaller font than the secondary area. Only one attribute can be assigned to the tertiary area. But you can choose a different attribute for each of the object profiles defined in your environment. The attribute that is assigned to this area of the card is displayed as the third column in the Advanced Search table.

The icon area of the card displays an image that is associated with the object. The icon is displayed at the side of the card, next to the primary, secondary, and tertiary areas. The attribute that is assigned to this area must provide the location (URI) of the image to display. You can choose a different attribute for each of the object profiles defined in your environment. The attribute that is assigned to this area of the card is not displayed in the Advanced Search table.

Sometimes the attribute that you want to display is not an attribute of the object, but it might be the attribute of a related object. For example, a user might have attributes that are called "manager" or "ersponsor" that are actually references to related users, namely the manager or sponsor of this user. To display an attribute like "name" from the related user in the card or the Advanced Search table, you can specify the attribute by using dotted notation. For example, "manager.name" or "ersponsor.name".

Some types of attributes, such as mapped attributes and attributes from related objects, can be selected and displayed in search results. But they cannot be used as the search criteria.

Procedure

  1. Optional: Customize the attributes that are displayed in the different areas of search cards and the Advanced Search table. Make a custom copy of the Search.json file and open the file with a text editor. The contents of this file are maintained in JavaScript Object Notation (JSON) format, which is a way of representing structured data.

    The Search.json file has sections for each object category, such as Person or ACCOUNT. You can use this file to select different display attributes for each type of object. There are sections within each object category that define the attributes to display for that object type.

    The primary section contains an attribute subsection. For example:
    "primary": {
     "attribute": {
         "default": "name",
         "Person" : "CN"
     },
     . . .
 },

    In the attribute section, define the object attribute to display in the primary area of the search card and in the first column of the Advanced Search table. You can choose a different attribute for each profile that is defined in your environment. You must always set a default attribute to use for any profiles not explicitly defined. In the preceding example, the default attribute is "name", but the attribute for objects in the "Person" profile is "CN".

    The secondary section is identical to the primary section. For example:
    "secondary": {
     "attribute": {
         "default": "mail"
     },
     . . .
 },

    In the attribute section, define the object attribute to display in the secondary area of the search card and in the second column of the Advanced Search table. You can choose a different attribute for each profile that is defined in your environment. You must always set a default attribute to use for any profiles that are not explicitly defined. In the previous example, the default attribute is "mail", and no other attributes are defined for specific profiles.

    The tertiary section of this file is identical to the primary and secondary sections. For example:
    "tertiary": {
     "attribute": {
         "default": "title"
     },
     . . .
 },

    In the attribute section, define the object attribute to display in the tertiary area of the search card and in the third column of the Advanced Search table. You can choose a different attribute for each profile that is defined in your environment. You must always set a default attribute to use for any profiles not explicitly defined. In the previous example, the default attribute is "title", and no other attributes are defined for specific profiles.

  2. Optional: Customize the labels that are displayed for the column headings in the Advanced Search table. Make a custom copy of the SearchCustomAttributes.properties file and open the file with a text editor. The properties in this file define the text that is displayed in the column headings of the Advanced Search table.The primary, secondary, and tertiary sections of each object category in the Search.json file contain a labelKey field. For example:
     "primary": {
     . . . 
     "labelKey": "name"
 },
 "secondary": {
     . . . 
     "labelKey": "contactInfo"
 },
 "tertiary": {
     . . . 
     "labelKey": "title"
 },

    The uppercase value of these labelKey fields is used to look up the display strings for the column headings of the Advanced Search table in the SearchCustomAttributes.properties file. In this example, the labelKey value NAME is looked up as a property to find the column heading to display for the primary attribute. It is the first column in the Advanced Search table. If any properties are not found, then the value of the labelKey field is used as the column heading.

  3. Customize the icon area of the search card to display an image for the associated object. Make a custom copy of the Search.json file and open the file with a text editor. The contents of this file are maintained in JavaScript Object Notation (JSON) format, which is a way of representing structured data.The icon section of each object category of this file contains an attribute subsection. For example:
    "icon": {
     "attribute": {
         "default": "erimageuri"
     } }

    In the attribute section, define the attribute that contains the location of the icon or image to display on the search card. You can choose a different attribute for each profile that is defined in your environment. You must always set a default attribute to use for any profiles that are not explicitly defined. If some profiles do not have an image attribute, you can specify null to indicate that no image must be displayed for objects in that profile. In the earlier example, the default attribute is "erimageuri", and no other attributes are defined for specific profiles.

Results

The appearance of the search controls on form fields of the Request Access wizard is changed to reflect the customization that you made.

What to do next

In a managed-cluster environment, you must wait until after the configuration is synchronized to the application servers in the cluster. For information about synchronizing, see Synchronizing a member node with a primary node.

Log in to the Identity Service Center. Start the Request Access wizard, and verify that the appearance of the search control reflects the customization that you made.

Parent topic: Request Access wizard