Web Services - authentication example

This example demonstrates how to invoke a Web Service that requires a logon. See Using Web Services in FileNet workflow for examples of other features.

Authentication diagram

In ProcessB, the Receive step requires a username and password (authentication) in order to continue. CheckRec is a user step to allow you to examine any data, and to confirm that the Receive step executed.

In ProcessA, the user provides the username and password in a step before the Invoke step. In a post-step assignment, the username and password are encoded to make this data unreadable in the running workflow.

The Invoke step is a system step with both an Assign and an Invoke system function. The Assign inserts the username and password into the Security section of the Web Services message header. The Invoke follows the usual procedure for choosing the Partner Link and specifying the data fields for the outgoing parameters.

CheckInv is a user step that allows you to examine the data. Note the encoding of the username and password.

 

Create ProcessB workflow

  1. In Process Designer, on the Workflow Properties >> General tab, provide a name and subject for the workflow definition (ProcessB).
  2. Define the Web Service.
    1. On the Partner Links tab, enter a name (RecProcessB) for the Web Service, then select Receive/Reply and clear Invoke.
    2. In Process Port Type , enter a name (RecProcessBPort).

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

    3. 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 wish.
  3. From the Web Services Palette, drag a Receive step to the workflow map and name it ReceiveAuth.

    NOTE  The Receive step must be the first step after the Launch step in order to launch this workflow automatically.

    1. In the Properties pane, select the Partner Link for this Web Service (RecProcessB)
    2. For Operation, enter a name (RecProcessBOp).
    3. Select Parameters message type.
    4. Under Operation Parameters, specify the required input fields:
       
      Name Type Field Name
      MyName String (Create) MyName
      MyCompany String (Create) MyCompany
    5. On the Advanced tab, select Authentication Yes.

      Under Only Accept Messages From, select the name of a user or group who is authorized to send messages to this web service.

      At runtime, the invoking message must provide the specified user name and the password.

  4. From the BPM step palette, drag an Activity step to the workflow map and name it CheckRec. This step allows you to look at the data fields and confirm that the Receive step executed.
    1. 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.

    2. Specify MyName and MyCompany as parameters for this step.
  5. Validate, save, and transfer this workflow.

 

Create ProcessA workflow

  1. Create a new workflow definition.
  2. On the Workflow Properties >> General tab, provide a name and subject for the workflow definition (ProcessA).
  3. In Workflow Properties >> Data Fields, define the following fields:

    MyUserName (String)
    MyPassword (String)

    TIP Data fields MyUserName and MyPassword will be passed to the web service in ProcessB as required by the Authentication option in the Receive step. Even though we will encode these fields so that they cannot be read in the running workflow, in an actual production application you might consider naming these fields something less obvious to avoid calling attention to them.

  4. Define the Web Services Partner Link.
    1. On the Web Services >> Partner Links tab, enter a name (InvProcessA) for the Partner Link.
    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 ProcessB, then click OK.
    5. On the Partner Links tab, select the Port Type (RecProcessBPort).

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

  5. From the BPM step palette, drag an Activity step to the workflow map and name it EnterLogon.
  6. From the BPM step palette, drag a System step to the workflow map and name it InvAuth.
    1. From the list of system function, move Assign and Invoke to the right column.

      We are using Assign to insert the user name and password into the header of the invoke message, so Assign must be before the Invoke system function.

    2. Under Selected Functions, double-click Invoke.

      In the Properties pane, select the Partner Link InvProcessA and Operation RecProcessBOp.

    3. Select Parameters and create the data field MyName and MyCompany.
  7. Double-click Assign system function in the InvAuth step.
  8. In Assignment Parameters, enter a name (temp)—we will replace it in a later step, then click Expression Builder.
  9. In Expression Builder, from the drop-down list, select Partner Links and choose InvProcessA. The message header displays in Header Information.

    Click Insert to insert it into the Expression area.

Message header

        Note that the Security section is in this header because the Receive Web Service requires authentication.

  1. Edit this header as follows:
    1. Cut (to the clipboard) F_EndPointRefInvProcessA= from the beginning of the message. We will paste it as the name of the assignment.
    2. Delete the line OPTIONAL_FINAL_SOAP_ADDRESS shown above in the box.
    3. Add double quotes (") to each existing double quotes, and at the beginning and end of the message to make it a valid string expression.
    4. Replace USERNAME and PASSWORD with the appropriate field names MyUserName and MyPassword, and add the closing and opening quotes and pluses to insert the field names into the string expression. The completed message is shown below.
"<wsa:EndPointReference xmlns:wsa=""http://schemas.xmlsoap.org/ws/2003/03/addressing"">     
<wsa:ReferenceProperties>
<wsse:Security xmlns:wsse=""http://schemas.xmlsoap.org/ws/2002/12/secext"">
<wsse:UsernameToken>
<wsse:Username>" + MyUserName + "</wsse:Username>
<wsse:Password>" + MyPassword + "</wsse:Password>
</wsse:UsernameToken>
</wsse:Security>
</wsa:ReferenceProperties>
</wsa:EndPointReference>"
  1. Click OK to close the Expression Builder.
  2. Paste F_EndPointRefInvProcessA into the Name field (replacing temp) in Assignment Parameters. (Delete the trailing =.)
  3. Select the EnterLogon step.
    1. Specify MyName, MyCompany, MyUserName, and MyPassword as step parameters.
    2. On the Assignments tab, select After Completion and use the following field assignments to encode MyUserName and MyPassword that will be passed to the receiving workflow.

      This encodes the username and password as soon as the EnterLogon step is completed so that the unencoded data cannot be viewed in the running workflow.

      CAUTION FileNet recommends that data to be encoded should be entered at an Activity step and encoded in an assignment made after completion on the same step. The data should not be entered at the Launch step because the unencoded data could be intercepted by the Process Tracker application during the launch process and before the data are encoded.

      Field name Expression
      MyUserName encode(MyUserName)
      MyPassword encode(MyPassword)
  4. From the BPM step palette, drag an Activity step to the workflow map as the last step in this workflow definition so that you can view the data.

    Step name: CheckInv

    Participant: F_Originator (the user who submits the request)

    Parameters: MyName, MyCompany, MyUserName, MyPassword

  5. Validate and save this workflow.

 

Run the authentication example

  1. Launch the ProcessA workflow.
  2. In Workplace Tasks, open the EnterLogon step and enter values for the four data fields. You must enter the expected user name and password for MyUserName and MyPassword.
  3. Open the CheckInv and CheckRec steps. Note the encoding of the username and password fields in CheckInv step; these do not display in the CheckRec step.

TIP If you provide an invalid username or password, the two user steps will not appear in your inbox. You can use Process Administrator to locate ProcessA in the Conductor queue; ProcessB will not launch.

NOTE   A FileNet workflow cannot invoke a web service that is deployed on a web server that requires authentication for access. This authentication feature relates to the Receive step, not to the web server where the web service is deployed.