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.
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:
-
Request metadata changes:
Dataplex Catalog Viewer (
roles/dataplex.catalogViewer) -
Approve metadata changes:
- Dataplex Workflow Approver (
roles/dataplex.workflowApprover) - Dataplex Catalog Editor (
roles/dataplex.catalogEditor) - Dataplex Entry Owner (
roles/dataplex.entryOwner)
- Dataplex Workflow Approver (
-
Administer governance workflows:
Dataplex Workflow Admin (
roles/dataplex.workflowAdmin)
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:
In the Google Cloud console, go to the Knowledge Catalog Glossaries page.
Select the glossary in which you want to create a category, and then click Create category.
Enter a Display name for the category.
Optional: In the Labels section, add labels for the glossary.
Optional: In the Justification section, provide the approver with a reason for your change.
In the Advanced Settings section, you can edit the Category ID if you want to change the auto-generated ID.
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 asus-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:
In the Google Cloud console, go to the Knowledge Catalog Glossaries page.
Select the glossary that includes the category you want to update.
Click the category name to open the Category details pane.
To add or update category details, click Add or Edit next to the section that you want to update.
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 asus-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:
In the Google Cloud console, go to the Knowledge Catalog Glossaries page.
Expand the glossary and click the category that you want to delete.
In the Category details pane, select Delete from the menu.
Optional: In the Justification section, provide the approver with the reason for your change.
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 asus-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:
In the Google Cloud console, go to the Knowledge Catalog Glossaries page.
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.
Enter a Display name for the category.
Optional: In the Labels section, add labels for the term.
Optional: In the Justification section, provide the approver with a reason for your change.
In the Advanced Settings section, you can edit the Term ID if you want to change the auto-generated ID.
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 asus-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:
In the Google Cloud console, go to the Knowledge Catalog Glossaries page.
Select the glossary that includes the term you want to update.
Click the term name to open the Term details pane.
Add or update term details by clicking Add or Edit next to the section you want to update.
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 asus-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:
In the Google Cloud console, go to the Knowledge Catalog Glossaries page.
Select the glossary that includes the term you want to delete.
Click the term name to open the Term details pane.
Click Delete.
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 asus-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:
In the Google Cloud console, go to the Knowledge Catalog Metadata types page.
Click the Entry groups tab.
Select the entry group in which you want to create an entry, and then click Create entry.
Enter an ID and display name for the entry.
Select an entry type.
Optional: Provide aspect details or add a description.
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 asus-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:
- In the Google Cloud console, go to the Knowledge Catalog Search or Catalog page.
- Search for and select the entry you want to update.
- Click the entry to open the Entry details page.
- Click Add next to the section you want to update.
- Update the section.
- 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 asus-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:
- In the Google Cloud console, go to the Knowledge Catalog Search or Catalog page.
- Search for and select the entry you want to delete.
- Click the entry to open the Entry details page.
- Click Delete.
- 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 asus-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:
- In the Google Cloud console, go to the Knowledge Catalog Search page.
- Search for and select the entry you want to request the change for.
- Click the entry to open the Entry details page.
- Go to the Aspects section and click Add.
- Provide aspect details.
- Optional: Provide the justification for your change.
- 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 asus-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:
In the Google Cloud console, go to the Knowledge Catalog Search page.
Search for and select the data asset entry that you want to link a term to.
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.
Search for and select the term to link.
Optional: Provide a justification for your change.
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 asus-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:
In the Google Cloud console, go to the Knowledge Catalog Search page.
Search for and select the data asset entry from which you want to remove a linked term.
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.
Optional: Provide a justification for your change.
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 asus-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
- Learn more about governance workflows
- Learn how to manage requests
- Learn more about glossaries