Oracle E-Business Suite Integrated SOA Gateway Implementation Guide Release 12.1 Part Number E12169-06 | Contents | Previous | Next |
This chapter covers the following topics:
To invoke all integration services from Oracle E-Business Suite, Oracle E-Business Suite Integrated SOA Gateway uses service invocation framework (SIF) that leverages Oracle Workflow Java Business Event System (JBES) and a seeded Java rule function to allow any WSDL-described service to be invoked.
Note: To have the Web service invocation feature work properly, Oracle E-Business Suite Integrated SOA Gateway has dependency on the Oracle Application Server WSIF and Oracle Workflow Java Business Event System.
By using this service invocation framework, developers or implementors can interact with Web services through WSDL descriptions instead of working directly with SOAP APIs, the usual programming model. This approach lets you use WSDL as a normalized description of disparate software, and allows you to access this software in a manner that is independent of protocol or location.
This invocation framework used in Oracle E-Business Suite allows updated implementations of a binding to be plugged into WSIF at run time. As a result, it not only facilitates a stubless or completely dynamic Web service invocation, but also allows the calling service to defer choosing a service binding until run time. More importantly, this enhances the seamless business integration between loosely coupled applications and accelerates service execution and consumption.
Note: WSIF is a simple Java API for invoking Web services. It is supported by Oracle 10g Application Server (Oracle 10gAS) Release 3 (10.1.3) which is shipped together with Oracle E-Business Suite Release 12. To upgrade your instance from Release 12, ensure that your system is upgraded to appropriate versions of Oracle 10g Application Server. See Installing Oracle E-Business Suite Integrated SOA Gateway, Release 12, My Oracle Support Knowledge Document 556540.1 for details.
Please note that the service invocation framework discussed here only supports document-based Web service invocation. Oracle E-Business Suite Integrated SOA Gateway does not support RPC (remote procedure call) style Web service invocation through this invocation framework.
Note: The document-based Web service typically uses the form of XML with commonly agreed upon schema between the service provider and consumer as a communication protocol. While RPC-based Web service is to invoke a cross-platform remote procedure call using SOAP.
To have a better understanding on how the service invocation framework invokes Web services, the following topics are described in this chapter:
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.
The Business Event System consists of an Event Manager and workflow process event activities. The Event Manager lets you register subscriptions to significant events; event activities representing business events within workflow processes let you model complex business flows or logics within workflow processes.
When an event occurs, the Event Manager executes subscription to the event. Subscription processing can include executing custom code on the event information, sending event information to a workflow process, and sending event information to other agents or systems.
For example, to invoke a Web service through Oracle Workflow JBES, the description of WSDL URL representing the Web service must be consumed through the event subscription definition so that Web service metadata can be parsed and stored as subscription parameters.
Note: By leveraging Oracle Workflow Java Business Event System (JBES), service invocation framework allows almost any forms of Web services representing in WSDL URLs to be invoked out from Oracle E-Business Suite.
At run time, when an invoker event is raised, the event and subscription parameters are used to invoke Web services.
Note: 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 parameters.
To better understand how the invocation process takes place and its relationship between Oracle Workflow components, the following architecture diagram provides the topology of various components that exchange information during the end-to-end service invocation from within Oracle Workflow process:
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
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.
Oracle Workflow Business Event System (BES) identifies that the event has a subscription with Java Rule Function oracle.apps.fnd.wf.bes.WebServiceInvokerSubscription.
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.
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
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 (CM) tier.
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.
After an event is raised either using PL/SQL API or Java method, the raised event can be processed in the following ways:
If the raised event is dispatched immediately to the Java Business Event System, then seeded Java rule function and its associated event subscription information will be retrieved and executed to invoke the Web service.
If the raised event is enqueued to WF_JAVA_DEFERRED queue, then Java Deferred Agent Listener running on concurrent tier will dequeue the event message and then dispatch the event to the Java Business Event System. The seeded Java rule function and its associated event subscription information will be then retrieved and executed to invoke the Web service.
While invoking the Web service, the seeded Java rule function first reads the Web service metadata created for the subscription.
If Web service input message requires transformation, the Java rule function performs XSL transformation on the request message generated during the event creation by using a PL/SQL API ECX_STANDARD.perform_xslt_transformation. Next, the Java rule function invokes the service.
Note: For detailed information on the XSL transformation PL/SQL API, see Execution Engine APIs, Oracle XML Gateway User's Guide.
If it is for the synchronous request - response operation, when the response message is available and XSL transformation is required on the Web service output message, XSL transformation on the output (response) message will be performed.
If callback information is provided, perform callback by either raising a business event or by enqueuing the event to a given workflow agent with the response message as payload.
Note: For the service invocation from Java code, if the Web service 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 is available immediately by using method getResponseData() on the BusinessEvent object.
Service Invocation Framework includes the following features:
It supports various service invocation sources or points from Oracle E-Business Suite instance. This includes
PL/SQL Layer
Workflow Process
Any other PL/SQL code
Forms
Java Layer
OA Framework
Standalone Java Code
It supports the Synchronous Request - Response, and One-way/Notification Only message patterns in WSDL.
It supports SSL-based Web service invocation over HTTPS protocol.
It supports Web Service (WS) security through UsernameToken-based Web Service authentication.
It supports passing values for any header part that may be required to embed application context into SOAP envelopes.
It provides errors and exception handling, and the invocation retry feature.
It provides a ability to test business event for service invocation.
This section discusses the following topics:
Web services can be invoked from any one of following tiers:
OACORE OC4J: Web service invocations from OA Framework page using a synchronous event subscription (phase < 100) is executed from within the OACORE OC4J container.
Concurrent Manager (CM) Tier JVM: The following Web service invocations are executed from CM tier JVM within Java Deferred Agent Listener that runs within Workflow Agent Listener Service:
Invocations from PL/SQL either through synchronous or asynchronous event subscriptions
Invocations from Java/OA Framework through asynchronous event subscriptions
Standalone JVM: Web service invocations from a Java process that runs outside OACORE or CM using a synchronous event subscription executes from within that JVM.
Proxy Host and Port Setups
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. Therefore, administrators must set up and configure proxy host and port appropriately for the tiers that Web service invocations occur in order to perform following activities:
Parse and consume WSDL during subscription definition
Invoke Web service from subscription definition
For Web services invoked from OA Framework, the JBES seeded Java rule function would run within OACORE's OC4J container.
The oc4j.properties ($INST_TOP/ora/10.1.3/j2ee/oacore/oc4j.properties) should have the following properties or proxy values in order for it to work:
http.proxyHost=myproxyhost
http.proxyPort=80
To update the oc4j.properties file, you need to update AutoConfig context file with following entries and run AutoConfig:
<!-- proxy -->
<proxyhost oa_var="s_proxyhost">myproxyhost</proxyhost>
<proxyport oa_var="s_proxyport">80</proxyport>
<porxybypassdomain oa_var="s_proxybypassdomain">any domain that needs to be by-passed (such as *.us.oracle.com)</porxybypassdomain>
For Web services invoked from PL/SQL and Java using asynchronous subscriptions, the event is raised by the application code wherever it executes and then it is enqueued to 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 a concurrent manager tier Java service's JVM. If the Web service resides outside the firewall, it requires updating the following Service Parameters for Workflow Agent Listener Service from Oracle Workflow Manager available through Oracle Applications Manager:
SVC_PROXY_SET=true
SVC_PROXY_HOST=<proxy_host>
SVC_PROXY_PORT=<proxy_port>
For detailed information, see Editing Service Parameters for a Container, Oracle Workflow Administrator's Guide.
You must set the following entries:
java -Dhttp.proxyHost=myproxyhost -Dhttp.proxyPort=80 class name
Service Invocation Framework supports SSL-based Web service invocation using Server Authentication method. When a client connects to a Web server securely 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), some manual setup tasks need to be performed properly to read SSL-based WSDLs and invoke SSL service endpoints.
A client may receive one of following two types of server certificates to verify:
Public certificate and it is issued by a Certification Authority (CA).
Self-signed certificate or certificate is not in trusted certificate list.
Following two setups are required for the service invocation framework to invoke a SSL-based Web service:
Public Certificate Issued by a Certification Authority (CA)
If server certificate is a public certificate and issued by a public CA such as VeriSign, then it is most likely available in a SIF's JVM's certificate store or in a trusted certificate list.
Self-signed Certificate or Certificate is not in Trusted Certificate List
Complete the following tasks to import the server's SSL certificate into a SIF's JVM's certificate store or add it to a trusted certificate list:
Export the server certificate using either one of the following methods:
Use openssl Utility:
Use openssl utility to connect to the destination server with the following syntax:
$ openssl s_client -connect <server>:<port> -showcerts
Important: If there is no port in destination, default HTTPS port 443 should be used.
For example: $ openssl s_client -connect host.domain.com:443 -showcerts
Copy the certificate content from BEGIN CERTIFICATE to END CERTIFICATE (including BEGIN CERTIFICATE and END CERTIFICATE lines as shown in the sample certificate) into a file and save the file (such as my_cert.cer).
A sample output of above openssl command can be like:
$ openssl s_client -connect host.domain.com:443 -showcerts
...
Server certificate
-----BEGIN CERTIFICATE-----
MIIFVjCCBD6gAwIBAgIQBVWzfUyIcCa5LtuV+f9WvjANBgkqhkiG9w0BAQUFADCB
sDELMAkGA1UEBhMCVVMxFzAVBgNVBAoTDlZlcmlTaWduLCBJbmMuMR8wHQYDVQQL
ExZWZXJpU2lnbiBUcnVzdCBOZXR3b3JrMTswOQYDVQQLEzJUZXJtcyBvZiB1c2Ug
YXQgaHR0cHM6Ly93d3cudmVyaXNpZ24uY29tL3JwYSAoYykwNTEqMCgGA1UEAxMh
VmVyaVNpZ24gQ2xhc3MgMyBTZWN1cmUgU2VydmVyIENBMB4XDTA5MDQyMTAwMDAw
MFoXDTEwMDUwNTIzNTk1OVowgckxCzAJBgNVBAYTAlVTMRMwEQYDVQQIEwpDYWxp
Zm9ybmlhMRcwFQYDVQQHFA5SZWR3b29kIFNob3JlczEbMBkGA1UEChQST3JhY2xl
IENvcnBvcmF0aW9uMR8wHQYDVQQLFBZJbmZvcm1hdGlvbiBUZWNobm9sb2d5MTMw
MQYDVQQLFCpUZXJtcyBvZiB1c2UgYXQgd3d3LnZlcmlzaWduLmNvbS9ycGEgKGMp
MDUxGTAXBgNVBAMUECoub3JhY2xlY29ycC5jb20wgZ8wDQYJKoZIhvcNAQEBBQAD
gY0AMIGJAoGBAL/EBxxt2keWTuJbo4SogWmiaJxThYDMvy8nWkpvKIp3s7OCQW0G
t17sAirfBkUirbGRlcWi5fi0RReruGXgYxFnf12fBNAimRWVo3mjeQo8BpRBm27n
3YcTZUlaIE77FvB3913jzD9c4sbjIe2fGpVmx+X9PZmDKSY9KPGjDbFNAgMBAAGj
ggHTMIIBzzAJBgNVHRMEAjAAMAsGA1UdDwQEAwIFoDBEBgNVHR8EPTA7MDmgN6A1
hjNodHRwOi8vU1ZSU2VjdXJlLWNybC52ZXJpc2lnbi5jb20vU1ZSU2VjdXJlMjAw
NS5jcmwwRAYDVR0gBD0wOzA5BgtghkgBhvhFAQcXAzAqMCgGCCsGAQUFBwIBFhxo
dHRwczovL3d3dy52ZXJpc2lnbi5jb20vcnBhMB0GA1UdJQQWMBQGCCsGAQUFBwMB
BggrBgEFBQcDAjAfBgNVHSMEGDAWgBRv7K+g3Yqk7/UqEGctP1WCvNfvJTB5Bggr
BgEFBQcBAQRtMGswJAYIKwYBBQUHMAGGGGh0dHA6Ly9vY3NwLnZlcmlzaWduLmNv
bTBDBggrBgEFBQcwAoY3aHR0cDovL1NWUlNlY3VyZS1haWEudmVyaXNpZ24uY29t
L1NWUlNlY3VyZTIwMDUtYWlhLmNlcjBuBggrBgEFBQcBDARiMGChXqBcMFowWDBW
FglpbWFnZS9naWYwITAfMAcGBSsOAwIaBBRLa7kolgYMu9BSOJsprEsHiyEFGDAm
FiRodHRwOi8vbG9nby52ZXJpc2lnbi5jb20vdnNsb2dvMS5naWYwDQYJKoZIhvcN
AQEFBQADggEBADBi9NfljQLuD2Tnol3pmQl717rc8kKmpLYEO6u5MxIK0+L2MslV
4NE1qbNx1dfIoW68HHXtpsF5KtKFLYk9EoOkBd7oMp7fFv31RANV3LpdAHZC9EaK
CA/oKB2RrSu7ZmaUvoRb+3v5FdhAmgtoY6Wljk0yxMvXVf/TOeXqKl8C/r1gSzyC
s/jVmy6N81Oeleqtozzt/aJNGu7xu/MdtP13eyu7RSEBRGJwEwTXH+rTUKK8mle0
Kz15DgJ6ByK2XZmD4Z+O8DTUhUhIHR1OhuLR7zjGp9W7wQuCizUcTvuKEGzVf5D/
y7orhV0U+AoXnl/5wntVMZc/Tmqr/Fkb8+g=
-----END CERTIFICATE-----
...
Use Web Browser:
Access the WSDL file available through HTTPS URL (such as https://<hostname>:<port>/webservices/SOAProvider/xmlgateway/ont__poi/?wsdl) through a Web browser.
After the WSDL file is successfully loaded in a browser, double click on the Lock icon on the bottom right hand corner of the browser and export the certificate.
For example, in Internet Explorer, double click on the Lock icon > Details > Copy to File.
In Mozilla Firefox, double click on the Lock icon > Security > View Certificate > Details > Export.
You can also use browser menu to access the certificate. For example, in Internet Explorer, select Internet Options from the Tools drop-down menu to open the Internet Options pop-up window. Select the Content tab, click Certificates and then select the Personal (or Other People) tab to select your certificate and click Export.
You can export or save certificate either in DER encoded binary X.509 (.CER) or in Base 64 encoded.
Note: Different browser versions may have different steps to Export SSL certificates.
Import the server's SSL certificate into an appropriate SIF JVM's certificate store to add it to the list of trusted certificates.
Important: 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 a certificate. 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 can 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 changeit -alias xabbott_bugdbcert -file my_cert.cer
Note: This must be typed as a single line.
The default value of StoreKey Password (-storepass ) is "changeit" The file (-file) is the exported certificate file i.e. my_cert.cer.
If the 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.
For Web services invoked from OA Framework, the JBES seeded Java rule function would run within OACORE's OC4J container.
The oc4j.properties ($INST_TOP/ora/10.1.3/j2ee/oacore/config/oc4j.properties) should have the following properties in order for it to work:
https.proxyHost=<proxyhost>
https.proxyPort=<sslproxyport>
Note: The default https port 443.
AutoConfig does not support properties https.proxyHost and https.proxyPortcurrently. If the above properties are added to oc4j.properties manually, subsequent AutoConfig run will remove these two properties. In order to make sure the above properties are retained during AutoConfig run, the context file could be customized to add these two properties.
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.
For Web services invoked from PL/SQL and Java using asynchronous subscriptions, the event is raised by the application code wherever it executes and then it is enqueued to 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 a concurrent manager 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>
You must set the following entries:
java -Dhttps.proxyHost=[proxyhost] -Dhttps.proxyPort=[sslproxyport]
<class name>
As mentioned earlier, service invocation framework, leveraging Oracle Workflow Business Event System and a seeded Java rule function, oracle.apps.fnd.wf.bes.WebServiceInvokerSubscription, enables the invocation of Web services from Oracle E-Business Suite. Therefore, the invocation of Web services using service invocation framework involves the following steps:
Defining invocation metadata and invoking Web services through the Business Event System
Calling back to Oracle E-Business Suite with Web service responses
Managing Errors
Testing Web service invocation
Extending Web service invocation
By using Oracle Workflow Business Event System to create events and event subscriptions, Web service invocation metadata can be defined. When a triggering event occurs, a Web service can be invoked through an appropriate event subscription.
Before invoking Web services, the following Web service invocation metadata must be defined first through the Business Event System:
Create a Web service invoker event
A business event that serves as a request message for a service needs to be created first.
Create a local subscription to invoke a Web service
You must subscribe to the invoker event with 'Invoke Web Service' action type.
To create an event subscription to the Invoker event, enter basic subscription information (such as source type, phase, event filter), and select 'Invoke Web Service' action type. Click Next to access the Invoke Web Service wizard where you can specify a WSDL file as an input parameter for the event subscription. The Business Event System then parses the given WSDL and displays all services contained in the WSDL for selection.
This parsing feature allows developers to select appropriate service metadata including service port, port type, and operation for a selected service and then stores the selected information as subscription parameters that will be used later during service invocation.
While defining a local subscription to the Invoker event, you can also specify the following subscription parameters:
Security parameters to support UsernameToken based WS-Security
WFBES_SOAP_USERNAME
WFBES_SOAP_PASSWORD_MOD
WFBES_SOAP_PASSWORD_KEY
Message transformation parameters to support XSL transformation
WFBES_OUT_XSL_FILENAME
WFBES_IN_XSL_FILENAME
Security Parameters to Support UsernameToken based WS-Security
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 Web 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.
To enforce this UsernameToken based WS-security during Web service invocation, this WS-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.
During the Web service requests or service invocation, the SOAP username and optional password locator information will be passed to the seeded Java rule function as the following subscription parameters when the Java rule function is defined through the Invoke Web Service wizard:
The username for the operation is stored in invoker subscription parameter WFBES_SOAP_USERNAME.
For example, it can be WFBES_SOAP_USERNAME=SYSADMIN.
The password corresponding to the SOAP username is stored in FND vault using a PL/SQL script $FND_TOP/sql/fndvltput.sql. The module name and key to retrieve the password corresponding to the SOAP user is stored in the following subscription parameters:
WFBES_SOAP_PASSWORD_MOD
For example, it can be WFBES_SOAP_PASSWORD_MOD=PO.
WFBES_SOAP_PASSWORD_KEY
For example, it can be WFBES_SOAP_PASSWORD_KEY=OrderConfirmService.
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 parameters. For example, the event parameters are passed as follows:
BusinessEvent.setStringProperty("WFBES_SOAP_USERNAME", "SYSADMIN");
BusinessEvent.setStringProperty("WFBES_SOAP_PASSWORD_MOD", "PO" );
BusinessEvent.setStringProperty("WFBES_SOAP_PASSWORD_KEY", "OrderConfirmService");
The seeded Java rule function then retrieves the password from FND vault and generates WS-Security header for the request to authenticate the Web services.
Parameters to Set Values for Input Parts
Two topics are discussed in this section:
Because the seeded Java rule function accepts SOAP body part value through business event payload, then that payload can be passed in either one of the following ways:
Event data or payload is passed through the Generate Function during the event raise.
Event data or payload is passed along with the event itself without using the Generate function.
After the event data or payload is passed, if the XML payload available at the time of invoking the Web service requires to be transformed into a form that complies with the input message schema, the seeded Java rule function performs XSL transformation on the XML payload, and then invokes the service.
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.
Message Transformation Parameters to Support XSL Transformation
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.
The following subscription parameters are used to pass the XSL file names to the seeded Java rule function for XSL transformation:
Note: The XSL file name is structured with the following format:
<filename>:<application_short_name>:<version>
For example, it can be like “PO_XSL_OUT_2.xsl:FND:1.1”.
WFBES_OUT_XSL_FILENAME: XSL file to perform transformation on the output (response) message
For example, it can be like WFBES_OUT_XSL_FILENAME=PO_XSL_OUT_2.xsl:FND:1.1.
WFBES_IN_XSL_FILENAME: XSL file to perform transformation on the input message
For example, it can be like WFBES_IN_XSL_FILENAME=PO_XSL_IN_2.xsl:FND:1.1.
At run time, a triggering event can be raised either from PL/SQL layer using a PL/SQL API WF_EVENT.Raise or from Java layer using a Java method oracle.apps.fnd.wf.bes.BusinessEvent.raise through the Business Event System.
If event parameters are passed with the same names, then the event parameters override the subscription parameters. For example, the event parameters are passed as follows:
BusinessEvent.setStringProperty("WFBES_OUT_XSL_FILENAME", "PO_XSL_OUT_2.xsl:FND:1.1");
BusinessEvent.setStringProperty("WFBES_IN_XSL_FILENAME", "PO_XSL_IN_2.xsl:FND:1.1");
For more information on Web service security and message payload, see Oracle E-Business Suite Integrated SOA Gateway Developer's Guide.
Setting 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.
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://rws60066rems.us.oracle.com:8078/webservices/SOAProvider/xmlgateway/ont__poi/PROCESS_PO_007.xsd"/>
</schema>
...
<message name="PROCESSPO_Input_Msg">
<part name="header" element="tns:SOAHeader"/>
<part name="body" element="tns1:PROCESS_PO_007"/>
</message>
...
<binding name="ONT__POI_Binding" type="tns:ONT__POI_PortType">
<soap: binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
<operation name="PROCESSPO">
<soap:operation soapAction="http://host:port/webservices/SOAProvider/xmlgateway/ont__poi/"/>
<input>
<soap:header message="tns:PROCESSPO_Input_Msg" part="header" use="literal"/>
<soap:body parts="body" use="literal"/>
</input>
</operation>
</binding>
...
</definitions>
The operation PROCESSPO requires input message PROCESSPO_Input_Msg, which has two parts:
Body: The value of PROCESS_PO_007 type to be set as SOAP body is sent as business event payload.
Header: The value of SOAHeader type to be sent in the SOAP header which is required for Web Service authorization can be set by 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>123</ns1:DOCUMENT_NUMBER>\n" +
" <ns1:PARTY_SITE_ID>4444</ns1:PARTY_SITE_ID>\n" +
"</ns1:SOAHeader>\n";
businessEvent.setStringProperty("WFBES_INPUT_header", headerPartMsg);
Note: Please note that this WFBES_INPUT_<partname> parameter can only be passed at run time during the event raise, not through the event subscription. Several constants are defined in interface oracle.apps.fnd.wf.bes.InvokerConstants for use in Java code.
If the Web service input message definition has several parts, value for the part that is sent as SOAP body is passed as 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, pass the following parameter with null value:
businessEvent.setStringProperty("WFBES_INPUT_myheader", null);
Create an error subscription to enable error processing
To enable error processing in the Business Event System that communicates with SYSADMIN user about an error condition during subscription execution, you must subscribe to the event with 'Launch Workflow' action type for error processing.
Create a receive event (optional)
If a Web service has an output or a response message to communicate or callback to Oracle E-Business Suite, and the invoker event is raised from Java code with the subscription phase is >= 100 or if the event is raised from PL/SQL, then you should create a receive event for callback feature to complete the invocation process. Additionally, you need to create external subscription to the receive event to pass the Web service response.
Note: If it is raised from Java with subscription has phase < 100, then the Web service is invoked immediately and response is available to the calling program using BusinessEvent.getResponseData() method after calling BusinessEvent.raise(). In this case, the response may not have to be communicated back to Oracle E-Business Suite using callback event.
If a Web service does not require a response, then there is no need to create a receive event.
Create a receive event subscription (optional)
If you have a receive event created, you must also create an external event subscription to pass the Web service response.
Please note that the subscription to the receive event does not have to be with "Launch Workflow" action type. It can be created with any action type that the integration developer wants.
To create an event, log on 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 on 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 Oracle E-Business Suite Integrated SOA Gateway Developer's Guide.
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:
WFBES_CALLBACK_EVENT
This subscription parameter can have a valid business event to be raised upon completion of the Web service with the service output message as payload.
For example, it can be like:
WFBES_CALLBACK_EVENT=oracle.apps.wf.myservice.callback
WFBES_CALLABACK_AGENT
This subscription parameter can have a valid business event system agent to which the event with the service response message as payload can be enqueued.
For example, it can be like:
WFBES_CALLBACK_AGENT=WF_WS_JMS_IN
Note: WF_WS_JMS_IN is a standard default inbound agent for Web service messages. If desired, a custom agent can also be created to enqueue Web service responses. Additionally, if an agent listener is not available, you need to create one. See Oracle Workflow Developer's Guide for details.
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:
BusinessEvent.setStringProperty("WFBES_CALLBACK_EVENT", "oracle.apps.wf.myservice.callback");
BusinessEvent.setStringProperty("WFBES_CALLBACK_AGENT", "WF_WS_JMS_IN");
To process Web service responses from inbound workflow agent, make sure you have agent listener set up properly.
Detailed information about these callback subscription parameters, see Oracle E-Busines Suite Integrated SOA Gateway Developer's Guide.
If there is a run-time 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 run-time exception when the Workflow Java Deferred Agent Listener executes event subscription to invoke the Web service, the event is enqueued to 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 SYSADMIN with Web service definition, error details and event details. SYSADMIN 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 Oracle E-Busines Suite Integrated SOA Gateway Developer's Guide.
To validate whether Web services can be successfully invoked from concurrent manager and OACORE OC4J, 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 OC4J can be tested. If there is a run-time 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:
Message transformation: XSL transformation for Web service input message and output message
WFBES_OUT_XSL_FILENAME
WFBES_IN_XSL_FILENAME
WS-Security: Information required to add UsernameToken header to a SOAP request
WFBES_SOAP_USERNAME
WFBES_SOAP_PASSWORD_MOD
WFBES_SOAP_PASSWORD_KEY
Input Message part value: Pass values for any part that may be required to embed application context into SOAP envelopes
WFBES_INPUT_<partname>
Callback: Callback to Oracle E-Business Suite with Web service responses
WFBES_CALLBACK_EVENT
WFBES_CALLBACK_AGENT
SOAP Body:
XML Input message (Required)
Detailed information on how to test Web service invocations, see Oracle E-Business Suite Integrated SOA Gateway Developer's Guide.
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:
preInvokeService
postInvokeService
invokeService
addWSSecurityHeader
setInputParts
For more information on these methods, see Oracle E-Business Suite Integrated SOA Gateway Developer's Guide.
While implementing the service invocation framework, consider the following limitations:
WFBES_INPUT_<partname> Parameter Can Only be Passed at the Event Raise
The service invocation framework uses event parameter WFBES_INPUT_<partname> to support passing values for any header part that may be required to embed application context into SOAP envelopes. However, unlike other parameters that can be defined while subscribing to the Invoker event, this event parameter can only be defined during the event raise.
Support Document Style Web Services Only
The service invocation framework supports invoking only document-based Web services. The RPC (remote procedure call) style remote Web service invocation is not supported in this release.
Support One-to-One Relationship of Event Subscriptions
To successfully invoke Web services, each event should only have one subscription (with 'Invoker Web Service' action type) associated with it. This one-to-one relationship of event subscription is especially important in regards to synchronous request - response service invocation.
For example, if there are three event subscriptions (S1, S2, and S3) for the same event (Event 1), when a triggering event occurs at run time, the services associated with each subscription can be invoked three times (WS1, WS2, and WS3) respectively. The scenario is illustrated in the following diagram:
If callback parameters are not passed, getResponseData() method on the BusinessEvent object returns the output (response) message in the same session after the invoker event raise. The R2 overrides the R1; R3 overrides the R2. As a result, you will only get R3 message back.
If callback parameters are passed, since there are three different instances of the receive event with the same event key, it is difficult to match the response to the corresponding Invoke Web Service subscription.
Copyright © 2008, 2010, Oracle and/or its affiliates. All rights reserved.