Develop mapping configs¶
The mapping_configs repo contains the mapping rules for transforming data from GameBus format to FHIR (R4) format. The mapping rules are implemented using the domain specific language Google Whistle language.
This section will show you how to develop new mapping rules.
Note
You don’t need to run a FHIR server to develop mapping rules.
Set up dev environment¶
Step 1. Build mapping engine
This step is similar to the section “Build mapping engine”, but it is not going to build a C shared library. Instead, we just need to build an executable from the Go source code.
First, install the following dependencies
Golang (>=1.7)
Java JDK (>= 8)
Protobuf Compiler protoc (>= 3.11.4)
Clang (>= 11.0.1-2)
Second, clone mapping engine codebase
git clone https://github.com/nwo-strap/healthcare-data-harmonizationLastly, build it
cd healthcare-data-harmonization ./build_all.shThe executable
healthcare-data-harmonization/mapping_engine/main/main
will be generated. Check if it exists.
Step 2. Clone mapping_configs repo
git clone https://github.com/nwo-strap/mapping_configs.gitLet’s call the path of this clone repo
MAPPING_CONFIG_PATH
, e.g./home/mapping_configs
.
Develop new mapping rules¶
The mapping_configs repo has a structure like this:
mapping_configs
├── LICENSE
├── README.md
└── gamebus_fhir_r4 # mapping rules for GameBus to FHIR R4
├── README.md
├── projector_library
│ ├── datatypes.wstl # You can find what GameBus data types are supported in "Property_ValueX" function
│ └── resources.wstl # You can find what FHIR resources are supported here
├── code_harmonization
│ ├── Activity2Resource.harmonization.json # You can find what GameBus activity types are supported here
│ ├── Gender.harmonization.json
│ ├── ObservationCategory.harmonization.json
│ ├── ObservationCode.harmonization.json
│ ├── ObservationComponentCode.harmonization.json # You can find what GameBus property types are supported here
│ └── Unit.harmonization.json # You can find what GameBus units are supported here
├── configurations
│ ├── activity.textproto
│ ├── activity.wstl
│ ├── player.textproto
│ └── player.wstl
└── example
├── gb_bp.json
├── gb_location.json
├── gb_player.json
├── gb_run.json
└── output
├── gb_bp.output.json
├── gb_location.output.json
├── gb_player.output.json
└── gb_run.output.json
Current mapping rules support the following:
- FHIR (R4) resources:
Patient
,Observation
andLocation
Better to double check the file
projector_library/resources.wstl
for all supported resources.
- GameBus data types (i.e.
property.inputType
): INT
,STRING
,BOOL
,DOUBLE
,DISTANCE
,DURATION
,COORDINATE
andDATE
.Better to double check the function
Property_ValueX
in the fileprojector_library/datatypes.wstl
for all supported data types.
- GameBus data types (i.e.
- GameBus activity types (i.e.
gameDescriptor.translationKey
): Check the file
Activity2Resource.harmonization.json
- GameBus activity types (i.e.
- GameBus property types (i.e.
property.translationKey
): Check the file
ObservationComponentCode.harmonization.json
- GameBus property types (i.e.
Depending on whether you need new FHIR resources or not, the development process will be different. We will discuss the two different scenarios in the following sections.
To work with mapping rules, you need to be familiar with the Google Whistle language. Here are some resources for you to get started:
Scenario 1: Using existing FHIR resources¶
In this scenario, you want to transform GameBus data to FHIR resources that are already supported,
e.g. Patient
, Observation
and Location
.
The workflow of developing new mapping rules is as follows:
Check if the data types of the GameBus data are supported. If not, you need to update the function Property_ValueX in the file
projector_library/datatypes.wstl
.Use the excel-to-fhir tool to generate the harmonization files for new GameBus activities, properties and/or units. Then you need to update the corresponding harmonization files in the folder
code_harmonization
.
That is all you need to do to develop new mapping rules in this scenario. Go next sections to see how to run and validate the mapping rules.
Scenario 2: Requiring new FHIR resources¶
In this scenario, you need to transform GameBus data to FHIR resources than the current ones, e.g. Device.
Here is the workflow of developing new mapping rules:
Check if the data types of the GameBus data are supported. If not, you need to update the function Property_ValueX in the file
projector_library/datatypes.wstl
.Use the excel-to-fhir tool to generate the harmonization files for new GameBus activities, properties and/or units. Then you need to update the corresponding harmonization files in the folder
code_harmonization
.Update the file
projector_library/resources.wstl
to add the new FHIR resource. You may also need to update the fileprojector_library/datatypes.wstl
to add some new functions.
After finishing the above steps, you can run and validate the mapping rules as described in the next sections.
Note
When you add new FHIR resources in mapping rules, you also need to update the FHIR server to support the new resources to make the whole system work properly. For more details, check next part.
Run the mapping¶
To run the mapping rules, you need to do the following:
Update all
local_path
variables inmapping_configs/gamebus_fhir_r4/configurations/*.textproto
files.If the path of the cloned repo (your
MAPPING_CONFIG_PATH
) is/mapping_configs
, you don’t need to do anything; Otherwise, you MUST update alllocal_path
with the absolute path.Run mapping
Use the following commands to convert GameBus player data to FHIR
Patient
:cd mapping_configs [BASE_PATH]/healthcare-data-harmonization/mapping_engine/main/main \ -data_harmonization_config_file_spec=./gamebus_fhir_r4/configurations/player.textproto \ -input_file_spec=./gamebus_fhir_r4/example/gb_player.json -output_dir=.
The
[BASE_PATH]
is the path to the mapping engine repo, replace it with real value.-data_harmonization_config_file_spec
sets which mapping config file to use. Take a look at all config files and try others for different types of input.-input_file_spec
sets the path to the input JSON file.-output_dir
sets the path to the output directory,
The output file is
./gb_player.output.json
, which is named based on the name of the input file.Use the following command to convert GameBus
RUN
data to FHIRObservation
:cd mapping_configs [BASE_PATH]/healthcare-data-harmonization/mapping_engine/main/main \ -data_harmonization_config_file_spec=./gamebus_fhir_r4/configurations/activity.textproto \ -input_file_spec=./gamebus_fhir_r4/example/gb_run.json -output_dir=.
The output file is
./gb_run.output.json
.Try other GameBus example data, you can find reference output files in the folder
gamebus_fhir_r4/example/output
.
Validate FHIR data¶
To make sure the mapping output conforms to FHIR (R4) specification, you can use the fhir-validator-app or its free service to validate the results. What you need to do is just to paste the content of the mapping output to the app or service. The app or service will tell you if the content is valid or not; if not valid, it will give you the error message.