Replace concept mapping and form configuration in outbound push with FHIR concepts accessible to the mediator

[andrablaj]

Is your feature request related to a problem? Please describe. cht-interoperability was primarily built to support the LTFU PoC. In order to be used by national deployments and to interoperate with existing health systems, it needs to be customized with specific mediators or FHIR resources.

Describe the solution you'd like Have a generic solution for building mediators that can be used out-of-the-box for new interoperability initiatives.

[witash]

There are some key points that a generic solution for building mediators should address:

1. Keep as much as practical as configuration in the cht config repositories, rather than code in the mediator. In particular, anything that is specific to a particular instance or workflow needs to be in configuration.
2. Have clear and limited responsibilities for mediators
3. Have the process of adding new systems be easy to document.
4. Have the process of configuring new instances and workflows be simple and easy to document. (i.e. not a lot of custom formats and configuration values)

CHT Forms should be represented as FHIR Questionnaires. Configuration in CHT should allow for marking forms as for inbound or outbound FHIR requests Then the forms should automatically (as much as possible without additional configuration) be converted to FHIR Questionnaires. For incoming requests, this allows the mediator to automatically convert FHIR resources to the CHT records API For outgoing requests, this allows the mediator to automatically convert CHT documents to FHIR resources

Reference data such as identifier types should be represented as ValueSets Systems will in general need to share additional reference data, e.g. Medic ID and OpenMRS ID for patients, CHT Visit Types for encounter, Location ID types for Mapping CHT locations to other Data sets These should be represented as FHIR ValueSet Resources; this allows their definitions to be represented as configuration instead of code, for the mediator to automatically create these on remote systems if necessary, and for identifier types specifically, to convert between identifiers automatically as needed. e.g. OpenMRS sends location with a Health Facility code, it needs to be converted to a place_id in CHT.

Mappings between fields in CHT documents should be done using concept Mappings and Questions The fields in CHT forms will often need to be represented as FHIR Observations, which requires them to have a code that is shared with the remote system, and which may not be available directly from the CHT form. Additionally the structure may need to change e.g. a field which is a yes or no question in a cht form may need to be an obersvation which is either present or absent. ConceptMappings can allow the mediator to get the shared code from CHT form fields And FHIR Questionnaires can hold the configuration necessary to convert the form fields to their corresponding Observation resources.

The remaining questions for me are how to manage urls for ValueSets correctly, if/how to use CodeSystems, if/how to use StructureDefinitions, and if/how to use any other FHIR workflow resources

[witash]

If all of the above is supported, the process for adding a new systems becomes

1. define the workflow in terms of CHT things and resources exchange. e.g. usually will want patient records to be exchanged, any restrictions on when and which ones? What CHT forms are expected to create what resources in the remote system?
2. Set up openHIM with the fhir server and the mediator from the main branch
3. add to the cht config respoistory the configuration for interop, including which forms are used, codes and mappings for form fields, url and outbound push conditions
4. run cht-config; this creates the outbound push config and sends questionnaires, conceptmappings and valuesets to the FHIR server.
5. Now, if everything is ok, you should have a fully functional FHIR conformant integration. In reality, usually it won't work right away even if everything from the CHT side is set up correctly. The remote system may not be fully FHIR conformant, or have other requirements that are not supported out of the box. In documentation we can give some examples from OpenMRS but it will be hard to predict these types of requirements in general.
6. This is where additional mediators may come in; create a branch of this repository, and new enpoints for the remote system. These endpoints are expected to send and receive valid FHIR resources to/from the CHT endpoints, but will send/receive whatever is necessary to/from the remote system. Because there is a lot of boilerplate (testing, boring server stuff, deployment) this should not be a "new" mediator, but new endpoints to the mediator in this repository

If we wanted to get very fancy, 5 and 6 are where we could use StructureDefinitions and other infrastructure resources as described here https://www.hl7.org/fhir/profiling.html to make this process more automatic and structured.