Introduction to OracleAS Adapter for Oracle Applications

This chapter covers the following topics:

• Overview of OracleAS Adapter for Oracle Applications
• New Features in This Release
• Understanding Applications Context
• Installing OracleAS Adapter for Oracle Applications
• Using the Oracle Applications Module Browser
• General Issues and Workarounds

Overview of OracleAS Adapter for Oracle Applications

Oracle Applications is a set of integrated business applications that runs entirely on the Internet. Oracle Applications offers you the following:

• Reduced costs

• Increased revenue across front-office and back-office functions

• Access to current, accurate, and consistent data

The applications in Oracle Applications are built on a unified information architecture that consolidates data from Oracle and non-Oracle applications and enables a consistent definition of customers, suppliers, partners, and employees across the entire enterprise. This results in a suite of applications that can give you information, such as current performance metrics, financial ratios, profit and loss summaries. To connect Oracle Applications to non-Oracle applications, you use OracleAS Adapter for Oracle Applications.

OracleAS Adapter for Oracle Applications provides comprehensive, bidirectional, multimodal, synchronous, and asynchronous connectivity to Oracle Applications. The adapter supports all modules of Oracle Applications for versions 11.5.1 to11.5.10. In addition, OracleAS Adapter for Oracle Applications provides real-time and bidirectional connectivity to Oracle Applications.

Note: This overview includes details about features and capabilities that are new in the current release of OracleAS Adapter for Oracle Applications.

Features

OracleAS Adapter for Oracle Applications includes the following features:

• It supports open standards, including J2EE Connector Architecture (J2CA), Extensible Markup Language (XML), Web Service Invocation Framework (WSIF), Web Service Inspection Language (WSIL), and Web Service Definition Language (WSDL).

• It uses a JDeveloper based design-time tool for dynamically browsing the Oracle Applications interface and configuring the adapter metadata.

• It integrates applications based on open standards, such as IFX, OAG, RosettaNet, and UCCnet by interfacing with XML Gateway.

• It generates adapter metadata as WSDL files with J2CA extension.

  Note: See Oracle Application Server Adapter Concepts on OTN for more information.

Architecture

OracleAS Adapter for Oracle Applications is based on J2CA 1.0 standards and deployed as a resource adapter in the same Oracle Application Server Containers for J2EE (OC4J) container as BPEL Process Manager. The architecture of OracleAS Adapter for Oracle Applications is similar to the architecture of technology adapters.

OracleAS Adapter for Oracle Applications Architecture

Integration Interface Types

OracleAS Adapter for Oracle Applications acts as a highly flexible integration interface for Oracle Applications. The adapter supports the following interface types for integrating with Oracle Applications:

• Oracle XML Gateway

  XML Gateway enables bidirectional integration with Oracle Applications. It helps you to insert and retrieve data from Oracle Applications. XML Gateway is a higher-level interface that exposes OAGIS-formatted XML documents for commonly used Oracle Application business objects and business interfaces. XML Gateway integrates with interface tables, Oracle Workflow Business Event System (BES), and interface views to insert and retrieve data from Oracle Applications. It maps the underlying table data to XML and back.

• Business events

  A business event occurs in an internet application whenever something of significance happens, or can happen. An example of a business event is the creation of a new sales order. The BES is an application service that uses the Oracle Advanced Queuing (AQ) infrastructure to communicate business events between systems.

• Concurrent programs

  Concurrent programs enable you to move data from interface tables to base tables.

• Interface tables

  Interface tables enable you to insert or update data into Oracle Applications. The associated concurrent program should be running to move the data from the interface tables to base tables.

• Interface views

  Interface views help you to retrieve data from Oracle Applications using the application tables.

• PL/SQL APIs

  These APIs enable you to insert and update data in Oracle Applications using PL/SQL.

• Oracle e-Commerce (EDI) Gateway

  Oracle e-Commerce Gateway provides a common, standards-based approach for Electronic Data Interchange (EDI) integration between Oracle Applications and third party applications.

New Features in This Release

This section describes the new features that have been added in OracleAS Adapter for Oracle Applications 10g (10.1.3.1.0).

Support for Oracle Integration Repository

Oracle Integration Repository, an integral part of Oracle E-Business Suite, is a prebuilt catalog of information about the numerous public integration interfaces delivered with Oracle applications, known as business interfaces. It provides a comprehensive view of the interface mechanisms available for Oracle E-Business Suite's business interfaces. These interfaces are exposed because their definitions were annotated at design-time as required by Oracle Integration Repository.

Oracle Integration Repository can only provide information about an integration interface that has been specifically annotated by the developer to make it public. OracleAS Adapter takes advantage of the annotations that have already been created to make the following business interface types visible in the Oracle Applications Module Browser:

• XML Gateway message maps

• PL/SQL APIs

• Concurrent programs

• Open Interface tables

• Interface views

• e-Commerce Gateway EDI messages

These business interfaces are exposed as Web services, and are available for process orchestration through the Oracle BPEL Process Manager.

Note: This view of business interfaces is provided from the static XML data file of Oracle Integration Repository for look-up into the integration interfaces for selection during design-time in the wizard.

For more information, see Oracle Integration Repository User's Guide.This guide is a part of the Oracle Applications documentation library. Oracle Applications documentation can be accessed with the following link:

http://www.oracle.com/technology/documentation/applications.html

Additional Integration Interface Types

OracleAS Adapter now provides new or enhanced support for several integration interface types, which are exposed by the Oracle Applications Module Browser:

• Business events

• Customized XML Gateway maps

• Customized PL/SQL APIs

Note: These interface types are not exposed by Oracle Integration Repository.

The integration interfaces are exposed as Web services, and are available for process orchestration through the Oracle BPEL Process Manager.

Meaningful Parameter Names

In the past, concurrent program parameters were listed generically by the Oracle BPEL Process Manager according to their positions in the input, for example: parm1, parm2, parm3, with no indication of their purpose or data type. Starting in the current release, the parameters will be displayed with meaningful names taken from the concurrent program definition. For example, for the concurrent program named OE Order Import (OEOIMP), the parameters would be:

• P_Order_Source

• P_Orig_Sys_Document_Ref

• P_Sold_To_Org_Id

• P_Perf_Param

Business Event Schema Selection Page

OracleAS Adapter now allows you to select the schema used for business event payload in the following three options:

• No Schema

• Any Schema

• Specify Schema

When you select either the 'No Schema' or 'Any Schema' option, there is no need to further specify the schema information for your business event service. The associated WSDL file corresponding to your specified business event service will be generated. If you select the 'Specify Schema' option, then you must specify the location of schema file and then select the schema element that defines the payload of outbound business event.

Understanding Applications Context

Applications context is required for secured transaction processing into and out of Oracle Applications.

Applications context is a combination of Organization ID, Username and Responsibility. To establish applications context, the Organization ID is implicitly derived from the Oracle Applications setup data.

To understand applications context, you need to understand first how Organization ID and multiple organizations are related.

You can define multiple organizations and the relationships between them in a single installation of Oracle Applications. These organizations can be sets of books, business groups, legal entities, operating units, or inventory organizations.

You can define multilevel organization hierarchies, with a business group at the top of each hierarchy. When you define new organizations, they are automatically assigned to the business group associated with your current session. Each organization is part of a business group. The business group is usually the top box on an enterprise organization chart.

Business Group Hierarchy

Example of a Multi-Organization Setup

Using the accounting, distribution, and materials management functions in Oracle Applications, you define the relationships among inventory organizations, operating units, legal entities, and sets of books to create a multilevel company structure, as shown in the following diagram.

A Multi-Organization Transaction

Consider two different organizations in your company: One is a French sales office and the other is a German warehouse. There is a sales order transaction with the customer, and this illustrates how the entire Order-to-Deliver process would work:

1. The customer places a sales order with the French sales office.

2. The German warehouse delivers the product shipment to the customer.

3. The German warehouse issues an inter-company invoice to the French sales office.

4. The French sales office makes the inter-company payment to the German warehouse.

5. The French sales office sends the customer invoice to the customer.

6. The customer makes payment to the French sales office.

The database architecture is the same for a Multi-Org and non-Multi-Org installation, and uses the standard install tools feature that automatically creates synonyms in the APPS schema for each base product table and defines these synonyms with the same name as the base product tables. For example, the PO Oracle schema has a table named PO_HEADERS_ALL and the APPS schema has a corresponding synonym of the same name, PO_HEADERS_ALL. The PO_HEADERS_ALL synonym can be used to access unpartitioned data.

Schema Synonyms

Now let's see how Oracle Applications ties Username, Responsibility with Organization ID. While setting up the System Profile Values, the username, responsibility is tied up with the Organization with Username, Responsibility.

Multi-Organization System Profile

The following diagram illustrates how Oracle Applications use the profile options.

Building Applications Context

1. When the system integrator runs, the process achieves the integration with Oracle Applications using PL/SQL APIs.

2. The Apps.Initialize process takes the parameters of Username and Responsibility.

3. With these parameters, a lookup on the System Profile Values is done to determine the Operating Unit.

4. The Operating Unit is modeled as Organization ID in the System Profile Values.

5. The data is read and written into the Oracle Applications with the parameters of Username, Responsibility and Organization ID.

Installing OracleAS Adapter for Oracle Applications

The installation of the Oracle Application Server Adapter happens out-of-the-box with the Oracle BPEL Process Manager (PM) product. OracleAS Adapter for Oracle Applications is deployed using the Oracle BPEL PM in Oracle JDeveloper.

Note: Refer to Oracle Application Server Integration Business Activity Monitoring User's Guide for more details about installing Oracle BPEL Process Manager. Refer to the section "Notes on Installing Oracle BPEL Process Manager."

Using the Oracle Applications Module Browser

In addition to the interfaces that are made available through Oracle Integration Repository, OracleAS Adapter for Oracle Applications enables you to use business events, customized PL/SQL APIs, customized XML Gateway maps, and selected concurrent programs, all of which you can explore using the Oracle Applications Module Browser.

Oracle Applications Module Browser

The Oracle Applications Module Browser is a key component of OracleAS Adapter for Oracle Applications. You use the Module Browser to select the interface needed to define a partner link. The Module Browser combines interface data from Oracle Integration Repository with information about the additional interfaces supported by OracleAS Adapter, organized in a tree hierarchy as follows:

ProductFamilies  |-[product_family]  |  |-[product]  |     |-[business_entity]  |        |-XML Gateway ([n])  |        |-EDI ([n])  |        |-PLSQL ([n])  |        |  |-[package_name]  |        |-OpenInterfaces ([n])  |           |-[OpenInterface_name]  |              |-Tables ([n])  |              |-Views ([n])  |              |-ConcurrentPrograms ([n])  |-Other Interfaces     |-Business Events     |-Custom Objects        |-PLSQL APIs        |  |-[package_name]        |-XMLGateway Maps           |-Inbound           |-Outbound 

Note: The items under Other Interfaces, as well as certain PL/SQL APIs and concurrent programs under the [product family] hierarchy, are available through OracleAS Adapter for Oracle Applications, but not through Oracle Integration Repository.

The Oracle Integration Repository interface data populates the [product_family] sections, grouped according to the products and business entities to which they belong. Each interface type heading is followed by a number [n] indicating how many of that type are listed in that section.

Business events appear under Other Interfaces. Customized XML Gateway maps appear under Other Interfaces > Custom Objects, categorized as either inbound or outbound.

Customized PL/SQL APIs appear in two places:

• Procedures within a package that's already exposed via Oracle Integration Repository appear under the package name within a product family hierarchy.

• Procedures within a completely new package appear under the package name, under Other Interfaces > Custom Objects.

General Issues and Workarounds

This section describes the following issues and workarounds:

• WSDL Context Information Default Values

  In the current release, BPEL Process manager generates WSDL code containing context information, including the username and responsibility of an Oracle Applications user who has sufficient privileges (based on the applications context of Organization ID, Username and Responsibility) to run the program.

  By default the Username value is set to SYSADMIN and the Responsibility value is set to SYSTEM ADMINISTRATOR. To change these values, you must manually edit the WSDL file.

• Correlation ID Defaults to BPEL for XML Gateway Transactions

  The Adapter Configuration wizard of OracleAS Adapter for Oracle Applications does not specify a correlation ID for XML Gateway transactions for inbound or outbound interfaces. Instead, a default correlation ID of BPEL is automatically set in the WSDL file. To make this configuration work, you must configure Oracle Applications to set the same correlation ID value of BPEL for the corresponding XML Gateway transactions.

  If you want the Adapter to use a different correlation ID than the default, you need to configure a correlation ID in Oracle Applications, then edit the Correlation="BPEL" line contained in the section of the adapter service WSDL. Replace BPEL with the string value of the correlation ID you specified in Oracle Applications.

• Workaround for Stored Procedures Using Complex Types and the DEFAULT Clause

  When working with stored procedures for which the Adapter Configuration wizard must generate wrapper SQL stored procedures, there is a current limitation on DEFAULT clauses not being carried over to the generated wrapper stored procedures.

  As a workaround, perform the following steps one time only for a given stored procedure:

  1. Open the generated wrapper SQL script.

  2. Copy all default clauses from the base-stored procedure into the corresponding wrapper.

  3. Use SQL*Plus to reload the wrapper SQL script into the database.

  4. Edit the generated XSD. If a parameter has a DEFAULT clause, its corresponding element in the XSD must have the extra attribute: db:default="true"

     For example, with the following SQL:

     FINANCE$INVOICE(isTrue INTEGER DEFAULT 1, value NUMBER DEFAULT 0) 

     The elements in the XSD for isTrue and value must have the new attribute:

• One-time Workaround for Concurrent Programs and E-Commerce Gateway Interfaces

  When working with Concurrent Programs and E-Commerce Gateway interfaces, you must perform the following workaround exactly once for a given E-Business Suite instance.

  Note: This is to work around the known issue with the Adapter Configuration wizard being unable to preserve DEFAULT clauses for PL/SQL wrappers that it generates underneath the covers.

  Load the following SQL file into the apps schema (using SQL*Plus) before launching the Oracle Applications adapter of the Adapter Configuration wizard to create services for either Concurrent Programs or E-Commerce Gateway Interfaces.

  ORACLE_HOME\bpel\samples\tutorials\150.AppsAdapter\OrderImportConcurrentProgram\bpel\XX_BPEL_FND_REQUEST_SUBMIT_REQUEST.sql 

• Cannot Create a Partner Link If the Underlying API Has Been Recreated

  The generation of a wrapper for an API that was recreated with the same name, but with a different set of parameters, will fail.

  Note: This can happen for both packaged procedures and top-level or root procedures that require generated wrappers.

  The following example illustrates the problem:

  1. Create the initial API that, in this case, is defined at the top level:

     SQL> create procedure test (a number, b varchar2, c BOOLEAN)  

     The BOOLEAN parameter indicates that a wrapper is necessary.

  2. Use the database adapter for stored procedures in the Adapter Configuration wizard to generate and load the wrapper for this API.

  3. Drop the API, then recreate it with a different set of parameters:

     SQL> drop procedure test SQL> create procedure test (a number, b varchar2, c number, d BOOLEAN) 

  4. An attempt to generate a partner link for this API using the Adapter Configuration wizard will fail with the following message:

     The wrapper procedure, TOPLEVEL$TEST, could not be found 

  5. As a workround, exit JDeveloper BPEL Designer and restart it after recreating the stored procedure, but before attempting to create the second partner link.