Oracle E-Business Suite


WebSphere Adapter for Oracle E-Business Suite documentation

With IBM WebSphere Adapter for Oracle E-Business Suite, you can create integrated processes that include the exchange of information with Oracle E-Business Suite, without special coding.


Overview of IBM WebSphere Adapter for Oracle E-Business Suite

With IBM WebSphere Adapter for Oracle E-Business Suite, you can create service-oriented integrated applications, which can interact and exchange information with Oracle E-Business Suite. By using the adapter, you can send requests and receive events from the underlying Oracle database, without special coding.

WebSphere Adapter for Oracle E-Business Suite enables a two-way communication between the application running on IBM Business Process Manager or WebSphere Enterprise Service Bus and the underlying Oracle database of Oracle E-Business Suite. Using the adapter, an application can send requests to read, create, modify, or delete data in the Oracle database, in many cases without writing any SQL code. To process requests received from an application, the adapter updates the Oracle database tables using SQL queries or stored procedures. An application can also receive events from the Oracle E-Business Suite. For example, it can be notified that specific objects in Oracle E-Business Suite are updated. To process events that result from changes to the Oracle E-Business Suite, the adapter delivers events to the application. Using the Oracle Business Event System and event notification, changes to the Oracle E-Business Suite can be automatically notified to other applications. By combining event processing by WebSphere Adapter for Oracle E-Business Suite and another adapter, updates can be automatically propagated to other enterprise applications such as Siebel, PeopleSoft, and SAP.

WebSphere Adapter for Oracle E-Business Suite provides a standard interface that integrates with the underlying Oracle database of the Oracle E-Business Suite applications; it supports the Oracle database server by using the Oracle Java™ Database Connectivity (JDBC) drivers. The JRE version required by the Oracle JDBC driver must not be higher than the JRE version in the run time environment. The adapter uses business objects to exchange data between the application and the Oracle database, so the application does not need to use the JDBC application programming interface (API). Business objects are containers for application data that represent business functions or elements, such as an Oracle table or the result of an SQL query. The adapter understands the data format provided by the application, and can process the data, perform the operation, and send the results back in that format.


Feedback


Hardware and software requirements

The hardware and software requirements for WebSphere Adapters are provided on the IBM Support website.

To view hardware and software requirements for WebSphere Adapters, see http://www.ibm.com/support/docview.wss?uid=swg27006249.


Additional information

The following links provide additional information you might need to configure and deploy your adapter:


Feedback


Technical overview of IBM WebSphere Adapter for Oracle E-Business Suite

The adapter supports integration of databases that are accessible through the JDBC application programming interface (API) with applications running on IBM Business Process Manager or WebSphere Enterprise Service Bus. The adapter provides outbound and inbound processing under the Java™ Platform, Enterprise Edition (JEE) Connector Architecture (JCA) and integrates with Service Component Architecture (SCA) components.

Outbound processing enables an application to access or modify data in a database. The adapter converts a request from the application to an outbound operation, which it runs to create, retrieve, update, or delete data in the database or to run a database program stored in the database. Processing these requests results in the creation, retrieval, update, or deletion of rows in the corresponding database tables. The adapter also enables you to run stored procedures or stored functions that are defined in the database, and to run user-defined SELECT, INSERT, UPDATE, and DELETE statements. You can use the adapter to integrate multiple applications with the same database.

Figure 1 presents an overview of the flow of outbound processing.

An application running on IBM Business Process Manager or WebSphere Enterprise Service Bus starts a service in an outbound module, which sends a request to the adapter to process one or more business objects. The adapter uses the JDBC API to connect to the database server, which accesses the tables and other objects.

Figure 1. Processing outbound requests

Inbound processing enables an application to receive notification when objects are changed. For example, an application can be notified when rows are created, updated, or deleted in selected database tables.

Figure 2 presents an overview of the flow of inbound processing.

A database application changes tables in the database. The change causes a trigger, or another automated mechanism, to update the event store with information about the change. Periodically, the adapter polls the event store, retrieves, and processes events, and then delivers them to the export of a module that is part of an application that runs in BPM or WebSphere Enterprise Service Bus.

Figure 2. Processing inbound events

The adapter can process events in one of the following ways:

During standard event processing, when data is changed in the tables in the database, appropriate events are inserted into a database table called an event store, along with relevant information, such as key values. To capture the changed data in the database, you can place triggers on the respective tables, or use other methods such as Oracle Change Data Capture, which is provided for Oracle databases. To capture the changed data in Oracle E-Business Suite, configure the Oracle Business Event system and Concurrent Program. The adapter polls the event store, and retrieves a batch of events. The events can be filtered by business object type and time stamp and connector ID. The adapter uses each event to construct a business graph or business object that contains the business objects changed by that event. The business object or business graph is then dispatched to the exports that are configured to receive the specific business object.

During custom event processing, the adapter runs a query specified by the user as a standard SQL statement, a stored procedure, or a stored function. Any of these actions returns a result set for data returned by the query. Each row of the result set corresponds to a row in the event store. The adapter constructs a business object for each event and delivers it to the exports (also called endpoints) that are configured for (or have subscribed to) the specific business object.

For both standard and custom event processing, you can specify how often the adapter polls for events and how many events it retrieves each polling period.


Feedback


Outbound processing

When an application component needs to query the existence of a record in the database or retrieve or modify data in the underlying Oracle database, the adapter acts as the connector between the application component and the database. The adapter provides a set of standard outbound operations, which process either the after-image or delta style business objects. The adapter also supports both local and XA (distributed) transactions for outbound processing.

The adapter business object model uses two styles of business objects for making updates: after-image and delta. An after-image business object is one that contains the complete state of the business object after the required changes have been made to it. A delta business object is one that contains only key values and the data to be changed. Delta business objects are used only in operations that update business objects.


Supported operations

Table 1 lists the outbound operations that are supported for each type of business object and indicates whether each supports after-image or delta style processing.

Outbound operations supported by type of business objects

Business objects supported Operation After-image support Delta support

Tables Views Synonyms - Nick Names

Create Yes Not applicable
Update Yes Not applicable
Delete Yes Not applicable
Retrieve Not applicable Not applicable
RetrieveAll Not applicable Not applicable
Exists Not applicable Not applicable
ApplyChanges Yes Yes
Stored procedures Execute Not applicable Not applicable
Queries RetrieveAll Not applicable Not applicable
XML Gateway Invoke Not applicable Not applicable
Publish Not applicable Not applicable
Advanced Queue Enqueue Not applicable Not applicable


Transaction management

The adapter supports both local and XA (distributed) transactions for outbound processing. In the adapter, a transaction is an isolated interaction with the database. A transaction consists of multiple operations on the database that are performed as an atomic unit. These operations are not affected by simultaneously occurring operations from other users of the database.

The adapter supports transactions only if the database server supports transactions. The types of transactions that are supported are local and XA transactions:


XA transactions

The adapter supports XA transactions for outbound processing. Choose one of these methods to configure the adapter for XA transactions:

The XADataSourceJNDIName property represents a data source created within BPM or WebSphere Enterprise Service Bus. If you define a JNDI data source that supports XA transactions on the server and specify that data source when you configure the adapter, the adapter participates in XA transactions. Optionally, if you use an XA data source, the adapter participates in XA transactions.



Related reference:

Managed connection factory properties

Feedback


Outbound operations

Application components use operations to perform actions such as retrieving from a database. The adapter provides certain outbound operations. Details are provided on how the adapter processes business objects for each of the supported operations.

An operation can be performed using a standard SQL statement provided by the adapter or by a stored procedure that you define. You can run a stored procedure to perform the operation or to do custom processing before or after the operation. In each business object, you can configure how each operation is performed.



Related concepts:

Outbound processing

Stored procedure overview

Feedback


Create operation

The Create operation creates rows in database tables corresponding to the business object in the request. When given a hierarchical business object, the Create operation recursively traverses the business object, creating rows corresponding to each business object in the hierarchy.

To process the Create operation, the adapter performs the following actions:

  1. Recursively inserts each single-cardinality child business object contained with ownership into the database. In other words, the adapter creates the child and all child business objects the child and its children contain.

    If the business object definition specifies that an attribute represents a child business object with single-cardinality and that attribute is empty, the adapter ignores the attribute. However, if the business object definition requires the attribute represent a child, and it does not, the adapter returns an error, and stops processing.

  2. Retrieves and checks for the existence of each single-cardinality child business object contained without ownership. If the retrieval is unsuccessful, indicating the child does not exist in the database, the adapter returns an error, and stops processing. If the Retrieve operation is successful, the adapter recursively updates the child business object. If the retrieve operation is successful, the adapter continues the process of creating the parent business object; the adapter does not update the child business object without ownership.

    For this approach to work correctly when the child business object exists in the database, primary-key attributes in child business objects must be cross-referenced correctly on Create operations. If the child business object does not exist in the application database, the primary-key attributes must not be set.

  3. Inserts the top-level business object in the database by performing the following actions:

    1. Sets each of the foreign-key values of the top-level business object to the primary key values of the corresponding child business object represented with single-cardinality. Because values in child business objects can be set by database sequences or counters or by the database itself during the creation of the child, this step ensures the foreign-key values in the parent are correct before the adapter inserts the parent in the database.
    2. Generates a new, unique ID value for each attribute that is set automatically by the database. The name of the database sequence or counter is stored in the attribute application-specific information. If an attribute has an associated database sequence or counter, the value generated by the adapter overwrites any value passed in by the application server.
    3. Inserts the top-level business object into the database.

      The adapter treats an empty complex column as null value irrespective of setting it to null or unset.

  4. Processes each of its multiple-cardinality child business objects as follows:

    1. Sets the foreign-key values in each child to reference the value in the corresponding primary key attributes in the parent. Because the parent primary key values might have been generated during the creation of the parent, this ensures the foreign-key values in each child are correct before the adapter inserts the child into the database.
    2. Inserts each of the multiple-cardinality child business objects into the database.



Related concepts:

Retrieve operation

RetrieveAll operation

Update operation

ApplyChanges operation

Delete operation

Execute operation

Exists operation

Invoke operation

Publish operation


Related reference:

Fault business objects

Feedback


Retrieve operation

The Retrieve operation extracts data from a database for a hierarchy of business objects.

To process the Retrieve operation, the adapter performs the following actions:

  1. Removes all child business objects from the top-level business object it received. In other words, it makes a copy of the top-level business object without any children.
  2. Retrieves the top-level business object from the database.

    • If the retrieval operation returns one row, the adapter continues processing.

    • If the retrieval operation returns no rows, indicating the top-level business object does not exist in the database, the adapter returns the RecordNotFoundException error.

    • If the retrieval operation returns more than one row, the adapter returns the MultipleMatchingRecordsException error.

    The Retrieve operation uses only the primary key. Other columns are ignored.

  3. Recursively retrieves all multiple-cardinality child business objects.

    The adapter does not enforce uniqueness when populating an array of business objects. The database is responsible for ensuring uniqueness of the business objects. If the database returns duplicate child business objects, the adapter returns duplicate children.

  4. Recursively retrieves each of the single-cardinality children, regardless of whether the child business object is contained with or without ownership.

    All single-cardinality child business objects are processed based on their occurrence in the business object and before the parent business object is processed.

Retrieve NULL data

The adapter can retrieve a record from a database table when the column value is NULL. For example, a Customer business object might have these columns: custid, ccode, fname, and lname, where custid and ccode form composite keys. Composite keys are primary keys that refer to more than one attribute and are used to define the uniqueness of the business object. You can retrieve a Customer record for which the value of ccode is NULL. The adapter generates a SELECT statement for the Retrieve operation as:



Related concepts:

Create operation

RetrieveAll operation

Update operation

ApplyChanges operation

Delete operation

Execute operation

Exists operation

Invoke operation

Publish operation


Related reference:

Fault business objects

Feedback


RetrieveAll operation

The adapter uses the RetrieveAll operation to retrieve an array of business objects from the database. The adapter uses different processes depending on whether the RetrieveAll operation is for database table business objects or for user-specified SQL business objects.

For database table business objects

All of the key and non-key attributes populated in the incoming business object determine the selection criteria for the retrieval. The adapter can retrieve multiple rows for the top-level business object from the database, depending on the attributes selected. All values specified in the top-level business object are used. The settings in the child business object are ignored. If no attributes are populated in the incoming business object, all the rows are retrieved from the respective table in the database.

The name of a generated business object matches the name of the table in the database. For example, the Customer table in the database is represented as a business object named "Customer".

To retrieve an array of business objects, the adapter performs the following actions:

  1. Constructs a container business object for all of the retrieved rows. The name of the container business object is the name of the business object with the string "Container" appended to it.

  2. If the module is configured to use business graphs, which are optional, then it constructs a top-level business graph for each of the retrieved rows. The name of the business graph is the business object name with the string "BG" appended to it.
  3. Retrieves each of the business graphs in the container using the Retrieve operation.

The following figures show the structure of objects returned from a RetrieveAll operation, with and without business graphs.

Figure 1. Structure of the business object returned in a RetrieveAll operation without optional business graphs

Figure 2. Structure of the business object returned in a RetrieveAll operation with optional business graphs

The following errors can result from a RetrieveAll operation:

For query business objects

Business objects that are created for user-specified SELECT statements (query business objects) also support the RetrieveAll operation. The external service wizard generates the query business object by running the user-specified SQL SELECT statement and creating a hierarchy of query business objects.

If you are using optional business graphs, the hierarchy will be as shown in Figure 3.

Figure 3. User-specified query business objects (with optional business graphs)

If you are not using optional business graphs, the hierarchy will be as shown in Figure 4.

Figure 4. User-specified query business objects (without optional business graphs)

To process the query business object generated by the external service wizard for the user-specified SELECT statement, the adapter performs the following actions:

  1. Obtains the SELECT SQL statement from the query business object.
  2. Determines whether a dynamic WHERE clause is specified in the query business object.

    • If there is a dynamic WHERE clause, the adapter replaces the default WHERE clause in the SELECT statement with the dynamic one.

    • If there is no dynamic WHERE clause, the adapter replaces parameters in the SELECT statement with the corresponding values specified in the query business object.

  3. Runs the SELECT statement.
  4. Obtains the result set that is returned and populates the query business object values with the data returned from the database, creating a container business object with the structure shown in Figure 3.
  5. Retrieves the entire hierarchy (a deep retrieve) of each top-level query business object in the container, if any child business objects are defined for the query business objects.

    A query business object can be a top-level business object only. A query business object cannot have child query business objects.

Retrieve NULL objects

The adapter can retrieve records from a database table when the column value is NULL. For example, a Customer business object might have these columns: custid, ccode, fname, and lname, where ccode need not be a primary key. You can query all the Customer records for which the ccode column is NULL. The adapter generates a select query for the RetrieveAll operation as:



Related concepts:

Create operation

Retrieve operation

Update operation

ApplyChanges operation

Delete operation

Execute operation

Exists operation

Invoke operation

Publish operation


Related reference:

Fault business objects

Feedback


Update operation

In an Update operation, the source business object is compared to a business object that is retrieved from the database using the primary keys specified in the top-level, source business object.

When updating a hierarchical business object, the adapter performs the following actions:

  1. Uses the primary key values of the source business object to retrieve the corresponding entity from the database. The retrieved business object is an accurate representation of the current state of the data in the database.

    If the retrieval fails, indicating the top-level business object does not exist in the database, the adapter returns the RecordNotFoundException exception, and the update fails.

    If the retrieval succeeds, the adapter compares the retrieved business object to the source business object to determine which child business objects require changes in the database. The adapter does not, however, compare values in the source business object's simple attributes to those in the retrieved business object. The adapter updates the values of all non-key simple attributes.

    If all the simple attributes in the top-level business object represent keys, the adapter cannot generate an update query for the top-level business object. In this case, the adapter logs a warning and continues.

  2. Recursively updates all single-cardinality children of the top-level business object.

    If ownership is true and the child is present in the source business object but not in the retrieved business object, the adapter recursively creates the child in the database.

    The adapter handles single-cardinality children contained with ownership in one of the following ways:

    • If the child is present in both the source and the retrieved business objects, instead of updating the existing child in the database, the adapter deletes the existing child and creates the child.

    • If the child is present in the source business object but not in the retrieved business object, the adapter recursively creates the child in the database.

    • If the child is present in the retrieved business object but not in the source business object, the adapter recursively deletes the child from the database.

    For single-cardinality children contained without ownership, the adapter attempts to retrieve every child that is present in the source business object from the database. If it successfully retrieves the child, the adapter populates the child business object but does not update it, because the adapter never modifies single-cardinality children contained without ownership. If the retrieval fails, the adapter returns an ObjectNotFound exception.

  3. Updates all simple attributes of the retrieved business object, except those whose corresponding attribute in the source business object is not specified.

    Because the business object being updated must be unique, the adapter verifies that only one row is processed as a result. If more than one row is returned, the adapter returns an error.

  4. Processes each multiple-cardinality child of the retrieved business object in one of the following ways:

    • If the child exists in both the source and the retrieved business object arrays, the adapter recursively updates it in the database.

    • If the child exists in the source array but not in the array of the retrieved business object, the adapter recursively creates it in the database.

    • If the child exists in the array of the retrieved business object but not in the source array, the adapter recursively deletes it from the database unless the application-specific information for the attribute that represents the child in the parent has the KeepRelationship property set to True. In this case, the adapter does not delete the child from the database.

NULL data and the Update operation

The adapter can update a record from a database table when the column value is NULL. For example, a Customer business object might have these columns: custid, ccode, fname, and lname, where custid and ccode form composite keys. Composite keys are primary keys that refer to more than one attribute and are used to define the uniqueness of the business object. You can update a Customer record for which the value of ccode is NULL. The adapter would generate an update query for the Update operation as:

The adapter treats an empty complex column as null value irrespective of setting it to null or unset.



Related concepts:

Create operation

Retrieve operation

RetrieveAll operation

ApplyChanges operation

Delete operation

Execute operation

Exists operation

Invoke operation

Publish operation


Related reference:

Fault business objects

Feedback


ApplyChanges operation

The ApplyChanges operation provides both delta and after-image support for modifying or deleting a business object. The ApplyChanges operation is available only if you use business graphs.

If you set the verb property of the business graph to the name of an operation, such as create, update, or delete, the adapter performs after-image processing for the ApplyChanges operation. For example, if the verb is set to create, the adapter processes the ApplyChanges operation the same as the Create operation.

If you do not set the verb in the business graph, the adapter uses the ChangeSummary in the business graph to update the business object. In this mode, the ApplyChanges operation differs from the Update operation in the following ways:

The adapter performs the following steps when updating a hierarchical business object from the ChangeSummary. It processes only the changes from the ChangeSummary.

  1. It recursively processes all single-cardinality children of the parent object. If a child is marked required in the business object specification, it must be present in the inbound object. If it is not, the ApplyChanges operation fails, and the adapter returns an error.
  2. It sets all foreign key values in the parent that reference attributes in single-cardinality children to their corresponding child values. This is necessary because single-cardinality children might have been added to the database during the previous steps, resulting in the generation of new sequence values.
  3. It updates the current object being processed using an SQL UPDATE statement or a stored procedure. All simple attributes of the individual business object are updated. The adapter does not use property level changes to determine which attributes need to be added to the UPDATE statement; they are all updated. Because the object being updated should be unique, the adapter checks to ensure that only one row is processed as a result. An error is returned if more than one row is processed.
  4. It sets all foreign key values in all cardinality N children of the current object that reference parent attributes to the corresponding parent values. Typically, these values are already cross-referenced during data mapping; however, this might not be the case for new children in cardinality N containers. This step ensures the foreign key values in all cardinality N children are correct before those children are updated.
  5. It updates all cardinality N containers of the current object.

    When the child objects are processed, each child's operation is taken, and the appropriate operation is performed. The operations allowed on a child in ApplyChanges are Create, Delete, and Update:

    • If a Create operation is found in the child, the child is created in the database if it is an ownership child. Non-ownership children are retrieved to validate their existence in the database.

    • If a Delete operation is found in the child, that child is deleted.

    • If an Update operation is found in the child, the child is updated in the database.



Related concepts:

Create operation

Retrieve operation

RetrieveAll operation

Update operation

Delete operation

Execute operation

Exists operation

Invoke operation

Publish operation


Related reference:

Fault business objects

Feedback


Delete operation

The Delete operation is performed by pruning the incoming business object and then retrieving the complete business object from the database. The Delete operation is then applied recursively on each business object in the hierarchy.

The Delete operation supports physical and logical deletes, depending on the StatusColumnName value in the application-specific information of the business object. If the StatusColumnName value is defined, the adapter performs a logical delete operation. If the StatusColumnName value is not defined, the adapter performs a physical delete operation.

Physical deletes

For physical deletes the adapter takes the following actions:

Logical deletes

For logical deletes the adapter takes the following actions:

NULL data and the Delete operation

The adapter can delete a record from a database table when the column value is null. For example, a Customer business object might have these columns: custid, ccode, fname, and lname, where custid and ccode form composite keys. Composite keys are primary keys that refer to more than one attribute and are used to define the uniqueness of the business object. You can delete a Customer record for which the value of ccode is null. The adapter generates a delete query for the Delete operation as:



Related concepts:

Create operation

Retrieve operation

RetrieveAll operation

Update operation

ApplyChanges operation

Execute operation

Exists operation

Invoke operation

Publish operation


Related reference:

Fault business objects

Feedback


Execute operation

The Execute operation is used to run stored procedures and stored functions. The external service wizard generates the required stored procedure business object corresponding to the stored procedure or stored function definition in the database. The adapter uses the Execute operation to process the stored procedure business object.

The following information provides a simple example of a stored procedure, the business object that is constructed from it, and the steps the adapter uses to process the stored procedure business object with an Execute operation.

A simple example of a stored procedure:

PROCEDURE testSP(IN int x,INOUT VARCHAR(10) msgSTR, OUT int status,
                 OUT struct outrec, OUT array retArr)

The procedure returns two result sets.

For this stored procedure, following is an example of the business object that is constructed:

BOLevel ASI
      SPName=testSP
      ResultSet=true
      MaxNumberOfResultSets=2
      ReturnValue = propName
                    Returned if the stored procedure is a function. function).
                    Will be property name corresponding to the child business                     object if returned value is complex type(array/struct/resultset)
          Defined only if it is a Function

Properties       x Type=IP
      msgStr Type=IO
      status Type=OP
      outrec Type OP - Child BO for outrec, ASI ChildBOType = struct
      retarr Type OP - n cardinality child BO for retArr, ASI ChildBOType = array       childBOName1 - Child BO for 1st result set, ASI ChildBOType = resultset
      childBOName2 - Child BO for 2nd result set, ASI ChildBOType = resultset

To process this stored procedure business object with an Execute operation, the adapter:

  1. Constructs the following stored procedure call: CALL testSP(x, msgStr, status, outrec, retArr).

  2. Sets the input parameters x and msgStr on the callable statement.
  3. Runs the callable statement.
  4. Obtains the return value (if Function) and sets the value in the appropriate attribute if it is a scalar value, or in a child business object if it is a complex value (such as struct, array).
  5. Obtains the first result set and creates the container for ResultSet1.
  6. Obtains the second result set and creates the container for ResultSet2.
  7. Obtains the output parameters msgStr and status, and sets the corresponding attributes on the business object.
  8. Obtains the output parameter outrec and creates the child business object from the data returned in outrec. If outrec is a nested struct type, then the adapter recursively creates and stores data in the hierarchical child business object.
  9. Obtains the output parameter retArr and creates a multiple cardinality child business object from the data returned in retArr. If retArr is a nested array type, then the adapter recursively creates and stores data in the hierarchical child business object.



Related concepts:

Create operation

Retrieve operation

RetrieveAll operation

Update operation

ApplyChanges operation

Delete operation

Exists operation

Invoke operation

Publish operation


Related reference:

Fault business objects

Feedback


Exists operation

The Exists operation determines whether the database contains records that match the attributes set in a business object.

You can use both key and non-key attributes in the selection criteria.

When using the external service wizard to discover table objects in a database, you can select multiple tables and add those tables to the selected objects portion of the Find Objects in the Enterprise System screen. However, you cannot use the external service wizard to link or join the tables that you selected. If the goal of your business application requires the table business object to perform an Exists operation on joined tables, you need to join the tables in the database to create a view of the joined tables.

After creating a view of the joined tables, you can then perform discovery on the view. The Exists operation would be supported on this view.

To process the Exists operation and send the results based on the specified business object attributes, the adapter performs the following actions:

  1. The adapter receives a table business object from the import. This business object can be flat (simple with no child business objects) or hierarchical (complex, containing one, or more child business objects).

    If the business object is hierarchical, it is only for the top-level business object (the individual business object at the top of a hierarchical business object) for which the adapter builds the query.

    The input business object that supports the Exists operation varies depending on the business object type. In addition to being supported by the table business object, the Exists operation is also supported by the views business object and the synonyms and nicknames business object.

  2. The adapter uses the table business object to generate an SQL SELECT statement that it sends to the server.

    The SQL SELECT statement used is as follows:

    select count(*) from TABLENAME where column1=? AND column2=?

    Here is a sample SQL statement for our example:

    select count(*) from CUSTOMER where fname='John' AND lname='Smith'

    In this case, the SQL statement specifies non-primary key attributes fname and lname, with the assigned values of John and Smith.

    The adapter includes the attribute information from the table business object in where clause of the SQL query.

  3. The database server runs the SQL query and sends the results back to the adapter.
  4. The adapter obtains the results of the SQL query from the database server and sets the recordcount and status attributes on the ExistsResults business object.

    For example, if the Exists operation determined there are two records that match the attribute and value settings in the business object, the adapter sets status=true and recordcount=2.

    If a record with the specified attributes is not found, the status output parameter is false and the recordcount output parameter is 0.

    The following screen capture illustrates the structure of the ExistsResult business object returned from an Exists operation.

  5. The adapter returns the ExistsResult business object to the caller.

The following illustration shows how the adapter processes a table business object with an Exists operation.



Related concepts:

Create operation

Retrieve operation

RetrieveAll operation

Update operation

ApplyChanges operation

Delete operation

Execute operation

Invoke operation

Publish operation


Related reference:

Fault business objects

Feedback


Invoke operation

The Invoke operation is used to start XML Gateway web Service. The external service wizard generates the required XML Gateway web Service business object corresponding to the XML Gateway web Service interface in Oracle E-Business Suite.

The following information provides a simple example of a XMLGateway web Service: http://hostname:port/webservices/AppsWSProvider/oracle/apps/fnd/XMLGateway?wsdl

<binding name="XMLGatewaySOAPBinding" type="tns:XMLGatewayPortType">
<Soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http" />
<operation name="ReceiveDocument">
<soap:operation soapAction="http://oraebs05.cn.ibm.com:port/webservices/AppsWSProvider/oracle/apps/fnd/XMLGateway" />
<input>
<soap:header message="tns:ReceiveDocument_Request" part="header" use="literal" />
<soap:body parts="body" use="literal" />
<input>
<output
</operation>
</binding>
<service name="XMLGateway">
<documentation>Generic Web Service for receiving XML Gateway Transactions</documentation>
<port binding="tns:XMLGatewaySOAPBinding" name="XMLGatewayPort">
<soap:address location="http://oraebs05.cn.ibm.com:8000/webservices/AppsWSProvider/oracle/apps/fnd/XMLGateway" />
</port>
</service>
The following three child business objects are generated:

The header contains the XMLGateway header properties, such as Message_Standard, Transaction_Type. The payload contains the integration data business object, such as Purchase Order, Invoice. The response contains the return information from Oracle E-Business Suite.

To process this stored procedure business object with an Invoke operation, the adapter:

  1. Initializes the web Service client with XMLGateway web Service WSDL.

  2. Sets the input parameters: header properties and payload integration data.

  3. Starts the operation:ReceiveDocument in XMLGateway web Service WSDL.
  4. Sends the data to Oracle E-Business Suite and receives the response information.



Related concepts:

Create operation

Retrieve operation

RetrieveAll operation

Update operation

ApplyChanges operation

Delete operation

Execute operation

Exists operation

Publish operation

Feedback


1.2.1.1.10. Publish operation

The Publish operation is used to start XML Gateway JMS interface. The external service wizard generates the required XML Gateway JMS business object corresponding to the XML Gateway JMS interface in Oracle E-Business Suite. The adapter uses the Publish operation to process the XML Gateway JMS business object.

The following information provides a simple example of a XMLGateway JMS Service:

<EBSConnectionType>XML Gateway</EBSConnectionType>XML Gateway>
<EBSHostName>ora220.cn.ibm.com</EBSHostName>
<EBSPortNumber>1521</EBSPortNumber>
<EBSQueueName>wf_jms_in</EBSQueueName>
<EBSSchemaName>applsys</EBSSchemaName>
<EBSSystemID>VIS</EBSSystemID>
<EBSTransport>JMS</EBSTransport>

The following three child business objects are generated:

The header contains the XML Gateway header properties, such as Message_Standard, and Transaction_Type. The payload contains the integration data business object, such as Purchase Order, Invoice. The response contains the return information from Oracle E-Business Suite.

To process this stored procedure business object with Publish operation, the adapter:

  1. Initializes the JMS client with XMLGateway JMS interface information such as hostname, port, queue name.

  2. Sets the input parameters: header properties and payload integration data.
  3. Constructs the integration data into JMS Message with header and body.
  4. Sends the data to Oracle E-Business Suite and receives the response information.



Related concepts:

Create operation

Retrieve operation

RetrieveAll operation

Update operation

ApplyChanges operation

Delete operation

Execute operation

Exists operation

Invoke operation

Feedback


Inbound processing

IBM WebSphere Adapter for Oracle E-Business Suite supports inbound event management with event delivery. Events are processed from an event store that is populated either by the database application or from the result of custom queries that you provide. You control how often the adapter polls for events and how many records are delivered to the export at one time.

The adapter polls for changes using one of these methods:

You can customize standard or custom event processing when use the external service wizard to configure the adapter initially or at a later time by using the administrative console of the server to change the activation specification properties.

The database object that is the subject of the event is not retrieved until after a notification is delivered to the export. As a result, the detection and notification of any retrieval errors that occur is deferred until after notification of the export. This differs from the event processing in version 6.2.x of the adapter, where retrieval errors can be detected before the adapter notifies the export.



Related tasks:

Configure the module for inbound processing


Related reference:

Activation specification properties

Feedback


Standard event processing

In standard event processing, the adapter provides the SQL queries that poll for events and ensure the event is delivered exactly one time.

When records are created, updated, or deleted in the tables in the database, an event program is run immediately. For Oracle database, the database triggers or tools such as Oracle Change Data Capture are run, and, for Oracle E-Business Suite, Oracle Business Event System and the concurrent programs are run. A trigger or other tool writes an event record into the event store, which is a persistent cache where event records are saved until a polling adapter can process them. The event store is implemented as a table in the same database as the user tables, which are the tables that contain the database objects accessed by the adapter.

Define the triggers or set up other tools to report changes to the database tables about which you want to receive events.

The adapter offers assured once delivery, which guarantees that each event is delivered only once to the export. If you enable assured once delivery for the module, a transaction ID (XID) is set for each event in the event store. After an event is obtained for processing, the XID value for that event is updated in the event store. The event is then delivered to its corresponding export, and then deleted from the event store. If the database connection is broken or the application is stopped before the event can be delivered, the event cannot be processed completely. In this case, the XID column indicates the event must be reprocessed and sent to the export again. After the database connection is reestablished or the adapter starts again, the adapter checks for events in the event store that have a value in the XID column. The adapter processes these events first, and then polls the other events during the poll cycles.

The adapter can process all events or filter events by business object type, time stamp, or connector ID. The filter is set by use of the activation specification property EventTypeFilter, FilterFutureEvents, or AdapterInstanceEventFilter. The EventFilterType property has a comma-delimited list of business object types. Only the types specified in the property are processed. If no value is specified for the property, no filter is applied, and all the events are processed. If the activation specification property FilterFutureEvents is set to true, the adapter filters events by timestamp and connector ID. The adapter compares the system time in each poll cycle to the time stamp on each event. If an event is set to occur in the future, it will not be processed until that time. If the AdapterInstanceEventFilter activation specification property is set, only the connector ID specified in the AdapterInstanceEventFilter property is processed.



Related concepts:

Custom event processing

Event store

Feedback


Custom event processing

In custom event processing, you provide the SQL queries or stored procedures that poll for events.

With custom event processing, you control which events are delivered to the export by providing a database query (the custom event query) for the adapter to run in place of the SQL query it uses to poll the event store in standard event processing. The custom event query must perform any necessary filtering. You specify that you want custom event processing by selecting an option in the wizard or by setting the EventQueryType activation specification property in the administrative console.

Custom event processing supports assured once delivery if you create the standard event store for storing XID values. The adapter stores the events returned by the custom event query in the event store, and it updates the events with XID values. The adapter processes the events in the same way as for standard event processing. Do not create a custom query that queries the standard event store, because that table temporarily holds the events when the adapter is configured for assured once delivery. In addition, in this situation the event store must not have an automatic generation of event ID values, because the adapter populates the event ID value it retrieves from the custom query in the event store.

When you are using custom event processing, set the property Ensure once-only event delivery (AssuredOnceDelivery) to True.

Turn custom event processing on by selecting an advanced option in the wizard when you configure your module to use the adapter or by setting the EventQueryType activation specification property.


Custom event query

You specify the custom event query to run by providing a user-defined event query in an advanced option in the wizard or by setting the CustomEventQuery activation specification property. Specify one of the following types of programs:

Any of these programs takes an input parameter containing the poll quantity, an activation specification property the adapter provides at run time. The program can accept other input parameters as well. These programs must return a result set that has the poll quantity number of records and contains the following columns in order: event_id, object_key, object_name, and object_function. The adapter generates the event object from the result set and processes the events.

Standard SQL statements

You can provide an SQL SELECT statement that selects the events to process. The query can have input parameters in addition to the input parameter for poll quantity.

Stored procedure

The custom query can be a stored procedure that accepts the poll quantity as input and returns an output parameter of type result set. Use the following syntax to specify a stored procedure:

Where procedure_name is the name of the stored procedure to run. The first parameter represents the poll quantity and the second parameter represents the result set.

The stored procedure can accept other input parameters as well, which you provide in the call statement itself, for example:

Stored function

The custom query can be a stored function that accepts the poll quantity as input and returns a result set. Use the following syntax to specify a stored function:

Where function_name is the name of the stored function. The first parameter represents the result set, and the second parameter represents the poll quantity.

The stored function can accept other input parameters, which you provide in the call statement itself, for example:


Custom update and delete queries

Custom event processing allows you to provide custom update and delete queries, which are run after each event is processed. You typically use an update query to ensure that a database record does not get picked up for processing during subsequent poll cycles. Use a delete query when database records need to be deleted after each event is processed. Both the update and delete queries are optional.

Update and delete queries are specified by the CustomUpdateQuery and CustomDeleteQuery activation specification properties. You can enter these queries as a standard SQL statement, a stored procedure, or a stored function. The syntax for the custom update or delete query is the same as the syntax for the custom query. Update and delete queries take an input parameter for the event ID. The adapter provides the value of event ID at run time. The queries can also have additional input parameters, which you provide in the query syntax itself, in the same way as described for the custom event query.



Related concepts:

Standard event processing

Event store

Feedback


Event store

The event store is a persistent cache where event records are saved until the polling adapter can process them. The adapter uses the event store to track the inbound requests as they make their way through the system. Each time a database record is created, updated, or deleted, the adapter updates the status of the event in the event store. The status of each event is continually updated by the adapter for recovery purposes until the events are delivered to a configured export on the server.

The adapter polls the event records from the event store at regular intervals. In each poll call, a number of events are processed by the adapter. Events are processed in ascending order of priority and ascending order of the event time stamp. In each poll cycle, the adapter picks up all new events. For each new event, the adapter retrieves the value set in the object key field for the event and then loads the business object corresponding to the value specified in the object name field. After the object is loaded, the adapter sets the primary key values of the business object based on the value specified in the object key field. After setting the keys, adapter performs a retrieval of the object based on the keys. The business object or optional business graph is created from the retrieved information and is published to the export.

If you associate a stored procedure with the Retrieve operation of the business object, you can define the mapping between the input parameters of the stored procedure and the business object attributes (generally, primary keys). If such a mapping is defined, then the adapter sets the input parameters for the stored procedure, starts the stored procedure, and populates the object based on the results obtained from the stored procedure.

For stored procedures and functions, if you defined a mapping between the input parameters of the stored procedure or function and the business object attributes (generally using primary keys) using the RetrieveSP application-specific information, then the adapter sets the input parameters on the stored procedure, starts the stored procedure, and populates the business object based on the results obtained from the stored procedure.

When the object_function column has the value Delete, which indicates the object was deleted, the object is not retrieved from the database. The keys are set on the data object and the business object or optional business graph is created and delivered to the export.

If an event is successfully posted, the entry is deleted from the event store. For failed events, the entries remain in the event store, and the event_status column is set to -1.

The table format and content of the event store are described Table 1.

Definition of the event store database table

Column name Type Description
XID String The unique transaction ID (XID) value for assured once delivery.
event_id Number The unique event ID, which is a primary key for the table. This can have the same value as the object_key.
object_key String A string that contains keys of the record in the event store that is retrieved.

This column cannot be null.

Set the value as one or more key=value pairs, separated by the semicolon character (;).

Alternatively, you can specify only the values for the primary keys separated by the semicolon (;) character. In this case, the values must be specified in the same order as primary keys are defined in the business object.

object_name String The name of the business object or business graph. The business object (or the business object within the business graph) can be a hierarchical business object. Each business object or business graph refers to a table or view.

This column cannot be null.

object_function String The operation corresponding to the event (Delete, Create, Update, and so on).

This column cannot be null.

event_priority Number Identifies the event priority. This value must be a positive integer.

This column cannot be null.

event_time Timestamp Date and time when event was generated. The format is mm/dd/yyyy hh:mm:ss.
event_status Number The event status is initially set to a value for a new event and updated by the adapter as it processes the event. The status can have one of the following values:

  • 0: Identifies a new event.
  • 1: Identifies an event that is delivered to an export.
  • -1: An error occurred while processing the event.

This column cannot be null.

event_comment String Any comment associated with the event.
connector_ID String The unique identifier for the adapter instance that receives a specific event.



Related concepts:

Standard event processing

Custom event processing

Feedback


Business objects

A business object is a structure that consists of data, the action to be performed on the data, and additional instructions, if any, for processing the data. WebSphere Adapter for Oracle E-Business Suite uses business objects to represent tables and views in the database along with the results of database queries, stored procedures, and stored functions. Business objects can also create a hierarchy of objects from the database, and group unrelated tables. Your component communicates with the adapter using business objects.


How the adapter uses business objects

An integrated application uses business objects to access a database. The adapter converts the business objects in outbound requests into JDBC API calls to access the database. For inbound events, the adapter converts the data in the events into business objects, which are returned to the application.

The adapter uses business objects to represent the following types of objects in a database:

Query business objects do not represent database objects. Query business objects represent a user-defined SQL query to run against the database.

Before using the business objects to represent the objects types mentioned earlier, ensure the Java™ keywords are not used to define the names of tables, views, stored procedures, and stored functions parameters.

Adapters use some business objects for output. These business objects include:


How data is represented in business objects

For table or view business objects

Each column in the table or view is represented by a simple attribute of the table or view business object. A simple attribute is an attribute that represents a single value, such as a String, Integer, or Date. Other attributes represent a child business object or an array of child business objects.

Simple attributes within the same business object cannot be stored in different database tables; however, the following situations are possible:

A table business object always has a primary key, even if the corresponding database table does not have a primary key. The adapter uses the column specified in the primary key attribute when it retrieves table business objects. The adapter supports tables that have composite, or multiple, primary keys. If a database table has one or more primary keys, the wizard sets the primary key property for those columns in the table business object. If the database table does not have a primary key, the external service wizard prompts you for primary key information when you configure that business object. Specify a column that contains unique data, such as a sequence or identity column.

If the table business object contains the Date and Timestamp data types, the format of these types can be customized in the Application Info section of the Properties view of the business object. For example, you can specify the date format in dd/MM/yy and timestamp in HH/mm/ss. To customize the format of the Date and Timestamp data types, ensure the data types are mapped to the default string data type in the Configuration Properties window.

Table and view business objects support the Create, Update, Delete, Retrieve, RetrieveAll, Exists, and ApplyChanges outbound operations. When running an Exists operation on a hierarchical table business object, only the top-level business object is queried.

Figure 1 shows a table business object in the business object editor. The business object has an attribute for each of the columns in the database table. Because the table has no child business objects, all the attributes are simple attributes.

Figure 1. A table business object with no child.

Figure 2 shows a table business object that has one child table business object. The business object has simple attributes for each of the columns in the database table, plus a complex attribute pointing to a child business object.

Figure 2. A table business object with one child business object.

For Oracle databases, the adapter supports complex data types such as array, table, structure, or nested structure in table business objects. The type name and the sub attribute details are automatically discovered and displayed for these types. The adapter processes these data types as child business objects of the table business object.

Figure 3. An Oracle table business object having complex data types as columns

For stored procedure and stored function business objects

In a business object for a stored procedure or stored function, all the input and output parameters for the stored procedure or stored function have corresponding attributes in the business object. If any of the input or output parameters is of a complex type, such as an array or structure, then the corresponding business object attribute is a child business object type with the child business object containing the attributes of the array or structure. If the stored procedure returns a result set, a child business object is created that contains the attributes of the returned result set.

The business object for stored procedures and stored functions supports the Execute outbound operation.

If the stored procedure or function business object contains the Date and Timestamp data types, the format of these types can be customized in the Application Info section of the Properties view of the business object. For example, you can specify the input or output parameter of date in dd/MM/yy and timestamp in HH/mm/ss format. To customize the format of the Date and Timestamp data types, ensure the data types are mapped to the default string data type in the Configuration Properties window.

The following Properties view shows business objects generated from a stored procedure that has one input type and two output types. One of the output parameters is of the Struct data type. The external service wizard generates a business object for the Struct type and adds it as a child object to the parent business object. For the attribute of type Struct in the parent business object, the ChildBOType application-specific information is set to Struct to indicate it is of type Struct.

Figure 4. Child business object type with attribute of the structure data type

In the Properties view, the ChildBOTypeName application-specific information is set to the value of the user-defined Struct type in the database.

Figure 5. Child business object type name set to Struct type

For query business objects

A business object for a database query defines the SQL statement that performs the query and the parameters the query requires. The query business object supports the RetrieveAll outbound operation.

As an example, assume a query business object to run the following SELECT statement:

The question mark (?) indicates an input parameter for the query. A query can have multiple parameters, each indicated in the SELECT statement by a question mark. Table 1 shows the attributes of the sample query business object. The query business object has simple attributes for each column to be extracted, a simple attribute for each parameter, and a "placeholder object" for the WHERE clause of the query, which holds the WHERE clause after parameter substitution.

Attributes of a query business object

Business object attribute Description
pkey Corresponds to database column PKEY in the Customer table
fname Corresponds to database column FNAME in the Customer table
city Corresponds to database column CITY in the Address table
parameter1 The parameter. There is one parameter for each ? (question mark) in the SELECT statement. In a SELECT statement with multiple parameters, subsequent parameters are named parameter2, parameter3.
jdbcwhereclause A placeholder object for the WHERE clause

If the query business object contains the Date and Timestamp data types, the format of these types can be customized in the Application Info section of the Properties view of the business object. For example, you can specify the input or output parameter of date in dd/MM/yy and timestamp in HH/mm/ss format. To customize the format of the Date and Timestamp data types, ensure the data types are mapped to the default string data type in the Configuration Properties window.

The following figure shows the business object for the sample query in the business object editor.

Figure 6. The attributes of a query business object

This figure shows the application-specific information for the query business object example. The SelectStatement application-specific information contains the SELECT statement.

Figure 7. The SELECT statement is saved in the business object application-specific information

For Oracle databases, the adapter supports complex data types such as array, table, structure, or nested structure in the query result of the business object. The adapter does not support these complex types as parameters in query business objects.


Business graphs

You can optionally choose, during adapter configuration, to generate a business graph. In version 7.5.0.3, business graphs are required only in these situations:

If business graphs exist, they are processed, but the verb is ignored for all operations except ApplyChanges.


How business objects are created

You create business objects by using the external service wizard, launched from IBM Integration Designer. The wizard connects to the database, discovers database objects, and displays them to you. Select the database objects for which you want to create business objects. For example, specify which schemas you want to examine. In those schemas, select tables, views, stored procedures and functions, and synonyms and nicknames. In addition, you can additional business objects. For example, you can create a business object to represent the results of user-defined SELECT, INSERT, UPDATE, or DELETE statements that are run against the database. The wizard helps you build a hierarchy of business objects, using parent-child relationships.

After you specify the business objects that you want and define the hierarchy of those objects, the wizard generates business objects to represent the objects that you have selected. It also generates other artifacts needed by the adapter.

Figure 8. How business objects are created

In some instances, the wizard cannot completely configure a parent-child relationship. For these relationships, use the business objects editor, started from IBM Integration Designer, to modify or complete the definition of a business object hierarchy that was created by the wizard. See the instructions for using the business object editor to modify business objects in the IBM Integration Designer information center at the following link: http://publib.boulder.ibm.com/infocenter/dmndhelp/v7r0mx/index.jsp.



Related reference:

Business object information

Feedback


Business object hierarchies

Define the relationships between database tables using parent-child relationships and data ownership in hierarchical business objects.

Business objects can either be flat or hierarchical. In a flat business object, all attributes are simple and represent one row in the database table. Hierarchies can contain related or unrelated business objects. Related business objects have parent-child relationships, with or without ownership.

The term hierarchical business object refers to a complete business object, including all the child business objects that it contains at any level. The term individual business object refers to one business object, independent of child business objects that it might contain or parent business objects that contain it. The individual business object can represent a view that spans multiple database tables. The term top-level business object refers to the individual business object at the top of the hierarchy, which does not itself have a parent business object.

A hierarchical business object has attributes that represent a child business object, an array of child business objects, or a combination of the two. In turn, each child business object can contain a child business object or an array of child business objects.

A single-cardinality relationship occurs when an attribute in a parent business object represents one child business object. In this case, the attribute is of the same type as the child business object. The adapter supports single-cardinality relationships, and single-cardinality relationships and data without ownership.

A multiple-cardinality relationship occurs when an attribute in the parent business object represents an array of child business objects. In this case, the attribute is of the same type as the child business objects.

Use the following types of relationships between business objects to define a hierarchy that represents the database tables:

In each type of cardinality, the relationship between the parent and child business objects is described by the application-specific information of the key attributes in the business object storing the relationship.



Related tasks:

Selecting and configuring tables, views, and synonyms or nicknames for outbound processing

Configure the module for inbound processing

Selecting and configuring tables, views, and synonyms or nicknames for inbound processing


Related reference:

Business object attributes

Feedback


Single-cardinality relationships in business objects

In a single-cardinality relationship, an attribute in a parent business object represents one child business object. In this case, the attribute is of the same type as the child business object. The adapter supports single-cardinality relationships, and single-cardinality relationships and data without ownership.


Single-cardinality relationships

Typically, a business object that contains a single-cardinality child business object has at least two attributes that represent the relationship. The type of one attribute is the same as the child's type. The other attribute is a simple attribute that contains the child's primary key as a foreign key in the parent. The parent has as many foreign key attributes as the child has primary key attributes.

Figure 1 illustrates a typical single-cardinality relationship. In the example, FKey in the ParentBOName object is the simple attribute that contains the child's primary key, and Child(1), also in the ParentBOName object, is the attribute that represents the child business object.

Figure 1. Typical single-cardinality relationship

Because the foreign keys that establish the relationship are stored in the parent, each parent can contain only one child business object of a defined type.

A parent business object can have a single-cardinality child with ownership and a single-cardinality child without ownership. Lookup tables are used for relationships without ownership. Ownership is indicated by the value of the Ownership application-specific information.


Single-cardinality relationships and data without ownership

Typically, each parent business object owns the data within the child business object that it contains. For example, if each Customer business object contains one Address business object, when a new customer is created, a new row is inserted into both the Customer and Address tables. The new address is unique to the new customer. Likewise, when deleting a customer from the Customer table, the customer's address is also deleted from the Address table.

However, situations can occur in which multiple hierarchical business objects contain the same data, which none of them owns. For example, assume the Address database table contains a reference to the StateProvince lookup table. Because the lookup table is rarely updated and is maintained independently of the address data, creating or modifying address data does not affect the state and province data in the lookup table. However, to be able to retrieve the StateProvince business object along with the Address business object, StateProvince must be a single-cardinality child of Address and the relationship must be defined without data ownership.

If the database design includes lookup tables, your business object design differs slightly from the database design. This is because the adapter retrieves data only for a table business object and its child table business objects. To use a lookup table, you need to create a single-cardinality parent-child relationship between the tables, without ownership. Although the StateProvince lookup table is not a child of the Address table in the database, the corresponding StateProvince business object is a single-cardinality child of the Address table business object because each address contains a single state or province. However, the Address business object does not "own" the StateProvince business object. Changes to an address do not result in a change to the list of states and provinces.

When the adapter receives a hierarchical business object with a Create, Delete, or Update request, the adapter does not create, delete, or update single-cardinality child business objects contained without ownership. The adapter performs only Retrieve operations on these business objects. If the adapter fails to retrieve such a single-cardinality business object, it returns an error and stops processing; it does not add or change values in the lookup table's business object.

Denormalized data and data without ownership

In addition to facilitating the use of static lookup tables, containment without ownership provides another capability: synchronizing normalized and denormalized data.

Synchronization of normalized to denormalized data: When the relationship is without ownership, you can create or change data when you synchronize from a normalized application to a denormalized one. For example, assume that a normalized source application stores data in two tables, A and B. Assume further the denormalized destination application stores all the data in one table such that each entity A redundantly stores B data.

In this example, to synchronize a change in table B data from the source application to the destination application, you must trigger a table A event whenever table B data changes. In addition, because table B data is stored redundantly in table A, you must send a business object for each row in table A that contains the changed data from table B.

When making updates to denormalized tables, ensure that each record has a unique key so that multiple rows are not modified as a result of one update. If such a key does not exist, the adapter provides an error stating that multiple records is updated.

Synchronization of denormalized to normalized data: When synchronizing data from a denormalized source application to a normalized destination application, the adapter does not create, delete, or update data contained without ownership in the normalized application.

When synchronizing data to a normalized application, the adapter ignores all single-cardinality children contained without ownership. To create, remove, or modify such child data, you must process the data manually.


Feedback


Multiple-cardinality relationships

In a multiple-cardinality relationship, an attribute in the parent business object represents an array of child business objects. The attribute is of the same type as the child business object. The foreign key that describes the relationship is stored in the child, except when an application stores a single-child entity. Then the parent-child relationship is stored in the parent.

Typically, a business object that contains an array of child business objects has only one attribute that represents the relationship, and this attribute is normally the primary key. The type of the attribute is an array of the same type as the child business objects. For a parent to contain more than one child, the foreign keys that establish the relationship are stored in the child.

Therefore, each child has at least one simple attribute that contains the parent's primary key as a foreign key. The child has as many foreign key attributes as the parent has primary key attributes.

Because the foreign keys that establish the relationship are stored in the child, each parent can have zero or more children.

Figure 1 illustrates a multiple-cardinality relationship. In the example, ParentId in the three ChildBOName boxes is the simple attribute that contains the parent's primary key, and Child1 in the ParentBOName box is that attribute that represents the array of child business objects.

Figure 1. Multiple cardinality business object relationship with N>1

A multiple-cardinality relationship can be an N=1 relationship. Some applications store one child entity so the parent-child relationship is stored in the child rather than in the parent. In other words, the child contains a foreign key whose value is identical to the value stored in the parent's primary key.

Applications use this type of relationship when child data does not exist independently of its parent and can be accessed only through its parent. Such child data requires the parent and its primary key value exist before the child and its foreign key value can be created.

Figure 2 shows this type of relationship.

Figure 2. Multiple cardinality relationship with N=1


Feedback


Database tables with multiple parent tables

If a child table in the database has more than one parent table, you must manually configure the additional parent business objects using the assembly editor. The external service wizard configures only one parent.


Feedback


The business object schema

The business object schema is built out of database objects that you select when you run the external service wizard. Each database object translates into a top-level business object.

The schema defines business objects names and application-specific information. The business objects and their attributes and application-specific information are represented in the schema as follows:

The template for the application-specific properties for the business object and for the attributes is defined in the metadata schema for the adapter. The name of the schema file is OracleEBSASI.xsd. The schema file generated for the adapter has a reference to this template in its annotations.


Feedback


Tables, views, and synonyms overview

The Oracle database provides the common database objects such as tables, views, synonyms.

Table is a common database schema object in a database. The table objects are used to store data in the database. Oracle provides a number of table types for entering data into the database such as object, normal, nested, clustered, index-organized. Data can be entered into the database table either directly or through the Oracle open interface tables. The Oracle open interface tables interface between two systems. These tables import data from one system, validates data, identifies errors if any, and transfers the valid data to the Oracle base tables appropriately.

View is a database object that is considered as a virtual table or a stored query. Views do not store the data physically in them; instead they derive the data from the base table on which they are created. All the operations that are performed on the tables can be performed on views too.

Synonym is an alias or an alternative name given for the database objects such as the tables, views, and other database objects.


Feedback


Stored procedure overview

A stored procedure can be a business object that your module runs with the Execute operation. It can run in place of the standard SQL for an operation on any business object, or it can perform additional actions before or after performing an operation.

A stored procedure is a group of SQL statements that form a logical unit and perform a particular task. A stored procedure encapsulates a set of operations or queries for the adapter to run on an object in a database server. The adapter uses stored procedures in the following ways:


Feedback


Stored procedure business object overview

You can create a stored procedure business object corresponding to a stored procedure or stored function in the database. You can then use the Execute operation to run the stored procedure against the data in the database.

The external service wizard helps you to build stored procedure business objects that run a stored procedure or stored function. The wizard examines the stored procedure or stored function in the database to create the business object. A stored procedure business object has an attribute for each parameter.

For validating the stored procedure attributes, a sample value parameter is provided with each attribute. The sample value parameter is provided for both simple and complex data type attributes. The wizard uses the sample values that you provide to validate the stored procedure before saving it. The adapter uses the result the stored procedure returns to validate the parameters, to obtain the maximum number of result sets returned, and to use the metadata of these result sets to generate child business objects. The wizard generates the hierarchy for stored procedure business objects automatically if you validate the stored procedure business object.

For both simple and complex data type attributes, the adapter automatically discovers and displays the data type and type name for each attribute of the stored procedure. If the stored procedure has input/output parameters or returns value parameters that are of complex data types such as the Struct or Array, the data type and the corresponding user-defined type name are saved in the SPComplexParameterTypeName property.

If the stored procedure contains the Oracle PL/SQL data type such as Record, the adapter creates a wrapper package with a wrapper stored procedure which converts the Record data type to Object data type so the Oracle E-Business Suite adapter can support the Oracle PL/SQL Record data type. The names of the wrapper packages and stored procedures created for this purpose comply with the Oracle database object naming conventions along with the appropriate suffixes to differentiate them from the Oracle database object names. The names of the wrapper package and wrapper stored procedure consists of both the original package and stored procedure names along with the appropriate suffixes such as “_WPKG” and “_W” ( PKGA_PROC7_REC_TAB_WPKG.PKGA_PROC7_REC_TAB_W, where “PKGA” is the original package name, “PROC7_REC_TAB” is the original stored procedure name, “_WPKG” is the suffix for the package, and “_W” is the suffix for stored procedure). For each selected overloaded stored procedure and function which has PL/SQL Record type parameters, the adapter creates wrapper stored procedure in specific wrapper package with two different number tag ( "XXXX_WPKG01 and XXXX_WPKG02").

In the generated Wrapper for SP/SF with Record type parameter, if you select the boolean type parameter as TRUE or False during runtime, the adapter processes this data type automatically.

WebSphere Adapter for Oracle E-Business Suite distinguishes the original SP/SF from the overloaded ones by a number tag corresponding to an overload sequence in the Oracle database. These corresponding parameters for the selected SP/SF is added based on the overload sequence.

If the stored procedure returns a result set, you need to set the number of result sets returned from this stored procedure in the MaxNumberOfResultSets property. This value represents the maximum number of result sets that are handled by the adapter run time.

During discovery and at run time, the WebSphere Adapter for Oracle E-Business Suite expects the returned result set from the stored procedure execution to contain columns with names. Some stored procedures return result set with unnamed columns. For example, a stored procedure with the SQL statements like the examples that follow return result set with unnamed columns:

SELECT COUNT(*) FROM EMPLOYEE; SELECT 111,222,333 FROM CUSTOMER;

Oracle processes such SQL SELECT statements by assigning "dummy" names to the table columns in the returned result set- like count(*) or d1, d2, d3 for the respective select statement examples shown above.

If the returned result set contains table columns with no names (because the database did not assign dummy names), the adapter creates dummy names for such columns.

Dummy column names, generated by either the database or by the adapter, are assigned to the attributes of the stored procedure business object.

The behavior (by the adapter or by the database) of assigning dummy names to unnamed table columns ensures the stored procedure runs successfully during discovery and at run time.

For stored procedure business objects, the wizard supports nested Struct and Array objects, and can support any number of layers of nested hierarchy. The wizard can generate corresponding child business objects for all these nested Struct and Array objects.

Complex data type properties for stored procedure business objects

Property name Type Description
SPComplexParameterType String Value can be one of:

Array ResultSet Struct

SPComplexParameterTypeName String The name of the user-defined type. This property is required when the value of SPComplexParameterType is Struct or Array.
MaxNumberOfResultSets Integer The maximum number of returned result sets to be handled by the Adapter for Oracle E-Business Suite run time.


Feedback


Stored procedures used in place of or in addition to operations

You can specify the adapter use a stored procedure in the database in place of, before, or after the SQL statements the adapter uses to perform an operation. Each business object can have a different set of stored procedures used with each operation.

The adapter can use simple SQL statements for Create, Update, Delete, Retrieve, or RetrieveAll operations. The column names used in the SQL statements are derived from an attribute application-specific information. The WHERE clause is constructed using key values specified in the business object. Each query spans one table only, unless posted to a view. However, you can replace or enhance the SQL statement provided by the adapter using stored procedures and stored functions.

WebSphere Adapter for Oracle E-Business Suite distinguishes the original SP/SF from the overloaded ones by a number tag corresponding to an overload sequence in the Oracle database. These corresponding parameters for the selected SP/SF is added based on the overload sequence.

The adapter can call a stored procedure or stored function in the following circumstances:

In a hierarchical business object, if you want the stored procedure to be performed for each business object in the hierarchy, you must separately associate a stored procedure with the top-level business object and each child business object or an array of business objects. If you associate a stored procedure with the top-level business object but do not associate it with each child business object, then the top-level business object is processed with the stored procedure, but the child business objects are processed using the standard SQL query.

Table 1 lists the application-specific information elements for a stored procedure and describes their purpose and use. A complete description of each element is provided in the sections that follow the table. A screen showing the stored procedure definition for a business object is shown in View of business object with stored procedure definition.

Application-specific information for stored procedures in table and view business objects

Descriptive name Element name Purpose
Stored procedure type StoredProcedureType The stored procedure type defines the type of stored procedure to be used and determines when the stored procedure is called. For example, before processing a business object.
Stored procedure name StoredProcedureName The name of the stored procedure that is associated with the appropriate StoredProcedureType.
Result set ResultSet This value specifies whether the stored procedure returns a result set. If the result set is returned, a multiple-cardinality child for the current business object is created using the values returned in the result set rows.
Parameters Parameters Each Parameters element describes one parameter for a stored procedure or stored function.
Return value ReturnValue A value that indicates it is a function call, not a procedure call, because the value is returned by the stored procedure.


Stored procedure type

The stored procedure type defines the type of stored procedure to be used and determines when the stored procedure is called. For example, before processing a business object.

Stored procedure type element characteristics

Required Yes
Default None
Possible values Can be one of:

  • BeforeOperationSP

  • AfterOperationSP
  • OperationSP

Operation specifies one of the operation names: Create, Update, Delete, Retrieve, or RetrieveAll.

Bidirectional transformation supported No
Property type String
Usage notes Stored procedure types associated with RetrieveAll apply to top-level business objects only.

You can remove any selected application-specific information from the StoredProcedureType property. All the corresponding operation application-specific information property groups are also removed.

Examples

  • CreateSP: Performs the create operation

  • UpdateSP: Performs the update operation
  • BeforeCreateSP: Runs before creating a business object

  • AfterCreateSP: Runs after creating a business object

  • AfterDeleteSP: Runs after deleting a business object


Stored procedure name

The name of the stored procedure that is associated with the appropriate StoredProcedureType.

Stored procedure name element characteristics

Required Yes
Default None
Bidirectional transformation supported Yes
Property type String


Result set

This value determines whether the stored procedure returns a result or not. If the result set is returned, a multiple-cardinality child for the current business object is created using the values returned in the result set rows.

Result set element characteristics

Required Yes
Default None
Possible values

True False

Bidirectional transformation supported No
Property type Boolean
Usage notes If your stored procedure returns a result set, use the business object editor after finishing the external service wizard to verify that this attribute is set to true. The Oracle JDBC driver does not always return this value correctly.


Parameters

There is one Parameters element for each parameter for a stored procedure or stored function. Each Parameters element defines the name and type of one parameter.

Parameters element characteristics

Required Yes
Default None
Contents Each Parameters element specifies the following information:

  • PropertyName: Specifies the name of the business object attribute to pass as the parameter.
  • Type: Specifies the type of the parameter, one of the following values:

    • IP for input only
    • OP for output only
    • IO for input and output
    • RS for result set

Bidirectional transformation supported No
Property type String
Usage notes

A result set can be returned only as an output parameter. In that case, one of the parameters must have the type RS, to indicate a result set.


Return value

A value that indicates it is a function call, not a procedure call, because a value is returned.

Return value element characteristics

Required No
Default None
Possible values Can be RS or the name of a business object attribute or child business object.
Bidirectional transformation supported No
Property type String
Usage notes If the returned value is RS, the returned value is a result set and is used to create the multiple-cardinality container corresponding to this business object. If the returned value is the name of an attribute, the value is assigned to that particular attribute in the business object. If the attribute is another child business object, the adapter returns an error.

When you associate a stored procedure with a business object that is generated from a table or view, and if the stored procedure is a function, a value is returned from this stored procedure. One ReturnValue application-specific information value is added to the operation application-specific information. The existence of this application-specific information implies that it is a function call and not a procedure call, because a value is being retuned by the function.

If the value of this application-specific information is a business object attribute name, the returned value is assigned to that particular attribute in the business object.

If the value of this application-specific information is another child business object, the adapter run time returns an error.

In summary, if the returned value is of a simple data type, the wizard enables you to bind one business object attribute to it, and the value of this application-specific information is set to the name of that business object attribute. But if the returned value is a result set, the wizard sets the value of this application-specific information to RS.

A result set can be returned as an output parameter or as a returned value if it is a stored function. The type of the output parameter is set to RS to indicate that this parameter is used to return a result set.


View of business object with stored procedure definition

The following Properties view screen shows the customer business object that has the associated stored procedure information for RetrieveSP and AfterRetrieveSP for the Retrieve operation. The adapter runs the RTASSER.RETR_CUSTNAME stored procedure in place of the standard SQL to retrieve a table business object. After the business object is retrieved, the adapter runs the RTASSER.RETR_CUSTINFO stored procedure.


Feedback


Stored functions overview

The Oracle database supports stored functions in addition to stored procedures. Stored functions are like stored procedures except they always return a value. The adapter supports them in a similar manner.

The adapter supports stored functions that a user creates with the CREATE FUNCTION statement. Although this type of function is sometimes called a user-defined function (UDF), that term more typically refers to a Java™ stored function or procedure, which the adapter does not support.

A function call has the following syntax:

? = call FunctionName parameter_list

Contrast this to a stored procedure call, which has the following syntax:

call SPName parameter_list

You specify the attribute that contains the returned value by using the ReturnValue business object application-specific information.


Feedback


Query business object overview

Query business objects run a user-defined SELECT statement against the database, and return the matching records in business objects.

The external service wizard helps you to build query business objects that run user-defined SELECT statements against the database. Set the SELECT statement, using ? (the question mark) in place of any parameter that can be substituted in the SELECT statement. The wizard then provides an area where you can specify the data type of each parameter and provide a sample value. The sample value must match data in the database because wizard uses the SELECT statement results to create the query business object.

You must validate the configuration of the query in the wizard before saving it. When you validate, the wizard runs the SELECT statement using the sample values. After obtaining the result set, the wizard analyzes the metadata to obtain the column name and column type of all columns. For each column of the returned result set, the wizard generates one corresponding attribute in the query business object.

In the query business object, the jdbcwhereclause takes precedence over the values specified for the parameter <n>, where 'n' is the parameter index. This means that, if the query business object contains the parameter <n> and the value is specified for the jdbcwhereclause, then the dynamic query is formed with the WHERE clause using the jdbcwhereclause value. This ignores the values in the parameter <n>. To use the default WHERE clause then you can specify the WHERE clause parameters by specifying values to parameter <n> and un-setting or setting jdbcwhereclause to null.

For example, assume that you specified the following SELECT statement:

The WHERE clause has two parameters, which are indicated by question marks (?). The first parameter has the data type string, to match the data type of the fname column. The second parameter has the data type int, matching the age column. If the database has a customer record where the fname column contains the string Mike and the age column contains the integer 27, you can specify those values as sample values when configuring the query business object. The wizard configures the business object to correspond to the returned result set.

You can also query business objects to retrieve the interface status of the Oracle open interface tables. The interface status column in the interface table contains the error codes. These codes indicate if the data processed from the Oracle open interface table to the Oracle base table is successful or not. The error code can be used to troubleshoot the issue in case of failure during the data transfer.



Related tasks:

Discovering database objects

Selecting and configuring query business objects

Feedback


1.2.10. Business faults

The adapter supports business faults, which are exceptions that are anticipated and declared in the outbound service description, or import. Business faults occur at predictable points in a business process, and are caused by a business rule violation or a constraint violation.

Although IBM Business Process Manager or WebSphere Enterprise Service Bus supports other types of faults, the adapter generates only business faults, which are simply called as faults in this documentation. Not all exceptions become faults. Faults are generated for errors that are actionable, that is, errors that can have a recovery action that does not require the termination of the application. For example, the adapter generates a fault when it receives a business object for outbound processing that does not contain the required data or when the adapter encounters certain errors during outbound processing.


Fault business objects

The external service wizard creates a business object for each fault the adapter can generate. In addition, the wizard creates a WBIFault superset business object, which has information common to all faults, such as the message, errorCode, and primaryKeySet attributes as shown in Figure 1.

Figure 1. The structure of the WBIFault business object

Some faults contain the matchCount attribute, to provide additional information about the error. For others, WBIFault contains all the information needed to handle the fault.



Related reference:

Fault business objects

Feedback


1.2.11. XML gateway interface overview

XML Gateway is an interface type in Oracle E-Business Suite Integration Repository. It allows outbound integration with Oracle E-Business Suite; helps in transferring data to the application. The interface exposes the XML documents in the specified format that is widely used by the Oracle applications business objects and interfaces. It interacts with the Oracle interface tables and views, and it maps the underlying tables to XML format. The interface services contain a common standards-based approach for XML integration between Oracle E-Business Suite and other third-party applications ( Enterprise Application Integration and Web Service Integration).

IBM WebSphere Adapter for Oracle E-Business Suite supports the XML gateway interface, which integrates Oracle E-Business Suite with the other EIS by web service and JMS. When XML Gateway interface is selected, the adapter converts the payload from the Document Type Definitions (DTD) format you specify to the XSD format, and generates the request and response business objects.

The external service wizard helps you to create an XML-based integrated service document that can be used as a payload content to start the web service or JMS in run time. After sending the business data to Oracle E-Business Suite by starting the runtime method, you can use Oracle E-Business Suite's import request to import such business data. There are a few supporting terms used in this feature, which are described as follows:

Oracle XML Gateway integration and Integration Repository metadata discovery is applicable for BPM or WebSphere Enterprise Service Bus only.

Currently, XML Gateway integration does not support iterative development.


Feedback


1.2.12. Advanced Queue integration overview

Advanced Queue is an interface type in Oracle E-Business Suite. It allows outbound integration with Oracle E-Business Suite and helps in transferring data to the application. It also interacts with the Oracle advanced queue. The interface services contain a common standard-based approach for integration between Oracle E-Business Suite and other third-party applications (Example: Enterprise Application Integration).

IBM WebSphere Adapter for Oracle E-Business Suite supports the advanced queue feature, which integrates Oracle E-Business Suite with other EIS. When the advanced queue interface is selected, the adapter generates the advanced queue header and payload business objects. Using the external service wizard you can create the advanced queue header and payload business object to start outbound or inbound at runtime.

Oracle advanced queue integration is applicable for BPM or WebSphere Enterprise Service Bus only.

WebSphere Adapter for Oracle E-Business Suite creates a dynamic SQL script, which uses some Oracle AQ PL/SQL API to enqueue or dequeue. After sending the business data to Oracle E-Business Suite by starting the runtime method, you can use Oracle E-Business Suite's import request to import such business data. Messages can be queried using standard SQL. This means SQL can be used to access the message properties, the message history, and the payload.

There are few supporting terms used in this feature, which are described as follows:



Related tasks:

Configure the module for inbound processing

Configure the module for outbound processing

Feedback


1.2.12.1. Enqueue operation

The Enqueue operation is used to run a dynamic PL/SQL script for enqueuing. The external service wizard generates the required advanced queue business object corresponding to the advanced queue definition in the database. The adapter uses the Enqueue operation to process the advanced queue business object.

The following information provides a simple example of an advanced queue:

Schema:APPLSYS
Queue:WF_JMS_IN

To process this stored procedure business object with an Enqueue operation, the adapter:

  1. Constructs a dynamic call statement based on Oracle AQ PL/SQL API.

  2. Sets the input parameters: queue header properties and queue payload integration data.
  3. Runs the script by JDBC connection to enqueue the data into specific queue.
  4. Receives the message id in queue.



Related tasks:

Configure the module for inbound processing

Configure the module for outbound processing

Feedback


1.2.12.2. Dequeue operation

The Dequeue operation dequeues messages from the advanced queue using PL/SQL or JMS. The dequeued message constituents are payload, message properties, and message ID.

When the dequeue mechanism is PL/SQL, the adapter can retrieve a batch of messages at once instead of one message at every poll cycle, which is the case with JMS dequeue mechanism.

  1. If the dequeue mechanism is JMS, the PollQuantity property is ignored.

  2. If the dequeue mechanism is PL/SQL, the PollQuantity can be up to 500 messages, beyond that you get an exception.

To process the Dequeue operation, the adapter performs the following actions:

  1. Polls the Oracle Advanced Queue and dequeues the messages or events matching the dequeue condition and consumer name from the advanced queue.
  2. Stages the retrieved messages or events into the configured staging table.
  3. Processes each message or event from the staging table, and delivers it to the endpoint.

  4. Updates records in the staging table based on success of message or event delivery.
  5. Deletes the successfully processed events from the staging table.

The table format and content of the staging table is described in the table below:

Definition of the staging table

Column name Type Description
XID VARCHAR Unique transaction ID (XID) value for assured once delivery.
STATUS INTEGER Event status is initially set to a value for a new event and updated by the adapter as it processes the event. The status can have one of the following values:

  • 0: Identifies a new event.
  • 1: Identifies an event that is delivered successfully to endpoint.
  • -1: An error occurred while processing the event.

MSGPROPS CLOB Message properties such as correlation, priority, message state.
PAYLOAD CLOB Message payload.
MSGID VARCHAR Message identifier of the message to be dequeued.
TEXT_LOB CLOB Contains the payload if the size is greater than 4000.



Related tasks:

Configure the module for inbound processing

Configure the module for outbound processing

Feedback


1.2.13. Support for metadata discovery for the supported interfaces

WebSphere Adapter for Oracle E-Business Suite provides a complete catalog of Oracle E-Business Suite business service interfaces, which can be started to get the structure and metadata of different business service interfaces.

Oracle E-Business Suite exposes Integration Repository (IREP) as web Service with a specific WSDL. Start Integration Repository (IREP) web Service to receive the XML Gateway interface metadata. To get the structure and metadata of different business service interfaces:

Oracle XML Gateway integration and Integration Repository metadata discovery is applicable for BPM or WebSphere Enterprise Service Bus only.

The Discovered objects pane lists the different business service interfaces supported by the adapter.


Feedback


1.2.14. The external service wizard

Use the external service wizard in IBM Integration Designer to discover objects in the Oracle database of Oracle E-Business Suite, to generate query business objects, and to generate business objects from selected database objects. The wizard also generates the module and the service artifacts that enable the adapter to run as a Service Component Architecture (SCA) component.


Feedback


1.2.15. Log and Trace Analyzer

The adapter creates log and trace files that can be viewed with the Log and Trace Analyzer.

The Log and Trace Analyzer can filter log and trace files to isolate the messages and trace information for the adapter. It can also highlight the adapter's messages and trace information in the log viewer.

The adapter's component ID for filtering and highlighting is a string composed of the characters OEBSRA plus the value of the adapter ID property. For example, if the adapter ID property is set to 001, the component ID is OEBSRA001.

If you run multiple instances of the same adapter, ensure the first seven characters of the adapter ID property are unique for each instance so that you can correlate the log and trace information to a particular adapter instance. By making the first seven characters of an adapter ID property unique, the component ID for multiple instances of that adapter is also unique, allowing you to correlate the log and trace information to a particular instance of an adapter. For example, when you set the adapter ID property of two instances of WebSphere Adapter for Oracle E-Business Suite to 001 and 002. The component IDs for those instances, OEBSRA001 and OEBSRA002, are short enough to remain unique, enabling you to distinguish them as separate adapter instances. However, instances with longer adapter ID properties cannot be distinguished from each other. If you set the adapter ID properties of two instances to Instance01 and Instance02, you will not be able to examine the log and trace information for each adapter instance because the component ID for both instances is truncated to OEBSRAInstanc.

For outbound processing, the adapter ID property is located in both the resource adapter and managed connection factory property groups. If you update the adapter ID property after using the external service wizard to configure the adapter for outbound processing, be sure to set the resource adapter and managed connection factory properties consistently. It prevents inconsistent marking of the log and trace entries. For inbound processing, the adapter ID property is located only in the resource adapter properties, so this consideration does not apply.

See the Adapter ID (AdapterID) property.


Feedback


Plan for adapter implementation

Before using WebSphere Adapter for Oracle E-Business Suite, make sure that you understand the experience you need and the server environment in which it runs. Learn the considerations for deploying the adapter in your server environment, and find out how to improve the performance and availability of the adapter by using a clustered server environment.



Next topic: Configure the module for deployment

Feedback


Before you begin

Before you begin to configure and deploy the module, you must possess a thorough understanding of the business integration concepts, Java™ Database Connectivity (JDBC), the Oracle database knowledge, the Oracle E-Business Suite products in the environment, and the features and capabilities of IBM Integration Designer and IBM Business Process Manager or WebSphere Enterprise Service Bus.

To configure and deploy WebSphere Adapter for Oracle E-Business Suite you must understand and have experience with the following concepts, tools, and tasks:


Feedback


Security

The adapter uses the J2C authentication data entry, or the authentication alias feature of Java™ EE security to provide secure user name and password authentication. For more information about security features, see the documentation for BPM or WebSphere Enterprise Service Bus.


Feedback


Support for protecting sensitive user data in log and trace files

You can configure the adapter to prevent sensitive or confidential data, in the log and trace files, from being viewed by users without authorization.

Log and trace files for the adapter can contain data from your Oracle database, which might contain sensitive or confidential information. Sometimes these files might be seen by individuals without authorization to view sensitive data. For example, a support specialist must use the log and trace files to troubleshoot a problem.

To protect the data in such situations, the adapter lets you specify whether you want to prevent confidential user data from displaying in the adapter log and trace files. You can select this option in the external service wizard or change the HideConfidentialTrace property. When this property is enabled, the adapter replaces the sensitive data with XXX's.

See Managed connection factory properties for information about this optional property.

The following types of information are considered potentially sensitive data and are disguised:

The following types of information are not considered user data and are not hidden:


Feedback


User authentication

The adapter supports several methods for supplying the user name and password needed to connect to the Oracle database. By understanding the features and limitations of each method, you can pick a method that provides the appropriate level of security and convenience for your application.

To integrate an adapter into your application, a user name and password are needed at the following times:


Authentication in the wizard

The external service wizard prompts for the connection information for the discovery process, and then reuses it as the default values of the adapter properties that specify the connection information used at run time. You can use a different user name and password while running the wizard than you use when the application is deployed to the server. You can even connect to a different Oracle database,although the schema name must be the same in both databases. For example, while developing and integrating an application that uses WebSphere Adapter for Oracle E-Business Suite, you might not use the production database; using a test database with the same data format but fewer, simulated records allows you to develop and integrate the application without impacting the performance of a production database, and without encountering restrictions caused by the privacy requirements for customer data.

The wizard uses the user name and password specified for the discovery process only during the discovery process; they are not accessible after the wizard is completed.


Authentication at run time

At run time, the adapter needs to provide the user name and password to connect to the Oracle database. To connect without user intervention, the adapter must access a saved copy of the user information. In a server environment, there are several methods for saving user information. You can configure the adapter to get your user information, through any of the following methods:

Saving the user name and password in adapter properties is a direct way to provide this information at run time. You provide this user name and password when use the external service wizard to configure your module. Although directly specifying the user name and password seems the most straightforward method, it has important limitations. Adapter properties are not encrypted; the password is stored as clear text in fields that are accessible to others on the server. Also, when the password changes, update the password in all instances of the adapter that access that Oracle database. This includes the adapters embedded in application EAR files and adapters that are separately installed on the server.

Use a data source allows you to use a connection already established for another application. For example, if multiple applications access the same database with the same user name and password, the applications can be deployed using the same data source. The user name and password can be known only to the first person who deploys an application to that data source or who defines a data source separately.

Use a J2C authentication data entry, or authentication alias, created with the Java™ Authentication and Authorization Service (JAAS) feature of Java EE security is a robust, secure way to deploy applications. An administrator creates the authentication alias used by one or more applications that need to access a system. The user name and password must be known only to that administrator, who can change the password in a single place, when a change is required.



Related tasks:

Create an authentication alias

Feedback


Deployment options

There are two ways to deploy the adapter. You can either embed it as part of the deployed application, or you can deploy it as a stand-alone RAR file. The requirements of the environment affect the type of deployment option you choose.

The following are the deployment options:

An embedded adapter is bundled within an enterprise archive (EAR) file and is available only to the application with which it is packaged and deployed.

A stand-alone adapter is represented by a stand-alone resource adapter archive (RAR) file, and when deployed, it is available to all deployed applications in the server instance.

While creating the project for your application using IBM Integration Designer, you can choose how to package the adapter [either bundled with the (EAR) file or as a stand-alone (RAR) file]. Your choice affects how the adapter is used in the run time environment and how the properties for the adapter are displayed on the administrative console.

Choosing either to embed an adapter with your application or to deploy the adapter as a stand-alone module depends on how you want to administer the adapter. For a single copy of the adapter and do not care about disruption to multiple applications when you upgrade the adapter, then you would be more likely to deploy the adapter as a stand-alone module.

If you plan to run multiple versions, and if you care more about potential disruption when you upgrade the adapter, you would be more likely to embed the adapter with the application. Embedding the adapter with the application allows you to associate an adapter version with an application version and administer it as a single module.


Considerations for embedding an adapter in the application

Consider the following items if you plan to embed the adapter with your application:


Considerations for using a stand-alone adapter

Consider the following items if you plan to use a stand-alone adapter:


Considerations while deploying adapters with different versions

When you install multiple adapters with different versions of CWYBS_AdapterFoundation.jar, and if a lower version of the CWYBS_AdapterFoundation.jar is loaded during run time, the adapter returns the ResourceAdapterInternalException error message, due to a version conflict. For example, when you install Oracle E-Business Suite adapter version 7.0.0.3 and WebSphere Adapter for Oracle E-Business Suite version 7.5.0.3, the following error message is displayed "The version of CWYBS_AdapterFoundation.jar is not compatible with IBM WebSphere Adapter for Oracle E-Business Suite" as IBM WebSphere Adapter for Oracle E-Business Suite loads file:/C:/IBM/WebSphere/ProcServer7/profiles/ProcSrv01/installedConnectors/CWYOE_OracleEBS.rar/CWYBS_AdapterFoundation.jar with version 7.0.0.3. However, the base level of this jar required is version 7.5.0.3. To overcome this conflict, you must migrate all adapters to the same version level.

There are occasions when you work with embedded adapters that do not need a client-server communication, stand-alone adapters that need a server connection, or a hybrid mix of adapter connections.

The following scenarios cover the different behaviors of AFC version conflict detection, when you are deploying two or more adapters and at least one of the adapter version is 7.5 or higher.

Deploy a stand-alone Adapter

  1. Install WebSphere Adapter for Flat Files version 7.0.1.0 through the BPM administrative console.
  2. Install WebSphere Adapter for SAP Software version 7.5.0.0 through the administrative console.

  3. Create ActivationSpec for an ALE pass-through inbound operation.

  4. Create an application in IBM Integration Designer for a stand-alone ALE pass-through inbound operation.
  5. Install and start the application through the administrative console.

  6. Verify the error.

An error message is generated in the log/trace area of IBM Business Process Manager, to indicate an AFC version conflict. Deploy an embedded Adapter

  1. Import a build of WebSphere Adapter for FTP version 7.0.1.0, using a RAR file.

  2. Create a FTP Inbound EMD operation.
  3. Import a build of WebSphere Adapter for Oracle E-Business Suite version 7.5.0.0, using a RAR file.

  4. Create an Oracle inbound EMD operation, in the same module where you have created the FTP Inbound EMD operation.
  5. Deploy the module to IBM Business Process Manager.
  6. Check the trace.

At step 5, the deployment fails. At step 6, you get an internal error message due to the AFC version conflict.

To avoid a name conflict between the business object generated by the two adapters, generate the artifacts into different folders.

Deploy a combination of stand-alone and embedded Adapters

  1. Install WebSphere Adapter for JDBC version 7.0.1.0 through theIBM Business Process Manager administrative console.

  2. Create an ActivationSpec for a JDBC inbound operation.

  3. Create an application in IBM Integration Designer for a JDBC inbound operation, for the stand-alone Adapter deployment.
  4. Deploy the JDBC inbound application and trigger your inbound events.

  5. Create an application in IBM Integration Designer for a WebSphere Adapter for SAP Software version 7.5.0.0 inbound embedded Adapter deployment.
  6. Deploy an SAP inbound application, and trigger your inbound events.

You can resolve the AFC version conflict by using different class loaders for the stand-alone and embedded deployments. With this approach, the migration process handles different CWYBS_AdapterFoundation.jar files and do not conflict with each other. You can start both JDBC and SAP inbound applications successfully, and process Inbound events without exception.

For further assistance, visit http://www.ibm.com/support/docview.wss?uid=swg27006249.


Feedback


WebSphere Adapters in clustered environments

You can improve adapter performance and availability by deploying a module on a clustered server environment. Clusters are groups of servers that are managed together to balance workloads and to provide high availability and scalability.

The module you deployed is replicated across all servers in a cluster, regardless of whether you deploy the module using a stand-alone or an embedded adapter. The following IBM products support WebSphere Adapters in a clustered environment:

To deploy and configure WebSphere Adapter for Oracle E-Business Suite in a clustered environment, see: Deploy the module in a clustered environment. When you set up a server cluster, you create a Deployment Manager profile. The HAManager, a subcomponent of the Deployment Manager, notifies the Java™ Platform, Enterprise Edition (JEE) Connector Architecture (JCA) container to activate an adapter instance. For information about creating clustered environments, see the following link: http://pic.dhe.ibm.com/infocenter/dmndhelp/v7r5mx/index.jsp?topic=/com.ibm.wbpm.imuc.z.doc/topics/tins_zos_create_cluster.html.

Use WebSphere Extended Deployment, you can optionally enhance the performance of adapter instances in your clustered environment. WebSphere Extended Deployment extends the WAS ND capabilities by using a dynamic Workload Manager instance instead of a static Workload Manager. The dynamic Workload Manager instance can optimize the performance of adapter instances in the cluster by dynamically balancing the load of the requests. It means that application server instances can be automatically stopped and started based on the load variations, allowing systems with different capacities and configurations to handle load variations evenly. For information about the benefits of WebSphere Extended Deployment, see http://publib.boulder.ibm.com/infocenter/wxdinfo/v6r1m1/index.jsp.

In clustered environments, adapter instances can handle both inbound and outbound processes.


High availability for inbound processes

Inbound processes are based on events triggered as a result of updates to data in the Oracle database. WebSphere Adapter for Oracle E-Business Suite is configured to detect updates by polling an event table. The adapter then publishes the event to its endpoint.

When you deploy a module to a cluster, the Java Platform, Enterprise Edition (JEE) Connector Architecture (JCA) container checks the enableHASupport resource adapter property. If the value for the enableHASupport property is true, which is the default setting, all of the adapter instances are registered with the HAManager with a policy 1 of N. This policy means that only one of the adapter instances starts polling for events. Although other adapter instances in the cluster are started, they remain dormant with respect to the active event until the active adapter instance finishes processing the event. If the server on which the polling thread was started shuts down for some reason, an adapter instance running on one of the backup servers is activated.

In the active-passive configuration mode of the adapters, the endpoint application of the passive adapter instance also listens to the events/messages even if the enableHASupport property is set to True. This is because the alwaysactivateAllMDBs property in the JMS activation specification is set to True. To stop the endpoint application of the passive adapter instance from listening to the events, you must set the alwaysactivateAllMDBs property value to False. See Disable end point applications of the passive adapter .

Do not change the setting of the enableHASupport property.


High availability for outbound processes

In clustered environments, multiple adapter instances are available to perform outbound process requests. So, if the environment has multiple applications that interact with WebSphere Adapter for Oracle E-Business Suite for outbound requests, then you might improve performance by deploying the module to a clustered environment. In a clustered environment, multiple outbound requests can be processed simultaneously, so they are not attempting to process the same record.

If multiple outbound requests are attempting to process the same record, such as a Customer address, the workload management capability in WAS Network Deployment distributes the requests among the available adapter instances in the sequence they were received. As a result, these types of outbound requests in a clustered environment are processed in the same manner as in a single server environment: one adapter instance processes only one outbound request at a time. For more information about workload management, see the following link: http://publib.boulder.ibm.com/infocenter/wasinfo/v8r0/index.jsp?topic=/com.ibm.websphere.nd.doc/info/ae/ae/trun_wlm.html.


Feedback


Support for prepared statement caching

WebSphere Adapter for Oracle E-Business Suite supports prepared statement caching by the server, which can reduce the time required to perform an outbound or inbound operation or a batch of operations.

The adapter uses prepared statements, which are Java™ objects containing an SQL QUERY statement that is compiled once, but can be run multiple times. The server caches prepared statements to optimize their handling. To use prepared statement caching for the adapter, define a data source using the administrative console, and enable caching on the data source. Then configure the adapter to use the data source, using one of these methods:


Feedback


Migrate to version 7.5.0.3 of WebSphere Adapter for Oracle E-Business Suite

When you migrate to WebSphere Adapter for Oracle E-Business Suite version 7.5.0.3, you automatically upgrade from the previous version of the adapter. WebSphere Adapter for Oracle E-Business Suite version 6.0.2.x and version 6.1.x do not have its own adapter but use the WebSphere Adapter for JDBC as the base. From version 6.2, WebSphere Adapter for Oracle E-Business Suite is an independent adapter and has no dependency on WebSphere Adapter for JDBC. If you migrate the adapter from version 6.0.2.x or version 6.1.x, the underlying JDBC adapter is upgraded to WebSphere Adapter for Oracle E-Business Suite version 7.5.0.3. The project artifacts are also migrated to version 7.5.0.3 appropriately. Migrating the embedded applications belonging to an earlier version of the adapter, enables the applications to use the latest features and capabilities available in version 7.5.0.3.


Feedback


Migration considerations

WebSphere Adapter for Oracle E-Business Suite version 7.5.0.3 may have some features and updates that might affect your existing adapter applications. Before migrating applications that use WebSphere Adapter for Oracle E-Business Suite, you must consider some factors that might affect your existing applications.


Compatibility with earlier versions

Since the version 6.1.x, version 6.2.x, version 7.0.x, version 7.5.0, and version 7.5.0.2 of the adapter were based on WebSphere Adapter for JDBC, the artifacts generated using those versions are not compatible with the latest adapter version. For applications created using version 6.1.x, version 6.2.x, version 7.0.x and version 7.5.0 and version 7.5.0.2, of the adapter to use the features and functions present in version 7.5.0.3, run the migration wizard to migrate the adapter artifacts too to the latest version.

Because the version 7.0 of WebSphere Adapter for Oracle E-Business Suite is not fully compatible with version 7.5.0.2, you have to modify some artifacts manually. For example, the 'resourceAdapter name' property in .import file must be changed from "XXXX.IBM WebSphere Adapter for Oracle" to "XXXX.IBM WebSphere Adapter for Oracle E-Business Suite." IBM recommends to run the migration wizard for both adapter and the adapter artifacts to avoid manual changes being done to the artifacts.

The migration wizard replaces (upgrades) version 6.1.x, version 6.2.x, version 7.0.x, version 7.5.0, or version 7.5.0.2 of the adapter with version 7.5.0.3 and enables version 7.5.0.3 features and functionality for use with applications.

If the artifacts within a module have inconsistent versions, the entire module is marked as unavailable for migration and cannot be selected. Version inconsistencies are recorded in the workspace log, as they indicate that a project might be corrupted.

The adapter migration wizard in IBM Integration Designer Version 7.5.1 only supports the migration of adapters from version 6.1.x, version 6.2.x, version 7.0.x, version 7.5.0, and version 7.5.0.2 to version 7.5.0.3. It does not support the adapter migration from lower versions to any of the versions before version 7.5.0.3.


Decide whether to upgrade or to upgrade and migrate

The default processing of the migration wizard is to upgrade the adapter and to migrate the application artifacts so the applications can use features and functions available in version 7.5.0.3 of the adapter. When you choose to upgrade the adapter by selecting a project of version 7.5.0.2, the wizard automatically selects the associated artifacts for migration.

If you decide to upgrade the adapter from version 6.1.x, version 6.2.x, version 7.0.x, version 7.5.0, or version 7.5.0.2 to version 7.5.0.3, but you do not want to migrate the adapter artifacts, you can do so by clearing the adapter artifacts from the appropriate area of the migration wizard.

Run the migration wizard without selecting any adapter artifacts installs and upgrades your adapter. As the artifacts are not migrated, applications cannot take advantage of the features and capabilities that exist in version 7.5.0.3 of the adapter.


Migrate multiple adapters referred within a project

When a module contains one or more connector projects and each of them refer to different adapters ( a module project that contains connector projects referring to Oracle and SAP adapters), the migration wizard identifies the artifacts belonging to each adapter and migrates the artifacts without disrupting the artifacts of the other adapters.

When you select the module project and launch the migration wizard:

If you select the connector project and launch the migration wizard:


Run the migration wizard in a test environment

Because adapter migration might require you to change those applications that use version 7.5.0.3 of WebSphere Adapter for Oracle E-Business Suite, always perform the migration in a development environment first and test applications before deploying the application to a production environment.

The migration wizard is fully integrated with the development environment.


Deprecated features

A deprecated feature is one that is supported but no longer recommended and that might become obsolete. The following feature from earlier versions of WebSphere Adapter for Oracle E-Business Suite have been deprecated in Version 6.1.x, version 6.2.x, version 7.0.xand Version 7.5.0 and version 7.5.0.2 and might require changes to applications:


Feedback


Performing the migration

You can migrate a project or EAR file to version 7.5.0.3 using the adapter migration wizard. When the tool is finished, the migration is complete and you can work in the project or deploy the module.

Review the information in Migration considerations. To perform the migration in IBM Integration Designer.

After migration is complete, the module is no longer compatible with previous versions of the BPM or WebSphere Enterprise Service Bus runtimes or IBM Integration Designer.

The following steps describe how to run the adapter migration wizard from the connector project menu while in the Java™ EE perspective in IBM Integration Designer.

  1. Import the PI (project interchange) file for an existing project into the workspace.

    Ensure that you do not modify the contents of the RAR or copy the adapter JAR file outside the connector project.

  2. When projects are created in an earlier version of IBM Integration Designer, the Workspace Migration wizard starts automatically and selects the projects to migrate. Follow the wizard and complete the workspace migration. See http://pic.dhe.ibm.com/infocenter/dmndhelp/v7r5m1/topic/com.ibm.wbpm.wid.imuc.doc/topics/tmigsrcart.html.
  3. Change to the Java EE perspective.
  4. Right-click the module and select Migrate connector project. For example, the adapter RAR module.

    You can also launch the adapter migration wizard in the following ways:

    • Right-click the project in the Java EE perspective and select Migrate adapter artifacts.

    • From the Problems view, right-click a migration-specific message and select Quick Fix to correct the problem.

  5. In the Select Projects window.

    1. The Source connector field displays the name of the connector project that you are migrating. If you are migrating a module project, this field lists all the connector projects in the module project. Select the source project from the list. See Migrate multiple adapters referred within a project.
    2. The Target connector field displays the name of the connector to which you are migrating. If you are working with more than one adapter version, this list displays the names of all the compatible connectors. Select the connector you want to migrate.
    3. The Target version field displays the version corresponding to the target connector that you selected in the previous step.
    4. The Dependent artifacts project area lists the adapter artifacts that are migrated. If you are migrating a module project, this area lists only the selected module project. If you are migrating a connector project within the module project, this area lists all projects which reference the selected connector project, including the module project. By default, all the dependent artifact projects are selected. If you do not select a dependent artifact project, that project is not migrated. You can migrate any project that you have not selected at a later time. Previously migrated projects, projects with a current version, and projects that contain errors are unavailable for migration and are not selected. See Upgrading but not migrating a project.

    5. Click Next. A warning window is displayed with the message, “Properties that are not supported in this version of the target adapter will be removed during the migration”.

    6. Click OK.

  6. In the Review Changes window, review the migration changes that occur in each of the artifacts that you are migrating. To view the details, expand each node by clicking the + sign.
  7. To complete the migration:

    • Click Finish.

    • If the files that need to be updated during migration are in read-only mode, you will be unable to click on the Finish button. To view these files, click Next. The Update Read-only files window displays the read-only files. To update these files and continue with the migration, click Finish. To exit the wizard without migrating the adapter, click Cancel.

    Before running the migration process, the wizard performs a backup of all projects affected by the migration. The projects are backed up to a temporary folder within the workspace. If the migration fails for any reason, or if you decide to cancel the migration before it completes, the wizard deletes the modified projects and replaces them with the projects stored in the temporary folder.

    Upon completing the migration successfully, all backed up projects are deleted.

  8. If you are migrating an EAR file, optionally create a new EAR file with the migrated adapter and artifacts, and deploy it to IBM Business Process Manager or WebSphere Enterprise Service Bus. For more information about exporting and deploying an EAR file, sees devoted to it in this documentation.

The project or EAR file is migrated to version 7.5.0.3. You do not need to run the external service wizard after exiting the adapter migration wizard.


Feedback


Upgrading but not migrating a project

You can upgrade the adapter from an earlier version, to version 7.5.0.3 while choosing not to migrate the adapter project artifacts. Running the migration wizard without selecting any adapter artifacts installs and upgrades your adapter. As the artifacts are not migrated, applications cannot take advantage of the features and capabilities that exist in version 7.5.0.3 of the adapter.

  1. Import the PI (project interchange) file into the workspace.
  2. When projects are created in an earlier version of IBM Integration Designer, the Workspace Migration wizard starts automatically and selects the projects to migrate. Follow the wizard and complete the workspace migration. See http://pic.dhe.ibm.com/infocenter/dmndhelp/v7r5m1/topic/com.ibm.wbpm.wid.imuc.doc/topics/tmigsrcart.html.

  3. In the Java™ EE perspective, right-click the project name and click Migrate connector project. The Adapter Migration wizard is displayed.

  4. In the Select Projects window, clear the dependent artifact projects, and click Next. A warning window is displayed with the message, “The properties that are not supported in the version of the target adapter will be removed during the migration.”

  5. Click OK.

  6. In the Review Changes window, review the migration changes that occur during updating the project. To view the details, expand each node by clicking the + sign.
  7. To complete the migration:

    • Click Finish.

    • If the files that need to be updated during migration are in read-only mode, you will be unable to click on the Finish button. To view these files, click Next. The Update Read-only files window displays the read-only files. To update these files and continue with the migration, click Finish. To exit the wizard without migrating the adapter, click Cancel.

The project can now be used with WebSphere Adapter for Oracle E-Business Suite, version 7.5.0.3.

After upgrading the adapter, you have to modify some artifacts manually depending on the versions of the adapters involved in migration. For example, if you are upgrading the adapter from version 7.5.0.2 to version 7.0, the 'resourceAdapter name' property in .import file must be changed from "XXXX.IBM WebSphere Adapter for Oracle" to "XXXX.IBM WebSphere Adapter for Oracle E-Business Suite." IBM recommends to run the migration wizard for both adapter and the adapter artifacts to avoid manual changes being done to some artifacts after the migration.



Related tasks:

Export the module as an EAR file

Install the EAR file

Feedback


Migrate WebSphere Business Integration applications

You need to migrate the WebSphere Business Integration applications so they become compatible with Version 7.5.0.3 of your adapter.

Migrate WebSphere Business Integration applications for use with Version 7.5.0.3 of your WebSphere adapter is a multistep process. First, the artifacts from WebSphere InterChange Server are migrated and converted. A project is then created for the artifacts in IBM Integration Designer. In the remaining steps, the adapter-specific artifacts are migrated and converted into the JCA-compliant format supported by Version 7.5.0.3 of the adapter.


Example

The following diagram shows the wizards that you use to migrate WebSphere Business Integration solutions from WebSphere InterChange Server, so these applications can be used with Version 7.5.0.3 of your adapter.


Feedback


Migrate applications from WebSphere InterChange Server

To use Version 7.5.0.3 of WebSphere Adapter for Oracle E-Business Suite with applications from WebSphere InterChange Server, you need to migrate the application artifacts and convert them so they can be deployed and run on IBM Business Process Manager or WebSphere Enterprise Service Bus. Understanding this task at a high level helps you perform the steps needed to accomplish the task.

The following figure illustrates the flow of the migration task. The steps that follow the figure describe this task at a high level only. See the topics following this roadmap for the details on how to perform each of these steps.

Figure 1. Roadmap for migrating applications from WebSphere InterChange Server

Migrate applications from WebSphere InterChange Server

This task consists of the following steps:

  1. Run the WebSphere InterChange Server migration wizard.

    The WebSphere InterChange Server migration wizard moves the application artifacts into IBM Integration Designer. The migrated adapter artifacts are not fully JCA-compliant at the completion of this task.

  2. Verify the WebSphere InterChange Server migration is successful.

    Review all messages from the Migration results window and take action if required.

  3. Consider the implications of using Version 7.5.0.3 of WebSphere Adapter for Oracle E-Business Suite.

    In addition to considerations for migrating WebSphere InterChange Server applications, you need to consider how Version 7.5.0.3 of WebSphere Adapter for Oracle E-Business Suite works with the migrated applications. Some of the adapter operations supported by WebSphere InterChange Server applications might be supported and implemented differently with Version 7.5.0.3 of the adapter.

  4. Run the adapter migration wizard.

    Run the adapter migration wizard to update adapter-specific artifacts such as the schemas and service definition files (.import, .export, and .wsdl files) for use with Version 7.5.0.3 of the adapter.



Related concepts:

Changes to the import, export, and WSDL files after migration


Related tasks:

Migrate application artifacts from WebSphere InterChange Server

Migrate adapter-specific artifacts


Related reference:

Migration considerations for WebSphere Business Integration adapters

Feedback


Migration considerations for WebSphere Business Integration adapters

By migrating to WebSphere Adapter for Oracle E-Business Suite Version 7.5.0.3, you have an adapter that is compliant with the Java™ Platform, Enterprise Edition (JEE) Connector Architecture (JCA) and designed specifically for service-oriented architecture.


Application artifacts

Before running the adapter migration wizard, use the WebSphere InterChange Server migration wizard to generate the application artifacts for the WebSphere Business Integration adapter, including the business objects, maps, and collaborations. Then you can run the adapter migration wizard to update the adapter-specific artifacts such as the schemas and service definition files (.import, .export, and .wsdl) so they are suitably converted into a format that is compliant with JCA.


Run the migration wizard in a test environment first

Because migrating from a WebSphere Business Integration adapter to WebSphere Adapter for Oracle E-Business Suite might require changes to the applications that use Version 7.5.0.3 of WebSphere Adapter for Oracle E-Business Suite, always perform the migration in a development environment first and test applications before deploying the application to a production environment.



Related concepts:

Migrate applications from WebSphere InterChange Server

Changes to the import, export, and WSDL files after migration


Related tasks:

Migrate application artifacts from WebSphere InterChange Server

Migrate adapter-specific artifacts

Feedback


Migrate application artifacts from WebSphere InterChange Server

To migrate the application artifacts into IBM Integration Designer, run the WebSphere InterChange Server migration wizard. The wizard imports and converts most of the artifacts into a format that is compatible with BPM or WebSphere Enterprise Service Bus.

Launch the WebSphere InterChange Server migration wizard from within IBM Integration Designer to migrate the application artifacts from WebSphere InterChange Server format into artifacts that are compatible with BPM or WebSphere Enterprise Service Bus.

For information about how to prepare to migrate artifacts from WebSphere InterChange Server and for detailed instructions on performing the migration and verifying the migration was successful, see http://pic.dhe.ibm.com/infocenter/dmndhelp/v7r5m1/index.jsp?topic=/com.ibm.wbpm.wid.imuc.doc/topics/twics.html. Running WebSphere InterChange Server migration wizard might not fully convert adapter-specific artifacts (such as service descriptors, service definitions, and business objects) into IBM Business Process Manager or WebSphere Enterprise Service Bus compatible artifacts. To complete the migration of adapter-specific artifacts, run the adapter migration wizard after you have successfully run the WebSphere InterChange Server migration wizard.

While you run the WebSphere InterChange Server migration wizard, ensure set each connector in the repository to the same adapter version.

The project and application artifacts are migrated and converted into IBM Business Process Manager compatible artifacts.


Run the adapter migration wizard to migrate the adapter-specific artifacts.



Related concepts:

Migrate applications from WebSphere InterChange Server

Changes to the import, export, and WSDL files after migration


Related tasks:

Migrate adapter-specific artifacts


Related reference:

Migration considerations for WebSphere Business Integration adapters

Feedback


Migrate adapter-specific artifacts

After a project is created for the artifacts in IBM Integration Designer, you can migrate the project using the adapter migration wizard. The adapter migration wizard updates adapter-specific artifacts such as the schemas and service definition files (.import, .export, and .wsdl) for use with version 7.5.0.3 of the adapter. When you finish running the adapter migration wizard, the migration is complete and you can work in the project or deploy the module.

Before running the adapter migration wizard, do the following steps:

After migration is complete, the module will work only with Version 7.5.0.3 of your adapter.

To perform the migration in IBM Integration Designer.

  1. Import the PI (project interchange) file for an existing project into the workspace.
  2. When projects are created in an earlier version of IBM Integration Designer, the Workspace Migration wizard starts automatically and selects the projects to migrate. Follow the wizard and complete the workspace migration. See http://pic.dhe.ibm.com/infocenter/dmndhelp/v7r5m1/topic/com.ibm.wbpm.wid.imuc.doc/topics/tmigsrcart.html.
  3. Change to the Java™ EE perspective.
  4. Right-click the connector project and select Migrate connector project.

    You can also launch the adapter migration wizard by using the right-click option and selecting the module project in the Java EE perspective and selecting Migrate adapter artifacts.

    If the adapter type ( CICS/IMS adapter) is not supported by the migration wizard, the Migrate connector project and Migrate adapter artifacts menus are not available for selection. If the adapter project is of the latest version and the module projects referencing this adapter project are also of the latest version, these menus are disabled. When you launch the migration wizard from the connector project while in the Java EE perspective, by default all the dependent artifact projects are selected. If you do not select a dependent artifact project, that project is not migrated.

  5. In the Select Projects window.

    1. The Source connector field displays the name of the connector project that you are migrating. Select the source project from the list.
    2. The Target connector field displays the name of the connector to which you are migrating. If you are working with more than one adapter version, this list displays the names of all the compatible connectors. Select the connector to which you want to migrate.
    3. The Target version field displays the version corresponding to the target connector you selected in the previous step.
    4. The Dependent artifacts project area lists the adapter artifacts that are migrated.
    5. Review the tasks and warnings presented on the welcome page, and click Next. A warning window is displayed with the message, “The properties that are not supported in the version of the target adapter are removed during the migration.”

    6. Click OK.

  6. In the Review Changes window, review the migration changes that occur in each of the artifacts that you are migrating. To view the details, expand each node by clicking the + sign.
  7. To complete the migration:

    • Click Finish.

    • If the files that need to be updated during migration are in read-only mode, you will be unable to click on the Finish button. To view these files, click Next. The Update Read-only files window displays the read-only files. To update these files and continue with the migration, click Finish. To exit the wizard without migrating the adapter, click Cancel.

    Before performing the migration process, the wizard backs up all projects affected by the migration. The projects are backed up to a temporary folder within the workspace. If the migration fails for any reason, or if you decide to cancel the migration before it completes, the wizard deletes the modified projects and replaces them with the projects stored in the temporary folder.

  8. Select Project > Clean, to refresh and rebuild the workspace for the changes to take effect.

  9. If you are migrating an EAR file, create a new EAR file with the migrated adapter and artifacts, and deploy it to IBM Business Process Manager or WebSphere Enterprise Service Bus. For information about exporting and deploying an EAR file, see Deploy the module for production.

The project is migrated to Version 7.5.0.3. You do not need to run the external service wizard after exiting the adapter migration wizard.



Related concepts:

Migrate applications from WebSphere InterChange Server

Changes to the import, export, and WSDL files after migration


Related tasks:

Migrate application artifacts from WebSphere InterChange Server


Related reference:

Migration considerations for WebSphere Business Integration adapters

Feedback


Changes to the import, export, and WSDL files after migration

When the WebSphere InterChange Server migration wizard moves the application artifacts into IBM Integration Designer, changes made are reflected in the service definition files: the import, export, and WSDL files.

The migrated adapter artifacts are not fully JCA-compliant at the completion of this task. You can complete the migration of the adapter-specific artifacts (such as service descriptors, service definitions, and business objects) to a JCA compatible format by running the adapter migration wizard.


Changes to the import file

During migration, the affected module artifacts are migrated to an import file. The existing JMS Binding property is changed to the EIS Binding property in the import file. The other property details added in the import file include information about the data binding configuration, changes to the connection information in the Managed Connection Factory properties, and several new method bindings.


Changes to the export file

During migration, the affected module artifacts are migrated to an export file. The existing JMS Binding property is changed to the EIS Binding property in the export file. The other property details added in the export file include information about the data binding configuration, changes to the connection information in the Activation Specification properties, and several new method bindings.


Changes to the WSDL file after migration

During migration, the affected module artifacts are migrated to corresponding WSDL files that include adapter specific service description WSDL artifacts. The service description files become JCA compatible. The WSDL files have an input and output type for each operation. Both the inbound and outbound operations work on their specific input types to produce corresponding output types after the operations are performed.



Related concepts:

Migrate applications from WebSphere InterChange Server


Related tasks:

Migrate application artifacts from WebSphere InterChange Server

Migrate adapter-specific artifacts


Related reference:

Migration considerations for WebSphere Business Integration adapters

Feedback


Samples and tutorials

To help you use WebSphere Adapters, samples and tutorials are available from the Business Process Management Samples and Tutorials website.

You can access the samples and tutorials in either of the following ways:


Feedback


Configure the module for deployment

To configure the adapter so that it can be deployed on IBM Business Process Manager or WebSphere Enterprise Service Bus, use IBM Integration Designer to create a module, which is exported as an EAR file when you deploy the adapter. You then specify the business objects you want to discover and the system on which you want to discover them.

  1. Road map for configuring the module Before you can use WebSphere Adapter for Oracle E-Business Suite in a runtime environment, configure the module. Understanding this task at a high level helps you perform the steps needed to accomplish the task.
  2. Create the event store You need to create the event store in the Oracle database before the adapter can process inbound events. You can set triggers on user tables as needed to populate the event store. For Oracle E-Business Suite, configure the Oracle Business Event System and Concurrent Program to capture the event.
  3. Create an authentication alias An authentication alias is a feature that encrypts the password used by the adapter to access the Oracle database. The adapter can use it to connect to the Oracle database instead of using a user ID and password stored in an adapter property.
  4. Create the project To begin the process of creating and deploying a module, you start the external service wizard in IBM Integration Designer. The wizard creates a connector project, which is used to organize the files associated with the module.
  5. Add external software dependencies The external service wizard needs a copy of certain files from the Oracle E-Business Suite to be able to communicate with it. Set the location of the JAR files that contain the JDBC driver for Oracle and any native system library files needed.
  6. Set connection properties for the external service wizard For the external service wizard to connect to the database instance to discover database objects, connection properties must be specified.
  7. Configure the module for outbound processing To configure a module to use the adapter for outbound processing, use the external service wizard in IBM Integration Designer to find and select business objects and services from the Oracle database, and to generate the business object definitions and related artifacts.
  8. Configure the module for inbound processing To configure a module to use the adapter for inbound processing, use the external service wizard in IBM Integration Designer to find and select business objects and services from the Oracle database, and to generate business object definitions and related artifacts.
  9. Configure the module for advanced queue integration To configure a module to use the adapter for outbound or inbound processing, use the external service wizard in IBM Integration Designer to create the advanced queue header and payload business objects.
  10. Configure the module for XML Gateway interface for web service To configure the module for XML Gateway interface, use the external service wizard in Integration Designer. You can configure this interface only for the outbound integration. You can select the number of interfaces you would want to create. For each interface you create, you can select the required elements as per your business requirement.
  11. Configure the module for XML Gateway interface for JMS To configure the module for XML Gateway interface for JMS, use the external service wizard in IBM Integration Designer. You can configure this interface only for the outbound integration. You can select the number of interfaces you would want to create. For each interface you create, you can select the required elements as per your business requirement.



Previous topic: Plan for adapter implementation


Next topic: Deploy the module for production

Feedback


Road map for configuring the module

Before you can use WebSphere Adapter for Oracle E-Business Suite in a runtime environment, configure the module. Understanding this task at a high level helps you perform the steps needed to accomplish the task.

You configure the module for the adapter to use by using IBM Integration Designer. The following figure illustrates the flow of the configuration task, and the steps that follow the figure describe this task at a high level only. See the topics following this road map for the details on how to perform each of these steps.

Figure 1. Road map for configuring the module

Configure the module for deployment environment

This task consists of the following step:

  1. Create the event store for inbound processing.

  2. Create an authentication alias to access the Oracle database with an encrypted password. This step is optional, depending on your policy for handling passwords and IDs. You perform this step using the server.

  3. Create the project. First, start the external service wizard in IBM Integration Designer to begin the process of creating and deploying a module. The wizard creates a project used to organize the files associated with the module.

  4. Add the JDBC drivers and native system library files required by WebSphere Adapter for Oracle E-Business Suite to the project. These dependencies are also required when you export the module as an EAR file, and deploy the EAR file to the server.

  5. Set connection properties the external service wizard needs to connect to the Oracle database for discovery of objects and services.

  6. Configure the module for inbound processing or outbound processing by using the external service wizard to find and select business objects and services from the Oracle database, and to generate business object definitions and related artifacts.

    1. Edit and run the query that discovers database objects that you can access.

    2. Select and configure business objects for inbound or outbound processing.

    3. Set global properties for operations.

    4. Set deployment properties the adapter uses to connect to the Oracle database at run time. Then, generate the service by using the external service wizard to save the new module, which contains the business object or objects you configured, the import file or export file, and the service interface.



Next topic: Create the event store

Feedback


Create the event store

You need to create the event store in the Oracle database before the adapter can process inbound events. You can set triggers on user tables as needed to populate the event store. For Oracle E-Business Suite, configure the Oracle Business Event System and Concurrent Program to capture the event.

Perform this task only if you need inbound processing of events. Create the event store in the database that contains the tables for which events are reported.

  1. Create the event store. Sample scripts are provided to create the event store for the Oracle database, as follows:

    • ibm_websphere_event_table_create.sql

    These files are in the IID_installation_dir/ResourceAdapters/OracleEBS_version/scripts directory, where IID_installation_dir is the installation directory for IBM Integration Designer, and version identifies the version of the adapter, for example, 7.5.

  2. For Oracle database, set up triggers on user tables so the changes to the user tables can automatically generate events that is stored in the event store. If using triggers is not an option, then you can populate the event store by using custom SQL code or stored procedures that are not started through triggers. Instead, the triggers can be started through a batch program that runs periodically or that you run manually. For Oracle E-Business Suite, it is recommended that you configure the Oracle Business Event System and Concurrent Programs to define the events and automatically capture the events. The Concurrent Programs can be scheduled to run periodically or run manually when required.

The event store is available for event processing.



Previous topic: Road map for configuring the module


Next topic: Create an authentication alias


Related concepts:

Event store

Feedback


Create an authentication alias

An authentication alias is a feature that encrypts the password used by the adapter to access the Oracle database. The adapter can use it to connect to the Oracle database instead of using a user ID and password stored in an adapter property.

To create an authentication alias, you must have access to the administrative console of IBM Business Process Manager or WebSphere Enterprise Service Bus. You must also know the user name and password to connect to the Oracle database.

The following procedure shows you how to gain access to the administrative console through IBM Integration Designer. If you are using the administrative console directly (without going through IBM Integration Designer, log on to the administrative console and skip to step 2

Use an authentication alias eliminates the need to store the password in clear text in an adapter configuration property, where it might be visible to others.

To create an authentication alias, use the following procedure.

  1. Start the administrative console.

    To start the administrative console through IBM Integration Designer.

    1. In the Business Integration perspective of IBM Integration Designer, click the Servers tab.

    2. If the server does not show a status of Started, right-click the name of the server ( IBM Business Process Manager) and click Start. Wait for the status of the server to be displayed as Started.
    3. Right-click the name of the server and click Run administrative console.
    4. Log on to the administrative console. If your administrative console requires a user ID and password, type the ID and password and click Log in. If the user ID and password are not required, click Log in.

  2. In the administrative console, click Security > Global security.

  3. Under Java Authentication and Authorization Service, click J2C authentication data.

  4. Create an authentication alias:

    1. In the list of J2C authentication aliases that is displayed, click New.

    2. In the General Properties area, type the name of the authentication alias in the Alias field.
    3. Type the User ID and password required to establish a connection to the Oracle database.

    4. Optional: Type a description of the alias.

    5. Click OK.

      The newly created alias is displayed.

      The full name of the alias contains the node name and the authentication alias name you specified. For example, if you create an alias on the node widNode with the name ProductionServerAlias, then the full name is widNode/ProductionServerAlias. This full name is the one you use in subsequent configuration windows.

    6. Click Save.

You created an authentication alias, which you specify when you configure the adapter properties later in the wizard.



Previous topic: Create the event store


Next topic: Create the project


Related concepts:

User authentication

Feedback


Create the project

To begin the process of creating and deploying a module, you start the external service wizard in IBM Integration Designer. The wizard creates a connector project, which is used to organize the files associated with the module.

Ensure that you have gathered the information you need to establish a connection to the Oracle database. For example, you need the name or IP address of the Oracle database, and the user ID and password to access it.

If you have an existing project, you can use it instead of creating a new one. Select it before starting the wizard.

  1. To start the external service wizard, go to the Business Integration perspective of IBM Integration Designer, and then click File > New > External Service. Click Next.

  2. In the Select the Service Type or Registry window, expand the Adapters node, select Oracle E-Business Suite, and then click Next.

  3. In the Select an Adapter window, expand the Oracle node. Select IBM WebSphere Adapter for Oracle E-Business Suite (IBM : version), where version is the version of the adapter you want to use, and then click Next.

  4. In the Import a RAR File window, accept the default project name in the Connector project field or type a different name.

  5. In the Target runtime environment field, select the type of server where you want to deploy the module. The wizard creates the artifacts appropriate to that server.

  6. Click Next. The Locate the Required Files and Libraries window is displayed.


Continue working in the external service wizard. The next step is to add dependent JAR files to the project.



Previous topic: Create an authentication alias


Next topic: Add external software dependencies


Related tasks:

Install the EAR file

Feedback


Add external software dependencies

The external service wizard needs a copy of certain files from the Oracle E-Business Suite to be able to communicate with it. Set the location of the JAR files that contain the JDBC driver for Oracle and any native system library files needed.

You must run the external service wizard in IBM Integration Designer to perform this task.

In addition to performing this task when you configure the module, you also need to deploy files on IBM Business Process Manager or WebSphere Enterprise Service Bus.

  1. Obtain the Oracle JDBC driver-specific files or native libraries for the database software and operating system from the database administrator or from the database software website. The following table lists the Oracle JDBC driver files needed for the Oracle database software.

    Oracle JDBC driver files for Oracle database software

    Database software Driver JDBC driver files Native System Libraries
    Oracle Thin driver ojdbc6.jar or ojdbc14.jar depending on the JRE version None

    The Java™ Runtime Environment (JRE) version required by the Oracle JDBC driver must not be higher than the JRE version in the runtime environment. For example, if the JRE version is 1.5 in the runtime environment, then the Oracle JDBC Driver must be "ojdbc14.jar" which supports both Java Development Kit (JDK) 1.4 and JDK 1.5; if the JRE version is 1.6 in the runtime environment, then the Oracle JDBC Driver must be "ojdbc6.jar" which supports JDK version 1.6.

  2. Obtain the Oracle JMS driver-specific files or native libraries for the database software and operating system from the database administrator or from the database software website. The following table lists the Oracle JMS files needed for Oracle database software.

    Oracle JMS driver files for Oracle database software

    Database software Driver JMS driver files Native System Libraries
    Oracle JDBC Thin ojdbc6.jar or ojdbc14.jar depending on the JRE version None
    Oracle JMS apaqi*.jar None
    Oracle JMS jmscommon*.jar None

    The jdbc driver and jms driver should be compatible with JRE version and Oracle Database version.

  3. In the Locate the Required Files and Libraries window, specify the location of the Oracle JDBC driver-specific files required by the adapter.

    1. In Oracle JDBC driver JAR files, click Add and select the Oracle JDBC driver files or Oracle JMS driver files.

    2. If using the Oracle JDBC type 2 driver, click Add in System libraries to add the native system libraries required to access the database server. If you use Oracle JDBC type 4 driver, leave this field empty.

  4. Click Next. The wizard displays the Select the Processing Direction window.

The wizard has the files it requires to communicate with the database server.


Continue working in the external service wizard. The next step is to provide the information the wizard needs to communicate with the Oracle database.



Previous topic: Create the project


Next topic: Set connection properties for the external service wizard


Related tasks:

Add external software dependencies on the server

Feedback


Set connection properties for the external service wizard

For the external service wizard to connect to the database instance to discover database objects, connection properties must be specified.

Before you can configure the connection properties, start the external service wizard.

The external service wizard requires these properties to connect to the database for discovery and for creating the service description. For more information about the properties, see Connection properties for the wizard.

  1. In the Select the Processing Direction window, select Outbound to pass data from your service import to the adapter or Inbound to pass data from the adapter to your service export, and then click Next. The Set the Discovery Properties window is displayed.

  2. In the Set the Discovery Properties window, specify the connection properties for the wizard to connect to the Oracle database.

    1. In the list of database software, select BPM and version. The Properties area displays fields where you specify database-specific connection properties.

    2. In the JDBC driver type field, select the type of JDBC driver you want to use.

    3. In the System ID field, specify the database name.

    4. In the Host name field, specify the host name or IP address of the database server. If you specify the IP address in IPv6 format, enclose the address within square brackets ([]).

    5. In the Port number field, specify the port number for connecting to the database. If you select a named driver in the JDBC driver type field, the wizard provides a default value for the Port number field. If you select the driver Other, the port number is not enabled.

    6. If you select a named driver in the JDBC driver type field, the wizard provides a default value for the JDBC driver class name field and builds the value for the Database URL field from other connection fields. If you select the driver Other, you must specify the driver class name and database URL (although part of the database URL is available).

    7. In the Additional JDBC driver connection properties field, specify additional properties to be set when connecting to the database. Specify one or more name:value pairs, separated by the semicolon character (;). For example:
      loginTimeout:20;readOnly:true;
      securityMechanism:USER_ONLY_SECURITY 

    The connection information is used only for the discovery process. Later in the wizard, you can specify different connection information to be used at run time.

  3. In the User name and Password fields, type the user name and password to use to connect to the database from the wizard. This user name is used only during the discovery process and is not saved. Later in the wizard, you can specify a different user name and password or a different authentication method to be used at run time.

  4. In the Prefix for business object names field, type a string to be placed at the beginning of business object names. This prefix field does not require a value, and can be left blank.

  5. To set additional advanced properties, click Advanced.

  6. To enable bidirectional support for the adapter at run time:

    1. In the Bidi properties area, select Bidi transformation.

    2. Set the ordering schema, text direction, symmetric swapping, character shaping, and numeric shaping properties to control how bidirectional transformation is performed.

  7. To turn on AUTOCOMMIT for the database, select the Set auto commit on database connection check box.
  8. To change the location of the log files or the amount of information included in the logs, select the Change logging properties for wizard check box, and then provide the following information:

    • In the Log file output location field, specify the location of the log file for the wizard.

    • In the Logging level field, specify the severity of errors that you want logged.

    This log information is for the wizard only; at run time, the adapter writes the error messages and the trace information into the standard log and trace files for the server.

  9. Click Next.

    If the wizard generates the com.ibm.adapter.framework.BaseException exception, the adapter cannot connect to the database server. The message contains additional information about a possible cause for the problem. In addition, you can check the logs, which are in the directory specified in the Log file output location field. Verify the connection information is correct.

The external service wizard connects to the database, and displays the Find Objects in the Enterprise System window.


Continue working in the wizard. The next step is to examine the database to locate the objects for which you want the wizard to create business objects.



Previous topic: Add external software dependencies


Next topic: Configure the module for outbound processing


Related concepts:

Globalization and bidirectional transformation


Related reference:

Connection properties for the wizard

Feedback


Configure the module for outbound processing

To configure a module to use the adapter for outbound processing, use the external service wizard in IBM Integration Designer to find and select business objects and services from the Oracle database, and to generate the business object definitions and related artifacts.

  1. Discovering database objects After connecting to the database, run a query to search for database objects. Browse through the discovered objects navigation tree to understand the structure of objects in the Oracle database, and use filters to display only the database objects you want to see. Define how many business objects you want to create for user-defined database queries.
  2. Selecting and configuring business objects Using the list of database objects discovered by the external service wizard, and the query object templates you specified, continue using the wizard to select the database objects that you need to access in your module. Then provide the configuration information for your new business objects.
  3. Set global properties for operations After you select database objects in the external service wizard, you need to specify properties that apply to all business objects.
  4. Set deployment properties and generating the service After you select and configure the business objects for your module, use the external service wizard to configure properties the adapter uses to connect to a specific database. The wizard creates a new business integration module where all the artifacts and property values are saved.
  5. Completing the configuration In some situations, manual configuration steps are needed to complete the configuration of your business objects.



Previous topic: Set connection properties for the external service wizard


Next topic: Configure the module for inbound processing


Related concepts:

Outbound processing

Feedback


Discovering database objects

After connecting to the database, run a query to search for database objects. Browse through the discovered objects navigation tree to understand the structure of objects in the Oracle database, and use filters to display only the database objects you want to see. Define how many business objects you want to create for user-defined database queries.

You must understand the data requirements of the program that requires to access the database. For example, you need the following information about the database:

This task starts in the Find Objects in the Enterprise System window of the external service wizard.

  1. In the Find Objects in the Enterprise System window, click Edit Query. The Set the Query Properties window is displayed.

    Use the Set the Query Properties window to perform the following tasks:

    • Reduce the search time by searching a subset of database schemas
    • Omit one or more types of database objects from the search

    • Make the wizard prompt you for application-specific information that cannot be automatically determined based on information in the database

    • Set the number of query business objects you want to create
    • Map the Oracle data types Date and Timestamp to date and dateTime

  2. To limit the number of database schemas that are retrieved, type the name of the schema or a name pattern in Schema name or pattern. Use the question mark or underscore (? or _) character to match a single character and the asterisk or percentage sign (* or %) to match multiple characters. Only schemas that start with that string or match that pattern are displayed when you run the query. If you do not specify a schema name pattern, all schemas in the database are displayed. Using a filter can speed up the discovery process if the database contains many schemas.
  3. To omit one or more types of objects from the search, select the types of objects to omit (tables, views, stored procedures and stored functions, and synonyms or nicknames) in Supported database object types, and then click Remove. If you change your mind, click Add to add the object type back. If you require to access only specific types of database objects and speed the discovery process, omit the ones you do not need.
  4. The table, stored procedure, and stored function objects with the date and timestamp data types are mapped to the string data type by default. To create map these objects to the actual data types that are supported by the JDBC driver such as the date and datetime data types, select the Map Oracle JDBC Date/Timestamp types to date/dateTime check box.

    The default data type mapping differs based on the different Oracle JDBC driver versions, for example, the JDBC driver version ojdbc6.jar maps the Date to dateTime data type instead of mapping it to Date. In such cases, the appropriate data type must be manually selected in the Set the Configuration Properties for 'object' window. To customize the format of the Date and Timestamp data types in the Application Info section of the Properties view, clear the Map Oracle JDBC Date/Timestamp types to date/dateTime check box. Also, ensure the data types are mapped to the default string data type in the Set the Configuration Properties for 'object' window.

  5. Select the Prompt for additional configuration settings when adding business object check box. Then, when you add a database object to the list of business objects to create, the wizard automatically prompts you for all user-configurable application-specific information for the object. For example, if you select this option, the wizard guides you through the process of building a simple parent-child hierarchy of business objects. If you need a hierarchy, that a table business object has two attributes referring to attributes in two different tables (that is, it has two parent business objects), complete the configuration in the IBM Integration Designer assembly editor.

    If you do not select this option, the wizard prompts only for required information. You must complete the configuration of the business objects using the assembly editor.

  6. To create business objects to run the user-defined database queries, select Create a query business object to build user-defined Select statements and then type the number of query business objects you want to create. In the Query Properties window, specify only the number of query business objects you want to create; the wizard prompts for the name and other details about the business objects at a later time.

    You can user-defined queries for various business requirements such as to track the interface status of the Oracle open interface table. The interface status ensures if the data transferred from the interface tables to the base tables is successful. The error code stored in the interface status column helps in troubleshooting any failure in data transfer.

  7. Click OK to save your changes to the database query.

  8. In the Find Objects in the Enterprise System window, click Run Query to use the query to discover database objects and to create a template for query business objects. The result of running a typical query is shown in the following figure.

    The Discovered objects pane lists the database objects that were discovered.

  9. In the Discovered objects list, click + (the plus sign) to expand a schema node and then expand Tables, Views, Stored Procedures, and Synonyms - Nicknames nodes beneath it, to see the database objects discovered by the wizard, or search a subset of each object type by using filtering.

    To limit the number of objects displayed for a particular object type, highlight a node but do not expand it. Click the Filtering icon. Use the question mark or underscore (? or _) character to match a single character, and the asterisk or percentage sign (* or %) to match multiple characters. Only object types, such as table or view, which start with that string or match that pattern are displayed under the node.

  10. Click + (the plus sign) to expand the node for Query Statements to display the template for query business objects.

The wizard displays the database objects you can access using the adapter and business object template for query business objects.


Continue working in the external service wizard. The next step is to select the objects you want to use in your module, configure each business object, and create hierarchies of business objects.



Next topic: Selecting and configuring business objects


Related concepts:

RetrieveAll operation

Query business object overview

Feedback


Selecting and configuring business objects

Use the list of database objects discovered by the external service wizard, and the query object templates you specified, continue using the wizard to select the database objects that you need to access in your module. Then provide the configuration information for your new business objects. The Find Objects in the Enterprise System window allows you to select and configure objects in any order, with the exception that you must select and configure a parent table before you can select and configure its child tables. Aside from this restriction, you have the flexibility to add objects individually or to add them several at a time. You can mix objects from the various nodes of the Discovered objects list. For example, you can select several table objects, a stored procedure object, and a Query statement, and add and configure them at the same time.

The high-level flow of selecting and configuring business objects is as follows:

  1. Select one or more objects in the Discovered objects list of the Find Objects in the Enterprise System window.

  2. Click the > (Add) button.
  3. The wizard opens the Set the Configuration Properties for 'object' window.

    • If you select a single object, a single Set the Configuration Properties for 'object' window is displayed.

      Complete that window, specifying the user-configurable attributes and other information the wizard cannot discover by examining the database, and click OK to save the configuration.

    • If you select multiple objects, the Set the Configuration Properties for 'object' window displays with one page for each object selected.

      Click the name of each object in turn. The window displays the same information you would see had you selected this object individually.

      Do not click OK until you complete the configuration pages for all the objects. The wizard does not close the notebook until you provide all the required fields, but you can close the window before providing optional fields. If you do not configure the optional fields in the wizard, use the business object editor to configure them after exiting the wizard.

  4. The wizard adds the configured object to the Selected objects list.

As long as you do not exit from the wizard, you can work iteratively to select and configure the business objects you need in your module. However, before starting the wizard to add objects to an existing module, understand the requirements of the program that uses the business objects carefully. The wizard overwrites the existing business objects in the same path.



Previous topic: Discovering database objects


Next topic: Set global properties for operations

Feedback nicknames for outbound processing, WebSphere Adapter for Oracle E-Business Suite


Selecting and configuring tables, views, and synonyms or nicknames for outbound processing

Select and configure business objects for tables, views, and synonyms or nicknames to be used in your module. For inbound processing, the selected business objects are delivered in events.

To perform this task, you need to understand the structure of the data in the database, and know what database objects the module needs to access. Specifically, you need to know the following information:

This task is performed through the external service wizard. Start in the Find Objects in the Enterprise System window and then work in a Set the Configuration Properties for 'object' window that is specific to the business object you are configuring.

  1. In the Discovered objects list of the Find Objects in the Enterprise System window, select one or more tables, views, or synonyms from the Discovered objects list, and click the > (Add) button to add the object or objects to the Selected objects list. Alternatively, you can also filter the tables, views, or synonyms by specifying a valid name or pattern for at least one of the filter fields in the Filter Properties window.

    1. Click the object you want to filter, and then click the (Create or edit filter.) button, at the top of the Discovered objects pane.

    2. In the Filter Properties window, type a name or pattern in the Object name or pattern field. Use the question mark or underscore (? or _) to match a single character, and the asterisk or percentage (* or %) to match multiple characters. The name is not case-sensitive.

    3. Click OK. The object that matches the defined filter condition is displayed.

    4. Select one or more objects from the discovered list, and click the > (Add) button to add the object to the Selected objects list.

    The following two figures show a typical Set the Configuration Properties for 'object' window for a table, view, synonym, or nickname business object. The first figure shows a typical window for the first table or group of tables that are selected.

    The following figure shows a typical window for subsequent tables you select. After you select and configure at least one table, the Set the Configuration Properties for 'object' window for subsequent tables displays an area where you can optionally define a parent-child hierarchy between tables.

    As you configure the object, choices that require advanced configuration might present additional fields in this window, causing the window to scroll. Ensure that you examine all the fields on the window before clicking OK.

  2. If the table has a column used to indicate logical deletes:

    1. Select the column name in the Name of the column used to perform logical deletes field.

    2. In the Value used to indicate a deleted object field, type the value that indicates that a row is logically deleted. You can get this value from the database administrator.

  3. If the Select primary key for table table_name area is displayed, click Add, select the column to be used as the primary key for the table business object, and then click OK. If the table has a composite key, you can select multiple columns. The Select primary key for table table_name area is displayed only when the database table does not have a column designated as the primary key. Each table business object must have a primary key, even if the associated database table does not have a key. If the primary key is defined in the database, this section of the window is not displayed.

  4. Optional: Define a parent-child relationship between business objects.

    To build a parent-child hierarchy, configure the parent table first, and return to the Find Objects in the Enterprise System window to select and configure the child tables.

    Configure the parent-child relationship using the area of the Set the Configuration Properties for 'object' window shown in the following figure. These fields are not displayed for the first table you configure.

    1. In the Choose parent table field, select the name of the parent table you are configuring. If you do not see the parent table in the list, the parent table has not yet been configured. Go back and configure the parent object before configuring the child objects.

    2. Set the cardinality of the relationship:

      • If the table has a single-cardinality relationship with the parent table, select the Single cardinality check box. In a single cardinality relationship, a parent can have only one child business object of this type. A single-cardinality relationship can be used with ownership to represent a true child or without ownership to represent lookup tables or other peer objects in a database.

      • If the table has a multiple-cardinality relationship, do not select the Single cardinality check box. In a multiple-cardinality relationship, a parent can have an array of child business objects of this type.

    3. Build the foreign key relationship between the parent and child by specifying for each child column whether it is a foreign key in the parent table.

      • If the child column is not a foreign key, select NONE.

      • If a child column is a foreign key, select the column in the parent table corresponding to the child column.

        The wizard can configure only a single parent table. If the child table has multiple parent tables, use the business object editor to configure the remaining parent tables after exiting the wizard.

    4. If the parent object owns the child object, then the child objects are deleted when the parent is deleted. To indicate that this child is owned by its parent, select the Parent object owns child object (cascade delete) check box. Otherwise, clear this option to prevent child objects, such as lookup tables, from being deleted when their parent is deleted.

    5. If you do not want the child objects to be deleted as part of an Update operation, select the Preserves child_table_name when the parent is updated check box.

      When a parent table is updated, the adapter compares the child business objects present in the input with the child business objects returned from the database. By default, the adapter deletes any child objects returned from the database that are not present in the input business object.

    6. By default, you can perform operations on parent business objects without specifying the child business objects. To ensure that a parent business object specifies its child business objects when the parent is submitted for a change, select the Child_table_name required for operations on parent check box.

  5. An operation can be performed using either a standard SQL statement generated by the adapter or using stored procedures or stored functions from the database. To use stored procedures or stored functions:

    1. Click Add.

    2. In the Add window, select the type of the stored procedure you want to run. For each operation, you can select a stored procedure that performs the operation, as well as stored procedures that run before or after the operation. For example, for the Create operation, you can specify any of these stored procedures: CreateSP, BeforeCreateSP, and AfterCreateSP.

      If you configure the table with RetrieveAllSP, ensure that at least one parameter of the stored procedure is a Cursor and the ResultSet ASI for the stored procedure is set to true to avoid the "No resultset found associated with the stored procedure" exception being generated at run time.

    3. Click OK. The Set the Configuration Properties for 'object' window now shows the stored procedure types you selected and expands to display an area where you configure each one. It might be necessary to scroll down to see the new areas.

      In a hierarchical business object, if you want the stored procedure to be performed for each business object in the hierarchy, you must separately associate a stored procedure with the top-level business object and each child business object or an array of business objects. If you associate a stored procedure with the top-level business object but do not associate it with each child business object, then the top-level business object is processed with the stored procedure, but the child business objects are processed using the standard SQL query.

  6. For each stored procedure type that you selected, specify the name of the stored procedure in the database, and then configure the business object.

    1. In the Schema name field, select the name of the schema that contains the stored procedure.

      1. Click Select.

      2. In the Select Value window, select the name of the schema you want to work with.

      3. Click OK.

    2. Set the name of the stored procedure or stored function.

      1. In the Stored procedure name or pattern field, either type the name of the stored procedure or stored function, or type a name pattern. Use the question mark or underscore (? or _ ) to match a single character, and the asterisk or percentage sign (* or %) to match multiple characters.

      2. In the Stored procedure name field, select the name of the procedure you want. If the stored procedure list contains many items, the Select button is displayed next to the Stored procedure name field. Click Select to open the Select window and select the name of the stored procedure or stored function.

      The Set the Configuration Properties for 'object' window expands to provide an area where you configure the stored procedure. The wizard automatically generates the list of parameters by examining the stored procedure in the database.

    3. For each parameter in the stored procedure (on the left), select the table column (on the right) to pass to the stored procedure in that parameter. The following figure shows a portion of the window after a stored procedure has been configured.

  7. To specify the data type mapping for each column in the table:

    1. Click Advanced.

    2. Expand Table columns. For each column in the table, the default data type mapping is displayed. For Oracle databases, if the table contains any complex data type such as an array, structure, nested structure or table, the type name and the child attribute details are also automatically discovered and displayed. The following figure displays the type name and child attribute details of an Oracle table containing complex data types.

    3. Review the mapping and make the required changes.

    If the primary key in a table is of the date or timestamp type, then the object_key in the event_table must be in the 'yyyy-mm-dd hh-mm-ss' format.

  8. When all the fields in the window are completed, click OK to save the configuration of the business object. The table, view, synonym, and nickname business objects you defined are now listed in the Find Objects in the Enterprise System window.
  9. To change the configuration of an object from the Selected objects list, select the object name and then click the (Edit) icon.
  10. When you have selected and configured all business objects that you need, click Next to set global properties and configure wrapper business objects.


Continue working in the Find Objects in the Enterprise System window to select and configure other types of business objects.



Related concepts:

Business object hierarchies

Business objects

Database tables with multiple parent tables


Related tasks:

Selecting and configuring stored procedures and stored functions

Selecting and configuring query business objects


Related reference:

Business object information

Feedback for outbound processing, WebSphere Adapter for Oracle E-Business Suite


Selecting and configuring stored procedures and stored functions

To select and configure business objects that correspond to stored procedures and stored functions in the database, you filter the database objects, and specify the configuration properties for the database object.

To select and configure business objects for stored procedures or stored functions, you require to understand the structure of the data in the database, and know what objects the module requires to access. In particular, you require to know the parameters passed to the stored procedures or stored functions that your module requires to access.

This task is performed through the external service wizard. Start in the Find Objects in the Enterprise System window and then work in a Set the Configuration Properties for 'object' window that is specific to the business object you are configuring.

  1. In the Discovered objects list of the Find Objects in the Enterprise System window, expand the node for the schema that contains the stored procedure or stored function you want to work with.
  2. Filter the stored procedures by specifying a valid name or pattern for at least one of the filter fields in the Filter Properties window.

    1. Click Stored Procedures and then click the (Create or edit filter) button, located at the top of the Discovered objects pane.

    2. In the Filter Properties window, type a name or pattern in the Object name or pattern field. Use the question mark or underscore (? or _ ) to match a single character and the asterisk or percentage (* or %) to match multiple characters. The name is case-sensitive.

    3. In the Catalog name or pattern field, type the name or a pattern. Use the question mark or underscore (? or _ ) to match a single character and the asterisk or percentage (* or %) to match multiple characters.

    4. Click OK. The Stored Procedures node displays all the stored procedures that match the given filter condition.

      WebSphere Adapter for Oracle E-Business Suite distinguishes the original SP/SF from the overloaded ones by a number tag corresponding to an overload sequence in the Oracle database. These corresponding parameters for the selected SP/SF will be added based on the overload sequence.

  3. Select one or more objects from the Stored Procedures list, and click the > (Add) button to add the object to the Selected objects list.

    Stored procedures that are defined in the PL/SQL packages are displayed in the format SPName(PackageName). For example, if the EMP_MGMT package contains the CREATE_DEPT stored procedure, the stored procedure is displayed in the list as CREATE_DEPT(EMP_MGMT). The Set the Configuration Properties for 'object' window lists the attributes of the stored procedure business object, which include the names and data types of the parameters of the stored procedure, and information about the result sets that are returned. If the stored procedure contains any complex data type (such as Array, Object, and Table), the type name and the sub attribute details are also automatically discovered and displayed. If the stored procedure contains the Oracle PL/SQL Record data type, the adapter creates a wrapper package with a wrapper stored procedure which converts the Record data type to Object data type so the Oracle E-Business Suite adapter can support the PL/SQL Record data type.

  4. If the stored procedure returns any result set, make sure the value for the The maximum number of ResultSets returned from the stored procedure field reflects the maximum number expected. The wizard creates the required number of result set business objects to hold the results.

  5. Configure each parameter:

    1. The Data type field displays the data type of the parameter.

    2. In the Sample Value field, type a valid value.

      If the stored procedure or function contains a VArray or an Object attribute with a Date data type, the sample value must be given in a specific format to successfully validate the stored procedure or function. The Date data type can also be mapped to the String data type. Therefore, the format for the sample value depends on the data type to which the Date is mapped. The following table provides the format to be followed for each Date data type mapping.

      Date data type formats

      Data type mapping SP/SF with Date data type VArray/Object in SP/SF with Date data type
      Date to String Format: Day-Month-Year (Example: '01-JAN-0001') Format: Year-Month-Day Hour:Minute:Second.[Millisecond] (Example: '0001-01-01 01:00:00.000000000').
      Date to Date Format:Year-Month-Day (Example: '0001-01-01') Format:Year-Month-Day (Example '0001-01-01')

      • The Year parameter can be specified from a minimum of one digit to a maximum of four digits in all the formats.
      • The Month parameter can be specified from a minimum of one digit to a maximum of two digits in all the formats, except in Date to String mapping of the SP/SF with the Date data type where the Month parameter is specified in three alphabetic characters as specified in the example in the previous table.
      • The Day, Hour, Minute, and Second parameters can be specified from a minimum of one digit to a maximum of two digits in all the formats.
      • The Milliseconds, which is an optional parameter, can be specified from a minimum of one digit to a maximum of nine digits in all the formats.

  6. To validate the syntax of the stored procedure using the sample values, click Validate. The result of the validation is displayed in the Result area.

    Ensure the number of result sets is correct after you validate the syntax of the stored procedure because the Oracle driver does not always return the expected result set information. If the number is not correct after validation, set the correct number, and then click OK to save and close the window. After you close the wizard, you might verify the setting in the MaxNumOfRetRS application-specific parameter for the business object.

    If the Result area displays the Validation failed message, use the error message that is displayed before the Validation failed message, to correct the definition. Ensure the data type of the parameters and the sample values are correct.

    The OracleMetadataDiscovery.log file in the .metadata folder of your workspace contains the additional information about the problem if the logging level includes a WARNING.

    The following window is displayed after a stored procedure has been validated.

    When you see the message Validation was successful, click OK to save the definition of the stored procedure business object.

    If the stored procedure or stored function returns a result set, do not click OK until the validation succeeds. The wizard uses the results returned during validation to create business objects to hold the result. If the stored procedure validation is not successful, the adapter does not return the result set at run time.

  7. To change the configuration of an object from the Selected objects list, select the object name and then click the (Edit) icon.

The business objects you configured for stored procedures and stored functions are listed in the Find Objects in the Enterprise System window.


In the Find Objects in the Enterprise System window, continue to select and configure other types of business objects. When you are finished, click Next to set the global properties.



Related concepts:

Business objects

Database tables with multiple parent tables


Related tasks:

Selecting and configuring tables, views, and synonyms or nicknames for outbound processing

Selecting and configuring query business objects


Related reference:

Business object information

Feedback


Selecting and configuring query business objects

Select and configure query business objects for user-defined SELECT statements for use in your module.

To configure query business objects, you must know the structure of the data in the database, including the tables and views. You require to know the name and data type of the columns that your module requires to access. You must also be able to write the SQL SELECT statements.

This task is performed through the external service wizard. Start in the Find Objects in the Enterprise System window and then work in a Set the Configuration Properties for 'object' window that is specific to the business object you are configuring.

  1. In the Discovered objects list of the Find Objects in the Enterprise System window, expand the Query Statements node. This node contains an object template, named Select Statement n, for each query business object you requested in the Set the Query Properties window. For example, if you specified a count of two query business objects in that window, the Discovered objects list contains two object templates, as illustrated in the following figure.

  2. Select one or more of the object templates and click the > (Add) button to add the objects to the Selected objects list. The following figure displays the Set the Configuration Properties for 'object' window that opens when you click > (Add) for a query business object.

  3. In Name of the business object, type a name for the business object. The name can contain spaces and national language characters.
  4. In Select statement, type the SELECT statement you want to run. Indicate each parameter with a question mark (?). The following sample SELECT statements illustrate the flexibility of the query business object:

    • select * from customer where ccode=?
    • select * from customer where id=? and age=?
    • select * from customer where lname like ?
    • select C.pkey, C.fname, A.city from customer C, address A WHERE (C.pkey = A.custid) AND (C.fname like ?)

    As you type each ?, the window expands to display an area where you define the WHERE clause for that parameter. The following figure displays the Set the Configuration Properties for 'object' window for a query business object that has a single parameter.

  5. In Where clause parameter n, provide information about each parameter in the SELECT statement.

    1. In Parameter type, select the data type of the parameter. For Oracle databases, the adapter does not support the complex types such as array, table, structure, or nested structure as parameters in the query business objects.
    2. In Sample value, type a sample value for the parameter.

    For example, for a parameter corresponding to a column containing the family name of the customer, you might select string as the data type and provide a sample value of Smith.

  6. Click the Validate button to validate the syntax of the select statement using the sample values. Result displays the result of the validation.

    If the Result area displays the Validation failed message, use the error message that is displayed before the Validation failed message, to correct the definition. Ensure the data type of the parameters and the sample values are correct.

    The OracleMetadataDiscovery.log file in the .metadata folder of your workspace contains the additional information about the problem if the logging level includes a WARNING.

  7. To specify the data type mapping for each column in the result set returned by the select statement:

    1. Click Advanced.

    2. Expand Result set returned by the Select statement. For each column in the result set, the default data type mapping is displayed. For Oracle databases, if the query result contains any complex data type, such as an array, structure, nested structure or table, the type name and the child attribute details are also automatically discovered and displayed.
    3. Review the mapping and make the required changes.

  8. Click OK to save the definition of the query business object.

The query business objects you defined are now listed in the Find Objects in the Enterprise System window.


In the Find Objects in the Enterprise System window, continue to select and configure other types of business objects. When you are finished, click Next to set the global properties.



Related concepts:

Query business object overview


Related tasks:

Selecting and configuring tables, views, and synonyms or nicknames for outbound processing

Selecting and configuring stored procedures and stored functions

Feedback


Set global properties for operations

After you select database objects in the external service wizard, you need to specify properties that apply to all business objects.

  1. When the Selected objects list in the Find Objects in the Enterprise System window contains all the business objects you want to use in your application, click Next.

  2. In the Specify Composite Properties window, review the list of operations.

    This window lists all the operations the adapter supports for the outbound services for all business objects that you selected on the previous window. Not all operations are supported by each business object. For example, query business objects support only the RetrieveAll operation. Stored procedure business objects support only the Execute operation.

  3. To remove an operation that you do not need, select the operation name and click Remove. If you change your mind, click Add and restore a removed operation.

  4. Specify how you want to retrieve the records.

    • To have the RetrieveAll operation to return all records matching the query, select the Return all records for RetrieveAll operation check box or enter -1 in the Maximum records for RetrieveAll operation field.

    • To specify the maximum number of records, the RetrieveAll operation must return, enter a value in the Maximum records for RetrieveAll operation field. The default value is 100. For more information about this property, see Maximum records for RetrieveAll operation.

      The Maximum records for RetrieveAll operation property applies only if you are using the RetrieveAll operation. This property field is disabled if you remove the RetrieveAll operation in step 3 or if you select the Return all records for RetrieveAll operation check box.

  5. In Business object namespace, accept the default namespace or type the full name of another namespace.

    The namespace is prefixed to the business object name to keep the business object schemas logically separated.

  6. Optionally, in Folder, type the relative path to the folder where the generated business objects are to be stored.

    If you are creating multiple adapter artifacts within a module, ensure specified different business object folders for each adapter within the module. For example, if you are creating artifacts for Oracle, JDBC, SAP, and JDE within a module, you need to create different relative folders for each of these adapters. If you do not specify different relative folders, the existing artifacts are overwritten when you generate new artifacts.

  7. For a business graph to be created for each business object, click Generate a business graph for each business object. Business graphs are needed only in these situations:

    • If you require to use the ApplyChanges operation
    • When adding business objects to a module created with a version of IBM Integration Designer earlier than version 7.5.0.2.

    You must select this option if you are adding business objects to a module that was created with an earlier version of IBM Integration Designer. Otherwise, you must rewire your interface.

  8. Click Next.

You have provided information that applies to all business objects in the module.


Continue working in the wizard. The next step is to specify deployment information to use at run time and information for saving the service as a module.



Previous topic: Selecting and configuring business objects


Next topic: Set deployment properties and generating the service

Feedback


Set deployment properties and generating the service

After you select and configure the business objects for your module, use the external service wizard to configure properties the adapter uses to connect to a specific database. The wizard creates a new business integration module where all the artifacts and property values are saved. This task is performed through the Set the Service Generation and Deployment Properties and Set the Location Properties windows of the external service wizard.

The connection properties in this task are initialized to the values the wizard used to connect to the database. To configure the module to use other values, change the values here. For example, to use the Oracle JDBC driver at run time instead of the Oracle Thin driver, set the driver information here.

  1. In the Set the Service Generation and Deployment Properties window, click Edit Operations to review the names of the operations or add a description for the operations for the business objects you are creating.

  2. In the Deployment Properties area, specify how you want the adapter to get the user name and password at run time.

    • To use a J2C authentication alias, click Using an existing JAAS alias (recommended) and enter the name of the alias in the J2C authentication data entry field. You can specify an existing authentication alias or create one at any time before deploying the module. The name is case-sensitive and includes the node name.
    • To use the managed connection properties, click Using security properties from the managed connection factory and enter values in the User name and Password fields.
    • To administer the user name and password from another mechanism, click Other.

    If you use local connection information to establish the database connection, a security credential is required. You can select either Using an existing JAAS alias (recommended) or Using security properties from the managed connection factory as the security mechanism. If you use an existing data source on the server, the security credential is not required. In this case, you can select Other as the security mechanism. Also, if you set the J2C authentication data entry field or set the User name and Password fields, they override the user name and password in the data source.

  3. By default, the adapter is configured to join the global transaction. The adapter uses the XA connection for global transaction. You can configure a XA connection by specifying either a predefined XA data source or XA database connection information. For a local transaction, clear the Join the global transaction check box. You can configure a local transaction by specifying either a predefined connection pool data source, local database connection information, predefined XA data source, or XA data source connection information.

    If you select the Join the global transaction check box, the Database connection information list displays only the XA related database connection options. If an artifact from an earlier version contains only the local connection properties and the Join the global transaction check box was selected, after migration, the Database connection information list in the assembly editor displays the option for local database connection.

    If you do not specify a valid connection information for global transaction, the adapter generates the ResourceException.

  4. In the Deploy connector project field, specify whether to include the adapter files in the module. Select one of the following values:

    • With module for use by single application: With the adapter files embedded in the module, you can deploy the module to any application server. Use an embedded adapter when you have a single module using the adapter or if multiple modules need to run different versions of the adapter. Using an embedded adapter enables you to upgrade the adapter in a single module without the risk of destabilizing other modules by changing their adapter version.
    • On server for use by multiple applications: If you do not include the adapter files in a module, install them as a stand-alone adapter on each application server where you want to run the module. Use a stand-alone adapter when multiple modules can use the same version of the adapter and you want to administer the adapter in a central location. A stand-alone adapter can also reduce the resources required by running a single adapter instance for multiple modules.

  5. If you selected On server for use by multiple adapters in the previous step, specify the connection properties used at run time.

    • If you manually created and configured a managed connection factory or activation specification on the server or if you have already deployed an application that connects to the same database using the same managed connection factory or activation specification properties, you can reuse the managed connection factory or activation specification by specifying the name of its Java™ Naming and Directory Interface (JNDI) data source:

      1. From the Connection settings list, select Use predefined connection properties.

      2. In the JNDI Lookup Name field, type the name of the JNDI data source for an existing managed connection factory or activation specification.

        The following figure displays the typical settings for reusing a managed connection factory or activation specification for a stand-alone deployment of the adapter.

      3. Click Next to complete this task.

    • If this is the first application that connects to the database with a specific user name and password, or to administer the user name and password separately from other applications, select Specify connection properties.

  6. In the Connection Properties area, specify how you want the adapter to establish database connection at run time. You can establish connection with the adapter at run time in one of the following ways:

    • To use a predefined XA data source on the server (for XA connection):

      1. Select the Join the global transaction check box.

      2. From the Database connection information list, select Specify predefined XA DataSource.

      3. In the Database system connection information area, enter the value in the XA DataSource JNDI name field. This value must be set to a JNDI data source that supports XA transactions created on the BPM or WebSphere Enterprise Service Bus. For more information about this property, see XA DataSource JNDI name (XADataSourceJNDIName).

    • To specify the connection information to be saved in the adapter properties (for XA connection):

      1. Select the Join the global transaction check box.

      2. From the Database connection information list, select Specify XA database connection information.

      3. In the Database system connection information area, enter values in the XA DataSource name and Database URL fields. For more information about these properties, see Database URL (DatabaseURL) and XA DataSource name (XADataSourceName).

    • To use a predefined connection pool data source (for local connection):

      1. Clear the Join the global transaction check box.

      2. From the Database connection information list, select Specify predefined connection pool DataSource.

      3. In the Database system connection information area, enter the name of the existing JNDI data source in the Connection pool DataSource JNDI name field. For more information about this property, see Connection pool DataSource JNDI name (PoolDataSourceJNDIName).

    • To specify connection information to be saved in the adapter properties (for local connection):

      1. Clear the Join the global transaction check box.

      2. From the Database connection information list, select Specify local database connection information.

      3. In the Database system connection information area, enter values in the Database URL and JDBC driver class name fields. For more information about these properties, see Database URL (DatabaseURL) and JDBC driver class (JDBCDriverClass).

  7. Review and, if necessary, change the values of the required connection properties. The fields are initialized with the connection information you specified when you started the wizard. You can change the values to specify a different user name and password at run time. You can also connect to an alternate Oracle database,although the schema names must be the same in both databases. The format of the connection properties is database-specific. For more information about the properties, see Managed connection factory properties.

  8. Optional: Click Advanced to specify the advanced properties. Expand each of the advanced sections to review the properties.

    • Additional connection configuration

      1. To turn on AUTOCOMMIT for the database, select Set auto commit on database connection. For more information about the property, see Auto commit (AutoCommit).

      2. Set Additional JDBC driver connection properties. For more information about the property, see Additional JDBC driver connection properties [name:value;name:value] (JDBCDriverConnectionProperties).

      3. Set SQL query to verify the connection. For more information about the property, see SQL query to verify the connection (PingQuery).
      4. In Query timeout, type the length of time, in seconds, the adapter must wait for a response to a database query. For more information about the property, see Query timeout (seconds) (QueryTimeOut).

      5. Set Return business object even when the stored procedure result set is empty. For more information about the property, see Return business object even when the stored procedure result set is empty (ReturnDummyBOForSP).

    • Processing methods for illegal XML characters

      1. From the Illegal XML character processing drop-down list, select one of the options that correspond to your requirement:

        • Do not validate illegal XML characters, to work with the default adapter behavior.
        • Throw exception if contents in the BO contains illegal XML characters, to proceed after you get an exception message, and log the illegal XML characters in the trace file, at runtime.
        • Discard all illegal XML characters and related logs, if you want the adapter to discard the illegal XML characters, and log the characters in the trace file, at runtime.

    • Logging and tracing

    • Bidi properties

      • To enable bidirectional support for the adapter at run time, select the Bidi transformation check box.

      • Set the properties, ordering schema, text direction, symmetric swapping, character shaping, and numeric shaping to control how bidirectional transformation is performed.

    • Connection retry settings

  9. Click Next. The Set the Location Properties window is displayed.

  10. In the Set the Location Properties window, specify the name of the module you want to create. This can be a new or existing module.

    • If the module name that you want appears in the Module list, select its name.

      If the module contains an interface or business object with the same name as any you are now configuring, the original interface or business object in the module is replaced by the new version.

    • Otherwise, create a module:

      1. Click New.

      2. In the Select a Business Integration Project Type window, select Create a module project and click Next.

      3. In the Create a Module window, type a name for the module. For example, OracleOutboundModule.

      4. To have the service description files (the .import and .wsdl files) to be in the default folder in the module, leave Use default location selected. To specify a different folder in the module, clear the option and then click Browse to specify a different folder in Location.

      5. To have the module to be automatically opened in the assembly diagram in IBM Integration Designer when the wizard closes, select Open module assembly diagram. Otherwise, clear this option.

      6. Click Finish to create the module.

  11. Set the namespace you want to use for your business artifacts.

    • To have the business objects in the module to use the default derived namespace, leave Use default namespace selected.
    • To specify a different namespace, clear the option and type a different value in Namespace.

  12. Optional: Set the folder within the new module where the service description must be saved. In Folder, type the folder name or browse to an existing folder. If you do not specify a folder name, the artifacts (the import, XSD, and WSDL files) are stored in the root folder of the module, that is, the folder with the module name.

  13. In the Name field, accept the default import name or type a different name.

  14. To save the business objects in a library where they can be used by other modules, select Save business objects to a library and specify the location of the library in the Library field.

  15. Optional: In the Description field, type a descriptive comment about the module.
  16. When you are finished setting properties, click Finish.

  17. If the Model Changed window is displayed, click Yes.

The wizard exits. The module is created in the project and artifacts are generated.


In some instances, you might need to use the assembly editor to complete the configuration. Then you can test or deploy your module.



Previous topic: Set global properties for operations


Next topic: Completing the configuration


Related concepts:

User authentication

Feedback


Completing the configuration

In some situations, manual configuration steps are needed to complete the configuration of your business objects.

Perform this task when you need to customize the artifacts generated by the wizard. You might do this in the following situations:

This topic provides detailed instructions for setting the CopyAttribute parameter to a table business object. Other changes to business object structures can be accomplished using similar techniques.

The CopyAttribute parameter is contained in the properties of the attribute for the column to populate with values and application-specific information from another column. For example, if you want the contact column of a new row in the table to contain the same value as the e-mail column, set the CopyAttribute parameter of the contact attribute to e-mail. You can use the assembly editor in IBM Integration Designer to set the value.

  1. In the Business Integration perspective of IBM Integration Designer, expand the module name, expand Data Type, and then locate the table business object. The business object name is the name of the database schema plus the name of the database table. An optional namespace might be included at the beginning of the name.
  2. Right-click the business object name and select Open. The assembly editor displays the business object, which has a field for each column.

  3. In the assembly editor, select the column you want to set to match another column.

  4. In the Properties view, select Application Info. If the Properties view is not visible, right-click the column name and click Show in Properties.

  5. Expand Oracle ASI schema, and then expand OracleAttributeTypeMetadata.
  6. Right-click OracleAttributeTypeMetadata and then select New > oracleasi:CopyAttribute.

  7. Select the CopyAttribute property.

  8. In the Extension Details area, set the text value to the name of the column that contains the information to copy. The column can be in the current business object or its parent business object. To copy from a column in the current business object, set the value to the column name, for example, phoneid. To copy from a column in the parent business object, prefix the column name with two periods (..), for example, ..phone. The following figure shows the assembly editor with the CopyAttribute property set to a column in the current table.

The business object is configured to use the CopyAttribute property to set the business object attribute and properties for a database column based on information in another column.


You can now test and deploy the module.



Previous topic: Set deployment properties and generating the service

Feedback


Configure the module for inbound processing

To configure a module to use the adapter for inbound processing, use the external service wizard in IBM Integration Designer to find and select business objects and services from the Oracle database, and to generate business object definitions and related artifacts.

  1. Discovering database objects After configuring the connection properties, run a query to search for database objects. Browse through the discovered objects navigation tree to understand the structure of objects in the Oracle database, and use filters to display only the database objects you want to see.
  2. Selecting and configuring business objects Using the list of database objects discovered by the external service wizard, and the query object templates you specified, continue using the wizard to select the database objects that you need to access in your module. Then provide the configuration information for your new business objects.
  3. Set global properties for operations After you have selected database objects in the external service wizard, you need to specify properties that apply to all business objects.
  4. Set deployment properties and generating the service After you select and configure the business objects for your module, use the external service wizard to configure properties the adapter uses to connect to a specific database. The wizard creates a new business integration module where all the artifacts and property values are saved.
  5. Completing the configuration In some situations, manual configuration steps are needed to complete the configuration of your business objects.



Previous topic: Configure the module for outbound processing


Next topic: Configure the module for advanced queue integration


Related concepts:

Business object hierarchies

Inbound processing

Feedback


Discovering database objects

After configuring the connection properties, run a query to search for database objects. Browse through the discovered objects navigation tree to understand the structure of objects in the Oracle database, and use filters to display only the database objects you want to see.

You must know the data requirement of the program that requires to access the database. For example, you need the following information about the database:

This task starts in the Find Objects in the Enterprise System window of the external service wizard.

  1. In the Find Objects in the Enterprise System window, click Edit Query. The Set the Query Properties window is displayed.

    The Create a query business object to build user-defined select statements is available only for outbound processing.

    Use the Set the Query Properties window to perform the following tasks:

    • Reduce the search time by searching a subset of database schemas
    • Omit one or more types of database objects from the search

    • Make the wizard prompt you for application-specific information that cannot be automatically determined based on information in the database
    • Map the Oracle data types Date and Timestamp to date and dateTime

  2. To limit the number of database schemas that are retrieved, type the name of the schema or a name pattern in Schema name or pattern. Use the question mark or underscore (? or _) character to match a single character and the asterisk or percentage sign (* or %) to match multiple characters. Only schemas that start with that string or match that pattern are displayed when you run the query. If you do not specify a schema name pattern, all schemas in the database are displayed. Using a filter can speed up the discovery process if the database contains many schemas.
  3. To omit one or more types of objects from the search, select the types of objects to omit (tables, views, and synonyms or nicknames) in Supported database object types, and then click Remove. If you change your mind, click Add to add the object type back. If the database contains object types that you do not need to access, omitting them can speed up the discovery process.

  4. Select the Prompt for additional configuration settings when adding business object check box. Then, when you add a database object to the list of business objects to create, the wizard automatically prompts you for all user-configurable application-specific information for the object. For example, if you select this option, the wizard guides you through the process of building a simple parent-child hierarchy of business objects. If you need a hierarchy, that a table business object has two attributes referring to attributes in two different tables (that is, it has two parent business objects), complete the configuration in the IBM Integration Designer assembly editor.

    If you do not select this option, the wizard prompts only for required information. You must complete the configuration of the business objects using the assembly editor.

  5. Click OK to save your changes to the query.

  6. In the Find Objects in the Enterprise System window, click Run Query to use the query to discover database objects. The result of running a typical query is shown in the following figure.

    The Discovered objects pane lists the objects that were discovered. The tables, views, and synonyms/nicknames are sorted by schema name.

  7. In the Discovered objects list, click + (the plus sign) to expand a schema node and the Tables, Views, and Synonyms - Nicknames nodes to see the database objects discovered by the wizard.

The wizard has discovered the database objects you can access using the adapter.


Continue working in the external service wizard. The next step is to select the objects you want to use in your module, configure each business object, and create hierarchies of business objects.



Next topic: Selecting and configuring business objects


Related concepts:

RetrieveAll operation

Query business object overview

Feedback


Selecting and configuring business objects

Use the list of database objects discovered by the external service wizard, and the query object templates you specified, continue using the wizard to select the database objects that you need to access in your module. Then provide the configuration information for your new business objects. The Find Objects in the Enterprise System window allows you to select and configure objects in any order, with the single exception that you must select and configure a parent table before you can select and configure its child tables. Apart from this restriction, you have the flexibility to add objects individually or to add them several at a time. You can mix objects from the various nodes of the Discovered objects list. For example, you can select several tables and view objects and a stored procedure object, and add them at the same time.

The high-level flow of selecting and configuring business objects is as follows:

  1. Select one or more objects in the Discovered objects list of the Find Objects in the Enterprise System window.

  2. Click the > (Add) button.
  3. The wizard opens the Set the Configuration Properties for 'object' window.

    • If you select a single object, a single Set the Configuration Properties for 'object' window is displayed.

      Complete that window, specifying the user-configurable attributes and other information the wizard cannot discover by examining the database, and click OK to save the configuration.

    • If you select multiple objects, the Set the Configuration Properties for 'object' window displays with one page for each object selected.

      Click the name of each object in turn. The window displays the same information you would see had you selected this object individually.

      Do not click OK until you complete the configuration pages for all the objects. The wizard does not close the notebook until you provide all the required fields, but you can close the window before providing optional fields. If you do not configure the optional fields in the wizard, use the business object editor to configure them after exiting the wizard.

  4. The wizard adds the configured object to the Selected objects list.

As long as you do not exit from the wizard, you can work iteratively to select and configure the business objects you need in your module. However, before starting the wizard to add objects to an existing module, understand the requirements of the program that uses the business objects carefully. The wizard overwrites the existing business objects in the same path.



Previous topic: Discovering database objects


Next topic: Set global properties for operations

Feedback nicknames for inbound processing, WebSphere Adapter for Oracle E-Business Suite


Selecting and configuring tables, views, and synonyms or nicknames for inbound processing

Select and configure business objects for tables, views, and synonyms or nicknames for use in your module. For inbound processing, the tables, views, and synonyms are the business objects that are delivered in events.

To perform this task, you need to understand the structure of the data in the database, and know what database objects the module needs to access. Specifically, you need to know the following information:

This task is performed through the external service wizard. Start in the Find Objects in the Enterprise System window and then work in a Set the Configuration Properties for 'object' window that is specific to the business object you are configuring.

  1. In the Discovered objects list of the Find Objects in the Enterprise System window, select one or more tables, views, or synonyms. Click the > (Add) button to add the object or objects to the Selected objects list. Alternatively, you can also filter the tables, views, or synonyms by specifying a valid name or pattern for at least one of the filter fields in the Filter Properties window.

    1. Click the object you want to filter, and then click the (Create or edit filter.) button, at the top of the Discovered objects pane.

    2. In the Filter Properties window, type a name or pattern in the Object name or pattern field. Use the question mark or underscore (? or _ ) to match a single character and the asterisk or percentage (* or %) to match multiple characters. The name is not case-sensitive.

    3. Click OK. The object that matches the defined filter condition is displayed.

    4. Select one or more objects from the discovered list, and click the > (Add) button to add the object to the Selected objects list.

    The following two figures show a typical Set the Configuration Properties for 'object' window for a table, view, synonym, or nickname business object.

    The first figure shows a typical window for the first table or group of tables selected.

    The second figure shows a typical window for subsequent tables you select. After you select and configure at least one table, the Set the Configuration Properties for 'object' window for subsequent tables displays an area where you can optionally define a parent-child hierarchy between tables.

    As you configure the object, choices that require advanced configuration might present additional fields in this window, causing the window to scroll. Be sure that you examine all fields on the window before clicking OK.

  2. If the table has a column used to indicate logical deletes:

    1. Select the column name in the Name of the column used to perform logical deletes field.

    2. In the Value used to indicate a deleted object field, type the value that indicates that a row is logically deleted. You can get this value from the database administrator.

  3. If the Select primary key for table table_name area is displayed, click Add, select the column to be used as the primary key for the table business object, and then click OK. If the table has a composite key, you can select multiple columns. The Select primary key for table table_name area is displayed only when the database table does not have a column designated as the primary key. Each table business object must have a primary key, even if the associated database table does not have a key. If the primary key is defined in the database, this section of the window is not displayed.

  4. Optional: Define a parent-child relationship between business objects.

    To build a parent-child hierarchy, configure the parent table first, and return to the Find Objects in the Enterprise System window to select and configure the child tables.

    Configure the parent-child relationship using the area of the Set the Configuration Properties for 'object' window shown in the following figure. These fields are not displayed for the first table you configure.

    1. In the Choose parent table field, select the name of the parent table you are configuring. If you do not see the parent table in the list, the parent table has not yet been configured. Go back and configure the parent object before configuring the child objects.

    2. Set the cardinality of the relationship:

      • If the table has a single-cardinality relationship with the parent table, select the Single cardinality check box. In a single cardinality relationship, a parent can have only one child business object of this type. A single-cardinality relationship can be used with ownership to represent a true child or without ownership to represent lookup tables or other peer objects in a database.

      • If the table has a multiple-cardinality relationship, do not select the Single cardinality check box. In a multiple-cardinality relationship, a parent can have an array of child business objects of this type.

    3. Build the foreign key relationship between the parent and child by specifying for each child column whether it is a foreign key in the parent table.

      • If the child column is not a foreign key, select NONE.

      • If a child column is a foreign key, select the column in the parent table corresponding to the child column.

        The wizard can configure only a single parent table. If the child table has multiple parent tables, use the business object editor to configure the remaining parent tables after exiting the wizard.

    4. If the parent object owns the child object, then the child objects are deleted when the parent is deleted. To indicate that this child is owned by its parent, select the Parent object owns child object (cascade delete) check box. Otherwise, clear this option to prevent child objects, such as lookup tables, from being deleted when their parent is deleted.

    5. If you do not want the child objects to be deleted as part of an Update operation, select the Preserves child_table_name when the parent is updated check box.

      When a parent table is updated, the adapter compares the child business objects present in the input with the child business objects returned from the database. By default, the adapter deletes any child objects returned from the database that are not present in the input business object.

    6. By default, you can perform operations on parent business objects without specifying the child business objects. To ensure that a parent business object specifies its child business objects when the parent is submitted for a change, select the Child_table_name required for operations on parent check box.

  5. An operation can be performed using either a standard SQL statement generated by the adapter or using stored procedures or stored functions from the database. To use stored procedures or stored functions:

    1. Click Add.

    2. In the Add window, select the type of the stored procedure you want to run. For each operation, you can select a stored procedure that performs the operation, as well as stored procedures that run before or after the operation. For example, for the Create operation, you can specify any of these stored procedures: CreateSP, BeforeCreateSP, and AfterCreateSP.

      If you configure the table with RetrieveAllSP, ensure that at least one parameter of the stored procedure is a Cursor and the ResultSet ASI for the stored procedure is set to true to avoid the "No resultset found associated with the stored procedure" exception being generated at run time.

    3. Click OK. The Set the Configuration Properties for 'object' window now shows the stored procedure types you selected and expands to display an area where you configure each one. It might be necessary to scroll down to see the new areas.

      In a hierarchical business object, if you want the stored procedure to be performed for each business object in the hierarchy, you must separately associate a stored procedure with the top-level business object and each child business object or an array of business objects. If you associate a stored procedure with the top-level business object but do not associate it with each child business object, then the top-level business object is processed with the stored procedure, but the child business objects are processed using the standard SQL query.

  6. For each stored procedure type that you selected, specify the name of the stored procedure in the database, and then configure the business object.

    1. In the Schema name field, select the name of the schema that contains the stored procedure.

      1. Click Select.

      2. In the Select Value window, select the name of the schema you want to work with.

      3. Click OK.

    2. Set the name of the stored procedure or stored function.

      1. In the Stored procedure name or pattern field, either type the name of the stored procedure or stored function, or type a name pattern. Use the question mark or underscore (? or _ ) to match a single character, and the asterisk or percentage sign (* or %) to match multiple characters.

      2. In the Stored procedure name field, select the name of the procedure you want. If the stored procedure list contains many items, the Select button is displayed next to the Stored procedure name field. Click Select to open the Select window and select the name of the stored procedure or stored function.

      The Set the Configuration Properties for 'object' window expands to provide an area where you configure the stored procedure. The wizard automatically generates the list of parameters by examining the stored procedure in the database.

    3. For each parameter in the stored procedure (on the left), select the table column (on the right) to pass to the stored procedure in that parameter. The following figure shows a portion of the window after a stored procedure has been configured.

  7. To specify the data type mapping for each column in the table:

    1. Click Advanced.

    2. Expand Table columns. For each column in the table, the default data type mapping is displayed. For Oracle databases, if the table contains any complex data type, such as an array, structure, nested structure or table, the type name and the sub attribute details are also automatically discovered and displayed. The following figure displays the type name and sub attribute details of an Oracle table containing complex data types.

    3. Review the mapping and change them if required.

    If the primary key in a table is of the date or timestamp type, then the object_key in the event_table must be in the 'yyyy-mm-dd hh-mm-ss' format.

  8. When all the fields in the window are completed, click OK to save the configuration of the business object. The table, view, synonym, and nickname business objects you defined are now listed in the Find Objects in the Enterprise System window.
  9. To change the configuration of an object from the Selected objects list, select the object name and then click the (Edit) icon.
  10. When you have selected and configured all business objects that you need, click Next to set global properties.


Continue working in the Find Objects in the Enterprise System window to select and configure other types of business objects.



Related concepts:

Business object hierarchies

Feedback


Set global properties for operations

After you have selected database objects in the external service wizard, you need to specify properties that apply to all business objects.

  1. When the Selected objects list in the Find Objects in the Enterprise System window contains all the business objects you want to use in your application, click Next.

  2. In the Specify Composite Properties window, review the list of operations. This list contains the operations the adapter supports for the inbound services. To add to the list of operation includes operations for all business objects you selected on the previous window.

    The specified operations are set for all business objects that are generated.

  3. To remove an operation that you do not need, select the operation name and click Remove. If you change your mind, click Add and restore a removed operation.
  4. In Business object namespace, accept the default namespace or type the full name of another namespace.

    The namespace is prefixed to the business object name to keep the business object schemas logically separated. For more information about this property, see Business object namespace (BusinessObjectNameSpace).

  5. Optionally, in Folder, type the relative path to the folder where the generated business objects are to be stored.

    If you are creating multiple adapter artifacts within a module, ensure specified different business object folders for each adapter within the module. For example, if you are creating artifacts for Oracle, JDBC, SAP, and JDE within a module, you need to create different relative folders for each of these adapters. If you do not specify different relative folders, the existing artifacts are overwritten when you generate new artifacts.

  6. For a business graph to be created for each business object, click Generate a business graph for each business object. Business graphs are needed only when adding business objects to a module created with a version of IBM Integration Designer earlier than version 7.5.0.2.

    You must select this option if you are adding business objects to a module that was created with an earlier version of IBM Integration Designer. Otherwise, you must rewire your interface.

  7. When you are finished, click Next.

You have provided information that applies to all business objects in the module.


Continue working in the wizard. The next step is to specify deployment information to use at run time and information for saving the service as a module.



Previous topic: Selecting and configuring business objects


Next topic: Set deployment properties and generating the service

Feedback


Set deployment properties and generating the service

After you select and configure the business objects for your module, use the external service wizard to configure properties the adapter uses to connect to a specific database. The wizard creates a new business integration module where all the artifacts and property values are saved. This task is performed through the Set the Service Generation and Deployment Properties and Set the Location Properties windows of the external service wizard.

The connection properties in this task are initialized to the values the wizard used to connect to the database. To configure the module to use other values, change the values here. For example, to use the Oracle JDBC driver at run time instead of the Oracle Thin driver, set the driver information here.

  1. In the Set the Service Generation and Deployment Properties window, click Edit Operations to review the names of operations or add a description for the operations for the business objects you are creating.

  2. In the Deployment Properties area, specify how you want the adapter to get the user name and password at run time.

    • To use a J2C authentication alias, click Using an existing JAAS alias (recommended) and enter the name of the alias in the J2C authentication data entry field. You can specify an existing authentication alias or create one at any time before deploying the module. The name is case-sensitive and includes the node name.
    • To use the managed connection properties, click Using security properties from the managed connection factory and enter values in the User name and Password fields.
    • To administer the user name and password from another mechanism, click Other.

    If you use local connection information to establish the database connection, a security credential is required. You can select either Using an existing JAAS alias (recommended) or Using security properties from the managed connection factory as the security mechanism. If you use an existing data source on the server, the security credential is not required. In this case, you can select Other as the security mechanism. Also, if you set the J2C authentication data entry field or set the User name and Password fields, they override the user name and password in the data source.

  3. In the Deploy connector project field, specify whether to include the adapter files in the module. Select one of the following values:

    • With module for use by single application: With the adapter files embedded in the module, you can deploy the module to any application server. Use an embedded adapter when you have a single module using the adapter or if multiple modules need to run different versions of the adapter. Using an embedded adapter enables you to upgrade the adapter in a single module without the risk of destabilizing other modules by changing their adapter version.
    • On server for use by multiple applications: If you do not include the adapter files in a module, install them as a stand-alone adapter on each application server where you want to run the module. Use a stand-alone adapter when multiple modules can use the same version of the adapter and you want to administer the adapter in a central location. A stand-alone adapter can also reduce the resources required by running a single adapter instance for multiple modules.

  4. If you selected On server for use by multiple adapters in the previous step, specify the connection properties used at run time.

    • If you manually created and configured a managed connection factory or activation specification on the server or if you have already deployed an application that connects to the same database using the same managed connection factory or activation specification properties, you can reuse the managed connection factory or activation specification by specifying the name of its Java™ Naming and Directory Interface (JNDI) data source:

      1. From the Connection settings list, select Use predefined connection properties.

      2. In the JNDI Lookup Name field, type the name of the JNDI data source for an existing managed connection factory or activation specification.

        The following figure displays the typical settings for reusing a managed connection factory or activation specification for a stand-alone deployment of the adapter.

      3. Click Next to complete this task.

    • If this is the first application that connects to the database with a specific user name and password, or to administer the user name and password separately from other applications, select Specify connection properties.

  5. In the Connection Properties area, specify how you want the adapter to establish database connection at run time.

    • To use an existing data source on the server:

      1. From the Database connection information list, select Specify predefined DataSource.

      2. In the Database system connection information area, enter the name of an existing JNDI data source in the DataSource JNDI name field. For more information about this property, see Data source JNDI name (DataSourceJNDIName).

    • To specify the connection information to be saved in the adapter properties:

      1. From the Database connection information list, select Specify database connection information.

      2. In the Database system connection information area, enter values in the Database URL and JDBC driver class name fields. For more information about these properties, see Database URL (DatabaseURL) and JDBC driver class (JDBCDriverClass).

  6. Review and, if necessary, change the values of the required connection properties. The fields are initialized with the connection information you specified when you started the wizard. You can change the values to specify a different user name and password at run time. You can also connect to an alternate Oracle database,although the schema names must be the same in both databases. The format of the connection properties is database-specific. For more information about the properties, see Activation specification properties.

  7. Optionally, specify advanced properties by clicking Advanced. Expand each of the advanced sections to review the properties.

    • Processing methods for illegal XML characters

      1. From the Illegal XML character processing drop-down list, select one of the options that correspond to your requirement:

        • Do not validate illegal XML characters, to work with the default adapter behavior.
        • Throw exception if contents in the BO contains illegal XML characters, to proceed after you get an exception message, and log the illegal XML characters in the trace file, at runtime.
        • Discard all illegal XML characters and related logs, if you want the adapter to discard the illegal XML characters, and log the characters in the trace file, at runtime.

    • Event polling configuration

      1. In Interval between polling periods, type the number of milliseconds the adapter waits between polling periods. See Interval between polling periods (PollPeriod).
      2. In Maximum events in polling period, type the number of events to deliver in each polling period. See Maximum events in polling period (PollQuantity).
      3. In Time between retries in case of case of system connection failure (in milliseconds) , type the number of milliseconds to wait before trying to connect after a connection failure during polling. See Time between retries in case of system connection failure (RetryInterval).
      4. In Maximum number of retries in case of system connection failure, type the number of times to retry the connection before reporting a polling error. See Maximum number of retries in case of system connection failure (RetryLimit).

      5. To have the adapter to stop if polling errors occur, select Stop the adapter when an error is encountered while polling. If you do not select this option, the adapter logs an exception but continues to run. See Stop the adapter when an error is encountered while polling (StopPollingOnError).
      6. Select the calendar based scheduling option to create calendar based polling for inbound activities. You can schedule your business activities, when you create a new calendar in IBM Integration Designer. The option of working with the calendar based scheduling feature is only possible with IBM Integration Designer as the tooling environment. The following figure helps you to schedule a calendar polling option.

        Figure 1. Polling based on business calendar

        You can either select a blank calendar or create a new calendar for a module or library.

        When you select a blank calendar, you will not be able to set predefined time intervals. You have to define your time intervals. When you create a calendar using a predefined template, you can define time intervals for each template.

        • To select an existing calendar for a module or library, click Browse. In the Select a Business Calendar window, you can search for existing calendar files (*cal) in the IBM Integration Designer workspace.

          1. In the Filter by name field, type the calendar name or name pattern. The calenders matching the pattern are displayed in the Matching business calendars area.

          2. Select a calendar and click OK to return to the external service wizard.

        • To create a new calendar entry for a module or library, click New. The Create a business calendar window is displayed.

          1. In the Module or library field, click Browse to select an existing calendar module or click New to create a module for the new calendar.

          2. In the Folder field, click Browse to select an existing folder or create a new folder for the calendar.

          3. In the Name field, enter a name for the new calendar.

            • To create a non template calendar, click Finish. Or
            • To generate the calendar based on a predefined template, click Next. In the Use a template window, select the Create a calendar using one of the templates check box and click Finish.

            The new business calendar is created and available in the Business Integration view. Once you complete the wizard, you can view or modify the calendar schedules in the Business Integration view using the Business Calendar Editor. You can modify the intervals and exceptions, or add new entries for these elements. For more details about working with business calendars, see Business calendars.

        You must deploy the Business Calendar module to the same IBM Business Process Manager or WebSphere Enterprise Service Bus instance, along with the inbound application. If you do not map these two connections to the same server instance, the inbound application using the business calendar will by default, poll as there is no calendar configured.

      7. Optionally, you can select Retry EIS connection on startup if you want the adapter to retry a failed connection when starting. See Retry EIS connection on startup (RetryConnectionOnStartup)

    • Event delivery configuration

      1. In Type of delivery, select the delivery method. The methods are described in Delivery type (DeliveryType).

      2. To ensure that events are delivered only once and to only one export, select Ensure once-only delivery. This option might reduce performance but does not result in duplicate or missing event delivery. See Ensure once-only event delivery (AssuredOnceDelivery).
      3. By default, the adapter processes all events that it finds when it polls. If you do not want it to process events that have timestamps later than the current time, select Do not process events that have a timestamp in the future. See Do not process events that have a timestamp in the future (FilterFutureEvents).
      4. In Event types to process, type a comma-separated list of the business objects for which you want events delivered. Leave this field blank to receive events for all business object types.

        For example, to receive events only when the Customer and Order tables, but not other tables, are changed in the database, set this field to Customer,Order.

        See Event types to process (EventTypeFilter).

      5. In Adapter Instance for event filtering, type the connector ID for which you want the events delivered. See Adapter Instance for event filtering (AdapterInstanceEventFilter).
      6. In Retry limit for failed events, specify the number of times to try to deliver an event after a delivery failure. See Retry limit for failed events (FailedEventRetryLimit).

      7. Under Number of connections for event delivery, specify the minimum and maximum number of connections to use to deliver events. See Minimum connections (MinimumConnections) and Maximum connections (MaximumConnections).

    • Additional connection configuration

      1. Set Additional JDBC driver connection properties. See more information about the property in Additional JDBC driver connection properties [name:value;name:value] (JDBCDriverConnectionProperties).

      2. Set SQL query to verify the connection. See more information about the property in SQL query to verify the connection (PingQuery).
      3. In Query timeout, type the length of time, in seconds, the adapter must wait for a response to a database query. See more information about the property in Query timeout (seconds) (QueryTimeOut).

      4. Set Return business object even when the stored procedure result set is empty. See more information about the property in Return business object even when the stored procedure result set is empty (ReturnDummyBOForSP).

    • Event configuration

      1. In Event order by, indicate the order in which events are retrieved and processed. This is a comma-separated list of column names from the event table, plus the keywords that control the sort order for each column. Use asc for ascending order and desc for descending order. See Event order by (EventOrderBy).
      2. In Event table name, accept the default name of the table that contains the event store, or type a different table name. See Event table name (EventTableName).
      3. In Stored procedure to run before poll, the name of a stored procedure or stored function to run before the actual poll query is called. See Stored procedure to run before polling (SPBeforePoll).
      4. In Stored procedure to run after poll, specify the name of a stored procedure or stored function to run after each polling cycle. See Stored procedure to run after polling (SPAfterPoll).
      5. In Event query type for processing events, select the type of event processing you want to use:

        • To use the standard event processing provided by the adapter, select Standard.
        • To provide your own queries to customize event processing, select User-Defined (Dynamic). If you select this option, complete the additional fields described in the following table.

          Field What to specify For more information
          User-defined delete query The name of the query, stored procedure, or stored function that is run after each event is processed to delete records that can be deleted after the event is delivered. User-defined delete query (CustomDeleteQuery)
          User-defined event query The name of the query, stored procedure, or stored function that performs the polling for events. User-defined event query (CustomEventQuery)
          User-defined update query for failed event delivery The name of the query, stored procedure, or stored function that is run when an event is not delivered successfully. User-defined update query for failed event delivery (CustomUpdateQueryForFailedEvent)
          User-defined update query The name of the query, stored procedure, or stored function that is run after each event is processed to prevent the event from being picked up for processing in a subsequent event cycle. User-defined update query (CustomUpdateQuery)

    • Logging and tracing

      1. If you have multiple instances of the adapter, set Adapter ID to a value that is unique for this instance.

      2. To create disguise potentially sensitive user information in log and trace files, select the Disguise user data as “XXX” in log and trace files field.

  8. Click Next.

  9. In the Set the Location Properties window, specify the name of the module you want to create. This can be a new or existing module.

    • If the module name that you want appears in the Module list, select the name.

      If the module contains an interface or business object with the same name as any you are now configuring, the original interface or business object in the module is replaced by the new version.

    • Otherwise, create a module:

      1. Click New.

      2. In the Select a Business Integration Project Type window, select Create a module project and click Next.

      3. In the Create a Module window, type a name for the module. For example, OracleInboundModule.

      4. To have the service description files (the .export and .wsdl files) to be in the default folder in the module, leave Use default location selected. To specify a different folder in the module, clear the option and then click Browse to specify a different folder in Location.

      5. To have the module to be automatically opened in the assembly diagram in IBM Integration Designer when the wizard closes, select Open module assembly diagram. Otherwise, clear this option.

      6. Click Finish to create the module.

  10. Set the namespace you want to use for your business objects.

    • To have the business objects in the module to use the default namespace, leave Use default namespace selected.
    • To specify a different namespace, clear the option and type a different value in Namespace.

  11. Optionally, specify the folder within the new module where the service description must be saved. In Folder, type the folder name or browse to an existing folder. If you do not specify a folder name, the artifacts (the export, XSD, and WSDL files) are stored in the root folder of the module, that is, the folder with the module name.
  12. In Name, accept the default name of the import or type a different name.

  13. Optionally, to save the business objects in a library where they can be used by other modules, select Save business objects to a library and specify the location of the library in Library.

  14. Optionally, in Description, type a descriptive comment about the module.
  15. When you are finished setting properties, click Finish.

  16. If the Model Changed window is displayed, click Yes.

The wizard exits. The module is created in the project and artifacts are generated.


In some instances, you might need to use the assembly editor to complete the configuration. Then you can test or deploy your module.



Previous topic: Set global properties for operations


Next topic: Completing the configuration


Related concepts:

User authentication

Feedback


Completing the configuration

In some situations, manual configuration steps are needed to complete the configuration of your business objects.

Perform this task when you need to customize the artifacts generated by the wizard. You might do this in the following situations:

This topic provides detailed instructions for setting the CopyAttribute parameter to a table business object. Other changes to business object structures can be accomplished using similar techniques.

The CopyAttribute parameter is contained in the properties of the attribute for the column to populate with values and application-specific information from another column. For example, if you want the contact column of a new row in the table to contain the same value as the e-mail column, set the CopyAttribute parameter of the contact attribute to e-mail. You can use the assembly editor in IBM Integration Designer to set the value.

  1. In the Business Integration perspective of IBM Integration Designer, expand the module name, expand Data Type, and then locate the table business object. The business object name is the name of the database schema plus the name of the database table. An optional namespace might be included at the beginning of the name.
  2. Right-click the business object name and select Open. The assembly editor displays the business object, which has a field for each column.

  3. In the assembly editor, select the column you want to set to match another column.

  4. In the Properties view, select Application Info. If the Properties view is not visible, right-click the column name and click Show in Properties.

  5. Expand Oracle ASI schema, and then expand OracleAttributeTypeMetadata.
  6. Right-click OracleAttributeTypeMetadata and then select New > oracleasi:CopyAttribute.

  7. Select the CopyAttribute property.

  8. In the Extension Details area, set the text value to the name of the column that contains the information to copy. The column can be in the current business object or its parent business object. To copy from a column in the current business object, set the value to the column name, for example, phoneid. To copy from a column in the parent business object, prefix the column name with two periods (..), for example, ..phone. The following figure shows the assembly editor with the CopyAttribute property set to a column in the current table.

The business object is configured to use the CopyAttribute property to set the business object attribute and properties for a database column based on information in another column.


You can now test and deploy the module.



Previous topic: Set deployment properties and generating the service

Feedback


Configure the module for advanced queue integration

To configure a module to use the adapter for outbound or inbound processing, use the external service wizard in IBM Integration Designer to create the advanced queue header and payload business objects.

  1. Configure the module for outbound processing To configure the module for the advanced queue interface, use the external service wizard in Integration Designer and create the advanced queue header and payload business object to start outbound at run time.
  2. Configure the module for inbound processing To configure the module for the advanced queue interface, use the external service wizard in Integration Designer and configure the advanced queue to be polled by the adapter inbound at run time.



Previous topic: Configure the module for inbound processing


Next topic: Configure the module for XML Gateway interface for web service

Feedback


Configure the module for outbound processing

To configure the module for the advanced queue interface, use the external service wizard in Integration Designer and create the advanced queue header and payload business object to start outbound at run time.

You must place the required JAR files for the advanced queue interface in a local directory.

This task is to create an outbound integration application using advanced queue interface.

  1. Create a project. For information about how to create a project, see Create the project.

  2. In the Select the Processing Direction window, select Outbound. Click Next.

    The advanced queue interface can be executed only for outbound processing.

  3. In the Set the Discovery Properties window, select Oracle E-Business Suite > Advanced Queue.

  4. Select the Oracle E-Business Suite version, and specify the connection information for the advanced queue interface.

    1. In the System ID field, specify the system ID (SID) to connect to the Oracle E-Business Suite.

    2. In the Host name field, enter the host name or IP address of the system on which Oracle E-Business Suite is installed.

    3. In the Port number field, specify the port number to connect to the Oracle database.

    4. In the User name and Password fields, type the user name and password to connect to the Oracle database.

  5. Click Next.

  6. In the Find Objects in the Enterprise System window, click Edit Query.

  7. In the Set the Query Properties window, specify the schema name or pattern you want to work with.

  8. Click OK to save your changes to the query. In the Find Objects in the Enterprise System window, click Run Query to use the query to discover the objects. The result of running a typical query is shown in the following figure:

    The Discovered objects pane lists the different business service interfaces supported by the adapter.

  9. Select one or more interfaces from the Discovered objects list, and click the > (Add) button to add the interfaces to the Selected objects list. Configure the properties for the Advanced queue header. The business objects for the advanced queue payload is generated with other artifacts. Click OK.

  10. In the Specify Composite Properties window, specify the business object information for the advanced queue interface.

  11. Click Next.

  12. In the Set the Service Generation and Deployment Properties window, select Using an existing JAAS alias (recommended) or Using security properties from the managed connection factory.

  13. In the Set the Location Properties window, select or create a module name, and then click Finish.


You can test or deploy your module.



Next topic: Configure the module for inbound processing


Related concepts:

Dequeue operation

Enqueue operation

Limitations of JMS dequeue mechanism

Advanced Queue integration overview

Feedback


Configure the module for inbound processing

To configure the module for the advanced queue interface, use the external service wizard in Integration Designer and configure the advanced queue to be polled by the adapter inbound at run time.

You must place the required JAR files for the advanced queue interface in a local directory.

This task is to create an inbound application module that integrates to an advanced queue interface.

  1. Create a project. For information about how to create a project, see Create the project.

  2. In the Select the Processing Direction window, select Inbound. Click Next.

  3. In the Set the Discovery Properties window, select Oracle E-Business Suite > Advanced Queue.

  4. Select the Oracle E-Business Suite version, and specify the connection information for the advanced queue interface.

    1. In the System ID field, specify the system ID (SID) to connect to the Oracle E-Business Suite.

    2. In the Host name field, enter the host name or IP address of the system on which Oracle E-Business Suite is installed.

    3. In the Port number field, specify the port number to connect to the Oracle database.

    4. In the User name and Password fields, type the user name and password to connect to the Oracle database.

  5. Click Next.

  6. In the Find Objects in the Enterprise System window, click Edit Query.

  7. In the Set the Query Properties window, specify the schema name or pattern you want to work with.

  8. Click OK to save your changes to the query. In the Find Objects in the Enterprise System window, click Run Query to use the query to discover the objects. The Discovered objects pane lists the different queues supported by the adapter for the dequeue operation. The result of running a typical query is shown in the following figure:

  9. Select the queue from the Discovered objects list, and click the > (Add) button to add the queue to the Selected objects list. Advanced Queue is the source, which the adapter polls to retrieve messages. As an inbound module can poll only one source, you can select only one queue. Click OK.

  10. In the Specify Composite Properties window, specify the information for the dequeue operation.

  11. Click Next.

  12. In the Set the Service Generation and Deployment Properties window, select Using an existing JAAS alias (recommended) or Using security properties from the managed connection factory.

    Properties for Advanced Queue Dequeue Operation:

    1. Required: In the Advanced Queue Consumer Name field, enter the consumer or recipient name based on target messages the adapter polls. Setting the recipient or consumer name is mandatory while enqueuing a message as messages are dequeued based on this name.

    2. Optional: In the Advanced Queue Dequeue Condition field, enter the condition for the dequeue operation. The dequeue condition is specified as a Boolean expression using a syntax similar to the WHERE clause of a SQL query. The dequeue condition parameter cannot exceed 4000 characters.

    3. Optional: In the Advanced Queue Correlation ID field, enter the identifier to group or correlate messages. This identifier is set during the enqueue operation.

    Properties related to staging event table and data source:

    1. From the Dequeue using list, select the dequeue mechanism used for the dequeue operation. If you select PL/SQL, the wrapper stored procedure (<schema>_<queue selected>_WPKG) and the required types are created by default at run time. If you select JMS, ensure that you selected the aqapi.jar file in the Locate the Required Files and Libraries window.

    2. In the Staging event table field, enter the name of the staging table. This table is automatically created during run time.

    3. In the Staging data source JNDI field, enter the name of the JNDI data source used to connect to the staging table.

    For information about other properties in the Set the Service Generation and Deployment Properties window, see Set deployment properties and generating the service.

    In the Advanced Queue Consumer Name field, you can also enter the recipient ID of the consumer or the subscription ID of the subscriber (of AQ). However, if multiple inbound modules using AQ inbound are configured to run on a server, ensure they have different subscription IDs and they use different staging tables. Using a common staging table across different subscribers can result in errors.

  13. In the Set the Location Properties window, select or create a module name, and then click Finish.


You can test or deploy your module.



Previous topic: Configure the module for outbound processing


Related concepts:

Dequeue operation

Enqueue operation

Limitations of JMS dequeue mechanism

Advanced Queue integration overview

Feedback


Configure the module for XML Gateway interface for web service

To configure the module for XML Gateway interface, use the external service wizard in Integration Designer. You can configure this interface only for the outbound integration. You can select the number of interfaces you would want to create. For each interface you create, you can select the required elements as per your business requirement.

You must place the required DTD files for the XML Gateway interface in a local directory. Also, you need to know the root DTD file and the root element for the selected XML Gateway interface.

This task is to create an outbound integration application using XML Gateway interface.

  1. Create a project. For information about how to create a project, see Create the Project.

  2. In the Locate the Required Files and Libraries window, click Next.

    The JDBC driver files must be provided only for connecting to the Oracle database server and for the JDBC-based Oracle interfaces.

  3. In the Select the Processing Direction window, select Outbound. Click Next.

    The XML Gateway interface configuration can be performed only for the Outbound processing.

  4. In the Set the Discovery Properties window, select Oracle E-Business Suite > XML Gateway > Web Service.

    You can select either the Oracle database node or the XML Gateway node and not both, in one EMD process. When you select the XML Gateway node, the Bidi and Advanced properties are not available for selection.

  5. Select the Oracle E-Business Suite version and specify the connection information of the selected XML Gateway interface.

    1. In the Host name field, enter the host name or the IP address of the system on which Oracle E-Business Suite is installed.

    2. In the Port number field, specify the port number for connecting to the Oracle E-Business Suite.
    3. The WSDL URL field displays the URL of the XML Gateway interface. It is generated by the adapter based on the version, host name and port number specified.

    4. In the User name and Password fields, type the user name and password to use to connect to the Oracle E-Business Suite.

  6. Click Next.

  7. In the Find Objects in the Enterprise System window, click Edit Query.

  8. In the Set the Query Properties window, you can work with Oracle seeded XML Gateway interface or custom XML Gateway interface or both. To create a custom XML interface, select the Custom XML Gateway interface check box and then type the number of interfaces to create.

  9. Click OK to save your changes to the query. In the Set the Query Properties window, click Run Query to use the query to discover the objects. The result of running a typical query is shown in the following figure.

    The Discovered objects pane lists the different business service interfaces supported by the adapter.

  10. Select one or more interfaces from the Discovered objects list, and click the > (Add) button to add the interfaces to the Selected objects list.

  11. In the Set the Configuration Properties for 'object' window, specify the DTD information.

    1. In the DTD files directory field, type the path where the DTD files are located or click Browse to search for the location of the files.

    2. From the Root DTD file name list, select the root DTD file name from the list.

    3. From the Root Element list, select a corresponding root element.

  12. Click OK.

  13. In the Find Objects in the Enterprise System window, click Next.

  14. In the Specify Composite Properties window, click Next.

  15. In the Set the Service Generation and Deployment Properties window, select Using an existing JAAS alias(recommended) or Using security properties from the managed connection factory.

  16. Since there is no transaction support for XML Gateway Web Services invoking, clear the Join global transaction check box, and click Next.

  17. In the Set the Location Properties window, select or create a module name, and then click Finish.


You can test or deploy your module.



Previous topic: Configure the module for advanced queue integration


Next topic: Configure the module for XML Gateway interface for JMS

Feedback


Configure the module for XML Gateway interface for JMS

To configure the module for XML Gateway interface for JMS, use the external service wizard in IBM Integration Designer. You can configure this interface only for the outbound integration. You can select the number of interfaces you would want to create. For each interface you create, you can select the required elements as per your business requirement.

You must place the required DTD files for the XML Gateway interface in a local directory. Also, you require to know the root DTD file and the root element for the selected XML Gateway interface.

This task is to create an outbound integration application using XML Gateway interface.

  1. Create a project. For information about how to create a project, see Create the project.

  2. In the Locate the Required Files and Libraries window, select the JAR files used in JMS run time. Click Next.

    The JDBC driver files must be provided only for connecting to the Oracle database server and for the JDBC based Oracle interfaces.

  3. In the Select the Processing Direction window, select Outbound. Click Next.

    The XML Gateway interface configuration can be performed only for the Outbound processing.

  4. In the Set the Discovery Properties window, select Oracle E-Business Suite > XML Gateway > JMS.

    You can select either the Oracle database node or the XML Gateway node but not both, in one EMD process. When you select the XML Gateway node, the Bidi and Advanced properties are not available for selection.

  5. Select the Oracle E-Business Suite version, and specify the connection information of the selected XML Gateway interface.

    1. In the Host name field, enter the host name or IP address of the system on which Oracle E-Business Suite is installed.

    2. In the Port number field, specify the port number to connect to the Oracle E-Business Suite.

    3. In the System ID field, specify the system ID (SID) to connect to the Oracle E-Business Suite.

    4. In the User name and Password fields, type the user name and password to connect to the Oracle E-Business Suite.

  6. For Oracle E-Business Suite V12.1, specify the Integration Repository (IREP) connection information to retrieve the interface metadata.

    1. In the Port number field, specify the port number for connecting to the Integration Repository.

    2. In the User name and Password fields, type the user name and password to connect to the Integration Repository.

  7. Click Next.

  8. In the Find Objects in the Enterprise System window, click Edit Query.

  9. In the Set the Query Properties window, you can work with Oracle seeded XML Gateway interface or custom XML Gateway interface or both. To create a custom XML interface, select the Custom XML Gateway interface check box, and then type the number of interfaces to create.

  10. Click OK, to save your changes to the query. In the Set the Query Properties window, click Run Query to use the query to discover the objects. The result of running a typical query is shown in the following figure.

    The Discovered objects pane lists the different business service interfaces supported by the adapter.

  11. Select one or more interfaces from the Discovered objects list, and click the > (Add) button to add the interfaces to the Selected objects list.

  12. In the Set the Configuration Properties for 'object' window, specify the DTD information.

    1. In the DTD files directory field, type the path where the DTD files are located or click Browse to search for the location of the files.

    2. From the Root DTD file name list, select the root DTD file name from the list.

    3. From the Root Element list, select a corresponding root element.

  13. Click OK.

  14. In the Find Objects in the Enterprise System window, click Next.

  15. In the Specify Composite Properties window, click Next.

  16. In the Set the Service Generation and Deployment Properties window, select Using an existing JAAS alias(recommended) or Using security properties from the managed connection factory.

  17. Clear the Join global transaction check box, as XML Gateway JMS Services does not support any transaction, and click Next.

  18. In the Set the Location Properties window, select or create a module name, and then click Finish.


You can test or deploy your module.



Previous topic: Configure the module for XML Gateway interface for web service

Feedback


Modify artifacts

Often business requirements mandate changes to the backend enterprise information system (EIS) data structures. These changes call for regeneration and reconfiguration of artifacts (import and export) that were previously generated using the external service wizard.

A few business scenarios where the output from one enterprise service discovery flow can be reused in successive flows, are outlined as follows:

To modify existing artifacts, you can invoke the wizard in one of the following ways. The external service wizard is initialized with previously configured settings.

The Edit Binding option is available for artifacts generated using IBM Integration Designer 7.0 only. If you are importing a project interchange from an earlier version of IBM Integration Designer, the Edit Binding option is not available. If you have made any manual changes to the configuration, running the wizard again will overwrite these changes.


Feedback


Modify service import

Modify an import component by rediscovering and reconfiguring the objects using the Edit Binding option in IBM Integration Designer. You can invoke the external service wizard to modify the information of a service import interface. The wizard automatically populates the existing information for the selected import interface. You can modify the objects and services, and then regenerate the import component with the modified data.

  1. Start the external service wizard for the selected service interface import component using one of the following methods.

    • In the assembly editor, select the component you want to modify, right-click and select Edit Binding.

    • In the Business Integration view, select the component you want to modify, right-click and select Edit Binding.

    • Select the interface in the assembly editor and select the Properties view. In the Binding tab, click the Edit link.

    The Find Objects in the Enterprise System window of the external service wizard is displayed. The external service wizard automatically populates the existing configuration details for the selected import interface.

  2. In the Find Objects in the Enterprise System window, make the required changes. For more information about discovering objects, see Discovering database objects.

    To change the connection properties for the external service wizard, click Back and change the properties in the Set the Discovery Properties window. For more information see, Set connection properties for the external service wizard.

    1. You can select and configure the following objects:

      • To select and configure business objects for tables, views, and synonyms or nicknames for use in your module, see Selecting and configuring tables, views, and synonyms or nicknames for outbound processing.

        If a table selected during the previous enterprise service discovery is deleted in the database, the adapter generates the Object not found exception.

      • To select and configure business objects corresponding to stored procedures and stored functions in the database, see Selecting and configuring stored procedures and stored functions.

        If the stored procedure definition in the database is changed, you must reconfigure the stored procedure and ensure that validation is successful.

        Ensure the sequence number of specific overloaded SP/SF is not changed when you make changes in the database. If you remove or insert an overloaded SP/SF before the selected SP/SF, the artifacts are either overwritten or made redundant during the edit binding operation.

      • To select and configure query business objects, see Selecting and configuring query business objects.

    2. To modify the configuration of an object from the Selected objects list, select the object name and then click the (Edit) icon.
    3. To remove an object from the Selected objects list, select the object name and then click the (Remove) button.

  3. Click Next. If you click Cancel, the changes you made in the previous step does not take effect.

  4. In the Specify Composite Properties window, specify properties that apply to all business objects. See Set global properties for operations.

  5. Click Next.

  6. In the Service Generation window, modify the service operations if required.

  7. Click Finish. The artifacts are regenerated.

    If the service export interface to modify contains a Java™ component added to it, ensure the Java component is regenerated manually in Integration Designer after completing the regeneration of the artifacts to resolve the Java component exception.

  8. Complete any other required manual configuration. See Completing the configuration.

The artifacts are regenerated.


You can test and deploy your module.


Feedback


Modify service export

Modify an export component by rediscovering and reconfiguring the objects using the Edit Binding option in IBM Integration Designer. You can invoke the external service wizard to modify the information of a service export interface. The wizard automatically populates the existing information for the selected export interface. You can modify the objects and services, and then regenerate the export component with the modified data.

  1. Start the external service wizard for the selected service interface export component using one of the following methods.

    • In the assembly editor, select the component you want to modify, right-click and select Edit Binding.

    • In the Business Integration view, select the component you want to modify, right-click and select Edit Binding.

    • Select the interface in the assembly editor and select the Properties view. In the Binding tab, click the Edit link.

    The Find Objects in the Enterprise System window of the external service wizard is displayed. The external service wizard automatically populates the existing configuration details for the selected export interface.

  2. In the Find Objects in the Enterprise System window, make the required changes. For more information about discovering objects, see Discovering database objects.

    To change the connection properties for the external service wizard, click Back and change the properties in the Set the Discovery Properties window. See Set connection properties for the external service wizard.

    1. You can select and configure the following objects:

      Ensure the sequence number of specific overloaded SP/SF is not changed when you make changes in the database. If you remove or insert an overloaded SP/SF before the selected SP/SF, the artifacts are either overwritten or made redundant during the edit binding operation.

    2. To modify the configuration of an object from the Selected objects list, select the object name and then click the (Edit) icon.
    3. To remove an object from the Selected objects list, select the object name and then click the (Remove) button.

  3. Click Next. If you click Cancel, the changes you made in the previous step does not take effect.

  4. In the Specify Composite Properties window, specify properties that apply to all business objects. See Set global properties for operations.

  5. Click Next.

  6. In the Service Generation window, modify the service operations if required.

  7. Click Finish. The artifacts are regenerated.

    If the service export interface to modify contains a Java™ component added to it, ensure the Java component is regenerated manually in Integration Designer after completing the regeneration of the artifacts to resolve the Java component exception.

  8. Complete any other required manual configuration. See Completing the configuration.

    In advanced queue inbound, when you modify the artifacts by adding a queue to the selection, make the following changes to the export file so the new values reflect in the activation specification after the application is deployed:

    1. Open the export file and manually update the values for the <queueName> and <schemaName> properties with the new value.
    2. Redeploy the application.

The artifacts are regenerated.


You can test and deploy your module.


Feedback


Change interaction specification properties

To change interaction specification properties for your adapter module after generating the service, use the assembly editor in IBM Integration Designer.

You must have used the external service wizard to generate a service for the adapter.

You might want to change interaction specification properties after you have generated a service for the adapter. Interaction specification properties, which are optional, are set at the method level, for a specific operation on a specific business object. The values you specify appear as defaults in all parent business objects generated by the external service wizard. You can change these properties before you export the EAR file. You cannot change these properties after you deploy the application.

To change the interaction specification properties, use the following procedure:

  1. From the Business Integration perspective of IBM Integration Designer, expand the module name.

  2. Expand Assembly Diagram and double-click the interface.

  3. Click the interface in the assembly editor. The module properties are displayed.

  4. Click the Properties tab. You can also right-click the interface in the assembly diagram and click Show in Properties.

  5. Under Binding, click Method bindings. The methods for the interface are displayed, one for each combination of business object and operation.

  6. Select the method whose interaction specification property you want to change.
  7. Change the property in the Generic tab. Repeat this step for each method whose interaction specification property you want to change.

The interaction specification properties associated with your adapter module are changed.


Deploy the module.



Related reference:

Interaction specification properties

Feedback


Deploy the module

Deploy a module to place the files that make up your module and adapter into an operational environment for production or testing. In IBM Integration Designer, the integrated test environment features runtime support for BPM or WebSphere Enterprise Service Bus, or both, depending on the test environment profiles that you selected during installation.


Feedback


Deployment environments

There are test and production environments into which you can deploy modules and adapters.

In IBM Integration Designer, you can deploy your modules to one or more servers in the test environment. This is typically the most common practice for running and testing business integration modules. However, you can also export modules for server deployment on IBM Business Process Manager or WebSphere Enterprise Service Bus as EAR files using the administrative console or command-line tools.


Feedback


Deploy the module for testing

In IBM Integration Designer, you can deploy a module that includes an embedded adapter to the test environment and work with server tools that enable you to perform such tasks as editing server configurations, starting, and stopping servers and testing the module code for errors. The testing is generally performed on the interface operations of your components, which enables you to determine whether the components are correctly implemented and the references are correctly wired.

  1. Add external software dependencies Dependent JARs have to be added to the libraries directory or packaged in the EAR.
  2. Generating and wiring a target component for testing inbound processing Before deploying to the test environment a module that includes an adapter for inbound processing, you must first generate and wire a target component. This target component serves as the destination to which the adapter sends events.
  3. Prepare to test outbound operations Before you can test your module outbound processing with the IBM Integration Designer test client, you might need to modify some of your business objects.
  4. Add the module to the server In IBM Integration Designer, you can add modules to one or more servers in the test environment.
  5. Testing the module for outbound processing using the test client Test the assembled module and adapter for outbound processing using the IBM Integration Designer integration test client.


Feedback


Add external software dependencies

Dependent JARs have to be added to the libraries directory or packaged in the EAR. The JARs are set in the class path and these dependent libraries have to be made available for run time when the module is deployed. There are two ways to make the dependent libraries available, one for either stand-alone deployment or embedded deployment and the other for embedded deployment only.



Next topic: Generating and wiring a target component for testing inbound processing

Feedback


Add external software dependencies on the server

The adapter needs certain files installed on IBM Business Process Manager or WebSphere Enterprise Service Bus server to be able to communicate with the Oracle database.

To obtain the required files and copy them to IBM Business Process Manager or WebSphere Enterprise Service Bus, use the following procedure. An adapter needs the Oracle JDBC driver-specific files to be able to communicate with it.

  1. Obtain the Oracle JDBC driver-specific files or native libraries for the database software and operating system from the database administrator or from the database software Website

    The following table lists the Oracle JDBC driver files needed for Oracle database software.

    Oracle JDBC driver files for Oracle database software

    Database software Driver JDBC driver files Native System Libraries
    Oracle Thin driver ojdbc6.jar or ojdbc14.jar depending on the JRE version None

    The Java Runtime Environment (JRE) version required by the Oracle JDBC driver must not be higher than the JRE version in the runtime environment. For example, if the JRE version is 1.5 in the runtime environment, then the Oracle JDBC Driver should be "ojdbc14.jar" which supports both Java Development Kit (JDK) 1.4 and JDK 1.5; if the JRE version is 1.6 in the runtime environment, then the Oracle JDBC Driver should be "ojdbc6.jar" which supports JDK version 1.6.

  2. Copy the files to the server.

    • In a testing environment in IBM Integration Designer, copy the files to the ${WAS_INSTALL_ROOT}/runtimes/bi_v7/lib/ext directory.
    • In a production environment, copy the files to the ${WAS_INSTALL_ROOT}/lib/ext directory of IBM Business Process Manager or WebSphere Enterprise Service Bus.




Next topic: Install the RAR file (for modules using stand-alone adapters only)


Related tasks:

Add external software dependencies

Feedback


Add external software dependencies when the adapter is bundled

You must copy the dependent JAR files to the EAR application before you can run your adapter applications. You must use this method only for embedded deployment.

To obtain the required files and copy them to the EAR application, use the following procedure:

  1. From the appropriate module, go to the workspace and copy the JAR files to the directory. For example if the name of the module is ModuleName, then go to the workspace and copy the JAR files to the ModuleNameApp/EarContent directory.

  2. Modify the adapter RAR's manifest file, manifest.mf, with the list of JAR files required by the adapter. Add the JAR files in the following format: Class-Path: dependantjar1.jar, dependantjar2.jar.
  3. Copy the native libraries to the run time bin directory and deploy the application.

The vendor software libraries are now a part of your run time environment.


Feedback


Generating and wiring a target component for testing inbound processing

Before deploying to the test environment a module that includes an adapter for inbound processing, you must first generate and wire a target component. This target component serves as the destination to which the adapter sends events.

You must have generated an export module, using the external service wizard.

Generating and wiring a target component for inbound processing is required in a testing environment only. It is not necessary when deploying the adapter in a production environment.

The target component receives events. You wire the export to the target component (connecting the two components) using the assembly editor in IBM Integration Designer. The adapter uses the wire to pass event data (from the export to the target component).

  1. Create the target component.

    1. From the Business Integration perspective of IBM Integration Designer, expand Assembly Diagram and double-click the export component. If you did not change the default value, the name of the export component is the name of your adapter + InboundInterface.

      An interface specifies the operations that can be called and the data that is passed, such as input arguments, returned values, and exceptions. The InboundInterface contains the operations required by the adapter to support inbound processing and is created when you run the external service wizard.

    2. Create a new component by expanding Components, selecting Untyped Component, and dragging the component to the Assembly Diagram.

      The cursor changes to the placement icon.

    3. Click the component to have it displayed in the Assembly Diagram.

  2. Wire the components.

    1. Click and drag the export component to the new component.

      Save the assembly diagram. Click File > Save.

  3. Generate an implementation for the new component.

    1. Right-click on the new component and select Generate Implementation > Java.

    2. Select (default package) and click OK. This creates an endpoint for the inbound module.

      The Java™ implementation is displayed in a separate tab.

    3. Optional: Add print statements to print the data object received at the endpoint for each of the endpoint methods.

    4. Click File > Save to save the changes.


Continue deploying the module for testing.



Previous topic: Add external software dependencies


Next topic: Prepare to test outbound operations

Feedback


Prepare to test outbound operations

Before you can test your module outbound processing with the IBM Integration Designer test client, you might need to modify some of your business objects.

This step is performed in the IBM Integration Designer test client. Open IBM Integration Designer it from the Business Integration perspective by right-clicking the name of your project and then clicking Test > Test Module.



Previous topic: Generating and wiring a target component for testing inbound processing


Next topic: Add the module to the server

Feedback


Add the module to the server

In IBM Integration Designer, you can add modules to one or more servers in the test environment.

If the module you are testing uses an adapter to perform inbound processing, generate and wire a target component to which the adapter sends the events.

In order to test your module and its use of the adapter, you need to add the module to the server.

  1. Conditional: If there are no servers in the Servers view, add and define a new server by performing the following steps:

    1. Place your cursor in the Servers view, right-click, and select New > Server.

    2. From the Define a New Server window, select the server type.

    3. Configure servers settings.

    4. Click Finish to publish the server.

  2. Add the module to the server.

    1. Switch to the servers view. In IBM Integration Designer, select Windows > Show View > Servers.

    1. Start the server. In the Servers tab in the lower-right pane of the IBM Integration Designer screen, right-click the server and then select Start.

  3. When the server status is Started, right-click the server and select Add and Remove Projects.

  4. In the Add and Remove Projects screen, select your project and click Add. The project moves from the Available projects list to the Configured projects list.

  5. Click Finish. This deploys the module on the server.

    The Console tab in the lower-right pane displays a log while the module is being added to the server.


Test the functionality of your module and the adapter.



Previous topic: Prepare to test outbound operations


Next topic: Testing the module for outbound processing using the test client

Feedback


Testing the module for outbound processing using the test client

Test the assembled module and adapter for outbound processing using the IBM Integration Designer integration test client.

You need to add the module to the server first.

Testing a module is performed on the interface operations of your components, which enables you to determine whether the components are correctly implemented and the references are correctly wired.

  1. Select the module you want to test, right-click on it, and select Test > Test Module.
  2. Follow the instructions for Testing modules and components at the Related tasks link of this topic.


If you are satisfied with the results of testing your module and adapter, you can deploy the module and adapter to the production environment.



Previous topic: Add the module to the server


Related tasks:

Testing modules and components in WebSphere Integration Developer

Feedback


Deploy the module for production

Deploy a module created with the external service wizard to IBM Business Process Manager or WebSphere Enterprise Service Bus in a production environment is a two-step process. First, you export the module in IBM Integration Designer as an enterprise archive (EAR) file. Second, you deploy the EAR file using the BPM or WebSphere Enterprise Service Bus administrative console.

  1. Add external software dependencies on the server The adapter needs certain files installed on IBM Business Process Manager or WebSphere Enterprise Service Bus server to be able to communicate with the Oracle database.
  2. Install the RAR file (for modules using stand-alone adapters only) If you chose not to embed the adapter with your module, but instead choose to make the adapter available to all deployed applications in the server instance, you need to install the adapter in the form of a RAR file to the application server. A RAR file is a Java™ archive (JAR) file used to package a resource adapter for the Java EE Connector Architecture (JCA).
  3. Export the module as an EAR file Using IBM Integration Designer, export your module as an EAR file. By creating an EAR file, you capture all of the contents of your module in a format that can be easily deployed to IBM Business Process Manager or WebSphere Enterprise Service Bus.
  4. Install the EAR file Installing the EAR file is the last step of the deployment process. When you install the EAR file on the server and run it, the adapter, which is embedded as part of the EAR file, runs as part of the installed application.



Previous topic: Configure the module for deployment


Next topic: Administer the adapter module

Feedback


Install the RAR file (for modules using stand-alone adapters only)

If you chose not to embed the adapter with your module, but instead choose to make the adapter available to all deployed applications in the server instance, you need to install the adapter in the form of a RAR file to the application server. A RAR file is a Java™ archive (JAR) file used to package a resource adapter for the Java EE Connector Architecture (JCA).

You must set Deploy connector project to On server for use by multiple adapters in the Set the Service Generation and Deployment Properties window of the external service wizard.

Install the adapter in the form of a RAR file results in the adapter being available to all Java EE application components running in the server run time.

  1. If the server is not running, right-click your server in the Servers view and select Start.
  2. When the server status changes to Started, right-click the server and select Administration > Run administrative console.
  3. Log on to the administrative console.

  4. Click Resources > Resource Adapters > Resource adapters.

  5. In the Resource adapters page, click Install RAR.

    Figure 1. The Install RAR button on the Resource adapters page

  6. In the Install RAR file page, click Browse and navigate to the RAR file for your adapter.

    The RAR files are typically installed in the following path: IID_installation_directory/ResourceAdapters/adapter_name/adapter.rar

  7. Click Next.

  8. Optional: In the Resource adapters page, change the name of the adapter and add a description.

  9. Click OK.

  10. Click Save in the Messages box at the top of the page.


The next step is to export the module as an EAR file that you can deploy on the server.



Previous topic: Add external software dependencies on the server


Next topic: Export the module as an EAR file

Feedback


Export the module as an EAR file

Use IBM Integration Designer, export your module as an EAR file. By creating an EAR file, you capture all of the contents of your module in a format that can be easily deployed to IBM Business Process Manager or WebSphere Enterprise Service Bus.

Before you can export a module as an EAR file, you must have created a module to communicate with your service. The module should be displayed in the IBM Integration Designer Business Integration perspective.

To export the module as an EAR file, perform the following procedure.

  1. Right-click the module and select Export.

  2. In the Select window, expand Java EE.

  3. Select EAR file and click Next.

  4. Optional: Select the correct EAR application. The EAR application is named after your module, but with "App" added to the end of the name.
  5. Browse for the folder on the local file system where the EAR file will be placed.

  6. To export the source files, select the Export source files check box. This option is provided in case you want to export the source files in addition to the EAR file. Source files include files associated with Java™ components, data maps, and so on.

  7. To overwrite an existing file, click Overwrite existing file.

  8. Click Finish.

The contents of the module are exported as an EAR file.


Install the module in the administrative console. This deploys the module to IBM Business Process Manager or WebSphere Enterprise Service Bus.



Previous topic: Install the RAR file (for modules using stand-alone adapters only)


Next topic: Install the EAR file


Related tasks:

Install the EAR file

Feedback


Install the EAR file

Install the EAR file is the last step of the deployment process. When you install the EAR file on the server and run it, the adapter, which is embedded as part of the EAR file, runs as part of the installed application.

You must have exported your module as an EAR file before you can install it on IBM Business Process Manager or WebSphere Enterprise Service Bus.

To install the EAR file, perform the following procedure. For more information about clustering adapter module applications, see the http://www.ibm.com/software/webservers/appserv/was/library/.

  1. If the server is not running, right-click your server in the Servers view and select Start.
  2. When the server status changes to Started, right-click the server and select Administration > Run administrative console.
  3. Log on to the administrative console.

  4. Click Applications > New Application > New Enterprise Application.

    Figure 1. Preparing for the application installation window

  5. Click Browse to locate your EAR file and click Next. The EAR file name is the name of the module followed by "App."

  6. If you are deploying to a clustered environment.

    1. On the Step 2: Map modules to servers window, select the module and click Next.

    2. Select the name of the server cluster.

    3. Click Apply.

  7. Click Next. In the Summary page, verify the settings and click Finish.

  8. If you are using an authentication alias:

    1. Expand Security and select Business Integration Security.

    2. Select the authentication alias to configure. You must have administrator or operator rights to change the authentication alias configurations.

    3. If it is not already specified, type the User name.

    4. If it is not already specified, type the Password.

    5. If it is not already specified, type the password again in the Confirm Password field.

    6. Click OK.

The project is now deployed and the Enterprise Applications window is displayed.


To set or reset any properties or you would like to cluster adapter project applications, make those changes using the administrative console before configuring troubleshooting tools.



Previous topic: Export the module as an EAR file


Related tasks:

Create the project

Export the module as an EAR file

Feedback

Deploy the module in a clustered environment

In IBM Integration Designer, you can deploy the IBM WebSphere Adapter for Oracle E-Business Suite in a clustered environment.

To deploy the module in a clustered environment, use any of the following approaches.


Feedback


Deploy module embedded in the application

The adapter is deployed embedded in the application and specific to it. The adapter cannot be shared between multiple applications.

The following steps are a necessary prerequisite to configure and deploy the module.

To create an application with the embedded adapter, use the external service wizard.

  1. In the Service Configuration Properties window, from the Deploy connector project property list, select With module for use by single application.

  2. Create the module as described in the Business process management samples for WebSphere Adapters.

  3. In the Dependencies option for the module, after the module is created, ensure the Deploy with module option is selected for the adapter.

  4. If the server is not running, right-click your server in the Servers view and select Start.
  5. When the server status changes to Started, right-click the server and select Administration > Run administrative console.

  6. From the Deployment Manager Admin Console, click Install applications to deploy the application.

  7. On the Step 2: Map modules to servers window, select the module and click Next. For the embedded adapter option, the adapter is deployed as part of the application.

  8. In the Enterprise Applications view, select the new application <adapter_name>EmbeddedModuleApp. The new application is displayed after the application is deployed at the deployment manager level.

  9. Select the node and click Installed applications to view the deployed application on each individual node.

The resource adapter is embedded and deployed as part of the application.


Feedback


Deploy module at node level with embedded activation specification

The adapter is deployed at the node level, with the activation specification created during module creation. The adapter can be shared across multiple applications.

The following steps are a necessary prerequisite to configure and deploy the module.

To create an application with the node level adapter and activation specification properties specified in the module itself, use the external service wizard.

  1. In the Service Configuration Properties window, from the Deploy connector project property list, select On server for use by multiple applications.

  2. From the Connection properties list, select Use properties below.

  3. Create the module as described in the Business process management samples for WebSphere Adapters.

  4. In the Dependencies option for the module, ensure the Deploy with module option is not selected for the adapter. Here, the adapter is not part of the module, therefore you must deploy the adapter before deploying the application.

  5. If the server is not running, right-click your server in the Servers view and select Start.
  6. When the server status changes to Started, right-click the server and select Administration > Run administrative console. Log on to the administrative console.
  7. To deploy the adapter at individual nodes, click Resources > Resource Adapters > Resource adapters. In the clustered environment, install the adapter in each node separately.

  8. In the Resource adapters page, click Install RAR.

  9. In the Install RAR file page, click Browse and navigate to the RAR file for your adapter. Deploy the RAR on each node.

    The RAR files are typically installed in the following path: IID_installation_directory/ResourceAdapters/adapter_name/adapter.rar

  10. For deployment at node level, do not select any Scope because the scope is always Node. Click Next.

  11. Optional: In the Resource adapters page, change the name of the adapter and add a description. Click OK.

  12. Click Save in the Messages box at the top of the page.

  13. For node level deployment, check if the adapter RAR is deployed at the node level.
  14. To deploy the adapter at the cluster level, click Resources > Resource Adapters > Resource adapters.

  15. In the Resource adapters window, set the Scope to Cluster, and then click New.

  16. Select the RAR deployed at the node level.
  17. Check if the adapter RAR is now deployed at the cluster level. Deploy the application after the adapter is deployed at the node level on the individual nodes, and then at the cluster level.

  18. From the Deployment Manager Admin Console, click Install applications to deploy the application.

  19. On the Step 2: Map modules to servers window, select the module and click Next. The adapter is not part of the deployed application.

  20. In the Admin Console, click Resources > Resource Adapters > IBM WebSphere Adapter for Oracle > J2C activation specifications to view the activation specification from the adapter deployed at the cluster level.

The resource adapter is deployed at the node level, with the activation specification.


Feedback


Deploy module at node level with JNDI activation specification

The adapter is deployed at the node level, and the application provides a JNDI reference to the activation specification. Create the activation specification with the same JNDI name at the cluster scope from the administrative console. The adapter can be shared across multiple applications

The following steps are a necessary prerequisite to configure and deploy the module.

To create an application with the node level adapter and activation specification properties specified in the module itself, use the external service wizard.

  1. In the Service Configuration Properties window, from the Deploy connector project property list, select On server for use by multiple applications.

  2. From the Connection properties list, select Use JNDI lookup name configured on server.

  3. In the JNDI lookup name property field, specify the JNDI name. Use this same JNDI name when you create the activation specification from the Admin Console.

  4. Create the module as described in the Business process management samples for WebSphere Adapters.

  5. In the Dependencies option for the module, ensure the Deploy with module option is not selected for the adapter.

  6. If the server is not running, right-click your server in the Servers view and select Start.
  7. When the server status changes to Started, right-click the server and select Administration > Run administrative console. Log on to the administrative console.
  8. To install the adapter at the node level, click Resources > Resource Adapters > Resource adapters. In the clustered environment, install the adapter in each node separately.

  9. In the Resource adapters page, click Install RAR.

  10. In the Install RAR file page, click Browse and navigate to the RAR file for your adapter. Deploy the RAR on each node.

    The RAR files are typically installed in the following path: IID_installation_directory/ResourceAdapters/adapter_name/adapter.rar

  11. For deployment at node level, do not select any Scope because the scope is always Node. Click Next.

  12. Optional: In the Resource adapters page, change the name of the adapter and add a description. Click OK.

  13. Click Save in the Messages box at the top of the page.
  14. To install the RAR at the cluster level, click Resources > Resource Adapters > Resource adapters

  15. In the Resource adapters page, set the Scope to Cluster, and then click New.

  16. Select the RAR deployed at the node level, and then check if the adapter RAR is now deployed at the cluster level. Deploy the application after the adapter is deployed at the node level on the individual nodes, and then at the cluster level.

  17. From the Deployment Manager Admin Console, click Install applications to deploy the application.

  18. In the Admin Console, click Resources > Resource Adapters > IBM WebSphere Adapter for Oracle > J2C activation specifications > New to create the activation specification from the adapter deployed at the cluster level.
  19. When installing the adapter, in the Name field, enter the same name as defined in the RAR.

  20. In the JNDI name field, enter the same name as given during the module creation.

  21. Click Resources > Resource Adapters > IBM WebSphere Adapter for Oracle > J2C activation specifications to check if the JNDI reference on the adapter is same as the one specified for the module.

  22. Click Resources > Resource Adapters > IBM WebSphere Adapter for Oracle > J2C activation specifications > Custom properties to set values for the activation specification in the Admin Console.

  23. From the Deployment Manager Admin console, click Install applications to deploy the application after you deploy the RAR and create the activation specification.

  24. On the Step 2: Map modules to servers page, select the module and click Next. The adapter is not part of the deployed application.

The resource adapter is deployed at the node level, with the JNDI activation specification reference.


Feedback


Administer the adapter module

When you are running the adapter in a stand-alone deployment, use the administrative console of the server to start, stop, monitor, and troubleshoot the adapter module. In an application that uses an embedded adapter, the adapter module starts or stops when the application is started or stopped.



Previous topic: Deploy the module for production

Feedback


Configure logging and tracing

Configure logging and tracing to suit your requirements. Enable logging for the adapter to control the status of event processing. Change the adapter log and trace file names to separate them from other log and trace files.


Feedback


Configure logging properties

Use the administrative console to enable logging and to set the output properties for a log, including the location, level of detail, and output format of the log. Before the adapters can log monitored events, you must specify the service component event points to monitor, what level of detail you require for each event, and format of the output used to publish the events to the logs. Use the administrative console to perform the following tasks:

For more information about monitoring on a Process Server, including service components and event points, see http://publib.boulder.ibm.com/infocenter/dmndhelp/v7r5m1/topic/com.ibm.wbpm.admin.doc/topics/welcome_wps_mon.html.

You can change the log configuration statically or dynamically. Static configuration takes effect when you start or restart the application server. Dynamic or run time configuration changes apply immediately.

When a log is created, the detail level for that log is set from the configuration data. If no configuration data is available for a particular log name, the level for that log is obtained from the parent of the log. If no configuration data exists for the parent log, the parent of that log is checked, and so on, up the tree, until a log with a non-null level value is found. When you change the level of a log, the change is propagated to the child logs, which recursively propagate the change to their child log, as necessary.

To enable logging and set the output properties for a log, use the following procedure.

  1. In the navigation pane of the administrative console, select Servers > WebSphere application servers.

  2. Click the name of the server to work with.

  3. Under Troubleshooting, click Logging and tracing.

  4. Click Change log detail levels.

  5. Specify when you want the change to take effect:

    • For a static change to the configuration, click the Configuration tab.

    • For a dynamic change to the configuration, click the Runtime tab.

  6. Click the names of the packages whose logging level you want to modify. The package names for WebSphere Adapters start with com.ibm.j2ca.*:

    • For the adapter base component, select com.ibm.j2ca.base.*.

    • For the adapter base component and all deployed adapters, select com.ibm.j2ca.*.

    • For the core component that is common between WebSphere Adapter for JDBC and WebSphere Adapter for Oracle E-Business Suite, select the com.ibm.j2ca.dbadapter.core.*

    • For the WebSphere Adapter for Oracle E-Business Suite only, select the com.ibm.j2ca.oracleebs.* package.

  7. Select the logging level.

    Logging Level Description
    Fatal The task cannot continue or the component cannot function.
    Severe The task cannot continue, but the component can still function. This logging level also includes conditions that indicate an impending fatal error, that is, situations that strongly suggest that resources are on the verge of being depleted.
    Warning A potential error has occurred or a severe error is impending. This logging level also includes conditions that indicate a progressive failure, for example, the potential leaking of resources.
    Audit A significant event has occurred that affects the server state or resources.
    Info The task is running. This logging level includes general information outlining the overall progress of a task.
    Config The status of a configuration is reported or a configuration change has occurred.
    Detail The subtask is running. This logging level includes general information detailing the progress of a subtask.

  8. Click Apply.

  9. Click OK.

  10. To have static configuration changes take effect, stop and then restart the Process Server.

Log entries from this point forward contain the specified level of information for the selected adapter components.


Feedback


Change the log and trace file names

To keep the adapter log and trace information separate from other processes, use the administrative console to change the file names. By default, log and trace information for processes and applications on a Process Server is written to the SystemOut.log and trace.log files.

You can change the log and trace file names at any time after the adapter module has been deployed to an application server. You can change the log and trace file names statically or dynamically. Static changes take effect when you start or restart the application server. Dynamic or run time changes apply immediately.

Log and trace files are in the install_root/profiles/profile_name/logs/server_name folder.

To set or change the log and trace file names, use the following procedure.

  1. In the navigation pane of the administrative console, select Applications >Application Types>WebSphere enterprise applications.

  2. In the Enterprise Applications list, click the name of the adapter application. This is the name of the EAR file for the adapter, but without the ear file extension. For example, if the EAR file is named Accounting_OutboundApp.ear, then click Accounting_OutboundApp.

  3. In the Configuration tab, select Modules>Manage Modules.

  4. In the list of modules, click IBM WebSphere Adapter for Oracle.

  5. In the Configuration tab, under Additional Properties, click Resource Adapter.

  6. In the Configuration tab, under Additional Properties, click Custom properties.

  7. In the Custom Properties table, change the file names.

    1. Click either logFilename to change the name of the log file or traceFilename to change the name of the trace file.

    2. In the Configuration tab, type the new name in the Value field. By default, the log file is called SystemOut.log and the trace file is called trace.log.

    3. Click Apply or OK. Your changes are saved on your local machine.
    4. To save your changes to the master configuration on the server, use one of the following procedures:

      • Static change: Stop and restart the server. This method allows you to make changes, but those changes do not take effect until you stop and start the server.
      • Dynamic change: Click the Save link in the Messages box above the Custom properties table. Click Save again when prompted.


Feedback


Change configuration properties for embedded adapters

To change the configuration properties after you deploy the adapter as part of a module, use the administrative console of the runtime environment. You can update resource adapter properties (used for general adapter operation), managed connection factory properties (used for outbound processing), and activation specification properties (used for inbound processing). For information about configuring logging properties and changing the log and trace file names, see Configure logging and tracing.


Feedback


Set resource adapter properties for embedded adapters

To set resource adapter properties for your adapter after it has been deployed as part of a module, use the administrative console. You select the name of the property you want to configure and then change or set the value.

Your adapter module must be deployed on IBM Business Process Manager or WebSphere Enterprise Service Bus.

Custom properties are default configuration properties shared by all IBM WebSphere Adapters.

To configure properties using the administrative console, use the following procedure:

  1. If the server is not running, right-click your server in the Servers view and select Start.
  2. When the server status changes to Started, right-click the server and select Administration > Run administrative console.
  3. Log on to the administrative console.

  4. Select Applications > Application Types > WebSphere enterprise application.

  5. From the Enterprise Applications list, click the name of the adapter module whose properties you want to change. The Configuration page is displayed.

    Figure 1. The Manage Modules selection in the Configuration tab

  6. Under Modules, click Manage Modules.

  7. Click IBM WebSphere Adapter for Oracle.

  8. From the Additional Properties list, click Resource Adapter.

  9. On the next page, from the Additional Properties list, click Custom properties.

  10. For each property you want to change.

    See Resource adapter properties for more information about these properties.

    1. Click the name of the property.

      The Configuration page for the selected property is displayed.

    2. Change the contents of the Value field or type a value, if the field is empty.

    3. Click OK.

  11. In the Messages area, click Save.

The resource adapter properties associated with your adapter module are changed.



Related tasks:

Set managed (J2C) connection factory properties for embedded adapters

Set activation specification properties for embedded adapters


Related reference:

Resource adapter properties

Feedback


Set managed (J2C) connection factory properties for embedded adapters

To set managed connection factory properties for your adapter after it has been deployed as part of a module, use the administrative console. You select the name of the property you want to configure and then change or set the value.

Your adapter module must be deployed on IBM Business Process Manager or WebSphere Enterprise Service Bus.

You use managed connection factory properties to configure the target Oracle database instance.

In the administrative console, the properties are referred to as "J2C connection factory properties."

To configure properties using the administrative console, use the following procedure.

  1. If the server is not running, right-click your server in the Servers view and select Start.
  2. When the server status changes to Started, right-click the server and select Administration > Run administrative console.
  3. Log on to the administrative console.

  4. Select Applications > Application Types > WebSphere enterprise application.

  5. In the Enterprise Applications list, click the name of the adapter module whose properties you want to change.

    Figure 1. The Manage Modules selection in the Configuration tab

  6. Under Modules, click Manage Modules.

  7. Click IBM WebSphere Adapter for Oracle.

  8. In the Additional Properties list, click Resource Adapter.

  9. On the next page, from the Additional Properties list, click J2C connection factories.

  10. Click the name of the connection factory associated with your adapter module.

  11. In the Additional Properties list, click Custom properties.

    Custom properties are those J2C connection factory properties that are unique to IBM WebSphere Adapter for Oracle E-Business Suite. Connection pool and advanced connection factory properties are properties you configure if you are developing your own adapter.

  12. For each property you want to change.

    See Managed connection factory properties for more information about these properties.

    1. Click the name of the property.
    2. Change the contents of the Value field or type a value, if the field is empty.

    3. Click OK.

  13. In the Messages area, click Save.

The managed connection factory properties associated with your adapter module are changed.



Related tasks:

Set resource adapter properties for embedded adapters

Set activation specification properties for embedded adapters


Related reference:

Managed connection factory properties

Feedback


Set activation specification properties for embedded adapters

To set activation specification properties for your adapter after it has been deployed as part of a module, use the administrative console. You select the name of the message endpoint property you want to configure, and then change or set the value.

Your adapter module must be deployed on IBM Business Process Manager or WebSphere Enterprise Service Bus.

You use activation specification properties to configure the endpoint for inbound processing.

To configure properties using the administrative console, use the following procedure.

  1. If the server is not running, right-click your server in the Servers view and select Start.
  2. When the server status changes to Started, right-click the server and select Administration > Run administrative console.
  3. Log on to the administrative console.

  4. Select Applications > Application Types > WebSphere enterprise application.

  5. From the Enterprise Applications list, click the name of the adapter module whose properties you want to change.

    Figure 1. The Manage Modules selection in the Configuration tab

  6. Under Modules, click Manage Modules.

  7. Click IBM WebSphere Adapter for Oracle.

  8. From the Additional Properties list, click Resource Adapter.

  9. On the next page, from the Additional Properties list, click J2C activation specifications.

  10. Click the name of the activation specification associated with the adapter module.

  11. From the Additional Properties list, click J2C activation specification custom properties.

  12. For each property you want to change.

    See Activation specification properties for more information about these properties.

    1. Click the name of the property.
    2. Change the contents of the Value field or type a value, if the field is empty.

    3. Click OK.

  13. In the Messages area, click Save.

The activation specification properties associated with your adapter module are changed.



Related tasks:

Set resource adapter properties for embedded adapters

Set managed (J2C) connection factory properties for embedded adapters


Related reference:

Activation specification properties

Feedback


Change configuration properties for stand-alone adapters

To set configuration properties after you install a stand-alone adapter, use the administrative console of the runtime environment. Provide the general information about the adapter and then set the resource adapter properties (which are used for general adapter operation). If the adapter is used for outbound operations, create a connection factory and then set the properties for it. If the adapter is used for inbound operations, create an activation specification and then set the properties for it. For information about configuring logging properties and changing the log and trace file names, see Configure logging and tracing.


Feedback


Set resource adapter properties for stand-alone adapters

To set resource adapter properties for your stand-alone adapter after it has been installed on IBM Business Process Manager or WebSphere Enterprise Service Bus, use the administrative console. You select the name of the property you want to configure and then change or set the value.

Your adapter must be installed on IBM Business Process Manager or WebSphere Enterprise Service Bus.

Custom properties are default configuration properties shared by all IBM WebSphere Adapters.

To configure properties using the administrative console, use the following procedure:

  1. If the server is not running, right-click your server in the Servers view and select Start.
  2. When the server status changes to Started, right-click the server and select Administration > Run administrative console.
  3. Log on to the administrative console.

  4. Click Resources > Resource Adapters > Resource adapters.

  5. In the Resource adapters page, click IBM WebSphere Adapter for Oracle.

  6. In the Additional Properties list, click Custom properties.

  7. For each property you want to change.

    See Resource adapter properties for more information about these properties.

    1. Click the name of the property.
    2. Change the contents of the Value field or type a value, if the field is empty.

    3. Click OK.

  8. In the Messages area, click Save.

The resource adapter properties associated with your adapter are changed.



Related reference:

Resource adapter properties

Feedback


Set managed (J2C) connection factory properties for stand-alone adapters

To set managed connection factory properties for your stand-alone adapter after it has been installed on IBM Business Process Manager or WebSphere Enterprise Service Bus, use the administrative console. You select the name of the property you want to configure and then change or set the value.

Your adapter must be installed on IBM Business Process Manager or WebSphere Enterprise Service Bus.

You use managed connection factory properties to configure the target Oracle database instance.

In the administrative console, the properties are referred to as "J2C connection factory properties."

To configure properties using the administrative console, use the following procedure:

  1. If the server is not running, right-click your server in the Servers view and select Start.
  2. When the server status changes to Started, right-click the server and select Administration > Run administrative console.
  3. Log on to the administrative console.

  4. Click Resources > Resource Adapters > Resource adapters.

  5. In the Resource adapters page, click IBM WebSphere Adapter for Oracle.

  6. In the Additional Properties list, click J2C connection factories.

  7. To use an existing connection factory, skip ahead to select from the list of existing connection factories.

    If you have selected Specify connection properties when use the external service wizard to configure the adapter module, you do not need to create a connection factory.

    If you are creating a connection factory, perform the following steps:

    1. Click New.

    2. In the General Properties section of the Configuration tab, type a name for the connection factory. For example, you can type AdapterCF.
    3. Type a value for JNDI name. For example, you can type com/eis/AdapterCF.

    4. Optional: Select an authentication alias from the Component-managed authentication alias list.

    5. Click OK.

    6. In the Messages area, click Save.

      The newly created connection factory is displayed.

      Figure 1. User-defined connection factories for use with the resource adapter

  8. In the list of connection factories, click the one you want to use.

  9. In the Additional Properties list, click Custom properties.

    Custom properties are those J2C connection factory properties that are unique to WebSphere Adapter for Oracle E-Business Suite. Connection pool and advanced connection factory properties are properties you configure if you are developing your own adapter.

  10. For each property you want to change.

    See Managed connection factory properties for more information about these properties.

    1. Click the name of the property.
    2. Change the contents of the Value field or type a value, if the field is empty.

    3. Click OK.

  11. After you have finished setting properties, click Apply.

  12. In the Messages area, click Save.

The managed connection factory properties associated with your adapter are set.



Related reference:

Managed connection factory properties

Feedback


Set activation specification properties for stand-alone adapters

To set activation specification properties for your stand-alone adapter after it has been installed on IBM Business Process Manager or WebSphere Enterprise Service Bus, use the administrative console. You select the name of the message endpoint property you want to configure, and then change or set the value.

Your adapter must be installed on IBM Business Process Manager or WebSphere Enterprise Service Bus.

You use activation specification properties to configure the endpoint for inbound processing.

To configure properties using the administrative console, use the following procedure.

  1. If the server is not running, right-click your server in the Servers view and select Start.
  2. When the server status changes to Started, right-click the server and select Administration > Run administrative console.
  3. Log on to the administrative console.

  4. Click Resources > Resource Adapters > Resource adapters.

  5. In the Resource adapters page, click IBM WebSphere Adapter for Oracle.

  6. In the Additional Properties list, click J2C activation specifications.

  7. To use an existing activation specification, skip ahead to select from an existing list of activation specifications.

    If you have selected Use predefined connection properties when use the external service wizard to configure the adapter module, create an activation specification.

    If you are creating an activation specification.

    1. Click New.

    2. In the General Properties section of the Configuration tab, type a name for the activation specification. For example, you can type AdapterAS.
    3. Type a value for JNDI name. For example, you can type com/eis/AdapterAS.

    4. Optional: Select an authentication alias from the Authentication alias list.

    5. Select a message listener type.

    6. Click OK.

    7. Click Save in the Messages box at the top of the page.

      The newly created activation specification is displayed.

  8. In the list of activation specifications, click the one you want to use.

  9. In the Additional Properties list, click J2C activation specification custom properties.

  10. For each property you want to set.

    See Activation specification properties for more information about these properties.

    1. Click the name of the property.
    2. Change the contents of the Value field or type a value, if the field is empty.

    3. Click OK.

  11. After you have finished setting properties, click Apply.

  12. In the Messages area, click Save.

The activation specification properties associated with your adapter are set.



Related reference:

Activation specification properties

Feedback


Start the application that uses the adapter

Use the administrative console of the server to start an application that uses the adapter. By default, the application starts automatically when the server starts.

Use this procedure to start the application, whether it is using an embedded or a stand-alone adapter. For an application that uses an embedded adapter, the adapter starts when the application starts. For an application that uses a stand-alone adapter, the adapter starts when the application server starts.

  1. If the server is not running, right-click your server in the Servers view and select Start.
  2. When the server status changes to Started, right-click the server and select Administration > Run administrative console.
  3. Log on to the administrative console.

  4. Click Applications > Application Types > WebSphere enterprise applications.

    The administrative console is labeled "Integrated Solutions Console".

  5. Select the application to start. The application name is the name of the EAR file you installed, without the .EAR file extension.

  6. Click Start.

The status of the application changes to Started, and a message stating the application has started displays at the top of the administrative console.



Related tasks:

Stop the application that uses the adapter

Feedback


Stop the application that uses the adapter

Use the administrative console of the server to stop an application that uses the adapter. By default, the application stops automatically when the server stops.

Use this procedure to stop the application, whether it is using an embedded or a stand-alone adapter. For an application with an embedded adapter, the adapter stops when the application stops. For an application that uses a stand-alone adapter, the adapter stops when the application server stops.

  1. If the server is not running, right-click your server in the Servers view and select Start.
  2. When the server status changes to Started, right-click the server and select Administration > Run administrative console.
  3. Log on to the administrative console.

  4. Click Applications > Application Types > WebSphere enterprise applications.

    The administrative console is labeled "Integrated Solutions Console".

  5. Select the application to stop. The application name is the name of the EAR file you installed, without the .EAR file extension.

  6. Click Stop.

The status of the application changes to Stopped, and a message stating the application has stopped is displayed at the top of the administrative console.



Related tasks:

Start the application that uses the adapter

Feedback


Monitor performance using Performance Monitoring Infrastructure

Performance Monitoring Infrastructure (PMI) is a feature of the administrative console that allows you to dynamically monitor the performance of components in the production environment, including IBM WebSphere Adapter for Oracle E-Business Suite. PMI collects adapter performance data, such as average response time and total number of requests, from various components in the server and organizes the data into a tree structure. You can view the data through the Tivoli Performance Viewer, a graphical monitoring tool that is integrated with the administrative console in BPM or WebSphere Enterprise Service Bus. You can monitor the performance of your adapter by having PMI collect data at the following points:

Before you enable and configure PMI for your adapter, you must first set the level of tracing detail and run some events from which to gather performance data.

To learn more about how PMI can help you monitor and improve the overall performance of your adapter environment, search for PMI on the BPM or WebSphere Enterprise Service Bus website: http://www.ibm.com/software/webservers/appserv/was/library/.

  1. Configure Performance Monitoring Infrastructure You can configure Performance Monitoring Infrastructure (PMI) to gather adapter performance data, such as average response time and total number of requests. After you configure PMI for your adapter, you can monitor the adapter performance using Tivoli Performance viewer.
  2. View performance statistics You can view adapter performance data through the graphical monitoring tool, Tivoli Performance Viewer. Tivoli Performance Viewer is integrated with the administrative console in BPM or WebSphere Enterprise Service Bus.


Feedback


Configure Performance Monitoring Infrastructure

You can configure Performance Monitoring Infrastructure (PMI) to gather adapter performance data, such as average response time and total number of requests. After you configure PMI for your adapter, you can monitor the adapter performance using Tivoli Performance viewer.

Before you can configure PMI for your adapter, you must first set the level of tracing detail and run some events to gather the performance data.

  1. To enable tracing and to receive event data, the trace level must be set to either fine, finer, finest, or all. After *=info, add a colon and a string, for example:
    *=info: WBILocationMonitor.CEI.ResourceAdapter.
    *=finest: WBILocationMonitor.LOG.ResourceAdapter.*=finest:
    For instructions on setting the trace level, see Enable tracing with the Common Event Infrastructure.
  2. Generate at least one outbound request or inbound event to produce performance data that you can configure.

  1. Enable PMI for your adapter.

    1. In the administrative console, expand Monitoring and Tuning, and then select Performance Monitoring Infrastructure (PMI).

    2. From the list of servers, click the name of your server.

    3. Select the Configuration tab, and then select the Enable Performance Monitoring (PMI) check box.

    4. Select Custom to selectively enable or disable statistics.

      Figure 1. Enabling Performance Monitoring Infrastructure

    5. Click Apply or OK.

    6. Click Save. PMI is now enabled.

  2. Configure PMI for your adapter.

    1. In the administrative console, expand Monitoring and Tuning, and then select Performance Monitoring Infrastructure (PMI).

    2. From the list of servers, click the name of your server.

    3. Select Custom.

    4. Select the Runtime tab. The following figure shows the Runtime tab.

      Figure 2. Runtime tab used for configuring PMI

    5. Click WBIStats.RootGroup. This is a PMI sub module for data collected in the root group. This example uses the name WBIStats for the root group.

    6. Click ResourceAdapter. This is a sub module for the data collected for the JCA adapters.

    7. Click the name of your adapter, and select the processes you want to monitor.

    8. In the right pane, select the check boxes for the statistics you want to gather, and then click Enable.

PMI is configured for your adapter.


Now you can view the performance statistics for your adapter.



Next topic: View performance statistics

Feedback Infrastructure (PMI), Tivoli Performance Viewer, IBM WebSphere Adapter for Oracle E-Business Suite


View performance statistics

You can view adapter performance data through the graphical monitoring tool, Tivoli Performance Viewer. Tivoli Performance Viewer is integrated with the administrative console in BPM or WebSphere Enterprise Service Bus.

Configure Performance Monitoring Infrastructure for your adapter.

  1. In the administrative console, expand Monitoring and Tuning, expand Performance Viewer, then select Current Activity.

  2. In the list of servers, click the name of your server.

  3. Under your server name, expand Performance Modules.

  4. Click WBIStatsRootGroup.

  5. Click ResourceAdapter and the name of your adapter module.

  6. If there is more than one process, select the check boxes for the processes whose statistics you want to view.

The statistics are displayed in the right panel. You can click View Graph to view a graph of the data, or View Table to see the statistics in a table format.

The following figure shows adapter performance statistics.

Figure 1. Adapter performance statistics, using graph view



Previous topic: Configure Performance Monitoring Infrastructure

Feedback


Enable tracing with the Common Event Infrastructure

The adapter can use the Common Event Infrastructure (CEI), a component embedded in the server, to report data about critical business events such as the starting or stopping of a poll cycle. Event data can be written to a database or a trace log file depending on configuration settings.

Use this procedure to report CEI entries in the trace log file by using the Common Base Event Browser within the administrative console.

  1. In the administrative console, click Troubleshooting.

  2. Click Logs and Trace.

  3. From the list of servers, click the name of your server.

  4. In the Change Log Detail Levels box, click the name of the CEI database ( WBIEventMonitor.CEI.ResourceAdapter.*) or the trace log file ( WBIEventMonitor.LOG.ResourceAdapter.*) to which you want the adapter to write event data.

  5. Select the level of detail about business events that you want the adapter to write to the database or trace log file, and (optionally) adjust the granularity of detail associated with messages and traces.

    • No Logging. Turns off event logging.
    • Messages Only. The adapter reports an event.
    • All Messages and Traces. The adapter reports details about an event.
    • Message and Trace Levels. Settings for controlling the degree of detail the adapter reports about the business object payload associated with an event. To create adjust the detail level, select one of the following options:

      Fine. The adapter reports the event but none of the business object payload.

      Finer. The adapter reports the event and the business object payload description.

      Finest. The adapter reports the event and the entire business object payload.

  6. Click OK.

Event logging is enabled. You can view CEI entries in the trace log file or by using the Common Base Event Browser within the administrative console.


Feedback


Add dependency libraries to the deployed resource adapter

The deployed resource adapter running in the WebSphere Application Server requires the same dependency libraries as it does in IBM Integration Designer to process requests. The method for adding these library files depends on the mode of the resource adapter deployment: standalone or embedded in the EAR file.


Feedback


Stand-alone deployment

The dependency libraries may be added to the resource adapter deployed stand-alone either during initial deployment of the RAR file or by configuring the Resource Adapter properties after deployment. To set the values during initial deployment of the RAR file, specify Class path and Native path locations. Class path is used to point to JAR files, and Native path is used to point to native libraries, such as *.dll, *.so. To set the dependency library path files after the adapter has been installed on WebSphere Application Server, use the administrative console to modify the values for the Resource Adapter.


Feedback


EAR deployment

For the rare case when the connector needs to be embedded in the EAR file, the dependant libraries are added as shared libraries. Define the appropriate shared library containing software dependency files and associate them with the EAR file.

There are two methods to do this task:


Feedback


Use enhanced EAR editor

You can use the EAR editor in IBM Integration Designer to add the dependency libraries. To shared libraries using the EAR editor, use the following procedure.

  1. Open Enhanced EAR editor.

  2. Click the Deployment tab.

  3. Expand Shared Library section.

  4. Click Add to add new shared library.

  5. Set the shared library parameters and click OK.
  6. Deploy the EAR to the server.

The dependent libraries are added as shared libraries.


Feedback


Use administrative console of the WAS

You can use the administrative console of the BPM or WebSphere Enterprise Service Bus to add the dependency libraries.

Ensure the dependent files are available on the server machine in the separate folder. If needed, copy the dependent files on the server machine.

  1. Define WebSphere variables to point to appropriate folders.
  2. Define the shared library through the server administrative console; you can specify it using WebSphere variables defined in step 1.
  3. Deploy the EAR to the server.

  4. Configure the EAR to reference defined shared library.

The dependent libraries are added as shared libraries.


Feedback


Troubleshooting and support

Common troubleshooting techniques and self-help information help you identify and solve problems quickly. For information about configuring logging properties and changing the log and trace file names, see Configure logging and tracing.


Feedback


Techniques for troubleshooting problems

Certain common techniques can help with the task of troubleshooting.

The first step in the troubleshooting process is to describe the problem completely. Without a problem description, neither you or IBM can know where to start to find the cause of the problem. This step includes asking yourself basic questions, such as:

The answers to these questions typically lead to a good description of the problem, and that is the best way to start down the path of problem resolution.


What are the symptoms of the problem?

When starting to describe a problem, the most obvious question is "What is the problem?" Which might seem like a straightforward question; however, you can break it down into several more-focused questions that create a more descriptive picture of the problem. These questions can include:


Where does the problem occur?

Determining where the problem originates is not always simple, but it is one of the most important steps in resolving a problem. Many layers of technology can exist between the reporting and failing components. Networks, disks, and drivers are only a few components to be considered when you are investigating problems.

The following questions can help you to focus on where the problem occurs in order to isolate the problem layer.

Remember that if one layer reports the problem, the problem does not necessarily originate in that layer. Part of identifying where a problem originates is understanding the environment in which it exists. Take some time to completely describe the problem environment, including the operating system and version, all corresponding software and versions, and hardware information. Confirm that you are running within an environment that is a supported configuration; many problems can be traced back to incompatible levels of software not intended to run together or have not been fully tested together.


When does the problem occur?

Develop a detailed timeline of events leading up to a failure, especially for those cases that are one-time occurrences. You can most simply do this by working backward: Start at the time an error was reported (as precisely as possible, even down to the millisecond), and work backward through the available logs and information. Typically, you need to look only as far as the first suspicious event that you find in a diagnostic log; however, this is not always simple to do and takes practice. Knowing when to stop looking is especially difficult when multiple layers of technology are involved, and when each has its own diagnostic information.

To develop a detailed timeline of events, answer the following questions:

Responding to these types of questions can provide you with a frame of reference in which to investigate the problem.


Under which conditions does the problem occur?

Knowing what other systems and applications are running at the time that a problem occurs is an important part of troubleshooting. These and other questions about the environment can help you to identify the root cause of the problem:

Answering these types of questions can help you explain the environment in which the problem occurs and correlate any dependencies. Remember that just because multiple problems might have occurred around the same time, the problems are not necessarily related.


Can the problem be reproduced?

From a troubleshooting standpoint, the "ideal" problem is one that can be reproduced. Typically with problems that can be reproduced, you have a larger set of tools or procedures at your disposal to help you investigate. Consequently, problems that you can reproduce are often simpler to debug and solve. However, problems that you can reproduce can have a disadvantage: If the problem is of significant business impact, you do not want it to recur! If possible, re-create the problem in a test or development environment, which typically offers you more flexibility and control during your investigation.

Tip: Simplify the scenario to isolate the problem to a suspected component.

The following questions can help you with reproducing the problem:


Feedback


First-failure data capture (FFDC) support

The adapter supports first-failure data capture (FFDC), which provides persistent records of failures and significant software incidents that occur during run time in BPM or WebSphere Enterprise Service Bus.

The FFDC feature runs in the background and collects events and errors that occur at run time. The feature provides a means for associating failures to one another, allowing software to link the effects of a failure to their causes, and facilitate the quick location of the root cause of a failure. The data that is captured can be used to identify exception processing that occurred during the adapter run time.

When a problem occurs, the adapter writes exception messages and context data to a log file, which is in the install_root/profiles/profile/logs/ffdc directory.

For more information about first-failure data capture (FFDC), see the BPM or WebSphere Enterprise Service Bus documentation.


Feedback


Tracing the XML Gateway web Service status

Use Oracle E-Business Suite administration console to find the XML Gateway web Service status.

The messages in return Business Object indicate whether the XML Gateway web Services are started successfully or not. If succeeded, it means the submitted document is received by XML Gateway web Services server side and put into the queue for consequent asynchronous process. To check whether the requests are successfully processed by XML Gateway internal implementation, log on to Oracle E-Business Suite administration console and find out the details in the Transaction Monitor.


Feedback


Resolve namespace conflict in Web Service/JMS interface

When using the Web Service/JMS interface to connect to two different Oracle E-Business Suite servers, if the selected root DTD and the root Element are similar, the generated artifacts will have the same namespace in the top BO, which results in a naming conflict.

To avoid this problem, set a different BO prefix.


Feedback


Resolve connection information lost during EMD

When using different interfaces of WebSphere Adapter for Oracle E-Business Suite and accessing the EMD several times, the connection information may be lost at the Set the Service Generation and Deployment Properties window. For example, when you are configuring the module for the first time, and choose the XML Gateway JMS processing option, to reach the Set the Service Generation and Deployment Properties window, and then go back to the Set the Discovery Properties window, to choose Advanced Queue for processing, and reach the Set the Service Generation and Deployment Properties window again, you may find the "Database URL" is empty, when you choose "Specify XA database connection information" as "Database connection information".

To avoid, choose only one type of interface during the configuration, and not switch between interface options.


Feedback


Disable end point applications of the passive adapter

Problem

In the active-passive configuration mode of the adapters, the endpoint application of the passive adapter instance also listens to the events or messages even if the enableHASupport property is set to True.

Cause

By default, in WebSphere Application Server, the alwaysactivateAllMDBs property in the JMS activation specification is set to True. This enables the endpoint application of all the adapter (active or passive) instances to listen to the events.

Solution

To stop the endpoint application of the passive adapter instance from listening to the events, you must set the alwaysactivateAllMDBs property value to False. The JMS activation specification is associated with one or more MDBs and provides the necessary configuration to receive events. If the alwaysActivateAllMDBs property is set to False, then the endpoint application of only the active adapter instance receives the events.

Perform the following procedure, to set the alwaysActivateAllMDBs property to False.

  1. Log on to the administrative console.
  2. Go to Resources> JMS > Activation specifications.

  3. Click the activation specification corresponding to the application from the list.

  4. Click Custom properties under Additional properties.

  5. Click alwaysActivateAllMDBs.
  6. Change the value to False.

  7. Click Apply and OK.

Result

The endpoint application of only the active adapter instance listens to the events.


Feedback


Limitations of JMS dequeue mechanism

The behavior of the JMS dequeue operation is found to differ based on the version of the aqapi.jar used. The aqapi.jar file from the Oracle database version 11i has stricter validations on the message header during the dequeue operation. Oracle E-Business Suite 12.x has Oracle database of 10g. The aqapi.jar file corresponding to this version seems to have lower restrictions during the dequeue operation. If you notice any dequeue errors with errors from the aqapi driver (JMS-xxx), then it indicates a problem with the driver version used. Recheck the version of aqapi.jar file and use aqapi.jar from the Oracle database 10g version.

Here are the limitations of JMS dequeue mechanism:



Related tasks:

Configure the module for inbound processing

Configure the module for outbound processing

Feedback


Known issues in advanced queue inbound

Problem

During advanced queue inbound processing, involving custom advanced queue, there is a delay experienced while selecting the queue during the enterprise metadata discovery.

Cause

The delay is driver related and it occurs when the DataBaseMetadata getProcedureColumns API is started. A delay of 2 to 10 minutes can be experienced while selecting custom advanced queues during the enterprise metadata discovery.


Feedback


Solutions to common problems

Some of the problems you encounter while running WebSphere Adapter for Oracle E-Business Suite with the database are described, along with solutions and workaround. These problems and solutions are in addition to technotes documented on the software support website.

For a complete list of technotes about WebSphere Adapters, see http://www.ibm.com/support/search.wss?tc=SSMKUK&rs=695&rank=8&dc=DB520+D800+D900+DA900+DA800+DB560&dtm.


RecordNotFoundException for RetrieveAll operation in test client

Problem

When performing a RetrieveAll operation in the IBM Integration Designer test client, the RecordNotFoundException exception is generated when data is expected from the query. The following message is generated: RecordNotFoundException: Record not found in EIS.

Cause

This exception can occur if the WHERE clause for the SELECT statement does not set all the attributes of the business object. Leaving the attribute blank, which is the default value, is not the same as explicitly unsetting the value.

Solution

In the test client, set the values of the attributes required to <unset>. Repeat the RetrieveAll operation. If the exception is generated again, it is likely that no matching records exist in the database table.


CLOB datatypes of 4K or larger cannot be inserted into Oracle 9i or 10g databases

Problem

You get the following exception when inserting CLOB (character large object) values of 4 K and larger into Oracle 9i or 10g databases:

Cause

You are using an older driver that does not correctly support CLOBs larger than 4K.

Solution

Use the Oracle Thin driver from Oracle 10.1.0.2 or a later release.


Some generated business objects have no attributes for Oracle database objects

Problem

For some business objects that are generated from an Oracle database object, the generated business object has no attributes for the table columns.

Cause

Under certain conditions, the Oracle JDBC driver does not return the column information for a database object. The following bugs are currently filed with Oracle for these issues:

Additionally, column information is not returned if a private synonym that references an object in another schema is used.

Solution

For tables that have a synonym, generate the business object using the synonym for the table.

For synonyms of a procedure, generate the business object using the original procedure the synonym is based on.

For private synonyms that reference an object in another schema, either use the original table or create a synonym in the current schema.


ResourceException exceptions during outbound processing

If you get a ResourceException exception, examine the root cause field to determine the cause. Common problems have the following root causes:


ResourceException exception during inbound processing

This exception indicates there is a repeated problem connecting to the database. To polls for events, the adapter must connect top the database. If the connection fails, the adapter waits a configurable amount of time before trying to connect again. The adapter tries a configurable number of times before it stops polling. When the adapter stops polling, it generates the ResourceException exception.


Class loader violation occurs when starting the external service wizard

Problem

It is not possible to use the external service wizard after using a connection to the database in the Data perspective. At the end of the second panel of the wizard, the following exception is generated:

com.ibm.adapter.framework.api.ImportException Reason: class loading constraint violated (class: oracle/jdbc/driver/OracleConnection method: getWrapper()Loracle/jdbc/OracleConnection;) at pc:0

The error occurs in both of the following situations:

Cause

The error occurs because the Data perspective and the wizard use their own class loaders. Once the DLL, which is the native library used by the JDBC driver, is loaded in the Data perspective, it cannot be loaded again in the wizard. JVMs have an inherent restriction that only allows one class loader to load native libraries at any defined time. So if class loader A loads DLL B, then no other class loader can load DLL B until class loader A is released and garbage is collected. Because you cannot really control garbage collection, it typically means that to load DLL B with another class loader, you need to restart the JVM. This limitation is a known one and is documented for BPM or WebSphere Enterprise Service Bus.

Solution

The only solution is to restart IBM Integration Designer when this error occurs.


Closed connection error occurs when using XA with Oracle 10g

Problem

When the Adapter for Oracle E-Business Suite is used to perform an XA transaction using Oracle 10g, the adapter generates a closed connection exception: javax.resource.ResourceException: Closed Connection.

Cause

This is a known issue with the Oracle 10g database driver. The following bug is filed with Oracle for this issue: 3488761 Connection closed error from OracleConnection.getConnection() - 10G drivers.

Solution

The bug is fixed in the Oracle 10g Release 2 driver. As a workaround, you can use the Oracle 9i JDBC Thin drivers to connect to the database for XA transactions.


Error occurs while starting a transaction on Oracle

Problem

When the Adapter for Oracle E-Business Suite is used to perform an XA transaction using Oracle database, the following error is generated: WTRN0078E: An attempt by the transaction manager to call start on a transactional resource has resulted in an error. The error code was XAER_RMERR.

Cause

For the Oracle database server to support XA transactions, some commands need to be run.

Solution

Run the two scripts that are included in the Oracle directory. This activity mostly needs to be performed by your Oracle database administrator, because you must be logged on to Oracle as SYSOPER or SYSDBA to have the necessary permissions for these scripts to work. The scripts are:

<ORACLE_HOME>javavm\install
file: initxa.sql
file: initjvm.sql

The initxa.sql script configures the database for XA. Once it runs successfully, the database is configured for XA. The script might run successfully for the first time you try. If it does not run successfully, it is because some of the database memory spaces are too small.

To fix this error, run the initjvm.sql script. It may probably fail again, but in doing so, it indicates which parameters need to be adjusted. The parameters are stored in this file:

<ORACLE_HOME>\database
file: init<DATABASE_SID>.ora

Table 1 shows two parameters that typically need to be increased. Your particular database configuration might require adjustment of different parameters.

Typical parameter sizes

Parameter Name Minimum Value
java_pool_size 12000000
shared_pool_size 24000000


Outbound fails due to an exception in global transactions

Problem

Outbound fails due to an exception in the global transaction and the global transaction cannot be rolled back successfully.

Cause

JCA WebSphere Adapter for Oracle E-Business Suite version 6.2 and version 7.5.0.3 supports business objects for exceptions IntegrityConstraintViolationException, MatchesExceededLimitException, MissingDataException, MultipleMatchingRecordsException, ObjectNotFoundException, RecordNotFoundException, and UniqueConstraintViolatedException. When any of these exceptions are thrown, the EIS binding encapsulates the exceptions as corresponding fault business objects like IntegrityConstraintFault, MatchesExceededLimitFault, MissingDataFault, MultipleMatchingRecordsFault, ObjectNotFoundFault, RecordNotFoundFault, and UniqueConstraintFault.

As soon as the EIS binding receives the fault business object, it throws a ServiceBusinessException instead of a ServiceRuntimeException. In global transactions, if a component throws a ServiceRuntimeException, the transaction manager will roll back the global transaction. However, if a component throws a ServiceBusinessException, the transaction manager commits global transaction.

Solution

  1. Delete all fault business object binding in the .import file.

  2. Define fault handlers to deal with business faults as shown below.
    DataObject bo = null;
      try {
       bo = (DataObject) locateService_JDBCOutboundInterfacePartner().invoke("createDb2adminAddressBG", createDb2adminAddressBGInput);
      } catch (ServiceBusinessException e) {
       // TODO Auto-generated catch block
       throw new ServiceRuntimeException(e);
      }

    Whenever WebSphere Adapter for Oracle E-Business Suite outbound process has any exception, a ServiceRuntimeException is generated and the global transaction is rolled back. Otherwise, the global transaction is committed.


A closer look at the transaction (XID) column in the event table

If the adapter is configured for assured once delivery, use the status column with the XID column to determine whether the event has been processed:


Handling unexpected results from a query SQL statement

Should you receive unexpected results from a query, turn on tracing and look at the query SQL in the log. Turning on tracing is especially helpful when you are in the test client to see if you forgot to unset all the unnecessary attributes. It is also practical to turn on tracing to determine if you did not specify your business object correctly.


Adapter returns version conflict exception message

Problem

When you install multiple adapters with different versions of CWYBS_AdapterFoundation.jar, and if a lower version of the CWYBS_AdapterFoundation.jar is loaded during run time, the adapter returns the ResourceAdapterInternalException error message, due to a version conflict. For example, when you install Oracle E-Business Suite adapter version 7.0.0.3 and WebSphere Adapter for Oracle E-Business Suite version 7.5.0.3, the following error message is displayed "The version of CWYBS_AdapterFoundation.jar is not compatible with IBM WebSphere Adapter for Oracle E-Business Suite" as IBM WebSphere Adapter for Oracle E-Business Suite loads file:/C:/IBM/WebSphere/ProcServer7/profiles/ProcSrv01/installedConnectors/CWYOE_OracleEBS.rar/CWYBS_AdapterFoundation.jar with version 7.0.0.3. However, the base level of this jar required is version 7.5.0.3. To overcome this conflict, you must migrate all adapters to the same version level.

Solution

Migrate all adapters to the same version level.

For further assistance, visit http://www.ibm.com/support/docview.wss?uid=swg27006249.


The Add and Remove buttons in the external service wizard do not function properly

Problem

When the external service wizard is run with the same Oracle E-Business Suite RAR file consecutively, and the imported Oracle E-Business Suite driver libraries are selected to be removed, all the libraries, even those not selected, are removed. For example, the Oracle driver libraries consists of a driver JAR file and a license JAR file. During the second run, if you try to remove one of the JAR files, both the JAR files are removed.

Cause

This is caused because of an issue with IBM Integration Designer.


Error displayed when using external service wizard

Problem

Error is displayed when using the external service wizard.

  1. Add a Oracle E-Business Suite driver file in the Locate the Required Files and Libraries window.

  2. Click Next and move to the Set the Discovery Properties window.

  3. Click Back and go to the Locate the Required Files and Libraries. Then add another Oracle E-Business Suite driver file.

  4. Click Next and move to the Set the Discovery Properties window.

IBM WebSphere Adapter for Oracle E-Business Suite returns the following error: 'Failure in connection to EIS. Failed to load the driver: oracle.jdbc.driver.OracleDriver. Check the Oracle E-Business Suite driver classes are in the class path'.

Cause

This is an Eclipse limitation for class loading.

Solution

Close the connector project and reopen it to add the Oracle E-Business Suite driver files again.


Unable to start adapter through web services

Problem

After configuring the adapter, you might note that:

  1. the webservices client based on the WSDL is not getting generated properly in IBM Integration Designer.
  2. you may not be able to invoke the WSDL using certain webservices client, such as RESTUI firefox plugin and soapUI tool.

Solution

Perform the following steps to enable the adapter module to load the ASI file.

  1. Create a library project.
  2. Change to the Enterprise Explorer view in IBM Integration Designer.

  3. Locate the ASI file of the adapter in connector project -> connectorModule.
  4. Copy the ASI file of the adapter and paste it in the library project.

  5. Add the library project to the list of dependencies for the adapter module.
  6. Clean project.


Staging table creation for DB2 fails with SQL errors

Problem

During advanced queue inbound, the staging table creation fails with SQL errors.

Resolution

If the staging table used for the advanced queue inbound feature is on DB2 , you must check for the below properties to have the advanced queue inbound feature functional. This is DB2 driver/database behavior.

To have LOB data read as a stream with DB2 driver, the following custom properties on the data source must be created using the administrative console:

progressiveStreaming = 2

fullyMaterializeLobData = true

Based on the DB2 version used (if server supports progressive streaming or not), the values for the properties fullyMaterializeLobData and progressiveStreaming must be set as described in Properties for the IBM DB2 Driver for JDBC and SQLJ.


Feedback

Support

This section provides information about how to troubleshoot a problem with your IBM software, including instructions for searching knowledge bases, downloading fixes, and obtaining support.


Feedback


Searching knowledge bases (Web search)

You can often find solutions to problems by searching IBM knowledge bases. You can optimize your results by using available resources, support tools, and search methods.

You can find useful information by searching the information center for Product X. However, sometimes you need to look beyond the information center to answer your questions or resolve problems.

To search knowledge bases for information that you need, use one or more of the following approaches:

Tip: Include "IBM" and the name of the product in your search if you are looking for information about an IBM product.


Feedback


Getting Fixes

A product fix might be available to resolve your problem.

To get product fixes.

  1. Determine which fix you need. Check the list of IBM WebSphere Adapter for Oracle E-Business Suite recommended fixes to confirm that your software is at the latest maintenance level. Check the list of problems fixed in the IBM WebSphere Adapter for Oracle E-Business Suite fix readme documentation that is available for each listed fix pack to see if IBM has already published an individual fix to resolve your problem. To determine what fixes are available using IBM Support Assistant, run a query on fix from the search page.

    Individual fixes are published as often as necessary to resolve defects in BPM or WebSphere Enterprise Service Bus IBM WebSphere Adapter for Oracle E-Business Suite. In addition, two kinds of cumulative collections of fixes, called fix packs and refresh packs, are published periodically for IBM WebSphere Adapter for Oracle E-Business Suite, in order to bring users up to the latest maintenance level. You should install these update packages as early as possible in order to prevent problems.

    A list of recommended, generally available (GA) fixes for the WebSphere Java™ Connector Architecture (JCA) and WebSphere Business Integration adapters are available here. If a Fix Pack is not available for an adapter, it implies the GA version is the recommended version and details about that version of the adapter can be found in the Release notes.

  2. Download the fix. Open the download document and follow the link in the Download package section. When downloading the file, ensure the name of the maintenance file is not changed. This includes both intentional changes and inadvertent changes caused by certain web browsers or download utilities.
  3. Apply the fix. Follow the instructions in the Installation Instructions section of the download document.

  4. To receive weekly notification of fixes and updates, subscribe to My Support e-mail updates.


Feedback


Self-help resources

Use the resources of IBM software support to get the most current support information, obtain technical documentation, download support tools and fixes, and avoid problems with WebSphere Adapters. The self-help resources also help you diagnose problems with the adapter and provide information about how to contact IBM software support.


Support website

The WebSphere Adapters software support website at http://www.ibm.com/support/docview.wss?uid=swg27006249 provides links to many resources to help you learn about, use, and troubleshoot WebSphere Adapters, including:


Recommended fixes

A list of recommended fixes apply is available at the following location: http://www.ibm.com/support/docview.wss?fdoc=aimadp&rs=695&uid=swg27010397.


Technotes

Technotes provide the most current documentation about WebSphere Adapter for Oracle E-Business Suite, including the following topics:

For a list of technotes for WebSphere Adapter for Oracle E-Business Suite, see http://www-01.ibm.com/support/docview.wss?uid=swg27020209.

For a list of technotes for all adapters, see http://www.ibm.com/support/search.wss?tc=SSMKUK&rs=695&rank=8&dc=DB520+D800+D900+DA900+DA800+DB560&dtm.


Feedback


10. Reference

Detailed information about business objects, adapter properties (enterprise service discovery properties, resource adapter properties, managed (J2C) connection factory properties, activation specification properties, and interaction specification properties), messages, and related product information is provided for your reference.


Feedback


Business object information

A business object is a structure that contains application-specific information (metadata) about how the adapter must process the business object as well as the operation to be performed on the business object. The name of the business object is generated by the external service wizard in accordance with the naming convention for the adapter.


Feedback


Business object attributes

Business object attributes define the content of a business object and are built from the list of columns in the database object.

A business object is simply a container for the data specified in the attributes. Each attribute has a name, type, cardinality, and several other properties. The external service wizard sets the attribute name to the name of the column. The adapter adds the attribute cardinality, type, and application-specific information. The structure of the data in the database is defined by the business object, but data in the database is in the business object attributes.

Table 1 lists the properties of a business object attribute and describes their interpretation and settings.

Attribute properties

Properties Interpretation and settings
Cardinality An integer specifying the cardinality of a business object. Each business object attribute that represents a child or an array of child business objects has the value of single or multiple (an unbounded integer) cardinality.

In both single- and multiple-cardinality relationships, the relationship between the parent and child business objects is described by the application-specific information of the key attribute in the business object storing the relationship.

Foreign Key When arrays of child business objects whose cardinality is n are retrieved, foreign keys are used in the WHERE clause of SELECT statements.

The RetrieveAll operation overrides the use of keys and foreign keys.

The adapter does not support specifying an attribute that represents a child business object as a foreign key.

Name This property represents the unique name of the attribute, if it is a simple attribute, or the name of the business object, if it is a child business object.

MinOccurs MaxOccurs

If the column is not a primary key and is not null able, the MinOccurs and MaxOccurs attributes are required, and their values are set to at least 1.
Primary Key Indicates whether this attribute is a primary key. At least one simple attribute in each business object must be specified as the primary key.

If the primary key property is set to true for a simple attribute, the adapter adds that attribute to the WHERE clause of the SELECT statement and SQL UPDATE statements that it generates while processing the business object. The RetrieveAll operation overrides the use of primary and foreign keys.

The adapter does not support specifying an attribute that represents a child business object or an array of child business objects as a primary key attribute.

Required Specifies whether an attribute must contain a value. If set to true for a container whose cardinality is single (1), then the adapter requires the parent business object contain a child business object for this attribute. Business objects that are passed to the adapter for Create, Update, and Delete operations must also contain a child business object. Cardinality is single (1) for simple attributes and multiple (n) for container attributes. The adapter causes a Create operation to fail if a business object does not have a valid value or a default value for a required attribute. It also fails if no data is available upon retrieval from the database for this object.
Type For simple attributes, this property specifies the type of the attribute, such as Integer, String, Date, Timestamp, Boolean, Double, or Float. The supported types for simple attributes and their mapping to the Oracle type of a database object are described in Table 2.

For attributes that specify a child business object, this property specifies the name of the business object.

The type of each database object, returned as the Oracle metadata, maps to the business object attribute types as listed in Table 2. Only the Oracle types listed are supported by the adapter. Any columns with types that are not listed are not added to the business object. An informational message is produced explaining the problem, for example, The column named xxxx in the table named yyyy is not of a supported type and is not added to the business object.

The default data type mapping varies based on the different Oracle JDBC driver versions. If the Oracle metadata does not map to the same data type during the configuration of the Oracle database objects, select the appropriate data type manually in the Set the Configuration Properties for 'object' window. After the generation of the business object, if you find the Oracle metadata not mapped to the same business object attribute type, update the attribute data type manually in the XSD file for the business object.

Oracle metadata column type and business object attribute types

Oracle metadata column type Business object attribute type

CHAR LONG VARCHAR2

String
NUMBER Decimal
TIMESTAMP DateTime (String data type is displayed by default)
DATE Date (String data type is displayed by default)
FLOAT Double
BLOB hexBinary
CLOB String

NCHAR NVARCHAR2

String

RAW LONG RAW

hexBinary
STRUCT or ARRAY The adapter processes these data types as child business objects of the table or query business objects.

The adapter supports complex types for the Oracle table and query business objects only. If the table contains any complex data type, such as an array, structure, nested structure or table, the type name and the sub attribute details are also automatically discovered and displayed.

The adapter treats an empty complex column as null irrespective of setting it to null or unset.

BOOLEAN The adapter supports the boolean data type for SP/SF with Record type parameter.



Related concepts:

Business object hierarchies

Feedback


Attribute application-specific information

Application-specific information (ASI) for business object attributes differs depending on whether the attribute is a simple attribute, or is an attribute that represents a child or an array of child business objects. The application-specific information for an attribute that represents a child differs depending on whether the parent-child relationship is stored in the child or in the parent.


Application-specific information for simple attributes

For simple attributes, the format for application-specific information consists of a number of parameters and their values. The only parameter that is required for a simple attribute is the column name. The application-specific information for simple attributes is described in Table 1.

Application-specific information for simple attributes

Parameter Type Description Default value
BLOB Boolean Indicates whether the database column corresponding to this attribute has the BLOB data type. While displaying BLOB data, the adapter displays the number of bytes as a hexadecimal value. The attribute type is hexBinary.

If True, the column data type is BLOB.

None
ByteArray Boolean Specifies whether the column is a binary data type. If True, the adapter reads and writes binary data to the database, and sends that data as a string to the application server. The adapter sets binary data on the business object. The attribute type is hexBinary. False
ChildBOType String If the attribute is a complex data type, use this application-specific information to specify the actual type:

  • Struct
  • Array
  • ResultSet

None
ChildBOTypeName String When the value of the ChildBOType application-specific information is either Struct or Array, this parameter value represents the name of the user-defined type. This value is case-sensitive.  
CLOB Boolean Indicates whether the database column corresponding to this attribute has the CLOB data type. This value applies only to attributes of type String.

If True, the column data type is CLOB.

The CLOB attribute has a String Type whose length is used to define the length of the CLOB.

None
ColumnName String The name of the database column corresponding to this attribute.

This is the only required parameter.

None
CopyAttribute String A user-specified value that refers to another attribute name from within the same business object or parent business object.

If the value set in the application-specific information refers to the name of another attribute within the same business object, then the adapter uses the value of the other attribute to set the value of this attribute (on which application-specific information is defined) before it adds the business object to the database during a Create operation.

For example, if you want the contact column of a new row in the table to contain the same value as the email column, set the CopyAttribute parameter of the contact attribute to email.

The value cannot reference an attribute in a child business object, but it can reference an attribute in the parent business object by preceding the name with two periods. For example, you can reference the ccode attribute in a parent business object as ..ccode.

If you do not include this parameter in the application-specific information, the adapter uses the value of the current attribute without copying the value from another attribute.

None
DateType String Specifies the corresponding element is a date or time stamp type. Specify one of the following values:

  • Date
  • Timestamp

When setting the value of an attribute of the DateType type, use the following formats:

  • For Date, use yyyy-MM-dd

  • For Timestamp, use yyyy-MM-dd hh:mm:ss.fffffffff

The adapter uses the Timestamp value present in the database. To learn more about the Timestamp method, go to the Sun website at http://java.sun.com/j2se/1.5.0/docs/api/ and search for Timestamp.

None
FixedChar Boolean Specifies whether the attribute is of fixed length when the columns in the table are of type CHAR, not VARCHAR. For example, when set to true, if a particular attribute is linked to a column that is of type CHAR, the adapter pads the attribute value with blanks to the maximum length of the attribute when querying the database.

This parameter must be updated manually in the XSD file for the business object. Open the business object by using an XML or text editor to edit the XSD file. Two changes must be made, as follows:

  1. Remove the type="string" added by default to the <element> tag for the object attribute.

  2. Add a new <simpletype> section before the </element> tag, as in this example:
    <xsd:simpleType>
    <xsd:restriction base="xsd:string">
    <xsd:maxLength value="10"/>
    </xsd:restriction>
    </xsd:simpleType>

Save the object definition, and ensure that no validation errors occur in the XSD file after it has been updated.

Following this table, see the Example of FixedChar parameter in the business object XSD file.

false
ForeignKey String The value of this property depends on whether the parent-child relationship is stored in the parent business object or in the child.

If the relationship is stored in the parent, the value includes both the type of the child business object and the name of the attribute in the child to be used as the foreign key (Child_BO_name/Child_Property_Name).

If the relationship is stored in the child, set the value to include only the name of the attribute in the parent to be used as the foreign key.

If an attribute is not a foreign key, do not include this parameter in the application-specific information.

None
OrderBy String If a value is specified and the attribute is in a child business object, the adapter uses the value of the attribute in the ORDER BY clause of retrieval queries.

The adapter can retrieve child business objects in either ascending order (ASC) or descending order (DESC). If you do not include this parameter in the application-specific information, the adapter does not specify the retrieval order.

None
PrimaryKey Boolean If the column associated with this attribute is a primary key in the corresponding table in the database, PrimaryKey is to True, None
SPParameterType String Specifies the type of stored procedure

Possible values are:

  • IP (input only)
  • OP (output only)
  • IO (input and output)
  • RS (result set)

None
UniqueIdentifier (UID) String The adapter uses this parameter to generate the unique ID for the business object. It supports the generation of sequences and identity columns.

The format of this parameter is as follows:

UID=AUTO|Sequence_Name

For a sequence, set the UID attribute to the name of the sequence.

For an identity column, set the UID attribute to AUTO.

If the attribute does not require a unique ID, do not include this parameter in the application-specific information.

None
DateFormat String Allows you to customize the format of the Date and Timestamp data types in the Application Info section of the Properties view in IBM Integration Designer. None

The format of attribute application-specific information is shown in the following example section of an XSD file:

Example section of an XSD file

<element name="pkey" nillable="true"
                        minOccurs="0" maxOccurs="1">
                        <annotation xml:space="preserve">
                  <appinfo

       source="http://www.ibm.com/xmlns/prod/websphere/j2ca/oracle/
metadata">

                        <oracleasi:OracleAttributeTypeMetadata
       xmlns:oracleasi="http://www.ibm.com/xmlns/prod/websphere/j2ca/
oracle/metadata">

       <oracleasi:ColumnName>PKEY</oracleasi:ColumnName>

       <oracleasi:PrimaryKey>true</oracleasi:PrimaryKey>

       <oracleasi:FixedChar>true</oracleasi:FixedChar>
                         </oracleasi:OracleAttributeTypeMetadata>
                   </appinfo>
            </annotation>
            <simpleType>
            <restriction base="string">
            <maxLength value="10"/>
            </restriction>
         </simpleType>        
                  </element>
                  <element name="ccode" type="string" nillable="true"
                        minOccurs="0" maxOccurs="1">
                        <annotation xml:space="preserve">
<appinfo
source="http://www.ibm.com/xmlns/prod/websphere/j2ca/oracle/metadata">
<oracleasi:OracleAttributeTypeMetadata
xmlns:oracleasi="http://www.ibm.com/xmlns/prod/websphere/j2ca/oracle/
metadata">
<oracleasi:ColumnName>CCODE</oracleasi:ColumnName>
<oracleasi:PrimaryKey>false</oracleasi:PrimaryKey>
<oracleasi:ForeignKey>custinfoobj/ccode</oracleasi:ForeignKey>
</oracleasi:OracleAttributeTypeMetadata>
</appinfo>
</annotation>
                  </element>
                  <element name="fname" type="string" nillable="true"
                        minOccurs="0" maxOccurs="1">
                        <annotation xml:space="preserve">
<appinfo
source="http://www.ibm.com/xmlns/prod/websphere/j2ca/oracle/metadata">
<oracleasi:OracleAttributeTypeMetadata
xmlns:oracleasi="http://www.ibm.com/xmlns/prod/websphere/j2ca/oracle/
metadata">
<oracleasi:ColumnName>FNAME</oracleasi:ColumnName>
<oracleasi:PrimaryKey>false</oracleasi:PrimaryKey>
</oracleasi:OracleAttributeTypeMetadata>
</appinfo>
</annotation>
                  </element>
                  <element name="lname" type="string" nillable="true"
                        minOccurs="0" maxOccurs="1">
                        <annotation xml:space="preserve">
<appinfo
source="http://www.ibm.com/xmlns/prod/websphere/j2ca/oracle/metadata">
<oracleasi:OracleAttributeTypeMetadata
xmlns:oracleasi="http://www.ibm.com/xmlns/prod/websphere/j2ca/oracle/
metadata">
<oracleasi:ColumnName>LNAME</oracleasi:ColumnName>
<oracleasi:PrimaryKey>false</oracleasi:PrimaryKey>
</oracleasi:OracleAttributeTypeMetadata>
</appinfo>
</annotation>
                  </element>
                  <element name="custinfoobj"
                        type="rtassercustinfo:RtasserCustinfo"
nillable="true" minOccurs="0"
                        maxOccurs="1">
                        <annotation xml:space="preserve">
<appinfo
source="http://www.ibm.com/xmlns/prod/websphere/j2ca/oracle/metadata">
<oracleasi:OracleAttributeTypeMetadata
xmlns:oracleasi="http://www.ibm.com/xmlns/prod/websphere/j2ca/oracle/
metadata">
<oracleasi:Ownership>true</oracleasi:Ownership>
<oracleasi:KeepRelationship>false</oracleasi:KeepRelationship>
</oracleasi:OracleAttributeTypeMetadata>
</appinfo>
</annotation>
                  </element>

Example of FixedChar parameter in the business object XSD file

<element name="pkey" nillable="true"
                        minOccurs="0" maxOccurs="1">
                        <annotation xml:space="preserve">
                  <appinfo

       source="http://www.ibm.com/xmlns/prod/websphere/j2ca/oracle/
metadata">
                         <oracleasi:OracleAttributeTypeMetadata

       xmlns:oracleasi="http://www.ibm.com/xmlns/prod/websphere/j2ca/
oracle/metadata">

       <oracleasi:ColumnName>PKEY</oracleasi:ColumnName>

       <oracleasi:PrimaryKey>true</oracleasi:PrimaryKey>

       <oracleasi:FixedChar>true</oracleasi:FixedChar>
                         </oracleasi:OracleAttributeTypeMetadata>
                   </appinfo>
             </annotation>
             <simpleType>
             <restriction base="string">
             <maxLength value="10"/>
             </restriction>
          </simpleType>        
</element>


Application-specific information for attributes of type child business object

Two application-specific information parameters are used for attributes that refer to child business objects (complex, as opposed to simple, attributes). When you set this application-specific information, specify the parameters listed in Table 2.

Application-specific information for attributes of type child business object

Parameter Type Description Default value
KeepRelationship Boolean If True, this parameter prevents the deletion of a child business object during an Update operation. None
Ownership Boolean This parameter specifies that a child business object is owned by the parent. If True, then Create, Update, and Delete operations on the child business object are allowed. If False, then no updates can be applied to the child business object. When its parent is created, the existence of the child is validated to ensure that relationship integrity is maintained in the database. None

Example of ownership in the business object XSD file

<element name="addressobj"
                        type="rtasseraddress:RtasserAddress"
nillable="true"
                        minOccurs="0"
                        maxOccurs="unbounded">
                        <annotation xml:space="preserve">
<appinfo
source="http://www.ibm.com/xmlns/prod/websphere/j2ca/oracle/metadata">
<oracleasi:OracleAttributeTypeMetadata
xmlns:oracleasi="http://www.ibm.com/xmlns/prod/websphere/j2ca/oracle/
metadata">
<oracleasi:Ownership>true</oracleasi:Ownership>
</oracleasi:OracleAttributeTypeMetadata>
</appinfo>
</annotation>
</element>

<element name="custinfoobj"
                         type="rtassercustinfo:RtasserCustinfo"
nillable="true"                                  minOccurs="0"
                         maxOccurs="1">
                         <annotation xml:space="preserve">
<appinfo
source="http://www.ibm.com/xmlns/prod/websphere/j2ca/oracle/metadata">
<oracleasi:OracleAttributeTypeMetadata
xmlns:oracleasi="http://www.ibm.com/xmlns/prod/websphere/j2ca/oracle/
metadata">
<oracleasi:Ownership>false</oracleasi:Ownership>
</oracleasi:OracleAttributeTypeMetadata>
</appinfo>
</annotation>
</element>

An example of the XSD definition file for single- and multiple-cardinality child business objects is provided here. The element custInfoObj is a single-cardinality child business object, and addressObj is a multiple-cardinality child business object.

Another example XSD file for single- and multiple-cardinality child business objects

<element name="addressobj"
                        type="rtasseraddress:RtasserAddress" 
nillable="true"
                        minOccurs="0"
                        maxOccurs="unbounded">
                       <annotation xml:space="preserve">
<appinfo
source="http://www.ibm.com/xmlns/prod/websphere/j2ca/oracle/metadata">
<oracleasi:OracleAttributeTypeMetadata
xmlns:oracleasi="http://www.ibm.com/xmlns/prod/websphere/j2ca/oracle/
metadata">
<oracleasi:Ownership>true</oracleasi:Ownership>
</oracleasi:OracleAttributeTypeMetadata>
</appinfo>
</annotation>
</element>

<element name="custinfoobj"
                         type="rtassercustinfo:RtasserCustinfo"
nillable="true"                                  minOccurs="0"
                         maxOccurs="1">
                         <annotation xml:space="preserve">
<appinfo 
source="http://www.ibm.com/xmlns/prod/websphere/j2ca/oracle/metadata">
<oracleasi:OracleAttributeTypeMetadata
xmlns:oracleasi="http://www.ibm.com/xmlns/prod/websphere/j2ca/oracle/
metadata">
<oracleasi:Ownership>false</oracleasi:Ownership>
</oracleasi:OracleAttributeTypeMetadata>
</appinfo>
</annotation>
</element>


Application-specific information for operations

The adapter uses application-specific information at the operation level to perform operations, such as to retrieve and update information in the database. The adapter retrieves and updates database tables using SQL queries, stored procedures, or stored functions, as specified in the business objects.

If you choose to add stored procedures or stored functions to the business objects, set the operation application-specific information (ASI) as specified in Table 3.

Operation application-specific information

Operation ASI for StoredProcedure parameters element Set by wizard Description
Parameters Yes Lists the stored procedure parameters.
PropertyName Yes Set to the name of the business object attribute that you select.
ResultSet No If the stored procedure returns a result set, set this parameter to True in the business object definition.
ReturnValue Yes If the stored procedure has a return value, this parameter contains one of these values:

  • The string RS. This value indicates the procedure returns a result set, which is used to create the multiple-cardinality container corresponding to this business object.
  • The name of the business object attribute. This value indicates that procedure returns the value that is to be assigned to that particular attribute in the business object at run time.

    If the attribute is another child business object, the adapter returns an error.

StoredProcedure Yes Set to the stored procedure name.
StoredProcedureType Yes You choose from a list of types. For information about valid stored procedure types, see .Stored procedure type
Type Yes Set to the type of the stored procedure parameter. Possible values are:

  • IP (input only)
  • OP (output only)
  • IO (input and output)
  • RS (result set)


Feedback


Business object-level application-specific information

Application-specific information in business object definitions provides the adapter with application-dependent instructions for how to process business objects. The adapter parses the application-specific information from the business object or from its attributes or operations to generate queries for Create, Update, Retrieve, and Delete operations.


Application-specific information for table and view business objects

Application-specific information at the business-object level specifies the name of the corresponding database table and to provide information necessary to perform a physical or logical Delete operation.

The external service wizard sets the TableName application-specific information attribute to a value in the form of SchemaName.TableName. It prompts you for the information necessary to perform a physical or logical Delete operation and then sets the business object-level application-specific information shown in Table 1.

Business object application-specific information (ASI) for a table business object

Application-specific information Type Description
TableName String The name of the database table corresponding to this business object.
StatusColumnName String Indicates whether the adapter is to logically or physically delete data in the table. If the StatusColumnName parameter is not set, data is physically deleted. If the parameter is set, it specifies the name of the column that indicates a logically deleted row. You specify this parameter when you select the table object in the external service wizard.

This parameter applies to both Update and Delete operations.

StatusValue String The value that indicates that a column is logically deleted. You specify this value when you select the table object in the external service wizard.

To illustrate how the adapter determines whether to do a logical or physical delete in response to an Update or Delete operation, assume that a Customer business object has the business object application-specific information shown in Table 2.

Sample parameters for business object application-specific information for a table business object

Application-specific information Value
TableName customer
StatusColumnName status
StatusValue deleted

Assume the adapter receives a request to delete a customer. Because the business object includes the StatusColumnName parameter in its application-specific information, the adapter performs a logical delete operation. It does this by placing the string "deleted", which is specified in the StatusValue parameter, in the status column, which is the column specified in the StatusColumnName parameter.

Such a request causes the adapter to issue the following SQL statement:

However, if the StatusColumnName parameter is not set, the customer records are physically deleted. The adapter issues the following SQL statement:


Application-specific information for stored procedure business objects

For business objects that are based on stored procedures, the external service wizard sets the business object-level application-specific information SPName to a value in the form of SchemaName + SPName. It sets the business object-level application-specific information, which is listed in Table 3. The attributes of the business object are created based on the stored procedure input/output parameters. If the stored procedure has one returned value, a corresponding business object attribute is created. If the returned value or any of the input/output parameters are complex data types, the wizard creates child business objects for them.

The discovery of database objects in the external service wizard can support nested structures and arrays. If these child business objects are generated from returned result sets, their names are in the form of Prefix + SchemaName + SPName + RetRS + Number. For example, if one stored procedure returns two result sets, the wizard creates two child business objects for them. Their names are Prefix + SchemaName + SPName + RetRS1 and Prefix + SchemaName + SPName + RetRS2.

When the child business objects are generated from input/output parameters with a complex data type of ResultSet, Struct, or Array, these child business object names are in the form of Prefix+SchemaName+SPName+ParameterName. For those child business objects that correspond to nested structures and arrays, their business object names are in the form of Prefix+SchemaName+SPName+ParameterName+ColumnName.

Business object application-specific information (ASI) for business objects based on stored procedures

Application-specific information Type Description
SPName String The name of the stored procedure or stored function
ResultSet Boolean Indicates whether the stored procedure or stored function returns a result set. If true, the stored procedure returns one or more result sets. If false, the stored procedure or stored function does not return a result set.
MaxNumberOfRetRS String The maximum number of returned result sets that are handled by the adapter run time
ReturnValue String Set to the name of the corresponding business object attribute if the stored procedure has a return value. If the returned value is of simple data type, the attribute is also of simple data type. If the returned value is a result set, this attribute points to a child business object.


Application-specific information for query business objects

For query business objects, there is one business object-level application-specific information, as shown in Table 4.

Business object application-specific information (ASI) for query business objects

Application-specific information Type Description
SelectStatement String The complete SELECT statement that performs the query. You specify the statement in the external service wizard.

The external service wizard also generates business graphs for all business objects, because all are top level. The name of the business graph is the business object name followed by "BG." For example, a business object with the name OracleSchema1Customer, would have the business graph named OracleSchema1CustomerBG. The operations set in the business object are also set in the business graph.

When the wizard generates a stored procedure business object, it creates a child business object if necessary, such as for ResultSet, Struct, and Array. Creating parent-child relationships between table business objects is done manually using the Business Object Editor.

The wizard handles business objects based on synonym/nicknames like objects based on tables and views, even when a synonym is of a stored procedure.


Feedback


Naming conventions

When the external service wizard generates a business object, it provides a name for the business object that reflects the naming convention for the adapter. Typically, the business object name indicates the structure of the business object.

When the external service wizard creates names for a business object, it replaces any special character except the underscore (_) in the business object name with U followed by its Unicode number. For example, the business object name for the Order_Item table in the database is Order_Item. The business object name for the Shipping-Address table is ShippingU45Address.

Business object names have no semantic value to the adapter or the database; that is, they derive no information nor meaning from the business object name. If one name is replaced by another, the adapter behavior remains the same.

Business object names can carry database-specific metadata. A name can use a string like Oracle or %AppName% as a prefix to help distinguish between two types of business objects: application-specific and generic. The remainder of the name can describe the table or stored procedure the business object represents. For example, if the business object definition is generated for the Employee Table in a database application, such as Human Resources (HR), then the respective business object name is HREmployee.

For business objects that do not correspond to database objects, such as business objects for database queries, if you give the business object the same name as a table or stored procedure business object, a different number is appended at the end of each name to differentiate them and avoid overwriting.

Globalized characters are supported in any business object name.

You can rename business objects by using the refactoring functionality in IBM Integration Designer. For more details, refer to the IBM Integration Designer documentation.

The following table describes the naming conventions the wizard uses for the business object.

Business object naming conventions

Element Naming convention
Business graph

The business graph that contains the parent business object is named for the contained business object, followed by the string "BG"; for example, the business graph that contains the SalesCustomer business object is named SalesCustomerBG.

Business objects for:

  • Tables
  • Views
  • Stored procedures
  • Stored functions
  • Synonyms and nicknames

For those business objects that are based on tables, views, stored procedures, and synonyms and nicknames, the external service wizard generates the name of the business object in the form of Prefix + SchemaName + ObjectName, where:

  • Prefix is the value as specified in the external service connection property named Prefix. A prefix is not required, and if not specified, no prefix is added to the business object name.
  • SchemaName is the name of the schema to which the object belongs.
  • ObjectName is the name of the table, view, stored procedure, stored function, or synonym/nickname. A number is appended if necessary to differentiate the business object from another business object with the same name.

For example, using the prefix Campaign12 for the Customer table in the Sales schema, the business object name is Campaign12SalesCustomer.

Query business objects

For query business objects, the external service wizard generates the name of the business object in the form of Prefix + QueryBOName, where:

  • Prefix is the prefix you specify in the wizard. A prefix is not required, and if not specified, no prefix is added to the business object name.

  • QueryBOName is the value you specified when you configured the business object in the wizard. A number is appended if necessary to differentiate the business object from another business object with the same name.



Related tasks:

Set connection properties for the external service wizard

Feedback


Fault business objects

The adapter supports business faults, which are exceptions that are anticipated and declared in the outbound service description, or import. Business faults occur at predictable points in a business process, and are caused by a business rule violation or a constraint violation.

The WebSphere Adapter for Oracle E-Business Suite enables faults for you. Manual configuration of faults is not required. Some faults contain the matchCount attribute which provides additional information about the error. For others, WBIFault contains all the information needed to handle the fault.

The adapter provides the following fault business objects the wizard creates:



Related concepts:

Create operation

Retrieve operation

RetrieveAll operation

Update operation

ApplyChanges operation

Delete operation

Execute operation

Exists operation

Business faults

Feedback


Configuration properties

IBM WebSphere Adapter for Oracle E-Business Suite has several categories of configuration properties, which you set with the external service wizard while generating or creating objects and services. You can change the resource adapter, managed connection factory, and activation specification properties after you deploy the application to IBM Business Process Manager or WebSphere Enterprise Service Bus.


Feedback


Outbound configuration properties

IBM WebSphere Adapter for Oracle E-Business Suite has several categories of outbound connection configuration properties, which you set with the external service wizard while generating or creating objects and services. You can change the resource adapter and managed connection factory properties after you deploy the module to IBM Business Process Manager or WebSphere Enterprise Service Bus using IBM Integration Designer or the administrative console, but connection properties for the external service wizard cannot be changed after deployment.



Related reference:

Inbound configuration properties

Feedback


Connection properties for the wizard

external service wizard connection properties are used to establish a connection between the external service wizard, a tool used to create business objects, and the database.


Feedback


Resource adapter properties

The resource adapter properties control the general operation of the adapter, such as specifying the namespace for business objects. You set the resource adapter properties using the external service wizard when you configure the adapter. After deploying the adapter, use the administrative console to change these properties.

The following table lists the resource adapter properties and their purpose. A complete description of each property is provided in the sections that follow the table. For information about how to read the property details table, see Guide to information about properties.

Resource adapter properties for the Adapter for Oracle E-Business Suite

Name Description
In the wizard In the administrative console
Adapter ID

AdapterID

Identifies the adapter instance for PMI events and for logging and tracing.

Database vendor DatabaseVendor

The type of database the adapter uses for special processing.

Disguise user data as "XXX" in log and trace files HideConfidentialTrace Specifies whether to disguise potentially sensitive information by writing X strings instead of user data in the log and trace files.
Query time out QueryTimeOut

The maximum number of seconds a query can take for all SQL statements.

Return business object even when the stored procedure result set is empty ReturnDummyBOForSP

Specifies whether to return output parameters when the result set is empty.

(Not available) enableHASupport

Do not change this property.

(Not available)

LogFileSize

Deprecated
(Not available)

LogFilename

Deprecated
(Not available)

LogNumberOfFiles

Deprecated
SQL query to verify the connection PingQuery

The SQL query used to test the reliability of the connection to the database.

(Not available)

TraceFileSize

Deprecated
(Not available)

TraceFileName

Deprecated
(Not available)

TraceNumberOfFiles

Deprecated


Adapter ID (AdapterID)

This property identifies a specific deployment or instance of the adapter.

Adapter ID details

Required Yes
Default 001
Property type String
Usage This property identifies the adapter instance in the log and trace files, and also helps identify the adapter instance while monitoring adapters. The adapter ID is used with an adapter-specific identifier, OEBSRA, to form the component name used by the Log and Trace Analyzer tool. For example, if the adapter ID property is set to 001, the component ID is OEBSRA001.

If you run multiple instances of the same adapter, ensure the first seven characters of the adapter ID property are unique for each instance so that you can correlate the log and trace information to a particular adapter instance. By making the first seven characters of an adapter ID property unique, the component ID for multiple instances of that adapter is also unique, allowing you to correlate the log and trace information to a particular instance of an adapter.

For example, when you set the adapter ID property of two instances of WebSphere Adapter for Oracle E-Business Suite to 001 and 002. The component IDs for those instances, OEBSRA001 and OEBSRA002, are short enough to remain unique, enabling you to distinguish them as separate adapter instances. However, instances with longer adapter ID properties cannot be distinguished from each other. If you set the adapter ID properties of two instances to Instance01 and Instance02, you will not be able to examine the log and trace information for each adapter instance because the component ID for both instances is truncated to OEBSRAInstanc.

For inbound processing, the value of this property is set at the resource adapter level. For outbound processing, the value can be set both at the resource adapter level and the managed connection factory level. After use the external service wizard to configure the adapter for outbound processing, you can set the resource adapter and managed connection factory properties independently. If using the IBM Integration Designer assembly editor or the administrative console to reset these properties, ensure set them consistently, to prevent inconsistent marking of the log and trace entries.

Globalized Yes
Bidi supported No


Database vendor (DatabaseVendor)

This property specifies the type of database used. The type is determined by the database vendor name.

Database vendor details

Required Yes
Possible values

Oracle

Default ORACLE
Property type String
Usage

Some SQL statements require special processing, which varies by database type. For example, the Struct and Array data types in Oracle require special processing. This property specifies the RDBMS used, which determines the database type.

For other databases, the adapter does not perform any special processing. Verify the correct driver is specified in the JDBCDriverClass property.

Specify Oracle as the value corresponding to the database vendor.

Globalized No
Bidi supported No


Disguise user data as "XXX" in log and trace files (HideConfidentialTrace)

This property specifies whether to replace user data in log and trace files with a string of X's to prevent unauthorized disclosure of potentially sensitive data.

Disguise user data as "XXX" in log and trace files details

Required No
Possible values

True False

Default False
Property type Boolean
Usage If you set this property to True, the adapter replaces user data with a string of X's when writing to log and trace files.

For inbound processing, the value of this property is set at the resource adapter level. For outbound processing, the value can be set both at the resource adapter level and the managed connection factory level. After use the external service wizard to configure the adapter for outbound processing, you can set the resource adapter and managed connection factory properties independently. If using the IBM Integration Designer assembly editor or the administrative console to reset these properties, ensure set them consistently, to prevent inconsistent marking of the log and trace entries.

Globalized No
Bidi supported No


Enable high availability support (enableHASupport)

Do not change this property. It must be set to true.


Query timeout (seconds) (QueryTimeOut)

This property specifies the maximum number of seconds a query can take to run all SQL statements.

Query timeout details

Required No
Default No default value
Unit of measure Seconds
Property type Integer
Usage If the query takes longer than the number of seconds specified, the database generates an SQL exception that is captured. The associated message is logged in the log file.

If a value is not specified, no timeout is set on the query.

Globalized No
Bidi supported No


Return business object even when the stored procedure result set is empty (ReturnDummyBOForSP)

This property specifies whether to return output parameters when the result set is empty.

Return business object even when the stored procedure result set is empty details

Required No
Possible values

True False

Default False
Property type Boolean
Usage

The Retrieve Stored Procedure (RetrieveSP) operation returns a result set. If the result set is empty and the ReturnDummyBOForSP property is set to False, no business objects are created, and the output parameters returned by the procedure call cannot be retrieved.

However, if the ReturnDummyBOForSP property is set to True, a dummy business object is created and the returned parameters (including the out and inout parameters) from the stored procedure are populated into the corresponding attributes

Globalized No
Bidi supported No


SQL query to verify the connection (PingQuery)

This property specifies the SQL query used to test the reliability of the connection to the database.

Ping query details

Required No
Property type String
Default No default value
Usage

This property contains the SQL query statement to run to determine whether the adapter can connect to the database.

The adapter runs the ping query every time it receives a SQLException exception while performing the outbound operation.

The adapter does not try to recover the connection. If the ping query indicates the connection to the database is no longer valid, the adapter notifies the container. It is the responsibility of the connection pool manager to remove the stale connection from the pool, which allows subsequent outbound requests to be processed.

Globalized No
Bidi supported No


Feedback


Managed connection factory properties

Managed connection factory properties are used by the adapter at run time to create an outbound connection instance with the Oracle E-Business Suite.

You set managed connection factory properties using the external service wizard during adapter configuration. You can change them using the IBM Integration Designer assembly editor or, after deployment, with the BPM or WebSphere Enterprise Service Bus administrative console.

The following table lists and describes the managed connection factory properties. A complete description of each property is provided in the sections that follow the table. For information about how to read the property detail tables in the sections that follow, see Guide to information about properties.

The external service wizard refers to these properties as managed connection factory properties, while the administrative console refers to them as J2C connection factory properties.

Managed connection factory properties for Adapter for Oracle E-Business Suite

Property name Description
In the wizard In the administrative console
Adapter ID

AdapterID

Identifies the adapter instance for PMI events and for logging and tracing.

Additional JDBC driver connection properties [name:value;name:value] JDBCDriverConnectionProperties

Additional properties for connecting to the database using the JDBC driver, which are used in addition to the UserName and Password properties.

Auto commit AutoCommit The AutoCommit value to use on the connection
DataSource JNDI name DataSourceJNDIName This property is deprecated. Use the XADataSourceJNDIName or PoolDataSourceJNDIName properties
Database URL DatabaseURL

The database URL used to connect to the database.

Database vendor DatabaseVendor

The type of database the adapter uses for special processing.

Disguise user data as "XXX" in log and trace files HideConfidentialTrace Specifies whether to disguise potentially sensitive information by writing X strings instead of user data in the log and trace files.
JDBC driver class JDBCDriverClass

The class name of the JDBC driver used to connect to the database.

Maximum retries on connection failure (connectionRetryLimit) connectionRetryLimit

Specifies the maximum number of times the adapter tries to reestablish an outbound connection to the EIS.

Password Password

Password for the corresponding user name

Query timeout QueryTimeOut

The maximum number of seconds a query can take for all SQL statements.

Connection Retry interval (in milliseconds) (connectionRetryInterval) connectionRetryInterval

Specifies the time interval between attempts to reconnect to the EIS if the connection fails.

Return business object even when the stored procedure result set is empty ReturnDummyBOForSP

Specifies whether to return output parameters when the result set is empty.

SQL query to connection PingQuery

The SQL query used to test the reliability of the connection to the database.

User name UserName

The database user name.

XA DataSource name (XADataSourceName) XADataSourceName The name of the XA data source to use to establish a connection to the database for XA (distributed) transactions
Database connection information (ConnectionType) ConnectionType Specifies how the adapter establishes connection to the database.
Connection pool DataSource JNDI name (PoolDataSourceJNDIName) PoolDataSourceJNDIName The JNDI name of the connection pool data source to be used to establish a connection to the database.
XA DataSource JNDI name (XADataSourceJNDIName) XADataSourceJNDIName

The JNDI name of the XA data source used to establish a connection to the database.

Managed connection factory properties for XML gateway interface

Property name Description
In the wizard In the administrative console
Oracle E-Business Suite Connection Type (EBSConnectionType) EBSConnectionType Specifies the Oracle E-Business Suite connection type.
Oracle E-Business Suite Transport (EBSTransport) EBSTransport Specifies the Oracle E-Business Suite transport.
Oracle E-Business Suite Version (EBSVersion) EBSVersion Specifies the Oracle E-Business Suite version.
Password (Password) Password Specifies the password required when starting the web or JMS service.
Host Name (EBSHostName) EBSHostName Specifies the Oracle E-Business Suite host name or IP address when starting the JMS service.
System ID (EBSSystemID) EBSSystemID Specifies the Oracle E-Business Suite system ID when starting the JMS service.
User Name (UserName) UserName Specifies the user name for starting the web or JMS service.
WSDL URL (WSDLURL) WSDLURL Specifies the WSDL URL of the XML gateway interface.
Port Number (EBSPortNumber) EBSPortNumber Specifies the Oracle E-Business Suite port number when starting the JMS.
Schema Name (EBSSchemaName) EBSSchemaName Specifies the schema name of XML gateway JMS advanced queue.
Queue Name (EBSQueueName) EBSQueueName Specifies the XML gateway JMS advanced queue name.


Adapter ID (AdapterID)

This property identifies a specific deployment or instance of the adapter.

Adapter ID details

Required Yes
Default 001
Property type String
Usage This property identifies the adapter instance in the log and trace files, and also helps identify the adapter instance while monitoring adapters. The adapter ID is used with an adapter-specific identifier, OEBSRA, to form the component name used by the Log and Trace Analyzer tool. For example, if the adapter ID property is set to 001, the component ID is OEBSRA001.

If you run multiple instances of the same adapter, ensure the first seven characters of the adapter ID property are unique for each instance so that you can correlate the log and trace information to a particular adapter instance. By making the first seven characters of an adapter ID property unique, the component ID for multiple instances of that adapter is also unique, allowing you to correlate the log and trace information to a particular instance of an adapter.

For example, when you set the adapter ID property of two instances of WebSphere Adapter for Oracle E-Business Suite to 001 and 002. The component IDs for those instances, OEBSRA001 and OEBSRA002, are short enough to remain unique, enabling you to distinguish them as separate adapter instances. However, instances with longer adapter ID properties cannot be distinguished from each other. If you set the adapter ID properties of two instances to Instance01 and Instance02, you will not be able to examine the log and trace information for each adapter instance because the component ID for both instances is truncated to OEBSRAInstanc.

For inbound processing, the value of this property is set at the resource adapter level. For outbound processing, the value can be set both at the resource adapter level and the managed connection factory level. After use the external service wizard to configure the adapter for outbound processing, you can set the resource adapter and managed connection factory properties independently. If using the IBM Integration Designer assembly editor or the administrative console to reset these properties, ensure set them consistently, to prevent inconsistent marking of the log and trace entries.

Globalized Yes
Bidi supported No


Additional JDBC driver connection properties [name:value;name:value] (JDBCDriverConnectionProperties)

This property contains additional information for connecting to the database using the JDBC driver.

Additional JDBC driver connection properties details

Row Explanation
Required No
Possible values Database connection properties are database-specific.
Default No default value
Property type String
Usage These connection properties are used in addition to the UserName and Password properties to customize the database connection used by the adapter.

Set the connection properties as one or more name:value pairs separated by the semicolon character (;).

Example

The following value of this property specifies a login timeout interval:

    loginTimeout:20; ConnectionRetryCount:5; ConnectionRetryDelay:5

Globalized Yes
Bidi supported No


Auto commit (AutoCommit)

This property specifies whether AutoCommit is set for the connection.

Auto commit details

Required No
Possible values

True False

Default False
Property type Boolean
Usage This property is ignored for XA (distributed) transactions.
Globalized No
Bidi supported No


Database URL (DatabaseURL)

This property specifies the JDBC driver-specific URL for creating a connection to the database.

Database URL details

Required Yes, when the connection is of the type LocalConnectionProps or ConnectionProps.
Default No default value
Property type String
Usage In the external service wizard, compose the database URL by entering in database-specific fields. For example, the database URL for an Oracle database is composed of the system ID (SID), server host name, and database port number. In the administrative console, type the complete database URL value.

If the database server supports IPv6, you can specify the host name portion of the database URL in IPv6 format.

If you specify the host name as an IP address in IPv6 format, enclose the IP address in square brackets ([]).

Examples

The following example illustrates typical database URL values for a common database:jdbc:oracle:thin:@9.26.248.148:1521:dev

Globalized Yes
Bidi supported Yes


Database vendor (DatabaseVendor)

This property specifies the type of database used. The type is determined by the database vendor name.

Database vendor details

Required Yes
Possible values

Oracle

Default ORACLE
Property type String
Usage

Some SQL statements require special processing, which varies by database type. For example, the Struct and Array data types in Oracle require special processing. This property specifies the RDBMS used, which determines the database type.

For other databases, the adapter does not perform any special processing. Verify the correct driver is specified in the JDBCDriverClass property.

Specify Oracle as the value corresponding to the database vendor.

Globalized No
Bidi supported No


Disguise user data as "XXX" in log and trace files (HideConfidentialTrace)

This property specifies whether to replace user data in log and trace files with a string of X's to prevent unauthorized disclosure of potentially sensitive data.

Disguise user data as "XXX" in log and trace files details

Required No
Possible values

True False

Default False
Property type Boolean
Usage If you set this property to True, the adapter replaces user data with a string of X's when writing to log and trace files.

For inbound processing, the value of this property is set at the resource adapter level. For outbound processing, the value can be set both at the resource adapter level and the managed connection factory level. After use the external service wizard to configure the adapter for outbound processing, you can set the resource adapter and managed connection factory properties independently. If using the IBM Integration Designer assembly editor or the administrative console to reset these properties, ensure set them consistently, to prevent inconsistent marking of the log and trace entries.

Globalized No
Bidi supported No


Throw exception when no records are found (ErrorOnEmptyResultSet)

This property specifies whether to generate a fault or return an empty business object when no records are found.

Throw exception when no records are found details

Required No
Possible values

True False

Default True
Property type Boolean
Usage If you set this property to False, the RetrieveAll operation does not generate a RecordNotFoundException exception when no records are found.
Globalized No
Bidi supported No


JDBC driver class (JDBCDriverClass)

This property specifies the class name of the JDBC driver used to connect to the database.

JDBC driver class details

Row Explanation
Required Yes, when the connection is of the type LocalConnectionProps or ConnectionProps.
Possible values

The value specified when you set the connection properties to connect to the database instance.

Default No default value
Property type String
Usage In the external service wizard, the JDBC driver class is displayed if you select a common database software and driver combination, such as type 4 drivers for recent versions of Oracle. For type 2 drivers , you must type the database class name.

If you select a type 2 driver or a generic driver, you must type the JDBC driver class name.

In the administrative console, type the database-specific name of the driver.

Examples

Values for the JDBC driver class is displayed in both the external service wizard and the administrative console. The following examples depict the JDBC driver class properties in both the external service wizard and the administrative console. In the external service wizard:

  • To connect to an Oracle 10 database using the type 4 driver, select Oracle Thin Driver.

In the administrative console:

Oracle Thin JDBC driver

oracle.jdbc.driver.OracleDriver
Globalized No
Bidi supported No


Password (Password)

This property specifies the password for the database user name.

Password details

Required No. For inbound processing, if you set the Authentication alias or the DataSourceJNDIName, the password is not mandatory. However, if you set the DataSourceJNDIName, and the Password field, the value specified for the Password takes precedence.

For outbound processing, if you set the Authentication alias, XADataSourceJNDIName or PoolDataSourceJNDIName property, the password is not mandatory. However, if you set the XADataSourceJNDIName or PoolDataSourceJNDIName property, and the Password field, the value specified for the Password takes precedence.

Default No default value
Property type String
Usage For inbound processing, setting this property overrides the password specified for the data source on the server using the Authentication alias or DataSourceJNDIName property.

For outbound processing, setting this property overrides the password specified for the data source on the server using the Authentication alias, or XADataSourceJNDIName or PoolDataSourceJNDIName property.

If you specify JAAS as the security credential, the authentication alias will override this property.

Globalized Yes
Bidi supported Yes


Query timeout (seconds) (QueryTimeOut)

This property specifies the maximum number of seconds a query can take to run all SQL statements.

Query timeout details

Required No
Default No default value
Unit of measure Seconds
Property type Integer
Usage If the query takes longer than the number of seconds specified, the database generates an SQL exception that is captured. The associated message is logged in the log file.

If a value is not specified, no timeout is set on the query.

Globalized No
Bidi supported No


Return business object even when the stored procedure result set is empty (ReturnDummyBOForSP)

This property specifies whether to return output parameters when the result set is empty.

Return business object even when the stored procedure result set is empty details

Required No
Possible values

True False

Default False
Property type Boolean
Usage

The Retrieve Stored Procedure (RetrieveSP) operation returns a result set. If the result set is empty and the ReturnDummyBOForSP property is set to False, no business objects are created, and the output parameters returned by the procedure call cannot be retrieved.

However, if the ReturnDummyBOForSP property is set to True, a dummy business object is created and the returned parameters (including the out and inout parameters) from the stored procedure are populated into the corresponding attributes

Globalized No
Bidi supported No


SQL query to verify the connection (PingQuery)

This property specifies the SQL query used to test the reliability of the connection to the database.

Ping query details

Required No
Property type String
Default No default value
Usage

This property contains the SQL query statement to run to determine whether the adapter can connect to the database.

The adapter runs the ping query every time it receives a SQLException exception while performing the outbound operation.

The adapter does not try to recover the connection. If the ping query indicates the connection to the database is no longer valid, the adapter notifies the container. It is the responsibility of the connection pool manager to remove the stale connection from the pool, which allows subsequent outbound requests to be processed.

Globalized No
Bidi supported No


User name (UserName)

This property specifies the database user name used to access the database.

User name details

Required No. For inbound processing, if you set the Authentication alias or the DataSourceJNDIName, the User name property is not mandatory. However, if you set the DataSourceJNDIName, and User name field, the value specified for the User name takes precedence.

For outbound processing, if you set the Authentication alias, XADataSourceJNDIName or PoolDataSourceJNDIName property, the User name is not mandatory. However, if you set the XADataSourceJNDIName or PoolDataSourceJNDIName property, and the User name field, the value specified for the User name takes precedence.

Default No default value
Property type String
Usage For inbound processing setting this property overrides the user name specified for the data source on the server using the DataSourceJNDIName property or the Authentication alias.

For outbound processing, setting this property overrides the user name specified for the data source on the server using the XADataSourceJNDIName property, PoolDataSourceJNDIName property or the Authentication alias.

If you specify JAAS as the security credential, the authentication alias will override this property.

Globalized Yes
Bidi supported Yes


XA DataSource name (XADataSourceName)

This property specifies the name of the XA data source used to establish a connection to the database for XA (distributed) transactions.

XA data source name details

Required No
Default No default value
Property type String
Usage

This property is used to make an XA connection to an Oracle database.

Examples

A typical value for an Oracle database:

oracle.jdbc.xa.client.OracleXADataSource

Globalized No
Bidi supported No


Maximum retries on connection failure (connectionRetryLimit)

This property specifies the number of times the adapter attempts to reestablish a connection to the EIS, when the adapter encounters an error related to the outbound connection.

Maximum retries in case of system connection failure details

Required No
Possible values Integer equal to and greater than zero
Default 0
Property type Integer
Usage

When the adapter encounters an error related to the outbound connection, it retries to establish a physical connection (when physical connection is not established) for the number of times specified for this property with a time delay specified in the property Connection Retry interval (in milliseconds) (connectionRetryInterval).

If the value is set to 0, the adapter does not validate the connection to the EIS and it executes the outbound operation. If the EIS connection is invalid, the outbound operation fails. The adapter does not attempt to reconnect to the EIS.

If the value is set to greater than 0, then during each request the adapter validates if the connection to the EIS is active.

  • If the connection is valid, the operation is completed.

  • If connection is invalid, the adapter terminates the current managed connection and a new managed connection is created (new physical connection). If the adapter is successful in reestablishing the connection to the EIS, the outbound operation is completed otherwise the adapter generates the ResourceException after trying to reconnect for the specified number of times.

Globalized No
Bidi supported No


Connection Retry interval (in milliseconds) (connectionRetryInterval)

This property specifies the time interval between attempts to reconnect to the EIS if the connection fails.

Retry interval if connection failure details

Required No
Possible values Integer equal to and greater than zero
Default 60000
Unit of measure Milliseconds
Property type Integer
Usage

When the adapter encounters an error while establishing a connection to the EIS, this property specifies the time interval the adapter waits between attempts to reestablish a connection.

By default, this property disabled and it is enabled only when the value of the Maximum retries on connection failure (connectionRetryLimit)property is set to greater than zero.

Globalized No
Bidi supported No


Database connection information (ConnectionType)

This property specifies how the adapter establishes connection to the database.

Database connection information

Required Yes
Possible values XADataSourceJNDI, XAConnectionProps, PoolDataSourceJNDI, or LocalConnectionProps
Default No default value
Property type String
Usage This property specifies how the adapter establishes database connection at run time. This property can have the following values:

  • XADataSourceJNDI- Indicates the database connection is established using the XADataSourceJNDIName property corresponding to the predefined XA data source.
  • XAConnectionProps - Indicates the database connection is established using the XADataSourceName and DatabaseURL or XADatabaseName properties.
  • PoolDataSourceJNDI - Indicates the database connection is established using the poolDataSourceJNDIName property corresponding to the predefined data source.
  • LocalConnectionProps - Indicates the database connection is established using the DatabaseURL and JDBCDriverClass properties.

For a new application, this property is automatically set by external service wizard. For a migrated application, this property is set during the migration process according to the ManagedConnectionFactory properties.

  • If the DataSourceJNDIName property is set, the value of this property is set to XADataSourceJNDI.

  • If the XADataSourceName is set, the value of this property is set to XAConnectionProps.
  • Otherwise, the value of this property is set to LocalConnectionProps.

If this property is not set, adapter uses compatibility with an earlier version mode to establish database connection. In the compatibility with an earlier version mode, the properties for connecting to the database are used in the following order:

  1. If the DataSourceJNDIName property is set, the adapter uses it to establish the connection to the database.

  2. If the DataSourceJNDIName property is not set, and the XADataSourceName and XADatabaseName properties are set, the adapter uses them to establish the connection. The DataSourceJNDIName property represents an XA or connection pool data source. If you define a JNDI data source on the server that supports XA transactions and then specify that data source when you configure the adapter, you can connect to any type of database that supports XA transactions. If you use an XA data source and database, the adapter supports XA transaction only for DB2 and Oracle databases.

  3. If the DataSourceJNDIName, XADataSourceName, and XADatabaseName properties are not set, then the adapter uses the DatabaseURL, JDBCDriverClass, UserName, and Password properties to establish the connection.

Globalized No
Bidi supported No


Connection pool DataSource JNDI name (PoolDataSourceJNDIName)

The JNDI name of the connection pool data source to be used to establish a connection to the database.

Connection pool data source

Required No
Default No default value
Property type String
Usage Use this property to specify the JNDI name of a connection pool data source in BPM or WebSphere Enterprise Service Bus that specifies connection information for the target database. If the Database connection information (ConnectionType) property is set to "PoolDataSourceJNDI" the adapter use this property to establish the connection to the database. To improve the performance of outbound operations, specify the name of a data source that is enabled for prepared statement caching. If the other valid authentication properties are also set, they override authentication properties in the data source.
Globalized No
Bidi supported No


JDBC driver class (JDBCDriverClass)

This property specifies the class name of the JDBC driver used to connect to the database.

JDBC driver class details

Row Explanation
Required Yes, when the connection is of the type LocalConnectionProps or ConnectionProps.
Possible values

The value specified when you set the connection properties to connect to the database instance.

Default No default value
Property type String
Usage In the external service wizard, the JDBC driver class is displayed if you select a common database software and driver combination, such as type 4 drivers for recent versions of Oracle. For type 2 drivers , you must type the database class name.

If you select a type 2 driver or a generic driver, you must type the JDBC driver class name.

In the administrative console, type the database-specific name of the driver.

Examples

Values for the JDBC driver class is displayed in both the external service wizard and the administrative console. The following examples depict the JDBC driver class properties in both the external service wizard and the administrative console. In the external service wizard:

  • To connect to an Oracle 10 database using the type 4 driver, select Oracle Thin Driver.

In the administrative console:

Oracle Thin JDBC driver

oracle.jdbc.driver.OracleDriver
Globalized No
Bidi supported No


XA DataSource JNDI name (XADataSourceJNDIName)

This property specifies the JNDI name of the XA data source used to establish a connection to the database.

XA Data source JNDI name details

Required No
Default No default value
Property type String
Usage Use this property to specify the JNDI name of a XA data source in BPM or WebSphere Enterprise Service Bus that specifies connection information for the target database. If the Database connection information (ConnectionType) is set to "XADataSourceJNDI" the adapter uses this property to establish the connection to the database. To improve the performance of outbound operations, specify the name of a data source that is enabled for prepared statement caching. If the other valid authentication properties are also set, they override authentication properties in the data source.
Globalized Yes
Bidi supported No


Oracle E-Business Suite Connection Type (EBSConnectionType)

This property specifies the Oracle E-Business Suite connection type.

Oracle E-Business Suite Connection Type details

Required Yes
Possible values XML Gateway
Property type String
Usage Integrates Oracle E-Business Suite using XML Gateway connection type. If blank, then the run time is for the database operation.
Globalized Yes
Bidi supported No


Oracle E-Business Suite Transport (EBSTransport)

This property specifies the Oracle E-Business Suite transport.

Oracle E-Business Suite Transport details

Required Yes
Possible values Web Service
Property type String
Usage Integrates Oracle E-Business Suite using web Service transport. For XML Gateway process, this property is set as 'XML Gateway', if no value is set, the JDBC connection type is used as default.
Globalized Yes
Bidi supported No


Oracle E-Business Suite Version (EBSVersion)

This property specifies the Oracle E-Business Suite version.

Oracle E-Business Suite Version details

Required Yes
Possible values 11.5, 12.0, 12.1
Property type String
Usage Connects to the selected version of Oracle E-Business Suite.
Globalized Yes
Bidi supported No


Schema Name (EBSSchemaName)

This property specifies the schema name of XML gateway JMS advanced queue.

Schema Name details

Required Yes
Default value applsys
Property type String
Usage Specifies the schema name of XML Gateway JMS Advanced Queue
Globalized No
Bidi supported No


Queue Name (EBSQueueName)

This property specifies the schema name of XML gateway JMS advanced queue.

Queue Name details

Required Yes
Default value wf_jms_in
Property type String
Usage Specifies the XML gateway JMS advanced queue name
Globalized No
Bidi supported No


Port Number (EBSPortNumber)

This property specifies the Oracle E-Business Suite port number when starting the JMS.

Port Number details

Required Yes
Property type Integer
Usage Specifies the Oracle E-Business Suite port number when starting the JMS.
Globalized No
Bidi supported No


Host Name (EBSHostName)

This property specifies the Oracle E-Business Suite host name or IP address when starting the JMS.

Host Name details

Required Yes.
Property type String
Globalized Yes
Bidi supported No


System ID (EBSSystemID)

This property specifies the Oracle E-Business Suite system ID when starting the JMS.

System ID details

Required Yes.
Property type String
Globalized Yes
Bidi supported No


Password (Password)

This property specifies the password required when starting the web service.

Password details

Required If you set the Authentication alias, the password is not mandatory.
Property type String
Usage

If you specify JAAS as the security credential, the authentication alias will override this property.

Globalized Yes
Bidi supported No


Password (Password)

This property specifies the password for the database user name.

Password details

Required No. For inbound processing, if you set the Authentication alias or the DataSourceJNDIName, the password is not mandatory. However, if you set the DataSourceJNDIName, and the Password field, the value specified for the Password takes precedence.

For outbound processing, if you set the Authentication alias, XADataSourceJNDIName or PoolDataSourceJNDIName property, the password is not mandatory. However, if you set the XADataSourceJNDIName or PoolDataSourceJNDIName property, and the Password field, the value specified for the Password takes precedence.

Default No default value
Property type String
Usage For inbound processing, setting this property overrides the password specified for the data source on the server using the Authentication alias or DataSourceJNDIName property.

For outbound processing, setting this property overrides the password specified for the data source on the server using the Authentication alias, or XADataSourceJNDIName or PoolDataSourceJNDIName property.

If you specify JAAS as the security credential, the authentication alias will override this property.

Globalized Yes
Bidi supported Yes


User name (UserName)

This property specifies the database user name used to access the database.

User name details

Required No. For inbound processing, if you set the Authentication alias or the DataSourceJNDIName, the User name property is not mandatory. However, if you set the DataSourceJNDIName, and User name field, the value specified for the User name takes precedence.

For outbound processing, if you set the Authentication alias, XADataSourceJNDIName or PoolDataSourceJNDIName property, the User name is not mandatory. However, if you set the XADataSourceJNDIName or PoolDataSourceJNDIName property, and the User name field, the value specified for the User name takes precedence.

Default No default value
Property type String
Usage For inbound processing setting this property overrides the user name specified for the data source on the server using the DataSourceJNDIName property or the Authentication alias.

For outbound processing, setting this property overrides the user name specified for the data source on the server using the XADataSourceJNDIName property, PoolDataSourceJNDIName property or the Authentication alias.

If you specify JAAS as the security credential, the authentication alias will override this property.

Globalized Yes
Bidi supported Yes


User Name (UserName)

This property specifies the username required when starting the web service.

User Name details

Required If you set the Authentication alias, the User name is not mandatory
Property type String
Usage If you specify JAAS as the security credential, the authentication alias will override this property.
Globalized Yes
Bidi supported No


WSDL URL (WSDLURL)

This property specifies the WSDL URL of the XML Gateway interface.

WSDL URL details

Required Yes
Property type String
Globalized Yes
Bidi supported No



Related tasks:

Set managed (J2C) connection factory properties for embedded adapters

Feedback


Interaction specification properties

Interaction specification, or InteractionSpec, properties control the interaction for an operation. The external service wizard sets the interaction specification properties when you configure the adapter. Typically, you do not need to change these properties. However, some properties for outbound operations can be changed by the user. For example, you might increase the value of the interaction specification property that specifies the maximum number of records to be returned by a RetrieveAll operation, if your RetrieveAll operations do not return complete information. To change these properties after the application is deployed, use the assembly editor in IBM Integration Designer. The properties reside in the method binding of the import.

Table 1 lists and describes the interaction specification property set. For information about how to read the property detail tables in the sections that follow, see Guide to information about properties.

Interaction specification property for the Adapter for Oracle E-Business Suite

Property name Description
Maximum records for RetrieveAll operation Maximum number of result sets to return during a RetrieveAll operation


Maximum records for RetrieveAll operation

This property specifies the maximum number of records to return for a RetrieveAll operation.

Maximum records for RetrieveAll operation details

Required Yes
Default 100
Usage

Use this property to control the number of records returned by the RetrieveAll operation. If the number of matches in the database exceeds the value of this property, the adapter throws the exception MatchesExceededLimitException which is wrappered as a fault, MatchesExceededLimitFault and is returned to the client.

The MatchesExceededLimitFault is stored in the trace file and the MatchesExceededLimitException is not stored in log or trace files.

  • If the value is-1, the RetrieveAll operation returns all records matching the query. The value for this property is set to -1 internally when you select the Return all records for RetrieveAll operation check box.

  • If the value is zero or less than zero except -1, the adapter generates the fault MatchesExceededLimitFault.

  • If the value is greater than zero and the number of matches in the database exceeds the value of this property, the adapter generates the fault MatchesExceededLimitFault. If the RetrieveAll operation does not return all the records, increase this value. For example, if you set the value to 50 and the table contains 100 records, the adapter generates the fault MatchesExceededLimitFault.

  • If the value is greater than zero and the number of matches in the database is lesser than the value of this property, the RetrieveAll operation returns all records. For example, if you set the value to 50 and the table contains 25 records, the RetrieveAll operation returns all the 25 records.

Property type Integer
Globalized No
Bidi supported No



Related tasks:

Change interaction specification properties

Feedback


Inbound configuration properties

WebSphere Adapter for Oracle E-Business Suite has several categories of inbound connection configuration properties, which you set with the external service wizard while generating or creating objects and services. You can change the resource adapter and activation specification properties after you deploy the module using IBM Integration Designer or the administrative console, but connection properties for the external service wizard cannot be changed after deployment.



Related reference:

Outbound configuration properties

Feedback


Connection properties for the wizard

external service wizard connection properties are used to establish a connection between the external service wizard, a tool used to create business objects, and the database.


Feedback


Resource adapter properties

The resource adapter properties control the general operation of the adapter, such as specifying the namespace for business objects. You set the resource adapter properties using the external service wizard when you configure the adapter. After deploying the adapter, use the administrative console to change these properties.

The following table lists the resource adapter properties and their purpose. A complete description of each property is provided in the sections that follow the table. For information about how to read the property details table, see Guide to information about properties.

Resource adapter properties for the Adapter for Oracle E-Business Suite

Name Description
In the wizard In the administrative console
Adapter ID

AdapterID

Identifies the adapter instance for PMI events and for logging and tracing.

Database vendor DatabaseVendor

The type of database the adapter uses for special processing.

Disguise user data as "XXX" in log and trace files HideConfidentialTrace Specifies whether to disguise potentially sensitive information by writing X strings instead of user data in the log and trace files.
Query time out QueryTimeOut

The maximum number of seconds a query can take for all SQL statements.

Return business object even when the stored procedure result set is empty ReturnDummyBOForSP

Specifies whether to return output parameters when the result set is empty.

(Not available) enableHASupport

Do not change this property.

(Not available)

LogFileSize

Deprecated
(Not available)

LogFilename

Deprecated
(Not available)

LogNumberOfFiles

Deprecated
SQL query to verify the connection PingQuery

The SQL query used to test the reliability of the connection to the database.

(Not available)

TraceFileSize

Deprecated
(Not available)

TraceFileName

Deprecated
(Not available)

TraceNumberOfFiles

Deprecated


Adapter ID (AdapterID)

This property identifies a specific deployment or instance of the adapter.

Adapter ID details

Required Yes
Default 001
Property type String
Usage This property identifies the adapter instance in the log and trace files, and also helps identify the adapter instance while monitoring adapters. The adapter ID is used with an adapter-specific identifier, OEBSRA, to form the component name used by the Log and Trace Analyzer tool. For example, if the adapter ID property is set to 001, the component ID is OEBSRA001.

If you run multiple instances of the same adapter, ensure the first seven characters of the adapter ID property are unique for each instance so that you can correlate the log and trace information to a particular adapter instance. By making the first seven characters of an adapter ID property unique, the component ID for multiple instances of that adapter is also unique, allowing you to correlate the log and trace information to a particular instance of an adapter.

For example, when you set the adapter ID property of two instances of WebSphere Adapter for Oracle E-Business Suite to 001 and 002. The component IDs for those instances, OEBSRA001 and OEBSRA002, are short enough to remain unique, enabling you to distinguish them as separate adapter instances. However, instances with longer adapter ID properties cannot be distinguished from each other. If you set the adapter ID properties of two instances to Instance01 and Instance02, you will not be able to examine the log and trace information for each adapter instance because the component ID for both instances is truncated to OEBSRAInstanc.

For inbound processing, the value of this property is set at the resource adapter level. For outbound processing, the value can be set both at the resource adapter level and the managed connection factory level. After use the external service wizard to configure the adapter for outbound processing, you can set the resource adapter and managed connection factory properties independently. If using the IBM Integration Designer assembly editor or the administrative console to reset these properties, ensure set them consistently, to prevent inconsistent marking of the log and trace entries.

Globalized Yes
Bidi supported No


Database vendor (DatabaseVendor)

This property specifies the type of database used. The type is determined by the database vendor name.

Database vendor details

Required Yes
Possible values

Oracle

Default ORACLE
Property type String
Usage

Some SQL statements require special processing, which varies by database type. For example, the Struct and Array data types in Oracle require special processing. This property specifies the RDBMS used, which determines the database type.

For other databases, the adapter does not perform any special processing. Verify the correct driver is specified in the JDBCDriverClass property.

Specify Oracle as the value corresponding to the database vendor.

Globalized No
Bidi supported No


Disguise user data as "XXX" in log and trace files (HideConfidentialTrace)

This property specifies whether to replace user data in log and trace files with a string of X's to prevent unauthorized disclosure of potentially sensitive data.

Disguise user data as "XXX" in log and trace files details

Required No
Possible values

True False

Default False
Property type Boolean
Usage If you set this property to True, the adapter replaces user data with a string of X's when writing to log and trace files.

For inbound processing, the value of this property is set at the resource adapter level. For outbound processing, the value can be set both at the resource adapter level and the managed connection factory level. After use the external service wizard to configure the adapter for outbound processing, you can set the resource adapter and managed connection factory properties independently. If using the IBM Integration Designer assembly editor or the administrative console to reset these properties, ensure set them consistently, to prevent inconsistent marking of the log and trace entries.

Globalized No
Bidi supported No


Enable high availability support (enableHASupport)

Do not change this property. It must be set to true.


Query timeout (seconds) (QueryTimeOut)

This property specifies the maximum number of seconds a query can take to run all SQL statements.

Query timeout details

Required No
Default No default value
Unit of measure Seconds
Property type Integer
Usage If the query takes longer than the number of seconds specified, the database generates an SQL exception that is captured. The associated message is logged in the log file.

If a value is not specified, no timeout is set on the query.

Globalized No
Bidi supported No


Return business object even when the stored procedure result set is empty (ReturnDummyBOForSP)

This property specifies whether to return output parameters when the result set is empty.

Return business object even when the stored procedure result set is empty details

Required No
Possible values

True False

Default False
Property type Boolean
Usage

The Retrieve Stored Procedure (RetrieveSP) operation returns a result set. If the result set is empty and the ReturnDummyBOForSP property is set to False, no business objects are created, and the output parameters returned by the procedure call cannot be retrieved.

However, if the ReturnDummyBOForSP property is set to True, a dummy business object is created and the returned parameters (including the out and inout parameters) from the stored procedure are populated into the corresponding attributes

Globalized No
Bidi supported No


SQL query to verify the connection (PingQuery)

This property specifies the SQL query used to test the reliability of the connection to the database.

Ping query details

Required No
Property type String
Default No default value
Usage

This property contains the SQL query statement to run to determine whether the adapter can connect to the database.

The adapter runs the ping query every time it receives a SQLException exception while performing the outbound operation.

The adapter does not try to recover the connection. If the ping query indicates the connection to the database is no longer valid, the adapter notifies the container. It is the responsibility of the connection pool manager to remove the stale connection from the pool, which allows subsequent outbound requests to be processed.

Globalized No
Bidi supported No


Feedback


Activation specification properties

Activation specification properties are properties that hold the inbound event processing configuration information for an export.

You set activation specification properties using the external service wizard during adapter configuration and can change them using the IBM Integration Designer assembly editor or, after deployment, the BPM or WebSphere Enterprise Service Bus administrative console.

The following table lists and describes the activation specification properties. A complete description of each property is provided in the sections that follow the table. For information about how to read the property detail tables in the sections that follow, see Guide to information about properties.

Activation specification properties for Adapter for Oracle E-Business Suite

Property name Description
In the wizard In the administrative console
Adapter Instance for event filtering AdapterInstanceEventFilter Identifier that determines whether this adapter instance processes specific events in the event store.
Additional JDBC driver connection properties [name:value;name:value] JDBCDriverConnectionProperties

Additional properties for connecting to the database using the JDBC driver, which are used in addition to the UserName and Password properties.

Business object namespace BusinessObjectNameSpace The namespace for the business object definitions
User-defined delete query CustomDeleteQuery The name of the query, stored procedure, or stored function that is run after each event is processed to delete records that can be deleted after the event is delivered.
User-defined event query CustomEventQuery The name of the query, stored procedure, or stored function that performs the polling for events.
User-defined update query CustomUpdateQuery The name of the query, stored procedure, or stored function that is run after each event is processed to prevent the event from being picked up for processing in a subsequent event cycle.
User-defined update query for failed event delivery CustomUpdateQueryForFailedEvent The name of the query, stored procedure, or stored function that is run when an event is not delivered successfully.
Data source JNDI name DataSourceJNDIName

The name of the JNDI data source used to establish a connection to the database.

Database URL DatabaseURL

The database URL used to connect to the database.

Database vendor DatabaseVendor

The type of database the adapter uses for special processing.

Do not process events that have a timestamp in the future

FilterFutureEvents

Specifies whether the adapter filters out future events by comparing the timestamp on each event with the system time.

Ensure once-only event delivery

AssuredOnceDelivery

Specifies whether the adapter provides assured once delivery of events.

Event order by EventOrderBy The order in which events are retrieved and processed
Event query type EventQueryType Determines whether to use the standard event store or custom query
Event table name EventTableName Name of the database table that contains events generated by the database for inbound processing
Event types to process

EventTypeFilter

A delimited list of event types that indicates to the adapter which events it should deliver. The adapter supports event filtering based on operations, in addition to the BO Name.

Retry limit for failed events FailedEventRetryLimit The number of times the adapter attempts to redeliver an event before marking the event as failed.
Interval between polling periods

PollPeriod

The length of time the adapter waits between polling periods.

JDBC driver class JDBCDriverClass

The class name of the JDBC driver used to connect to the database.

Maximum connections

MaximumConnections

The maximum number of connections the adapter can use for inbound event delivery.

Minimum connections

MinimumConnections

The minimum number of connections the adapter can use for inbound event delivery.

Maximum number of retries in case of system connection failure

RetryLimit

The number of times the adapter tries to reestablish an inbound connection after an error.

Password Password

Password for authorizing the user to retrieve events from the database.

Poll quantity

PollQuantity

The number of events the adapter delivers to the export during each poll period.

Query time out QueryTimeOut

The maximum number of seconds a query can take for all SQL statements.

Retry EIS connection on startup RetryConnectionOnStartup

Controls whether the adapter retries the connection to the Oracle database if it cannot connect at startup.

Time between retries in case of system connection failure (milliseconds)

RetryInterval

The length of time the adapter waits between attempts to reestablish connection after an error during inbound operations.

Return dummy business object for RetrieveSP ReturnDummyBOForSP

Specifies whether to return output parameters when the result set is empty.

SQL query to verify the connection PingQuery

The SQL query used to test the reliability of the connection to the database.

Stop the adapter when an error is encountered while polling

StopPollingOnError

Specifies whether the adapter stops polling for events when it encounters an error during polling.

Stored procedure to run after polling SPAfterPoll The name of the stored procedure to be run after each poll cycle
Stored procedure to run before polling SPBeforePoll The name of the stored procedure to be run before the actual poll query is called
Type of delivery

DeliveryType

Determines the order in which events are delivered by the adapter to the export.

User name UserName The database user name to use for inbound events
Database connection information (ConnectionType) ConnectionType Specifies how the adapter establishes connection to the database.
Advanced Queue Dequeue Condition dequeueCondition The conditional expression based on the message properties, message data properties, and PL/SQL functions.
Advanced Queue Correlation ID correlationID Specifies the correlation identifier of the message to be dequeued.
Advanced Queue Consumer Name consumerName Consumer name based on which messages are dequeued.
Staging data source JNDI stagingDataSourceJNDIName Name of the JNDI data source used to connect to the staging table.
Staging event table stagingEventTableName Name of the staging event table to be created at run time.
Dequeue using dequeueMechanism Dequeue mechanism used for the dequeue operation.


Adapter Instance for event filtering (AdapterInstanceEventFilter)

This property controls whether the adapter instance processes specific events in the event store.

Adapter Instance for event filtering details

Required No
Default null
Property type String
Usage This property helps you migrate from WebSphere Business Integration Adapter for Oracle Applications to WebSphere Adapter for Oracle E-Business Suite. WebSphere Business Integration Adapter for Oracle Applications allows you to perform load balancing on high-volume event types by allowing multiple adapter instances to process events of the same type. When load balancing is not required, a single adapter instance processes all events of a given type. This property is to enable seamless migration for WBIA customers to JCA for customers who are currently taking advantage of the connectorID filtering.

WebSphere Adapter for Oracle E-Business Suite typically does not require load balancing in this way, but supports it so that you can migrate without modifying the database triggers or other mechanisms that write events to the event store.

The AdapterInstanceEventFilter property corresponds to the ConnectorID property of the WebSphere Business Integration Adapter for Oracle Applications.

To use this feature, the database triggers or other mechanisms that create events in the event store must assign the appropriate value to the connectorId column.

Table 3 shows the interaction between the AdapterInstanceEventFilter property and the value in the connectorId column in the event store.

If the EventTypeFilter and AdapterInstanceEventFilter properties are both set, the adapter processes only events that meet both criteria. That is, it processes only those events whose type is specified in the EventTypeFilter property and whose connectorId column matches the AdapterInstanceEventFilter property.

Example See Table 3.
Globalized Yes
Bidi supported Yes

Interaction of the AdapterInstanceEventFilter property with the connectorId column in the event store

AdapterInstanceEventFilter property connectorId column of an event Result
null null The adapter processes the event.
null Instance1 The adapter processes the event, because the connectorId column is not checked.
Instance1 Instance1 The adapter processes the event.
Instance1 Instance2 The adapter does not process the event, because the instance IDs do not match.
Instance1 null The adapter does not process the event, because the instance IDs do not match.


Additional JDBC driver connection properties [name:value;name:value] (JDBCDriverConnectionProperties)

This property contains additional information for connecting to the database using the JDBC driver.

Additional JDBC driver connection properties details

Row Explanation
Required No
Possible values Database connection properties are database-specific.
Default No default value
Property type String
Usage These connection properties are used in addition to the UserName and Password properties to customize the database connection used by the adapter.

Set the connection properties as one or more name:value pairs separated by the semicolon character (;).

Example

The following value of this property specifies a login timeout interval:

    loginTimeout:20; ConnectionRetryCount:5; ConnectionRetryDelay:5

Globalized Yes
Bidi supported No


Business object namespace (BusinessObjectNameSpace)

This property specifies the namespace for the business object definitions.

Business object namespace property characteristics

Required

No

Default http://www.ibm.com/xmlns/prod/websphere/j2ca/oracle
Property type String
Usage

This value is added as a prefix to the business object name to keep business object names logically separated.

Example

The following example shows the Schema1Customer business object with the default namespace: http://www.ibm.com/xmlns/prod/websphere/j2ca/oracle/Schema1Customer

Bidi supported No


User-defined delete query (CustomDeleteQuery)

Use this property to specify the SQL statement, stored procedure, or stored function to run after each event is processed to delete records that can be deleted after the event is delivered.

Custom delete query details

Required No
Default No default value
Property type String
Usage Use this property to specify the SQL statement, stored procedure, or stored function to run when the EventQueryType property is set to Dynamic.
Globalized Yes
Bidi supported Yes


User-defined update query for failed event delivery (CustomUpdateQueryForFailedEvent)

Use this property to specify the SQL statement, stored procedure, or stored function to run to update event status when an event is not delivered successfully.

Custom update query for failed event details

Required No
Default No default value
Property type String
Usage Use this property to specify the SQL statement, stored procedure, or stored function to run when the EventQueryType property is set to Dynamic.

If an event is delivered successfully, the property User-defined update query (CustomUpdateQuery) is used to update event status. If an event is not delivered successfully, the property User-defined update query for failed event delivery (CustomUpdateQueryForFailedEvent) is used to update event status.

Globalized Yes
Bidi supported Yes


User-defined event query (CustomEventQuery)

Use this property to specify the SQL statement, stored procedure, or stored function to run to poll for events in custom event processing.

Custom event query details

Required No
Default No default value
Property type String
Usage Use this property to specify the SQL statement, stored procedure, or stored function to run during each poll cycle when the EventQueryType property is set to Dynamic.
Examples In the following example, the custom event query runs an SQL statement that returns the event ID, object key, and object name of every record in the MY_EVENT_TABLE event store whose status column has the value 0:

    select event_id, object_key, object_name from MY_EVENT_TABLE where status = 0

The following example limits the returned event records to the value of the PollQuantity property:

select event_id, object_key, object_name from MY_EVENT_TABLEwhere status = 0
and rownum < POLL QUANTITY

The following example runs a stored procedure with two parameters:

    CALL MY_EVENT_STORED_PROC (?,?)

The following example runs a stored function with one parameter and one return value:

    ? = CALL MY_EVENT_FUNCTION(?)

Globalized Yes
Bidi supported Yes


User-defined update query (CustomUpdateQuery)

Use this property to specify the SQL statement, stored procedure, or stored function to run after each event is processed so the same event does not get picked up for processing in the subsequent event cycle.

Custom update query details

Required No
Default No default value
Property type String
Usage Use this property to specify the SQL statement, stored procedure, or stored function to run when the EventQueryType property is set to Dynamic.
Globalized Yes
Bidi supported Yes


Data source JNDI name (DataSourceJNDIName)

This property specifies the name of the JNDI data source to use to establish a connection to the database.

Data source JNDI name details

Required No
Default No default value
Property type String
Usage Use this property to specify the JNDI name of a data source in IBM Business Process Manager or WebSphere Enterprise Service Bus that specifies connection information for the target database.

To improve the performance of inbound or outbound operations, specify the name of a data source that is enabled for prepared statement caching.

If the UserName and Password properties are also set, they override the user name and password in the data source.

Do not confuse the data source JNDI name property with the JNDI name of a managed connection factory or activation specification on the server. The following list highlights important differences between the types of JNDI names:

  • Data source JNDI name

    • Specifies a connection to a database
    • Is used instead of saving user name and password in adapter properties
    • Is saved as an adapter property

  • JNDI name of the managed connection factory or activation specification

    • Specifies a connection to a managed connection factory or activation specification on the server
    • Is used instead of specifying the value of each managed connection factory or activation specification property in the wizard
    • Is saved as the connection target in the import file

Globalized Yes
Bidi supported No


Database URL (DatabaseURL)

This property specifies the JDBC driver-specific URL for creating a connection to the database.

Database URL details

Required Yes, when the connection is of the type LocalConnectionProps or ConnectionProps.
Default No default value
Property type String
Usage In the external service wizard, compose the database URL by entering in database-specific fields. For example, the database URL for an Oracle database is composed of the system ID (SID), server host name, and database port number. In the administrative console, type the complete database URL value.

If the database server supports IPv6, you can specify the host name portion of the database URL in IPv6 format.

If you specify the host name as an IP address in IPv6 format, enclose the IP address in square brackets ([]).

Examples

The following example illustrates typical database URL values for a common database:jdbc:oracle:thin:@9.26.248.148:1521:dev

Globalized Yes
Bidi supported Yes


Database vendor (DatabaseVendor)

This property specifies the type of database used. The type is determined by the database vendor name.

Database vendor details

Required Yes
Possible values

Oracle

Default ORACLE
Property type String
Usage

Some SQL statements require special processing, which varies by database type. For example, the Struct and Array data types in Oracle require special processing. This property specifies the RDBMS used, which determines the database type.

For other databases, the adapter does not perform any special processing. Verify the correct driver is specified in the JDBCDriverClass property.

Specify Oracle as the value corresponding to the database vendor.

Globalized No
Bidi supported No


Delivery type (DeliveryType)

This property specifies the order in which events are delivered by the adapter to the export.

Delivery type details

Required No
Possible values

ORDERED UNORDERED ORDEREDBYKEY

Default ORDERED
Property type String
Usage The following values are supported:

  • ORDERED: The adapter delivers events to the export one at a time.
  • UNORDERED: The adapter delivers all events to the export at once.
  • ORDEREDBYKEY: The adapter delivers all events simultaneously except for the matching event keys. The events with matching keys are delivered to the export one at a time. In advanced queue inbound, the behaviour of ORDEREDBYKEY delivery is the same as the ORDERED delivery as there is no sorting based on key carried out before delivery.

Globalized No
Bidi supported No


Do not process events that have a timestamp in the future (FilterFutureEvents)

This property specifies whether the adapter filters out future events by comparing the timestamp on each event with the system time.

Do not process events that have a timestamp in the future details

Required Yes
Possible values

True False

Default False
Property type Boolean
Usage

If set to True, the adapter compares the time of each event to the system time. If the event time is later than the system time, the event is not delivered.

If set to False, the adapter delivers all events.

Globalized No
Bidi supported No


Ensure once-only event delivery (AssuredOnceDelivery)

This property specifies whether to provide ensure once-only event delivery for inbound events.

Ensure once-only event delivery details

Required Yes
Possible values

True False

Default True
Property type Boolean
Usage When this property is set to True, the adapter provides assured once event delivery. This means that each event is delivered once and only once. A value of False does not provide assured once event delivery, but provides better performance.

When this property is set to True, the adapter attempts to store transaction (XID) information in the event store. If it is set to False, the adapter does not attempt to store the information.

This property is used only if the export component is transactional. If it is not, no transaction can be used, regardless of the value of this property.

Globalized No
Bidi supported No


Event order by (EventOrderBy)

The order in which events are retrieved and processed.

Event order by details

Required No
Possible values A comma-separated (,) list of column names in the event store, and the order attributes asc and desc
Default event_time, event_priority
Property type String
Usage Specify a comma-separated list of column names from the event store, with the optional attributes for ascending or descending order.
Examples To present events ordered first by time and then by priority, specify:

    event_time, event_priority

To present events ordered first by object name in ascending order and then by event time in descending order, specify:

    object_name asc, event_time desc

Globalized Yes
Bidi supported Yes


Event query type (EventQueryType)

This property specifies whether to use standard or custom query processing.

Event query type details

Required Yes
Possible values

Standard Dynamic

Default Standard
Property type String
Usage

The valid values are Standard, for standard event processing, and Dynamic, for custom event processing.

If set to Dynamic, the CustomEventQuery, CustomUpdateQuery, and CustomDeleteQuery properties are used. If set to Standard, those properties are ignored.

Globalized No
Bidi supported No


Event table name (EventTableName)

This property specifies the name of the table in the target database that contains the event store, which is used for inbound processing.

Event table name details

Required Yes
Default WBIA_Oracle_EventStore
Property type String
Usage Create the event store before starting to configure the adapter.

For standard event processing, the event is generated by the database through a trigger or other mechanism. For custom query processing, the adapter saves events in the event store as it receives the result of the custom queries.

Globalized Yes
Bidi supported Yes


Event types to process (EventTypeFilter)

This property contains a delimited list of event types that indicates to the adapter which events it should deliver.

Event types to process details

Required No
Possible values

A comma-delimited (,) list of business object types

Default null
Property type String
Usage Events are filtered by business object type and operations. If the property is set, the adapter delivers only those events that are in the list. A value of null or * indicates that no filter will be applied and that all events will be delivered to the export.

When the default operation set (Create/Update/Delete) is not preferred, the adapter will provide an operation-based event polling capability.

For example:

If you select Create|Update operation, the adapter will poll only those events with Create or Update operation for all the BOs. The default string generated for eventTypeFilter is *: Create|Update.

Syntax: BOName:Operation1|Operation2, BOName:Operation1|Operation2|Operation3

  • "," is used for separating the business objects. The objects not in this list are ignored.
  • ":" is used for separating the business object name and the operation name.
  • "|" is used for separating the supported operations, such as Create, Delete, and Update.

Example

To receive events related to the Customer and Order business objects only, specify this value: Customer,Order

  • To receive events related to the Customer and Order business objects regardless of operations, specify this value: Customer,Order or specify this value for all supported operations: Customer:Create|Update|Delete,Order:Create|Update|Delete.
  • To receive all events of the Customer business object and the Create and Delete events of the Order business object, specify this value: Customer,Order:Create|Delete
  • To receive the Create and Delete events of all the business objects, specify this value: *:Create|Delete.

In this property, you can use only those operations that are chosen while selecting business objects and services.

If the EventTypeFilter and AdapterInstanceEventFilter properties are both set, the adapter processes only events that meet both criteria. That is, it processes only those events whose type is specified in the EventTypeFilter property and whose connectorId column matches the AdapterInstanceEventFilter property.

Globalized No
Bidi supported No


Retry limit for failed events (FailedEventRetryLimit)

This property specifies the number of times the adapter attempts to redeliver an event before marking the event as failed.

Retry limit for failed events details

Required No
Possible values Integers
Default 5
Property type Integer
Usage Use this property to control how many times the adapter tries to send an event before marking it as failed. It accepts the following values:

Default

If this property is not set, the adapter tries five additional times before marking the event as failed.

0

The adapter tries to deliver the event an infinite number of times. When the property is set to 0, the event remains in the event store, and the event is never marked as failed.

> 0

For integers greater than zero, the adapter retries the specified number of times before marking the event as failed.

< 0

For negative integers, the adapter does not retry failed events.
Globalized No
Bidi supported No


JDBC driver class (JDBCDriverClass)

This property specifies the class name of the JDBC driver used to connect to the database.

JDBC driver class details

Row Explanation
Required Yes, when the connection is of the type LocalConnectionProps or ConnectionProps.
Possible values

The value specified when you set the connection properties to connect to the database instance.

Default No default value
Property type String
Usage In the external service wizard, the JDBC driver class is displayed if you select a common database software and driver combination, such as type 4 drivers for recent versions of Oracle. For type 2 drivers , you must type the database class name.

If you select a type 2 driver or a generic driver, you must type the JDBC driver class name.

In the administrative console, type the database-specific name of the driver.

Examples

Values for the JDBC driver class is displayed in both the external service wizard and the administrative console. The following examples depict the JDBC driver class properties in both the external service wizard and the administrative console. In the external service wizard:

  • To connect to an Oracle 10 database using the type 4 driver, select Oracle Thin Driver.

In the administrative console:

Oracle Thin JDBC driver

oracle.jdbc.driver.OracleDriver
Globalized No
Bidi supported No


Maximum connections (MaximumConnections)

This property specifies the maximum number of connections the adapter can use for inbound event delivery.

Maximum connections details

Required No
Default 1
Property type Integer
Usage Only positive values are valid. Any value less than 1 is treated as 1 by the adapter.
Globalized No
Bidi supported No


Minimum connections (MinimumConnections)

This property specifies the minimum number of connections the adapter can use for inbound event delivery.

Minimum connections details

Required No
Default 1
Property type Integer
Usage Only positive values are valid. Any value less than 1 is treated as 1 by the adapter.
Globalized No
Bidi supported No


Password (Password)

This property specifies the password for the database user name.

Password details

Required No. For inbound processing, if you set the Authentication alias or the DataSourceJNDIName, the password is not mandatory. However, if you set the DataSourceJNDIName, and the Password field, the value specified for the Password takes precedence.

For outbound processing, if you set the Authentication alias, XADataSourceJNDIName or PoolDataSourceJNDIName property, the password is not mandatory. However, if you set the XADataSourceJNDIName or PoolDataSourceJNDIName property, and the Password field, the value specified for the Password takes precedence.

Default No default value
Property type String
Usage For inbound processing, setting this property overrides the password specified for the data source on the server using the Authentication alias or DataSourceJNDIName property.

For outbound processing, setting this property overrides the password specified for the data source on the server using the Authentication alias, or XADataSourceJNDIName or PoolDataSourceJNDIName property.

If you specify JAAS as the security credential, the authentication alias will override this property.

Globalized Yes
Bidi supported Yes


SQL query to verify the connection (PingQuery)

This property specifies the SQL query used to test the reliability of the connection to the database.

Ping query details

Required No
Property type String
Default No default value
Usage

This property contains the SQL query statement to run to determine whether the adapter can connect to the database.

The adapter runs the ping query every time it receives a SQLException exception while performing the outbound operation.

The adapter does not try to recover the connection. If the ping query indicates the connection to the database is no longer valid, the adapter notifies the container. It is the responsibility of the connection pool manager to remove the stale connection from the pool, which allows subsequent outbound requests to be processed.

Globalized No
Bidi supported No


Interval between polling periods (PollPeriod)

This property specifies the length of time the adapter waits between polling periods.

Interval between polling periods details

Required Yes
Possible values Integers greater than or equal to 0.
Default 2000
Unit of measure Milliseconds
Property type Integer
Usage The poll period is established at a fixed rate, which means that if running the poll cycle is delayed for any reason ( if a prior poll cycle takes longer than expected to complete) the next poll cycle occurs immediately to make up for the lost time caused by the delay.
Globalized No
Bidi supported No


Maximum events in polling period (PollQuantity)

This property specifies the number of events the adapter delivers to the export during each poll period.

Maximum events in polling period details

Required Yes
Default 10
Property type Integer
Usage The value must be greater than 0. If this value is increased, more events are processed per polling period and the adapter may perform less efficiently. If this value is decreased, fewer events are processed per polling period and the adapter's performance might improve slightly.
Globalized No
Bidi supported No


Query timeout (seconds) (QueryTimeOut)

This property specifies the maximum number of seconds a query can take to run all SQL statements.

Query timeout details

Required No
Default No default value
Unit of measure Seconds
Property type Integer
Usage If the query takes longer than the number of seconds specified, the database generates an SQL exception that is captured. The associated message is logged in the log file.

If a value is not specified, no timeout is set on the query.

Globalized No
Bidi supported No


Time between retries in case of system connection failure (RetryInterval)

When the adapter encounters an error related to the inbound connection, this property specifies the length of time the adapter waits before trying to reestablish a connection.

Retry interval details

Required Yes
Default 2000
Unit of measure Milliseconds
Property type Integer
Usage Only positive values are valid. When the adapter encounters an error related to the inbound connection, this property specifies the length of time the adapter waits before trying to establish a new connection.
Globalized No
Bidi supported No


Maximum number of retries in case of system connection failure (RetryLimit)

This property specifies the number of times the adapter tries to reestablish an inbound connection.

Maximum number of retries in case of system connection failure

Required No
Possible values 0 and positive integers
Default 0
Property type Integer
Usage

This property controls how many times the adapter retries the connection if the adapter cannot connect to the Oracle database to perform inbound processing. A value of 0 indicates an infinite number of retries.

To control whether the adapter retries if it cannot connect to the Oracle database when it is first started, use the RetryConnectionOnStartup property.

Globalized No
Bidi supported No


Retry EIS connection on startup (RetryConnectionOnStartup)

This property controls whether the adapter attempts to connect again to the Oracle database if it cannot connect at startup.

Retry EIS connection on startup details

Required No
Possible values

True False

Default False
Property type Boolean
Usage This property indicates whether the adapter should retry the connection to the Oracle database if the connection cannot be made when the adapter is started:

  • Set the property to False when you want immediate feedback about whether the adapter can establish a connection to the Oracle database, for example, when you are building and testing the application that receives events from the adapter. If the adapter cannot connect, the adapter writes log and trace information and stops. The administrative console shows the application status as Stopped. After you resolve the connection problem, start the adapter manually.

  • Set the property to True if you do not need immediate feedback about the connection. If the adapter cannot connect during startup, it writes log and trace information, and then attempts to reconnect, using the RetryInterval property to determine how frequently to retry and the value of the RetryLimit property to retry multiple times until that value is reached. The administrative console shows the application status as Started.

Globalized No
Bidi supported No


Return business object even when the stored procedure result set is empty (ReturnDummyBOForSP)

This property specifies whether to return output parameters when the result set is empty.

Return business object even when the stored procedure result set is empty details

Required No
Possible values

True False

Default False
Property type Boolean
Usage

The Retrieve Stored Procedure (RetrieveSP) operation returns a result set. If the result set is empty and the ReturnDummyBOForSP property is set to False, no business objects are created, and the output parameters returned by the procedure call cannot be retrieved.

However, if the ReturnDummyBOForSP property is set to True, a dummy business object is created and the returned parameters (including the out and inout parameters) from the stored procedure are populated into the corresponding attributes

Globalized No
Bidi supported No


Stop the adapter when an error is encountered while polling (StopPollingOnError)

This property specifies whether the adapter will stop polling for events when it encounters an error during polling.

Stop the adapter when an error is encountered while polling details

Required No
Possible values

True False

Default False
Property type Boolean
Usage

If set to True, the adapter stops polling when it encounters an error.

If set to False, the adapter logs an exception when it encounters an error during polling and continues polling.

Globalized No
Bidi supported No


Stored procedure to run after polling (SPAfterPoll)

This property specifies the name of the stored procedure or stored function to run after each polling cycle.

Stored procedure to run after poll details

Required No
Default No default value
Property type String
Usage The stored procedure takes one parameter for poll quantity.
Globalized Yes
Bidi supported Yes


Stored procedure to run before polling (SPBeforePoll)

This property specifies the name of any stored procedure or stored function to run before the actual poll query is called.

Stored procedure to run before poll details

Required No
Default No default value
Property type String
Usage The stored procedure takes one parameter for poll quantity.
Globalized Yes
Bidi supported Yes


User name (UserName)

This property specifies the database user name used to access the database.

User name details

Required No. For inbound processing, if you set the Authentication alias or the DataSourceJNDIName, the User name property is not mandatory. However, if you set the DataSourceJNDIName, and User name field, the value specified for the User name takes precedence.

For outbound processing, if you set the Authentication alias, XADataSourceJNDIName or PoolDataSourceJNDIName property, the User name is not mandatory. However, if you set the XADataSourceJNDIName or PoolDataSourceJNDIName property, and the User name field, the value specified for the User name takes precedence.

Default No default value
Property type String
Usage For inbound processing setting this property overrides the user name specified for the data source on the server using the DataSourceJNDIName property or the Authentication alias.

For outbound processing, setting this property overrides the user name specified for the data source on the server using the XADataSourceJNDIName property, PoolDataSourceJNDIName property or the Authentication alias.

If you specify JAAS as the security credential, the authentication alias will override this property.

Globalized Yes
Bidi supported Yes


Database connection information (ConnectionType)

This property specifies how the adapter establishes connection to the database.

Database connection information

Required Yes
Possible values ConnectionProps or DataSourceJNDI
Default ConnectionProps
Property type String
Usage This property specifies how adapter establish database connection at run time. This property can have the following values:

  • ConnectionProps - Indicates the database connection is established using the DatabaseURL and JDBCDriverClass properties.
  • DataSourceJNDI - Indicates the database connection is established using the DataSourceJNDIName property corresponding to predefined data source.

For a new application, this property is automatically set by external service wizard. For a migrated application, this property is set during the migration process according to the ActivationSpecification properties.

  • If the DataSourceJNDIName property is set, the value of this property is set to DataSourceJNDI.

  • If the DataSourceName is set, the value of this property is set to ConnectionProps.

If this property is not set, adapter uses compatibility with an earlier version mode to establish database connection. In compatibility with an earlier version mode, the properties for connecting to the database are used in the following order:

  1. If the DataSourceJNDIName property is set, the adapter uses it to establish the connection to the database.

  2. If the DataSourceJNDIName is not set, then the adapter uses the DatabaseURL, JDBCDriverClass, UserName and Password properties to establish the connection.

Globalized No
Bidi supported No


Advanced Queue Dequeue Condition

This property specifies the conditional expression based on the message properties, message data properties, and PL/SQL function.

Advanced Queue Dequeue Condition

Required No
Default No default value
Property type String
Usage A dequeue condition is specified as a Boolean expression that can include conditions on message properties, and PL/SQL or SQL functions (as specified in the WHERE clause of a SQL query). Message properties include priority, expiration, and other columns in the queue table. The dequeue condition parameter cannot exceed 4000 characters. If more than one message satisfies the dequeue condition, the order of dequeuing is undetermined.

Example: PRIORITY=1

Globalized Yes
Bidi supported Yes


Advanced Queue Correlation ID

Specifies the correlation identifier of the message to be dequeued.

Advanced Queue Correlation ID (correlation)

Required No
Default No default value
Property type String
Usage Identifier that was used during enqueuing of a message. The string can contain special characters like percent (%) and underscore (_).
Globalized Yes
Bidi supported Yes


Advanced Queue Consumer Name

Consumer name based on which messages are dequeued.

Advanced Queue Consumer Name

Required Yes
Default No default value
Property type String
Usage Name of the consumer or recipient. Setting the recipient or consumer name is mandatory while enqueuing a message as messages are dequeued based on this name.
Globalized Yes
Bidi supported Yes


Staging data source JNDI

The JNDI name of the data source used to connect to the staging table.

Staging data source JNDI

Required Yes
Default No default value
Property type String
Usage The JNDI name of the data source to be used to establish a connection to the database. The data source must be created in the administrative console.
Globalized Yes
Bidi supported Yes


Staging event table

Name of the staging event table to be created at run time.

Staging event table

Required Yes
Default No default value
Property type String
Usage Name of the database table that stores events that are fetched from the Oracle Advanced Queue for inbound processing. This is the temporary table where the adapter stores the events during the dequeue operation.
Globalized Yes
Bidi supported Yes


Dequeue using

Dequeue mechanism used for the dequeue operation.

Dequeue using

Required Yes
Default PL/SQL
Property type String
Possible values PL/SQL or JMS
Usage The adapter internally uses the selected dequeue mechanism to dequeue messages from the Oracle Advanced Queue. If the dequeue mechanism is PL/SQL, the adapter creates a wrapper procedure during run time to dequeue events from the Advanced Queue. If the dequeue mechanism is JMS, the adapter uses the corresponding API to dequeue events.
Globalized Yes
Bidi supported Yes


Feedback


Globalization

WebSphere Adapter for Oracle E-Business Suite is a globalized application that can be used in multiple linguistic and cultural environments. Based on character set support and the locale of the host server, the adapter delivers message text in the appropriate language. The adapter supports bidirectional script data transformation between integration components.


Feedback


Globalization and bidirectional transformation

The adapter is globalized to support single and multibyte character sets and deliver message text in the specified language. The adapter also performs bidirectional transformation, which refers to the task of processing data that contains both right-to-left (Hebrew or Arabic, for example) and left-to-right (a URL or file path, for example) semantic content within the same file.


Globalization

Globalized software applications are designed and developed for use within multiple linguistic and cultural environments rather than a single environment. WebSphere Adapters, IBM Integration Designer, IBM Business Process Manager or WebSphere Enterprise Service Bus are written in Java™. The Java run time environment within the Java virtual machine (JVM) represents data in the Unicode character code set. Unicode contains encoding for characters in most known character code sets (both single- and multi-byte). Therefore, when data is transferred between these integration system components, there is no need for character conversion.

To log error and informational messages in the appropriate language and for the appropriate country or region, the adapter uses the locale of the system on which it is running.


Bidirectional transformation

Languages such as Arabic and Hebrew are written from right to left, yet they contain embedded segments of text that are written left to right, resulting in bidirectional script. There are multiple ways that a software application might display and process bidirectional script. IBM Business Process Manager or WebSphere Enterprise Service Bus uses the Windows standard format, but an enterprise information system exchanging data with BPM or WebSphere Enterprise Service Bus can use a different format. WebSphere Adapters transform bidirectional script data is passed between the two systems so that it is accurately processed and displayed on both sides of a transaction.

Bidirectional format

IBM Business Process Manager or WebSphere Enterprise Service Bus uses the bidirectional format of ILYNN (implicit, left-to-right, on, off, nominal). This is the format used by Windows. If an enterprise information system uses a different format, the adapter converts the format before introducing the data to IBM Business Process Manager or WebSphere Enterprise Service Bus.

The bidirectional format consists of five attributes. When you set bidirectional properties, you assign values for each of these attributes. The attributes and settings are listed in the following table.

Bidirectional format attributes

Letter position Purpose Values Description Default setting
1 Order schema I Implicit (Logical) I
V Visual
2 Direction L Left-to-Right L
R Right-to-Left
C Contextual Left-to-Right
D Contextual Right-to-Left
3 Symmetric Swapping Y Symmetric swapping is on Y
N Symmetric swapping is off
4 Text Shaping S Text is shaped N
N Text is not shaped (Nominal)
I Initial shaping
M Middle shaping
F Final shaping
B Isolated shaping
5 Numeric Shaping H National (Hindi) N
C Contextual shaping
N Numbers are not shaped (Nominal)

The adapter transforms data into a logical, left-to-right format before sending the data to IBM Business Process Manager or WebSphere Enterprise Service Bus.

Use bidirectional properties

You can use multiple bidirectional properties to control the transformation of both content data and metadata. You can set special bidirectional properties to exclude either content data or metadata from bidirectional transformation, or to identify data that requires special treatment during a transformation.

The following table describes the types of bidirectional properties.

Bidirectional property types

Property type Data transformations
EIS Controls the format for content data, or data that is sent by the enterprise information system, which is, the database.
Metadata Controls the format for metadata, or data that provides information about the content data.
Skip Identifies content or metadata to exclude from transformation.
Special Format Identifies certain text, such as file paths or URLs, which require different treatment during the transformation process. Can be set for either content data or metadata.

You can set properties that control bidirectional transformation in the following areas:

Property scope and lookup mechanism

After you set values for bidirectional properties for an adapter, the adapter performs bidirectional transformations. It does so by using logic that relies on a hierarchical inheritance of property settings and a lookup mechanism.

Properties defined within the resource adapter are at the top of the hierarchy, while those defined within other areas or annotated within a business object are at lower levels of the hierarchy. So for example, if you set values for EIS-type bidirectional properties only for the resource adapter, those values are inherited and used by transformations that require a defined EIS-type bidirectional property, whether they arise from an inbound (activation specification) transaction or an outbound (managed connection factory) transaction.

However, if you set values for EIS-type bidirectional properties for both the resource adapter and the activation specification, a transformation arising from an inbound transaction uses the values set for the activation specification.

The processing logic uses a lookup mechanism to search for bidirectional property values to use during a transformation. The lookup mechanism begins its search at the level where the transformation arises and searches upward through the hierarchy for defined values of the appropriate property type. It uses the first valid value it finds. It searches the hierarchy from child to parent only; siblings are not considered in the search.



Related reference:

Properties enabled for bidirectional data transformation

Feedback


Properties enabled for bidirectional data transformation

WebSphere Adapter for Oracle E-Business Suite has several configuration properties that are enabled for bidirectional data transformation.

The adapter enables the exchange of bidirectional data between a client application and the database, even if the data in the database is in a different bidirectional format than is used by the runtime environment. You can use bidirectional characters when configuring the adapter and in the application-specific information of your business objects. The following sets of properties and application-specific information are enabled for bidirectional support:

The sections which follow list the specific configuration properties and application-specific information that are enabled for bidirectional transformation.


Activation specification properties

The following activation specification properties are enabled for bidirectional script data transformation:


Connection properties used in the wizard

The following connection properties for the external service wizard are enabled for bidirectional script data transformation:


Managed connection factory properties

The following managed connection properties are enabled for bidirectional script data transformation:


Business object application-specific information

The following business object application-specific information parameters are enabled for bidirectional script data transformation:


Operation application-specific information

The following operation application-specific information parameters are enabled for bidirectional script data transformation:


Attribute application-specific information

The following attribute application-specific information parameters are enabled for bidirectional script data transformation:



Related concepts:

Globalization and bidirectional transformation

Feedback


Adapter messages

View the messages issued by WebSphere Adapter for Oracle E-Business Suite at the following location.

Link to messages: Adapter messages

The displayed Web page shows a list of message prefixes. Click a message prefix to see all the messages with that prefix:


Feedback


Related information

The following information centers, IBM Redbooks , and web pages contain related information for WebSphere Adapter for Oracle E-Business Suite.


Information resources


Information about related products


developerWorks resources


Feedback


Video samples

To help you use WebSphere Adapters, sample videos are available to detail some of the scenarios.

You can find several WebSphere Adapters video demonstrations at this FTP location ftp://ftp.software.ibm.com/software/websphere/integration/wsa/library/videos/.

To view these video samples:

  1. Download the zip file of the required sample from the FTP location.
  2. Extract the downloaded zip file to your system.

  3. From the extracted folder, double-click the HTML file.
  4. The video sample opens in your default Web browser.

    The video has a built-in audio narration. If you do not want to listen to the audio, you can lower its tab to the minimum, and slide the tab to an audio level, whenever you want the audio back.

The following sample videos are currently available at this location: ftp://ftp.software.ibm.com/software/websphere/integration/wsa/library/videos/


Feedback


11. Adapter documentation in PDF format

Documentation in PDF format for WebSphere Adapter for Oracle E-Business Suite is available at the following location.

Adapter documentation in PDF format: ftp://ftp.software.ibm.com/software/websphere/integration/wsa/library/pdf7503/


Feedback


+

Search Tips   |   Advanced Search