Receive system function
Use the Receive system function to provide a Web Service that can be invoked. The Receive step can be at any location in the workflow.
Under the following conditions, a workflow with a Receive system function will launch automatically in response to an Invoke system function:
- The system step with the Receive system function (or a Receive step) must be immediately after the Launch step.
- The Receive system function must be the first system function in the step.
NOTE If a Receive step is not the first step in the workflow, the step must include a correlation set that provides a way to identify an appropriate instance of an invoke message.
To specify a Receive system function
- From the Web Services Palette, drag a Receive step onto the workflow map where you want to provide a Web Service operation.
General tab
- On the Receive General tab, select a previously defined Partner Link that specifies the Web Service.
- Enter an operation name.
- Under Message Type, select Parameters or XML.
Parameters — use workflow data fields for input and output. Use this message type for simple parameters or for schemas up to two levels deep. Schemas may not contain duplicate element names.
- For each input parameter for this Web Service, specify a parameter name and data type. The parameters will display in the Invoke step to indicate the appropriate input.
Choose one of the following options to specify the expression.
- <undefined> - The expression for this parameter is not defined. It must be defined prior to transfer to the Process Engine.
- <Create parameter_name> - Choose this option to automatically create a field of the appropriate type with the same name as the parameter. This option should be used only if an appropriate field does not already exist.
NOTE If the <Create parameter_name> option is not available, a field with the parameter name might already exist, or the parameter name might result in an invalid field name, such as a reserved word.
- <Build Expression...> - Choose this option to open the Expression Builder dialog box and define an expression using data fields, attachments, system fields, functions, and operators.
- Existing fields of the matching data type - Choose one of these, as appropriate.
NOTE Parameter names must not contain numbers, special characters, or spaces.
XML — use XML schema for input and output. You must use this message type when parameters are nested more than two levels deep.
- Incoming XML data field - Select a previously defined XML data field to hold the incoming message. See Workflow Properties - Web Services for information about defining XML data fields and XML schemas.
- Schema - Select a previously defined XML schema for the Web Service. The elements in the schema will display in the Invoke step to prompt for the appropriate input.
- Element - Specify either the root element of the schema or some other element, as appropriate.
Advanced tab
- Timeout
- On the Advanced tab under Timeout Expression, you can enter a expression that specifies a time limit for the Receive system function to wait.
For example, you can enter a time function such as
addminutes(systemtime(), 30)
This allows the step to wait 30 minutes before it goes to the specified timeout map.
- Select an appropriate submap to be executed if the timeout condition occurs. You can choose one of the default maps (Terminate or Malfunction), or you can create your own submap to provide custom processing.
- Authentication
- To require logon and password in order to use the Web Service provided by the Receive system function, select Yes under Authentication.
- If you choose Yes (Authentication is required), for Accept Messages From, specify a user or group as the valid requester.
In the workflow that invokes a Receive step that requires authentication, the appropriate username and password values must be in the Partner Link message header. In FileNet workflows, the header of the invoking message will include a Security section containing placeholders for the username and password. See Web Services Authentication example for an example of implementing authentication in both the receiving and invoking processes.
Correlation Set
A correlation set provides an identifier between two Web Services so that one can identify an appropriate message from another.
NOTE A correlation set is required for any Receive step that is not the first step after the Launch step.
You can define a correlation set for any of the Web Services system functions—Receive, Reply, and Invoke. For example, if you define a Receive step with a correlation step consisting of an order number with a specific value, that Receive step will wait for an Invoke request that contains the specified value of that order number.
- Parameter messages
- On the Correlation Set tab, select a Web Service parameter that will contain a unique value to differentiate one workflow instance from another.
For example, you might use an invoice number.
- Select the data field in the current workflow definition that will contain the value to be matched.
NOTE Since all incoming data is in string format, the correlation value to be compared must also be a string. For example, if the data field in the current workflow definition were an integer, you would use an expression to convert it to a string—convert(field_name, string).
- XML messages
- On the Correlation Set tab, specify a name for this correlation set. (You can specify more than one correlation set.)
- Under Properties, specify a name and the XPath Query to the appropriate element in the schema. You can specify more than one name/XPath Query pair to define the correlation expression. For example, you might use a combination of an account number and invoice number to identify the appropriate incoming message.
A template version of the schema displays to help you in creating the XPath Query. See Web Services Correlation example for an example correlation set using XML.
For XML messages, in addition to setting up the Correlation set in the Receive step, you must assign the correlation value to the system field F_Corr<Correlation_Set_Name> at some point in the workflow preceding the Receive step.