> For the complete documentation index, see [llms.txt](https://doc.wearepatchworks.com/product-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://doc.wearepatchworks.com/product-documentation/process-flows/building-process-flows/process-flow-shapes/standard-shapes/data-transform-shape.md).
# Data Transformation
## Introduction
The **Data Transformation** shape handles common payload transformations - converting between formats, or running a find/replace - without writing or deploying a custom script.
Pick from a library of predefined transformation functions, maintained centrally by Patchworks. Each transformation shows what it accepts and produces, and you can test it against a sample payload before saving.
{% hint style="info" %}
Transformations are versioned. When a newer version of a transformation is released, flows already using the previous version keep running unchanged - older versions simply emit a warning in the run log and can no longer be selected for new use.
{% endhint %}
### Need to know
* Each Data Transformation shape runs **one transformation**. To run several in sequence, add a Data Transformation shape for each one - they run in order, with the output of one becoming the input of the next.
* Transformations are managed and versioned by Patchworks - there's nothing to write, deploy or maintain yourself.
* By default, a shape uses the **latest version** of its transformation, picking up new versions automatically. Turn off *always use the latest version* to pin a specific version.
* A pinned, deprecated version continues to run, but a warning is logged in the run log and the version can no longer be selected for new shapes.
* The shape is fully supported in flow duplication, export/import and blueprints. Transformations are matched by name and version, so flows move cleanly between companies and environments.
* If the incoming payload isn't valid for the selected transformation (for example, broken XML or a malformed regex), the step fails with a clear error - it won't pass bad data through.
### Available transformations
| Transformation | What it does |
| -------------------- | ------------------------------------------------------------------------------------------ |
| CSV to JSON | Converts a CSV payload into a JSON array of objects, using the header row for field names. |
| Find/Replace | Finds a simple string throughout the payload and replaces it with another. |
| Find/Replace (regex) | Finds matches for a regular expression throughout the payload and replaces them. |
| JSON to CSV | Converts a JSON array of objects into a CSV payload with a header row. |
| JSON to XML | Converts JSON to an XML document under a root element. List items become item elements. |
| XML to JSON | Converts an XML document into a JSON payload, including attributes and text values. |
{% hint style="info" %}
Bespoke transformations can also be added privately for a specific company (and, optionally, its child companies). If there's a script you reuse often enough that it should be on this list, contact the Patchworks support team.
{% endhint %}
### Adding a Data Transformation shape
{% stepper %}
{% step %}
**Add the shape**
In your process flow, hover over the point where the Data Transformation should run, click to add a new shape, and choose **Data Transformation** from the shapes list.
{% endstep %}
{% step %}
**Select a transformation**
Use the *select a transformation* dropdown to choose the transformation to apply. A short description of what the selected transformation accepts and produces is displayed beneath the field.
{% endstep %}
{% step %}
**Test with a sample payload**
Click **test with sample payload** to run the selected transformation against sample data and confirm the output is what you expect, before the flow ever runs.
{% endstep %}
{% step %}
**Choose a version setting**
Leave *always use the latest version* toggled on (the default) to pick up new versions of the transformation automatically, or toggle it off to pin the shape to a specific version.
{% endstep %}
{% step %}
**Save the shape**
Click **save** to confirm your settings. The shape is added to the canvas, showing the selected transformation and version setting.
{% endstep %}
{% endstepper %}
### Transformation versions
Transformations are versioned centrally by Patchworks:
* **Latest version** - with *always use the latest version* on, the shape runs the newest version of the transformation each time, with no flow edit needed when a new version is released.
* **Pinned version** - with the toggle off, the shape keeps running the version you selected. If a newer version is released, the settings panel lets you know one is available.
* **Deprecated versions** - when a version is deprecated, shapes pinned to it keep working, but each run logs a deprecation warning and the version can no longer be selected for new shapes. Publishing a blueprint containing a shape pinned to a deprecated version shows a warning, but doesn't block publishing.
{% hint style="warning" %}
Deprecated versions will continue to run, but we recommend moving affected shapes to the latest version when you see a deprecation warning in your run logs.
{% endhint %}
