Oracle® Application Server Integration InterConnect Adapter for Oracle Applications Installation and User's Guide
10g Release 2 (10.1.2) B14360-02 |
|
Previous |
Next |
This chapter describes the design-time and run-time concepts for the OA adapter. It contains the following topics:
The OA adapter acts as a highly flexible integration interface to the Oracle Applications. This section describes the design-time aspects of the OA adapter. The OA adapter provides the following interfaces to integrate with the Oracle Applications:
This interface type is used to integrate with Oracle Applications through direct database access using tables/views/APIs/ADTs. This interface type enables you to define your Application or Common Views using the database tables/views/APIs/ADTs in Oracle Applications. This interface shields integration code from underlying changes, which may exist between apps versions. As a result, it is suitable for performing DML operations against the Oracle Applications. Custom staging tables may also be used for inbound data to provide reporting and editing prior to application to base tables. Custom Object or XML views can be created which provide the structures necessary for producing outbound messages.This method is mainly used when the volume of data is large. Once the data is received in the table or by the API, you have to ensure that all messages (successful and errored) are backtracked.
This interface type should be used to integrate with Oracle Applications using XML Gateway. This interface type enables you to define your Applciation or Common Views by importing one of the Oracle Applications prescribed DTDs. While publishing/subscribing events and invoking/implementing procedures, iStudio will automatically retrieve the standard queue header fields required for XML Gateway queue and define the Payload field (ANY type) with the imported DTD. Oracle provides out of the box implementations of OAG documents, which can be integrated with OracleAS Integration InterConnect. The BOD's provided are tightly integrated with seeded workflows and API's. Thus, they can be quickly implemented with a minimum of custom development.
Workflow Business Event System (BES)
This interface type can be used to integrate with Oracle Applications using Workflow BES queue. This interface type enables you to define you Application or Common Views either importing database tables/views/APIs/ADTs (from Oracle Applications) or by importing a DTD file. While publishing/subscribing events and invoking/implementing procedures, iStudio will automatically retrieve the standard queue header fields required for Workflow BES queue and define the EVENT_DATA field (ANY Type) with the imported definition. BES in conjunction with Worfklow enables you to include other systems in seeded or custom workflows. Workflow is tightly integrated with many apps modules and is ideal for producing and consuming event based messages. BES/Worfklow may also be used to model long running and conversational type integration processes. Availability of predefined business events in Oracle Applications plays a big role in deciding which message can be logically grouped together instead of at the table level.
While using the WF BES Interface, set the recipient list on the message that you are enqueuing on to the BES queue, by using the AddHeader transformation to create an aq_recipients
field in the message header. Then, add the recipients to the aq_recipients field. OracleAS Integration InterConnect AQ adapter will automatically use the contents of aq_recipients as the recipient list for the message.
This interface type can be used to integrate with the Oracle Applications using custom queues, if you are unable to use either XML Gateway or Workflow BES queue. This interface type enables you to define your Application or Common Views by either importing database tables/views/APIs/ADTs (from Oracle Applications) or by importing a DTD file. In this case, you are responsible for defining the queue headers, if required, as well as the payload part of the queue. Custom queues are often defined for very specific tasks or situations where very high throughput is required. User-defined payloads can provide quick access to message metadata without the overhead of xml parsing. Custom queues may also be integrated with BES by developing queue handlers. This method is suitable when message payload is large and dynamic in nature. It also fits well with XML handling capabilities of the database and can be easily used with the Workflow both standalone and embedded.
OA adapter supports both the publish/subscribe and request/reply messaging paradigms. To create the message definitions, you must invoke the required wizards. For example, to create a publish event, you must use the Publish wizard, as described in the following steps:
In the Design Navigation list, expand the Application node.
Right-click Published Events and select New. The Publish Wizard is displayed.
Enter following information in the fields:
Application: The name of the invoking application is selected by default.
Message Type: The mode of communication between OracleAS Integration InterConnect and the application. Select the Oracle Applications message type.
Select the event name.
Click Next. The Select Interface Type dialog box is displayed.
Select the type of interface from which the definition is to be imported. The interface types are:
Tables/Views/APIs
XML Gateway
Workflow Business Event System
Custom Queue
Click Next. The Define Application View dialog box is displayed.
Once an event is selected to publish, the application view is defined. The application view dialog box is initially an empty table.
Click Import to import the definitions. A list of Import options are displayed.
Depending on the option selected in Step 6, the import menu options vary, as displayed in Table 3-1.
Table 3-1 Import Menu Options
If you had selected... | Import Menu Options are... |
---|---|
Tables/Views/APIs |
Common View, Application Data Type, Common Data Type, Tables/Views/APIs |
XML Gateway |
Application Data Type, Common Data Type, XML Gateway, XML |
Workflow Business Event System |
Application Data Type, Common Data Type, Tables/Views/APIs, XML |
Custom Queue |
Common View, Application Data Type, Common Data Type, Tables/Views/APIs, XML |
If you select Common View, Application Data Type, or Common Data Type, then the steps to be followed are identical to those explained in the Oracle Application Server Integration InterConnect User's Guide.
If you select the XML option from the Import Menu, then go to Step 11.
If you select Tables/Views/APIs, then the Oracle Applications Login dialog box is displayed as shown in Step 9.
Enter information in the following fields:
User Name: The database log in name. By default, the user name for the application schema of the Oracle Applications is apps.
Password: The database log in password.
URL: The computer name: port number: database SID
.
Driver: The JDBC driver used to connect to the database.
Save settings as default: Select this check box to save the settings for the workspace.
Click Login. The Oracle Applications Browser is displayed.
The browser displays the list of installed modules. You can use the following approaches to find the desired object:
Browse Modules: Browse through the list of modules displayed, and select the desired object. The attributes of the selected object are displayed on the right pane of the Browser. Select the desired attributes, and click Apply. The Define Application View dialog box is displayed with the selected attributes. Go to Step 14 to continue.
Note: For PL/SQL APIs, the browse mode only displays the PL/SQL packages that start with the module short name.For example, if the Oracle Receivables module has the short name "AR", then AR_package name packages only will be displayed under this module. If the Oracle Receivables module has RA_package name and HZ_package name packages also, then these will not be displayed under this module. For all other PL/SQL packages that logically belong to a module but do not show up where expected, use the search functionality. |
Search Object: Use the search facility to search for the desired object in the Oracle Applications schema. Enter the object name in the Object Name field, and select the required object types (Tables, Views, APIs, ADTs).
If you are not sure of the complete name of the desired object, then you can enter the entire object name that you are looking for or use the wild card '%', for example, AMV_STOCK%
. You must select at least one of the database object types listed at the top of the dialog box to enable the Search button.
Click Search to display the list of matching object names. Select the desired object, the attributes of the selected object are displayed on the right pane of the Browser. Select the desired attributes, and click Apply. The Define Application View dialog box is displayed with the selected attributes. Go to Step 14 to continue.
Note: To return from the Search option to the Browse option, click the Browse button. |
If you have selected XML Gateway in Step 6, then the XML Gateway Browser is displayed. In the Browser, the left pane displays a list of DTDs and the right pane displays the details of the DTD such as its root element, file name, version, description, and payload. Also, the payload details of the selected DTD are displayed, as shown in the following figure. Select a DTD, and click Apply. The Define Application View dialog box is displayed with the selected attributes. Go to Step 14 to continue.
The Open dialog box is displayed. Select a DTD file, and click Open.
The Choose Root Element dialog box is displayed. Select a root DTD element.
Click OK. The Define Application View dialog box is displayed with the imported DTD.
Click Next in the Define Application View page. The Define Mapping page is displayed. Mapping involves copying the individual fields or simple shape-change transformations.
Click Define Mappings to define new mappings. The Mapping Parameters dialog box is displayed.
Use a transformation to map fields in the application view to fields in the common view. For example, to map fields in the FirstName
and LastName
in the common view to Name
in the application view, use the ExpandFields
transform.
Click OK to return to the Publish Event Wizard.
Click Finish.
You have successfully created a publish event using iStudio, leveraging the OA adapter. The steps for the creation of subscribe events, as well as for invoking and implementing procedures, are similar to those described in the preceding steps.
This section describes the key run-time components of the OA adapter. You can choose one or more of the interface types to connect to a single Oracle Applications instance. The adapter is designed so that a single adapter instance can handle all the different interface types (inbound and outbound) for one application instance. You do not need to have dedicated adapters for each interface type.
This section contains the following topics:
On the subscribing/receiving side, the OA adapter receives the message from the hub, transforms it from common view to application view, and passes it to the bridge that
calls the required PL/SQL procedures to inform the application about the newly arrived message if the interface type is Tables/Views/APIs.
enqueues the message to the subscribe queue configured through the Deploy tab of iStudio if the message is for one of the queue interface types (XML Gateway, Custom Queue, and Workflow BES). The application should then pick this message from this queue.
Note: The adapter subscribing to an event should be started before any other adapter can publish that event. If you publish an event before starting the subscribing adapter, then the event would not be delivered to the subscribing adapter. |
The OA adapter is comprised of the bridge and the run-time agent. This bridge has two different modes of communication with the Oracle Applications instance:
Database Access: Interface Type: Tables/Views/APIs
One part of the bridge component is constantly polling the MESSAGEOBJECTTABLE
table in the oai schema, specified by the oa_bridge_schema_username
parameter. A new row in this table indicates a new outbound OracleAS Integration InterConnect message waiting to be sent by this adapter. The adapter then picks up the message from the interface tables residing in the oai schema, builds the corresponding OracleAS Integration InterConnect message, persists it, transforms it to the common view, and routes it to the hub. From the hub, the message gets routed to the required subscriber based on configuration completed in iStudio, which can be content-based or subscription-based.
The application and the OA adapter communicate in the form of direct database access through the interface tables residing in the oai schema for outbound messages and through iStudio PL/SQL generated procedures for inbound messages. Therefore, if the adapter is down while the application is publishing OracleAS Integration InterConnect messages using the iStudio generated PL/SQL procedures, the messages are held in the interface tables and will be picked up in a FIFO method by the OA adapter once it is up and running. If there are messages in the interface tables that no longer need to be published, then the DELETE FROM MESSAGEOBJECTTABLE
using SQLPlus can be run in the oai schema.
The second part of the OA adapter is constantly polling one or more queues (XML Gateway, Workflow BES, Custom Queue) selected for publishing messages in the apps
schema. A new message in this queue indicates a new outbound OracleAS Integration InterConnect message waiting to be sent by the adapter. The adapter then picks up the message, builds the corresponding OracleAS Integration InterConnect message, persists it, transforms it to the common view, and routes it to the hub. From the hub, the message is routed to the required subscriber based on configuration done using iStudio, which could be content-based, or subscription-based.
The application and the OA adapter communicate through the publishing and invoking queues, residing in the apps
schema for outbound messages and through subscribing and implementing queues for inbound messages. Therefore, the OA adapter is down while the application is publishing OracleAS Integration InterConnect messages. These messages are held in the queues and will be picked up in the order they were enqueued by the OA adapter once it is up and running. If there are messages in the queues, which should no longer be published, dequeue them manually.
Based on the operating system, the process for starting the adapter varies.
To start the OA adapter on UNIX:
Change to the directory containing the start script.
cd ORACLE_HOME/integration/interconnect/adapters/Application
Type start
and press Enter.
To start the OA adapter from Services on Windows:
Access the Services window from the Start menu.
Select the OracleHomeOracleASInterConnectAdapter-Application service.
Start the service.
Note: You can also start and stop the OA adapter using the IC Manager. Refer to OracleAS InterConnect User’s Guide for more details. |
You can verify the start up status by viewing the log.xml
files. The files are located in the time-stamped subdirectory of the log
directory of the OA adapter. Subdirectory names take the following form:
timestamp_in_milliseconds
The following is an example of the information about an OA adapter that started successfully:
The Adapter service is starting.. Registering your application (OAAPP).. Initializing the Bridge oracle.oai.agent.adapter.ebusiness.EBSBridge.. Starting the Bridge oracle.oai.agent.adapter.ebusiness.EBSBridge.. oa_bridge_reader_1 has been started. Service started successfully. oa_bridge_writer_1 has connected to the database successfully. oa_bridge_reader_1 has connected to the database successfully.
Based on the operating system, the process for stopping the adapter varies.
To stop the OA adapter on UNIX:
Change to the directory containing the stop script.
cd ORACLE_HOME/integration/interconnect/adapters/Application
Type stop
and press Enter.
To stop the OA adapter from Services on Windows:
Access the Services window from the Start menu.
Select the OracleHomeOracleASInterConnectAdapter-Application service.
Stop the service. Based on the operating system, the method for stopping it varies.
You can verify the stop status of the OA adapter by viewing the log.xml
files. These files are located in the time-stamped subdirectory of the log
directory of the OA adapter.