RESTful Service From Email Using Orbeon to Intalio

In a previous blog, I wrote about how you could use Intalio REST Connector to call an LDAP service created in Orbeon XPL.  In this blog I take a different tactic in using Orbeon and Intalio to meet a clients needs.

The client project entailed creating a reminder/alerting service using Intalio as the business rules service.  If a timer expires before an updated message comes in to the process, emails are to be sent out to staff and manager.  In the email, they wanted the capability of checking a box and replying to the email which would end the Intalio Process for monitoring that case if monitoring was no longer required.  So this is what I put together for them using Intalio and Orbeon.

When the email is sent, I format the body of the email using Intalio bpel:doXSLTransform function and in the xsl include HTML and values from the process.  As part of the html email I include a link which is formatted to call an Orbeon XPL file - a RESTful service.  In the url is the location of the service and the necessary parameters.  An example of the url format is below:

http://{ip}:{port}/orbeon/{appName}/{pagePath}?{parameter1}={value}&........

So, all this does is call the xpl file location which does the following.

1. First we use an xsl processor to take the parameters from the url and put them in the pattern required by the delegation processor.
2. The output of the xsl processor is passed to the input for the call of the delegation processor.  The delegation processor is configured to call Intalio Web Service.
3. Intalio receives the message and responds back with the results, which in the case is just that the message was received.
4. An xsl processor takes the result from the delegation processor and displays that result in the users browser.

So, in this example we were able to call a web service (in this example the service endpoint was located in Intalio as part of a business process) from within an email using orbeon as the RESTful service provider.

Thinking outside the box, Orbeon components were used without displaying one single xForms to add functionality to our process.

If you would like more information or would like to implement something similar in your organization, contact us at http://btmsoftwaresolutions.com.

Intalio - Orbeon Email Service

In a previous post I provided an example of how you could combine Orbeon and Intalio using rest to retrieve information from an LDAP and use it within a business process.  In this post I will describe a completed email service using this approach with the ability to send in multiple LDAP filters and send multiple emails.

The concept was as follows - allow a process or a user to send in multiple LDAP filter criteria and send emails to all those users returned from the service.  For example, a process may want to send an email to not only one user (cn='userID'), but also that user and a everyone with the title supervisor (title='supervisor'). 

Email service explained.

Email service contract expects the following:

1. A subject for the email
2. A body for the email (can send in a nicely formatted HTML)
3. The LDAP attribute(s) you want to filter and the value(s) - 1 to many
• cn, userID
• title, supervisor

The process first counts the number of LDAP parameters being sent in and sets an in process variable to this value - $countFilters.  This variable is set within a main looping sub-process.  The main sub-process exits only when the number of loops equals the number of $countFilters.  We also set a variable $ldap to yes and the $mainLoop variable to 1.  Finally we set a variable $countNodes to 0.  This tells this email sub-process (explained next) gateway whether to call the LDAP REST service.  If $ldap set to yes, the LDAP Service is called.  If set to no, then bypass the LDAP service.

The process then enters another sub-process (email sub-process).  The first thing this process does is set the in process variable $countNodes to $countNodes +1.  Remember $countNodes is set to 0 by default in the main sub-process because if we have multiple LDAP parameters being sent in, when the email sub-process is completed we may have to start all over again so we have to reset $countNodes.  This email sub-process will only exit when $countNodes equals count(result)  - the xpath function count() of the result nodes returned from the LDAP Rest service.  Next a gateway evaluates the $ldap variable and since we set it to yes, we call LDAP REST service.  We pass in the first filter by using the Intalio data editor and then in process variable $mainLoop to select the node position.  So, params/attribute[$mainLoop] and params/filter[$mainLoop].  LDAP returns 1 or more user information and then we start sending emails.  We use the $countNodes variable to iterate through all the potential results.  So to get the first email, we say results/result[$countNodes]/attribute[name='mail']/value.  This gives us the first person's email.  After the email is sent, we set the $ldap variable to no, because we do not need to call ldap again at this point.  If more emails are to be sent, we loop back in the email sub-process, do not go LDAP REST service because we set $ldap to no and $countNodes is now set to 2.  The next email will be sent.  If there are no emails, then $countNodes = count(result) and we exit the email sub-process.  But, if we sent in more then one LDAP filter, we loop back to the very beginning of the main sub-process because $countParams does not equal count(params).  We also set $mainLoop to 2 and $ldap variable to yes because we need to call the LDAP REST service again to get new user(s) information.  So, we take the next LDAP filters based on node position the user sent in and start the entire email sub-process over.  When email sub-process completes again, if $mainLoop = count(params), then we exit the main sub-process and the email service ends.

You can call this email service from within an existing business process designed in Intalio or an external system since the email service generated in Intalio provides you with a WSDL.  So for example, you could call this email service from within Orbeon.

If you would like to implement something similiar in your organization, contact BTM Software Solutions for more information.

LDAP connector using Orbeon and Intalio

In my business processes that I develop for customers they often want email notifications sent for alerts and or events that happen along the business process.  The user information is stored in Apache DS LDAP so the trick is getting the data in the process to be used for html emails.  I came up with a solution several months back which involved using openESB and their LDAP Binding Connector (BC) to create a composite application deployed on Glassfish Server.  The Trigger was an HTTP SOAP call which passed information to the LDAP BC and returned the desired results.

Even though this solution got the job done, you had to download openESB, develop the composite application in Netbeans, deploy the process to GlassFish Server, etc.  More tools, possibility for errors, something else to learn, something else to support and servers running just for basic LDAP information.

The product I use for Business Process workflow is Intalio.  And although they currently do not have an LDAP Connector, they do have a REST connector.  Another product I use is Orbeon xForms.  Orbeon does have the ability to query an LDAP through XML Pipe Line (XPL).  So how do these technologies get me my LDAP information into a Intalio Business Process without having to add Netbeans, openESB, Glassfish to my toolbox.  Let me share.

Orbeon page-flow controller can be called from within your browser - http://localhost:8080/orbeon/ldap/rest.  If you want to filter your LDAP response, then add the parameter to your url - http://localhost:8080/orbeon/ldap/rest?cn={value}.  In the page-flow controller, construct a page element /ldap/rest and a default submission to extract the parameter from the url.  You have to create an xml file to hold these parameters.  The submission will call the ldap.xpl file which I first pass into a xsl processor to construct the filter dynamically for the ldap process.  I pass the xsl processor output to the ldap processor filter configuration.  You can build a test case and test it from your browser.  There is your RESTful LDAP service.

So how do you integrate this with Intalio.  Well, like I said, Intalio has a REST Connector.  Take your url statement above and using Intalio REST wizard create the RESTful service in intalio.  Drop the WSDL in your process and map your elements (input parameter and response message).  You are done.  Your process will call your end point url, which will call Orbeon XPL file and return the results to Intalio.  No need to install more servers and other tools.  I just use Orbeon and Intalio.

One note, the xml returned by Orbeon is in an empty namespace.  Intalio mapper will not recognize the variable without a namespace.  So, I had to add one more layer of transformation within the Orbeon XPL file.  After the LDAP response is returned, I pass this output to one final XSL Processor and include a namespace in the root of the xsl - xmlns="http://example.com/rest".  Then when intalio gets the data, a namespace is present and you can map the results in your business process to send out emails.

Another tip is to use xsl within the process to pass html into the body of the email service so your clients get nicely formatted email messages.

If you would like assistance on integrating this solution into one of your projects contact me at http://BTMSoftwareSolutions.com.

Instant Messaging with Intalio, openESB, GlassFish, PSI and OpenFire XMPP Server

If you are interested in deploying an Instant Messaging component in your Intalio process, read on.  I recently was involved in a project in which a telecommunications company wanted to send instant messaging notifications when certain events where triggered (usually timers).  The architecture that was chosen was using a php script that accepted a post and then relayed the information to XMPP server.  In this scenario OpenFire XMPP server was used. I was only responsible for developing the REST call from within Intalio which was pretty easy and straight forward.  However not being a php developer, I wanted another solution I could use in other environments.

In a previous blog, I noted how I used openESB to create an LDAP web service Intalio could call to query for users and then send email notifications.  I have not been back to openESB in sometime, but I came across their new XMPP Binding Connector (BC).  I read some documentation and figured I could use the same design with XMPP that I did with LDAP.  Create a web service in openESB using NetBeans and then deploy the service to Glassfish Server and let Intalio call the web service.

So, here are the basic components.  Create a project with two WSDLs and one BPEL diagram.  The first WSDL I usually call trigger, since Intalio will call this end point and trigger the invocation of the XMPP WSDL.  The WSDL will be SOAP document literal and just pass in two parameters, jabber id (jid) and message.  The BPEL process will receive the message and then assign the variables for the XMPP WSDL.  Then invoke the XMPP WSDL and you are done.  You have to add the XMPP jar files to openESB but the documentation is on openESB for you to read.

Next take the WSDL for the trigger (SOAP document literal) and put it in your Intalio project.  Also take the schema you had to create for the WSDL and place that in Intalio.  Wire up the WSDL in the intalio mapper, deploy and test.

I installed OpenFire XMPP server locally and used PSI XMPP Client.  Installation and set up is easy.

Any questions, contact me at btmsoftwaresolutions.com.  Any other good XMPP uses in BPM let me know.

Intalio Timer - xPath Durations

This is a short blog to share my experience in creating a process which uses a parallel gateway in a potentially long ongoing process to allow users to perform work while process simultaneously calls a reporting service quarterly while that process is still in progress.  Here is how I did it:

The user form (Orbeon xForms) which kicks off the process determines the current date and using xpath sets date to either {year}-01-01T12:00:00.000, {year}-04-01T12:00:00.000,  {year}-07-01T12:00:00.000, or {year}-10-01T12:00:00.000.  If the month is 10, 11 or 12, one year is added to the current year so reporting quarter is in the correct year.

So, the process recives this dateTime value and it is mapped to a process variable called reportKickOff.  After the one parallel gateway branch a timer is placed and set to this value.  When the dateTime is reached, the process continues into a loop which first calls a reporting service and after service completes encounters another timer.  Here I take the reportKickOff value and add 3 months.  So, if it was 2009-01-01T12:00:00.000 it is now 2009-04-01T12:00:00.000.  The key here in the mapper is to take the reportingDate (of type xs:dateTime) variable and map to function op:add-yearMonthDuration-to-dateTime() and then map String "P0Y3M" of type xs:yearMonthDuration() to same function.  This is then mapped to 'date' variable in right side of mapper.

Once this date is reached, process continues into an intermediate event which resets the reportKickOff variable by adding another three months using the same technique above, the loop condition is evaluated and if condition to exit is not met, the process loops and calls the reporting service.  After the service completes, the timer is reached again and it waits until the next quarter.  This process repeats every 3 months until the loop is broken. 

To end the process, both branches of parallel gateway have to complete.  If user is done with this long ongoing process, before they reach the end of the parallel gateway I set reportKickOff variable to currentDate() and a loop variable to exit.  By setting the reportKickOff variable to currentDate(), the timer will release and the reporting loop will evaluate to exit.  Both parallel branches will now meet and the entire process can complete.  Before the process ends, I call the reporting service one last time to submit the data for the duration the process was in progress since last reporting period.

If you would like to learn more information about how you can use timers and loops like this in one of your Intalio processes - contact me at BTMSoftwareSolutions.com.

Intalio Diagram Web Service and Orbeon

Intalio and Orbeon yet again make my life so easy that I had to share a short blog about my late night coding. I had a thought today how I wanted to provide the ability for users to query some records and then start an Intalio business process off of one of those records. Now I did not want to develop a diagram that was a query and stick it into the processes tab of Intalio - too me a query is a query and may or may not lead to starting a process. And knowing that an Intalio Process does not have to start with a user entering data onto a form within Intalio, but may be started from any external system that can access a web service, I started down this path.

In a previous project, I developed a diagram which when compiled in Intalio creates a WSDL. This WSDL was provided to a client. The client imported that wsdl into ASP.NET and after several hours of trying to figure out the ASP.NET portion - we got processes kicked off from a .NET application into Intalio. Well, I use Orbeon forms and not ASP.NET. But I figured Orbeon is a powerful program, I should be able to start an Intalio process from an external Orbeon form. Yep - and pretty easy too. This is all that it took.

I had to create the diagram in Intalio which created my WSDL.

I had to create one instance, one control (Trigger) and one submission in my Orbeon xForm:

1. A Trigger inside a repeated table which would first dynamically set an xml element and second send a Submission to the web service
2. An instance which would hold the SOAP message passed to the web service. Inside the SOAP message body is the parameter the web service is expecting which I set above using the trigger and a setvalue action.
3. A submission which would invoke the web service and send the SOAP payload

That was it. Real simple. And here is another trick if you need it.

I use the soapUI plugin in the Intalio eclispe framework - great tool. To create a new wsdl project in soapUI you just browse out to the Intalio generated WSDL. Once you double click on the request message, you get the web service end point displayed for you and in the request frame, the SOAP payload which you can just copy and place within the xform instance you are going to reference in the submission. Just make sure you have any namespaces from your SOAP message referenced in the xhtml document or you will get an error.

Any questions or comments drop me a line:

Brian Steuhl: bsteuhl@btmsoftwaresolutions.com