IBM Worklight and IBM Business Process Manager Create a mobile BPM application …€¦ · · 2013-09-30This article describes how to integrate IBM® Worklight® and IBM Business

© Copyright IBM Corporation 2013 TrademarksCreate a mobile BPM application by integrating IBM Worklightand IBM Business Process Manager

Page 1 of 35

Create a mobile BPM application by integrating IBMWorklight and IBM Business Process ManagerGianpaolo Gabutti ([email protected])Senior IT SpecialistIBM

Luciano Raso ([email protected])Senior IT ArchitectIBM

Tony Pigram ([email protected])Solution ArchitectIBM

28 August 2013

This article describes how to integrate IBM® Worklight® and IBM Business Process ManagerV8.0.1 Standard (IBM BPM) by leveraging the IBM BPM REST APIs. By combining thepowerful development environment of IBM Worklight with the simplicity of the IBM BPM RESTAPIs, BPM developers can quickly deliver mobile applications to their BPM users.

IntroductionThis article describes the various components of a simple IBM Worklight mobile application thatinteracts with BPM processes via REST API calls. It shows all of the necessary componentsneeded to create a Worklight mobile application (in an Android™ environment) that enablesauthorised BPM users to activate, work on, and complete process tasks using their mobiledevices.

This article is targeted mainly at BPM developers who want to better understand how to enhancetheir BPM solutions with mobile capabilities, or who need to quickly improve their understandingof the possibilities offered by integrating the two products. The focus of this article is on hands-ondevelopment, not on infrastructure.

For all the aforementioned reasons and from an architectural standpoint, we have decided tokeep things as simple as possible. We developed our solution on the simplest and most basicenvironment, composed of a standalone IBM BPM server (IBM BPM Express V8.0.1), and IBMWorklight Developer Edition V5.0.6, because this environment is likely available to the majority ofthe readers. This simplified architecture has the advantage of being installable on a single machine

http://www.ibm.com/legal/copytrade.shtml

http://www.ibm.com/developerworks/ibm/trademarks/

mailto:[email protected]



developerWorks® ibm.com/developerWorks/

Create a mobile BPM application by integrating IBM Worklightand IBM Business Process Manager

Page 2 of 35

(the reader's laptop, for example) and can therefore be utilised as a self-study environment by"lone" developers to prove the concept and to enhance it as they experiment and learn more.

Although we assume that the reader has a basic knowledge of Java, JavaScript®, jQuery andBPM development, we have tried to avoid any possible complexity that could make reading thisarticle particularly difficult to inexperienced developers.

Sample code is included so you can set up and test the scenario yourself (and make your ownimprovements). This solution is a sample of the capabilities, and should only be used as a learningexercise in a development or test environment for self-study and education purposes.

Prerequisites

The process package is composed of a sample BPM process application called Car TyresOrder Placement, or CTOP, developed with IBM BPM Express V8.0.1 and available in the fileCarTyresOrderPlacement.twx.

The mobile package is composed of an IBM Worklight project, CarTyresOrderPlacementProject,developed with IBM Worklight Developer V5.0.6 in an Eclipse Juno 4.2 SR2 installation. Thepackage is available in the file CarTyresOrderPlacementProject.zip

The operating system we used was Microsoft® Windows® 7 with Java® Development Kit Version7 Update 13.

While we were writing the article, IBM released a new version of IBM Worklight (V6.0). We testedthe Worklight project in the new release and have not found any issues in migrating or running ourartefacts (adapters and application), so you can decide which version of Worklight to use. Pleasenote that the only supported Eclipse version for Worklight V6.0 is Eclipse Juno 4.2 SR2 package.

IBM also released a new version of IBM BPM (V8.5), and we also tested in this new release andfound no obvious issues. However, be aware that we developed and tested this sample on a BPMV8.0.1 environment.

In order to set up your IBM Worklight environment, we recommend that you follow the instructionsin IBM Worklight : Getting started. We will assume you are familiar with those documents and havefollowed those instructions.

You can import the sample IBM Worklight project into your Eclipse workspace in the same way asany other Eclipse project, although you must have previously installed the IBM Worklight plug-in,as instructed on the above link.

To import the sample, download and unzip the file onto your hard drive and use the standardEclipse option Import => Existing project into workspace.

In order to view the sample BPM process, you will also need to import the provided .twx file intoyour BPM environment. Although not necessary, you may want to create some users in your BPMProcess Center server (the user repository used by the process application). We assume that

http://www.ibm.com/developerworks/mobile/worklight/getting-started.html#setup

ibm.com/developerWorks/ developerWorks®


Page 3 of 35

you know how to create BPM internal users using the Process Admin Console. If not, refer to theproduct documentation.

Overview of IBM Worklight

Worklight helps organisations extend their business to mobile devices. It provides an open,comprehensive and advanced mobile application platform to build, run and manage mobileapplications. With Worklight, you can effectively develop, run and manage HTML5, hybrid andnative apps, and reduce your development cost, improve time-to-market and enhance mobile appgovernance and security. IBM Worklight uses standards-based technologies that avoid the use ofcode translation, proprietary interpreters and unpopular scripting languages.

A good starting point for understanding IBM Worklight is IBM Worklight : Getting Started. Hereyou'll find videos, demos, how-to information and other materials to help you gain a thoroughunderstanding of Worklight. You can also check out the Worklight Developer Edition supportcommunity on stackoverflow to ask questions and find answers about getting, installing, and usingWorklight.

Setting up the environment

After successfully installing and setting up the IBM Worklight and IBM BPM environments,you need to import the sample process. Open the IBM BPM Process Designer and importthe process application called Car Tyre Order Placement (CTOP) contained in the fileCarTyresOrderPlacement.twx included in the download sample package.

Test the sample process

Once you have imported the process application, open it in the Process Designer and then openthe BPD called Car Tyres Order Placement. then click Run to execute a new process instance.Switch to the Process Inspector view and verify that the sample process is working as expected.

Set up IBM Worklight

Unzip the file CarTyresOrderPlacementProject.zip onto your hard drive. Open up your Eclipse IDEand import the project by selecting File => Import, then select Existing project into workspace,as shown in Figure 1.

http://pic.dhe.ibm.com/infocenter/dmndhelp/v8r0m1/topic/com.ibm.wbpm.admin.doc/adminguide/topic/managing_users_A.html

http://www.ibm.com/developerworks/mobile/worklight/getting-started.html#setup

http://stackoverflow.com/



Page 4 of 35

Figure 1. Import the Worklight project into Eclipse

If you're using Worklight V6.0, the system will recognize that the project needs to be upgraded andwill automatically start the migration procedure for you.

For this sample, we used Android as the target platform for the mobile devices, but your choiceof the client environment operating system can be different from ours. You can add extraenvironments to the project after you have tested and ensured that the Android version is workingcorrectly.

Once you've finished importing the project, navigate to the server/conf directory of the project andopen the file worklight.properties. You'll need to modify the last section of this file to match yourBPM environment settings, as shown in the code snippet below.

######################################### Car Tyres Order Placement #########################################bpm.admin.user=adminbpm.admin.password=adminbpm.hostname=192.168.201.169bpm.port=9080

where:

• bpm.hostname is the BPM host name responding to the REST calls• bpm.port is the BPM port number for the REST calls (the default value is 9080).

Make sure you don't leave trailing blanks on the bpm.port element, or you'll see the followingerror message on the Worklight console when you deploy the adapters on the server:



Page 5 of 35

[2013-07-01 10:10:04] Adapter deployment failed[2013-07-01 10:10:04] Element <port> must be a number.

Overview of the sample process

In order to demonstrate how to integrate Worklight and IBM BPM, we created a simplified businessscenario, concerning an fictitious company called FooTyres.com. In our scenario, FooTyres.comis a tyre reseller company. The sales agents of FooTyres.com periodically visit their clients (suchas tyre dealers, tyre repairers, car mechanics, and so on) and collect orders from them during theirvisits. In some cases, the orders are placed by a sales agent after a telephone conversation withthe clients.

The sales agent starts the process by filling in the order details (such as the tyre characteristics,the quantity, and the proposed discount rate), and the system will calculate the total price for theorder. Once the sales agent fills in the remaining details (such as shipment address and due date),and the client is happy with the calculated price, the sales agent can send the order for approval.If the order has a total price or a discount rate greater than a given threshold (in our sample theselimits have been set to 5000 for the total price and to 8% for the discount rate), the order requiresapproval by a sales manager. If the total price or discount rate is lower than the threshold, theorder does not require approval and goes directly to the warehouse for shipment (the order is auto-approved).

The sales manager has the ability to reject the order for commercial reasons (for example, if theybelieve the discount rate is too high or the total price for the order is excessive for that specificclient). In such cases, the sales manager must explain the reason for the rejection and the orderwill be returned to the sales person. The sales person then has to decide to cancel the order, orresend it for approval, usually after having made an update. If the sales manager approves theorder, it is sent to the warehouse for the fulfillment.

The warehouse manager also has the ability to return the order to the sales agent, but in thiscase the reason is bound to logistic issues, for example, because they know they have run outof stock for that particular tyre, or because it is impossible for them to arrange the shipment bythe expected date. Likewise the sales managers have the ability to notify the sales agent of thereasons for their refusal to proceed with the order. Once the order has returned to the sales agent,he or she can update the order details (by changing, for example, the expected delivery date) andresubmit or cancel the order.

Once the order has been approved by the warehouse managers, the shipment is arranged and theprocess terminates. At this point, the process could be extended to notify an external accountingsystem, but this is not included in our sample.

The business scenario is illustrated in the business process definition (BPD) shown in Figure 2.



Page 6 of 35

Figure 2. The sample process

A walkthrough of the scenarioTo better understand which files and code do what, we'll step through a scenario from themobile application and indicate which related code is responsible for the functionality. To test theapplication, we'll use the Android v4.0.3 emulator.

From the Home page of the device, select to see the installed applications and click theCarTyresOrderPlacement icon, as shown in Figure 3.

Figure 3. Start the application

This starts the application and displays the initial screen. If the user is not already logged in, he orshe will see a simple screen showing two buttons: Get Task List and Logout.



Page 7 of 35

Clicking Get Task List invokes the challenge interaction (explained in depth in Implementauthentication and, if the user isn't logged in, he or she is prompted to enter a user name andpassword, then click Submit, which again invokes the challenge interaction. The authenticationadapter is called and an attempt to log in is made.

If this fails (for instance, the user forgot to change the IP address of the BPM server), the errormessage in Figure 4 is displayed.

Figure 4. Authentication error message

As you can see, the IP address that was set in the worklight.properties file points to192.168.201.169. Because this is incorrect, an exception is thrown. The Worklight console log alsodisplays the message shown in Figure 5.

Figure 5. Worklight console output

As you can see, that message is little more detailed. You need to open the worklight.properties fileand modify it point to the correct location of the BPM server, as shown in the code snippet below.

############################################################## Car Tyres Order Placement#############################################################bpm.admin.user=adminbpm.admin.password=adminbpm.hostname=192.168.201.172bpm.port=9083



Page 8 of 35

Once you've made this update, you'll need to rebuild and redeploy the application on the Androidenvironment. After downloading and reinstalling the application onto the device, you can log in asbefore. Once you're successfully authenticated, you'll see the BPM Task list associated with theuser (you).

Fetch and render the task list

As mentioned, clicking Get Task List" invokes the challenge interaction. This is done internally byWorklight because we have declared this method "protected" in the authenticationConfig.xml file.

Once the challenge has completed, the BPM task list is sent to the client application to beprocessed and rendered to the UI. Here is what happens in the callback function: functiongetTaskListOK(response) The purpose of this function is to receive the data returned by theadapter and to dynamically construct the content to be output to the <div> tag named responseDiv.

You can click on a listed task to open it, as shown in Figure 6.

Figure 6. Task list screen

Notice the click handler attached to each row (of class taskRow) representing an available task,as shown in the snippet below.

$('tr.taskRow').click(function() { var idx = $('tr').index(this); showOrder(myTaskData[idx-1].instanceId, myTaskData[idx-1].taskId);});

This JavaScript snippet invokes the showOrder() function when the task is clicked on by a user.The function is passed the instance id and the task id.

If you click on the first row in Figure 6, you should see the screen shown in Figure 7.



Page 9 of 35

Figure 7. Existing order details

The screen indicates that this order was previously submitted and was automatically approved.The fields are in read-only mode, except for the Notes field, which can be modified if there arefurther instructions for the shipping manager.

If you click the Get Task List button, you are returned to the initial task list screen.

To create a New Order on the mobile device, click the New Order button. A new order submissionscreen is displayed, as shown in Figure 8.



Page 10 of 35

Figure 8. New order

The values for the dropdown selection boxes are located in the UIMaterial.js file. For this sample,these values were hard-coded because they are unlikely to change often, if at all. The actualHTML for the screens is also hard-coded in the UIMaterial.js file. Depending upon which screen isbeing rendered, a call to the relevant function is made and a string response is returned. This is, inturn, returned and rendered in the responseDiv div tag. Following is function that returns the codeto render the New Order screen.

//Get the layout for placing a new order or updating an existing one (most of the data can be entered / updated) function getNewOrderLayout() {

return '<div class="box" id="message"></div>' + '<select id="widthSelect"></select><select id="profileSelect" style="float: right;"></select> <br><br>'+ '<select id="rimSizeSelect"></select> <select id="quantitySelect" style="float: right;"></select> <br><br>'+ '<label id="unitPriceLabel" for="unitPriceOutput" style="float: left; ">Unit Price : </label> <label isNumeric="true" baseType="Decimal" id="unitPriceOutput" style="font-weight : bold; ">0</label>'+ '<span style="float: right;margin-right:10px"> <label class="" id="totalPriceLabel" for="totalPriceOutput" >Total Price : </label> <label isNumeric="true" baseType="Decimal" id="totalPriceOutput" style="font-weight : bold;" >0</label> </span><br><br>'+ '<select id="discountSelect"></select> <input type="button" value="Calculate Price" onclick="calculatePrice()" class="formButton" style="float: right;" /> <br><br>'+ '<table width="100%">'+ '<tr> <td><label class="" id="nameLabel" for="nameInput" >Name : </label></td>



Page 11 of 35

<td colspan="2"><input id="nameInput" type="text" value="" initialValue="" style="width: 100%; float: right;" /></td> </tr>'+ '<tr><td><label class="" id="streetLabel" for="streetInput" >Street : </label></td> <td colspan="2"><input id="streetInput" type="text" value="" initialValue="" style="width: 100%;float: right;"/></td> </tr>'+ '<tr> <td><label class="" id="cityLabel" for="cityInput" >City : </label></td> <td colspan="2"><input id="cityInput" type="text" value="" initialValue="" style="width: 100%;float: right;" /></td> </tr>'+ '<tr> <td><label class="" id="datePickerLabel" for="datePicker" >Shipment Date : </label></td> <td><input id="datePicker" type="text" style="width: 100%;float: right;" /> </td> </tr>'+ '</table><br><br>'+ '<label class="" id="notesLabel" for="noteInput" >Notes : </label> <textarea id="notesInput" rows="2" style="width: 80%;float: right;"></textarea> <br><br>';

}

This function might look a little weird at first glance, but it actually simply returns a Stringrepresenting the content for a div HTML element. The div is further manipulated by some jQuerycode, as you'll see in the section Client-side development. The user can select the values from theselection boxes, as shown in Figure 9.

Figure 9. Device dropdown selection



Page 12 of 35

In a web browser, the dropdown selection box would have just shown itself as such on the pageand the user would have selected a value with either the keyboard or a mouse click. However,because this application is running on a mobile device, the native method of rendering a dropdownselection is used. The user can swipe up and down to go through the list of items. The UI functionsthe same way for the Profile, Rim Size, Quantity and Discount fields.

Once those fields have been selected, the user can press the Calculate Price button, as shown inFigure 10 to calculate the Unit and Total price based upon any selected Discount value.

Figure 10. JQuery datePicker control

The user can then enter text for Name, Street and City. Since this is a mobile application, textentry should be kept to a minimum to prevent typing mistakes.

When the user clicks the Shipment Date field, the jQuery datePicker is displayed, as shown inFigure 10 and he or she can scroll through a calendar to select a future date.

The code to include the datePicker in the screen is located in three files: UIMaterial.js,CarTyresOrderPlacement.js and CarTyresOrderPlacement.html. As mentioned earlier, theUIMaterial.js file returns the HTML to render the output to the screen. The following snippet showswhere the datePicker is defined.

<input id="datePicker" type="text" style="width: 100%;float: right;" />

In the CarTyresOrderPlacement.js file, an initialiser function is called when the New Order screenis to be displayed. This initialises the datePicker and sets the correct date format. Because theinput field has an id of datePicker, it is detected as requiring the pop-up calendar to be invoked asshown below.



Page 13 of 35

function initNewOrderLayout() {

$('#ResponseDiv').html(getNewOrderLayout()); $('#message').hide(); // Hide the message box $('#message').click(function() {

$('.box').animate({ opacity : 'toggle', height : 'toggle' }); }); //Init the date picker with the proper format... $( "#datePicker" ).datepicker({ dateFormat: "dd-mm-yy" });

addOptions('#widthSelect', widthOptions); addOptions('#profileSelect', profileOptions); addOptions('#rimSizeSelect', rimSizeOptions); addOptions('#quantitySelect', quantityOptions); addOptions('#discountSelect', discountOptions);}

Finally, the CarTyresOrderPlacement.html file contains the include files that are required for theJQuery DatePicker, as shown in the snippet below.

 <link rel="stylesheet" href="http://code.jquery.com/ui/1.10.3/themes/smoothness/jquery-ui.css" /> <script src="http://code.jquery.com/jquery-1.9.1.js"></script> <script src="http://code.jquery.com/ui/1.10.3/jquery-ui.js"></script> 

Check out the jQuery datepicker web site for more information on the jQuery datePicker.

Submit the new order

Once the user has finished entering the details, he or she can press Submit Order, as shown inFigure 11.

http://jqueryui.com/datepicker/



Page 14 of 35

Figure 11. Submit a new order

The new order details are passed back to the newOrder() function (contained in theCarTyresPlacement.js file). As shown in the snippet below, this function then calls thestartProcess() function in the CarTyresOrderPlacementSOAPAdapter-impl.js file. ThestartProcess() function constructs a SOAP message containing the new order data and invokesa SOAP call to the BPM server.

Note that the other interactions, such as getOrderDetails, getTaskList and CompleteOrder usethe REST API.

function newOrder() {

initNewOrderLayout();

$('#newOrder').hide(); // Hide new order button $('#submitOrder').show(); // Show submit order button $('#complete').hide();// Hide complete button $('#header').html("New order submission"); $('#submitOrder').click(function() { hideMessage();

var myOrder = checkOrder(); // WL.Logger.debug(JSON.stringify(myOrder));

if (myOrder != null) { var invocationData = { adapter : "CarTyresOrderPlacementSOAPAdapter", procedure : "startProcess", parameters : [ myOrder ] }; var options = { onSuccess : newOrderOK, onFailure : newOrderFAIL };



Page 15 of 35

WL.Client.invokeProcedure(invocationData, options); }

});}

Once the submission has been successful, the user gets the message shown in Figure 12.

Figure 12. New order successful

If for some reason the order submission failed, the user is informed of this via this samemechanism. You can use Process Designer to verify that the new order submission really worked.Load the Car Tyres Order Placement process and click on the Process Inspector view, as shown inFigure 13.

Figure 13. Process Inspector view

Here you can see that a new process instance has been created and that the process token hasmoved onto the Approval step. By using the debugging feature on the right, you can double-clickthe order variable and view the contents to verify that the data you entered on the New Orderscreen on the mobile device has been successfully passed to this new process instance.

Now, when you return back to the Task List screen on the mobile device, shown in Figure 14you will see the new task in the list and you will see that the indicator is a different colour, whichindicates that the task requires approval.



Page 16 of 35

Figure 14. Task List showing new task in the list

Note: Because we're logged in as admin in our sample, we're able to see all tasks associated withthe sample process. If you were logged in as a non-admin user, you would only see the tasks thatbelong to our user. Because this is a developer article, we want to show everything, but be awarethat when you run this sample with a real user account assigned to the swimlanes and activities,you won't see tasks that do not belong to you on the Task List screen.

If you click on the last Task in the list (the new order that is awaiting approval), you can verify thatthe data is correct, as shown in .

Figure 15. Display task details



Page 17 of 35

The screen in is dynamically constructed from the getApproveOrderLayout() function in theUIMaterial.js file. The actual order details are retrieved by calling the getOrderDetails() functionin the CarTyresOrderPlacement.js file, as shown below.

function getOrderDetails(taskId,callBack) {

var order = null; var invocationData = { adapter : "CarTyresOrderPlacementRestAdapter", procedure : "getOrderDetailByTaskId", parameters : [ taskId ] };

WL.Client.invokeProcedure(invocationData, { onSuccess : function(response) { [...]

This in turn calls the REST API adapter getOrderDetailByTaskId() function in theCarTyresOrderPlacementRestAdapter-impl.js file, as shown below.

function getOrderDetailByTaskId(taskId){

path = 'rest/bpm/wle/v1/task/'+taskId+'?parts=all';

var input = { method : 'get', returnedContentType : 'json', path : path };

response=WL.Server.invokeHttp(input); WL.Logger.debug(JSON.stringify(response)); return response;}

Log out

On any of the screens, the user can click on Logout to cancel the current session authentication.If the user subsequently selects Get Task List, he or she will have to re-enter the user name andpassword and be re-authenticated.

Approve an order

The approval scenario occurs when an order needs approval by the managers or by thewarehouse. In this scenario, most of the order data is presented as labels, because it cannotbe modified by the approvers, except for the Notes field, where the approvers are supposed toenter the reason for denying approval before sending back the order to the sale agent, and theApproved and Shipped checkboxes.

Update an existing order

This scenario occurs when an order has been sent back to the sales agents by the managers or bythe warehouse. The UI in this case is similar to that in the Submit the New Order scenario, exceptthat in this case the data is already filled in and ready to be modified.



Page 18 of 35

Server-side development

For information on the role of the adapters in Worklight, their different typology, and how toconfigure them, refer to the developerWorks Worklight server-side development documents.

Our sample shows the usage of HTTP adapters in two different flavours: a SOAP/HTTP adapter(the adapter that starts the process) and a REST adapter (to carry on all other interactions with theBPM server)

Implement authentication

In a real production environment, the authentication will be handled differently than in our sampleapplication. Nevertheless, we believe there are some advantages in developing an ad-hoc,simplified authentication mechanism, even for a basic environment such as ours, because:

• It helps in understanding the functioning of the authentication and authorisation mechanismavailable out-of-the-box with IBM Worklight.

• It can be used in proofs of concept to simulate the runtime behaviour for more complexenvironments.

A general description of how security is handled by the IBM Worklight platform is explained indetail in the developerWorks Worklight authentication and security topics. These documentsprovide clear and simple instructions on how to create adapters using the wizard that comes withthe Worklight plug-in.

Before discussing the adapter authentication implementation, we want to clarify some conceptsthat we believe are important to understand before proceeding further. As described in the IBMWorklight documentation:

• An authenticator is a server-side entity responsible for collecting the credentials from theclient application (this activity is also called "challenge").

• A login module is a server-side entity responsible for verifying the user credentials (andfor creating a user identity object, which holds the user properties for the remainder of thesession).

• An authentication realm defines the process to be used to authenticate users.• Each authentication realm consists of one authenticator and one login module.• Each authentication realm requires a challenge handler component to be present on a

client side.• A security test is an ordered set of authentication realms that is used to protect a resource,

such as an adapter procedure, an application, or a static URL.

All these authentication settings are configured in the server/conf/authenticationConfig.xml file ofthe project.

With a clearer understanding of these concepts, let's look at how to proceed in order to protect aresource (in our case the resource is represented by an adapter procedure).

http://www.ibm.com/developerworks/mobile/worklight/getting-started.html#server-side-development

http://www.ibm.com/developerworks/mobile/worklight/getting-started.html#security



Page 19 of 35

Server-side configuration

The first things to be configured are the adapter procedures, which need to be protected. In oursample, we've protected the procedure that provides the users with the list of tasks available tothem (what's known on a BPM portal server as the Task Inbox view). The procedure's name isgetTasksList() and it is implemented by the adapter CarTyresOrderPlacementRestAdapter. Youmust add the following entry in the CarTyresOrderPlacementRestAdapter.xml file.

<procedure name="getTaskList" securityTest="SimpleAuthAdapter-securityTest"> <description>Gets the initial task list for the user</description></procedure>

We are stating here that the usage of this procedure is subject to a security test called"SimpleAuthAdapter-securityTest".

The next step is the definition of the security test: this needs another entry in the file "server/conf/authenticationConfig.xml":

</securityTests> <customSecurityTest name="SimpleAuthAdapter-securityTest"> <test isInternalUserID="true" realm="CTOPAuthRealm"/> </customSecurityTest></securityTests>

If the internal users are in the authentication realm called CTOPAuthRealm, they are to beconsidered as authenticated.

The next step is the definition of the realm, which is another entry in the same file, as shownbelow.

<realms> <realm name="CTOPAuthRealm" loginModule="SimpleAuthLoginModule"> <className>com.worklight.integration.auth.AdapterAuthenticator</className> <parameter name="login-function" value="SimpleAuthAdapter.onAuthRequired"/> <parameter name="logout-function" value="SimpleAuthAdapter.onLogout"/> </realm></realms>

As defined earlier, an authentication realm is made up of one authenticator and one login module.Therefore, here we declare the login module used by this realm and the class implementation forour authenticator. We also declare the callback methods invoked by Worklight when authenticationis required or when the user logs out.

The final configuration step is to define our login module. To do this, you add the entry below in theserver/conf/authenticationConfig.xml file.

<loginModules> <loginModule name="SimpleAuthLoginModule"> <className>com.worklight.core.auth.ext.NonValidatingLoginModule</className> </loginModule><loginModules>



Page 20 of 35

Here we chose the predefined NonValidatingLoginModule, which means that no additionalvalidation is performed by Worklight, and the developer must take responsibility for the credentialvalidation in the adapter (in our sample, this is contained in SimpleAuthAdapter).

Now that the authentication configuration steps are complete, you need to implement theJavaScript components. To accomplish this, you need a client-side challenge handler and aserver-side authenticator.

Implement the challenge handlerThe challenge handler must implement two methods:

• isCustomResponse(): This function is called by Worklight each time that a response isreceived from the server. It is used to detect whether the response contains data that isrelated to this challenge handler and must return either true or false.

• handleChallenge(): If the isCustomResponse returns true, the framework calls thehandleChallenge() function. This function is used to perform required actions (in our sample,we present the user with a login screen on which they can enter their user name andpassword. Once they have entered these values, we invoke the adapter's authenticationprocedure using the API submitAdapterAuthentication. This challenge handler's API is usedto send collected credentials to a specific adapter procedure.In the sample provided, you'll find the following this function call:var invocationData = { adapter : "SimpleAuthAdapter", procedure : "submitAuthentication", parameters : [ username, password ] };

simpleAuthRealmChallengeHandler.submitAdapterAuthentication(invocationData, {});

Implement server-side authenticationOn the server side, you need to implement the authenticator SimpleAuthAdapter. To developour adapter, we found that a good starting point is the example provided in the presentation IBMWorklight V5.0.6 Getting Started: Custom Authenticator and Login Module (PDF).

During the challenge, the client application invokes submitAuthentication(username, password),so you need to create a function to handle this. This function must return a JSON object to theclient, stating whether the authentication was successful or not. The returned object is as follows:

{ authRequired: true, errorMessage: errorMessage, isSuccessful : false}

If you need to authenticate the user (the security test was unsuccessful) or if the security test ispassed, the following is returned:

{ authRequired: false}

http://public.dhe.ibm.com/software/mobile-solutions/worklight/docs/v506/08_04_Custom_Authenticator_and_Login_Module.pdf

http://public.dhe.ibm.com/software/mobile-solutions/worklight/docs/v506/08_04_Custom_Authenticator_and_Login_Module.pdf



Page 21 of 35

By examining our sample, you'll notice that in order to check whether the credentials are valid,the submitAuthentication() function utilises the internal function checkUser(user, password).In our implementation, we send an HTTP post request to the BPM server and check whether theresponse contains an LtpaToken. If the credentials are valid, the server will send back a cookie(LtpaToken2) to be used for subsequent requests, otherwise the cookie will not be present in theresponse. For our sample, we're not interested in storing the cookie, we just need to check that itexists.

Following is the implementation of the submitAuthentication() function:

function submitAuthentication(username, password){

var userDetails = checkUser(username,password);

if (!userDetails.isSuccessful) { return onAuthRequired(null, userDetails.errors[0]);

} elseif (userDetails.data != undefined && userDetails.data != null ){ //Store user's data var userIdentity = { userId: username, displayName: userDetails.data.fullName, attributes: { memberships : userDetails.data.memberships } };

WL.Server.setActiveUser("CTOPAuthRealm", userIdentity);

return { authRequired: false }; }

It's worth noting that if the authentication succeeded, the user is set as active in the CTOPAuthRealmby using the server API WL.Server.setActiveUser(). This will prevent the failure of further securitytests.

The second function that needs to be implemented is the protected function getTaskList(). Thisperforms a query on the BPM server using the REST API, and returns a list of tasks available forthe authenticated user (the list is represented by an array of JSON objects). This request is madeon behalf of the user, but this time the system utilises the HTTP "basic authentication" mechanism,which we'll explain in more detail.

To confirm what happens at runtime, following is the complete sequence of steps that occur whenthe protected function is invoked:

1. The client invokes the adapter's protected procedure (getTaskList()).2. Worklight intercepts the request and activates the challenge mechanism. If the security test

is not satisfied, the client challenge handler receives a callback on its isCustomResponsemethod, signaling that authentication is requested.



Page 22 of 35

3. The client handles the challenge by invoking the adapter's submitAuthentication()procedure

4. The client receives a second notification and is now able to determine whether theauthentication procedure ended successfully (the user is authenticated).

5. If the user is authenticated, the client informs the server that it intends to carry on withthe initial procedure invocation (this is done by invoking the challenge handler APIsubmitSuccess()).

6. The client receives the response of the initial invocation to the protected procedure andrenders the result.

Create the adaptersEach adapter can be created using the wizard provided by the Worklight developmentenvironment. When you create a new adapter, you'll see the wizard shown in Figure 16, where youenter the adapter name and type.

Figure 16. Worklight Adapter wizard

This creates a folder with the structure shown in Figure 17.

Figure 17. Adapters folder structure



Page 23 of 35

<AdapterName>.xml is the adapter descriptor, and contains several adapter configurationparameters. If the adapter type is set to HTTP, you need to enter information about the usedprotocol, the server address and port used for the connection and the type of authentication, asshown in Figure 18.

Figure 18. Adapters descriptor connection policy

The SOAP adapterWhen the user presses the Submit button on the New Order screen, a new process instanceof the BPM sample process Car Tyres Order Placement is created. The new instance can belaunched using the Start Event (WS Start) that is associated with a web service, as shown inFigure 19.

Figure 19. The entry point of the SOAP adapter in the process

This task is performed by the HTTP adapter CarTyresOrderPlacementSOAPAdapter, which isdefined by the following descriptor:

<wl:adapter name="CarTyresOrderPlacementSOAPAdapter" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:wl="http://www.worklight.com/integration" xmlns:http="http://www.worklight.com/integration/http">

<displayName>CarTyresOrderPlacementHTTPAdapter</displayName> <description>CarTyresOrderPlacementSoapAdapter</description> <connectivity> <connectionPolicy xsi:type="http:HTTPConnectionPolicyType"> <protocol>http</protocol> <domain>${bpm.hostname}</domain> <port>${bpm.port}</port> <authentication> <basic /> <serverIdentity> <username>${bpm.admin.user}</username> <password>${bpm.admin.password}</password> </serverIdentity> </authentication>



Page 24 of 35

</connectionPolicy> <loadConstraints maxConcurrentConnectionsPerNode="2" /> </connectivity>

<procedure name="startProcess" securityTest="SimpleAuthAdapter-securityTest"> <displayName>start process</displayName> </procedure></wl:adapter>

The adapter contains only the procedure exposed to the client: startProcess(order). Thisprocedure is set as protected, (the same as the other procedures in this sample), by means of thesecurity test SimpleAuthAdapter-securityTest described in the previous section. This procedureinvokes the web service by building the SOAP envelope derived from the WSDL file that describesthe web service itself.

In general, if you have to invoke a web service from a Java class, you can use one of the severalframeworks available, such as AXIS, which provides wizards to generate the helper classes aswell as the core classes needed to call the web service. These helper classes provide a moreabstract layer that helps developers simplify a web service call, thereby hiding the complexity ofthe marshalling and un-marshalling of the object model used to exchange data between the clientand the web service. They also hide the complexity of communicating through the HTTP protocol.

In our sample we're using JavaScript to implement the adapter, not Java, so we have noframework or wizard available to generate the web service request. However, a Worklight HTTPadapter simplifies the exchange of data with a back-end system via the HTTP protocol, because itonly requires the SOAP envelope that is needed to invoke the web service.

To create the envelope, we exploited the envelope skeleton generated by the open-source SoapUItool, which helps with the testing and analyzing of web services. Given a WSDL, SoapUI cangenerate the corresponding envelope template filled in with the requested data, as shown in Figure20.



Page 25 of 35

Figure 20. The envelope to start the process as shown in SOAP UI

Each of the above ? symbols needs to be replaced with the correct data value. Using the followingsnippet, the adapter can merge the above template with the requested data:

var request = '<soapenv:Envelopexmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:star="http://CTOP/StartWS.tws">' + ' <soapenv:Header/>' + ' <soapenv:Body>' + ' <star:createOrder>' + ' <star:order>' + ' <star:userId>'+user.userId+'</star:userId>' + ' <star:quantity>'+order.quantity+'</star:quantity>' + ' <star:width>'+order.width+'</star:width>' + ' <star:profile>'+order.profile+'</star:profile>' + ' <star:rimSize>'+order.rimSize+'</star:rimSize>' + ' <star:unitPrice>'+order.unitPrice+'</star:unitPrice>' + ' <star:discount>'+order.discount+'</star:discount>' + ' <star:total>'+order.total+'</star:total>' + ' <star:notes>'+order.notes+'</star:notes>' + ' <star:dateRequired>'+order.dateRequired+'</star:dateRequired>' + ' <star:shippingAddress>' + ' <star:name>'+order.shippingAddress.name+'</star:name>' + ' <star:street>'+order.shippingAddress.street+'</star:street>' + ' <star:city>'+order.shippingAddress.city+'</star:city>' + ' </star:shippingAddress>' + ' <star:approved>'+order.approved+'</star:approved>' + ' <star:canceled>'+order.canceled+'</star:canceled>'



Page 26 of 35

+ ' <star:shipped>'+order.shipped+'</star:shipped>' + ' </star:order>' + ' </star:createOrder>' + ' </soapenv:Body>' + '</soapenv:Envelope>';

The following snippet obtains the envelope that will be sent to the BPM using the API provided byWorklight:

var path = "teamworks/webservices/CTOP/StartWS.tws";var input = { method : 'post', returnedContentType : 'xml', path : path, headers : { 'SOAPAction' : 'http://CTOP/StartWS.tws/createOrder' }, body : { content : request, contentType : 'text/xml; charset=utf-8' } }; response = WL.Server.invokeHttp(input);

In the snippet above, there is no evidence of the web service endpoint. This is computed byWorklight, which concatenates the information in the adapter descriptor as shown here:

<connectivity> <connectionPolicy xsi:type="http:HTTPConnectionPolicyType"> <protocol>http</protocol> <domain>${bpm.hostname}</domain> <port>${bpm.port}</port>

The value of the variable path is set to the following:

var path = "teamworks/webservices/CTOP/StartWS.tws";

The REST APIsIBM BPM provides a set of APIs that are implemented using Representational State Transfer(REST) services. A set of business process definition (BPD) related REST resources are providedfor accessing business process, human task and business category data. These REST APIsenable developers to build a user interface or customise an existing portal application. The APIsare simple enough to be called from mobile devices or from Rich Internet Applications (RIAs).

For more information on how to use the REST APIs in IBM BPM, refer to the developerWorksarticle Using the REST APIs in IBM Business Process Manager V7.5.

The REST adapterThe REST adapter CarTyresOrderPlacementRestAdapter contains all the functions needed toinvoke some of the RESTFUL services provide by the IBM BPM. Like the SOAP adapter, theREST adapter is an HTTP adapter. The REST API is invoked through the HTTP protocol. Thedescriptor of the REST adapter shows that it defines and exposes to the client the following threefunctions:

http://www.ibm.com/developerworks/websphere/library/techarticles/1108_thaker/1108_thaker.html



Page 27 of 35

function getTaskList()function getOrderDetailByTaskId(taskId)function completeOrder(order)

You can define the connectivity policy in the descriptor, as shown in Figure 21, so that when theAPI WL.Server.invokeHttp is called, you don't need to provide the connectivity details.

Figure 21. The adapter editor

Following is a brief description of each of the three functions defined by the REST adapter:

Function getTaskList()

The purpose of this function is to retrieve the list of tasks assigned to the current mobile useror to the participant group to which this user belongs. To retrieve the task list the followingsnippet of code is used:function getTaskList() { var user = WL.Server.getActiveUser().userId; path ='rest/bpm/wle/v1/search/query?condition=bpdName%7CCar%20Tyres%20Order%20Placement&condition=taskStatus%7CReceived&organization=byInstance'; var input = { method : 'put', returnedContentType : 'json', path : path }; return filterTaskList(WL.Server.invokeHttp(input), user);}

Because the authentication mechanism is based on the information hard-coded in the adapterdescriptor, each call to a service is done using the "admin" user. In this way, the retrieved tasklist can contain tasks that cannot be assigned to the user logged into the mobile application.For this reason, the task list must be filtered in order to exclude those tasks and only includethe tasks that belong to the logged in user.



Page 28 of 35

In order to do that, for each task the assignedTo property is compared to the list of groupsto which the logged on user belongs. If the task is assigned to a group of which the user ismember the task is left in the list, otherwise it is removed.

function filterTaskList(response, user) { var filteredTaskList = []; var data = response.data.data; var groups = getUserGroups(user); for ( var i = 0; i < data.length; i++) { var task = data[i]; if (checkAssignement(task,user,groups)){ filteredTaskList[filteredTaskList.length]=task; } } response.data.data=filteredTaskList; return response;}

To retrieve the list of groups to which the user belongs, you can use the following function:function getUserGroups(user) { var groups = new Array(); var path = 'rest/bpm/wle/v1/users?filter=' + user + '&includeTaskExperts=false&sort=true &includeInternalMemberships=true&parts=all'; var input = { method : 'get', returnedContentType : 'json', path : path }; response = WL.Server.invokeHttp(input); if (response != null && response.data.users.length > 0) { groups = response.data.users[0].memberships; } return groups;}

Function getOrderDetailByTaskId(taskId)When the user selects a row on the task list, the data related to the corresponding order isretrieved by calling this function. In this case, the required data is retrieved calling a RESTfulservice provided by BPM. This function does not present any particular issue, as you can seeby looking at the following code:function getOrderDetailByTaskId(taskId) { path = 'rest/bpm/wle/v1/task/' + taskId + '?parts=all'; var input = { method : 'get', returnedContentType : 'json', path : path }; response = WL.Server.invokeHttp(input); return response;}

function completeOrder(order)When the user creates or approves a new order or modifies a rejected order they have topress the Submit button to invoke the function.



Page 29 of 35

This function calls a RESTful service and passes the order data that the user has enteredvia the mobile application. This behaviour is the same as if the user had worked on the orderwithin a traditional BPM human task coach. Because a task has been created in BPM, thetask data is passed to that service and the task is completed. Once this occurs, the processflows to the next task in the process.

The only remarkable aspect in this function is that BPM expects the date in ISO8601 format (0000-00-00T00:00:00Z), but when JavaScript converts the object orderfrom JSON to a String, each property defined as a date is converted in the format0000-00-00T01:02:03.mmmmZ, which makes the REST call fail. We solved the problem withthe following workaround:

var orderToBeSent = JSON.stringify(bpmOrder).replace(/\.[0-9][0-9][0-9]Z/g,"Z");

This replaces each date to the format as expected by BPM. The following is the completefunction code:

function completeOrder(order) { var bpmOrder = new BPMOrder(order); if (bpmOrder.userId == null || bpmOrder.userId == "") bpmOrder.userId = "admin"; var orderToBeSent = JSON.stringify(bpmOrder).replace(/\.[0-9][0-9][0-9]Z/g,"Z");// correct date format: millisec not accepted by bpm -> from // 0000-00-00T01:02:03.mmmmZ to 0000-00-00T01:02:03Z path = 'rest/bpm/wle/v1/task/' + order.taskId + '?action=finish&params=' + escape('{"order":' + orderToBeSent + '}') + '&parts=all'; var input = { method : 'put', returnedContentType : 'json', path : path }; response = WL.Server.invokeHttp(input); return response;}

Client-side developmentAlthough there are many possibilities to improve the client UI with fancy widgets, we decidedto keep the UI as basic and simple as possible. The UI can be improved in many ways, butthis should be done once the basic pieces of functionality have been understood, set up andimplemented. We based the UI for this article on what is available out-of-the-box with the IBMWorklight: platform: jQuery.

In order to show how a jQuery plug-in can be effectively used, we placed a jQuery datepickerwidget for selecting dates in the UI. The widget is available here.

Client-side materialThe client material is composed by a set of JavaScript .js files, an HTML file, a .css file and someimages. After you have imported the project into your workspace, open the Java EE perspectiveand check that the Project Explorer view is the same as shown in Figure 22. The client-sidematerials are described in this section.

http://jqueryui.com/datepicker/



Page 30 of 35

Figure 22. The apps folder structure

CarTyresOrderPlacement.htmlThis is the main HTML page and will not change throughout the lifespan of a user's session.The HTML contains two HTML div elements (ResponseDiv and AuthDiv), which are manipulatedthrough the jQuery functions whenever a response has been received by the Worklight server.A typical example of manipulation of DOM in order to change the div content is represented bythe function getTaskListOK(), the callback function that runs upon a successful invocation of theadapter procedure getTaskList() :

var myTaskData = response.invocationResult.data.data; var tasks = null; if (myTaskData != null) { tasks = $.map(myTaskData, function(value, i) {

var image= "'images/mblDomButtonOrangeBall.png'"; if (value.taskSubject.indexOf("Approval") > 0) image= "'images/mblDomButtonRedBall.png'"; elseif (value.taskSubject.indexOf("Shipment") > 0) image= "'images/mblDomButtonGreenBall.png'";



Page 31 of 35

return '<td><img src='+image+'/></td><td><b>Order Number : </b>'+ value.instanceId + ' <b>Activity : </b>'+ value.taskSubject+'</td>'; }); } if (tasks == null || tasks.length == 0) $('#ResponseDiv').html('No orders found '); else $('#ResponseDiv').html( '<br/><table><tr class="taskRow">' +tasks.join('</tr><tr class="taskRow" >')+ '</tr></table>');

As you may notice, the JSON object representing the response is used to build a valid array ofHTML td elements. These elements are then joined together so to build an HTML table, which iseventually used to set the content of the div (by using the jQuery html() function).

BO.jsBo.js contains the JavaScript business objects used client-side CarTyresOrderPlacement.js. Itcontains the main JavaScript code to handle the interactions with the Worklight server. Basically,depending on the button clicked by the user, an adapter procedure gets invoked and a responseis received back as a JSON object. The code then builds the content of the ResponseDiv andattaches the handlers to various elements in order to provide the correct sequence of events. Thecode is commented to make easy to understand what operations are being executed.

You can use the usual JavaScript debugging tools to debug this code when it runs as a commonresource or in the mobile browser simulator.

InitOptions.jsThis file is generated automatically by the wizard when a new project is generated, and we left itmostly untouched.

Messages.jsThis file is also generated automatically by the wizard when a new project is generated. Itspurpose is to provide a place for the internationalisation (i18n) of the messages, which we didnot consider in our sample (although it is something which is normally necessary in a real worldapplication).

SimpleAuthRealmChallengeProcessor.jsThis file contains the JavaScript client code to handle the challenge, as described previously in thisarticle

UIMaterial.jsThis file contains some utility functions to support the UI interface.

CarTyresOrderPlacement.cssThis file contains the common CSS statements (that is, the default CSS definitions). Thesestatements may be overridden by other CSS files leveled at the diverse environments (such asAndroid, for example)



Page 32 of 35

Conclusion

In this article, we provided concepts and sample code to help you see the benefits and possibilitiesof integration between IBM Worklight and IBM BPM using the REST API. It's our hope that you'veseen how simple it is to achieve this integration -- not a single line of Java code was needed todevelop the application!

Next steps

The following is a list of potential enhancements that you could undertake. These are things thateither we didn't have time to finish or would have liked to have done a little differently:

• Internationalisation• Pushing notifications to the mobile users once events occur on the server side• UI improvements (using additional jQuery plug-ins)



Page 33 of 35

Downloads

Description Name SizeSample application CarTyresOrderPlacement.twx 1MB

Sample project file CarTyresOrderPlacement.zip 17MB

http://www.ibm.com/developerworks/apps/download/index.jsp?contentid=942182&filename=CarTyresOrderPlacement.twx&method=http&locale=

http://www.ibm.com/developerworks/apps/download/index.jsp?contentid=942182&filename=CarTyresOrderPlacement.zip&method=http&locale=



Page 34 of 35

Resources

• IBM Worklight• Eight steps to IBM Worklight mobile application development• IBM BPM V8 Information Center• Using the REST APIs in IBM BPM• Using the REST APIs in IBM Business Process Manager V7.5• developerWorks Worklight Developer zone• IBM Software Services for WebSphere: Find out how IBM expertise in cutting-edge and

proven technologies can help you achieve your business and IT goals.• developerWorks BPM zone: Get the latest technical resources on IBM BPM solutions,

including downloads, demos, articles, tutorials, events, webcasts, and more.• IBM BPM Journal: Get the latest articles and columns on BPM solutions in this quarterly

journal.

http://www-03.ibm.com/software/products/us/en/worklight/

http://www.ibm.com/developerworks/websphere/techjournal/1210_chen/1210_chen.html

http://pic.dhe.ibm.com/infocenter/dmndhelp/v8r0m1/index.jsp

http://pic.dhe.ibm.com/infocenter/dmndhelp/v8r0m1/index.jsp

http://www.ibm.com/developerworks/websphere/library/techarticles/1108_thaker/1108_thaker.html

http://www.ibm.com/developerworks/mobile/worklight/

http://www.ibm.com/developerworks/websphere/services/

http://www.ibm.com/developerworks/bpm/

http://www.ibm.com/developerworks/bpm/bpmjournal/



Page 35 of 35

About the authors

Gianpaolo Gabutti

Gianpaolo Gabutti is a Senior IT Specialist in Italy, where he works as a businessprocess management consultant in IBM Software Services for WebSphere. Hehas been working in the IT industry since 1988, and has experience in diversetechnologies, such as object-oriented programming, Enterprise ApplicationIntegration, J2EE and Eclipse. He holds a degree in Economics from the CatholicUniversity of Milan.

Luciano Raso

Luciano Raso is an IBM IT Architect from Italy. In IBM since 1989, he has beenworking as an IT architect on different technologies related first to distributed systemsand then to JEE systems. In 2010, he joined Software Group as a Technical Salesand Solution Specialist in the business process management (BPM) and operationaldecision management (ODM) areas. He holds a degree in Electronic Engineering.

Tony Pigram

Tony Pigram is an IBM Solution Architect with 20 years experience across a broadspectrum of technologies. He spent seven of those years working as a Consultantin the Enterprise Mobile Application industry. He currently works on the IBM SmarterProcess portfolio.

© Copyright IBM Corporation 2013(www.ibm.com/legal/copytrade.shtml)Trademarks(www.ibm.com/developerworks/ibm/trademarks/)

http://www.ibm.com/legal/copytrade.shtml

http://www.ibm.com/developerworks/ibm/trademarks/

Documents

IBM Worklight and IBM Business Process Manager Create a mobile BPM application …€¦ · · 2013-09-30This article describes how to integrate IBM® Worklight® and IBM Business