caadapter fundamentals session date: session length: 1.5 hours trainer:
TRANSCRIPT
caAdapter Fundamentals
Session Date:
Session Length: 1.5 hours
Trainer:
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.
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.
Session Details:
Online Training Etiquette
Be an active learner! – This is your best opportunity to ask lots of questions. – Avoid the temptation to multi-task; keep distractions to a minimum.
When not actively asking a question or making a comment, please keep your phone on MUTE.– This will minimize background noise so that all can hear the person
who is speaking.
Please do not put your phone on HOLD.– HOLD music will disrupt the conference call.
When asking a question or making a comment, please state your name. – This way, all participants will know who is speaking.
Session Details
Target Audience: HL7 v3 domain analysts and developers
Prerequisites: – Intermediate to advanced knowledge of HL7 v3– A strong understanding of HL7 v3 specifications and artifacts– Completion of the HL7 and caAdapter Overview Training– A working knowledge of UML
Session Details:
Presenters and Participants
Who is Presenting?
Who is in attendance?– Name – Title – Cancer Center– Reason for Attending
Upon successful completion of this training, you should be able to:– Discuss the role of caAdapter at NCICB– Describe caAdapter’s features, architecture and capabilities– Demonstrate how to use caAdapter’s four main functions
Session Details:
Training Objectives
Session Details:
Lesson Plan
caAdapter Introduction
Comma Separated Values (CSV) Specification
HL7 v3 Specification
Map Specification
Generating HL7 v3 Messages
caAdapter Introduction
In this lesson, we will:– Discuss the role of caAdapter at NCICB– Describe caAdapter’s features, architecture and functions– Present key information, files and software required prior to using
caAdapter
caAdapter Introduction:
The Role of caAdapter at NCICB…
The Department of Health and Human Services (HHS) adopted Health Level Seven (HL7) as a messaging standard.
The main goal of HL7 version 3 (v3) is semantic and syntactic interoperability of healthcare data, which is also an important part in NCICB’s mission statement.
To promote the use of HL7 v3 in the cancer community, NCICB developed caAdapter (formerly called HL7 SDK) as a component of its biomedical informatics infrastructure.
caAdapter Introduction:
The Role of caAdapter at NCICB
Capabilities of caAdapter: caAdapter facilitates HL7 v3 message building, parsing and
validation based on HL7’s specific message definitions. caAdapter provides the capability to perform vocabulary validation
of core structural attributes through integration with caBIO APIs for the Enterprise Vocabulary Services (EVS).
caAdapter also provides a graphical user interface (GUI) and backend engine for mapping and converting clinical data in the form of comma separated values (CSV) files into HL7 v3 XML messages.
caAdapter Introduction:
caAdapter is Part of the Clinical Architecture Vision
HL7 v3 is a potential data exchange solution within the NCICB Clinical Architecture Vision.
caAdapter Introduction:
caAdapter Features
HL7 v3 Message Parser– Parses HL7 v3 messages to RIM object graph
HL7 v3 Message Builder– Builds HL7 v3 messages from the RIM object graph
HL7 v3 Java Artifacts– Implements RIM objects, data types and metadata objects
Metadata Loader– Represents HL7 v3 metadata in-memory
Validation Services– Integrates with W3C XML schema validation services and NCICB
caCORE components such as EVS
caAdapter API– Provides interfaces to caAdapter services
Mapping Tool– Provides GUI and engine for mapping and converting CSV data into HL7
v3 XML
HL7 v3
XML file
Validation
Vocabulary
HL7 v3 API
Metadata Loader
Message Parser
Message Builder
Data Type
Objects
RIM
Objects
Metadata
Objects
SchemaXSD
EVS
HL7 CTS
caBIO
caAdapter Introduction: Architecture of the Core Engine
HMD
caAdapter Introduction: The Mapping Tool’s Associated Features
The Mapping Tool– Graphical application for mapping clinical data to an HL7 v3 message
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 basic source data manipulation
XML Transformer– Generation of XML message instances from source data based on the
mapping
Specification Component
External Clinical Data:
CSV
CSV
Graphical User Interface
Tree Function Drag-n-Drop Property
Transformation Service
HL7 v3 Mapping Function
CSV Specification Mapping SpecificationHL7 v3 Specification
CSV to HL7 v3 Processor Validation
Core
Engine
Function Specification
HMD
HL7 v3
XML file
caAdapter Introduction:
caAdapter Architecture of the Mapping Tool
caAdapter Introduction:
How the Mapping Tool Works…
Transformation (APIs)
Mapping Tool
Clinical Data
Source Data
(CSV)
HL7 v3 XML
CDMS
caAdapter Introduction:
How the Mapping Tool Works
Source Data
(CSV)
1
caAdapter Introduction:
How the Mapping Tool Works
Mapping ToolCDMS
Source Data
(CSV)
1
2a 2b
Source Specification
2
HMD
HL7 Specification
3
TransformationHL7 v3 XML
Convert Clinical Data to HL7 v3 Message
5
2
4
Mapping File
Mapping Tool
caAdapter Introduction:
How the Mapping Tool Works
CDMS
Source Data
(CSV)
1
Source Specification
The four main functions of caAdapter are:– Defining a source specification – Defining a target specification – Defining a mapping specification – Converting source data to target data format
Each of these four functions has a dedicated tab in the GUI and provides sub-functions for handling data, such as:– Creating– Modifying– Saving– Validating
caAdapter Introduction:
The Main Functions and Sub-Functions of caAdapter
caAdapter Introduction: Key Information for Installing and Using caAdapter…
Reading the Installation Guide and User’s Guide is highly recommended prior to installation.
Using caAdapter requires access to HL7 v3 HMDs (Hierarchical Message Definitions) which are the basis for the target specifications.
HL7 requires membership to access their HMDs.
caAdapter Introduction: Key Information for Installing and Using caAdapter
Prior to running caAdapter, you should also:– Install the Java Development Kit (JDK) version 1.5.0_04 on the target
system (for example, C:\jdk1.5.0_04).– Download HMDs for the messages you want to generate.– Verify that the V3mHMD.dtd file is saved in the dtd directory under
same directory as your HMD files. (If not, download the sample HMD files from http://www.hl7.org/Special/committees/java/index.cfm#WorkProduct using your HL7 member login.)
caAdapter Introduction
Any Questions?
The role of caAdapter at NCICB
caAdapter’s features, architecture and functions
Key information, files and software required prior to using caAdapter
CSV Specification
In this lesson, we will:– Explain CSV file concepts and structures – Describe a Segmented CSV File Example– Provide an introduction to the CSV Specification Tab– Show how to create, modify and save CSV specifications– Explain how to validate CSV specifications– List business rules for CSV specifications– Describe how to generate a report
CSV Specification: CSV File Concepts and Structures…
In a generic CSV file each line has one or more values separated by commas
caAdapter uses segmented CSV files:– Each line starts with an identifier describing what type of data is
on that line– Segment is the term for a line with an identifier in the first
position; this identifier is called a segment identifier– Other positions that contain the data items are called fields – Fields are terminated by commas
PERS,Doe,Jane,Q,NRS10,RAD
PERSID,2.16.840.1.113883.19.1,12345
PERSAD,123 Main St.,Suite 500,Rockville,MD,20852Segment Identifier
SegmentFields
CSV Specification: CSV File Concepts and Structures…
Segmented CSV files follow strict hierarchical rules:– A logical record is several different segments physically
sequenced together to form a meaningful set of data– The first segment in a logical record is the root segment
• Each logical record has one, and only one, root segment
• Each root segment may have zero, one, or many child segments– Child segments may have zero, one or more grandchild segments,
and so on
CSV Specification:
CSV File Concepts and Structures…
“PERS” is the root
segment
3 Logical Records
Number and presence of child segments may vary from record to record, e.g. ORGNM, but always follow their parent segment
2
2
3
CSV Specification:
CSV File Concepts and Structures…
Segmented CSV files follow more hierarchical rules:– Child (and grandchild, etc.) segments may appear zero, one, or
more times in a logical record– Segments always follow their parent or a sibling segment (a
segment with the same parent)– A segmented CSV file may include one or more logical records,
with each logical record terminated by the next root segment or the end-of-file (EOF)
CSV Specification:
CSV File Concepts and Structures
The “family tree” of the root segment, and it’s child, grandchild, etc. segments and all their fields, is represented in caAdapter in a tree hierarchy:
PERS
PERSADPERSID ORGID
ORGNM ORGAD
Logical Model
PERS
PERSID
PERSAD
ORGID
ORGNM
ORGAD
Physical Model
(PERS fields)
(ORGID fields)
(PERSID fields)
(PERSAD fields)
(ORGNM fields)
(ORGAD fields)
The tree structure displays the hierarchy of segments and fields
CSV Specification: Introduction to the CSV Specification Tab…
Validation messages are shown in this pane
Property details for segments or fields are shown in this pane
CSV Specification: Introduction to the CSV Specification Tab
Click on segment to edit segment name or field order
The Field Properties pane is context
sensitive
CSV Specification: Creating CSV Specifications…
File > New > CSV Specification
Three Options:1. From scratch
2. From a CSV data file
3. From an existing CSV specification
CSV Specification: Creating CSV Specifications
From scratch: From a CSV data file: From an existing CSV specification:
CSV Specification: Modifying CSV Specifications…
Options for modifying CSV specifications include:– Adding segments– Adding fields– Deleting segments– Deleting fields– Editing segment names– Editing field names– Moving segments (drag and drop)– Moving fields to a different segment (drag and drop)– Reordering fields within a segment
CSV Specification: Modifying CSV Specifications…
Add a segment
Add a field
Edit a segment name
CSV Specification: Modifying CSV Specifications…
Two ways to edit– Right-click and then select Edit – then edit the name in the pop-up– Edit the name in the Properties pane
One way to delete– Right-click and then select Delete – then confirm in the pop-up
CSV Specification: Modifying CSV Specifications
Move a segment to a different parent segment
Move a field to a different parent segment
Reorder fields within a segment
Drag-n-drop segment onto new parent
Drag-n-drop field onto new parent
Select field & use buttons to reorder
CSV Specification: Saving CSV Specifications
To save: Select File > Save
To save as: Select File > Save as
Note that the file name on the tab will change
CSV Specification: Validating CSV Specifications
Select File > Validate, then choose an option:– Validate Specification
• Validates specification against business rules
– Validate CSV Data Against Specification
• Validates contents of data file against specification
• Click Browse to display the Open CSV File dialog box, select a .csv file, choose Open then choose Validate
Four Validation Message Types:
- FATAL- ERROR
- WARNING- INFO
CSV Specification: Business Rules for Segmented CSV Specifications…
Business rules for CSV specifications include the following:– There must only ever be one root segment– Segment names must be unique across the specification– Segment names must be a combination of capital letters,
numbers, or the underscore character– Field names must be unique within the segment– Field names must be a combination of any letters (A-Z or a-z),
numbers, or the underscore character
CSV Specification: Business Rules for Segmented CSV Specifications
Business rules for validating data files against specifications generate messages when:– An extraneous segment is found in the data, but not in the
specification– The root segment is missing from the data all together– Child segments appearing without their parent– Segments in the data contain more fields than in the specification
CSV Specification: Generating a Report
Once a CSV specification is displayed in the tab, it can be exported to Excel by:– Selecting Report >
Generate Report which will display the Select File to Save Generated Report dialog box
– To finish, simply choose a File Name, and select Save
CSV Specification: Any Questions?
CSV file concepts and structures
The CSV Specification Tab
Creating, modifying and saving CSV specifications
How to validate CSV specifications
Business rules for CSV specifications
How to generate a report
HL7 v3 Specification
In this lesson, we will:– Present an introduction to the HL7 v3 Specification Tab– Describe how to create, modify and save HL7 v3 specifications
using HMDs – Explain how to validate HL7 v3 specifications – Establish business rules for HL7 v3 specifications
HL7 v3 Specification: Introduction to the HL7 v3 Specification Tab
The HL7 v3 specification tab allows you to identify the hierarchy of elements needed for your data (based on what is available in the predefined structure of an HL7 v3 message type).
Same three panes as in the CSV specification tab
HL7 message elements in tree hierarchy
Validation messages
Context sensitive
properties
HL7 v3 Specification: Creating HL7 v3 Specification Files
There are three types of elementsin the tree hierarchy:– C = Clone
• A RIM class renamed withinthe context of this message
– A = Attribute
• A RIM attribute– D = Data Type Field
• A property of an HL7 data type
HL7 v3 Specification: Creating HL7 v3 Specifications
Select File > New > HL7 v3 Specification
Select an option from the dropdown list
caAdapter will:– Parse the selection– Build out the tree using only
mandatory clones (minimum cardinality of 1)
HL7 v3 Specification: Modifying HL7 v3 Specification Files…
Several ways to tailor the specification to your needs within the bounds of the official HL7 message definition:– Including optional clones– Adding multiples of clones or attributes with a cardinality of greater
than one– Selecting a clone for a choice box– Selecting a concrete data type where HL7 defined an abstract one– Entering user-defined default values
You may not change the specification to add clones, attributes or data type fields that are not in the standard HL7 message definition
HL7 v3 Specification: Modifying HL7 v3 Specification Files…
Initially, caAdapter includes only mandatory clones
Users must explicitly include optional clones if they want to map to that area of the message:– Right-click on the clone you want to include associations for– Select the clone, caAdapter will add it to the end of the tree
Optional Clone
HL7 v3 Specification: Modifying HL7 v3 Specification Files…
Sometimes during mapping you will need to map to more than one instance of a clone/attribute that has a cardinality of greater than one
caAdapter handles this by allowing you to add instances wherever you see the [Multiple] label following a clone or attribute:
Context menu for instance [1] allows you to add more or
remove instances
HL7 v3 Specification: Modifying HL7 v3 Specification Files…
Right-click on clone with[Choice – Unselected], choose Select Choice
Select a clone
caAdapter will replace the choice box name with the chosen clone and change the label to [Selected Choice for…]
HL7 v3 Specification: Modifying HL7 v3 Specification Files
Properties are context sensitive based on selected tree element
Most are populated automatically from the HMD properties
Only 2 are editable:– Data Type – only editable if the HL7-assigned value is abstract
(e.g. ANY or QTY)
– User-defined Default Value – editable for all data type fields
To save: Select File > Save
To save as: Select File > Save as
Note that the file name on the tab will change
HL7 v3 Specification: Saving HL7 v3 Specifications
HL7 v3 Specification: Validating HL7 v3 Specifications…
Select File > Validate
caAdapter will validate the specification against the business rules for HL7 v3 specifications and generate validation messages.
HL7 v3 Specification: Validating HL7 v3 Specifications
After the validation has been processed, any messages will be shown in the right hand pane.
HL7 v3 Specification:
Business Rules for HL7 v3 Specifications
Abstract data types must be specialized– Every data element has a data type assigned by HL7– If the HL7-assigned data type is abstract (e.g. ANY or QTY), then
it must be specialized to something concrete so that caAdapter can process it
A choice must be selected from the list of choice options– This only applies to clones included in the specification– If a choice is in an optional part of the message, then it is not
required to be part of the specification
HL7 v3 Specification:
Any Questions?
Introduction to the HL7 v3 Specification Functions
How to create, modify, and save HL7 v3 specifications using HMDs
How to validate HL7 v3 specifications
Business rules for HL7 v3 specifications
Map Specification
In this lesson, we will:– Provide an introduction to the Map Specification Tab– Describe how to create, modify and save map specifications– Explain how to validate map specifications– Establish business rules for map specifications– Share some lessons learned
Map Specification:
Introduction to the Map Specification Tab…
A mapping is a user-defined relationship between a source element and a target element.
Using the mapping tool, the user can create links between source fields and target data type fields, and between source segments and target clones or attributes. – Links between source fields and target data type fields are used to
represent data relationships. – Links between segments and clones or attributes are used to
explicitly link concepts that provide a context to the data and are also called container mappings.
– Links may also be created between source fields and input parameters of a variety of functions provided by caAdapter, and between the function's output parameters and target elements.
Map Specification:
Introduction to the Map Specification Tab…
Two tree panels - contain source specification in first tree panel, and target specification in second tree panel.
Center mapping panel - displays lines that indicate mapping between source fields and target fields and any functions that are used in mappings.
Functions panel - displays tree of available functions.
Properties panel - changes depending on item selected in other panels (for example, displays link properties, segment properties, clone properties, etc.).
Map Specification:
Introduction to the Map Specification Tab
The Properties pane is context sensitive to whatever item is selected:
– Source segments– Source fields– Target clones– Target attributes– Target data type fields– Mapping lines– Functions:
• In Function pane: functions
• In Mapping pane: instances of functions
None of the properties are editable in the Properties pane on the mapping tab, they are just for informational purposes
Map Specification:
Creating Map Specifications…
Select File > New > Map Specification
Select a source file (a CSV Specification) and a target file (an HL7 v3 Specification) using the Open buttons
This will display the source and target elements in the 2 tree hierarchies, and the file names in the fields beside the Open button
Map Specification:
Creating Map Specifications…
To map source elements to target elements:– Drag and drop the source element onto the target element– Once a source field is mapped to a target element, a mapping line
appears between them in the mapping panel. – When a mapping line is clicked, it is highlighted along with the
source and target elements.
Map Specification:
Creating Map Specifications
17 functions in 4 types available:
Drag-n-drop directions – not always left to right– Drag source fields to input function parameters– Drag target fields to output function parameters
Chaining functions is permitted – e.g., using a constant function as an input to another function
Constant Data Math String String (cont.)
(User Defined Value)
ChangeFormat Add Concatenate Replace
Subtract Split Instring
Multiply Length Upper
Divide Substring Lower
Round Trim Initcap
Map Specification:
Saving Map Specifications
To save: Select File > Save
To save as: Select File > Save as
Note that the file name on the tab will change
Map Specification:
Validating the Map Specification
Perform the following steps to validate the map specification:– Select File > Validate or select the Validate icon from the tool bar
to perform the validation.– A Message dialog box displays indicating the status of the
validation. Click OK.– The detailed messages will display in the Validation Messages
dialog box (please see Chapter 5 of the User’s Guide for more information).
Map Specification:
Business Rules for Map Specifications
The mapping specification must contain a valid mapping pair (source and target files).
The source field referenced in the map specification must exist in the source specification.
The destination field referenced in the map specification must exist in the destination specification.
A mandatory HMD element must have either a mapping in the map specification, or an HL7-defined or user-defined default value in the HL7 v3 specification.
Each input parameter for a function must have a mapping (or a constant) defined.
Each output parameter for a function must have a mapping defined.
Map Specification:
Lessons Learned…
Start by spending some significant time getting to know the HL7 v3 message you are targeting before doing anything else.
Whenever possible, define your CSV specification based on cardinalities of the clones in the HL7 v3 message you plan to use.
Do the detailed analysis to contrast your source data with what is mandatory in the HL7 v3 message to identify what you’ll need to create default values for and to determine how to accommodate all the source data needed in the HL7 v3 message.
Map Specification:
Lessons Learned
Use a spreadsheet to do initial mapping between source and target files to identify problem areas before you start mapping in caAdapter.
Expect to do an iterative process of defining your HL7 v3 specification, creating an initial mapping, finding problems, going back to fix the HL7 v3 specification, mapping again, etc.
Reminder: When using any of the four function tabs in caAdapter, only one tab of each type can be open at a time; i.e. if the Map tab is open, it must be closed prior to working with another .map file.
Map Specification:
Any Questions?
Introduction to the Map Specification Tab
How to create, modify and save map specifications
How to validate map specifications
Business rules for map specifications
The overall mapping process
Lessons Learned
Generating HL7 v3 Messages
In this lesson, we will:– Provide an introduction to the HL7 v3 message tab– Describe how to start the conversion process– Establish business rules for generating HL7 v3 messages– Show how to save HL7 v3 messages– Show how to save validation messages
Generating HL7 v3 Messages: Introduction to the HL7 v3 Message Tab…
The HL7 v3 Message tab is used to display the XML messages generated from a CSV data file and a map specification, and any associated validation messages.
Each data file may have one or more logical records which result in a corresponding number of XML instances (or more depending on the structure of the mapping).
The user interface allows you to navigate between the instances.
Generating HL7 v3 Messages:
Introduction to the HL7 v3 Message Tab
The HL7 v3 message tab contains four panels
These two panels are
coordinated Validation Messages
HL7 v3 XML Message Instances
Files UsedNavigation
Generating HL7 v3 Messages: Starting the Conversion Process
To convert a data file into an HL7 v3 message– Select File > New > HL7 v3 Message to display the HL7 v3
Message dialog box
– Click Browse next to Data File to select the CSV data file from the Open Data File dialog box
– Click Browse next to Map Specification to select the map file from the Open Map Specification dialog box
– Click OK to generate HL7 v3 messages from the selected files
Generating HL7 v3 Messages: Business Rules for Generating HL7 v3 Messages
Data must be in a CSV format.
The map specification must be valid.
The source and target specifications used to create the map must be placed in the same directory as they were when the map specification was created.
Generating HL7 v3 Messages:
Saving HL7 v3 Messages and Validation Messages
Saving generated HL7 v3 XML messages: File > Save – You will be prompted to enter a file name– Note that all HL7 v3 messages will be saved individually at the
same time using the naming convention:
<file_name>_<#>.xml
– For example, Personnel_1.xml, Personnel_2.xml, etc.
Saving validation messages:– Click the Save button in the Validation Messages panel – All validation messages for the current HL7 v3 message are
saved at one time rather than saving all validation messages for all HL7 v3 messages at once using separate files as above
Generating HL7 v3 Messages:
Any Questions?
Introduction to the HL7 v3 message tab
How to start the conversion process
Business rules for generating HL7 v3 messages
How to save HL7 v3 messages
How to save validation messages
Session Review
Now that you have successfully completed this session, you should be able to:– Discuss the role of caAdapter at NCICB– Describe caAdapter’s features, architecture and capabilities– Demonstrate how to use caAdapter’s four main tabs
Resources
caAdapter 1.2 User Guide:– may be downloaded from the caAdapter website
caAdapter Website:– http://trials.nci.nih.gov/projects/infrastructureProject/caAdapter
caAdapter Download Site:– http://ncicb.nci.nih.gov/download/
NCICB Application Support
Live Support: Monday – Friday 8 am – 8 pm Eastern Time– Telephone support is available Monday to Friday, 8 am – 8 pm
Eastern Time, excluding government holidays. – You may leave a message, send an email or submit a support
request via the Web at any time.
Email: [email protected]
Phone: 301-451-4384
Toll-free: 888-478-4423
Web: http://ncicb.nci.nih.gov/NCICB/support