Using APIs

19.1 About Oracle Identity Governance APIs

Oracle provides a network-aware, Java-based application programming interface (API) that exposes Services available in Oracle Identity Governance.

This API is based on Plain Old Java Objects (POJO) and takes care of all the plumbing required to interact with Oracle Identity Governance. This API can be used for building clients for Oracle Identity Governance and for integrating third-party products with the Oracle Identity Governance platform.

Note:

In this release, Oracle Identity Governance does not support the following:

Legacy APIs
Signature-based login

19.2 Accessing Oracle Identity Governance Services

You can use the OIMClient class for developing clients to integrate with Oracle Identity Manager.

This section describes Oracle Identity Manager services and how to use the services to develop clients to integrate with Oracle Identity Manager.

It contains the following topics:

19.2.1 About Oracle Identity Governance Services

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.

19.2.2 Using OIMClient

Using OIMClient involves creating an instance of OIMClient, looking up a service, and calling method on a service.

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, t3://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);
OR
tcLookupOperationsIntf lookupIntf = oimClient.getService(tcLookupOperationsIntf.class);

Call method on a service, as shown:

HashMap userAttributes = new HashMap();
……………..
UserManagerResult result = userMgr.create(new User(null, userAttributes));

19.2.3 Using OIMClient and tcUtilityFactory in Integrated Deployments

Using OIMClient and tcUtilityFactory in integrated deployments can be done by using OPSS Framework or by invoking the OIMClient API.

In Oracle Identity Manager deployment that is integrated with Access Manager (OAM), OIMSignatureAuthenticator is not configured in the Oracle Identity Manager domain's security realm. Therefore, all the custom or partner applications that you want to integrate with Oracle Identity Manager must not use signature-based login to Oracle Identity Manager. Instead, you must follow any one of the following approaches:

Oracle Platform Security Services (OPSS) Framework: If the partner or client application is a J2EE application based on Fusion Middleware stack, then it can use the following from OPSS framework:

Note:

See Introduction to Oracle Platform Security Services in the Application Security Guide for information about OPSS and its main features
- OPSS credential store: This allows credentials to be managed (store, retrieve, modify) in a secure manner. You can store the password in the OPSS credential store, and retrieve it while performing a Oracle Identity Manager client login by using user ID and password. See Managing the Credential Store in the Application Security Guide for more information about OPSS credential store.
- OPSS SubjectSecurity API: If a partner application wants to invoke Oracle Identity Manager EJB/Service APIs with a higher privilege, such as system administrator user, then OPSS SubjectSecurity API can be used. The following sample partner application code tries to invoke Oracle Identity Manager API with higher privilege:
  
  See Also:
  
  Oracle Fusion Middleware Java API Reference for Oracle Platform Security Services for detailed information about the SubjectSecurity API
```
//Get ActionExecutor for OIM System administrator, xelsysadm
ActionExecutor actionExecutor = SubjectSecurity.getInstance().getActionExecutor("xelsysadm");
actionExecutor.execute(new PrivilegedAction<Object>() {
  public Object run() {
       //OIM EJB method invocation goes here….
                   Hashtable env = new Hashtable();
      //serverURL – OIM server's RMI URL
                   // ctxFactory – WLS/WAS context factory class
         env.put(OIMClient.JAVA_NAMING_PROVIDER_URL, serverURL);
         env.put(OIMClient.JAVA_NAMING_FACTORY_INITIAL,ctxFactory);
         OIMClient client = new OIMClient(env);
  //Invoking EJB service method as "xelsysadm"
         RequestService reqSrvc = client.getService(RequestService.class);
         reqSrvc.getBasicRequestData("1");//1 is the request ID.
              }
});
```
If using the OPSS framework is not possible for some reason, then it is recommended to invoke the OIMClient API with user ID and password. However, it is up to the client or partner to store and manage the Oracle Identity Manager user's password in a secure manner.

19.3 Oracle Identity Governance Services

The Oracle Identity Manager API provides access to services available in Oracle Identity Manager.

Because the APIs in Oracle Identity Manager 11g Release 1(11.1.1) onwards and the legacy APIs use different conventions, this section discusses them separately in the following topics:

19.3.1 Services in Oracle Identity Governance

Services are based on conventions related to package names and service interface names.

Services in Oracle Identity Manager 11g onwards are based on 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
```

Some new services introduced in Oracle Identity Manager are:

oracle.iam.api.OIMService
oracle.iam.platform.authopss.api.AuthorizationService
oracle.iam.provisioning.api.ProvisioningService
oracle.iam.provisioning.api.ApplicationInstanceService

19.3.2 Legacy Services or Utilities

Utilities follow naming conventions related to package names and service interface names.

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.

19.4 Commonly Used Services

Some commonly used services are UserManager, RequestService, RoleManager, OrganizationManager, and oracle.iam.api.OIMService.

Table 19-1 lists some commonly used services in Oracle Identity Manager.

Table 19-1 Commonly Used Services

Service Name	Description
UserManager	Provides operations for user management, such as create, search, modify, and delete users
RequestService	Provides operations to submit, withdraw, close, and search requests.
RoleManager	Provides operations for role management such as create, search, modify, and delete roles. In addition, this service provides operations for management of role members and relationships between roles.
OrganizationManager	Provides operations for organization management such as create, search, modify, delete, enable, and disable organizations.
oracle.iam.api.OIMService	Provides method to perform an operation in Oracle Identity Manager. You can pass an intent while calling API of this service. Intent here can be request or direct.

19.5 Mapping Between Legacy and New Services

In Oracle Identity Manager, some of the legacy APIs have been rewritten by using new architecture and the corresponding utility services or interface classes have been changed.

Table 19-2 provides a high-level correspondence between the legacy and new interfaces.

Table 19-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 Note: The Group Manager APIs related all delegated admin APIs for adding and removing admins have been deprecated.	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

19.6 Working With Legacy Oracle Identity Manager APIs

Legacy Oracle Identity Manager APIs extensively use the tcResultSet interface.

This section describes how to use the result set. It contains the following topics:

19.6.1 Using a Result Set Object

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.

19.6.2 Example of Using a Result Set

Understand the example that obtains a result set by calling the findAllUsers() method. This method searches for all users matching certain criteria.

The following is an example of how to use a result set.

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");

19.6.3 Handling Oracle Identity Manager Exceptions

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.

19.6.4 Cleaning Up

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.

19.7 Code Samples

Understand code samples for retrieving information and using Certification and OIMService APIs.

This section contains the following code samples:

19.7.1 Retrieving Oracle Identity Governance Information

Understand the example that creates an instance of the factory class. The instance is then called several times to retrieve individual utility classes and use them to retrieve Oracle Identity Governance information.

To retrieve Oracle Identity Governance information:

As a prerequisite, make sure that the following JAR files are in the classpath for API execution:

$MW_HOME/oracle_common/modules/oracle.jrf/jrf-api.jar
$MW_HOME/idm/designconsole/lib/oimclient.jar
$MW_HOME/oracle_common/modules/thirdparty/spring-context-4.3.20.RELEASE.jar
$MW_HOME/oracle_common/modules/org.apache.commons.logging_1.2.jar
$MW_HOME/idm/server/idmdf/idmdf-common.jar
$MW_HOME/wlserver/server/lib/wlthint3client.jar
$MW_HOME/oracle_common/modules/thirdparty/spring-core-4.3.20.RELEASE.jar

Run the following command to execute the code:

$JAVA_HOME/bin/java -Djava.security.policy=$DC_HOME/config/xl.policy -Djava.security.auth.login.config=$DC_HOME/config/authwl.conf  -DAPPSERVER_TYPE=wls -cp $CLASSPATH Sample

The following example illustrates how to retrieve Oracle Identity Manager information.

/*
 This class is intented to showcase some of OIM API's. These API's are 
 specific to OIM 11g release. As an example, Legacy API's usage for
 Organization is also shown. 
*/

// Role related API's
import oracle.iam.identity.rolemgmt.api.RoleManager;
import oracle.iam.identity.rolemgmt.vo.Role;
import oracle.iam.identity.exception.RoleSearchException;
import oracle.iam.identity.rolemgmt.api.RoleManagerConstants.RoleAttributeName;
import oracle.iam.identity.rolemgmt.api.RoleManagerConstants.RoleCategoryAttributeName;
 
// User related API's
import oracle.iam.identity.usermgmt.api.UserManager;
import oracle.iam.identity.usermgmt.vo.User;
import oracle.iam.identity.exception.UserSearchException;
import oracle.iam.identity.usermgmt.api.UserManagerConstants.AttributeName;
 
// Organization Legacy API's
import Thor.API.Operations.tcOrganizationOperationsIntf;
import Thor.API.tcResultSet;
import Thor.API.Exceptions.tcAPIException; 
import Thor.API.Exceptions.tcColumnNotFoundException; 
import Thor.API.Exceptions.tcOrganizationNotFoundException; 
 
import oracle.iam.platform.OIMClient;
import oracle.iam.platform.authz.exception.AccessDeniedException;
import oracle.iam.platform.entitymgr.vo.SearchCriteria;
 
import java.util.*;
 
import javax.naming.NamingException;
import javax.security.auth.login.LoginException;
 
 
public class Sample {
 
     private static OIMClient oimClient;
 
     /*
      * Initialize the context and login with client supplied environment
     */
     public void init() throws LoginException {
        System.out.println("Creating client....");
        String ctxFactory = "weblogic.jndi.WLInitialContextFactory";
        String serverURL = "t3://OIM_HOSTNAME:OIM_PORT";
        String username = "xelsysadm";
        char[] password = "xelsysadm".toCharArray();
        Hashtable env = new Hashtable();
        env.put(OIMClient.JAVA_NAMING_FACTORY_INITIAL,ctxFactory);
        env.put(OIMClient.JAVA_NAMING_PROVIDER_URL, serverURL);
 
        oimClient = new OIMClient(env);
        System.out.println("Logging in");		
        oimClient.login(username, password);
        System.out.println("Log in successful");
     }
 
     /**
     * Retrieves User login based on the first name using OIM 11g 
     * UserManager service API. 
     */
     public List getUserLogin(String psFirstName) {
        Vector mvUsers = new Vector();
        UserManager userService = oimClient.getService(UserManager.class); 
        Set<String> retAttrs = new HashSet<String>();
 
        // Attributes that should be returned as part of the search. 
        // Retrieve "User Login" attribute of the User.
        // Note: Additional attributes can be specified in a 
        // similar fashion.
        retAttrs.add(AttributeName.USER_LOGIN.getId());
 
        // Construct a search criteria. This search criteria states 
        // "Find User(s) whose 'First Name' equals 'psFirstName'".  
        SearchCriteria criteria;
        criteria = new SearchCriteria(AttributeName.FIRSTNAME.getId(), psFirstName, SearchCriteria.Operator.EQUAL);
        try {
            // Use 'search' method of UserManager API to retrieve 
            // records that match the search criteria. The return 
            // object is of type User. 
            List<User> users = userService.search(criteria, retAttrs, null);
			
            for (int i = 0; i < users.size(); i++) {
                //Print User First Name and Login ID 
                System.out.println("First Name : " + psFirstName + "  --  Login ID : " + users.get(i).getLogin());
                mvUsers.add(users.get(i).getLogin());
            }
        } catch (AccessDeniedException ade) {
            // handle exception
        } catch (UserSearchException use) {
            // handle exception
        }
       return mvUsers;
    }
 
    /** 
     * Retrieves the administrators of an Organization based on the 
     * Organization name. This is Legacy service API usage. 
     */
    public List getAdministratorsOfOrganization(String psOrganizationName) {
        Vector mvOrganizations = new Vector();
        tcOrganizationOperationsIntf moOrganizationUtility = oimClient.getService(tcOrganizationOperationsIntf.class);
        Hashtable mhSearchCriteria = new Hashtable();
        mhSearchCriteria.put("Organizations.Organization Name", psOrganizationName);
        try {
            tcResultSet moResultSet = moOrganizationUtility.findOrganizations(mhSearchCriteria);
            tcResultSet moAdmins;
            for (int i = 0; i < moResultSet.getRowCount(); i++) {
                moResultSet.goToRow(i);
                moAdmins = moOrganizationUtility.getAdministrators(moResultSet.getLongValue("Organizations.Key"));
                mvOrganizations.add(moAdmins.getStringValue("Groups.Group Name"));
                System.out.println("Organization Admin Name : " + moAdmins.getStringValue("Groups.Group Name"));
            }
        } catch (tcAPIException tce) {
            // handle exception
        } catch (tcColumnNotFoundException cnfe) {
            // handle exception
        } catch (tcOrganizationNotFoundException onfe) {
            // handle exception
        }
        return mvOrganizations;
    }
 
    /**
     * Retrieves Role Display Name based on Role name and Role Category 
     * using OIM 11g RoleManager service API. This example shows how 
     * to construct compound search criteria.
     */
    public List getRoleDisplayName(String roleName, String roleCategory ) {
        Vector mvRoles = new Vector();
        RoleManager roleService = oimClient.getService(RoleManager.class); 
        Set<String> retAttrs = new HashSet<String>();
 
        // Attributes that should be returned as part of the search. 
        // Retrieve the "Role Display Name" attribute of a Role.
        // Note: Additional attributes can be specified in a 
        // similar fashion.
        retAttrs.add(RoleAttributeName.DISPLAY_NAME.getId());
 
        // Construct the first search criteria. This search criteria 
        // states "Find Role(s) whose 'Name' equals 'roleName'".  
        SearchCriteria criteria1;
        criteria1 = new SearchCriteria(RoleAttributeName.NAME.getId(), roleName, SearchCriteria.Operator.EQUAL);
 
        // Construct the second search criteria. This search criteria 
        // states "Find Role(s) whose 'category' equals 'roleCategory'".  
        SearchCriteria criteria2;
        criteria2 = new SearchCriteria(RoleCategoryAttributeName.NAME.getId(), roleCategory, SearchCriteria.Operator.EQUAL);
		
        // Construct the compound search criteria using 'criteria1' and 
        // 'criteria2' as arguments. This showcases how to construct
        // compound search criterias. 
        SearchCriteria criteria = new SearchCriteria(criteria1, criteria2, SearchCriteria.Operator.AND);
        try {
            // Use 'search' method of RoleManager API to retrieve 
            // records that match the search criteria. The return 
            // object is of type Role. 
            List<Role> roles = roleService.search(criteria, retAttrs, null);
 
            for (int i = 0; i < roles.size(); i++) {
                //Print Role Display Name
                System.out.println("Role Display Name : " + 
                    roles.get(i).getDisplayName());
                mvRoles.add(roles.get(i).getDisplayName());
            }
        } catch (AccessDeniedException ade) {
            // handle exception
        } catch (RoleSearchException use) {
            // handle exception
        }
        return mvRoles;
    }
 
    // Main method invocation 
    // Following assumptions are made
    //1. A User "Joe Doe" already exists in OIM
    //2. An Organization  "Example Organization" already exists in OIM
    //3. A Role "Foobar" already exists in OIM
    public static void main(String args[]) {
        List moList = null;
	
        try {
            Sample oimSample = new Sample();
 
            // initialize resources
            oimSample.init();
            // retrieve User logins with first name 'Joe'
            moList=oimSample.getUserLogin("Joe");
            // retrieve User logins with first names starting with 'J'
            moList=oimSample.getUserLogin("J*");
            // retrieve the administrators of an Organization with name 
            // 'Example Organization'
            moList=oimSample.getAdministratorsOfOrganization(
                "Example Organization");
            // retrieve Role display name with role name 'FooBar'
            // and role category as 'Defaut' 
            moList=oimSample.getRoleDisplayName("foobar", "Default");
            // release resources
            oimClient.logout();
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

The following is the sample output:

[java] Creating client....
[java] Logging in
[java] Log in successful
[java] First Name : Joe  --  Login ID : JDOE
[java] First Name : J*  --  Login ID : JHOND
[java] First Name : J*  --  Login ID : JDOE
[java] Organization Admin Name : SYSTEM ADMINISTRATORS
[java] Role Display Name : foobar

19.7.2 Using Certification APIs

Understand code examples for retrieving certifications belonging to a user, retrieving application instance certification, certifying or denying certifications, and completing the certification.

This section provides code examples for using APIs related to certification, such as CertificationService. It contains the following topics:

19.7.2.1 Retrieving Certifications Belonging to a User

The following example provides the code sample to get certifications belonging to a user.

public List<CertificationInstance> findCertifications(SearchCriteria
searchCriteria, Set<String> retAttrs, Map<String,Object> configParams) throws
CertificationServiceException;
Example of searchCriteria to use:
  SearchCriteria searchCriteria1 = new
SearchCriteria(CertificationConstants.CERTIFICATION_SEARCH_FIELDPRIMARY_REVIEW
ER_ID, userKey, SearchCriteria.Operator.EQUAL);
  SearchCriteria searchCriteria2 = new
SearchCriteria("certificationStatusForQuery",
CertificationConstants.STATE_IN_PROGRESS.toString(),
SearchCriteria.Operator.EQUAL);
  SearchCriteria searchCriteria = new SearchCriteria(searchCriteria1,
searchCriteria2, SearchCriteria.Operator.AND);

19.7.2.2 Retrieving an Application Instance Certification

The following example provides the code sample to retrieve an application instance certification.

public List<IDCAccountAttributeAndRoleWrapper> loadBatchUserEntitlements(LongcertificationId, String taskUid, Long userId, PaginationContext context,SearchCriteria searchCriteria) throws CertificationServiceException;

19.7.2.3 Certifying or Denying Certifications

The following example provides the code sample to certify or deny entitlements.

public void certifyUserEntitlements(Long certId, String taskUid, Long
userEntityId, Set<Long> roleEntityIds, Set<Long> accountEntityIds, Set<Long>
accountAttributeEntityIds, Integer certified, Date statusEndDate, String
comments) throws CertificationServiceException;

19.7.2.4 Completing the Certification

The following example provides the code sample to complete the certification.

public CertificationInstance completeCertification(final Long certificationId, String taskUid, char[] cleartextPassword)

19.7.3 Using OIMService API

Construct the RequestData object and understand examples of OIMService API usage for invoking operations through OIMService API.

This section lists the sample usage for few operations by using the OIMService API. It contains the following topics:

19.7.3.1 RequestData Object Construction

For invoking the operations supported through OIMService API, you must first construct the RequestData object.

This section describes the RequestData object construction. It contains the following topics:

19.7.3.1.1 Constructing RequestData Object for Operations Involving Target User and Cart Item

For all the operations that involve target user and cart item, such as role, application instance, or entitlement, construct the RequestData object as follows:

Create an instance of the RequestData object.
Create List of Beneficiary object(s), set the fields, and associate the object with RequestData object by invoking:
```
requestData.setBeneficiaries();
```
Create List of RequestBeneficiaryEntity object(s), and set the cart item data, such as entity type, entity key, and operation. Associate the object with Beneficiary object by invoking:
```
beneficiary.setTargetEntities();
```
The entityKey, which is set by using the entity.setEntityKey() method for a given operation, must be based on Table 19-3.
Create List of RequestBeneficiaryEntityAttribute object(s), and set the attribute name and value in each object. Associate the object with the entity object by invoking entity.setEntityData().This is required only if the cart item is associated with a form.
Note:
- RequestData.setTargetEntities() must not be used in this scenario.
- See Samples of OIMService API Usagefor more details on OIMService API usage.

19.7.3.1.2 Constructing RequestData Object for Operations Involving the User Entity

For all the operations that involve only the User entity, such as Create User, Modify User, Enable User, Disable User, and Delete User, the RequestData object must be populated as follows:

Create an instance of the RequestData object.
Create List of RequestEntity object(s) by setting entity type, entity key, and operation. Entity key must be set as user key for all the operations exception Create User.
Create List of RequestEntityAttribute object(s), and set attribute name and value in each object. This is required only for Create User and Modify User operations.

19.7.3.1.3 Operations and Entity Keys

Table 19-3 lists the operations and corresponding entity keys that are set by using the entity.setEntityKey() method.

Table 19-3 Operation and entityKey

Operation	entityKey
Provision Application Instance	Application Instance Key
Modify Account	Account Key
Revoke Account	Account Key
Enable Account	Account Key
Disable Account	Account Key
Provision Entitlement	Entitlement Key
Modify Entitlement	Entitlement Instance Key
Revoke Entitlement	Entitlement Instance Key

19.7.3.2 Samples of OIMService API Usage

Understand code samples of revoking an account and creating a user by using OIMService API.

This section provides code samples of using the OIMService API. It contains the following topics:

19.7.3.2.1 Revoking an Account

The following is a code sample for revoking an account:

RequestData requestData = new RequestData();
Beneficiary beneficiary = new Beneficiary();
beneficiary.setBeneficiaryKey("12"); //User with key 12
beneficiary.setBeneficiaryType(Beneficiary.USER_BENEFICIARY);
 
RequestBeneficiaryEntity entity = new RequestBeneficiaryEntity();
entity.setEntityType("ApplicationInstance");
entity.setEntityKey(String.valueOf(accountKey));
entity.setOperation("REVOKE");
 
List<RequestBeneficiaryEntity> entities = new ArrayList<RequestBeneficiaryEntity>();
 
entities.add(entity);
beneficiary.setTargetEntities(entities);
 
List<Beneficiary> beneficiaries = new ArrayList<Beneficiary>();
beneficiaries.add(beneficiary);
requestData.setBeneficiaries(beneficiaries);
OperationResult result = oimService.doOperation(requestData, OIMService.Intent.ANY);
if( result.getRequestID() != null ) {
//Operation resulted in to request creation.
System.out.println("Request submitted with ID: " + result.getRequestID());
} else {
System.out.println("Account is revoked successfully");
}

19.7.3.2.2 Creating a User

The followins is a code sample for creating a user:

RequestData requestData = new RequestData("Create User");
RequestEntity ent = new RequestEntity();
ent.setRequestEntityType(OIMType.User);
ent.setOperation("CREATE");
HashMap<String, String> userData = new HashMap<String, String>();
 
List<RequestEntityAttribute> attrs = new ArrayList<RequestEntityAttribute>();
 
RequestEntityAttribute attr = new RequestEntityAttribute("Last Name", "Doe", RequestEntityAttribute.TYPE.String);
attrs.add(attr);        
attr = new RequestEntityAttribute("First Name", "John", RequestEntityAttribute.TYPE.String);
attrs.add(attr);
attr = new RequestEntityAttribute("User Login", "jdoe", RequestEntityAttribute.TYPE.String);
attrs.add(attr);
Long organizationKey = new Long(1);
attr = new RequestEntityAttribute("Organization", organizationKey , RequestEntityAttribute.TYPE.Long);
attrs.add(attr);
attr = new RequestEntityAttribute("Role", "Full-Time", RequestEntityAttribute.TYPE.String);
attrs.add(attr);
 
ent.setEntityData(attrs);
 
List<RequestEntity> entities = new ArrayList<RequestEntity>();
entities.add(ent);
requestData.setTargetEntities(entities);
OperationResult result = oimService.doOperation(requestData, OIMService.Intent.ANY);
if( result.getRequestID() != null ) {
//Operation resulted in to request creation.
System.out.println("Request submitted with ID: " + result.getRequestID());
} else {
System.out.println("User is created successfully");
}

19 Using APIs