1. Developing Services with Oracle Service Bus
  2. Transforming Data
  3. Mapping Data with Domain Value Maps

22 Mapping Data with Domain Value Maps

This chapter provides an overview of domain value maps and how they are used in Service Bus services to associate terms used by different domains to describe like objects. It also describes how to create domain value maps in Service Bus projects.

This chapter includes the following sections:

For more in-depth information about domain value maps, see "Working with Domain Value Maps" in Developing SOA Applications with Oracle SOA Suite.

22.1 Introduction to Domain Value Maps

A domain value map associates values used by one domain for a specific field to the values used by other domains for the same field, providing the capability to map values across vocabularies or systems.

For example, you can map country codes, city codes, currency codes, and so on. You might have several domain value maps for one Service Bus project, depending on the number of fields that require mapping. Domain value maps are similar to cross references, but they are based on a static definition. You create and populate domain value maps in the design time, and deploy them to the runtime. Domain value map data is not changed by runtime activities as it is for cross references, but rather the domain value maps are used for lookups only.

Domain value maps can be used across Oracle SOA Suite components. In Service Bus, you can create domain value maps in both JDeveloper and the Oracle Service Bus Console.

22.1.1 Domain Value Map Functions

In the Service Bus message flow, you can reference domain value maps from XQuery expressions and XSLT transformations using a set of DVM functions to lookup values at runtime based on information in incoming messages. Use these functions so Service Bus knows how to map data coming in from one system to data being sent to another system.

You can access the DVM functions in JDeveloper from the XSLT mapper, the XQuery mapper, and the expression editors. In the Oracle Service Bus Console, the functions are available from the expression and condition editors. For information about the Service Bus DVM functions, see Domain Value Map Functions.

22.2 Creating Domain Value Maps in JDeveloper

You can create domain value maps in a Service Bus project in JDeveloper, and then use them in XQuery expressions in pipelines and split-joins to map objects between external systems.

Since a domain value map typically defines the mapping for only one field, a pipeline or split-join can reference multiple domain value maps.

22.2.1 How to Create a Domain Value Map in JDeveloper

Create and configure domain value maps using the Create Domain Value Map(DVM) File dialog in JDeveloper. This dialog lets you define two domains, each with one value. Upon completion, the Domain Value Map Editor appears so you can define additional domains and corresponding values.

When you create a domain value map, you can specify a name for up to two domains whose values are being mapped, along with the value for each domain. Once you create the map, you can add more domains and values.

To create a domain value map in JDeveloper:

  1. In the Application Navigator, right-click the project in which you want to create a domain value map, point to New, and select Domain Value Map(DVM).

    The Create Domain Value Map(DVM) File dialog appears.

  2. In the File Name field, enter a unique and descriptive name for the domain value map file. The file name must have an extension of .dvm.
  3. Optionally enter a new directory location and a brief description for the cross reference.

    The location must be within the directory structure of the current application.

  4. In the Domain Name fields, enter a name for up to two domains.

    These are the column names for the domain value map, and each represents the same field in different domains.

    Note:

    Domain names must be of the type NCName (non-colonized name), which is a valid XML element name with no colons. Each domain name must be unique in a domain value map. You can add more domains later.

  5. In the Domain Value field, enter the value corresponding to each domain.
  6. Click OK.

    The Domain Value Map Editor appears with the new domain value map displayed.

  7. To add new domains to the domain value map, see "How to Add Domains to a Domain Value Map" in Developing SOA Applications with Oracle SOA Suite.
  8. To add new values to the domain value map, see "How to Add Domain Values to a Domain Value Map" in Developing SOA Applications with Oracle SOA Suite.

22.3 Working with DVM Resources in the Oracle Service Bus Console

If you are using the Oracle Service Bus Console, you can create new domain value maps or you can upload domain value maps that you first created in JDeveloper into a DVM resource.

22.3.1 How to Create DVM Resources in the Console

When you create a DVM, you define the names of up to two end systems that are sharing the data along with the corresponding values for the field covered by the domain value map. After you create the map, you can define additional domains and values in the DVM Definition Editor.

Before you Begin

If you are uploading a domain value map file already created in JDeveloper, as described in Creating Domain Value Maps in JDeveloper, make sure the file is available on your system.

To create a DVM resource in the console:

  1. In the Project Navigator, right-click the project or folder to contain the new domain value map, point to Create, and select Resource Click Miscellaneous, click DVM, and then click OK.

    The Create DVM dialog appears.

  2. Do one of the following:

    • To upload an existing domain value map file, click Browse next to the File Upload field and then navigate to and select the file you created in JDeveloper.

      The Resource Name field is automatically populated with the file name minus the file extension. You can change this name.

    • To create a new domain value map, enter a unique name for the DVM resource.

  3. Optionally, enter a brief description of the resource.
  4. Click Create.

    The new domain value map appears on the DVM Definition Editor.

  5. In the DVM Definition Editor toolbar, click Save.
  6. Configure domains and values by performing the following steps:

22.3.2 How to Add Domains to a Domain Value Map

You can define additional domains to map, which are represented as columns in the domain value map. Each new domain can contain values that are either to be included in the lookups at runtime or to be used only to qualify the mapping. Domain names must be of the type NCName (non-colonized name), which is a valid XML element name with no colons.

To add a domain to a domain value map:

  1. If the DVM resource is not open, locate the DVM resource in the Project Navigator and click its name.
  2. In the Map Table, click Add and then select Add Domain.

    The Add Domain dialog appears.

  3. In the Name field, enter a name for the domain.
  4. To set this column as a qualifier column, select Enable a Qualifier for lookup.

    Tip:

    For more information about qualifier domains and qualifier order, see "Qualifier Domains" and "Qualifier Hierarchies" in Developing SOA Applications with Oracle SOA Suite.

  5. In the Lookup Order field, enter a number indicating the priority of the qualifier domain.

    This field is enabled only if you selected Enable a Qualifier for lookup.

  6. Click Add.
  7. To define a value for the new domain, continue to How to Add Domain Values to a Domain Value Map.

22.3.3 How to Add Domain Values to a Domain Value Map

Domain values are displayed in rows in the domain value map, with each row containing the value to be mapped for each domain. You can add as many domain values as required to fully define the mapping between domains.

To add domain values to a domain value map:

  1. If the DVM resource is not open, locate the DVM resource in the Project Navigator and click its name.
  2. In the Map Table, click Add and then select Add Domain Values.

    A new row appears beneath the existing rows in the Map Table.

  3. In the new row, enter the values for each domain.
  4. Repeat the above steps to create any additional values.
  5. In the DVM Definition Editor toolbar, click Save.
  6. To end the session and deploy the configuration to the runtime, click Activate.

22.3.4 How to Edit a Domain Value Map in the Console

If you are using the Oracle Service Bus Console, use the following procedure to modify an existing domain value map.

To edit a domain value map in the console:

  1. In the Project Navigator, expand the project and folders containing the domain value map to edit.

  2. Click the DVM resource name.

  3. To modify the source file, do the following:

    1. Click Edit Source in the toolbar.

      The Edit Source dialog appears.

    2. To browse to and select a new cross reference file to upload, click Browse.

    3. To modify the contents of the file, update the code directly in the Contents section of the dialog.

    4. Click Save.

  4. To add domains to the map, see How to Add Domains to a Domain Value Map.

  5. To add domain values, see How to Add Domain Values to a Domain Value Map.

  6. To edit a domain, select the domain in the Map Table and click Edit. In the Update Domain dialog, make any of the changes describe in How to Add Domains to a Domain Value Map.

  7. To change a value, double-click the value name in the Map Table and enter the new value.

  8. In the DVM Definition Editor toolbar, click Save.

  9. To end the session and deploy the configuration to the runtime, click Activate.

22.4 Deleting a Domain Value Map

If any resources reference the resource you want to delete, remove those references before deleting the resource.

You can delete the resource even if it is referenced by other resources, though this might result in conflicts due to unresolved references to the deleted resource.

22.4.1 How to Delete a Domain Value Map

Before deleting a domain value map, check for resources or dependencies. In the Oracle Service Bus Console, open the DVM in the DVM Definition Editor and click the Tools icon in the upper right, and then select References to find out whether any services are using it. In JDeveloper, right-click the DVM and select Explore Dependencies.

To delete a DVM resource:

  1. In the Application Navigator or Project Navigator, expand the project and folders containing the resource to delete.
  2. Right-click the name of the resource, and select Delete.
  3. If you are using JDeveloper, a confirmation dialog displays the number of references for the transformation. Click Show Usages to view information about the references, and then click Yes to confirm that you want to delete the resource.
  4. If you are using the Oracle Service Bus Console, click Activate to end the session and deploy the configuration to the runtime.

22.5 Using Domain Value Maps in Expressions and Conditions

Use the DVM XPath functions provided with Service Bus to define the domain value lookups that will occur during runtime.

The XPath functions provide a variety of ways to perform a lookup for either a single value or multiple values. These XPath functions can be used in the Expression Builder to create an expression or in the XSLT Mapper to create transformations. You can access the Expression Builder dialog through several pipeline activities and split-join operations.

For information about the DVM functions provided with Service Bus, see Domain Value Map Functions. For general information and instructions on using functions in the Oracle Service Bus Console expression and condition editors, see Building Expressions in the Editor Workspace Text Fields.

For information, examples, and instructions on using DVM functions in JDeveloper, see Using Domain Value Map Functionsin Developing SOA Applications with Oracle SOA Suite. This information is also helpful when working in the Oracle Service Bus Console.