OpenSRP Document Configurability

Owned by Ephraim Kigamba
Last updated: Aug 12, 2020
4 min read

Contents

  1. Purpose

  2. Setup

  3. How it works

  4. Technical Details for Developers

Purpose

High level goal - The goal of OpenSRP document configurability is to move OpenSRP towards the product direction whereby we would have one APK for different deployments, countries and use-cases. However, these implementations would have different configurations eg. forms, views & models.

Other goal - The goal of OpenSRP document configurability is to come up with a structure for moving implementation-specific features to configuration files & then moving these files to the server so that any update of the implementation-specific features can be done remotely from the server.

Implementation-specific features are:

  • Add, update or remove form questions

  • Edit label on form questions

  • Add or update constraints, validations on current form questions

  • Model changes that enable processing of data from new form questions

    • This would enable you to show new questions from the form

  • View changes

    • Button font, color, size, position & label changes

    • Client profile changes

    • Register view changes

    • menu changes

eg. 2 OpenSRP apps might fundamentally function the same but have different themes based on client preferences. These two apps might also have different questions or use different languages due to the nature of implementation requirements.

Currently, to provide an update of implementation-specific features you need to make the changes in the code ,generate an APK & upload this to PlayStore where the update will be reviewed. The client needs to be notified of the application update and perform a complete download of the APK before the update is performed.

With document configurability, there would be one codebase that can serve multiple implementations by the change of the configurations to fit the expectation.

Setup

Server-setup

Document configurability is enabled by default on the opensrp-web-server repository. The server can store and provide any of the configurations documents by default.

  1. Deploy OpenSRP server version >= v2.1.12

  2. Deploy OpenSRP web version >= v0.1.4

Client-setup:

  1. Make sure you are using opensrp-client-core version >= v1.12.0-SNASPHOT

  2. Make sure you are using opensrp-client-native-form version >= v.1.13.1-SNAPSHOT

  3. Add the following code to the last line in your Application.onCreate method

    NativeFormLibrary .getInstance() .setClientFormDao(CoreLibrary.getInstance().context().getClientFormRepository());

  4. Change any references, extensions and manifest declarations of com.vijay.jsonwizard.activities.JsonFormActivity to com.vijay.jsonwizard.activities.FormConfigurationJsonFormActivity

    1. Change the AndroidManifest.xml declaration of the JsonFormActivity to FormConfigurationJsonFormActivity

    2. Change any startActivity and startActivityForResult methods to use FormConfigurationJsonFormActivity instead of JsonFormActivity as the target activity

    3. Replace parent activities from JsonFormActivity to FormConfigurationJsonFormActivity in the activities which extend JsonFormActivity

  5. Add the following lines to your AppJobCreator#onCreate method to make the DocumentConfigurationServiceJob available

    case DocumentConfigurationServiceJob.TAG: return new DocumentConfigurationServiceJob(DocumentConfigurationIntentService.class);

  6. Schedule the DocumentConfigurationServiceJob to run every 15 minutes by adding the following line to LoginInteractor#scheduleJobsPeriodically

    DocumentConfigurationServiceJob .scheduleJob(DocumentConfigurationServiceJob.TAG , TimeUnit.MINUTES.toMillis(BuildConfig.CLIENT_SETTINGS_SYNC_MINUTES) , getFlexValue(BuildConfig.CLIENT_SETTINGS_SYNC_MINUTES));

  7. Create the ClientFormRepository and ManifestRepositoryby adding the create statements in the ApplicationRepository eg. ANCRepository or add the create statements as migrations. To create the tables, add the following statements

  8. Add the forms sync to the immediate sync call. This function enables forms sync to happen when the user clicks on the Sync button

  9. When opening forms, use com.vijay.jsonwizard.utils.FormUtils#getFormJsonFromRepositoryOrAssets method to fetch the JSON form. The rules & other assets required when loading the form are handled by the FormConfigurationJsonFormActivity

  10. Make an initial upload of the form files:

    1. Clone this repo github.com/OpenSRP/opensrp-server-web

    2. Change client project assets folder path in the configuration file named doc_config_script_configs.properties

    3. Change the server url & authentication credentials in the configuration file named doc_config_script_configs.properties

    4. Change the appId and appVersion values in the configuration file named doc_config_script_configs.properties

    5. Run the main method in InitialFormConfigUploadUtil.java file

    6. Check the output for any failures. Increment the formVersion and repeat in case of any failures

How it works

  1. Changes to the form eg. child_enrollment.json, disease_effects.json are made and tested

  2. Create a Manifest in json form with the package name, app version & forms version as below

The identifier should be the version of the Manifest and uniquely identify this Manifest

3. Upload the manifest to the rest/manifest endpoint as described here

4. Upload the form(s) that has changed

 

Technical Details & How to use it

These are the technical details

 

Server side APIs

 

1. Manifest Endpoint

rest/manifest

  • GET request - Returns all the manifests available on the server

  • POST request with the following application/json body - Publish a new manifest to the server

    • Returns 201 when successful

  • GET request at endpoint rest/manifest/search with params

    • app_id - (Required) The app package name eg. org.smartregister.chw

    • app_version - (Required) The application version name eg. 0.0.1

Returns a 200 with the latest manifest of the app or 404 if no manifest is found

 

2. Client Form endpoint

rest/clientForm

  • POST with the following multi-part params

    • form_version (Required) The semantic version of the form

    • form_identifier (Required) The unique identifier of the form eg. en/json.form/maternity/enrollment.json

    • form_name (Required) The title or label of the form eg. Child Registration

    • form (File, Required) The actual json form file

    • module (Optional) The parent module of the form eg. Child, Immunization

Returns a 201 when successful

 

  • GET request with params

    • form_version (Required) The semantic version of the form

    • form_identifier (Required) The unique identifier of the form eg. en/json.form/maternity/enrollment.json

    • current_form_version (Optional) The current form version on the client app

 

Client side APIs

Coming soon. This work is under development

Assumptions

Coming soon.

Questions

  • Are the uploaded forms stored as files on the server? No, they are currently stored on the database server as JSON

  •  

How to customise for your project

Coming soon