An example configuration for OpenCRVS using a fictional country
Report an issue · Join our community · Read our documentation · www.opencrvs.org
- What is this module for?
- How do I run the module alongside the OpenCRVS core?
- What is in the Farajaland configuration module repository?
This is the fictional country "Farajaland" OpenCRVS country configuration repository for OpenCRVS You must fork this for your own country.
Read our documentation to learn how to set up your own country configuration using this repo as an example.
This is an example country configuration package for the OpenCRVS core. OpenCRVS requires a country configuration in order to run.
OpenCRVS is designed to be highly configurable for your country needs. It achieves this by loading reference data that it needs from this module.
This module also provides a logical location where you may wish to store the code and run the servers for any custom API integrations, extension modules and innovations to OpenCRVS.
- Ensure that you are running OpenCRVS Core.
If you successfully ran the bash setup.sh script in OpenCRVS Core you already have this module checked out, the dependencies are installed, the Farajaland database is populated and you can just run the following command.
yarn dev <!-- PATH_TO_OPEN_CRVS_CORE_DIRECTORY -->You can find out "PATH_TO_OPEN_CRVS_CORE_DIRECTORY" by runningpwdin your opencrvs-core directory.
Thats it! 🎉
If you did not run the OpenCRVS Core bash setup.sh command, or you are forking this repository in order to build your own country configuration.
- Ensure that you are running OpenCRVS Core.
In a separate Terminal window, checkout this repository and checkout the master branch. The develop branch is used for active feature development.
- Run
git clone https://github.com/opencrvs/opencrvs-farajaland.git - Run
cd opencrvs-farajaland - Run
git checkout master - Run
yarn install - Run
yarn dev <!-- PATH_TO_OPEN_CRVS_CORE_DIRECTORY -->You can find out "PATH_TO_OPEN_CRVS_CORE_DIRECTORY" by runningpwdin your opencrvs-core directory.
One of the key dependencies and enablers for OpenCRVS is country configuration and a reference data source. This source is bespoke for every implementing nation. If you would like to create your own country implementation, we recommend that you duplicate this repository and use it as a template. So what does it contain?
- On the root level, this repository contains:
-
Cypress end-to-end tests that can be run in continuous integration.
-
Docker Compose environment variables. Secrets required for your external API integrations unique to your country. Examples include: SMS gateway provider selection between Clickatell & Infobip
-
Backups (Backup zips of default reference data for a nation, for a factory reset, clean installation or for local development purposes.)
- The src folder contians the code required to run the configuration server and endpoints for receiving configuration values. It also contains a handler to receive health notifications from an optional DHIS2 instance. It contains a "validate" webhook handler where you can integrate with an external system when OpenHIM recieves a registration. A K6 data-generator example is included that populates a demo environment with example registrations so you can see what performance analytics look like at scale.
Required endpoints that CANNOT be changed:
- JS configuration settings files that the clients require in order to initialise, set up languages, track any errors and find essential services.
GET /login-config.js
GET /client-config.js
- An endpoint for loading country configuration content such as languages.
GET /content/{application}
- An endpoint for loading country administrative location data for offline use in the OpenCRVS web client. This is reference data for states, districts and any other kind of administrative boundary. This data has been previously populated into Hearth and linked to facilities and employees following the steps later in this README.
GET /locations
- An endpoint for loading country civil registation and health facility data for offline use in the OpenCRVS web client. This is reference data for the buildings where civil registration occurs and where births and deaths happen in the health context. This data has been previously populated into Hearth and linked to administrative locations and employees following the steps later in this README.
GET /facilities
- An endpoint for loading country specific public assets e.g. logos
GET /definitions/{declaration}
- An endpoint that can be used to pilot OpenCRVS alongside an exsting Civil Registration system. This is an optional configuration for OpenCRVS. OpenCRVS validates its own registration data and creates its own independent and official registration identifiers "Birth/Death Registration Numbers (BRN, DRN)". But you may wish to pilot OpenCRVS and add an additional layer of 3rd party validation. If you use this feature, then the following endpoint should perform the validation tasks you need and return your own BRN/DRN
POST /validate/registration
- Another endpoint that can be used to pilot OpenCRVS alongside an exsting Civil Registration system to generate numbers without the validation step. This is an optional configuration for OpenCRVS. OpenCRVS creates its own independent and official registration identifiers "Birth/Death Registration Numbers (BRN, DRN)". But you may wish to pilot OpenCRVS and generate the official registrations somewhere else. If you use this feature, then the following endpoint should perform whatever tasks you need and return your own BRN/DRN
POST /generate/{type e.g. <brn|drn>}
The features folder, contains the scripts needed to populate OpenCRVS databases with reference data when creating a new country config installataion and backup
Read our documentation in order to learn how to make your own country configuration!