> For the complete documentation index, see [llms.txt](https://docs.rhinofcp.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rhinofcp.com/data-harmonization/creating-editing-and-removing-a-syntactic-mapping.md).
# Creating, Editing, and Removing a Syntactic Mapping
## 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.
### Open the Syntactic Mappings Page
To open the Syntactic Mappings page, do the following.
Select Data Mappings from the main menu.
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.
| Button or Field | Description |
| --------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Create Syntactic Mapping | Click this button to create a new syntactic mapping. |
| New version | Click this button to create a new version of an existing syntactic mapping. |
| Syntactic Mapping Name | Name of the mapping. |
| Version | Indicates the version of the Syntactic Mapping. The first version of a Syntactic Mapping is the number 0. |
| Information icon (on hover) | Displays additional information about the syntactic mapping, such as the description provided during creation of the syntactic mapping. |
| Date Created | Indicates the date the syntactic mapping was created. |
| Target Data Model | Indicates the target data model for the mapping, such as OMOP v5.4. |
| Source Data Schemas | Indicates the source data schemas of the datasets that you would like to map. If there is more than one, the number of source schemas will appear (e.g. “3 Schemas”). If there is more than one schema, hover to see the names of the schemas. |
| Target Tables | Indicates the target tables for the transformation. If there is more than one, the number of target tables will appear (e.g. "2 Tables"). If there is more than one table, hover to see the names of the tables. |
| Creator | Name of the person who created the syntactic mapping. |
| 3 Dot Menu
| The three dot menu (also known as the "context menu") provides access to additional options: Copy UID, Show Configuration, Download Mapping Config, and Remove Syntactic Mapping. |
### Creating a Syntactic Mapping
To create a syntactic mapping, complete the following steps.
{% stepper %}
{% step %}
#### Enter the mapping details
In the Syntactic Mappings page, select Create Syntactic Mapping.
The Create Syntactic Mapping page appears.
Enter the name of the syntactic mapping.
Optionally, enter the description of the syntactic mapping.
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.
{% endstep %}
{% step %}
#### Choose how to create the configuration
You can either create the configuration in the UI or upload a configuration from a file (in JSON format).
{% tabs %}
{% tab title="Manually Configure" %}
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*. For more information on these tables, see [this link](https://simplifier.net/hdp-il).
{% endtab %}
{% tab title="Upload from File" %}
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.
{% endtab %}
{% endtabs %}
{% endstep %}
{% step %}
#### Create the mapping
Click Create Syntactic Mapping.
Your new mapping appears in the Data Mapping page under the Syntactic Mappings tab.
{% endstep %}
{% endstepper %}
### 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.
{% stepper %}
{% step %}
#### Open the mapping
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.
{% endstep %}
{% step %}
#### Review the target fields
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.
{% endstep %}
{% step %}
#### Map source fields
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.
{% endstep %}
{% step %}
#### Edit transformations
You can edit the transformations each target field by clicking the pencil icon in the Transformations column.
{% endstep %}
{% step %}
#### Save your work
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.
{% endstep %}
{% endstepper %}
## 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.
{% stepper %}
{% step %}
#### Review the fields
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.
{% endstep %}
{% step %}
#### Generate recommendations
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.
{% endstep %}
{% step %}
#### Review the AI output
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.
{% endstep %}
{% step %}
#### Handle errors
When AI fails to generate relevant recommendation, an error message appears on the corresponding row.
{% endstep %}
{% step %}
#### Make manual changes
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.
{% endstep %}
{% step %}
#### Review transformations
Review and address transformations as well.
{% endstep %}
{% step %}
#### Regenerate if needed
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.
{% endstep %}
{% endstepper %}
{% hint style="warning" %}
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.
{% endhint %}
## Editing a Syntactic Mapping
This topic explains how to edit 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) 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.
* The syntactic mapping you want to edit must exist.
### Open the Syntactic Mappings Page
To open the Syntactic Mappings page, do the following.
{% stepper %}
{% step %}
#### Select Data Mappings
Select Data Mappings from the main menu.
{% endstep %}
{% step %}
#### Open Syntactic Mappings
In the Data Mappings page, select Syntactic Mappings.
{% endstep %}
{% endstepper %}
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.
| Button or Field | Description |
| --------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Create Syntactic Mapping | Click this button to create a new syntactic mapping. |
| New version | Click this button to create a new version of an existing syntactic mapping. |
| Syntactic Mapping Name | Name of the mapping. |
| Version | Indicates the version of the Syntactic Mapping. The first version of a Syntactic Mapping is the number 0. |
| Information icon (on hover) | Displays additional information about the syntactic mapping, such as the description provided during creation of the syntactic mapping. |
| Date Created | Indicates the date the syntactic mapping was created. |
| Target Data Model | Indicates the target data model for the mapping, such as OMOP v5.4. |
| Source Data Schemas | Indicates the source data schemas of the datasets that you would like to map. If there is more than one, the number of source schemas will appear (e.g. “3 Schemas”). If there is more than one schema, hover to see the names of the schemas. |
| Target Tables | Indicates the target tables for the transformation. If there is more than one, the number of target tables will appear (e.g. "2 Tables"). If there is more than one table, hover to see the names of the tables. |
| Creator | Name of the person who created the syntactic mapping. |
| 3 Dot Menu
| The three dot menu (also known as the "context menu") provides access to additional options: Copy UID, Show Configuration, Download Mapping Config, and Remove Syntactic Mapping. |
## Reviewing and Editing the Syntactic Mapping
{% stepper %}
{% step %}
#### Open the mapping
Click on the syntactic mapping you'd like to review or edit in the Syntactic Mappings page. The Edit Syntactic Mapping page appears.
{% endstep %}
{% step %}
#### Review target fields
All of the target tables for the syntactic mapping along with their fields appear in the Target Field column. A red asterisk indicates that the target field is required.
{% endstep %}
{% step %}
#### Map source fields
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 of the 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.
{% endstep %}
{% step %}
#### Edit transformations
You can edit the transformations each target field by clicking the pencil icon in the Transformations column.
{% endstep %}
{% step %}
#### Save your work
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 Data Harmonization Code Object that references a Syntactic Mapping, it can no longer be edited (in order to ensure reproducibility), and you can create a new version of the Syntactic Mapping to continue editing it.
{% endstep %}
{% endstepper %}
## Creating a New Syntactic Mapping Version
Before you create a new version, it is helpful to understand that when a new version is created, the system uses the most recent existing version of the same Syntactic Mapping for preservation. The following table shows the schema change and the user interface behavior in the new version.
| Field | Description |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| Schema Change | User Interface Behavior in the New Mapping Version |
| Unchanged Target or Source Fields | Previously defined Source Fields and Transformations are preserved. You can edit preserved mappings as needed. |
| New Target Fields | Appear as empty, editable rows in the Syntactic Mapping panel, ready for you to define a new mapping. |
| New Source Fields | Become available in the Source Field selection dropdowns. |
| Deleted or Renamed Target Fields | Corresponding mapping rows are removed and will not be displayed in the new version. |
| Deleted Source Fields | Mappings referencing these fields are cleared, and the affected rows will appear empty and editable if the Target Field still exists. |
* **Preservation Logic:** Mappings are preserved only when the Target Field exists in the new Target Schema version AND all referenced Source Fields exist in the new Source Schema version.
* **Matching:** Field preservation requires an exact match on the field name.
* **Scope:** Preservation applies only within the same Syntactic Mapping object; it does not support copying mappings between different mapping objects.
* **No Automatic Remapping:** No automatic or heuristic remapping is performed for renamed fields. If a field is renamed, the mapping is cleared or removed, ensuring you explicitly review and redefine any mappings where schema semantics have changed.
To create a new syntactic mapping version do the following.
{% stepper %}
{% step %}
#### Open the new version flow
In the Syntactic Mapping page, click the New Version button of the Syntactic Mapping you want to create a new version of.
{% endstep %}
{% step %}
#### Review the version details
The Create New Syntactic Mapping Version page appears.
{% endstep %}
{% step %}
#### Keep required fields unchanged
The name and target data model cannot be changed - they must be consistent for all versions of the same Syntactic Mapping. If you would like to select a different name or target data model, you can create a new Syntactic Mapping instead of creating a new version.
{% endstep %}
{% step %}
#### Update the description
The description can be updated. Update it to indicate changes, if desired.
{% endstep %}
{% step %}
#### Update source data schemas
Update the source data schemas if needed. For more information on how to do this, see the Creating a Syntactic Mapping article.
{% endstep %}
{% step %}
#### Update target tables
To streamline data harmonization when Source and Target Schemas evolve (e.g., due to regulatory updates or new source data), Syntactic Mapping definitions are automatically preserved. This feature allows you to focus only on mapping new or changed fields (schema deltas) without redoing your completed work. Update the target tables if needed. For more information on how to do this, see the Creating a Syntactic Mapping article.
{% endstep %}
{% step %}
#### Create the new version
Click the Create New Version button. The new version of the syntactic mapping appears on the Syntactic Mappings page.
{% endstep %}
{% endstepper %}
## Removing a Syntactic Mapping
This topic explains how to remove a syntactic mapping.
### Prerequisites
* You must have Manage Data Mappings permission.
* A syntactic mapping must exist.
### 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.
| Button or Field | Description |
| --------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Create Syntactic Mapping | Click this button to create a new syntactic mapping. |
| New version | Click this button to create a new version of an existing syntactic mapping. |
| Syntactic Mapping Name | Name of the mapping. |
| Version | Indicates the version of the Syntactic Mapping. The first version of a Syntactic Mapping is the number 0. |
| Information icon (on hover) | Displays additional information about the syntactic mapping, such as the description provided during creation of the syntactic mapping. |
| Date Created | Indicates the date the syntactic mapping was created. |
| Target Data Model | Indicates the target data model for the mapping, such as OMOP v5.4. |
| Source Data Schemas | Indicates the source data schemas of the datasets that you would like to map. If there is more than one, the number of source schemas will appear (e.g. “3 Schemas”). If there is more than one schema, hover to see the names of the schemas. |
| Target Tables | Indicates the target tables for the transformation. If there is more than one, the number of target tables will appear (e.g. "2 Tables"). If there is more than one table, hover to see the names of the tables. |
| Creator | Name of the person who created the syntactic mapping. |
| 3 Dot Menu
| The three dot menu (also known as the "context menu") provides access to additional options: Copy UID, Show Configuration, Download Mapping Config, and Remove Syntactic Mapping. |
### Removing the Syntactic Mapping
To remove a Syntactic Mapping, complete the following steps.
{% stepper %}
{% step %}
#### Select the mapping you want to remove
In the Syntactic Mapping page, select the three-dot menu for version of the syntactic mapping you want to remove.
{% endstep %}
{% step %}
#### Select the option to remove syntactic mapping
Select “Remove syntactic mapping”. A message appears indicating that the mapping has been removed.
{% endstep %}
{% endstepper %}