Oracle BPM Human Task Management : Using Human Task Events to Invoke Microsoft Exchange Web Services

Recently while working on a specific use case for an enterprise where I had to develop a mechanism of notifying organizational users in case a human workflow task is assigned to them. The enterprise in consideration here had a need to create an Microsoft Exchange Task for the user once he is assigned with a BPM Human Task and need to act on it.

In this blog post I would be covering as how we can achieve this. This may also be useful in case you are required to use Exchange Web Services in Oracle SOA Suite. Before i begin I would like to cover a little bit of rationale behind this approach.

The Rationale to this Approach

Oracle Human Workflow Tasks allow us to configure Notification settings through which we can can Email/SMS notifications through the Notification service. For a human task we can choose to set reminders at preset intervals, send actionable links in notification emails, attach task attachments, add custom headers etc.

However our need was quite simple. What we needed was to simply create a Outlook Task for the assigned user that will take care of Reminders. Imagine a task in which we have some bulky attachments. Retrying from the Notification Service by leveraging the Oracle Taskflow Messaging mechanism is quite expensive as this leads to multiple emails being sent.

Creating a Recurring Task saves us from repetitive emails. We can use recurring Outlook Task for reminders.

Readying the Backbone

A bit about Exchange Web Service APIs

Microsoft provides a very rich and exhaustive set of API as well as Developer SDK’s for Exchange web services.

You can see the whole list of operations provided by the API in the link below

http://msdn.microsoft.com/en-us/library/bb409286%28v=EXCHG.140%29.aspx

In this post however i will be demonstrating how to invoke the “CreateItem” operation to create a user Task in outlook.

The WSDL for the exchange web services can be obtained at by typing the following in your browser.

https://exchangeServerURL/EWS/Services.wsdl

You can obtain the Exchange Service URL by opening Outlook->File->Account Settings

I was able to get this web service running from a web service client like SOAPUI to see it in action.

The Exchange Web Services are on HTTPS and require HTTP Basic Authentication credential to invoke the caller. They are no different from your NT Credentials.

However Off course we would need to invoke this service from within our SOA Suite domain. But this gives us a heads up about the working of Exchange web services.

Oracle Service Bus Plumbing to Invoke The Exchange Web Services

This part is somehow tricky. We would need to invoke the Exchange service from the Human Task Service. Since Oracle Service Bus is the place where we organize our enterprise wide reusable services i choose to implement the service call to the Exchange endpoint from within the bus.

That shouldn’t be difficult.

Create a  Proxy Service in OSB based on the Exchange service WSDL. Also copy the dependent XSD’s in the service bus project.

This is the place I had hit my first roadblock. The Exchange Web Services need a NTLM Authentication mechanism where as OSB doesn’t support NTLM out of the box. The workaround for this is that we have to create a custom Java class for doing this which can be invoked from OSB by a Java Callout action.

Create a simple Java Project in Eclipse and use the Java Class below. It works like a treat to get this thing done.

package blog.soatech;
import java.io.IOException;</pre>
import org.apache.commons.httpclient.HttpClient;
import org.apache.commons.httpclient.HttpException;
import org.apache.commons.httpclient.HttpStatus;
import org.apache.commons.httpclient.NTCredentials;
import org.apache.commons.httpclient.auth.AuthScope;
import org.apache.commons.httpclient.methods.PostMethod;
import org.apache.commons.httpclient.methods.StringRequestEntity;

public class ExchangeServices {
private static final String userAgent = "Mozilla/5.0 (Windows; U; Windows NT 6.0; en-GB; rv:1.9.2.13) Gecko/20101203 Firefox/3.6.13";
@SuppressWarnings("unused")
public static String invokeExService(String endPoint, String messageHeader, String messageBody, String userName, String password, String operation) throws HttpException, IOException
{
StringBuffer soapMessage = new StringBuffer();
soapMessage.append("<?xml version=\"1.0\" encoding=\"utf-8\"?>\n");
soapMessage.append("<soapenv:Envelope xmlns:soapenv=\"http://schemas.xmlsoap.org/soap/envelope/\" xmlns:typ=\"http://schemas.microsoft.com/exchange/services/2006/types\" xmlns:mes=\"http://schemas.microsoft.com/exchange/services/2006/messages\">\n");
soapMessage.append(messageHeader);
soapMessage.append(messageBody);
soapMessage.append("</soapenv:Envelope>\n");
//System.out.print("Request : " + soapMessage.toString());
HttpClient client = new HttpClient();
String soapAction ="http://schemas.microsoft.com/exchange/services/2006/messages/"+operation;</a>
PostMethod postMethod = new PostMethod(endPoint.trim());
postMethod.setRequestHeader("SOAPAction", soapAction);
postMethod.setRequestHeader("Content-Type", "text/xml; charset=UTF-8");
postMethod.setRequestHeader("SOAPAction", soapAction);
postMethod.setRequestHeader("User-Agent", userAgent);
postMethod.setRequestEntity(new StringRequestEntity(soapMessage.toString().trim(), "text/xml; charset=UTF-8", null));
String errorMessage ="";
String responseBodyString ="";
NTCredentials ntCredentials = new NTCredentials(userName, password, "hostName", "domainName");
client.getState().setCredentials(new AuthScope(null,-1,null), ntCredentials);
int status = client.executeMethod(postMethod);
if(status != HttpStatus.SC_OK)
{
errorMessage = "Method Failed :" + postMethod.getStatusLine();
// System.out.println(errorMessage);
}
responseBodyString= postMethod.getResponseBodyAsString();
//System.out.println("Response Message ;" +responseBodyString);
return responseBodyString;
}
}

The above class is needs a few Apache Jar’s as dependent jars in the build path.

Package this as a JAR file by exporting it as a JAR from eclipse. Next we will have to import this JAR in our OSB project so that the ExchangeService.class inside it can be used for Java Callout.

Add a line the setDomainEnv.cmd file in the OSB Domain so that it can locate these classpath entries at runtime.

set POST_CLASSPATH=%DOMAIN_HOME%\lib\commons-codec-1.5.jar;%DOMAIN_HOME%\lib\commons-httpclient-3.1.jar;%DOMAIN_HOME%\lib\commons-logging-1.1.1.jar;%POST_CLASSPATH%

The second thing that we need to do is add the Exchange service certificate to the Keystore of the OSB domain. Remember the Exchange services are https services.

Obtain the X.509 certificate from the exchange server and save it as a .pem file. Locate the location of the DemoKeyStore from the weblogic server console.

The X.509 certificate from the exchange server can be imported in the keystore by running the Keytool command below

keytool -import -trustcacerts -file <FileLoc>\cert.pem -keystore <KeyStoreLoc>\DemoTrust.jks

The default keystore password is DemoTrustKeyStorePassPhrase

Reboot the OSB Domain after applying these changes for them to take affect.

Lastly export the OSB Proxy Service as a WSDL so that it can be used in our BPM composite.

We can now move on to create the BPM process with a Human task that will invoke this OSB service.

Creating the BPM Composite with a Human Task

For the purpose of demonstration here I will be creating the most basic BPM process that has one message start event, one user task event (implemented as an Oracle Human Task) and an end event.

The process can be exposed as a web service since it has a Message Start event. This is a simple Card Approval Process in which a Credit Card Approver is presented with a Credit Card request that he has to either approve or reject.

The Task Activity is implemented as a Human Workflow Task. Open the .task for this task in JDeveloper.

We can enter additional task details from here like Task Title, Task Deadlines, Assignees, Notification Setting etc.

Add a Fixed Duration Deadline to this Task in the Deadlines tab.

This will set the expirationDate element in the task payload.

This is also where lies the crux of this article.

Since we want to create an Exchange Task for the assignee as soon as the Human Task is assigned to him we have to create and implement an onAssigned Event for this task.

You are allowed to create different events based on the task status from here. For now we are only interested in the first event i.e onAssigned event.

When a workflow event is triggered the in build EDN (Event Delivery Network) framework throws an event that contains the assigned Task Message payload containing the complete task information.

Learn more about EDN in Oracle SOA Suite here.

https://beatechnologies.wordpress.com/2011/06/14/lightweight-introduction-to-oracle-soa-suite-11g/

http://blogs.oracle.com/soabpm/entry/event_delivery_network_chapter

Creating a Mediator to Subscribe to Workflow Events

We have raised an event from the Human Task. We now have to implement a listener for this event that can listen to it and do something (calling the Exchange Service operations in this case).

Doing this couldn’t have been much simpler. What you need to do is create a composite application that has a Mediator component listening to this event.

The Event Definition File (EDL) for subscribing to Human Workflow events can be found in the MDS Repository under soa/shared/workflow/HumanTaskEvent.edl.

The mediator can subscribe to any one or all of the events and will fan out the process depending upon the event it receives.

Next create a Web service reference in the composite that is based on the Exchange Service OSB Proxy and wire the Mediator to Create Item of this service.

Open the Mediator Routing Definition to see that the a Static Routing Rule has been created for OnTaskAssigned event.

We can use the an XSL based Transformation to transform a task request to the CreateItemRequest message for the Exchange webservice.

Deploy the BPM Application for Card Approval Process and also the composite application containing the Event Subscribing Mediator component to a running soa server so see everything in action together.

Seeing Everything in Action

Go to the Enterprise Manager console where the Card Approval BPM composite is deployed.

Test the composite with a card approval request message from the composite. You will see that a running instance of the composite is created.

Looking at the Audit Trail of this instance will reveal an interesting thing. You will see that as soon as the the process flow reaches the ApproveCard user activity an OnTaskAssigned event is fired.

A WorkflowEventSubcriber Mediator Component that is listening to this type of event processes the event and calls the external web service. Opening the trace will further reveal that the service has returned a success response.

An outlook Task with a recurring reminder has now been created in the user inbox.

The Ending Conclusion

Another thing we did was to delete this Outlook task once a Human Workflow participant has acted on the it.

This is quite simple and achievable by raising an OnTaskCompleted event from the Human Task, extending the composite to subscribe to this type of event as well and call the DeleteItem operation on the Exchange web service.

Please feel free to post your questions and suggestions here.

.