Skip to main content


An OpenSRP application needs configurations to work properly. These configurations are used to define application workflows (or events), user interface content, which user interface component to display and which data (FHIR Resources) to load.

OpenSRP configs are represented using two types of FHIR resources (Composition and Binary) which are stored in JSON format. A Binary resource can contain any content including custom JSONs modeled for OpenSRP's use case. These Binary resources are referenced in the Composition resource sections; each Binary resource representing a valid configuration. A Composition section can nested in other sections; commonly used to group related configs.

A Composition resource acts as the application config manifest. It MUST have a unique identifier to differentiate the application from the rest of the applications sharing the same server.

Configuration Types

OpenSRP supports the following types of configurations:

Config typeFunctionCardinality
compositionUniquely identifiers the application. References other configurations1..1
applicationProvides application level configurations e.g. languages used in the app, title of the app1..1
navigationConfigures the app's navigation side menu (drawer). e.g. how many registers to display1..1
registerConfigures a register (what resources to use, which views to render etc)1..*
profileConfigures a profile (what resources to use and how the views are to be rendered)1..*
syncConfigures the resources to be synced to and from the server1..1
geoWidgetConfigures the geowidget map view1..*
measureReportConfigures the various measure report indicators used in the app1..1

NOTE: Cardinality chart: 1..1 ( only one required); 1..* (can be multiple); 0..1 (optional)

Config Conventions

  • Config attributes and types should be in camelCase e.g. application.deviceToDeviceSync
  • Some config values are expected to be enum classes constants. They MUST be provided in UPPER_SNAKE_CASE e.g the valid ServiceStatus values include: DUE, OVERDUE, UPCOMING and COMPLETED
  • Computed configuration values use @{placeholder} format to reference the name of the computed rule. The placeholder will be replaced with an actual value at runtime.


  1. How do I come up with a name for the app id: app Ids should be short, human readable and easy to remember. Different application should not share the same app id. Examples of good app Ids: quest, g6pd etc. You can derive an app Id after the name of the client project.

  2. Can I share configurations between two apps?: yes and no. Yes when the configs are available in the same server. This is however not recommended


  • Missing Resource - Check whether the referenced Binary resource exists in the server. Could be a typo in the Composition resource or you forgot include the Binary resource to the Composition section.
  • Error loading configuration. Details : Key application is missing in the map - Composition resource for the given application ID is missing