Change Proposals & Approval Workflows

Feature Availability

Self-Hosted DataHub

DataHub Cloud

Overview

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.

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

Proposing Tags and Glossary Terms

1. When adding a Tag or Glossary Term to a column or entity, you will see a propose button.

2. After proposing the Glossary Term, you will see it appear in a proposed state.

3. This proposal will be sent to the inbox of reviewers.

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.

2. After proposing the Owner(s), you will see the owner(s) appear in a proposed state.

3. This proposal will be sent to the inbox of reviewers.

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.

2. After proposing the Domain, you will see the Domain appear in a proposed state.

3. This proposal will be sent to the inbox of reviewers.

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.

2. After proposing the Structured Properties, you will see them appear in a proposed state.

3. This proposal will be sent to the inbox of reviewers.

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.

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.

3. This proposal will be sent to the inbox of reviewers.

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.

Reviewing Proposals

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.

Change Proposal Notifications

You can enable notifications in the following scenarios:

• 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

Via Slack and Email.

To enable notifications, navigate to Settings > My Notifications.

Creating Proposals via API

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, 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.

Constructing an Entity Identifier

Inside DataHub, each Metadata Entity is uniquely identified by a Universal Resource Name, or an URN. This identifier can be copied from the entity page, extracted from the API, or read from a downloaded search result. You can also use the helper methods in the datahub python library given a set of components.

Constructing a Sub-Resource Identifier

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 an Identifier for Tag/Glossary Term/Owner/Domain/Structure property

All of these are uniquely identified by an URN.

Tag URNs have the following format: urn:li:tag:<id>

Glossary Term URNs have the following format: urn:li:glossaryTerm:<id>

Domain URNs have the following format: urn:li:domain:<id>

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, we're ready to propose! To do so, we'll use the DataHub GraphQL API.

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 {
  proposeTags(input: ProposeTagsInput!): String! # Returns Proposal URN.
}

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 {
  proposeTerms(input: ProposeTermsInput!): String! # Returns Proposal URN.
}

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)
}

"""
Currently supports DatasetField descriptions only
"""
input DescriptionUpdateInput {
  description: String! # the new description
  resourceUrn: String!
  subResourceType: SubResourceType
  subResource: String
  proposalNote: String # Context for the proposal
}

FAQ

1. My colleagues have created some proposals, but I'm not seeing this in my Task Center. Why not?

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.