# Workflows to create entities

> Build scheduled entity-creation workflows with sources, JSONata transforms, and catalog sinks.

*Published: 2026-04-09*


## Overview

**Workflows** (entity-creation pipelines) are directed graphs that describe how data becomes [Backstage catalog entities](https://backstage.io/docs/features/software-catalog/descriptor-format/). 

At the moment, these are constructed wholly in the Roadie Editor UI. 

In the Editor you connect nodes on a canvas; execution moves from a trigger through **sources** and **transforms** into **sinks**. New workflows are created as **entity-creation** type so the graph is validated for publishing entities into the catalog.

![users-workflow](./users-workflow.webp)

## Triggers

| Node | Role |
| ---- | ---- |
| **Schedule** | Runs the workflow on a recurring interval (minutes, hours, days, or weeks; weekly schedules can optionally fix a day of week). |

## Sources

| Node | Role |
| ---- | ---- |
| **Data source** | Reads objects from the catalog datastore, typically populated by [data sources](/docs/catalog/building-your-catalog/data-sources/). |

## Transforms

| Node | Role |
| ---- | ---- |
| **Map** | Transforms each item with a [JSONata](https://jsonata.org/) expression to shape fields for entity templates. |
| **Filter** | Keeps or drops items using JSONata. |
| **Merge** | Joins two inputs on configurable keys (for example correlating two datastore snapshots). |

## Sinks

| Node | Role |
| ---- | ---- |
| **Entity provider** | Emits catalog entities via the entity provider mechanism, using templates (including Nunjucks) so each record becomes a valid entity. Standard kinds include Component, API, Resource, Group, User, System, Domain, Location, Repository, and Product, subject to your validators. |

## Creating a new Workflow

<div role="alert">
  <div class="bg-teal-500 text-white font-bold px-4 py-2">Note</div>
  <div class="bg-teal-100 border border-t-0 border-teal-400 text-teal-700 px-4 py-3">
    <p>Workflows require at least one configured Data Source. It needs to have successfully run to collect data in order for that data to be accessible to a Workflow.</p>
  </div>
</div>

1. From the Workflows page, select `+ New`.
2. Drag over configured Data Sources on to the Editor on the right panel. Each Data Source becomes a node.
3. Any number of Data Sources can be added to the Editor. 
4. Data Sources data can be filtered, mapped and merged together with data from other Data Sources using the `Filter`, `Map` and `Merge` nodes.
5. Nodes are connected by dragging edges between nodes.
6. In order to create entities in the Catalog, drag an Entity Provider node on to the Editor panel.
7. Entity Providers can either be configured using the `Composer` or via the `Advanced` option (writing raw YAML). Entity Providers use templating to pull data from Data Sources into individual entities.
8. Once you're ready to see how a Workflow operates, use `Test`. 
9. Once you're happy with the workflow, `Save`, and `Commit` to add those entities to your Catalog. 

## Dry runs and operations

Where supported, nodes allow **dry runs** so you can validate extraction and transforms before enabling a schedule or relying on the workflow in production. Enable the workflow when you are satisfied, then monitor executions and adjust JSONata or templates when upstream APIs change.

## Permissions

Workflow actions are protected by catalog workflow permissions (read, create, update, delete, and **execute**). Grant execute only to users or roles that should be able to run pipelines against real data.

## Further reading

- [Building your Catalog — overview](/docs/catalog/building-your-catalog/)
- [Data sources](/docs/catalog/building-your-catalog/data-sources/)
- [Integrations](/docs/catalog/building-your-catalog/integrations/)
- [Modeling entities](/docs/catalog/modeling-entities/)