Using Service Invocation Framework to Invoke SOAP Services

SOAP Service Invocation Framework Overview

Oracle E-Business Suite Integrated SOA Gateway leverages Oracle Workflow Java Business Event System to provide infrastructure for SOAP and REST 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 events or services between systems, and implementing workflow process definitions at runtime as well as handling errors.

Since Oracle Workflow provides a total solution of managing and streamlining complex business processes and supporting highly-integrated workflow in Oracle E-Business Suite, Oracle E-Business Suite Integrated SOA Gateway relies on Oracle Workflow to enable the service invocation process. The following diagram illustrates the high level service invocation process flow:

the picture is described in the document text

In this diagram, when a tax calculation triggering event is raised from Oracle E-Business Suite through Oracle Workflow, the service that subscribes to this triggering event will be invoked to interact with an external tax system. If required, the external system will send a response message to acknowledge this request.

To be able to invoke external SOAP services from Oracle E-Business Suite, this invocation framework uses a wizard-based user interface in Oracle Workflow Business Event System to parse a given WSDL URL during the subscription creation and store the parsed service information or metadata as subscription parameters which will be used later at runtime during the actual service invocation.

Note: 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.

In summary, the SOAP service invocation framework provides the following functionality:

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

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

Note: All outbound service invocation messages from Oracle E-Business Suite through service invocation framework are monitored using Service Invocation Monitor. See: Monitoring and Managing Outbound Service Invocation Messages Using Service Invocation Monitor, Oracle E-Business Suite Integrated SOA Gateway Implementation Guide.

Understanding SOAP Service Message Patterns

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 SOAP 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, a client's zip code location sends updated weather data to the service when the local conditions change using the request only operation. The server updates the data but no response is sent back.

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

To support synchronous request - response service operation, if a web service has an output or a response message, the SOAP 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 a web service operation where a client asks a service provider a question and then waits for a response before continuing on. For more information about this operation pattern, see Understand SOAP Service 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 a "Raise" event activity and waits for a web service response using a "Receive" event activity, the invoker event key should be the 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 event and agent, the SOAP service invocation can be integrated back with a waiting workflow process or any other module within Oracle E-Business Suite. A SOAP service invocation uses the following callback subscription or event parameters:

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 subscription parameters. For instance, 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 An Example of Invoking a SOAP Service from a Workflow Process

Supporting SOAP Service Security

The SOAP service invocation framework supports WS-Security through UsernameToken based security.

This security mechanism authenticates the user invoking a SOAP service by passing a user name and an optional password in the SOAP Header of a SOAP request sent to the web service provider.

When creating the event subscription for the SOAP service to be invoked, the developer needs to specify the user name and password information through the design-time event subscription user interface.

Note that the SOAP service security is also handled based on the customization level. The customization level is used to protect Oracle E-Business Suite seed data and to preserve your customizations in an upgrade. If the Invoke Web Service event subscription's customization level is Core or Limit, and if the user name is supplied by the subscription owner, it cannot be updated. If the user name is not already supplied, you can update the user name if it's required. The Password field can always be updated regardless of the customization level if it is required.

For more information about UsernameToken based security and customization level usage, see Understanding and Configuring WS-Security for the SOAP Service Invocation Framework, Oracle E-Business Suite Integrated SOA Gateway Implementation Guide.

Understanding SOAP 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://<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, 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:

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.

Message Transformation Parameters to Support XSL Transformation

If the invoker event's XML payload (to be used as a 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 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, 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 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 
<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 an event payload, the SOAP 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 user name, 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>xxx<DOCUMENT_NUMBER>\n" +
                                                                        " <PARTY_SITE_ID>xxxx<PARTY_SITE_ID>\n" +
                                                                        "<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 interface oracle.apps.fnd.wf.bes.InvokerConstants for use in Java code.

If the SOAP 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);

Understanding SOAP Service Invocation Metadata

To invoke a SOAP service through Business Event System, you must create a subscription to the event that triggers the invocation. Before creating an event subscription with all the data required for the invocation, you should first understand the concepts of invocation parameters and metadata and how they work behind the scene to invoke a SOAP service.

This section describes the required parameters that you need to provide during the event subscription creation through the following topics:

Invoke Web Service Wizard

To subscribe to a SOAP service 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 SOAP service.

With the "Invoke Web Service" action type, the Create Event Subscription - Invoke Web Service wizard appears where you need to provide a WSDL URL representing the SOAP service to be invoked. The SOAP service can be of any type, such as a native service or BPEL process.

Note: A BPEL process itself is a 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 Oracle SOA Suite to connect to services.

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

Create Event Subscription - Invoke Web Service Wizard

the picture is described in the document text

The entered WSDL information will be parsed into service metadata for your further selections later in the wizard. The service metadata you selected along with the WSDL URL will be stored as the following subscription parameters and displayed in the Web Service Details region:

Note: The SOAP address derived from the SERVICE_WSDL_URL parameter captured here during the event subscription can be overridden by an event parameter called SERVICE_SOAP_ADDRESS if passed at runtime during service invocation.

The seeded Java Rule Function for SOAP services 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 SOAP Service Seeded Rule Function.

SOAP Service Security

Configuring Web Service Security for SOAP Services

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

Important: This UsernameToken based WS-security header is implemented during the service invocation only if the web service provider that processes the web service request needs this security header.

After entering needed information in the Create Event Subscription - Invoke Web Service wizard, the Web Service Security region is displayed letting you specify or update the user name and password if appropriate. The information will then be stored in Vault securely.

Oracle Workflow allows various levels of updates on business event and subscription based on the customization level. If the Invoke Web Service event subscription's customization level is Core or Limit, and if the user name is supplied by the subscription owner, it cannot be updated. If the user name is not already supplied, you can update the user name if required. The Password field can always be updated regardless of the customization level if it is required.

For more information about UsernameToken based security and customization level usage, see Understanding and Configuring WS-Security for the SOAP Service Invocation Framework, Oracle E-Business Suite Integrated SOA Gateway Implementation Guide.

Additional Subscription Parameters

Setting Additional Subscription Parameters

Apart from the subscription parameters that have been parsed and stored through the Invoke Web Service Subscription page, the following information could 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 the service invocation:

Managing SOAP Service Invocation Errors

The SOAP service invocation framework uses the same way of handling errors in the Business Event System to manage errors if occur during the implementation of business event subscriptions. If the service invocation returns a fault message, the event is enqueued to an error queue to trigger error processing. If an exception occurred during the 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, the SOAP 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 processes an event subscription to invoke a 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 processes the error subscription which sends a notification to SYSADMIN with the web service definition, error details, and event details. Since Oracle Workflow default event error handler provides options for SYSADMIN to retry the service invocation process after verifying that the reported error has been corrected, SYSADMIN can invoke the service again from the notification if necessary.

However, if there is a runtime exception when invoking the service by raising the Invoker event with synchronous subscription (phase less than 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:

To access the Create Event Subscription page, log in to Oracle E-Business Suite as a user who has the Workflow Administrator Web Applications responsibility. Select Business Events from the navigation menu and choose the Subscriptions subtab. In the Event Subscriptions page, click Create Subscription.

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

Defining SOAP Service Invocation Metadata

Because the service invocation is taken place in the Oracle Workflow Business Event System, before invoking a SOAP service, the 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 SOAP Service Invoker Business Event

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

  2. Creating a Local Subscription to the SOAP Service Invoker Event

    This event subscription indicates that when a triggering event occurs, the action item of this subscription is to invoke a SOAP service defined as part of this subscription.

  3. Creating an Error Subscription to Enable Error Processing for the SOAP Service

    This error subscription enables error processing in the Business Event System that is used to communicate with the SYSADMIN user of an error condition in subscription processing.

  4. Creating a Receive Event for SOAP Response (Optional)

    This step is required only if a SOAP service has an output or a response message to communicate or call back to Oracle E-Business Suite.

    If a SOAP service does not require a response, then you do not need to create a receive event.

  5. Creating a Receive Event Subscription for SOAP Response (Optional)

    Once a receive event is in place, you must create an External subscription to the receive event to pass the SOAP service response message.

Step 1: Creating a SOAP 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 SOAP service invoker business event.

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

To invoke a SOAP service through the Business Event System, you must create an invoker business event, and then subscribe to the SOAP service invoker event later with an appropriate action type.

Note: In this release, the SOAP 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 in to Oracle E-Business Suite as a user who has 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.xxx.user.webservice.invoke

    • Display Name: Enter an event display name, such as oracle.apps.xxx.user.webservice.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')

  4. Click Apply to save your work.

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

Step 2: Creating a Local Subscription to the SOAP Service Invoker Event

After creating a SOAP service invoker event in step 1, you need to create a local subscription to the invoker event with "Invoke Web Service" action type. When a triggering event occurs, the Business Event System processes the subscription through the seeded Java function and invokes the SOAP service as indicated by the action type.

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

  1. Log in to Oracle E-Business Suite as a user who has 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.xxx.user.webservice.invoke

    • Phase: 90

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

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

      • If the phase is greater than or equal to 100, then the event is enqueued to the WF_JAVA_DEFFERED queue and will be dispatched later.

      • If the phase is less than 100, then the event is dispatched immediately to the Java Business Event System soon after a 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.

    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. Click Next to display all ports for a selected service

    3. Select an appropriate service port and click Next to display all operations for a selected port.

    4. Select an appropriate service operation and click Next. This opens the last page of the Create Event Subscription - Invoke Web Service wizard.

    5. All the selected service metadata information is automatically displayed in the Web Service Details region.

    6. In the Web Service Security region, enter information in the Username and Password fields if appropriate.

    7. In the Web Service Invoker region, the default Java Rule Function for SOAP services 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.

    8. In the Documentation region, enter an application name or a program name that owns the subscription (such as 'Oracle Workflow') in the Owner Name field. Enter 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.

Step 3: Creating an Error Event Subscriptions to Enable Error Processing for the SOAP Service

To enable the error processing feature during the service invocation, you must create an Error subscription with "Launch Workflow" action type to the SOAP invoker event.

Once subscribing to this error processing, if any errors occurred during the invocation, the error process sends a workflow notification to the SYSADMIN user. This notification includes the SOAP service definition, event details, and error details allowing the SYSADMIN user to easily identify the error. The notification also provides an option for the SYSADMIN user to respond to the error. The SYSADMIN user can invoke the SOAP 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 SOAP Service Invocation Errors.

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

  1. Log in to Oracle E-Business Suite as a user who has 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.xxx.user.webservice.invoke

    • Phase: This can be any phase number.

    • Status: Enabled

      Note: While updating an event and an event subscription, for seeded events with a customization level of Limit, you can only update the status. For seeded product-specific events with a customization level of Core, you cannot update any properties. You can only view the subscription definition.

      For information on how to use customization level, see Configuring Security Password with Customization Level, Oracle E-Business Suite Integrated SOA Gateway Implementation Guide.

    • Rule Data: Key

    • Action Type: Launch Workflow

    • On Error: Stop and Rollback

  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 a 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.

  7. Click Apply.

Step 4: Creating a Receive Event for SOAP Response (Optional)

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

For Synchronous Request-Response Service Invocation

For Request-only Web Service

If it is a request-only SOAP 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.xxx.user.webservice.receive

    • Display Name: Enter an event display name, such as oracle.apps.xxx.user.webservice.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')

  3. Click Apply to create a receive event.

Step 5: Creating a Receive Subscription for SOAP Response (Optional)

If you create a receive event as described in step 4, you must create an external event subscription to the receive event. The SOAP service response message communicated through the receive event is always enqueued to an inbound workflow agent. In order to process an event from the inbound workflow agent, an external subscription is required.

To create a receive event subscription:

  1. Log in to Oracle E-Business Suite as a user who has 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.xxx.user.webservice.receive

    • Phase: any phase number

    • Status: Enabled

    • Rule Data: Key

    • Action Type: any action type

    • On Error: Stop and Rollback

  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 any other action type is selected, then a different type of the create event subscription page is displayed. By entering an appropriate action type through the subscription page, you can launch a workflow process or invoke 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 a workflow type that is waiting for the response

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

    • Priority: Normal

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

  7. Click Apply.

Invoking SOAP 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 a PL/SQL or Java layer.

Service Invocation from PL/SQL

  1. An 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 the 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 the SOAP service Java Rule Function oracle.apps.fnd.wf.bes.WebServiceInvokerSubscription.

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

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

Service Invocation from Java

  1. A Java application raises a business event using Java method oracle.apps.fnd.wf.bes.BusinessEvent.raise either from an OA Framework page controller/AMImpl or Java code running on the 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 processed inline or deferred is determined by the phase of the subscription.

    • If the invoker subscription is created with the Phase value greater than or equal to 100, the event is enqueued to the WF_JAVA_DEFERRED queue.

    • If the invoker subscription is created with the Phase value less than 100, the event is dispatched inline.

      If the event is raised from an OA Framework page, the dispatch logic runs within OACORE WebLogic Server.

    Note: If the SOAP service invoker event is raised from Java on the application tier, and the invoker subscription is synchronous with the subscription phase value less than 100, then the SOAP service is invoked as soon as the event is raised. If the invocation is successful, the response can be read by the calling application and is available immediately by using method BusinessEvent.getResponseData().

    oracle.apps.fnd.wf.bes.BusinessEvent.raise throws oracle.apps.fnd.wf.bes.BusinessEventException if there are any issues while invoking a SOAP service inline. BusinessEventException object internally stores the underlying root cause exception within a linkedException object. In order to see the complete exception details, print the exception stack trace from BusinessEventException.getLinkedException();.

    If the event is raised from Java with the subscription phase value greater than or equal to 100 or if the event is raised from PL/SQL, the event message will be enqueued to the WF_JAVA_DEFERRED queue. If the SOAP service has an output or a response message, a 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 a SOAP 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 =
"<IntegrationRepositoryService_GetInterfaceFunctionByName
xmlns:=\"http://xmlns.oracle.com/apps/fnd/rep/ws\"> \n"+
<fullMethodName>SERVICEBEAN:/oracle/apps/fnd/rep/ws/IntegrationRepos
itoryService:getInterfaceFunctionByNameSERVICEBEAN:/oracle/apps/fnd/
rep/ws/IntegrationRepositoryService:getInterfaceFunctionByName</fullMethodName>\n"+
<IntegrationRepositoryService_GetInterfaceFunctionByName>";
                                        event.setData(input);

                        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" +
                        " <PARTY_SITE_ID>xxx<PARTY_SITE_ID>\n" +
                        " <DOCUMENT_NUMBER>xxxx<DOCUMENT_NUMBER>\n" +
                        " <SOAHeader>\n"
businessEvent.setStringProperty("WFBES_INPUT_header",
headerPartMsg);
                        event.raise(conn);
        conn.commit();
        
                        Object resp = event.getResponseData();
        if (resp != null) {
                                                String respStr = resp.toString();   
                                        // Process web service response here
                }
                else {
                                                // Either web service invocation failed and no exception was thrown
                // or the web service is one-way or asynchronous and did not return
                                                // a valid response 
                 System.out.println("No response received");
                }
        }
  catch (BusinessEventException e) {
    // Use appropriate logging mechanism as per your coding standards
    // instead of System.out.println
                        System.out.println("Exception occured " + e.getLinkedException().getMessage());
    // Print the complete exception stack to log file for troubleshooting
          // Most importantly, if an exception occured, do not proceed to process the
          // response
e.getLinkedException().printStackTrace();
  }
        catch (Exception e) {
    // Use appropriate logging mechanism as per your coding standards
    // instead of System.out.println
    System.out.println("Exception occured " + e.getMessage());
    // Print the complete exception stack to log file for troubleshooting
          // Most importantly, if an exception occured, do not proceed to process the
          // response
 e.printStackTrace();
  }
 }

Important: When invoking a SOAP service using the SOAP service invocation framework, the invoker business event is raised using the oracle.apps.fnd.wf.bes.BusinessEvent.raise(Connection) method that requires a JDBC connection to be passed.

To get the JDBC connection, always use the current application context object available for your scenario. For example, if a service invocation is from an OA Framework page, then get the JDBC connection from the OAPageContext object. If it is from a concurrent program, get the JDBC connection from the CpContext object. You should not create a WorkflowContext in these situations. Otherwise, a duplicate application context will be unnecessarily created. A new WorkflowContext should be created only if JDBC connection is not already available through other means.

Testing SOAP Service Invocation

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

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

Using the Test Business Event Page

Use the Test Business Event page to test an event by raising it from PL/SQL API or Java.

Testing Service Invocations

After logging in to Oracle E-Business Suite as a user who has the Workflow Administrator Web responsibility, select Business Events from the navigation menu. 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 a 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 the XML response message if appropriate.

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 the data that you have entered.

Following parameters may be specified when raising the event from the Test Business Event page to invoke a SOAP 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, enter the following parameters and values:

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.

To test an event invocation:

  1. Log in to Oracle E-Business Suite as a user who has the Workflow Administrator Web responsibility and select Business Events.

  2. Search on a business event that you want to run the test, such as oracle.apps.xxx.user.webservice.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 an input message. For example, you can enter:

      <Process xmlns="http://xmlns.oracle.com/MyFirstSOAComposite_jws/UseMovieService/InvokeMovie">
   <zipCode>32822</<zipCode>
   <radius>5</radius>
</Process>

  7. Click Raise in Java to raise an event from the OACORE WebLogic server.

    If the SOAP service is successfully invoked, a confirmation message appears on top of the Test Business Event page indicating that the event (oracle.apps.xxx.user.webservice.invoke) has been successfully raised.

    This test page reloads and displays the XML Response region right after the XML Content field.

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

  9. If errors occur, the Event Error Details region appears letting you view the error details.

Viewing Error Details in the Test Business Event Page

If any errors occur while testing the service invocation, an error message appears indicating that errors occurred while dispatching the event and detailed information is shown in the Event Error Details region.

The Event Error Details region lets you quickly view error information through the same page for easier debugging.

Optionally, to see detailed log messages that capture each occurrence in sequential order for service invocation, before testing the invocation, 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 SOAP Service Invocation Failures on OACORE WebLogic Server.

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 PL/SQL or Java based events.

An Example of Invoking a SOAP Service from a Workflow Process

The following example is to invoke a SOAP 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 SOAP 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 events and subscriptions in place:

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

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

    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 it is for the 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 a successful web service invocation.

    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 in to Oracle E-Business Suite as a user who has the Oracle Workflow Web Administrator responsibility.

  2. From the navigation menu, select Oracle Applications Manager > Workflow Manager.

  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.

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.

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

Troubleshooting SOAP Service Invocation Failure

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

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

For information on how to set up proxy host and port appropriately at each layer, see detailed information described in the Setup Tasks, Oracle E-Business Suite Integrated SOA Gateway Implementation Guide.

At runtime, if a SOAP service invocation fails, an exception is thrown and the invoker event is enqueued to the WF_ERROR queue. Since the service can be invoked from any of the three tiers, this section provides the troubleshooting information to help you resolve the failure invocation based on the tier that service invocation could occur:

Troubleshooting SOAP Service Invocation Failure on OACORE WebLogic Server

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 running 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 Form for Setting 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, you enable the on-screen logging feature. 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 in to Oracle E-Business Suite as a user who has the Workflow Administrator Web responsibility. Select the Business Events link to locate an invoker business event hat you want to run the test, such as oracle.apps.xxx.user.webservice.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.

  6. Navigate to the Test Business Event page and raise an event to run 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 invocation status, exception or fault if there is any, and whether the callback succeeded or not.

The following example log indicates that the service invocation 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 SOAP Service Invocation Failure on Concurrent Manager (CM) Tier JVM

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

Error Subscription

For all SOAP 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 processing. It sends a workflow notification to SYSADMIN with the SOAP 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 processes the error subscription which sends a notification to SYSADMIN with the SOAP service definition, error details, and event details.

For more information, see Managing SOAP Service Errors.

Enabling Logging for Workflow Java Deferred Agent Listener

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

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

Enabling Logging for Java Concurrent Program

To enable logging for the SOAP service invocation framework when used from within a Java Concurrent Program to invoke SOAP services, set the following profile option values for the right application context based on how JDBC connection is obtained to raise the business event:

Oracle strongly recommends that you get the JDBC connection directly from the concurrent program context itself as listed below, then use the application context (User and Responsibility) under which the Java Concurrent Program request was submitted. Using the JDBC connection from the concurrent program context helps to group all logs for that concurrent program request and the service invocation framework invocation under that Request ID. After the concurrent program completes the processing, use the Request ID to search for all the log messages for the component 'Concurrent Program'.

Connection conn = cpContext.getJDBCConnection();       
event.raise(conn)

However, if you use an unrecommended approach by creating a separate WorkflowContext to get the JDBC connection from it, as listed below:

WorkflowContext wfCtx = new WorkflowContext();  
Connection conn = wfCtx.getJDBCConnection();      
event.raise(conn)

Use the following context to set the logging profile options:

Although the Java Concurrent Program would be processed under the application context under which the request was submitted, creating a new WorkflowContext within the program results in setting a hard-coded application context of SYSADMIN and SYSTEM_ADMINISTRATOR for its JDBC connection. Hence, this approach is not recommended. A new WorkflowContext should be created only if the JDBC connection is not already available through other means.

Since there are two separate application contexts, one created for concurrent program context and a new one for WorkflowContext, the logs for the concurrent program request and the invocation through the SOAP service invocation framework are stored under the two different contexts.

After the concurrent program processing completes, retrieve the logs for modules fnd.wf.bes% and fnd.sif% which will give logs only for the invocation through the framework. Also, you could retrieve the logs for the rest of the concurrent program processing using the Request ID.

To retrieve logs, log on to Oracle E-Business Suite as a user who has the System Administrator responsibility. Select Oracle Applications Manager > Logs from the Navigator to search your logs.

Troubleshooting SOAP Service Invocation Failure on Standalone JVM

When invoking a 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 for SOAP Services

Oracle E-Business Suite Integrated SOA Gateway allows developers to extend the seeded rule function oracle.apps.fnd.wf.bes.WebServiceInvokerSubscription for SOAP services 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.

Use the following steps to extend the seeded rule function:

  1. Extend the methods using oracle.apps.fnd.wf.bes.WebServiceInvokerSubscription.

  2. Upload the compiled custom class file at $JAVA_TOP/oracle/apps/fnd/wf/bes/.

  3. Bounce the oacore and oafm servers.

  4. Use the custom rule function oracle.apps.fnd.wf.bes.xxxx while creating the subscription.

    Note that xxxx is the name of extended custom class. For example, oracle.apps.fnd.wf.bes.CustomWebServiceInvoker.

preInvokeService

This method is used for preprocessing before invoking a SOAP service.

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

The 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 the business event Generate function.

This method can perform an 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 the input payload message is available.

postInvokeService

This method performs the post-processing after invoking a SOAP service.

     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 an additional processing on the response and updates application state if required. The default implementation through the seeded Java rule function performs the following tasks:

addWSSecurityHeader

protected void addWSSecurityHeader(ArrayList headersList) throws Exception;

This method adds WS-Security compliant header to the SOAP request. The default implementation through the Java seeded rule function adds the UsernameToken element to the security header based on the event parameters WFBES_SOAP_USERNAME, WFBES_SOAP_PASSWORD_MOD, and WFBES_SOAP_PASSWORD_KEY, and sets the expiration time for the header in the Timestamp element based on the WFBES_SOAP_EXPIRY_DURATION parameter.

This method can be overridden to add any WS-Security header or have custom logic to retrieve user name and password to build the 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(String[] partNames, Hashtable<String,Element> partValues) throws Exception;

Note: The method, setInputParts(WSIFMessage, Input, String) throws Exception;, used in earlier releases is not supported in this release. Any subclass of WebServiceInvokerSubscription that implements this method should be modified to use the new method as explained here. Developers are required only to create the org.w3c.dom.Element objects for input part values and set it to the Collections object.

This setInputParts method can be optionally implemented in a subclass of WebServiceInvokerSubscription to set values for all input parts for the operation. The subclass then is used as the Java Rule Function for the "Invoke Web Service" event subscription.

This method gives the list of input part names for the operation that is invoked by that specific invocation instance as an array of java.lang.String in parameter partNames. Implementation of this method could set self-contained XML elements of type org.w3c.dom.Element to partValues java.util.Hashtable parameter for each part name as key.

You can use a mix of event parameters, event payload, and extension of the setInputParts method to pass input part values for a service invocation. For example, one or more of the following combinations are possible:

Input part values of type org.w3c.dom.Element for the SOAP service operation can be set in one of the following two ways:

The following code snippet shows how this method is used to set the values for Input parts 'header' and 'body' by creating Element objects out of hand-coded XML element string:

final protected void setInputParts(String[] partNames, Hashtable<String,Element>
partValues) throws Exception {
                String METHOD_NAME = CLASS_PREFIX+"setInputParts(String[], 
Hashtable<String,Element>";
                writeLog(METHOD_NAME, "BEGIN", Log.PROCEDURE);
                String value = "<SOAHeader xmlns:ns1=\"http://xmlns.oracle.com/apps/fnd/soaprovider/plsql/fnd_user_pkg/\>
                          <Responsibility>SYSTEM_ADMINISTRATOR<Responsibility>
                          <RespApplication>SYSADMINn<RespApplication>
                          <SecurityGroup><SecurityGroup> 
                          <NLSLanguage><NLSLanguage>
           <Org_Id><Org_Id>
<SOAHeader>";  
                                partValues.put("header", getDocumentElement(value));
                        value = "<InputParameters 
xmlns=\"http://xmlns.oracle.com/apps/fnd/soaprovider/plsql/fnd_user_pkg/testusername/\"><X_USER_NAME>SYSADMIN</X_USER_NAME></InputParameters>";
                                partValues.put("body", getDocumentElement(value));
                value = "<GetTheatersAndMovies 
xmlns=\"http://www.example.com/whatsshowing\"><zipCode>32822</zipCode><radius>10</radius></GetTheatersAndMovies>";
                                partValues.put("parameters", getDocumentElement(value));
                writeLog(METHOD_NAME, "END", Log.PROCEDURE);
                        }
        
            /**
             * This function is called to convert String to XML Element
             * @param data
             * @return
             * @throws Exception
             */
        
            public Element getDocumentElement(String data) 
            throws Exception {
                String METHOD_NAME = "getDocumentElement(String)";
                Element ret = null;
                writeLog(CLASS_PREFIX + METHOD_NAME, "BEGIN", Log.PROCEDURE);
                DOMParser parser = new DOMParser();
                parser.parse(new StringReader(data));
                Document doc = parser.getDocument();
                if(doc != null) {
                  ret = doc.getDocumentElement();
                          }
                writeLog(CLASS_PREFIX + METHOD_NAME, "END", Log.PROCEDURE);
                return ret;
            }

addCustomSOAPHeaders

protected void addCustomSOAPHeaders(ArrayList<Element> customHeaders) throws Exception;

Note: The method addSOAPHeaders used in earlier releases is not supported in this release. Any subclass of WebServiceInvokerSubscription that implements this method should be modified to use the addCustomSOAPHeaders method as explained here. Developers are required only to create org.w3c.dom.Element objects for your custom SOAP header and set it to the Collections object.

This addCustomSOAPHeaders method can be optionally implemented in a subclass of WebServiceInvokerSubscription to set custom SOAP headers for the SOAP request. The subclass then is used as the Java Rule Function for the "Invoke Web Service" event subscription.

Implementation of this method could set any number of self-contained XML elements of type org.w3c.dom.Element to customHeaders java.util.ArrayList parameter. All the XML elements will be added to the SOAP header.

This method helps to add a custom SOAP header to the SOAP request that is not defined in the input message for the WSDL operation that is invoked. For setting values to specific input parts as defined in WSDL operation's input message, use the setInputParts method.

The following code snippet shows how this method is used to set custom SOAP headers for a SOAP request:

final protected void addCustomSOAPHeaders(ArrayList customHeaders) 
throws Exception {
   String custHdr = mEvent.getStringProperty("XXX_CUSTOM_HEADER");
   try {
        DocumentBuilderFactory factory = DocumentBuilderFactory.newInstance();
                factory.setNamespaceAware(true);
                DocumentBuilder bldr = factory.newDocumentBuilder();
                Document doc = bldr.newDocument();
                doc = bldr.parse(new ByteArrayInputStream(custHdr.getBytes()));
                customHeaders.add((Element)doc.getFirstChild());
    }  
   catch (Exception e) {
                throw e;
         }
        }

Sample Codes

The following code shows how to extend the addCustomSOAPHeaders method to add any additional Header elements to a SOAP header that are not defined in WSDL:

final protected void addCustomSOAPHeaders(ArrayList customHeaders) 
            throws Exception {
                String METHOD_NAME = CLASS_PREFIX+"addCustomSOAPHeaders(ArrayList)";
                writeLog(CLASS_PREFIX + METHOD_NAME, "BEGIN", Log.PROCEDURE);
                           
                // Add my own Custom header
                writeLog(METHOD_NAME, "Adding Custom header", Log.STATEMENT);
                addMyCustomHeader(customHeaders);
                
                // Add more headers if required to the ArrayList
                System.out.println("Adding Custom Headers in the sub-class");
                writeLog(METHOD_NAME, "END", Log.PROCEDURE);
            }
                
            private void addMyCustomHeader(ArrayList headersList) 
            throws Exception {
            
                String METHOD_NAME = CLASS_PREFIX+"addMyCustomHeader(ArrayList)";
                
                writeLog(METHOD_NAME, "BEGIN", Log.PROCEDURE);
                
                // Adding special SOAP Header to the request. This is required only
                // if the WSDL's SOAP binding does not mandate the header but it is
                // still required by the service. The XML element should be self-sufficient
                // with all namespace declarations local to this element
                
                // In this case, the custom header is passed as an Event Parameter and 
                // set to the request to avoid hard-coding the header element in code.
                // Any element can be passed at the time of raising the invoker business event
                String custHdr = mEvent.getStringProperty("XXX_CUSTOM_HEADER");
                
                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());
                        writeLog(CLASS_PREFIX + METHOD_NAME, "Successfully added custom header 1", Log.STATEMENT);
                    }
                    catch (Exception e) {
                        throw new BusinessEventException("Exception when creating header element - "+e.getMessage());
                    }
                }
                
                String custHdr2 = mEvent.getStringProperty("XXX_CUSTOM_HEADER2");
                
                if (custHdr2 != null && !"".equals(custHdr2)) {
                    try {
                        DocumentBuilderFactory factory = DocumentBuilderFactory.newInstance();
                        factory.setNamespaceAware(true);
                        DocumentBuilder bldr = factory.newDocumentBuilder();
                        Document doc = bldr.newDocument();
                                
                        doc = bldr.parse(new ByteArrayInputStream(custHdr2.getBytes()));
                        
                        // Add the element to the Headers list
                        headersList.add((Element)doc.getFirstChild());
                        writeLog(CLASS_PREFIX + METHOD_NAME, "Successfully added custom header 2", Log.STATEMENT);
                    }
                    catch (Exception e) {
                        throw new BusinessEventException("Exception when creating header element - "+e.getMessage());
                    }
                }
                
                writeLog(METHOD_NAME, "END", Log.PROCEDURE);
            }

Other SOAP Service Invocation Usage Considerations

While implementing the framework to invoke SOAP services, some limitations need to be considered.

For more implementation consideration about the framework, see Implementation Limitation and Consideration for the SOAP Service Invocation Framework, Oracle E-Business Suite Integrated SOA Gateway Implementation Guide.