The Enketo Smart Paper web application. It can be used directly by form servers or used as inspiration for building applications that wrap Enketo Core. See this diagram for a summary of how the different Enketo components are related.
This is a fork of enketo/enketo-express that has the following additions:
- An account manager to use multiple accounts with a single Enketo installation.
- A fieldsubmission webform view that uses OpenClinica's Fieldsubmission API.
- An OpenClinica theme: theme-oc.
- Advanced comment widgets: discrepancy note widget
See this faq.
Enketo endeavors to show a helpful (multi-lingual) error message on unsupported browsers when the form is loaded to avoid serious issues.
To run Enketo Express, you will first need to configure it. Read about all configuration options here
All configuration is normally done in config/config.json. This file only has to contain the default properties that you'd like to override. For some it may be preferable to include all properties, to avoid surprises when the default configuration changes. Others may want to reduce hassle and keep the config.json as small as possible to automatically deploy configuration changes (e.g. new widgets). The application needs to be rebuilt when the widget configuration is changed but otherwise a restart should be sufficient.
You can use environment variables instead of a config/config.json file. If the config/config.json file is missing Enketo will assume configuration is done with environment variables. A combination of both options is not supported. See config/sample.env for more information on equivalent environment variable names.
Always leave config/default-config.json unchanged.
The default production configuration includes 2 redis instances: one for caching form transformations (see Enketo Transformer) and one for persistent data like associations between form server URLs and Enketo form IDs. You can greatly simplify installation by using 1 redis instance instead (for development usage). To do this set the redis.cache.port to 6379 (same as redis.main.port).
OpenClinica users, in addition to the configuration documentation linked above, may want to take special note of the following recommended settings:
- Set a secret value for
"account manager api key"(or set it tofalseif OC's custom Account Manager is not used). - The
"linked form and data server"object should not have"server url"and"api key"properties (if OC's custom Account Manager API is used). - Set
"disable save as draft": true - Set
"repeat ordinals": true. This feature is required for the fieldsubmission webform views. - Set
"query parameter to pass to submission": "ecid" - Set
"validate continuously": true - Set
"validate page": false(though some applications may wish to usetrue) - Set
"default theme": "oc" - Set
"text field character limit": 3999
For development usages, it is helpful to set "linked form and data server" -> "server url" to "", so you can use any OpenRosa server with your local Enketo Express.
For detailed guidance on each configuration item, see the configuration tutorial.
To configure your own custom external authentication also see this document.
Enketo Express is generally used as a service which is part of a broader platform including at minimum an OpenRosa form server. If you would like to embed web forms directly in an existing application, consider using Enketo Core and looking at the Enketo Express codebase to understand how the host application can interact with Enketo Core.
We generally recommend deploying Enketo Express using Docker. See the toplevel README.
First, make sure redis is running and available at the port(s) configured in config/config.json. You should also read the section on configuring Enketo Express above. You will also need to have an OpenRosa server running and accessible to Enketo Express and which knows about the API key in the configuration.
As described in the the toplevel README, all tasks should be run from the project root. To build and start Enketo Express:
yarn build
yarn workspace enketo-express startYou can now check that the app is running by going to e.g. http://localhost:8005 (depending on your server and port set in config/config.json)
The easiest way to start the app in development and debugging mode with livereload is with yarn workspace enketo-express grunt develop.
Testing is done with Mocha and Karma:
- all:
yarn workspace enketo-express run test - headless:
yarn workspace enketo-express run test-headless - browsers:
yarn workspace enketo-express run test-browsers
Tests can be run in watch mode for TDD workflows with:
- client:
yarn workspace enketo-express run test-watch-client - server:
yarn workspace enketo-express run test-watch-server
Basic usage:
- Go to VSCode's "Run and Debug" panel
- Select "Test client (watch + debug)" or "Test server (watch + debug)"
- Click the play button
Optionally, you can add a keyboard shortcut to select launch tasks:
- Open the keyboard shortcuts settings (cmd+k cmd+s on Mac, ctrl+k ctrl+s on other OSes)
- Search for
workbench.action.debug.selectandstart - Click the + button to add your preferred keybinding keybinding
Enketo Express needs an OpenRosa-compliant server to obtain forms from and submit data to. For development you can use any public or local server.
For example to use your https://kobotoolbox.org or https://ona.io account "ali", the server_url to use in API calls is "https://kc.kobotoolbox.org/ali" or "https://ona.io/ali".
An API call to get the Enketo webform url for a form called "TestForm" can be made like this:
curl --user enketorules: -d "server_url=https://kc.kobotoolbox.org/ali&form_id=TestForm" http://localhost:8005/api/v2/survey
Once you have the Enketo webform URL can start development on a feature or bug.
Another convenient way for some subset of development work is to put your XForm on any webserver (local, public), and use a preview url with a query parameter, e.g.:
http://localhost:8005/preview?xform=http://example.org/myform.xml (officially, the query parameter should be URL encoded, though for development use this is often fine).
Enketo uses the npm debug module. All debug statements are prefixed with enketo: and will not appear unless the environment variable is set. To enable debugging logs for enketo specifically, set DEBUG as follows:
export DEBUG=enketo*Enketo Express includes a number of customization and extension points. See tutorials for details, especially on themes and widgets.
The user interface was translated by: Oleg Zhyliak (Ukrainian), Karol Kozyra (Swedish), Badisches Rotes Kreuz (German), Serkan Tümbaş (Turkish), Hélène Martin (French), Gurjot Sidhu (Hindi, Panjabi), "Abcmen" (Turkish), Otto Saldadze, Makhare Atchaidze, David Sichinava, Elene Ergeshidze (Georgian), Nancy Shapsough (Arabic), Noel O'Boyle (French), Miguel Moreno (Spanish), Tortue Torche (French), Bekim Kajtazi (Albanian), Marc Kreidler (German), Darío Hereñú (Spanish), Viktor S. (Russian), Alexander Torrado Leon (Spanish), Peter Smith (Portugese, Spanish), Przemysław Gumułka (Polish), Niklas Ljungkvist, Sid Patel (Swedish), Katri Jalava (Finnish), Francesc Garre (Spanish), Sounay Phothisane (Lao), Linxin Guo (Chinese), Emmanuel Jean, Renaud Gaudin (French), Trần Quý Phi (Vietnamese), Reza Doosti, Hossein Azad, Davood Mottalee (Persian), Tomas Skripcak (Slovak, Czech, German), Daniela Baldova (Czech), Robert Michael Lundin (Norwegian), Margaret Ndisha, Charles Mutisya (Swahili), Panzero Mauro (Italian), Gabriel Kreindler (Romanian), Jason Reeder, Omar Nazar, Sara Sameer, David Gessel (Arabic), Tino Kreutzer (German), Wasilis Mandratzis-Walz (German, Greek), Luis Molina (Spanish), Martijn van de Rijdt (Dutch).
Join the project on Transifex to contribute!
The development of this application is now led by ODK and funded by customers of the ODK Cloud hosted service.
Past funders include KoBo Toolbox (Harvard Humanitarian Initiative), iMMAP, OpenClinica, London School of Hygiene and Tropical Medicine, DIAL Open Source Center and Enketo LLC. Also see Enketo Core sponsors.