9 Integrating With BPEL

This chapter has the following sections:

Section 9.1, "Invoking I/PM Web Services From a BPEL Process"

For additional information on workflow integration points, connection configuration, security and fault reporting, see Oracle Fusion Middleware Administrator's Guide for Imaging and Process Management.

9.1 Invoking I/PM Web Services From a BPEL Process

One possible integration point between Oracle I/PM and BPEL is a service call into BPEL from Workflow Agent to create a new process instance using document metadata stored in Oracle I/PM. It is also possible for the BPEL process to make web service calls back to Oracle I/PM. Such calls can retrieve the latest document metadata, additional metadata, or update document metadata to synchronize changes made during the execution of the process instance.

Calls to any Oracle I/PM web service from BPEL will use the same general procedure:

On the composite design diagram, select the Web Service service adapter from the Component Palette and drag it to the External References swim lane.
Enter a name for the service and the WSDL URL for the service. Oracle I/PM web service WSDLS take the form:

http://<host>:<port>/imaging/ws/<service>?wsdl

Where <service> would be one of the possible Oracle I/PM Web Service end points (ApplicationService, DocumentService, etc.).
On the composite diagram, link the BPEL process to the newly create external reference.
Open the BPEL process diagram. In this diagram, the external reference added to the composite will appear in the Partner Links swim lane.
Add an Invoke activity to the diagram and link it to the web service partner link.
In the invoke properties dialog, select the desired operation, and then click the + button next to the Input and Output variables to link the Invoke activity.
Click OK. The dialog box closes.
Add a Transform activity to the BPEL process diagram before the Invoke activity.
In the properties for the Transform Activity, select an appropriate source variable from the process, and select the input variable of the Invoke activity created in step 5 as the Target Variable.
Click the + next to the Mapper File to define the transformation mapping of process data into the web service input payload.
If output is expected to be returned from the Oracle I/PM web service invoke, a Transform or Assign activity can be used after the Invoke to transfer data from the Invoke output variable back into process variables.

9.1.1 Invoking DocumentService.updateDocument Sample

As mentioned above, the transform definition from BPEL instance variables to Oracle I/PM web service input variables is a complex topic that is dependent on the specific schemas involved. However, because updating document metadata is a common use case for BPEL to Oracle I/PM interaction, this section provides an example of how the transform might be defined for a DocumentService updateDocument operation used to modify document field values.

In this example, a purchase order document is indexed into Oracle I/PM and a BPEL process instance is created in an approval process. During the execution of the approval process, the instance is approved or denied. At the end of the process, Oracle I/PM needs to be updated with the approval status and the name of the user setting the status. This example assumes the following configuration.

Application Definition contains the following fields:

PurchaseOrder: id=1, type string
ApprovedBy: id=2, type string
ApprovedStatus: id=3, type string

The BPEL Process variable is defined as follows:

<element name="process">
  <complexType>
    <sequence>
      <element name="docId" type="string"/>
      <element name="docURL" type="string"/>
      <element name="poNumber" type="string"/>
      <element name="approvedBy" type="string"/>
      <element name="approvedStatus" type="string"/>
    </sequence>
  </complexType>
</element>

An external partner link is defined using the document service WSDL:

http://host:port/imaging/ws/DocumentService?wsdl.

The updateDocument operation payload type is defined as follows:

<xs:complexType name="updateDocument">
  <xs:sequence>
    <xs:element name="documentId" type="xs:string" minOccurs="0"/>
    <xs:element name="uploadToken" type="xs:string" minOccurs="0"/>
    <xs:element name="fieldValues" type="tns:FieldValue" 
          minOccurs="0" maxOccurs="unbounded"/>
    <xs:element name="updateAnnotations" type="xs:boolean"/>
  </xs:sequence>
</xs:complexType>

For modifying document field values, the elements that are significant are the documented elements and the fieldValues element. The FieldValue type and the types references are defined as follows:

<xs:complexType name="FieldValue">
  <xs:complexContent>
    <xs:extension base="tns:baseId">
      <xs:sequence>
        <xs:element name="value" type="tns:TypedValue" minOccurs="0"/>
      </xs:sequence>
      <xs:attribute name="name" type="xs:string"/>
      <xs:attribute name="id" type="xs:long" use="required"/>
    </xs:extension>
    </xs:complexContent>
</xs:complexType>
<xs:complexType name="TypedValue">
  <xs:simpleContent>
  <xs:extension base="xs:string">
    <xs:attribute name="type" type="tns:FieldType"/>
  </xs:extension>
  </xs:simpleContent>
</xs:complexType>
<xs:simpleType name="FieldType">
   <xs:restriction base="xs:string">
     <xs:enumeration value="TEXT"/>
     <xs:enumeration value="NUMBER"/>
     <xs:enumeration value="DECIMAL"/>
     <xs:enumeration value="DATE"/>
   </xs:restriction>
 </xs:simpleType>

Although the XSD for FieldValue looks rather complicated, the following sample XML instance of FieldValue demonstrates that it is actually fairly simple.

<fieldValues name=”ApprovedStatus”, id=”3”>
   <value type=”TEXT”>
        APPROVED
   </value>
</fieldValues>

The name and ID attributes in the fieldValues node are the name and ID of the document field value to be modified. In practice, providing one or the other is enough to identify the field. The value element provides the new value of the document field, and the type attribute, which is one of TEXT, NUMBER, DECIMAL, or DATE) indicates the Oracle I/PM type of data being provided.

The updateDocument type XSD indicates that the fieldValues has an unbounded maxOccurs attribute. In fact, the service expects that there be one instance of the element for each document field value that is being modified. Field Values that are not being modified need not be supplied.

Finally, the XSL transform in the BPEL process must assign the docId element from the BPEL instance variable to the documentId node in updateDocument and transform the ApprovedBy and ApprovedStatus values in the BPEL process variable into two FieldValue elements. The transform is defined as follows:

<xsl:template match="/">
  <tns:updateDocument>
    <documentId>
      <xsl:value-of select="/client:process/client:docId"/>
    </documentId>
    <xsl:for-each select="/client:process/client:approvedBy">
      <fieldValues>
        <xsl:attribute name="name">
          <xsl:text>ApprovedBy</xsl:text>
        </xsl:attribute>
        <value>
          <xsl:attribute name="type">
            <xsl:text>TEXT</xsl:text>
          </xsl:attribute>
          <xsl:value-of select="/client:process/client:approvedStatus"/>
        </value>
      </fieldValues>
    </xsl:for-each>
    <xsl:for-each select="/client:process/client:approvedStatus">
      <fieldValues>
        <xsl:attribute name="name">
          <xsl:text>ApprovedBy</xsl:text>
        </xsl:attribute>
        <value>
          <xsl:attribute name="type">
            <xsl:text>TEXT</xsl:text>
          </xsl:attribute>
          <xsl:value-of select="/client:process/client:approvedStatus"/>
        </value>
      </fieldValues>
    </xsl:for-each>
  </tns:updateDocument>
</xsl:template>