yujunjun/datahub
2
0
Fork 0
mirror of https://github.com/datahub-project/datahub.git synced 2025-06-27 05:03:31 +00:00
Code Issues Packages Projects Releases Wiki Activity

fix(docs): Update proposals docs (#13800)

Browse Source 
Co-authored-by: John Joyce <john@acryl.io>
This commit is contained in:
Saketh Varma 2025-06-18 14:49:57 -06:00 committed by GitHub
parent ee7adcc1b4
commit bb1a593e2a
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 261 additions and 93 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

354
docs/managed-datahub/approval-workflows.md
View File

@ -1,14 +1,53 @@
import FeatureAvailability from '@site/src/components/FeatureAvailability';
# Approval Workflows
# Change Proposals & Approval Workflows
<FeatureAvailability saasOnly />
## Overview
Keeping all your metadata properly classified can be hard work when you only have a limited number of trusted data stewards. With DataHub Cloud, you can source proposals of Tags and Glossary Terms associated to datasets or dataset columns. These proposals may come from users with limited context or programatic processes using hueristics. Then, data stewards and data owners can go through them and only approve proposals they consider correct. This reduces the burden of your stewards and owners while increasing coverage.
Keeping your data organized can be hard work when you have a limited number of data owners. With DataHub Cloud, you can crowdsource metadata completion using change proposals. Change Proposals enable data users to suggest Tags, Terms, Domains, Owners, Descriptions, and even Structured Properties to be added to data assets. Once a change proposal is raised, data owners and stewards can review change proposals, approving or denying these suggestion.
Approval workflows also cover the Business Glossary itself. This allows you to source Glossary Terms and Glossary Term description changes from across your organization while limiting who has final control over what gets in.
## Permissions
### Creating Proposals
To create proposals on assets, users need to have the following resource privileges:
- `Propose Tags`
- `Propose Glossary Terms`
- `Propose Owners`
- `Propose Domain`
- `Propose Properties`
- `Propose Description`
- `Propose Dataset Column Tags`
- `Propose Dataset Column Glossary Terms`
- `Propose Dataset Column Structured Properties`
- `Propose Dataset Column Descriptions`
To create proposals to change the Business Glossary, users need to have the following platform privileges:
- `Propose Create Glossary Term`
- `Propose Create Glossary Node (Term Group)`
Which are granted by default using the **Reader**, **Editor**, and **Admin** roles by default.
### Reviewing Proposals
To review proposals for an asset, users need to have the following resource privileges:
- `Manage Tag Proposals`
- `Manage Glossary Term Proposals`
- `Manage Property Proposals`
- `Manage Domain Proposals`
- `Manage Owner Proposals`
- `Manage Description Proposals`
To review proposals to change the Business Glossary, users need to have the following platform privileges:
- `Manage Glossaries`
Which are granted by default **Editor** and **Admin** roles.
## Using Approval Workflows
@ -16,67 +55,143 @@ Approval workflows also cover the Business Glossary itself. This allows you to s
1. When adding a Tag or Glossary Term to a column or entity, you will see a propose button.
<p align="center">
<img width="70%" src="https://raw.githubusercontent.com/datahub-project/static-assets/main/imgs/propose_term_on_dataset.png"/>
<p align="left">
<img width="70%" src="https://raw.githubusercontent.com/datahub-project/static-assets/main/imgs/proposals/propose_term_on_dataset.png"/>
</p>
2. After proposing the Glossary Term, you will see it appear in a proposed state.
<p align="center">
<img width="70%" src="https://raw.githubusercontent.com/datahub-project/static-assets/main/imgs/propsed_term_on_dataset.png"/>
<p align="left">
<img width="70%" src="https://raw.githubusercontent.com/datahub-project/static-assets/main/imgs/proposals/proposed_term_on_dataset.png"/>
</p>
3. This proposal will be sent to the inbox of Admins with proposal permissions and data owners.
3. This proposal will be sent to the inbox of reviewers.
<p align="center">
<img width="70%" src="https://raw.githubusercontent.com/datahub-project/static-assets/main/imgs/proposed_term_to_dataset_in_inbox.png"/>
<p align="left">
<img width="70%" src="https://raw.githubusercontent.com/datahub-project/static-assets/main/imgs/proposals/proposed_term_to_dataset_in_inbox.png"/>
</p>
4. From there, they can choose to either accept or reject the proposal. A full log of all accepted or rejected proposals is kept for each user.
### Proposing Owners
1. When adding an Owner to an entity, you will see a propose button.
<p align="left">
<img width="70%" src="https://raw.githubusercontent.com/datahub-project/static-assets/main/imgs/proposals/propose_owner_on_dataset.png"/>
</p>
2. After proposing the Owner(s), you will see the owner(s) appear in a proposed state.
<p align="left">
<img width="70%" src="https://raw.githubusercontent.com/datahub-project/static-assets/main/imgs/proposals/proposed_owner_on_dataset.png"/>
</p>
3. This proposal will be sent to the inbox of reviewers.
<p align="left">
<img width="70%" src="https://raw.githubusercontent.com/datahub-project/static-assets/main/imgs/proposals/proposed_owner_to_dataset_in_inbox.png"/>
</p>
4. From there, they can choose to either accept or reject the proposal. A full log of all accepted or rejected proposals is kept for each user.
### Proposing Domain
1. When adding a Domain to an entity, you will see a propose button.
<p align="left">
<img width="70%" src="https://raw.githubusercontent.com/datahub-project/static-assets/main/imgs/proposals/propose_domain_on_dataset.png"/>
</p>
2. After proposing the Domain, you will see the Domain appear in a proposed state.
<p align="left">
<img width="70%" src="https://raw.githubusercontent.com/datahub-project/static-assets/main/imgs/proposals/proposed_domain_on_dataset.png"/>
</p>
3. This proposal will be sent to the inbox of reviewers.
<p align="left">
<img width="70%" src="https://raw.githubusercontent.com/datahub-project/static-assets/main/imgs/proposals/proposed_domain_to_dataset_in_inbox.png"/>
</p>
4. From there, they can choose to either accept or reject the proposal. A full log of all accepted or rejected proposals is kept for each user.
### Proposing Structured Properties
1. When adding a Structured property to a column or an entity, you will see a propose button.
<p align="left">
<img width="70%" src="https://raw.githubusercontent.com/datahub-project/static-assets/main/imgs/proposals/propose_property_on_dataset.png"/>
</p>
2. After proposing the Structured Properties, you will see them appear in a proposed state.
<p align="left">
<img width="70%" src="https://raw.githubusercontent.com/datahub-project/static-assets/main/imgs/proposals/proposed_property_on_dataset.png"/>
</p>
3. This proposal will be sent to the inbox of reviewers.
<p align="left">
<img width="70%" src="https://raw.githubusercontent.com/datahub-project/static-assets/main/imgs/proposals/proposed_property_to_dataset_in_inbox.png"/>
</p>
4. From there, they can choose to either accept or reject the proposal. A full log of all accepted or rejected proposals is kept for each user.
### Proposing Documentation or Description Updates
1. When updating the documentation of any entity, or description of a dataset column, you can click the propose button
2. This proposal will be sent to the inbox of reviewers.
<p align="left">
<img width="70%" src="https://raw.githubusercontent.com/datahub-project/static-assets/main/imgs/proposals/inbox_with_description_proposal.png"/>
</p>
3. From there, they can choose to either accept or reject the proposal.
### Proposing additions to your Business Glossary
1. Navigate to your glossary by going to the Govern menu in the top right and selecting Glossary.
2. Click the plus button to create a new Glossary Term. From that menu, select Propose.
<p align="center">
<img width="70%" src="https://raw.githubusercontent.com/datahub-project/static-assets/main/imgs/proposing_new_glossary_term.png"/>
<p align="left">
<img width="70%" src="https://raw.githubusercontent.com/datahub-project/static-assets/main/imgs/proposals/proposing_new_glossary_term.png"/>
</p>
3. This proposal will be sent to the inbox of Admins with proposal permissions and data owners.
3. This proposal will be sent to the inbox of reviewers.
<p align="center">
<img width="70%" src="https://raw.githubusercontent.com/datahub-project/static-assets/main/imgs/inbox_with_new_glossary_proposal.png"/>
<p align="left">
<img width="70%" src="https://raw.githubusercontent.com/datahub-project/static-assets/main/imgs/proposals/inbox_with_new_glossary_proposal.png"/>
</p>
4. From there, they can choose to either accept or reject the proposal. A full log of all accepted or rejected proposals is kept for each user.
### Proposing Glossary Term Description Updates
### Reviewing Proposals
1. When updating the description of a Glossary Term, click propse after making your change.
Proposals will be visible inside your **Task Center**, which is accessible via the navigation sidebar. From the task center, you can choose to accept or deny proposals sourced for assets you are responsible for.
<p align="center">
<img width="70%" src="https://raw.githubusercontent.com/datahub-project/static-assets/main/imgs/propose_glossary_description_change.png"/>
</p>
## Change Proposal Notifications
2. This proposal will be sent to the inbox of Admins with proposal permissions and data owners.
You can enable notifications in the following scenarios:
<p align="center">
<img width="70%" src="https://raw.githubusercontent.com/datahub-project/static-assets/main/imgs/inbox_with_description_proposal.png"/>
</p>
- A proposal you raised is approved or denied
- You are assigned to a new change proposal
- A proposal you are assigned to is approved or denied
3. From there, they can choose to either accept or reject the proposal.
Via **Slack** and **Email**.
## Proposing Programatically
To enable notifications, navigate to **Settings > My Notifications**.
DataHub exposes a GraphQL API for proposing Tags and Glossary Terms.
## Creating Proposals via API
At a high level, callers of this API will be required to provide the following details:
DataHub exposes a GraphQL API for each type of change proposal. At a high level, callers of this API will be required to provide the following details:
1. A unique identifier for the target Metadata Entity (URN)
2. An optional sub-resource identifier which designates a sub-resource to attach the Tag or Glossary Term to. for example reference to a particular "field" within a Dataset.
3. A unique identifier for the Tag or Glossary Term they wish to propose (URN)
2. An optional sub-resource identifier which designates a sub-resource to attach the Tag, Glossary Term, owner, domain or Structured property to. For example reference to a particular "field" within a Dataset.
3. A unique identifier for the Tag/Glossary Term/Owner/Domain/Structured property they wish to propose (URN)
In the following sections, we will describe how to construct each of these items and use the DataHub GraphQL API to submit Tag or Glossary Term proposals.
@ -89,9 +204,9 @@ Inside DataHub, each Metadata Entity is uniquely identified by a Universal Resou
Specific Metadata Entity types have additional sub-resources to which Tags may be applied.
Today, this only applies for Dataset Metadata Entities, which have a "fields" sub-resource. In this case, the `subResource` value would be the field path for the schema field.
#### Finding a Tag or Glossary Term Identifier
#### Finding an Identifier for Tag/Glossary Term/Owner/Domain/Structure property
Tags and Glossary Terms are also uniquely identified by an URN.
All of these are uniquely identified by an URN.
Tag URNs have the following format:
`urn:li:tag:<id>`
@ -99,96 +214,149 @@ Tag URNs have the following format:
Glossary Term URNs have the following format:
`urn:li:glossaryTerm:<id>`
These full identifiers can be copied from the entity pages of the Tag or Glossary Term.
Domain URNs have the following format:
`urn:li:domain:<id>`
<p align="center">
<img width="70%" src="https://raw.githubusercontent.com/datahub-project/static-assets/main/imgs/copy_urn_from_entity.png"/>
</p>
Owner URNs have the following format:
`urn:li:corpuser:<id>` or `urn:li:corpGroup:<id>`
Structured Property URNs have the following format:
`urn:li:structuredProperty:<id>`
These identifiers can be copied from the url of the corresponding entity pages.
#### Issuing a GraphQL Query
Once we've constructed an Entity URN, any relevant sub-resource identifiers, and a Tag or Term URN, we're ready to propose! To do so, we'll use the DataHub GraphQL API.
Once we've constructed an Entity URN, any relevant sub-resource identifiers, we're ready to propose! To do so, we'll use the DataHub GraphQL API.
In particular, we'll be using the proposeTag, proposeGlossaryTerm, and proposeUpdateDescription Mutations, which have the following interface:
In particular, we'll be using the proposeTags, proposeTerms, proposeDomain, proposeOwners, proposeStructuredProperties, proposeCreateGlossaryTerm, proposeCreateGlossaryNode, proposeDataContract, and proposeUpdateDescription Mutations, which have the following interface:
```
type Mutation {
proposeTerm(input: TermAssociationInput!): String! # Returns Proposal URN.
proposeTags(input: ProposeTagsInput!): String! # Returns Proposal URN.
}
input TermAssociationInput {
resourceUrn: String! # Required. e.g. "urn:li:dataset:(...)"
subResource: String # Optional. e.g. "fieldName"
subResourceType: String # Optional. "DATASET_FIELD" for dataset fields
term: String! # Required. e.g. "urn:li:tag:Marketing"
input ProposeTagsInput {
description: String # Optional note explaining the proposal
resourceUrn: String! # Required. e.g. "urn:li:dataset:(...)"
subResource: String # Optional. e.g. "fieldName"
subResourceType: String # Optional. "DATASET_FIELD" for dataset fields
tagUrns: [String!]! # Required. e.g. ["urn:li:tag:Marketing"]
}
```
```
type Mutation {
proposeTag(input: TagAssociationInput!): String! # Returns Proposal URN.
proposeTerms(input: ProposeTermsInput!): String! # Returns Proposal URN.
}
input TagAssociationInput {
resourceUrn: String! # Required. e.g. "urn:li:dataset:(...)" subResource: String # Optional. e.g. "fieldName"
subResourceType: String # Optional. "DATASET_FIELD" for dataset fields
tagUrn: String! # Required. e.g. "urn:li:tag:Marketing"
input ProposeTermsInput {
description: String # Optional note explaining the proposal
resourceUrn: String! # Required. e.g. "urn:li:dataset:(...)"
subResource: String # Optional. e.g. "fieldName"
subResourceType: String # Optional. "DATASET_FIELD" for dataset fields
termUrns: [String!]! # Required. e.g. ["urn:li:glossaryTerm:Marketing"]
}
```
```
type Mutation {
proposeDomain(input: ProposeDomainInput!): String! # Returns Proposal URN.
}
input ProposeDomainInput {
description: String # Optional note explaining the proposal
resourceUrn: String! # Required. e.g. "urn:li:dataset:(...)"
domainUrn: String! # Required. e.g. ["urn:li:domain:Marketing"]
}
```
```
type Mutation {
proposeOwners(input: ProposeOwnersInput!): String! # Returns Proposal URN.
}
input ProposeOwnersInput {
description: String # Optional note explaining the proposal
resourceUrn: String! # Required. e.g. "urn:li:dataset:(...)"
owners: [OwnerInput!]! # Required
}
input OwnerInput {
ownerUrn: String! # Required. e.g. "urn:li:owner:(...)"
ownerEntityType: OwnerEntityType! # Required. e.g. "CORP_USER"
type: OwnershipType # Optional
ownershipTypeUrn: String # Optional. The urn of the ownership type entity.
}
```
```
type Mutation {
proposeStructuredProperties(input: ProposeStructuredPropertiesInput!): String! # Returns Proposal URN.
}
input ProposeStructuredPropertiesInput {
description: String # Optional note explaining the proposal
resourceUrn: String! # Required. e.g. "urn:li:dataset:(...)"
subResource: String # Optional. e.g. "fieldName"
subResourceType: String # Optional. "DATASET_FIELD" for dataset fields
structuredProperties: [StructuredPropertyInputParams!]!
}
input StructuredPropertyInputParams {
structuredPropertyUrn: String! # Required. e.g. "urn:li:structuredProperty:(...)"
values: [PropertyValueInput!]! # Required. e.g. "{ stringValue: ''}"
}
```
```
type Mutation {
proposeCreateGlossaryTerm(input: CreateGlossaryEntityInput!): Boolean
}
input CreateGlossaryEntityInput {
id: String # Optional. Otherwise uuid is generated
name: String! # Required. e.g. "Marketing"
description: String # Optional
parentNode: String # Optional. e.g. "urn:li:glossaryNode:(...)"
proposalNote: String # Optional. Context for the proposal
}
```
```
type Mutation {
proposeCreateGlossaryNode(input: CreateGlossaryEntityInput!): Boolean
}
input CreateGlossaryEntityInput {
id: String # Optional. Otherwise uuid is generated
name: String! # Required. e.g. "Marketing"
description: String # Optional
parentNode: String # Optional. e.g. "urn:li:glossaryNode:(...)"
proposalNote: String # Optional. Context for the proposal
}
```
```
mutation proposeUpdateDescription($input: DescriptionUpdateInput!) {
proposeUpdateDescription(input: $input)
proposeUpdateDescription(input: $input)
}
"""
Currently supports updates to Glossary Term descriptions only
Currently supports DatasetField descriptions only
"""
input DescriptionUpdateInput {
description: String! # the new description
resourceUrn: String!
subResourceType: SubResourceType
subResource: String
description: String! # the new description
resourceUrn: String!
subResourceType: SubResourceType
subResource: String
proposalNote: String # Context for the proposal
}
```
## Additional Resources
## FAQ
### Permissions
**1. My colleagues have created some proposals, but I'm not seeing this in my Task Center. Why not?**
To create & manage metadata proposals, certain access policies or roles are required.
#### Privileges for Creating Proposals
To create a new proposal one of these Metadata privileges are required. All roles have these priveleges by default.
- Propose Tags - Allows to propose tags at the Entity level
- Propose Dataset Column Tags - Allows to propose tags at the Dataset Field level
- Propose Glossary Terms - Allows to propose terms at the Entity level
- Propose Dataset Column Glossary Terms - Allows to propose terms at the Dataset Field level
To be able to see the Proposals Tab you need the <strong>"View Metadata Proposals"</strong> PLATFORM privilege
#### Privileges for Managing Proposals
To be able to approve or deny proposals you need one of the following Metadata privileges. `Admin` and `Editor` roles already have these by default.
- Manage Tag Proposals
- Manage Glossary Term Proposals
- Manage Dataset Column Tag Proposals
- Manage Dataset Column Term Proposals
These map directly to the 4 privileges for doing the proposals.
To be able to approve or deny proposals to the glossary itself, you just need one permission:
- Manage Glossaries
### Videos
<p align="center">
<iframe width="560" height="315" src="https://www.loom.com/embed/1e450bde6b544653bbbf7f9762d1b157" title="Approval Workflows" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
</p>
Most likely, this means your privileges are not configured properly. If you are a DataHub Admin, navigate to **Settings > Permissions** to edit your roles and policies to ensure you have the privileges listed in the **Permissions** section above.