How to use the survey builder tool in HSLynk to capture APR reportable HMIS data elements
Let's give a couple examples of how to store the new 2020 HUD HMIS Data elements in HSLynk. The first example simply describes how to populate any HMIS element. The second example describes the slightly different task of storing the new coordinated entry data elements for 2020. These instructions could be easily generalized to apply to any HMIS data element from any HMIS Data Standard year 2014-2020, which HSLynk supports.
Please note, these instructions would be shorter, if one were just making custom surveys with custom questions, but these instructions require an extra step, to show how to get the question and response data also into the HMIS schema as well. When the data is in the very strictly controlled HMIS Schema, then you can run the required HMIS reports HUD requires, such as the 2020 HMIS Annual Performance Report. If you don't take this extra step, your questions and response data will be stored and retrievable, but you won't be able to get HMIS reports.
Populate the responses to the survey tool, responding to surveys questions that are built-in HUD HMIS 2020 questions
In order to double-post a survey question needs to be originally created with the following options:
POST /v2/questiongroups/{questiongroupid}/questions
In the POST request body, the following fields distinctly identify a survey question as HUD question:
hudQuestion:true, "updateUriTemplate": "/v2020/rest/clients/{clientid}/enrollments", "uriObjectField": "enrollment.timeshomelesspastthreeyears"
[to keep this brief and to the point, we don't show the preliminary steps of creating the survey by adding the questions to the survey]
Then add your client survey responses.
POST /v3/clients/{dedupclientid}/surveys/{surveyid}/responses
Populate (double-POST) the same response to the 2020 HUD HMIS schema, so you can run reports off the data
Once a survey question is created correctly and responses are collected for it in the last step, a double posting to the respective HUD schema can be performed by making a PUT call to the updateUriTemplate field passing uriObjectField.
PUT /v2020/rest/clients/{clientid}/enrollments
Populate the responses to the survey tool, responding to custom surveys questions that your community set up in the survey tool
In order to double-post, a survey question needs to be originally created with the following options:
POST /v2/questiongroups/{questiongroupid}/questions
In the POST request body, the following fields distinctly identify a survey question as HUD question:
hudQuestion:true, "updateUriTemplate": "/v2020/rest/clients/{clientid}/enrollments", "uriObjectField": "enrollment.timeshomelesspastthreeyears"
[to keep this brief and to the point, we don't show the preliminary steps of creating the survey by adding the questions to the survey]
Then add your client survey responses.
POST /v3/clients/{dedupclientid}/surveys/{surveyid}/responses
POST: v2020/clients/{clientid}/enrollments/{enrollmentid}/assessments
(you will insert actual IDs where the ellipses placeholders are...)
Add the CES questions the client responded to in the survey tool, to the 2020 HUD HMIS Schema's Coordinated Entry questions table
POST: /clients/{clientid}/enrollments/{enrollmentid}/assessmentquestions
Add survey tool responses in the first step, to the 2020 HUD HMIS Schema's Coordinated Entry responses table (aka results)
POST: /clients/{clientid}/enrollments/{enrollmentid}/assessmentresults
Assessments are always tied to enrollment. So you need to have the clientid and enrollmentid before posting your response to the HMIS 2020 Schema.
Note: This wiki document is related to issue #787 https://github.com/servinglynk/hslynk-open-source-docs/issues/787