DRAFT 02-Feb-07 1 caAdapter Model Mapping Service Hands-On Training (Course# 2040) Session Date: TBD Session Length: 90 minutes Target Audience:caCORE

1DRAFT 02-Feb-07

caAdapter Model Mapping Service Hands-On Training

(Course# 2040)

Session Date: TBD

Session Length: 90 minutes

Target Audience: caCORE Application Developers

caBIG Developers

Trainer: Charles Yaghmour

Developer Subject Matter Expert: Ye Wu

2DRAFT 02-Feb-07

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

3DRAFT 02-Feb-07

Session Details:

Online Training Environment: Centra…

Use these buttons (or choose from the Actions menu) to communicate with the trainer and other attendees.

Example:Raise your hand to ask a question.

4DRAFT 02-Feb-07

Session Details:

Online Training Environment: Centra

You can adjust what you see on screen by choosing from the View menu or by scrolling with the slide bars.

5DRAFT 02-Feb-07

Session Details:

Online Training Etiquette

• Be an active learner! Ask questions, and avoid temptation to multi-task. Keep distractions away!

• When not asking a question or making a comment, please keep your phone on MUTE to minimize background noise.

• Please do not put your phone on HOLD – the music is distracting.

• When asking a question or making a comment, please state your name so we know who’s speaking.

6DRAFT 02-Feb-07

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 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

7DRAFT 02-Feb-07

Session Details:

Lesson Plan

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

8DRAFT 02-Feb-07

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:– Review the current caCORE model mapping process– Show how caAdapter can make mapping easier – Show other uses of caAdapter

9DRAFT 02-Feb-07


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

10DRAFT 02-Feb-07


The caCORE SDK Process Flow

1. Design system and draw model(UML tool)

2. Annotate model (Semantic Connector)

3. Register metadata (UML Loader)

4. Generate and deploy system (Code Generator)

UML Model

Semantic Integration Workbench

XMI File

Curated Semantic

Report

SemanticReport

Code Generator

Annotated XMI

UML Loader

caDSR

CDEs

Public APIsMetadataRetrieval

EVS

Terminology

TerminologyService

11DRAFT 02-Feb-07


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

12DRAFT 02-Feb-07


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

13DRAFT 02-Feb-07


caAdapter Can Help

• Uses Enterprise Architect (EA) XMI export of object & data models

• Provides graphical user interface• Supports mapping

of…– Objects– Attributes– Associations

14DRAFT 02-Feb-07


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

15DRAFT 02-Feb-07


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

16DRAFT 02-Feb-07

Lesson 1: The Mapping Process Step-by-Step

Mapping Process Diagram

UML Model


XMI File

Curated Semantic

Report

SemanticReport

Code Generator

Annotated XMI

UML Loader

caDSR

CDEs


EVS

Terminology

TerminologyService

caAdapter supports mapping of object model to data model

Cur

rent

caC

OR

E S

DK

Pro

cess

17DRAFT 02-Feb-07


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

18DRAFT 02-Feb-07

• Reviewed the current caCORE model mapping process

• Introduced caAdapter and its capabilities• Showed how caAdapter can make model

mapping easier

• Any questions so far?


Review & Questions

19DRAFT 02-Feb-07

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

20DRAFT 02-Feb-07


Mapping Process Diagram

UML Model


XMI File

Curated Semantic

Report

SemanticReport

Code Generator

Annotated XMI

UML Loader

caDSR

CDEs


EVS

Terminology

TerminologyService

1

54

8

3

72 6

alt 6

Cur

rent

caC

OR

E S

DK

Pro

cess

21DRAFT 02-Feb-07


Mapping Steps

Step 6: Generate a tagged XMI file

Step 7: Import the XMI file into EA

Step 8: Create (export) an XMI file from EA

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

22DRAFT 02-Feb-07


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

23DRAFT 02-Feb-07


Step 1 – Export XMI File

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

(EA v6.5)

24DRAFT 02-Feb-07


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

25DRAFT 02-Feb-07


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

26DRAFT 02-Feb-07


Step 4 – Validate the Mapping

Validate Button

27DRAFT 02-Feb-07


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

28DRAFT 02-Feb-07


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

29DRAFT 02-Feb-07


Alternate Step 6 – Generate Hibernate Files

– Specify output directory– Generate one Hibernate

file per object or per inheritance hierarchy

Generate HBM Files Button

30DRAFT 02-Feb-07


Step 7 – Import the XMI File into EA…

• Create a new Project in EA

• Right click on the Model• SELECT Import Model

from XMI …

31DRAFT 02-Feb-07


Step 7 – Import the XMI File into EA

Attribute Mapping

Dependency Mapping

(Tables)

(Objects)

AfterBefore

32DRAFT 02-Feb-07


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)

33DRAFT 02-Feb-07


Perform a Live Demonstration of the Steps

Live Demonstration of the Mapping

Steps in Lesson 2

34DRAFT 02-Feb-07

• 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?

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

35DRAFT 02-Feb-07

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

36DRAFT 02-Feb-07


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

37DRAFT 02-Feb-07


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

38DRAFT 02-Feb-07


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

39DRAFT 02-Feb-07


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

40DRAFT 02-Feb-07

• Association on“one” end has a different color and is unmappable

• Map remaining association to table w/ foreign key


Scenario 3 – One-to-Many Bidirectional

Unmappable

class One to Many

bidirectional::Adv erseEv ent

- id: Integer- type: String

bidirectional::Adv erseEv entTherapy


+adverseEvent

1+adverseEventTherapyCollection

1..*

41DRAFT 02-Feb-07


Scenario 4 & 5 – 1:M & M:1 Unidirectional

• One-to-manymaps same asmany-to-one, except for fakedassociation

• See a pattern?• Map association in class with table with FK to FK

Ignore, unmappable

42DRAFT 02-Feb-07


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

class One to Many

bidirectional::Adv erseEv ent


bidirectional::Adv erseEv entTherapy


+adverseEvent

1

+adverseEventTherapyCollection

1..*

43DRAFT 02-Feb-07


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

44DRAFT 02-Feb-07


Scenario 7 – Many-to-Many Unidirectional

• Back to normal pattern

• Map X-Collection to X_ID

45DRAFT 02-Feb-07


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

46DRAFT 02-Feb-07


Demonstration of Mapping Scenarios

Live Demonstration of the Mapping Scenarios

47DRAFT 02-Feb-07


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 Semantic Integration Workbench (SIW)

48DRAFT 02-Feb-07


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

49DRAFT 02-Feb-07


General Tips – Choose 1 Mapping Method

• 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

50DRAFT 02-Feb-07


General Tips – Sharing Files

• Must provide both the .map and the original .xmi• The .map file contains a reference to the .xmi,

including a file path• Other user must put .xmi in same path as first

user, or edit the .map file and change the path• USE CAUTION if you edit the .map file!

.map.xmi +

51DRAFT 02-Feb-07


General Tips – Other Modeling Tips…

• Follow general caCORE SDK guidelines for modeling

• 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.

52DRAFT 02-Feb-07


General Tips – Other Modeling Tips

• 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”

53DRAFT 02-Feb-07

• 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?

Lesson 3: Advanced Mapping Review & Questions

54DRAFT 02-Feb-07

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

55DRAFT 02-Feb-07

Exercises: Completing Hands-On Exercises: Overview

1. Minimize Centra or CBR/WBT teaching environment (Do NOT close the window)

2. Launch a new web session

3. Access the application you are being trained on

4. Complete the hands-on exercises

5. Minimize the web session

6. Maximize Centra to rejoin training

56DRAFT 02-Feb-07

• When instructed, minimize the Centra Session

Exercises: Minimizing Centra

57DRAFT 02-Feb-07

Exercises: Launching a New Web Session

• Launch a new web session• Complete the hands-on exercise• Minimize the web session

58DRAFT 02-Feb-07

Exercises: Rejoining Training Module (e.g, Centra)

• Once hands-on exercises are complete and you have minimized the web session, rejoin the training by maximizing the training session.

• Locate the Centra window in your Task Bar and click to maximize it.

59DRAFT 02-Feb-07

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

60DRAFT 02-Feb-07

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 SDK– 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

61DRAFT 02-Feb-07

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

62DRAFT 02-Feb-07

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

63DRAFT 02-Feb-07

Exercises

Download Files If You Haven’t Already

• The exercise instructions and files are available at the following URL:

http://<fill_in_URL_for_downloading_exercises>

• Please begin the exercises now• Ask questions as you need

64DRAFT 02-Feb-07

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 athttp://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

65DRAFT 02-Feb-07

Session Summary:

Course Evaluation

• Please provide feedback so we can improve this training

• Training Evaluation Form is on the Training Portal athttp://ncicb.nci.nih.gov/NCICB/training/cadsr_training/EvaluationForm

66DRAFT 02-Feb-07

THANK YOU!

For Additional Information:

Sichen Liu: [email protected]

Ye We: [email protected]

Charles Yaghmour: [email protected]

Documents

DRAFT 02-Feb-07 1 caAdapter Model Mapping Service Hands-On Training (Course# 2040) Session Date: TBD Session Length: 90 minutes Target Audience:caCORE