Skip to main content

Creating a Syntactic Mapping

This topic explains how to create a syntactic mapping. Syntactic Mappings are used as part of the Harmonization Copilot, 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. 

What You'll Learn

In this topic, you will learn how to:

  • Access the Syntactic Mappings Page
  • Create a Syntactic Mapping
  • Review and Edit a Syntactic Mapping

Access the Syntactic Mappings Page 

To access 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.  

datamappings.png

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.

  1. In the Syntactic Mappings page, select Create Syntactic Mapping.
  2. The Create Syntactic Mapping page appears.

createasyntacticmapping.png

  1. Enter the name of the syntactic mapping.
  2. Optionally, enter the description of the syntactic mapping.
  3. Select the Target Data Model from the drop down menu.
  4. 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 (supported for the OMOP v5.4 target data model), 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. 
    manuallyconfigure.png

    - To upload a configuration from a file (supported for all target data models), click Upload from File, then click either drag and drop a JSON file into the shaded area or select Browse to select a JSON file from your computer.
    configurefromfile.pngconfigurefromfile2.png
  5. Click Create Syntactic Mapping.
  6. Your new mapping appears in the Data Mapping page under the Syntactic Mappings tab.

 

Reviewing and Editing the Syntactic Mapping

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.

syntacticmappingfields.png

    1. 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.
    2. 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.
    3. 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.
    4. 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.

 

Next Steps

Related Articles

Was this article helpful?