Using Web Services: XML message example

A simplified vehicle registration process illustrates the following features:

• SubmitVehicleReg
  • This workflow prompts for the vehicle data in the Launch step, then invokes the VehicleReg Web Service in the Invoke step, sending the vehicle data in the outgoing message.
  • In the RegFeeInfo step, the user sees the reply values.
• RegisterVehicles
  • This workflow defines the VehicleReg Web Service, which takes vehicle data (owner's name, value, and so on) as input. The incoming message uses a data-gathering schema for the Receive step. An Assign system function extracts data from the incoming XML message into workflow data fields using XPath expressions.
  • In the AssignReg step, a user enters a registration number for the reply message.
  • In the Reply step, the registration number and a calculated fee value are returned to the Invoking process.

Create a workflow to provide the VehicleReg Web Service

1. In Process Designer start a new workflow definition.
2. On the Workflow Properties >> General tab, provide a name and subject (RegisterVehicles).
3. Define the Web Service.
   1. On Web Services >> Partner Links, create the Web Service.

      Name: VRegistration Receive/Reply: select this check box Invoke: clear this check box Process Port Type: VRegPort

      TIP Click Receive/Reply in the Type field to update the data. A new blank line will display in the Partner Links table.

   2. On the XML Schema tab, define two schemas, one for the incoming data, and one for the reply message.

      NOTE These two XML schemas are simple enough to be interpreted as parameters by Process Designer, but they are used here as examples of using XML messages.

      Table 1. Incoming data and reply message schemas

      Incoming	Outgoing
      Name: VehicleReceiveSchema Schema Definition : click here for definition text	Name: VehicleReplySchema Schema Definition : click here for definition text

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

   3. On the XML data fields tab, specify XMLVehicleData to hold the incoming vehicle data message.

      Name: XMLVehicleData Schema: VehicleReceiveSchema Element: VehicleReg

   4. On Web Services >> General tab, Finalize existing web services should not be selected—we want to be able to modify the web service input and output parameters as many times as we want.
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 for the incoming and outgoing messages. Specify the following data fields in Workflow Properties >> Data Fields.  

   Table 2. Incoming and outgoing name workflow fields

   Incoming Name (type)	Outgoing Name (type)
   OwnerName (String)	ReplyRegNum (String)
   VehicleNumber (String)	Fee (Float)
   VehicleValue (Float)

5. Create a step to provide the vehicle registration web service.
   1. From the BPM palette, place a System step, and specify a Receive system function.

      Name: Receive

      The step must be the first step after the Launch step and Receive must be the first function in the step in order to launch this workflow automatically in response to a request for this Web Service.

      Partner Link: VRegistration Operation: VRegOp Message Type: XML Incoming XML Data Field: XMLVehicleData Schema: VehicleReceiveSchema Element: VehicleReg

6. In the same system step, add an Assign system function to extract data from the incoming XML message into the corresponding data fields.  

   Table 3. Data fields and associated expressions

   Field	Expression
   OwnerName	xmlstringexpr(XMLVehicleData, "/", "/*[local-name()=""VehicleReg""]/*[local-name()=""Owner""]")
   VehicleNumber	xmlstringexpr(XMLVehicleData, "/", "/*[local-name()=""VehicleReg""]/*[local-name()=""Vehicle""]/*[local-name()=""VIN""]")
   VehicleValue	convert(xmlstringexpr(XMLVehicleData, "/", "/*[local-name()=""VehicleReg""]/*[local-name()=""Vehicle""]/*[local-name()=""Value""]"),float)
   Fee	VehicleValue * 0.01   (This is a calculated value for the reply message.)

7. From the BPM step palette, create a step that allows the registration worker to examine the vehicle data and enter a registration number for the reply.
   1. Drag an Activity step to the workflow map.

      Name: AssignReg

   2. Choose a specific user (you can assign it to yourself) as the participant for the step.

      Since the workflow system launches this workflow automatically when the Web Service is invoked, you must not assign F_Originator for any step in this workflow because the system is not considered a valid user with an inbox.

   3. Specify the registration information as parameters for this step so the registration worker can examine the vehicle data and enter a registration number for the reply. You can also specify the XML data field, XMLVehicleData, as a parameter if you want to see the actual invoking message.

      Parameter Name: OwnerName Parameter Name: ReplyRegNum Parameter Name: VehicleNumber Parameter Name: VehicleValue Parameter Name: XMLVehicleData

8. From the Web Services step palette, place a Reply step on the workflow map—or use a System step with Reply system function. This step provides a reply message to the process that invokes the web service.
   1. In the Properties pane, select the same partner link and operation you defined in the Receive step.
   2. Select Message.
   3. For Schema, select VehicleReplySchema, and VehicleReply element.
   4. Click the Create Message template button to display the outgoing message in template format.
   5. Edit the outgoing message to substitute the appropriate data fields for the placeholders, as indicated above.

      The Fee data must be converted from float to string for the message.

9. Validate, save, and transfer this workflow definition.  

Create a workflow that invokes the Web Service

1. Create a new workflow definition.
2. In Workflow Properties >> General tab, provide a name and subject for the workflow definition (SubmitVehicleReg).
3. Define the Web Services Partner Links.
   1. On the Web Services >> Partner Links tab, enter a name for the Partner Link (VehicleReg).
   2. With Invoke selected, click Web Services explorer in WSDL URL.
   3. 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.
   4. Select RegisterVehicles, then click OK.
   5. On the Partner Links tab, select the Port (VRegPort).

      TIP Click Invoke in the Type field to update the data. A new blank line will display in the Partner Links table.

4. From the Web Services palette, drag an Invoke step to the workflow map.
   1. In the Properties pane, select the Partner Link (VehicleReg).
   2. Select the operation (VRegOp).

      The parameters required by the invoked Web Service display.

      The remainder of this example uses the Parameter mode as the simpler solution. As a more challenging alternative, you can select XML mode and substitute the appropriate data field names into the message templates.

5. Create the data fields for the Invoke step XML messages.
   1. For Outgoing Parameters, create the data fields in this workflow that will be used in the invoke message to the RegisterVehicles workflow.  

      Table 4. Outgoing parameters and data fields

      Name	Type	Expression
      Owner	String	<Create> Owner
      VIN	String	<Create> VIN
      Value	Float	<Create> Value

   2. For Incoming Parameters, create the data field in this workflow that will contain the reply message from the RegisterVehicles workflow.  

      Table 5. Incoming parameters and data fields

      Parameter	Type	Data field
      Owner_reply	String	<Create> Owner_reply
      VIN_reply	String	<Create> VIN_reply
      RegNumber_reply	String	<Create> RegNumber_reply
      RegFee_reply	Float	<Create> RegFee_reply

6. From the BPM palette, drag an Activity step to the workflow map so that you can view the Reply message.

   Step name : RegFeeInfo Participant: F_Originator Parameters: All of the data fields

7. Select the Launch step and specify Owner , VIN, and Value as parameters.

   The launch user enters these values to start the process.

8. Validate, save, and transfer this workflow.
9. Continue with Run the SubmitVehicleReg workflow.

Run the SubmitVehicleReg workflow

1. Launch the SubmitVehicleReg workflow.
2. In the Launch step, enter appropriate values for data fields Owner, VIN, and Value, then launch the workflow.
3. In Workplace >> Tasks, log on as the user who will assign registration numbers (probably yourself, in this example), and open the AssignReg task.
4. Examine the data fields, then enter text to represent a registration number in the RegNumber_reply field.
5. Complete the step.
6. Log on as the launch user and open the RegFeeInfo step in your inbox.
7. Check data fields RegNumber and RegFee.