> 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/executing-the-transformation.md).

# Executing the Transformation

## Overview

The **Rhino Data Harmonization Engine (RhinoDHE)** automatically converts [Syntactic Mappings](/data-harmonization/syntactic-mapping.md) (and any associated [Semantic Mappings](/data-harmonization/semantic-mapping.md)) into reusable ETL workflows. These workflows run directly on your Rhino Client, in accordance with the principles of federated computing, to transform datasets from a source format into the defined target format.

**Syntactic Mappings** can be used to generate **Data Harmonization Code Objects**, which function like other Code Objects in Rhino FCP and can be executed remotely on a Rhino Client.

When a **Data Harmonization Code Object** is run, the Syntactic Mapping is applied to the input dataset, mapping source fields to target fields and applying any configured transformations. The resulting harmonized dataset is stored on the same Rhino Client and can then be used like any other dataset in Rhino FCP.

## Prerequisites

* You must have the "**Manage Data Mappings**" permission.
* You must have the "**Run Code on This Site**" permission for the site on which the harmonization is to be run.
* The datasets that you want to harmonize must have been imported into FCP.
* The [syntactic mapping](/data-harmonization/syntactic-mapping.md) you want to edit must exist.
* Any [semantic mappings](/data-harmonization/semantic-mapping.md) referenced by the syntactic mapping must exist.

## Running a Data Harmonization Code Object

{% stepper %}
{% step %}
On **Projects** page, click on the project that contains your data mappings and datasets to select it.
{% endstep %}

{% step %}
Select the **Code** option from the navigation menu on the left-hand side of the page.
{% endstep %}

{% step %}
Locate the code object for your syntactic mapping. It has the same name as the mapping and type **Data Harmonization**.

{% hint style="info" %}
A code object is *automatically generated* for each syntactic mapping created. 
{% endhint %}

![](https://content.gitbook.com/content/ydySyCBmy6F7NnGn4bPa/blobs/MOloZ6WmkB9e8a6p71VP/23456568252701)
{% endstep %}

{% step %}
Select the **Run** button to the right of the code object to open the Run Settings page.

![](https://content.gitbook.com/content/ydySyCBmy6F7NnGn4bPa/blobs/pC52AsmaOFsfkcLlAX1J/24099997741725)
{% endstep %}

{% step %}
Select the **Workgroup** on which you want to run the code object.
{% endstep %}

{% step %}
Select the **Input** datasets.

There should be one for each input data schema. 

An initial selection is already made for you, but you can change it by selecting the dataset dropdown menu and selecting a different dataset. 

If there are no datasets that match a given source data schema, the text "NO OPTIONS" will appear. In this case, please close this dialog, import a matching dataset (from the Datasets menu option on the left-hand side navigation menu), then try again.
{% endstep %}

{% step %}
Select the **Semantic Mappings**.

One for each vocabulary or OMOP domain referenced by the syntactic mapping in different transformations. 

An initial selection will already be made for you, but you can change it by clicking on the semantic mapping dropdown menu and selecting a different semantic mapping. 

If there are no semantic mappings that match a given target vocabulary or OMOP domain, the text "NO OPTIONS" will appear. In this case, please close this dialog, create a matching semantic mapping (from the Data Mappings -> Semantic Mappings page), then try again.
{% endstep %}

{% step %}
Click **Run** to start the code run.

![](https://content.gitbook.com/content/ydySyCBmy6F7NnGn4bPa/blobs/ImC3wit5LNH3SUQRHjHB/23456594328477)
{% endstep %}

{% step %}
Click **Code Runs** from the menu on the left to see the code run entry.

You will see the status of the code run here. 

Click on the status of the code run to see a detailed log from the code run (only visible if you have the required permissions.
{% endstep %}

{% step %}
Once the code has finished running, you will see the **status** change to Completed if the run completed successfully or Error if there was any error.

If the run completed successfully, you will see the number of output datasets under the **Output Datasets** field. 

If there was an **Error**, click on the status to see the detailed logs with a description of the error encountered.
{% endstep %}
{% endstepper %}

## Troubleshooting

| Symptom                                   | Likely Cause                                               | Resolution                                                                                                |
| ----------------------------------------- | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| **NO OPTIONS** for input dataset          | No imported dataset matches the source schema              | Import a dataset with the correct schema from the Datasets page                                           |
| **NO OPTIONS** for semantic mapping       | No semantic mapping matches the required vocabulary/domain | Create and approve a semantic mapping for that vocabulary/domain                                          |
| Run status: **Error**                     | Configuration or data issue                                | Click the status to view detailed logs; review the error message for the affected field or transformation |
| Output dataset is empty                   | All rows failed transformation                             | Check error handling settings on transformations; review logs for per-row errors                          |
| Syntactic mapping is locked / cannot edit | The mapping was already run                                | Create a new version of the mapping — see \[\[Editing a Syntactic Mapping]]                               |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.rhinofcp.com/data-harmonization/executing-the-transformation.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.