Defining and Populating Value Maps

This chapter provides an overview of value maps and discusses how to:

• Define map options.

• Define value map.

• Populate a domain value map.

• Import value maps.

• Export value maps.

Understanding Value Maps

The Define Value Maps component enables users to define and classify value maps and elements. Each value map must be defined as either dynamic (cross-reference) or static (DVM).

Value maps support the following types of maps:

• One-to-one

• One-to-many

• Multiple elements per domain

One-to-One Cross-Reference

Cross-reference maps support a one-to-one relationship between two systems. For example, the PeopleSoft system uses one ID for customer A, the enterprise business object (EBO) or common value uses a GUID, and the external system uses another ID for the same customer.

The cross-reference map would be defined like this:

In this scenario, when a PeopleSoft application creates a new customer and sends the create customer message to the external system, the routing includes a transformation program that uses the cross-reference map to translate the data.

One-to-Many Cross-Reference

Cross-reference maps support a one-to-many relationship between two systems. Two or more values in a system may correspond to a single value in another system. For example, three different job codes might exist in the PeopleSoft system that correspond to one job code in the external system.

The cross-reference map would be defined like this:

In this scenario, when the PeopleSoft application assigns or changes a job code and sends the message to the external system, the routing includes a transformation program that uses the cross-reference map to translate the data. If the integration requires translation from the external system value to a PeopleSoft value, the developer is responsible for determining how to handle the multiple PeopleSoft values returned from the lookup. Options include replicating the source data for each value, implementing a method of choosing a default value, and generating an error for the transaction.

Cross-Reference with Multiple Domains

Many times a system implements functionality using compound keys. This is supported in the cross-reference framework by means of multiple elements to identify the value set. For example, item integrations from a PeopleSoft application to an external system would use a cross-reference map to translate SetID/ItemID on the PeopleSoft system to Product on the external system.

The cross-reference map would be defined like this:

In this scenario, when the PeopleSoft application creates an item and sends the message to the external system, the routing includes a transformation program that maps the setID and itemID to a common element (UniqueGUID) and the external system receives the translated data.

One-to-One DVM

In a domain value map, the one-to-one relationship contains the actual data values. For example, the PeopleSoft application uses the short name for the state code, the EBO defines state code using the full name as the common value, and the external application uses an abbreviated name for state code.

The DVM would be defined like this:

In this scenario, when a PeopleSoft application creates an outbound message to the external system that includes the state code, the routing includes a transformation program mapping the short name to the full name and the external system requires a transformation from the full name to the abbreviated name. The transformation for the external system can be done by means of the AIA middleware or a proprietary transformation on the external system.

One-to-Many DVM

In the domain value map, a one-to-many relationship is created by entering multiple values for one domain mapping to a single value in another domain. For example, in the PeopleSoft application, multiple person types can map to a single person type in the external application.

The DVM would be defined like this:

In this scenario, when a PeopleSoft application creates an outbound message to an external system that includes the person type, the routing includes a transformation program to translate the data values.

DVM with Multiple Elements Per Domain

In the DVM, you can map multiple elements to define a value set. For example, in the PeopleSoft application, the Business Unit/Chartfield combination could map to a Ledger/Segment combination in an external application.

In this scenario, when a PeopleSoft application creates an outbound message to the external system that includes the person type, the routing includes a transformation program providing the data translation.

The DVM would be defined like this:

In this scenario, when a PeopleSoft application creates an outbound message to an external system that includes the Business Unit/Chartfield, the routing includes a transformation program to translate the data values for the multiple elements to a single UniqueGUID. The external system would then need to transform the UniqueGUID to the equivalent Segment/Ledger.

DVM with Qualifiers

Qualifiers provide additional context to uniquely identify mapping values. A mapping may not be valid unless qualified with additional contextual information. For example, a domain value map containing city code to city name mapping may have multiple mappings for a city based on the country. For example, Kensington is a city in Canada as well as the United States.

The DVM would be defined like this:

In this scenario, when the PeopleSoft application creates an outbound message to an external system that includes the Business Unit/Chartfield, the routing includes a transformation program mapping city name, country, and state to a common value.

Defining Map Options

This section discusses how to define value map options.

Page Used to Define Value Map Options

Defining Map Options

Access the Value Map Options page (Enterprise Components, Integration Definitions, Transformation Framework, Define Map Options).

Cache Minutes	The cache for map definitions and DVM data uses this value to determine the stale datetime. Once this time is exceeded, the cache is refreshed before use.
Concatenation Separator	Indicates the separator for concatenation when importing or exporting data. For V1 (Fusion Middleware FMW) schemas, if values are concatenated from multiple element domains into a single column during export or unconcatenated during an import of data then this separator value is used.

Import Options

These options are defaulted into the import component and any maps that are created. The import process uses the map specific options.

Export Options

These options are defaulted into maps that are created. The export process uses map specific options.

Defining Value Maps

This section discusses how to:

• Add a value map.

• Add elements to a value map.

• Map level options.

• Assign domains to a value map.

Pages Used to Define Value Maps

Adding a Value Map

Access the Define Value Maps search page (Enterprise Components, Integration Definitions, Transformation Framework, Define Value Maps).

To add a value map:

1. Select the Add a New Value tab.

2. In the Map Name field, enter a name for the map.

3. In the Map Type field, select the map type.

4. Click the Add button.

The Elements page appears, where you can define the elements for the map.

Note. After you save the map, you can not change the map type.

Map Types

Maps are either static or dynamic.

Adding Elements to the Map

Access the Define Value Map - Elements page (Enterprise Components, Integration Definitions, Transformation Framework, Define Value Maps).

Description	Enter a description for the value map.
Options	Use this link to modify the options for this map. The link will take you to the Define options for a value map page, where you can set up the options, as well as delete the existing cache for the map. When you click OK, the options will be applied to the map. For new maps, the option values will default to the defined system level option values. See Defining Map Options.
Comments	Enter comments for the value map.
Order	The common element is always assigned order 1. All other elements must be assigned an order of 2 or higher.
Element Name	Enter the element name. Select one and only one element as the common element. The common element must always contain a unique value for each row of data entered into both dynamic and static value maps. For dynamic maps, the common element must be a unique guid. For static maps, the common element can be assigned as required.
Data Type	Values are: String Numeric The data type is used for validation when you are entering data values.
Length	Enter the length of the element. The length is used for validation when you are entering data values.
Required	Select to indicate that this is a required element.
Export	This button allows the user to publish the map definition and data in an XML format using the options defined for the value map. See Exporting Value Maps.
Delete	Use this button to delete the value map.

Mapping Level Options

Access the Define options for a value map page (click the Options link on the Define Value Maps - Elements page).

This page is similar to Define options for a value map used to define the default options, the difference is:

• The options apply to this specific map.

• A Delete Cache button is available to delete the existing cache for the map.

When you click the OK button, the options will be applied to the map and you will be returned to the Define Value Maps page.

See Defining Map Options.

Assigning Domains to the Value Map

Access the Define Value Maps - Domains page (Enterprise Components, Integration Definitions, Transformation Framework, Define Value Maps, Domains).

Each element in a value map must be assigned to at least one domain.

Note. Domain name “UniqueGUID” will be automatically generated as it is required to maintain a unique value for each row of data in a map. Elements may be shared across multiple domains, as long as users understand the data value in the element is unique to the map, not the domain. In general, it is expected most DVM domains will contain a single element, and most PeopleSoft XREF domains will contain multiple elements, though this is not a rule.

Populating a Domain Value Map

This section discusses how to populate a domain value map.

Page Used to Populate a Domain Value Map

Populating a Domain Value Map

Access the Domain Value Map page (Enterprise Components, Integration Definitions, Transformation Framework, Populate Domain Value Maps).

You use domain value maps to enter and maintain data in static value maps. The elements that you define for the value map make up the columns displayed on the page. Elements are ordered and validated as specified in the map definition.

A unique value must be entered for each row of data in every DVM. When you save the page, the component looks for a cached rowset and destroys it. The cache is reloaded the next time it is called.

Importing Value Maps

This section provides an overview of the import file types used with value maps and describes how to import value maps.

Understanding Import File Types Used with Value Maps

There are 2 import file types supported in the Transformation Framework:

• XML Files

• CSV Files

Importing XML Files

There are 2 types of schemas supported in the Transformation Framework:

• V1 Fusion Middleware (FMW)

  This is the schema used with FMW using 11g format. The associated service operation is EOTF_DVM_IMPORT.v1. This is not the default version of the service operation, therefore a version transformation program is executed when a value map is imported in this format.

  See EOTF_DVM_IMPORT.v1, EOTF_XREF_IMPORT.v1.

• PeopleSoft Format

  This is the schema used for PeopleSoft. The associated service operation is EOTF_DVM_IMPORT .v2, which is the default service operation.

  See EOTF_DVM_IMPORT.v2, EOTF_XREF_IMPORT.v2.

When the specified file contains XML, the XML must conform to one of the schemas supported by the import web service. When the file contains XML, users may choose to import a map definition, map data, or both. When importing using the FMW (V1) schema, users may desire to have the import process break composite values into element values. To do so, users need to import the definition, then alter the definition to specify multiple elements for one or more of the domains using the Value Map Definition component, then go back and import data values only. In this scenario, the process will unconcatenate the values using the specified separator. An error will be thrown if a required element is not valued.

Importing CSV Files

When the file contains CSV data, the following rules apply:

• The first row in the file must contain the type of the value map (DVM or XREF) in the first column, and the name of the value map to be imported in the second column.

• Each column in the second row of the file must identify either domain names or element names to import into (no mixing allowed), or reference data. When importing into an existing map, domain and element names will be validated against the map definition. An error will be thrown if not found, or if all required elements for a domain are not included in the file. To define a reference data column that will be ignored by the import process, prefix the name with an asterisk, or leave the name blank.

• Subsequent rows in the file identify the data values to be imported, and must contain the same number of columns as the second row.

• When the data values in a column are composite (concatenated) values identifying the value of each element in the domain, and the second row in the file identifies domain names, the import process will unconcatenate the values using the specified separator for each domain defined with multiple elements. An error will be thrown if a required element is not valued.

• If the value map already contains data for other domains, and the user wishes to add this domain’s values to the existing rows of data, the domain referenced in the first column of data will be used to locate an existing row of data. If a row of data is not found, a new row of data will be created. If multiple rows are found and the additional domain(s) in the file do not allow duplicates, an error will occur. Otherwise, the existing rows of data will be updated with the data values for the other domain(s) in the file.

• If UniqueGUID is blank or not specified in the file, a value will be generated for each new row of data.

• When importing a map definition, each column will be treated as a domain with a single element by the same name. Users may import definition only, then use the Define Value Maps component to alter the definition, then import data only to allow importing composite (concatenated) values or domains with multiple elements.

This is an example of the cross-reference value map csv file in MicroSoft Excel:

This is an example of the DVM value map csv file in MicroSoft Excel:

Page Used to Import Value Map

Importing Value Maps

Access the Import Value Maps page (Select Enterprise Components, Integration Definitions, Transformation Framework, Import Value Maps).

The import value maps component provides users the ability to import a DVM or XREF from a specified file. The import file must be formatted as XML or comma separated values (CSV). If the import may result in data loss, a confirmation dialog will be displayed. Option defaults will be pulled from the system defaults set up by the user in the Value Map Options component.

Exporting Value Maps

This section provides an overview of export schemas and discusses how to export a value map.

Understanding Export Schemas

Value maps can be exported from the Define Value Maps page using the Export button. The map definition and data is published in an XML format using the options defined for the value map. The XML will conform to the schemas specified in the active version of the EOTF_DVM_EXPORT service operation.

• FMW format (V1)

  To export using the FMW schema, you must activate and supply a valid routing for the service operation EOTF_DVM_EXPORT.v1.

  Domain names are used as column names when exporting to a V1 schema. If multiple element domains are exported to the V1 schema, the element values are concatenated to form a compound value for each domain.

• PeopleSoft

  To export using the PeopleSoft schema, you must activate and supply a valid routing for the service operation EOTF_DVM_EXPORT.v2.

• Both

  Activate and provide a routing for both EOTF_DVM_EXPORT.v1 and EOTF_DVM_EXPORT.v2.

See Enterprise PeopleTools PeopleBook: Integration Broker,Managing Service Operations, Configuring Service Operation Definitions

Exporting a Value Map

To export a value map:

1. Select Enterprise Components, Integration Definitions, Transformation Framework, Define Value Maps.

2. Select the map you want to export.

3. Click the Export button.