Package com.ibm.itim.dataservices.model

Provides a a low-level application programming interface for querying elements of the data model.

See:
Description

Interface Summary

ManagableCategoryConstant	This class provides a list of pre-defined categories within the platform's data model.
ManagableProfile	This interface provides supports to allow customization of lifecycle management for entities Lifecycle management on the entities are defined in terms of operations on the entities.
ObjectProfileCategoryConstant	This class provides a list of pre-defined categories within the platform's data model.
ProtectedObject	Defines the base interface for all objects that are protected, thereby requiring authorized access.
Relationship	The Relationship interface provides the method signature of all relationship implementations in the data model.
SearchResults	Interface for retrieving the results of a search request.
SearchResultsIterator	Interface for iterating over a set of search results (see SearchResults).

Class Summary

AccessRight	Class that represents an access right, or Access Control Information (ACI).
AccessRightFactory	It should be noted that, like all other classes in the com.ibm.itim.dataservices package and its sub-packages, the AccessRightFactory class is not remote able.
AttributeRight	Class representing a right, or operation, that can be performed on a set of attributes.
AuthorizationOwner	Class representing a system user or role authorized to change access rights on a related entity.
CategoryTable
CompoundDN	The CompoundDN class represents a sequence of distinguished names that can be used to represent a series of related entities.
DirectoryEntry	Represents a raw directory entry.
DirectoryObject	Value Object class for a directory entry.
DirectoryObjectEntity	Class that represents an entry in the directory.
DirectoryObjectParent	The DirectoryObjectParent class implements the parent relationship to a DirectoryObjectEntity.
DirectoryObjectSearch	Class that provides searching capabilities for DirectoryObjects.
DistinguishedName	DistinguishedName represents the distinguishing name, or key, that uniquely identifies an entry in the ITIM data model.
EntityLifecycleProfile	This class implements the ManagableProfile interface for entities themselves.
LifecycleRule	Class that represents a lifecycle rule associated with an object profile.
ModelMetaData	The ModelMetaData provides an interface for discovering and querying meta-data about the data model.
ModelSchema	Class that provides an interface for retrieving schema information about entities within the data model.
ObjectProfile	Value Object class that holds the attribute data of an object profile.
ObjectProfileCategory	This class provides a list of pre-defined categories within the platform's data model.
ObjectProfileEntity	Class that describes how a class in the data store maps to a semantic entity in the system's data model.
ObjectProfileFactory	Factory class that creates object profiles in the data store.
ObjectProfileOperation	Value Object class that holds the attribute data of an object profile operation.
ObjectProfileOperationContentHandler	This class parses ObjectProfileOperation from xml string
ObjectProfileOperationFactory
ObjectProfileSearch	Class that provides an interface for searching for object profiles that reside in the data store.
OperationParameter	Value Object class that represents the operation parameter Support for formal parameter definition in profile operation is optional in this release Formal parameter specification allow design time type validation on the operation and its implementation
PartialResultsReason	Deprecated. Replaced by SearchResultsStatus.
Permission	Class that represents a permission within an AccessRight, or ACI.
ProfileLocator	Provides an interface for retrieving profiles (object and service) registered with the provisioning platform.
SearchParameters	Class that holds a set of parameters that can be used to further define how a search should be implemented against the data store.
SearchResultsStatus	Class that represents result information from search.
ServiceProfile	Value Object class that holds the attribute data of an object profile.

Exception Summary

DuplicateEntryException	DuplicateEntryException is a subclass of ModelCreationException used for errors that arise when attempting to create an entry in the data store and in case the entry already exists.
ModelCommunicationException	ModelCommunicationException is an exception class used for errors that arise due to communications issues.
ModelCreationException	ModelCreationException is an exception class used for errors that arise when attempting to create an entry in the data store for data model specific reasons.
ModelException	ModelException is the base Exception class for all published data model exceptions.
ModelIntegrityException	ModelIntegrityException is an exception class used for errors that arise due to issues with the integrity of the data model.
ModelModificationException	ModelModificationException is an exception class used for errors that arise due to failure of updating an object of the data model.
ModelRemoveException	ModelRemoveException is an exception class used for errors that arise due to failure of removing an object of the data model.
ObjectNotFoundException	ObjectNotFoundException is an exception class used when an entry that is searched for is not found.
PartialResultsException	PartialResultsException is an exception class used for errors that arise that result in only a portion of a data model request being completed.
SearchResultsException

Package com.ibm.itim.dataservices.model Description

Provides a a low-level application programming interface for querying elements of the data model.

Overview

The Data Services API has been developed to provide the developers of custom extensions to Identity Manager a portable and backwards-compatible interface to the Identity Manager data model.

The API consists of a set of java classes that abstract the more commonly used data model entities in the provisioning process, such as identities, accounts, and services. The classes that make up this API are the same classes the platform uses for its out-of-the-box feature set. A note about security: these classes communicate directly with the data store (directory server) using the platform’s credentials. Clients of this API will be assumed to have an appropriate level of trust. In fact, the platform credentials needed for this trust are obtained within the API code, which requires the client code to be executed within the platform’s environment. The easiest way to deploy client code within the platform’s environment is to have the platform call the code from its published extensions, such as authentication, workflow, and its JavaScript interpreter.

Although the ability to change the data model is provided within this API, it is very important to understand that this ability is not the focus of the API, and in fact, it is highly recommended that a client does not make changes to the data model through this API. The reason for this is that the Data Services API is a low level API that abstracts the physical layout of the data store (directory server), but does not provide a lot of the business logic that the provisioning applications within the platform do. For example, when adding a new person (identity) with the Data Services API, an entry is added to the data store only, but when adding a new person through the Identity Management application, the entry is added to the data store and the process of automatically provisioning the person is performed using the platform’s workflow engine. With that said, in limited situations this ability can safely be used as long as the client understands their effects. For example, the creation of containers in the org chart does not require any special provisioning business logic and can be safely done through this API.

API Description

The Data Services API consists of a set of classes that represent the commonly used entities within the Identity Manager data model and a set of classes. All of these classes can be found in the com.ibm.itim.dataservices.model package and its sub-packages.

An entity represents one entry of the data model, such as an identity, account, or service. Once a client obtains an instance of one of these entities, they can retrieve both Identity Manager specific attributes and custom attributes that describe it. An Identity Manager specific attribute is one that is used by Identity Manager for its internal business logic, such as an account’s status, or for navigating relationships, such as determining a business partner’s sponsor. A custom attribute is one that is not used within Identity Manager business logic, but is made available when the customer for business reasons extends the Identity Manager schema. Since these attributes may be relevant to business logic extensions making use of this API, an interface is provided to retrieve them. The UML class diagram in Figure 1 below illustrates the primary entities available in the API and their relationships. There are several more entities available in the API that are not shown in this diagram, but are documented in this package.

Figure 1 - Primary Entity Class Diagram

There is a consistent framework implemented in this API for querying and operating on entities along with their relationships (the framework is graphically depicted in figure 2 below). This framework is centered on the entity class itself. An entity class is a composite class that holds a reference to a value class that holds the defining attribute information for the entity, and provides access to other related entities with relationship-based interfaces. The relationships and attribute information are cached for the life of the entity, however, every time a relationship is evaluated, the entity, or entities, that participate in that relationship will be loaded from the data store. For example, the reference to the supervisor of a person is cached within the person entity class, but when the client requests the supervisor, the supervisor’s attribute information will be loaded from the data store at the time the supervisor entity is constructed.

To query for entities, the framework provides a search class for each type of entity. The search class will possibly provide canned queries as well as a filtered query where the client can create their own custom query criteria using a string representation of an LDAP filter (see RFC 2254).

To create a new entity in the data store, the framework provides a factory class for each type of entity. The factory class abstracts the physical placement and naming requirements of the data store implementation.

The deletion and modification of entities is made directly on the entity itself. The modification is made by passing an updated value object to the entity. It is important to note that the value object itself tracks the changes that have been made to it by the client. This is done for efficiency and to avoid confusion as to whether a missing attribute in a value object is due to it never being queried to start with (see the SearchParameters class and its use with search classes), or due to the client requesting it to be removed from the data store. Keep this in mind when passing value objects around in client code.

The evaluation of relationships in the data model is commonly achieved by using specific relationship-based methods on entity classes, such as getSupervisor() on a person entity. There is, however, support for additional relationships to be added to the data model to extend its capabilities for customization purposes. This can be achieved by creating a class to represent a relationship and registering it in the meta-data of the data model. Please see ModelMetaData and Relationship. Once registered, the relationship object can be obtained from an associated entity instance (see DirectoryObjectEntity) and evaluated.

Figure 2 - API Framework

API Example

The following method uses the Data Services API to print the accounts owned by a specified user.

public static void printAccounts(String rawIdentityDN) {

    try {

        // create compatible object from raw dn

        DistinguishedName identityDN = new DistinguishedName(rawIdentityDN);


        // obtain an Identity object needed to look up accounts

        PersonEntity identityEntity = new PersonSearch().lookup(identityDN);


        if (identityEntity != null) {

            // lookup accounts

            Collection accounts = identityEntity.getAccounts();

            Iterator iter = accounts.iterator();

            // loop through accounts and print user id and service name

            while (iter.hasNext()) {

                AccountEntity accountEntity = (AccountEntity)iter.next();

                Account account = (Account)accountEntity.getDirectoryObject();

                ServiceEntity serviceEntity = accountEntity.getService();

                Service service = (Service)serviceEntity.getDirectoryObject();


                System.out.println("*****Account*****");

                System.out.println("User Id: " + account.getUserId());

                System.out.println("Service: " + service.getName());

                System.out.println();

            }

        }

    } catch (ModelCommunicationException mce) {

        System.err.println("Communication Exception: " + mce.toString());

    } catch (ObjectNotFoundException onfe) {

        System.err.println("Object Not Found Exception: " + onfe.toString());

    }

}