Accessing Data Mapper

You can access Data Mapper to map source schema elements to target schema elements.

Prerequisites:

To open Data Mapper applet:

JRE 1.6 or later must be installed.
Pop-up Blocker must be disabled in the web browser.

To access Data Mapper:

Go to Develop > Services > Data Transformation > Data Mapping.
Click Create New.
Type the name and description of the new mapping activity in the Name and Description text boxes.
You may find Metadata option. This feature is available in Beta version only. Type the keywords in Metadata. iMap will use these keywords to fetch the mapping for future use. All the keywords are stored in Adeptia secure cloud that will help iMap to fetch the mapping suggestions.
Click Data Mapper. A file - startMapper.jnlp will get downloaded to your computer. Double-click the file to view the Data Mapper screen. Click here to know how to map source and target elements.

If you are starting the Data Mapper on your system for the first time, then a warning message is displayed that prevents you from starting this application. Ignore this message and click Start to continue.

If you have read-only permissions, you can view a mapping activity in read-only mode. You can view the applied mapping, create new mapping rules, edit existing mapping rules and even run the simulation. For details, refer to the View Mapping in Read-Only Mode section.
Expand Advanced Properties to set options for splitting data. You can split the source data into different chunks. You can specify the size of chunks in terms of the number of records. In the output, however, only one file is generated at the location specified in the target activity. To know more about splitting data, refer to the Splitting Source Data.

You can set the Advanced Properties at any time of the mapping activity.
Click Save to save mapping.

Understanding Data Mapper

The Data Mapper screen is displayed below:

The Data Mapper screen is divided into eight sections. These are outlined as:

Menu Bar
Tabs Panel
Tool Bar
Source Panel
Target Panel
Mapping Functions Panel
Mapping Graph Area
Parameters Panel

Menu Bar

Menu Option	Sub-Option	Function
File	Load Schema	Loads the source and target schema activity into Data Mapper.
	Save	Saves the mapping activity.
	Exit	Exits the Data Mapper.
View	Enable Tool Tips For Source/Target Tree	Activates or deactivate tooltips to be displayed at the source or target leaf elements. Tool Tips are always displayed as active for root elements.
	Move Connection Ends	Sets the width of connecting lines. By default, it is set to 50px.
	View Mapping XML	Displays the generated XML file with line numbers. It is displayed in read-only mode.
Actions	Validate XSL	Validates the generated XSL file.
	Global Custom XSL Before	Adds a custom XSL code at the top of the mapping XSL.
	Global Custom XSL After	Adds a custom XSL code at the bottom of the mapping XSL.
	On demand (optimized) loading of XML Schema tree	Process only the root level element; not the complete XSD, if the XSD is complex. When you expand the hierarchy elements, it processes child elements and loads them into memory. The hierarchy elements expansion is now displayed in the applet. This option is applicable only on XML schemas. It optimizes the processing of XML schemas and loads the XSD elements only up to 2 levels in the source and target panels. You need to click a hierarchy element to load its further child elements.
	Cache Included Schemas	Set whether or not to cache the included XML schemas instead of inlining them as specified by the XML schema specification. This is applicable to all XML Schema which uses XSD.
	Tree Expand Level for Optimized Loading	Defines the hierarchy level up to which the source and target files will be displayed for the schema loaded in Data Mapper. Hierarchy level is defined in the Tree Expand Level Dialog, which is opened when a user clicks this menu option. By default, its value is 3, that is, Data Mapper will display the hierarchy of source and target files for the respective schema up to level 3.
	Easy Schema Parser Configuration	Defines the hierarchy level up to which the source and target files will process the schema to load it into the Data Mapper. You can define the hierarchy level in the Tree Expand Level Dialog box, it appears when you click on this menu option. The default value in the Tree Expand Level Dialog box is 10. This means that the Data Mapper will display the hierarchy of source and target files for the respective schema up to level 10.
	Namespace	Manages Namespace.
	Enable DBQuery caching	Enables DBQuery cache. This implies that if the same DBquery is fired on another element, it will generate the result from the existing query, instead of creating a new connection.
	Search Element	Searches an element in the Source or Target schema hierarchy on the basis of Wild Card character(s) Comments, Data Type, Current Mapping Rules, Documentation, and Extension Node Element in the tree node of the Data Mapper.
	Set Data Viewer Record Count	Sets the maximum number of records that can be shown in the data viewer.
	Custom Auto Map Options	Adds a custom option for the Auto Mapper.
	Value Map	Adds an option for value map.
	Enable Quick Splitting	Splits data at the source and merges at the target end automatically.
	Import Mapping	Maps the elements in a pattern similar to an existing mapping.
	Set Character Set Encoding for Data Parsing	Sets the character set encoding for the target schema before mapping the data elements.
	Create Context Schema Definition	Contains the name of the context variable that you want to map to another element.
	XSL Settings	XSL Version: Gives you options to change the XSL version used in data mapping. The available options are - Version 1.1, Version 2.0, and Version 3.0. XSL Transformer: Gives you a choice to select a parser to parse your mapping activity in the Data Mapper from the options - SAXON and XALAN. XALAN is supported only in XSL Version 1.1. Changing SAXONICA Transformer Properties If you are using Adeptia Suite v6.9.2 or later, you can change the SAXONICA Transformer Properties. The link contains a complete list of the configuration features available. Steps to include/update a feature: Visit SAXONICA Configuration features page Copy the property URL written in the Description column. (For Example: http://saxon.sf.net/feature/allow-external-functions) Open the file saxonicaConfig.properties from the path ...\<AdeptiaInstallFolder>\AdeptiaServer\ServerKernel\etc Paste the copied property URL Type equality sign (=) and enter a value. All possible values are provided in Description column in the above link. For example: http://saxon.sf.net/feature/allow-external-functions=false You can set multiple properties in the file by defining each property in a new line. Streaming Mode: Streaming is useful while working with large files or documents. Streaming processes files by streaming the part of a file rather than loading the whole file into memory. You need to enable streaming to process large size file while mapping Source and Destination elements but before enabling you must follow some streaming guidelines. This option is supported only with XSL Version 3.0.
	Set Font for Mapping	Sets the font for mapping elements.
	Output Settings	Exclude Result Prefixes: Excludes a namespace prefix from the target element. CData Section Elements: Defines the CDATA elements for the target schema which will be displayed on the Output section of the Debugger screen. Filter Unmapped Elements: Filters the elements or attributes from appearing in the target XML. Indent Output XML: Generates an indented mapping output (XML). Filter Empty Elements: Filters the empty elements from appearing in the output mapping XML. Enabling Filter Empty Elements To enable Filter Empty Elements, you will have to change the jar name manually. Following are the steps to change the jar name. Go to ….Adeptia-installation-path\AdeptiaServer\ServerKernel\etc\launcher.properties In the launcher properties file search for JAR:SAXON. Rename old saxon9pe.jar (old jar name) to saxon9ee.jar (new jar name) Restart kernel and web runner. Handling Saxonica in v6.9.1 With upgrade to Adeptia Suite v6.9.2, existing customers using Adeptia Suite v6.9.2 will be automatically rolled back to the older version (i.e. saxon9pe.jar) of Saxonica. If you want to use Filter Empty Elements feature, follow the steps mentioned above for changing the jar name. After you have upgraded Saxonica to ee version in latest version, you must run regression testing to ensure that all you’re existing mappings are working fine.
Help	Data Mapper Help	Displays online help for the Data Mapper section.
	Mapping Functions Help	Displays online help for mapping functions.
	Tip of the Day	Displays the tips on startup.
	About Data Mapper	Displays the About box for the Data Mapper tool.

Tabs Panel

Name	Function
Data Mapper	Displays the Data Mapper screen for mapping source and target elements.
XSL	Displays the generated XSL code with line numbers for the mapping activity.
Debugger	Validates and views the output of the mapping activity.

Tool Bar

Button	Name	Function
	Load Schema	Open source and target schemas.
	Save Mapping	Saves mapping activity.
	Remove All Mappings	Removes all the mapping between the source and the target elements.
	Validate XSL	Validates generated XSL.
	Auto Mapper	Maps the source and the target elements if the structure of the source and the target schemas and the names of the source and the target elements are similar.
	One to One Mapping	Maps all the source and the target elements under a parent element if the number of elements in the source and the target schemas are same.
	Toggle Element Properties	Displays the property of the source or target element if it is defined in the schema. To view the property, click this button and then click the element whose property you want to view.
	Value Map	Opens the Value Map Options dialog box.
	Custom Auto Map	Automatically map elements of source and target schemas where hierarchy and elements are different.
	XSL Template(s)	Creates an XSL Template and further manage XSL templates from the Manage XSL Template screen.

Source Panel
The Source Panel is used to display a source schema. All the elements of the source schema are listed in the Source Panel. When multiple source schemas are loaded, then all elements of each schema are listed under their respective source nodes.

Target Panel
The Target Panel is used to display a target schema. All the elements of the target schema are listed in the Target Panel. When multiple target schemas are loaded, then all elements of each schema are listed under their respective target nodes.

Mapping Functions Panel
The Mapping Functions Panel displays all mapping functions that can be used to map source and target schema elements. Mapping functions are supported by XSLT. However, the Data Mapper also includes some customized functions, which are not standard of XSLT. Refer to Using Mapping Functions for details on mapping elements using these functions.

In addition to the mapping functions, an option of XSL Template is also displayed on the Mapping Functions Panel. This option enables you to Add XSL Template and further manage XSL templates from the Manage XSL Template screen.

Mapping Graph Area
The Mapping Graph Area is used to map the source and the target elements. You can apply the mapping function between source and target elements in this section. Mapping of the selected target element is displayed in the Mapping Graph Area. This mapping is displayed in the form of Mapping Rules (graphical representation) or as Textual Rules (code representation). Additionally, you can view and set target element properties such as adding comments for target elements and also repeat occurrences of a target element based on the occurrences of a source element, by applying the For Each property. Further, you can apply sorting rules for elements and also set the Disable-Output-Escaping property.

Additionally, you can create Local, Global, and Context Variables in Mapping Graph Area. You can also define Custom Methods and Key Functions in this section.
The Mapping Graph Area comprises of two tabs. These tabs further list sub tabs using which you can perform various functions. These are outlined in the table below.

Tabs of Mapping Graph Area

Tab	Sub-Tabs	Function
Node	Mapping Rules	Displays the graphical representation of the mapping of source and target elements.
	Textual Rule	Displays the textual code representation of the mapping of source and target elements.
	Local Variables	Creates and defines local variables for mapping source and target elements.
	Properties	Displays and set properties for source and target elements. Enables you to add comments for elements and applies sorting rules for target elements. It allows you to set the Disable-Output-Escaping property.
Global	Global Variables	Creates and defines global variables for mapping source and target elements.
	Custom Methods	Creates global methods for mapping source and target elements.
	Key Functions	Creates and defines keys for mapping source and target elements.
	Context Variables	Creates and defines context variables for mapping source and target elements.
	Connection Info	Creates and defines connection info variables for mapping source and target elements.
Data Viewer	Source	Preview data of the uploaded file at the source end.
Data Viewer	Target	Preview data at the target end according to the uploaded source file and mapping rule applied.

The Mapping Graph Area also comprises of buttons. These buttons are displayed based on the selected tabs. All buttons of the Mapping Graph Area are explained in the table below.

Buttons of Mapping Graph Area

Button	Name	Function
	Apply Mapping	Maps the selected source elements to the selected target elements.
	Remove Mapping	Removes the mapping between the selected source and the target elements
	Pop Out Parameters Panel	Pop out the Parameters Panel and display it as maximized.
	Add Global/Local/Context Variable/Key	Adds a new global, local, context variable or a key.
	Save Global/Local/Context Variable/Key	Saves a new local, global, context variable or a key.
	Remove Selected Global/Local/Context Variable/Key	Removes the selected global variable, local variable, context variable or key.
	Remove all Global/Local/Context Variables/Keys	Removes all existing global variables, local variables, context variables or keys.
	Clears Global/Local variable name and value text fields	Clears all data entry fields while adding a local or global variable.
	Add New Method	Adds a new custom method.
	Remove Selected Method	Removes the selected custom method.

You can expand the Mapping Graph Area by clicking Maximize () button displayed on the Split Bar below the Source and Target Panels. Similarly, by clicking Minimize () button, you can restore the Mapping Graph Area to its original size. Alternately, you can drag the Split Bar to resize the Mapping Graph Area and Source and Target Panels.

Parameters Panel

Parameters	Description
Global Variables	Displays a list of all the global variables defined for the mapping of source and target elements in the current mapping object.
Local Variables	Displays a list of all the local variables defined for the mapping of source and target elements in the current mapping object.
Custom Methods	Displays a list of all the methods defined for the mapping of source and target elements in the current mapping object.
Keys	Displays a list of all the keys defined for the mapping of source and target elements in the current mapping object.
Context Variables	Displays a list of all the context variables defined for the mapping of source and target elements in the current mapping object. All context variables created in the Data Mapper are transferred to the Process Flow Designer.
Templates	Displays a list of all the XSL templates created for the mapping of source and target elements in the current mapping object.
Connection Info	Displays a list of all connection info variables.
Global Methods	Displays a list of all class files present in the Custom Classes folder.
Value Map	Displays a list of value maps created for the elements

All parameters are displayed in this section as and when they are created in the mapping process.

You can remove a parameter by right-clicking the parameter and selecting the Remove option.

You can expand the Mapping Graph Area by clicking Maximize () button displayed on the Split Bar below the Source and Target Panels. Similarly, by clicking Minimize () button, you can restore the Mapping Graph Area to its original size. Alternately, you can drag the Split Bar to resize the Mapping Graph Area and Source and Target Panels.

If the Data Mapper needs to process a large file (more than 50 MB) then always use splitting inside the Data Mapper activity. You can enable splitting in Advanced Properties of the Data Mapper activity and set the Splitter/Merger x-path inside the Data Mapper Applet. For information on how to apply splitting in Data Mapper, click here.

Always try to implement database caching inside the Data Mapper. This can be achieved by making a DBQuery at the root node, storing the results in the global variable, and then for each record in the input, use the global variable value to get the results from the database. It would reduce the number of database interactions, probably one for whole Data Mapping and hence optimizing the performance of the Data Mapper.