| Oracle® Fusion Middleware Developer's Guide for Oracle Identity Manager 11g Release 1 (11.1.1) E14309-05 |
|
 Previous |
 Next |
| Oracle® Fusion Middleware Developer's Guide for Oracle Identity Manager 11g Release 1 (11.1.1) E14309-05 |
|
Previous |
Next |
Oracle provides a network-aware, Java-based application programming interface (API) that exposes Services, called Utility in earlier releases, available in Oracle Identity Manager. This API is based on Plain Old Java Objects (POJO) and takes care of all the plumbing required to interact with Oracle Identity Manager. This API can be used for building clients for Oracle Identity Manager and for integrating third-party products with the Oracle Identity Manager platform.
This chapter contains these sections:
For information about the reconciliation APIs in Oracle Identity Manager 11g Release 1 (11.1.1), see "Reconciliation APIs".
The entry point to Oracle Identity Manager Services is through oracle.iam.platform.OIMClient class. Thor.API.tcUtilityFactory used in earlier releases is also supported. Oracle recommends using the oracle.iam.platform.OIMClient for developing clients to integrate with Oracle Identity Manager.
This section describes the following topics:
OIMClient is the entry point for accessing the services available in Oracle Identity Manager. You use the following sequence of steps when using OIMClient:
Create an instance of OIMClient with the environment information required to connect to Oracle Identity Manager application, as shown:
Hashtable env = new Hashtable(); env.put(OIMClient.JAVA_NAMING_FACTORY_INITIAL, "weblogic.jndi.WLInitialContextFactory"); env.put(OIMClient.JAVA_NAMING_PROVIDER_URL, http://OIM_HOSTNAME:OIM_PORT); OIMClient oimClient = new OIMClient(env);
Here, replace OIM_HOSTNAME with the host name on which Oracle Identity Manager is deployed and OIM_PORT with the port number.
Login to the Oracle Identity Manager with the appropriate credentials, as shown:
oimClient.login(OIM_USERNAME, OIM_PASSWORD);
Lookup a service, as shown:
UserManager usermgr = oimClient.getService(UserManager.class);
Load operations on a service, as shown:
HashMap userAttributes = new HashMap(); …………….. UserManagerResult result = userMgr.create(new User(null, userAttributes));
Earlier releases of Oracle Identity Manager supports tcUtilityFactory for accessing Oracle Identity Manager Services (or Utilities, as they are called in legacy releases). tcUtilityFactory continues to be supported. However, as mentioned earlier, Oracle recommends using OIMClient for building all client applications for Oracle Identity Manager.
You use the following sequence of steps when using tcUtilityFactory:
Create an instance of tcUtilityFactory with the environment information, such as username and password, as shown:
tcUtilityFactory ioUtilityFactory = new tcUtilityFactory(env, "OIM_USERNAME", "OIM_PASSWORD"); }
Look up utility or service by providing the fully qualified name of the utility, as shown:
tcUserOperationsIntf moUserUtility = (tcUserOperationsIntf)ioUtilityFactory.getUtility("Thor.API.Operations.tcUserOperationsIntf");
Run operations on the utility, as shown:
Hashtable mhSearchCriteria = new Hashtable();
mhSearchCriteria.put("Users.First Name", psFirstName);
tcResultSet moResultSet = moUserUtility.findUsers(mhSearchCriteria);
The Oracle Identity Manager API provides access to services available in Oracle Identity Manager. Because the APIs introduced in 11g Release 1 (11.1.1) and the legacy APIs use different conventions, this section discusses them separately in the following topics:
Services introduced in Oracle Identity Manager 11g Release 1 (11.1.1) follow the following conventions:
Package Names: Services are in packages whose names end with "api", for example:
oracle.iam.request.api oracle.iam.identity.usermgmt.api
Service Interface Names: Services introduced in 11g typically use the naming convention of "*Service", for example:
oracle.iam.request.api.RequestService oracle.iam.selfservice.self.selfmgmt.api.AuthenticatedSelfService
Some Identity Administration APIs use the "*Manager" naming convention for their APIs, for example:
oracle.iam.identity.usermgmt.api.UserManager
Legacy services, also called utilities, follow the following naming conventions
Package Names: All legacy APIs are in Thor.API.Operations package.
Service Interface Names: Service names are of the form "*Intf", for example, Thor.API.Operations.tcImportOperationsIntf.
|
See Also: Oracle Fusion Middleware Java API Reference for Oracle Identity Manager for a full list of services available in Oracle Identity Manager. You can use the naming conventions above to find the APIs. |
Table 28-1 lists some commonly used services in Oracle Identity Manager.
Table 28-1 Commonly Used Services
| Service Name | Description |
|---|---|
|
UserManager |
Provides operations for user management, such as create, search, modify, and delete users |
|
RequestService |
Provides operation to submit, withdraw, close, and search requests Note: Using the request template service, when you search for a request template that does not exist, a null value is returned. |
|
RoleManager |
Provides operations for managing roles |
In Oracle Identity Manager 11g Release 1 (11.1.1), some of the legacy APIs have been rewritten by using new architecture and the corresponding utility services or interface classes have been changed. Table 28-2 provides a high-level correspondence between the legacy and new interfaces.
Table 28-2 Mapping Between Legacy and New Services
| Legacy Service | New Service |
|---|---|
|
Thor.API.Operations.tcUserOperationsIntf |
oracle.iam.identity.usermgmt.api.UserManager |
|
Thor.API.Operations.tcGroupOperationsIntf |
oracle.iam.identity.rolemgmt.api.RoleManager |
|
Thor.API.Operations.tcOrganizationOperationsIntf |
oracle.iam.identity.orgmgmt.api. OrganizationManager |
|
Thor.API.Operations.tcRequestOperationsIntf |
oracle.iam.request.api.RequestService |
|
Thor.API.Operations.tcSchedulerOperationsIntf |
oracle.iam.scheduler.api.SchedulerService |
|
Thor.API.Operations.tcEmailOperationsIntf |
oracle.iam.notification.api.NotificationService |
This section includes the following topics:
The following prerequisites must be met for developing clients for Oracle Identity Manager:
Java Development Kit (JDK) 1.6 installed and set in the path
ANT 1.7 installed and set in the path
Oracle Identity Manager package contains a ZIP file that contains the required libraries and configuration files for developing clients. It also contains a sample client, which you can use as the starting point for developing your application.
To run an application client for Oracle Identity Manager:
Copy OIM_ORACLE_HOME/server/client/oimclient.zip to the computer on which you want to develop the client, for example the oimclient/ directory. This directory is referred to as OIM_CLIENT_HOME in this document. Extract the ZIP file. Note that the oimclient.zip file consists of the conf, lib, sample, directories, oimclient.jar, and README.
Copy the application server-specific client library to the OIM_CLIENT_HOME/lib/ directory. For Oracle WebLogic Server, wlfullclient.jar is the client library. It is created in MIDDLEWARE_HOME/WL_HOME/server/lib/ directory, for example, /scratch/beahome/wlserver_10.3/server/lib/. Check if wlfullclient.jar is present. If not, then you must generate one by using the jarbuilder tool. See Oracle WebLogic Server documentation on how to generate wlfullclient.jar.
Edit and run the sample client. To do so:
Open the OIM_CLIENT_HOME/sample/src/oracle/iam/samples/SampleOIMClient.java sample client file.
Edit the following constants to point to the host on which Oracle Identity Manager is displayed:
OIMURL: The URL of the Oracle Identity Manager host computer
OIMUserName: Administrator username for Oracle Identity Manager
OIMPassword: Administrator password for Oracle Identity Manager
Run the ant command. This compiles and runs the sample client. The sample generates the following output when it runs successfully:
[java] LOGGER >> Creating client.... [java] LOGGER >> Logging in [java] LOGGER >> Log in successful [java] LOGGER >> User Created
This section describes the following topics:
Legacy Oracle Identity Manager APIs extensively use the tcResultSet interface. The Thor.API.tcResultSet interface is a data structure that stores records retrieved from the database. Methods in the Oracle Identity Manager API that must return a set of data use a result set. This is a two-dimensional data structure in which the columns correspond to the attributes and rows correspond to the entities. For example, a result set that is returned by the method that searches for users, each row would represent data pertaining to one user, and each column in the row would be an attribute for that user.
You can scroll through the result set and retrieve individual entries corresponding to particular attributes by using the various methods provided. To locate a particular row in the result set, use the goToRow() method with the row number as a parameter. To retrieve the values for the columns from a row, use appropriate accessor methods, such as getStringValue(). To obtain the value from a specific column, pass the column name as a parameter to the accessor method. The column name is the descriptive code defined in the Oracle Identity Manager Meta-Data system.
The following table shows some sample metadata values. This mapping is based on lookup codes and can be looked up in the Design Console by using the Lookup Definition Form.
| Column Code | Explanation |
|---|---|
| IT Resources.Name | The name of an IT resource |
| Process Definition.Name | The name of a provisioning process |
|
Note: Keep track of the result set objects that are retrieved, because they will be required when updating an existing record. |
The following is an example of how to use a result set. This example obtains a result set by calling the findAllUsers() method. This method searches for all users matching certain criteria:
tcResultSet moResultSet = moUserUtility.findAllUsers(mhAttribs);
To check if the findAllUsers() method returned any records, use the isEmpty() method, for example:
boolean mbEmpty = moResultSet.isEmpty();
To retrieve the number of records found, use the getRowCount() method. If no records are found, then the method returns 0. The following is an example:
int mnNumRec = moResultSet.getRowCount();
To select a particular record in the system, use the goToRow() method:
moResultSet.goToRow(5);
To retrieve the values of attributes from the current row, use the appropriate accessor method, for example:
String msUserLastName = moResultSet.getStringValue("Users.Last Name");
The API methods throw Oracle-defined Java exceptions. Instead of using the getMessage() method on the exception object received, you can access the isMessage internal variable to retrieve the exception message.
The tcUtilityFactory class manages all resources used by a utility or factory instance and provides a means to release these resources after they are used.
If you instantiate and use tcUtilityFactory to obtain utility class instances, to release the resources that are associated with the utility class, call the close(utility Object) method on the factory class. If the session has ended, then call the close() method on the factory instance to release all the utility classes, the session objects, and the database objects.
If you obtain a utility class directly by using static calls, after the utility object is no longer needed, call the close(object) method on the utility object.
Example 28-1 illustrates how to retrieve Oracle Identity Manager information. This example creates an instance of the factory class. The instance is then employed several times to retrieve individual utility classes and use them to retrieve Oracle Identity Manager information.
Example 28-1 Retrieving Oracle Identity Manager Information
/** The factory instance. */
OIMClient oimClient;
public void init(){
String ctxFactory = "weblogic.jndi.WLInitialContextFactory";
String serverURL = "t3://OIM_HOSTNAME:OIM_PORT";
Hashtable env = new Hashtable();
env.put(OIMClient.JAVA_NAMING_PROVIDER_URL, serverURL);
env.put(OIMClient.JAVA_NAMING_FACTORY_INITIAL,ctxFactory);
OIMClient oimClient = new OIMClient(env);
oimClient.login(username, password);
}
/** Retrieves user login based on the first name. */
public List getUserLogin(String psFirstName){
Vector mvUsers=new Vector();
UserManager usrService = clientPlatform.getService(UserManager.class);
Set<String> retAttrs = new HashSet<String>();
retAttrs.add("User Login");
SearchCriteria criteria;
Set<String> searchAttrs;
criteria = new SearchCriteria("First Name", psFirstName,
SearchCriteria.Operator.EQUAL);
List<User> users = userMgmt.search(criteria, retAttrs, null);
for (int i=0; i< users.size(); i++){
mvUsers.add(users.get(i).getLogin());
}
}
/** Retrieves the administrators of an organization based on the organization
name. */
public List getAdministratorsOfOrganization(String psOrganizationName){
Vector mvOrganizations=new Vector();
tcOrganizationOperationsIntf moOrganizationUtility =
clientPlatform.getService("Thor.API.Operations.tcO
rganizationOperationsIntf");
Hashtable mhSearchCriteria = new Hashtable();
mhSearchCriteria.put("Organizations.Organization Name", psOrganizationName);
tcResultSet moResultSet =
moOrganizationUtility.findOrganizations(mhSearchCriteria);
tcResultSet moAdmins;
for (int i=0; i<moResultSet.getRowCount(); i++){
moResultSet.goToRow(i);
moAdmins=moOrganizationUtility.getAdministrators(moResultSet.getLongValue("Org
anizations.Key"));
mvOrganizations.add(moAdmins.getStringValue("Groups.Group Name"));
}
}
public void example(){
List moList;
// initialize resources
init();
// retrieve user logins with first name 'Joe'
moList=getUserLogin("Joe");
// retrieve user logins with first names starting with 'D'
moList=getUserLogin("D*");
// retrieve the administrators of an organization with name 'Example
Organization'
moList=getAdministratorsOfOrganization("Example Organization");
// release resources
oimClient.logout();
}
This section introduces the reconciliation APIs.
The reconciliation APIs are a set of published APIs that can be used to create reconciliation events with single-valued and multi-valued attribute data and other features.
Reconciliation connector developers must use these APIs to push data to the reconciliation event repository.
Most of these APIs existed in earlier versions of Oracle Identity Manager. However, in 11g Release 1 (11.1.1), the implementation has changed and is based on the new reconciliation architecture introduced in the release.
Existing standard connectors also use these APIs; since the earlier APIs continue to be supported, no changes are necessary to those connectors.
callingEndOfJobAPI is the only new reconciliation API in 11g Release 1 (11.1.1).
Each run of a connector is known as a job. In 11g Release 1 (11.1.1), reconciliation events are submitted to the reconciliation engine in batches. At the end of a job, the scheduler (which executes the connector scheduled task) executes a listener, which in turn invokes the callingEndOfJOBAPI. This API submits any open batch for processing to the reconciliation engine.
The API calls are similar for Multilanguage Supported (MLS) and non-MLS data. The connector passes in data to be reconciled as a HashMap. The difference is that if an attribute is MLS-enabled, then the key is the attribute name, while the value is another HashMap of MLS data. The keys of this MLS-specific HashMap are language codes, and the values are the corresponding locale-specific data obtained from target system. If there is any MLS data that does not have a locale defined with it in the target system, that data is passed with key "base" in the MLS input data HashMap.
|
 Copyright © 1991, 2011, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|