Implementing Service Invocation Framework

This section discusses the following topics:

Setup Tasks

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

Proxy Host and Port Setups

If a target Web service resides within the firewall and is directly accessible from an Oracle E-Business Suite server, administrators do not need to configure proxy host and port.

However, if a target Web service that is invoked resides outside the firewall and thus the request needs to be routed through the proxy, in this circumstance, administrators must set up and configure proxy host and port appropriately for the tiers that Web service invocations occur in order to perform the following activities:

Common Proxy Setup at WebLogic Server and Concurrent Manger Tier JVM

Use common setup information to configure proxy host and port. This information is applicable to the following conditions:

To configure proxy host and port for WebLogic server and CM tier JVMs, you need to update AutoConfig context file with the following entries and run AutoConfig:

<!-- proxy -->
		<proxyhost oa_var="s_proxyhost">myproxyhost</proxyhost>
   <proxyport oa_var="s_proxyport">80</proxyport>  
   <nonproxyhosts oa_var="s_nonproxyhosts">any domain that needs to be by-passed (such as *.us.oracle.com)</nonproxyhosts>

Proxy Host and Port Setup When Using Standalone Java Class

You must set the following entries:

java -Dhttp.proxyHost=myproxyhost -Dhttp.proxyPort=80 classname

Setup Tasks for Invoking SSL-based Web Services over HTTPS

Service Invocation Framework supports SSL-based Web service invocation using Server Authentication method. When a client connects to a Web server via HTTPS, the server sends back its server certificate to the client for verification. Once verified, the client sends the data, encrypted, to the server. Server Authentication allows the client to identify the server. Before invoking a Web service from a server over HTTPS (HTTP protocol over TLS/SSL), you need to perform manual setup tasks in order to read SSL-based WSDLs and invoke SSL service endpoints.

A client may receive one of the following two types of server certificates:

Perform the following two setup tasks for the Service Invocation Framework to invoke a SSL-based Web service:

Importing Server SSL Certificate into a SIF JVM's Certificate Store

Public Certificate Issued by a Certification Authority (CA)

If server certificate is a public certificate and is issued by a public CA such as VeriSign, then it is most likely available in a SIF JVM's certificate store or in a trusted certificate list.

Self-signed Certificate or Certificate is not in Trusted Certificate List

Perform the following tasks to import the server's SSL certificate into a SIF JVM's certificate store or add it to a trusted certificate list:

  1. Export the server certificate using either one of the following methods:

  2. Import the server's SSL certificate into an appropriate SIF JVM's certificate store to add it to the list of trusted certificates.

    Attention: Information about where Web services are invoked through the Service Invocation Framework is described in the Setup Tasks.

    There are many utilities available to import certificates. For example, you can use keytool, a key and certificate management utility that stores the keys and certificates in a keystore. This management utility is available by default with JDK to manage a keystore (database) of cryptographic keys, X.509 certificate chains, and trusted certificates.

    The keytool commands have the following syntax:

    keytool -import -trustcacerts -keystore <key store location> -storepass <certificate store password> -alias <alias name> -file <exported certificate file>

    For example:

    keytool -import -trustcacerts -keystore "$AF_JRE_TOP/jre/lib/security/cacerts" -storepass password -alias xabbott_bugdbcert -file my_cert.cer

    Note: This must be typed as a single line. The file (-file) is the exported certificate file i.e. my_cert.cer.

Setting Up SSL Proxy Host and Port

If a SSL-based Web service resides outside the firewall, the JVM that invokes the Web service has to communicate through SSL proxy. Following setup tasks are required in all appropriate tiers to use SSL proxy.

Setting Up Proxy Host and Port at WebLogic Server

For a Web service invoked from OA Framework, the JBES seeded Java rule function would run within the OACORE's WebLogic Server.

WebLogic Server start script (<EBSDomain>/bin/startWebLogic.sh) should have the following system properties setup in the JAVA_OPTIONS in order for it to work:

-Dhttps.proxyHost=myproxy.host.name

-Dhttps.proxyPort=80

-Dhttps.nonProxyHosts=*.mydomain.com|localhost

AutoConfig does not support properties https.proxyHost and https.proxyPort currently. To ensure the above properties are retained during the execution of AutoConfig, the context file could be customized to add these two properties.

For information on how to customize AutoConfig-managed configurations, see Using AutoConfig to Manage System Configurations in Oracle E-Business Suite Release 12, My Oracle Support Knowledge Document 387859.1 for details.

Setting Up Proxy Host and Port at Concurrent Manger Tier JVM

For a Web service invoked from PL/SQL and Java using an asynchronous subscription, the event is raised by the application code wherever it executes and then enqueued to the WF_JAVA_DEFERRED queue by the Event Manager. The event subscription is executed from the CM tier by the Java Deferred Agent Listener.

If a Web service is invoked by the Java Deferred Agent Listener, then the code would run within the CM tier Java service's JVM. Workflow Agent Listener Service does not currently support Service Parameters to set SSL proxy. The SSL proxy could be set up directly to Concurrent Manager's JVM system properties in $APPL_TOP/admin/adovars.env using AutoConfig.

<oa_environment type="adovars">
 <oa_env_file type="adovars" oa_var="s_adovars_file" osd="unix">
  $APPL_TOP/admin/adovars.env</oa_env_file>
...
 <APPSJREOPTS oa_var="s_appsjreopts">="-Dhttps.proxyHost=[proxyhost] 
  -Dhttps.proxyPort=[sslproxyport]</APPSJREOPTS>
...
</oa_environment>

Setting Up Proxy Host and Port When Using Standalone Java Class

You must set the following entries: 

java -Dhttps.proxyHost=[proxyhost] -Dhttps.proxyPort=[sslproxyport] 
<classname>

Implementing Service Invocation Framework

The invocation of Oracle E-Business Suite Web services using the Service Invocation Framework involves the following steps:

Defining Invocation Metadata and Invoking Web Services Through the Business Event System

Web service invocation metadata can be defined by using Oracle Workflow Business Event System to create events and event subscriptions. When a triggering event occurs, a Web service can be invoked through an appropriate event subscription.

Specifically, the invocation metadata can be defined through the following steps:

To create an event, log in to Oracle Workflow with the Workflow Administrator Web Applications responsibility and select the Business Event link and click Create.

To access the business event subscription page, log in to Oracle Workflow with the same Workflow Administrator Web Applications responsibility and select the Business Event link > Subscriptions. Click Create Subscription to access the event subscription page.

For detailed instructions on how to create business events and event subscriptions to invoke Web services, see the Oracle E-Business Suite Integrated SOA Gateway Developer's Guide.

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

As mentioned earlier, if a Web service has an output or a response message to communicate or callback to Oracle E-Business Suite, then a receive event and the local subscription to the receive event must be created first in the Business Event System.

To accomplish this synchronous request - response process, the Service Invocation Framework uses the callback mechanism to communicate the response back to Oracle E-Business Suite through the Business Event System. As a result, a new or waiting workflow process can be started or executed. The following callback subscription parameters are used to support the callback mechanism:

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 process Web service responses from inbound workflow agent, make sure that you have agent listener set up properly.

Detailed information about these callback subscription parameters, see the Oracle E-Busines Suite Integrated SOA Gateway Developer's Guide.

Managing Errors

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.

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 Error workflow process WFERROR:DEFAULT_EVENT_ERROR2, the Workflow Java Error Agent Listener executes the error subscription which sends a notification to a user (SYSADMIN) with Web service definition, error details and event details. The SYSADMIN user can correct the error and then invoke the Web service again from the notification if necessary.

For more information on error handling during Web service invocation, see the Oracle E-Busines Suite Integrated SOA Gateway Developer's Guide.

Testing Web Service Invocations

To validate whether Web services can be successfully invoked from concurrent manager and OACORE WebLogic Server, integration developers can run a test case through Oracle Workflow Test Business Event page. Use this test to check the basic operation of Business Event System by raising a test event from Java or from PL/SQL and executing synchronous and asynchronous subscriptions to that event.

By using 'Raise in Java' option to raise the Invoker event with synchronous subscription (phase <100), Web service invocation within OACORE WebLogic Server can be tested. If there is a runtime exception when invoking the Web service using synchronous subscription, the exception message is shown on the Test Business Event page.

The following event parameters may be specified when raising the event from the Test Business Event page to invoke a Web service:

Detailed information on how to test Web service invocations, see the Oracle E-Business Suite Integrated SOA Gateway Developer's Guide.

Extending Web Service Invocation

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 could extend the seeded rule function to override following methods for custom processing:

For more information on these methods, see the Oracle E-Business Suite Integrated SOA Gateway Developer's Guide.

Implementation Limitation and Consideration

While implementing the Service Invocation Framework, consider the following limitations: