From b5cf415ae5f8cac2bac80a4f4498cee7d6c633d8 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Mon, 20 Jul 2026 16:09:03 +0000 Subject: [PATCH 1/2] docs: clarify nested hierarchy modeling with Locations, Folders, and Activity rollups --- async-collaboration/activity/overview.mdx | 2 ++ key-concepts/overview.mdx | 11 +++++++++++ 2 files changed, 13 insertions(+) diff --git a/async-collaboration/activity/overview.mdx b/async-collaboration/activity/overview.mdx index 5cfe6b079..dcc758dfe 100644 --- a/async-collaboration/activity/overview.mdx +++ b/async-collaboration/activity/overview.mdx @@ -47,7 +47,9 @@ This lets you merge application-level events (deployments, escalations, status t - **Org-wide feed:** No filters. Returns all activity across every document in the organization. Useful for admin dashboards and team lead overviews. - **Per-document timeline:** Filter by `documentId` to show the full history of a single document, from first draft to final approval. Useful for inline review panels and document sidebars. +- **Cross-document rollup:** Pass multiple IDs in `documentIds` to merge the timelines of several Documents into one feed — useful for hierarchies like `Folder → Documents` or `Parent entity → Child entities`, where each child is its own Document. Resolve the descendant Documents with the [Get Folders REST API](/api-reference/rest-apis/v2/folders/get-folders) (`maxDepth` returns nested subfolders) and pass the collected IDs to `getAllActivities()`. - **Feature-scoped feed:** Filter by feature type (e.g., only Comments or only CRDT edits) to reduce noise for specific views. +- **Custom hierarchy metadata:** The subscription config does not support filtering by arbitrary custom fields. To roll up or filter by your own hierarchy fields (`entityType`, `parentEntityId`, etc.), attach them via `entityData` / `entityTargetData` on [`createActivity()`](/api-reference/sdk/api/api-methods#createactivity) and filter client-side after subscribing. ## Immutability diff --git a/key-concepts/overview.mdx b/key-concepts/overview.mdx index 1b9b15ca9..be6d9dda6 100644 --- a/key-concepts/overview.mdx +++ b/key-concepts/overview.mdx @@ -843,11 +843,22 @@ For instance: - Any user with access to the document will have access to all locations in the document. - Access controls cannot be set at the location level. - Locations automatically generate location groups in the sidebar and organizes the comments within the group. +- Locations are **flat** — a location cannot contain another location. The `id` and `locationName` fields are scoped to a single document and are not hierarchical. - The location object has these fields: - `id` (optional when `locationName` is set): A unique string or numeric identifier. An id of `0` is valid and takes precedence over `locationName`. - `locationName` (optional when `id` is set): A non-empty, human-readable name displayed in Velt components like `VeltCommentsSidebar`. It also identifies the location when `id` is omitted. - You can add any number of custom fields to the location object. +#### Modeling nested hierarchies + +Because Locations are flat, model nested product hierarchies (for example, `Style → Variant → SKU → Price`) using the resources higher in the tree: + +- **Folders and subfolders** carry the parent tree. [Folders can contain subfolders](#folders), and access cascades down the folder tree. Use one folder per parent entity (for example, one folder per Style, containing a subfolder per Variant). +- **Documents** represent the leaf collaborative surface (for example, one Document per SKU or per Sample Request). Each Document has its own activity timeline. +- **Locations** partition data within a single Document. Represent sibling sections of the same entity (for example, `prices`, `samples`, `variant-summary`) as separate Locations on that Document. Add your own hierarchy fields (`entityType`, `entityId`, `parentEntityType`, `parentEntityId`) as custom fields on the location object so your app can filter comments and activity by them client-side. +- **Roll-up queries** across the hierarchy work by passing multiple `documentIds` to [`getAllActivities()`](#subscribe-to-activities) (or the [Get Activities REST API](/api-reference/rest-apis/v2/activities/get-activities)). To get every Document under a Folder, first resolve the tree with the [Get Folders REST API](/api-reference/rest-apis/v2/folders/get-folders) using the `maxDepth` parameter, collect the descendant `documentIds`, then subscribe to activity for that list. +- **Custom activity records** created via [`createActivity()`](/api-reference/sdk/api/api-methods#createactivity) accept `entityData` and `entityTargetData` — use these to attach your own hierarchy metadata (parent IDs, entity type, etc.) to non-Velt events so the same rollups work across custom and Velt-generated activity. + ### APIs ### Frontend APIs From b4b30fca9fb7bf62cd1444e2183330cd0a5d636e Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Mon, 20 Jul 2026 16:10:56 +0000 Subject: [PATCH 2/2] docs: add SEO metadata and tighten hierarchy rollup wording --- async-collaboration/activity/overview.mdx | 1 + key-concepts/overview.mdx | 6 +++++- 2 files changed, 6 insertions(+), 1 deletion(-) diff --git a/async-collaboration/activity/overview.mdx b/async-collaboration/activity/overview.mdx index dcc758dfe..d846441bf 100644 --- a/async-collaboration/activity/overview.mdx +++ b/async-collaboration/activity/overview.mdx @@ -1,6 +1,7 @@ --- title: "Activity Logs" sidebarTitle: "Overview" +description: "Track every collaboration event—comments, reactions, recordings, CRDT edits, and custom app events—in one real-time, filterable audit timeline." --- Every collaboration event in your app, every comment, approval, edit, and review, generates a question someone eventually asks: "Who did what, and when?" Activity Logs gives you a complete, real-time record of everything that happens across your product. diff --git a/key-concepts/overview.mdx b/key-concepts/overview.mdx index be6d9dda6..a1ecf7536 100644 --- a/key-concepts/overview.mdx +++ b/key-concepts/overview.mdx @@ -1,3 +1,7 @@ +--- +title: "Key concepts: Organizations, Folders, Documents, Locations" +description: "Understand how Velt models collaborative data with Organizations, Folders, Documents, Locations, Users, and access control across your product." +--- ## Overview @@ -856,7 +860,7 @@ Because Locations are flat, model nested product hierarchies (for example, `Styl - **Folders and subfolders** carry the parent tree. [Folders can contain subfolders](#folders), and access cascades down the folder tree. Use one folder per parent entity (for example, one folder per Style, containing a subfolder per Variant). - **Documents** represent the leaf collaborative surface (for example, one Document per SKU or per Sample Request). Each Document has its own activity timeline. - **Locations** partition data within a single Document. Represent sibling sections of the same entity (for example, `prices`, `samples`, `variant-summary`) as separate Locations on that Document. Add your own hierarchy fields (`entityType`, `entityId`, `parentEntityType`, `parentEntityId`) as custom fields on the location object so your app can filter comments and activity by them client-side. -- **Roll-up queries** across the hierarchy work by passing multiple `documentIds` to [`getAllActivities()`](#subscribe-to-activities) (or the [Get Activities REST API](/api-reference/rest-apis/v2/activities/get-activities)). To get every Document under a Folder, first resolve the tree with the [Get Folders REST API](/api-reference/rest-apis/v2/folders/get-folders) using the `maxDepth` parameter, collect the descendant `documentIds`, then subscribe to activity for that list. +- **Roll-up queries** across the hierarchy work by passing multiple `documentIds` to [`getAllActivities()`](/async-collaboration/activity/setup#3-subscribe-to-activities) (or the [Get Activities REST API](/api-reference/rest-apis/v2/activities/get-activities)). To get every Document under a Folder, resolve the tree with the [Get Folders REST API](/api-reference/rest-apis/v2/folders/get-folders) using `maxDepth`. Collect the descendant `documentIds` and pass that list to your activity subscription. - **Custom activity records** created via [`createActivity()`](/api-reference/sdk/api/api-methods#createactivity) accept `entityData` and `entityTargetData` — use these to attach your own hierarchy metadata (parent IDs, entity type, etc.) to non-Velt events so the same rollups work across custom and Velt-generated activity. ### APIs