Oracle SOA - DVM & XREF

Domain-Value Maps (DVM) and Cross References (XREFs)

Requirement

When an object flows from one system to another system, both using their own entities to represent the same type of object, transformation is required to map the entity from one system to another. For example, when a new customer is created in a SAP application, you might want to create a new entry for the same customer in your Oracle E-Business Suite application named as EBS.

or A Simple scenario, Applications that we want to integrate often use different vocabulary to represent the same information. For example, one domain might represent a city with a long name (Boston), whereas another domain may represent a city with a short name (BO).

So the required functionality is that these two entities should be mapped from different domains. Even if in future, another domain gets added, again this is the requirement to represent that entity in some common entity format.

Oracle SOA (ESB) offers two solutions for such problems:

• Domain-Value Maps (DVM)
• Cross References (XREFs)

1. Domain-Value Maps (DVM)

Domain-Value Maps enable mapping of vocabulary in one domain to another, which is useful when different domains represent the same data in different ways.

A domain-value map can be created and populated using Oracle ESB Control. It can than be used with the Oracle JDeveloper Mapper tool while developing XSLT data transformations during design time. Then, at runtime the lookups for application-specific values occur. It uses XML file to store the mapping values.

For example, suppose we want to use a domain-value map to perform a runtime lookup to convert source id to the target id. Using Oracle Service Bus, the source id is passed and the target id returned using lookup function in transformation.

1.1 Architecture

Oracle ESB DVM uses XML to store the mapping values. The response time of the first call of lookup-dvm is high, as internal cache manager loads the XML document into the memory. If the data is frequently changing than the response time increases, because internal cache manager has to reload it again and again.
The search algorithm used by lookup-dvm is sequential search. If the value to be found exists in the last row of dvm file, than the response time increases. The DVM functionality of Oracle ESB is memory intensive if it has large set of mapping values.
Each Domain-Value Map typically holds a specific category of mappings among multiple applications. For example, one Domain-Value Map might hold mappings for city codes and another might hold mappings for state codes

DVM is best when having small set of mapping values. when it is small set of values, you can directly map values between multiple domains. A direct mapping of values between two or more domains is also known as Point-to-Point mapping. Internal cache manager increases the performance tremendously in this case, as xml document always resides in runtime memory.

Features of Domain-Value Maps include:

• Qualifier Support: Allows you to validate a mapping using additional information
• Qualifier Order Support: Is used to find the best match during lookup at run time
• One-to-Many Mapping Support: Allows you to map one value to multiple values in a Domain-Value Map

1.2 How to Use DVMs

Creating and populating DVM – There are two ways of creating and populating data value maps in Oracle ESB. Either to manually edit the dvm using Oracle ESB Console or import values using import command provided in Oracle ESB console. DVM does not allow to enter two rows having same set of values. Manual edit functionality should be used, when we don’t have large set of mapping values and which are frequently changing. Importing dvm files is the other options, provided the dvm files have specific format.

Looking up – To lookup the values we have lookup-dvm function. This function can be used in both Oracle ESB and Oracle BPEL through transformation. If the lookup target domain has multiple values for specific source domain value then it returns the first value, as this search is sequential. If lookup fails to find the target domain value, then it returns the default value passed in lookup-dvm function.

2. Cross References (XREFs)

Using cross references, you can dynamically populate, maintain, and map values for equivalent entities created by different applications. When creating, updating, and deleting objects in one application, there may be a need to propagate the changes to other applications. For example, when a new customer is created in a SAP application, you may need to create a new entry for the same customer in your Oracle E-Business Suite application (EBS).

However, since the applications being integrated are using different entities and IDs to represent the same information you need to cross reference these entities Cross references are stored in table structures defined by an .xref file that you can create by using JDeveloper.

To use the cross reference table defined by an .xref file you need XSD structures that defined the data to be cross referenced, the data itself, and a composite application with either a Mediator or BPEL component containing an XSL transformation that executes the appropriate XREF functions to populate, update, or look up cross references. When you execute a function to populate a cross reference table, the data is stored in the XREF_DATA table in a database referenced by the jdbc/xref JNDI name.

A cross reference table consists of following two parts, metadata and the actual data. The metadata is created by using the cross reference command line utilities and is stored in the repository as an XML file. The actual data is stored in the database.

By default, the XREF_DATA table is created in the SOA_INFRA schema created by the Repository Creation Utility (RCU), which is used to create the Oracle SOA Suite 11g database schemas required before installing Oracle SOA Suite 11g.

Because the cross reference data is persisted in a database it remains available for applications until explicitly deleted, preferably by using the appropriate XREF functions.

2.1 How it works:

This functionality of finding the cross domain mapping uses both xml and database. XML is used to store the metadata of the xref table and actual data get stored in database. Creation of xref tables is done using xreftool command line utility. Default datasource used by cross reference has jndi name jdbc/xref. Other datasources can be used are jdbc/esb and jdbc/BPELServerDataSource. To start working with cross reference, it is required to create a table in any of the above datasources. Following sql query is used to create XREF_DATA table -

CREATE TABLE XREF_DATA ( XREF_TABLE_NAME VARCHAR2(4000) NOT NULL, XREF_COLUMN_NAME VARCHAR2(4000) NOT NULL, ROW_NUMBER VARCHAR2(48) NOT NULL, VALUE VARCHAR2(4000) NOT NULL, IS_DELETED VARCHAR2(1) NOT NULL, LAST_MODIFIED VARCHAR2(100) NOT NULL, LAST_ACCESSED VARCHAR2(100) NOT NULL );

So here for each lookup, a jdbc call is made to select target domain value. So this type of referencing is not memory intensive. This proved to be best if we have large set of mapping values, and is dynamic. The performance is totally depends on the type and the location of the datasource. It also supports 1:M mapping of domain values.

2.2 How to use :

XPath functions provided in Oracle BPEL can be used in transformation and assign activity. These functions have better exception handling capability. To import and export the cross reference tables, command line utilities such as xrefexport and xrefimport are provided.

1. Create Xref
   The initial step is create two End System entries, which appear as a XML elements in a XREF source file. Each End System represents a collection of unique reference values for a given system. The actual cross reference values are created dynamically at run-time
2. Add or Delete new End systems
3. Populating Cross Reference Tables
   Drag the populateXRefRow (or populateXRefRow1M) function into the middle column of the XSLT :
   
   • The xrefLocation, specifies the directory and name of the .xref file defining the cross reference structure. Click the Browse (magnifying glass) icon to locate the file.
   • The referenceColumnName, which is the primary End System name
   • The referenceValue, which is the unique ID value in the primary End System
   • The columnName, which is the End System name being cross referenced
   • The value, which is the unique ID value in the End System being cross referenced
   • The mode, which can be the value ADD, UPDATE, or LINK (in uppercase). ADD creates a new row, UPDATE modifies an existing row.
4. Looking up - by using lookup xref
5. Delete - by using markforDelete