| Oracle® Enterprise Service Bus Developer's Guide 10g (10.1.3.3.0) Part Number E10295-01 |
|
|
View PDF |
| Oracle® Enterprise Service Bus Developer's Guide 10g (10.1.3.3.0) Part Number E10295-01 |
|
|
View PDF |
This chapter introduces domain-value maps, presents the XML structure required by Oracle Enterprise Service Bus for a domain-value-map, describes how to create, populate, import and export domain-value maps using the Oracle ESB Control, and how to use domain-value maps when designing transformations within enterprise service bus routing rules.
This chapter contains the following topics:
Applications that you want to integrate using Oracle Enterprise Service Bus likely use different values to represent the same information. For example, one application might represent a state with the long name (Massachusetts) while another application may represent the state with an abbreviation (MA). A domain-value map enables you to associate values from one application with values from another.
Each domain-value map typically holds a specific category of value mappings among multiple applications. For example, one domain-value map might hold mappings for state codes and another might hold mappings for units of measurement.
After a domain-value map is created and populated using Oracle ESB Control, it can 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.
For example, suppose you want to use a a domain-value map to perform a runtime lookup to convert long state names input to the two-letter state code output. In this scenario, the state name is passed to an Oracle Enterprise Service Bus. Within the enterprise service bus, the data is transformed by a transformation specified in the routing rule of the routing service from the state name to the state code using a domain-value map look up.
The overall process of creating and using a domain value map is summarized in the following list:
Using the Oracle ESB Control, you create a domain-value map and populate it with values that will need to be mapped across the applications integrated using the enterprise service bus. This process is described in the subsections of this topic.
Using Oracle JDeveloper, you create an XSL file to define the source to target transformation within a routing rule transformation. This process is described in "Creating an XSL Map File for Data Structure Transformation".
At runtime, Oracle Enterprise Service Bus uses the domain-value map to look up appropriate values and populate the targets for the applications that it integrates with.
You create (and then save) a domain-value map using the Map view of the Oracle ESB Control. When you save the domain-value map, it is saved in the ESB repository, which makes it available for use with the data mapper in Oracle JDeveloper. The following sections describe the various methods available for creating (and saving) a domain-value map.
To create a domain-value map from scratch, follow these steps:
At the top of the Oracle ESB Control, click the Map icon.
Click the Create down-arrow on the left side of the Oracle ESB Control.
Two choices are presented: Create a new map and Import a new map.
Click Create a new map.
The Oracle ESB Control refreshes and appears similar to Figure 7-1.
Figure 7-1 Oracle ESB Control Map View – Create New Map
Replace the default New DVM with a name for the domain-value map file. To edit New DVM, click in the name field in the right pane of the screen above the Mappings area.
For example, you replace New DVM with StateCodes to identify a domain-value map for state names, abbreviations, and short codes.
If you export the domain-value map, the name you specify is used for the export file name. See "Exporting a Domain-Value Map" for information about exporting a domain-value map.
In the Description field, enter a description of the domain-value map.
For example, you might enter: Mappings of state names, abbreviations, and short codes
If you need additional columns, click the Add down-arrow, and then click Column once for each additional column you want to add. If you add too many columns, select the column and click Delete.
Each column represents a domain. If you will be using the domain-value map to map values among four domains, for example, you click Column twice to add two more columns. There are no restrictions on what can be considered a domain; you specify domains based on your needs. A domain might be, for example, a trading partner, an organization, a department, an application, and so on.
For example, add one column Add > Column.
Double-click a column name to change it from the default value of Applicationn to a more meaningful name. Each column name must be unique within the domain-value map.
For example, you change the default column names to Long, Abbrev, and Short.
If you need additional rows, click the Add down-arrow, and then click Row once for each additional row you want to add. If you add too many rows, select the row and click Delete, or leave it as-is. Empty rows are deleted when you save the domain-value map.
Double-click a row and enter values for the domain value map.
For example, enter Massachusetts, Mass, and MA in the columns under Long, Abbrev, and Short.
Repeat the previous step until you have entered the desired rows. You do not have to enter all rows that will be required by the applications. You can edit the domain-value map to add more rows later.
Figure 7-2, shows an example of a domain-value map.
Review the name for the domain-value map and click the Save button above the Description field.
After you click the Save button, you can change components of the domain-value map, as described in "Editing a Domain-Value Map".
You can change the name of a saved domain-value map by double-clicking on the map name, but any transformation map referring to the domain-value map would need to modified. See "Using a Domain-Value Map in a Transformation".
Although these instructions indicate that you click Save when you have completed a domain-value map, you can click Save at any point in the process.
If you want to export the map, see "Exporting a Domain-Value Map".
The domain-value map can now be used when creating a transformation in Oracle JDeveloper.
Figure 7-2 Domain-Value Map – Rows Created
After you have created and saved a domain-value map, you can export it to a file. You might want to do this if you have created it on a test system and now want to export it so that you can import it on a production system.
To export a domain-value map, follow these steps:
In the Maps view of the Oracle ESB Control, create or import a domain value map, as described in "Creating a New Domain-Value Map from Scratch" or "Importing an Existing Domain-Value Map File".
Click Save, if you have not already done so.
Click Export.
Click OK, and then wait for the operating system dialog box to open that enables you to save the file to the local file system. If you are prompted whether to open or save the file, select Save.
In the save file dialog box, save the domain-value map file, such as StateCodes.xml, in the desired location.
After the map file has been exported and saved to the file system, you can edit the XML file with a text editor. However, make sure that you have carefully updated the file so that the file remains valid. See Example 7-1 for a sample domain-value map file.
Example 7-1 Sample Domain-Value Map File
<?xml version = '1.0' encoding = 'UTF-8'?>
<dvm name="StateCodes" isNew="null">
<description>Mapping of state names, abbreviations, and codes</description>
<columns>
<column name="Long"/><column name="Abbrev"/><column name="Short"/>
</columns>
<rows>
<row><cell>Massachusetts</cell><cell>Mass</cell><cell>MA</cell></row>
<row><cell>California</cell><cell>Calif</cell><cell>CA</cell></row>
</rows>
</dvm>
This section provides examples of the domain-value map template and schema definition file.
Example 7-2 shows the domain-value map template (XML) file. This file should be used if you are creating a domain-value map file from scratch with a text editor.
Example 7-2 Domain-Value Map Template File
<?xml version="1.0" encoding="UTF-8"?>
<dvm name="New DVM" isNew="true">
<description>DVM description</description>
<columns>
<column name="Domain1"/>
<column name="Domain2"/>
</columns>
<rows>
<row>
<cell>value1</cell>
<cell>value2</cell>
</row>
</rows>
</dvm>
Example 7-3 shows the domain-value map schema definition (XSD) file. All imported domain-value map XML files are validated against this schema definition file.
Example 7-3 Domain-Value Map XSD File
<?xml version="1.0" encoding="UTF-8" ?>
<!-- Copyright (c) 2006, Oracle. All rights reserved. -->
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<xsd:element name="dvm">
<xsd:annotation>
<xsd:documentation>The Top Level Element
</xsd:documentation>
</xsd:annotation>
<xsd:complexType>
<xsd:sequence>
<xsd:element name="description" minOccurs="0">
<xsd:annotation>
<xsd:documentation>The DVM Description. This is optional
</xsd:documentation>
</xsd:annotation>
</xsd:element>
<xsd:element name="columns">
<xsd:annotation>
<xsd:documentation>This element holds DVM's column List.
</xsd:documentation>
</xsd:annotation>
<xsd:complexType>
<xsd:sequence>
<xsd:element name="column" minOccurs="2" maxOccurs="unbounded">
<xsd:annotation>
<xsd:documentation>This represents a DVM Column
</xsd:documentation>
</xsd:annotation>
<xsd:complexType>
<xsd:attribute name="name" use="required"/>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="rows">
<xsd:annotation>
<xsd:documentation>This represents all the DVM Rows.
</xsd:documentation>
</xsd:annotation>
<xsd:complexType>
<xsd:sequence>
<xsd:element name="row" minOccurs="1" maxOccurs="unbounded">
<xsd:annotation>
<xsd:documentation>
Each DVM row of values
</xsd:documentation>
</xsd:annotation>
<xsd:complexType>
<xsd:sequence>
<xsd:element name="cell" minOccurs="2" maxOccurs="unbounded">
<xsd:annotation>
<xsd:documentation>This is the value for this row and for each column in
the same order as defined in Columns.
</xsd:documentation>
</xsd:annotation>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:sequence>
<xsd:attribute name="name" use="required"/>
<xsd:attribute name="isNew"/>
</xsd:complexType>
</xsd:element>
<xsd:annotation>
<xsd:documentation>This schema is used to validate the DVM Document used for creating
and updating a domain-value map
</xsd:documentation>
</xsd:annotation>
</xsd:schema>
If you have an existing domain-value map on the local file system, you can import it into Oracle ESB Control as a means to add it to the ESB repository so that it can be used when you are specifying a transformation in a routing rule.
Typical scenarios for importing an existing domain-value map file are the following:
To move a domain-value map from a test system to a production system
If you need to move an entire ESB configuration from a test system to a production system, Oracle recommends you use the import method described in "Moving the ESB Instance to a Different Oracle Home". To import a domain-value map only, first export it on the test system, as described in "Exporting a Domain-Value Map".
To import an XML lookup file exported from a database as the basis for a domain-value map.
This scenario assumes that you exported the schema from the database using a tool such as XSU, and have converted the exported file to use the schema required for ESB domain-value maps. See "Domain-Value Map Template and XSD Files". For an example of an exported domain-value map, see Example 7-1.
To import an existing domain-value map file and store it in the ESB repository, follow these steps:
At the top of the Oracle ESB Control, click Maps.
Click the Create down-arrow on the left side of the Oracle ESB Control.
Two choices are presented: Create a new map and Import a new map.
Click Import a new map.
The Import a New Map dialog box opens. See Figure 7-3.
In the Import a New Map dialog box, follow these steps:
In the Import field, enter the complete path for the file on the local file system that you want to import.
Select or deselect overwrite if a map with the same name already exists, as desired.
Because the name becomes the primary key for the domain-value map when it is stored in the ESB repository, the name must be unique. If you select overwrite if a map with the same name already exists and a domain-value map with the same name already exists that you do not want to overwrite, you can do either of the following:
Cancel this dialog box, rename the domain-value map, and then restart the import operation. See "Editing the Name of a Domain-Value Map".
Deselect overwrite if a map with the same name already exists.
Click OK.
The Oracle ESB Control refreshes and presents the imported domain-value map file. The imported file is saved to the ESB repository and the domain-value map can now be used when creating a transformation in Oracle JDeveloper.
Figure 7-3 Maps View – Import a New Map Dialog
If you are working on a domain-value map that currently has several rows and then want to import additional rows from a properly formatted file, you can do so as described in the list that follows. When you do so, rows from the imported file may conflict with rows in the current domain value map.
Rows are considered to conflict, when a given column contains the same value in two or more different rows, such as shown for the Oracle application in Figure 7-4.
Figure 7-4 Sample Domain-Value Map with a Conflict
When such a conflict exists you are given the following options:
Overwrite conflicting rows
If you select this option, conflicting rows in the domain-value map displaying in the Oracle ESB Control are overwritten with rows from the file being imported.
Skip conflicting rows
If you select this option, conflicting rows in the domain-value map displaying in the Oracle ESB Control are not overwritten with rows from the file being imported. Those rows are not imported into the domain-value map.
Add conflicting rows
If you select this option, rows from the file being imported are added to the domain-value map, even if they conflict with existing rows in the domain value map. You should only select this option under particular circumstances and if you are familiar with the applications that will use the domain-value map at runtime.
For example, the rows presented in Figure 7-4, should remain only if the domain-value map will be used to map values from the SAP application values to the Oracle application at run time, and not the reverse. If values from the Oracle application will map to the SAP application at run time, then it is impossible for the ESB Server to determine whether, Gallon should map to Container or Gal, and therefore an error will result.
Follow these steps to import rows into a domain-value map:
In the Maps view of the Oracle ESB Control, create or import a domain value map, as described in "Creating a New Domain-Value Map from Scratch" or "Importing an Existing Domain-Value Map File".
Click Save to save any changes you have made.
Click Import.
The Import into an Existing Map dialog box opens.
In the Import File field, enter the path for the file from which you want to import rows.
Select one of the Import Options, which are described in section.
Figure 7-5 Oracle ESB Control Map View – Import into an Existing Map Dialog
Click OK.
The Oracle ESB Control refreshes the view and presents the imported rows. The domain-value map is saved to the ESB repository and it can be used when creating a transformation in Oracle JDeveloper, as described in "Using a Domain-Value Map in a Transformation".
Figure 7-6 Oracle ESB Control Map View – Updated Map After Importing Rows
This section presents the editing options that are available for editing a domain-value map and making adjustments to the presentation of data in the Map view. All of the options described here can be used while you are creating a domain-value map.
This section contains the following topics:
Follow these steps:
Double-click the domain-value map name.
Edit the map name.
You can change the name of a saved domain-value map by double-clicking on the map name, but any transformation map referring to the domain-value map would need to modified. See "Using a Domain-Value Map in a Transformation".
Follow these steps:
Click the Add down-arrow
A drop-down list presents a choice of row or column.
Click row or column to add the desired table element. You can click the option multiple times to add multiple rows or columns.
Follow these steps:
Click the number of the row that you want to delete.
The row is highlighted in blue.
Click the Delete button under the Mappings heading.
Follow these steps:
Click the name of the column that you want to delete.
The column is highlighted in blue.
Click the Delete button under the Mappings heading.
Follow these steps:
Double-click the name of the column that you want to rename.
The text cursor appears before the first letter of the existing column name.
Edit the column name.
You can delete all the existing characters and type in the new name.
Click the Save button to save the changes.
You can move a selected column one position at a time, as described in the following list. This options is provided to support user preferences, it has no effect on how the domain-value map is applied at run-time.
Follow these steps:
Click the column that you want to move to the right.
Small arrows appears in the column heading, as shown in Figure 7-7.
Figure 7-7 Arrows for Rearranging Columns In Domain-Value Maps
Click the arrow in the direction you want to move the selected column.
Repeat steps 1 and 2 until all the columns appear in the desired order.
As you are creating or editing a domain-value map, it is best to save it frequently, especially if you are adding numerous rows manually.
Suppose, for example, you save a domain value map, and then add multiple additional rows. You realize that entered many incorrect rows since the last time you saved the domain-value map. You can reset the domain-value map to its last saved state by clicking the Reset button. Any changes made after the last time you clicked the Save button are removed.
If the values you add to the cells in a domain value map are wider than the default cell width, you might want to resize the columns, by following these steps:
Place the cursor on the boundary between two column headers so that the cursor shape changes to a double-headed arrow; this is the resize cursor.
Left-click the double-headed arrow – a dotted line appears at the column boundary.
Drag the dotted line left or right, as desired, to indicate the new placement of the boundary.
Release the mouse button.
If you a domain-value map is no longer used in any routing rule transformations and you want to delete it, follow these steps:
Click Maps in the Oracle ESB Control.
In the Domain-Value Maps navigator, select the name of the domain-value map that you want to delete.
Click the Delete button within the Domain-Value Maps navigator.
The Delete Map dialog box opens.
Click Yes.
The selected domain-value map is deleted from the Domain-Value Maps navigator and from the ESB repository.
To include a domain-value map in a transformation, you drag and drop a lookup-dvm function from the component palette onto the connection between the source and target elements where you want the domain-value map to be used.
Note:
If you have previously used Oracle BPEL Process Manager, you may be familiar with thelookup-xml and lookup-table functions. Using these functions you can accomplish operations similar to using the Oracle Enterprise Service Bus lookup-dvm function. However, the lookup-xml and lookup-table functions are independent of the domain-value map infrastructure; a lookup-table function, for example, cannot be used with an ESB domain-value map.Open an ESB project in Oracle JDeveloper.
For example, open the CustomerData project to display the routing service icons in the Design tab. See Figure 2-2 for a sample screenshot of the CustomerData project.
Select a routing icon in the Design tab and then double-click the transformation XSL icon to display the Data Mapper window.
For example, select CustOut_RS in the Design tab and double click the XSL icon.
Expand the trees in the Source and Target panes in the Data Mapper window.
Drag and drop the source element to the target element.
For example, State to top:state as shown in Figure 7-8.
Figure 7-8 Data Mapper – Source to Target Map
In the Components palette, click the down-arrow and then select Advanced Functions.
The lookup-dvm function is listed in the component palette, as shown in Figure 7-9.
Figure 7-9 Component Palette – lookup-dvm Function
Drag and drop lookup-dvm onto the line that connects the source object to the target object.
A lookup-dvm icon appears on the connecting line, as shown in Figure 7-10. The yellow warning triangles indicate that the definition of the lookup-dvm function is not complete.
Figure 7-10 Data Mapper – look-up dvm Function Added
Double-click the look-up dvm icon.
The Edit Function – look-up dvm dialog box opens.
Specify values for the fields in the Edit Function – look-up dvm dialog box.
You can manually enter a value in sourceValue or the following methods:
Move the source value that appears in the dvmName field to the sourceValue field by clicking Move Down twice.
Press Ctrl-Space to launch Expression Builder. Press the up and down keys to locate an object in the list and press enter to select that item.
In the dvmName field, enter the name of the domain-value map schema that you previously defined using the Oracle ESB Control.
Click the flashlight icon to the right of the dvmName field to select the name from a list of domain-value maps stored in the ESB repository.
For example, select 'StateCodes' that was described in "Creating a New Domain-Value Map from Scratch".
In the sourceColumnName field, enter the name of the column in the domain-value map that is associated with the source element value.
Click the flashlight icon to the right of the sourceColumnName field to select the name from the columns defined for the domain-value map you previously selected.
For example, 'Long'
In the targetColumnName field, enter the name of the column in the domain-value map that is associated with the target element value.
Click the flashlight icon to the right of the targetColumnName field to select the name from the columns defined for the domain-value map you previously selected.
For example, 'Short'
Enter an optional default value.
For example, ""
Click OK.
The data mapper appears in the Design tab with the lookup-dvm function icon, as shown in Figure 7-12.
Figure 7-12 Data Mapper – look-up dvm Function Defined
From the File menu, click Save All.
Register the project with the ESB Server.
When the transformation is included in an ESB routing rule, the transformation is applied at run time. For example, if the StatesCodes domain-value map is used in the transformation, the transformation from the user-specified state value to the state code value required by the target application is applied at run time.
You can view the results of a transformation if you have set up the field in the Trackable Fields tab of the Oracle ESB Control Services view. The tracking data is displayed in the Details tab of the Oracle ESB Control Instances view, as shown in Figure 10-1.
