Web services are Web-based applications that provide a standard means of interoperating between different software applications, running on a variety of platforms or frameworks. Web services have an interface described in a machine-processable format called WSDL (Web Services Description Language). Other systems interact with the Web service in a manner prescribed by its description using SOAP (Simple Object Access Protocol) messages, typically conveyed using HTTP with an XML serialization in conjunction with other Web-related standards.
Service-Oriented Architecture for Enabling XML Gateway Web Services
By leveraging the concept of service-oriented architecture (SOA) in Oracle E-Business Suite, XML Gateway inbound messages can be service enabled.
Note: Outbound XML Gateway messages are first enqueued to the ECX_OUTBOUND queue. They are used through subscription model by first dequeuing the messages to retrieve outbound data and then invoking appropriate outbound XML Gateway maps to exchange messages with any trading partner that conforms to Oracle E-Business Suite Web service client. Hence, all the XML Gateway Web services discussed here are for inbound services.
The common service-oriented architecture used in enabling Web services is illustrated in the following diagram:
Service-Oriented Architecture
Service Provider is the primary engine underlying the Web services. It acts as a bridge between Oracle E-Business Suite and Oracle SOA Suite to facilitate the service enablement for various types of Oracle E-Business Suite interfaces.
Note: In earlier Oracle E-Business Suite Releases, SOA Provider and Web Service Provider were used in enabling Oracle E-Business Suite Web services. In the Release 12.2, Service Provider is the engine for service enablement.
Service Provider is the engine that performs the actual service generation and deployment behind the scene.
Service Consumer (Web service client) is the party that uses or consumes the services provided by the Service Provider.
Service Broker (Service Registry) describes the service's location and contract to ensure service information is available to potential service consumers.
WSDL and SOAP are the communication vehicles facilitating the services. Part of the WSDL provided by a service provider is passed to the service consumer in specifying what the requests and responses are for the service provider. The service consumer sends SOAP messages as service requests to the service provider. The service provider then provides the expected SOAP responses back to the service consumer to complete the requests.
In Oracle XML Gateway, WSDL description is used to inform trading partners how to communicate with Oracle E-Business Suite. Inbound Web services must conform to this WSDL. Outbound message are first enqueued to ECX_OUTBOUND queue and the Transport Agent dequeues the message and delivers it to any trading partner that conforms to Oracle E-Business Suite Web service client.
Any transaction supported by Oracle XML Gateway can be sent or received as a document style Web service using the Simple Object Access Protocol (SOAP).
Following are the components and features implemented for Web services in Oracle E-Business Suite.
One of the major components for publishing a Web service is the WSDL. It enables your trading partner to call your Web service without any further details. Partners can use any third party Web service tools to call your service.
Typically, schema structure is defined as part of the WSDL. For strongly-typed XML Gateway services through Oracle E-Business Suite Integrated SOA Gateway's Service Provider, each service contains a complete definition of its input and output message content in XML schema included in the WSDL definition. XML Gateway knows the data structure based on the transaction type and the DTD defined in the map for the message enabled for the trading partner. For generic XML Gateway services through Web Service Provider, the schema structure type is defined as "anyType". This allows the Oracle E-Business Suite to accept XML documents containing any XML structure.
Note: Oracle recommends that you use strongly-typed XML Gateway Web services.
Oracle E-Business Suite publishes the WSDL to an URL for your customers to access.
Delivery is guaranteed for messages exchanged between trading partners that both recognize unique message IDs. The Oracle E-Business Suite leverages the AQ message ID. This ID is guaranteed to be the same across any database system in the world.
The message IDs are maintained in a repository on the receiving side. Before receiving any message, it interrogates the repository for the ID. If the message has not been received, the Web service provider receives and commits. If the message has already been received, it ignores the message and sends a successful response.
The sending side reviews the response. If it is successful, it does not retry. If it is a failure, it retries based on two parameters: Number of attempts and time-to-live for a transaction. Once both are exhausted, the message is marked as undeliverable. If implemented, a sent to the Workflow.
SOAP is a protocol specification for exchanging structured information in the implementation of Web services in computer networks.
The current release of Oracle E-Business Suite supports document style Web services.
The SOAP servlet receives inbound transactions. It is responsible for the following:
Authentication
The system-level User ID and Password are validated against the Oracle E-Business Suite application user.
Authorization
The trading partner information is validated against the trading partner tables.
Message extraction
The message is enqueued.
Attachments are supported for XML Gateway outbound messages.
Security is the most critical feature that is designed to guard service content from unauthorized access. To ensure secure access and the execution of Web services, security can be enforced through subject authentication and authorization:
To authenticate users on Oracle E-Business Suite Web service access, appropriate authentication types supported by Oracle E-Business Suite Integrated SOA Gateway must be selected from either one of the following mechanisms before service deployment.
To authenticate users who request Oracle E-Business Suite Web services, the SOAP requests must be authenticated through either one of the following authentication types supported by Oracle E-Business Suite Integrated SOA Gateway:
Username Token: This authentication type provides username and password information in the security header for a Web service provider to use in authenticating the SOAP request.
SAML Token (Sender Vouches): This authentication type is used for Web services relying on sending a username only through SAML Assertion.
The identified authentication information is embedded in the wsse:security
Web Security headers for service authentication.
To authorize users on specific services or operations, the access permissions must be explicitly given to the users through security grants. Multiple organization access control (MOAC) security rule is also implemented for authorizing interface execution related to multiple organizations.
Additionally, for strongly-typed XML Gateway services through Oracle E-Business Suite Integrated SOA Gateway's Service Provider, all XML Gateway header parameters for inbound transactions are defined in SOAHeader
part of a SOAP request. These parameters are used for XML Gateway inbound transactions to be completed successfully.
For generic XML Gateway services through Web Service Provider, all mandatory XML Gateway header parameters for inbound transactions are defined in XMLGateway_Header
part of a SOAP request.
Oracle XML Gateway provides a set of services that can be easily integrated with Oracle E-Business Suite to support XML messaging.
XML Gateway messages can be displayed through Oracle Integration Repository, an centralized repository that contains numerous interface endpoints exposed by applications within the Oracle E-Business Suite.
Based on the SOA architecture described earlier, XML messages resided on the Oracle Integration Repository (serves as a service broker) can be service enabled through a service provider and then in the form of WSDL description to inform trading partners how to communicate with Oracle E-Business Suite.
To better understand XML Gateway Web services, the following topics are discussed in this section:
Oracle E-Business Suite Integrated SOA Gateway (ISG) leverages Oracle SOA Suite running on Oracle WebLogic Server to provide greater capabilities for exposing integration interfaces within Oracle E-Business Suite as Web services.
Oracle E-Business Suite and Oracle SOA Suite
Oracle E-Business Suite is on Oracle WebLogic Server and is integrated with Oracle SOA Suite running on WebLogic Server.
With this integration, Oracle SOA Suite provides the most current SOA technology such as Web services standards support, protocols, and binding, while Oracle E-Business Suite provides the integration content (such as the XML Gateway interfaces), security model, and guidelines for best practices. This architecture not only provides best-in-class SOA infrastructure for Oracle E-Business Suite, but also facilitates the development and execution of complex business processes into highly flexible and reusable Web services.
XML Gateway messages are enabled through Service Provider, previously known as SOA Provider. It is the engine that performs the actual service generation and deployment behind the scene.
XML Gateway messages can be exposed as Web services in the following types:
Strongly-typed XML Gateway Services
Strongly-typed XML Gateway service contains a complete definition of its input and output messages in XML Schema that is either included in the WSDL definition or referred to by that WSDL definition.
Strongly-typed or fine-grained services are enabled through Oracle E-Business Suite Integrated SOA Gateway's Service Provider in Oracle E-Business Suite release 12.2 and SOA Provider in Oracle E-Business Suite release 12.1.x.
XML Gateway header parameters are defined in SOAHeader
part of a SOAP request.
For more information about strongly-typed XML Gateway services, see Strongly-Typed XML Gateway Services.
Generic XML Gateway Services
Compared to strongly-typed service, the generic structure or loosely-typed service definition in WSDL does not contain a schema that strongly defines any kind of message format that the service uses. Instead, a generic WSDL description is used.
This type of service is available prior to Oracle E-Business Suite release 12.1. Mandatory XML Gateway header parameters for inbound transactions are defined in XMLGateway_Header
part of a SOAP request.
For more information about generic XML Gateway services, see Generic XML Gateway Services.
Web service security (WS-Security) is a specification to enable applications to conduct secure SOAP message exchanges. It proposes a standard set of SOAP extensions that can be used when building secure Web services to implement message content integrity and confidentiality. It also provides support for multiple security tokens, the details of which are defined in the associated profile documents.
To secure Web service content and authenticate users who request XML Gateway services provided through Oracle E-Business Suite Integrated SOA Gateway, the following security mechanisms for inbound service requests are used:
For more Web Service security information, see Oracle E-Business Suite Integrated SOA Gateway Implementation Guide.
In the UsernameToken based security mechanism, the username/password is sent in the SOAP header for authentication. The username/password sent with the SOAP header is associated with the User created in Oracle E-Business Suite.
Username is a clear text; password is the most sensitive part of the UsernameToken profile. In this security model, the supported password type is plain text password (or PasswordText).
Note: The PasswordText password type is the password written in clear text. SOAP requests invoking the Web services should include security header consisting of Username and plain text password. The password received as part of the SOAP request at runtime will be validated against the encrypted password stored in Oracle E-Business Suite. After validation, the plain text password from the SOAP request will be discarded.
At run time, SOAP request messages received through Oracle SOA Suite are passed on to a JAAS based login module for Oracle E-Business Suite for authentication based on the wsse:security
Web Security headers. The username/password discussed here in wsse:security
is associated with the User created in Oracle E-Business Suite.
A SOAP header should include the following wsse:security
section:
<wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wsswssecurity-secext-1.0.xsd> <wsse:UsernameToken> <wsse:Username>username</wsse:Username> <wsse:Password>password</wsse:Password> </wsse:UsernameToken> </wsse:Security>
Important: Authorization Check at Both the Trading Partner Level and WS-Security Level for XML Gateway Interfaces
In Oracle XML Gateway, each trading partner is configured with Oracle E-Business Suite users. Only these authorized users defined in the Trading Partner Setup form are allowed to perform XML transactions. External clients can pass such usernames in the <USERNAME>
and <PASSWORD>
elements defined within the <ECX:SOAHeader>
element (or <XMLGateway_Header>
element for generic XML Gateway services) in the SOAP body. These username parameters are validated by Oracle XML Gateway against the username defined in the trading partner setup before initiating a transaction.
Therefore, for XML Gateway interface type, the authorization check is performed at both the trading partner level, as well as on the username passed in the wsse:security
header in the SOAP request.
For more information on how to set up trading partners, see Trading Partner Setup and Trading Partner User Security.
A typical WS-Security header in the SOAP message from Oracle E-Business Suite can be as follows:
<xml version="1.0" encoding="UTF-8"> <env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <env:Header> <wsse:Security xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wsswssecurity-secext-1.0.xsd> <wsse:UsernameToken> <wsse:Username>username</wsse:Username> <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">password</wsse:Password> </wsse:UsernameToken> </wsse:Security> </env:Header> <env:Body> ... </env:Body> </evn:Envelope>
Note: The username/password information in XMLGateway_Header is the username/password associated with trading partner setup.
For more information about setting up a trading partner, see Trading Partner Setup.
To authenticate Web services relying on sending a username only through SAML assertion, SAML Token (Sender Vouches) based Web service security is supported by Oracle E-Business Suite Integrated SOA Gateway for XML Gateway services..
Security Assertion Markup Language (SAML) is an XML-based standard for exchanging authentication and authorization data between security domains, that is, between an identity provider and a service provider.
How to Authenticate Users through a Trusted Sender-Vouches SAML Token
A SAML token uses SAML assertions as security tokens. One type of SAML token is the sender-vouches SAML token. This token uses a method called a sender-vouches method to establish the correspondence between a SOAP message and the SAML assertions added to the SOAP message.
When a Web application invokes a service that uses SAML as its authentication mechanism, this SOAP request message containing or referencing SAML assertions is received and passed on to a JAAS based login module for Oracle E-Business Suite for authentication based on the wsse:security
Web Security headers. As part of the validation and processing of the assertions, the receiver or the login module for Oracle E-Business Suite must establish the relationship between the subject, claims of the referenced SAML assertions, and the entity providing the evidence to satisfy the confirmation method defined for the statements.
In other words, in order to validate and authenticate a user who logs on to the enterprise information system, a trusted sender-vouches SAML token security mechanism must be used to establish the correspondence between the SOAP message and the SAML assertions added to the SOAP message.
Note: Since everyone can send a SAML Token with valid conditions, the authentication framework only trusts certain SAML token sources and stores the public key of each of these sources in a common key store. This Public Key Infrastructure (PKI) based security provides more sophisticated trusted rules to authenticate Web services.
Please note that the following algorithms have been certified for SAML Token security in this release:
Symmetric Encoding Algorithm:
http://www.w3.org/2001/04/xmlenc#aes128-cbc
Key Encryption Algorithm:
http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p
Important: To ensure SAML Token security works properly, necessary setup steps need to be performed. For setup information on SAML Token security, see Setting Up SAML Token Security for Oracle E-Business Suite Integrated SOA Gateway Release 12.2, My Oracle Support Knowledge Document 1332262.1 for details.
To authenticate users, any entity that establishes a PKI trust with Oracle E-Business Suite Integrated SOA Gateway can send the SAML Assertion with a valid Username. A PKI trusted entity will send a SAML token profile with the username embedded with it and that must be digitally signed. The SAML Token policy attached to the Web service verifies attributes like "Issuer", "Conditions" etc. After the verification, the login module (IsgSAMLLoginModule
) extracts the SAML principal (username in NameIdentifier
) through a NameCallback. This is verified against LDAP for Single Sign-On (SSO) users or against Oracle E-Business Suite FND_USER
for non-SSO users.
Please note that for strongly-typed XML Gateway services enabled through Oracle E-Business Suite Integrated SOA Gateway, it is mandatory that all users must be valid Oracle E-Business Suite users. If SSO mechanism is used, then the user in LDAP server for SSO should be in synchronous with Oracle E-Business Suite FND_USER
table. Otherwise, the user authorization check will fail when looking up the application responsibilities for user authorization against entries in the FND_USER
table. For more information on integrating Oracle E-Business Suite in an enterprise single sign-on environment, see the Oracle E-Business Suite Security Guide.
A sample sender-vouches SAML assertion for a non-SSO environment can be as follows:
<Assertion AssertionID="be7d9814c36381c27fefa89d8f27e126" IssueInstant="2010-02-27T17:26:21.241Z" Issuer="www.oracle.com" MajorVersion="1" MinorVersion="1" xmlns="urn:oasis:names:tc:SAML:1.0:assertion" xmlns:samlp="urn:oasis:names:tc:SAML:1.0:protocol"><Conditions NotBefore="2010-02-27T17:26:21.241Z" NotOnOrAfter="2011-02-27T17:26:21.241Z"/> <AuthenticationStatement AuthenticationInstant="2010-02-27T17:26:21.241Z" AuthenticationMethod="urn:oasis:names:tc:SAML:1.0:am:password"> <Subject> <NameIdentifier Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified" NameQualifier="notRelevant">SYSADMIN</NameIdentifier> <SubjectConfirmation> <ConfirmationMethod>urn:oasis:names:tc:SAML:1.0:cm:sender-vouches</ConfirmationMethod> </SubjectConfirmation> </Subject> </AuthenticationStatement> </Assertion>
A sample sender-vouches SAML assertion for a SSO environment can be as follows:
<Assertion IssueInstant="2010-02-27T17:26:21.241Z" Issuer="www.oracle.com" MajorVersion="1" MinorVersion="1" xmlns="urn:oasis:names:tc:SAML:1.0:assertion" xmlns:samlp="urn:oasis:names:tc:SAML:1.0:protocol"><Conditions NotBefore="2010-02-27T17:26:21.241Z" NotOnOrAfter="2011-02-27T17:26:21.241Z"/> <AuthenticationStatement AuthenticationInstant="2010-02-27T17:26:21.241Z" AuthenticationMethod="urn:oasis:names:tc:SAML:1.0:am:password"> <Subject> <NameIdentifier Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified" NameQualifier="notRelevant">orclApplicationCommonName=PROD1,cn=EBusiness,cn=Products,cn=OracleContext,dc=us,dc=oracle,dc=com</NameIdentifier> <SubjectConfirmation> <ConfirmationMethod>urn:oasis:names:tc:SAML:1.0:cm:sender-vouches</ConfirmationMethod> </SubjectConfirmation> </Subject> </AuthenticationStatement> </Assertion>
For information on how the sender-vouches SAML Token is used in SOAP security header to authenticate Web services, see Managing Web Service Security, Oracle E-Business Suite Integrated SOA Gateway Implementation Guide.
XML Gateway messages (along with other integration interfaces) within Oracle E-Business Suite are displayed through Oracle Integration Repository where they can be exposed to all users.
Note: Oracle Integration Repository is one of essential components within Oracle E-Business Suite Integrated SOA Gateway. Building on the principle of service-oriented architecture technology, Oracle E-Business Suite Integrated SOA Gateway provides the service enablement capability for strongly-typed XML Gateway services through Service Provider.
Strongly-typed XML Gateway Service through Service Provider
Web Service Region
The Web Service region is displayed in the interface details page for strongly-typed XML Gateway inbound maps, no matter if the service is generated or not.
This region contains the following fields:
Web Service Status: This indicates whether the selected XML Gateway map has an associated service generated or not, or whether it is deployed.
If an XML Gateway service is available for the selected map, the Web Service Status field can be any values other than 'Not Generated'. It can be 'Generated' if is not deployed, or 'Deployed' with 'Active' state if it has been deployed to an Oracle SOA Suite managed server.
View WSDL link: This link lets you view the WSDL description for the generated or deployed service.
Interaction Pattern: This field appears only when the associated service is generated for this XML Gateway map.
Please note that XML Gateway interface can be service enabled only with synchronous operation pattern. If a selected XML Gateway interface is exposed as a Web service, the single method contained in the interface must be generated only with the support for synchronous pattern by default. Once the XML Gateway service is generated, 'Synchronous' is automatically displayed in the Interaction Pattern field by default.
Authentication Type: This field displays the selected Authentication Type in read-only mode once the service has been deployed.
Username Token: This authentication type provides username and password information in the security header for a Web service provider to use in authenticating users who request XML Gateway services.
SAML Token (Sender Vouches): This authentication type is used for Web services relying on sending a username only through SAML Assertion.
If the Web service has been generated successfully, the service can be deployed to Oracle SOA Suite for public access. For more information on the Web Service region for XML Gateway Web services, see the Oracle E-Business Suite Integrated SOA Gateway User's Guide.
Managing User Security for XML Gateway Web Services
User security is managed through the Trading Partner User Setup form where the administrator needs to associate users with a trading partner. Only these authorized users can perform XML Gateway inbound transactions with the trading partner. Specifically, the administrator needs to:
Set the "ECX: Enable User Check for Trading Partner" profile option to "Yes" to enable the trading partner specific security feature
Associate users with a trading partner in the Trading Partner User Setup form
For more information about setting the user security, see Trading Partner User Security.
For more information on how to access strongly-typed XML Gateway services, see Enabling and Accessing Strongly-typed XML Gateway Services through Oracle E-Business Suite Integrated SOA Gateway.
For strongly-typed XML Gateway services enabled through Service Provider, all XML Gateway header parameters for inbound transactions are defined in SOAHeader
part of a SOAP request.
The following code snippet shows the SOAHeader
part of a SOAP request for an XML Gateway inbound message through Service Provider:
<soapenv: Envelope xmlns:ecx="http://xmlns.oracle.com/apps/ecx/soaprovider/xmlgateway/ecx__cbodi/" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sys="http://xmlns.oracle.com/xdb/SYSTEM"> <soapenv:Header> <wsse:Security soapenv:mustUnderstand="1" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"> <wsse:UsernameToken wsu:Id="UsernameToken-10586449" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"> <wsse:Username>SYSADMIN</wsse:Username> <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">password</wsse:Password> </wsse:UsernameToken> </wsse:Security> <ecx:SOAHeader> <sys:ECXMSG> <MESSAGE_TYPE></MESSAGE_TYPE> <MESSAGE_STANDARD></MESSAGE_STANDARD> <TRANSACTION_TYPE></TRANSACTION_TYPE> <TRANSACTION_SUBTYPE></TRANSACTION_SUBTYPE> <DOCUMENT_NUMBER></DOCUMENT_NUMBER> <PARTYID></PARTYID> <PARTY_SITE_ID></PARTY_SITE_ID> <PARTY_TYPE></PARTY_TYPE> <PROTOCOL_TYPE></PROTOCOL_TYPE> <PROTOCOL_ADDRESS></PROTOCOL_ADDRESS> <USERNAME></USERNAME> <PASSWORD></PASSWORD> <ATTRIBUTE1></ATTRIBUTE1> <ATTRIBUTE2></ATTRIBUTE2> <ATTRIBUTE3></ATTRIBUTE3> <ATTRIBUTE4></ATTRIBUTE4> <ATTRIBUTE5></ATTRIBUTE5> </sys:ECXMSG> </ecx:SOAHeader> </soapenv:Header>
For the description of each XML Gateway message parameter in the SOAHeader
part of a SOAP request, see XML Gateway Envelope.
Please note that the Username and Password in <wsse:Security>
is Oracle E-Business Suite username/password or the username/password created through the Users window in defining an application user.
The Username and Password in <ecx:SOAHeader>
is the username and password associated with trading partner setup.
For more information about setting up a trading partner, see Trading Partner Setup.
In Oracle E-Business Suite release 12.0, XML Gateway maps were service enabled and deployed as generic XML Gateway services.
If your system is upgraded from a previous release and if you have been using generic XML Gateway services, these generic XML Gateway services can be displayed in the interface details page from Oracle Integration Repository by setting FND: XML Gateway Map Generic Service profile value to 'Yes'.
In the Web Service region of the interface details page, click the Show Generic XML Gateway Service or Hide Generic XML Gateway Service link to display or close the Generic XML Gateway Service subregion.
For information on setting profile options for XML Gateway services, see Setting Profile Options.
In addition to setting profile options, additional setup tasks for enabling generic XML Gateway services through Oracle E-Business Suite Integrated SOA Gateway need to be configured. For setup information, see Installing Oracle E-Business Suite Integrated SOA Gateway, Release 12.2, My Oracle Support Knowledge Document 1311068.1 for details.
Generic XML Gateway Service Subregion
The Generic XML Gateway Service subregion contains the following fields:
Web Service Status: This field indicates the current state of the selected XML Gateway interface whether it has a generic service available, or if the service has been deployed or not.
If Oracle E-Business Suite Integrated SOA Gateway is not configured for generic XML services, the Web Service Status field is displayed as 'Not Deployed'.
View Generic WSDL: Click the View Generic WSDL link to display the deployed generic WSDL URL for the selected XML Gateway interface.
The deployed generic WSDL URL has the following syntax:
http://<SOA server host>:<SOA Suite managed server port>/soa-infra/services/default/XMLGatewayService!<version chosen while deploying>XMLGateway?WSDL
<SOA Suite managed server port>
: It is the port of the server where SOA composite is deployed.
<version chosen while deploying>
: At the time of deployment, deployement version will be asked. Default version value is 1.0.
For example, http://<SOA server host>:<SOA Suite managed server port>/soa-infra/services/default/XMLGatewayService!1.0/XMLGateway?WSDL
.
After the upgrade to Oracle E-Business Suite Release 12.2, the deployed WSDL URL has been changed from an earlier release. Therefore, you may have to replace it with the new WSDL URL and service location or address accordingly in Web service clients while invoking the generic XML Gateway service. To ensure backward compatibility, the previous service endpoint (services deployed in Oracle E-Business Suite) will continue to work at run time after the upgrade. New service endpoint from Oracle SOA Suite server will be shown in the interface detail page and should be used for client programs.
The updated WSDL URL is also populated in the ISG: Generic Service WSDL URL for XMLG profile option by default if setup tasks for generic XML Gateway services are configured properly.
Interaction Pattern: 'Synchronous' is displayed by default in read-only mode.
Authentication Type: 'Username Token' is displayed by default in read-only mode.
For generic XML Gateway services, all mandatory XML Gateway header parameters for inbound transactions are defined in XMLGateway_Header
part of a SOAP request.
The following code snippet shows the XMLGateway_Header
part of a SOAP request for an XML Gateway inbound message:
<soap:Envelope> <soap:Header> ... <ns1:XMLGateway_Header xmlns:ns1="http://xmlns.oracle.com/apps/fnd/XMLGateway soapenv:mustUnderstand="0"> <ns1:MESSAGE_TYPE></ns1:MESSAGE_TYPE> <ns1:MESSAGE_STANDARD></ns1:MESSAGE_STANDARD> <ns1:TRANSACTION_TYPE></ns1:TRANSACTION_TYPE> <ns1:TRANSACTION_SUBTYPE></ns1:TRANSACTION_SUBTYPE> <ns1:DOCUMENT_NUMBER></ns1:DOCUMENT_NUMBER> <ns1:PARTY_SITE_ID></ns1:PARTY_SITE_ID> </ns1:MLGateway_Header> </soap:Header> ... </soap:Envelope>
The following table describes the XML Gateway header information in XMLGateway_Header
part of a SOAP request:
Parameter Name | Description |
---|---|
MESSAGE_TYPE | Payload message format. This defaults to XML . Oracle XML Gateway currently supports only XML . |
MESSAGE_STANDARD | Message format standard as displayed in the Define Transactions form and entered in the Define XML Standards form. This defaults to OAG . The message standard entered for an inbound XML document must be the same as the message standard in the trading partner setup. |
TRANSACTION_TYPE | External Transaction Type for the business document from the Trading Partner table. The transaction type for an inbound XML document must be the same as the transaction type defined in the Trading Partner form. |
TRANSACTION_SUBTYPE | External Transaction Subtype for the business document from the Trading Partner table. The transaction subtype for an inbound XML document must be the same as the transaction subtype defined in the Trading Partner form. |
DOCUMENT_NUMBER | The document identifier used to identify the transaction, such as a purchase order or invoice number. This parameter is not used by the XML Gateway, but it may be passed on inbound messages. |
PARTY_SITE_ID | The party site identifier for an inbound XML document must be the same as the Source Trading Partner location defined in the Trading Partner form. |
This section describes the process flow of an inbound Web service in Oracle E-Business Suite.
Requests are authorized against the Application Object Library user tables (fnd_user). After authorization, the body (XML data) and header (trading partner data) information is extracted from the request. XML messages are prepared and enqueued to the SOAP agent (Web Services IN Agent). The agent listeners pick up the message and push to XML Gateway engine for further processing.
XML messages are created by Workflow processes and passed to the SOAP agent (Web Services OUT Agent). The messages are picked up by the SOAP Web service client running under the Web service container of the Generic Service Manager (GSM).
The client is responsible for the actual delivery of the message to the trading partner. The client examines the event or message from the queue and delivery. Messages are formatted according to the required protocol. Attachments to the message are extracted and packaged in the MIME format. References to the attachments are passed throughout the message processing.
To enable XML Gateway services through Oracle E-Business Suite Integrated SOA Gateway, some setup tasks are required for both strongly-typed services and generic XML Gateway services. For detailed setup and configuration tasks, see Installing Oracle E-Business Suite Integrated SOA Gateway, Release 12.2, My Oracle Support Knowledge Document 1311068.1 for details.
Additionally, to enable Web service transactions, the following setup tasks are required to provide and consume Web services:
Perform the following setup tasks to provide services through XML Gateway inbound transactions:
Enabling Agents and Starting Agent Listeners
For providing services through XML Gateway inbound transactions, agent listeners running on ECX_INBOUND queue for strongly-typed XML Gateway services need to be running.
The following agents must be enabled and the seeded agent listener service components must be running:
Agent Name | Listener Name |
---|---|
WF_WS_JMS_IN | Web Services IN Agent for generic XML Gateway services |
Use the Workflow Administrator: Agents window to enable the agents if necessary (the agents are enabled by default). The same window can be used to disable an agent.
Use Oracle Applications Manager to schedule and manage agent listener service components. For more information, refer to the Oracle Applications Manager online help.
The agent listener components are seeded with a manual startup mode and therefore must be manually started.
Setting profile option ECX_IN_JAVA_PROCESSING to Yes
This enables message processing in Java. For more information about this profile option, see Setting Profile Options.
Perform the following setup tasks to consume services through XML Gateway outbound transactions:
Enabling Agents and Starting Agent Listeners
The following agents must be enabled and the seeded agent listener service components must be running for XML Gateway outbound services
Agent Name | Listener Name |
---|---|
WF_WS_JMS_OUT | Web Services OUT Agent |
Use the Workflow Administrator: Agents window to enable the agents if necessary (the agents are enabled by default). The same window can be used to disable an agent.
Use Oracle Applications Manager to schedule and manage agent listener service components. For more information, refer to the Oracle Applications Manager online help.
The agent listener components are seeded with a manual startup mode and therefore must be manually started.
Defining Lookup Values
You need to set up the correlation identifier in Oracle E-Business Suite. The correlation identifier enables you to label messages meant for a specific agent, in case there are multiple agents listening on the outbound queue. The agent listening for a particular correlation picks up the messages that match the correlation identifier for the agent.
In the Lookup form, search for COMM_METHOD in the Type field to see if it exists in the system. Add a new record to the COMM_METHOD type by entering BPEL for the Code field and the Meaning field. Enter description information and save the record.
Oracle XML Gateway puts the correlation of BPEL when enqueueing the message on the ECX_OUTBOUND queue. In addition to having the correlation identifier set up correctly, you need to ensure the trading partner that you want to use has the Protocol Type field set to BPEL.
To support XML Gateway Web services, the following profile options described in the table need to be set properly.
Profile Option | Description | Required | Default Value |
---|---|---|---|
FND: XML Gateway Map Generic Service | Use this profile option to display or hide the generic XML Gateway service information for the selected XML Gateway map.
|
Yes | Yes
Important: If you do not start from this release and you have been using generic XML Gateway Web service, set the profile option to 'Yes'. This allows the Generic XML Gateway Services subregion to be displayed within the Web Service region. Otherwise, subregion will not be shown and any invocations of generic XML Gateway Web services will return a fault message. |
ISG: Generic Service WSDL URL for XMLG | Once a generic XML Gateway Web service has been deployed, the deployed service WSDL URL should be populated as the profile value. The URL is also displayed in the 'Generic XML Gateway Service' subregion. If the profile value is not shown which means that the generic service has not yet been deployed, no WSDL URL is displayed in the subregion for the selected XML Gateway interface. |
Yes | N/A |
ECX_IN_JAVA_PROCESSING | This profile option determines if inbound messages will be processed in Java or in PL/SQL.
|
Yes | Yes |
Use the FND: XML Gateway Map Generic Service profile option to display or hide generic XML Gateway service information in the Generic XML Gateway Service subregion only if your system is upgraded from a previous release and you have been using generic XML Gateway Web services.
For information on setting profile options, see User Profiles and Profile Options in Oracle Application Object Library, Oracle E-Business Suite Setup Guide.
This section discuss how to enable and access strongly-typed XML Gateway services and how to invoke them from Oracle E-Business Suite. This section includes the following topics:
To enable strongly-typed XML Gateway services, you must log in to Oracle E-Business Suite as a user who has the Integration Administrator role.
Note: Oracle E-Business Suite Integrated SOA Gateway allows the following three user roles to access the Integration Repository user interface and perform different tasks. Each user role is associated with a specific responsibility by default to access the Integration Repository.
Integration Analyst - Integration Repository responsibility
Integration Developer - Integrated SOA Gateway responsibility
Integration Administrator - Integrated SOA Gateway responsibility
Only users who have the Integration Administrator role can perform administrative tasks including generating and deploying Web services as well as creating security grants. Integration developers (or users who have the Integration Developer role) can generate Web services, but they cannot perform other administrative tasks. Integration analysts (or users who have the Integration Analyst role) can only search and view interfaces from the Integration Repository.
Select the Integrated SOA Gateway responsibility from the Navigator. Click the Integration Repository link to access the Integration Repository where you can find XML Gateway interfaces.
To enable a Web service for an XML Gateway interface, you must first locate the interface that you want to enable. This step can be achieved through the following ways:
Navigate to the interface from the Integration Repository browser window
Select 'Interface Type' from the View By drop-down list. Select 'XML Gateway Map' folder to expand the navigation tree and see a list of the available XML Gateway interfaces.
Locate the interface through a search
Click Search to open the main search window. Enter appropriate search criteria to locate a desired XML Gateway map.
Once you locate the desired interface from the tree or a search result, click the interface name link to open the interface details page. The Web Service region appears allowing you to perform administrative tasks for the selected map.
Only users who have the Integration Administrator role or the Integration Developer role can find the Generate button in the interface details page for a selected XML Gateway map.
Generating Web Services with Support for Synchronous Interaction Pattern
Since XML Gateway interfaces can be service enabled only with the support for synchronous operation pattern, if a selected interface of XML Gateway interface type is exposed as a Web service, the service is generated synchronously by default. Therefore, once an XML Gateway service has been successfully generated, 'Synchronous' is displayed in the Interaction Pattern field along with the Web Service Status - 'Generated'.
Click the View WSDL link to view the WSDL description for the generated or deployed service.
Deploying Web Services with Authentication Types
To secure Web service content and authenticate Oracle E-Business Suite users at run time through Oracle SOA Suite WebLogic environments, prior to deploying a Web service, an integration administrator must first select one authentication type - Username Token or SAML Token (Sender Vouches).
Click Deploy to deploy the generated service from Oracle Integration Repository to an Oracle SOA Suite managed server with active deployment state. A deployed service with active state indicates that the service is ready to accept new SOAP requests.
Recording Deployed WSDL URL
To use and invoke the deployed Web services, an integration developer must record the deployed Web service WSDL URL for the inbound message map by clicking the View WSDL link. This opens a new window where you can record the deployed WSDL URL and use it to invoke a service.
For detailed instruction on how to generate and deploy a Web service, see:
Generating SOAP Web Services, Oracle E-Business Suite Integrated SOA Gateway Implementation Guide
Deploying and Undeploying SOAP Web Services, Oracle E-Business Suite Integrated SOA Gateway Implementation Guide
Use the following steps to enable and access strongly-typed XML Gateway services:
Log in to Oracle E-Business Suite as a user who has the Integration Administrator role.
Select the Integrated SOA Gateway responsibility.
Select the Integration Repository link to access the Integration Repository.
From the Integration Repository browser window, select 'Interface Type' from the View By drop-down list.
Select 'XML Gateway Map' folder to expand the navigation tree and see a list of the available XML Gateway interfaces.
Alternatively, locate an XML Gateway message directly by performing a search.
Click Search to open the main search window. Enter appropriate search criteria to locate a desired XML Gateway map.
Click a desired XML Gateway map link either from the navigation tree or from the search result. This opens the interface details page for the selected XML Gateway map.
Click Generate to generate the Web service with the support for synchronous interaction pattern for the selected XML Gateway map. Once the service has been successfully generated, the WSDL URL appears in the Web Service region.
Select one authentication type and click Deploy to deploy the generated service to Oracle SOA Suite.
Click the View WSDL link to open and view the deployed WSDL description.
If your system is upgraded from a previous release and you have been using generic XML Gateway services, you may find the Generic XML Gateway Service subregion available within the Web Service region in the interface details page if a selected XML Gateway map has the generic Web service deployed.
Click the Show Generic XML Gateway Service or Hide Generic XML Gateway Service link to display or close the Generic XML Gateway Service subregion.
Note: To support backward compatibility for generic XML Gateway services, a profile option FND: XML Gateway Map Generic Service is used allowing Generic XML Gateway Service subregion to be displayed in the interface details page.
For more information about setting profile options for generic XML Gateway services, see Setting Profile Options.
Click the View Generic WSDL link to display the deployed generic WSDL URL for the selected XML Gateway interface.
The deployed generic WSDL URL has the following syntax:
http://<SOA server host>:<SOA Suite managed server port>/soa-infra/services/default/XMLGatewayService!<version chosen while deploying>XMLGateway?WSDL
<SOA Suite managed server port>
: It is the port of the server where SOA composite is deployed.
<version chosen while deploying>
: At the time of deployment, deployement version will be asked. Default version value is 1.0.
For example, http://<SOA server host>:<SOA Suite managed server port>/soa-infra/services/default/XMLGatewayService!1.0/XMLGateway?WSDL
.
To locate a deployed XML Gateway service for an inbound transaction:
Log in to Oracle E-Business Suite as a user who has the Integration Administrator role or the Integration Developer role. Select the Integrated SOA Gateway responsibility from the Navigator.
If you log in to Oracle E-Business Suite as a user who has the Integration Analyst role, select the Integration Repository responsibility instead from the Navigator.
Select the Integration Repository link to access the Integration Repository.
From the Integration Repository browser window, select 'Interface Type' from the View By drop-down list.
Select 'XML Gateway Map' folder to expand the navigation tree and see a list of the available XML Gateway interfaces.
Alternatively, locate an XML Gateway message directly by performing a search.
Click Search to open the main search window. Enter appropriate search criteria to locate a desired XML Gateway map.
Click a desired XML Gateway map link either from the navigation tree or from the search result.
This opens the interface details page for the selected XML Gateway map.
If this message map has a generic XML Gateway service available, the generic service information can be displayed in the Generic XML Gateway Service subregion within the Web Service region of the interface details page.
Click the Show Generic XML Gateway Service or Hide Generic XML Gateway Service link to display or close the Generic XML Gateway Service subregion.
Click the View Generic WSDL link to view the deployed WSDL description.
From Oracle E-Business Suite Release 12.1 onwards, XML Gateway messages within Oracle E-Business Suite are displayed through Oracle Integration Repository where they can be exposed as Web services.
Before service invocation, XML Gateway interfaces must first be transformed into Web services, and then be deployed to Oracle SOA Suite for further service consumption.
Only users who have the Integration Administrator role or the Integration Developer role can perform the generate action to transform a selected XML Gateway map into a Web service.
Only users who have the Integration Administrator role can deploy the generated XML Gateway service to an Oracle SOA Suite managed server for further consumption.
For inbound transactions, locate and provide the deployed WSDL description to trading partners.
For information on enabling XML Gateway Web services and obtaining the WSDL URL information, see Enabling and Accessing Strongly-typed XML Gateway Services through Oracle E-Business Suite Integrated SOA Gateway.
For information on invoking XML Gateway Web services, see Example of Using XML Gateway Services.
To enable bidirectional integration with Oracle E-Business Suite and consumers, XML Gateway services can be used through the following approaches:
For an inbound XML Gateway Map interface, once a Web service of an inbound XML Gateway interface is deployed, the deployed service represented in WSDL can be used in creating a BPEL process to insert inbound data into Oracle E-Business Suite.
For an outbound XML Gateway Map interface, since an outbound message is first enqueued to the ECX_OUTBOUND queue, it can be consumed through subscription model in Oracle E-Business Suite Integrated SOA Gateway. This can be done by first dequeuing the message to retrieve outbound data from Oracle E-Business Suite through a BPEL process. The retrieved data can then be passed to trading partners or consumers who subscribed to the message.
To better understand how to use a deployed Web service of an inbound XML Gateway interface as well as understand how the subscription model works for an outbound XML Gateway, the following topics are discussed in this chapter:
For the examples described in the following sections, Oracle JDeveloper 11g (11.1.1.6.0) is used as a design-time tool to create the BPEL process and Oracle SOA Suite 11g (11.1.1.6.0) is used for the process deployment.
Note: While using Oracle JDeveloper with other Oracle Fusion Middleware components (such as Oracle SOA Suite), to enable SOA technologies, you need to manually download Oracle SOA Suite Composite Editor, a JDeveloper's extension for SOA technologies. For more information on installing additional Oracle Fusion Middleware design-time components, see the Oracle Fusion Middleware Installation Guide for Oracle JDeveloper.
This section includes the following topics:
SOA Composite Application with BPEL Process Scenario
Use the XML Gateway Inbound Process PO XML Transaction as an example to explain the SOA Composite application with BPEL process creation. In this example, the XML Gateway inbound message map is exposed as a Web service through PROCESS_PO_007
inbound map. It allows sales order data including header and line items to be inserted into Order Management system while an associated purchase order is created.
When a purchase order is sent by a trading partner, the purchase order data is used as input to the BPEL process along with ECX Header properties such as MESSAGE_TYPE, MESSAGE_STANDARD, TRANSACTION_TYPE, TRANSACTION_SUBTYPE, PARTY_SITE_ID,
and DOCUMENT_NUMBER
. The BPEL process then pushes this purchase order in ECX_INBOUND queue. Agent Listeners running on ECX_INBOUND would enable further processing by the Execution Engine. Oracle XML Gateway picks this XML message, does trading partner validation, and inserts order data to Order Management application.
If the BPEL process is successfully executed after deployment, you should get the same order information inserted into the Order Management table once a purchase order is created.
Prerequisites to Configure a Configure a SOA Composite Application with BPEL Process Using an XML Gateway Inbound Service
Before performing the design-time tasks for XML Gateway Inbound services, ensure the following tasks are in place:
An integration administrator or an integration developer needs to generate a Web service first. The administrator will then deploy the generated service to an Oracle SOA Suite WebLogic managed server.
An integration developer needs to locate and record the deployed WSDL URL for the inbound message map exposed as a Web service.
XML Gateway header variables need to be populated for XML transaction.
A trading partner should be available for receiving the XML documents.
ECX Inbound Agent Listener and ECX Transaction Agent Listener must be running.
Deploying XML Gateway Inbound WSDL URL
Once a Web service for the selected XML Gateway inbound map has been successfully created, the integration administrator must deploy the service from Oracle Integration Repository to an Oracle SOA Suite WebLogic managed server.
For example, the following steps must be performed first before the integration developer creates a SOA composite application with BPEL process by using the deployed WSDL:
To generate a Web service, the integration administrator or the integration developer locates the interface definition first (such as an XML Gateway inbound interface INBOUND:Process Purchase Order XML Transaction (ONT:POI)
) and then clicks Generate in the interface details page.
Once the service has been successfully generated, the Web Service Status field changed from 'Not Generated' to 'Generated' in the Web Service region.
For detailed instruction on how to generate a Web service, see Enabling and Accessing Strongly-typed XML Gateway Services through Oracle E-Business Suite Integrated SOA Gateway.
To deploy the generated Web service, the integration administrator selects one desired authentication type before clicking Deploy. The deployed XML Gateway service in Oracle SOA Suite is an active service and is ready to accept new SOAP requests.
Once the service has been successfully deployed, the selected authentication type will be displayed along with 'Deployed' with 'Active' state in the Web Service Status field.
For more information on securing Web services with authentication types, see Web Service Security.
For information on how to deploy a Web service, see Deploying and Undeploying SOAP Web Services, Oracle E-Business Suite Integrated SOA Gateway Implementation Guide.
Searching and Recording WSDL URL
The integration developer needs to locate and record the deployed Web service WSDL URL for the inbound message map.
This WSDL information will be used later in creating a partner link for the inbound map exposed as a Web service during the BPEL process creation.
Populating XML Gateway Header Variables
Certain XML Gateway header variables in the BPEL PM need to be populated in order to provide context information for Oracle E-Business Suite. These variables are MESSAGE_TYPE
, MESSAGE_STANDARD
, TRANSACTION_TYPE
, TRANSACTION_SUBTYPE
, DOCUMENT_NUMBER
and PARTY_SITE_ID
. They are the mandatory header variables that need to be populated in order for the XML transaction to complete successfully.
Refer to Adding an Assign activity for more information.
Setting Up a Trading Partner for Receiving XML Documents
Use the following steps to set up a trading partner:
Log in to Oracle E-Business Suite as a user who has the XML Gateway responsibility.
Click the Define Trading Partners link from the Navigator.
The Trading Partner Setup form is displayed. Search an existing trading partner by selecting View > Query by Example > Enter and enter the following information:
Trading Partner Type: Customer
Trading Partner Name: Example Inc.
Trading Partner Site: 401 Island Parkway Redwood Shores, CA 94065
Execute the query by selecting View > Query by Example > Enter to locate the trading partner along with existing transactions.
Trading Partner Setup Window
Enter the following trading partner details:
Transaction Type: ONT
Transaction SubType: POI
Standard Code: OAG
External Transaction Type: PO
External Transaction SubType: PROCESS
Direction: IN
Map: ONT_3A4R_OAG72_IN
Source Trading Partner Location Code: Example-01
Save your entry.
Ensuring Agent Listeners Are Up and Running
Ensure listeners on the ECX_INBOUND, ECX_TRANSACTION queues are running. Use the following steps to configure these listeners in Oracle E-Business Suite:
Log in to Oracle E-Business Suite as a user who has the Workflow Administrator responsibility.
Click the Workflow Administrator Web Applications link from the Navigator.
Click the Workflow Manager link under Oracle Applications Manager.
Click the status icon next to Agent Listeners.
Configure and schedule the ECX Inbound Agent Listener and the ECX Transaction Agent Listener. Select the listeners, and select Start from the Actions box. Click Go if they are not up and running.
SOA Composite Application with BPEL Process Creation Flow
Based on the XML Gateway Inbound Process PO XML Transaction business scenario, the following design-time tasks are discussed in this chapter:
Create a New SOA Composite Application with BPEL Process
Use this step to create a new SOA Composite application with BPEL process called XMLGatewayInbound.bpel
using an Synchronous BPEL Process template. This automatically creates two dummy activities - Receive and Reply - to receive input from a trading partner and to reply output of the BPEL process to the request application.
Use this step to create a partner link to allow the inbound message to be inserted to the Oracle E-Business Suite.
Add a Partner Link for File Adapter
Use this step to add a partner link for File Adapter in order to pick up an XML file received from the trading partner to get the XML message.
Use this step to add two Invoke activities in order to:
Get the XML message details that is received from the Receive activity.
Enqueue the purchase order information to the ECX_INBOUND queue.
Use this step to create two Assign activities in order to:
Pass XML message obtained from the first Invoke activity to the second Invoke activity.
Pass ECX header variables to the second Invoke activity as input variables.
For general information on how to create SOA composite applications using BPEL process service component, see the Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite.
Use this step to create a new SOA composite application with BPEL process that will contain various BPEL process activities.
To create a new SOA composite application with BPEL process:
Open Oracle JDeveloper.
Click New Application in the Application Navigator.
The "Create SOA Application - Name your application" page is displayed.
The Create SOA Application - Name your application Page
Enter an appropriate name for the application in the Application Name field and select SOA Application from the Application Template list.
Click Next. The "Create SOA Application - Name your project" page is displayed.
The Create SOA Application - Name your project Page
Enter an appropriate name for the project in the Project Name field, for example, XMLGatewayInbound
.
In the Project Technologies tab, select 'Web Services' and ensure that SOA is selected from the Available technology list to the Selected technology list.
Click Next. The "Create SOA Application - Configure SOA settings" page is displayed.
Select Composite With BPEL Process from the Composite Template list, and then click Finish. You have created a new application, and a SOA project. This automatically creates a SOA composite.
The Create BPEL Process page is displayed.
The Create BPEL Process Page
Leave the default BPEL 1.1 Specification selection unchanged. This creates a BPEL project that supports the BPEL 1.1 specification.
Enter an appropriate name for the BPEL process in the Name field, for example, XMLGInbound
.
Select Synchronous BPEL Process in the Template field.
Select required from the Transaction drop-down list. Click OK.
A synchronous BPEL process is created with the Receive and Reply activities. The required source files including bpel and wsdl, using the name you specified (for example, XMLGInbound.bpel
and XMLGInbound.wsdl
) and composite.xml
are also generated.
Navigate to SOA Content > Business Rules and double click composite.xml
to view the composite diagram.
Double click on the XMLGInbound
component to open the BPEL process.
Use this step to create a Partner Link called ONT__POI
to insert sales order data to Oracle E-Business Suite.
To create a partner link to insert sales data to Oracle E-Business Suite:
In Oracle JDeveloper, place your mouse in the right side of the Partner Links area and right click to select Create Partner Link... from the pull-down menu. Alternatively, you can drag and drop Partner Link from the BPEL Constructs list into the right Partner Link swim lane of the process diagram.
The Create Partner Link window appears.
Copy the WSDL URL corresponding to the XML Gateway inbound map INBOUND:Process Purchase Order XML Transaction (ONT:POI)
that you recorded earlier from the Integration Repository and paste it in the WSDL File field.
Press the [Tab] key.
A Partner Link Type message dialog box appears asking whether you want the system to create a new WSDL file that will by default create partner link types for you.
Click Yes to have the Partner Name value populated automatically. You can manually enter the partner link name as ONT__POI.
Create Partner Link Dialog
Select the Partner Link Type and Partner Role fields from the drop-down lists.
Click Apply and OK.
The partner link is created with the required WSDL settings, and is represented in the BPEL project by a new icon in the border area of the process diagram.
Partner Link is added to the Partner Links section in the BPEL process diagram.
Use this step to configure a BPEL process by adding a partner link for File Adapter to get the XML Message.
To add the Partner Link for File Adapter to get the XML Message:
In Oracle JDeveloper, drag and drop the File Adapter service from the BPEL Services into the right Partner Link swim lane of the process diagram. The Adapter Configuration wizard welcome page appears.
Click Next. The Service Name dialog box appears.
Enter a name for the file adapter service, such as GetXMLMsg
. You can add an optional description of the service.
Click Next. The Adapter Interface dialog box appears.
Select the Define from operation and schema (specified later) radio button and click Next. The Operation dialog box appears.
Adapter Configuration Wizard - Operation
Specify the operation type, for example Synchronous Read File. This automatically populates the Operation Name field.
Click Next to access the File Directories dialog box.
Adapter Configuration Wizard - File Directories
Select the Physical Path radio button and enter the input payload file directory information. For example, enter /usr/tmp/
.
Note: To be able to locate the file from the physical directory that you specified here, you must first place the input payload file (such as order_data_xmlg.xml
) to the specified directory.
Click Next to open the File Name dialog box.
Enter the name of the file for the synchronous read file operation. For example, enter order_data_xmlg.xml
. Click Next. The Messages dialog box appears.
Adapter Configuration Wizard - Messages
Select Browse for schema file in front of the URL field.
The Type Chooser window is displayed.
Click the Import Schema Files button on the top right corner of the Type Chooser window. This opens the Import Schema File pop-up window.
Enter the schema location for the service, such as http://<soa_suite_hostname>:<port>/soa-infra/services/default/<jndi_name>_XMLGATEWAY_ONT__POI/ONT__POI_Service?XSD=xsd/PROCESS_PO_007.xsd
Schema location for your service can be found from the service WSDL URL (for example, http://<soa_suite_hostname>:<port>/soa-infra/services/default/<jndi_name>_XMLGATEWAY_ONT__POI/ONT__POI_Service?wsdl
).
Select the Copy to Project check box and click OK.
The Localize Files window appears. Ensure the Maintain original directory structure for imported files check box is selected and click OK.
The Imported Schema folder is automatically added to the Type Chooser window.
Expand the imported schema folder and select PROCESS_PO_007 from the PROCESS_PO_007.xsd
. Click OK. The selected PROCESS_PO_007.xsd
is displayed as URL and the PROCESS_PO_007 element is selected as Schema Element.
Click Next and then Finish. The wizard generates the WSDL file corresponding to the partner link. The main Create Partner Link dialog box appears, specifying the new WSDL file GetXMLMsg.wsdl
.
Click Apply and then OK to complete the configuration and create the partner link with the required WSDL settings for the File Adapter service.
The GetXMLMsg
Partner Link appears in the BPEL process diagram.
Under applications window, navigate to file GetXMLMsg_file.jca. Set value of property "DeleteFile" to "false".
This step is to configure three Invoke activities:
To get the XML message details that is received from the Receive activity by invoking the GetXMLMsg
partner link in an XML file.
To enqueue the purchase order information to the ECX_INBOUND queue by invoking ONT__POI
partner link in an XML file.
To add the first Invoke activity for a partner link to get XML message:
In Oracle JDeveloper, expand the BPEL Constructs from the Component Palette. Drag and drop the Invoke activity into the center swim lane of the process diagram, between the receiveInput and replyOutput activities.
Link the Invoke activity to the GetXMLMsg
service. The Edit Invoke dialog box appears.
Enter a name for the Invoke activity (such as 'Invoke_Msg') and then click the Create icon next to the Input Variable field to create a new variable. The Create Variable dialog box appears.
Enter an input variable name. You can also accept the default name. Select Global Variable and click OK.
Click the Create icon next to the Output Variable field to create a new variable. The Create Variable dialog box appears.
Enter an input variable name. You can also accept the default name. Select Global Variable and click OK.
Click Apply and then OK in the Edit Invoke dialog box to finish configuring the Invoke activity.
The first Invoke activity appears in the process diagram.
To add the second Invoke activity for a partner link to enqueue PO information:
In Oracle JDeveloper, expand the BPEL Constructs from the Component Palette. Drag and drop the second Invoke activity into the center swim lane of the process diagram, after the first Invoke activity and the reployOutput activity.
Link the Invoke activity to the ONT_POI
service. The Edit Invoke dialog box appears.
Enter a name for the Invoke activity and then click the Create icon next to the Input Variable field to create a new variable. The Create Variable dialog box appears.
Enter an input variable name. You can also accept the default name. Select Global Variable and click OK.
Click Apply and then OK in the Edit Invoke dialog box to finish configuring the Invoke activity.
The process diagram appears.
This step is to configure two Assign activities:
To pass XML message as an input to the Invoke activity for enqueuing message.
To pass XML Gateway header variables as input variables to the Invoke activity in order to provide context information for Oracle E-Business Suite.
To add the first Assign activity to pass XML message as input to the Invoke activity:
In Oracle JDeveloper, expand the BPEL Constructs from the Component Palette. Drag and drop the Assign activity into the center swim lane of the process diagram between the two Invoke activities you just created earlier.
Double-click the Assign activity to access the Edit Assign dialog box.
Click the General tab to enter the name for the Assign activity, such as 'SetOrderXML'.
Select the Copy Rules tab and expand the source and target trees:
In the From navigation tree, navigate to Variable > Process > Variables > Invoke_Msg_SynchRead_OutputVariable and select Process_PO_007.
In the To navigation tree, navigate to Variable > Process > Variables > Invoke_ONT__POI_InputVariable and select body.
Drag the source node (Process_PO_007) to connect to the target node (body) that you just identified. This creates a line that connects the source and target nodes. The copy rule is displayed in the From and To sections at the bottom of the Edit Assign dialog box.
Click Apply and then OK to complete the configuration of the Assign activity.
To add the second Assign activity to pass XML Gateway header variables to the Invoke activity:
In Oracle JDeveloper, expand the BPEL Constructs from the Component Palette. Drag and drop the Assign activity into the center swim lane of the process diagram between the first Assign and the second Invoke activities you just created earlier.
Add the second Assign activity by dragging and dropping the Assign activity into the center swim lane of the process diagram between the SetOrderXML
Assign activity and the second Invoke activity.
Repeat Step 2 to Step 3 described in creating the first Assign activity to add the second Assign activity called 'SetECXHeader'.
Select the Copy Rules tab and expand the source and target trees:
Click the Expression icon to invoke the Expression Builder dialog.
Enter 'XML' in the Expression box. Click OK. The Expression icon with the expression value ('XML') appears in the center of the Edit Assign dialog, between the From and To navigation tree nodes.
In the To navigation tree, navigate to Variable > Process > Variables > Invoke_ONT__POI_InputVariable > header > ns1:SOAHeader > ns4:ECXMSG and select MESSAGE_TYPE.
The XPath field should contain your selected entry.
Drag the Expression icon to connect to the target node (MESSAGE_TYPE) that you just identified. This creates a line that connects the source and target nodes. The copy rule is displayed in the From and To sections at the bottom of the Edit Assign dialog box.
Use the same mechanism described in step 3 to assign values to the following parameters:
MESSAGE_STANDARD: 'OAG'
TRANSACTION_TYPE: 'PO'
TRANSACTION_SUBTYPE: 'PROCESS'
DOCUMENT_NUMBER: 'PO-4466-5''
PARTY_SIDE_ID: 'Example-01'
Click Apply and OK to complete the configuration of the Assign activity.
Configuring Web Service Policies
Use the following steps to add security policies at design time:
Navigate to SOA Content > Business Rules > composite.xml. Right click on the ONT__POI
service and select "Configure WS Policies" from the drop-down list.
The Configure SOA WS Policies dialog appears.
In the Security section, click the Add icon (+). The Select Server Security Policies dialog appears.
Select Server Security Policies Dialog
Select 'oracle/wss_username_token_service_policy' and click OK.
The attached security policy is shown in the Security section.
A lock icon appears in the ONT__POI
service of the composite.xml
indicating that a security policy has been successfully attached.
From the navigation menu, select View > Property Inspector to display the Property Inspector window for ONT__POI
service component.
In the Properties section, click the Add icon (+) for binding properties. The Create Property dialog appears.
Enter 'oracle.webservices.auth.username
' in the Name field and enter 'operations' as the value.
Create Property Dialog
Click OK.
Use the same approach by clicking the Add icon (+) again in the Properties section for binding properties. Enter 'oracle.webservices.auth.password
' in the Name field. Enter the associated password for user 'operations' in the Value field.
Click OK.
Both selected property names and values appear in the Properties section.
Click the Source tab of composite.xml
and notice that the oracle.webservices.auth.username
and oracle.webservices.auth.password
property names and the associated values are added to the ONT__POI
reference.
Property Information Shown in the composite.xml File
To invoke the synchronous XML Gateway inbound map (PROCESS_PO_007) service from the BPEL client contained in the SOA composite, the SOA composite needs to be deployed to the Oracle WebLogic managed server. This can be achieved using Oracle JDeveloper. Once the composite is deployed, it can be tested from the Oracle Enterprise Manager Fusion Middleware Control Console.
Prerequisites
Before deploying the SOA composite with BPEL process using Oracle JDeveloper, you must have established the connectivity between the design-time environment and the run-time server. For information on how to configure the necessary server connection, see Configuring Server Connection, Oracle E-Business Suite Integrated SOA Gateway Developer's Guide.
Note: If a local instance of the WebLogic Server is used, start the WebLogic Server by selecting Run > Start Server Instance from Oracle JDeveloper. Once the WebLogic Admin Server "DefaultServer" instance is successfully started, the <Server started in Running mode> and DefaultServer started message in the Running:DefaultServer and Messages logs should appear.
To validate your BPEL process, perform the following run-time tasks:
You must deploy the SOA composite application with BPEL process (XMLGatewayInbound.bpel
) that you created earlier before you can run it.
Note: Before deploying the SOA composite application with BPEL Process for XML Gateway Inbound service, you should:
Load the order_data_xmlg.xml
file into the specified directory '/usr/tmp/' folder of SOA Suite server (or D:\HOL in case of SOA Server in Windows machine).
Edit the input file order_data_xmlg.xml
by entering values for <REFERENCEID> and <POID> such as 'order_xml_01'.
To deploy the SOA composite application with BPEL process:
In the Applications Navigator of Oracle JDeveloper, select the XMLGInbound project.
Right-click the project and select Deploy > [project name] > [serverConnection] from the menu.
For example, you can select Deploy > XMLGInbound > SOAServer to deploy the process if you have the connection appropriately.
Note: If this is the first time to set up the server connection, then the Deployment Action dialog appears. Select 'Deploy to Application Server' and click Next.
Deployment Action Dialog
In the Deploy Configuration dialog, ensure the following information is selected before clicking Next to add a new application server:
New Revision ID: 1.0
Mark composite revision as default: Select this check box.
Overwrite any existing composites with the same revision ID: Select this check box.
For information on how to create a new server connection for Oracle WebLogic Server, see Configuring Server Connection, Oracle E-Business Suite Integrated SOA Gateway Developer's Guide.
In the Select Server dialog, select 'soa-server1' that you have established the server connection earlier. Click Next.
Select Server Dialog
In the SOA Servers dialog, accept the default target SOA Server ('soa-server1') selection.
SOA Servers Dialog
Click Next and Finish.
If you are deploying the composite for the first time from your Oracle JDeveloper session, the Authorization Request window appears. Enter username and password information specified during Oracle SOA Suite installation. Click OK.
Deployment processing starts. Monitor deployment process and check for successful compilation in the SOA - Log window.
Verify that the deployment is successful in the Deployment - Log window.
Deployment - Log Tab
Once the BPEL process contained in the SOA composite application has been successfully deployed, you can manage and monitor the process from Oracle Enterprise Manager Fusion Middleware Control Console. You can also test the process and the integration interface by manually initiating the process.
For more information about Oracle SOA Suite, see the Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite.
To test the SOA composite application with BPEL process:
Navigate to Oracle Enterprise Manager Fusion Middleware Control Console (http://<hostname>:<port>/em
). The login page appears.
Enter the username and password information specified during the installation, and then click Login to log in to a farm. The composite (XMLGInbound) you deployed is displayed in the Applications Navigation tree.
You may need to select an appropriate target instance farm if there are multiple target Oracle Enterprise Manager Fusion Middleware Control Console farms.
From the Farm navigation pane, expand the SOA >soa-infra
node in the tree to navigate through the SOA Infrastructure home page and menu to access your deployed SOA composite applications running on soa-infra
managed server.
Click the XMLGInbound [1.0] link.
Click the Policies tab and notice that the 'oracle/wss_username_token_service_policy' policy you attached to the ONT__POI
service binding earlier at the design time is now displayed here.
In the XMLGInbound [1.0] home page, click Test.
The Test Web Service page for initiating an instance appears.
Note: If the WS-Security credentials are not entered at design time, you can enter the credentials at run time by selecting the WSS Username Token option in the Security section at the top of the Request tab. Enter 'operations' in the Username field and the associated password for user 'operations' in the Password field.
WS-Security Credentials in the Request Tab
Enter the input string (such as 'test') required by the process and click Test Web Service to initiate the process.
The test results appear in the Response tab upon completion.
Click the Instances tab. The SOA composite application instance ID, name, conversation ID, most recent known state of each instance since the last data refresh of the page are displayed.
Click your BPEL service component instance link (such as XMLGInbound) to display the Instances page where you can view execution details for the BPEL activities in the Audit Trail tab.
Click the Flow tab to check the BPEL process flow diagram. Click an activity of the process diagram to view the activity details and flow of the payload through the process.
Verifying Records in Oracle E-Business Suite
Once the BPEL process has been successfully initiated and completed, you can validate the transaction in Oracle E-Business Suite.
To Transmit the XML Payload Using Oracle Transport Agent (OTA)
Oracle Transport Agent is a lightweight messaging platform for transmitting documents over HTTP and Secure HTTP (HTTPS). Refer to Oracle Transport Agent for details.
Perform the following steps to attach the payload for the inbound transaction:
Navigate to the Oracle Transport Agent Inbound Test Page (http://<EBS hostname>:<port>/webservices/ECXOTAInbound
).
Important: As part of the January 2017 CPU update, the access to the Oracle Transport Agent Inbound Test Page is restricted to trusted nodes or servers. Therefore, to use this page to send an inbound XML message, you should add a fully-qualified node name or IP address as a trusted node in Oracle E-Business Suite. To extend access to additional hosts, perform the following tasks:
Add space-separated node names, fully qualified node names, or client machine IP addresses to the existing content of the s_admin_ui_access_nodes
context variable.
Run AutoConfig.
Restart the Oracle HTTP Server.
For more information, refer to the Known Issues section in My Oracle Support Knowledge Document 2212223.1, Oracle E-Business Suite Release 12 Critical Patch Update Knowledge Document (January 2017) for details.
Oracle Transport Agent Inbound Test Page
Enter the following information:
USERNAME: 'operations'
PASSWORD: Enter the associated password for the user 'operations'.
REQUEST_TYPE: SEND
MESSAGE_STANDARD: OAG
TRANSACTION_TYPE: PO
TRANSACTION_SUBTYPE: PROCESS
PARTYID: 1004
SOURCE_TP_LOCATION_CODE: Example-01
Enter the payload information in the Payload field and click Submit.
For the payload information, see Sample Payload for Inbound Process Purchase Order XML Transaction, Oracle E-Business Suite Integrated SOA Gateway Developer's Guide.
Specify Payload Information
The status code '1000' appears indicating that the request is successfully handled.
Successful Transmit the XML Payload
To Validate the Transaction in Oracle Transaction Monitor:
You can validate it from the Transaction Monitor. The Transaction Monitor is a tool for monitoring the status of inbound and outbound transactions originating from and going into Oracle E-Business Suite that have been processed by the XML Gateway and delivered or received by the Oracle Transport Agent. It shows a complete history and audit trail of these documents.
Log in to Oracle E-Business Suite as a user who has the Workflow Administrator Web Applications responsibility.
Select the Transaction Monitor link to open the search window to search for the order.
Clear From Date and To Date fields and enter 'PO-4466-5' in the Document ID field.
Select Customer as the Party Type. Click Go to execute the search.
This retrieves XML inbound transaction 'PO-4466-5' in the Inbound Search Results region.
Confirm that the transaction 'PO-4466-5' has status 'SUCCESS'.
You can verify it by logging in to Oracle E-Business Suite as a user who has the Order Management Super User, Vision Operations (USA) responsibility. Select Orders, Returns : Import Orders > Corrections. The Find Orders window is displayed and select 'XML' from drop-down list in the Order Source field. The Corrections window is displayed with all the transactions with the XML order source.
Notice that 'PO_4466-5' is listed in the Orig_Sys_Document_Reference field.
Corrections Window
To Import the Order to Oracle Order Management:
Log in to the Forms-based Oracle E-Business Suite as a user who has the Order Management Super User, Vision Operations (USA) responsibility.
Select Orders, Returns : Import Orders > Order Import Request. The Order Import Request window is displayed along with the Parameters dialog.
Select 'PO-4466-5' from the Order Reference drop-down list.
Order Import Request Window and Parameters Dialog
Click OK in the parameters dialog. The Order Import request name is populated automatically in the Import Request window.
Click Submit to submit the request. This displays a concurrent request number. Record the request number, but click No in the Decision dialog that you will not submit another request.
From the application menu, select View > Requests to open the Find Requests window.
Enter the request number you recorded earlier and click Find.
This would show the status of Order Import request. It should be success and the order should be created in Order Management application.
To Validate the Transaction in Oracle Order Management:
Log in to the Forms-based Oracle E-Business Suite as a user who has the Order Management, Super User responsibility.
Select Order Returns > Sales Order. The Sales Order Forms is displayed.
Search for an order by entering the order number in the Customer PO field (such as 'PO-4466-5'). The details of a newly created order appears.
Sales Orders Window
The following information shows the sample payload in the order_data_xmlg.xml
file:
<?xml version = '1.0' encoding = 'UTF-8' standalone = 'no'?> <!-- Oracle eXtensible Markup Language Gateway Server --> <!DOCTYPE PROCESS_PO_007 SYSTEM "003_process_po_007.dtd"> <PROCESS_PO_007> <CNTROLAREA> <BSR> <VERB>PROCESS</VERB> <NOUN>PO</NOUN> <REVISION>007</REVISION> </BSR> <SENDER> <LOGICALID>ORACLE</LOGICALID> <COMPONENT>PURCHASING</COMPONENT> <TASK>POISSUE</TASK> <REFERENCEID>MO4YD220.US.EXAMPLE.COM:oracle.apps.po.event.xmlpo:32636-148970</REFERENCEID> <CONFIRMATION>0</CONFIRMATION> <LANGUAGE>us</LANGUAGE> <CODEPAGE>UTF8</CODEPAGE> <AUTHID>APPS</AUTHID> </SENDER> <DATETIME qualifier="CREATION" type="T" index="1"> <YEAR>2011</YEAR> <MONTH>04</MONTH> <DAY>05</DAY> <HOUR>23</HOUR> <MINUTE>44</MINUTE> <SECOND>09</SECOND> <SUBSECOND>0000</SUBSECOND> <TIMEZONE>+0000</TIMEZONE> </DATETIME> <OPERAMT qualifier="EXTENDED" type="T"> <VALUE>1329432</VALUE> <NUMOFDEC>2</NUMOFDEC> <SIGN>+</SIGN> <CURRENCY>USD</CURRENCY> <UOMVALUE>1</UOMVALUE> <UOMNUMDEC>0</UOMNUMDEC> <UOM/> </OPERAMT> <POID>PO-4466-5</POID> <POTYPE>STANDARD</POTYPE> <ACKREQUEST>N</ACKREQUEST> <CONTRACTB/> <CONTRACTS/> <DESCRIPTN/> <PORELEASE/> <USERAREA><DATETIME qualifier="ACTSTART" type="T" index="1"><YEAR/><MONTH/><DAY/><HOUR/><MINUTE/><SECOND/><SUBSECOND/><TIMEZONE/></DATETIME><DATETIME qualifier="ACTEND" type="T" index="1"><YEAR/><MONTH/><DAY/><HOUR/><MINUTE/><SECOND/><SUBSECOND/><TIMEZONE/></DATETIME><DATETIME><FOB><DESCRIPTN>Vendor's responsibility ceases upon transfer to carrier</DESCRIPTN><TERMID>Origin</TERMID></FOB><TANDC/><FTTERM><DESCRIPTN>Buyer pays freight</DESCRIPTN><TERMID>Due</TERMID></FTTERM><EXCHRATE/><DATETIME qualifier="EXCHRATEDATE"><YEAR>2011</YEAR><MONTH>04</MONTH><DAY>05</DAY><HOUR>00</HOUR><MINUTE>00</MINUTE><SECOND>00</SECOND><SUBSECOND>0000</SUBSECOND><TIMEZONE>+0000</TIMEZONE></DATETIME><DATETIME ualifier="APPREQ" type="T" index="1"><YEAR/><MONTH/><DAY/><HOUR/><MINUTE/><SECOND/><SUBSECOND/><TIMEZONE/></DATETIME><CONFIRM>N</CONFIRM><SHIPPINGCONTROL/><DFFPOHEADER><ATTRIBUTE1/><ATTRIBUTE2/><ATTRIBUTE3/><ATTRIBUTE4/><ATTRIBUTE5/><ATTRIBUTE6/><ATTRIBUTE7/><ATTRIBUTE8/><ATTRIBUTE9/><ATTRIBUTE10/><ATTRIBUTE11/><ATTRIBUTE12/><ATTRIBUTE13/><ATTRIBUTE14/><ATTRIBUTE15/><ATTRIBUTE16/></DFFPOHEADER><PCARDHDR><MEMBERNAME/><PCARDNUM>0</PCARDNUM><DATETIME qualifier="EXPIRATION"><YEAR>2011</YEAR><MONTH>04</MONTH><DAY>05</DAY><HOUR>00</HOUR><MINUTE>00</MINUTE><SECOND>00</SECOND><SUBSECOND>0000</SUBSECOND><TIMEZONE>+0000</TIMEZONE></DATETIME><PCARDBRAND/></PCARDHDR></USERAREA> <PARTNER> <NAME index="1">Example Inc.</NAME> <ONETIME>0</ONETIME> <PARTNRID><PARTNRID/> <PARTNRTYPE>Supplier</PARTNRTYPE> <CURRENCY>USD</CURRENCY> <DUNSNUMBER/> <PARTNRIDX>Example-01</PARTNRIDX> <TAXID/> <TERMID/> <USERAREA><DFFVENDOR><ATTRIBUTE1/><ATTRIBUTE2/><ATTRIBUTE3/><ATTRIBUTE4/><ATTRIBUTE5/><ATTRIBUTE6/><ATTRIBUTE7/><ATTRIBUTE8/><ATTRIBUTE9/><ATTRIBUTE10/><ATTRIBUTE11/><ATTRIBUTE12/><ATTRIBUTE13/><ATTRIBUTE14/><ATTRIBUTE15/><ATTRIBUTE16/></DFFVENDOR><CUSTOMERNUM/></USERAREA> <ADDRESS> <ADDRLINE index="1"></ADDRLINE> <ADDRLINE index="2"/> <ADDRLINE index="3"/> <ADDRTYPE/> <CITY></CITY> <COUNTRY></COUNTRY> <COUNTY/> <DESCRIPTN></DESCRIPTN> <FAX index="1"/> <POSTALCODE></POSTALCODE> <REGION/> <STATEPROVN></STATEPROVN> <TAXJRSDCTN/> <TELEPHONE index="1"></TELEPHONE> <TELEPHONE index="2"/> <TELEPHONE index="3"/> <URL/> <USERAREA><DFFVENDORSITE><ATTRIBUTE1/><ATTRIBUTE2/><ATTRIBUTE3/><ATTRIBUTE4/><ATTRIBUTE5/><ATTRIBUTE6/><ATTRIBUTE7/><ATTRIBUTE8/><ATTRIBUTE9/><ATTRIBUTE10/><ATTRIBUTE11/><ATTRIBUTE12/><ATTRIBUTE13/><ATTRIBUTE14/><ATTRIBUTE15/><ATTRIBUTE16/></DFFVENDORSITE></USERAREA> </ADDRESS> <CONTACT> <NAME index="1"/> <EMAIL/> <FAX index="1"></FAX> <TELEPHONE index="1"></TELEPHONE> </CONTACT> </PARTNER> <PARTNER> <NAME index="1">Vision Operation</NAME> <ONETIME>0</ONETIME> <PARTNRID>204<PARTNRID/> <PARTNRTYPE>SoldTo</PARTNRTYPE> <CURRENCY>USD</CURRENCY> <DUNSNUMBER/> <PARTNRIDX>Example-01</PARTNRIDX> <PAYMETHOD/> <TAXID/> <TERMID/> <USERAREA/> <ADDRESS> </ADDRESS> <CONTACT> <NAME index="1">Lastname, Ms. Firstname</NAME> <CONTCTTYPE/> <DESCRIPTN/> <EMAIL>username@example.com</EMAIL> <FAX index="1"/> <TELEPHONE index="1"/> <USERAREA/> </CONTACT> </PARTNER> <PARTNER> <NAME index="1">Vision Operation</NAME> <ONETIME>0</ONETIME> <PARTNRID>204<PARTNRID/> <PARTNRTYPE>BillTo</PARTNRTYPE> <CURRENCY/> <DUNSNUMBER/> <PARTNRIDX>Eample-01</PARTNRIDX> <PAYMETHOD/> <TERMID/> <USERAREA/> <ADDRESS> </ADDRESS> </PARTNER> <PARTNER> <NAME index="1">UPS</NAME> <ONETIME>0</ONETIME> <PARTNRID>204<PARTNRID/> <PARTNRTYPE>Carrier</PARTNRTYPE> <PARTNRIDX>UPS</PARTNRIDX> </PARTNER> <POTERM> <DESCRIPTN>Scheduled for payment 30 days from the invoice date (invoice terms date = system date, goods received date, invoice date or invoice received date). Invoice terms date can default from supplier header, site, PO, system default, etc.</DESCRIPTN> <TERMID>30 Net (terms date + 30)</TERMID> <DAYSNUM/> <QUANTITY qualifier="PERCENT"> <VALUE/> <NUMOFDEC/> <SIGN/> <UOM/> </QUANTITY> <USERAREA/> </POTERM> </POORDERHDR> <POORDERLIN> <QUANTITY qualifier="ORDERED"> <VALUE>12</VALUE> <NUMOFDEC/> <SIGN>+</SIGN> <UOM>Ea</UOM> </QUANTITY> <OPERAMT qualifier="UNIT" type="T"> <VALUE>110786</VALUE> <NUMOFDEC>2</NUMOFDEC> <SIGN>+</SIGN> <CURRENCY>USD</CURRENCY> <UOMVALUE>1</UOMVALUE> <UOMNUMDEC>0</UOMNUMDEC> <UOM>Ea</UOM> </OPERAMT> <POLINENUM>1</POLINENUM> <HAZRDMATL/> <ITEMRV></ITEMRV> <ITEMRVX/> <POLNSTATUS/> <DESCRIPTN></DESCRIPTN> <ITEM>AS54888</ITEM> <ITEMX/> <USERAREA><REQUESTOR/><CATEGORYID>PRODUCTN.FINGOODS</CATEGORYID><CONTRACTNUM/><CONTRACTPONUM/><CONTRACTPOLINENUM/><VENDORQUOTENUM/><CONFIGID/><LISTPRICE>1107.86</LISTPRICE><MARKETPRICE>0</MARKETPRICE><PRICENOTTOEXCEED/><NEGPRICE>N</NEGPRICE><TAXABLE>N</TAXABLE><TXNREASONCODE/><TYPE1099>AVAN/N</TYPE1099><LINEORDERTYPE>Goods</LINEORDERTYPE><HAZRDUNNUM/><HAZRDUNDESC/><DFFLINE><ATTRIBUTE1/><ATTRIBUTE2/><ATTRIBUTE3/><ATTRIBUTE4/><ATTRIBUTE5/><ATTRIBUTE6/><ATTRIBUTE7/><ATTRIBUTE8/><ATTRIBUTE9/><ATTRIBUTE10/><ATTRIBUTE11/><ATTRIBUTE12/><ATTRIBUTE13/><ATTRIBUTE14/><ATTRIBUTE15/><ATTRIBUTE16/></DFFLINE><DFFITEM><ATTRIBUTE1/><ATTRIBUTE2/><ATTRIBUTE3/><ATTRIBUTE4/><ATTRIBUTE5/><ATTRIBUTE6/><ATTRIBUTE7/><ATTRIBUTE8/><ATTRIBUTE9/><ATTRIBUTE10/><ATTRIBUTE11/><ATTRIBUTE12/><ATTRIBUTE13/><ATTRIBUTE14/><ATTRIBUTE15/><ATTRIBUTE16/></DFFITEM><KFFITEM><ATTRIBUTE1>PRODUCTN</ATTRIBUTE1><ATTRIBUTE2>FINGOODS</ATTRIBUTE2><ATTRIBUTE3/><ATTRIBUTE4/><ATTRIBUTE5/><ATTRIBUTE6/><ATTRIBUTE7/><ATTRIBUTE8/><ATTRIBUTE9/><ATTRIBUTE10/><ATTRIBUTE11/><ATTRIBUTE12/><ATTRIBUTE13/><ATTRIBUTE14/><ATTRIBUTE15/><ATTRIBUTE16/><ATTRIBUTE17/><ATTRIBUTE18/><ATTRIBUTE19/><ATTRIBUTE20/></KFFITEM><GLOBALCONTRACT/><GLOBALCONTRACTLIN/><JOBTITLE/><AMOUNT qualifier="TOTAL" type="T"><VALUE/><NUMOFDEC/><SIGN/><CURRENCY/><DRCR>C</DRCR></AMOUNT><CONTRACTORFIRSTNAME/><CONTRACTORLASTNAME/><DATETIME qualifier="ACTSTART" type="T" index="1"><YEAR/><MONTH/><DAY/><HOUR/><MINUTE/><SECOND/><SUBSECOND/><TIMEZONE/></DATETIME><DATETIME qualifier="ACTEND" type="T" index="1"><YEAR/><MONTH/><DAY/><HOUR/><MINUTE/><SECOND/><SUBSECOND/><TIMEZONE/></DATETIME></USERAREA> <POLINESCHD> <DATETIME qualifier="NEEDDELV" type="T" index="1"> <YEAR>2011</YEAR> <MONTH>04</MONTH> <DAY>21</DAY> <HOUR>00</HOUR> <MINUTE>00</MINUTE> <SECOND>00</SECOND> <SUBSECOND>0000</SUBSECOND> <TIMEZONE>+0000</TIMEZONE> </DATETIME> <QUANTITY qualifier="ORDERED"> <VALUE>12</VALUE> <NUMOFDEC/> <SIGN>+</SIGN> <UOM>Ea</UOM> </QUANTITY> <DESCRIPTN/> <PSCLINENUM>1</PSCLINENUM> <USERAREA><DATETIME qualifier="PROMSHIP"><YEAR/><MONTH/><DAY/><HOUR/><MINUTE/><SECOND/><SUBSECOND/><TIMEZONE/></DATETIME><DATETIME qualifier="APPROVAL"><YEAR/><MONTH/><DAY/><HOUR/><MINUTE/><SECOND/><SUBSECOND/><TIMEZONE/></DATETIME><OPERAMT qualifier="UNIT" type="T"><VALUE>110786</VALUE><NUMOFDEC>2</NUMOFDEC><SIGN>+</SIGN><CURRENCY>USD</CURRENCY><UOMVALUE>1</UOMVALUE><UOMNUMDEC>0</UOMNUMDEC><UOM>Ea</UOM></OPERAMT><PRICEOVRRD/><TAXABLE>N</TAXABLE><TAXCODE/><PARTNER><NAME index="1">Vision Operations</NAME><ONETIME>0</ONETIME><PARTNRID>204</PARTNRID><PARTNRTYPE>ShipTo</PARTNRTYPE><CURRENCY>USD</CURRENCY><DUNSNUMBER/><PARTNRIDX>Example-01</PARTNRIDX><PAYMETHOD/><TERMID/><USERAREA/> <ADDRESS></ADDRESS> <CONTACT><NAME index="1"/><CONTCTTYPE/><EMAIL/><FAX index="1"/><TELEPHONE index="1"/></CONTACT> </PARTNER> <PARTNER><NAME index="1"/><ONETIME/><PARTNRID/><PARTNRTYPE>DeliveryTo</PARTNRTYPE><PARTNRIDX/><USERAREA/><ADDRESS><ADDRLINE index="1"/><ADDRLINE index="2"/><ADDRTYPE/></ADDRESS><CONTACT><NAME index="1"/><CONTCTTYPE/><EMAIL/><FAX index="1"/><TELEPHONE index="1"/> </CONTACT></PARTNER><DROPSHIPDETAILS><DROPSHIPMENT/><DROPSHIPCUSTNAME/><SHIPINSTR/><PACKINSTR/><SHIPMETHOD/><CUSTOMERPONUM/><CUSTOMERLINENUM/><CUSTOMERSHIPNUM/><CUSTOMERDESC/></DROPSHIPDETAILS><CONSIGNEDINV>N</CONSIGNEDINV><DISTPROJECT><REQUESTOR/><DISTNUM>1</DISTNUM><PROJECTNUM/><PROJECTTYPE/><TASKNUM/><QUANTITY qualifier="ORDERED"><VALUE>12</VALUE><NUMOFDEC/><SIGN>+</SIGN><UOM>Ea</UOM></QUANTITY><CONVRATE/><DATETIME qualifier="EXCHRATEDATE"><YEAR>2011</YEAR><MONTH>04</MONTH><DAY>05</DAY><HOUR>00</HOUR><MINUTE>00</MINUTE><SECOND>00</SECOND><SUBSECOND>0000</SUBSECOND><TIMEZONE>+0000</TIMEZONE></DATETIME><DESTTYPE>INVENTORY</DESTTYPE><DFFDISTRIBUTN><ATTRIBUTE1/><ATTRIBUTE2/><ATTRIBUTE3/><ATTRIBUTE4/><ATTRIBUTE5/><ATTRIBUTE6/><ATTRIBUTE7/><ATTRIBUTE8/><ATTRIBUTE9/><ATTRIBUTE10/><ATTRIBUTE11/><ATTRIBUTE12/><ATTRIBUTE13/><ATTRIBUTE14/><ATTRIBUTE15/><ATTRIBUTE16/></DFFDISTRIBUTN></DISTPROJECT><AMOUNT qualifier="TOTAL" type="T"><VALUE/><NUMOFDEC/><SIGN/><CURRENCY/><DRCR>C</DRCR></AMOUNT></USERAREA> </POLINESCHD> </POORDERLIN> <POORDERLIN> <QUANTITY qualifier="ORDERED"> <VALUE>13</VALUE> <NUMOFDEC/> <SIGN>+</SIGN> <UOM>Ea</UOM> </QUANTITY> <OPERAMT qualifier="UNIT" type="T"> <VALUE>110786</VALUE> <NUMOFDEC>2</NUMOFDEC> <SIGN>+</SIGN> <CURRENCY>USD</CURRENCY> <UOMVALUE>1</UOMVALUE> <UOMNUMDEC>0</UOMNUMDEC> <UOM>Ea</UOM> </OPERAMT> <POLINENUM>2</POLINENUM> <HAZRDMATL/> <ITEMRV></ITEMRV> <ITEMRVX/> <POLNSTATUS/> <DESCRIPTN></DESCRIPTN> <ITEM>ASO0021</ITEM> <ITEMX/> <USERAREA><REQUESTOR/><CATEGORYID>PRODUCTN.FINGOODS</CATEGORYID><CONTRACTNUM/><CONTRACTPONUM/><CONTRACTPOLINENUM/><VENDORQUOTENUM/><CONFIGID/><LISTPRICE>1107.86</LISTPRICE><MARKETPRICE>0</MARKETPRICE><PRICENOTTOEXCEED/><NEGPRICE>N</NEGPRICE><TAXABLE>N</TAXABLE><TXNREASONCODE/><TYPE1099>AVAN/N</TYPE1099><LINEORDERTYPE>Goods</LINEORDERTYPE><HAZRDUNNUM/><HAZRDUNDESC/><DFFLINE><ATTRIBUTE1/><ATTRIBUTE2/><ATTRIBUTE3/><ATTRIBUTE4/><ATTRIBUTE5/><ATTRIBUTE6/><ATTRIBUTE7/><ATTRIBUTE8/><ATTRIBUTE9/><ATTRIBUTE10/><ATTRIBUTE11/><ATTRIBUTE12/><ATTRIBUTE13/><ATTRIBUTE14/><ATTRIBUTE15/><ATTRIBUTE16/></DFFLINE><DFFITEM><ATTRIBUTE1/><ATTRIBUTE2/><ATTRIBUTE3/><ATTRIBUTE4/><ATTRIBUTE5/><ATTRIBUTE6/><ATTRIBUTE7/><ATTRIBUTE8/><ATTRIBUTE9/><ATTRIBUTE10/><ATTRIBUTE11/><ATTRIBUTE12/><ATTRIBUTE13/><ATTRIBUTE14/><ATTRIBUTE15/><ATTRIBUTE16/></DFFITEM><KFFITEM><ATTRIBUTE1>PRODUCTN</ATTRIBUTE1><ATTRIBUTE2>FINGOODS</ATTRIBUTE2><ATTRIBUTE3/><ATTRIBUTE4/><ATTRIBUTE5/><ATTRIBUTE6/><ATTRIBUTE7/><ATTRIBUTE8/><ATTRIBUTE9/><ATTRIBUTE10/><ATTRIBUTE11/><ATTRIBUTE12/><ATTRIBUTE13/><ATTRIBUTE14/><ATTRIBUTE15/><ATTRIBUTE16/><ATTRIBUTE17/><ATTRIBUTE18/><ATTRIBUTE19/><ATTRIBUTE20/></KFFITEM><GLOBALCONTRACT/><GLOBALCONTRACTLIN/><JOBTITLE/><AMOUNT qualifier="TOTAL" type="T"><VALUE/><NUMOFDEC/><SIGN/><CURRENCY/><DRCR>C</DRCR></AMOUNT><CONTRACTORFIRSTNAME/><CONTRACTORLASTNAME/><DATETIME qualifier="ACTSTART" type="T" index="1"><YEAR/><MONTH/><DAY/><HOUR/><MINUTE/><SECOND/><SUBSECOND/><TIMEZONE/></DATETIME><DATETIME qualifier="ACTEND" type="T" index="1"><YEAR/><MONTH/><DAY/><HOUR/><MINUTE/><SECOND/><SUBSECOND/><TIMEZONE/></DATETIME></USERAREA> <POLINESCHD> <DATETIME qualifier="NEEDDELV" type="T" index="1"> <YEAR>2011</YEAR> <MONTH>04</MONTH> <DAY>21</DAY> <HOUR>00</HOUR> <MINUTE>00</MINUTE> <SECOND>00</SECOND> <SUBSECOND>0000</SUBSECOND> <TIMEZONE>+0000</TIMEZONE> </DATETIME> <QUANTITY qualifier="ORDERED"> <VALUE>12</VALUE> <NUMOFDEC/> <SIGN>+</SIGN> <UOM>Ea</UOM> </QUANTITY> <DESCRIPTN/> <PSCLINENUM>1</PSCLINENUM> <USERAREA><DATETIME qualifier="PROMSHIP"><YEAR/><MONTH/><DAY/><HOUR/><MINUTE/><SECOND/><SUBSECOND/><TIMEZONE/></DATETIME><DATETIME qualifier="APPROVAL"><YEAR/><MONTH/><DAY/><HOUR/><MINUTE/><SECOND/><SUBSECOND/><TIMEZONE/></DATETIME><OPERAMT qualifier="UNIT" type="T"><VALUE>110786</VALUE><NUMOFDEC>2</NUMOFDEC><SIGN>+</SIGN><CURRENCY>USD</CURRENCY><UOMVALUE>1</UOMVALUE><UOMNUMDEC>0</UOMNUMDEC><UOM>Ea</UOM></OPERAMT><PRICEOVRRD/><TAXABLE>N</TAXABLE><TAXCODE/><PARTNER><NAME index="1">Vision Operations</NAME><ONETIME>0</ONETIME><PARTNRID>204</PARTNRID><PARTNRTYPE>ShipTo</PARTNRTYPE><CURRENCY>USD</CURRENCY><DUNSNUMBER/><PARTNRIDX>Example-01</PARTNRIDX><PAYMETHOD/><TERMID/><USERAREA/> <ADDRESS></ADDRESS> <CONTACT><NAME index="1"/><CONTCTTYPE/><EMAIL/><FAX index="1"/><TELEPHONE index="1"/></CONTACT> </PARTNER> <PARTNER><NAME index="1"/><ONETIME/><PARTNRID/><PARTNRTYPE>DeliveryTo</PARTNRTYPE><PARTNRIDX/><USERAREA/><ADDRESS><ADDRLINE index="1"/><ADDRLINE index="2"/><ADDRTYPE/></ADDRESS><CONTACT><NAME index="1"/><CONTCTTYPE/><EMAIL/><FAX index="1"/><TELEPHONE index="1"/></CONTACT></PARTNER><DROPSHIPDETAILS><DROPSHIPMENT/><DROPSHIPCUSTNAME/><SHIPINSTR/><PACKINSTR/><SHIPMETHOD/><CUSTOMERPONUM/><CUSTOMERLINENUM/><CUSTOMERSHIPNUM/><CUSTOMERDESC/></DROPSHIPDETAILS><CONSIGNEDINV>N</CONSIGNEDINV><DISTPROJECT><REQUESTOR/><DISTNUM>1</DISTNUM><PROJECTNUM/><PROJECTTYPE/><TASKNUM/><QUANTITY qualifier="ORDERED"><VALUE>12</VALUE><NUMOFDEC/><SIGN>+</SIGN><UOM>Ea</UOM></QUANTITY><CONVRATE/><DATETIME qualifier="EXCHRATEDATE"><YEAR>2011</YEAR><MONTH>04</MONTH><DAY>05</DAY><HOUR>00</HOUR><MINUTE>00</MINUTE><SECOND>00</SECOND><SUBSECOND>0000</SUBSECOND><TIMEZONE>+0000</TIMEZONE></DATETIME><DESTTYPE>INVENTORY</DESTTYPE><DFFDISTRIBUTN><ATTRIBUTE1/><ATTRIBUTE2/><ATTRIBUTE3/><ATTRIBUTE4/><ATTRIBUTE5/><ATTRIBUTE6/><ATTRIBUTE7/><ATTRIBUTE8/><ATTRIBUTE9/><ATTRIBUTE10/><ATTRIBUTE11/><ATTRIBUTE12/><ATTRIBUTE13/><ATTRIBUTE14/><ATTRIBUTE15/><ATTRIBUTE16/></DFFDISTRIBUTN></DISTPROJECT><AMOUNT qualifier="TOTAL" type="T"><VALUE/><NUMOFDEC/><SIGN/><CURRENCY/><DRCR>C</DRCR></AMOUNT></USERAREA> </POLINESCHD> </POORDERLIN> </PROCESS_PO> </DATAAREA> </PROCESS_PO_007>
This section includes the following topics:
For an outbound XML Gateway Map interface, since an outbound message is first enqueued to the ECX_OUTBOUND queue, Oracle BPEL PM listens to ECX_OUTBOUND queue for the message with the same correlation Id.
Oracle E-Business Suite Integrated SOA Gateway supports it through subscription model by dequeuing the message in the ECX_OUTBOUND queue to retrieve outbound data from Oracle E-Business Suite. The retrieved data can be passed to trading partners or consumers who subscribed to the message.
SOA Composite Application with BPEL Process Scenario
Take XML Gateway outbound interface 'PO acknowledgement XML Transaction' as an example. The XML Gateway outbound interface is exposed as a Web service through ECX_CBODO_OAG72_OUT
outbound map.
When a purchase order is created and approved, on approval of the purchase order, a workflow will be triggered which creates the Purchase Order Acknowledgement flow and sends out the PO Acknowledgement as an XML file. The workflow delivers the Confirm BOD as the PO Acknowledgement to ECX_OUTBOUND queue for delivery to the other system.
The correlation Id for this message is set to 'BPEL' and the Oracle BPEL PM listens to ECX_OUTBOUND queue for the message with the correlation Id = 'BPEL'. 'Confirm BOD' as the PO Acknowledgement is written as an output XML file using File Adapter.
When the BPEL process has been successfully executed after deployment, the same order book reference ID (Customer PO) from the output XML file should be obtained once a purchase order is approved.
Prerequisites to Create a SOA Composite Application with BPEL Process Using XML Gateway Outbound Messaging
You need to set up the correlation identifier in Oracle E-Business Suite. The correlation identifier enables you to label messages meant for a specific agent, in case there are multiple agents listening on the outbound queue. The agent listening for a particular correlation picks up the messages that match the correlation identifier for the agent.
To set up the correlation identifier:
Log in to Oracle E-Business Suite as a user who has the XML Gateway responsibility.
Click the XML Gateway link from the Navigator.
Click the Define Lookup Values link under XML Gateway.
XML Gateway Lookups Window
Search for COMM_METHOD
in the Type field to see if it exists in the system.
Add a new record to the COMM_METHOD
type by entering BPEL
for the Code field and the Meaning field. Enter description information and save the record.
Oracle XML Gateway puts the correlation of BPEL when enqueueing the message on the ECX_OUTBOUND queue.
In addition to having the correlation identifier set up correctly, ensure the trading partner that you want to use has the Protocol Type field set to BPEL
. For information on how to set up the trading partner with desired transactions, see Manually Testing the SOA Composite Application with BPEL Process.
SOA Composite Application with BPEL Process Creation Flow
Based on the PO acknowledgement XML Transaction scenario, the following design-time tasks are discussed in this chapter:
Create a New SOA Composite Application with BPEL Process
Use this step to create a new SOA composite application with BPEL process called XMLGOutbound.bpel
.
Create a Partner Link for AQ Adapter
Use this step to dequeue the event details from the ECX_OUTBOUND queue.
Use the Receive activity to take PO acknowledgement details as an input to the Assign activity.
Add a Partner Link for File Adapter
This is to write PO acknowledgement details in an XML file as an output file.
This is to write PO acknowledgement information to an XML file through invoking the partner link for File Adapter.
Use the Assign activity to take the output from the Receive activity and to provide input to the Invoke activity.
For general information and how to create SOA composite applications using BPEL process service component, see the Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite for details.
Use this step to create a new SOA composite application that will contain various BPEL process activities.
To create a new SOA composite application with BPEL process:
Open Oracle JDeveloper.
Click New Application in the Application Navigator. The "Create SOA Application - Name your application" page is displayed.
Enter an appropriate name for the application in the Application Name field and select SOA Application from the Application Template list.
Click Next. The "Create SOA Application - Name your project" page is displayed.
Enter an appropriate name for the project in the Project Name field. For example, XMLGatewayOutbound
.
In the Project Technologies tab, select 'Web Services' and ensure that SOA is selected from the Available technology list to the Selected technology list.
Click Next. The "Create SOA Application - Configure SOA settings" page is displayed.
Select Composite With BPEL Process from the Composite Template list, and then click Finish. You have created a new application, and a SOA project. This automatically creates a SOA composite.
The Create BPEL Process page is displayed.
Leave the default BPEL 1.1 Specification selection unchanged. This creates a BPEL project that supports the BPEL 1.1 specification.
Enter an appropriate name for the BPEL process in the Name field. For example, XMLGOutbound
.
Select Synchronous BPEL Process in the Template field.
Select required from the Transaction drop-down list. Click OK.
A synchronous BPEL process is created with the Receive and Reply activities. The required source files including bpel and wsdl, using the name you specified (for example, XMLGOutbound.bpel
and XMLGOutbound.wsdl
) and composite.xml
are also generated.
Navigate to SOA Content > Business Rules and double click composite.xml
to view the composite diagram.
Composite Diagram
Double click on the XMLGOutbound
component to open the BPEL process.
Use this step to create a Partner Link called GetAck
for AQ Adapter to dequeue the XML Gateway outbound message (for example, ECX_CBODO_OAG72_OUT
) in the ECX_OUTBOUND
queue.
To create a partner link for AQ Adapter:
In Oracle JDeveloper, drag and drop the AQ Adapter service from the BPEL Services list into the right Partner Link swim lane of the process diagram. The Adapter Configuration wizard welcome page appears.
Click Next. The Service Name dialog box appears.
Enter a service name in the Service Name dialog box, for example GetAck
.
Adapter Configuration Wizard - Service Name
Click Next. The Service Connection dialog box appears.
You can use an existing database connection by selecting a database connection from the Connection list or define a new database connection by clicking New to open the Create Database Connection Wizard.
Note: You need to connect to the database where Oracle E-Business Suite is running.
To create a new database connection:
Click New to open the Create Database Connection Wizard. Click Next and enter an unique connection name and then select a connection type, such as Oracle (JDBC), for the database connection. Click Next.
Enter appropriate username and password information to authenticate the database connection in the Authentication dialog box. Click Next.
Specify the following information in the Connection dialog box:
Driver: Thin
Host Name: Enter the host name for the database connection. For example, myhost01.example.com
.
JDBC Port: Enter JDBC port number (such as 1521
) for the database connection.
SID: Specify an unique SID value for the database connection.
Click Next to test your database connection.
The status message "Success!"
indicates a valid connection.
Click Next to return to the Service Connection dialog box providing a summary of the database connection.
The JNDI (Java Naming and Directory Interface) name corresponding to the database connection you specified appears automatically in the JNDI Name field of the Service Connection dialog box. Alternatively, you can enter a different JNDI name.
Click Next to open Adapter Interface dialog box.
Select the Define from operation and schema (specified later) radio button and click Next. The Operation dialog box appears.
Select the Dequeue radio button in the Operation Type field. 'Dequeue' is also populated in the Operation Name field.
Adapter Configuration Wizard - Operation
Click Next to open the Queue Name dialog box.
Select 'APPLSYS' as the Database Schema field. Enter 'ECX_OUTBOUND' as the Queue Name field.
AQ Adapter Configuration Wizard - Queue Name
Click Next to open the Queue Parameters dialog box.
Enter a unique customer name, such as 'Example Inc.', in the Correction Id field. Click Next. The Messages dialog box opens.
Click Browse for schema file to open the Type Chooser window.
Click Import Schema Files on the top right corner of the Type Chooser window. This opens the Import Schema File pop-up window.
Click the Browse Resources... icon to display the SOA Resource Browser window. Select the xsd folder as the location and CONFIRM_BOD_004.xsd
file from the folder.
SOA Resource Browser Window for Importing a Desired Schema
Click OK. The Localize Files dialog box opens. Click OK.
In the Type Chooser window, the selected CONFIRM_BOD_004.xsd
file is displayed. Scroll down to select elect CONFIRM_BOD_004
schema from the CONFIRM_BOD_004.xsd
. Click OK.
Type Chooser Dialog
The Messages dialog box is automatically displayed with the selected schema location and schema element.
AQ Adapter Configuration Wizard - Messages
Click Next to proceed to the Finish dialog box to confirm that you have finished defining the AQ Adapter for the GetAck
service.
Click Finish. The wizard generates the WSDL file corresponding to the GetAck
service.
Click Apply and then OK to complete the partner link configuration. The partner link is created with the required WSDL settings, and is represented in the BPEL project by a new icon in the border area of the process diagram.
This step is to configure a Receive activity to receive XML data from the partner link GetAck
that you configured for the AQ adapter.
The XML data received from the Receive activity is used as an input variable to the Assign activity that will be created in the next step.
To add a Receive activity:
In Oracle JDeveloper, expand the BPEL Constructs from the Component Palette. Drag and drop the Receive activity into the center swim lane of the process diagram.
Link the Receive activity to the GetAck
partner link. The Receive activity will take event data from the partner link. The Edit Receive dialog box appears.
Enter a name for the Receive activity.
Click the Create icon next to the Variable field to create a new variable. The Create Variable dialog box appears.
Select Global Variable, and then enter a name for the variable. You can accept the default name. Click OK to return to the Edit Receive dialog box.
Edit Receive Dialog
Click Apply and OK to finish configuring the Receive activity.
The Receive activity appears in the BPEL process diagram.
Use this step to configure a partner link by writing the purchase order acknowledgement to an XML file.
To add a Partner Link for File Adapter:
In Oracle JDeveloper, drag and drop the File Adapter service from the BPEL Services list into the right Partner Link swim lane of the process diagram. The Adapter Configuration wizard appears.
Click Next. The Service Name dialog box appears.
Enter a name for the File Adapter service, such as WriteAck
.
Click Next and the Adapter Interface dialog box appears.
Select the Define from operation and schema (specified later) radio button and click Next. The Operation dialog box appears.
Specify the operation type, for example Write File. This automatically populates the Operation Name field.
Adapter Configuration Wizard - Operation
Click Next to access the File Configuration dialog box.
File Adapter Configuration Wizard - File Configuration
For the Directory specified as field, select Logical Path. Enter directory path in the Directory for Outgoing Files field, and specify a naming convention for the output file such as PO_%yyMMddHHmmss%.xml
.
Confirm the default write condition: Number of Messages Equals 1. Click Next. The Messages dialog box appears.
Select the Browse check box to locate the schema location and schema element.
The Type Chooser dialog box appears. Expand the Project Schema Files > CONFIRM_BOD_004.xsd and select CONFIRM_BOD_004
.
Type Chooser
Click OK in the Type Chooser window to populate the selected schema location and element in the Messages dialog box.
File Adapter Configuration Wizard - Messages
Click Next and then Finish. The wizard generates the WSDL file corresponding to the partner link. The main Create Partner Link dialog box appears, specifying the new WSDL file WriteAck.wsdl
.
Click Apply and then OK to complete the configuration and create the partner link with the required WSDL settings for the File Adapter Service.
The WriteAck
Partner Link appears in the BPEL process diagram.
This step is to configure an Invoke activity to send the purchase order acknowledgement that is received from the Receive activity to the WriteAck
partner link in an XML file.
To add an Invoke activity:
In Oracle JDeveloper, expand the BPEL Constructs from the Component Palette. Drag and drop the Invoke activity into the center swim lane of the process diagram, after the Receive activity.
Link the Invoke activity to the WriteAck
service. The Invoke activity will send event data to the partner link. The Edit Invoke dialog box appears.
Enter a name for the Invoke activity, and then click the Create icon next to the Input Variable field to create a new variable. The Create Variable dialog box appears.
Select Global Variable, and then enter a name for the variable. You can also accept the default name. Click OK.
Edit Invoke Dialog
Click Apply and then OK in the Edit Invoke dialog box to finish configuring the Invoke activity.
The Invoke activity appears in the process diagram.
Use this step to pass the purchase order acknowledgement details from the Receive activity to the Invoke activity.
To add an Assign activity:
In Oracle JDeveloper, expand the BPEL Constructs from the Component Palette. Drag and drop the Assign activity from the Component Palette into the center swim lane of the process diagram, between the Receive activity and the Invoke activity.
Double-click the Assign activity to access the Edit Assign dialog box.
Select the Copy Rules tab and expand the source and target trees:
In the From navigation tree, navigate to Variable > Process > Variables > Receive_DEQUEUE_InputVariable and select CONFIRM_BOD_004. The XPath field contains your selected entry.
In the To navigation tree, navigate to Variable > Process > Variables > Invoke_Write_InputVariable > body and select CONFIRM_BOD_004. The XPath field contains your selected entry.
Edit Assign Dialog
Drag the source node (CONFIRM_BOD_004) to connect to the target node (CONFIRM_BOD_004) that you just identified. This creates a line that connects the source and target nodes. The copy rule is displayed in the From and To sections at the bottom of the Edit Assign dialog box.
Click Apply and then OK in the Edit Assign dialog box to complete the configuration of the Assign activity.
After creating a SOA composite application with BPEL process for XML Gateway outbound message map, you need to deploy it to the Oracle WebLogic managed server. This can be achieved using Oracle JDeveloper. Once the composite is deployed, it can be tested from the Oracle Enterprise Manager Fusion Middleware Control Console.
Prerequisites
Before deploying the SOA composite with BPEL process using Oracle JDeveloper, you must have established the connectivity between the design-time environment and the run-time server. For information on how to configure the necessary server connection, see Configuring Server Connection, Oracle E-Business Suite Integrated SOA Gateway Developer's Guide.
Note: If a local instance of the WebLogic Server is used, start the WebLogic Server by selecting Run > Start Server Instance from Oracle JDeveloper. Once the WebLogic Admin Server "DefaultServer" instance is successfully started, the <Server started in Running mode> and DefaultServer started message in the Running:DefaultServer and Messages logs should appear.
Perform the following run-time tasks:
You must deploy the SOA composite application with BPEL Process (XMLGOutbound.bpel
) that you created earlier before you can run it.
To deploy the SOA composite application with BPEL process:
In the Applications Navigator of Oracle JDeveloper, select the XMLGOutbound project.
Right-click the project and select Deploy > [project name] > [serverConnection] from the menu.
For example, you can select Deploy > XMLGInbound > SOAServer to deploy the process if you have the connection appropriately.
Note: If this is the first time to set up the server connection, then the Deployment Action dialog appears. Select 'Deploy to Application Server' and click Next.
Deployment Action Dialog
In the Deploy Configuration dialog, ensure the following information is selected before clicking Next to add a new application server:
New Revision ID: 1.0
Mark composite revision as default: Select this check box.
Overwrite any existing composites with the same revision ID: Select this check box.
For information on how to create a new server connection for Oracle WebLogic Server, see Configuring Server Connection, Oracle E-Business Suite Integrated SOA Gateway Developer's Guide.
In the Select Server dialog, select 'soa-server1' that you have established the server connection earlier. Click Next.
Select Server Dialog
In the SOA Servers dialog, accept the default target SOA Server ('soa-server1') selection.
SOA Servers Dialog
Click Next and Finish.
If you are deploying the composite for the first time from your Oracle JDeveloper session, the Authorization Request window appears. Enter username and password information specified during Oracle SOA Suite installation. Click OK.
Deployment processing starts. Monitor deployment process and check for successful compilation in the SOA - Log window.
Verify that the deployment is successful in the Deployment - Log window.
Once the BPEL process contained in the SOA composite application has been successfully deployed, you can manage and monitor the process from Oracle Enterprise Manager Fusion Middleware Control Console. You can log on to Oracle E-Business Suite to manually create and book the order as well as generate the order acknowledgement by submitting a Workflow Background Process concurrent request.
Log on to the Oracle Enterprise Manager Fusion Middleware Control Console to validate the BPEL process which writes purchase order acknowledgement in an output directory after receiving from the XML Gateway ECX_OUTBOUND queue.
To manually test the SOA composite application with BPEL process:
Log in to Oracle E-Business Suite as a user who has the XML Gateway responsibility.
This is to ensure that the XML Gateway trading partner is set up correctly so that a purchase order can have a valid customer that has been defined.
Select Define Trading Partner from the navigation menu to access the Trading Partner Setup window.
Enter the header values on the Trading Partner Setup form as follows:
Trading Partner Type: Customer
Trading Partner Name: For example, Example Inc.
Trading Partner Site: Enter a trading partner site information, for example, 401 Island Parkway Redwood Shores, CA 94065.
Company Admin Email: Enter a valid email address.
Enter the following trading partner details:
Transaction Type: ECX
Transaction SubType: CBODO
Standard Code: OAG
External Transaction Type: BOD
External Transaction SubType: CONFIRM
Direction: Out
Map: ECX_CBODO_OAG72_OUT
Connection / Hub: DIRECT
Protocol Type: BPEL
Username: 'operations'
Password: Enter the associated password for the user 'operations' twice.
Protocol Address: 'http://us.example.com'
Protocol Address is the complete URL where the XML document can be posted.
Source Trading Partner Location Code: Example-01
Trading Partner Setup Form
Save the trading partner details.
To successfully generated PO Acknowledgement, perform the following setup tasks in Order Management and then manually book the order:
Switch responsibility back to Order Management Super User, Vision Operations (USA) and select Customer > Standard from the navigation menu to open the Enter Customer form.
Search on the 'Example Inc.' in the Name field and click Go.
Select the Business World with the following information from the search results:
Name: Example Inc.
Registry ID: 1004
Address: 401 Island Parkway Redwood Shores, CA 94065
Select the account with the following information:
Account Number: 1004
Account Description: Example Inc.
Status: Active
Click the Details icon to open the Update Account: 1608 page.
Locate the address with 401 Island Parkway Redwood Shores, CA 94065 and click the Details icon to open the Site page of your selected account.
In the Site Details tab, the Account Site Details region, enter 'Example-01' in the EDI Location field.
In the Business Purposes tab, create a new row with the following values:
Purpose: Sold To
Check on the 'Primary' Check box
Click Apply.
Use the following steps to generate acknowledgement for the order that you have created for the XML Gateway Inbound service.
With the same Order Management Super User, Vision Operations (USA) responsibility, select Order Returns > Sales Order to open the Sales Order form.
Retrieve the order that you have created earlier in the XML Gateway inbound service by entering the order ID 'PO-4466-5' in the Customer PO field.
Click Book Order to book the order.
Notice that the Status field is now changed to 'Booked'.
Sales Orders Form
Switch to the System Administrator responsibility and select Request > Run.
Select Single Request and click OK.
Enter the following information in the Submit Request form:
Submit Request Form and Parameters Dialog
Name: Workflow Background Process
Enter the following parameters:
Item Type: OM Send Acknowledgement
Process Deferred: Yes
Process Timeout: No
Process Stuck: No
Click OK.
Click Submit to submit the 'send acknowledgement' request.
View your request by entering the request ID to ensure its status is 'Success'.
Validation Using Oracle Enterprise Manager Fusion Middleware Control Console
Log on to Oracle Enterprise Manager Fusion Middleware Control Console (http://<servername>:<portname>/em
) to confirm that the XMLGOutbound
process has been deployed. This process is continuously polling the ECX_OUTBOUND queue for purchase order acknowledgement.
From the Farm navigation pane, expand the SOA > soa-infra
node in the tree to navigate through the SOA Infrastructure home page and menu to access your deployed SOA composite applications running on soa-infra
managed server. Click the XMLGOutbound [1.0] link.
Click Test. The Test Web Service page for initiating an instance appears. Enter the input string required by the process and click Test Web Service to initiate the process. The test results appear in the Response tab upon completion. Click your BPEL service component instance link (such as XMLGOutbound) to display the Instances page where you can view execution details for the BPEL activities in the Audit Trail tab.
Click the Flow tab to check the BPEL process flow diagram. Click an activity of the process diagram to view the activity details and flow of the payload through the process. For example, click Receive activity. Click the view xml document link to open the received XML file. Note the Reference ID such as Customer PO.
Go to the directory you specified for the write operation, for example outputDir
- logical location (typically c:\temp
) where the File Adapter has placed the file after writing the PO Acknowledgement in an XML file (such as 'PO_060719175318.xml').
Open the 'PO_060719175318.xml' file and search for ORIGREF element. Its value should be 'PO-4466-5' (the order booked) for which the acknowledgement is generated.