Skip to content

How to use the survey builder tool in HSLynk to capture APR reportable HMIS data elements

Jump to bottom
Eric Jahn edited this page Mar 3, 2020 · 53 revisions

Let's give an example of how to store the new 2020 HUD HMIS Data elements in HSLynk, specifically the new coordinated entry ones. These instructions could be easily generalized to apply to any HMIS data element from any HMIS Data Standard year 2014-2020, which HSLynk supports.

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.

Example 1: non-Coordinated Entry 2020 HUD HMIS responses

Populate the responses to the survey tool, responding to surveys questions that are built-in HUD HMIS 2020 questions

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

Example 2: Coordinated Entry 2020 HUD HMIS responses

Populate the responses to the survey tool, responding to surveys questions that are built-in HUD HMIS 2020 questions

Step 1: Create a new survey

(you will insert actual IDs where the ellipses placeholders are...)

POST: v2020/clients/{clientid}/enrollments/{enrollmentid}/assessments

Step 2: Add pre-made 2020 HMIS Questions to the new survey you just made

POST: /clients/{clientid}/enrollments/{enrollmentid}/assessmentquestions

Step 3: Now that the survey is built, have someone take the survey, and add responses to the Coordinated Entry questions

POST: /clients/{clientid}/enrollments/{enrollmentid}/assessmentresults

Step 4: Populate (double-POST) the same response to the 2020 HUD HMIS schema, so you can run reports off the data

Assessments are always tied to enrollment. So you need to have the clientid and enrollmentid before posting your response to the HMIS 2020 Schema. Example: Lets take an example where one needs to update EventDate (4.20.1) for an Event.

You need to do the following.

  1. Make an API call to the /questions API. GET: https://api.hslynk.com/hmis-clientapi-v2020/rest/questions/

Here is an example response excerpt:

questions": [
  {
"links": [
  {
   "rel": "pickList",
   "href": "/hmis-clientapi/rest/v2020/hmistypes/event_date/values"
  }
],
"questionId": "353ada26-44d1-4d9d-8b1a-f52133fb8b31",
"questionDescription": "Event Date",
"displayText": "Event Date",
"questionDataType": "STRING",
"questionType": "DATE",
"picklistGroupName": "event_date",
"hudQuestionId": "4.20.1",
"uriObjectField": "event.eventDate",
"updateUriTemplate": "/v2020/clients/{clientid}/enrollments/{enrollmentid}/events/{eventid}",
"options": {}
}
... and so on, listing all the questions from the 2020 HMIS Data Standard

If you filter your result by the hudQuestionId = 4.20.1 you would see that we have uriObjectField and updateUriTemplate which you can use to call to update an event date for an event.

  1. Call the below API by populating the event.eventDate PUT: /v2020/clients/{clientid}/enrollments/{enrollmentid}/events/{eventid}

Please refer to our API documentation for more details. https://docs.hslynk.com/?urls.primaryName=2020%20Apis#/default/PUT_clients-clientId-enrollments-enrollmentId-events-eventId

Note: This wiki document is related to issue #787 https://github.com/servinglynk/hslynk-open-source-docs/issues/787

Clone this wiki locally