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.