Bahmni-SNOMED TS Integration Local Installation Guide (using docker)

We highly recommend going through this page to understand different features available with SNOMED Integration before proceeding for the setup

This page contains the steps to setup SNOMED enabled integration of Bahmni with SNOMED Terminology Server over FHIR in local machine

Pre-requisite

Docker should be up and running with docker compose installed.
SNOMED RF2 File. You can get this from SNOMED International. This is a licensed file and cannot be shared across.

Steps

Checkout bahmni-docker repository
git clone https://github.com/Bahmni/bahmni-docker.git

You can choose to run either Bahmni Lite or Bahmni Standard. There are two terminology server options: SNOWSTORM (External SNOMED Server) and SNOWSTORM LITE (Micro FHIR Server)

Using SNOWSTORM Lite (bundled with docker compose):
Bahmni Docker Compose configuration bundled SNOWSTORM Lite service which is a lightweight terminology server. Read more about it here.
1. Go to bahmni-lite or bahmni-standard subfolder. For example: cd bahmni-standard.
2. Update the value of COMPOSE_PROFILES environment variable in .env file. You can add snowstorm-lite,cdss if you want to use SNOWSTORM Lite and CDSS features or only add snowstorm-lite. For example: COMPOSE_PROFILES=emr,snowstorm-lite,cdss .
3. Update the location of your RF2 File in the SNOWSTORM_RF2_FILE_PATH environment variable in the .env file. Then uncomment the volume in load-snowstorm-lite-data service to mount the RF2 file for initialisation
4. Update the Admin password for Snowstorm Lite server by changing the value of SNOWSTORM_LITE_ADMIN_PASSWORD environment variable in .env file
5. Now you can bring up the services by either using the run-bahmni.sh script or docker compose up -d command. The initial import of RF2 takes around 10mins to complete.
Using External SNOWSTORM Server:
You can setup your own standard version of SNOWSTORM server or use an external SNOMED terminology server with Bahmni. Instructions on setting up SNOWSTORM server can be found here. Once you have the terminology server up and running, follow the steps below to use the external terminology server.
1. Go to bahmni-clinic or bahmni-standard subfolder. For example: cd bahmni-standard.
2. If you want to use the CDSS feature, add cdss profile to the COMPOSE_PROFILES variable in the .env file. Example: COMPOSE_PROFILES=emr, cdss
3. Update the value of TERMINOLOGY_SERVER_URL variable in the .env file with the URL of the external terminology server.
4. Also set the value of ICD10_LITE_INDICATOR to false.
5. Now you can bring up the services by either using the run-bahmni.sh script or docker compose up -d command.

4. Go to browser, and hit https://localhost.

5. List of Global properties to be updated - Under OpenMRS → Administation → Settings, lookup for below properties, and update the values as required

Mandatory Properties to be looked at:

	Global Property Name	Description	Example

	Global Property Name	Description	Example
1	bahmni.lookupExternalTerminologyServer	Boolean property to determine whether external terminology server is being used or not	true
2	cdss.enable	Boolean Property used to determine whether CDSS being used or not (Requires CDSS profile to be enabled)	true
3	ts.fhir.baseurl	Base URL of the terminology server	Defaults to Snowstorm Lite: http://snowstorm-lite:8080/fhir/ Update with external terminology server URL (Example: https://snowstorm.snomed.mybahmni.in/fhir/ )

Other Properties available with default values:

1	ts.fhir.valueset.urltemplate	Valueset URL template for FHIR terminology server	ValueSet/$expand?url={0}&filter={1}&count={2}&displayLanguage={3}&includeDesignations={4}
2	ts.fhir.diagnosissearch.valueseturl	Valueset URL for Diagnosis Search on terminology server	http://snomed.info/sct?fhir_vs=ecl/<404684003 i.e includes subset of Clinical finding (finding)
3	ts.fhir.conceptDetailsUrl	URL template pattern for fetching concept details from terminology server	http://snomed.info/sct?fhir_vs=ecl/{0}
4	ts.fhir.diagnosiscount.valueseturl	Valueset URL for Diagnosis Count on terminology server	http://snomed.info/sct?fhir_vs=ecl/<<
5	ts.fhir.diagnosiscount.valueset.urltemplate	Valueset URL template for Diagnosis Count Reports	ValueSet/$expand?url={0}{1}&displayLanguage={2}&count={3,number,#}&offset={4,number,#}
6	ts.fhir.observation.valueset.urltemplate	Valueset URL template for Observation on terminology server	ValueSet/$expand?url={0}&displayLanguage={1}&_format={2}&filter={3}&count={4}
7	ts.fhir.procedure.valueset.urltemplate	URL template pattern for fetching valueset for procedure details from terminology server	http://bahmni.org/fhir/ValueSet/
8	cdss.fhir.baseurl	Base URL for CDSS service	http://cdss:8080/cds-services
9	fhir.export.anonymise.config.path	Path of the config file that controls the anonymisation mechanism during bulk-export of patient data	/openmrs/data/fhir-export-anonymise-config.json see this page for more details

To upload procedures in Bahmni, please follow steps mentioned here
There are also snomed specific configuration docker images published which has pre-configured forms and reports which uses SNOMED Terminology server integrations. If you want to try out with those config images, update the value of CONFIG_IMAGE_TAG to snomed-latest in the .env file.

Creation of Custom ValueSets:

In some cases, there could be a need to create a custom ValueSet for a curated set of answers for a concept when designing a form. Snowstorm APIs allows creation and management of ValueSets using REST APIs. Postman Collection can be found here.

As an example, the SNOMED CoVID form shipped out-of-the-box in config needs three custom ValueSets to be manually created. http://bahmni.org/fhir/ValueSet/bahmni-valueset-covid,http://bahmni.org/fhir/ValueSet/bahmni-valueset-hospitalisation,http://bahmni.org/fhir/ValueSet/bahmni-valueset-symptoms. A POST request needs to be made to https://<SNOWSTORM_URL>/fhir/ValueSet with the Payload below to create the ValueSets. Also CURL commands are added which can be used to create the ValuseSets by running them directly inside the snowstorm-lite container.

{
    "resourceType": "ValueSet",
    "url": "http://bahmni.org/fhir/ValueSet/bahmni-valueset-covid",
    "version": "0.1",
    "name": "bahmni-valueset-covid",
    "description": "Bahmni Valueset for CoVID",
    "status": "draft",
    "experimental": true,
    "compose": {
        "include": [
            {
                "system": "http://snomed.info/sct",
                "concept": [
                    {
                        "code": "1240581000000104"
                    },
                    {
                        "code": "1240591000000102"
                    }
                ]
            }
        ]
    }
}

CURL Command that can be executed inside snoswtorm-lite container. Remember to replace password in the --user argument.

curl --location 'http://localhost:8080/fhir/ValueSet' --user admin:Admin123 -X POST --header 'Content-Type: application/json' --data '{
    "resourceType": "ValueSet",
    "url": "http://bahmni.org/fhir/ValueSet/bahmni-valueset-covid",
    "version": "0.1",
    "name": "bahmni-valueset-covid",
    "description": "Bahmni Valueset for CoVID",
    "status": "draft",
    "experimental": true,
    "compose": {
        "include": [
            {
                "system": "http://snomed.info/sct",
                "concept": [
                    {
                        "code": "1240581000000104"
                    },
                    {
                        "code": "1240591000000102"
                    }
                ]
            }
        ]
    }
}'

{
    "resourceType": "ValueSet",
    "url": "http://bahmni.org/fhir/ValueSet/bahmni-valueset-hospitalisation",
    "version": "0.1",
    "name": "bahmni-valueset-hospitalisation",
    "description": "Bahmni Valueset for Hospitalisation",
    "status": "draft",
    "experimental": true,
    "compose": {
        "include": [
            {
                "system": "http://snomed.info/sct",
                "concept": [
                    {
                        "code": "707852009"
                    },
                    {
                        "code": "707851002"
                    }
                ]
            }
        ]
    }
}

CURL Command that can be executed inside snoswtorm-lite container. Remember to replace password in the --user argument.

curl --location 'http://localhost:8080/fhir/ValueSet' --user admin:Admin123 -X POST --header 'Content-Type: application/json' --data '{
    "resourceType": "ValueSet",
    "url": "http://bahmni.org/fhir/ValueSet/bahmni-valueset-hospitalisation",
    "version": "0.1",
    "name": "bahmni-valueset-hospitalisation",
    "description": "Bahmni Valueset for Hospitalisation",
    "status": "draft",
    "experimental": true,
    "compose": {
        "include": [
            {
                "system": "http://snomed.info/sct",
                "concept": [
                    {
                        "code": "707852009"
                    },
                    {
                        "code": "707851002"
                    }
                ]
            }
        ]
    }
}'

{
    "resourceType": "ValueSet",
    "url": "http://bahmni.org/fhir/ValueSet/bahmni-valueset-symptoms",
    "version": "0.1",
    "name": "bahmni-valueset-symptoms",
    "description": "Bahmni Valueset for Covid Symptoms",
    "status": "draft",
    "experimental": true,
    "compose": {
        "include": [
            {
                "system": "http://snomed.info/sct",
                "concept": [
                    {
                        "code": "84387000"
                    },
                    {
                        "code": "82272006"
                    },
                    {
                        "code": "38666106"
                    },
                    {
                        "code": "79890006"
                    },
                    {
                        "code": "44169009"
                    },
                    {
                        "code": "36955009"
                    },
                    {
                        "code": "162397003"
                    },
                    {
                        "code": "29857009"
                    },
                    {
                        "code": "21522001"
                    },
                    {
                        "code": "131148009"
                    },
                    {
                        "code": "49727002"
                    },
                    {
                        "code": "84229001"
                    },
                    {
                        "code": "25064002"
                    }
                ]
            }
        ]
    }
}

CURL Command that can be executed inside snoswtorm-lite container. Remember to replace password in the --user argument.

curl --location 'http://localhost:8080/fhir/ValueSet' --user admin:Admin123 -X POST --header 'Content-Type: application/json' --data '{
    "resourceType": "ValueSet",
    "url": "http://bahmni.org/fhir/ValueSet/bahmni-valueset-symptoms",
    "version": "0.1",
    "name": "bahmni-valueset-symptoms",
    "description": "Bahmni Valueset for Covid Symptoms",
    "status": "draft",
    "experimental": true,
    "compose": {
        "include": [
            {
                "system": "http://snomed.info/sct",
                "concept": [
                    {
                        "code": "84387000"
                    },
                    {
                        "code": "82272006"
                    },
                    {
                        "code": "38666106"
                    },
                    {
                        "code": "79890006"
                    },
                    {
                        "code": "44169009"
                    },
                    {
                        "code": "36955009"
                    },
                    {
                        "code": "162397003"
                    },
                    {
                        "code": "29857009"
                    },
                    {
                        "code": "21522001"
                    },
                    {
                        "code": "131148009"
                    },
                    {
                        "code": "49727002"
                    },
                    {
                        "code": "84229001"
                    },
                    {
                        "code": "25064002"
                    }
                ]
            }
        ]
    }
}'

Known Issues with SNOMED CLINIC CONFIGURATION

For any concept supporting multiple languages, the form builder report displays all the languages against the corresponding concept. For more details, refer to this link
'Procedure Orders' concept is not automatically added as set member under 'All Orderables' after SNOMED CLINIC deployment. As a workaround 'Procedure Orders' needs to be manually added as set member under 'All Orderables' using OpenMRS concept dictionary. For more details refer to this link

Known Issues with SNOMED STANDARD CONFIGURATION

The Patient Identifier (GAN) needs to be updated in OpenMRS with Max Length of 14. This will allow new patients to be created in Bahmni.

Known Issues common to CLINIC and STANDARD CONFIGURATION

The concept ‘Procedure Orders’ need to be edited under OpenMRS and the checkbox of the ‘Is Set’ field should be checked. This will allow Bahmni to add procedures, once uploaded.