Creating a Syntactic Mapping

This topic explains how to create a syntactic mapping. Syntactic Mappings are used as part of the Rhino Data Harmonization Engine (RhinoDHE), and streamline the process of mapping your local data to a target data model, like Observational Medical Outcomes Partnership (OMOP), FHIR R4 IL Core or FHIR R4 IL HDP, or a custom data model.

Prerequisites 

• You must have Manage Data Mappings permission. 
• The dataset that you want to harmonize must have been imported into FCP. 

What You'll Learn

In this topic, you will learn how to:

• Open the Syntactic Mappings Page
• Create a Syntactic Mapping
• Manually Define Mappings 
• Auto-Generate Mapping Recommendations by AI  
• Review and Edit a Syntactic Mapping

Open the Syntactic Mappings Page 

To open the Syntactic Mappings page, do the following.

1. Select Data Mappings from the main menu.
2. In the Data Mappings page, select Syntactic Mappings.

The Syntactic Mappings page shows syntactic mappings that have been created. To search for a syntactic mapping, use the Seach Syntactic Mapping text box located at the top right corner of the page. 

The fields in the screenshot above are defined in the table below.

Creating a Syntactic Mapping

To create a syntactic mapping, complete the following steps.

1. In the Syntactic Mappings page, select Create Syntactic Mapping.
2. The Create Syntactic Mapping page appears.
   
3. Enter the name of the syntactic mapping.
4. Optionally, enter the description of the syntactic mapping.
5. Select the Target Data Model from the drop down menu.  If you selected FHIR R4, a second drop down menu "Target Data Model Version" will appear with options for FHIR R4 IL Core and FHIR R4 IL HDP.  Note that you can also use the Custom option to create a syntactic mapping with FHIR R4 as the target.  The only difference between the Custom and FHIR R4 options that the Syntactic Mapping will be tagged as FHIR R4 in Rhino, which makes it easier to locate. 
6. You can either create the configuration in the UI or upload a configuration from a file (in JSON format).
   • To create the configuration in the UI, click Manually Configure, then select the source data schema(s) from the drop-down menu under Source Data Schemas. You can select more than one. Next, select the Target Table(s) from the drop down menu. You can select more than one.  
   • For FHIR R4 IL HDP, there are 20 tables (also called profiles) available: IL Core Device, IL Core Encounter, IL Core Immunization, IL Core Procedure, IL HDP Allergy Intolerance, IL HDP  Condition, IL HDP Device Dispense, IL HDP Device Request, IL HDP Document Reference, IL HDP Medication, IL HDP Medication Administration, IL HDP Medication Dispense, IL HDP Medication Request, IL HDP Medication Statement, IL HDP Observation Lab, IL HDP Organization, IL HDP Patient, IL HDP Practitioner, IL HDP Service Request, IL HDP Vital Signs.
     
   • To upload a configuration from a file (supported for all target data models), click Upload from File, then click or drag and drop a JSON file into the shaded area or select Browse to select a JSON file from your computer.  When uploaded, the name of the file appears.
     
     
     
7. Click Create Syntactic Mapping.
8. Your new mapping appears in the Data Mapping page under the Syntactic Mappings tab.

Manually Define Mappings 

Once you have created the syntactic mapping, you can review and edit the mapping from source to target fields, and their associated transformations.

1. Click on the syntactic mapping in the Syntactic Mappings page. If you created a new syntactic mapping and selected to manually configure it in the UI, then you will automatically be brought to this page for your new syntactic mapping. The Edit Syntactic Mapping page appears.
2. All target tables for the syntactic mapping and their fields appear in the Target Field column. A red asterisk indicates that the target field is required.  
3. For each target field, you can select one or more source fields to map to the target field. Click on the source field dropdown and you can select fields from any input data schemas for the syntactic mapping. If you select more than one field, make sure that you select fields from the same schema, and note that you will be required to configure a transformation to define how to generate the value for the target field from the different source fields.
4. You can edit the transformations each target field by clicking the pencil icon in the Transformations column. More on this in the Syntactic Mapping Transformations topic.
5. At any time, you can click the Save button to save your work. Syntactic Mappings can be updated as you work through the different source to target field mappings and transformations. Once you run a Rhino Data Harmonization (RhinoDHE) Code Object that references a Syntactic Mapping, it can no longer be edited (to ensure reproducibility), and you can create a new version of the Syntactic Mapping to continue editing it.

Auto-Generate Mapping Recommendations by AI

Rhino FCP can auto-generate mapping recommendations and their associated transformations to speed the initial mapping process. After recommendations are made, you can review them and adjust as necessary. 

Prerequisites

• The syntactic mapping must have been generated using Custom as the target data model.
• If a Rhino Data Harmonization (RhinoDHE) Code Object references syntactic mapping, it must not have been executed (run).  If it has, the mapping can no longer be edited (to ensure reproducibility).  If that has happened, create a new version of the Syntactic Mapping to continue editing it.

Generating Recommendations

To generate recommendations, complete the following steps.

1. In the Syntactic Mappings page, the Source Fields appear in the Source Fields column.  All target tables for the syntactic mapping and their fields appear in the Target Field column. A red asterisk indicates that the target field is required.  
2. Select the "Generate Recommendations" button in the top right section of the screen to suggest source mappings for the target field automatically.  A pop up note appears in the bottom right corner of the screen indicating that recommendations are being generated.  While recommendations are being generated, you can go to other screens in Rhino FCP to work. 

3. When the recommendations have been made, review each field to determine the accuracy of each mapping. AI recommendations have icons next to them that indicates that a row was populated by AI. The icon disappears after a user edits and saves source or/ and relevant transformation. Note that some rows will be populated with recommendations, but some might not. 

   

4. When AI fails to generate relevant recommendation, an error message appears on the corresponding row. 
5. Make changes to mappings manually if needed. As you do this, click the Save button to save your work. Syntactic Mappings can be updated as you work through the different source to target field mappings and transformations.
6. Review and address transformations as well. See Syntactic Mapping Transformations article for more details about transformation types. 
7. If needed, you can choose to generate LLM recommendations again.  The fields that you already populated will remain as is and the LLM will generate recommendations for remaining fields only. 

NOTE: If you need to start all over again, select the Clear All button at the top right corner of the screen, then select Remove all Mappings in the message that appears.  If you do this, it will clear all current mappings and reset the table, so proceed with caution.  This change cannot be undone. 

Next Steps

• Editing a Syntactic Mapping
• Syntactic Mapping Transformations
• Running a Rhino Data Harmonization Engine (RhinoDHE) Code Object

Related Articles

• Syntactic Mapping Transformations
• Removing a Syntactic Mapping
• Working with Syntactic Mapping Configurations in JSON Format
• Running a Rhino Data Harmonization Engine (RhinoDHE) Code Object