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.

image

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.

image

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

image

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

image

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.

image

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.

image

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.

image

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.

image

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.

image

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.

image

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.

image

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.

image

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.

image

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.

image

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.

image

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.

image

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.

image

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.

image

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.

image

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

image

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.

.

26 thoughts on “Oracle BPM Human Task Management : Using Human Task Events to Invoke Microsoft Exchange Web Services

  1. The article is very nice, but how do you get the password of the user for the Exchange web service? password is always a crux.
    Or do you us an application user for creating the task?

    Like

  2. Hi Robert,

    Your concern is very valid. The actual approach used by me was something like this.

    Created a Master/Admin user in exchange server who had the permission to impersonate other users in exchange server, then the master user will impersonate a user and will create the task to the users task list. And the task will be available in the assigned user’s task list in outlook.

    The email address of the user to whom the task is assigned can be obtained from the task Payload.

    Secondly to protect the credentials of the Super Admin user, I used Service Account in OSB.

    Did not go into all these nitty gritty in this article as this was meant for simple understanding of a real life use case.

    Like

    • Hi Arun,

      thanks. I am interested how this impersonate works, because as I see the original web service (CreateItem) does not support this – something like a proxy user. So may be we can discuss this details offline.

      Like

  3. Hi Arun,

    We also have a similar requirement of creating tasks in Microsoft Exchange Server. But our Server version is 2003. Are these services available in Exchange Server 2003 as well ? if not is there any alternate approach for integrating SOA server with Exchange Server 2003. Any pointers will be of great help.

    Thanks
    Lakshminadh.

    Like

    • I am afraid i am not very sure of how to integrate with MS Exchange 2003 server as it doesn’t have any sort of EWS as in for Exchange 2007 and 2010.

      I will however try to see if I can find any alternative means and update it here.

      Like

  4. Pingback: facebook123

  5. Hi Arun | I am working on a OBPM 11g project and I am pretty much new to this technology. I have a scenario where I need to receive emails from the various clients with excel attachments.

    I need to parse the excel document and each row in the excel goes as a work item for a user. Could you please advise on how we shall implement this in Oracle BPM 11g Suite, thank you.

    Like

  6. Hi Vijay,

    If you intend to create a process in Oracle BPM Suite 11g that is triggered with an email activity i doubt if this is possible by using any out of the box feature.

    Email Adapter/Transport that can be used to implement a Listener Service for incoming emails aren’t available in Oracle BPM 11g as of now. However they will become a first class citizen in some future release.

    There are however workarounds possible depending upon a couple of things. My first question to you would be whether you are using Oracle BPM Suite 11g alone or in conjunction with other OFM related technologies like Oracle SOA Suite or Oracle Service Bus.

    Another important aspect i would like to share with you regarding BPM is to design the process in a manner in which it is as business friendly as possible.

    Your BPM process can be invoked as a standard web service that contains an xml collection of work-items that your BPM process can iterate over and assign them to users.

    But once again as i said any recommendation that can be provided is only after you can provide replies to my earlier question.

    Thanks

    Like

  7. Hi Arun,

    I am working on a similar requirement where I need to send a mail on assignment and reassignment.With the help of your blog I have created a project but however when I am doing a reassignment, the event service is not firing.As i understand reassign is a subtask of assignment and when i do a reassignment the mediator which is calling human task event should be fired.Pls could you let me know the settings for Oracle events which should get fired on reassignment too.

    Regards,
    Ritu

    Like

    • Hi,
      Have you tried to trigger a workflow event from the Human Task for “OnUpdated” or “OnSubTaskUpdated” events. If not please check “Trigger Workflow Event” for these states while configuring the .task file for your human task. This can be found in the Events pane.
      You can then listen to these events as well in your mediator and call a service from there.

      Like

  8. Hi,

    Has anyone had troubles with this problem when creating the JAR for OSB?
    java.lang.NoClassDefFoundError: org/apache/commons/httpclient/methods/RequestEntity

    I have commons-codec-1.5, commons-httpclient-3.1, commons-logging-1.1.1 in my class/build path per screenshot.

    Like

  9. Pingback: Fernando Alencar | Oracle BPM Human Task Management : Using Human Task Events to Invoke Microsoft Exchange Web Services

  10. Hi Arun, I have subscribed to an “onTaskUpdated” event in mediator and wanted to call a operation of my process WSDL,that obviously needs correlation Id that I have in my payload of human task. But to my surprise I’m not getting payload element when I try to perform transformation in mediator, it’s an empty tag only. Can you please suggest.

    Like

  11. Pingback: Getting Started with Oracle BPM 11g – Very useful links_02 | IT(s) Inspired

  12. Hi Arun,
    Is it possible to use this functionality without using OSB? If yes, can you explain me how to leverage in BPM 11g?

    Thanks,
    Alice

    Like

    • Well you could. The only reason I used OSB because the exchange services are secured and wanted to use OSB for that. Oracle SOA Suite 11g also has a web service adapter that can be used along with specific or custom OWSM policies to achieve a similar functionality

      Like

  13. Pingback: elettricisti

  14. Pingback: Fix Com.microsoft.tfs.core.httpclient.jar Errors - Windows XP, Vista, 7 & 8

If you have any comments, suggestions or feedback about the post, please feel free to type it here and I will do my best to address them asap

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s