Using Web Services: Parameter example

For the simple data used in this example, we can use workflow parameters.

Table 1. Interaction between Invoke and Receive workflows Workflow diagram Details A simplified expense approval process illustrates the interaction between the two workflows: A user launches the SubmitExpenses workflow and supplies the expense data—the employee name, the total amount, and the actual expense report document as an attachment. The Invoke step sends the request to a Web Service for approving expenses—the Receive step in the ApproveExpenses workflow—and waits for a reply from the Web Service. The ApproveExpenses workflow launches automatically in response to a request for the Web Service defined in the Receive step. The Receive step accepts the request. At the Review step, a user reviews the request and enters a reply comment. The Reply step sends a message back to the Invoke step in the SubmitExpenses workflow. The launch user views the reply in the Answer step.

Create the ApproveExpenses workflow to receive a Web Service request

1. In Process Designer, start a new workflow definition.
2. On the Workflow Properties >> General tab, provide a name and subject for the new workflow definition (ApproveExpenses).
3. Define the Web Service.
   1. In Workflow Properties >> Web Services, on the General tab specify a folder on your object store where incoming attachments (the expense report) will be stored.
   2. Be sure that Finalize existing web services is not selected.

      We want to be able to modify the web service input and output parameters as many times as we want.

   3. On the Partner Links tab, enter a name (ApproveExp) for the Web Service, then select Receive/Reply.
   4. In Process Port Type , enter a name (ExpPort) for the port.

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

4. In Workflow Properties >> Data Fields, specify a data field, ReplyMsg (string), that will be used to hold the reply message.

   We will create other data fields and an attachment automatically as we define the parameters for the Web Services.

5. From the Web Services step palette, drag a Receive step to the workflow map and specify the properties as follows.

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

   1. In the Properties pane, select the Partner Link for this Web Service (ApproveExp)
   2. For Operation, enter a name (ExpOp).
   3. Select Parameters, specify each input parameter, and automatically create the corresponding data fields and attachment.

      Note that you can also create the data fields in the usual way in Workflow Properties >> Data Fields, and the field names do not need to match the parameter names.

      Table 2. Parameter information

      Parameter Name	Type	Data field
      EmpName	String	<Create> EmpName
      TotalAmount	Float	<Create> TotalAmount
      ExpenseRpt	Attachment by Value (This means that the actual file will be attached to the message, not referenced in an object store. We could use either option in this workflow since both workflows are in the same isolated region and have access to the same object store.)	<Create> ExpenseRpt

6. From the BPM step palette, drag an Activity step to the workflow map and name it Review. At this step, a Reviewer of expense reports checks the attached expense report and enters a reply message.
   • Assign a specific user (the Reviewer of expense reports) as the participant for the step. (For the purpose of this example, it is efficient to assign yourself.)

     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.

   • Specify EmpName, TotalAmount, ExpenseRpt, and ReplyMsg as parameters for this Activity step so the reviewer can examine the expense report and enter a reply. ReplyMsg should be read-write.
7. From the Web Services step palette, place a Reply step on the workflow map, and define the parameters.
   1. In the Properties pane, select the same partner link and operation you defined in the Receive step (ApproveExp).
   2. Under Message Type, select Message.
   3. Specify the parameter for the reply message.  

      Table 3. Reply parameter

      Parameter Name	Type	Data field
      ReplyParam	String	EmpName+ReplyMsg

8. Add routes between the steps.
9. Validate, save, and transfer this workflow definition.

Create the SubmitExpenses workflow that invokes the Web Service

1. Start a new workflow definition.
2. On the Workflow Properties >> General tab, provide a name and subject for the workflow definition (SubmitExpenses).
3. Define the Web Services.
   1. On the Web Services >> Partner Links tab, enter a name (SubmitExp) for the Partner Link.
   2. Select Invoke and 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 ApproveExpenses and click OK.
   5. On the Partner Links tab, note the Port (ExpPort).

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

   6. Close Workflow Properties.
4. From the Web Services step palette, drag an Invoke step to the workflow map.
   1. In the Properties pane, select the Partner Link for this Web Service (SubmitExp)
   2. Select the operation (ExpOp).

      Process Designer displays the outgoing parameters (input required for the invoked service) and incoming parameters (reply from the service) from the WSDL.

5. Select the Invoke step on the workflow map. In the Properties pane under Outgoing Parameters, create the data fields that will be parameters in the invoke message to the Web Service. (In this example, we have accepted the same names as the parameters; you can specify any data field names.)  

   Table 4. Outgoing parameters

   Parameter	Type	Data field
   EmpName	String	EmpName
   TotalAmount	Float	TotalAmount
   ExpenseRpt	Attachment	ExpenseRpt

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

   Table 5. Incoming parameters

   Parameter Name	Type	Data field
   ReplyParam	string	ReplyParam

7. From the BPM step palette, drag an Activity step to the workflow map so that you can view the Reply message. Place this step after the Invoke step.
   1. Name the step Answer.
   2. Assign Workflow Group F_Originator (the user who submits the request) as the participant for this step.
   3. Specify ReplyParam as a parameters for this step.
8. Select the Launch step, and specify EmpName, TotalAmount, and ExpenseRpt as parameters. The Launch user will supply these values to submit the expense report.
9. Add the routes between the steps.
10. Validate, save, and launch this workflow.
11. In the Launch step, enter appropriate values for data fields EmpName, TotalAmount, and select an Attachment target document for ExpenseRpt, then launch the workflow.
12. Log on as the launch user and open the Answer step in your inbox.
13. Check ReplyMsg. It should be what you entered for the EmpName + ReplyMsg.