19.0.1Semantic Standardization Module

Experimental

19.0.1.3.1Web Admin Console Configuration

1. Navigate to Configuration → Module Config 2. Select Add Module dropdown 3. Choose Semantic Standardization 4. Select target Node 5. Click Add

19.0.1.3.1.1Configuration Parameters

19.0.1.3.2Property-Based Configuration

if you are running in node.propertysource=PROPERTIES mode, you would add the following line to your cdr-config-Master.properties file:

module.[MODULE_ID].config.base_url=http://localhost:8080
module.[MODULE_ID].config.min_confidence=0.85
module.[MODULE_ID].config.fhir_version=R4

19.0.1.4.1Configuration Structure

19.0.1.4.1.1Root Level

{
  "description": "Configuration description",
  "version": "1.0.0", 
  "fhirVersion": "4.0.1",
  "resourceMappings": []
}

The description, version and fhirVersion are currently only provided of the file creator/maintainer.

19.0.1.4.1.2Resource Mapping

The resourceMapping is a JSON array that allows configuration specific to each FHIR Resource.

The resourceMapping has two main component the resourceType and the codeableConceptMapping

• resourceType is a FHIR resource type. Condition as an example
• codeableConceptMapping is an Array for additional configuration discussed below

{
  "resourceType": "Condition",
  "codeableConceptMapping": []
}

19.0.1.4.1.3CodeableConcept Mapping

The codeableConceptMapping is a JSON array that allows configuration specific to each FHIR Resource

• fhirPath is a FHIRPath. code as an example
• targetOntologyUrl is the url of the standard ontology. http://snomed.info/sct as an example
• correctCode is a boolean flag that will direct the system to correct code values is true
• correctDisplay is a boolean flag that will direct the system to correct display values if true
• translate is a boolean flag that will direct the system to add codings from the Code system referenced in the targetOntologyUrl if true
• textToCoding is a boolean flag that will evaluate the text and display elements of the CodeableConcept to add codings if true

The flags provide fine grain control over actions taken by Semantic Standardization module

{
  "fhirPath": "code",
  "targetOntologyUrl": "http://snomed.info/sct",
  "correctCode": true,
  "correctDisplay": true,
  "translate": true,
  "textToCoding": true
}

19.0.1.4.2Example Configuration

This example configuration can be used as a starting point for an implementation and referenced in the module configuration

• File Path to JSON mapping file (Advanced)

{
	"description": "Configuration for mapping FHIR resources to their respective CodeableConcepts using FHIRPath. Each potential path is explicitly paired with a target terminology URL and processing options",
	"version": "1.0.0",
	"fhirVersion": "4.0.1",
	"resourceMappings": [
		{
			"resourceType": "AdverseEvent",
			"codeableConceptMapping": [
				{ "fhirPath": "substance.code", "targetOntologyUrl": "http://snomed.info/sct", "correctCode": false, "correctDisplay": false, "translate": false, "textToCoding": false }
			]
		},
		{
			"resourceType": "AllergyIntolerance",
			"codeableConceptMapping": [
				{ "fhirPath": "code", "targetOntologyUrl": "http://snomed.info/sct", "correctCode": true, "correctDisplay": true, "translate": true, "textToCoding": true }
			]
		},
		{
			"resourceType": "Condition",
			"codeableConceptMapping": [
				{ "fhirPath": "code", "targetOntologyUrl": "http://snomed.info/sct", "correctCode": true, "correctDisplay": true, "translate": true, "textToCoding": true }
			]
		},
		{
			"resourceType": "Device",
			"codeableConceptMapping": [
				{ "fhirPath": "type", "targetOntologyUrl": "http://snomed.info/sct", "correctCode": true, "correctDisplay": true, "translate": true, "textToCoding": true }
			]
		},
		{
			"resourceType": "Immunization",
			"codeableConceptMapping": [
				{ "fhirPath": "vaccineCode", "targetOntologyUrl": "http://hl7.org/fhir/sid/cvx", "correctCode": true, "correctDisplay": true, "translate": true, "textToCoding": true }
			]
		},
		{
			"resourceType": "MedicationAdministration",
			"codeableConceptMapping": [
				{ "fhirPath": "medication.as(CodeableConcept)", "targetOntologyUrl": "http://www.nlm.nih.gov/research/umls/rxnorm", "correctCode": true, "correctDisplay": true, "translate": true, "textToCoding": true }
			]
		},
		{
			"resourceType": "MedicationDispense",
			"codeableConceptMapping": [
				{ "fhirPath": "medication.as(CodeableConcept)", "targetOntologyUrl": "http://www.nlm.nih.gov/research/umls/rxnorm", "correctCode": true, "correctDisplay": true, "translate": true, "textToCoding": true }
			]
		},
		{
			"resourceType": "MedicationRequest",
			"codeableConceptMapping": [
				{ "fhirPath": "medication.as(CodeableConcept)", "targetOntologyUrl": "http://www.nlm.nih.gov/research/umls/rxnorm", "correctCode": true, "correctDisplay": true, "translate": true, "textToCoding": true }
			]
		},
		{
			"resourceType": "MedicationStatement",
			"codeableConceptMapping": [
				{ "fhirPath": "medication.as(CodeableConcept)", "targetOntologyUrl": "http://www.nlm.nih.gov/research/umls/rxnorm", "correctCode": true, "correctDisplay": true, "translate": true, "textToCoding": true }
			]
		},
		{
			"resourceType": "Observation",
			"codeableConceptMapping": [
				{ "fhirPath": "code", "targetOntologyUrl": "http://loinc.org", "correctCode": true, "correctDisplay": true, "translate": true, "textToCoding": true }
			]
		},
		{
			"resourceType": "Procedure",
			"codeableConceptMapping": [
				{ "fhirPath": "code", "targetOntologyUrl": "http://snomed.info/sct", "correctCode": true, "correctDisplay": true, "translate": true, "textToCoding": true }
			]
		},
		{
			"resourceType": "Substance",
			"codeableConceptMapping": [
				{ "fhirPath": "code", "targetOntologyUrl": "http://snomed.info/sct", "correctCode": true, "correctDisplay": true, "translate": true, "textToCoding": true }
			]
		}
	]
}

19.0.1.5.1$semantic-uplift Operation

The module provides a $semantic-uplift operation for on-demand semantic enhancement of FHIR resources.

19.0.1.5.1.1Usage

POST [base]/[ResourceType]/$semantic-uplift

The operation processes the resource(s) according to the configured mapping rules and returns semantically enhanced versions.

19.0.1.9.1Common Issues

Module fails to start

• Verify terminology provider URL is accessible
• Check network connectivity to external services
• Review configuration syntax in mapping JSON

Poor mapping quality

• Adjust confidence level threshold
• Review terminology provider configuration
• Validate input data quality

Performance issues

• Enable result caching
• Increase network timeouts
• Consider batch processing for large volumes