Configuring Directory Search

uPortal includes a built-in directory portlet backed by the person directory.  Directory results are filtered by the permissions of the searching user.

Search Attributes

To be able to search for a user via a particular attribute, that attribute must actually be listed as a search attribute in the person directory context, as well as in the list of directory queries.  These two lists ensure that uPortal only performs directory search against the desired attributes, producing more performant and relevant results.  The searching user must also have permission to view the search attribute in question.

As an example, lets consider searching for a user by email address.  First, we would need to add the "mail" attribute as query attribute in the person directory configuration.  Next, this attribute must also be added to the directoryQueryAttributes bean in uportal-war/src/main/resources/properties/contexts/userContext.xml:

<util:list id="directoryQueryAttributes">
    <value>givenName</value>
    <value>sn</value>
    <value>mail</value>
</util:list>

Finally, we would need to check to ensure that searching users have permission to view the mail attribute (see below).

Display Attributes

User accounts often contain many more user attributes than we might like to be displayed in the directory.  As a result, uPortal requires explicit configuration of the user attributes displayed in directory search results.  Each listed directory display attribute is displayed in order, assuming a value exists and that the viewing user is permitted to see the attribute in question.  Each attribute is associated with a content type which controls how the value will be displayed in the directory portlet.

Display Types

The display name of the attribute is determined by the value associated with the key "attribute.displayName.attributeName" in the messages file.  As of the current uPortal release, directory attributes are configured via the directoryDisplayAttributes map in uportal-war/src/main/resources/properties/contexts/userContext.xml.  The key for each entry must match a mapped attribute in personDirectoryContext.xml.

As an example, lets consider adding a mobile phone number to the directory results.  We will assume that we already have a mapped user attribute in personDirectoryContext.xml named "mobile".  To add this new attribute to the directory, we would modify the directoryDisplayAttributes bean definition, adding a new entry mapping "mobile" as a "PHONE" type attribute:

<util:map id="directoryDisplayAttributes">
    <entry key="title" value="GENERIC"/>
    . . . 
    <entry key="mobile" value="PHONE"/>
</util:map>

In addition, we would map a display name for this attribute.  If we wanted the attribute to display as "Cell", we could add the following line to uportal-war/src/main/resources/properties/i18n/Messages.properties. 

attribute.displayName.mobile=Cell

Finally, to ensure that the new mapped attribute is visible to end users, we would need to add permissions (see below).

Permissions

uPortal includes two key permissions that affect directory search results.  First, the VIEW_USER permission controls whether a given user is visible to the searching user.  For example, for Sally to be able to successfully view Jim, Sally (or a group Sally is a member of) would have to have the VIEW_USER on Jim (or a group Jim is a member of).  If the searching user does not have permission to view a user, that user will not show up in the directory result list.

The VIEW_USER_ATTRIBUTE permission controls whether a given user attribute is visible to the searching user.  For example, for Sally to be able to view a mobile phone number for any user, she (or a group she is a member of) would need to have the VIEW_USER_ATTRIBUTE permission on "mobile".  As of the current release of uPortal, user attribute permissions cannot be granted in a more granular fashion.  For example, it is not possible to grant Sally view permissions on the mobile attribute only for a single group.