Web Services - XML message example

This example outlines the steps to create a pair of workflows that use Web Services with XML schemas, rather than using workflow parameters. See Using Web Services in FileNet workflow for examples of other features.

Invoke and Reply between workflows

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.
       

      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.
     
    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

      NOTE 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.

      Receive step properties

      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.
     
    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 will allow 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.

      NOTE  Since the workflow system will launch 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.

    Reply step properties

    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.

      NOTE  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 Process Engine.
    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.

      NOTE 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.
       
      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.
       
      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.