The following section describes how to set the properties of the atg/userprofiling/ProfileUserDirectory component for an LDAP user directory configuration.

Property

Description

profileItemFinder

The profile item finder which looks users up by their attributes or IDs. Set this property to the Personalization module’s profile item finder. The default is /atg/userprofiling/ProfileItemFinder.

repositoryItemGroupRegistry

The registry of repository item groups (also known as profile groups). No change.

repositoryUserDirectoryProperties

The component which tracks repository item property names, much as does the /atg/userprofiling/PropertyManager. No change.

repository

The backing repository. This property should point to the implicitly linked SQL/LDAP repository. If you follow the procedure earlier in this section, you should not have to change this property.

transactionManager

The component which helps the user directory make use of Dynamo’s transactional database interaction. For more information, see Transaction Management in the ATG Programming Guide.

Note: Since LDAP systems are not transaction aware, the LDAP repository is also not transactional. This behavior means that it is possible for LDAP data to be written permanently even if the transaction within which the operation occurred is rolled back.

userDirectorySpider

A spider that walks the user directory’s organization and user hierarchy on a specified schedule, thereby creating ATG-side objects corresponding to each user and organization in LDAP, beginning with the root organization. This property is not required. Set this property to null if you don’t require this behavior.

See also ProfileUserDirectorySpider.

organizationCache

The cache that translates organization primary keys into organization objects. Set this property to LDAPOrganizationCache.

organizationPathCache

Translates organization paths within the organization hierarchy into organization objects. No change.

repositoryItemGroupRoleCache

Translates profile groups into role objects. No change.

roleCache

Translates role primary keys into role objects. No change.

rolePathCache

Translates role paths within the role folder structure into role objects. No change.

folderCache

Translates role folder primary keys into role folder objects. No change.

folderPathCache

Translates role folder paths within the role folder structure into role folder objects. No change.

userCache

Translates user primary keys into user objects. Set this property to LDAPUserCache.

userViewName

The name of the user view in the repository backing this directory.

organizationViewName

The name of the organization view in the repository backing this directory.

relativeRoleViewName

The name of the relative role view in the repository backing this directory.

roleViewName

The name of the role view in the repository backing this directory.

folderViewName

The name of the folder view in the repository backing this directory.

rootRoleFolderPrimaryKey

The primary key of the root role folder. No change.

rootOrganizationPrimaryKey

The primary key of the root organization. See Setting the rootOrganizationPrimaryKey Property below.

organizationItemFinder

Similar to the ProfileItemFinder (see ProfileItemFinder Component). Its purpose is to locate organization repository items. This property points to an instance of RepositoryLinkProfileItemFinder that is configured to look for organization items. Set this property to /atg/userprofiling/
LDAPOrganizationItemFinder
(the default).

useGSARepositoryIdAsPrimaryKey

Determines whether user directory objects use their SQL repository item’s repository ID as their primary key (the default, and the way that the default user directory is configured) or whether user directory objects use the repository ID of the linked LDAP item as their primary key. Your choice here has significant effects on the portability of your code. See Important Notes About the useGSARepositoryIdAsPrimaryKey Property for information.

Setting the rootOrganizationPrimaryKey Property

The value you set for the rootOrganizationPrimaryKey property depends on the value of useGSARepositoryIdAsPrimaryKey. If useGSARepositoryIdAsPrimaryKey is true (the default), this value should be the repository ID of the SQL repository item that is implicitly linked to the LDAP item that you want to be your root organization.

For example, assume you want the organization People in LDAP to be your root organization (remember that you must pick an LDAP object of object class organizationalUnit, or of whatever type the organization LDAP repository view specifies). First make sure that your organization shows up as an item of type organization in your LDAP repository. Next, if useGSARepositoryIdAsPrimaryKey is false, you set rootOrganizationPrimaryKey to be the People organization item’s repositoryId (ou=People,dc=atg.com, perhaps). You don’t need to create a root SQL repository item, because the organizationItemFinder will automatically create a SQL repository counterpart item when the root organization is requested.

If useGSARepositoryIdAsPrimaryKey is true, you must first create a SQL repository item of type organization and configure it so that it is implicitly linked with the LDAP organization repository item for people (the LDAP item with ID ou=People,dc=atg.com). Then, set rootOrganizationPrimaryKey to be the repository ID of your newly created root SQL repository organization (it could be anything, for example 1111).

See the next section for some important information about the effects of setting the useGSARepositoryIdAsPrimaryKey property.

Important Notes About the useGSARepositoryIdAsPrimaryKey Property

Do not write any application code that determines a user directory object’s primary key from a source outside the user directory and then uses that key to fetch a user directory object.

Example: the default user directory uses a profile ID (user repository item repositoryId) as a user directory user object’s primary key. However, applications should not use this knowledge to take a profile ID from a session and then call findUserByPrimaryKey on the user directory, passing in the session’s profile ID. Primary keys are implementation specific. Therefore, any application code written to rely on aspects of the default user directory implementation’s primary key system is not portable.

The recommended way to work with user directory primary keys is as follows:

Obviously, these steps apply only to an application that wants to get a child organization of the root organization by primary key. The important point is that user directory primary keys must come from the user directory objects themselves, not from a source outside the user directory.

Nonetheless, in some exceptional circumstances it is necessary to write non-portable application code that does exactly what this section recommends against doing. For example, some parts of the ACC interface employ the knowledge that user directory user objects have a primary key that is the same as their backing item’s repositoryId in order to reuse some RepositoryItem picker code. This design makes the ACC interface non-portable but more functional. For purposes of maximum compatibility with the user interface, therefore, the default setting for useGSARepositoryIdAsPrimaryKey is true. If you require use of the ACC for managing organization, role, and user data, you must leave this property set to true.

When useGSARepositoryIdAsPrimaryKey is true, only user directory objects whose SQL repository item has already been created will be available for fetching by primary key. If your application code follows the 5-step coding guidelines shown above, the problem is avoided, because by the time your code asks a user directory object for its primary key, it has by definition got a SQL repository item associated with it. However, if a primary key is fabricated outside the user directory, only items that have been accessed through the user directory in some other way will be available for fetching by primary key.

Consider the following example. Some application code searches for a user whose primary key is 4444. In the default user directory, the profile repository is not implicitly linked. Therefore, all available users exist in the SQL repository and can be fetched at any time by their primary key (in this case, 4444). Assume, however, that you change the SQL repository to be implicitly linked to an LDAP repository. With this configuration, users can be in the LDAP repository but not have a SQL repository counterpart yet. When useGSARepositoryIdAsPrimaryKey is true, the user with primary key 4444 cannot be found by primary key until he or she is found as a member of an organization or by some similar operation.

To summarize, a useGSARepositoryIdAsPrimaryKey setting of true makes all existing user directory application code compatible with the LDAP user directory, but it has some unexpected and potentially undesirable results: namely that LDAP organizations and users cannot be fetched by primary key until a SQL repository link item has been created that is implicitly linked to its LDAP manifestation. If you must set this property to true, for example because you want to use the ACC for managing user directory data, make sure that any code you write follows the 5-step coding guidelines in this section.

When useGSARepositoryIdAsPrimaryKey is false, user directory objects use their implicitly linked LDAP repository item’s ID as their primary key. This behavior means that application code that must fetch a user directory user object directly by primary key can do so, and success can be guaranteed; if the primary key corresponds to a user repository item in LDAP, the user directory user object will always be found.

The false setting is most useful for new application code, as existing code will not be determining the correct primary key for a user. Existing code uses SQL repository IDs rather than LDAP repository IDs as primary keys.

Sample ProfileUserDirectory.properties File

The code below is an example of a ProfileUserDirectory.properties file for an LDAP user directory.

$class=atg.userdirectory.repository.ldap.LDAPRepositoryUserDirectory

#basics

profileItemFinder=/atg/userprofiling/ProfileItemFinder
repositoryItemGroupRegistry=/atg/registry/RepositoryGroups
repositoryUserDirectoryProperties=ProfileUserDirectoryProperties
repository=/atg/userprofiling/ProfileAdapterRepository
transactionManager=/atg/dynamo/transaction/TransactionManager
userDirectorySpider=ProfileUserDirectorySpider

# caches

organizationCache=LDAPOrganizationCache
organizationPathCache=OrganizationPathCache
repositoryItemGroupRoleCache=RepositoryItemGroupRoleCache
roleCache=RoleCache
rolePathCache=RolePathCache
folderCache=FolderCache
folderPathCache=FolderPathCache
userCache=LDAPUserCache

#view names
userViewName=user
relativeRoleViewName=organizationalRole
organizationViewName=organization
roleViewName=role
folderViewName=roleFolder

#random
rootRoleFolderPrimaryKey=root
# rootOrganizationPrimaryKey=ou=People,dc=atg.com
rootOrganizationPrimaryKey=1111

# ldap
organizationItemFinder=/atg/userprofiling/LDAPOrganizationItemFinder
useGSARepositoryIdAsPrimaryKey=true
 
loading table of contents...