Working With Oracle Workflow Business Event System to Invoke Web Services

This chapter covers the following topics:

Oracle Workflow and Service Invocation Framework Overview

Oracle E-Business Suite Integrated SOA Gateway leverages Oracle Workflow Java Business Event System to provide infrastructure for Web Service Invocation natively from Oracle E-Business Suite.

Oracle Workflow is the primary process management solution within Oracle E-Business Suite. It consists of some key components enabling you model and automate business processes and activities in a process diagram based on user-defined business rules, providing routing mechanism to support each decision maker in the process, facilitating subscriptions to significant events or services between systems, and implementing workflow process definitions at run time with monitoring capability of each workflow state as well as handling errors. Since it provides a total solution of managing and streamlining complex business processes and supporting highly-integrated workflow in and out from Oracle E-Business Suite, Oracle E-Business Suite Integrated SOA Gateway relies on Oracle Workflow to enable the service invocation process and provide the following functionality:

For detailed information about Oracle Workflow, see Oracle Workflow User's Guide, Oracle Workflow Developer's Guide, and Oracle Workflow Administrator's Guide.

To better understand how service invocation framework is used in facilitating the invocation of Web services, the following topics are discussed in this chapter:

Web Service Invocation Using Service Invocation Framework

Service invocation framework provides an infrastructure allowing developers to interact with Web services through WSDL descriptions and to invoke Web services from Oracle E-Business Suite.

To achieve this goal, the invocation framework uses a wizard based user interface in Oracle Workflow Business Event System to parse a given Web service WSDL URL during the subscription creation and store identified service information or metadata as subscription parameters that will be used later during service invocation.

Since a WSDL URL is used in representing a Web service, the underlying service can be a simple native Web Service or it can be a BPEL process.

Please note that the service invocation framework discussed here only supports document-based Web service invocation. The invocation framework does not support RPC (remote procedure call) style Web service invocation.

The following diagram illustrates the high level service invocation process flow:

the picture is described in the document text

To successfully invoke Web services at run time, Web service invocation metadata must first be in place. In addition to defining the invocation metadata, the concepts of message patterns, Web service input message parts, and Web service security that the service invocation framework supports are also introduced in this section.

The section covers the following topics:

Understanding Message Patterns in WSDL

There are two major message exchange patterns — a request-response pattern, and a one-way (request - only) pattern.

Request - Response Message Pattern

The request - response message exchange pattern is where a client asks a service provider a question and then receives the answer to the question. The answer may come in the form of a fault or exception. Both the request and the response are independent messages. The request - response pattern is often implemented using synchronous operations for simple operations. For longer running operations, asynchronous (with message correlation) is often chosen.

Request - Response Message Pattern

the picture is described in the document text

Important: In this release, the Web service invocation framework only supports Synchronous Request - Response message pattern and One - Way (Request Only) message pattern.

Request Only Message Pattern

The request only operation model includes one input element, which is the client's request to the server. No response is expected.

Request Only Message Pattern

the picture is described in the document text

For example, client zip code locations send updated weather data to the service when local conditions change using the request only operation. The server updates the data but no response is sent back.

Defining Web Service Invocation Metadata

Because the service invocation is taken place in the Oracle Workflow Business Event System, before invoking a Web service, the Web service invocation metadata including events and event subscriptions must be defined first through the Business Event System.

This section discusses the following topics:

  1. Creating a Web Service Invoker Business Event

    A Web service Invoker business event that serves as a request message (or Web service input message) for a service needs to be created first.

  2. Creating Local and Error Event Subscriptions to the Invoker Event

    After defining the Invoker event, you need to create the following two subscriptions:

  3. Creating a Receive Event and Event Subscription (Optional)

    This step is required only if a Web service has an output or a response message to communicate or callback to Oracle E-Business Suite. Once a receive event is in place, you must create an External subscription to the receive event to pass the Web service response message.

    If a Web service does not require a response, then you do not need to create a receive event, nor the event subscription.

Step 1: Creating a Web Service Invoker Business Event

A business event is an occurrence in an internet or intranet application or program that might be significant to other objects in a system or to external agents. For instance, the creation of a purchase order is an example of a business event in a purchasing application.

Use the Oracle Workflow Business Event System to define a web service invoker business event.

The invoker event can be served as a request message (or web service input message) in a message pattern to send inquiries to a service.

To invoke a web service through the Business Event System, we will first create an invoker business event, and then subscribe to the invoker event later with an appropriate action type.

Note: In this release, the web service invocation framework supports the following types of service invocation:

For more information about business events, see Events, Oracle Workflow Developer's Guide.

To create an invoker event:

  1. Log on to Oracle E-Business Suite with the Workflow Administrator Web responsibility. Select the Business Events link, and choose Events in the horizontal navigation if the Events page is not already displayed.

  2. In the Events page, click Create Event to open the Create Event page.

  3. Enter the following information in the Create Event page:

    • Name: Enter an event name, such as oracle.apps.wf.xmlgateway.invoke

    • Display Name: Enter an event display name, such as oracle.apps.wf.xmlgateway.invoke

    • Description: Enter a description for the event

    • Status: Enabled

    • Generate Function: Specify a generate function for the PL/SQL based event if the application where the event occurs will not provide the event data

    • Java Generate Function: Specify a generate function for the Java based event if the application where the event occurs will not provide the event data

    • Owner Name: Specify the program or application name that owns the event (such as Oracle Workflow)

    • Owner Tag: Specify the program or application ID that owns the event (such as 'FND')

    Create Event Page

    the picture is described in the document text

  4. Click Apply to save your work.

    Leave this page open to create a receive event.

For more information on how to create a business event, see Oracle Workflow Developer's Guide for details.

Step 2: Creating Local and Error Event Subscriptions to the Invoker Event

Create a Local Subscription With 'Invoke Web Service' Action Type

To subscribe to an invoker event, you must create a subscription with 'Invoke Web Service' Action Type which indicates that when a triggering event occurs, the action item of this subscription is to invoke a web service. This requires you enter a WSDL URL representing a web service of any type (such as a native web service or BPEL process) in the Create Event Subscription - Invoke Web Service wizard. That WSDL information entered in the wizard will then be parsed into service metadata for further selections.

Note: A BPEL process itself is a web service, defining and supporting a client interface through WSDL and SOAP. The BPEL process WSDL URL can be created through a partner link which allows the request to be published to the Oracle BPEL Process Manager to connect to web services.

When a triggering event occurs, the Business Event System executes the subscription through the seeded Java function and invokes the BPEL process.

After you select appropriate service metadata, this selected data will be stored as subscription parameters as follows:

The seeded Java Rule Function oracle.apps.fnd.wf.bes.WebServiceInvokerSubscription uses these subscription parameters during the service invocation.

Note: Oracle E-Business Suite Integrated SOA Gateway allows developers to extend the invoker subscription seeded rule function using Java coding standards for more specialized service invocation processing. For more information on customizing seeded Java rule function, see Extending Seeded Rule Function.

Apart from the subscription parameters that have been parsed and stored through the Invoke Web Service Subscription page, the following information could also be captured if it is specified as additional subscription parameters that will then be used by the seeded Java rule function to enable message processing for web service invocation:

Creating a Local Event Subscription with 'Invoke Web Service' Action Type

Create Event Subscription Page

the picture is described in the document text

To create a local event subscription with 'Invoke Web Service' action type:

  1. Log on to Oracle E-Business Suite with the Workflow Administrator Web responsibility. Select the Business Events link, and choose Subscriptions in the horizontal navigation.

  2. In the Event Subscriptions page, click Create Subscription to open the Create Event Subscription page.

  3. Enter the following information in the Create Event Subscription page:

    • Subscriber: Select the local system

    • Source Type: Local

    • Event Filter: Select the event name that you just created, such as oracle.apps.wf.xmlgateway.invoke

    • Phase: 50

      If the event is raised from Java, the phase number determines whether an event will be invoked right away or enqueued to WF_JAVA_DEFFERED queue.

      Note: If the invoker event is raised from PL/SQL, it is always deferred to WF_JAVA_DEFERRED queue regardless of the phase because the subscription has a Java rule function that cannot be executed in the database.

      • If the phase is >=100, then the event is enqueued to WF_JAVA_DEFFERED queue and will be dispatched later.

      • If the phase is <100, then the event is dispatched immediately to the Java Business Event System soon after an triggering event occurs.

    • Status: Enabled

    • Rule Data: Message

    • Action Type: Invoke Web Service

    • On Error: Stop and Rollback

  4. Click Next. This opens a Create Event Subscription - Invoke Web Service wizard allowing you to enter a WSDL URL that will be parsed into service metadata for further selection.

    Create Event Subscription - Invoke Web Service Wizard

    the picture is described in the document text

    1. Enter WSDL URL information for the web service to be invoked. Click Next to parse the WSDL and display all services.

    2. Select an appropriate service name from the drop-down list.

      Create Event Subscription - Invoke Web Service: Select Service

      the picture is described in the document text

      Click Next to display all ports for a selected service.

    3. Select an appropriate service port.

      Create Event Subscription - Invoke Web Service: Select Service Port

      the picture is described in the document text

      Click Next to display all operations for a selected port.

    4. Select an appropriate service operation.

      Create Event Subscription - Invoke Web Service: Select Operation

      the picture is described in the document text

      Click Next to display the last page of the Create Event Subscription - Invoke Web Service wizard.

    5. In the Subscription Documentation of the Create Event Subscription - Invoke Web Service page, the default Java Rule Function name oracle.apps.fnd.wf.bes.WebServiceInvokerSubscription is automatically populated.

      Important: If you have extended the functionality of the seeded rule function, manually enter your custom function name here.

      Create Event Subscription - Invoke Web Service: Subscription Documentation

      the picture is described in the document text

    6. In the Documentation region, enter an application name or program name that owns the subscription (such as 'Oracle Workflow') in the Owner Name field and the program ID (such as 'FND') in the Owner Tag field. Click Apply.

For more information, see Defining Event Subscriptions, Oracle Workflow Developer's Guide.

Create an Error subscription with 'Launch Workflow' Action Type

To enable the error processing feature during the service invocation, you must create an Error subscription to the invoker business event.

Once subscribing to this error processing, if any error occurs during the invocation, the error process sends a workflow notification to SYSADMIN. This information includes web service definition, event details, and error details allowing SYSADMIN to easily identify the error. The notification also provides an option for SYSADMIN to respond to the error. The SYSADMIN can invoke the web service again after the underlying issue that caused the error is resolved, abort the errored event if needed, or reassign an errored notification to another user if appropriate.

For detailed information on managing errors during web service invocation, see Managing Errors.

To create an error subscription with 'Launch Workflow' action type:

  1. Log on to Oracle E-Business Suite with the Workflow Administrator Web responsibility. Select the Business Events link, and choose Subscriptions in the horizontal navigation.

  2. In the Event Subscriptions page, click Create Subscription to open the Create Event Subscription page.

  3. Enter the following information in the Create Event Subscription page:

    • Subscriber: Select the local system

    • Source Type: Error

    • Event Filter: Select the event name that you just created, such as oracle.apps.wf.xmlgateway.invoke

    • Phase: this can be any phase number

    • Status: Enabled

    • Rule Data: Key

    • Action Type: Launch Workflow

    • On Error: Stop and Rollback

    Create Event Subscription Page

    the picture is described in the document text

  4. Click Next to open the Create Event Subscription - Launch Workflow page.

  5. Enter the following information in the Action region:

    • Workflow Type: WFERROR

    • Workflow Process: DEFAULT_EVENT_ERROR2

    • Priority: Normal

  6. In the Documentation region, enter an application or program name that owns the event subscription (such as Oracle Workflow) in the Owner Name field and application or program ID (such as 'FND') in the Owner Tag field.

    Create Event Subscription - Launch Workflow Page

    the picture is described in the document text

  7. Click Apply.

Step 3: Creating a Receive Event and Subscription (Optional)

A receive event can serve as a communication vehicle to communicate or callback to Oracle E-Business Suite if a web service has an output or response message required to be communicated back after the web service is successfully invoked. However, whether you need to create a receive event and external subscription to the receive event depends on the following criteria:

For Synchronous Request-Response Web Service Invocation

For Request-only Web Service

If it is a request-only web service which does not require a response, you do not need to create a receive event.

To create a receive event:

  1. In the Events page, click Create Event to open another Create Event page.

  2. Enter the following information in the Create Event page:

    • Name: Enter an event name, such as oracle.apps.wf.xmlgateway.receive

    • Display Name: Enter an event display name, such as oracle.apps.wf.xmlgateway.receive

    • Description: Enter a description for the event

    • Status: Enabled

    • Owner Name: Enter an application or program name that owns the event (such as 'Oracle Workflow')

    • Owner Tag: Enter the application or program ID that owns the event (such as 'FND')

    Create Event Page

    the picture is described in the document text

  3. Click Apply to create a receive event.

To create a receive event subscription:

  1. Log on to Oracle E-Business Suite with the Workflow Administrator Web Applications responsibility. Select the Business Events link, and choose Subscriptions in the horizontal navigation.

  2. In the Event Subscriptions page, click Create Subscription to open the Create Event Subscription page.

  3. Enter the following information in the Create Event Subscription page:

    • Subscriber: Select the local system

    • Source Type: External

    • Event Filter: Select the receive event name that you just created, such as oracle.apps.wf.xmlgateway.receive

    • Phase: any phase number

    • Status: Enabled

    • Rule Data: Key

    • Action Type: any action type

    • On Error: Stop and Rollback

    Create Event Subscription Page

    the picture is described in the document text

  4. Click Next to open the Create Event Subscription - Launch Workflow page.

    Note that the type of the Create Event Subscription page to be shown depends on the value selected in the Action Type field. If "Launch Workflow" is selected, you will see the Create Event Subscription - Launch Workflow page. If other action types are selected, different types of the create event subscription pages are displayed. By entering an appropriate action type through the subscription page, you can launch a workflow process or just execute a custom rule function for the event defined as part of this subscription.

  5. Enter the following information in the Action region:

    • Workflow Type: Enter any workflow type that is waiting for the response

    • Workflow Process: Enter any workflow process that is waiting for the response

    • Priority: Normal

  6. In the Documentation region, enter an application or program name in the Owner Name field (such as 'Oracle Workflow') and application or program ID in the Owner Tag field (such as 'FND').

    Update Event Subscription: Launch Workflow Page

    the picture is described in the document text

  7. Click Apply.

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 and body part in the input message.

For example, consider the operation PROCESSPO in Oracle E-Business Suite XML Gateway service (http://<hostname>:<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://<hostname>:<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:

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

Event Payload as SOAP Body

Any detail 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:

Note: The generate function must follow a standard PL/SQL or Java API. See Oracle Workflow Developer's Guide and 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 SOAP envelope.

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:

At runtime, 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:

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 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, Oracle XML Gateway User's Guide.

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

  1. Upload the XSL files to Oracle E-Business Suite using the oracle.apps.ecx.loader.LoadXSLTToClob loader in Oracle XML Gateway.

  2. 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 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 
<hostname>:<port>:<sid> PO_XSL_IN_2.xsl FND 1.1

For more information, see Loading and Deleting an XSLT Style Sheet, Oracle XML Gateway User's Guide.

Other Web Service Input Message Parts

Apart from passing the SOAP body part as 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 same as the part name in the input message definition in WSDL.

For example, the header part for above example is passed to 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 = "<ns1:SOAHeader
xmlns:ns1=\"http://xmlns.oracle.com/xdb/SYSTEM\" " +
                                                                        "env:mustUnderstand=\"0\"
xmlns:env=\"http://schemas.xmlsoap.org/soap/envelope/\"> \n" +
                                                                        " <ns1:MESSAGE_TYPE>XML</ns1:MESSAGE_TYPE>\n" +
                                                                        " <ns1:MESSAGE_STANDARD>OAG</ns1:MESSAGE_STANDARD>\n" +
                                                                        " <ns1:TRANSACTION_TYPE>PO</ns1:TRANSACTION_TYPE>\n" +
                                                                        " <ns1:TRANSACTION_SUBTYPE>PROCESS</ns1:TRANSACTION_SUBTYPE>\n" +
                                                                        " <ns1:DOCUMENT_NUMBER>xxx</ns1:DOCUMENT_NUMBER>\n" +
                                                                        " <ns1:PARTY_SITE_ID>xxxx</ns1:PARTY_SITE_ID>\n" +
                                                                        "</ns1:SOAHeader>\n"; 
businessEvent.setStringProperty("WFBES_INPUT_header", headerPartMsg);

Note: This WFBES_INPUT_<partname> parameter can only be passed at runtime during the event raise, not through the event subscription. Several constants are defined in the 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 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);

Supporting WS-Security

Web service security (WS-Security) is a communication protocol providing a means for applying security to web services. It describes enhancements to SOAP messaging to provide quality of protection through message integrity and single message authentication. It also describes how to attach security tokens to SOAP messages to enhance security features.

Service invocation framework supports WS-Security in a general-purpose mechanism for associating security tokens with messages to authenticate web service requests and service invocation from Oracle E-Business Suite.

To accomplish this goal, service invocation framework supports WS-Security through UsernameToken based security.

UsernameToken Based Security

This security mechanism provides a basic authentication for Web service invocation by passing a username and an optional password in the SOAP Header of a SOAP request sent to the web service provider.

Note that the username/password information discussed in this UsernameToken based security model is the concept of Oracle E-Business Suite username/password.

If the web service being invoked enforces Username/Password based authentication, then the service invocation framework also supports the UsernameToken-based WS-Security header during the service invocation.

Note: SOAP requests invoking the web services should include security header consisting of Username and Plain text password. Encryption is not supported in this release.

Username

The username is a clear text, and its value for the operation is stored in the subscription parameter:

WFBES_SOAP_USERNAME

For example, WFBES_SOAP_USERNAME =SYSADMIN

Following sample code describes how the username is stored with the subscription as web service metadata:

SERVICE_WSDL_URL=http://<hostname>:<port>/OA_HTML/XMLGatewayWSDL SERVICE_NAME=XMLGateway SERVICE_PORT=XMLGatewayPort SERVICE_PORTTYPE=XMLGatewayPortType SERVICE_OPERATION=ReceiveDocument WFBES_SOAP_USERNAME=SYSADMIN

Password

Password is the most sensitive part of the UsernameToken profile. Service invocation framework supports the UsernameToken based WS-Security during service invocation with username and an optional password with Type PasswordText.

Note: The PasswordText password type is the password written in clear text. There is another password type called 'PasswordDigest' which is a base64-encoded SHA-1 hash value of the UTF8-encoded password and this type of password is not supported in this release.

The password corresponding to the SOAP username is stored in FND vault using a PL/SQL script $FND_TOP/sql/afvltput.sql. For example,

sqlplus apps/password@db @$FND_TOP/sql/afvltput.sql <Module> <Key> <Value>

The module and key values to retrieve the password corresponding to the SOAP username are passed to the following invoker subscription parameters:

For example, if you want to store the password value ("password") for a web service, it could be stored as follows:

sqlplus apps/password@db @$FND_TOP/sql/afvltput.sql FND sysadmin password

At runtime, if event parameters are passed with the same names as the subscription parameters that have been parsed and stored, the event parameter values take precedence over the subscription parameters.

For example, the event parameters are passed as follows:

In summary, use the following steps to pass username and password for WS-Security during web service invocation:

  1. Pass the username to event or subscription parameter WFBES_SOAP_USERNAME.

  2. Store the password in FND Vault using $FND_TOP/sql/afvltput.sql script through appropriate module and key.

  3. Pass the module name and key to event or subscription parameters WFBES_SOAP_PASSWORD_MOD and WFBES_SOAP_PASSWORD_KEY.

Calling Back to Oracle E-Business Suite With Web Service Response

As mentioned earlier that Oracle Workflow is the primary process management solution within Oracle E-Business Suite; Oracle Workflow Business Event System, an essential component within Oracle Workflow, provides event and subscription features that help identify integration points within Oracle E-Business Suite. Thus, to successfully invoke Web services from Oracle E-Business Suite requires highly integrated environment with Oracle Workflow.

To support synchronous request - response service operation, if a Web service has an output or a response message, service invocation framework uses the callback mechanism in Oracle Workflow to communicate the response message back to Oracle E-Business Suite through the Business Event System.

Note: A synchronous request - response message is a common message exchange pattern in Web service operation where a client asks a service provider a question and then waits for a response before continuing on. For more information, see: Understand Message Patterns.

This callback feature takes the invoker event's event key to enqueue the callback event to the specified inbound agent (the callback agent) for the response. In addition, if a workflow process invokes a Web service using "Raise" event activity and waits for Web service response using "Receive" event activity, the invoker event key should be same as the invoker and/or waiting workflow process's item key so that when callback is performed, the waiting workflow process is correctly identified by WF_ENGINE.EVENT API.

By using both the callback events and agents, Web service invocation can be integrated back with a waiting workflow process or any other module within Oracle E-Business Suite. Web service invocation uses the following callback subscription or event parameters:

At run time, if event parameters are passed with the same names as the subscription parameters that have been parsed and stored, the event parameter values take precedence over subscription parameters. For example, the event parameters are passed as follows:

To use the callback feature during the service invocation, you must create a receive event and subscribe to the receive event. See: Creating a Receive Event and Event Subscription (Optional).

The better understand how to invoke a Web service, see Example of Invoking a Web Service From a Workflow Process

Invoking Web Services

Oracle Workflow Business Event System is a workflow component that allows events to be raised from both PL/SQL and Java layers. Therefore, the service invocation from Oracle E-Business Suite can be from PL/SQL or Java

Service Invocation from PL/SQL

  1. Application raises a business event using PL/SQL API WF_EVENT.Raise.

    The event data can be passed to the Event Manger within the call to the WF_EVENT.Raise API, or the Event Manger can obtain the event data or message payload by calling the Generate function for the event if the data or payload is required for a subscription.

    Note: See Oracle Workflow API Reference for information about WF_EVENT.Raise API.

  2. Oracle Workflow Business Event System (BES) identifies that the event has a subscription with Java Rule Function oracle.apps.fnd.wf.bes.WebServiceInvokerSubscription.

  3. The Business Event System enqueues the event message to WF_JAVA_DEFERRED queue. The Java Deferred Agent Listener then dequeues and executes the subscription whose Java rule function invokes the web service.

  4. If callback event and agent parameters are mentioned, the web service response is communicated back to Oracle E-Business Suite using the callback information. The Java Deferred Agent Listener process that runs in Concurrent Manager (CM) tier invokes the web service.

Service Invocation from Java

  1. Java Application raises a business event using Java method oracle.apps.fnd.wf.bes.BusinessEvent.raise either from OA Framework page controller/AMImpl or Java code running on Concurrent Manager tier.

  2. Since the event is raised in Java where the subscription's seeded Java Rule Function oracle.apps.fnd.wf.bes.WebServiceInvokerSubscription is accessible, whether the rule function is executed inline or deferred is determined by the phase of the subscription.

    • If the invoker subscription is created with Phase >= 100, the event is enqueued to WF_JAVA_DEFERRED queue.

    • If the invoker subscription is created with Phase < 100, the event is dispatched inline.

      If the event is raised from OA Framework page, the dispatch logic executes (that uses WSIF to invoke the web service) within OACORE OC4J container.

    Note: If the web service invoker event is raised from Java code in the application tier, and the invoker subscription is synchronous with subscription phase < 100, then the web service is invoked as soon as the event is raised, and if successful the response can be read by the calling application and is available immediately by using method BusinessEvent.getResponseData().

    If the event is raised from Java code with the subscription phase is >= 100 or if the event is raised from PL/SQL, the event message will be enqueued to WF_JAVA_DEFERRED queue. If the web service has an output or a response message, callback event with callback agent is required to receive the output message into Oracle E-Business Suite.

    The following sample Java code raises a business event that invokes web service and reads the response in the same session:

    package oracle.apps.fnd.wf.bes;

import java.sql.Connection;

import oracle.apps.fnd.common.AppsLog;
import oracle.apps.fnd.common.Log;
import oracle.apps.fnd.wf.bes.InvokerConstants;
import oracle.apps.fnd.wf.common.WorkflowContext;

public class InvokeWebService {

    static Log mLog;
    static WorkflowContext mCtx;
    
    public InvokeWebService() {
    }
        
    public static Connection getConnection(String dbcFile) {
        Connection conn = null;

        System.setProperty("dbcfile", dbcFile);
        WorkflowContext mCtx = new WorkflowContext();
        
        mLog = mCtx.getLog();
        mLog.setLevel(Log.STATEMENT);
        ((AppsLog)mLog).reInitialize();
        mLog.setModule("%");

        return mCtx.getJDBCConnection();    
    }
      
    public static void main(String[] args)
    {
        BusinessEvent event;
        Connection conn;
        conn = getConnection(args[0]);
        
        try {
            // Proxyt host and port requires to be set in Java options
            System.setProperty("http.proxyHost", args[1]);
            System.setProperty("http.proxyPort", args[2]);

            event = new BusinessEvent ("oracle.apps.wf.IrepService.invoke", "eventKey1");
                         
            // Input XML message for Web Service                        
            String input = null;
            input = "<ns3:IntegrationRepositoryService_GetInterfaceFunctionByName xmlns:ns3=\"http://xmlns.oracle.com/apps/fnd/rep/ws\"> \n"+
<fullMethodName>SERVICEBEAN:/oracle/apps/fnd/rep/ws/IntegrationRepositoryService:getInterfaceFunctionByNameSERVICEBEAN:/oracle/apps/fnd/rep/ws/IntegrationRepositoryService:getInterfaceFunctionByName</fullMethodName>\n"+
"</ns3:IntegrationRepositoryService_GetInterfaceFunctionByName>";
            event.setData(input);
                                 
                                 String headerPartMsg = "<ns1:SOAHeader
xmlns:ns1=\"http://xmlns.oracle.com/xdb/SYSTEM\" " +
                                                                        "env:mustUnderstand=\"0\"
xmlns:env=\"http://schemas.xmlsoap.org/soap/envelope/\"> \n" +
                                                                        " <ns1:MESSAGE_TYPE>XML</ns1:MESSAGE_TYPE>\n" +
                                                                        " <ns1:MESSAGE_STANDARD>OAG</ns1:MESSAGE_STANDARD>\n" +
                                                                        " <ns1:TRANSACTION_TYPE>PO</ns1:TRANSACTION_TYPE>\n" +
                                                                        " <ns1:TRANSACTION_SUBTYPE>PROCESS</ns1:TRANSACTION_SUBTYPE>\n" +
                                                                        " <ns1:DOCUMENT_NUMBER>123</ns1:DOCUMENT_NUMBER>\n" +
                                                                        " <ns1:PARTY_SITE_ID>4444</ns1:PARTY_SITE_ID>\n" +
                                                                        "</ns1:SOAHeader>\n"; 
businessEvent.setStringProperty("WFBES_INPUT_header", headerPartMsg);
                        
            event.raise(conn);
            conn.commit();
            
            Object resp = event.getResponseData();
            if (resp != null) {
                System.out.println(resp.toString());   
            }
            else {
                System.out.println("No response received");   
            }
        }
        catch (Exception e) {
            System.out.println("Exception occured " + e.getMessage());
            e.printStackTrace();
        }
    }
}

Example of Invoking a Web Service From a Workflow Process

The following example is to invoke a web service through launching a workflow process including the following nodes or activities:

The following workflow process diagram illustrates the service invocation process flow:

Workflow Process Diagram to Invoke a Web Service

the picture is described in the document text

Defining Service Invocation Metadata

To define the service invocation metadata with the callback feature, you must have the following necessary event and subscription in place:

  1. An invoker event, such as INVOKE_SERVICE in the workflow diagram.

    This activity is used to pass the event XML payload to be used as SOAP body and other required event parameters required for web service invocation as already discussed.

    See: Creating a Web Service Invoker Business Event.

  2. Local and error event subscriptions to the invoker event. See: Creating Local and Error Event Subscriptions to the Invoker Event.

  3. A receive event (such as RECEIVE_SERVICE in the workflow diagram) and the External subscription to the receive event.

    Important: The receive event is raised with the same event key as the event key for invoker event. It is important that the waiting workflow process's item key and the invoker event's event key are the same.

    If callback event and agent parameters are set, this activity waits for the receive event to occur after web service invocation is successful.

    See: Creating a Receive Event and Event Subscription (Optional).

Verifying Workflow Agent Listener Status

In order to process a web service response message from the inbound agent, you need to verify if a Workflow Agent Listener is running on that agent.

Use the following steps for verification:

  1. Log on to Oracle Workflow with Oracle Workflow Web Administrator responsibility.

  2. From the navigation menu, select Oracle Applications Manager, and click the Workflow Manager link.

  3. Click the Agent Listener status icon to open the Service Components page.

  4. Locate the Workflow Agent Listener that you use for the callback agent listener. For example, locate the 'Workflow Inbound JMS Agent Listener' for processing a web service response message to ensure it is up and running.

    Service Components Page to Validate the Status of a Workflow Agent Listener

    the picture is described in the document text

After the verification, you can launch the workflow process to invoke a web service with a callback response through Oracle Workflow. You can also validate the process by reviewing the progress status of each activity contained in your workflow process diagram.

When the web service has been successfully invoked from the automated workflow process, you should receive a workflow notification message if the notification activity is included in the process.

Web Service Invoked Page with a Notification Message

the picture is described in the document text

For more information on how to create and launch a workflow, see Oracle Workflow Developer's Guide.

Managing Errors

Service invocation framework uses the same way of handling errors in Business Event System to manage errors occurred during the execution of business event subscriptions. If the service invocation returns a fault message, the event is enqueued to error queue to trigger error processing. If an exception occurred during invocation process is due to service unavailability, the service faults should be logged and error subscription should be invoked.

To effectively process runtime exceptions for the events that are enqueued to an error queue, service invocation framework uses the following event ERROR process to specifically trigger error processing during the service invocation:

For example, if there is a runtime exception when the Workflow Java Deferred Agent Listener executes event subscription to invoke the web service, the event is enqueued to the WF_JAVA_ERROR queue. If the event has an Error subscription defined to launch the Error workflow process WFERROR:DEFAULT_EVENT_ERROR2, the Workflow Java Error Agent Listener executes the error subscription which sends a notification to SYSADMIN with web service definition, error details and event details. Since Oracle Workflow default event error handler provides options for SYSADMIN to retry the web service invocation process after verifying that the reported error has been corrected, SYSADMIN can invoke the web service again from the notification if necessary.

However, if there is a runtime exception when invoking the web service by raising the Invoker event with synchronous subscription (phase <100), the exception thrown to the calling application. It is the responsibility of the calling application to manage the exception.

Enabling Error Processing During Service Invocation

To enable the error processing feature during the service invocation, you must create an Error subscription with the following values:

Create Error Subscription - Launch Workflow Page

the picture is described in the document text

To access the Create Event Subscription page, log on to Oracle E-Business Suite with the Workflow Administrator Web Applications responsibility. Select the Business Events link and choose the Subscriptions subtab. In the Event Subscriptions page, click Create Subscription.

For information on how to create an error subscription for service invocation, see Create an Error Subscription with 'Launch Workflow' Action Type.

Testing Web Service Invocation

Service invocation framework uses the Oracle Workflow Test Business Event page to check the basic operation of Business Event System by raising a test event from either Java or PL/SQL layer and executing synchronous and asynchronous subscriptions to that event. This testing feature provides a flexible mechanism which easily lets you validate whether a web service can be successfully invoked from concurrent manager tier and OACORE OC4J.

You can test a web service invocation using one of the following ways:

Using the Test Business Event Page

Use the Test Business Event page to test a event by raising it from both PL/SQL API and Java method.

Testing Service Invocations

After logging on to Oracle Workflow with the Workflow Administrator Web responsibility. Select the Business Events link to search for an event that you want to test. From the search result table, click the Test icon next to the event you want to raise. This opens the Test Business Event page where you can raise the event with an unique event key. Enter event parameters for the invoker event subscription and a valid XML message that complies with input message schema. The Test Business Event page will also display response XML message if appropriate.

Note that the Test Business Event page will retain all the data entered. Therefore, if there is a need to raise another event, you must click Clear to clear all data that you have entered.

Following parameters may be specified when raising the event from the Test Business Event page to invoke a web service:

For information about these parameters, see:

Testing Invocation with Callback Required

If you want to test an invocation with callback to Oracle E-Business Suite, then you must enter the following parameters and values:

Note that for testing from the Test Business Event page, since the XML message is prewritten and entered in the XML Content field, if there is an error in the input XML message, the error notification will not provide you with an option to correct it before retrying the process.

Before testing the invocation, for easier debugging or troubleshooting purposes throughout the test, you can enable the diagnostics and logging feature to directly display on-screen logs in the test page. For instructions on how to turn on this logging feature, see Troubleshooting Invocation Failures on OACORE OC4J.

To test an event invocation:

  1. Log on to Oracle E-Business Suite with the Workflow Administrator Web responsibility and select the Business Events link.

  2. Search on a business event that you want to run the test, such as oracle.apps.wf.xmlgateway.invoke and click Go.

  3. Select the business event that you want to raise from the result table and click the Test icon to open the Test Business Event page.

  4. Enter a unique event key in the Event Key field and leave the Sand Date field blank.

  5. Enter appropriate parameters in the Enter Parameters region.

  6. In the Event Data region, enter the following information:

    • Upload Option: Write XML

    • XML Content: Enter appropriate XML information as input message. For example, you can enter:

      <ReceiveDocument xmlns="http://xmlns.oracle.com/xdb/SYSTEM">
   <PO_DOCUMENT>
   <PO_NUM>12345</PO_NUM>
   <PO_TYPE>standards</PO_TYPE>
          </DESCRIPTION>
   </PO_DOCUMENT>
</ReceiveDocument>

    Test Business Event Page

    the picture is described in the document text

  7. Click Raise in Java to raise an event from OACORE OC4J.

    If the web service is successfully invoked, the Test Business Event page reloads and displays the XML Response region right after the XML Content field.

    Test Business Event Page: Event Response Region

    the picture is described in the document text

  8. Click Raise in PLSQL to raise an event is from the concurrent manager tier.

For more information about testing business events, see To Raise a Test Event, Oracle Workflow Developer's Guide.

Using Command Lines

You can also use the command line API based test method to raise both PL/SQL-based or Java-based events.

Troubleshooting Web Service Invocation Failure

Web services can be invoked from any one of following tiers:

In most cases, the web service resides outside the firewall and the executing host does not have direct access to the WSDL or the web service endpoint to send the SOAP request. Without properly setting up and configuring the proxy parameters for each tier that web service invocations occur, WSDL files will not be parsed and consumed during subscription or web services will not be successfully invoked.

For information on setting up proxy host and port appropriately at each layer, see Setup Tasks, Oracle E-Business Suite Integrated SOA Gateway Implementation Guide.

At runtime, if a web service invocation fails, an exception is thrown and the invoker event is enqueued to the WF_ERROR queue. Since the web service can be invoked from any one of the layers described earlier, how to troubleshoot and resolve the failure invocation can be explained as follows based on the layer that web service invocations occur:

Troubleshooting Invocation Failure on OACORE OC4J

For the purposes of easier debugging or troubleshooting throughout a test run of the web service invocation from within an OA Framework page, on-screen logging mechanism should be used.

Enabling On-screen Logging

You can enable the on-screen logging feature and have the logs directly displayed at the bottom of the Test Business Event page. These logs provide processing details while executing the code to invoke the web service.

If there is a fault or a runtime exception in processing the event and invoking the service, the on-screen logging quickly discloses what is happening.

Enabling on-screen logging involves the following two steps:

  1. Setting FND: Diagnostics Profile Option

  2. Displaying On-screen Logging

Setting FND: Diagnostics Profile Option

Before using the Test Business Event page, first set the FND: Diagnostics profile option to 'Yes' at an appropriate level to enable the Diagnostics link on the global menu of the HTML-based application pages.

Note: Through the Diagnostics link, we can enable database trace, profiling, and on-screen logging that will help troubleshooting the transactions performed from the HTML-based application pages.

System Profile Values Page to Set the "FND: Diagnostics" Profile Option

the picture is described in the document text

With the diagnostics feature, the on-screen logging can be enabled which helps us track the WebServiceInvokeSubscription's log messages when an invoker event is raised from the Test Business Event page and subsequently the web service is invoked.

Displaying On-screen Logging

After setting the "FND: Diagnostics" profile option to 'Yes', you should find the Diagnostics link available in the upper right corner of your HTML page.

By selecting the Diagnostics link and entering appropriate information, the on-screen logging feature can be enabled. Once you locate a desired event and test its invocation, relevant log messages directly appear at the bottom of your test page for an easier debugging or troubleshooting if needed.

Important: If the "FND: Diagnostics" profile option is not set to 'Yes', then the Diagnostics link will not be visible as a global menu for selection. See: Setting FND: Diagnostics Profile Option.

To display on-screen logs while testing your service invocation in the Test Business Event page:

  1. Log on to Oracle Workflow with appropriate responsibility, and select the Business Events link to locate an invoker business event hat you want to run the test, such as oracle.apps.wf.xmlgateway.invoke and click Go to perform a search.

  2. From the search result table, select the business event that you want to raise and click the Test icon to open the Test Business Event page.

  3. Click the Diagnostics link in the upper right corner of the page.

  4. Enter the following information to enable the on-screen logs:

    • Diagnostics: Show Log on Screen

    • Log Level: Statement (1)

    • Module: %

  5. Click Go. The on-screen logging is now enabled.

    Oracle Diagnostics Page

    the picture is described in the document text

  6. Navigate to the Test Business Event page and raise an event to execute the invocation testing.

Review On-Screen Log Messages

After you have enabled the on-screen logging feature, during the testing, you should find relevant log messages displayed at the bottom of the Test Business Event page. This provides the detailed information of all processing by the code that invokes the web service.

For example, you can review WebServiceInvokerSupscription log messages displayed on the same page to verify the service execution status, exception or fault if there is any, and whether the callback succeeded or not.

The following example log indicates that the service execution is completed with callback response message enqueued to the WF_WS_JMS_IN inbound queue if the 'WFBES_CALLBACK_EVENT' parameter value is set to receive event and the 'WFBES_CALLBACK_AGENT' parameter value is set to 'WF_WS_JMS_IN':

WebServiceInvokerSubscription Logs

the picture is described in the document text

For detailed information on how to enable the logging feature, see Enabling On-Screen Logging.

Troubleshooting Invocation Failure on Concurrent Manager (CM) Tier JVM

To troubleshoot web service invocation failure on Concurrent Manager (CM) Tier JVM, you must ensure that the Error subscription is created for the all web service invoker events to capture complete exception details when invocation happens from Workflow Java Deferred Agent Listener.

Error Subscription

For all web service invoker events, error subscription is required to enable error processing in the Business Event System that is used to communicate with the SYSADMIN user of an error condition in subscription execution. It sends a workflow notification to the SYSADMIN user with web service definition, error details, and event details allowing the SYSADMIN user to process the errors if needed.

For example, if an error occurs during the invocation and the event is enqueued to the WF_JAVA_ERROR queue, with an Error subscription defined to launch Error workflow process WFERROR:DEFAULT_EVENT_ERROR2, the Workflow Java Error Agent Listener executes the error subscription which sends a notification to the SYSADMIN user with web service definition, error details and event details.

For more information, see Managing Errors.

Enabling Workflow Java Deferred Agent Listener Logging

Since Oracle Workflow default event error handler provides options for the SYSADMIN user to retry the web service invocation process after verifying that the reported error has been corrected, the SYSADMIN user can invoke the web service again from the notification if necessary. However, if further analysis of the steps leading to the exception is required, use Workflow Java Deferred Agent Listener logging mechanism to set the STATEMENT level log for Workflow Java Deferred Agent Listener and retry the failed web service invocation to obtain detailed steps leading to the exception.

For more information, see Java Agent Listeners, Oracle Workflow Administrator's Guide.

Troubleshooting Invocation Failure on Standalone JVM

When invoking a web service from a Java process that runs outside OACORE or CM by calling the BusinessEvent.raise method to raise the invoker event with a synchronous 'Invoke Web Service' subscription, the following situation can occur:

Extending Seeded Java Rule Function

Oracle E-Business Suite Integrated SOA Gateway allows developers to extend the invoker subscription seeded rule function oracle.apps.fnd.wf.bes.WebServiceInvokerSubscription using Java coding standards for more specialized processing.

Developers can extend the seeded rule function to override following methods:

For detailed information about these methods, see Oracle Workflow API Reference.

preInvokeService

This method is used for pre processing before Web service invocations.

     protected String preInvokeService(Subscription eo, 
                                       BusinessEvent event,
                                       WorkflowContext context) 
throws BusinessEventException;

The Web service input message or request message is available by calling event.getData(). This is the business event payload passed when raising the invoker event or generated by business event Generate function.

This method can perform additional processing on the request data if required. The default implementation through the seeded Java rule function performs XSL transformation using the XSL file specified in WFBES_IN_XSL_FILENAME if input payload message is available.

postInvokeService

     protected void postInvokeService(Subscription eo, 
                                      BusinessEvent event,
                                      WorkflowContext context, 
                                      String requestData, 
                                      String responseData) 
throws BusinessEventException;

If the operation is synchronous request - response, the response is available in parameter responseData.

This method performs additional processing on the response and update application state if required. The default implementation through seeded Java rule function performs the following tasks:

invokeService

     protected String invokeService(String wsdlLocation, 
                                    String serviceName, 
                                    String invokePort, 
                                    String portTypeName, 
                                    String operationName, 
                                   String eventData)
throws Exception;

This invokeService method provides the implementation that makes use of Web service invocation metadata and invokes the Web service using WSIF APIs. This method can be overridden if a different implementation is required other than WSIF to invoke Web services.

addWSSecurityHeader

protected void addWSSecurityHeader(ArrayList headersList) throws Exception;

This method adds WS-Security compliant header to the SOAP request. The default implementation through Java seeded rule function adds UsernameToken element to the security header based on event parameters WFBES_SOAP_USERNAME, WFBES_SOAP_PASSWORD_MOD, and WFBES_SOAP_PASSWORD_KEY. This method can be overridden to add any WS-Security header or have custom logic to retrieve username and password to build UsernameToken element. The well-formed XML Element should be added to the ArrayList.

The following code snippet shows WS-Security added to a SOAP header:

  try {
                 DocumentBuilderFactory factory = DocumentBuilderFactory.newInstance();
                 factory.setNamespaceAware(true);
                 DocumentBuilder bldr = factory.newDocumentBuilder();
                 Document doc = bldr.newDocument();
        
                 Element sec = doc.createElement("wsse:Security");
                 Attr attr = doc.createAttribute("xmlns:wsse");
                 attr.setValue("http://docs.oasis-open.org/wss/2004/01/oasis-200401-wsswssecurity-secext-1.0.xsd");
                 sec.setAttributeNode(attr);
                 doc.appendChild(sec);
                     
                 Element unt = doc.createElement("wsse:UsernameToken");
                 sec.appendChild(unt); 
                 .... build XML message ....
               }      
               catch (Exception e) {
                }
        headersList.add(doc.getDocumentElement());

setInputParts

protected void setInputParts(WSIFMessage inputMessage,Input input,String eventData) throws Exception

This setInputParts method supports setting input part values such as header, body, or other parts, that are defined for the Web service operation's input message. The default implementation through Java seeded rule function adds the event data payload as the body of the input message. It also adds any other parts provided as event parameters in the triggering event.

The event parameters that contain input message parts must be identified by parameter names with the following format:

WFBES_INPUT_<partname>

This method can be overridden to set specific input parts that you require or to set values for RPC (remote procedure call) style Web service invocation.

Important: The service invocation framework supports invoking document-based Web service only. The RPC style Web service invocation is not naturally supported in this release unless you extend this method to set input part values for RPC style.

The following code snippet shows how this method is used to set values for document style Web service invocation:

protected void setInputParts(WSIFMessage inputMessage, Input input, String eventData)
throws Exception {
   BusinessEvent event = this.getBusinessEvent();
   String bindingStyle = this.getBindingStyle();
   if (bindingStyle.equalsIgnoreCase("document") {
      String headerPartMsg = event.getStringProperty("WFBES_INPUT_header");
      // header part
      inputMessage.setObjectPart("header", getDocumentElement(headerPartMsg));      
      // body part
      inputMessage.setObjectPart("body", getDocumentElement(eventData));
   else {
      // Web service style is RPC
      // Code can be added to set input parts for RPC style invocation
   }   
}

Sample Codes

The following code shows how to extend the seeded Java rule function:

package oracle.apps.fnd.wf.bes;

import java.io.ByteArrayInputStream;

import java.util.ArrayList;

import javax.xml.parsers.DocumentBuilder;
import javax.xml.parsers.DocumentBuilderFactory;

import oracle.apps.fnd.common.Log;
import oracle.apps.fnd.wf.bes.server.Subscription;
import oracle.apps.fnd.wf.common.WorkflowContext;

import org.apache.wsif.WSIFConstants;
import org.apache.wsif.WSIFMessage;
import org.apache.wsif.WSIFOperation;

import org.w3c.dom.Document;
import org.w3c.dom.Element;


public class MyWebServiceInvoker 
  extends WebServiceInvokerSubscription 
  implements SubscriptionInterface
{

  private static final String CLASS_PREFIX = 
  MyWebServiceInvoker.class.getName() + ".";
        
  public MyWebServiceInvoker() 
   {
   }
    
  final protected String invokeService( String wsdlLocation, 
                                                                                                                String serviceName, 
                                                                                                                String invokePort, 
                                                                                                                String portTypeName,
                                                                                                                String operationName, 
                                                                                                                String eventData) 
  throws Exception {
     super.preInvokeService(wsdlLocation, serviceName, invokePort,
                                                                                portTypeName, operationName, eventData);

 // Perform special pre invocation processing like updating application
 // state and so on.                
   }

 final protected void postInvokeService(Subscription eo, 
                                                                                                                BusinessEvent event,
                                                                                                                WorkflowContext context, 
                                                                                                                String requestData, 
                                                                                                                String responseData) 
  throws Exception {
    
   super.postInvokeService(eo, event, context, requestData, 
                                                                                responseData);
        
 // Perform special post invocation processing like updating application
 // state and so on.        
   }
    
  /**
            * Implementing addSOAPHeaders method to include custom header 
    * required to invoke an EBS Web Service.
    */
  final protected void addSOAPHeaders(WSIFOperation operation) 
  throws Exception {
   String METHOD_NAME = "addSOAPHeaders";
   mLog.write(CLASS_PREFIX + METHOD_NAME, "BEGIN", Log.PROCEDURE);
                   
   WSIFMessage hdrMsg = operation.getContext();
   ArrayList hdr = new ArrayList();
            
   // Call seeded implementation to add WS-Security header
      super.addWSSecurityHeader(hdr);
        
   // Add my own Custom header
   mLog.write(CLASS_PREFIX + METHOD_NAME, "Adding Custom header", 
   Log.STATEMENT);
   addMyCustomHeader(hdr);

   // Set the headers to WSIFOperation           
   hdrMsg.setObjectPart(WSIFConstants.CONTEXT_REQUEST_SOAP_HEADERS, 
                                                                        hdr);
   operation.setContext(hdrMsg);
        
   mLog.write(CLASS_PREFIX + METHOD_NAME, "END", Log.PROCEDURE);
    }
    
  final protected void addMyCustomHeader(ArrayList headersList) 
   throws Exception {
    String METHOD_NAME = "addMyCustomHeader";
    // Adding special Custom Header to the WSIF's SOAP request
    String custHdr = 
 "ns1:SOAHeader 
         xmlns:ns1=\"http://xmlns.oracle.com/xdb/SYSTEM\" " +
 "env:mustUnderstand=\"0\" 
         xmlns:env=\"http://schemas.xmlsoap.org/soap/envelope/\"> \n" + 
                 "      <ns1:MESSAGE_TYPE>XML</ns1:MESSAGE_TYPE>\n" + 
                 "      <ns1:MESSAGE_STANDARD>OAG</ns1:MESSAGE_STANDARD>\n" + 
                 "      <ns1:TRANSACTION_TYPE>PO</ns1:TRANSACTION_TYPE>\n" + 
                 "      <ns1:TRANSACTION_SUBTYPE>PROCESS</ns1:TRANSACTION_SUBTYPE>\n" + 
                 "      <ns1:DOCUMENT_NUMBER>xxx</ns1:DOCUMENT_NUMBER>\n" +
                 "      <ns1:PARTY_SITE_ID>xxxx</ns1:PARTY_SITE_ID>\n" +
                 " </ns1:SOAHeader>\n";
       
                 if (custHdr != null && !"".equals(custHdr)) {
            try {
                DocumentBuilderFactory factory =
                DocumentBuilderFactory.newInstance();
                factory.setNamespaceAware(true);
                DocumentBuilder bldr = factory.newDocumentBuilder();
                Document doc = bldr.newDocument();
                        
                doc = bldr.parse(new 
                ByteArrayInputStream(custHdr.getBytes()));
                
                // Add the element to the Headers list
                headersList.add((Element)doc.getFirstChild());
            }
            catch (Exception e) {
                throw new BusinessEventException(
                                          "Exception when creating header element - "+e.getMessage());
            }
        }
        mLog.write(CLASS_PREFIX + METHOD_NAME, "END", Log.PROCEDURE);
    }

}

Other Invocation Usage Considerations

While implementing the service invocation framework to invoke Web services, some limitations need to be considered.

For detailed information about implementation consideration on service invocation framework, see Implementation Limitation and Consideration, Oracle E-Business Suite Integrated SOA Gateway Implementation Guide.