Understanding Application Integration Framework

This chapter discusses:

• Application Integration Framework.

• Maps.

• Functions to populate and maintain the cross-reference and domain value maps (DVMs).

• Use Case: Integration Broker transformation without Application Integration Architecture (AIA) middleware.

• Use Case: Integration Broker point-to-point transformation.

• Use Case: Integration Broker transformation in which a third party uses AIA middleware.

Application Integration Framework

Application Integration Framework extends PeopleSoft Integration Broker (IB) functionality to provide a standard way to represent, classify, store, query, publish, acquire, and invoke data that maps element names, structures, and values between PeopleSoft Application Business Messages (ABMs) and other applications. PeopleSoft Integration Broker provides the framework to send and receive messages with other PeopleSoft systems or third-party systems. If the message structure differs between systems, transformation programs are used to transform the incoming or outgoing message to a message format that the PeopleSoft system understands.

Each application that you are integrating with may use different data values or identifiers to represent the same information. For example, for a new customer in a PeopleSoft application, a new row is inserted in its customer database with a unique identifier such as PS1001. When the same information is propagated to an Oracle E-Business Suite application and a Siebel application, a new row should be inserted with different identifiers, such as EBS1001 and SBL1001. The application integration framework enables you to transform this data.

Application Integration Architecture

Application Integration Architecture (AIA) is built on Oracle's Service Operation Architecture (SOA) as a unified approach for integrating business processes across applications, including third-party applications, based on a common architecture and common definition of business objects called Enterprise Business Objects (EBOs). These applications were designed using different technologies and use different names and structures to represent the same business object. AIA is the foundation for creating transformations on messages sent between diverse systems to integrate multiple applications without the need to create separate point-to-point integrations for each system involved.

AIA middleware can be used to transform business objects to a common object. Oracle's Fusion middleware includes AIA as well as prebuilt integrations for Oracle products.

Oracle Application Integration Architecture Foundation Pack

AIA Process Integration Packs (PIPs) are prebuilt integrations across Oracle applications, such as Siebel CRM, Oracle E-Business Suite, Agile PLM, and Oracle Communications Billing and Revenue Management. The integrations consist of EBOs and Enterprise Business Services (EBS). Enterprise Business Messages (EBMs) are designed to be operation-specific.

AIA provides a middle layer between the PeopleSoft system and other third-party systems. If a third-party Siebel customer uses AIA, when a message from that customer arrives at the PeopleSoft system, the common AIA names and values are seen by the PeopleSoft application, rather than the Siebel names and values. On the other hand, if a Siebel customer did not purchase the AIA PIP, then the PeopleSoft application would see the Siebel names and values.

Note. PIPs are available from the Oracle E-Delivery website.

Application Integration Framework Integrations

Application Integration Framework is designed to assist developers with the tasks required to produce integrations that are architected to be AIA-supportive. The integration produces ABMs with the same semantic content and approximately the same shape as the canonical (AIA) EBMs, thus minimizing transformation requirements. Each AIA-supportive integration that PeopleSoft applications delivers includes a sample transformation to enable the integrations to map as closely as possible to the EBOs. This strategy enables PeopleSoft customers to utilize IB to complete partner integrations without the need for middleware to perform transformations. Of course, customers who choose to purchase Oracle AIA middleware or who already own it can use the features of the EBS for transformations instead of or in addition to using the delivered IB samples.

Note. PeopleSoft-delivered integrations transform messages to the EBM format for direct integration with other Oracle products.

This diagram illustrates a PeopleSoft message transformed to a common value.

Common value mapping for outgoing message

Use Cases for Application Integration Framework

Use cases fall into two categories:

• Key-mapping transforms using the dynamic cross-reference framework

• Static value transforms using the domain value map framework

These two frameworks are assumed to be separate; however, they in fact share common elements. The values of keys are open-ended and are usually extended; thus they are created programmatically during the transformation process, not in advance of the transform. Static value transforms generally have all values entered into the maps prior to the transformation process, and are less frequently extended.

In addition to these two categories, the integration use case depends on whether the third party is using AIA middleware.

This table shows where the transformations take place depending on whether AIA middleware is used:

Maps

Two different kinds of maps are available, domain values maps (DVM) and cross-reference maps (XREF). The maps are similar in that both maps group elements by domain name and are composed of elements that map specific values from one domain to another. The difference from a technical perspective is that XREF values are constantly being created, whereas DVM values are relatively static.

Map cardinality provides an independent classification of the mapping functions. Maps are based on single values (1:1) or multivalues (N:N).

Domain Value Map

A Domain Value Map (DVM) is used for values that are relatively static and are relatively limited in total number, such as country codes and states. DVMs generally have all values entered into the maps prior to the transformation process, and are less frequently extended compared to cross-reference maps.

The DVM consists of domains, maps, and elements.

Cross-Reference Map

A cross-reference map is used for values that are dynamic in nature, such as key elements used to identify an instance. These are referred to as key maps or cross-references. The values are the names of larger data entities.

Cross-references consist of domains, maps, and elements.

Functions to Populate and Maintain the Cross-Reference and DVMs

Three types of functions are available to query and maintain the DVM and cross-reference data during the transformation process.

These functions enable you to query, manipulate, and delete cross-reference (XREF) and DVM data during transforms. The cardinality of the function is incorporated into the API naming convention. Each set of functions can be further broken down into three activities: lookup, populate, and delete.

The provided functions by class, activity, and form are:

Use Case: Integration Broker Transformation Without AIA Middleware

This section discusses the use case in which both the PeopleSoft and third-party map transformations take place within the PeopleSoft Integration Broker through Application Integration Framework. In this use case, PeopleSoft applications can take advantage of a canonical integration model without the need to purchase AIA middleware.

Use case includes:

• Outbound request or post to a third party.

• Inbound request or post from a third party.

Outbound Request or Post to a Third Party

This diagram illustrates an outbound request or post to a third party:

Outbound request to a third party without AIA middleware

The following steps are performed in this scenario:

1. A user in the PeopleSoft system triggers publishing of an AIA supportive integration to a third-party system.

2. Within PeopleSoft Integration Broker, a transform on the outbound routing generates the EBM. The method used to translate the data values depends on the transaction. This table lists the transaction types and the necessary transformation action.

   Transaction	Action
   Dynamic key add-request	If the transaction is an add-request, the transform creates a new common key (GUID) and uses the appropriate form of the populate XRef XPath extension function to put the new common key and the corresponding PeopleSoft keys into the PeopleSoft cross-reference framework.
   Dynamic key lookup	If the transaction is not an add-request, the transform looks up the common key using the appropriate form of the lookup XRef XPath extension function with the PeopleSoft keys as input. If a common key does not exist, the developer determines whether to create a new common key, generate an error, or return an error message in the reply message if the integration supports it.
   Dynamic key delete request	For asynchronous notification (request-only) integrations that delete a keyed entity, developers may choose to leave the cross-reference values in place for historical purposes or, if desired, they may choose to delete the cross-reference values. To mark the PeopleSoft keys for deletion, the transform uses the appropriate form of the deleteXRef XPath extension function with the PeopleSoft keys as input.
   Static value lookup	If the transaction uses a domain value map, the transform looks up the PeopleSoft values using the appropriate form of the lookupDVM XPath extension function with the PeopleSoft values as input. If a value is not found, the developer determines whether the transform supplies the PeopleSoft values by default, leaves them blank, throws an error, or returns an error message in the reply message if the integration supports it.

3. The EBM is routed to the third-party system for processing.

Integrations supporting response messages have these additional steps.

1. The third-party system processes the request, formats the reply message, and then returns it along with the common key or value.

2. Within PeopleSoft Integration Broker, asynchronous request-reply operations have a transform to look up the PeopleSoft keys using the appropriate form of the lookupXref XPath extension function with the common key as input. The PeopleSoft keys are then put into the PeopleSoft ABM. Synchronous operations do not require this lookup because the PeopleSoft application already knows the PeopleSoft keys from the initial request.

   Transaction	Action
   Asynchronous request-reply operation using dynamic key value	Requires a transform program to look up the PeopleSoft keys using the appropriate form of the lookupXRef XPath extension function with the common key as input. The PeopleSoft keys are then put into the PeopleSoft ABM.
   Synchronous operations using dynamic key value	Lookup is not required because the PeopleSoft application already knows the PeopleSoft keys from the initial request.
   Asynchronous request-reply operation using DVM value	Requires a transform program to look up the PeopleSoft values using the appropriate form of the lookupDVM XPath extension function with the common value as input. The PeopleSoft keys are then put into the PeopleSoft ABM.

3. The PeopleSoft ABM reply is then returned to the originating PeopleSoft application.

Inbound Request or Post from a Third Party

This diagram illustrates an inbound request from a third party:

Inbound request from third party without AIA middleware

1. A user in the third-party system triggers publishing of an integration to a PeopleSoft system.

2. The EBM is routed to the PeopleSoft system for processing.

3. Within PeopleSoft Integration Broker, a transform on the inbound routing performs the following actions based on transaction type:

   Transaction	Action
   Dynamic key add request	If the transaction is an add-request, the transform leaves the PeopleSoft keys blank in the ABM and passes the common key along for use in the handler.
   Dynamic key lookup	If the transaction is not an add-request, the transform looks up the PeopleSoft keys using the appropriate form of the lookup XRef XPath extension function with the common key in the EBM as input. Optionally, this can be done in the PeopleSoft inbound handler through the appropriate PeopleSoft lookup XRef API with the common key as input.
   DVM lookup	The transform on the inbound routing looks up the PeopleSoft values using the appropriate form of the lookupDVM XPath extension function with the common value from the EBM. If a value is not found, the developer determines whether the transform supplies the PeopleSoft values, omits them, throws an error, or returns an error message in the reply message if the integration supports it.

4. The PeopleSoft inbound handler processes the message.

   Transaction	Action
   Dynamic key add request	If the transaction is an add-request, it creates the PeopleSoft keys and then uses the appropriate form of the populate XRef API to add the PeopleSoft keys and the corresponding common key to the PeopleSoft cross-reference framework. If the keys cannot be created or added to the framework, an error occurs or an error message is returned in the reply message if the integration supports it.
   Dynamic key lookup	If the transaction is not an add-request, the message is processed with the PeopleSoft keys from the ABM. If the PeopleSoft key values are not found, an error occurs or a message is returned in the reply message if the integration supports it.

Integrations supporting response messages have these additional steps:

1. The PeopleSoft application processes the request and returns the ABM reply to the PeopleSoft inbound handler.

2. The PeopleSoft inbound handler formats the EBM reply and returns it to the third-party system with the common key.

3. Optionally, if the third-party system uses the PeopleSoft cross-reference framework to persist their key mappings, asynchronous request-reply operations need to look up the third-party keys using the appropriate form of the lookup XRef web service with the common key from the EBM reply as input.

Use Case: Integration Broker Point-to-Point Transformation

This section discusses the use case in which PeopleSoft Integration Broker performs all of the transformations with a third party. In the previous use case, the messages were transformed to the EBM format; in this use case, the message is transformed into the third-party ABM. If the third party is another PeopleSoft system, no transform is necessary.

Use case includes:

• Outbound request or post to a third party.

• Inbound request or post from a third party.

Outbound Request or Post to a Third Party

This diagram illustrates an outbound point-to-point request or post to a third party:

Outbound point-to-point request to a third party

The following steps are performed in this scenario:

1. A user in the PeopleSoft system triggers publishing of a point-to-point integration to a third-party system.

2. Within PeopleSoft Integration Broker, a transform on the outbound routing generates the third-party ABM. The method used to translate the data values depends on the transaction. This table lists the transaction types and the necessary transformation action.

   Transaction	Action
   Dynamic key add-request	If the transaction is an add-request, the transform creates a new common key (GUID) and uses the appropriate form of the populate XRef XPath extension function to put the new common key, corresponding PeopleSoft key, and third-party key in the PeopleSoft cross-reference framework.
   Dynamic key lookup	If the transaction is not an add-request, the transform looks up the key using the appropriate form of the lookup XRef XPath extension function with the PeopleSoft keys as input. If a common key does not exist, the developer determines whether to create a new common key, generate an error, or return an error message in the reply message if the integration supports it.
   Dynamic key delete request	For asynchronous notification (request-only) integrations that delete a keyed entity, developers may choose to leave the cross-reference values in place for historical purposes or, if desired, they may choose to delete the cross-reference values. To mark the PeopleSoft keys for deletion, the transform uses the appropriate form of the deleteXRef XPath extension function with the PeopleSoft keys as input.
   Static value lookup	If the transaction uses a domain value map, a transform on the outbound routing looks up the common value using the appropriate form of the lookupDVM XPath extension function with the PeopleSoft value as input. If a value is not found, the developer determines whether the transform supplies the PeopleSoft values by default, omits them, throws an error, or returns an error message in the reply message if the integration supports it.

3. The third-party ABM is routed to the third-party system for processing.

Integrations supporting response messages have these additional steps.

1. The third-party system processes the request, formats the reply message, and then returns it along with the common key or value.

2. Within PeopleSoft Integration Broker, asynchronous request-reply operations have a transform to look up the PeopleSoft keys using the appropriate form of the lookup XRef XPath extension function with the third-party key as input. The PeopleSoft keys are then put into the PeopleSoft ABM. Synchronous operations do not require this lookup because the PeopleSoft application already knows the PeopleSoft keys from the initial request.

   Transaction	Action
   Asynchronous request-reply operation using dynamic key value	Requires a transform program to look up the PeopleSoft keys using the appropriate form of the lookupXRef XPath extension function with the third-party key as input. The PeopleSoft keys are then put into the PeopleSoft ABM.
   Synchronous operations using dynamic key value	Lookup is not required because the PeopleSoft application already knows the PeopleSoft keys from the initial request.
   Asynchronous request-reply operation using DVM value	Requires a transform program to look up the PeopleSoft value using the appropriate form of the lookupDVM XPath extension function with the third-party value as input. The PeopleSoft keys are then put into the PeopleSoft ABM.

3. The PeopleSoft ABM reply is returned to the originating PeopleSoft application.

Inbound Request or Post from a Third Party

This diagram illustrates an outbound point-to-point request or post to a third-party:

Inbound point-to-point request from a third party

1. A user in the third-party system triggers publishing an integration to a PeopleSoft system.

2. In this example, the request is sent in the third-party ABM format.

   Note. In many instances, the third-party may be aware of the PeopleSoft ABM format and perform a transformation before sending the message; in this case, no transform is required.

3. Within PeopleSoft Integration Broker, a transform on the inbound message performs the following actions based on transaction type:

   Transaction	Action
   Dynamic key add request	If the transaction is an add-request, the transform leaves the PeopleSoft keys blank in the ABM and passes the third-party key along for use in the handler.
   Dynamic key lookup	If the transaction is not an add-request, the transform looks up the PeopleSoft keys using the appropriate form of the lookup XRef XPath extension function with the reference key in the third-party ABM as input.
   DVM lookup	The transform on the inbound routing looks up the PeopleSoft values using the appropriate form of the lookupDVM XPath extension function with the reference key from the third-party ABM. If a value is not found, the developer determines whether the transform supplies the PeopleSoft values, omits them, throws an error, or return an error message in the reply message if the integration supports it.

4. Within PeopleSoft Integration Broker, a transform on the inbound message performs the following actions based on transaction type.

5. The PeopleSoft Inbound handler processes the message.

   Transaction	Action
   Dynamic key add request	If the transaction is an add-request, it creates the PeopleSoft keys and then uses the appropriate form of the populate XRef API to add the PeopleSoft keys and the corresponding UniqueGUID to the PeopleSoft cross-reference framework. If the keys cannot be created or added to the framework, an error occurs or a message is returned in the reply message if the integration supports it.
   Dynamic key lookup	If the transaction is not an add-request, the message is processed with the PeopleSoft key values from the ABM. If the PeopleSoft key values not found, an error occurs or a message is returned in the reply message if the integration supports it.

Integrations supporting response messages have these additional steps:

1. The PeopleSoft application processes the request and the PeopleSoft inbound handler formats the ABM reply and returns it along with the common key or value.

2. No key translation is required in the transform, so the EBM reply is then returned to the third-party system along with the common key from the ABM reply.

Use Case: Integration Broker Transformation in Which a Third Party Uses AIA Middleware

From a PeopleSoft perspective, this use case has an identical flow to the transformation without the AIA middleware. From a third-party perspective, however, it is similar in flow, but not in implementation. In this case, the third-party system integrates with the AIA using their ABM instead of with PeopleSoft software using an EBM. All of the third-party value maps and transforms between the EBM and the third-party ABM are done on the AIA layer using the EBS graphical-mapper and XPath extension functions instead of being done on the third-party system.

Note. This is the model used with AIA PIPs.

Use cases include:

• Outbound request or post to a third party.

• Inbound request or post from a third party.

Outbound Request or Post to a Third Party

In this use case, a request is sent from the PeopleSoft application to a third party that uses their own AIA middleware to perform message transformation.

Outbound request to a third party that uses AIA middleware

1. A user in the PeopleSoft system triggers publishing of an AIA supportive integration to a third-party system through the AIA.

2. Within PeopleSoft Integration Broker, a transform on the outbound routing occurs, generating the EBM. The method used to translate the data values depends on the transaction. This table lists the transaction types and the necessary transformation action.

   Transaction	Action
   Dynamic key add request	If the transaction is an add-request, the transform creates a new common key (GUID) and uses the appropriate form of the populateXRef XPath extension function to put the new common key and the corresponding PeopleSoft keys in the PeopleSoft cross-reference framework.
   Dynamic key lookup	If the transaction is not an add-request, the transform looks up the common key using the appropriate form of the lookupXRef XPath extension function with the PeopleSoft keys as input. If a common key does not exist, the developer determines whether to create a new common key, generate an error, or return an error message in the reply message if the integration supports it.
   Dynamic key delete request	For asynchronous notification (request-only) integrations that delete a keyed entity, developers may choose to leave the cross-reference values in place for historical purposes or, if desired, they may choose to delete the cross-reference values. To mark the PeopleSoft keys for deletion, the transform uses the appropriate form of the deleteXRef XPath extension function with the PeopleSoft keys as input.
   DVM lookup	If the transaction uses a domain value map, the transform looks up the PeopleSoft values using the appropriate form of the lookupDVM XPath extension function with the common value from the EBM. If a value is not found, the developer determines whether the transform supplies the PeopleSoft values by default, omits them, throws an error, or returns an error in the reply message if the integration supports it.

3. The EBM is routed to the AIA.

4. Upon receiving the EBM request, the AIA transforms the common key to the third-party key and sends the transformed request to the third party using their ABM.

Integrations supporting response messages use these additional steps:

1. The third party processes the request, formats the reply message, and returns it to the AIA middleware.

2. The AIA transforms the third-party key in the reply to the common key and returns the EBM reply to PeopleSoft software.

3. Within PeopleSoft Integration Broker, asynchronous request-reply operations have a transform program to transform the common key or value and place it into the PeopleSoft ABM. Synchronous operations do not require this lookup because the PeopleSoft application already knows the PeopleSoft keys or values from the initial request.

   Transaction	Action
   Dynamic key lookup	Transform looks up the PeopleSoft keys using the appropriate form of the lookup XRef XPath extension function with the common key as input.
   Dynamic key delete	(Optional) For integrations that delete a keyed entity, developers may choose to leave the cross-reference values in place for historical purposes or, if desired, they may choose to delete the cross-reference values. To mark the PeopleSoft keys for deletion, the transform uses the appropriate form of the deleteXRef XPath extension function with the PeopleSoft keys as input.
   DVM lookup	The transform looks up the common value using the appropriate form of the lookup DVM XPath extension function with the PeopleSoft values as input.

4. The PeopleSoft ABM reply is returned to the originating PeopleSoft application.

Inbound Request or Post from a Third Party

In this use case, a third-party application creates a request that is transformed using the third-party AIA middleware and sent to the PeopleSoft application.

Inbound request from a third party using AIA middleware

1. A user in the third-party system triggers publishing of an integration to a PeopleSoft system through the AIA.

2. The AIA transforms the third-party ABM key and values to the common key and values and routes the EBM request to the PeopleSoft system for processing.

3. Within PeopleSoft Integration Broker, a transform on the inbound routing transforms the EBM to PeopleSoft ABM using one or more of the following methods depending on the transaction.

   Transaction	Action
   Dynamic key add	If the transaction is an add-request, the transform leaves the PeopleSoft keys blank in the ABM and passes the common key along for use in the handler.
   Dynamic key lookup	If the transaction is not an add-request, the transform looks up the PeopleSoft key using the appropriate form of the lookupXRef XPath extension function with the common key in the EBM as input. Optionally, this can be done in the PeopleSoft inbound handler using the appropriate PeopleSoft lookup XRef API with the common key as input.
   DVM lookup	A transform on the inbound routing looks up the PeopleSoft values using the appropriate form of the lookup DVM XPath extension function with the common value from the EBM. If a value is not found, the developer determines whether the transform supplies the PeopleSoft values by default, leaves them blank, throws an error, or returns an error message in the reply message if the integration supports it.

For synchronous and asynchronous request-reply messages, the following additional steps are performed:

1. The PeopleSoft application processes the request and the PeopleSoft inbound handler formats the ABM reply and returns it along with the common key or value.

2. No key translation is required in the IB transform, so the EBM reply is returned to the AIA for routing back to the third-party system.

3. The AIA transforms the common key and values to the third-party ABM key and values and routes the third-party ABM reply back to the third-party system.