Oracle ICS Integration Patterns (Part 1 of 3): Map My Data

Oracle Integration Cloud Service (ICS) is another powerful yet simple Cloud platform offering by Oracle that simplifies the development of cloud and hybrid integrations (applications in the cloud and on premises).

The entire integration development and operational lifecycle is managed through a web based service console offering a point and click integration and monitoring experience without having to write a single line of code.

Furthermore Oracle ICS supports various industry standards like SOAP and REST and comes with a set of cloud adapters providing pre-integration capabilities with several SaaS applications (such as Oracle ERP Cloud, Oracle HCM Cloud, Oracle Sales Cloud, Oracle RightNow, Eloqua, NetSuite and Salesforce) shortening the time-to-market in integration projects.

The concepts in Oracle ICS are really simple; you create connections (using the pre-defined offered adapters) and leverage those connections to create integrations which you can then dashboard monitor to track the current state of your running integrations and fix any errors that might occur.

Oracle ICS supports three types of integration patterns:

• Map My Data: You can create an integration where using your own adapters can define a a custom source and a custom target (and define routing paths and data mappings)
• Publish to ICS: You can create an integration where you can configure a service to publish message to ICS through a predefined ICS Messaging target (which is created for you automatically by choosing this pattern)
• Subscribe to ICS: You can create an integration where you can configure a service to subscribe to messages from ICS through an ICS Messaging source (which is created for you automatically by choosing this pattern)

In this first part of a three part series on Oracle ICS integration patterns we will see in detail how you can use the "Map My Data" integration pattern in a simulated use case.

The use case is really simple; I have a service that processes a purchase order. Based on the order total it will either automatically approve the purchase or will route it for manual approval. The logic has been implemented in Java using two methods; processPurchaseOrderBS representing the business service where the actual logic has been implemented and the processPurchaseOrderPS acting as a wrapper/proxy service.

Using the JDeveloper embedded JAX-WS capabilities I have exposed those two Java methods as web services and deployed them on my Integrated Weblogic Server.

So the first thing that we need to do is to create a connection to the on-prem web services exposed in the previous step. From the Oracle ICS home page click on the "Create Connections" banner image and from the "Connections" page click on the "Create New Connection" button.

From the "Create Connection - Select Adapter" popup the "SOAP" adapter to create a SOAP connection to the "Process Purchase Order" web services.

In the "New Connection - Information" popup enter a connection name, and optionally update the identifier populated automatically based on the connection name, default version and provide a description, and click "Create".

From your connection's home page click on the "Configure Connectivity" button and enter the WSDL url of your web service and click "OK".

By default when you create a new connection in Oracle ICS, it pre-populates the security section with the "Username and Password Token"security policy. I did not configure any security in my "Process Purchase Order" services therefore i will turn security off. To do so click on the "Configure Credentials" button and from the "Credentials" popup select "No Security Policy" from the "Security Policy" drop down list and click "OK".

Now we can test our connection. From the top right section of your connection's home page click on the "Test" button and ensure that your connection is successful. 

Save and close the connection details. You should be redirected to the connections home page and your connection should feature at the top of the list of connections and marked as "New".

We can now go on and create our integration. Using the menu on the left click on the "Integrations" link to navigate to the integrations home page and click on the "Create New Integration" button.

From the "Create Integration" popup select the "Map my Data" integration pattern.

In the "New Integration - Information" popup enter an integration name, and optionally update the identifier populated automatically based on the integration name, default version and provide a description if needed, and click "Create".

You should be presented with the integration canvas with an empty source and an empty target. 

From the "Connections" palette on the right of the canvas, drag and drop the connection created in the previous steps (if you followed my exact instructions it should be named "Process Purchase Order") to the source placeholder.

This will bring up the SOAP Configuration Wizard to help in configuring the source endpoint. Enter a name for your endpoint (I named it "ProcessPurchaseOrderPS") and click "Next".

In the second step of the SOAP Configuration Wizard select the operation name from the "Select the Operation" drop down list (in my example I selected "processPurchaseOrderPS") and click "Next".

In the third and last step review the source endpoint configurations and click "Done".

Do the exact same thing for the target endpoint (using the same connection as with the source endpoint) but this time give your endpoint a different name and select the other operation from the operations drop down list (I named the endpoint "ProcessPurchaseOrderBS" and selected the "processPurchaseOrderBS" operation).

Your integration canvas should now be populated with a source and a destination target.

Next we will need to map the request data from source to target and then the response data from target to source. Click on the "Request Mapping" and click on the "plus" icon to create a new request transformation.

Map orderId to orderId and orderTotal to orderTotal by just drag and dropping the source element to the target element.

For the target "fullname" we will have to concatenate the first name and last name elements from source. To do so click on the "fullname" destination element to open the "Mapping Builder". Expand "Mapping Components" and from the "Functions" category expand "String"and drag and drop the "concat" function to the right (just below "fullname") and map "firstname" to string1 and "lastname" to string2.

Click "Save" and close the "Mapping Builder". Your request transformation should look like below.

Save and exit the request mapper. We now need to do the same thing with the response data but this time we need to map the target response to the source response (drag the "result" target element to the "result" source element).

On the top right of our integration we have a progress bar showing the progress of our integration. If you click on it you will see the missing steps. Doing so we can see that we are still missing one step, to configure tracking for our source,

Oracle ICS enables you to declaratively define business identifiers to enable runtime tracking on messages. To do so click on the "Tracking" button. This will open the "Business Identifiers for Tracking" popup. Drag and drop the "orderId" element to the tracking field and specify a business friendly tracking name (named it "Order Id") and click "Done".

The integration progress should now show 100% complete. Save and exit your integration to be redirected to the integrations home page where you should be able to see your integration at the top of the list, marked as new and with a new option to activate the integration.

Click on the "Activate" button to activate the new integration we just created. In the "Confirmation" popup click on "Activate"and your integration should show as "Active".

By activating your integration Oracle ICS has created a new ICS specific endpoint url for your integration for invocation which can be found by clicking on the "info" button next to your integration. I will use this endpoint url to test my integration (using SoapUI).

I will first invoke my integration by supplying an order with an order total less than 100 to see if the integration will return an auto-approval status.

Please note that if you attempt to invoke your integration without a username and a password token and a timestamp you will get a security exception "OSB-386200: General web service security error").

After invoking my integration supplying the request a username, password and a timestamp I can now see a auto-approval response back from my integration.

If you invoke the integration with a higher value order total (in the example below 110) you should get a different response back (pending manual approval).

Oracle ICS provides you with a monitoring dashboard where you can visually see how your integrations are performing during runtime. To access this dashboard simply click on the "Dashboard" link/button on the horizontal navigation toolbar.

The default view lists all activated integrations with a summary view on the top and a detailed view per integration just below listing key KPIs such as the average response time, messages received, message processed and faulted messages.

If you navigate to the "Tracking" page you will see all messages processed by default in the last 1 hour by all active integrations. Please note how instances are displayed; they are displaying using the custom business identifiers defined.

You can view the details of a specific instance by just clicking on the instance link. The instance will open in the integration canvas in viewing mode where you can inspect the business identifiers, go to the audit train and view any error messages.

SOA Magazine edition VI

The SOA Magazine 6th edition is out!

The latest edition of the SOA Magazine focuses on a summary from Oracle Open World 2015 of which I had the honor to author and publish my three-part blog post series on "BPM 12c Events".

Make sure you subscribe to the magazine to enjoy all this wealth of information, for free!

Oracle BPM 12c Subprocesses (Part 3 of 3): Event Subprocess

In this third and last part of a three part series on subprocesses we will explore a special type of subprocess referred to as an “Event” subprocess.

This type of subprocess is triggered by an event that can occur anytime during the execution of a process flow that allows you to interrupt the normal flow of an instance.

Such capability can be applicable in various use cases. For example, an error might occur in the process, or you can very well define various service level agreements to delineate execution times or you can even have a business requirement to cancel a flow (for example cancel an order).

You can use the “Event” subprocess to implement such requirements (i.e. handle system and business exceptions).

“Event” subprocesses posses various unique characteristics. One of them is that, by configuration, you can have an “Event” subprocess either as interrupting, that is interrupting the normal process flow execution or have an “Event” subprocess running in parallel (concurrently) to the main flow of your process.

Another really nice and useful characteristics of an “Event” subprocess is that it shares the same context as the main flow of the process, meaning that from the “Event” subprocess you can have access to all the data objects that are used by the main process (and of course update their state).

An “Event” subprocess resembles like an embedded subprocess (except that it’s displayed in a dashed-line boarder), however an “Event” subprocess cannot have outgoing or incoming sequence flows. And just as with the other types of subprocesses an “Event” subprocess can define data objects that are local to its scope.

We will implement a very simple process that will make use of the event sub-process to simulate the functional use case depicted by the image above; the scenario is straightforward, you can cancel an order as long as it’s not shipped.

Create the basic BPM application and BPM project (I named it OracleBPM12cEventSubProcessDemoApp and OracleBPM12cEventSubProcessDemo respectively) and choose "Compsite with BPMN Process" in step 3 of the "Create BPM Application" and click “Finish”.

This will bring up the “BPMN 2.0 Process Wizard”. Give your process a name (for example “OrderProcess” and select the “Asynchronous Service” message pattern. In the second step of the wizard I will define a single input string argument that I will name “OrderId”. For the purpose of this demo I will not create any output arguments.

The first thing that I will do is to create a corresponding string process data object to pass the “OrderId” process input argument for reference throughout the process.

I will also create a Boolean process data object that I will use later to define whether an order cancellation can be performed or not.

Next assign the “OrderId” process input argument to the “orderId” process data objects and set the “orderCancellationAllowed” data object to true (since it’s the start of the process and a cancellation is allowed).

Drag and drop two interactive human task activities onto the sequence flow that connects the message start and message end components. In the first human task we will simulate the order submission while in the second human task we will simulate the dispatch of the order.

Notice how the human task activities are marked as incomplete. That’s because they haven’t been implemented yet. So let’s create a single human task definition to serve both interactive activities..

Double click on the “Place Order” human task and from the “Properties” window go to the “Implementation” tab and click on the green “Add” button to create a new definition. Specify a name, (for example DemoHT) and leave the rest on defaults.

Before closing the properties of the first human task activity make sure you specify a title it (just as you would like it to appear in the BPM Workspace task inbox; I named it “Place Order”).

Just to keep things simple I will make use of the same human task definition for the second interactive activity that I have in my process (don’t forget to define a title).

To simplify the assignment of tasks, open the human task definition file and in the task assignments switch from lane participants to "Names and Expressions" and define "weblogic" as the user to be assigned our order item tasks.

Next I will add a “Script” activity between the two human tasks to update the “orderCancellationAllowed” process data object and set it to false (since I don’t want an order to be cancelled once it has been placed.

Now it’s time to use the “Event” sub-process to allow but also control the cancellation of an order. Drag and drop an “Event” sub-process activity just below your order definition (in the same swimlane).

Interrupting event subprocesses can start with a message, timer, signal or error activity. The default start activity is a message that we will also use.

Also notice how the message start activity of the event sub-process is marked with a warning; that’s because it has no implementation defined. So double click on the message start activity, go to the “Implementation” tab and from the “Type” drop down select “Define Interface”.
Now here is the trick; the event sub-process will invoke a request for cancelling an order. However, we will need a way to associate the request for cancellation with the initiated order. To achieve such functionality we will use a custom correlation that needs to rely on a common identifier. This will be the order id. Therefore I will create an event sub-process “OrderId” string argument.

Click on the “Correlations” link to define our custom correlation and click on the “New Correlation Property” button. Define a name for the correlation property and ensure “STRING” is selected as the correlation property type.

Using the expression builder map the “OrderId” event sub-process argument to the correlation property you just created and click “OK” to dismiss the “Correlation Definition” window.

The “Start” properties window should still be open. Please notice, just below the “Implementation Type”, the two options for configuring your event sub-process; “Interrupting Event” to basically forcibly stop the execution of your process flow and “Suspending Event” (with the options pause and resume the process flow). Ensure you selected “Suspending Event”.

There is one thing left to enable our custom correlation to work and that is to define the same correlation logic to the message start component of the main process. Since this will be the “parent” process you need to make sure you select the “Initiates” checkbox.

We have configured the event sub-process to be a suspending sub-process, meaning that it will pause the normal execution of the parent process flow. This option has a really nice feature that you can instruct the BPMN engine to resume the execution of the parent flow based on specific conditions (in our case this will be the “orderCancellationAllowed” data object.

Therefore drag and drop an exclusive gateway inside the event sub-process on the default sequence that connects the event sub-process start and end components (named it “Order Cancellation Allowed?”).

To define the resume functionality described above we will need to use a “Script” activity and use the “action” predefined variable and assign it the value “resume” (using “Data Associations”).

 Add a conditional sequence flow from the exclusive gateway to the script task and a default sequence flow from the script task to the end component.

In the properties of the conditional sequence flow define a condition that should enable that branch of the exclusive gateway only if the “orderCancellationAllowed” data object value is false (hint: you will have to negate the data object value using the “not” logical operator).

Your process should look like below.

We are finally ready to deploy and test our process (and event sub-process). From the EM (Enterprise Manager) invoke a new instance of your process (ensure you are using the “start” operation which maps to the message start event of the core process).

Go to the BPM Workspace and you should see a task in the weblogic user’s inbox.

Without submitting the task, go back to the Enterprise Manager console and invoke a cancellation request. Make sure that you use the same order id as you used for initiating your previous order request instance (because we are correlating requests from the event sub-process to the main process via the order id).

Go to the BPM Workspace and refresh your inbox. The previously task should be removed.

Initiate a new order request but this time submit the “Place Order” task. You should get another task in your inbox (“Ship Order”). Go back to the Enterprise Manager console and invoke a cancellation request (for the same order id). If you go to the BPM Workspace you should notice that the “Ship Order” task is still in your inbox. That’s because the main process has passed the acceptable cancellation threshold that we’ve defined.

Download sample application: Event Subprocess