> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/internal-developer-portal/use-idp/self-service-workflows/link-workflows-to-entities.md).

# Link Workflows to Catalog Entities

Link a Workflow to catalog entities so that it appears on matching entity pages with inputs pre-filled from entity data.

Without a link, developers may find it difficult to and search and [trigger a Workflow](/internal-developer-portal/use-idp/self-service-workflows/manage-workflow-2o.md#execute-workflows) from the **Workflows** page, and then manually enter entity-specific details such as the service name, owner, and project.

Harness IDP lets you link your Workflow to catalog entities. When you link a Workflow to an entity kind and type, the Workflow appears on each matching entity page with its inputs pre-filled from the entity metadata. For example, when a developer triggers the `Create S3 Bucket` workflow from a service's entity page, IDP fills in the service name and owner from that service's YAML.

![](https://1305598861-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1bzrz9ybUGCcYdvS4u0z%2Fuploads%2Fgit-blob-ca4e7e8174ebf84225342528e5f348c6ae0e67ec%2Flinked-workflows.png?alt=media)

***

## Before you begin

* You need the **Create/Edit** permission for Workflows in the Workflow's scope. Users without this permission can view linked Workflows on entity pages, but they can't create, edit, or unlink a link configuration. Go to [Workflows RBAC](/internal-developer-portal/admin-and-customization/rbac/workflow-rbac.md) to configure permissions.
* The Workflow must define the inputs you plan to map. Go to [Configuring Workflow Inputs](/internal-developer-portal/use-idp/self-service-workflows/create-workflow/flows-input.md) to add inputs.
* The catalog must contain entities of the kind and type you plan to target.

***

## Link a workflow to entities

1. In Harness IDP, go to **Workflows**.
2. On the Workflow card, click the three-dot menu, and then select **Link workflow to entity**.

   ![](https://1305598861-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1bzrz9ybUGCcYdvS4u0z%2Fuploads%2Fgit-blob-0eeee2740637358da9ffc9bfc400f4fade2157b0%2Flink-workflow-menu.png?alt=media)

The **Link Workflows** page opens with the **Link target** and **Field mapping** sections.

Each Workflow has one link configuration with three parts:

| Part              | What it defines                                                                                                                                                                           |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Scope**         | The Account, organizations, and projects whose entities receive the link. Optional. If you leave **Scope** empty, the Workflow appears on matching entities across the account.           |
| **Link target**   | One or more **Entity Kind** and **Entity Type** pairs. The Workflow appears on every entity that matches a pair, for example every `Component` of type `service`.                         |
| **Field mapping** | Pairs of a Workflow input and an entity field path. IDP reads the value at the path from the entity YAML and pre-fills the input. Optional. The same mappings apply to every link target. |

![](https://1305598861-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1bzrz9ybUGCcYdvS4u0z%2Fuploads%2Fgit-blob-cf0d562f6557406378d6cc25ad7cf963ff4407e3%2Flinked-workflows-config.png?alt=media)

### Define the link target

1. (Optional) Click **Scope**, and then select the Account, organizations, or projects whose entities receive the link. Use the search box to find a project or organization. Each selection appears as a tag in the field.
2. In **Entity Kind**, select the kind of entity to target. The list includes the built-in kinds and the [custom kinds](/internal-developer-portal/admin-and-customization/custom-entity-kinds/overview.md) defined in your account.
3. In **Entity Type**, select the type. The list displays the types available for the selected kind.
4. If you wish to target additional kind and type, click **+ Add More**, and then repeat steps 2 and 3 for the new row.

### Map entity fields to workflow inputs

1. In **Field mapping**, click **Create a Mapping**. If the link already has a mapping, click **+ Add More**.
2. In **Workflow Input**, select the input to pre-fill. The list groups inputs by the Workflow form page they belong to.
3. In **Entity Field Source**, enter the path to the entity YAML field that supplies the value. Use dot notation for nested fields.
4. Repeat steps 1 to 3 for each input you want to pre-fill.

The following entity YAML and table illustrate how IDP resolves each path:

```yaml
apiVersion: harness.io/v1
kind: Component
name: Payment Processing Service
identifier: payment_processing_service
type: service
owner: group:account/platform_team
spec:
  lifecycle: production
metadata:
  description: Processes card payments for checkout.
```

| Entity Field Source    | Pre-filled value                        |
| ---------------------- | --------------------------------------- |
| `name`                 | `Payment Processing Service`            |
| `owner`                | `group:account/platform_team`           |
| `spec.lifecycle`       | `production`                            |
| `metadata.description` | `Processes card payments for checkout.` |

{% hint style="info" %}

* If you leave **Entity Field Source** empty, the developer enters the input value manually.
* If the path doesn't exist on an entity, IDP leaves the input empty for the developer to fill in.
* Point each path to a single value. If a path points to an object or a list, IDP converts it to a string and pre-fills that string.
  {% endhint %}

### Save the link

Click **Confirm** to save the link, or click **Discard** to cancel it.

![](https://1305598861-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1bzrz9ybUGCcYdvS4u0z%2Fuploads%2Fgit-blob-65d40238c9429ebf6b72cf7f53fef9658912eade%2Flink-workflow-configured.png?alt=media)

The Workflow now appears in the **Linked Workflows** card on every entity that matches the scope and a link target.

***

## Execute a linked workflow from an entity page

1. Go to **Catalog**, and then open an entity that matches a link target.
2. On the **Overview** tab, locate the **Linked Workflows** card. The card lists every Workflow linked to the entity.

   ![](https://1305598861-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1bzrz9ybUGCcYdvS4u0z%2Fuploads%2Fgit-blob-77f58199154fdeaf59214bb80638af7a0c627f6e%2Flinked-workflows-card.png?alt=media)
3. Click **Execute** next to the Workflow.

The Workflow form opens with the mapped inputs pre-filled from the entity YAML. Review the values, complete any empty inputs, and then submit the form.

***

## Edit a workflow link

1. Go to **Workflows**.
2. On the Workflow card, click the three-dot menu, and then select **Edit workflow entity link**.
3. Update the scope, link targets, or field mappings. To remove a row, click the delete icon next to it.
4. Click **Save Changes**.

***

## Unlink a workflow

Unlinking removes the Workflow from every entity page and resets its link configuration. You can't undo this action. The Workflow itself stays on the **Workflows** page.

1. Go to **Workflows**.
2. On the Workflow card, click the three-dot menu, and then select **Edit workflow entity link**.
3. In **Danger Zone**, click **Unlink**.
4. In the **Confirm Delink** dialog, click **Delink**.

{% @harness-feedback/feedback %}