- Business scenario
- Technical overview
- Key concepts
- Implementation of the business scenario
- Define the business process
- Define the business objects
- Defining and implementing the activities
- Implement the undercover agents
- Implementing Web services and web services handler
- Test the application
- Downloadable resources
- Related topics
Implementing a negotiation process in IBM Business Process Manager using web services
This article demonstrates how you can implement a negotiation process in a business activity using IBM Business Process Manager (IBM BPM). Negotiations between different entities are crucial for closure of business processes. The sample scenario is a simple loan processing system, but a similar design could be implemented in any day-to-day business communications. Some of the key design techniques found here include how a process implemented in an external system communicates with IBM BPM, maintenance of business object's state, and negotiations between two or more parties.
The scenario we'll use is as follows:
- A financial institution, such as a bank, may lend a maximum of $100,000 as loan against a customers term deposit (assuming the customer has more than $100,000 as a fixed deposit).
- If the requested loan amount is less than $100,000, the loan request will be automatically approved. Otherwise, the request will be routed to the approver for further reviews and approval.
- The approver may decide to take one of the following actions: approve, reject or negotiate. If the approver wishes to negotiate, the loan request will be updated with a new maximum loan amount and supporting remarks, as a new offer.
- The loan applicant may now accept the new offer or counter the offer. This negotiation can continue until the approver accepts or rejects the loan request.
This article does not focus on the presentation logic, but rather on the design pattern for intermediate communications between the external system and the process engine. The technical flow is explained below:
- The applicant submits a loan request form consisting of name, location, contact, fixed deposit account number, requested loan amount, and so on, through the user interface, which uses the default IBM BPM Coach.
- An automated decision gateway verifies whether the requested loan amount is less than $100,000. If request is less that 100,000, the request is automatically approved; otherwise, the request is assigned to the manager/approver, who may then approve, reject or negotiate.
- The approver claims the activity and, if he or she decides to negotiate, the loan request is updated with the negotiated amount and remarks, and the loan applicant is notified.
- The IBM BPM runtime waits for the loan applicant to respond through an intermediate messaging event.
- The applicant needs to respond to the proposed new offer made by the approver. In order to demonstrate the use of the undercover agent (UCA) and intermediate message event functionality in IBM BPM, we'll assume that the loan applicant may use an external application to do the negotiation. The interaction between the external application and the IBM BPM runtime uses web services. Hence, we'll focus on the interaction and not on the external application's user interface.
- For this article, we'll use a SOAP client (SOAPUI or Rational Application Developer Web Services Explorer) to post the web services request to the IBM BPM runtime. The loan applicant sends the response to the approver through a web services call. The applicant's response is routed to the approver and the loop continues until the approver accepts or rejects the loan request.
- User tasks are human-centric activities that require a human intervention in the process flow to claim and complete the activity. The user should have rights to access the activity and, if valid, is required to complete the activity before the process can proceed to the next activity.
- Gateways are used to split or converge multiple execution paths based on certain conditions.
- An intermediate messaging event is used to model an event to take place between a process, which is in an execution state, and an external event through a web service call or Java™ Messaging Service (JMS).
- An intermediate messaging event must be attached to a UCA. When a message is received from an external system, a UCA is required to initiate the intermediate process. The message could be triggered via a JMS or a web service.
- UCA and web service handlers are required to for defining the parameters, for routing, and for transformation of the messages.
Implementation of the business scenario
The implementation of the business scenario consists of the following high-level tasks:
- Define the business process.
- Define the business objects.
- Defining and Implementing the activities.
- Test the application.
The scenario implementation is provided as a downloadable .twx file with this article. Before proceeding with the steps in this article, download and import the .twx file into IBM BPM V7.5.1 or above, so that you can follow along.
Note: The application has been tested on IBM BPM V7.5.1 and IBM BPM V8.
Define the business process
Once you have imported the twx file into the Process Center, open the Banking-Solution (BANKING) application in Process Designer. On the left pane, click Processes and view the business process definition (BPD) called BankingSolution. We'll cover how to implement the BPD in Defining and implementing the activities.
The following sections describe how to implement the scenario.
Define the business objects
Two business objects are defined for this application. You can find them under the Data in the Process Designer. These business objects are LoanRequest and StatusUpdates.
LoanRequest is used by an applicant to submit a request.
Table 1. The LoanRequest business object, its fields and datatypes.
StatusUpdates is used to persist the history and communication between the approver and the loan applicant. The RequestId is used as a correlation identifier to uniquely identify the current instance of the process in the IBM BPM runtime. The RequestAmount is the loan amount requested by the applicant, and the ProposedAmount is what the bank is ready to offer. The status can be either accept, reject or negotiate.
Table 2. The StatusUpdates business object, its fields and datatypes.
The LoanRequest object is used by the applicant to submit the loan request.
Defining variables used by the activities
The business process consists of three private variables:
- The LoanRequestData variable is a LoanRequest business object that will be used for loan request submission.
- Status is an array of StatusUpdates, where each object in the array contains the details of each negotiation.
- NegotiateCount is an Integer contains the count of total negotiations that have occurred.
Click the Variables tab in the BankingSolution process diagram to see the variables, as shown in Figure 1.
Figure 1. Private variable definition diagram
Defining and implementing the activities
This section describes the BPMN. Figure 2 illustrates the complete flow of the activities used in the sample application. The following sections describe each of the swimlanes, the activities and their implementation.
Figure 2. Business process definition showing the complete activity flow
Three swimlanes had been defined: System, Manager and Applicant. The System lane is used for automated activities, such as initialization. Select each swimlane. At the bottom of the Process Designer, under Behavior, select the group whose users you want to give access to the activities in the swimlanes. This article doesn't show you the steps for creating users and groups. However, the Manager swimlane should be assigned to the group containing managers authorized to process the request and the Applicant swimlane to a group containing fixed deposit account holders.
Implementing the LoanRequest activity
The first activity in the process is the LoanRequest activity. This activity receives the request from the applicant. The input data is a LoanRequest object. Double-click the LoanRequest activity. The LoanRequest Human service is displayed. Double-click LoanRequest Coach. The Coach is displayed, as shown in Figure 3.
Figure 3. LoanRequest Coach
Note that the RequestId is not available for the applicant to fill in. Rather, it will later be automatically populated by the system and will be provided to the applicant during notification.
Initialize the RequestId
- The next activity is Initialize RequestId. This is an automated activity in the System lane and is implemented as a script. Click the Implementation property to see the following code in the Script Object section.
Listing 1. Initialize_RequestId
var temprequestId; temprequestId=Math.floor(Math.random()*100000); tw.local.LoanRequestData.RequestId=temprequestId;
This code generates a random integer value and assigns it to the RequestId of the LoanRequestData object.
Validating the loan request amount
The Validate Amount is a decision gateway activity that checks whether the loan request amount is greater that 100,000. For demonstration purposes, the amount is hard-coded. In a real world scenario, the condition should be checked against the applicant's fixed deposit amount.
Figure 4. Validate Amount decision gateway used to check if loan request amount is greater that 100,000
if the amount is greater than 100,000, the request moves on to initialize negotiation. If the request amount is less than 100,000, the request is automatically approved and the applicant is notified.
Implement the negotiation activity
The Negotiate activity in the Manager swimlane is a Human service, and the LoanRequestData and Status are its input and output. While running the application, you'll be able to see that the RequestId and RequestAmount are set because we already initialized them.
The ProposedAmount is the loan amount the approver is ready to grant the applicant. A comment can be provided and the status field should contain one of the following values: Approve, Reject and Negotiate. ProposedAmount, Comment and Status are the only input fields. The other fields are read only. Prior to beginning negotiation, the Status object, which is used for negotiation needs to be initialized. To do this, select Initialize Negotiation and then select the Implementation section in the Properties tab. You'll see the following code under Script Object.
Listing 2. Initializing StatusUpdates
tw.local.Status[tw.local.NegotiateCount].RequestId=tw.local.LoanRequestData.RequestId; tw.local.Status[tw.local.NegotiateCount].RequestAmount=tw.local. LoanRequestData.LoanAmount;
The status variable is a list of StatusUpdates objects. Each array index in the list represents a communication between the approver and the loan applicant, as shown in Figure 5. Later, we'll explain the runtime behavior of the negotiation using the StatusUpdates object.
Figure 5. The negotiation process coach used by reviewer/manager to validate the request.
The Review gateway activity checks the status of loan request as follows:
- If the status is Approved or Rejected, the Notify activity in the Applicant swimlane is initiated.
- If the status is Negotiate, the Update activity is initiated.
- The Update activity is just a placeholder for post review activity. In this example, this activity is implemented as a simulator. You can implement this activity or not based on your business requirements.
Figure 6. Decision gateway to check Approver's decision
The first index in the array of the Status variable contains the Proposed Amount, Comment and Status as provided by the approver. A second object now needs to be initialized in the list, so that it can store the incoming data from the applicant. The initial value of NegotiateCount is 0, which will now be incremented by 1 and initialized with the requestId. The new request amount needs to be submitted by the applicant from an external resource.
This could also be implemented as a Coach, but the purpose of this article is to demonstrate how an external process can invoke an intermediate activity so that multiple applications can communicate asynchronously. This initialization is performed in the Initialize Customer activity, as shown in the code under Script Object in Listing 3.
Listing 3. Initializing the Customer activity
ttw.local.NegotiateCount=tw.local.NegotiateCount+1; tw.local.Status[tw.local.NegotiateCount]=new tw.object.StatusUpdates(); tw.local.Status[tw.local.NegotiateCount].RequestId=tw.local. LoanRequestData.RequestId;
Create the messaging intermediate event
The next step is to create an intermediate messaging event to receive the RequestId, RequestAmount and Applicant Status from an external resource. The received value will be stored in Status list object and redirected to the Negotiate activity, which is to claimed by the approver once again for review.
Figure 7. Intermediate messaging event used to trigger the next activity upon receiving update from applicant
Implement the undercover agents
In this section, we'll look into the components that connect and route the message to the messaging event. Click the Implementation under BANKING-SOLUTION. Four components are defined, as seen in Figure 8:
- a) UCA handler for Customer
- b) UCA for Customer
- c) Web services handler for Customer
- d) LoanServices
Refer to the below diagram.
Figure 8. Implementation components for WebServices and UCA
Create a UCA handler
You need to create a UCA and attach it to an intermediate message event. However, before creating an undercover agent, you need to create a handler to define the parameters and routing the data. In this case, all the artifacts are already created. Click on Implementation under Banking-Solution and select UCA Handler for customer. Three variables have been defined, as shown in Figure 9. This data will be routed to the messaging event.
Figure 9. Variables defined in UCA handler
Click the Diagram tab and take a look at the Start and End activities as shown in Figure 10.
Figure 10. UCA diagram
The above flow shows that the incoming data is routed across to the messaging event without any modification.
Implementing the UCA
- Click Implementation under Banking-Solution and select UCA for customer.
- Under the Details section note that the UCA Handler for Customer service is attached to the UCA for customer, as shown in Figure 11.
Figure 11. Attaching the UCA handler to the UCA
Attach the UCA to the intermediate messaging event
This section explains how an external system triggers an intermediate messaging event.
Open the messaging event created in the BPD to see how the UCA Handler parameters are mapped, as shown in Figure 12.
Figure 12. Attaching the UCA to the messaging event
The most important concept in this implementation is the mapping of the correlation id. In Figure 12, you can see that the option button next to RequestId is selected. This means that this variable is selected as the correlation id.
So how does the correlation works? There can be hundreds of processes running at any given time, and there can be hundreds of external activities calling the UCA, either through web services or a JMS. How does the incoming data attach itself to the corresponding process? The correlation id is used to achieve this. A variable in the process should have been already initialized and mapped to an incoming field -- this is the correlation id. If both the values match, the other fields will be set and will trigger the next activity.
Implementing Web services and web services handler
The UCA can now be called through web services or a JMS. Posting a message through a JMS is simpler because when a message with a predefined format is placed in an event queue, the UCA is triggered. In our sample, we'll look at how to invoke the UCA using a web service.
Just as we created a UCA handler, we also need to create a web services handler to define the parameters and routing.
- Under Implementation, select WS Handler for Customer. Three variables are defined: WSRequestId, WSRequestAmount and WSComments.
- Select the Diagram tab. You can see that the Invoke UCA
activity invokes the UCA for Customer UCA, as shown in Figure 13.
Figure 13. Web services handler
The WS Handler fields are mapped to the UCA Handler fields, as shown in Figure 14.
Figure 14. WS Handler parameter mapping
- Finally, the web services need to be implemented. Under Implementation, select the LoanServices web services.
- Click Add under Operations and select the WS Handler for Customer. The operation is named LoanApplication, as shown in Figure x.
- A WSDL is automatically generated, and its link is displayed under
Behavior, as shown in Figure 15.
Figure 15. Web services implementation displaying the WSDL to be used by end customer for invocation.
- Click the WSDL URL and verify the operation and parameter definition. This should match what was defined in the web services handler.
Test the application
To test the application, complete the following steps:
- Playback the BPD by clicking the Run Process button in the top right of the BPD.
- Provide the details for the LoanRequest activity and request a loan amount greater than 100,000.
- You'll see that the Negotiate activity is initiated. Claim this activity. Make a note of the RequestId that is generated.
- Provide a negotiated amount and set the Status field to Negotiate.
- Complete the activity.
- Complete the Update process. You can see that the process is now waiting at the messaging event.
- Run a web services client, such as SoapUI or the Eclipse Web Services Explorer in Rational Application Developer or the IBM Integration Designer. Provide the WSDL link and submit a SOAP request with the fields WSRequestId, WSRequestAmount and WSComments. Once submitted, the process returns to the Negotiate activity.
- The negotiation continues until the approver changes the status to Approved or Rejected.
After a series of communications, the Negotiate page should look similar to Figure x:
Testing the scenario
This negotiation shows that a request was made for $150,000 but the manager only approved $110,000. The applicant countered, requesting $140,000. This time the approver counters with $120,000. Finally, the applicant requests $130,000 and the manager approves the amount.
This article implemented a sample application (provided for download) that you can use as a model for implementing a negotiation process by communicating with external resources using web services. The article illustrated the flow of data between multiple layers such as web services, UCA and messaging events.
- Creating an undercover agent for an incoming message event (IBM Business Process Manager V7.5 Information Center)
- Posting a message to IBM Business Process Manager Event Manager (IBM Business Process Manager V7.5 Information Center)
- IBM BPM Journal: Get the latest articles and columns on BPM solutions in this quarterly journal, also available in both Kindle and PDF versions.