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. 

What You'll Learn

In this topic, you will learn how to:

• Access the Syntactic Mapping Page
• Reviewing and Editing a Syntactic Mapping
• Create a new Syntactic Mapping version

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.

Reviewing and Editing the Syntactic Mapping

1. Click on the syntactic mapping you'd like to review or edit in the Syntactic Mappings page.The Edit Syntactic Mapping page appears.

2. 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.
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 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.
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 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.

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.

• 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.

1. In the Syntactic Mapping page, click the New Version button of the Syntactic Mapping you want to create a new version of.

2. The Create New Syntactic Mapping Version page appears.

4. 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.
5. The description can be updated. Update it to indicate changes, if desired.
6. Update the source data schemas if needed. For more information on how to do this, see the Creating a Syntactic Mapping article.
7. 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.
8. Click the Create New Version button. The new version of the syntactic mapping appears on the Syntactic Mappings page.

Next Steps

• Syntactic Mapping Transformations
• Running a Data Harmonization Code Object

Related Articles

• Creating a Syntactic Mapping
• Syntactic Mapping Transformations
• Removing a Syntactic Mapping
• Working with Syntactic Mapping Configurations in JSON format