Server Setup Steps

From an app point of view, the following steps need to be run on server instance.

Note : These steps should be done after the DHIS and metadata setup is done.

1. Setup metadata sync

Zebra uses Metadata Sync App to sync events between EIDSR instance and Zebra instance. Install latest metadata sync app in EIDSR instance. Download the installation zip metadata-synchronization.zip (or whichever is the latest release)

The EBS and IBS tracker programs in EIDSR instance is mapped to Zebra Alerts in Zebra instance.

1. Instance white listing

In the EIDSR Instance, go to system settings app Go to "Access" menu on left nav bar Add "https://metadata.eyeseetea.com" to the CORS whitelist

2. Add instance settings

In the EIDSR Instance, go to Metadata Sync app Go to "Instance Settings" Add new instance Add Zebra instance settings. The following is the example for dev instance setup. Change the URL and credentials to UAT/Prod accordingly.

3. Add instance settings

In the EIDSR Instance, go to Metadata Sync app

Go to "Instance Settings"

Select Zebra Instance and click on "Metadata Mapping"

You can manually map each program, program stage, TEA, Data Element, Option from EIDSR to Zebra OR

The following json contains the mapping for dev. The ids of program, program stage, TEA, Data Element, Option should be same between dev and UAT/Prod instances. Find the appropriate mapping key in datastore(metadata-synchronization/mappings-) and replace the json.

metadata-mappings.json

4. Create a Sync rule

In the EIDSR Instance, go to Metadata Sync app Go to Events Sync --> Sync Rules Add new sync rule Fill in the steps of sync rule to sync EBS and IBS tracker programs. Refer to following sync rule in dev : https://dev.eidsr.znphi.co.zm/api/apps/MetaData-Synchronization/index.html#/sync-rules/events/edit/x3N2xyDt804

5. Setup metadata sync Scheduler

Download metadata-synchronization-server.zip from https://cloud.eyeseetea.com/index.php/s/2sT2HNGjRy64E3W

Unzip metadata-synchronization-server.zip

cd metadata-synchronization-server

Copy app-config.json from https://cloud.eyeseetea.com/index.php/s/JJjZH7EnBRnPFBT to metadata-synchronization-server folder. Make appropriate changes to app-config.json for UAT/Prod Url and credentials.

node index.js -c app-config.json

We need to ensure that the Scheduler auto-starts and is always running on the server. In order to achieve this, at EyeSeeTea we use the Supervisor app instances which run the Scheduler. If you already use this or some other app to achieve something similar, please add Scheduler to the list. If you need further assistance on configuring the Supervisor app, please let us know.

2. Mapping Scheduler script setup

Zebra uses an independent script to map Zebra Events Trackers to Alerts. This script is also responsible to send notifications to Zebra users on creation of Zebra alerts. Run the following steps to setup the script on Zebra UAT/Prod instance.

git clone [email protected]:EyeSeeTea/zebra-dev.git

cd zebra-dev

yarn install

copy .env file with zebra credentials to zebra-dev folder

yarn script-map-outbreak-to-alerts

Once the script works, this needs to be run every 2 hours on the server by setting up a cron job.

3. Maps

1. Make sure that the org units have the geometry imported as well

2. Import or create if not available the legend needed for Dashboard and Event Tracker page maps

RTSL_ZEB_LEG_DASHBOARD_ACTIVE_VERIFIED

RTSL_ZEB_LEG_EVENT_TRACKER_CASES

3. Import maps or create if not available in core Maps app (not custom) the maps needed:

Event tracker Alerts: # of Cases (RTSL_ZEBRA_ALERTS program)

Dashboard: # of active verified (RTSL_ZEBRA_ALERTS program)

4. Make sure in datastore we have inside zebra:

• key maps-config: where we need the corresponding mapId for each map page, the programId and programName, the startDate if there is no duration filter applied (it will go from this start date to current date), and the timeFiled which is used to know which field to target when filtering by duration.

For checking the mapId go to core Maps app --> File --> Open --> Choose Dashboard or Event tracker map --> check in the URL the Id. programId will be the id of program RTSL_ZEBRA_ALERTS and programName has to be directly RTSL_ZEBRA_ALERTS (or the corresponding code of RTSL_ZEBRA_ALERTS in the instance)

{
  "dashboard": {
    "currentPage": "DASHBOARD",
    "mapId": "",
    "programId": "",
    "programName": "RTSL_ZEBRA_ALERTS",
    "startDate": "2000-01-01",
    "timeField": "ENROLLMENT_DATE"
  },
  "event_tracker": {
    "currentPage": "EVENT_TRACKER",
    "mapId": "",
    "programId": "",
    "programName": "RTSL_ZEBRA_ALERTS",
    "startDate": "2000-01-01",
    "timeField": "EVENT_DATE"
  }
}

• key active-verified-alerts-program-indicators: indicators used in Dashboard map (RTSL_ZEBRA_ALERTS program). disease, hazardType, incidentStatus should be the values selected in the filters of the page or ALL if apply to all and null if it does not apply, id is the id of the program indicator and name could appear in the map popup.

Here you can find an example without the id that you can check in datastore of dev instance or in the excel of program indicators:

example-active-verified-alerts-program-indicators.json

[
  {
    "disease": "ALL",
    "hazardType": "ALL",
    "id": "",
    "incidentStatus": "ALL",
    "name": "Number of active verified"
  },
  {
    "disease": "ALL",
    "hazardType": "ALL",
    "id": "",
    "incidentStatus": "Watch",
    "name": "Number of active verified - Watch"
  },
...
]

• key cases-alerts-program-indicators: program indicators used in Event tracker map (RTSL_ZEBRA_ALERTS program). disease, hazardType, incidentStatus and should be the code in the option set or ALL if apply to all and null if it does not apply, id is the id of the program indicator and name could appear in the map popup

Here you can find an example without the id that you can check in datastore of dev instance or in the excel of program indicators:

example-cases-alerts-program-indicators.json

[
  {
    "disease": "ALL",
    "hazardType": "ALL",
    "id": "",
    "incidentStatus": "ALL",
    "name": "Number of Cases"
  },
  {
    "disease": "RTSL_ZEB_OS_DISEASE_ACUTE_RESPIRATORY",
    "hazardType": null,
    "id": "",
    "incidentStatus": null,
    "name": "Number of Cases - Acute respiratory"
  }
...
]

5. Now for Custom Maps app:

The repository is https://github.com/EyeSeeTea/maps-app

⚠️ The Custom Maps App (core app) of Zebra instance has version 1.23.16, hence in the repo there is a branch version-1.23.16 to work with this version. From this version branch there is a branch called version-1.23.16-zebra that is the one used in ZEBRA project to build Zebra custom DHIS2 Maps App, so this branch never has to be removed or merged

Make sure to merge all PRs to have all the features you need for maps-app into version-1.23.16-zebra branch

Build in this branch the app:

1. Add in package.json in build script the corresponding DHIS2_BASE_URL and save
2. run yarn install
3. run yarn build
4. You will get the zebra-custom-maps-app.zip

Remove old verion in the instance and install zebra-custom-maps-app.zip (sometimes after this, you have to empty cache and hard reload in browser)

Test in ZEBRA App if everything is well installed. If not check if you have all changes in version-1.23.16-zebra branch and if the DHIS2_BASE_URL is the correct one. Also check all datastore configurations are ok.

4. DHIS Configurations

Install Zebra App

Setup continuous analytics every 5 mins

Setup default starting page as Zebra app.

Charts and Cards setup - ensure that all keys present in Zebra dev instance datastore, are migrated to prod instance.

5. Testing