Enhancements in the Content Platform Engine 5.2.0 FP1 release for IBM Connections environments

Content

This technote discusses a set of functional enhancements that were made in the IBM FileNet Content Manager 5.2.0 FP1 release. These enhancements were developed specifically for the IBM Connections application. It is possible that they may be exposed in the future by other applications which are also clients of IBM FileNet Content Manager.


1 User Identity Mapping for Creator & Last Modifier properties

Problem

For applications that wish to display the creator or last modifier of a document, the Creator and LastModifier properties are available for this purpose. These properties store a string, which is normally the short name of the user. A limitation of this approach is that this short name value is not guaranteed to be unique and stable over time. There are two scenarios where this can be a problem:
1. Jane Smith, short name jsmith created a document. Jane now marries and becomes Jane Jones, with her short name being changed to jjones. Someone viewing the document created before the name change should see it attributed to jjones, but it is instead attributed to jsmith.
2. John Brown (jbrown) created a document. John then leaves the company. At a later date Julia Brown is employed and is given the now unused short name jbrown. A user viewing the document created by John Brown will see it incorrectly attributed to Julia Brown since that is to whom the short name now resolves.

Solution
To address these issues, a new User Identity Mapping capability is introduced in the 5.2.0 FP1 release. This capability requires the installation of a new AddOn: Social Collaboration User Identity Extensions. This capability will only be enabled when this AddOn is installed.

Note that this capability was developed for the IBM Connections integration, and is currently only leveraged by the Connections application. It is not currently exposed via IBM Content Navigator or any other ECM application.

Implementation Details

The Social Collaboration User Identity Extensions AddOn creates a new custom root class: ClbUserIdentityMapping, which stores the user’s SID in the ClbUserSid property. A SID is the user’s unique security ID, obtained from the LDAP directory service. A user keeps the same SID for the lifetime of their membership in the LDAP service, regardless of any name changes, or any other attribute changes. SID’s are also never reused. Therefore, referring to the user by their SID resolves both of the issues identified above.

The Social Collaboration User Identity Extensions AddOn also adds two new integer properties (ClbLastModifierIndex and ClbCreatorIndex) to the Document, Folder, and Task classes. These new properties can be used to look up the SID of the creator or last modifier of the object in the ClbUserIdentityMapping table. When the AddOn is installed, Content Engine change preprocessors are associated with these classes, and these change preprocessors keep the values of ClbLastModifierIndex and ClbCreatorIndex up to date during creation or update operations, adding new rows to the ClbUserIdentityMapping table whenever a row does not yet exist for a user.

When retrieving documents, the application will retrieve the ClbCreatorIndex and ClbLastModifierIndex properties, along with LastModifier and Creator. If a retrieved object has a value for an index property then the user’s SID can be obtained by finding the ClbUserIdentityMapping object having that sequence number, and the unique user can be looked up. If the index property is null (legacy object) then the system Creator and LastModifier properties must be used.

Note that while the installation of this new AddOn makes the user identity information available through the new ClbCreatorIndex and ClbLastModifierIndex, this data will not be displayed to end users without application changes. This capability was developed for the IBM Connections application, and will be exposed in the Connections 4.5 CR1 release. There are not plans to expose this capability through other applications at this time.


2 Expire Access Tokens on Demand

Background

When a user sends a request to a Content Platform Engine (CPE) server, the server builds a “User Access Token” for the user. This token is an object that records the user’s identity (as specified in the LDAP server) as well as all of the groups that the user belongs to. Building this user access token may require many round trips to the LDAP server, so it can be expensive. For this reason, the CPE server maintains a cache of User Access Tokens (UAT cache). If a new user request arrives, and the user’s access token is already in cache, then it is not re-computed. User Access Tokens remain in this cache until their Time To Live (TTL) expires, at which point they are aged out, and must be re-computed for any subsequent user requests.

Problem

In IBM Connections environments, when a user is added to a community, they expect to be able to access that community immediately. Conversely, when they are removed from a community, they should lose access to that community immediately. Since community membership is reflected by adding or removing users from groups that represent the communities, these goals are not met, due to the UAT cache. User’s will not gain access to new communities, or lose access to old communities, until their User Access Token times out and is expired from the UAT cache. The default value of the UAT cache TTL is one hour (3600 seconds) –which is a long time to wait for access changes to take effect.

A customer may avoid this latency by setting the UAT cache TTL to one second. However if they do this, then the CPE will recompute each user’s UAT with almost every request. This incurs a lot of LDAP calls for every request, which not only slows response times significantly, but places a large burden on the customer’s LDAP server.


Solution
To address these issues, Content Platform Engine 5.2.0 FP1 introduces a pseudo-property, @ExpireUAT. This property may be requested using a property filter, when retrieving the current user through the Content Engine Java API (i.e. Factory.User.getCurrent()).

The expiration can be controlled by setting the MaxSize parameter of the @ExpireUAT's filter element. The values > 0 of MaxSize are interpreted to mean "expire the current user's UAT cache entry if it is older than this many seconds"; not setting MaxSize or having a value <= 0 will unconditionally expire the UAT cache entry. If the cache entry is expired, then the next request from that user will cause the UAT to be recalculated.

This new server capability is one part of an overall solution. The application must have some knowledge of when a user’s group memberships have last changed, and use this knowledge to make calls to the Content Engine API to expire the user’s UAT cache entry when appropriate.


3 New Connections Directory Provider Type

Background

The Content Platform Engine 5.2.0 release introduced support for a new directory service provider: CmDirectoryConfigurationVMM. This provider allows WebSphere VMM configurations to be supported for any underlying LDAP server. This provider is also used in IBM Connections environments. However, when it is used in Connections environments it functions differently, going through the IBM Connections “Waltz” API layer, to retrieve both LDAP user and group entries, as well as the Connections communities that the user belongs to. Connections communities are not stored in an LDAP server. Rather, they are stored in a Connections maintained database. The Waltz layer makes a Connections community appear as two virtual groups that the user belongs to.

Problem
In the 5.2.0 release, both of these configurations are supported through the CmDirectoryConfigurationVMM provider. When a Connections environment is in use, then a JVM argument must be set to tell the Content Platform Engine server to use the Waltz layer, rather than going directly through the WebSphere VMM API’s. Using a JVM argument to distinguish these two different configuration types has proven to be problematic, and does not allow for easily adjusting the functionality of one of these two configuration types, without impacting the other.

Solution
To resolve these issues, the CmDirectoryConfigurationVMM provider is split in the 5.2.0 FP1 release into two providers. CmDirectoryConfigurationVMM will be used for pure WebSphere VMM environments, while the new CmDirectoryConfigurationConnections provider should be used for IBM Connections environments.

When creating new domains starting in the 5.2.0 FP1 release, the IBM Connections configuration tool should make use of CmDirectoryConfigurationConnections, instead of CmDirectoryConfigurationVMM.

Upon upgrade from 5.2.0 to 5.2.0 FP1, the Content Platform Engine will check each directory configuration. If a CmDirectoryConfigurationVMM instance is found, and the –Dibm.filenet.security.vmmProvider.waltzImpl=true JVM argument is set, then autoupgrade will change the class of this directory provider instance to CmDirectoryConfigurationConnections. Once upgrade to 5.2.0 FP1 is complete, the JVM argument can be removed.