docs(): Adding docs for approval workflows (datahub-project#14259)

Co-authored-by: John Joyce <john@Mac-4333.lan>
Co-authored-by: John Joyce <john@Mac-4560.lan>
Co-authored-by: John Joyce <john@Mac-4605.lan>

Author: 4 people

docs-website/sidebars.js

@@ -105,9 +105,14 @@ module.exports = {
           ],
         },
         {
-          label: "Access Management",
+          label: "Data Access Workflows",
           type: "doc",
-          id: "docs/features/feature-guides/access-management",
+          id: "docs/managed-datahub/workflows/access-workflows",
+        },
+        {
+          label: "Data Access Roles",
+          type: "doc",
+          id: "docs/features/feature-guides/access-roles",
         },
         {
           label: "Automations",
@@ -415,7 +420,7 @@ module.exports = {
     },
     {
       type: "doc",
-      id: "docs/managed-datahub/approval-workflows",
+      id: "docs/managed-datahub/change-proposals",
       className: "saasOnly",
     },
     {

docs/actions/events/entity-change-event.md

@@ -603,3 +603,109 @@ This event is emitted when a structured property association is proposed for an
   }
 }
 ```
+
+### Approval Workflow Request Create Event
+
+This event is emitted when a new approval workflow form request is submitted on DataHub.
+
+Note that `parameters.fields` contains all of the form fields provided when the user originally
+submitted the approval request form. It contains a serialized JSON object that must be deserialized from string before accessing!
+
+#### Sample Event
+
+```json
+{
+  "event_type": "EntityChangeEvent_v1",
+  "event": {
+    "entityType": "actionRequest",
+    "entityUrn": "urn:li:actionRequest:88170f40-b4f5-4b05-a997-f5f680248b59",
+    "category": "LIFECYCLE",
+    "operation": "CREATE",
+    "auditStamp": {
+      "time": 1753829419490,
+      "actor": "urn:li:corpuser:admin"
+    },
+    "version": 0,
+    "parameters": {
+      "actorUrn": "urn:li:corpuser:admin",
+      "actionRequestType": "WORKFLOW_FORM_REQUEST",
+      "workflowUrn": "urn:li:actionWorkflow:7a6e7a24-7525-4f1e-8d9b-08ba562399d0",
+      "expiresAtMs": 1756680611743,
+      "fields": "{\"reason\":[\"Building Tableau Dashboard Q2\"],\"privileges\":[\"SELECT\"],\"projects\":[\"Orders Dashboard Q2\"],\"tags\":[\"urn:li:tag:__default_gold\"]}",
+      "workflowId": "7a6e7a24-7525-4f1e-8d9b-08ba562399d0"
+    }
+  }
+}
+```
+
+### Approval Workflow Request Step Complete Event
+
+This event is emitted when an approval step within a workflow request has been completed (approved, rejected, or requires more information).
+
+Note that `parameters.fields` contains all of the form fields provided when the user originally
+submitted the approval request form. It contains a serialized JSON object that must be deserialized from string before accessing!
+
+#### Sample Event
+
+```json
+{
+  "event_type": "EntityChangeEvent_v1",
+  "event": {
+    "entityType": "actionRequest",
+    "entityUrn": "urn:li:actionRequest:ce424fff-7fab-4731-b106-fab9d69238da",
+    "category": "LIFECYCLE",
+    "operation": "MODIFY",
+    "auditStamp": {
+      "time": 1753829625133,
+      "actor": "urn:li:corpuser:admin"
+    },
+    "version": 0,
+    "parameters": {
+      "actorUrn": "urn:li:corpuser:admin",
+      "actionRequestType": "WORKFLOW_FORM_REQUEST",
+      "stepId": "approval-step-2",
+      "workflowUrn": "urn:li:actionWorkflow:7a6e7a24-7525-4f1e-8d9b-08ba562399d0",
+      "expiresAtMs": 1754002407730,
+      "stepResult": "ACCEPTED",
+      "fields": "{\"reason\":[\"Test\"],\"privileges\":[\"SELECT\"],\"tags\":[\"urn:li:tag:NeedsDocumentation\"]}",
+      "workflowId": "7a6e7a24-7525-4f1e-8d9b-08ba562399d0"
+    }
+  }
+}
+```
+
+### Approval Workflow Request Complete Event
+
+This event is emitted when an approval workflow request has been fully completed - either approved through all steps or rejected at any step.
+
+Note that `parameters.fields` contains all of the form fields provided when the user originally
+submitted the approval request form. It contains a serialized JSON object that must be deserialized from string before accessing!
+
+#### Sample Event
+
+```json
+{
+  "event_type": "EntityChangeEvent_v1",
+  "event": {
+    "entityType": "actionRequest",
+    "entityUrn": "urn:li:actionRequest:553595ec-2295-4970-89a4-bb7d02e691c0",
+    "category": "LIFECYCLE",
+    "operation": "COMPLETED",
+    "auditStamp": {
+      "time": 1753829954539,
+      "actor": "urn:li:corpuser:admin"
+    },
+    "version": 0,
+    "parameters": {
+      "result": "ACCEPTED",
+      "actorUrn": "urn:li:corpuser:admin",
+      "actionRequestType": "WORKFLOW_FORM_REQUEST",
+      "workflowUrn": "urn:li:actionWorkflow:7a6e7a24-7525-4f1e-8d9b-08ba562399d0",
+      "expiresAtMs": 1756335474418,
+      "fields": "{\"reason\":[\"test\"],\"privileges\":[\"SELECT\"],\"projects\":[\"test\"],\"tags\":[\"urn:li:tag:NeedsDocumentation\"]}",
+      "operation": "COMPLETE",
+      "workflowId": "7a6e7a24-7525-4f1e-8d9b-08ba562399d0"
+    }
+  }
+}
+```

docs/automations/ai-term-suggestion.md

@@ -18,7 +18,7 @@ This automation can:
 
 - Automatically suggests glossary terms for tables and columns.
 - Goes beyond a predefined set of terms and works with your business glossary.
-- Generates [proposals](../managed-datahub/approval-workflows.md) for owners to review, or can automatically add terms to tables/columns.
+- Generates [proposals](../managed-datahub/change-proposals.md) for owners to review, or can automatically add terms to tables/columns.
 - Automatically adjusts to human-provided feedback and curation (coming soon).
 
 ## Prerequisites

docs/deploy/environment-vars.md

@@ -465,7 +465,7 @@ Reference Links:
 
 Reference Links:
 
-- **Access Management**: [Access Management Feature](../features/feature-guides/access-management.md)
+- **Access Management**: [Access Management Feature](../features/feature-guides/access-roles.md)
 - **Structured Properties**: [Structured Properties Overview](../features/feature-guides/properties/overview.md)
 - **Lineage Features**: [Data Lineage](../features/feature-guides/lineage.md), [UI Lineage Management](../features/feature-guides/ui-lineage.md)
 - **Compliance Forms**: [Compliance Forms Overview](../features/feature-guides/compliance-forms/overview.md)

docs/features/feature-guides/access-management.md renamed to docs/features/feature-guides/access-roles.md

@@ -2,13 +2,20 @@ import FeatureAvailability from '@site/src/components/FeatureAvailability';
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 
-# Access Management
+# Data Access Roles
 
 <FeatureAvailability/>
 
+> **Note**: This feature is under active development and subject to significant change.
+
 ## Introduction
 
-DataHub's Access Management feature allows you to associate external roles from your source systems with your data assets in DataHub. This creates a unified view of access control across your data ecosystem, helping data consumers:
+DataHub's Access Roles feature allows you to ingest external roles from your source systems with your data assets in DataHub so that users can understand which roles they need in order to access a given asset.
+
+Whereas [Data Access Workflows](../../managed-datahub/workflows/access-workflows.md) enable you to create workflows for requesting and reviewing access for tables, dashboards, etc, this feature enables users to understand the roles
+that already have access for a given asset, and redirect to an external platform to request access to the role.
+
+This creates a unified view of access control across your data ecosystem, helping data consumers:
 
 1. **Discover available access** - Find what roles are already provisioned for them across different data platforms
 2. **Request appropriate access** - Easily identify and request to join the appropriate role for the access they need

docs/managed-datahub/approval-workflows.md renamed to docs/managed-datahub/change-proposals.md

@@ -1,6 +1,6 @@
 import FeatureAvailability from '@site/src/components/FeatureAvailability';
 
-# Change Proposals & Approval Workflows
+# Change Proposals
 
 <FeatureAvailability saasOnly />
 

docs/managed-datahub/managed-datahub-overview.md

@@ -161,5 +161,5 @@ Fill out
 
 ## More Ways to Act on Metadata
 
-- [Approval Workflows](docs/managed-datahub/approval-workflows.md)
+- [Approval Workflows](docs/managed-datahub/change-proposals.md)
 - [Metadata Tests](docs/tests/metadata-tests.md) -->