SSAS Enketo

This module is built around enketo-core to facilitate offline and online data collection.

Features

• Designed to work both in the browser and on mobile devices (Android and iOS).
• Uses PouchDB to store sessions and attachments for offline support.
• Session management. Support for multiple survey sessions.
• Easily localizable. Has multi-language support.
• Jump to screen to navigate around the survey.
• Image optimization for large photos.

Development

nvm use 14
# Do not use npm, use yarn.
yarn install

Clone this repository and install dependencies (yarn is recommended). There are two types of tests in this project: integration tests (cypress) and unit tests (mocha). Make sure both tests are passing before releasing a new version. You have to download and install cypress on your machine and open the project folder in the app to run the tests. Plus, make sure you are running a http-server which serves the contents of www folder at http://127.0.0.1:8080/

How to Use

This module is used by simply loading the necessary html file in the Browser or in a WebView. Take a look at the configuration table and pass your parameters in your query string.

1) survey.html

This is where the survey is displayed. It will start with a loading screen until the survey is loaded (either from disk or from a URL). Then it will prompt the user to create a session or continue from a previous session. You need to pass in necessary configuration for this file to work properly.

| Name | Required | Description | | ---------- | -------- | ----------------------------------------------------------------------------------------------- | | lang | Yes | Determines UI and Survey language. Pass in "en" if not sure. | | survey | Yes | Path to your survey json file (previously transformed from xml using enketo-transformer) | | mode | Yes | Options: online, offline (default). See survey modes section for further explanation. | | base | No | This will be prepended to all of the parameters taking paths (survey, submit, edit and return). | | return | No | Upon submission, this url will be loaded. | | bg | No | Sets the background photo to be shown while the survey is being loaded. | | novalidate | No | When this parameter is found, validation will be turned off for that session. | | assets | No | Assets (images) will be loaded relative to this path. | | sms | No | If exists, submissions can be sent via SMS to the number passed in. | | jumpto | No | Set this to "off" if you want to remove the search button in the toolbar | | title | No | Set this to "off" if you want to hide the survey title | | readonly | No | Loads the survey in read-only mode. Submit, save and validate buttons are hidden |

Based on your mode, further parameters may apply.

1) A. Extra parameters for "online" mode

| Name | Required | Description | | ------ | -------- | ------------------------------------------------------------------------------------------------ | | submit | Yes | Required with online mode. Should be the url to receiving OpenRosa server's submission endpoint. | | auth | No | Sets the authorization token for the current session. Only applicable in online mode. | | edit | No | Use with online mode only. You need to pass the path to the json file for the submission. |

1) B. Extra parameters for "offline" mode

| Name | Required | Description | | -------------- | -------- | ---------------------------------------------------------------------------------------------------------- | | session | No | Name of the session to create or continue. If you provide this, session modal will be skipped. | | session_extra | No | Pass a json string to be served alongside with the session. Will be submitted to the server. | | db | No | Sets the name of the database used to store sessions. Defaults to "sessions" when not set. | | instant_submit | No | If this parameter is set, the session can be submitted from the survey page, without going to submissions. |

2) submissions.html

This page will display all the submissions stored offline and let the user upload them to the server either one by one or all of them at one go.

| Name | Required | Description | | ------ | -------- | ------------------------------------------------------------------------------------------------------------- | | lang | Yes | Determines UI and Survey language. Pass in "en" if not sure. | | submit | Yes | The path for the OpenRosa server's submission endpoint | | base | No | This will be prepended to all of the parameters taking paths (server). | | db | No | Sets the name of the database used to store sessions. Defaults to "sessions" when not set. | | auth | No | Sets the authorization token for the current session. Always pass this if the server requires authentication. | | bg | No | Sets the photo to be shown in the background while this screen is being displayed |

Survey Modes

When displaying the questionnaire, you can choose from three survey modes

online

• No locally stored sessions. When interrupted, all data may be lost.
• At the end of the survey, the data is submitted to the server.
• If there's no internet connection, survey may not be completed.

offline

• Sessions are stored on the device.
• Sessions will not be submitted to the server at the end of the survey.
• Sessions must be sent to the server separately (via submissions.html)

Authorization

Some portal instances may have 'require authentication' turned on. In this case, it is not possible to download the survey or make a submission without a valid authorization token. There are two ways of passing in the authorization token into enketo.

1. Pass via query parameter ?auth=...token...
2. Pass via cookie enketo_token