Data Mapper is a visual data-mapping tool used for mapping elements in advanced data integration projects. This tool allows you to specify source and target schemas and to map data fields from source schema to target schema.

You can use the Data Mapper tool to map source schema elements to target schema elements. You can map one source schema element to a target schema element directly by drag and drop method. Additionally, this tool also offers certain mapping functions using which you can map source and target schema elements.  Furthermore, the Data Mapper supports multiple source and target schemas. This implies that you can select more than one schema at a time, both at the source and the target end. This facilitates mapping of multiple source and target schema elements.

This feature is available in:

Accessing Data Mapper

Pre- Requisites

• JRE 1.6 needs to be installed on your system to open the Data Mapper applet.
• Pop-up Blocker needs to be disabled in the web browser, to open the Data Mapper applet. By default, the Pop-up Blocker is enabled.

Steps to access Data Mapper

1. On the Adeptia Suite homepage, go to Configure > Services > Data Transform and then click Data Mapping.

   This action will show you the Manage Data Mapping screen (see Figure 376).

   

   Figure 376: Manage Data Mapping

2. Click the Create New link. The Create Data Mapping screen is displayed (see Figure 377).

   

   Figure 377: Create Data Mapping

3. Enter the name and description of the new mapping activity in the textboxes Name and Description respectively.

4. Click the Data Mapper button. This displays the Data Mapper screen (refer to Figure 378).

   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.

5. Click Advanced Properties if you want 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 section.

   You can set the Advanced Properties at any time of the mapping activity.

6. Once you have set the Advanced Properties, click Save to save the splitting options.
7. Understanding Data Mapper Applet

The Data Mapper screen is displayed below:

Figure 378: Data Mapper Applet

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
Options of the Menu Bar are explained in the table below.
Table 1: Options of Menu Bar

Tabs Panel
Options of the Tabs Panel are explained in the table below.
Table 2: Options of Tabs Panel

Tool Bar
Options of the Tool Bar are explained in the table below.

Table 3: Options of Tool Bar

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|Using Data Mapper#setForEachproperty]. 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.

Table 4: Tabs of Mapping Graph Area

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.

Table 5: Buttons of Mapping Graph Area

Parameters Panel
The parameters listed in the Parameters Panel are explained in the table below.

Table 6: Parameters Listed in the Parameters Panel

Mapping Elements

The process of mapping elements comprises of various steps. These are outlined as:

• Load So urce an d Target Schemas
• Map Source a n d Ta rget Elements
• Sav e Mapping and Exit Data Mapper

Load Source and Target Schemas

Steps to load Source and Target Schemas

1. Click the Load Schema ( ) button on the Tool Bar (see Figure 379)
   

   
   Figure 379: Load Schema button

   Or click the File menu and select the Load Schema option (see Figure 380).

   
   Figure 380: File Menu in Data Mapper

   
   This action will show you the Select Schema screen which displays a list of existing schemas (see Figure 381).
   

   
   Figure 381: Select Schema

   If you create a new schema, then it will not be displayed in this list. To refresh the list of schemas click the Synchronize button.

2. Select the schema that you want to load. This action will enable the Load button.
   The Select Schema window supports the following functionality:
   • At times, the list of schemas is very long. In such a case, you can search for schemas to be loaded, based on the schema name or type. Enter the name of the schema to be searched in the Quick Search text box and as you type letters, the search field will dynamically search for the values defined in all the schema types and update the table accordingly.
   • To refine the search, you can select the schema type from the Schema Type column. The table will display you only the schema types that you would select. For example, if you select the Excel schema type button then, you will only see the Excel Schemas and the table will be updated accordingly. By default, you will be able to see all the schema types in alphabetical order.
   • To load a schema, search the schema type and select the checkbox(s) corresponding to the schema type. You can select both the source and target schemas for the schema type. In addition, you can select different source and target schema type. This way, you can load multiple schemas at the same time. You can also select all the checkboxes to load all the schemas. There is no limit to the number of schemas that you can load at the same time.
   • You can simultaneously load multiple web service schemas along with other schemas.
   • If you have not created any a particular schema type the no schema will be displayed on clicking the respective schema type button.

3. Click the Load button after you have selected the schema(s) to open. The schema(s) that you will select, will be loaded into the Data Mapper window.

   Click the Close button to close the Select Schema window.

4. Click the Expand button to expand and display all elements of the schemas in their respective panels (see Figure 382).

Figure 382: Source and Target Schema Elements

You can identify the elements in the Source and Target Panels by the legends displayed before the name of the element. These legends are explained in the table below.

Table 7: Legends of Elements

Configuring XSLT Transformer

The Adeptia Suite provides two XSLT processors for transforming data mapping activity.

1. 1. Saxon (New Transformer)
   2. Xalan (Old Transformer)

Saxon transformer is much faster than Xalan. By default, the Data Mapper selects the Saxon transformer to transform all of your new mapping activity.
You can change the parser of any existing Data Mapping activity by following the steps below:

1. Click on the Action menu of the Data Mapping activity of your choice and then select the Edit menu option (see Figure 383).

   
   Figure 383: Editing A Data Mapping Activity

2. On the Edit Data Mapping screen, click on the Data Mapper button to edit the mapping activity (see Figure 384).

   
   Figure 384: Edit Data Mapping Activity Screen

3. In the Data Mapper, click on the Actions menu and then select the XSL Transformer menu option.
4. In the XSL Transformer dialog box, select the Saxon radio button and click Ok.
5. Click on Save button to save the mapping of the Data Mapper.
6. On the Edit Data Mapping screen, click on the Save button to edit the mapping activity. This action will display you a confirmation message (see Figure 385).

Figure 385: Confirmation Message

If you wish to revert to the old transformer (Xalan Transformer) then, you can achieve
that by the following steps:

1. In the Data Mapper, click on the Actions menu and then select the XSL Transformer menu option.
2. In the XSL Transformer dialog box, select the Xalan radio button and click the OK button.
3. Click on the Save button to save the mapping activity.

Search Element in Source or Target Schema Tree

At times, when the source or target schemas are quite large, then searching an element can be very cumbersome. The Data Mapper applet eases this task by allowing you to search for an element in a source or target schema.

Steps to search an element in a source or target schema hierarchy

1. Ensure that the source and target schemas are loaded and all their elements are listed under their respective nodes.

2. Click the Actions menu and select Search Element option (see Figure 386).

   Alternately you can press <Ctrl> + <F> on the keyboard.

   

   Figure 386: Select Search Element from Actions menu

   The Element Search Dialog window is displayed (see Figure 387).

   

   Figure 387: Element Search Dialog Box

3. Enter the name of the element that you want to search for, in the Search Value field. You can also use Wild Card character(s) to search for an element. The Xpath of the element is automatically displayed in the Element Path field.

4. Select the appropriate option in the Scope Panel, to search the element in the Source or Target schema hierarchy. For example, if you want to search in the Source schema hierarchy, then select Source Tree option. Only one option can be selected at a time. By default, Target Tree is selected (see Figure 388).

   

   Figure 388: Enter Parameters in Element Search Dialog Box

   As per the enhanced functionality of the search element, you can now also search the element on the basis of comments, Data Type, Current Mapping (Rules), Documentation and Extension Node Element in the tree node of the Data Mapper.

5. Click Find. This searches for the first occurrence of the element in the selected hierarchy. If the element match is found, then that element is selected and highlighted. The Xpath of that node is displayed in the Element Path field (see Figure 389).

   

   Figure 389: Element Match Found

6. If multiple matches are found for the search criteria, then the Direction Panel and the Find Next button is activated (see Figure 390). You can select the direction in which you want to search in the selected hierarchy. For example, if you want to search upwards in the hierarchy, select Up option. Only one option can be selected at a time. By default, Down is selected.

   

   Figure 390: Multiple Matches Found

7. Click Find Next to search for the next element in the hierarchy, based on the selected direction. Once the element match is found, click Close to close the Search Element dialog box. 

   In case no element match is found, then a warning message is displayed (see Figure 391).

   

   Figure 391: Adeptia Mapper Warning

8. Click Yes to search again, else click No to close this screen.

Map Source and Target Elements

You can map source and target elements using any of the listed methods:

• Drag and Drop Approach
• Buttons on the Tool Bar
• Copy/Paste Mapping
•  Mapping Functions 
  
  

Map Elements Using Drag and Drop Approach

This is the default and most commonly used method for mapping source and target elements.
 

Steps to map elements using Drag and Drop approach

1. Ensure that the source and target schemas are loaded and all their elements are listed under their respective nodes.
2. Click a source element and drag it to the desired target element. A line is displayed, indicating the mapping between the selected source and target element.
3. The graphical representation of the above mapping is displayed in the Mapping Graph Area (see Figure 392).
   
   

   Figure 392: Map Source and Target Element using Drag and Drop Approach

   Once a source and target element is mapped, the letter (M) is displayed next to each mapped source and target element. This signifies that the target element has been mapped to a source element. Refer to Table of Suffixes for details on suffixes displayed next to an element.

4. Similarly, drag and drop each source and target element that you want to map. The mapping between all source and target elements will be displayed (see Figure 393).

   

   Figure 393: Map Source and Target Elements

5. If you have loaded multiple source and target schemas, then drag and drop the source and target elements you want to map. The mapping between these elements will be displayed (see Figure 394).

   

   Figure 394: Map Multiple Source and Target Schema Elements

6. Save the mapping activity and exit the Data Mapper.

   If you are mapping multiple source and target schema elements, then you need to assign data streams, before saving the mapping activity.

   Once you have mapped source and target elements, you can view and validate the generated mapping XSL, from the Data Mapper screen. You can also view the target XML and view and validate mapping output from this screen.

    

   Map Elements using Buttons on the Tool Bar
   You can map source and target elements using certain buttons on the Tool Bar. These buttons are explicated as:

• • One To One Mapping ( )
  • Auto Mapper ( )
  • Remove All Mappings ( )

One to One Mapping
If the number of leaf elements of the parent element in the source and target schema is same, then you can use the One to One mapping button to map all the source elements to the corresponding target elements. 

Steps to use One to One mapping 

1. Ensure that the source and target schemas are loaded and all their elements are listed under their respective nodes.
2. Click and drag the parent element of the source schema to the parent element of the target schema. This will apply template of the source parent element on the target parent element, and activate the One to One Mapping button.

3. Click One to One Mapping ( ) button. All the leaf elements of the parent element in the source schema will be mapped to their respective leaf elements of the parent element in the target schema.

    

   Only leaf elements are mapped using this button. It does not map complex elements. To map complex elements, you need to use the drag and drop method.

   If multiple schemas are loaded, then dragging a source parent element will map all leaf elements of schemas displayed previous to the current schema.
   Moreover, in multiple schemas, mapping can be performed between parents at any level, if the number of their leaf elements is the same.

   
   Auto Mapper
   If the hierarchy and the names of the complex elements are similar, then you can use the Auto Mapper option to map the source elements to the corresponding target elements. In case of complex elements, the hierarchy and the name of all elements must be the same.
   
   

   Steps to use the Auto Mapper

1. Ensure that the source and target schemas are loaded and all their elements are listed under their respective nodes. Additionally, the hierarchy and name of the all elements is the same (see Figure 395).

   
   Figure 395: Same Hierarchy and Element Names

2. Click Auto Mapper ( ) button. The Auto Mapper Options dialog box is displayed (see Figure 396).

   
   Figure 396: Auto Mapper Options

3. Select the mapping criteria from the Choose the Criteria dropdown list. Its options are listed as:
    
   • Ignore Case: The source and the target elements are mapped even if they are of different case. Their attributes are not mapped.
   • Case Sensitive: The source and target elements are mapped only if they are of the same case. Their attributes are not mapped.
   • Ignore Case and Include Attributes: The source and target elements and their attributes are mapped even if they are of different case.
   • Case Sensitive and Include Attributes: The source and target elements and their attributes are mapped, only if they are of the same case.
   • Consider Only Leaf Element Count: The source and target elements are mapped only if the number of leaf elements in the source schema and target schema are the same. It is not necessary that names of source and target elements are similar. Their attributes are not mapped.
   • Consider Only Leaf Element Count and Include Attributes: The source and target elements and their attributes are mapped only if the number of leaf elements in the source schema and target schema are the same. It is not necessary that names of source and target elements are similar.
4. Click OK button. All elements of the source and target schema will automatically be mapped based on the selected criteria (see Figure 397).

Figure 397: Mapped Elements using Auto Mapper

Remove All Mappings
You can use the Remove All Mappings option to remove all mappings from the Data Mapper.

Steps to remove all mappings between source and target elements 

1. Click Remove all Mapping ( ) button. The Remove Options screen is displayed (see Figure 398).This screen displays a list of the properties, variables, custom methods, keys and templates associated with a mapped element, which can be removed with the mapping.

   

   Figure 398: Remove Options

   The Remove Mapping, Remove Comments, Remove For Each and Remove Local Variables options are always enabled. The other options are enabled only if they have been defined for the mapped element.

   
   

2. Select the checkbox(s) of the options that you want to remove and click OK button. All the selected options and all mappings between source and target elements will be removed.

   You can remove mapping associated with each element individually. For details, refer to the section Remove Mapping of an Element.

   Custom Auto Map

   The Auto Mapper feature can be used only when the elements of source and target schema are at the same hierarchy level and have the same names. However, if you want to automatically map the elements when the names of the elements of source and target schemas are different, you cannot use this feature. For example, if the source schema has elements, EmpFirstName and EmpLastName and the target schema has the elements, firstName and lastName then you cannot define mapping between these two schemas using the Auto Mapper feature. 
   
   To define a mapping between the schemas when the elements of source and target schema are at the different hierarchy level (which may include elements at the different parent and child level) and have the different names, you can use the Custom Auto Map feature. This feature enables you to define the mapping between such schemas where elements to be mapped are stored in different parent and child level and in addition elements name are different. 
   

   Scope of a Custom Auto Map

   You can also select the scope of a Custom Auto Map at the time of defining and saving it. Scope of a Custom Auto Map is the context within which it is defined and is accessible within or across the user groups. A Custom Auto Map can be defined in any of the following scope:

• • Global: The Custom Auto Maps defined within Global scope are available within all the mapping activities. Once you create a global Custom Auto Map in a mapping activity, you can use it in all the mapping activities.
  • Group: The Custom Auto Maps defined within Group scope are available only within the specific user group.

By default, a Custom Auto Map is saved in the Global scope and in the Parameter Panel; it is added and displayed under the folder Custom Auto Map/Global. If you select to save the Custom Auto Map in the Group scope then in the Parameters Panel, it is added and displayed under the folder Custom Auto Map/Group. You can also change the scope of a Custom Auto Map from Group to Global directly from the Parameters Panel by right-clicking the Custom Auto Map and selecting the Move to Global option. However, you cannot change the scope of a Custom Auto Map from Global to Group.

The high-level steps to use Custom Auto Maps are:

• Defining a Custom Auto Map
• Activating a Custom Auto Map
• Using a Custom Auto Map in Mapping

In addition, you can also manage a Custom Auto Map from the Parameters Panel.

Defining a Custom Auto Map

You can define a Custom Auto Map by both manually providing the names of the source and target elements to be mapped in the Custom Auto Map Dialog screen or by defining the names of source and target elements to be mapped in a CSV file and then loading the CSV file in the Custom Auto Map Dialog screen. Loading a CSV file is useful when you have a large set of source and target elements to be mapped.

Defining a Custom Auto Map Using a CSV File

Steps to Manually Define a Custom Auto Map

1. Ensure that the source and target schemas are loaded in the Data Mapper and all their elements are listed under their respective nodes (see Figure 399).

   

   Figure 399: Source and Target Schemas with different Element Names

2. Click the Custom Auto Map button on the tool bar or select Custom Auto Map from the Actions menu. The Custom Auto Map Dialog screen is displayed (see Figure 400).

   

   Figure 400: Custom Auto Map Dialog screen

3. Enter the name of Custom Auto Map in the Name textbox.

4. Select the scope of the Custom Auto Map. By default, the radio button Global is selected and a Custom Auto Map is saved in the Global scope.

   If you want to save the Custom Auto Map within the current user group, select the Group radio button. This will save the Custom Auto Map as the group Custom Auto Map and can be used in any mapping activity within the current user group. In the Parameters panel, the Custom Auto Map will be displayed under the folder hierarchy Custom Auto Map/Group.

5. Click the Add button to add a new row for Source Element and Target Element columns. You can also add a row by pressing the Enter key. This will add the row immediately next to the row which is currently selected.
6. Enter the name of the source element for which you want to define Custom Auto Map in the Source Element column.

7. Enter the name of the target element to which you want to map the source element specified in previous step, in the Target Element column (see Figure 401).

   If you need to delete any row, select the respective row and click the Delete  button.

   
   
   Figure 401: Custom Auto Map Dialog

8. Click the Save & Close button to save the Custom Auto Map. This will add the Custom Auto Map in Custom Auto Map hierarchy in the Parameter Panel. Similarly you can add more Custom Auto Map (see Figure 402 ).

Figure 402: Parameters Panel

Defining a Custom Auto Map Using a CSV File

The Custom Auto Map feature also enables you to load a Comma Separated Values (CSV) file. You can use the set of values from the csv file which are separated by comma as a Map set for your process flow. For example, if you want to map the following source and target elements:

Then, you can define the set of values in a csv file as:

• EmpFirstName,firstName
• EmpLastName, lastName
• EmpMiddleInitial, middleNames

Steps to Define a Custom Auto Map Using a CSV File

1. In the Custom Auto Map Dialog screen, enter the name of Custom Auto Map in the Name textbox.

2. Click the CSV button to load a csv file if you want to map the values using the values defined in the csv file. The server will consider the comma separated pair of values as the source and target elements to be mapped (see Figure 403).

   

   Figure 403: Custom Auto Map Dialog: Load CSV

   An Open window is displayed.

3. Browse and select the respective csv file.
4. Click Open to upload the csv file. This will populate the source and target elements columns with the values defined in the CSV file. .

5. Select the scope of the Custom Auto Map (see Figure 404).

   

   Figure 404: Custom Auto Map Dialog

6. Click the Save & Close button to save the Custom Auto Map. This will add the Custom Auto Map value map in Custom Auto Map hierarchy in the Parameter Panel (see Figure 424).

Figure 405: Parameters Panel

Similarly you can add more Custom Auto Maps.

Activating a Custom Auto Map

When you define a Custom Auto Map, by default it is in deactivated state. To use a Custom Auto Map, you need to first activate it. Once you have activated the Custom Auto Map, you can use it in your mapping. Note that only activated Custom Auto Maps can be used in a mapping.
 

Steps to Activate a Custom Auto Map

1. In the Properties Panel, select the Custom Auto Map which you want to activate to use in a mapping.

2. Right-click the Custom Auto Map and select the option Activate (see Figure 406).

   

   Figure 406: Parameters Panel: Custom Auto Map Activate option

3. The status of the Custom Auto Map changes to Active (see Figure 407).

Figure 407: Parameters Panel: Custom Auto Map Status

You can now use this Custom Auto Map in your mapping. Similarly, right-click the Custom Auto Map and select the option Deactivate to deactivate a Custom Auto Map.

Using a Custom Auto Map

After activating a Custom Auto Map, you can use it in your mapping. Note that only one Custom Auto Map can be activated in the current mapping. 

Steps to Use the Custom Auto Map in a Mapping 

1. Load the respective source and target schema.
2. Create and activate the Custom Auto Map.
3. Map the parent record of the Source schema to the parent record of the Target schema.

4. Right-click the parent record of the target schema and select Connect Matching Record options (see Figure 408).

   

   Figure 408: Select Connect Matching Children

   The Connect Matching Children Dialog window is displayed (see Figure 409).

   

   Figure 409: Connect Matching Children Options

    

5. Select the mapping criteria from the Automap options list. Its options are listed as:
    
   • Ignore Case: The source and the target elements are mapped even if they are of different case. Their attributes are not mapped.
   • Ignore Namespace: The source and target elements are mapped, when their names are same but source schema has any namespace prefix.
   • Recursive: Elements of parent level as well as all child level with the corresponding target elements.
   • Mix Attributes: Attributes of source and target schemas are mapped.
6. Select the mapping criteria from the Existing Options list. These options are :
    
   • Retain: If any source and target elements are already mapped, those mapping will not be overwritten.
   • Overwrite: Overwrites all the existing mappings.
7. Click OK. This will map source and target schema as per the criteria selected (see Figure 410).

Figure 410: Source and Target elements are mapped

Managing a Custom Auto Map from Parameters Panel

You can also manage the Custom Auto Map from the Parameters Panel. When you right-click the Custom Auto Map in the Parameters Panel, you can perform the following operations on a Custom Auto Map:

• Edit a Custom Auto Map
• Move a Custom Auto Map from Group to Global
• Delete a Custom Auto Map

Editing a Custom Auto Map
In edit mode, you can edit the name of the Custom Auto Map and the source and target elements to be mapped. Note that you cannot edit the scope of a Custom Auto Map in edit mode. The radio buttons to select the scope becomes non-editable once you save the Custom Auto Map. However, you cannot edit the Custom Auto Map when it has been already been used in the mapping and that mapping has been saved.
 

Steps to Edit a Custom Auto Map

1. In the Properties Panel, select the Custom Auto Map to be edited.

2. Right-click the Custom Auto Map and select the option Edit (see Figure 406).

    

   

   Figure 411: Parameters Panel: Custom Auto Map Edit option

   The Custom Auto Map is open in Edit mode (see Figure 412).

   

   Figure 412: Custom Auto Map Dialog screen in Edit mode

3. Click the Save & Close button to save the Custom Auto Map.

Moving a Custom Auto Map from Group to Global
You can also change the scope of a Custom Auto Map from the Parameters Panel by moving the Custom Auto Map from Group to Global. However, you cannot move a Custom Auto Map if it is in the activated state and has been used in mapping. In addition, you cannot move a Custom Auto Map from Global to Group.
 

Steps to Move a Custom Auto Map

1. In the Properties Panel, select the Custom Auto Map which you want to move from group to global.

2. Right-click the Custom Auto Map and select the option Move To Global (see Figure 429).

   

   Figure 413: Parameters Panel: Move to Global option

3. A warning message is displayed (see Figure 430).

   
   Figure 414: Warning Message

4. Click Yes to confirm moving the Custom Auto Map from Group to Global (see Figure 431).

Figure 415: Change Scope in Parameters Panel

This will change the scope of the selected Custom Auto Map and now the Custom Auto Map will be displayed under the Global folder.
 

Deleting a Custom Auto Map
Steps to Delete a Custom Auto Map

1. In the Properties Panel, select the Custom Auto Map which you want to delete.

2. Right-click the Custom Auto Map and select the option Remove (see Figure 406).

   

   Figure 416: Parameters Panel: Custom Auto Map Remove option

3. A warning message is displayed (see Figure 417).

   

   Figure 417: Parameters Panel: Custom Auto Map Status

4. Click Yes to confirm the deletion of selected Custom Auto Map. The selected Custom Auto Map will be deleted.

Using Value Map

The Value Map feature enables you to define a Map set for a particular value of an element. A Map set enables you to define the mapping values that will be used in the target schema against the values of the elements present in the source schema. For example, if you have a source schema, which has an element, Priority. This element stores the priority levels for the incoming emails and can have the values, Low, Medium, and High. You want to create a Map set for these values and want to map the values in the target schema as:

• For the source element 'High' the Map value for the target element will be 'H'.
• For the source element 'Low' the Map value for the target element will be 'L'.
• For the source element 'Medium' the Map value for the target element will be 'M'.

Scope of a Value Map

You can also select the scope of a Value Map at the time of defining and saving it. Scope of Value Map is the context within which it is defined and can be accessible within or across the user groups. A Value Map can be defined in any of the following scope:

• Global: The Value Maps defined within Global scope are available within all the mapping activities. Once you create a global Value Map in a mapping activity, you can use it in all the mapping activities.
• Group: The Value Maps Templates defined within Group scope are available only within the specific user group.

By default, a Value Map is saved in the Global scope and in the Parameter Panel; it is added and displayed under the folder Value Map/Global. If you select to save the Value Map in the Group scope then in the Parameters Panel, it is added and displayed under the folder Value Map/Group. You can also change the scope of a Value Map from Group to Global directly from the Parameters Panel by right-clicking the Value Map and selecting the Move to Global option. However, you cannot change the scope of a Value Map from Global to Group.
This section covers the following tasks:

• Defining a Value Map
• Using a Value Map in Mapping
• Managing a Value Map from the Parameters Panel

Defining a Value Map

You can define a Value Map by either manually providing the mapping values that will be used in the target schema against the values of the elements present in the source schema in the Value Map Dialog screen or by defining the mapping values that will be used in the target schema against the values of the elements present in the source schema in a CSV file and then loading the CSV file. Loading a CSV file is useful when you have a large set of values to be mapped.

Defining a Value Map Manually

Steps to Manually Define a Value Map

1. Ensure that the source and target schemas are loaded and all their elements are listed under their respective nodes (see Figure 418).

   

   Figure 418: Elements of Source and Target Schema

2. Click the Value Map button on the toolbar or select the option Value Map from the Actions menu. The Value Map Dialog screen is displayed (see Figure 419).

   

   Figure 419: Value Map Options Dialog screen

3. Enter the name of Value Map (for example, PriorityMap) in the Name textbox.

4. Select the scope of the Value Map. By default, the radio button Global is selected and a Value Map is saved in the Global scope.

   If you want to save the Value Map within the current user group, select the Group radio button. This will save the Value Map as the group Value Map and can be used in any mapping activity within the current user group. In the Parameters panel, the Value Map will be displayed under the folder hierarchy Value Map/Group.

5. Enter the value (for example, Low) in Value column and enter its map value(for example, L) in Map column.
6. Click the Add button to add a new row for Value and Map columns. You can also add the row by pressing the Enter key. This will add the row immediately next to the row which is currently selected.
7. You can also provide the default Map value in the Default Value field (for example, Normal). In case if at the source side any value is not provided then the value provided in the Default Value field will be mapped to the target element (see Figure 420). For example, if you want to map the priority of the mail as:
    
   • • For the source element 'High' the Map value for the target element will be 'H'.
     • For the source element 'Low' the Map value for the target element will be 'L'.
     • For the source element 'Medium' the Map value for the target element will be 'M'.

   For the source element which is not provided the target element will be mapped to 'Normal' as defined in the Default Value field.

   
   
   Figure 420: Value Map

8. Select the checkbox Pick from Source if you want to use the source element as the map value for the target element or if you do not want to use the default value as the Map value. For example, if there is a source element 'Normal' then the Map value for the corresponding target element will be 'Normal' and for the source element which is not provided the Map value for the target element will also be a blank.
   
   

   If you need to delete any row, select the respective row and click the Delete  button.

   
   

9. Click the Save & Close button to save the Value Map. This will add the Value Map in Value Map hierarchy in the Parameter Panel. Similarly you can add more Value Map.

Figure 421: Parameters Panel

Defining a Value Map Using a CSV File

The Value Map feature also enables you to load a Comma Separated Values (CSV) file. You can use the set of values from the csv file which are separated by comma as a Map set for your process flow. For example, if you want to change the values defined for the priority of mail as:

• For the source element 'High' the Map value for the target element is 'H'.
• For the source element 'Low' the Map value for the target element is 'L'.
• For the source element 'Medium' the Map value for the target element is 'M'.

Then, you can define the set of values in a csv file as:
Low,L
Medium,M
High,H
 

Steps to Define a Value Map Using a CSV File

1. In the Value Map Dialog screen, enter the name of Value Map (for example, PriorityMap_forcsvfile in the Name textbox.

2. Click the CSV button to load a csv file if you want to map the values using the values defined in the csv file. The server will consider the comma separated pair of values as the target element and its mapped value (see Figure 422).

   

   Figure 422: Value Map Dialog: Load CSV

   An Open window is displayed

3. Browse and select the respective csv file.
4. Click Open to upload the csv file. This will populate the Value and Map columns.
5. Select the scope of the Value Map.

6. Enter the default value in the Default Value field (see Figure 423).

   

   Figure 423: Value Map Dialog screen

7. Select the Pick from Source checkbox, if required.
8. Click the Save & Close button to save the Value Map. This will add the Value Map value map in Value Map hierarchy in the Parameter Panel. Similarly you can add more Value Maps (see Figure 424).

Figure 424: Parameters Panel

Using a Value Map in a Mapping

Steps to Use the Value Map in a Mapping

1. Now to map it, select a target element, for example Priority. The selected target element is shown in Mapping Graph Area.
2. Double click on a value map you want to use, from the Value Map hierarchy of Parameter Panel. For example, PriorityMap.
3. Now double-click the source element. For example, Priority.

4. Connect the output of the source element to input of value map and then connect the output of value map to the input of the target element (see Figure 425).

   

   Figure 425: Use Auto Map in a Mapping

5. Once you have performed the mapping activity, click Apply Mapping ( ) button to save the mapping. The mapping will be applied (see Figure 426).

Figure 426: Mapping between the Source and Target Schema

Managing a Value Map from Parameters Panel

You can also manage the Value Map from the Parameters Panel. When you right-click the Value Map in the Parameters Panel, you can perform the following operations on a Value Map:

• Edit the Value Map
• Move a Value Map from Group to Global
• Delete a Value Auto Map

Editing a Value Map
In edit mode, you can edit the name of Value Map and the map set for an element value. Note that you cannot edit the scope of a Value Map in edit mode. The radio buttons to select the scope becomes non-editable once you save the Value Map. The radio buttons to select the scope becomes non-editable once you save the Value Map. However, you cannot edit the Value Map when it has been already been used in the mapping and that mapping has been saved.
 

Steps to Edit a Value Map

1. In the Properties Panel, select the Value Map to be edited.

2. Right-click the Value Map and select the option Edit (see Figure 406).

   

   Figure 427: Parameters Panel: Value Map Edit option

   The Value Map is open in Edit mode (see Figure 412).

   

   Figure 428: Value Map Dialog screen in Edit mode

3. Click the Save & Close button to save the Value Map.

Moving a Value Map from Group to Global
You can also change the scope of a Value Map from the Parameters Panel by moving the Value Map from Group to Global. However, you cannot move a Value Map if it is has been used in mapping and that mapping has been saved. In addition, you cannot move a Custom Auto Map from Global to Group.
 

Steps to Move a Value Map

1. In the Properties Panel, select the Value Map which you want to move from group to global.

2. Right-click the Value Map and select the option Move To Global (see Figure 429)

   

   Figure 429: Change Scope in Parameters Panel

3. A warning message is displayed (see Figure 430).

   

   Figure 430: Warning Message

4. Click Yes to confirm the change of scope from Group to Global (see Figure 431).

Figure 431: Change Scope in Parameters Panel

This will add the change the scope of the selected Value Map and now the Value Map will be displayed under the Global folder.
 

Steps to Delete a Value Map

1. In the Properties Panel, select the Value Map which you want to delete.

2. Right-click the Value Map and select the option Remove (see Figure 406).

    

   

    

   Figure 432: Parameters Panel: Value Map Remove option

   A warning message is displayed (see Figure 417).

   
   Figure 433: Application Message
   

3. Click Yes to confirm the deletion of selected Value Map. The selected Value Map will be deleted.

Copy/Paste Mapping

This is an additional feature of mapping elements. You can copy the mapping associated with a target element and paste it on other target elements.
 

Steps to copy the mapping of a target element

1. Ensure that the source and target schemas are loaded and all their elements are listed under their respective nodes. Additionally, a source and target element should be mapped.
2. Right-click the target element whose mapping you want to copy and select the Copy Mapping option. This copies the mapping of the selected target element.

Steps to paste the mapping on a target element

1. Ensure that the source and target schemas are loaded and all their elements are listed under their respective nodes. Additionally, the mapping of a target element should be copied.

2. Right-click the target element on which you want to paste the mapping and select the Paste Mapping option.

   The Paste Mapping Options screen is displayed with a list of Paste options (see Figure 434).

   

   Figure 434: Paste Mapping Options

3. This screen displays a list of options that can be pasted with the mapping. It includes the For Each and Comments properties and local variables.

   The Paste Mapping option is always enabled. The other options are enabled only if they have been defined for the copied element.

4. Select the checkbox(s) of options you want to paste with the mapping, and click OK. The mapping with the selected options is pasted on the target element.

   If local variables are pasted for a target element, they are not overwritten, but are added to the existing local variables of that target element.

   You can also copy a mapping instance and paste it onto another instance. This is possible only if the schemas are same in both the mapping instances.

   Import Mapping

   If you want to map elements in a pattern that is similar to an existing mapping, you can import the existing mapping.
   
   Steps to import an existing mapping to a new mapping

1. Ensure that the [source and target schemas are loaded and all their elements are listed under their respective nodes. (see Figure 435).

   
   
   Figure 435: Elements of Source and Target Schema

2. Click Actions menu and select Import Mapping (see Figure 436).

    
   Figure 436: Select Import Mapping Option

   The Import Mapping Dialog screen is displayed (see Figure 437).

   
   
   Figure 437: Import Mapping Dialog

3. Select the mapping you want to import and click Load. This imports the mapping of the selected schemas to the new schemas (see Figure 438 ).

Figure 438: Mapping Imported

Mapping Functions

You can use the mapping functions built-in the Data Mapper to map source schema elements to the target schema elements. These mapping functions are listed as:

• Math
• String
• Date
• Aggregation
• Conditional
• Axis
• Boolean
• Context
• DB

All these mapping functions comprise of sub-functions using which you can map elements.

Steps to map elements using Mapping Function

1. Ensure that the source and target schemas are loaded and all their elements are listed under their respective nodes.

2. Click a target element. The target element node is displayed in the Mapping Graph Area (see Figure 439).

   

   Figure 439: Select Target Element

3. Double-click a source element. The source element is displayed in the Mapping Graph Area (see Figure 440).

   

   Figure 440: Select Source Element

   You can double-click more source elements if required. This will display the selected source elements in the Mapping Graph Area (see Figure 441).

   
   
   Figure 441: Select Second Source Element

4. Click the desired mapping function. This displays a list of sub-functions associated with the selected mapping function.
5. Select the desired sub-function and use it to map the displayed source and target elements.
6. Once you have performed the mapping activity, click Apply Mapping ( ) button to save the mapping.

For details on using these mapping functions, refer to the section Using Mapping Functions.
While mapping elements, certain suffixes are displayed next to source and target elements in the Source and Target Panels. These suffixes are explained in the table below.
Table 8: Suffixes of Source and Target Elements

Save Mapping and Exit Data Mapper

Once you have mapped source and target elements, you can save the mapping and exit the Data Mapper.

Steps to save the mapping and exit the Data Mapper

1. Click the File menu and select Save to save the mapping. Alternately, you can click the Save ( ) button on the toolbar. The server first validates the mapping activity. If successful, it displays a dialog box confirming that the mapping has been saved successfully. If the Comments property is enabled, then clicking Save will display a screen where you need to enter comments related to the mapping. (see Figure 442).

   
   Figure 442: Add Comments (Mapping)

2. Enter comments in the textbox Specify comments for mapping object<object name>.

   The comment should be at least 1 character in length.
   If you enable/disable the Comments property in the middle of a mapping activity, you need to restart the mapping applet.

3. Click OK to save the comments. This displays a dialog box confirming that the mapping has been saved successfully.

4. Click File menu and select Exit to close the Data Mapper applet. A confirmation dialog box is displayed (see Figure 443).

   

   Figure 443: Exit from Data Mapper

5. Click the Yes button to exit the Data Mapper screen and return to the Manage Data Mapping screen. If the mapping object has not been saved, then the Save Mapping Object dialog box is displayed (see Figure 444).

   

   Figure 444: Save Mapping Object

6. Click the Save To Server button to save the mapping object to the Adeptia Suite. A screen is displayed where you need to enter comments related to the mapping. (refer to Figure 442).
7. Enter comments in the Specify comments for mapping object <object name> field.
8. Click OK to save the comments. This displays a confirmation dialog box stating that the mapping has been saved successfully. The control returns to the Manage Data Mapping screen, where a list of mapping activities is displayed.
9. Refresh the Internet browser to view the saved mapping activity.

View and Validate Generated Mapping XSL

This is a very useful feature of the Data Mapper. It enables you to validate and test the generated XSL before saving the mapping activity.

Steps to view and validate the generated mapping XSL

1. Click the XSL tab on the Tabs Panel to view the generated mapping XSL. The generated XSL code with line numbers is displayed (see Figure 445).

   

   Figure 445: Mapping XSL

2. Click the Action menu and select Validate XSL option to validate the generated XSL. A dialog box is displayed confirming that the XSL is valid.

   If generated XSL is invalid, then an error is displayed as a selected line. Error details are displayed in the XSL Errors Pane. It displays one error at a time.

3. Click OK to close the above dialog box.

    

   You can also validate the generated XSL from the Create Data Mapping screen. For more details, refer to the section Splitting Source Data.

    

   View Mapping XML

   The Data Mapper allows you to view the generated XML code, before saving the mapping activity.
   
   Steps to view Mapping XML

1. Click the View menu and select View Mapping XML option. This displays the generated XML code with line numbers, in read-only mode (see Figure 446).

Figure 446: View Mapping XML

View and Validate Mapping Output

Once you have mapped source and target schema elements, you can view and validate the output of the mapping activity. This feature enables you to test the data and make modifications to the mapping activity, before saving it.
 

Steps to view and validate mapping output

1. Click the Debugger tab on the tabs panel to view and validate the output of the mapping activity. The Debugger is displayed on the Data Mapper screen (see Figure 447).

   

   Figure 447: Debugger screen

   This screen is divided into five sections as listed in the table below. 
   Table 9 : Options of the Debugger Screen

   Suffix	Description
   Input	Displays data for all input schemas in XML format. This data can be mockup data or a selected XML file.
   XSL	Displays the generated XSL. You can generate sample output data based on the input data.
   Output	Displays the generated output data for all schemas.
   Variables/ Params	This section comprises of two tabs: Variables Params The Variables tab displays the local variables that are encountered in the generated XSL. The Params tab displays all parameters that are defined for a XSL template. These parameters are displayed only if that XSL template is used in the mapping activity.
   Errors	Displays all errors encountered during debugging.

2. Click the Generate Input Mock up Data button displayed in the Input section, to generate the sample input data in XML format. The sample input data contains name of the element as XML Tags and some randomly generated values as their data. The sample input XML file is displayed in the Input section (see Figure 448).

   
   Figure 448: Generate Mockup Data

   Data will be generated for all input schemas.

3. Alternately, you can attach a source file to the root element of the source schema. Right-click the root element of the source schema and select Attach Source from the dropdown list. Select the source file to attach it. This automatically converts the actual data of the source file into XML input data, which can be validated.

4. Alternately, you can display input data from an existing XML file. Click Load Input XML button ( ) displayed in the Input section to select and upload the existing XML file.

   Another way of uploading the XML file is right-clicking the Input section and clicking the Load option.
   If you load an XML file, then the existing XML code is overwritten. It is not appended.

5. Click the Save button ( ) displayed in the Input section to save the generated input data.

   You can simulate the mapping either on the desktop or on the server. By default, simulation is done on the desktop. Simulating on the server supports global functions, custom methods, Context Variable, Set Context, Get Context and the DBlookup () functions. However, it can be used only in case of mapping of single source and target elements.
    
   While simulating on the server using context variables, if you assign a value to the context variable using the Set Context function and retrieve its value using the Get Context function, it will return the default value of the context variable, instead of the new value assigned. For example, a context variable 'Var1' has the default value as 10 and is later assigned the value of 20 by Set Context function. When the Get Context function is used to retrieve the value of the variable, it returns 10 instead of 20.

6. Select the radio button Run on Server if you want to simulate the mapping activity on the server.

7. Click the Start Execution button displayed in the Output section to generate sample output data based on input data. The generated sample output data is displayed in the Output section (see Figure 449).
   
   

   
   Figure 449: Output XSL

   You can stop the generation of output data at any time by clicking the Stop button displayed in the XSL section.
    In case XML Schema is used at target end, then unmapped elements are filtered out automatically.

8. Click the Save button ( ) displayed in the Output section to save the generated mapping output.
9. A dialog box is displayed using which you can save the XML file at the desired location.

Using Data Viewer

Data Viewer is an advanced feature of Data Mapper which is used to view actual input and output data after applying mapping rules. In data viewer, you can upload actual input file and view the actual output. It also displays error records (if any). Additionally, it also validates the enumerated values and displays the list of enumerated literals for the target element in case XML Schema is used at target.
Data Viewer is helpful if you want to know what will be the output of the mapper. In this case you need not to execute the process flow. You can simply upload the source file and view input and output record.
In data viewer, records are displayed in Grid View as well as Tree View. Table 10 lists the schemas, whose records can be displayed in data viewer.
Table 10: List of schema whose records can be shown in Data Viewer

Steps to use Data Viewer

1. Ensure that the source and target schemas are loaded and all their elements are listed under their respective nodes.
2. Map source and target elements and apply the mapping rule as per your need.

3. To use Data Viewer, click the Data Viewer tab. The Data Viewer panel is displayed (see Figure 450).

   

   Figure 450: Data Viewer

4. To attach the source file, right click the Root element in the Source Panel and select Attach Source option and select the source file (see Figure 451).

   

   Figure 451: Attach Source

5. After selecting the source file, again right click the Root element in source panel and select Preview. Source Data is displayed in the Grid View panel (see Figure 452).

   
   Figure 452: Source records in Grid View

   By default maximum 50 records are displayed in the Data Viewer. To view more records, click Action menu and select Set Data Viewer Record Count and enter the desired value. When you change this value, you need re-attach the source.

6. If there is any error record in the source file, a pop-up message is displayed that "Error Records found in the source data." (see Figure 453).

   

   Figure 453: Pop-up message

7. Click OK to close this pop-up message.

8. To view the source data in Tree View, click the Tree View tab. The source data is selected in the hierarchy view (see Figure 454).

   

   Figure 454: Tree View

9. To view the values of the record, click [+] to expand the Record. Values of the expanded record are shown (see Figure 455).

   
   Figure 455: Records in Tree View

10. Similarly to view values of other records, expand other records.

11. If there is any error encountered in the source data, those error records are shown in the Errors tab. To view the error records, click Errors tab (see Figure 456).

    

    Figure 456: Error Record

12. To view the output record, right click the Root element of the target panel and select Preview option. The generated output records are displayed in the Target panel of Preview pane (see Figure 457).
    
    
    Figure 457: Target Records in Grid View

    In case XML Schema is used at target end, then unmapped elements are filtered out automatically.

13. To view the error records at the target end, click Errors tab of target panel of Data Viewer. It displays:
     
    • The number of errors occurred during transformation
    • The list of errors occurred during transformation
    • List of enumerated literals for the target element if invalid data is mapped to the target element which is restricted to the enumerated values
14. In case you perform any changes in mapping rules, you need to click to refresh the target data according to mapping rules applied.
15. You can also view the output data in hierarchy view, by clicking the Tree View tab.

16. To expand the Source or Target panel, click . The Source or Target panel is shown in the expanded (see Figure 458).

    

    Figure 458: Target Panel in expanded mode

17. To close the expanded Source or Target panel, click .

Viewing Mapping in PDF format

Steps to view mapping activity in PDF format

1. On the Adeptia Suite homepage, go to Configure > Services > Data Transform and then click Data Mapping. The Manage Data Mapping screen is displayed (refer to Figure 376).
2. Click the radio button against the mapping activity whose PDF details you want to view. This selects the mapping activity and activates the PDF View link. Clicking this link displays a PDF file with all information associated with the mapping activity.

3. This file displays divides the mapping information into various pages. The first page contains mapping information such as mapping name, description; creation details and the group owner (see Figure 459).

   

   Figure 459: Mapping Information Document

4. The next page displays all source and target schema information (see Figure 460).

   

   Figure 460: Schema Information

5. The next page displays all other mapping information such as XSL templates used, variables defined, properties, keys, and sorting rules (see Figure 461).

Figure 461: Detailed Mapping Information

View Mapping in Read-Only Mode

If you have read-only rights, you can still view a mapping activity. You can view the applied mapping, create new mapping rules, edit existing mapping rules and run simulation. However, you cannot save the mapping activity.
 

Steps to view mapping in read-only mode

1. On the Adeptia Suite homepage, go to Develop > Services > Data Transform and then click Data Mapping. The Manage Data Mapping screen is displayed (refer to Figure 462).

   

   Figure 462: Manage Data Mapping Screen

2. Click the mapping activity that you want to view in read-only mode. The View Data Mapping screen is displayed (see Figure 463).

   

   Figure 463: View Data Mapping

3. Click the Data Mapper button. This displays the selected mapping activity in the Data Mapper applet in read-only mode (see Figure 464).

   In the read-only mode all save options in the Data Mapper are disabled.

   
   
   Figure 464: Data Mapper in Read-Only Mode

4. You can edit this mapping activity, by adding new mapping rules, or modifying existing ones. Additionally, you can also run simulation on this mapping.
5. Once you have made all changes, if you try and save the modified mapping, you will not be able to save it, as all save options are disabled in read-only mode. The Save ( ) icon and the Save option in the File menu are disabled. Additionally, after making the changes, if you close the Data Mapper applet, then the pop-up to save the mapping activity before exiting, will not appear.

Splitting Source Data

Splitting feature enables you to process large files. You must use splitting if your source file is huge. If you do not use splitting in this case, then Data Mapper may not be able to map it. If the data in the source file is huge, you can split the source data into different chunks. You can specify the size of the chunks in terms of the number of records or data streams. In the output, however, only one file is generated at the location specified in the target activity.
 

Steps to split the source data

1. Click Advanced Properties on the Create Data Mapping screen to expand the advanced properties of the new Mapping activity (see Figure 465).

   

   Figure 465: Advanced Properties

2. Select the Splitting Data checkbox to enable the splitting of data.

   If you select this checkbox, then you have to split the data. You can do this by setting the Splitter XPath in the Data Mapper applet. Alternately, you can split the data by Enabling Quick Splitting feature.

3. Enter the number of records into which you want to split the data, in the Split Number of Records field. For example, if you have a source file of 100,000 records and you want split this file into records of 10,000 each, then you need to enter 10,000 in this field.
4. Select the Parallel Processing checkbox to parallel process these records. By default, records are processed sequentially.

5. Enter the number of chunks you want to process concurrently, in the Maximum Concurrent Processes field. By default, value of 1 is entered.

   It is advised to change this value, if Parallel Processing is selected. Else, only one chunk is processed at a time and hence sequentially.

6. Select the owner from the Owner dropdown list. By default, Administrator is selected.
7. Select the Read, Write and Execute checkboxes to set permissions for the Owner, Group or Other entities. By default, permissions are selected for the Owner and Group entities.

8. If mapping has been saved in the Data Mapper applet, then the XSL code is displayed in Mapping XSL field. This is a very useful feature. You can enter new XSL code or edit existing code to test or debug the mapping. If you save these changes, then they are reflected in the applet. For example, if you need to change the value of a constant, you can change it from this screen itself, instead of the applet. Additionally, any modifications made in the Mapping XSL code in the Data Mapper applet, will overwrite the XSL code in this field.

   If the Advanced Properties and the Data Mapper screens are open simultaneously, then the changes made in the Mapping XSL field in the Advanced Properties screen will not be reflected in the Data Mapper screen.

9. The mapping XML code is displayed in Mapping XML field. You can enter new code or edit existing code. If you save these changes, they will be reflected in the applet.
10. Click Save to save the splitting details.

Set Splitter XPath

To split data you need to set the Splitter XPath on the source hierarchy. The data is split and sent to the transformer which executes the split data. You can set the Splitter XPath in case of a single source schema only. You can also set multiple Splitter XPaths in a source schema.
The following example explains the use of multiple Xpath splitting:

In this scenario we have Root element as the Root for schema. It has two child elements R1 and R2 at the first level. R1 element has two children R1C1 and R1C2. R2 element has two children R2C1 and R2C2.
If in the source xml, there are multiple occurrences for R1 and R2 elements, then we need to set split XPath on both R1 and R2 elements. If we set split XPath on R1 element only then the Data Mapper will assume that R2 has only one occurrence and vice versa. Similarly, if child elements R1C1, R1C2, R2C1 and R2C2 have multiple occurrences, then also R1 and R2 should be set as split XPath. Thus the thumb rule is that the top most node which is repeating, should be set as splitter XPath.
 

Once splitter XPath is defined, during execution, mapping will split the source hierarchy using each splitter Xpath and each chunk will have records specified by Split Number of Records.
In this scenario, when we set R1 and R2 as split XPath then Split Number of Records property is applied for both R1 and R2. For example if the value of Split Number of Records property is 500 then 500 records of R1 and 500 records of R2 are selected.
Splitting data and setting Splitter XPath is very effective when the source data is very large. You can set the Splitter XPath in case of a single source and target schema. You can also set multiple Splitter XPaths in a source and target schema.

Steps to set Splitter XPath

1. Ensure that all the source and target schemas are loaded and all their elements are listed under their respective nodes.

2. Right-click the source schema element that you want to split and select the Set as Splitter XPath option. A screen showing the Splitter XPath details is displayed (see Figure 466).

   
   Figure 466: Splitter XPath Details

   Splitting can be set only on root or record levels. You cannot split on an element level.

3. Click OK. This splits and sets the Splitter XPath on the selected source element.

   Once a Splitter XPath is set for a source element, the letter (S) is displayed next to that source element. This signifies that the source element has been split and the Splitter XPath has been set. Refer to Table of Suffixes for details on suffixes displayed next to an element.

   
   Once you have set a Splitter XPath, you can view it in the Output XML.

   Enabling Quick Splitting

   Another way of splitting source data is to enable the quick splitting feature. This splits the source and sets the Splitter Xpath.
   
   Steps to split data by enabling quick splitting

1. Ensure that all the source and target schemas are loaded and all their elements are listed under their respective nodes.

2. Select Actions menu and select Enable Quick Splitting option. Alternately, you can press <Ctrl> + <Q>. This splits the data and displays the splitter Xpath details (see Figure 467).

   
   Figure 467: Splitter Xpath Details(Enable Quick Splitting)

3. Click OK. This splits and sets the Splitter XPath on the selected source element.
   However, quick splitting splits the records in default numbers. To split into a specific number, you need to set the Splitter Xpath explicitly.

Steps to view Splitter XPath

1. Click View menu and select View Mapping XML. The Mapping XML window is displayed. The Splitter XPath details are displayed with a $Input tag prefixed to Source XPath code (see Figure 468).

   

   Figure 468: Splitter XPath in Mapping XML

You can remove a Splitter XPath that has been set for a source element.
 

Steps to remove Splitter XPath

1. Right-click the source schema element whose Splitter XPath you want to remove and select the Remove Splitter XPath option. A screen showing the Splitter XPath details is displayed (see Figure 469).

   

   Figure 469: Remove Splitter XPath Details

2. Click OK. This removes the Splitter XPath set on the selected source element.

Set Merger XPath

Once you have split the source data by setting the Splitter XPath on a source element, you need to merge the split data at the target end. For this, you need to set the Merger XPath on a target element.
Setting the Merger XPath is largely dependent upon the Splitter XPath. You need to ensure that the number of Splitter XPaths and the Merger XPaths at the source and target schemas respectively are the same.
 

Steps to set Merger XPath

1. Ensure that all the source and target schemas are loaded and all their elements are listed under their respective nodes.
2. Ensure that a Splitter XPath has been set for a source schema element.

3. Right-click the target schema element on which you want to merge the split data and select the Set as Merger XPath option. A screen showing the Merger XPath details is displayed (see Figure 470).

   
   Figure 470: Merger XPath Details

   Merging can be set only on root or record levels. You cannot merge on an element level.

4. Click OK. This merges the split data and sets the Merger XPath on the selected target element.

   Once a Merger XPath is set for a target element, the letter (S) is displayed next to that target element. This signifies that the split data has been merged on the target element and the Merger XPath has been set. Refer to Table of Suffixes for details on suffixes displayed next to an element.

   You can view Merger XPath details in the output XML. A $ input tag is prefixed to the line containing the Splitter XPath details.

   When using Enable Quick Splitting feature, the Merger Xpath is also automatically set when this feature is selected.

5. Once you have set a Merger XPath, you can view it in the Output XML.

To view Merger XPath

Click View menu and select View Mapping XML. The Mapping XML window is displayed. The Merger XPath details are displayed with Target XPath code (refer to Figure 468).

You can remove a Merger XPath that has been set for a target element.
 

Steps to remove Merger XPath

1. Right-click the target schema element whose Merger XPath you want to remove and select the Remove Merger XPath option. A screen showing the Merger XPath details is displayed (see Figure 471).

   

   Figure 471: Remove Merger XPath Details

2. Click OK. This removes the Merger XPath set on the selected target element.

Assign Data Streams

When mapping multiple source and target schema elements, you need to assign streams to the root element of the target schema structures.
 

Steps to assign data streams

1. Ensure that all the source and target schemas are loaded and all their elements are listed under their respective nodes.

2. Right-click the root element of a target schema structure and select the Assign Stream option. The Assign Streams dialog box is displayed (see Figure 472).

   

   Figure 472: Assign Streams

3. This dialog box contains the fields listed in the table below. All fields are populated with values.
   

   Table 11: Fields of Assign Streams Screen

   Field	Description
   Order	Represents the order of occurrence of target schema in the Data Mapper. This field is a read-only field and is automatically populated with value.
   Schema Name	Represents the name of the schema which includes the root to which the stream is to be assigned. This field is a read-only field and is automatically populated with value.
   Root Element	Represents the root element to which the stream is to be assigned. This field is a read-only field and is automatically populated with value.
   Stream Name	Represents the name of the stream to be assigned. This field is automatically populated with value, but is an editable field.

   The root elements, occurrence order and default stream names of all the loaded target schemas are listed in the Assign Streams dialog box. You can edit the stream name.

   It is important to note that the order of streams and the stream names, listed in the Assign Streams dialog box (Mapping) and the Multiple Streams defined in Process Designer should be the same. If you edit a stream name of a mapping activity or add or delete a stream or schema after the activity has already been used in the Process Designer, then you need to update it manually in the Process Designer (Create Multiple Streams section). To know how to use multiple stream in Process Designer, refer to the section Creating Multiple Stream

4. Enter the name of the data stream(s) that you want to edit, for the target element(s), in the textbox Stream Name.

   The name of the data stream does not accept special characters and white spaces.

5. Click OK to assign the stream(s), else click Cancel.

Remove Mapping of an Element

You can remove mapping associated with a particular element.
 

Steps to remove mapping of a particular element

1. Ensure that all the source and target schemas are loaded and all their elements are listed under their respective nodes.
2. Right-click the target element whose mapping you want to remove and select the Remove Mappings option.

3. The Remove Options window is displayed (see Figure 473).

   
   Figure 473: Remove Options (Particular Element)

   This screen displays a list of properties and variables associated with the selected element that can be removed with the mapping.

   Only the Remove Mapping is displayed as always enabled. The other options are enabled only if they have been defined for the particular element.

4. Select the checkbox(s) of the options that you want to remove and click OK button. All the selected options and mapping associated with the particular element will be removed.

Using Context Schema

Context schema allows you to map Context Variable with any element of schema.
This section explains you how to use context schema to map context variable.
High level steps to use context schema are as follows:

• Create Context Schema Definition
• Load Context variables
• Map schema elements
• Modify streaming properties of Mapping Activity

Create Context Schema Definition

First of all you need to create context schema definition. Context schema definition contains name of the context variable that you want to map to other element. While creating context schema definition, you can create context variables or you can import it from the process flow within which you want to use this mapping activity.
 

Steps to create Context Schema Definition

1. In Data Mapper applet, from the Action menu and select Create Context Schema Definition. The Create Context Schema Definition Dialog window is displayed ( see Figure 474 ).

   

   Figure 474: Create Context Schema

   Only the Remove Mapping is displayed as always enabled. The other options are enabled only if they have been defined for the particular element.

2. To add a context variable click Add button and enter the name of the variable.

3. Repeat the same steps to create other variables (see Figure 475 ).

   

   Figure 475: Add Variables

4. You can also import the context variables of the process flow in which you want to use this mapping activity. To import context variables from process flow, click Import From Process Flow button. Import Context Variable dialog box is displayed (see Figure 476 )

   

   Figure 476: Import Context Variables

5. Select the process flow, from which you want to import context variables and click Load.
6. Click Save.

Load Context Variable

Once you have created the context schema, you need to load it at source or target end depending on your need.
 

Steps to Load Context Schema Definition

1. To load the Context Schema at source end, click the Open Source Schema button in the source panel. Select Schema dialog box is displayed ( see Figure 477).

   

   Figure 477:Load Context Variable

2. Select the Context Variable radio button and click the Load button. The variables on Context schema are loaded in source panel.
3. Similarly you can load context schema in the target panel.

Map Schema Elements

Once you load the context schema, you can map its variables to elements of other schema (see Figure 478 ).

Figure 478:Map elements

Modify Streaming Properties of Mapping Activity

Once you created the mapping activity using context schema you need to changes its streaming properties while creating process flow using this mapping activity.
If Context Schema is loaded at source side then there is no need to provide the source (dummy source) stream to the Mapping activity. Similarly if Context schema is loaded at target side then Mapping activity will not generate any output stream, so there is no need to attach dummy target. To achieve this Generate Stream and Consume Stream property has been added to Data Mapper activity in the Process Designer. User can disable these properties based on whether Context schema is loaded at source or target side.
 

Steps to disable input and output stream of mapping activity

1. While designing the process flow, double click the mapping activity that you have created using context schema definition. Properties of the mapping activity are displayed (see Figure 479 )

   

   Figure 479:Change streaming

2. Change the value of Consume Stream or Generate Stream property to false.

   If Context Schema is used at source side, then at run time the actual value of these context variables will be used in the Data mapping. Similarly if Context Schema is used at target side then the output of the data mapping will be parsed and corresponding new value of these context variables will be set.

   Using Mapping Functions

   You can map source and target schema elements using the various mapping functions built-in the Data Mapper. All these mapping functions comprise of sub-functions, which are used to map elements.
   Some mapping functions require use of constant values for mapping elements. For this, you need to add the constant node to the Mapping Graph Area.
   

   Adding a Constant

   Steps to add a Constant

1. Ensure that the source and target schemas are loaded and all their elements are listed under their respective nodes.
2. Ensure that the source and target elements to be mapped are selected and displayed in the Mapping Graph Area.

3. Right-click the blank space in the Mapping Graph Area and select the Constants option. A Constant node is displayed in the Mapping Graph Area (see Figure 480).

   

   Figure 480: Add a Constant Node

4. Double-click the Constant node. The Input dialog box is displayed (see Figure 481).

   
   Figure 481: Enter Constant Value

5. Enter the desired constant value in the Constant Value field.

6. Mark the Add Quotes checkbox as checked, if you want to define the constant as a string. Else, the constant is defined as numeric data. By default, this checkbox is unchecked, implying that a constant is defined as a number. However, you can change the constant to string data type by checking this checkbox anytime.

   If the constant is defined as a string data type, then Appose trophy (') symbol is supported. Additionally, you can enter constants as an input for Select query too.
   You can also define an element name as a constant, and leave the Add Quotes checkbox as unchecked. This will generate a valid XSL.

7. Click OK. This displays the entered value in the Constant node in the Mapping Graph Area.

Using Math Function

The Math mapping function enables you to map elements by performing simple mathematic operations. It comprises of various sub-functions, which are listed in the table below.
Table 12: Sub-Functions of Math Mapping Function

You can use the required sub-function of Math mapping function to map elements. The process of using the Math function is the same for all its sub-functions. Thus, the mapping process using one sub- function is outlined below.
 

Steps to map elements using the 'Division' Math Mapping Function

1. Ensure that the source and target schemas are loaded and all their elements are listed under their respective nodes.
2. Ensure that the source and target elements to be mapped are selected and displayed in the Mapping Graph Area.
3. You need to add a constant value for using this function. Once it is added, a Constant node with its value is displayed in Mapping Graph Area.

4. Click Math function menu and select the Division sub-function. A div node is displayed in the Mapping Graph Area (see Figure 482).

   

   Figure 482: Add Div Sub-Function Node

5. Create a link from the output of the Source element to the first input of the div node.
6. Create a link from the output of Constant node to the second input of the div node.

7. Create a link from the output of the div function node to the Target element (see Figure 483).

   

   Figure 483: Create Links between Nodes for Mapping Elements using Div Function

8. Click Apply Mapping ( ) button. This maps elements using the div sub-function. A line is displayed between the source and target panels showing the mapping of the source element to the target element.

Using String Function

The String mapping function enables you to map elements by manipulating strings. It comprises of various sub-functions, which are listed in the table below.
Table 13 : Sub-Functions of String Mapping Function

You can use the required sub-function of String mapping function to map elements. The process of using the String function is the same for all its sub-functions. Thus, the mapping process using one sub- function is outlined below.
 

Steps to map elements using the 'Concat' String Mapping Function

1. Ensure that the source and target schemas are loaded and all their elements are listed under their respective nodes.

2. Ensure that the source and target elements to be mapped are selected and displayed in the Mapping Graph Area.

   You need to load two source elements for using this mapping function.

   
   
   Figure 484: Add Concat Sub-Function Node

3. Create a link from the output of the first Source element to the first input of the concat node.
4. Create a link from the output of the second Source element to the second input of the concat node.

5. Create a link from the output of the concat node to input of the target element node (see Figure 485).

   

   Figure 485: Create Links between Nodes for Mapping Elements using Concat Function

6. Click the Apply Mapping ( ) button. This maps elements using the concat sub-function. A line is displayed between the source and target panels showing the mapping of the source element to the target element.

Using Date Function

The Date mapping function enables you to map elements by generating dates in specific formats. It also returns the current date and the difference between two dates. It comprises of various sub-functions, which are listed in the table below.

Table 14: Sub-Functions of Date Mapping Function

You can use the required sub-function of Date mapping function to map elements. The process of using the Date function is the same for all its sub-functions. Thus, the mapping process using one sub- function is outlined below.
 

Steps to map elements using the 'Date-Difference' Date Mapping Function

1. Ensure that the source and target schemas are loaded and all their elements are listed under their respective nodes.
2. Ensure that the source and target elements to be mapped are selected and displayed in the Mapping Graph Area.

3. You need to add a constant value for using this function. Once it is added, a Constant node with its value is displayed in Mapping Graph Area.

   This function requires four inputs. The first input represents the value of Date1. The second input represents the value as the format of Date1. The third input represents the value as Date2. The fourth input represents the value as format of Date2. The Date1 and Date2 values can either be in the form of constants or XPath values. The formats of Date1 and Date2 are however always in the form of constants.

4. Click Date mapping function and select Date-Difference sub-function. A date-difference node is displayed in the Mapping Graph Area (see Figure 486).

   

   Figure 486: Add Date-Difference Sub-Function Node

5. Create a link from the output of the first constant value to the first input of the date-difference node.
6. Create a link from the output of the second constant value to the second input of the date-difference node.
7. Create a link from the output of the third constant value to the third input of the date-difference node.
8. Create a link from the output of the fourth constant value to the fourth input of the date-difference node.

9. Create a link from the output of the date-difference node to input of the target element node (see Figure 487).

   

   Figure 487: Create Links between Nodes for Mapping Elements using Date-Difference Function

10. Click the Apply Mapping ( ) button. This maps elements by generating the difference between Date1 and Date2 using the date-difference sub-function.

Using Aggregation Functions

The Aggregation function enables you to map elements by aggregating or counting the values of all nodes in an element. It comprises of various sub-functions, which are listed in the table below.
Table 15: Sub-Functions of Aggregation Mapping Function

You can use the required sub-function of Aggregation mapping function to map elements. The process of using the Aggregation function is the same for all its sub-functions. Thus, the mapping process using one sub- function is outlined below.
 

Steps to map elements using the 'Sum' Aggregation Mapping Function

1. Ensure that the source and target schemas are loaded and all their elements are listed under their respective nodes.
2. Ensure that the source and target elements to be mapped are selected and displayed in the Mapping Graph Area.

3. Click Aggregation function and select the Sum sub-function. A Sum node is displayed in the Mapping Graph Area (see Figure 488).

   

   Figure 488: Add Sum Sub-Function Node

4. Create a link from the output of the Source element to the input of the Sum node.

5. Create a link from the output of the Sum function node to the Target element (see Figure 489).

   

   Figure 489: Create Links between Nodes for Mapping Elements using Sum Function

6. Click the Apply Mapping ( ) button. This maps elements using the Sum sub-function. A line is displayed between the source and target panels showing the mapping of the source element to the target element.

Using Conditional Function

The Conditional mapping function enables you to map elements by building conditional expressions. It comprises of various sub-functions, which are listed in the table below.
Table 16: Sub-Functions of Conditional Mapping Function

Some conditional sub-functions are not included in the Data Mapper screen, but are implemented by extending the 'IF' and 'When' conditions declared in Table 13.14 These sub-functions are listed in Table 13.15.
Table 17: Conditional Functions ('If' and 'When')

You can use the required sub-function of Conditional mapping function to map elements. The process of using the Conditional function is the same for all its sub-functions. Thus, the mapping process using one sub- function is outlined below.
Steps to map elements using the 'IF' Condition (IF CONDITION {} VALUE=[]) Conditional Mapping Function

1. Ensure that the source and target schemas are loaded and all their elements are listed under their respective nodes.
2. Ensure that the source and target elements to be mapped are selected and displayed in the Mapping Graph Area.
3. Click Boolean function menu and then select the >=Greater than Equal operator. A >= node is displayed in the Mapping Graph Area (see Figure 490).
   

   
   Figure 490: Add Greater Than or Equal To Boolean Function Node

   To learn more about Boolean Functions, refer to the section Using Boolean Functions.

4. Add a constant value in the Mapping Graph Area.
5. Create a link from the output of the source element to the first input of the >= operator node.

6. Create a link from the output of the Constant node to the second input of the >= operator node (see Figure 491).

   

   Figure 491: Create Links between Nodes for Mapping Elements using Greater Than Equal To Function

7. Click Conditional mapping function and select IF CONDITION sub-function. Further select For Mapping to Elements option. An IF CONDITION node is displayed in the Mapping Graph Area (see Figure 492).

   

   Figure 492: Add IF Conditional Function Node

8. Create a link from the output of the >= operator element to the first input of the IF CONDITION node.
9. Add a constant value of integer type (for example, 25) in the Mapping Graph Area.
10. Create a link from the output of the Constant element to the second input of the IF CONDITION node.
11. Create a link from the output of the IF CONDITION node to the input of the target element node (see Figure 493).
     

    
    Figure 493: Creating Links between Nodes for Mapping Elements using IF Conditional Function

    If the value of SALARY element in the source data is greater than or equal to 5000, output will be 3000. If the value of TESTCASENO element in the source data is less than 100, output will be an empty tag.

12. Click Apply Mapping ( ) button. This maps elements using IF CONDITION function. A line is displayed between source and target panels showing the mapping of the source element to the target element.

    This function simply filters the records based on the specified Boolean condition, but it does not create a data stream of the filtered records. You need to explicitly create the filtered data stream by creating another mapping (or adding same output schema in Target Panel) and using the IFF CONDITION () function based on the opposite Boolean condition.

    Using Axis Function

    The Axis function contains a list of advance XSL functions that are used to map elements only when the For Each function is applied on the Target node. It comprises of various sub-functions, which are listed in the table below.
    Table 18: Sub-Functions of Axis Mapping Function

    Mapping Function	Sub-Functions	Description	Example
    Axis	File Path – XPath	This is a customized mapping function. This is an XML Lookup which returns the value of the element/attribute within the XML file whose path is specified. The File path and XPath must be specified in single quotes.	FilePath ['C:/correct_file.xml'] XPath {'/employees/employee/Name'} Returns value of Name element from the file correct_file.xml.
    	Self	Returns the element which is the context node itself.	Self::Employee Returns Employee which is the context node itself.
    	Child	Returns the element which is the child of the context node.	Child::Name Returns Name which is a child of the context node.
    	Parent	Returns the element, which is the parent (if any) of the context node.	Parent::Name Returns Name which is a parent of the context node.
    	Following-sibling	This axis contains all the following siblings of the context node. It returns the first occurrence of the element/attribute in the next sibling of the context node. If the context node is an attribute node or namespace node, then this axis is empty.	following-sibling: employee/Name Returns the first occurrence of Name in the next employee node.
    	Ancestor	Returns the element which is the ancestor of the context node. This axis always includes the root node, unless the context node is the root node.	Ancestor::Name Returns Name which is an ancestor of the context node.
    	Ancestor-or-self	This axis contains the context node and the ancestors of the context node. It always includes the root node. It returns the context node or ancestors of the context node.	ancestor-or-self::employees/@val Returns context node or ancestors of context node.
    	Preceding-sibling	This axis contains all the preceding siblings of the context node. It returns the first occurrence of the element/attribute in the preceding sibling of the context node. If the context node is an attribute node or namespace node, then this axis is empty.	preceding-sibling: employee/Name Returns the first occurrence of Name in the previous employee node.
    	Descendant	Returns the element which is the descendant of the context node. This axis does not contain attribute nodes.	descendant::Name Returns Name, which is a descendant of the context node.
    	Descendant-or-self	This axis contains the context node and the descendants of the context node. It returns the context node or descendants of the context node.	descendant-or-self::employees/salary Returns context node or descendants of context node.
    	Generate-id	Generates a unique id for the element/attribute specified by the XPath argument.	generate-id (employees/employee/Name) Returns unique ID for Name element
    	Current	Removes all tags from the specified xml file and returns the data.	current() Returns data of the xml file without tags.

    
    You can use the required sub-function of Axis mapping function to map elements. The process of using the Axis function is the same for all its sub-functions.

    Using Boolean Function

    The Boolean mapping function enables you to map elements by applying various logical operators in building Boolean expressions. It comprises of various sub-functions, which are listed in the table below.
    Table 19: Sub-Functions of Boolean Mapping Function

    Mapping Function	Sub-Functions	Description	Example
    Boolean	Equal	Returns TRUE the first variable argument is equal to the second variable argument.	(5) = (5) returns true
    	Not Equal	Returns TRUE the first variable argument is not equal to the second variable argument.	(5) != (50) returns true
    	Greater Than	Returns TRUE the first variable argument is greater than the second variable argument.	(5)> (3) returns true
    	Less Than	Returns TRUE the first variable argument is less than the second variable argument.	(5) < (8) returns true
    	Greater than Equal	Returns TRUE the first variable argument is greater than or equal to the second variable argument.	(5)>= (5) returns true (5)>= (3) returns true
    	Less than Equal	Returns TRUE the first variable argument is less than or equal to the second variable argument.	(5) <= (8) returns true (5) <= (5) returns true
    	Or	Returns TRUE if either of the two variable arguments evaluate to TRUE otherwise FALSE. These variable arguments can only be of Boolean data type. Hence, their value can either be TRUE or FALSE only.	(True) Or (True) returns true (True) Or (False) returns true
    	And	Returns TRUE if both of the two variable arguments evaluate to TRUE otherwise FALSE. These variable arguments can only be of Boolean data type. Hence, their value can either be TRUE or FALSE only.	(True) And (True) returns true (True) And (False) returns false

    
    A Boolean sub-function is always used in conjunction with a Conditional function. Thus for the process of using the Boolean function, refer to Steps to map elements using the IF Conditional Mapping Function.

    Using Context Functions

    The Context mapping function enables you to map elements by setting or getting value of process flow context variables. It comprises of various sub-functions, which are listed in the table below.
    Table 20: Sub-Functions of Context Mapping Function

    Mapping Function	Sub-Functions	Description	Example
    Context	Set-Context	This is a customized mapping function. Sets the value of the specified variable argument in the process flow context. This value can be string constant, numeric constant, XPath or output of limited set of mapping function, which can be used before set-context function. This function does not return a value. If mapped to a target element, it creates an empty tag of that target element in output XML.	set-context ('index', '123') sets the value of index variable as 123 in the process flow.
    	Get-Context	This is a customized mapping function. Returns the value of the specified variable argument from process flow Context. This value can be string constant, numeric constant, XPath or output of limited set of mapping function. If no value has been set, then the value specified in the second argument is returned.	get-context ('index', '100') Returns the value of index variable from the process flow. If no value has been set for index, then 100 is returned. In get-context function you can also use any variable, which is not declared. In such case get-context creates a variable with the specified name and value, which can be further used with the selected target element. This can be done only in Textual Rule panel.

    
    You can use the Set-Context sub-function of Context mapping function to set value of the process flow variable and send it to the Process Designer. The Get-Context sub-function is used to return the value of the process flow variable.

    Using Set-Context Function

    You can use the Set-Context Function in various ways. These are outlined as:

• Mapping Set-Context function using local variable
• Global declaration of Set-Context function
• Mapping Set-Context function to any target element

Mapping Set-Context function using local variable
Concept
You can map the Set-Context function to a local variable, when you want to set the value of process flow context variable based on output of a mapping function or condition. You can pass the output of mapping function or condition to a local variable and use that local variable as value of set-context function.

For example, if you want to set the value of process flow context variable based on the output of WHEN condition. The WHEN condition is used to return "True" when value of a source element "SALARY" is greater than 8000, else it will return "False". The output of WHEN condition is mapped to a local variable "BolSalary8K". To set the value of "BolSalary8K" to the process flow context variable, you can use Set-Context function. You have to create another local variable "Var1", where value of process flow context variable "ContextVar" is set using Set-Context function. This is done by mapping Set-Context to the value part of the local variable "Var1". The first argument of the Set-Context function is the name of the process flow context variable "ContextVar" and second argument is the local variable "BolSalary8K", which contains the output of WHEN condition.
Advantages

• Need not be mapped to a target element
• Local variable can be used as second argument of Set-Context function
• XPath of a source element can be used as second argument of Set-Context function
• Set-Context function is executed for each record of the source data

Disadvantages

• Local Variable used to map set-context function will have an empty value.

Map Set-Context Function using Local Variable
 

Steps to pass output of mapping function or condition to a local variable

1. Ensure that the source and target schemas are loaded and all their elements are listed under their respective nodes.
2. Click Node tab displayed in the Mapping Graph Area. All tabs of the Node tab are displayed.
3. Click the Local Variables tab. The Local Variable pane is displayed. (refer to Figure 527).
4. Click any target element to declare the local variable in the Local Variable pane.
5. Click Local Variable Name text field and enter the name of the local variable you want to create (e.g. BolSalary8K). Press the Tab or Enter key. This takes the control to the Local Variable Value field.

6. Enter the value of the local variable in the Local Variable Value field. In this example, you have to specify the WHEN condition as displayed in Figure 494.

   

   Figure 494: Create Local Variable

7. Click the Save Local Variable ( ) button to save the declared local variable.

Steps to map Set-Context function using local variable

1. Ensure that the source and target schemas are loaded and all their elements are listed under their respective nodes.
2. Click the Node tab displayed in the Mapping Graph Area. All tabs of the Node tab are displayed.
3. Click the Local Variables tab. The Local Variable pane is displayed. (refer to Figure 527).
4. Click any target element to declare the local variable in the Local Variable pane.
5. Click Local Variable Name text field and enter the name of the local variable you want to create (e.g. Var1). Press the Tab or Enter key. This takes the control to the Local Variable Value field.
6. Click Context mapping function menu and select Set-Context sub-function. Syntax for Set-Context function is displayed in Local Variable Value field.
7. Enter the process flow variable name you want to create (e.g. ContextVar) in the first argument of the Set-Context function.

8. Enter the value of the variable in the second argument of the Set-Context function (see Figure 495).
   
   

   Second argument can be string constant, integer constant, XPath, local variable or output of limited set of mapping function, which can be used before Set-Context function. In this example, BolSalary8K variable is used as second argument of set-context function.

   
   
   Figure 495: Mapping Set-Context to Local Variable

9. Click Save Local Variable ( ) button to save the declared local variable.

Global Declaration of Set-Context Function
Concept
Another way of using the Set-Context function is to declare it globally. When doing this, you need not map it to a target element or local variable.
Advantages

• Easy to use
• Need not be mapped to a target element
• Need not create any local variable

Disadvantages

• Local variable cannot be used in value part of Set-Context function
• If XPath of a source path is used, Set-Context function is executed for the first record only.

Declare Set-Context Function Globally
Steps to declare Set-Context function globally

1. Ensure that the source and target schemas are loaded and all their elements are listed under their respective nodes.
2. Click the Global tab displayed in the Mapping Graph Area. All tabs of the Global tab are displayed.

3. Click the Context Variables tab. The Context Variables pane is displayed (see Figure 496).

   

   Figure 496: Context Variables Pane

4. Click the Context Variable Name text field and enter the name of process flow context variable you want to create (e.g. Var1) Press the Tab or Enter key. This takes the control to the Context Variable Value field.

5. Enter the value of process flow context variable in the Context Variable Value field (see Figure 497).

   

   Figure 497: Enter Context Variable Value

6. Click the Save Context Variable ( ) button to save the declared process flow context variable. This context variable is added to the list of existing context variables in the Context Variables tab. It is also displayed under Context Variables in the Parameters Panel. If you shift focus to another node, or click any of the Mapping Rules, Textual Rules, Node, Properties, XSL or Debugger tabs, without saving the context variable, an alert message is displayed (refer to Figure 522).

7. Click No to save the context variable and shift focus to the other object. If you click Yes, then the defined context variable is cleared and the focus is shifted to the other object.

   You can also set the value of a context variable that is used in a particular condition. For example, if the context variable Var1 is used in an IFF condition in such a way the value of Var1 depends on the condition being True or False. If it is True then Var1 will have a different value. You can set this value of Var1 if the condition is True, using the Set Context function.
   Similarly, you can retrieve the value of a context variable used in a particular condition, if the condition is True.

   You can edit or delete a context variable from the Parameters Panel itself. For details, refer to the Managing a Global Variable from Parameter Panel section.

   
   Mapping Set-Context function to any target element
   Concept
   You can map the Set-Context function to a target element. Since this function does not return a value, it will create an empty tag of that target element in output XML. Thus, it is recommended that you should map the Set-Context function to a target element, whose value is not required at the target end.
   Advantages

• • Need not to create any local variable
  • Executed for each record

Disadvantages

• • Need an additional target element, whose value is not required at the target end

Map Set-Context Function to a Target Element
Steps to map Set-Context function to a target element

1. Ensure that the source and target schemas are loaded and all their elements are listed under their respective nodes.
2. Select the target element that you want to map with Set-Context function.

3. Click Context mapping function menu and select Set-Context sub-function. A set-context node is displayed in the Mapping Graph Area (see Figure 498).

   

   Figure 498: Set-Context Node

4. Add a constant node with the name of variable (e.g. index), whose value is to be set in the process flow context.
5. Create a link from the output of the constant node (index) to the first input of the set-context node.

6. Add another constant node for the second argument (e.g. 100) of the set-context function.

   Second argument can be string constant, integer constant, XPath, local variable or output of limited set of mapping function, which can be used before Set-Context function.

7. Create a link from the output of second constant node (100) to the second input of the set-context node.

8. Create a link from the output of the set-context node to the target element (see Figure 499).

   

   Figure 499: Create Links between Nodes for Mapping Set-Context Function to Target Element

9. Click the Apply Mapping ( ) button. This maps the Set-Context function to the target element. The defined variable (index) is passed to the process flow with the value 100. If you shift focus to another node, or click any of the Mapping Rules, Textual Rules, Node, Properties, XSL or Debugger tabs, without applying the mapping, an alert message is displayed (refer to Figure 522).

10. Click No to apply the mapping and shift focus to the other object. If you click Yes, then the mapping activity is cleared and is replaced by the previous mapping in the Mapping Graph Area and the focus is shifted to the other object.

    At times the mapping is too large and the applet memory may exceed 256M. In such cases, the mapping will fail and return an error of insufficient memory. You can overcome this situation by increasing the applet memory. For details, refer to Appendix A in the Administrator Guide.

    Using DB Function

    The DB function enables you to get data from the database, based on a condition. It comprises of a sub-function, which is listed in the table below.
    Table 21: Sub-Function of DB Mapping Function

    Mapping Function	Sub-Functions	Description	Example
    DB	DBQuery	Returns data from the database, based on a query.	DBQuery( 'select EmpID from EMP where EMPID=1035', var1, 'true') returns all the records from the EMP table, where EMPID is 1035. Here, 'var1' is the Connection Info variable. If you change the last boolean argument from true to false, only the first record is returned.
    	PreparedQuery	Returns data from the database, based on a query.	PreparedQuery ('SELECT EMPID FROM EMP WHERE EMPNAME=? AND EMPCITY=? AND EMPISMALE=?, $oracle_databaseserver, true ,('Smith','Chicago','true')'). Here, '=?' is the variable name that you pass in the braces. The '$oracle_databaseserver' is the name of the Connection Info variable. If you change the last boolean argument from true to false, only the first record is returned.

    
    You can use this sub-function of DB mapping function to get data from the database. The process of using this sub-function is outlined below.
    

    Steps to get data from the database using the 'DBQuery' DB Mapping Function

1. Ensure that the source and target schemas are loaded and all their elements are listed under their respective nodes.

2. Ensure that a Connection Info variable is created for the DBQuery and is listed in the Parameters Panel.

   For details on creating a Connection Info variable, refer to the Declaring Connection Info Variable section.

3. Double-click the target element that you want to map with the DBQuery. It is displayed in the Mapping Graph Area.

4. Click the DB function and select the DBQuery sub-function. A DBQuery node is displayed in the Mapping Graph Area (see Figure 500).

   

   Figure 500: Add DBQuery Sub-Function Node

5. Add a constant node with the query for searching data from the database based on the specified condition (e.g. select Name from EMP where designation= 'Manager').
6. Create a link from the output of the constant node to the first input of the DBQuery node.

7. Double-click the required Connection Info variable under Connection Info in the Parameters Panel. The selected Connection Info variable node is displayed in the Mapping Graph Area (see Figure 501).

   

   Figure 501: Connection Info Variable in Mapping Graph Area

8. Create a link from the output of the Connection Info variable to the second input of the DBQuery node.
9. Add another constant node for the third argument of the DBQuery function. This is a Boolean value as true or false.
10. Create a link from the output of this constant node to the third input of the DBQuery node.

11. Create a link from the output of the DBQuery node to the input of the target element (see Figure 502).

    

    Figure 502: Create Links between Nodes for Mapping DBQuery Function to Target Element

12. Click the Apply Mapping ( ) button. This maps the DBQuery function to the target element. The defined query is passed to the database where a connection is created using the Connection Info variable. If the Boolean value is set as 'True' then the database fetches all the values that match the query. If the value is 'False', then the database fetches only the first matching value. If you shift focus to another node, or click any of the Mapping Rules, Textual Rules, Node, Properties, XSL or Debugger tabs, without applying the mapping, an alert message is displayed (refer to Figure 522).

13. Click No to apply the mapping and shift focus to the other object. If you click Yes, then the mapping activity is cleared and is replaced by the previous mapping in the Mapping Graph Area and the focus is shifted to the other object.

    At times the mapping is too large and the applet memory may exceed 256M. In such cases, the mapping will fail and return an error of insufficient memory. You can overcome this situation by increasing the applet memory. For details, refer to Appendix A in Administrator Guide.

    
    Steps to get data from the database using the 'PreparedQuery' DB Mapping Function

1. Ensure that the source and target schemas are loaded and all their elements are listed under their respective nodes.

2. Ensure that a Connection Info variable is created for the PreparedQuery and is listed in the Parameters Panel.

   For details on creating a Connection Info variable, refer to the Declaring Connection Info Variable section.

3. Double-click the target element that you want to map with the PreparedQuery. It is displayed in the Mapping Graph Area.

4. Click the DB function and select the PreparedQuery sub-function. A PreparedQuery node is displayed in the Mapping Graph Area (see Figure 503).

   

   Figure 503: Add PreparedQuery Sub-Function Node

5. Add a constant node with the query for searching data from the database based on the specified condition (e.g. Select EMPID from EMP where EMPNAME=? AND EMPCITY=? AND EMPISMALE=?, $oracle_databaseserver, true ,('Smith','Chicago','true')).
6. Create a link from the output of the constant node to the first input of the PreparedQuery node.

7. Double-click the required Connection Info variable under Connection Info in the Parameters Panel. The selected Connection Info variable node is displayed in the Mapping Graph Area (see Figure 504).

   

   Figure 504: Connection Info Variable in Mapping Graph Area

8. Create a link from the output of the Connection Info variable to the second input of the PreparedQuery node.
9. Add another constant node for the third argument of the PreparedQuery function. This is a Boolean value as true or false.
10. In the fourth argument of the PreparedQuery function you can pass values through either as a variable, or as a constant, or as a xpath.
11. Create a link from the output of this constant node to the third input of the PreparedQuery node.

12. Create a link from the output of the PreparedQuery node to the input of the target element (see Figure 505).

    

    Figure 505: Create Links between Nodes for Mapping PreparedQuery Function to Target Element

13. Click the Apply Mapping ( ) button. This maps the PreparedQuery function to the target element. The defined query is passed to the database where a connection is created using the Connection Info variable. If the Boolean value is set as 'True' then the database fetches all the values that match the query. If the value is 'False', then the database fetches only the first matching value. If you shift focus to another node, or click any of the Mapping Rules, Textual Rules, Node, Properties, XSL or Debugger tabs, without applying the mapping, an alert message is displayed (see Figure 506).

    
    Figure 506: Mapper Warning

14. Click No to apply the mapping and shift focus to the other object. If you click Yes, then the mapping activity is cleared and is replaced by the previous mapping in the Mapping Graph Area and the focus is shifted to the other object.
    
    

    At times the mapping is too large and the applet memory may exceed 256M. In such cases, the mapping will fail and return an error of insufficient memory. You can overcome this situation by increasing the applet memory. For details, refer to Appendix A in Administrator Guide.

    Using Textual Rules

    Textual Rules are used for mapping source elements, mapping functions or constants to target elements, by defining the elements in syntax form.
    
    Steps to map elements using the Concat function using Textual Rules

1. Ensure that the source and target schemas are loaded and all their elements are listed under their respective nodes.
2. Select the target element that you want to map. It is displayed in the Mapping Graph Area.
3. Click the Textual Rules tab in the Mapping Graph Area.

4. Click String mapping function and select Concat sub-function. The syntax for the Concat sub-function is displayed in the Mapping Graph Area (see Figure 507).

   

   Figure 507: Syntax for Concat Sub-Function

5. This syntax has two parameters. Double-click a source element that you want to set as the first parameter. This displays the selected source element in the syntax.
   Similarly, double-click another source element as the second parameter. This is displayed in the syntax (see Figure 508).
   
   

   Figure 508: Parameters of the Concat Syntax

   You can indent the textual rule content as per your requirement.

6. Click the Apply Mapping ( ) button. This maps elements using the concat sub-function. A line is displayed between the source and target panels showing the mapping of the source element to the target element

Using Namespace

Namespace allows you to add, view, edit, and remove the namespace in the XSL. All the Namespaces present in the source and target XSD's are automatically placed in the XSL generated. These Namespaces can be viewed using View Namespace option in the Namespace submenu.
Adding Namespace
 

Steps to add a Namespace in the XSL

1. Click the Actions menu and select Namespace.

2. Click the Namespace submenu and select Add Namespace. The Namespace dialog box is displayed (see Figure 509).

   

   Figure 509: Adding Namespace

3. Enter the Namespace and click OK. The Namespace is added to the XSL.

For Example, xmlns:oa="http:/ /www.openapplications.org/oagis"

Editing Namespace
Steps to edit a Namespace in the XSL

1. Click the Actions menu and select Namespace.

2. Click the Namespace submenu and select Edit Namespace. The Select Namespace screen is displayed (see Figure 510).

   

   Figure 510: Select Namespace

3. Select the namespace you want to edit. This activates the OK button. This displays the Namespace dialog box in edit mode.
4. Make the necessary changes.

5. Click OK to save the modifications.

   Similarly, you can view or remove an existing namespace.

   Using XSL Template

   An XSL template is a customized template. If you need to repeatedly perform a set of functions, you can create an XSL template defining those functions, and then later call that XSL template whenever required. For example, if you need to perform addition of two numbers at regular intervals, you can define the addition function in an XSL template. You can then call this XSL template whenever required.
   The XSL Template option enables you to manage XSL templates. You can add, update or delete an XSL template using this option. Once you have added an XSL template, you can use it to map elements. You can also define the scope of an XSL template while creating and saving it. Scope of an XSL Template is the context within which it is defined. An XSL template can be defined in any of the following scope:

• Local: The XSL Templates defined within Local scope are available within the mapping activity, in which you have created the template.
• Global: The XSL Templates defined within Global scope are available within all the mapping activities. Once you create a global template in a mapping activity, you can use it in all the mapping activities.
• Group: The XSL Templates defined within Group scope are available only within the specific group.

Creating XSL Template

You can create a XSL template using:

• Mapping Rules: Enables you to use the predefined mapping functions.
• XSL Rules: Enables you to define the XSL Template code to use the defined parameters.

Steps to Create an XSL template using the XSL Rules

1. Click XSL Template option displayed next to mapping functions on the Mapping Functions Panel.

2. Select Manage XSL Template option or click the Manage XSL Template icon in the toolbar (Figure 511).

   

   Figure 511: Data Mapper

   The Manage XSL Template screen is displayed (see Figure 512).

   

   Figure 512: Manage XSL Template

3. Enter the name of the new XSL template that you want to create in the Name field. This displays the XSL tags in the XSL Template area.

4. Select the scope of the XSl Template. The default scope of an XSl Template is Local.

   If you want to save the template as the Global Template, select the Global radio button. This will save the XSL template as Global XSL template and can be used in any mapping activity. In the Parameters panel, the XSL template will be displayed under the folder hierarchy Templates/Global.
    
   If you want to save the template within the current user group, select the Group radio button. This will save the XSL template as Group XSL template and can be used in any mapping activity within the current user group. In the Parameters panel, the XSL template will be displayed under the folder hierarchy Templates/Group.

   You cannot change the scope of a XSL Template once you have saved the XSL template. The respective radio buttons become non-editable thereafter.

5. Click the Add button to add parameters for the new XSL template.
6. Enter the name of the parameter you want to add in the Name field. It also generates the corresponding XSL in the XSL Template editor on the Manage XSL Template screen

7. Click the Add icon again to add the required parameters or press the Enter key to insert a new row. This will add a row immediately next to the row which is currently selected (see Figure 513).

   
   Figure 513: Manage XSL Template: XSL Rules

   If you need to delete any row, select the respective row and click the Delete  icon.

   You can also define variables as the parameters of the XSL Template. To add a global variable, refer to the section Using Global Variable.

8. Enter the code for the function that you want to perform, for example, addition of two numbers, in the 'add here' line, in the XSL Template field. The syntax of the addition function would be:
   <xsl:value-of select ="$param1 + $param2"/>
   
   where:
   value-of is the syntax for the value to be returned
   param1 and param 2 are the defined parameters
9. Once you have entered the code, click Local XSL template. This displays the saved template under the Templates list on the XSL Template screen. The new XSL template is also displayed under Templates in the Parameters Panel (see Figure 514).

Figure 514: Parameters Panel

Once you have created a XSL template, you can use it to map elements. On the Manage XSL Template screen, by default the XSL Rules tab is selected. To create a XSL template using the Mapping Rules, click the Mapping Rules tab.
 

Steps to create an XSL template using the XSL Rules

1. On the Manage XSL Template screen, click the Mapping Rules tab.
2. Enter the name of the new XSL template that you want to create in the Name field.
3. Select the scope of the XSL Template. The default scope of the XSL template is Local.
4. Click the Add icon to add parameters for the new XSL template.
5. Enter the name of the parameter you want to add, in the Parameter Name field.
6. Click the Add icon again to add the required parameters or press the Enter key to insert a new row. This will add a row immediately next to the row which is currently selected.

7. Select the required Mapping Function. For example, select the mapping function, Math > Add (see Figure 515).

   

   Figure 515: Manage XSL Template: Mapping Rules

8. The respective mapping function (add symbol for this example) is displayed in the Mapping template.

   

   Figure 516: Mapping Template: Mapping Function Symbol

9. Use the parameters that you have added in the previous steps.
   

   

   If you need to delete any row, select the respective row and click the Delete  icon.

10. Click the Save button to save the Local XSL template. This displays the saved template under the Templates list on the XSL Template screen. The new XSL template is also displayed under Templates in the Parameters Panel.

Figure 517: Parameters Panel

Map Elements using XSL Template

Steps to map elements using an XSL Template

1. Ensure that the source and target schemas are loaded and all their elements are listed under their respective nodes.
2. Ensure that the source and target elements to be mapped are selected and displayed in the Mapping Graph Area.

3. Click the XSL template that you want to use for performing the required function, from the Templates list in the Parameters Panel. A Call XSL Template node is displayed in the Mapping Graph Area (see Figure 518).

   

   Figure 518: Call XSL Template Node

4. Create a link from the output of the first Source element to the first input of the Call XSL Template node.
5. Create a link from the output of the second Source element to the second input of the Call XSL Template node.

6. Create a link from the output of the Call XSL Template function node to input of the Target element node (see Figure 519).

   

   Figure 519: Create Links between Nodes for Mapping Elements using XSL Template

7. Click Apply Mapping ( ) button. This maps elements using the Call XSL Template function node.

Using Global Variable

Global variables are used for mapping source elements, mapping functions or constants to target elements. They are declared and used globally for all target elements.
To use a global variable in a mapping activity, you need to map it to a target element. This will successfully execute the global variable when you execute the mapping activity in the process flow.

Declare Global Variable
 

Steps to declare a Global Variable

1. Ensure that the source and target schemas are loaded and all their elements are listed under their respective nodes.
2. Click the Global tab in the Mapping Graph Area. All tabs of the Global tab are displayed.

3. Click the Global Variables tab. The Global Variable pane is displayed in the Mapping Graph Area (see Figure 520). 

   
   Figure 520: Global Variable Pane

4. Click the Global Variable Name text field and enter the name of the global variable you want to create (e.g. emp_age). Press the Tab or Enter key. This takes the control to the Global Variable Value field.
5. Enter the value of the global variable in the Global Variable Value field. You can enter the value of the global variable using one of the listed methods:
    
   • Click required source element
   • Select the required Mapping function
   • Type the required value manually

   • Select a Custom Method

     To select a Custom Method as the value of a global variable, double click the desired Custom Method under Custom Methods in the Parameters Panel. The selected Custom Method is displayed in the Variable Definition field.
     To learn how to declare a Custom Method, refer to section Using Custom Method.

6. Enter comments for the global variable in the Add Comment field (see Figure 521). For example, if the global variable value contains complex XSLT logic, you can enter its description in this field.

   The Comments field is resizable.

   
   
   Figure 521: Enter Name, Value and Comments of Global Variable

7. Click Save Global Variable ( ) button to save the global variable. This global variable is added to the list of existing variables in the Global Variable Name field. It is also displayed under Global Variables in the Parameters Panel. If you shift the focus to another node, or click any of the Mapping Rules, Textual Rules, Local Variables, Properties, XSL or Debugger tabs, without saving the global variable, an alert message is displayed. (see Figure 522). The comments added for the global variable are saved and displayed above the global variable declaration in the Mapping XSL (refer to Figure 523).

   
   Figure 522: Alert Message

   For example, you have defined a global variable Var1, and you click the Name target element, without saving Var1, then the alert message is displayed.
   The alert message is also displayed when shifting focus between Global and Node tabs.

8. Click No to save the global variable and shift the focus to the other object. If you click Yes, then the defined global variable is cleared and the focus is shifted to the other object.

Figure 523: Comment in Mapping XSL

Managing a Global Variable from the Parameters Panel
Once the global variable is added to the Parameters Panel, you can edit it or delete it anytime from this Panel itself.
 

Steps to manage a Global Variable from the Parameters Panel

1. Right-click the global variable that you want to edit or delete. This displays the right dropdown menu (see Figure 524).

   

   Figure 524: Right-Click menu of Elements in Parameter Panel

2. Select Edit to edit the variable. This displays the selected global variable in Edit mode. You can edit the value of the global variable in the Global Variable Value field. You can also edit the name of the global variable.

3. Alternately, select Remove to delete the selected variable. This displays a confirmation screen for the delete operation (see Figure 525).

   

   Figure 525: Confirm Delete of Global Variable

4. Click Yes to delete the selected variable.

Map Global Variable to Target Element
Once you have created a global variable, you can map it to a target element.
 

Steps to map Global Variable to target element

1. Ensure that the source and target schemas are loaded and all their elements are listed under their respective nodes.
2. Click the Node tab displayed in the Mapping Graph Area. All tabs of the Node tab are displayed. Click Mapping Rules tab.
3. Select a target element. This displays the selected target element node in the Mapping Graph Area.

4. Double-click the required global variable under Global Variables in the Parameters Panel. The selected global variable node is displayed in the Mapping Graph Area (see Figure 526).

   

   Figure 526: Add Global Variable Node

5. Create a link from the output of the global variable to the input of the target element.
6. Click the Apply Mapping ( ) button. This maps the global variable to the target element. If you shift the focus to another target element, or click any of the Node, XSL or Debugger tabs, without applying the mapping, then an alert message is displayed. (refer to Figure 522).

7. Click No to apply the mapping and then shift the focus to the other object. If you click Yes, then the mapping activity is cleared and is replaced by the previous mapping in the Mapping Graph Area and the focus is shifted to the other object.

   Once a global variable is mapped to a target element, the letter (M) is displayed next to the mapped target element. This signifies that a target element has been mapped. Refer to Table of Suffixes for details on suffixes displayed next to a target element.

8. Save the mapping activity and exit the Data Mapper.

   You can view and validate the generated mapping XSL, view the target XML and view and validate mapping output, before saving the mapping activity.

   Using Local Variable

   Local variables are used for mapping source elements, mapping functions or constants to a specific target element. They are declared and used only for the specific target element or attribute for which they are declared.
   To use a local variable in a mapping activity, you need to map it to the specific target element or attribute. This will successfully execute the local variable when you execute the specific mapping activity in the process flow.
   Declare Local Variable
   
   
   Steps to declare a Local Variable

1. Ensure that the source and target schemas are loaded and all their elements are listed under their respective nodes.
2. Click Node tab displayed in the Mapping Graph Area. All tabs of the Node tab are displayed.

3. Click the Local Variables tab. The Local Variable pane is displayed in the Mapping Graph Area (see Figure 527).

   

   Figure 527: Local Variable Pane

4. Click Local Variable Name text field and enter the name of the local variable you want to create (e.g. varQuery). Press the Tab or Enter key. This takes the control to the Local Variable Value field.
5. Enter the value of the local variable in the Local Variable Value field. You can enter the value of the local variable using one of the listed methods:
    
   • Click required source element
   • Select the required Mapping function
   • Type the required value manually
   • Select a Custom Method

6. Enter comments for the local variable in the Add Comment field (see Figure 528). For example, if the local variable value contains complex XSLT logic, you can enter its description in this field.
    

   The Comments field is resizable.

   
   
   Figure 528: Enter Name, Value and Comment for Local Variable

    

   To select a Custom Method as the value of a local variable, double click the desired Custom Method under Custom Methods in the Parameters Panel. The selected Custom Method is displayed in the Variable Definition field.
   To learn how to declare a Custom Method, refer to section Using Custom Method.

7. Click the Save Local Variable ( ) button to save the local variable for the selected target element. This local variable is added to the list of existing variables in the Local Variable Name field. It is also displayed under Local Variables in the Parameters Panel. If you shift the focus to another node, or click any of the Mapping Rules, Textual Rules, Global Variables, Properties, XSL or Debugger tabs, without saving the local variable, an alert message is displayed (refer to alertmsg Figure 522). The comments added for the local variable are saved and displayed above the local variable declaration in the Mapping XSL (refer to Figure 523).

   The alert message is also displayed when shifting focus between Global and Node tabs.

8. Click No to save the local variable and shift the focus to the other object. If you click Yes, then the defined local variable is cleared and the focus is shifted to the other object.

   Once the local variable is saved, it is categorized as Current Variable or Ancestor Variable in the Parameters Panel. If it is created for a child node, then it is saved as a Current Variable. If it is created for a parent's parent node, then it is saved as an Ancestor Variable.

   You can rearrange the local variables by dragging it up or down in the list.

    

   Steps to manage a Local Variable from the Parameters Panel

1. Right-click the local variable that you want to edit or delete. This displays the right dropdown menu.

2. Select Edit to edit the variable. This displays the selected local variable in Edit mode. You can edit the value of the local variable in the Local Variable Value field. You can also edit the name of the local variable in the Local VariableName field (see Figure 529).

   

   Figure 529: Edit Name, Value and Comment for Local Variable

3. Click the Save Local Variable ( ) button to save the edited local variable. An alert message is displayed.

   

   Figure 530: Alert Message

4. Click OK to save the changes.

   To remove a local variable, select the local variable and click Remove selected local variable ( ) button.
   To remove all local variables, click Remove all local variables ( ) button.
   Alternately, you can delete a local variable from the Parameters Panel itself. For details, refer to the Managing a Global Variable from Parameter Panel section.

   Map Local Variable to Target Element
   Once you have created a local variable, you can map it to the specific target element or attribute.
   
   

   Steps to map Local Variable to specific target element

1. Ensure that the source and target schemas are loaded and all their elements are listed under their respective nodes.
2. Click the Node tab displayed in the Mapping Graph Area. All tabs of the Node tab are displayed. Click Mapping Rules tab.
3. Select a target element. This displays the selected target element node in the Mapping Graph Area.

4. Double-click the required local variable under Local Variables in the Parameters Panel. The selected local variable node is displayed in the Mapping Graph Area (see Figure 531).

   

   Figure 531: Add Local Variable Node

5. Create a link from the output of the local variable to the input of the target element.
6. Click the Apply Mapping ( ) button. This maps the local variable to the selected target element. If you shift the focus to another target element, or click any of the Global, XSL or Debugger tabs, without applying the mapping, then an alert message is displayed (refer to Figure 522).

7. Click No to apply the mapping and then shift focus to the other object. If you click Yes, then the mapping activity is cleared and is replaced by the previous mapping in the Mapping Graph Area and the focus is shifted to the other object.

   Once a local variable is mapped to a target element, the letter (LV) is displayed next to the mapped target element. This signifies that a local variable has been mapped to the target element. The letter (M) is also displayed indicating the target element has been mapped. Refer to Table of Suffixes for details on suffixes displayed next to a target element.

   Local variables do not allow duplicate names at the same level. You need to right-click to edit the local variable, where you can select the source.

8. Save the mapping activity and exit the Data Mapper.

   You can view and validate the generated mapping XSL, view the target XML and view and validate mapping output, before saving the mapping activity.

    

   Using Custom Methods

   A custom method is used to call a function from a custom Java class in a package. It is declared and used globally for all target elements.
   To use a custom method in a mapping activity, you need to map it to a target element. This will successfully execute the custom method when you execute the mapping activity in the process flow.
   
   Prerequisites

• • The package containing the custom java class must be copied in the folder <InstallFolder>/ServerKernel/customClasses.

Declare a Custom Method
Steps to declare a Custom Method

1. Ensure that the source and target schemas are loaded and all their elements are listed under their respective nodes.
2. Click the Global tab displayed in the Mapping Graph Area. All tabs of the Global tab are displayed.

3. Click the Custom Methods tab. The Custom Methods pane is displayed (see Figure 532).

   

   Figure 532: Custom Methods Pane

4. Click the Add New Method ( ) button to add a Custom Method. A row is inserted with the listed columns as displayed in Figure 533:
   
   • Alias
   • Class (PKG)
   • Method
   • # Parameters

   
   Figure 533: Add Custom Method

5. The value 'java' is automatically displayed in the Alias column. This is a read-only field.
6. Click Alias field and then press Enter or Tab key to activate the Class (PKG) field.
7. Enter the fully qualified name of the Java class in the Class (PKG) field and press Enter or Tab key to activate the Method field.
8. Enter the name of the custom method in the Method column and press Enter or Tab key to activate the #Parameter field.

9. Enter the number of arguments taken by Method in the #Parameter column. A custom method can take any number of arguments. However, if you enter a value greater than 4, then a warning message appears (see Figure 534).

   

   Figure 534: Warning for Adding more than 4 Parameters

10. Click OK to close the message. This saves the custom method and displays it under Custom Methods in the Parameters Panel (see Figure 535).

Figure 535: Custom Method added to Parameters Panel

Map Custom Method to Target Element
Once you have created a custom method, you can map it to a target element.
 

Steps to map Custom Method to target element

1. Ensure that the source and target schemas are loaded and all their elements are listed under their respective nodes.
2. Click the Node tab displayed in the Mapping Graph Area. All tabs of the Node tab are displayed. Click Mapping Rules tab.
3. Select a target element. This displays the selected target element node in the Mapping Graph Area.

4. Double-click the required custom method under Custom Methods in the Parameters Panel. The selected method node is displayed in the Mapping Graph Area (see Figure 536).

    

   If the custom method is defined with more than 4 parameters, then double-clicking the custom method will display the warning message (refer to Figure 534). Once you click OK, you need to define the mapping using Textual Rules.

   Figure 536: Add Custom Method Node

5. Click two source elements. The selected source nodes are displayed in the Mapping Graph Area.
6. Create a link from the output of the first source element to the first input of the custom method node.
7. Create a link from the output of the second source element to the second input of the custom method node.

8. Create a link from the output of the custom method node to the input of the target element (see Figure 537).

   

   Figure 537: Create Links between Nodes

9. Click the Apply Mapping ( ) button. This maps the custom method to the target element.

10. Save the mapping activity and exit the Data Mapper.

    You can view and validate the generated mapping XSL, view the target XML and view and validate mapping output, before saving the mapping activity.

    Dynamically Loading Custom Methods

    Adeptia supports dynamic loading of custom methods in the Data Mapper. It loads the custom methods available in the Custom Classes folder, under the Global Methods node in the Parameters Panel. This enables you to access any custom method from the Data Mapper itself, without any need to specify method parameters, such as class name, method name and the number of arguments in the Data Mapper applet.
    
    Steps to dynamically load Custom Methods

1. Copy all the class files in the Custom Classes folder and then restart the kernel.
    

   The current implementation of Global Methods does not support package hierarchy. So all class files that are directly placed in the Custom Classes folder, will be visible through the Global Methods node in the Parameters Panel.

   
   

2. Ensure that the source and target schemas are loaded and all their elements are listed under their respective nodes. The Global Methods node is already displayed in the Parameters Panel, each time Data Mapper is opened (see Figure 538).

   
   Figure 538: Global Methods Node

3. Expand the Global Methods node to display all the class files present in the Custom Classes folder (see Figure 539).

   
   Figure 539: List of Class Files in Custom Classes Folder

4. Expand a class node to display all custom methods available for that class (see Figure 540).

Figure 540: Custom Methods in a Custom Class

Using Key Function

The Key function is used to extract information from two or more related input data sources. For example, if there are two input data sources: source1 and source2, then the Key function will extract information from source2 based on the matching field from source1.
Key function is always created in context of source2 (the data source from where data needs to be fetched based on matching field ). All the parameters of the Key function correspond to source2 only. It has the following 3 parameters: