Customizing a user card in the Request Access wizard

The first step in the Request Access wizard is used to select the user for whom access is being requested. The set of users to choose from is displayed as a collection of user cards that are arranged in a grid. You can customize the information that is displayed in the user cards, and also how the user cards in the grid can be sorted.

Before you begin

You must have read or 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

A user card is like a business card for people in your organization. The information that is displayed on a user card is arranged into several areas. You can customize which user attributes are displayed in each of the areas to meet your needs.

The primary area of the user card displays the most important user attribute, such as the user name. The information in this area displays at the top of the card and in the largest font. Only one user attribute can be assigned to the primary area, but you can choose a different attribute for each of the user profiles defined in your environment.

The secondary area of the user card displays the next most important user attribute, such as the user email address. The information in this area is displayed just under the primary area and in a smaller font than the primary area. Only one user attribute can be assigned to the secondary area, but you can choose a different attribute for each of the user profiles defined in your environment.

The tertiary area of the user card displays extra information about the user, such as the user title, department name, or sponsor name. The information in this area is displayed just under the secondary area and in a smaller font than the secondary area. Multiple user attributes can be assigned to the tertiary area. You can choose different sets of attributes for each of the user profiles defined in your environment. Each assigned attribute is given a label, such as Title or Sponsor that is displayed on the user card with the attribute value. The label is to help the user understand the information that is displayed on the card.

The icon area of the user card displays an image that is associated with the user, such as the user picture from your organization directory.

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

• To go to a custom file and edit, download, upload, or search it, see Managing custom files.
• To go to a property file and edit, upload, or search it see Managing the server properties.

Procedure

1. Optional: Customize the user attributes that are displayed in the different areas of user cards and whether sorting on the information in those areas is supported. Make a custom copy of the Person.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 primary section of this file contains attribute and sort subsections. For example:

   "primary": {
        "attribute": {
            "default": "name",
            "Person" : "CN",
            "BPPerson" : "CN"
        },
        "sort": {
            "enabled": true,
            "labelKey" : "name"
        } },

   In the attribute section, define the user attribute to display in the primary area of the user card. You can choose a different user attribute for each user profile that is defined in your environment. You must always set a default user attribute to use for any user profiles that are not explicitly defined. In the earlier example, the default user attribute is "name", but the attribute for users in the "Person" and "BPPerson" user profiles is "CN". Ensure that the primary section is defined with a valid LDAP attribute for the specified profiles or for a default attribute that is common across all profiles.

   In the sort section, you can enable or disable sorting of the user card that is based on the information in the primary area of the card. If you enable sorting, "enabled": true, the uppercase value of the labelKey field is used to look up the display string for this sort option in the customizable nls/Picker.properties file. In this example, the labelKey value NAME is looked up as a property in the nls/Picker.properties file to find the sort option string to display.

   The secondary section of this file is identical to the primary section. For example:

   "secondary": {
        "attribute": {
            "default": "mail",
            "Person": "manager.name"
        },
        "sort": {
            "enabled": true,
            "labelKey" : "contactInfo"
        } },

   In the attribute section, define the user attribute to display in the secondary area of the user card. You can choose a different user attribute for each user profile that is defined in your environment. You must always set a default user attribute to use for any user profiles not explicitly defined. In the earlier example, the default user attribute is "name", but the attribute for users in the "Person" user profile is "manager.name".

   In the sort section, you can enable or disable sorting of the user card that is based on the information in the secondary area of the card. If you enable sorting, "enabled": true, the uppercase value of the labelKey field is used to look up the display string for this sort option in the customizable nls/Picker.properties file. In this example, the labelKey value CONTACTINFO is looked up as a property in the nls/Picker.properties file to find the sort option string to display.

   The tertiary section of this file contains an attributes section. The attributes section is used to define the list of user attributes to be displayed in the tertiary area of the user card. For example:

   "tertiary": {
        "attributes": {
            "default": [ "title", “department” ],
            "BPPerson":[ "ersponsor.name" ]
        } },

   The attributes to be displayed are separated by commas and enclosed in square brackets. You can choose a different set of user attributes for each user profile that is defined in your environment. You must always set a default list of user attributes to use for any user profiles that are not explicitly defined. In the earlier example, the default list of user attributes is [ "title", "department" ], but the attribute list for users in the "BPPerson" user profile is [ "ersponsor.name" ].

   Sometimes the attribute that you want to display is not an attribute of the user, but it might be an attribute of an object that is related to the user. 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 this user card, you can use the dotted notation that is shown in the earlier examples:

     "manager.name"
     "ersponsor.name"

2. Optional: Customize the labels that are displayed with the user attributes in the tertiary area of the user card. Make a custom copy of the nls/Picker.properties file and open the file with a text editor. The properties in this file define the text that displays in various parts of the user selection step of the Request Access wizard.User attributes assigned to the tertiary area of the user card are displayed with a label to help the user understand what information they see. For example, if the config/Person.json file contains this definition for the tertiary section:

   "tertiary": {
        "attributes": {
            "default": [ "title", “department” ],
            "BPPerson":[ "ersponsor.name" ]
        } },

   Then, for the users in the BPPerson user profile, the tertiary field of the user card might be displayed as follows:

   Sponsor: John Doe

   To customize the label for a user attribute in the tertiary area of the user card, look for a property in the nls/Picker.properties file. The property must match the uppercase form of the user attribute name that is specified in the tertiary section of the config/Person.json file. For example, ERSPONSOR.NAME. If this property does not exist in the file, add a property with this name. Customize this property value to specify the string that you want to display as the user attribute label in the tertiary area of the card.

3. Customize the text that is displayed in the sort option list for the primary or secondary areas of the user card. Make a custom copy of the nls/Picker.properties file and open the file with a text editor. The properties in this file define the text that is displayed in various parts of the user selection step of the Request Access wizard.You can enable sorting of the user cards that are based on information in the primary and secondary areas of the user card. For example, if the config/Person.json file contains the following definition for the primary and secondary sections.

   "primary": {
        "attribute": {
            "default": "name",
            "Person" : "CN",
            "BPPerson" : "CN"
        },
        "sort": {
            "enabled": true,
            "labelKey" : "name"
        } },
    "secondary": {
        "attribute": {
            "default": "mail",
            "Person": "manager.name"
        },
        "sort": {
            "enabled": true,
            "labelKey" : "contactInfo"
        } },

   Then, sorting of user cards is enabled for both the primary and secondary areas of the user card. The set of user cards has a sort control at the top that displays as follows:

   Sort By: Name, Contact Information

   Sorting is not supported for attributes from objects that are related to the user, such as "manager.name". If any attributes that are specified in the primary section are from related objects, then the sort control does not include an option to sort on the primary area of the user card. Similarly, if any attributes that are specified in the secondary section are from related objects, then the sort control does not include an option to sort on the secondary area of the user card.

   You can customize the text to display in the list of sort options for the primary or secondary areas of the user card. To customize the text, look for a property in the nls/Picker.properties file. The property must match the uppercase value of the labelKey of the corresponding section of the config/Person.json file. For example, NAME or CONTACTINFO in the earlier example. If this property does not exist in the file, add a property with this name. Customize the value of this property to specify the string that you want to display in the list of sort options.

4. Optional: Customize the icon area of the user card to display an image for the associated user. Make a custom copy of the config/Person.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 this file contains an attribute subsection. For example:

   "icon": {
        "attribute": {
            "default": "erimageuri",
            “BPPerson": null
        } }

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

   See Customizing the server to generate user image URIs for information about how to configure a plug-in for the IBM Security Identity Manager Server that can dynamically generate the location of an image for the erimageuri attribute by using the values of attributes that are associated with users.

5. Customize the display value for user attributes with values that are not intuitive.

   You might want to display some user attributes on a user card, but the value of these user attributes is not intuitive to the user. For example, there might be a user attribute name such as employeeType whose value is encoded as "a" for active employees, "r" for retired employees or "p t" for part-time employees. Displaying the actual value of this attribute on the user card might not be intuitive to the user.

   To customize the displayed values for some user attributes, make a custom copy of the nls/CardCustomValue.properties file and open the file with a text editor. The properties in this file define the custom text that is displayed in place of the actual values for various user attribute and value combinations. For example, to define the display text for the values of the employeeType user attribute, you can add or modify the properties in this file as follows:

   employeeType.a=Active
   employeeType.r=Retired
   employeeType.p__DELIMITER__t=Part-time

   With these assigned values, the user card displays Active when the employeeType value is "a", Retired when the employeeType value is "r", and "Part-time" when the employeeType value is "p t". The property names in this file cannot contain spaces. If any of the possible user attribute values contain a space, you must replace it with the special character sequence __DELIMITER__. See the earlier example for reference. The employeeType value of "p t" is represented by a property name of employeeType.p__DELIMITER__t.

Results

The appearance of the user cards on the user selection step 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 user cards reflects the customization that you made.

Parent topic: Request Access wizard