Working With Oracle Workflow Business Event System to Invoke Web Services

Understanding Web Service Input Message Parts

A message consists of one or more logical parts. Each part describes the logical abstract content of a message. For example, a typical document-style Web service could have a header part and a body part in the input message.

For example, consider the operation PROCESSPO in Oracle E-Business Suite XML Gateway service (http://<host>:<port>/webservices/SOAProvider/xmlgateway/ont__poi/?wsdl) as described below.

<definitions targetNamespace="ONT__POI" targetNamespace="http://xmlns.oracle.com/apps/ont/soaprovider/xmlgateway/ont__poi/">
<type>
   <schema elementFormDefault="qualified" targetNamespace="http://xmlns.oracle.com/apps/ont/soaprovider/xmlgateway/ont__poi/">
    <include schemaLocation="http://<host>:<port>/webservices/SOAProvider/xmlgateway/ont__poi/PROCESS_PO_007.xsd"/>
   </schema>
...
<message name="PROCESSPO_Input_Msg">
	 <part name="header" element="tns:SOAHeader"/>
   <part name="body" element="tns1:PROCESS_PO_007"/>
</message>
...
<binding name="ONT__POI_Binding" type="tns:ONT__POI_PortType">
<soap: binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
	 <operation name="PROCESSPO">
		<soap:operation soapAction="http://<host>:<port>/webservices/SOAProvider/xmlgateway/ont__poi/"/>
		<input>
			<soap:header message="tns:PROCESSPO_Input_Msg" part="header" use="literal"/>
			<soap:body parts="body" use="literal"/>
   </input>
  </operation>
</binding>
...
</definitions>

The operation PROCESSPO requires input message PROCESSPO_Input_Msg, which has two parts:

Body: The value of PROCESS_PO_007 type to be set as SOAP body is sent as business event payload.
Header: The value of SOAHeader type to be sent in the SOAP header which is required for Web Service authorization.

To better understand the Web service operation's input message, this section includes the following topics:

Event Payload as SOAP Body

Any detailed information needed to describe what occurred in an event, in addition to the event name and event key, is called the event data. For example, the event data for a purchase order event includes the item numbers, descriptions, and cost.

During the event creation, you can have the event data specified either with or without using the Generate Function for an event from both PL/SQL and Java. If the application where the event occurs does not provide event data, then you can use the Generate Function while creating the event. The Generate Function will produce the complete event data from the event name, event key, and an optional parameter list at the event raise. Otherwise, you do not need to specify the Generate Function field if the application where the event occurs does provide event data. In other words, the event payload can be passed in either one of the following ways:

Event data or payload is passed through the Generate Function during the event raise.
Event data or payload is passed along with the event itself without using the Generate Function.

Note: The Generate Function must follow a standard PL/SQL or Java API. See the Oracle Workflow Developer's Guide and the Oracle Workflow API Reference.

The event data can be structured as an XML document and passed as SOAP body during the event raise. The seeded Java rule function accepts this SOAP body through business event payload. The SOAP body is described in a well-formed XML element that would be embedded into a SOAP envelope.

BusinessEvent.setData(String)
WF_EVENT.Raise(.... p_event_data => ....);

Message Transformation Parameters to Support XSL Transformation

If the invoker event's XML payload (to be used as Web service input message) requires to be transformed into a form that complies with the input message schema, the seeded Java rule function could perform XSL transformation on the payload before invoking the Web service. Similarly, if the Web service output message requires to be transformed into a form that is required for processing by Oracle E-Business Suite, the seeded Java rule function could perform XSL transformation on the response before calling back to Oracle E-Business Suite.

Note: An input message is the XML payload that is passed to the Web service in the SOAP request. An output message is the XML document received as a response from the Web service after a successful invocation.

For the synchronous request - response operation, when the output (response) message, an XML document, is available, if this XML document requires to be transformed to a form that is easier for Oracle E-Business Suite to understand, then XSL transformation on the output message will be performed.

Note: The XSL filename is given based on the format of <File Name>:<Application Short Name>:<Version>.

For example, "PO_XSL_1_1_2.xsl:FND:1.1".

The XSL file names are passed to the seeded Java rule function as the following subscription parameters while creating the subscription to the Web service invoker event through the Create Event Subscription - Invoke Web Service wizard:

WFBES_OUT_XSL_FILENAME: XSL file to perform transformation on the output (response) message

For example, WFBES_OUT_XSL_FILENAME=PO_XSL_OUT_2.xsl:FND:1.1
WFBES_IN_XSL_FILENAME: XSL file to perform transformation on the input message

For example, WFBES_IN_XSL_FILENAME=PO_XSL_IN_2.xsl:FND:1.1

At run time, the XSL filenames are passed through the same parameters as event parameters. If event parameters are passed with the same names as the subscription parameters that have been parsed and stored, the event parameter values override the subscription parameter values. For example, the event parameters are passed as follows:

BusinessEvent.setStringProperty("WFBES_OUT_XSL_FILENAME", "PO_XSL_OUT_2.xsl:FND:1.1");
BusinessEvent.setStringProperty("WFBES_IN_XSL_FILENAME", "PO_XSL_IN_2.xsl:FND:1.1");

If WFBES_OUT_XSL_FILENAME is null, no outbound transformation will be performed. If WFBES_IN_XSL_FILENAME is null, no inbound transformation will be performed.

Loading XSL files to Oracle E-Business Suite

The seeded Java rule function performs the XSL transformation on the input and output messages by using the XML Gateway API, ECX_STANDARD.perform_xslt_transformation; therefore, the XSL files for the XSL transformation on the input and output messages are loaded to Oracle XML Gateway using the oracle.apps.ecx.loader.LoadXSLTToClob loader.

Note: For information on the XSL transformation PL/SQL API, see Execution Engine APIs.

As a result, use the following steps to perform XSL transformation during service invocation:

Upload the XSL files to Oracle E-Business Suite using the oracle.apps.ecx.loader.LoadXSLTToClob loader in Oracle XML Gateway.
Specify the XSL file names (such as PO_XSL_IN_2.xsl:FND:1.1) in the event or subscription parameters (WFBES_IN_XSL_FILENAME and WFBES_OUT_XSL_FILENAME) if applicable for XSL transformation on the input and output messages.

For example, upload the XSL files to Oracle E-Business Suite as follows:

java oracle.apps.ecx.loader.LoadXSLTToClob apps password 
ap601sdb:4115:owf12dev PO_XSL_IN_2.xsl FND 1.1

For more information, see Loading and Deleting an XSLT Style Sheet.

Other Web Service Input Message Parts

Apart from passing the SOAP body part as an event payload, service invocation framework also supports passing values for other parts that are defined for the Web service operation's input message using the business event parameter with the following format:

WFBES_INPUT_<partname>

<partname> is the same as the part name in the input message definition in WSDL.

For example, the header part for the above example is passed to the business event as parameter WFBES_INPUT_header during the invoker event raise. The following code snippet shows the header part that is used to pass username, responsibility, responsibility application, and NLS language elements for Web service authorization:

	String headerPartMsg = "<SOAHeader
xmlns:=\"http://xmlns.oracle.com/xdb/SYSTEM\" " +
			 	  					"env:mustUnderstand=\"0\"
xmlns:env=\"http://schemas.xmlsoap.org/soap/envelope/\"> \n" +
									" <MESSAGE_TYPE>XML<MESSAGE_TYPE>\n" +
									" <MESSAGE_STANDARD>OAG<MESSAGE_STANDARD>\n" +
									" <TRANSACTION_TYPE>PO<TRANSACTION_TYPE>\n" +
									" <TRANSACTION_SUBTYPE>PROCESS<TRANSACTION_SUBTYPE>\n" +
									" <DOCUMENT_NUMBER>123<DOCUMENT_NUMBER>\n" +
									" <PARTY_SITE_ID>4444<PARTY_SITE_ID>\n" +
									"<SOAHeader>\n"; 
businessEvent.setStringProperty("WFBES_INPUT_header", headerPartMsg);

Note: Please note that this WFBES_INPUT_<partname> parameter can only be passed at run time during the event raise, not through the event subscription. Several constants are defined in interface oracle.apps.fnd.wf.bes.InvokerConstants for use in Java code.

If the Web service input message definition has several parts, value for the part that is sent as SOAP body is passed as an event payload. Values for all other parts are passed as event parameters with parameter name format WFBES_INPUT_<partname>. If the value for a specific input message part is optional to invoke the Web service, you still have to pass the parameter with null value so that invoker subscription knows to which part the event payload should be set as SOAP body.

For example, if input message part myheader for a Web service is optional and does not require a valid value for the invocation to succeed, the event parameter for the input should still be set with null value as follows.

businessEvent.setStringProperty("WFBES_INPUT_myheader", null);