# Presentation: 106309

## caAdapter Model Mapping Service Hands-On Training

***Target Audience: ***
***	******caCORE Application Developers***
***	******caBIG Developers***

**Charles Yaghmour**

## Session Details

- Training Topic Statement:  This training is designed to teach you about the caAdapter Model Mapping Service
- Target Audience:  caCORE developers and caAdapter end-users
- Prerequisites:  caCORE SDK Session 1:  Semantic Interoperability

## Session Details: Session Goals

- By the end of this training, you will be able to:
- Describe how caAdapter Model Mapping Service supports the caCORE SDK code generation process
- Demonstrate the eight steps involved in using caAdapter to map an object model to a data model
- Use caAdapter to perform mapping for a variety of complex object associations

## Session Details:Lesson Plan

**Lesson 1:  Introduction and Background**
**Lesson 2:  Mapping Process Step-by-Step**
**Lesson 3:  Advanced Mapping**
**Exercise I**
**Exercise II**

## Lesson 1: Introduction and BackgroundLesson Overview

**This lesson is about the caCORE model mapping process, the caAdapter Model Mapping Service, and other services provided by caAdapter**
**Learning Objectives for this Lesson:**
- Introduction to caAdapter different modules
- Review the current caCORE model mapping process
- Show how caAdapter can make mapping easier
- Show other uses of caAdapter

## caAdapter Modules

**CSV to HL7 v3 Mapping and Transformation Service**

**HL7 v2 to v3 Conversion Service**

**SDTM Mapping and Transformation Service **

**Web Service **

**Model Mapping Service **

**Model Mapping Service **

## Lesson 1: Introduction and BackgroundOverview of caAdapter Capabilities

**The Mapping Tool –** graphical application for mapping source specification to target specification
**Source and Target Specification –** graphical interface for defining input and output data formats
**Drag and Drop Interface –** simple interface for mapping source fields to target elements
**Mapping Functions –** capability to do simple source data manipulation with HL7-related mapping
**Transformer –** generation of output from source data based on the mapping
**Validation Services –** integrates with NCICB caCORE components such as Enterprise Vocabulary Service (EVS) and W3C XML schema validation services
**caAdapter API –** uses mappings to generate output files

## Lesson 1: Introduction and BackgroundWhat are caCORE-compatible applications?

**Data management framework**
**Software infrastructure pattern**
**Characteristics of caCORE:**
- Model-Driven Architecture (MDA)
- n-tier architecture
- Controlled vocabularies
- Registration of metadata
**All caCORE components are built using these principles**

## Lesson 1: Introduction and BackgroundThe caCORE SDK Process Flow

**Design system and draw model****(UML tool)**
**Annotate model ****(Semantic Connector)**
**Register metadata ****(UML Loader)**
**Generate and deploy system (Code Generator)**

## Lesson 1: Introduction and BackgroundThe Current Manual Mapping Process...

**Lesson 1: Introduction and Background****The Current Manual Mapping Process...**

**Design the object model and the data model**
**Map tables to the classes in a new diagram**
**Manually tag table columns with the full path of the associated class’s attribute or association**

## Lesson 1: Introduction and BackgroundThe Current Manual Mapping Process

**Requires a new diagram for mapping**
**Requires tagging almost every table and column manually**
**Must include an accurate and complete path to each object **
**Must make sure case-sensitive tags are correct**

## Lesson 1: Introduction and BackgroundcaAdapter Can Help

**Uses Enterprise Architect (EA) XMI export of object & data models**
**Provides graphical user interface**
**Supports mapping****of...**
- Objects
- Attributes
- Associations

## Lesson 1: The Mapping Process Step-by-StepMapping Process Diagram

**Lesson 1: The Mapping Process Step-by-Step****Mapping Process Diagram**

**caAdapter supports mapping of object model to data model**

- caCORE SDK Code Gen.

## Lesson 1: The Mapping Process Step-by-StepMapping Process Diagram ...

**caAdapter supports mapping of object model to data model**

## Lesson 1: Introduction and BackgroundAdvantages of Using caAdapter for Mapping

**No mapping diagram needed**
**Graphical user interface for drag & drop mapping**
**Includes validation**
**Can generate Hibernate files as well as XMI**

## Lesson 1: Introduction and BackgroundcaAdapter Mapping Modules

**CSV to HL7 v3 Mapping and Transformation Service **
**Model Mapping Service **
**SDTM Mapping and Transformation Service **
**HL7 v2 to v3 Conversion Service **
**Plus...**
**caAdapter Web Service **

## Lesson 2: Mapping Process Step-by-StepLesson Overview

**This lesson is about using the caAdapter Model Mapping Service to perform mapping for the caCORE SDK process.**
**Learning Objectives for this Lesson:**
- Examine the steps for using caAdapter Model Mapping Service one by one
- Explain the different types of mappings
- Perform a live demonstration of the steps

## Lesson 1: The Mapping Process Step-by-StepMapping Process Diagram ...

**Lesson 1: The Mapping Process Step-by-Step****Mapping Process Diagram ...**

- caCORE SDK Code Gen.

**1**

**5**

**4**

**8**

**3**

**7**

**2**

**6**

**alt 6**

## Lesson 2: Mapping Process Step-by-StepMapping Steps

**Step 7:****	****Import the XMI file into EA**
**Step 8:****	****Create (export) an XMI file from EA to feed into the Code Generator**

**Alternate Step 6:**** ****	****Generate Hibernate files**

**Step 1:****	****Export the XMI file from EA**
**Step 2:****	****Load the XMI file into caAdapter**
**Step 3:****	****Perform the mapping using the Mapping Panel**
- Dependency mapping
- Attribute mapping
- Association mapping
**Step 4:****	****Validate the mapping**
**Step 5:****	****Save the .map file**
**Step 6:****	****Generate a tagged XMI file**

## Lesson 2: Mapping Process Step-by-StepStep 1 – Export XMI File...

**EA File must have final Object Model and Data Model**
**Project Browser View > Right click Logical View > Import/Export > Export package to XMI file**

## Lesson 2: Mapping Process Step-by-StepStep 1 – Export XMI File

**Format XMI Output**
**Enable Roundtrip**
**XMI v1.1 or v2.0**

- (EA v6.5)

## Lesson 2: Mapping Process Step-by-Step Step 2 – Load the XMI File into caAdapter

**Use file created in Step 1**
**New > Model Mapping Service > Object Model to Data Model Map Specification**

## Lesson 2: Mapping Process Step-by-Step Step 3 – Perform the Mapping

**Lesson 2: Mapping Process Step-by-Step ****Step 3 – Perform the Mapping**

**Dependency Mapping****	****(Object to Table)**
**Attribute Mapping ****	****(Attribute to Column)**
**Association Mapping****	****(Object Relationship to Table Relationship)**

**Objects**

**Mappings**

**Tables**

**Note: Different colors were used for clarification only. caAdapter presents all mapping lines in the same color**

## Lesson 2: Mapping Process Step-by-Step Step 4 – Validate the Mapping

**Validate Button**

## Lesson 2: Mapping Process Step-by-Step Step 5 – Save & Re-Open the Mapping File

**When opening a .map file, caAdapter will ask for the associated .xmi file**

**Re-opening the .map File**

**Saving the .map File**

## Lesson 2: Mapping Process Step-by-Step Step 6 – Generate a Tagged XMI File

**Generated tagged file:**
- Saved in the same directory where the .xmi and .map files stored
- Automatically named: <map_file_name>*_Tagged*.xml
- For example: Example_Tagged.xmi

**Tag XMI File Button**

## Lesson 2: Mapping Process Step-by-Step Alternate Step 6 – Generate Hibernate Files

- Specify output directory
- Generate one Hibernate file per object or per inheritance hierarchy

**Generate HBM Files Button**

## Lesson 2: Mapping Process Step-by-Step Step 7 – Import the XMI File into EA...

**Create a new Project in EA**
**Right click on the Model**
**SELECT Import Model from XMI ...**

## Lesson 2: Mapping Process Step-by-Step Step 7 – Import the XMI File into EA

**Attribute Mapping**

**Dependency Mapping**

**(Tables)**

**(Objects)**

**After**

**Before**

## Lesson 2: Mapping Process Step-by-Step Step 8 – Export an XMI File from EA

**Do not export diagrams**
**Disable full EA roundtrip**
**Use XMI version 1.1 (caCORE SDK requirement)**

- (EA v6.5)

## Showed the step-by-step process for using caAdapter in the caCORE SDK process 
Identified 3 different types of mappings 
Performed a live demonstration of the steps

Questions? 

**Identified 3 different types of mappings **
**Performed a live demonstration of the steps**
**Questions? **

**Lesson 2: Mapping Process Step-by-Step**** ****Review & Questions**

## Lesson 3: Advanced MappingLesson Overview

**This lesson explains some of the more advanced features of the caAdapter Model Mapping Service**
**Learning Objectives for this Lesson:**
- Explain how to map associations in 7 different scenarios and how to map inheritance
- Perform a live demonstration of the scenarios
- Identify tips for working with the caAdapter Model Mapping Service

## Lesson 3: Advanced MappingSeven Association Mapping Scenarios

**The following 7 scenarios cover all association types in an object model:**
**One-to-one bidirectional**
**One-to-one unidirectional**
**One-to-many bidirectional**
**One-to-many unidirectional**
**Many-to-one unidirectional**
**Many-to-many bidirectional**
**Many-to-many unidirectional**

## Lesson 3: Advanced MappingThey all start the same....

**Map the classes to the tables**
**Map the attributes to the columns**
**That’s the easy part...and it must be done first, then we can do the association mapping....**
**Associations are mapped to foreign key columns**
**Business rules guide the mapping of associations**

## Lesson 3: Advanced MappingScenario 1 – One-to-One Bidirectional

**Lesson 3: Advanced Mapping****Scenario 1 – One-to-One Bidirectional**

**Map classes & ****attributes**
**Map association ****from child table’s ****class to the child table’s foreign key (ignore the other association)**

- Leave this unmapped

## Lesson 3: Advanced MappingScenario 2 – One-to-One Unidirectional

**Lesson 3: Advanced Mapping****Scenario 2 – One-to-One Unidirectional**

**Map association ****from child table’s ****class to the child ****table’s foreign key**
**Note that FK column must be in the originating class’s table**

## Association on“one” end has a different color and is unmappable
Map remaining association to table w/ foreign key

**Association on****“one” end has a ****different color ****and is unmappable**
**Map remaining association to table w/ foreign key**

**Lesson 3: Advanced Mapping****Scenario 3 – One-to-Many Bidirectional**

- Unmappable

## Lesson 3: Advanced MappingScenario 4 & 5 – 1:M & M:1 Unidirectional

**Lesson 3: Advanced Mapping****Scenario 4 & 5 – 1:M & M:1 Unidirectional**

**One-to-many****maps same as****many-to-one, ****except for faked****association**
**See a pattern?**
**Map association in class with table with FK to FK**

- Ignore, unmappable

## Lesson 3: Advanced MappingNot a Scenario – Many-to-One Bidirectional

**Note that many-to-one bidirectional is literally the same as one-to-many bidirectional**
**No distinction in caAdapter**
**Not considered a separate scenario**

## Lesson 3: Advanced MappingScenario 6 – Many-to-Many Bidirectional

**Lesson 3: Advanced Mapping****Scenario 6 – Many-to-Many Bidirectional**

**ONLY** time you map both associations

- Make sure to map the X-Collection to the X_id

- Intersection table does not need dependency mapping

## Lesson 3: Advanced MappingScenario 7 – Many-to-Many Unidirectional

**Lesson 3: Advanced Mapping****Scenario 7 – Many-to-Many Unidirectional**

**Back to ****normal ****pattern**
**Map X-Collection to X_ID**

## Lesson 3: Advanced MappingInheritance Mapping

**Lesson 3: Advanced Mapping****Inheritance Mapping**

**Map the attributes that are distinct to the subclass (as normal attribute mappings)**
**For inherited attributes marked with the ****“(A – Derived)” label, only map if it’s the PK**
**During validation, an “INFO” level message will be displayed**

- Mapped

- Not mapped

## Lesson 3: Advanced MappingGeneral Tips – Using XMI Versions

**Note that you must have a version of EA that can export XMI v1.1 (XMI v2.0 is optional) **
**caAdapter can load both XMI v1.1 and v2.0 for mapping and tagging.**
**XMI v1.1 is required by the caCORE Code Generator**

## Lesson 3: Advanced MappingGeneral Tips – Updating Data/Object Models

**Once a mapping has been created, you can go back and change the object or data model without having to redo the entire mapping**
**If model(s) must be changed... **
- Edit model(s) in the original EA file
- Export the .xmi file again
- Either use the _*same*_ .xmi file name or _*remove the old file*_ and use a new name
- Open the .map file in caAdapter and select the new .xmi file when it prompted
- Continue mapping as needed
**In the current release of caAdapter, you can’t start the mapping manually and then continue it in caAdapter **
**Note that you can’t view manually created mappings in caAdapter either**
**The next release of caAdapter will contain those capabilities**

## Lesson 3: Advanced MappingGeneral Tips – Other Modeling Tips...

**Follow general caCORE SDK guidelines for modeling (caCORE Technical Guide)**
**Any association with unspecified directionality will be treated as bidirectional by caCORE SDK**
**Can’t do 3-way intersection table in caCORE SDK (or more ways!)**
**To map a one-to-one unidirectional association, for the object that has the association attribute, the corresponding table must have the foreign key.**
**caAdapter adds a caCORE SDK-required tag on many-to-many associations, called “correlation-table” with value = name of intersection table (yes, this is on the object model whereas other tags are on data model)**
**Other tags:  “mapped-attribute”, “implements-association”, “inverse-of”**

## Explained how to handle 7 different association mapping scenarios & inheritance mapping
Performed a live demonstration of the scenarios
Identified tips for working with the caAdapter Model Mapping Service

Questions? 

**Performed a live demonstration of the scenarios**
**Identified tips for working with the caAdapter Model Mapping Service**
**Questions? **

**Lesson 3: Advanced Mapping**** ****Review & Questions**

## ExercisesOverview

**The exercises will help you get some practical, hands-on experience in working with the caAdapter Model Mapping Service within the caCORE SDK process.**
**Learning Objectives for the Exercises:**
- Identify the difference between manual mapping and caAdapter-based mapping
- Perform basic and advanced mapping with a robust example
- Generate an XMI file for use with caCORE SDK and hibernate files

## ExercisesExercise I – Basic Mapping

**Part 1:  Review a manual mapping in EA **
- Explore object/table, attribute/column mappings
**Part 2:  Use caAdapter to recreate the mapping **
- Open the .eap file in EA
- Export the .xmi file (v1.1 or v2.0)
- Start caAdapter & load .xmi in model mapping tab
- Drag-n-drop object model elements onto data model
- Validate model and view validation messages
- Save the mappings to a .map file

## ExercisesExercise II – Advanced Mapping & Generation

**Part 1:  Map 1:M, M:M bidirectional associations **
- Open .map file that has been started for you
- Map associations for StudySite to Participant & AdverseEvent to AdverseEventTherapy
- Click the Validate button or choose File > Validate
**Part 2:  Generate the .xmi file for caCORE Code Generator**
- Continuing with current mapping file, map the associations
- Export the mapping to HBM
- Export the mapping to XMI
- Open EA, import the .xmi and view the mapping tags

## ExercisesExercise I Files - In case you don’t finish a step

- Exercise I – Part 1 – manually completed mappings.eap** – an EA file with the mapping already completed manually**
- Exercise I – Part 2a – model without mappings.eap** – an EA file with the same classes and tables but no mappings, from which the XMI file will be exported**
- Exercise I – Part 2b – model without mappings.xmi** – a successful export from EA containing classes and tables**
- Exercise I – Part 2c – new caAdapter mappings.map** – a valid map file generated by caAdapter with the classes & attributes mapped to the tables & columns**

## ExercisesExercise II Files - In case you don’t finish a step

- Exercise II – Part 1a – completed caAdapter mappings.map** – a caAdapter map file with the 2 association mappings completed, ready for validation**
- Uses **Exercise I – Part 2b – model without mappings.xmi** as the basis of the untagged original models
- Exercise II – Part 2a – completed caAdapter mappings_tagged.xmi** – an XMI export from caAdapter with complete valid mappings**
- Exercise II – Part 2b – caAdapter mappings reimported.eap** – an EA file with the mapped classes and tables successfully re-imported**

## ExercisesDownload Files If You Haven’t Already

**The exercise instructions and files are available at the following URL:**
**	**_**[https://gforge.nci.nih.gov/docman/view.php/196/5977/caAdapter%20Model%20Mapping%20Service%20Hands-On%20Training%20Exercises.zip](https://gforge.nci.nih.gov/docman/view.php/196/5977/caAdapter%20Model%20Mapping%20Service%20Hands-On%20Training%20Exercises.zip)**_
**Please begin the exercises now**
**Ask questions as you need**

## Session Summary:Follow-On Training & Next Steps

**Training presentations available online at ****http://trials.nci.nih.gov/projects/infrastructureProject/caAdapter/HL7_Tutorial**
- HL7 Version 3 and caAdapter Overview
- caAdapter Fundamentals
**caCORE SDK training at****http://gforge.nci.nih.gov/docman/index.php?group_id=63&selected_doc_group_id=181&language_id=1**
- caCORE SDK (Session 1: Semantic Interoperability)
- caCORE SDK (Session 2: Code Generation)
- Plus many other courses

## Session Summary:Course Evaluation

**Please provide feedback so we can improve this training  **
**Training Evaluation Form is on the Training Portal at****http://ncicb.nci.nih.gov/NCICB/training/cadsr_training/EvaluationForm**** **

## THANK YOU!

**For Additional Information:****	****Sichen Liu:****	**_**[liusi@mail.nih.gov](mailto:liusi@mail.nih.gov)**_**	****Ye Wu:****	**_**[wuye@mail.nih.gov](mailto:wuye@mail.nih.gov)**_**	****Charles Yaghmour:****	**_**[cyaghmour@scenpro.com](mailto:cyaghmour@scenpro.com)**_