This repository contains the proposed FHIR API for use in the OpenCRVS system. It is a work in progress and will continue to evolve, however, it has reached a level of maturity.
It describes both the sub-set of the FHIR RESTful API that is used (along with a few custom endpoint) as well as the some FHIR templates that map out the data needed for CRVS birth and death events.
There are two methods to submit a CRVS event to the system. One using the MHD profile for FHIR and simpler method where FHIR documents are posted directly to the FHIR API.
Using this option you can submit the FHIR document (E.g. fhir-document.jsonc template) directly to the /fhir
endpoint and it will be processed in the same way as the MHD document below, except document manifests and document references aren't created and a full binary copy of the submitted document isn't captured for record keeping. This method is useful for a simpler integration where the additional metadata and standardization that the MHD profile provides isn't necessary.
Using this option a new event can be sent by submitting a FHIR MHD transaction bundle (this conforms to the Mobile Health Document profile by IHE) to Hearth containing 3 things along with some optional resources:
- The document manifest - describes the purpose of the document and it's context (links to patient, practitioner etc)
- The document reference (referenced by the document manifest) - describes where to find the document, the
content.attachment.url
property will reference the binary reference below - The Binary resource (referenced by the document reference)
- Any other resources that are referenced in the bundle link patient
The binary resource will contain a base64 encoded version of the fhir-document.jsonc template depending on the event we are sending. It also contains references to related resources from the document manifest like patient and encounter.
Hearth will process FHIR document submitted both by the MHD methods and the direct submission method and it will store the individual resources listed in those documents individually. Those resources are then available using normal FHIR queries and update operations.
Below we explore the type of data we need to store for each type of event and how they map to FHIR resources. The templates in this repository then expands on this to show how they may be constructed.
This is used to notify the OpenCRVS system that a birth (or death) has occurred and it should be followed up on. This information is not considered formal and is just used to report enough information (such as contact details and location) so they event can be followed up by a CRVS official.
Data captured:
- Notification type
- Contact details
- Basic demographics details
- Location
This is represented as a FHIR document of type Birth Notification with the following sections:
- Patient resource for mother details (minimal)
- Patient resource for father details (optional)
- Location (optional)
See fhir-document.jsonc template for a template.
This is used to formally declare that a birth event has taken place and is used by certified applications that are allowed to submit such a declaration. This starts the process for formal registration of the event. The event will move through a few stages being being fully registered and certified. There stages are declaration, verification, registration and certification. Certification is where the physical certificate is actually produced.
Data captured:
- Registration type
- All demographics of the child
- Location
- Particular form fields and observation about the event
- Scans of original forms necessary for registration
This is represented as a FHIR document of type Birth Registration with the following sections:
- Patient resource for mother details
- Patient resource for father details (optional)
- Patient resource for child/ren details
- Encounter w/ Location and Observations for clinical form fields from the birth encounter
- DocumentReference resources for scanned images/pdfs
See fhir-document.jsonc template for the template.
Authentication and Authorization for the API is done via JWTs. For external system interfacing with OpenCRVS a JWT token will be issued manually for your application. To use the token each HTTP request made to the API must include the token in it's Authorization
header along with the prefix bearer
for token type:
Authorization: bearer <token>
This token will contain restrictions to which endpoints a system can access which the API will enforce.
- Submit notification
POST fhir/
- with a direct FHIR Document or a FHIR MHD transaction bundle
- returns FHIR operation outcome
- Query pending notifications at a particular location
GET fhir/Composition?entry=Location/<id>&type=birth-notification
- return a Bundle of Compositions (This links to the other resources in the notification and those can be fetched using
GET fhir/<resourceType>/<id>
)
- Update notification resources
PUT fhir/<resourceType>/<id>
- with the updated resource details
- return 200
- Submit preliminary registration
POST /fhir
- with a direct FHIR Document or a FHIR MHD transaction bundle
- returns FHIR operation outcome
- Note: This will additionally create a default task resource to track the progress of the registration if one doesn't exist.
- Query registration list
GET fhir/Composition?type=birth-registration
- return Bundle of Composition (This links to the other resources in the registration and those can be fetched using
GET fhir/<resourceType>/<id>
)
- Query registration details
GET fhir/Composition/<id>
- return Bundle of Composition (This links to the other resources in the registration and those can be fetched using
GET fhir/<resourceType>/<id>
)
- Query registration progress
GET fhir/Task?focus=Composition/<id>
- return Task resource
- Query registration progress full history
GET fhir/Task?focus=Composition/<id>/_history
- return FHIR history bundle resource
- Update registration resources
PUT fhir/<resourceType>/<id>
- with the updated resource details
- return 200
- Transition/Update registration state
PUT fhir/Task/<id>
- with the updated resource details
- return 200
- Note: This is to transition tasks between the states 'declared', 'verified' 'registered' and 'certified'.
TODO: Add to GraphQL
- Generate certificate
GET api/certificate/<compositionId>
- return FHIR Binary resource with image or pdf content
- Check payment received
GET api/payment/<compositionId>
- return payment details, TBD
OpenCRVS uses a GraphQL API to make calling these FHIR endpoint easier for the frontend web app. This is only to be used by the official OpenCRVS we app. The following is a mapping between the GraphQL queries and mutations from the frontend webapp to corresponding FHIR endpoints.
- createNotification(details: NotificationInput!): Notification!
- Submit notification -
POST /fhir
- Submit notification -
- voidNotification(id: ID!): Notification
GET fhir/Composition/<id>
DELETE fhir/<resourceType>/<id>
for all resources referenced in composition
- listNotifications(locationIds: [String], status: String, userId: String, from: Date, to: Date): [Notification]
- Query pending notifications at a particular location -
GET fhir/Composition?
- Query pending notifications at a particular location -
- listBirthRegistrations(locationIds: [String], status: String, userId: String, from: Date, to: Date): [BirthRegistration]
- Query registration list -
GET fhir/Composition?
- Query registration list -
- listDeathRegistrations(locationIds: [String], status: String, userId: String, from: Date, to: Date): [BirthRegistration]
- Query registration list -
GET fhir/Composition?
- Query registration list -
- createBirthRegistration(details: BirthRegistrationInput!): ID!
- Submit preliminary registration -
POST /fhir
- Submit preliminary registration -
- updateBirthRegistration(id: ID!, details: BirthRegistrationInput!): BirthRegistration!
- Update registration resources - For each resource updated:
PUT fhir/<resourceType>/<id>
- Update registration resources - For each resource updated:
- markBirthAsVerified(id: ID!, location: LocationInput): BirthRegistration
- Transition registration state -
PUT fhir/Task
- Transition registration state -
- markBirthAsRegistered(id: ID!, location: LocationInput): BirthRegistration
- Transition registration state -
PUT fhir/Task
- Transition registration state -
- markBirthAsCertified(id: ID!, location: LocationInput): BirthRegistration
- Transition registration state -
PUT fhir/Task
- Transition registration state -
- markBirthAsVoided(id: ID!, reason: String!, location: LocationInput): BirthRegistration
- Transition registration state -
PUT fhir/Task
GET fhir/Composition/<id>
DELETE fhir/<resourceType>/<id>
for all resources referenced in composition
- Transition registration state -
- createDeathRegistration(details: DeathRegistrationInput!): ID!
- Submit preliminary registration -
POST /fhir
- Submit preliminary registration -
- updateDeathRegistration(id: ID!, details: DeathRegistrationInput!): DeathRegistration!
- Update registration resources - For each resource updated:
PUT fhir/<resourceType>/<id>
- Update registration resources - For each resource updated:
- markDeathAsVerified(id: ID!, location: LocationInput): DeathRegistration
- Transition registration state -
PUT fhir/Task
- Transition registration state -
- markDeathAsRegistered(id: ID!, location: LocationInput): DeathRegistration
- Transition registration state -
PUT fhir/Task
- Transition registration state -
- markDeathAsCertified(id: ID!, location: LocationInput): DeathRegistration
- Transition registration state -
PUT fhir/Task
- Transition registration state -
- markDeathAsVoided(id: ID!, reason: String!, location: LocationInput): DeathRegistration
- Transition registration state -
PUT fhir/Task
GET fhir/Composition/<id>
DELETE fhir/<resourceType>/<id>
for all resources referenced in composition
- Transition registration state -
- user(id: Int!): User
- role(id: Int!): [UserRole]
There are a few bash scripts to demonstrate the sending some of the templates. To run these you need to have node.js installed and have installed the following global dependency: npm install --global strip-json-comments-cli
.
Each of the script accepts the server to query as the first commandline argument, otherwise they default to the staging server (http://opencrvs-staging.jembi.org:5001
). E.g.
./find-composition.sh http://localhost:5001