Aliases

Aliases connect catalog entities to their corresponding resources in external systems. Alias types become available in your catalog entity type settings when you enable a connection to a third-party service in Admin > Connections. Once enabled, DX will automatically assign aliases when the name or identifier matches exactly.

Some alias types are multi-instance, meaning the same external system can be connected to DX more than once (for example, two separate Jira instances). For these alias types, the same identifier value may exist across multiple instances, and an instance_identifier can be paired with identifier to ensure the alias is linked to the correct instance.

For aliases that support URLs, the alias is linked back to the resource in the third-party system from within Software catalog.

Supported alias types

Using the API

Aliases are organized by alias type, with each type containing a list of alias entry definitions. The key in the object is the alias type. Each alias entry must include either identifier (optionally paired with instance_identifier for multi-instance alias types) or lookup, but not both.

To remove an alias, update or upsert a catalog entity with the alias type set to an empty array []. Omitted alias types are not affected.

Example Request

When creating or updating aliases, use identifier when you know the external system’s unique identifier for the alias entry. For multi-instance alias types, you can optionally include instance_identifier alongside identifier to target a specific connected instance.

Use lookup when you want the API to find a single matching alias entry by name or identifier from the Data Cloud database. A lookup value uses case-insensitive partial matching. If the lookup matches more than one alias entry, the request returns alias_lookup_ambiguous.

{
  "github_repo": [
    {
      "lookup": "get-dx/payment-processing"
    }
  ],
  "pagerduty_service": [
    {
      "identifier": "P123ABC"
    }
  ],
  "jira_project": [
    {
      "identifier": "PLAT",
      "instance_identifier": "abc123"
    }
  ]
}

Example Response

The API response will include the name and optional url fields that were fetched from the Data Cloud database:

{
  "github_repo": [
    {
      "identifier": "671150935",
      "name": "get-dx/payment-processing",
      "url": "https://github.com/get-dx/payment-processing"
    }
  ],
  "pagerduty_service": [
    {
      "identifier": "P123ABC",
      "name": "Payment Service"
    }
  ],
  "jira_project": [
    {
      "identifier": "PLAT",
      "instance_identifier": "1",
      "name": "Platform",
      "url": "https://your-org.atlassian.net/jira/software/projects/PLAT"
    }
  ]
}

Properties