Tuesday, February 16, 2016

Oracle ICS Integration Patterns (Part 2 of 3): Publish To ICS

In this second part of a three part series on Integration Cloud Service (ICS) Integration Patterns we will explore the "Publish to ICS" integration pattern, a motivo which allows you to configure a service to publish messages to ICS through a predefined ICS Messaging target that is automatically created by ICS when choosing this pattern.

Typical use cases for using this pattern is when you want to decouple your service producers from your service consumers in a typical service bus scenario to provide a visualization layer to your service topology.

Building on the existing source code prepared and presented in the first part on ICS Integration Patterns where we saw the "Map My Data" integration pattern, we will extend the ProcessPurchaseOrder interface with an additional method.

This method will serve as a proxy service, a facade to service consumers. There will be no implementation other than annotating the method with the @WebMethod JAX-WS annotation to expose it as a web service and the @OneWay annotation to denote that this will be a fire-and-forget web service.

Deploy your service and go to the ICS Service Console. Because this second part is a continuation of the first part I assume that you already have a connection defined on ICS to point to the "ProcessPurchaseOrder" web service. We only added a new operation.

Unfortunately ICS doesn't have a way to invalidate its connections cache to pick up the new operation. One way to make ICS aware of your new operation on an existing SOAP connection is to drop the connection and re-create it which of course can be quite time consuming.

An alternative approach that I discovered is to make a small deliberate change to the WSDL URL, test the service (which would of course fail), save the connection and restore back the WSDL URL, testing the service again and doing one final save to the connection.

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 "Publish To ICS" 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 a preconfigured target using the ICS Messaging Service.

From the "Connections" palette on the right of the canvas, drag and drop your connection (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 "PublishToICS") 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".

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 "Yes"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).

Using SoapUI I will invoke my integration by supplying a sample order.
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 that my invocation was successful.

I can confirm that data was actually published to ICS by navigating to the monitoring dashboard provided 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.

Click on your integration's "Messages Received" to be navigated to the "Tracking" page which will should display all messaged processed by the selected integration in the last 3 days (by default). 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.

Monday, February 15, 2016

Correlations in Oracle BPM 12c

Correlations in Oracle Business Process Management (BPM) is a special mechanism used to associate a message with a conversation between different partners in a business process.

There are two types of correlations:
  • Automatic: This is the default and out-of-the-box correlation used between two business partners which makes use of a special token called "Conversation Id" to uniquely associate a message with a conversation via Web Service Addressing (WS-Addressing) to correlate a callback message using the "Conversation Id".
  • Message Based: This type of correlation enables the definition and use of "business-friendly" information carried as part of the message payload to be used to uniquely identify and associate a message with a conversation (for example, OrderId, CustomerId, etc.). This type of correlation enables the definition of multiple attributes referred to as "Correlation Properties" into various correlation sets know as "Correlation Keys".
So let's see how you to use the two correlation types in a demo scenario. The simulated process will invoke an asynchronous process first by using the default correlations and then by using message-based correlations.

Create the basic BPM application and BPM project (I named it OracleBPM12cCorrelationsDemoApp and OracleBPM12cCorrelationsDemo respectively) and choose "Composite 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 “DemoProcess” 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 “MyId” and a single output string argument that I will name "MyStatus".

The first thing that I will do is to create two corresponding string process data objects, the first one to pass the “MyId” process input argument for reference throughout the process and the second one to be used later for assigning the process output argument.

Next using the "Start Message" data associations assign the "MyId" process input argument to the "myId" process data object.

To simulate the interruption between business partners in a business process I will create another asynchronous process which I will then invoke from the main process.

So create a new "Asynchronous Process" (named it "DemoReUsableProcess") with a single string input argument (MyId) and a single string output argument (MyId).

As as we did with the main process create a a string process data object to pass the MyId process input argument for reference throughout the process.

Using the "Start Message" data associations assign the "MyId" process input argument to the "myId" process data object.

Drag and drop an interactive human task activity onto the sequence flow that connects the message start and message end components to simulate difference approval scenarios.

Give your human task activity a name (for example "Demo User Task"). From the "Implementation" tab 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 “Demo User Task”).

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.

Based on the human task outcome (approved or rejected) the "DemoReUsableProcess" will respond using a different operation. Therefore drag an exclusive gateway right after the human task activity and name it "Outcome?".

Open the properties of the "End Message" component and change the default callback operation name from "end" to "reject".

Open the data associations of the reject "End Message" component and ensure you map the "myId" input data object to the the "MyId" argument of the "End Message". This is crucial as the custom correlation will be based on this argument.

Drag another "End Message" component and this time define it's callback operation to "approve" (ensure that you have created a string argument just like the default "End Message" operation).

Open the data associations of the approve "End Message" component and ensure you map the "myId" input data object to the the "MyId" argument of the "End Message". This is crucial as the custom correlation will be based on this argument.

Open the properties of the human task component and from the data associations go to the "Output" tab and first create a new string data object and then map the human task string output argument to your newly created string data object. The human task data association assignment should look like below.

Add a conditional sequence flow from the exclusive gateway to the second "End Message" component with the XPath expression set to bpmn:getDataObject('outcome') = 'APPROVE'

Your simulated business partner process should look as follow.

We are now ready to invoke our re-usable process from our main process. Open your main process and place a "Send" activity between the "Start" and "End" components. From the implementation tab select "Process Call" as the type and select your re-usable process.

Place an "Event-based" gateway right after the "Send" activity and rename it to "Outcome". JDeveloper should have created for you a "Message Catch" event and a "Timer Catch" event. We will use a "Receive" activity to asynchronously receive the response from our re-usable process so go ahead and remove the "Message Catch" event.

Open the "Timer Catch" event and set its time cycle to 1 minute (in case there isn't a reply from the asynchronous sub-process the "Timer Catch" event will get kick-started).

Extend the "Event-based" activity with two additional "Receive" activities. Your main process should look as follows:
The two new "Receive" activities are marked with a warning sign to indicate that no implementation is defined yet. So go to the properties of the first "Receive" activity (Approve Msg) and from the implementation type select "Process Call". Select your re-usable process and select the appropriate target node.

Do the same thing with the second "Receive" activity but this time select the other target node option (in my case it's the "Reject" target node).
We are now ready to define our custom correlation. Open the "Send" task and from the "Implementation" tab click on "Correlations". In the "Correlation Definition" window click on the "New Correlation Property" button to create a new correlation property. This will be a string correlation property which i named "myCorrelationId". Ensure that you have selected the "Initiates" check-box and assign the "MyId" argument to your correlation property.

We also need to define the same correlation properties on the two "Receive" activities. So go to your first "Receive" activity and from the "Implementation" tab click on "Correlations". From the correlation property drop-down list select the correlation property created just above. Map the "MyId" argument to your correlation property.

Apply the same correlation definition to the second "Receive" activity and deploy your process and test your process. If you inspect the audit trail you should see that the instance is waiting at the event-based split gateway activity.

Go to the BPM Workspace and submit the pending task (either approve or reject it). If you go back to the audit trail you should see the related branch being followed.

Download sample application: Correlations in Oracle BPM 12c