About Adapter for Oracle Applications

Overview of the Adapter

IBM webMethods Adapter for Oracle Applications is an add-on to IBM webMethods Integration Server that allows you to exchange data with Oracle Applications systems. The adapter provides seamless and real-time communications to and from the Oracle Applications system without requiring changes to the existing security infrastructure.

Using Adapter for Oracle Applications, Integration Server clients can run services that execute transactions to retrieve data from, and insert and update data into, Oracle Applications systems. For example, you can use Adapter for Oracle Applications in a flow that receives an XML-based purchase order and then inserts a sales order into an Oracle Applications system.

The adapter also provides user interfaces that enable you to configure and manage adapter connections, adapter services, adapter notifications, and transaction definitions.

Sample transaction definitions are available that you can use when configuring your own adapter services. You can use the samples as they are provided, or you can modify them or create new transaction definitions customized for your needs. This flexibility facilitates integration with highly customized Oracle Applications .

For Oracle Applications integrations that are not highly customized, there are sets of predefined transaction services that are available as add-ons to Adapter for Oracle Applications. Predefined transaction services are complete, ready-to-use flow services that simplify the process of integrating with Oracle Applications systems. In most cases, you can use these services as they are supplied. You only need to modify a connection to specify your Oracle Applications system connection information.

Architecture and Components

Adapter for Oracle Applications provides a set of user interfaces, services, and templates that enable you to create integrations with Oracle Applications systems. The adapter is provided as a single package that must be installed on Integration Server. For detailed installation instructions, see Installing Adapter for Oracle Applications. For a list of the operating systems, Oracle products, and webMethods products supported by Adapter for Oracle Applications , see IBM webMethods Adapters System Requirements.

Because Adapter for Oracle Applications uses an Oracle Thin JDBC driver to access the data in an Oracle Applications system, the adapter requires the driver to be installed and loaded in the packages directory of Integration Server.

The following diagram shows at a high level how the adapter components connect to an Oracle Applications system.

IBM webMethods Integration Server . Adapter for Oracle Applications is installed and runs on Integration Server.
WmART Package. The WmART package provides a common framework and later adapters to use Integration Server functionality, making Integration Server the run-time environment for Adapter for Oracle Applications. The WmART package is installed with Integration Server.
Adapter for Oracle Applications . Adapter for Oracle Applications is delivered as a single package called WmOAAdapter .
Adapter for Oracle Applications provides Integration Server Administrator and Designer user interfaces that enable you to configure and manage adapter connections, adapter services, adapter notifications, and transaction definitions.
Adapter Connection Templates. Adapter connections enable Adapter for Oracle Applications to connect to Oracle Applications systems. You must configure an adapter connection before you can configure adapter services or notifications.
The adapter provides a template for adapter connections in Integration Server Administrator. For a detailed description of adapter connections, see Adapter Connections.
Adapter Service Templates. Adapter services enable Integration Server to initiate and perform operati0ons on the Oracle Applications system.
The adapter provides templates for adapter services in Designer. For a detailed description of adapter services, see Adapter Services.
Adapter Notification Templates. Adapter notifications enable Adapter for Oracle Applications to process data from an event that has occurred on an Oracle Applications system. Adapter for Oracle Applications uses a polling mechanism that supports polling services to provide Oracle Applications -to-Integration Server notification capabilities.
The adapter's polling notification template is available in Designer. For a detailed description of polling notifications, see Adapter Notifications.
Oracle Thin JDBC Driver. Enables Adapter for Oracle Applications to access the data in an Oracle Applications system. For more information about the JDBC driver, see Setting Up Your Adapter's Environment.
webMethods Repository or Shared Cache. The repository or shared cache contains the adapter's transaction definition information. It also maintains the status of services running in the cluster.

The following diagram illustrates a typical business-process integration involving Adapter for Oracle Applications.

Package Management

Adapter for Oracle Applications is provided as a package called WmOAAdapter . You manage the adapter package the same way you manage any package on Integration Server. There are several considerations regarding how you set up and manage your packages on Integration Server, such as those described in the following list.

Create user-defined packages for your connections, adapter services, and adapter notifications. See Adapter for Oracle Applications Package Management for details.
Understand how package dependencies work so you make the best decisions regarding how you manage your connections, adapter services, and adapter notifications. See Setting Package Dependencies for details.
Control which development groups have access to which adapter services and adapter notifications. See Group Access Control for details.
Understand how clustering, an advanced feature of Integration Server, works to effectively manage your adapter services and adapter notifications. See Adapter for Oracle Applications in a Clustered Environment for details.
Enable and disable packages. See Enabling and Disabling Packages for details.
Load, reload, and unload packages. See Loading, Reloading, and Unloading Packages for details.

Adapter Connections

Adapter for Oracle Applications connects to an Oracle Applications system using a JDBC driver and adapter connections.

Adapter connections contain sets of connection parameters, including the logon parameters that the adapter needs to connect to the Oracle Database Server supporting the release of the Oracle Applications Server. Using Integration Server Administrator, you configure Adapter for Oracle Applications connections for use with adapter services and adapter notifications. You must configure an adapter connection before you can configure an adapter service or adapter notification.

If you are configuring your own adapter services, you configure one or more adapter connections at design time to use in integrations. To use Adapter for Oracle Applications you must first configure one or more adapter connections, depending on your environment. For example, if you have multiple installations of Oracle Applications , you can access each installation using separate adapter connections. In addition, if you have a test system and a production system, you can configure an adapter connection for each system.

If you are using the predefined transaction services, you do not need to configure a connection because one is included. The underlying transaction definitions used by the predefined transaction services have all been preconfigured to use the same connection, allowing the services to connect to only one Oracle Applications system at a time. You only need to edit the connection parameters to specify your database connection information. For more information about how connections are used with the predefined transaction services, see the IBM webMethods Adapter for Oracle Applications Predefined Transaction Services Installation and User's Guide for the version of Oracle Applications with which you are using the adapter.

For instructions for configuring, viewing, editing, enabling, and disabling Adapter for Oracle Applications connections, see Adapter Connections. For information about setting user privileges, see IBM webMethods Integration Server Administrator’s Guide for your release.

Using the JDBC Driver to Connect to `Oracle Applications`

Adapter for Oracle Applications connections access databases using the Oracle Thin JDBC driver.

The JDBC driver must be installed on the Integration Server machine and loaded when the adapter starts. See Installing Adapter for Oracle Applications for instructions.

Transaction Management of Adapter for Oracle Applications Connections

Adapter for Oracle Applications connections support the LOCAL_TRANSACTION transaction type. With this transaction type, all of the operations on the same connection in one transaction boundary will be committed or rolled back together. A transaction boundary means the scope of the transaction, from the beginning to the end of a transaction. It can be in one adapter service, one flow service, one Java service, or several steps in a flow service. This transaction type maintains the integrity of your business documents.

Note: The adapter also provides a NO_TRANSACTION type; however, we strongly suggest that you do not use it. Using this type of configuration the connection automatically commits (Auto Commit) all database operations.

When you configure a connection, the transaction type that you choose determines the type of transaction management that the connection's operations use implicitly. Implicit transactions are managed by the Integration Server transaction manager.

You can also explicitly manage transactions using built-in services. See Built-In Transaction Management Services for information about, and examples of, explicitly managing transactions.

Connection Pools

Integration Server includes a connection management service that dynamically manages connections and connection pools based on configuration settings that you specify for the connection. All adapter services use connection pooling.

A connection pool is a collection of connections with the same set of attributes. Integration Server maintains connection pools in memory. Connection pools improve performance by enabling adapter services to reuse open connections instead of opening new connections.

Run-Time Behavior of Connection Pools

When you enable a connection, Integration Server initializes the connection pool, creating the number of connection instances you specified in the connection's Minimum Pool Size field when you configured the connection. Whenever an adapter service needs a connection, Integration Server provides a connection from the pool. If no connections are available in the pool, and the maximum pool size has not been reached, the server creates one or more new connections (according to the number specified in the Pool Increment Size field) and adds them to the connection pool. If the pool is full (as specified in Maximum Pool Size field), the requesting service will wait for Integration Server to obtain a connection, up to the length of time specified in the Block Timeout field, until a connection becomes available. Periodically, Integration Server inspects the pool and removes inactive connections that have exceeded the expiration period that you specified in the Expire Timeout field.

You can enable the system to retry the initialization any number of times, at specified intervals. For information about configuring connections, see Adapter Connections.

Built-In Services For Connections

Integration Server provides built-in services that enable you to programmatically control connections. You can use them to enable and disable a connection, and to return usage statistics and the current state (Enabled or Disabled) and error status for a connection. These services are located in the WmART package, in the pub.art.connection folder.

There are also two built-in services, pub.art.service:setAdapterServiceNodeConnection and pub.art.notification:setPollingNotificationNodeConnection, that enable you to change the connection associated with an adapter service or notification respectively. Read more about these services in the section Changing the Connection Associated with an Adapter Service or Polling Notification at Design Time.

Changing the Connection Associated with an Adapter Service or Polling Notification at Design Time

Integration Server provides built-in services that you can use at design time to change the connection associated with an adapter service or polling notification. These built-in services are named pub.art.service:setAdapterServiceNodeConnection and pub.art.notification:setPollingNotificationNodeConnection. Using these services, you can change the specific connection associated with an adapter service or polling notification at design time so that you do not need to recreate adapter services or polling notifications.

Note: These built-in services can be run at design time only; do not use them within an Integration Server flow or Java service. You must run this service directly from Designer by selecting the service and running it.

For details, see the IBM webMethods Integration Server Built-In Services Reference for your release.

Other built-in services enable you to control connections; for more information, see Built-In Services For Connections.

Changing the Connection Associated with an Adapter Service at Run Time

Integration Server enables you to dynamically select the connection a service uses to interact with the adapter's resource. This feature enables one service to interact with multiple, similar backend resources.

For example, a service can be defined to use a default connection that interacts with your company's North American Oracle Applications database. However, at run time you can override the default connection and instead use another connection to interact with the company's European Oracle Applications database.

For more information about overriding a service's default connection at run time, see Dynamically Changing a Service's Connection at Run Time.

Transaction Definitions

Transaction definitions define the processing that the adapter services perform in Oracle Applications systems. Transaction definitions can map to open interface tables, stored procedures, views, and raw SQL statements.

Sample transaction definitions are available that you can use to configure your own adapter services. You can modify the sample transaction definitions or create new transaction definitions customized for your needs. For more information about the sample transaction definitions, see the IBM webMethods Adapter for Oracle Applications Sample Transaction Definitions User’s Guide.

If you are using the predefined transaction services, you do not need to do anything with the transaction definitions. However, if you want to customize any of the transaction definitions from which the services were partially created, or if you want to configure new transaction definitions, you can do so using the adapter's page in Integration Server Administrator. For example, you might want to customize a transaction definition for a send service if the service delivers more business document fields than you need. For more information about the transaction definitions used with the predefined transaction services, see the IBM webMethods Adapter for Oracle Applications Predefined Transaction Services Installation and User's Guide for the version of Oracle Applications with which you are using the adapter.

For information about importing, exporting, configuring, and managing transaction definitions, see Transaction Definitions.

Adapter Services

Adapter services enable an Integration Server to initiate operations on Oracle Applications systems. Adapter services use transaction definitions to determine the processing to perform on an Oracle Applications system.

Adapter for Oracle Applications enables you to configure customized adapter services that you can use to integrate with Oracle Applications systems. You configure adapter services using adapter service templates, which are provided with Adapter for Oracle Applications. For more information about the templates, see Adapter Service Templates.

You will need to configure your own adapter services if:

You are using the predefined transaction services but you have a highly customized Oracle Applications system and some of the predefined transaction services do not meet your needs, or
You want to continue to use the adapter services that were created and generated with versions of Adapter for Oracle Applications earlier than 6.0.

You can create a webMethods client that invokes the adapter service, or you can integrate the adapter service into an existing flow service. For example, if you want to code a webMethods client that creates a customer order from a purchase order, code the webMethods client to invoke the service that executes the OEOrderImport transaction of Oracle Order Management.

Adapter Service Templates

You use adapter service templates to configure adapter services. Each adapter service template represents a specific Oracle Applications operation. For example, the Insert SQL template enables you to insert business documents into the Oracle Applications open interface tables in one operation.

Adapter service templates contain all of the code that is necessary to perform an operation on an Oracle Applications system, but without the Oracle Applications data specifications. You provide these specifications through transaction definitions when you configure an adapter service.

Configuring a new adapter service from an adapter service template is straightforward. Using Designer, you assign the service a default adapter connection, select the adapter service template, and supply your transaction definition.

After you configure an adapter service, you can incorporate it into a flow service or Java service to interact with an Oracle Applications system. For example, you can create a flow service that collects customer order information from another one of your backend systems and then within that service you can call an Insert SQL service to insert the customer order information into your Oracle Applications system.

Adapter for Oracle Applications provides the following adapter service templates for adapter services:

Adapter Service Template	Description
Insert SQL	This type of service is used to insert business documents into `Oracle Applications` using the open interface tables names specified in the IS-to- `Oracle Applications` transaction definitions. You can execute this service with an Error service (using the Simple SQL service template) to verify the status of the import performed by the concurrent process. See Configuring Insert SQL Services for instructions.
Compound Select SQL	This type of service is used to query an `Oracle Applications` system and retrieve data based on the query conditions (specified in either a SQL tree or stored procedure). You can execute this service with an Acknowledge service (using the Simple SQL service template) to notify `Oracle Applications` that the document has been processed. This prevents the document from being retrieved multiple times. See Configuring Compound Select SQL Services for instructions.
Simple SQL	Use this template to create Acknowledge services or Error services: When used with a Compound Select SQL service, Acknowledge services maintain an accurate status of the transactions within the Oracle system. You create an Acknowledge service from an `Oracle Applications` -to-IS transaction definition that either calls a stored procedure or executes a SQL UPDATE statement to tell the `Oracle Applications` instance that the transaction has been processed. When used with an Insert SQL service, Error services query `Oracle Applications` for errors that might have occurred during the import process. You create an Error service from an IS-to- `Oracle Applications` transaction definition that is based on a stored procedure, view, or SQL SELECT statement. The service receives the query parameters for the SQL statement via the service specification. See Configuring Simple SQL Services for instructions.

Adapter Service Template

Description

Insert SQL

This type of service is used to insert business documents into Oracle Applications using the open interface tables names specified in the IS-to- Oracle Applications transaction definitions.

You can execute this service with an Error service (using the Simple SQL service template) to verify the status of the import performed by the concurrent process.

See Configuring Insert SQL Services for instructions.

Compound Select SQL

This type of service is used to query an Oracle Applications system and retrieve data based on the query conditions (specified in either a SQL tree or stored procedure).

You can execute this service with an Acknowledge service (using the Simple SQL service template) to notify Oracle Applications that the document has been processed. This prevents the document from being retrieved multiple times.

See Configuring Compound Select SQL Services for instructions.

Simple SQL

Use this template to create Acknowledge services or Error services:

When used with a Compound Select SQL service, Acknowledge services maintain an accurate status of the transactions within the Oracle system. You create an Acknowledge service from an Oracle Applications -to-IS transaction definition that either calls a stored procedure or executes a SQL UPDATE statement to tell the Oracle Applications instance that the transaction has been processed.
When used with an Insert SQL service, Error services query Oracle Applications for errors that might have occurred during the import process. You create an Error service from an IS-to- Oracle Applications transaction definition that is based on a stored procedure, view, or SQL SELECT statement. The service receives the query parameters for the SQL statement via the service specification.

See Configuring Simple SQL Services for instructions.

Predefined Transaction Services

Predefined transaction services are complete, ready-to-use flow services that simplify the process of integrating with Oracle Applications systems. Available as an add-on to Adapter for Oracle Applications, predefined transaction services are available for different versions of Oracle Applications .

In most cases, you can use these services as they are supplied. To use predefined transaction services you must reconfigure the associated connection to match your Oracle Applications system connection information. However, if necessary, you can use the adapter to modify the services or their underlying transaction definitions.

See the IBM webMethods Adapter for Oracle Applications Predefined Transaction Services Installation and User's Guide for the version of Oracle Applications with which you are using the adapter for a detailed description of the components involved in the predefined transaction services. The guides also include information about the transaction definitions used by the predefined transaction services, including where to locate them and how to import them into your webMethods system.

Adapter Notifications

An adapter notification enables Adapter for Oracle Applications to retrieve data from an Oracle Applications system at regular intervals and publish a document. The notification retrieves the data based on query conditions specified in either an SQL Tree or a stored procedure.

You must create a trigger on the Integration Server for the publishable document associated with the notification. This trigger identifies the receiver of the published document. For more information about creating triggers and working with publishable documents, see the Publish-Subscribe Developer’s Guide for your release.

Note: Adapter notifications do not use Acknowledge services. Without an Acknowledge service you may not be able to guarantee that the Oracle Applications event is only retrieved once. If you need to guarantee that the Oracle Applications event is retrieved only once, you should create the notification using a stored procedure, and that stored procedure should update the record in Oracle Applications to indicate that it is being processed.

Any exception produced by the notification is logged in the Integration Server Error Audit Log.

Use Designer to configure, edit, and delete polling notifications. All notifications are configured from a notification template and require a configured connection.

Beginning with Integration Server 8.0, you can choose whether the asynchronous notification templates use JMS APIs to publish messages to Integration Server or IBM webMethods Broker APIs to publish notification messages to IBM webMethods Broker. For more information, see Adapter Notifications.

Note: To use the JMS protocol with both polling and listener asynchronous notifications, you must first configure a JMS connection alias on Integration Server. For more information about configuring Integration Server for JMS messaging, see the IBM webMethods Integration Server Administrator’s Guide for your release.

Using Integration Server Administrator you can display all polling notifications that have been configured for Adapter for Oracle Applications. You can also enable notifications and schedule them for execution. A notification can also be disabled; however, this is separate from the containing Integration Server package being disabled. If the Integration Server package is disabled, the notification is suspended, but the notification is not disabled. When the package containing the notification is enabled, the scheduled execution resumes. If the notification is disabled it will not be executed until it is enabled.

For instructions about how to configure and manage notifications, see Adapter Notifications.

Using Version Control Systems to Manage Adapter Elements

The adapter supports the Version Control System (VCS) Integration feature provided by Designer. When you enable the feature in Integration Server, you can check adapter packages or elements into and out of your version control system from Designer. For more information about the VCS Integration feature, see the Configuring the VCS Integration Feature.

Beginning with Integration Server 8.2 SP3, the adapter supports the local service development feature in Designer. This feature extends the functionality of the VCS Integration feature to check package elements and their supporting files into and out of a VCS directly from Designer. For more information about local service development and how it compares to the VCS Integration feature, see the IBM webMethods Service Development Help.

Optimize Infrastructure Data Collector Support for Oracle Applications Adapter

Optimize Infrastructure Data Collector monitors the system and operational data associated with webMethods run-time components such as Integration Servers, Broker Servers, Brokers, and adapters, and reports the status of these components on Optimize for Infrastructure or other external tools. When you start monitoring an Integration Server, Infrastructure Data Collector automatically starts monitoring all ART-based adapters that are installed on the Integration Server.

For information about monitored key performance indicators (KPIs) collected for the monitored adapter components, see the Administering IBM webMethods Optimize and IBM webMethods Optimize User’s Guide for your release.

Viewing the Adapter's Update Level

You can view the list of updates that have been applied to the adapter. The list of updates appears in the Updates field on the adapter's About page in Integration Server Administrator.

Controlling Pagination

About this task

When using the adapter on Integration Server, you can control the number of items that are displayed on the adapter Connections screen and Notifications screen. By default, 10 items are displayed per page. Click Next and Previous to move through the pages, or click a page number to go directly to a page.

To change the number of items displayed per page, set the watt.art.page.size configuration parameter and specify a different number of items.

To set the number of items per page

Procedure

From Integration Server Administrator, click Settings > Extended.
Click Edit Extended Settings. In the Extended Settings editor, add or update the watt.art.page.size configuration parameter to specify the preferred number of items to display per page. For example, to display 50 items per page, specify:
```
watt.art.page.size=50
```
Click Save Changes. The configuration parameter appears in the Extended Settings list.

For more information about working with extended configuration settings, see the IBM webMethods Integration Server Administrator’s Guide for your release.