4.3 Working with entities and attributes

Any identity vault object that you want users to search, display, or edit in the Identity Manager user application must be defined as an entity in the directory abstraction layer. For example, to use the inetOrgPerson identity vault object in the user application, you must create an entity definition for it.

4.3.1 Steps for adding entities

Follow these steps to add entities to the directory abstraction layer:

Step	Task	For more information
1	Decide what identity vault objects you want to use in the user application	Section 4.3.2, Analyzing your data needs
2	Use the directory abstraction layer editor to define the identity vault objects in the directory abstraction layer	Section 4.3.3, Defining entities
3	Use the Provisioning View to validate the data definitions	Section 4.8, Importing, validating, and deploying directory abstraction layer definitions
4	Deploy the definitions to the identity vault	Section 4.8.3, About deploying
5	Update the application server’s cache to include the new abstraction layer definitions	Section 13.0, Caching Configuration
6	Test the Identity Manager user application to ensure that your changes display properly

4.3.2 Analyzing your data needs

To model your identity vault data in the directory abstraction layer, you’ll need to know:

The parts of the directory you want to make available to the Identity Manager user application.

For example, the list of objects that the user can search and display. Check this list against the base set of abstraction layer definitions to determine what you need to add.

The structure of the schema including custom extensions and auxiliary classes
The structure of the data including:
- What is required and what is optional
- Validation rules
- Relationships between objects (DN references)
- How attributes are defined (for example, an attribute that represents a phone number might be multi-valued for home, office, and cell phone numbers)
Who will see the data

Is this a public or private site?

Once you have this information, you can use it to map your identity vault objects to abstraction layer entities.

NOTE:The eDirectory ACLs are applicable to all abstraction layer objects. Effective rights on objects and attributes are based on the authenticated user established at application login.

4.3.3 Defining entities

Depending on what you want to expose in the user application, you’ll be defining two kinds of entities:

Entities that are mapped from schema. These entities represent objects that exist in the identity vault that are directly exposed to users in the user application. When defining this type of entity, you’ll expose all of the attributes that you’ll want your users to work with. Examples of this entity type include: User, Group, and Task Group.You can also create more than one entity definition for the same object if you want to expose different sets of attributes to different kinds of users. For more information, see Creating multiple entity definitions for a single object.
Entities that represent LDAP relationships. This type of entity is known as a DNLookup and it is used by the user application to:
- Populate a list with the results of a DN search among related entities
- Maintain referential integrity across DN referenced attributes during updates and deletes
Entities that support DNLookups are used by the Org Chart portlet to determine relationships and are also used by the Search, Create, and Detail portlets to provide pop-up selection lists and DN contexts. Examples of this kind of entity include: Manager Lookup, Task Manager Lookup, and User Lookup. For more information, see Using DNLookup control types.

Creating multiple entity definitions for a single object

You can create more than one entity definition that represents the same identity vault object, but provides a different view of the data. Within the entity definitions you could:

Define different attributes for each entity definition

Define the same attributes, but specify different access properties that control how the attributes are searched, viewed, edited or hidden

NOTE:The entity definitions can optionally include a filter to hide certain entities from the result set.

You could then use these different entity definitions in different parts of the user interface. For example, suppose that you wanted to create a directory of employees; one for a public site and one for an internal site. On the public site you wanted to supply first and last names and a phone number, but on the internal site, you wanted to list additional information like title, managers, and so on. Here’s how you could accomplish this:

Create two entity definitions (with different keys).

Both entity definitions expose the same identity vault object, but one entity definition key is public-staff-information, and the other is internal-staff-information.
Within each entity definition define a different set of attributes: one for public-staff-information, the other for internal-staff-information.
Use the Portal Administration tab of the Identity Manager user application to create a portlet instance for the public page, and another one for the internal page.

For more information about creating portlet instances, see Section 9.0, Portlet Administration.

Procedures for creating entity definitions

When you have determined the entities and attributes that you want to expose, you can start adding them to the directory abstraction layer using the editor. You’ll follow a set of steps like this:

Step	What to do	See this procedure
1.	Decide which set of files to start with.
	You want to add to the base set of definitions	Section 4.3.1, Steps for adding entities
	You want to start with already deployed definitions	Section 4.8.1, About importing
1a.	Some of the entities that you want to use are not part of the eDirectory base schema. Any extensions to the eDirectory schema will not show up automatically in the editor’s list of selectable objects and attributes. This means that you have to update the designer’s local schema file to include these custom objects and attributes.	To update the list of available schema elements:
2.	Add one or more entities to the directory abstraction layer	Adding entities
3.	Add attributes to the entities	Adding attributes

Updating the list of available schema elements

To update the list of available schema elements:

With the Identity Manager project open, select the Identity Vault, right-mouse and select Live Operations>Import Schema.
Choose Import from eDirectory and provide the specifications for the eDirectory host.
Click Next.
Select the classes and attributes that you want to import, and click Finish.

Adding entities

You can add an entity via the Add Entity Wizard (described next) or by clicking the Add Entity button from the editor’s toolbar.

NOTE:When using the Add Entity button, you are prompted to select the object class of the entity you want to create. The editor automatically adds the required attributes to the entity. You can then use the Add Attribute dialog to complete the entity definition.

To add an entity using the Add Entity Wizard:

Launch the Add Entity Wizard in one of these ways:

From the Provisioning View:
- Select the Entities node, right-mouse click and choose New.
- Select File>New>Provisioning. Choose Directory Abstraction Layer Entity. Click Next.
From the directory abstraction layer editor:
- Select the Entities node, right-mouse click and choose New Entity-Attributes Wizard.
  
  The New Entity dialog displays.
NOTE:If launched from the File menu, the dialog contains fields not displayed when launched in either of the other ways. It is shown below.

Complete the panel as follows:

Field	Description
Identity Manager Project and Provisioning Application	Select the Identity Manager project and Provisioning Application where you want to add the entity and attributes. NOTE:These fields display when you launch the wizard from the File menu.
Entity Key	The unique identifier for the entity.
Display Label	The string displayed whenever this entity is referenced in the user interface.

Click Next. The New Entity dialog displays:
Choose the Object Class for the entity that you want to create, then select the attributes that you want from the Available Attributes list

HINT:If the object class of the entity that you want to create is not shown in the Available Object Classes list you might need to update the designer’s local schema file. Follow the steps described in To update the list of available schema elements:.
Click Finish.

The property sheet is displayed for editing.

For more information, see Entity property reference.

NOTE:To make the attribute available to the user application, you must deploy the entity that contains the attribute.

Adding attributes

To add an attribute:

Select an entity.
Add an attribute by:
- Right-clicking and selecting Add Attribute.
or
- Clicking the Add Attribute icon.
You are prompted as follows:
Choose the attribute from the Available Attributes for Entity Class list and add it to the Selected Attributes for Entity list.

HINT:If the attribute that you want to create is not shown in the Available Attributes from Entity Class list you might need to update the designer’s local schema file. Follow the steps described in To update the list of available schema elements:.
Click OK.

The property sheet is displayed for editing.

For more information, see Attribute property reference.

NOTE:To make the attribute available to the user application, you must deploy it.

Entity property reference

You can set the following kinds of properties on entities:

Entity access properties

The Access Properties control how the user application interacts with the entity. They include:

Property	Description
Create	Selected—This object can be created by the user application.
Edit	Deselected—This object is not changeable by the user application regardless of the underlying ACLs. Selected—This object might be changeable, but the identity vault ACLs are used to determine this.
View	Selected—This object can be displayed by the user application.
Remove	Selected—This object can be deleted by the user application.

Entity required properties

The Required entity properties are:

Property name	Description
Key	The unique identifier for this entity. It defines the way the user application will reference this object.
Display Label	Defines how the object is shown in the user interface.
Class name	The Novell Directory Service (NDS) class name.
LDAP name	The LDAP object class name.
Search	Selected—This entity is searchable. Entities used in queries by identity portlets (such as Entity Search List or Entity Org Chart) must be selected (true).
Auxiliary Classes	A list of zero or more auxiliary classes for this entity. If adding auxiliary classes, you must specify the auxiliary class LDAP Name, NDS Name, and whether or not it can be searched.

Entity search properties

The entity Search properties are:

Property name	Description
Search container	The distinguished name of the LDAP node or container where searching starts (the search root). For example: ou=sample,o=ourOrg You can browse the identity vault to select the container, or you can use one of the predefined parameters described in Using predefined parameters.
Search scope	Specifies where the search occurs in relation to the search root. Values are: <Default>—This search scope is the same as selecting Containers and subcontainers. Container—Search occurs in the search root DN and all entries at the search root level. Container and subcontainers—Search occurs in the search root DN and all subcontainers. This is the same as selecting <Default>. Object—Limits the search to the object specified. This search is used to verify the existence of the specified object.
Search Time Limit [ms]	Specify a value in milliseconds or specify 0 for no time limit.
Max Search Entries	Specify the maximum number of search result entries you want returned for a search. Specify 0 if you want to use the runtime setting. Recommendations: Set between 100 and 200 for greatest efficiency Do not set over 1000

Entity create and edit properties

The entity Create and Edit Properties are:

Property name	Definition
Create Container	The name of the container where a new entity of this type is created. You can browse the identity vault to select the container, or you can use one of the predefined parameters described in Using predefined parameters. If this value is not specified, then the Create portlet will prompt the user to specify a container for the new object. The portlet will use the search-root specified in the entity definition as the base and allow the user to drill down from there. If there is no search-root specified in the entity definition then it will use the root DN specified during the user application installation.
Naming Attribute	The naming attribute of the entity (the Relative Distinguished Name (RDN)). This value is only necessary for entities where the access parameter Create is selected.
Alternate Edit Entity	The attributes of the Edit Entity are displayed in the edit mode of the Detail portlet. Choose an entity from the dropdown or <None> if this entity is not displayed by the Detail portlet.

Property name

Definition

Create Container

The name of the container where a new entity of this type is created.

You can browse the identity vault to select the container, or you can use one of the predefined parameters described in Using predefined parameters.

If this value is not specified, then the Create portlet will prompt the user to specify a container for the new object. The portlet will use the search-root specified in the entity definition as the base and allow the user to drill down from there. If there is no search-root specified in the entity definition then it will use the root DN specified during the user application installation.

Naming Attribute

The naming attribute of the entity (the Relative Distinguished Name (RDN)). This value is only necessary for entities where the access parameter Create is selected.

Alternate Edit Entity

The attributes of the Edit Entity are displayed in the edit mode of the Detail portlet.

Choose an entity from the dropdown or <None> if this entity is not displayed by the Detail portlet.

Password Management properties

The Password Management Properties are:

Property name	Definition
Password Attribute	Choose the attribute where the password for this entity will be stored.
Password required when attribute is created	Selected—Means a password is required when this entity is created.

Using predefined parameters

The directory abstraction layer editor allows you to use predefined parameters for certain values. The parameters are:

Predefined parameter	Description
%driver-root%	Represents the Provisioning Driver DN. This value is specified during the user application configuration during installation or a later configuration. It is stored in the user application’s realm configuration.
%user-root%	Represents the User Container DN. This value is specified during the user application configuration during installation or a later configuration. It is stored in the user application’s realm configuration.
%group-root%	Represents the Group Container DN.This value is specified during the user application configuration during installation or a later configuration. It is stored in the user application’s realm configuration.

Attribute property reference

You can set the following kinds of properties on attributes:

Attribute access properties

The attribute access properties are:

Name	Description
Edit	Selected—This attribute can be edited/modified by the user application. Even if it is selected (true), the attribute might still not be editable if the underlying identity vault ACLs/effective rights prevent it.
Enable	Deselected—This attribute cannot be used by the user application. It is the same as removing the entry from the file.
Hide	Controls whether the Hide check box in the user application is enabled or disabled. The Hide check box allows users to control whether an attribute (such as their photo) is displayed by the application. Deselected—The Hide check box is disabled for this attribute, so the user cannot choose to hide this attribute. Selected—The Hide check box can be enabled in the user application. However, the following must also be true of the logged-in user. They: Are either the owner of the attribute or a User Application Administrator. Have Trustee rights to update the srvprvHideAttributes attribute on the identity vault. If these requirements are not met, then the Hide check box is disabled in the user interface even if this setting is selected (true). HINT:When a user hides an attribute that contains an image, users who have viewed the image might continue to see it until their browser cache is refreshed.
Multivalue	Specifies whether this attribute can be multivalued, for example, a phone number. Selected—the attribute can be multivalued.
Read	Selected—The user application can query this attribute. For most attributes this should be selected (true), but for some attributes, like password, it should be deselected.
Require	Selected—the attribute must be supplied.
Search	Selected—The user application can search on this attribute. Attributes that will be used in queries by identity portlets (such as Entity Search List or Entity Org Chart) must be selected. HINT:If an attribute used in a search is also indexed in eDirectory the search will be faster.
View	Selected—The user application can display this attribute. In most cases this would be true, but for some attributes, like password, it would probably be deselected.

Attribute required properties

Name	Description
Key	The unique identifier for the attribute.
Display Label	The label that is displayed in the user application.
Attribute Name	The NDS name for this attribute.
LDAP Name	The LDAP name for this attribute.

Attribute filter and format properties

Name	Description
Filter: WHERE Attribute	Lets you specify an LDAP filter on the identity vault search for this attribute.
Enable	Selected—Enables the filter.

Attribute UI control properties

Name	Description
Data Type	Choose a data type from the following list: Binary Boolean DN Integer LocalizedString String Time
Format Type	Used by the user application to format data. Format types include: None AOL IM Email Groupwise IM Image Phone Number Yahoo IM Image URL Date DateTime The Format Types are dependent on the data type. For example, a Time data type can only be associated with Date and DateTime formats.
Control Type	Types include: DNLookup—Defines that this attribute contains a DN reference. Use when you want to: Populate a list with the results of a DN search among related entities Maintain referential integrity across DN referenced attributes during updates and deletes The user application use this information to generate special user interface elements, and to perform optimized searches based on the DNLookup definition. For more information, see Using DNLookup control types
	Global List—Display this attribute as a dropdown list whose contents are defined in a file outside of this attribute definition. For more information, see Section 4.4, Working with lists.
	Local List—Display this attribute as a dropdown list whose contents are defined with this attribute. To define a local list: With the attribute selected, set the control type to Local List. Click the Add button to add more values. Use the up and down arrow buttons to change the position of the item in the list. In the Value column, type the value to write to the identity vault. It can only include lowercase letters, numbers, and underscore (_) characters. In the Labels column, type the text you want displayed in the user interface.
	Range—Use the Range control type with Integer data types to restrict user input to a sequential range of values. You’ll supply the range’s start and end values.

Using DNLookup control types

When you define a control type as a DNLookup, it means that:

Users can select from a list of possible values when searching on this attribute.
When this attribute is created, populated, or deleted an attribute on a related entity will be updated appropriately depending on the user action (create, delete, update) to maintain referential integrity.

DNLookups for selection lists

The installed user application contains entity definitions for Users and Groups. The Users entity definition contains an attribute called Group which is defined as a DNLookup control type. This enables any identity portlet to provide a selection list of groups for a particular user. For example, a user chooses to do a Directory Search. They want to find a user in a group, but they do not know the group name. They would select User as the object to search for and include Group as a search criteria as shown here:

Because Group is defined as a DNLookup control type for the User entity, the Lookup icon displays. If the user selects it, then a list of possible groups displays:

The user can select a group from the list.

DNLookups for referential integrity

DNLookups for updates and synchronization are important because LDAP allows group relationships to map in both directions. For example, your data might be set up so that:

User object contains a group attribute. The group attribute:
Is multi-valued
Lists all of the groups to which a user belongs
Group object contains a user attribute. The user attribute:
Is multi-valued
Lists all of the users that belong to the group

This means that you can have an attribute on the user object that shows all the groups a user belongs to, and on the Group object you have a DN attribute that includes all the members of that group.

When the user requests an update, the user application must honor the relationships and ensure that the target and source attributes are synchronized. In the DNLookup, you’ll specify both attributes that must be synchronized. You can use this technique to provide synchronization between any objects that are related not just group structural objects. You create this kind of DNLookup control type by specifying the advanced DNLookup properties described in the DNLookup Relational Integrity properties reference.

DNLookup property reference

The DNLookup Display properties are:

Field	Definition
Lookup Entity	The name of the entity to search, for example, the Task Group entity contains an attribute for Task Manager. To populate that field, you’d need to know which users are Task Managers.
Detail entity	The key of the entity whose details you want displayed if the user requests more information by clicking a hypertext link in the user application. When you define a DNLookup the identity portlets are able to provide a hypertext link that allows users to display the details of the linked object.
Attributes to display	Choose one or more attributes to display when the search is complete.
Perform Automatic Query	Defines how the Attributes to display (above) are displayed. Selected—Performs an automatic query of the entity and presents the results in a selectable list. You might not want to choose this option if the data returned will be a large number because it will force the user to scroll through a large result set. Deselected—allows the user to specify the search criteria for the entity query, then presents the results in a selectable list.

DNLookup Relational Integrity properties—These properties are used for synchronizing data between two objects such as groups and group members.

Property	Definition
Source attributes to update	Name of the attribute to update. The attribute must contain a DN reference to the Target attributes to update. This is required to synchronize attributes on two different objects.
Target attributes to update	Name of the attribute that must be updated along with the Source attributes to update.This is an LDAP attribute name. This is required to synchronize attributes on two different objects. The attribute must contain a DN reference.
Target auxiliary classes, if any	Name of the auxiliary class that contains the Target attributes to update.