OIM 11g R2 Requests Lifecycle Management API’s

Introduction

OIM 11g R2 being such a comprehensive provisioning solution, it provides API’s for almost every aspect of functionality available in the product. This makes it a little difficult to decide which examples are needed the most in the documentation. Fortunately, the documentation does supply samples that can definitely serve as a foundation for more complex pieces of code. Some of the API’s I found developers using more often than others are the ones related to the operations associated with users’ requests for resources. Amongst those the following API’s are mostly required:

• Request Creation/Submission
• Request History Data Access
• Child Table Data Manipulation
• Approval Information Data Access

This blog post will include a few samples on how to accomplish each one of the above mentioned operations within the context of a use case described shortly. The intent is to provide some useful API’s code samples that customers and partners can use to write their own custom code that requires such functionality.

Retrieving and Setting HTTP Headers in BPEL

The capability to retrieve and set HTTP headers in BPEL was recently added to Oracle SOA Suite 11g. Edwin Biemond has written an excellent blog post on how to use this capability.

From a security/IDM perspective, I think this feature opens up the ability to create some interesting solutions whereby identity information is added to HTTP headers by OAM (or other SSO products) in the web tier and consumed by services in the app tier. It also makes it possible to pass identity data between services in HTTP headers and thereby ignore having to modify web service requests themselves.

I’ll only add as a warning to remember that end users have the capability to add whatever HTTP headers they want to the requests they make. So, solutions should be developed with this in mind. In particular, if you are going to create a solution that depends on BPEL consuming an HTTP header created by an OAM response, you need to take steps to either ensure that this header really came from OAM (by signing or encrypting it) or take steps to ensure that all requests to BPEL really did originate by coming through the web tier with OAM.

Encapsulating OIM API’s in a Web Service for OIM Custom SOA Composites

Introduction

This document describes how to encapsulate OIM API calls in a Web Service for use in a custom SOA composite to be included as an approval process in a request template.

We always recommend customers to follow this approach when trying to invoke OIM’s APIs inside SOA composites used as approval processes for the following reasons:

• A web service implementation allows the instantiation of all related APIs once at service startup as opposed to getting a remote reference to each required API interface. This improves performance and reduces the memory footprint of the composite if these API’s are instantiated in embedded Java Tasks.
• This paradigm allows the implementation of HA for the Web Service encapsulating the API calls and provides the ability to deploy the web service in a separate server from the SOA and OIM servers is so desired. This increases the robustness and reliability of the solution.
• According to BPEL’s documentation Embedded Java Tasks should only be used for quick utility logic, no business logic should be included in these tasks. For details refer to http://docs.oracle.com/cd/E15586_01/integration.1111/e10224/bp_java.htm#BABHJHBG section 13.2.3 How to Embed Java Code Snippets into a BPEL Process with the bpelx:exec Tag. The reason for that is because all memory required for objects being instantiated within the embedded Java code is adding to the memory space of the composite instance itself which will be kept for the life of the composite instance. This means that if a composite has an asynchronous BPEL process (which is definitely the case for OIM’s Approval Process composites) and that can make the BPEL process to remain there for days or weeks, memory problem may start to arise.

Procedure

The assumption here is that JDeveloper is going to be used to edit the SOA composite and there are no other tools suitable for this purpose. JDeveloper is also a good tool to create the Web Service wrapping the OIM API calls. All that is needed is to create a POJO (Plain Old Java Object) and convert it to a Web Service, and then deploy it to an application server (Weblogic in this case); all of which can be accomplished with JDeveloper.

Please refer to JDeveloper 11g documentation for information on how to create a Web Service out of a POJO since this is out of scope for this document. Once the web service is created and deployed one can obtain the WSDL from the Web Logic Admin console. Just access the deployments and drill down to the Test Client of the web service. The WSDL will be available from the Test client window or from the table showing the testing points in the Weblogic Admin Console. All that is needed is to copy the URL for the WSDL and paste it in the proper text box when configuring the Web Service reference in the composite.

Once the Web Service reference is configured in the Composite, it can be linked to the BPEL process inside the composite. All we need to do is to connect the icon representing the BPEL process with the Web Service reference by stretching an arrow connecting the two of them. Consult the SOA Composite Editor documentation from JDeveloper’s 11g users guide. To invoke methods on the newly wired in Web Service an Invoke Task must be included for each method to be called. The Invoke Task allows you to define the following elements:

• An input variable that will include the input values for the specific method call taken from the WSDL of the Web Service.
• An output variable that will receive the returning data from the invocation of the Web Service method formatted as specified by the WSDL of the Web Service.

Before an invocation there typically is an Assign Task that will populate the input parameters of a Web Service call by copying values from other variables or assigning literal values to the input parameters in the Input Variable. So inserting the Invoke Task prior to inserting the Assign Task allows you to create the Input and Output Variables that will be populated by the Assign Task for the case of the Input Variable and with the output data from the Web Service method call in the case of the Output Variable. Now the values in the Output Variable can be used anywhere else in the composite and can be transferred using other Assign Tasks within the BPEL Process flow.

Summary

SOA Suite allows the execution of embedded Java logic within the composites. OIM Java APIs are not a good candidate to be included in Embedded Java Tasks, especially if the composites are meant to serve as approval processes that can potentially keep instances of the composite for a long time. The recommended approach is encapsulating the OIM APIs in Web Services with a SOAP interface. Then invoke operations on the OIM API Wrapping Web Service and just manipulate the results. This allows for other benefits from the architecture design perspective and from the performance and memory footprint stand point as well to prevent Out of Memory issues.