# Uniform Siphon Transformation

> Command-line tools to refactor Uniform serialization after import - convert entries to blocks, replace entries with components/patterns, fix inline assets, and audit/clean datasources.

Source: https://docs.uniform.app/docs/guides/migration/transformation

**Uniform Siphon** is a focused toolkit for refactoring Uniform serialization.  
It helps you clean up after imports, migrate between datasources, and standardize models by:

- converting entries → blocks/components/patterns,
- replacing inline asset URLs with proper Uniform assets,
- scanning for orphaned datatypes/dataresources and JPTR tokens.

### Transformation Commands

Siphon includes various transformation commands for post-migration cleanup and optimization.

#### Calculate Migration Scope (Experimental)

This utility analyzes a Uniform serialization dataset and scans for **all unique jptr tokens** (data resource references).  
It reports how many datatypes and compositions/entries are used and where they are referenced.  
This helps to understand the migration scope of a given datasource and archetype before performing actual transformations.

```powershell
calculate-scope --inputDir <uniform_path> --datasourceId <datasource_name>
```

#### Required Parameters

| Parameter | Description |
| --- | --- |
| `--inputDir` | Path to the folder containing Uniform serialization (`entry`, `composition`) |
| `--datasourceId` | The datasource ID to search for references (e.g., `contentful`, `bigquery`) |

#### Optional Parameters

| Parameter | Description |
| --- | --- |
| `--archetype` | Filter datatypes by archetype within the selected datasource (e.g., `entry`, `composition`) |
| `--logLevel` | Sets the log level. Options: `debug`, `info`, `warn`, `error` (default: `debug`) |
| `--no-timestamps` | Disable timestamps in logs |

#### Convert Entries to Components (Experimental)

This utility processes a Uniform serialization dataset and **replaces entries with components or patterns**.  
It migrates source data from `entry` files directly into compositions, updating component parameters and patterns so that entries are no longer required as separate entities.

For example, when there is an Author entry referenced by a News Article composition through an Author component, after running the command the entry's field values will be copied directly into the component's fields. The original Author entry will then be removed.

```powershell
replace-entries-with-components --inputDir <uniform_path> --outputDir <output_path>
```

#### Required Parameters

| Parameter | Description |
| --- | --- |
| `--inputDir` | Path to the folder containing Uniform serialization (`entry`, `composition`, etc.) |
| `--outputDir` | Path to the folder where transformed data will be written |

#### Optional Parameters

| Parameter | Description |
| --- | --- |
| `--excludeContentTypes` | ex: hero,carousel or * for all |
| `--singleRefAsComponent` | Replace a pattern with a component for entries that have a single reference |
| `--defaultLanguage` | Used to create a pattern name from entry text fields if they are localized |
| `--entriesDir` | If not set the --outputDir is used |
| `--logLevel` | Sets the log level. Options: `debug`, `info`, `warn`, `error` (default: `debug`) |
| `--no-timestamps` | Disable timestamps in logs |

---

#### Merge Entries into Components (Experimental)

This utility processes a Uniform serialization dataset and migrates **entries** into **components and patterns**.  
It identifies components that reference entries, transforms those entries into blocks, and updates component definitions accordingly.  
Unused or fully migrated entries can be removed, and new block definitions or patterns are created when necessary.

```powershell
merge-entries-into-components --inputDir <uniform_path> --outputDir <output_path>
```

#### Required Parameters

| Parameter | Description |
| --- | --- |
| `--inputDir` | Path to the folder containing Uniform serialization (`entry`, `composition`, `contentType`, etc.) |
| `--outputDir` | Path to the folder where transformed data will be written |

---

#### Find JPTR Tokens (Experimental)

Scans a Uniform serialization dataset and finds **all unique JPTR tokens** (`${#jptr:/...}`) that point to data resources from selected datasources.  
Useful for auditing connected data usage before refactors or migrations.

```powershell
find-jptr-tokens --inputDir <uniform_path>
```

#### Required Parameters

| Parameter | Description |
| --- | --- |
| `--inputDir` | Path to the folder containing Uniform serialization (`composition`, `entry`, etc.) |

#### Optional Parameters

| Parameter | Description |
| --- | --- |
| `--datasourceId` | Limit the search to a specific datasource. If omitted, all datasources with singleEntry / multipleEntry archetypes are considered. |
| `--logLevel` | Log verbosity: `debug`, `info`, `warn`, `error` (default: `debug`) |
| `--no-timestamps` | Disable timestamps in logs |

---

#### Find Orphaned Datatypes (Experimental)

Scans a Uniform serialization dataset to detect **datatypes that are not used anywhere**.  
Optionally removes orphaned datatypes from all serializations and deletes the datatype files.

```powershell
find-orphaned-datatypes --inputDir <uniform_path>
```

#### Required Parameters

| Parameter | Description |
| --- | --- |
| `--inputDir` | Path to the folder containing Uniform serialization (`composition`, `entry`, etc.) |

#### Optional Parameters

| Parameter | Description |
| --- | --- |
| `--datatypeId` | Check a **single** datatype by ID. If omitted, all datatypes are checked. |
| `--delete` | If set, **removes** orphaned datatypes from compositions/entries and deletes their files under `datatype/`. |
| `--logLevel` | Log verbosity: `debug`, `info`, `warn`, `error` (default: `debug`) |
| `--no-timestamps` | Disable timestamps in logs |

---

#### Convert Entries to Blocks (WIP)

This utility analyzes Uniform serialization data (`entries` and `contentTypes`) and automatically transforms all entries of a specified `--contentType` into **blocks**.  
By doing so, it replaces direct content type references with block references, making the data model more flexible and modular.

For example, when having a News Article entry with a reference field "Author" pointing to another entry called John Doe, after using the command the Author field will become a block field with John Doe being an block entry. The John Doe entry will be removed.

```powershell
entries-to-blocks --inputDir <uniform_path> --outputDir <output_path>
```

#### Required Parameters

| Parameter | Description |
| --- | --- |
| `--inputDir` | Path to the folder containing Uniform serialization data |
| `--outputDir` | Path to the folder where transformed data will be written |

#### Optional Parameters

| Parameter | Description |
| --- | --- |
| `--contentType` | Content type to convert into a block |
| `--whatIf` | Runs validation and prints a detailed report without applying transformations |
| `--force` | Forces transformation even if multiple references to the same entry are detected |

---

#### Find Entry Missing References (Experimental)

Scans a Uniform serialization entries to detect missing references.

```powershell
find-entries-missing-references --inputDir <uniform_path>
```

#### Required Parameters

| Parameter | Description |
| --- | --- |
| `--inputDir` | Path to the folder containing Uniform serialization (`composition`, `entry`, etc.) |

#### Optional Parameters

| Parameter | Description |
| --- | --- |
| `--logLevel` | Log verbosity: `debug`, `info`, `warn`, `error` (default: `debug`) |
| `--no-timestamps` | Disable timestamps in logs |

---

#### Entries to Canvas (WIP)

Generates Uniform Canvas artifacts (components, compositions, and project map) from the Uniform Entries and ContentTypes serialization.
The tool creates component definitions based on Content Types (including slots from contentReference fields). Transforms entries of specified page types into compositions. Builds a Project Map (nodes and definition) based on page hierarchy (parentPages field) and inserts links to map nodes where required.

```powershell
entries-to-canvas --inputDir <uniform_path> -o <output_path> --pages <content_type_ids>
```

#### Required Parameters

| Parameter | Description |
| --- | --- |
| `--inputDir` | Path to the folder containing Uniform serialization (`entry`, `composition`, `contentType`, …). Serves as the data source. |
| `--outputDir` | Path to the folder where the generated artifacts will be written (`component/`, `composition/`, `projectMapDefinition/`, `projectMapNode/`). |
| `--pages` | Comma/semicolon/pipe/dot-separated list of **Content Type IDs** that should be treated as **page types** (top-level compositions) |

#### Optional Parameters

| Parameter | Description |
| --- | --- |
| `--dynamic-pages` | Content Type IDs for **dynamic page templates**. _(Dynamic composition generation is partially implemented, see notes below)._ |
| `--ref-field-as-link` | Comma/semicolon/pipe/dot-separated list of `contentReference` field IDs to be converted into **links** pointing to **Project Map Nodes**, instead of being inlined as slots. |
| `--contenttypes` | Comma/semicolon/pipe/dot-separated list of Content Types to **exclude from migration** (no component/composition will be generated for them). |
| `--exclude-fields` | Comma/semicolon/pipe/dot-separated list of field IDs to exclude from components/compositions (e.g., system/internal fields). |
| `--defaultLanguage` | Default locale to use when resolving field values for slot generation. If not set, the **first available locale** will be used. |

---

#### Generate Project Map (Experimental)

Generate Project Map from Compositions by slug.

```powershell
build-projectmap --inputDir <uniform_path>
```

#### Required Parameters

| Parameter | Description |
| --- | --- |
| `--inputDir` | Path to the folder containing Uniform serialization (`composition`, `entry`, etc.) |

#### Optional Parameters

| Parameter | Description |
| --- | --- |
| `--logLevel` | Log verbosity: `debug`, `info`, `warn`, `error` (default: `debug`) |
| `--no-timestamps` | Disable timestamps in logs |

---

For additional support, contact Uniform support with detailed log files and error messages.