Skip Navigation
NIH | National Cancer Institute | NCI Wiki   New Account Help Tips
Skip to end of metadata
Go to start of metadata

2 - Transformation Mapping v1.0

This chapter explains how to create relationships between the source data schema, target schema, and data manipulation functions using transformation mapping.

A transformation mapping defines the relationship between the source data schema, target schema, and data manipulation functions. It also contains annotation information about the source data schema and target data schema.

caAdapter CMTS links any of the following pairs:

  • a source data schema entry to a target data schema entry
  • a source data schema entry to a function's input port
  • a function's output port to a target data schema entry

The annotation information set constrains the data schema, including:

  • one and only one chosen child element of a choice group
  • one or more cloned record(s) of an element

Return to top of page

Transformation Mapping Rules

CMTS module enforces the following mapping rules:

  • It must contain a valid mapping pair (source data schema and target data schema files).
  • The source entry referenced must exist in the source data schema
  • The destination entry referenced must exist in the target data schema
  • A mandatory target entry must have either a mapping from data source or predefined default value in its schema; the mapping data source could be a source entry or function output
  • Each input parameter for a function must have a mapping from source or a constant defined.
  • Each output parameter for a function must have a mapping to target

Return to top of page

Understand Transformation Mapping

This section includes the following topics:

Return to top of page

Overview of the Transformation Mapping Panel

The transformation mapping panel graphically presents a transformation mapping with source and target metadata, schema annotation, mapping links, function boxes, and other elements. It is divided into several sub-panels. An example follows.

transformation mapping panel

The transformation mapping panel has the following components.

  • Source schema panel – The left-hand panel contains tree view of source schema
  • Target schema panel – The right-hand panel contains tree view of target schema
    • Mapping panel – The center panel displays mapping lines and functions.
    • Functions panel – The upper panel of the most right split pane display a tree view of all applicable functions.
    • Properties panel – The lower panel of the most right split pane displays detail information of a selected item, such as link properties, schema entry properties, and function properties.

The tree view of schema data is read-only on the mapping panel, no change is allowed on any node on source schema tree or target schema tree. If you want to change the referenced schema, you must work with available XSD editing tools.

Be Careful

Icon

Editing or removing source or target elements may result in the loss of related mapping (broken links) or producing other unpredictable behavior.

Return to top of page

Create New Transformation Mapping

To create a new transformation mapping, perform the following steps:

  1. Select File > New > Transformation Mapping.
    New Transformation Mapping
  2. System creates a new mapping tab with empty source and target panels.
    Empty Transformation Mapping Panel
  3. Click Open Source button on source schema panel. The Open Source data schema dialog box appears.
    Open Source Data Schema Dialog box
  4. Select the source xsd file and click Open to populate the source Choose Root Element dialog box.
  5. Select the root element of the XSD file. In general cases, the root element name can be seen just like the following figure, but if not, you must search for it among the element names that will be listed down after clicking on the circled button. Click OK.
    Choose Root element dialog box
    The parsed XSD Tree appears.
    XSD structure tree

    Be Careful

    Icon

    In many cases, one schema links to others with <include> tags, though it appears to be a single file. If the system cannot find all of the linked schema files, the reading and parsing schema processing will fail.

  6. Click the Open Target button on target schema panel and then repeat steps 3 through 5.
    A mapping panel appears.
    Empty mapping panel with source and target XSD opened

    Warning

    Icon

    When a '+' button in the source or target tree is pressed for the branch expending, it is reported that a defect may be seen that the link data of the branch are lost. The cause of this problem has been identified to be related to processing CDE element and so it should be safe if the branch doesn't have any CDE element. This problem will be fixed at the next release.

Return to top of page

To create a mapping link, perform the following steps:

  1. Select a source entry and drag it to the appropriate target entry.
  2. Drop the source on the target element.
  3. Once a source field is mapped to a target element, a mapping line appears between them in the mapping panel. The following screen shot shows a mapping line between shipto[1…1] node on source schema tree and address[1…1] node on target schema tree.
    mapping link from source schema node to target schema node

    Note

    Icon

    When a mapping link is selected, the link and associated mapping ends are highlighted. The property panel displays the link's properties.

Return to top of page

To delete a mapping link, perform the following steps:

  1. Right-click any mapping line to select it.
    A popup menu appears.
    delete mapping link
  2. Click Delete to delete only the selected mapping line.
  3. Alternatively, click Delete All to delete all mapping links. A confirmation message box appears.
  4. Click Yes to delete all mapping links.

Return to top of page

Save Transformation Mapping

To save a transformation mapping, perform the following steps:

  1. Select File > Save menu bar or the Save icon.
    If the open mapping is an existing one, the latest mapping is saved to the referenced map file.
    If the open mapping is a new one, you are prompted to choose a file.
  2. Choose or input file name. The latest mapping is saved to the chosen file.
  3. To save a mapping to different file, perform the following steps.
    1. Select File > Save As on menu bar or Save As icon on tool bar.
      choose or input file name to save a mapping
    2. Choose or input the file name. The latest mapping is saved to the chosen file.

      Warning

      Icon

      Transformation mapping has internal references to associated source schema and target schema files, which are parts of the transformation mapping. If a transformation mapping file is moved to other location or other system, all the associated schema files have be moved together.

Return to top of page

Open Transformation Mapping

To open an existing transformation mapping, perform the following steps:

  1. Select File > Open > Open or click Open.
    open existing mapping
    You are prompted to choose a mapping file.
  2. Choose a mapping file and click Open.
    choose a mapping file to open
    Mapping panel displays mapping links, source data schema, target data schema and data processing functions.

Return to top of page

Use Data Processing Functions in Transformation Mapping

The Functions panel lists all the data processing functions that facilitate the CMTS data transformation requirement. These data processing functions are grouped by functional categories:

  • math
  • constant
  • dateTime
  • string
    data processing functions

Warning

Icon

It is reported that the countDays function generates wrong calculations when the input date values are in different months. The cause of this problem has been identified and will be removed at the next release.

Note

Icon

Among these functions, four functions, constant, currentDate, currentDateTime, currentTime, currentDateHL7, currentDateTimeHL7 and currentTimeHL7, have an output port only.

Return to top of page

Add Function to Transformation Mapping

To add a function item in transformation mapping, perform the following steps:

  1. Select a function in the Functions panel.
  2. Drag-and-drop the required function from the Functions panel to the mapping central panel.
  3. Move the function box around the mapping panel.
    add function to transformation mapping

Return to top of page

Create Mapping from Source schema entry to Function Input Port

To create a mapping link from source schema entry to function input port, perform the following steps:

  1. Select a schema entry from source schema tree.
  2. Drag-and-drop the selected schema entry to an input port of function box on the mapping panel.

Return to top of page

Create Mapping from Function Output Port to Target Schema entry

To create a mapping link from a function output port to a target schema entry, perform the following steps:

  1. Select a schema entry from target schema tree.
  2. Drag-and-drop the selected schema entry to an output port of function box on the mapping panel.

Return to top of page

Delete Function from Transformation Mapping

To delete a function box from transformation mapping, perform the following steps:

  1. Select a function box in the mapping panel.
  2. Right-click the selected function box.
    A popup menu appears.
  3. Click Delete.
  4. The selected function box is removed from the mapping panel.
    delete function from transformation mapping

    Be Careful

    Icon

    Before deleting a function box, you must delete the linked mapping lines.

Return to top of page

Edit Constant Function

To edit a constant function, perform the following steps.

  1. Select a constant function in the mapping panel.
  2. Right-click a selected function box.
    A popup menu appears.
  3. Click Edit Constant.
    The Edit Constant dialog box appears.
    edit constant function.
  4. Change the Type and/or Value for the constant.
  5. Click OK. The edited function is assigned with the new value.

Return to top of page

Use Math Function Group

The math function group includes the following functions:

  • abs – returns the absolute value of the argument
  • ceiling – returns the smallest integer that is greater than the number argument
  • floor – returns the largest integer that is not greater than the number argument
  • round – rounds the number argument to the nearest integer
  • addition – returns the sum of term1 and term2
  • subtraction – returns the difference of term2 from term1
  • multiplication – returns the product of factor1 and factor2
  • division – returns the quotient of the dividend and divisor
  • modulus – returns the rounded quotient of the dividend and divisor

Return to top of page

Use DateTime Function Group

The dateTime function group includes the following functions:

  • currentDate – returns the current date
    Format: yyyy-MM-dd
  • currentDateTime – returns the current dateTime (with timezone)
    Format: yyyy-MM-ddThh:mm:ss.sss{+/-}9999
  • currentTime – returns the current time (with timezone)
    Format: hh:mm:ss.sss{+/-}9999
  • countDays – returns an integer that represents the day component in the localized value of the argument
  • currentDateHL7 – returns the current date with HL7/ISO21090 format
    Format: yyyyMMdd
  • currentDateTimeHL7 – returns the current date and time with HL7/ISO21090 format (with timezone)
    Format: yyyyMMddhhmmss.sss{+/-}9999
  • currentTimeHL7 – returns the current time with HL7/ISO21090 format (with timezone)
    Format: hhmmss.sss{+/-}9999

Return to top of page

Use String Function Group

The string function group includes the following functions:

  • length – returns the length of the specified string.
  • lower – converts the string argument to lower-case
  • upper – converts the string argument to upper-case
  • concatenate – returns the concatenation of the strings
  • substringAfter – returns the remainder of string1 after string2 occurs in it
  • substringBefore – returns the start of string1 before string2 occurs in it
  • substring – returns the substring from the start position to the specified length. Index of the first character is 1.
  • replace – returns a string that is created by replacing the given pattern with the replace argument

Return to top of page

Annotate XML Schema

In the schema conforming step, caAdapter CMTS annotate an XML schema with the following kinds of actions:

  • Choice Element – XML Schema choice element allows only one of the elements contained in the <choice> declaration to be present within the containing element. The annotation process allows user select one and only element to be present.
  • Clone Element – If an element has the maxOccurs attribute greater than one or "unbounded", it could be mapped to more than one source/target nodes. The annotation process allows user to clone the same element for multiple mapping source/target nodes.
  • Recursive Data Type – If the data type of element is same with its ancestor, it is referred as recursive element. As default, caAdapter CMTS mapping panel only display the name of recursive data type without any content to avoid any indefinite loop. The annotation process allows user to navigate a recursive data type down level by level.

Return to top of page

Select Choice Child Element

To select a child for choice element, perform the following steps:

  1. Right-click a child element of <choice> element.
    A popup menu appears. The Select Choice menu item is enabled if the selected element has not been selected.
  2. Click Select Choice. The selected child is set as selected child for the choice element and the other selected child is removed.
    select choice child element

Return to top of page

De-select Choice Child Element

To de-select a child for choice element, perform the following steps:

  1. Right-click a child element of <choice> element.
    A popup menu appears. The De-select Choice menu item is enabled if the selected element has already been designated as the selected child.
  2. Click De-select Choice. The selected child no longer has a status of selected.
    deselect choice child element

Return to top of page

Add Clone Element

To clone an element, perform the following steps:

  1. Right-click an element.
    A popup menu appears. The Add Clone menu option is enabled if the selected element has the "maxOccurs" attribute greater than one or "unbounded".
  2. Click Add Clone.
    The selected element is cloned and added to the schema tree.

    Note

    Icon

    User can only clone an element from the "original" element, that is, the cloned element can never be cloned.

    add clone element

Return to top of page

Remove Clone Element

To remove a cloned element, perform the following steps:

  1. Right-click the element.
    A popup menu appears.
    The Remove Clone menu item is enabled if the selected element is a cloned element.
  2. Click Remove Clone.
    The selected element is removed from the schema tree.
    remove clone element

Return to top of page

Enable Recursion

To navigate a recursive data type down to next level, perform the following steps:

  1. Right-click the element.
    A popup menu appears.
  2. The Enable Recursionmenu item is enabled if:
    1. The selected element has recursive data type.
    2. The selected element does not have its content displayed in schema tree.
  3. Click Enable Recursion menu item, the selected element would navigate down one more level.
    enable data type recursion

Return to top of page

Disable Recursion

To disable a recursive element, perform the following steps:

  1. Right-click an element.
    A popup menu appears.
  2. The Disable Recursion menu item is enabled if:
    1. The selected element has recursive data type and
    2. The selected element has its contents displayed in schema tree.
  3. Click Disable Recursion menu item, the selected element would remove all its contents.
    disable data type recursion

Return to top of page

  • No labels