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:
  • Oracle E-Business Suite Adapter Configuration service
  • HTTP Server adapter
  • BP Fault Log adapter
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:
  • Oracle E-Business Suite Adapter Configuration service
  • Oracle E-Business Suite Message service
  • Timezone Offset service
This adapter also uses other Sterling B2B Integrator services including, but not limited to:
  • Document XPath Replace service
  • Correlation service
  • Request Response XREF service
  • Request Response DXREF service
  • B2B Send adapter
  • Consume service
Application requirements You must:
  • Have a valid user name and password for the Oracle E-Business Suite
  • Create a trading profile to send messages to Oracle
  • Exchange digital certificates with Oracle E-Business suite (to use HTTPS for secure transport)
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:
  • Success: All steps of the business process completed successfully. If a response (Confirm BOD) indicates an application-level error, the business process status is still Success.
  • Error: Some step in the business process had an error. The adapter BPML logs all errors to a file in a configurable folder.
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.

Note: Modules within the Oracle E-Business Suite might use different versions of the OAG documents; be sure to use the correct version of the OAG documents for the module you use.

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.

The adapter can be used to send OAG documents to Oracle and receive OAG documents from Oracle. The following topics describe how each mode works:
  • 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

To send documents to Oracle, you must create a configuration of the Oracle E-Business Suite Adapter Configuration service that will provide the necessary parameter settings to your business process.
  1. 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.
  2. 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.
  3. 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
  4. The Oracle E-Business Suite adapter constructs and encodes the message using the Oracle E-Business Suite Message service.
  5. 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.
  6. 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

  1. 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.
  2. The OracleEBusinessReceive business process sends back a synchronous HTTP response to Oracle to close the HTTP connection.
  3. 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.
  4. The adapter decodes the message using the Oracle E-Business Suite Message service and puts the OAG XML payload into the primary document.
  5. 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
  6. 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

  7. 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:
    1. If the configuration option Business Process to handle received messages is specified, then this business process runs.
    2. 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.
  8. 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:
    1. The CONFIRMATION value in the received document was 2.
    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.

The following DTDs are already checked in; you must check in any others (including different versions of these transactions).
  • 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

To implement the Oracle E-Business Suite adapter, complete the following tasks:
  1. Activate your license for the Oracle E-Business Suite adapter. For information, see An Overview of Implementing Services.
  2. 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 .
  3. 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.
  4. 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
  5. Create and configure a perimeter server for use with the Oracle E-Business Suite adapter.
  6. 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:
    1. From the Administration menu, select Deployment > Services > Configuration.
    2. Select Create > New Service.
    3. For Service Type, choose HTTP Server Adapter, then click Next.
    4. 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.
    5. Deploy the perimeter server on the host machine in the DMZ if required.
  7. Create the following trading profiles for Sterling B2B Integrator and Oracle:
    1. 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.
    2. 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.

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

  9. 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.
  10. 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.
  11. 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>

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

This section contains a brief overview of how each service is used, but specific information about each can be found on the pages listed below:
  • 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

When this service runs with the MODE set to DECODE, the following output will be produced:
  • 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.
  1. If REFERENCEID is blank, assign it a unique value.
  2. If the Insert date and time option is true, run the business process OracleEBusinessInsertDate.
  3. Run the business process OracleEBusinessCorrelate.
  4. Encode the XML document using the Oracle E-Business Suite Message service.
  5. Send the message to Oracle E-Business Suite.
  6. If a Confirm BOD is expected, wait for it.
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.
  1. Run the business process OracleEBusinessCorrelate.
  2. If the received message is a Confirm BOD, send the Confirm BOD to the configuration of OracleEBusinessSend which is waiting for it.
  3. If the message is not a Confirm BOD, run the user-specified business process to handle it. If you did not specify a business process, run a business process named OracleEBusinessRecv_<VERB>_<NOUN>.
  4. If the Auto send Confirm BOD option is set to true, run the business process OracleEBusinessSendConfirmBOD.
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.

To edit the sample trading profile:
  1. Import the sample trading profile, SendingContract.xml, into Sterling B2B Integrator. At the prompt for the passphrase, enter password.
  2. 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.
  3. 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.

Consider the following when creating a Confirm BOD template:
  • 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.