Feature: Online Survey with Auth and Case components; Case and Online Survey APIs; "Locked" Online Surveys with Links from Case Event Forms

[esurface]

Description

This is a major update to Tangerine Online Surveys.

Online Survey Authorization
With this update, the survey manager will be able to deploy "locked" surveys that require the respondent to enter an access code to, well, access the form. The authorization protects sensitive form content, like proprietary assessments. Login access is provided to users by creating 'Device Users' and assigning the 6-digit short code for the user as the access code. Users will be logged out when the authentication token expires. They will be warned 15 minutes before expiry.

The online survey supports 'Custom Login Markup'. To override the default login, create a file in the content set called custom-login-markup.html. Valid html will be loaded and displayed by the online survey login page.

Online Survey "Help Link"

Provide link to instructions or help by adding a URL to the app-config.json. For example:
"helpLink":"/releases/prod/online-survey-apps/group-id/help_form/#/form/help_form" will link to another published Tangerine form. Any external URL can be used as well (put the whole link starting with http://).

Online Survey Publish

Online Surveys that require authorization vs those that do not are differentiated in the Tangerine web interface by the 'lock' symbol.

__ Online Survey API__

Use getOnlineSurveys to get the list of published and unpublished surveys. Provide an optional formId to filter the online surveys by formId.

API	Parameters	Return
getOnlineSurveys	groupId, [formId]	online-surveys.json

Case in Online Surveys
If the Case module is enable, the content manager can choose (not in the UI yet) which forms are accessible through Online Surveys. An example use case is a longitudinal study that collects lab samples. The lab techs can enter the lab results directly in an online survey connected to the case event form which saves the requirement to install a Tangerine APK or PWA on a tablet or laptop in the lab.

Case event forms filled out as online surveys will be saved to the server each time the user clicks 'Next' or 'Back' allowing the respondent to return to the survey with progress saved. Once they submit the form, they will be able to review the form response in 'locked' mode.

Case APIs
This version introduces new Tangerine server APIs for the creation of Case, Event, Form, Participant instances, plus a few helper APIs for working with case. The user must be authorized through the '/login' API.

API	Parameters	Return
getCaseDefinitions	groupId	case-definitions.json
getCaseDefinition	groupId, caseDefinitionId	<case>-definition.json
createCase	groupId, caseDefinitionId	<caseId>
readCase	groupId, caseId	<case-doc.json>
createCaseEvent	groupId, caseId, caseEventDefinitionId	<case-event-id>
createEventForm	groupId, caseId, caseEventId, caseEventFormDefinitionId	<event-form-id>
createParticipant	groupId, caseId, caseDefinitionId, caseRoleId	<participant-id>
getCaseEventFormSurveyLinks	groupId, caseId	<event-links-json>

getCaseEventFormSurveyLinks

getCaseEventFormSurveyLinks is helpful when using Tangerine and the Case module as a backend server for online survey forms. After publishing online surveys and creating cases, you can call this API to get the full list of links to the incomplete, online-enabled event forms in the case. A typical order of API calls might be:

authToken = /login
userId = /userProfile/createUserProfile/:groupId
caseId = /case/createCase/:groupId/:caseDefinitionId
participantId = /case/createParticipant/:groupId/:caseId/:caseDefinitionId/:caseRoleId
getCaseEventFormSurveyLinks = /case/getCaseEventFormSurveyLinks/:groupId/:caseId

Example link returned from getCaseEventFormSurveyLinks:

{
   "eventDefinitionId": "remote-parent-2-5-event",
   "eventFormDefinitionId": "remote-parent-assessment-form",
   "formId": "assessments_for_2_5",
   "url": "http://localhost/releases/prod/online-survey-apps/<groupId>/assessments_for_2_5/#/case/event/form/<case-id>/<event-id>/<form-id>"
 }