Using the Undercover Agent with a message event in WebSphere Lombardi Edition V.7.2

This tutorial demonstrates both the Intermediate and Start Message Events to restart an activity, terminate a process, update a process state, and start a new process application in WebSphere® Lombardi Edition. The events are released by the Undercover Agent. You will learn about the Undercover Agent, services, message events, human services, and some basic tasks in Lombardi Edition.

Share:

Danh Ngoc Phi (phidn@vn.ibm.com), IT Specialist, IBM

Photo of Danh Ngoc PhiDanh Ngoc Phi is a Software Developer with the IBM Software Group in IBM Vietnam. He has more than five years of experience in software development, maintenance, deployment, and support as an IT Specialist, Technical Team Leader, and Technical Architect.



26 October 2011

Introduction

WebSphere Lombardi Edition V7.2 (hereafter called Lombardi Edition) has two kinds of message events: Intermediate Message Event (IME) and Start Message Event (SME). A message event represents a data where incoming message is captured. A message event is derived from several sources, one of which is from the Undercover Agent (UCA). When receiving the message event, you need to have a message event listener respond to the event. The IME listens to all events occurring anywhere in the process. The function of the SME is similar to the Start Event based on the incoming message.

Objectives

This tutorial demonstrates both Intermediate and Start Message Events. The events are released by the UCA. The IME (listener) restarts an activity, terminates a process, and updates a process state. The SME (listener) starts a new process application.

In this tutorial, you will learn how to use the:

  • UCA to generate message event.
  • Coach and embed JavaScript into your activity.
  • IME to end the process.
  • IME to restart an activity.
  • IME to update a process state.
  • SME to start a new process.

Prerequisites

You need to be familiar with WebSphere Lombardi Edition V7.2, WebSphere Application Server V7.0, and DB2® V9.7 Fix Pack 1.

System requirements

You need WebSphere Lombardi Edition V7.2 running on Windows® XP or Windows 7 with access to DB2 V9.7.1.

Duration

This tutorial takes about 6 hours to complete.


Creating an initial BPD

  1. You will create a simple request and approve business process definition (BPD) with a name of Message Event, as shown in Figure 1.
    Figure 1. BPD overview
    BPD overview

    There are three activities: Submit Request, Review Request, and View Request located in two swimlanes: Requestor and Reviewer. They are assigned to the Requestor and Reviewer user groups, respectively.

  2. There are two data Request and Response that you need to capture. The Request complex data includes the Request ID, Requestor ID, and Request Description, as shown in Figure 2.
    Figure 2. Request’s data details
    Request's data details

    The Response complex data includes the Request ID, Reviewer ID, and decision, as shown in Figure 3.

    Figure 3. Response’s data details
    Response’s data details
  3. Add these variables into your BPD as private variables with the default values, as shown in Figure 4.
    Figure 4. BPD’s variable
    BPD's variable

Adding the Coach to activities

  1. Add a Coach for the Submit Request. According to best practice, name this Coach as Submit Request, as shown in Figure 5.
    Figure 5. Submit Request Coach’s flow diagram
    Submit Request Coach’s flow diagram

    The purpose of the Submit Request activity is submitting a request, which means you have to populate values for the request data as shown in Figure 6 via the user interface (web). The next step is building a Coach for the Submit Request.

    Figure 6. Submit Request Coach’s variables
    Submit Request Coach’s variables
  2. Design the Submit Request Coach UI as shown in Figure 7.
    Figure 7. Submit Request Coach UI
    Submit Request Coach UI

    The Request Description has the number for the row, which is 4.

    You can drag and drop the variables into our Coach Design window. In this tutorial, there is a variable named request, which you drag to the Coach. Lombardi Edition automatically generates the graphical user interface (GUI) for you. With a little customization on the GUI, you can have a friendly user interface.

  3. Add the script shown in Listing 1 into the Setup activity.
    Listing 1. Code for the Setup activity
    CODE LINE 1 tw.local.request.requestorId = tw.system.user_loginName;
    CODE LINE 2 tw.local.request.requestID = tw.system.currentProcessInstanceID;
  4. Attach this newly designed coach to the Submit Request activity, if you have not done this yet. Map the process application's data to the Submit Request Coach's data: input and output to tw.local.request.
  5. Add the Coach to the Review Request activity. Create another new Coach named Review Request, as shown in Figure 8.
    Figure 8. Review Request Coach diagram
    Review Request Coach diagram
  6. For the architect data of this new coach, you need to define the data required for this coach, as shown in Figure 9.
    Figure 9. Variables
    Variables
  7. Add the implementation for the Init Response. You need to initialize the response data. The requestID is assigned to the requestID of request. The response's reviewerID is assigned to the user loginned (see Listing 2).
    Listing 2. Code for Init Response
    CODE LINE 1 tw.local.response.requestId=tw.local.request.requestID;
    CODE LINE 2 tw.local.response.reviewerId=tw.system.user_loginName;
  8. Design the Review Request Coach as shown in Figure 10. You need to design a GUI for the user to interact with during the Review Request activity.
    Figure 10. Review Request Coach design
    Review Request Coach design

    With this design, the response data will be populated when the user clicks on the Reject or Approve button. Therefore, you need a script to handle this and to re-modify the diagram (Figure 11).

    Figure 11. Review the Request diagram
    Review the Request diagram
  9. Add the JavaScript (JS) code into the Approve Decision and Reject Decision components. See Listing 3 and Listing 4 for the JS code.
    Listing 3. Code for Approve Decision
    CODE LINE 1 tw.local.response.decision = "true";
    Listing 4. Code for Reject Decision
    CODE LINE 1 tw.local.response.decision = "false";
  10. Attach this coach to the Review Request activity, if you have not done so already. Remember to map data for this activity and its coach.

    You have just finished with the Review Request activity. The next step is to implement the Review Result activity.

  11. Add the coach to the View Result activity. You need to create another new coach for the View Result activity (third activity) so that the user can view his request's result after proceeding with the reviewer. Name this new Coach as Review Result. See Figures 12, 13, and 14 for details of the Review Result Coach.
    Figure 12. Review Result Coach diagram
    Review Result Coach diagram
    Figure 13. Architect data for Review Result Coach
    Architect data for Review Result Coach
    Figure 14. Coach design of Review Result Coach
    Coach design of Review Result Coach

    Notes:

    • The Request Description has a number for the row as 4.
    • The decision is a combo box, not a check box.
  12. Attach this new coach to the View Result activity, if you have not done so already, and map the data for this activity and its coach. You can now run a test with this BPD.

Using IME to terminate the process

In this process, during the Review Request activity, if a reviewer detects an error and wants to terminate this request without any further investigation, he can press the End Process button. Hence, the End Process can yield an event to the BPD. In this BPD, you can use the IME (event handler) to capture this event and terminate this process.

  1. Create the UCA to generate the End Process event. The event can come from different sources, one of which is the UCA. In this tutorial, we use the UCA to generate an event. The UCA requires a service to receive and output data. At minimum, the UCA needs one variable for both input and output, which is the correlationID. Because an IME listener lives within an existing process instance when an event occurs, that event must be matched against the correct instance of the process for which the event is destined. The ability to match the event against this correct instance is called a "correlation".
  2. Define the End Process Service and variables as shown in Figures 15 and 16.
    Figure 15. End Process Service diagram
    End Process Service diagram
    Figure 16. Variable of End Process Service
    Variable of End Process Service
  3. Create the UCA for the Release End Process event (Figure 17).
    Figure 17. Configuration of End Process UCA
    Configuration of End Process UCA
  4. Re-design the Review Request coach, so that whenever the user clicks on the End Process! button, the UCA generates a terminate event for the process. The UCA connects to a Confirm End Process Coach before reaching the End event, as shown in Figure 18.
    Figure 18. Review Request Coach diagram
    Review Request Coach diagram
  5. Map the data for the End Process UCA to tw.local.request.requestID (current process instance ID). Design the Confirm End Process Coach (Figure 19.)
    Figure 19. Design of Confirm End Process Coach
    Design of Confirm End Process Coach

    In this coach, you are just displaying a static message to inform the end user: "Terminate this process".

  6. Add the IME to the BPD to listen to the End Process event (Figure 20).
    Figure 20. BPD diagram after adding the IME
    BPD diagram after adding the IME

    There are two kinds of IMEs: attached IME and inlined IME. In this tutorial, we use the attached IME to listen to the event coming from the Review Request activity. The circled envelop is the newly added IME. However, you need to configure the new IME to listen to the End Process event, released from End Process UCA, and terminate the process with the Terminate Process Event, as shown in Figure 21.

    Figure 21. Configuration of the End Process IME
    Configuration of the End Process IME

    In Figure 21, Attached UCA is now the End Process UCA. Consume Message is checked, which means that you just received the message once. correlationID is tw.local.request.requestID, which is used to identify the current process instance ID.

  7. You can now test this new process by running the process application. Run the application in the web browser. If you arrive at the Review Request activity, click on the End Process! button to terminate the process, as shown in Figure 22.
    Figure 22. UI of Review Request activity on the web
    UI of Review Request activity on the web

You just went through the steps on how to build an IME to terminate the entire process. The next lesson is to build an IME to restart an activity by pressing the Re-submit Request button in the Review Request Coach.


Using the IME to re-start an activity

In the Review Request activity, if the reviewer detects something wrong and would like the requestor to re-submit this request again, he can press the Re-submit request button on the Review Request Coach to return this request to the requestor. However, in this tutorial, we do not focus on routing techniques. We will focus on data flow only. Therefore, the request will be returned to the Requestor group user, but not to the correct requestor.

  1. Create the Re-submit UCA to the Release event. Before creating the Re-Submit UCA, you need to create a service for this UCA. We named this new service Re-Submit Service (Figure 23). This UCA will call the attached service to run when it receives the incoming message.
    Figure 23. Diagram of Re-Submit Service
    Diagram of Re-Submit Service

    As you can see, it is a simple service. The purpose of this service is to pass the correlationID variable only (Figure 24).

    Figure 24. Variables configuration of Re-Submit Service
    Variables configuration of Re-Submit Service
  2. After creating this service, you can create a new UCA, Re-submit UCA (Figure 25).
    Figure 25. Configuration of Re-submit UCA
    Configuration of Re-submit UCA
  3. Re-design the Review Request Coach to enable the Re-submit Process button. Drag the Re-submit UCA into the Coach's diagram, as well as drag a new coach, Confirm End Process, into the diagram (Figure 26).
    Figure 26. Re-design of the Review Request Coach
    Re-design of the Review Request Coach

    In Figure 26, the Confirm re-submit Coach is just a simple coach displaying the information.

  4. You need to map the data for the Re-submit UCA, so that you can receive the event and invoke the service. The correlationID is now tw.local.request.requestID, as shown in Figure 27.
    Figure 27. Configure data mapping for Re-Submit UCA
    Configure data mapping for Re-Submit UCA
  5. Re-design the BPD to add an IME listener so that it can listen to the new Re-submit Event. You need to add a new IME on the Review Request activity to listen to the event coming from this activity (Figure 28).
    Figure 28. New BPD diagram design
    New BPD diagram design

    In Figure 29, the Attached UCA is Re-Submit UCA. The correlationID now shows tw.local.request.requestID.

    Figure 29. New IME named as Resubmit Event Handler
    New IME named as Resubmit Event Handler

Now you can test this BPD. When the user is on the Review Request activity and clicks on the Re-submit Process button, the system brings the user to the Submit Request activity.


Using the UCA to update the process state

With this design, the data is synchronized when passing through each activity. However, in this tutorial, we want to demonstrate the Message Event updating a process state. Particularly, we will use the UCA to update the response.decision value when the user interacts in the Review Request Coach.

  1. Create a UCA to listen to the response.decision value. This task requires two steps: create a service (named Monitor Decision) and an UCA (also named Monitor Decision), as shown in Figure 30 and Figure 31.
    Figure 30. Service diagram of Monitor Decision
    Service diagram of Monitor Decision
    Figure 31. Variable configuration of Monitor Decision service
    Variable configuration of Monitor Decision service
  2. You need to add one more variable, decision, in order to pass this value to the outside BPD to capture it. For the two previous services, you do not need to pass out any values because you just need one variable, correlationId, to identify the process instance (see Figure 32).
    Figure 32. Configuration of the new UCA, Monitor Decision
    Configuration of the new UCA, Monitor Decision

    At this stage, you have enough information to re-design the Review Request Coach to monitor the response.decision value.

    Figure 33. Review Request Coach’s diagram
    Review Request Coach’s diagram
  3. In Figure 33, you need to map the data for Monitor Decision as follows:
    decision = tw.local.response.decision
    correlationId = tw.local.request.requestID

    A newly inserted coach, Display confirmation, is just a simple coach to display the static information to the end user.

  4. Add the IME listener on the BPD in order to listen to the incoming event of the decision value (Figure 34).
    Figure 34. Newly designed BPD
    Newly designed BPD

    As you can see, the new IME is attached to Review Request activity. This new IME connects to the View Result activity, so that the Review Request activity does not connect directly to the View Result activity.

    This new IME (named Monitor Decision Event Handler) will receive the event and update the response.decision value of the BPD, as shown in Figure 35.

    Figure 35. Configuration of new IME, Monitor Decision Event Handler
    Configuration of new IME, Monitor Decision Event Handler

Now you can run this BPD.


Using the SME to start a new process

By going through these steps, you have learned that the IME and UCA can terminate a process, restart an activity, and update a process state. However, this is not enough. For example, a reviewer approves or rejects a request and this status needs to be visible to another other person, or it triggers other processes to start. In this tutorial, we will trigger a simple process to view the result only. This process is simple, but in reality the problem will be more complex and complicated.

  1. When the reviewer approves or rejects the request, it triggers another process, Review Result Start Message, to execute. Figure 36 shows the new BPD.
    Figure 36. Review Result Start Message BPD’s diagram
    Review Result Start Message BPD’s diagram

    Note: We used Start Message Event, not Intermediate Event.

  2. In Figure 37, do not check "Is System Lane", so that the user can interact with this new BPD. You need to create variables for the "Review ResultStart Message" BPD, as shown in Figure 38.
    Figure 37. Participant swimlane’s configuration
    Participant swimlane’s configuration
    Figure 38. Review Result Start Message BPD’s variables
    Review Result Start Message BPD’s variables
  3. The variables for both the response and request have Has Default checked. Create a simple coach for the Review Result activity to display the information of the request and response values. We do not go into this step because this is not the purpose of this scenario. We assume that you can easily develop a simple coach to display such information.
  4. You need to configure the SME to respond to the event in the Message Event BPD, as shown in Figure 39.
    Figure 39. Configuration of SME
    Configuration of SME

    With this configuration, whenever the user approves or rejects the request in the Message Event BPD, the UCA will trigger and release an event not only for the IME listener, but also for the SME Listener to start a new BPD, "Review Result Start Message".

Running the message event BPD test

  1. Start the Message Event BPD. When you arrive at the Review Request activity, you just have one process active (Figure 40).
    Figure 40. Before releasing the event
    Before releasing the event
  2. Run the Review Request activity. Click on the Reject/Approve button to invoke the Monitor Decision UCA. A new process instance is created (Figure 41).
    Figure 41. New process instance is created
    New process instance is created

Now you have two processes. The Message Event process is the current running process. Since you clicked the Approve/Reject button before, it triggered another process instance named Review Result Start Message, but in Figure 41, you see Review Result.

As a reference, you can use the Test - V6-Message_Event_Demo.twx file, which is provided as a zip file in the Download section of the tutorial.


Conclusion

By going through this tutorial, you now have a better understanding about the IME and SME by using a practical approach: restart an activity, terminate a process, update a process state, and start a new process application. The UCA is one of the sources of the message event. You used it to generate an event and trigger other processes.


Download

DescriptionNameSize
Demo fileMessage_Event_Demo.zip514KB

Resources

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Business process management on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Business process management, WebSphere
ArticleID=767712
ArticleTitle=Using the Undercover Agent with a message event in WebSphere Lombardi Edition V.7.2
publish-date=10262011