Using Web Services: Correlation example

An order entry conversation between two process (a Buyer and a Supplier) illustrates how to define a correlation set for XML mode and parameter mode. This example contains three invoke/receive/reply conversations. Since the first conversation launches the SupplyItems workflow, no correlation set is required.

These example processes are intended only to demonstrate the use of correlation sets to enable the conversation between the two processes. They do not include any decisions or error handling which would be required in any production process.

Create the SupplyItems workflow

1. Start a new workflow definition that the Supplier uses to respond to inquiries and to process orders.

   In Process Designer Workflow Properties >> General tab, identify the workflow definition.

   Name: SupplyItems Subject: SupplyItems

2. Define the two Web Services that this workflow will provide.
   1. On Web Services >> General tab, be sure that Finalize existing web services is not selected.

      We will save and transfer this workflow definition more than once to get the Web Services steps defined, and we might need to change the web service parameters.

   2. On Web Services >> Partner Links, specify a Partner Link for each Web Service that this workflow will provide.

      Name: ReceiveInquiry Invoke: clear this check box Receive/Reply: select this check box Process Port Type: RecInquiryPort

      Name: ReceiveOrder Invoke: clear this check box Receive/Reply: select this check box Process Port Type: RecOrderPort

   3. On the XML Schema tab, define two schemas: one for the order entry, and one for the order acknowledgement.  

      Table 2. XML schema tab

      Order entry	Acknowledgement message
      Name: OrderEntrySchema Schema Definition : click here for text	Name: OrderAckSchema Schema Definition : click here for text

      TIP If the text does not display on separate lines in the schema definition, click Check Well Formed XML.  

   4. On the XML Data Fields tab, specify a field to hold the incoming order message.

      Name: XMLOrderField Schema: OrderEntrySchema Element: OrderEntry

3. Create a step to provide a purchase inquiry Web Service.

   From the Web Services Palette, drag a Receive step to the workflow map.

   On the Properties >> General tab, enter the following:

   Step name: ReceiveInquiry Partner Link: ReceiveInquiry Operation: RecInquiryOp Message Type: Parameters Operation Parameters:

   Table 3. Example parameters

   Name	Type	Option
   Name              CustomerName    ItemName	Type         String String	Field Name <Create> CustomerName <Create> ItemName

   NOTE  The Receive step must be the first step after the Launch step in order to launch this workflow automatically in response to a request in another workflow to invoke this Web Service.  

4. By examining the XML schemas (Web Services >> XML Schema tab), you can see that you will need the workflow fields listed below to hold the data contained in the incoming and outgoing messages. In addition, we're going to define the other data fields we will need in future steps at this time.

   Specify all of the following in Workflow Properties >> Data Fields.  

   Table 4. Workflow fields

   Workflow properties
   InStock (Boolean) Shipped (String) OrderNum (Integer) Price (Float) Contact (String) Address (String) OrderCompleteMsg (String)

5. Create a step to represent a process that checks stock and price.

   From the BPM Palette, drag an Activity step to the workflow map.

   On the Properties >> General tab, enter the following:

   Step name: InStock? Participants: Choose a specific user (you can assign it to yourself) as the participant for the step.

   NOTE Do not assign F_Originator for any step in this workflow because this workflow will be launched by the system.

   Parameters tab:    CustomerName (read only—from the buyer)    ItemName (read only—from the buyer)    InStock: (read-write—entered by the supplier)    Price: (read-write—entered by the supplier)    OrderNum: (read-write—entered by the supplier)

   TIP In this example, you will alternately add an Activity step from the BPM palette, then add a step from the Web Services palette. You might find it useful to copy these steps to MyPalette to minimize switching palettes.

6. Create a step to reply with the availability, price, and an order number to allow tracking of the conversation with the buyer.

   From the Web Services Palette, drag a Reply step to the workflow map. On the Properties >> General tab, enter the following:

   Name: ReplyStockInfo Partner Link: ReceiveInquiry Operation: RecInquiryOp Message Type: Message Operation Parameters:

   Table 5. Operation parameters

   Name	Type	Option
   Name                     CustomerName ItemName InStock Price OrderNum	Type                     String String Boolean Float Integer	Expression CustomerName ItemName InStock Price OrderNum

7. From the BPM palette, drag an Activity step to the workflow map. We will use this step to assign the correlation value used to identify a particular incoming message for the Receive step that follows.

   Name: AssignF_Corr

   Do not specify a participant or queue for this step.

   We will return to this step after we define the correlation set in the next step.

8. From the Web Services Palette, drag a Receive step to the workflow map.

   This step will receive the actual order information if the Buyer decides to continue with the order. (In our example, the Buyer always continues.)

   1. On the General tab, enter:

      Name: ReceiveOrder Partner Link: ReceiveOrder Operation: RecOrderOp Message Type: XML Incoming XML Data Field: XMLOrderField Schema: OrderEntrySchema Element: OrderEntry  

   2. On the Correlation Set tab, specify a name and properties to correlate a specific invoke request (from another workflow) with a corresponding instance of this receive step. We will use a combination of the CustomerName and OrderNum to identify the appropriate incoming message.

      Since the incoming message uses XML mode, we must use XPath to specify the correlation data.

      Name: OrderCorrelation

      Properties/Name: xpathCustomerName XPath Query String: /*[local-name()="OrderEntry"]/*[local-name()="CustomerName"]

      Properties/Name: xpathOrderNum XPath Query String: /*[local-name()="OrderEntry"]/*[local-name()="OrderNum"]

9. Select the AssignF_Corr step. We are using this step to assign the correlation value that will be used to compare with the value specified in the correlation set for the incoming message.

   On the Assignments tab, select After Completion. Under Field Assignments, enter the following:

   Field name: F_CorrOrderCorrelation Expression: CustomerName + convert(OrderNum,string)

10. Create a step that acknowledges receipt of the order.
    1. From the Web Services Palette, drag a Reply step to the workflow map.

       Step name: ReplyAckOrder Partner Link: ReceiveOrder Operation: RecOrderOp Message Type: Message (be sure to click Message, even if it is already selected) Schema: OrderAckSchema Element: OrderAck

    2. Click the Create Message Template button to display the outgoing message template.
    3. In the Outgoing Message, edit the variables to supply the appropriate data fields. Note that OrderNum must be converted to a string. The edited Outgoing Message looks like this:

       "<OrderAck xmlns=""http://www.filenet.com/ns/fnpe/2004/06/po/schema/OrderAckSchema"">" + "<CustomerName>" + CustomerName +"</CustomerName>" + "<OrderNum>" + convert(OrderNum,string) + "</OrderNum>" +"</OrderAck>"

11. Create a step to represent the order processing.

    From the BPM Palette, drag an Activity step to the workflow map.

    Step name: FillOrder Participants: Choose a specific user (you can assign it to yourself) as the participant for the step.

    Parameters tab:    OrderNum    Shipped

12. Add routes as shown in the illustration at the beginning of this example.
13. Validate, transfer, and add this workflow definition to your object store.

Skip now to Create the OrderItems workflow in this document. This SupplyItems workflow definition is not complete—it needs an Invoke step to send an "order shipped" message to the other workflow, but we cannot create the Invoke step until we define a web service (a Receive step) in the other workflow.

After you complete the OrderItems workflow, add the remaining steps to the SupplyItems workflow.

1. On Workflow Properties >> Web Services >> Partner Links, create the Partner Link for the Web Services that notifies the Buyer that the order was shipped.

   Name: InvShip Invoke: Select this check box Receive/Reply: Clear this check box

   Click Web Services Explorer in WSDL URL.

   1. In the Web Services Explorer dialog box, select Web Services workflows, then click Execute to display workflows with a Receive system function that have been transferred to workflow system.
   2. Select OrderItems, then click OK.

   Still on the Partner Links tab, select: Port Type : RecStatusPort

2. Create a step to notify the Buyer that the order has been shipped.

   This step then waits for a reply from the Buyer indicating that the order was received.

   1. From the Web Services Palette, place an Invoke step on the workflow map. On the Properties >> General tab, enter the following:

      Name: InvShipNotice Partner Link: InvShip Operation: RecStatusOp

   2. Specify the appropriate data fields for the outgoing parameters and incoming parameters.
3. Create a step that allows you to verify that the Invoke step completed (it received its reply), and to see the data fields.

   From the BPM Palette, drag an Activity step to the workflow map.

   Step name: ShipComplete Participants: Choose a specific user (not F_Originator) as the participant for the step.

   Parameters tab:    All data fields

4. Validate this workflow definition.
5. In Workflow Properties >> Web Services >> General tab, select Finalize existing web services operations.
6. Transfer and check in this workflow definition.
7. Proceed to Run the workflows.

Create the OrderItems workflow

1. Create a new workflow definition that the Buyer will use to order items from the Supplier.

   In Process Designer Workflow Properties >> General tab, identify the workflow definition.

   Name: OrderItems Subject: OrderItems

2. Define the Partner Links for the two requests for Web Services.
   1. On Web Services >> Partner Links, specify the Partner Link that invokes a web service provided by the Supplier—a service that returns the availability and price of an item.

      Name: InquireItem Invoke: select this check box Receive/Reply: clear this check box

      Click Web Services Explorer in WSDL URL.

      1. In the Web Services Explorer dialog box, select Web Services workflows, then click Execute to display workflows with a Receive system function that have been transferred to workflow system.
      2. Select SupplyItems, then click OK.

      Still on the Partner Links tab, select: Port Type : RecInquiryPort

   2. On Web Services >> Partner Links, create the Partner Link for the Supplier's web service that inquires about the availability of an item.

      Name: InvOrder Invoke: select this check box Receive/Reply: clear this check box

      Click Web Services explorer in WSDL URL. From the list of Web Services workflow, select SupplyItems.

      On the Partner Links tab, select Port Type: RecOrderPort

3. Create a step to invoke the ReceiveInquiry web service in the SupplyItems workflow.
   1. From the Web Services Palette, drag an Invoke step to the workflow map.

      Step name: InquireItem Partner Link: InquireItem Operation: RecInquiryOp

   2. Select Parameters. In the expression fields, create the data field for each outgoing and incoming parameter.
4. Select the Launch step. On the Properties >> General tab, specify parameters that the Buyer will enter to inquire about the availability of an item

   Parameters:   CustomerName   ItemName

5. Create a step to allow the user to evaluate the returned order inquiry information, and to enter the additional order shipping information to continue with the order.

   From the BPM Palette, drag an Activity step to the workflow map.

   Name: Order? Participants: F_Originator (the Buyer who submits the request) Parameters tab:   CustomerName (read only)   ItemName (read only)   InStock (read only)   OrderNum (read only)   Price (read only)

6. Create a step to place the order by invoking RecOrder in the SupplyItems workflow.
   1. From the Web Services Palette, place another Invoke step on the workflow map.

      Name: InvOrder Partner Link: InvOrder Operation: RecOrderOp

      Note the required parameters for placing an order and receiving an acknowledgment reply. In addition to the existing fields, the new web service requires additional data fields—Contact and Address.

   2. In the outgoing parameter expressions and incoming parameter fields, create data fields as necessary.
   3. Select the Order? step and add the Contact and Address fields as parameters.
7. On Workflow Properties >> Web Services >> Partner Links, define a Partner Link to receive the shipping confirmation from the Supplier.

   Name: RecItemStatus Receive/Reply: select this check box Invoke: clear this check box Process Port Type: RecStatusPort

8. Create a step to receive a message from the SupplyItems workflow when the order ships. (For this example, this step demonstrates a two-way asynchronous conversation between two processes.)
   1. From the Web Services Palette, drag a Receive step to the workflow map

      Name: RecShip Partner Link: RecItemStatus Operation: RecStatusOp Message Type: Parameters Operation Parameters:

      Table 6. Parameter example

      Name	Type	Field Name
      OrderNum Shipped	Integer String	OrderNum Shipped

   2. On the Correlation Set tab, select the correlation parameter.

      Table 7. Correlation parameter

      Parameter	Explanation
      Operation Parameter Contains Correlation: OrderNum	(the value to be checked in the incoming message)
      Correlation Expression: convert(OrderNum,string)	(the data field in the current workflow that contains the value to match)

      If the data field OrderNum were a string, you could just select that field. Since it is an integer, you must convert it to a string to compare it with the value in the incoming message.

9. Create a step to view and acknowledge the shipping confirmation.

   From the BPM Palette, drag an Activity step to the workflow map.

   Name: OrderComplete Participants: F_Originator (the user who submits the request) Parameters tab:   CustomerName (read only)   ItemName (read only)   OrderNum (read only)   Shipped (read only)

10. Create a step to reply to the supplier, acknowledging receipt of the order.

    From the Web Services Palette, drag a Reply step to the workflow map.

    Step name: RepShip Partner Link: RecItemStatus Operation: RecStatusOp Message Type: Message Operation Parameter:

    Table 8. Sample parameter

    Name	Type	Option
    Name                               OrderCompleteMsg	Type           String	Expression CustomerName + " " + Shipped + " " + convert(systemtime(),string)

11. Validate the workflow definition and fix any errors.
12. On the Workflow Properties >> Web Services >> General tab, select Finalize existing web services operations.

    This option ensures consistent input and output parameters for the web services (Receive functions) provided in this workflow—once you transfer this workflow definition, you cannot change the input and output parameters. It also allows any invoking process to run the latest version (or any version) of this workflow, which is essential in this situation where two workflows invoke web services in each other.

13. Transfer, and then add this workflow definition to your object store.
14. Open the SupplyItems workflow and complete the final steps in the SupplyItems workflow.

1. Check out the OrderItems workflow definition.
2. On the Workflow Properties >> Web Services >> Partner Links tab, use the following steps to update the two invoke partner links.

   This is necessary because the first two partner links in this workflow currently invoke a specific version of the SupplyItems workflow—the WSDL URL contains a workspace identification number after the name of the workflow and before ?wsdl. We have made changes and re-transferred the SupplyItems workflow and we want to invoke the latest version.

   1. Select partner link InquireItem
   2. Click Web Services explorer in WSDL URL.
   3. In the Web Services Explorer dialog box, double-click Web Services workflows to close the list, then click Execute to display workflows with a Receive system function that have been transferred to workflow system.
   4. Select SupplyItems, then click OK.
   5. Select the Port Type: RecInquiryPort.

      TIP This partner link invokes the latest version of the SupplyItems workflow--the WSDL URL no longer contains the workspace identificationnumber.

   6. Select partner link InvOrder and repeat the steps above (selecting RecOrder Port) to update this partner link.
3. Validate, then Launch the OrderItems workflow.
4. In the Launch step, enter a name (CustomerName) and the name of an item you want to buy (ItemName), then click Launch.

   Use the picture at the beginning of this example to help you navigate through the user steps involved in the order and supply processes.

5. In Workplace Tasks, open the InStock? step in your Inbox.

   You (the supplier) enter an order number, such as 1234, that will be used to track this order, and enter a price, then complete the step.

   TIP If you run this workflow multiple times, you should enter a different customer name and order number each time you launch so that the correlation set can match the appropriate two-way conversations between the workflows.

6. At the Order? step, you (the buyer) check the price, then enter your shipping address and a contact name,. Complete the step.
7. At the FillOrder step, you (the supplier) enter a shipped message, such as Shipped Today, then complete the step.
8. At the OrderComplete step, you (the buyer) enter a message to acknowledge receipt of the order.
9. At the ShipComplete step, you (the supplier) note that this transaction is complete.