Importing Data

Data Import Tool: Assessment Screen Mapping Improvements



The HUD XML and CSV formats don't include information on pinpointing the type of screen and how Bitfocus should import the client Assessment records. There wasn't a way to say some Assessment records within a single file should be imported as one type of Assessment Screen, and others should be imported as another.

Because of this, our 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. 

Extending XML and CSV formats to include screen information

The DIT is updated, adding the optional ScreenID and ScreenName elements/columns to the HUD XML and HUD CSV. 

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>









    <!-- New elements -->


    <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 the assessment screen mappings to allow mapping these records through the DIT API. See below for an example mapping:





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