Data Mapping Using the Siebel Data Mapper

This chapter describes the process of using the Siebel Data Mapper to convert your external data to the Siebel format and your Siebel data to your external data specifications. It contains the following topics:

Siebel Data Mapper Overview

The Siebel Data Mapper provides you with a declarative interface to specify maps for both inbound and outbound data transformation. The maps you set up using the Siebel Data Mapper call the EAI Data Mapping Engine to complete the data transformation. Using the Siebel Data Mapper can often reduce or even eliminate the number of scripts you need to write. The following illustrates the Siebel Data Mapper architecture.

For data mapping within Siebel, Siebel applications now support two data mapping solutions, the Siebel Data Mapper and Siebel eScript Data Mapping. The Siebel Data Mapper has a declarative interface and requires no programming skills. The Siebel eScript Data Mapping uses scripts programmed in eScript as data maps. Because the Siebel Data Mapper is based on a declarative interface, it does not have the flexibility that script-based data mapping has. Use Siebel Data Mapper for most of your integration needs, except for complex mapping situations requiring aggregation, joins, or programmatic flow control.

EAI Data Mapping Engine

To use the EAI Data Mapping Engine, you must enable the following component groups:

Siebel Workflow
Siebel EAI

Note: The display name of the EAI Data Transformation Engine business service in Siebel Tools is EAI Data Mapping Engine. Throughout this guide, it is referred to by both names interchangeably.

EAI Data Mapping Engine Methods

The EAI Data Mapping Engine business service has two methods: Execute and Purge.

Execute

Use the Execute method when your integration requires data transformation. Input and output arguments for the Execute method are shown in the following two tables.

Table Input Arguments for Execute Method

Input Argument	Description
Map Name	Name of your data map.
Output Integration Object Name (Optional)	The target integration object in your map. If you use this argument you have to match it with the data map.
Siebel Message	The instance of your source integration object.
Map Arguments (Optional)	Used as an argument when you call your map from a workflow.

Table Output Argument for the Execute Method

Property Name	Description
Name of the property	The output integration object in Siebel Message format.

Purge

This method is only for development mode. Use the Purge method to purge the database of an existing map. Use this method when you have made a change to a map and you would like to run Execute after these changes. This method does not require any input or output arguments.

Using the EAI Data Mapping Engine

The following checklist outlines the main steps required to use the EAI Data Mapping Engine.

Checklist
□	Create integration objects. For details, see Define Integration Objects.
□	Create data maps. For details, see Creating New Data Maps.
□	Validate data maps. For details, see Validating the Data Map.

The Siebel Data Mapper

The Siebel Data Mapper maps one integration object, source, to another integration object, target. Integration objects contain one or more integration components, which in turn contain one or more integration fields. For details on integration objects, see Integration Platform Technologies: Siebel Enterprise Application Integration.

The following illustrates the Siebel Data Mapping Engine architecture.

The EAI Data Mapping Engine Architecture

A data map defines the relationship between source and target object format. The map controls the transformation process. Transformation maps are stored in the Siebel Database as explained in the following table.

Table Maps and Data Table Relationship

Map Type	Siebel Data Table
Integration Object maps	S_INT_OBJMAP
Integration Object Component maps	S_INT_COMPMAP
Integration Object Field maps	S_INT_FLDMAP

Integration Object Maps

An integration object map is a high-level data map specifying mapping from one integration object to another. An integration object map contains one or more integration component maps and can optionally contain integration map arguments.

Integration Map Arguments

Data maps can be parameterized using integration map arguments. Map arguments can be referenced in any expression, including the integration field map expression, source search expression, precondition expression, and postcondition expression. For example, you may want to have a field map that creates an Order Number in the target object by prefixing the Order Number in the source object with a constant.

You may want to use this map for orders coming from multiple partners and use a different prefix for each partner. To achieve this with a single data map, you can define an argument Prefix in the Integration Map Argument List, and use this argument Prefix in the field map source expression: [&Prefix]+[Order Number]. Then in the input method arguments in EAI Data Mapping Engine business service, you can specify any value for Prefix.

Integration Component Maps

Integration component maps specify how integration components in the source object get mapped to integration objects in the target object. For every occurrence of the source component in the source integration object instance, an instance of the target component is created in the target object instance. An integration component map contains one or more integration field maps. For details on integration component maps, see Creating Integration Component Maps.

Integration Field Maps

Integration field maps specify how fields in the source integration object are mapped to fields in the target integration component. An integration field map target is always a field in the target component of the parent component. An integration field map source can be a constant, a reference to a map argument, a field in the source component, or other legally addressable components such as ancestors of the source component. It can also be a Siebel Query Language expression using one or more of the preceding elements.

Note: For details on integration field maps, see Creating Integration Field Maps. For details on addressing fields in components other than the source component, see Addressing Fields in Components. For details on Source Expression, see Source Expression.

Creating Data Maps

The following checklist provides the high-level steps for creating data maps.

Checklist
□	Define and validate integration objects and determine the required maps. For details, see Define Integration Objects
□	List components and fields within the Siebel object to use. For details, see Define Integration Objects
□	Create a map between the two integration objects. For details, see Creating New Data Maps.
□	Create maps between the components of the objects you mapped. For details, see Creating Integration Component Maps.
□	Create maps between individual fields within the components you mapped. For details, see Creating Integration Field Maps.
□	Validate the data maps. For details, see Validating the Data Map.

Define Integration Objects

Before you create a data map, you need to verify that valid integration objects exist for the source and the target data you want to map. For details on creating and validating integration objects, see Integration Platform Technologies: Siebel Enterprise Application Integration.

Determining Required Maps

The Integration Object Browser lists the existing integration object maps. Use this browser to determine which maps you need to create.

To determine which maps to create

Navigate to Administration - Integration, then Data Maps.
In the Data Maps list, query for the integration objects you want to map.

Creating New Data Maps

Once you determine what objects you need to map, use the Data Map form to create data maps. See Define Integration Objects.

To create a new data map

Navigate to Administration - Integration, then Data Maps.
In the Integration Object Map list, click New to create a new map.
Provide the necessary fields:
- Name. Enter a name for the map you are creating.
- Source Object Name. From the list of values, select the source integration object you want to create the data mapping for.
- Target Object Name. From the list of values, select the target integration object into which you want the data to be transferred.

Creating Maps Using Auto-Map

Once you have created your integration object map, you can use the Auto-Map button to have the Siebel application create the necessary mappings between the underlying components. The root components are always mapped by Auto-Map, whether or not they have the same name. Once the root components are mapped, the Auto-Map recursively walks through every component and their fields to map them. If the components have the same name, the Auto-Map continues to map their fields and their children components. However, if the components have different names, the Auto-Map ignores the current components, their fields, and their children components, and moves on to map the next component. In cases where only the field names are different, the Auto-Map only ignores that one field and continues with its recursive mapping.

Note: You can also use the Auto-Map on an existing mapping when you modify the integration object. The Auto-Map does not overwrite your manual mappings.

Defining Arguments for a Data Map (Optional)

After you create a data map, you can define the arguments for your map. You can then use these arguments when you call the map within workflow. To define arguments, use the Integration Map Argument list on the Integration Object Map form.

To define integration map arguments

Create a new record in the Integration Map Argument list.
Provide the following fields:
- Name. Enter a name for the argument.
- Data Type. From the list of values, select the Siebel Data Type for the argument.
- Display Name. Enter the name that you want displayed.

Creating Integration Component Maps

Once you have defined a data map (see Creating New Data Maps), you need to set up the mapping between the components and the fields within the objects you have mapped. You do this using the Data Map Editor form. The Integration Object Editor list displays existing object maps and provides views in which you can define maps for components and for fields. You use the Integration Component Map view to create integration component maps.

To define integration component maps

Navigate to Administration - Integration, then Data Map Editor.
In the Integration Object Map list, select the map for which you want to define integration component maps.
Create a new record in the Integration Component Map list.
Provide the following fields.
- Name. Name of the map you are creating.
- Source Component Name. The component where you are getting the data.
- Target Component Name. The component where you want to store the data.
- Source Search Specification (optional). The search criteria based on which the records are filtered. See Source Search Specification for details.
- Parent Component Map Name (optional). The parent component field is used when there is a mapping to two target components that share multiple parent components. You can exclude data from one of these child objects by choosing a parent component.
- Precondition (optional). See Preconditions for details.
- Postcondition (optional). See Postconditions for details.

Creating Integration Field Maps

You define the integration field map between your source and target fields using the Integration Field Map form.

To define an integration field map

Create a new record in the Integration Field Map list.
Provide the following fields:
- Target Field Name. Name of the field in the Target Component where the value will be assigned.
- Source Expression. An expression that is used to calculate a value for the Destination Field. See Source Expression for details.

Validating the Data Map

Once you have created your data map, you need to validate your data map.

To validate your data map

Navigate to Administration - Integration, then Data Maps.
Select your data map.
Click Validate to validate your data map.
Take the necessary actions to fix the problems with your map or the associated integration objects.

Examples of Workflow Processes

Depending on whether you are preparing for an outbound or an inbound data exchange, you need to design different workflow processes as described in the following two procedures.

Outbound Workflow Process

To execute the map for an outbound process create a workflow process to query the database, purge the data map, execute the data map, and then write the XML into a file. The following examples illustrate integration between contact and employee business objects.

To create an outbound workflow process

In Siebel Tools, create a workflow process consisting of Start, End, and four business service steps. Set up each business service according to the task it needs to accomplish.

Note: Use the EAI Data Mapping Engine Purge step only in a development environment.

Define the following process properties:

Input Argument	Type
Employee Message	Hierarchy
IntObjName	Hierarchy
Process Instance Id	String
Error Code	String
Error Message	String
Object Id	String
Siebel Operation Object Id	String

The Read DTE from File step uses the EAI Siebel Adapter business service with the Query method, to query the information from the database. The business service uses the following input and output arguments.

Input Argument	Type	Value
Output Integration Object Name	literal	An Employee
Search Specification	Literal	[Employee.Last Name] LIKE "Peterson"

Property Name	Type	Output Argument
Employee Message	Output Argument	Siebel Message

Note: For more information on using the EAI Siebel Adapter, see Integration Platform Technologies: Siebel Enterprise Application Integration.

The second business service step purges the map using the EAI Data Transformation Engine business service (display name is EAI Data Mapping Engine) with the Purge method. This step is only for development mode so that the latest map is picked for the process and should not be used in a production environment. This step does not require any input or output arguments.

The third business service step uses the EAI Data Transformation Engine business service with the Execute method to execute the data map. The business service uses the following input and output arguments.

Input Argument	Type	Value	Property Name	Property Data Type
Map Name	Literal	Outbound DDTE Map	-	-
Output Integration Object Name	Literal	My DTE	-	-
Siebel Message	Process Property	-	Employee Message	Hierarchy

Property Name	Type	Output Argument
IntObjName	Output Argument	Siebel Message

The Siebel Query step uses the EAI XML Write to File business service with the Write Siebel Message method to write the XML into a file. The business service uses the following input and output arguments.

Input Argument	Type	Value	Property Name	Property Data Type
File Name	Literal	c:\emp.xml	-	-
Siebel Message	Process Property	-	IntObjName	Hierarchy

The output argument for this step is optional and can be defined as follows.

Property Name	Type	Value	Output Argument
IntObjName	Output Argument	-	Siebel Message

You can use this argument to put the Siebel Message into a Hierarchy type process property.

Use the Workflow Process Simulator to test your workflow process.

Note: For details on creating a workflow process and using the Workflow Process Simulator to test your workflow process, see Siebel Business Process Framework: Workflow Guide.

Inbound Workflow Process

To execute the map for an inbound process you need to create a workflow process to read the data from a file, purge the data map, execute the data map, and then write the XML into a file.

To create an inbound workflow process

In Siebel Tools, create a workflow process consisting of Start, End and four business service steps. Set up each business service according to the task it needs to accomplish.

Note: The EAI Data Mapping Engine Purge step should only be used in a development environment.

Define the following process properties:

Name	Data Type
Contact Message	Hierarchy
DTE Message	Hierarchy
Process Instance Id	String
Error Code	String
Error Message	String
Object Id	String
Siebel Operation Object Id	String

The Read DTE from File step uses the EAI XML Read from File business service with the Read Siebel Message method, to read the information from a file. The business service uses the following input and output arguments.

Input Argument	Type	Value
File Name	Literal	c:\emp.xml

Property Name	Type	Output Argument
DTE Message	Output Argument	Siebel Message

The second business service step purges the map using the EAI Data Transformation Engine business service (display name is EAI Data Mapping Engine) with the Purge method. This step is only for development mode so that the latest map is picked for the process and should not be used in a production environment. This step does not require any input or output arguments.

The third business service step uses the EAI Data Transformation Engine business service with the Execute method, to execute the data map. The business service uses the following input and output arguments.

Input Argument	Type	Value	Property Name	Property Data Type
Map Name	Literal	Inbound DDTE Map	-	-
Output Integration Object Name	Literal	A Contact	-	-
Siebel Message	Process Property	-	DTE Message	Hierarchy

Property Name	Type	Output Argument
Contact Message	Output Argument	Siebel Message

The Upsert Contact step uses the EAI Siebel Adapter business service with Insert or Update method to write the data into the database. This business service uses the following input argument.

Input Argument	Type	Property Name	Property Data Type
Siebel Message	Process Property	Contact Message	Hierarchy

This step does not have any output arguments.

Note: For more information on using the EAI Siebel Adapter, see Integration Platform Technologies: Siebel Enterprise Application Integration.

Use the Workflow Process Simulator to test your workflow process.

Note: For details on creating a workflow process and using the Workflow Process Simulator to test your workflow process, see Siebel Business Process Framework: Workflow Guide.

About Executing Workflows

Once you have designed and tested your workflows, you can run them in your production environment using Workflow Process Manager Server.

Note: For details on how to activate and execute a workflow, see Siebel Business Process Framework: Workflow Guide.

EAI Data Mapping Engine Expressions

The EAI Data Mapping Engine uses four categories of expressions:

Source expressions
Source search specifications
Preconditions
Postconditions

These expressions support Siebel Query Language expressions. These expressions can address fields in the source component, map arguments, and constants. In addition to fields in the source component, fields in certain other components in the source integration object can be addressed. For details, see Addressing Fields in Components. These expressions are just like Siebel Query Language support invocations of predefined functions and custom business services.

Note: For details on the Siebel Query Language, see Siebel Tools Online Help.

Source Expression

Source Expression is a required field for every integration field map. The source expression can be a literal or, based on scripting if you need to parse data or query the database for a specific value. The source expression is associated with an instance of the input integration component named in the integration component map, which is the parent of the integration field map that contains the source expression. An example of a source expression is:

 [First Name] + " " + [Last Name]

This expression concatenates the First Name and the Last Name and separates them with a space to be moved into a target field such as Full Name.

Note: Only a subset of Siebel Query Language Expressions that do not require context of a business component, is supported by EAI Data Mapping Engine. You can not use the following Siebel Query Language Expressions that require context of a business component in the Source Expression: BCName(), Count(mvlink), IsPrimary(), Min (mvfield), Max(mvfield), ParentBCName(), ParentFieldValue(field_name), Sum(mvfield), GetXAVal(), GetXAValAsNum(), GetXAValAsInt(), GetXAValAsDate(), and XAIsClass().

Source Search Specification

Source Search Specification is a Boolean expression that is used to determine if a given component instance satisfies given criteria. It may only appear in an integration object map or a integration component map together with an integration component name. Defining a source search specification is optional, and if you do not define it, then it does not apply any criteria and returns True.

If a field in the current integration component has the same name as a field in a parent component, then you can only address the parent component field by using dot ('.') notation. An example of a source search specification is:

[Role] = "Billing"

The expression returns True only if the current input integration component has the value Billing in the Role field.

Note: If a source search specification is not provided, then every input integration component whose type matches the input component of the integration component map is processed.

Preconditions

You can use preconditions to make sure that a field of the input object has a certain value or otherwise terminate the process. An error is generated if the field in the input object has any other value, or no value. Preconditions are evaluated immediately before their containing integration component map is executed. If the condition is true then the process continues. If the condition is false then the whole transformation is aborted and EAI Data Mapping Engine returns an error to the caller. An example of a precondition is:

[Role]=Billing Or [Role]=Shipping

This precondition makes sure that the field Role of the input object either has a value Billing or a value Shipping before it proceeds with the process of data transformation.

The precondition is only applied to the input components that are selected by the source search specification. The input components that fail to match the source search specification will not be checked against the precondition.

A precondition expression may address any field in the current input component, and any of its parent components. It can also address any service call parameter that has been declared as a map argument.

Note: The default value for the precondition is True. If the precondition is omitted from an integration component map then no constraint is enforced.

Postconditions

Postconditions are evaluated and applied to the newly created objects when you execute the containing integration component map. If the result of the postcondition is true then the process continues. If the result is false, the whole transformation is aborted and EAI Data Mapping Engine returns an error. Here is an example of a postcondition:

[Object Id]<> Or ([First Name]<> And [Last Name]<>)

This postcondition checks the output component for a value in the Object Id or in the First Name and the Last Name.

Note: Because there is no search specification for output components, the postcondition is applied only once for every output component instantiated because it executes its containing integration component map.

The type of the expression may be any type that can be assigned to the Destination Field type either directly or after applying standard conversions to the result of the expression.

Addressing Fields in Components

You may want to address fields in components other than the source component. This is because your target component may depend on more than one component in the source object. In such cases, you cannot use different component maps with different source components, and the same target component, because each component map creates a different instance of the target component. Data Mapping Engine expressions allow you to use the dot notation to address fields, other than the source component, in source integration object components—for example, [Component Name.Field Name].

Note: The picklist for the source expression in the Data Mapper View does not list fields in components other than the source component. Such fields should be typed in using the dot notation.

Addressing fields in other components is legal only if the cardinality of the component is less than or equal to one relative to the source component—that is, only if the component can be uniquely identified from the context of the source component without using any qualifiers other than the component name. If a field in a component that is not legally addressable is used in the source expression then it leads to a runtime error to the effect that such a field does not exist. Any component that is an ancestor of the source component in the integration object hierarchy has a relative cardinality of 1 which means it can always be uniquely identified from the source component. Therefore, fields in ancestor components can always be legally addressed.

Sibling components can be uniquely identified from the context of the source component only if they do not occur multiple times—that is have a cardinality of less than or equal to 1. Only such siblings can be legally addressed. Therefore, it is not legal to address repeated sibling components. Components that are descendants of a sibling component can be legally addressed only if there is no repeated component in the hierarchical path from the sibling component to the component.

Further, components that are descendants of a sibling of some ancestor of a source component can be legally addressed only if there is no multiply-occurring component in the hierarchical path from the sibling-of-ancestor-of-source component to the component.

Data Mapping Scenario

The following scenarios concern an IT developer named Chris Conway, who works for a computing company, PCS Computing. One of his responsibilities is creating and maintaining the data mappings between Siebel and the other applications in use at PCS. He is assigned to create mapping between Siebel applications and the external application they need to integrate with.

Mapping Between Siebel and an External Application

Chris is in charge of integrating PCS’s Siebel implementation with a custom in-house application. The purpose is to exchange customer information between the two systems.

After weighing various options, Chris decides to use the Siebel Data Mapper instead of scripts to perform the data mapping. He creates the internal integration object using the Siebel Integration Object Wizard in Siebel Tools. He also creates an external integration object using the external application’s DTD.

When Chris is ready to map the two integration objects, he navigates to the Data Mapper and creates a new entry by supplying the name of the map and associating the internal integration object with the external integration object, as explained in Creating New Data Maps. He then uses the Map Editor form to create object, component, and field maps, as explained in Creating Integration Component Maps.

When he finishes creating the map, Chris creates a workflow process in Siebel Tools to define the integration flow. For one of the workflow steps, he defines an invocation of the Siebel Data Mapper. He supplies the appropriate parameters, including the name of the map, and saves his work.