Request metadata changes with governance workflows

This document describes how to propose single-resource changes to business glossary categories and terms, as well as Knowledge Catalog (formerly Dataplex Universal Catalog) entries, using governance workflows.

Before you begin

To use governance workflows for metadata changes, ensure that you have enabled the required APIs and that you have the necessary Identity and Access Management (IAM) roles and permissions.

Enable the Dataplex API, if it is not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the API

Required roles

To get the permissions that you need to request metadata changes, ask your administrator to grant you the following IAM roles on your project, glossary, or entry group:

For more information about granting roles, see Manage access to projects, folders, and organizations.

You might also be able to get the required permissions through custom roles or other predefined roles.

For more information about roles and permissions, see Knowledge Catalog IAM roles.

Request changes for a glossary category

If you don't have direct write access to create, update, or delete a glossary category, you can request such a change using governance workflows. After a metadata change request is submitted, requesters, approvers, and workflow administrators can monitor and manage the request throughout its lifecycle.

Create a category

Console

Follow these steps to request a category:

  1. In the Google Cloud console, go to the Knowledge Catalog Glossaries page.

    Go to Glossaries

  2. Select the glossary in which you want to create a category, and then click Create category.

  3. Enter a Display name for the category.

  4. Optional: In the Labels section, add labels for the glossary.

  5. Optional: In the Justification section, provide the approver with a reason for your change.

  6. In the Advanced Settings section, you can edit the Category ID if you want to change the auto-generated ID.

  7. Click Submit for review.

The system logs a new change request and notifies the approver. You can track the request progress on the Governance Workflows page under the My Requests tab.

REST

To request creating a category, use the glossaries.requestGlossaryChange method:

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "projects/PROJECT_ID/locations/LOCATION/glossaries/GLOSSARY_ID",
    "createCategoryRequest": {
      "parent": "projects/PROJECT_ID/locations/LOCATION/glossaries/GLOSSARY_ID",
      "categoryId": "sample-category-id",
      "category": {
        "displayName": "Sample category name",
        "description": "Sample category description",
        "parent": "projects/PROJECT_ID/locations/LOCATION/glossaries/GLOSSARY_ID"
      }
    },
    "justification": "JUSTIFICATION"
  }' \
  "https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/glossaries/GLOSSARY_ID:requestGlossaryChange"

Replace the following:

  • PROJECT_ID: the ID of your Google Cloud project.
  • LOCATION: the region where the glossary exists, such as us-central1.
  • GLOSSARY_ID: the ID of the parent glossary.
  • JUSTIFICATION: an explanation of why you're proposing the change.

The service returns a response containing the resource name of the change request. The system logs a new change request and notifies the approver.

Update a category

Console

Follow these steps to suggest changes to a category:

  1. In the Google Cloud console, go to the Knowledge Catalog Glossaries page.

    Go to Glossaries

  2. Select the glossary that includes the category you want to update.

  3. Click the category name to open the Category details pane.

  4. To add or update category details, click Add or Edit next to the section that you want to update.

  5. Click Submit for review. Some items might require additional justification for the change. Provide the justification and click Proceed to Submit Changes.

The system logs a new change request and notifies the approver. You can track the request progress on the Governance Workflows page under the My Requests tab.

REST

To request an update to a category display name and description, use the glossaries.requestGlossaryChange method:

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "projects/PROJECT_ID/locations/LOCATION/glossaries/GLOSSARY_ID",
    "updateCategoryRequest": {
      "category": {
        "name": "projects/PROJECT_ID/locations/LOCATION/glossaries/GLOSSARY_ID/categories/CATEGORY_ID",
        "displayName": "Sample new name",
        "description": "Sample new description"
      },
      "updateMask": {
        "paths": [
          "display_name",
          "description"
        ]
      }
    },
    "justification": "JUSTIFICATION"
  }' \
  "https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/glossaries/GLOSSARY_ID:requestGlossaryChange"

Replace the following:

  • PROJECT_ID: the ID of your Google Cloud project.
  • LOCATION: the region where the glossary exists, such as us-central1.
  • GLOSSARY_ID: the ID of the parent glossary.
  • CATEGORY_ID: the ID of the target category you want to update.
  • JUSTIFICATION: an explanation of why you're proposing the change.

The service returns a response containing the resource name of the change request. The system logs a new change request and notifies the approver.

Delete a category

Console

Follow these steps to request deleting a category:

  1. In the Google Cloud console, go to the Knowledge Catalog Glossaries page.

    Go to Glossaries

  2. Expand the glossary and click the category that you want to delete.

  3. In the Category details pane, select Delete from the menu.

  4. Optional: In the Justification section, provide the approver with the reason for your change.

  5. Click Submit for review.

The system logs a new change request and notifies the approver. You can track the request progress on the Governance Workflows page under the My Requests tab.

REST

To request deleting a category, use the glossaries.requestGlossaryChange method:

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "projects/PROJECT_ID/locations/LOCATION/glossaries/GLOSSARY_ID",
    "deleteCategoryRequest": {
      "name": "projects/PROJECT_ID/locations/LOCATION/glossaries/GLOSSARY_ID/categories/CATEGORY_ID"
    },
    "justification": "JUSTIFICATION"
  }' \
  "https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/glossaries/GLOSSARY_ID:requestGlossaryChange"

Replace the following:

  • PROJECT_ID: the ID of your Google Cloud project.
  • LOCATION: the region where the glossary exists, such as us-central1.
  • GLOSSARY_ID: the ID of the parent glossary.
  • CATEGORY_ID: the ID of the target category you want to delete.
  • JUSTIFICATION: an explanation of why you're proposing the change.

The service returns a response containing the resource name of the change request. The system logs a new change request and notifies the approver.

Request changes for a glossary term

If you don't have direct write access to create, update, or delete a glossary term, you can request such a change using governance workflows.

Create a glossary term

Console

Follow these steps to request creating a glossary term:

  1. In the Google Cloud console, go to the Knowledge Catalog Glossaries page.

    Go to Glossaries

  2. Select the glossary or category in which you want to create a term to open the details pane.

    • If you create a term from the glossary details page, select Create term from the menu.
    • If you create a term from the category details page, select Add term from the menu.
  3. Enter a Display name for the category.

  4. Optional: In the Labels section, add labels for the term.

  5. Optional: In the Justification section, provide the approver with a reason for your change.

  6. In the Advanced Settings section, you can edit the Term ID if you want to change the auto-generated ID.

  7. Click Submit for review.

The system logs a new change request and notifies the approver. You can track the request progress on the Governance Workflows page under the My Requests tab.

REST

To request creating a glossary term, use the glossaries.requestGlossaryChange method:

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "projects/PROJECT_ID/locations/LOCATION/glossaries/GLOSSARY_ID",
    "createTermRequest": {
      "parent": "projects/PROJECT_ID/locations/LOCATION/glossaries/GLOSSARY_ID",
      "termId": "sample-term-id",
      "term": {
        "displayName": "Sample term name",
        "description": "Sample term description",
        "parent": "projects/PROJECT_ID/locations/LOCATION/glossaries/GLOSSARY_ID"
      }
    },
    "justification": "JUSTIFICATION"
  }' \
  "https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/glossaries/GLOSSARY_ID:requestGlossaryChange"

Replace the following:

  • PROJECT_ID: the ID of your Google Cloud project.
  • LOCATION: the region where the glossary exists, such as us-central1.
  • GLOSSARY_ID: the ID of the parent glossary.
  • JUSTIFICATION: an explanation of why you're proposing the change.

The service returns a response containing the resource name of the change request. The system logs a new change request and notifies the approver.

Update a glossary term

Console

Follow these steps to request changes to a glossary term:

  1. In the Google Cloud console, go to the Knowledge Catalog Glossaries page.

    Go to Glossaries

  2. Select the glossary that includes the term you want to update.

  3. Click the term name to open the Term details pane.

  4. Add or update term details by clicking Add or Edit next to the section you want to update.

  5. Click Submit for review. Some sections might require that you provide additional justification before you can submit the request. Provide the justification and click Proceed to Submit Changes.

The system logs a new change request and notifies the approver. You can track the request progress on the Governance Workflows page under the My Requests tab.

REST

To request an update to a glossary term display name and description, use the glossaries.requestGlossaryChange method:

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "projects/PROJECT_ID/locations/LOCATION/glossaries/GLOSSARY_ID",
    "updateTermRequest": {
      "term": {
        "name": "projects/PROJECT_ID/locations/LOCATION/glossaries/GLOSSARY_ID/terms/TERM_ID",
        "displayName": "Sample new name",
        "description": "Sample new description"
      },
      "updateMask": {
        "paths": [
          "display_name",
          "description"
        ]
      }
    },
    "justification": "JUSTIFICATION"
  }' \
  "https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/glossaries/GLOSSARY_ID:requestGlossaryChange"

Replace the following:

  • PROJECT_ID: the ID of your Google Cloud project.
  • LOCATION: the region where the glossary exists, such as us-central1.
  • GLOSSARY_ID: the ID of the parent glossary.
  • TERM_ID: the ID of the target term you want to update.
  • JUSTIFICATION: an explanation of why you're proposing the change.

The service returns a response containing the resource name of the change request. The system logs a new change request and notifies the approver.

Delete a glossary term

Console

Follow these steps to request deleting a term:

  1. In the Google Cloud console, go to the Knowledge Catalog Glossaries page.

    Go to Glossaries

  2. Select the glossary that includes the term you want to delete.

  3. Click the term name to open the Term details pane.

  4. Click Delete.

  5. Click Submit for review. Some sections might require that you provide additional justification before you can submit the request. Provide the justification and click Proceed to Submit Changes.

The system logs a new change request and notifies the approver. You can track the request progress on the Governance Workflows page under the My Requests tab.

REST

To request deleting a glossary term, use the glossaries.requestGlossaryChange method:

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "projects/PROJECT_ID/locations/LOCATION/glossaries/GLOSSARY_ID",
    "deleteTermRequest": {
      "name": "projects/PROJECT_ID/locations/LOCATION/glossaries/GLOSSARY_ID/terms/TERM_ID"
    },
    "justification": "JUSTIFICATION"
  }' \
  "https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/glossaries/GLOSSARY_ID:requestGlossaryChange"

Replace the following:

  • PROJECT_ID: the ID of your Google Cloud project.
  • LOCATION: the region where the glossary exists, such as us-central1.
  • GLOSSARY_ID: the ID of the parent glossary.
  • TERM_ID: the ID of the target term you want to delete.
  • JUSTIFICATION: an explanation of why you're proposing the change.

The service returns a RequestGlossaryChangeResponse that contains the resource name of the ChangeRequest.The system logs a new change request and notifies the approver.

Request changes for an entry

If you don't have direct write access to create, modify, or delete a Knowledge Catalog entry, you can request such a change using governance workflows.

Create an entry

Console

Follow these steps to request creating an entry:

  1. In the Google Cloud console, go to the Knowledge Catalog Metadata types page.

    Go to Metadata types

  2. Click the Entry groups tab.

  3. Select the entry group in which you want to create an entry, and then click Create entry.

  4. Enter an ID and display name for the entry.

  5. Select an entry type.

  6. Optional: Provide aspect details or add a description.

  7. Click Submit for review. Some sections might require that you provide additional justification before you can submit the request. Provide the justification and click Proceed to Submit Changes.

The system logs a new change request and notifies the approver. You can track the request progress on the Governance Workflows page under the My Requests tab.

REST

To request creating an entry, use the entryGroups.requestCatalogChange method:

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID",
    "createEntryRequest": {
      "parent": "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID",
      "entryId": "sample-entry-id",
      "entry": {
        "entryType": "projects/PROJECT_ID/locations/LOCATION/entryTypes/ENTRY_TYPE_ID",
        "entrySource": {
          "displayName": "Sample entry name",
          "description": "Sample entry description"
        }
      }
    },
    "justification": "JUSTIFICATION"
  }' \
  "https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID:requestCatalogChange"

Replace the following:

  • PROJECT_ID: the ID of your Google Cloud project.
  • LOCATION: the region where the entry group exists, such as us-central1.
  • ENTRY_GROUP_ID: the ID of the parent entry group.
  • ENTRY_TYPE_ID: the ID of the entry type.
  • JUSTIFICATION: an explanation of why you're proposing the change.

The service returns a response containing the resource name of the change request. The system logs a new change request and notifies the approver.

Update an entry

Console

Follow these steps to request updates for an entry:

  1. In the Google Cloud console, go to the Knowledge Catalog Search or Catalog page.

Go to Search

  1. Search for and select the entry you want to update.
  2. Click the entry to open the Entry details page.
  3. Click Add next to the section you want to update.
  4. Update the section.
  5. Click Submit for review. Some sections might require that you provide additional justification before you can submit the request. Provide the justification and click Proceed to Submit Changes.

The system logs a new change request and notifies the approver. You can track the request progress on the Governance Workflows page under the My requests tab.

REST

To request an update to an entry source display name and description, use the entryGroups.requestCatalogChange method:

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID",
    "updateEntryRequest": {
      "entry": {
        "name": "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID/entries/ENTRY_ID",
        "entrySource": {
          "displayName": "Sample new name",
          "description": "Sample new description"
        }
      },
      "updateMask": {
        "paths": [
          "entry_source.display_name",
          "entry_source.description"
        ]
      }
    },
    "justification": "JUSTIFICATION"
  }' \
  "https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID:requestCatalogChange"

Replace the following:

  • PROJECT_ID: the ID of your Google Cloud project.
  • LOCATION: the region where the entry group exists, such as us-central1.
  • ENTRY_GROUP_ID: the ID of the parent entry group.
  • ENTRY_ID: the ID of the target entry.
  • JUSTIFICATION: an explanation of why you're proposing the change.

The service returns a response containing the resource name of the change request. The system logs a new change request and notifies the approver.

Delete an entry

Console

Follow these steps to request deleting an entry:

  1. In the Google Cloud console, go to the Knowledge Catalog Search or Catalog page.

Go to Search

  1. Search for and select the entry you want to delete.
  2. Click the entry to open the Entry details page.
  3. Click Delete.
  4. Click Submit for review. Some sections might require that you provide additional justification before you can submit the request. Provide the justification and click Proceed to Submit Changes.

The system logs a new change request and notifies the approver. You can track the request progress on the Governance Workflows page under the My Requests tab.

REST

To request deleting an entry, use the entryGroups.requestCatalogChange method:

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID",
    "deleteEntryRequest": {
      "name": "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID/entries/ENTRY_ID"
    },
    "justification": "JUSTIFICATION"
  }' \
  "https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID:requestCatalogChange"

Replace the following:

  • PROJECT_ID: the ID of your Google Cloud project.
  • LOCATION: the region where the entry group exists, such as us-central1.
  • ENTRY_GROUP_ID: the ID of the parent entry group.
  • ENTRY_ID: the ID of the target entry you want to delete.
  • JUSTIFICATION: an explanation of why you're proposing the change.

The service returns a response containing the resource name of the change request. The system logs a new change request and notifies the approver.

Update an aspect

Console

Follow these steps to request updates to an aspect:

  1. In the Google Cloud console, go to the Knowledge Catalog Search page.

Go to Search

  1. Search for and select the entry you want to request the change for.
  2. Click the entry to open the Entry details page.
  3. Go to the Aspects section and click Add.
  4. Provide aspect details.
  5. Optional: Provide the justification for your change.
  6. Click Submit for review.

The system logs a new change request and notifies the approver. You can track the request progress on the Governance Workflows page under the My Requests tab.

REST

To request attaching or updating a Contacts aspect on an entry, use the entryGroups.requestCatalogChange method:

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID",
    "updateEntryRequest": {
      "entry": {
        "name": "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID/entries/ENTRY_ID",
        "aspects": {
          "dataplex-types.global.contacts": {
            "data": {
              "identities": [
                {
                  "role": "Data Steward",
                  "name": "Dana",
                  "id": "dana@example.com"
                }
              ]
            }
          }
        }
      },
      "updateMask": {
        "paths": [
          "aspects"
        ]
      },
      "aspectKeys": [
        "dataplex-types.global.contacts"
      ]
    },
    "justification": "JUSTIFICATION"
  }' \
  "https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID:requestCatalogChange"

Replace the following:

  • PROJECT_ID: the ID of your Google Cloud project.
  • LOCATION: the region where the entry group exists, such as us-central1.
  • ENTRY_GROUP_ID: the ID of the parent entry group.
  • ENTRY_ID: the ID of the target entry.
  • JUSTIFICATION: an explanation of why you're proposing the change.

The service returns a response containing the resource name of the change request. The system logs a new change request and notifies the approver.

Create an entry link

Console

Follow these steps to request creating an entry link—for example, to attach a glossary term:

  1. In the Google Cloud console, go to the Knowledge Catalog Search page.

    Go to Search

  2. Search for and select the data asset entry that you want to link a term to.

  3. On the entry details page, do one of the following:

    • To link a term to the entry, on the Details tab, in the Glossary terms section, click Add.
    • To link a term to a column, on the Schema tab, select the column and click Add business term.
  4. Search for and select the term to link.

  5. Optional: Provide a justification for your change.

  6. Click Submit for review.

The system logs a new change request and notifies the approver. You can track the request progress on the Governance Workflows page under the My Requests tab.

REST

To request creating a definition link between a glossary term and a data asset entry, use the entryGroups.requestCatalogChange method:

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID",
    "createEntryLinkRequest": {
      "parent": "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID",
      "entryLinkId": "sample-definition-link",
      "entryLink": {
        "entryLinkType": "projects/dataplex-types/locations/global/entryLinkTypes/definition",
        "entryReferences": [
          {
            "name": "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID/entries/ENTRY_ID",
            "type": "SOURCE"
          },
          {
            "name": "projects/PROJECT_ID/locations/global/entryGroups/@dataplex/entries/projects/PROJECT_ID/locations/global/glossaries/GLOSSARY_ID/terms/TERM_ID",
            "type": "TARGET"
          }
        ]
      }
    },
    "justification": "JUSTIFICATION"
  }' \
  "https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID:requestCatalogChange"

Replace the following:

  • PROJECT_ID: the ID of your Google Cloud project.
  • LOCATION: the region where the entry group exists, such as us-central1.
  • ENTRY_GROUP_ID: the ID of the parent entry group.
  • ENTRY_ID: the ID of the target entry.
  • GLOSSARY_ID: the ID of the glossary containing the term.
  • TERM_ID: the ID of the glossary term.
  • JUSTIFICATION: an explanation of why you're proposing the change.

The service returns a response containing the resource name of the change request. The system logs a new change request and notifies the approver.

Delete an entry link

Console

Follow these steps to request deleting an entry link—for example, to remove an attached glossary term:

  1. In the Google Cloud console, go to the Knowledge Catalog Search page.

    Go to Search

  2. Search for and select the data asset entry from which you want to remove a linked term.

  3. On the entry details page, do one of the following:

    • To remove a term from the entry, on the Details tab, in the Glossary terms section, click the term, and then click Remove.
    • To remove a term from a column, on the Schema tab, click Remove next to the term.
  4. Optional: Provide a justification for your change.

  5. Click Submit for review.

The system logs a new change request and notifies the approver. You can track the request progress on the Governance Workflows page under the My Requests tab.

REST

To request deleting an entry link between a glossary term and a data asset entry, use the entryGroups.requestCatalogChange method:

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID",
    "deleteEntryLinkRequest": {
      "name": "projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID/entryLinks/ENTRY_LINK_ID"
    },
    "justification": "JUSTIFICATION"
  }' \
  "https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID:requestCatalogChange"

Replace the following:

  • PROJECT_ID: the ID of your Google Cloud project.
  • LOCATION: the region where the entry group exists, such as us-central1.
  • ENTRY_GROUP_ID: the ID of the parent entry group.
  • ENTRY_LINK_ID: the ID of the target entry link you want to delete.
  • JUSTIFICATION: an explanation of why you're proposing the change.

The service returns a response containing the resource name of the change request. The system logs a new change request and notifies the approver.

What's next