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 NCI CBIIT – 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 NCI CBIIT – 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 NCI CBIIT…  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 NCI CBIIT’s mission statement.  To promote the use of HL7 v3 in the cancer community, NCI CBIIT developed caAdapter (formerly called HL7 SDK) as a component of its biomedical informatics infrastructure.

caAdapter Introduction: The Role of caAdapter at NCI CBIIT  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 NCI CBIIT Clinical Architecture Vision.

caAdapter Introduction: caAdapter Features  HL7 v3 Message Builder – Builds HL7 v3 messages  Metadata Loader – Represents HL7 v3 metadata in-memory  Validation Services – Integrates with W3C XML schema validation services and NCI CBIIT 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

caAdapter Introduction: Architecture of the Core Engine

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

caAdapter Introduction: caAdapter Architecture of the Mapping Tool

 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 using your HL7 member login.)

caAdapter Introduction Any Questions?  The role of caAdapter at NCI CBIIT  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, ,12345 PERSAD,123 Main St.,Suite 500,Rockville,MD,20852 Segment Identifier Segment Fields

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 ORGNMORGAD 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 – 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 elements in the tree hierarchy: – C = Clone A RIM class renamed within the 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 > CSV To HL7 v3 Mapping and Transformation Service > HL7 v3 Specification

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 ConstantDataMathStringString (cont.) (User Defined Value) ChangeFormatAddConcatenateReplace SubtractSplitInstring MultiplyLengthUpper DivideSubstringLower RoundTrimInitcap

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

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: _.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 NCI CBIIT – Describe caAdapter’s features, architecture and capabilities – Demonstrate how to use caAdapter’s four main tabs

Resources  caAdapter 4.0 User’s Guide: – may be downloaded from the caAdapter website  caAdapter Website: – adapter adapter  caAdapter Download Site: –

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 or submit a support request via the Web at any time.   Phone:  Toll-free:  Web: