> For the complete documentation index, see llms.txt.
Skip to main content

Check out Port for yourself ➜ 

Workflow catalog and ownership

Every workflow in Port is automatically represented as an entity based on the _workflow system blueprint. This lets you assign team ownership to workflows and control access using Port's standard blueprint permissions model.

The _workflow blueprint​

When the workflow catalog feature is enabled for your organization, Port provisions a _workflow system blueprint and syncs all of your workflows to it as entities. The catalog entry for each workflow stays in sync automatically: when you create, update, or delete a workflow, its catalog entity is updated accordingly.

Port keeps each workflow's catalog entity in sync with its definition. Core catalog fields (such as nodes, connections, and versionIdentifier) update automatically when you create or change a workflow in the builder or through the Workflows API. You manage workflow definitions through the Workflows API or the Port UI.

You can extend the _workflow blueprint with additional properties and non-required relations, then set those values on each workflow's catalog entity along with owning teams. See extend the _workflow blueprint below.

Blueprint properties​

Each workflow entity in the _workflow blueprint includes the following system-managed properties:

PropertyTypeDescription
triggerTypesstring[]The trigger types configured on the workflow (e.g. SELF_SERVE_TRIGGER, EVENT_TRIGGER)
nodesobject[]The full list of nodes that make up the workflow
connectionsobject[]The connections between workflow nodes
categorystringAn optional category label used to group the workflow
descriptionstringAn optional description of what the workflow does
versionIdentifierstringThe identifier of the latest workflow version (e.g. wfv_abc123)
Updating workflow catalog properties

These properties reflect the live workflow definition. Attempts to modify them through the entities API return an error.

Any custom properties or non-required relations you add to the _workflow blueprint can be updated on the catalog entity like on any other blueprint.

Extend the _workflow blueprint​

You can extend the _workflow blueprint with new properties and non-required relations to track metadata that belongs in the catalog (for example cost center, criticality, or a relation to a runbook entity). Default workflow properties and required relations stay protected and cannot be changed or removed.

To add a property:

  1. Go to the Data model page in your portal.
  2. Open the _workflow blueprint.
  3. Click + New property (or + New relation), fill in the details, and save.

After you extend the blueprint, each workflow's catalog entity can store values for the fields you added.

Set catalog metadata when saving a workflow​

When you create or update a workflow, you can set custom catalog property values and owning teams in the same request instead of editing the catalog entity separately.

In the workflow builder, use the Additional properties section in the create or edit workflow dialog. Fill in your custom fields and Owning Teams, then save the workflow.

Through the API, pass a catalogEntity object on POST and PUT /v1/workflows:

{
"identifier": "security_scan",
"title": "Security scan",
"nodes": [],
"connections": [],
"catalogEntity": {
"properties": {
"criticality": "high"
},
"team": ["platform-team"]
}
}

Omitted keys under catalogEntity.properties are left unchanged on update. Set a property to null to clear it. Omit catalogEntity.team to leave owning teams unchanged.

The caller must have permission to register or update the workflow's catalog entity with the property values and teams you send.

Team ownership​

The _workflow blueprint supports direct team ownership. Assign one or more owning teams when you create or edit a workflow (see set catalog metadata when saving a workflow), or update the workflow entity in the catalog.

Assigning ownership gives a team visibility into and, depending on your permissions configuration, control over the workflow. This follows the same ownership model used across the rest of Port's catalog.

To assign owning teams from the catalog:

  1. Navigate to the catalog and open the Workflow catalog page.
  2. Find the workflow entity you want to update.
  3. Edit the entity and set the Owning Teams field.
Admins always have access

Admins can always read and modify any workflow, regardless of ownership or permissions configuration.

Catalog-level permissions​

The _workflow blueprint's permissions model controls read and write access to workflows:

  • Read permissions - determine which users can view a workflow (see it in the UI or fetch it via the API).
  • Write permissions - determine which users can create, update, or delete a workflow.

These are distinct from execute permissions, which control who can trigger a workflow run from the self-service hub.

Configuring permissions​

Workflows run with organization-level permissions

Workflows execute with organization-level permissions, which may exceed the permissions of the user who created them. Ensure that workflows are reviewed and scoped appropriately to avoid unintended access changes.

Permissions on the _workflow blueprint follow the same structure as permissions on any other blueprint. You can restrict access by role, by team, or using a policy expression.

To configure permissions:

  1. Navigate to Data model in your portal.
  2. Find the _workflow blueprint and open its Permissions panel.
  3. Set read and update permissions as needed.
Protected system blueprint

The _workflow blueprint cannot be deleted, and its core schema cannot be modified. You can add custom properties and non-required relations, configure blueprint permissions, and set owning teams and custom property values on individual workflow entities.