> 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](https://developer.harness.io/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.

You can also link a Workflow to an integration, such as PagerDuty, Kubernetes, or GitHub, so that it appears only on the matching entities that the integration imported. This doc covers both types of linkage:

* [Link a workflow to entities](#link-workflows-to-entities) directly by entity kind and type.
* [Link workflows to integrations](#link-workflows-to-integrations) to display a Workflow only on the entities an integration imported.

![](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

Make sure you have the following in place:

* 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 cannot create, edit, or unlink a link configuration. Go to [Workflows RBAC](https://developer.harness.io/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](https://developer.harness.io/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 workflows to entities

To open the link configuration for a Workflow, do the following:

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.

### Link configuration

Each Workflow has one link configuration with the following 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`.                             |
| **Integration**   | (Optional) The integration whose imported entities receive the workflow link. If you select an integration, the Workflow appears only on the matching entities that the integration imported. |
| **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-294399a4f1fb76c9a3f5a2f22a0752cf67f054ea%2Flinked-workflows-config.png?alt=media)

#### Define the link target

Set the scope and the entity kind and type pairs that receive the Workflow:

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](https://developer.harness.io/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.

{% hint style="info" %}
The **Link target** section also includes the **Add Integration (Optional)** toggle. Leave it off to link the Workflow directly to entities. To display the Workflow only on the entities an integration imported, go to [Link workflows to integrations](#link-workflows-to-integrations).
{% endhint %}

#### Map entity fields to workflow inputs

Map each Workflow input to the entity field that supplies its value:

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 does not 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-e7e0bf700b0120b0a02d479e608eb3cb7f67f38b%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

Run a linked Workflow from an entity page with the following steps:

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-d65b906624d57ca4e353f2806ed27d3e76fd8aba%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

Open the link configuration and update it with the following steps:

1. Open the **Link Workflows** page using one of the following paths:
   * **From the Workflows page** - Go to **Workflows**. On the Workflow card, click the three-dot menu, and then select **Edit workflow entity link**.

     ![](https://1305598861-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1bzrz9ybUGCcYdvS4u0z%2Fuploads%2Fgit-blob-4d764a23283607e614d8552d38e9f7bcceb088a1%2Flink-workflow-entity-menu1.png?alt=media)
   * **From the Workflow's entity page** - Open the Workflow from the **Catalog**. Click the three-dot menu at the top right, and then select **Edit workflow entity link**.

     ![](https://1305598861-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1bzrz9ybUGCcYdvS4u0z%2Fuploads%2Fgit-blob-70c67e8e80217ee8c54f07921c0fdc8bebde7e7a%2Flink-workflow-entity-menu2.png?alt=media)
2. Update the scope, link targets, or field mappings. To remove a row, click the delete icon next to it.
3. Click **Save Changes**.

***

### Unlink a workflow

Unlinking removes the Workflow from every entity page and resets its link configuration. You cannot 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**.

***

## Link workflows to integrations

When an integration imports entities into the catalog, you can link a Workflow to that integration so developers can act on those entities from the entity page. IDP displays an integration-linked Workflow on an entity page only when the Workflow's integration matches the integration that imported the entity. For example, a Workflow linked to a Kubernetes integration appears on a `Component` of type `service` that your integration imported, and does not appear on a `Component` of type `service` that a different integration imported.

### Prerequisites

Make sure you have the following in place:

* To link a Workflow to an integration, the `IDP_INTEGRATION_DRIVEN_ACTIONS` feature flag must be enabled and the integration must already be configured. Contact [Harness Support](https://www.harness.io/support) to enable the feature flag.
* The requirements in [Before you begin](#before-you-begin) also apply.

### Supported integrations and default configuration

The PagerDuty, Kubernetes, and GitHub integrations each offer an out-of-the-box (OOTB) Workflow in the **Workflows** section of the integration's **Overview** tab. When you install the Workflow from there, IDP links it to that integration, sets the link scope to the integration's scope, and populates the link with the defaults declared in the integration schema:

| Integration                                                                                                                                              | OOTB Workflow                                                                                                                                                                        | Default target (Entity Kind / Entity Type) | Default field mappings (Workflow Input ← Entity Field Source)                                                                                                                                     |
| -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [PagerDuty](https://developer.harness.io/internal-developer-portal/use-idp/software-catalog/create-entity/catalog-discovery/integrations/pagerduty.md)   | [Manage PagerDuty Incident](https://developer.harness.io/internal-developer-portal/use-idp/self-service-workflows/workflow-library/available-workflows.md#manage-pagerduty-incident) | `Component` / `service`                    | <p><code>service\_id</code> ← <code>metadata.integration\_properties.PagerDuty.identifier</code><br><code>service\_name</code> ← <code>metadata.integration\_properties.PagerDuty.name</code></p> |
| [Kubernetes](https://developer.harness.io/internal-developer-portal/use-idp/software-catalog/create-entity/catalog-discovery/integrations/kubernetes.md) | [Kubernetes Day-2 Ops](https://developer.harness.io/internal-developer-portal/use-idp/self-service-workflows/workflow-library/available-workflows.md#kubernetes-day-2-ops)           | `Component` / `service`                    | None. The developer provides every input at run time.                                                                                                                                             |
| [GitHub](https://developer.harness.io/internal-developer-portal/use-idp/software-catalog/create-entity/catalog-discovery/integrations/github.md)         | [Create GitHub Issue](https://developer.harness.io/internal-developer-portal/use-idp/self-service-workflows/workflow-library/available-workflows.md#create-github-issue)             | `Component` / `service`                    | <p><code>repo</code> ← <code>metadata.integration\_properties.GitHub.name</code><br><code>owner</code> ← <code>metadata.integration\_properties.GitHub.org</code></p>                             |

The install wizard does not let you change these defaults. To override the target or the field mappings, [edit the link](#edit-a-workflow-link) after the install completes.

### Install and link a workflow from an integration

You need the Workflow and Pipeline permissions listed in [Install a Workflow](https://developer.harness.io/internal-developer-portal/use-idp/self-service-workflows/workflow-library/install-a-workflow.md#before-you-begin).

1. In Harness IDP, click **Configure** in the left sidebar.
2. In the left sidebar, switch to the scope of the integration, and then click **Integrations**.
3. On the integration card, click **View**. The integration opens on the **Overview** tab.
4. Scroll to the **Workflows** section. The section lists the OOTB Workflow available for your integration, along with the Workflows already linked to it.

   ![](https://1305598861-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1bzrz9ybUGCcYdvS4u0z%2Fuploads%2Fgit-blob-8ec63cbb0e2a9d75f4e8e76d76b1599847cabac7%2Flink-workflow-integration-overview.png?alt=media)
5. Next to the OOTB Workflow, click **Preview & Enable**. The preview page opens with a description of the Workflow, the values you configure at install time, and its prerequisites.
6. Click **Install & link**. The install wizard opens. A banner at the top informs you which integration IDP links the Workflow to, along with the integration identifier.
7. In **Target & settings**, enter the Workflow details, and then click **Next**. Go to [Step 1: Set the target and settings](https://developer.harness.io/internal-developer-portal/use-idp/self-service-workflows/workflow-library/install-a-workflow.md#step-1-set-the-target-and-settings) for a description of each field.
8. In **Admin inputs**, provide the values the Workflow needs, and then click **Next**. Go to [Step 2: Provide the admin inputs](https://developer.harness.io/internal-developer-portal/use-idp/self-service-workflows/workflow-library/install-a-workflow.md#step-2-provide-the-admin-inputs) for details.
9. In **Review & install**, review the summary. The **Workflow & Pipeline** section includes an **Integration** row that displays the integration name and identifier.

   ![](https://1305598861-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1bzrz9ybUGCcYdvS4u0z%2Fuploads%2Fgit-blob-02f89bd4cbffff490307f94a809844d6e44814f5%2Flink-workflow-install-review.png?alt=media)
10. Click **Install & link**.

The confirmation screen displays the Workflow, its backing pipeline, the scope, and the admin inputs you provided. Go to [After the install](https://developer.harness.io/internal-developer-portal/use-idp/self-service-workflows/workflow-library/install-a-workflow.md#after-the-install) for the actions available on the screen.

Back on the integration's **Overview** tab, the installed Workflow appears in the **Workflows** section with a **View Workflow** button. The OOTB Workflow keeps its **Preview & Enable** button, so you can install it again, for example with different admin inputs.

### Link a library-installed workflow to an integration

A Workflow you install from the **Library** tab is not linked to any integration, as the Library install wizard does not include an integration selection. To link it, complete the following steps:

1. Go to **Workflows**. On the Workflow card, click the three-dot menu, and then select **Link workflow to entity**.
2. In **Link target**, select the **Scope**, **Entity Kind**, and **Entity Type**. Go to [Define the link target](#define-the-link-target) for details.
3. Turn on the **Add Integration (Optional)** toggle, and then select the integration in the **Integration** dropdown.

   ![](https://1305598861-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1bzrz9ybUGCcYdvS4u0z%2Fuploads%2Fgit-blob-73384a493846a490acbe0addc01a032e902beefd%2Flink-workflow-add-integration.png?alt=media)
4. (Optional) In **Field mapping**, map Workflow inputs to entity fields. To match the defaults IDP applies at install time, use the field mappings listed in [Supported integrations and default configuration](#supported-integrations-and-default-configuration). Go to [Map entity fields to workflow inputs](#map-entity-fields-to-workflow-inputs) for details.
5. Click **Confirm**.

The Workflow appears in the **Workflows** section of the integration's **Overview** tab, and in the **Linked Workflows** card of the matching entities that the integration imported. Developers run it the same way as any linked Workflow. Go to [Execute a linked workflow from an entity page](#execute-a-linked-workflow-from-an-entity-page) for details.

### Scope of an integration link

IDP identifies an integration by its identifier together with the scope it belongs to (Account, Organization, or Project). When you save a link, IDP sets the link scope as follows:

* **No integration selected** - If you leave **Scope** empty, IDP sets the link at the account scope.
* **Integration selected** - IDP sets the link with the integration's scope, regardless of what you select in **Scope**. For example, if you select an account and a project in **Scope** but link an account-scoped integration, IDP sets only the account scope.

### Edit an integration link

Edit the link to change the integration, or to override the default target and field mappings of a Workflow you installed from an integration.

1. Go to **Configure** → **Integrations** in the scope of the integration, and then click **View** on the integration card.
2. On the **Overview** tab, click **View Workflow** next to the Workflow in the **Workflows** section.
3. On the Workflow's entity page, click the three-dot menu at the top right, and then select **Edit workflow entity link**.
4. Update the integration, scope, link targets, or field mappings.
5. Click **Save Changes**.

You can also open the **Link Workflows** page from the **Workflows** page, as described in [Edit a workflow link](#edit-a-workflow-link).

### Delink a workflow from an integration

{% hint style="warning" %}
Delinking removes only the link between the Workflow and the integration. IDP does not delete the Workflow, and it stays on the **Workflows** page. The Workflow no longer appears in the integration's **Workflows** section, and IDP no longer filters it by that integration on entity pages.
{% endhint %}

**Method 1: From the integration**

1. Go to **Configure** → **Integrations** in the scope of the integration, and then click **View** on the integration card.
2. On the **Overview** tab, click **View Workflow** next to the Workflow in the **Workflows** section.
3. On the Workflow's entity page, click the three-dot menu at the top right, and then select **Edit workflow entity link**.
4. Turn off the **Add Integration (Optional)** toggle.
5. Click **Save Changes**.

**Method 2: From 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. Turn off the **Add Integration (Optional)** toggle.
4. Click **Save Changes**.

{% hint style="info" %}
To remove the entire link configuration, including the link targets and field mappings, [unlink the workflow](#unlink-a-workflow).
{% endhint %}

### Integration deletion

When you delete an integration configuration, IDP removes the link between the integration and the Workflows linked to it. IDP does not delete the associated Workflows, and they stay on the **Workflows** page.

{% @harness-feedback/feedback %}
