Example project for the Kairos FHIR DSL

Scope

This project contains Groovy example scripts for the use of the CentraXX FHIR custom export interface. The examples show the possibilities how to export CXX data to FHIR in accordance to almost any FHIR R4 profile. More infos about CentraXX can be found on the Kairos Website

Getting Started

A brief tutorial on how to set up and configure the FHIR custom export in CentraXX..

How-To

Detailed instructions to the interface and its DSL can be found in the German how-to.

Requirements

• To write or modify custom export scripts, it is necessary to have a very good understanding of the source and target data models to transform into each other. Therefore, it is very helpful to use the kairos-fhir-dsl library as a dependency, which contains a CentraXX JPA meta model as a source, and the FHIR R4 model as a target.
• This project uses Maven for build management to download all necessary dependencies from Maven Central or the kairos-fhir-dsl library from GitHub Packages.

GitHub Authentication with Maven

• Because GitHub does not allow downloading packages without access token, use maven with the access token in the local settings.xml in this project.

  mvn install -s settings.xml
  

• IntelliJ user can override the user settings file by File -> Settings -> Build Tools -> Maven or create own Maven run configurations. It is also possible to add it to .mvn/maven.config or to copy and past the repository authentication to another existing settings.file

• The kairos-fhir-dsl binaries before v.1.5.0 have not been published on a public maven repository yet, but can be downloaded in the assets section of the corresponding tag and installed manually.

Versioning

• The versioning of this example projects will be parallel to the kairos-fhir-dsl library, which follows Semantic Versioning.
• All Groovy example scripts will contain a @since annotation that describes the first CentraXX version, that can interpret the respective script. The specified CentraXX version contains the necessary minimal version of the kairos-fhir-dsl library, CXX entity exporter, initializer and support for the ExportResourceMappingConfig.json.
• The master branch might contain scripts, which using methods of the SNAPSHOT version of the underlying KAIROS-FHIR-DSL that has not been released yet. Please use only scripts of release tags, intended for your installed CentraXX version.

Contribution / Participation

• Everyone can fork the project.
• If you want to enrich the project with your own scripts, follow these steps:
  • Fork the project.
  • Create a new directory on your fork under src/main/groovy/projects
  • Add your new scripts.
  • Add a meaningful README.md file describing the purpose, sources, participants and CXX version.
  • Create a pull request with your changes against our master branch.
  • If possible, please follow the existing basic coding standards:
    • use 2 spaces for indent / tab size
    • use final keyword wherever possible
    • prefer explicit typization instead of the untyped def keyword
• If you discover errors or bugs in existing scripts, we would be happy to receiving a notices in the form of e-mails, issues or pull requests.

License

Copyright 2021 KAIROS GmbH

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this project except in compliance with the License. You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

SNOMED CT

This project includes SNOMED Clinical Terms® (SNOMED CT®) which is used by permission of the InternationalHealth Terminology Standards Development Organisation (IHTSDO). All rights reserved. SNOMED CT®, was originally created by The College of American Pathologists. “SNOMED” and “SNOMED CT” are registered trademarks of the IHTSDO.

Please make sure, that you have a valid SNOMED CT license, if you use example scripts with SNOMED CT concepts. SNOMED CT concepts are recognizable by the system url http://snomed.info/sct .

Example

coding {
  system = "http://snomed.info/sct"
  code = "261665006"
}

Testing

The project supports testing of scripts using context maps that represent the CXX source data and the groovy script. The CXX test data needs to be provided as a json file, that contains an array if the maps for each Instance of a CXX entity. To instantiate a Test, create a Unit test that extends AbstractExportScriptTest and annotate the test class with the @TestResource annotation. The annotation takes two arguments groovyScriptPath, and contextMapPath which are the paths to the groovy script to test and the json file with the CXX Entity map data, respectively

@TestResources(
    groovyScriptPath = "src/main/groovy/projects/mii_bielefeld/encounter.groovy",
    contextMapsPath = "src/test/resources/projects/mii_bielefeld/encounter.json"
)
class EpisodeExportScriptTest extends AbstractExportScriptTest<Encounter> {}

The AbstractExportScript test will load the context map and the groovy script and apply the script to the given map. The context map and the resulting resource are provided as argument and can be used in each test method to run assertions. For that annotate each test method with the @ExportScriptTest and declare with the method parameters like

@ExportScriptTest
  void testThatClassIsSet(final Context context, final Encounter resource) {
    Assumptions.assumeTrue(context.source[episode().stayType()] != null)

    assertTrue(resource.hasClass_())
    assertEquals("http://terminology.hl7.org/CodeSystem/v3-ActCode", resource.getClass_().getSystem())
    assertEquals(context.source[episode().stayType().code()], resource.getClass_().getCode())
  }

The test will then be run for each entry in the context map with the CXX entitiy instances.

Resource validation

Additionally the HAPI validation can be used to validate the resulting resources against certain FHIR profiles. For that, the required FHIR packages need to be provided in a separate folder. The Test can then be annotated with the @Validate annotation like:

@TestResources(
    groovyScriptPath = "src/main/groovy/projects/mii_bielefeld/encounter.groovy",
    contextMapsPath = "src/test/resources/projects/mii_bielefeld/encounter.json"
)
@Validate(packageDir = "src/test/resources/fhirpackages")
class EpisodeExportScriptTest extends AbstractExportScriptTest<Encounter> {}

The test will then load all package files from the given path an instantiate a HAPI validator. All resources that are created during the transformation, the validation will be run.

If the validation fails, the whole test will fail with a ClassConfiguration error. The validation message with errors are displayed in the stack traces.

Remember that for proper validation, you have to specify the profile a resource shall be compliant to in the meta element.

Where to get the test maps from

Currently, you would have to print the context map into the server log when testing with your local CXX/HDRP instance. For that in a script add the following line:

package projects.mii_bielefeld

import com.fasterxml.jackson.databind.ObjectMapper

condition {
  new ObjectMapper().writerWithDefaultPrettyPrinter().writeValueAsString(context.source)
}

Of course, you can also write this to a custom file in the file system, if you do not want to spam the server log.

Considerations for validation

The validation may fail, when the profiling declares fields as mandatory, which are optional in CXX and, therefore, may not be present. Here you will have to make sure that the test data in CXX is complete and compliant with the need for the FHIR profiling.