Oracle E-Business Suite Adapter
The Oracle E-Business Suite adapter exchanges messages with the Oracle E-Business Suite by using the Oracle XML Gateway with HTTP or HTTPS.
The following table provides an overview of the Oracle® E-Business Suite adapter:
Category | Description |
---|---|
System name | None (BPML-based adapter and does not have a system name) |
Graphical Process Modeler (GPM) category | None |
Description | The Oracle E-Business Suite adapter enables you to exchange messages with the Oracle E-Business Suite using the Oracle XML Gateway with HTTP or HTTPS. The adapter supports version 12.0.0 of the E-Business Suite. The adapter supports XML messages that meet the Open Applications Group (OAG) standard. See the Oracle E-Business Suite documentation for more information. |
Business usage | The Oracle E-Business Suite adapter enables you to exchange messages with the Oracle E-Business Suite, which includes modules for financials, purchasing, accounts payable, and accounts receivable, among others. |
Usage example | You want to send a purchase order to a trading partner Oracle E-Business Suite server. Build a business process to construct an OAG-format purchase order (PROCESS PO) and use the Oracle E-Business Suite adapter to send it to the trading partner. The trading partner may send back an invoice, which can be received by the Oracle E-Business Suite adapter. |
Preconfigured? | No. You must create a trading partner contract,
a perimeter server, and configurations of these services or adapters:
|
Requires third-party files? | OAG DTDs must be checked in to Sterling B2B Integrator for each document type exchanged with Oracle. |
Platform availability | All Sterling B2B Integrator supported platforms |
Related services | Related services include:
|
Application requirements | You must:
|
Initiates business processes? | The HTTP Server adapter must be configured with a URL that runs the OracleEBusinessReceive business process when a message is received from Oracle. |
Invocation | To send a message to Oracle, create a business process that does the following: Starts the Oracle E-Business Suite Adapter Configuration service. Places an OAG XML document (for example, PROCESS PO) into the primary document. Runs the OracleEBusinessSend business process. To receive a message from Oracle, do the following: Configure a URL in the HTTP Server adapter that starts the OracleEBusinessReceive. Write a single business process to handle all incoming Oracle messages, or write a separate business process for each type of incoming message (PO, Invoice, and so forth). Use the Oracle E-Business Suite Adapter Configuration service to configure the option you select. |
Business process context considerations | See Invocation. |
Returned status values | Returned status values:
|
Restrictions | Oracle E-Business Suite 12.0.0 and the adapter both support only UTF-8 encoding. |
Persistence level | All Oracle E-Business adapter business processes use the system default persistence level (Full persistence, unless you change the system default). The Oracle E-Business Suite Adapter Configuration service, Oracle E-Business Suite Message service, and Timezone Offset service use the default service persistence level (Full persistence). |
Testing considerations | Modify the sample BPML provided (samples/oracleEBusiness/bpml/testOraclePO.bpml), and import and modify the sample trading partner contract provided (samples/oracleEBusiness/TradPartnerProfiles/SendingContract.xml). A sample OAG document (samples/oracleEBusiness/OAG_XML/process_po.xml) can also be used. |
Requirements
You must have a valid user name and password to log in to the Oracle E-Business Suite. To use HTTPS, you must exchange digital certificates with Oracle E-Business Suite.
How the Oracle E-Business Suite Adapter Works
The adapter communicates with the Oracle E-Business Suite using the Oracle XML Gateway and Oracle Transport Agent (OTA). The OTA protocol sends and receives several parameters in addition to the OAG XML document. All of these parameters are transmitted in the form of a standard HTTP POST.
- Sending Documents to Oracle
- Receiving Documents from Oracle
The adapter uses a customized configuration of the BP Fault Log adapter called OracleEBusinessAdapterLogger to log all errors.
Send Documents to Oracle
- Create a business process which does the following:
- Generates an OAG document and stores it in the primary document.
The document must have a CONFIRMATION value of 0 (no confirmation requested) or 2 (confirmation always requested); the value 1 (confirmation only on error) is not permitted.
- Starts a configuration of the Oracle E-Business Suite Adapter Configuration service to access the configuration parameters for the adapter.
- Runs the business process OracleEBusinessSend.
If the REFERENCEID field in the CNTROLAREA of the document is blank, the Oracle E-Business Suite adapter will set a unique value for this field; otherwise, the adapter will leave the existing value in place.
Note: This value is used to correlate responses with requests, so a unique value is required.
- Generates an OAG document and stores it in the primary document.
- If the Oracle E-Business Suite Adapter Configuration service parameter Insert Date and Time into OAG doc at run time is set to true, the Oracle E-Business Suite adapter starts the business process OracleEBusinessInsertDate to insert the current date and time into the OAG DATETIME element within the CNTROLAREA. It will not insert the date/time into the DATETIME element within the DATAAREA of the document.
- The Oracle E-Business Suite adapter uses the Correlation service
to correlate the primary document using the names and values listed
in the following table. This enables you to easily locate all Oracle
OAG documents using the Correlation Search page in Sterling B2B Integrator.
Correlation Name Correlation Value Literal or from OAG Document? OracleEBusiness True Literal ReferenceID CNTROLAREA/SENDER/REFERENCEID From document Verb CNTROLAREA/BSR/VERB From document Noun CNTROLAREA/BSR/NOUN From document - The Oracle E-Business Suite adapter constructs and encodes the message using the Oracle E-Business Suite Message service.
- The Oracle E-Business Suite adapter sends the message to Oracle using the settings defined in the trading partner contract specified in the Oracle E-Business Suite Adapter Configuration service.
- If the OAG document CONFIRMATION value is 2, the Oracle E-Business Suite adapter waits for Oracle to respond with a Confirm BOD message. The Confirm BOD is placed in the primary document.
Receive Documents from Oracle
- The Oracle E-Business Suite sends an OAG XML document to Sterling B2B Integrator. The HTTP Server adapter must have a URI configured that matches the URI where the document was posted and runs the OracleEBusinessReceive business process.
- The OracleEBusinessReceive business process sends back a synchronous HTTP response to Oracle to close the HTTP connection.
- The OracleEBusinessReceive business process starts a configuration
of the Oracle E-Business Suite Adapter Configuration service named
OracleEBusinessAdapterConfig to get the configuration settings. Note: If you create a configuration of this service with a different name, you must change the business process to point to the new configuration.
- The adapter decodes the message using the Oracle E-Business Suite Message service and puts the OAG XML payload into the primary document.
- The Oracle E-Business Suite adapter uses the Correlation service
to correlate the primary document using the names/values listed in
the previous table. This enables you to find Oracle OAG documents
using the Correlation Search page in Sterling B2B Integrator.
Correlation Name Correlation Value Literal or from OAG Document? OracleEBusiness True Literal ReferenceID CNTROLAREA/SENDER/REFERENCEID From document Verb CNTROLAREA/BSR/VERB From document Noun CNTROLAREA/BSR/NOUN From document - If the received message is a confirm BOD, the Oracle E-Business
Suite adapter sends the confirm BOD to the configuration of the OracleEBusinessSend
business process that is waiting for it.
In the Confirm BOD, the value in element DATAAREA/CONFIRM_BOD/CONFIRM/CNTROLAREA/SENDER/REFERENCEID must match the value from the original request in element CNTROLAREA/SENDER/REFERENCEID
- If the received message is not a confirm BOD, the adapter runs
a business process to handle the message. The business process name
is chosen as follows:
- If the configuration option Business Process to handle received messages is specified, then this business process runs.
- If this configuration option is left blank [Not applicable], the adapter starts a business process named OracleEBusinessRecv_<VERB>_<NOUN>, where <VERB> and <NOUN> are taken from the received OAG document CNTROLAREA. For example, a PROCESS PO would be handled by a business process named OracleEBusinessRecv_PROCESS_PO.
- If the configuration service parameter Automatically send Confirm
BOD for received messages is false, confirm BOD is returned to Oracle
if required. If this parameter is true, the adapter will send back
a confirm BOD using the business process OracleEBusinessSendConfirmBOD
if either of the following conditions is met:
- The CONFIRMATION value in the received document was 2.
- The CONFIRMATION value in the received document was 1 and there was an error handling the received document, either in an adapter business process or a user-defined sub-process called to handle the received message.
Message Exchange
The Oracle E-Business Suite adapter supports the OAG standard XML documents. The OAG provides DTDs (and XML schema, in OAG version 8.0) to define the documents which must be checked into Sterling B2B Integrator.
- 002_confirm_bod_004.dtd
- 003_process_po_007.dtd
- 161_show_shipment_005.dtd
- 171_process_invoice_002.dtd
- oagis_domains.dtd
- oagis_entity_extensions.dtd
- oagis_extensions.dtd
- oagis_fields.dtd
- oagis_resources.dtd
- oagis_segments.dtd
The adapter and Oracle XML Gateway support only UTF-8 encoding. For any other encoding, use the Encoding service to change encoding to UTF-8. See Encoding Conversion Service for information about this service.
Implement the Oracle E-Business Suite Adapter
- Activate your license for the Oracle E-Business Suite adapter. For information, see An Overview of Implementing Services.
- Check in the DTDs or XML schema for the OAG documents you will exchange. Several OAG DTDs are pre-installed with the adapter. For information, see Message Exchange .
- Configure the configuration of the BP Fault Log adapter named OracleEBusinessAdapterLogger. Set the path to the log file (for example, /home/sampleuser/logs/oracleEBusiness.log). See BP Fault Log Adapter for more information about the BP Fault Log adapter.
- If using HTTPS for secure transport, exchange digital certificates
between Sterling B2B Integrator and
Oracle E-Business Suite, and configure the web servers on both sides
to use the certificates. The steps required will depend on the web
server used on both sides and whether you use self-signed or CA-signed
certificates.
For the Oracle configuration, see the following documents (152775.1 and 119873.1). You will need an Oracle Metalink account to view these documents.
- http://metalink.oracle.com/metalink/plsql/showdoc?db=Not&id=152775.1
- http://metalink.oracle.com/metalink/plsql/ml2_documents.showNOT?p_id=119873.1
- Create and configure a perimeter server for use with the Oracle E-Business Suite adapter.
- Create an HTTP Server adapter configuration called Oracle_HTTPServerAdapter.
For information about configuring the HTTP Server adapter, see HTTP
Server Adapter. To set up this configuration, complete the following
steps:
- From the Administration menu, select Deployment > Services > Configuration.
- Select Create > New Service.
- For Service Type, choose HTTP Server Adapter, then click Next.
- Complete the adapter configuration by using the settings shown in the table below for the
corresponding fields. Configure all other fields according to your requirements:
For this field... Specify this setting... Name Oracle_HTTPServerAdapter Perimeter Server Name Select the node and perimeter server you configured in step 5. URI 1. On the Oracle_HTTPServerAdapter: URI page, select add New URI. 2. The Oracle_HTTPServerAdapter: URI: URI Config page displays. Enter the URI where Oracle will post messages. This is the interface through which Oracle E-Business Suite will call Sterling B2B Integrator. Example:
/b2bhttp/inbound/oracleadapter
Launch BP or WAR Select Business Process. Business Process Choose OracleEBusinessReceive Send Raw Messages Select No. - Deploy the perimeter server on the host machine in the DMZ if required.
- Create the following trading profiles for Sterling B2B Integrator and Oracle:
- Sterling B2B Integrator consumption profile for receiving messages from Oracle E-Business Suite. This profile is not used; it is required only because a contract requires both a production and consumption profile.
- Oracle E-Business Suite production profile for sending messages
to Oracle E-Business Suite.
You can configure the trading profiles by importing the SendingContract.xml file in the samples/oracleEBusiness/TradPartnerProfiles directory and modifying the trading partner profiles. For more information, see Editing the Trading Profile Sample.
- Create one or more business processes to handle messages received
from Oracle. You may create a single process to handle all incoming
messages, or a separate business process for each type of message
received, based on the NOUN/VERB combination in the received OAG document.
This is done as part of the Oracle E-Business Suite Adapter Configuration
service setup (option: Business Process to handle received messages).
See Receiving Documents from Oracle for more information.
If you choose to use a different business process for each message type, the process names must be OracleEBusinessRecv_<VERB>_<NOUN>.
- If you select the option Automatically send Confirm BOD for received messages, you must create a template Confirm BOD. A sample Confirm BOD is provided in the directory samples/oracleEBusiness/OAG_XML/ConfirmBODtemplate.xml. For more information, see Creating a Confirm BOD template.
- In Sterling B2B Integrator, set up the configuration of the Oracle E-Business Suite Adapter Configuration service named OracleEBusinessAdapterConfig. Choose the trading partner contract created earlier in this process.
- Create a business process that starts the OracleEBusinessSend
business process. Your business process must include a call to your
configuration of the Oracle E-Business Suite Adapter Configuration
service, and it must put the OAG XML document into the primary document.
See testOraclePO.bpml in the directory samples/oracleEBusiness/bpml
for an example.
Oracle uses the following message parameters to match a message to a transaction defined in the XML Gateway. The adapter assigns these parameters based on values in the OAG document as shown in the table below. The assignments occur when the OracleEBusinessSend business process starts the Oracle E-Business Suite Message service.
Message Parameter Name Must match XML Gateway transaction field Adapter assigns parameter value from OAG element TRANSACTION_TYPE External transaction type CNTROLAREA/BSR/NOUN TRANSACTION_SUBTYPE External transaction subtype CNTROLAREA/BSR/NOUN PARTY_SITE_ID Source location code CNTROLAREA/SENDER/LOGICALID To assign different values to any of these fields, the user-defined business process must assign values to the fields. For example: <assign to=”TRANSACTION_TYPE”>MyTransactionType</assign>
- Run the business process.
Oracle E-Business Suite Custom Services
The Oracle E-Business Suite adapter uses the following custom services, which are installed automatically with the adapter.
- Oracle E-Business Suite Adapter Configuration service: for more information, see Oracle E-Business Suite Adapter Configuration Service.
- Oracle E-Business Suite Message service: for more information, see Oracle E-Business Suite Message Service.
- Timezone Offset service: for more information, see Timezone Offset Service.
For general information about creating service configurations, see Managing Services and Adapters.
Oracle E-Business Suite Adapter Configuration Service
Use the Oracle E-Business Suite Adapter Configuration service to set configuration parameters for the adapter.
You must create a configuration of the Oracle E-Business Suite Adapter Configuration service and start it from the business process which runs the OracleEBusinessSend business process to send messages. For receiving messages, the OracleEBusinessReceive business process starts a configuration of this service named OracleEBusinessAdapterConfig. In a typical situation, it is best to create a single configuration of this service and name it OracleEBusinessAdapterConfig.
At run time, this service simply inserts the configured parameters into process data. The configured parameter values cannot be overridden with the GPM.
Oracle E-Business Suite Message Service
This service encodes messages for sending to Oracle and decodes messages received from Oracle. The Oracle XML Gateway/Oracle Transport Agent (OTA) uses several parameters in addition to the XML payload, and it uses standard HTTP POST semantics for all parameters including the XML payload.
See the business process OracleEBusinessSend for an example of using this service to encode a message for sending. To encode a message, the XML payload must be in the primary document when this service runs. The resulting encoded message (in standard HTTP POST format) will be placed in the primary document as output.
See the business process OracleEBusinessReceive for an example of using this service to decode a received message. The XML payload will be placed in the primary document as output.
Service Output for ENCODE MODE
With the MODE set to ENCODE, this service outputs to the primary document only. The primary document will contain an HTTP POST message ready to be sent to Oracle.
Service Output for DECODE MODE
- The PAYLOAD (XML document) of the received message will be stored in the primary document.
- All other OTA parameters except the PASSWORD will be stored in process data within the element ProcessData/OracleEBusiness/Recv_OTA_Params, for example ProcessData/OracleEBusiness/Recv_OTA_Params/USERNAME.
- The OTA parameter PASSWORD will not be stored for security reasons.
Timezone Offset Service
This service computes the difference between the local time zone and Greenwich Mean Time (GMT), using the format +/-HHMM. For example, the value for U.S. Eastern time would be -0500 during standard time, or -0400 during daylight savings time.
Output
The output of this service is a single XML element named timezoneOffsetFromGMT.
Predefined Business Processes
The Oracle E-Business Suite adapter uses predefined business processes to handle communications with Oracle.
The following table describes each of the predefined business processes:
Business Process | Description |
---|---|
OracleEBusinessSend | The top-level business process to send a message
to Oracle.
|
OracleEBusinessInsertDate | Replace the values within the CNTROLAREA/DATETIME element of the primary document with the current time. |
OracleEBusinessCorrelate | Uses the Correlation service to correlate the primary document. See the correlation table in the section Sending Documents to Oracle for a list of the values correlated. |
OracleEBusinessReceive | The top-level business process to handle all messages
received from E-Business Suite.
|
OracleEBusinessSendConfirmBOD | Sends a Confirm BOD message to Oracle. If the Insert date and time option is true, run the business process OracleEBusinessInsertDate to insert the current date into the Confirm BOD CNTROLAREA/DATETIME. |
Edit the Trading Profile Sample
You can configure the trading profiles by importing the profile XML file in the samples/oracleEBusiness/TradPartnerProfiles directory and then editing parts of the profile.
- Import the sample trading profile, SendingContract.xml, into Sterling B2B Integrator. At the prompt for the passphrase, enter password.
- If you are using HTTPS, obtain the digital certificate used by the Oracle E-Business Suite. Check this certificate in to Sterling B2B Integrator as both a trusted certificate and a CA certificate.
- Edit the Oracle EBusiness Suite transport:
In the End Point field, enter the URL for the Oracle XML gateway.
Note: Note that the protocol part of the URL will be HTTP whether you use HTTP or HTTPS.If you are using HTTPS:
- For SSL, select MUST.
- For Cipher Strength, select STRONG.
- In the User Certificate field, select the trusted certificate from Oracle E-Business Suite.
- In the CA certificate field, select the CA certificate from Oracle E-Business Suite.
- In the Key Certificate field, select the Sterling B2B Integrator certificate
(B2BHttp).
If you are using HTTP:
- For SSL, select None.
- All three certificate fields can be left blank.
Create a Confirm BOD template
If you select Automatically send Confirm BOD for Received Messages, then you must create a template Confirm BOD file. A sample Confirm BOD is provided in the directory samples/oracleEBusiness/OAG_XML/ConfirmBODtemplate.xml.
- If the first REFERENCEID element (/CONFIRM_BOD_004/CNTROLAREA/SENDER/REFERENCEID) is left blank, the OracleEBusinessSendConfirmBOD business process will insert a unique value for this element. Typically, Oracle will expect a unique value here, so it is recommended to leave this element blank.
- The first CONFIRMATION value (/CONFIRM_BOD_004/CNTROLAREA/SENDER/CONFIRMATION) should be set to 0 (zero) or 1, but not 2. The value 2 indicates that a Confirm BOD is requested, but it does not make sense to request a Confirm BOD in response to a Confirm BOD.
- The OracleEBusinessSendConfirmBOD business process will replace all the confirm BOD elements within DATAAREA/CONFIRM_BOD/CONFIRM with the CNTROLAREA from the original request document.
BPML Error Handling
The adapter logs errors in a file specified by the OracleEBusinessAdapterLogger configuration. Errors are also passed to the user-defined business process that ran the OracleEBuinessSend business process. During error handling, the adapter cleans out any waiting consume services and unusable XREF information. This ensures that when you rerun the adapter nothing interferes with its operation.
Security
The adapter supports HTTPS/SSL for secure transport. The adapter also hides the Oracle E-Business Suite password so the clear text password is not shown in process data.
Internationalization
The adapter supports internationalization using UTF-8 encoding. This is the only encoding supported by Oracle E-Business Suite and XML Gateway. If your documents use any other encoding, use the Encoding Conversion service to convert to UTF-8. See Encoding Conversion Service for information about this service.