caadapter fundamentals session date: session length: 1.5 hours trainer:

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


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.


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 is Part of the Clinical Architecture Vision

HL7 v3 is a potential data exchange solution within the NCICB Clinical Architecture Vision.


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 Architecture of the Mapping Tool


How the Mapping Tool Works…

Transformation (APIs)

Mapping Tool

Clinical Data

Source Data

(CSV)

HL7 v3 XML

CDMS


How the Mapping Tool Works

Source Data

(CSV)

1



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



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


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


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


Add a segment

Add a field

Edit a segment name


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


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


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


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




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




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.


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


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

caadapter fundamentals session date: session length: 1.5 hours trainer:

Documents

caadapter slide

role of caadapter

caadapter overview

use of hl7 v3

hl7 v3 messages

slide bars

hl7 sdk

advanced knowledge of