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.
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.
- IME to end the process.
- IME to restart an activity.
- IME to update a process state.
- SME to start a new process.
You need to be familiar with WebSphere Lombardi Edition V7.2, WebSphere Application Server V7.0, and DB2® V9.7 Fix Pack 1.
You need WebSphere Lombardi Edition V7.2 running on Windows® XP or Windows 7 with access to DB2 V9.7.1.
This tutorial takes about 6 hours to complete.
Creating an initial BPD
- 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
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.
- 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
The Response complex data includes the Request ID, Reviewer ID, and decision, as shown in Figure 3.
Figure 3. Response’s data details
- Add these variables into your BPD as private variables with the
default values, as shown in Figure 4.
Figure 4. BPD’s variable
Adding the Coach to activities
- 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
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
- Design the Submit Request Coach UI as shown in Figure 7.
Figure 7. 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.
- 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;
- 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
- Add the Coach to the Review Request activity. Create another new
Review Request, as shown in Figure 8.
Figure 8. Review Request Coach diagram
- 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
- 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
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;
- 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
Figure 10. 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
Reject Decision components. See Listing 3 and Listing 4 for the JS
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";
- 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.
- 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
Figure 13. Architect data for Review Result Coach
Figure 14. Coach design of Review Result Coach
- The Request Description has a number for the row as 4.
- The decision is a combo box, not a check box.
- 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.
- 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".
- Define the End Process Service and variables as shown in Figures
15 and 16.
Figure 15. End Process Service diagram
Figure 16. Variable of End Process Service
- Create the UCA for the Release End Process event (Figure 17).
Figure 17. Configuration of End Process UCA
- 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
- Map the data for the
End Process UCAto
tw.local.request.requestID(current process instance ID). Design the Confirm End Process Coach (Figure 19.)
Figure 19. Design of Confirm End Process Coach
In this coach, you are just displaying a static message to inform the end user:
"Terminate this process".
- Add the IME to the BPD to listen to the End Process event (Figure
Figure 20. 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 Requestactivity. 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
In Figure 21,
Attached UCAis now the
End Process UCA.
checked, which means that you just received the message once.
tw.local.request.requestID, which is used to identify the current process instance ID.
- 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
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.
- 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
As you can see, it is a simple service. The purpose of this service is to pass the
correlationIDvariable only (Figure 24).
Figure 24. Variables configuration of Re-Submit Service
- After creating this service, you can create a new UCA,
Re-submit UCA(Figure 25).
Figure 25. Configuration of Re-submit UCA
- 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
In Figure 26, the Confirm re-submit Coach is just a simple coach displaying the information.
- 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
- 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. New BPD diagram design
In Figure 29, the Attached UCA is
Re-Submit UCA. The correlationID now shows
Figure 29. 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.
- Create a UCA to listen to the
response.decisionvalue. 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
Figure 31. Variable configuration of Monitor Decision service
- 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
At this stage, you have enough information to re-design the Review Request Coach to monitor the
Figure 33. Review Request Coach’s diagram
- In Figure 33, you need to map the data for Monitor Decision as
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.
- Add the IME listener on the BPD in order to
listen to the incoming event of the decision value (Figure
Figure 34. 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.decisionvalue of the BPD, as shown in Figure 35.
Figure 35. 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.
- 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
Note: We used Start Message Event, not Intermediate Event.
- 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
Figure 37. Participant swimlane’s configuration
Figure 38. Review Result Start Message BPD’s variables
- 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.
- 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
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
- 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
- Run the Review Request activity. Click on the
Reject/Approve button to invoke the Monitor
Decision UCA. A new process instance is created (Figure
Figure 41. 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
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.
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.
- Using the SQL integration service with WebSphere Lombardi Edition V7.2 and WebSphere Application Server V7
- WebSphere Lombardi Edition 7.2.0 Authoring Environment User Guide
- WebSphere Lombardi V7.2 Information Center
- IBM Business Process Management zone on developerWorks