Form Configuration User Documentation
- Benjamin Mwalimu Mulyungi
Form Configuration in OpenSRP Web: User Guide
Table of Contents
Purpose of this document
Acronyms
Definitions
Background
Login to the OpenSRP server
Upload forms & any related files
Go to the drafts page to makes a release
Sync & use the form on the mobile client.
(Infrequent) Upload JSON validator files
Form Authoring Links
Purpose of this document
This document provides end-user instructions on using the form configuration work on OpenSRP web. These instructions will generally apply to all the OpenSRP web instances, however, the user will need to swap out the OpenSRP web URL with the one for their specific implementation.
Acronyms
Acronym | Description |
YAML | YAML (a recursive acronym for "YAML Ain't Markup Language") is a human-readable data-serialization language. It is commonly used for configuration files and in applications where data is being stored or transmitted. |
JSON | JavaScript Object Notation |
Definitions
Term | Description |
Manifest Release | This is a bundle of all the files uploaded together. It is used by the client application to know when new file/form bundles are available. |
JSON Validator | This is a json file with the following spec. This file is used during validation when a form is being uploaded. It mainly stores the keys of all the widgets or keys that cannot be removed for a specific file/form. |
Draft Files | These are all the files that have been uploaded to the server but have not been bundled into a release yet. |
Rules Files | These are YAML files that hold relevance, calculation, or constraint rules for specific widgets in native forms. |
Subforms | These are extra JSON files/forms apart from the primary native form JSON forms that are used to display more questions in popups. |
Property Files | These are .properties files used to enable multi-language support in native forms. |
Background
OpenSRP uses JSON forms to dynamically create native Android forms during the OpenSRP client apps runtime. These forms are used to collect data in OpenSRP. Due to the increase in OpenSRP client apps adoption, there was a need to make these JSON forms dynamic. This means that after an app release, clients could easily update the forms to add or remove widgets/questions on the JSON forms.
The following steps will show how to use OpenSRP web to upload and release new form batches. This will be covered in 5 steps:
Log in to the OpenSRP server web client
Upload forms and related files
Upload JSON validator files
Go to the drafts page to make a release
Sync and use the new form(s) on the mobile client
Log in to the OpenSRP server
Go to the server URL for your project, e.g: https://web.reveal-stage.smartregister.org, and click on the button labelled OpenSRP, then enter your username and password. Contact your project administrator for login details, if necessary.
Click the Admin menu where you will see three menu items named Manifest Releases, JSON Validators, and Draft Files. These three items are critical for uploading configurable forms. This page might be structured differently depending on your OpenSRP Web instance design, but these menu items will always be on the Admin menu.
Forms are embedded within each app release to guarantee that the business logic is consistently available for the implementation. The form configuration feature allows system administrators to update existing forms in order to allow users to collect more information or modify the existing fields in each form. Forms are uploaded in packages that we call a “Manifest Release”. System administrators can update one or many forms in a manifest. It’s important to note that these packages of forms build on each other. So, if you change the add location form and then the spray form, you need to ensure the latest manifest package includes all of the modifications for all of the previous manifest releases. We’ll get more into this in the later sections of this guide.
The JSON Validators are used to ensure that there aren’t any breaking changes per form. These are usually just uploaded once when the forms are first created in the system. Please contact a system administrator if you make a change to a form that could cause a breaking change.
The Draft Files menu item shows all files that have been uploaded in preparation to create a Manifest Release.
Upload forms & any related files
Click on the Manifest releases menu item on the images shown above to go to the Manifest releases page. This displays a list of releases that have already been made. We always want to build off of the current release. Find the most recent release and click View Files on the right column.
This page has provisions for 2 actions, viewing existing releases or uploading new files.
Click on the View Files button to go to the page that shows all the files bundled up/ uploaded for that release. This page has a table that lists the files that were bundled up as part of that specific release. It also has 2 action buttons. These are the Upload edit & Download buttons. Download a copy of each file and put them into a folder on your computer. You can make any edits to them and upload them in the make a release process. (next step)
Upload edit: - This takes you to the edit file page
This page will allow you to upload an edit of the selected file. It has all the fields disabled except the Upload files field. Click on the Choose file input field to select the edit file for upload.
Click on the upload file button to upload the file and save it as a draft.
Download button: - Click this to download the selected file for edit.
You can also upload a file that isn’t available in the latest release. You would do this if a particular form hasn’t been uploaded to an existing manifest file. Navigate to the “Manifest Releases” page and click the Upload new files button to go to the uploads page.
Fill in the given fields
Filename : - This is the human-readable name of the file to be uploaded
Module: - This is the module that the file belongs to. This mostly applies to applications with multiple modules. Examples of modules are ANC, Child, PNC
Relates to: - Denotes which file/form the file being uploaded is related to. Mostly applies when uploading Rules files, property files & subforms.
Upload file: - This is the file you wish to upload to the server.
After filling in the necessary fields click on the Upload files button. This should upload the file and save it as a draft. The form is evaluated during the upload process. The system will present a list of errors if there are errors in the validation process.
Go to the drafts page to makes a release
Click on Drafts files menu items on the Admin menu to go to the view drafts page.
This page lists all the drafts files uploaded to the server. It also offers 2 action items which are: Upload New File, Download & Make release.
Upload New File: - On clicking this button you will be taken to the new file upload page discussed above on point 2
Download: - Click this to download and view the draft file.
Make release: - Click this to make a bundled up release of all the files currently listed as draft files.
Once a release is made you are redirected to the Manifest Release page.
Sync & use the form on the mobile client.
Open your Reveal or any other OpenSRP mobile client application (Depends on which server you are using on the mobile application). Enter your username and password. Contact your project administrator for login details, if necessary
Click on the sync button if automatic sync hasn’t kicked in. The mobile application will download the new forms.
Open the form you updated. You will notice a popup notifying you that the form has new content. Press OK and continue filling your form since the new updated form is in use.
(Infrequent) Upload JSON validator files
System administrators have the capability to upload form validation logic to ensure that form editors don’t make breaking changes that lead to app crashes. This logic is defined in the “JSON Validators” section. Note that you can download a validation template within the web UI. Click on the JSON Validators menu items on the Admin Menu. This will open the view all validators pages.
This page displays the list of all JSON validators in the server. It also provides you with 3 actions, these are Upload new file, Download & Upload edit.
Upload new file: - Click this to be redirected to the Upload new validator page.
Fill in the given fields
File name : - This is the human readable name of the file to be uploaded
Module: - This is the module that the file belongs to. This mostly applies to applications with multiple modules. Examples of modules are ANC, Child, PNC
Relates to: - Denotes which file/form the file being uploaded is related to. Mostly applies when uploading Rules files, property files & subforms.
Upload file: - This is the file you wish to upload to the server.
NB: - Makes sure the JSON validator fine name is the same as the form name it needs to validate
Upload edit: - Click this to be redirected to the edit validator page.
This page will allow you to upload an edit of the selected JSON validator. It has all the fields disabled except the Upload files field. Click on the Choose file input field to select the edit file for upload.
Makes sure the JSON validator fine name is the same as the form name it needs to validate
Click on the upload file button to upload the file and save it as draft.
Download: - Click this to download the selected file for edit.
Form Authoring Links
This user guide does not cover the topic of form authoring. OpenSRP uses a JSON form standard, which is documented in the form library on GitHub. We also have the ability to test forms before you upload them through an APK.
Reveal Form JSON Folder - Each form is represented as a file. Note that country specific forms are prefixed with the country name.
Reveal Calculation and Relevance Logic - This folder contains all of the relevance rules and calculations for all forms in Reveal. These filenames are associated with the form names found in the JSON folder.
This site is no longer maintained. Please visit docs.opensrp.io for current documentation.