Skip to content
  • There are no suggestions because the search field is empty.

Data Import Tool: Assessment Screen Mapping Improvements

This article provides details on how the Data Import Tool (DIT) handles Assessment screen mapping.

Table of Contents

Overview

The CSV and XML formats don't include information to pinpoint the type of screen or how Clarity Human Services should import the client Assessment records. There wasn't a way to specify that some Assessment records within a single file should be imported as one type of Assessment screen, and others as another.

Because of this, our Data Import Tool (DIT) allowed a user to designate a single default value to import all Assessment records. There are cases where a user will have a single file that contains records for multiple Assessment screens. The DIT is now updated to support these cases for Clarity CSV and Clarity XML. 

Extending XML and CSV Formats to Include Screen Information

The DIT has been updated to add the optional ScreenID and ScreenName elements/columns to the Clarity CSV and Clarity XML. 

When a user includes ScreenID and ScreenName elements/columns, this provides a way to map Client Assessment records to the Assessment Screens within Clarity Human Services.

We share a sample of an XML element within the Sample Format, including the new elements.

Note: The CSV is structured the same as the XML.

Sample Format

<hmis:Assessment hmis:dateCreated="..." hmis:dateUpdated="..." hmis:userID="...">       <hmis:AssessmentID>123</hmis:AssessmentID>

   <hmis:EnrollmentID>456</hmis:EnrollmentID>

   <hmis:PersonalID>789</hmis:PersonalID>

   <hmis:AssessmentDate>2019-01-01</hmis:AssessmentDate>

   <hmis:AssessmentLocation>1</hmis:AssessmentLocation>

   <hmis:AssessmentType>1</hmis:AssessmentType>

   <hmis:AssessmentLevel>1</hmis:AssessmentLevel>

   <hmis:PrioritizationStatus>1</hmis:PrioritizationStatus>

 

    <!-- New elements -->

    <hmis:ScreenID>10</hmis:ScreenID> 

    <hmis:ScreenName>Custom Assessment ABC</hmis:ScreenName> </hmis:Assessment> 

Element Definitions

  • ScreenID: the legacy screen identifier, used to build the mapping from the legacy screen to the Clarity screen.
  • ScreenName: the legacy screen name, used for display purposes when showing the legacy screens that need to be mapped in the DIT interface.

Mapping the Screens

After uploading the file through the DIT, the distinct ScreenID values in the file are collected and used to build the Assessment Mapping section in the DIT.

The previous behavior where users could select a single Assessment screen for all imported Client Assessment records still exists, including the new elements and using them for mapping not required. 

Any imported records that do not include a ScreenID value will are processed with the default value selected when importing the file. 

Allowing for imports where Client Assessment records are imported to specific Assessment screens, others just need to be imported to the default one.

Mapping XML File

The mapping XML file has also been extended to include assessment screen mappings, allowing these records to be mapped through the DIT API.

See below for an example mapping:

<AssessmentScreen>

            <ExternalID>10</ExternalID>

            <ClarityID>20</ClarityID>

</AssessmentScreen> 

Mapping Priority

  1. Any assessment with a ScreenID value will potentially be imported if the legacy ScreenID has a mapping set up.
  2. Otherwise, the default screen selected in the DIT dropdown will be used.

Mapping Error Handling

When processing the mapping records using the Mapping Priority listed above:

  •  Client assessments have ScreenID values referenced that don't exist will result in an error, and the Assessment skipped.
  • Client Assessments have ScreenID values are mapped to Assessment screens that a user shouldn't access will result in an error, and the Assessment skipped.

Updated: 06/16/2026