diff --git a/site/guide/_sidebar.yaml b/site/guide/_sidebar.yaml index 28b811a4e..821e1d0c4 100644 --- a/site/guide/_sidebar.yaml +++ b/site/guide/_sidebar.yaml @@ -153,6 +153,7 @@ website: - guide/validation/manage-artifact-types.qmd - guide/validation/manage-artifact-severities.qmd - guide/validation/manage-artifact-fields.qmd + - guide/validation/manage-artifact-segments.qmd - file: guide/validation/preparing-validation-reports.qmd contents: - guide/validation/review-documentation.qmd diff --git a/site/guide/inventory/manage-inventory-segments.qmd b/site/guide/inventory/manage-inventory-segments.qmd index fb03576f8..2ffed4932 100644 --- a/site/guide/inventory/manage-inventory-segments.qmd +++ b/site/guide/inventory/manage-inventory-segments.qmd @@ -27,6 +27,7 @@ Save a set of inventory filters as a named, reusable segment that spans every in - A segment spans every inventory record type in your organization. Record types added later are automatically in scope, so a segment never needs to be updated when your inventory grows. - Matching records are evaluated live — a segment always reflects the current state of your inventory, and users only see the matching records they have permission to view. - A segment starts as a personal [Draft]{.bubble}. Publishing it makes it available to your entire organization. +- A published segment can be opened as the scope of the Inventory page, applied as a filter rule within a record type, and used as an analytics dataset. ::: {.callout title="Note that segments differ from saved views and grouping."} - **Segments** — Named filters managed by administrators in the organization settings, reusable by everyone once published. @@ -60,6 +61,7 @@ By default, only the [{{< fa hand >}} Customer Admin]{.bubble} role can add segm - Inventory Record Type is available as a condition, so you can scope a segment to specific record types. - A segment cannot reference another segment, so Segment is not offered as a condition field here. + - Calculation and Aggregation fields can be used as conditions. They are evaluated against the stored values, which refresh in the background, and they offer the same operators as in the inventory filters, including **has error**.^[[Filter by calculated and aggregation fields](/guide/inventory/working-with-the-inventory.qmd#filter-by-calculated-and-aggregation-fields)] ::: {.callout-button .pl4 .nt2} ::: {.callout collapse="true" appearance="minimal"} @@ -101,10 +103,6 @@ Each segment shows one of the following statuses: : Segment statuses {.hover} -::: {.callout title="Note that your organization starts with an example segment."} -Every organization includes an All Inventory Records segment managed by {{< var vm.product >}}. This example segment cannot be edited or unpublished, but it can be deleted. -::: - ## Edit segments To rename a segment or update its description: @@ -135,9 +133,23 @@ Archiving and deletion of segments are permanent. - **Archive Segment** — Permanently retires the segment. An archived segment cannot be edited, published, or restored. Click **Yes, Archive Segment** to confirm. - [**Delete Segment**]{.red} — Permanently deletes the segment. The inventory records it matched are not affected. Click **Yes, Delete Segment** to confirm. +## View a segment as the inventory scope + +Once a segment is published, anyone in your organization can open it as the scope of the Inventory page and work with every matching record across inventory record types: + +1. In the left sidebar, click **{{< fa cubes >}} Inventory**. + +2. Click the page title to open the scope selector. Options are grouped under **Inventory Record Types** and **Segments**. + +3. Select a segment. + + The listing shows every matching record you have permission to view, across all record types, with the fields shared by every record type as columns plus an **Inventory Record Type** column. Filter and Group By offer those shared fields and Inventory Record Type; search, sorting, and CSV export work as usual, and the export includes the Inventory Record Type column. + +In segment scope, Manage Columns, Register, and bulk editing are not available because columns, stages, and stakeholder roles differ by record type. You can still save views: a view saved while a segment is selected is scoped to that segment and listed separately from the views of each record type.[^3] The Inventory page remembers your last selected scope. + ## Apply segments as inventory filters -Once a segment is published, anyone in your organization can filter the inventory by it: +Within a single record type's listing, a published segment can also be used as a filter rule: 1. In the left sidebar, click **{{< fa cubes >}} Inventory**. diff --git a/site/guide/reporting/_create-a-visualization.qmd b/site/guide/reporting/_create-a-visualization.qmd index 9b6749731..f21095e9d 100644 --- a/site/guide/reporting/_create-a-visualization.qmd +++ b/site/guide/reporting/_create-a-visualization.qmd @@ -29,6 +29,7 @@ a. Select a **Dataset**: - **Artifact Statuses Durations** — Days each artifact has spent in each status, across all artifact types, with `Artifact Type` as a column so you can compare or filter by type.^[[Manage artifact types](/guide/validation/manage-artifact-types.qmd)] - **Inventory Record - Dependencies** — One row per dependency between two inventory records, with the related record's ID and the dependency direction.^[[Configure record interdependencies](/guide/inventory/configure-record-interdependencies.qmd)] - **Inventory Segments - {Segment}** — Inventory records matching a published segment.^[[Manage inventory segments](/guide/inventory/manage-inventory-segments.qmd)] + - **Artifact Segments - {Segment}** — Artifacts across all artifact types matching a published segment.^[[Manage artifact segments](/guide/validation/manage-artifact-segments.qmd)] The two duration datasets return one row per record and stage, or per artifact and status, with a `Total Duration (Days)` measure you can average, sum, or take the minimum or maximum of. Time is counted in whole calendar days, the current stage or status is counted up to today, and repeat visits to the same stage or status are added together.^[Artifact status history is built from each artifact's activity log. Status changes made before per-field activity logging was introduced are counted toward the earliest status on record for that artifact.] @@ -57,6 +58,7 @@ a. Select a **Dataset**: - **Artifact Statuses Durations** — Days each artifact has spent in each status, across all [artifact types](/guide/validation/manage-artifact-types.qmd){target="_blank"}, with `Artifact Type` as a column so you can compare or filter by type. - **[Inventory Record - Dependencies](/guide/inventory/configure-record-interdependencies.qmd){target="_blank"}** — One row per dependency between two inventory records, with the related record's ID and the dependency direction. - **[Inventory Segments](/guide/inventory/manage-inventory-segments.qmd){target="_blank"} - {Segment}** — Inventory records matching a published segment. + - **[Artifact Segments](/guide/validation/manage-artifact-segments.qmd){target="_blank"} - {Segment}** — Artifacts across all artifact types matching a published segment. a. Select the [visualization configuration options](/guide/reporting/manage-custom-reports.qmd#visualization-configuration-options){target="_blank"} to apply to the dataset. diff --git a/site/guide/shared/_work-with-filters.qmd b/site/guide/shared/_work-with-filters.qmd index 72d58cf76..256cc5331 100644 --- a/site/guide/shared/_work-with-filters.qmd +++ b/site/guide/shared/_work-with-filters.qmd @@ -53,6 +53,8 @@ Value editor - **[artifact information]{.smallcaps}** — One of the artifact fields always created by {{< var vm.product >}}, such as the Business Unit. - **[assignees]{.smallcaps}** — User assigned to the Validation Issue type artifact. - **[artifact fields]{.smallcaps}** — One of the organization-specific artifact fields you added for your own use. +- **[inventory record fields]{.smallcaps}** — Fields of the parent inventory record that the artifact type is configured to display, such as the record's Stage. +- **[segment]{.smallcaps}** — A published [artifact segment](/guide/validation/manage-artifact-segments.qmd): a named, reusable filter managed by your organization's administrators. Available on artifact listings, and not offered inside a segment's own conditions. :::: diff --git a/site/guide/validation/manage-artifact-segments.qmd b/site/guide/validation/manage-artifact-segments.qmd new file mode 100644 index 000000000..bbe123017 --- /dev/null +++ b/site/guide/validation/manage-artifact-segments.qmd @@ -0,0 +1,192 @@ +--- +# Copyright © 2023-2026 ValidMind Inc. All rights reserved. +# Refer to the LICENSE file in the root of this repository for details. +# SPDX-License-Identifier: AGPL-3.0 AND ValidMind Commercial +title: "Manage artifact segments" +date: last-modified +includes: + artifacts: true +--- + +Save a set of artifact filters as a named, reusable segment that spans every artifact type, then publish the segment so everyone in your organization can view, filter, and analyze the matching artifacts together. + +::: {.attn} + +## Prerequisites + +- [x] {{< var link.login >}} +- [x] There are artifacts logged on records in your inventory.[^1] +- [x] You are a [{{< fa hand >}} Customer Admin]{.bubble} or assigned another role with sufficient permissions to perform the tasks in this guide.[^2] + +::: + +## Key concepts + +*Artifact segments* are named, reusable filters over your artifacts, built the same way as inventory segments:[^3] + +- A segment spans every artifact type in your organization, including validation issues. Artifact Type is available as a condition, so you can scope a segment to specific types. +- Segment conditions use the fields that every artifact type shares. Severity, Assignee, Risk Area, and Due Date count as shared fields only while every active artifact type has them switched on.[^4] If an artifact type is added or reconfigured later so that a saved segment no longer fits the shared fields, the segment is refused with a message wherever it is used until its conditions are updated. +- Matching artifacts are evaluated live. A segment always reflects the current state of your artifacts, and users only see the matching artifacts they have permission to view. +- A segment starts as a personal [Draft]{.bubble}. Publishing it makes it available to your entire organization. + +::: {.callout title="Note that segments differ from saved views and grouping."} +- **Segments** — Named filters managed by administrators in the organization settings, reusable by everyone once published. +- **Saved views** — Personal or shared table configurations that capture the columns, filters, sorting, and grouping applied to an artifact listing.[^8] +- **Grouping** — A listing layout option that organizes a table view into collapsible sections by field.[^9] +::: + +## Add segments + +::: {.callout} +By default, only the [{{< fa hand >}} Customer Admin]{.bubble} role can add artifact segments. To let other roles add segments, grant the Add Artifact Segment permission to those roles.[^2] +::: + +1. In the left sidebar, click **{{< fa gear >}} Settings**. + +2. Under {{< fa expand >}} Artifacts, select **Artifact Segments**. + +3. Click **{{< fa plus >}} Add Segment**. + +4. On the Add New Segment dialog that opens, enter the **Segment Name** and an optional **Description**. + +5. Click **Add Segment**. + + The detail page for your new segment opens, where you define the segment conditions. + +### Define segment conditions + +1. On your segment's detail page, click **{{< fa filter >}} Filter**. + +2. On the Edit Segment Conditions dialog that opens, enter the conditions that artifacts must match to belong to the segment: + + - Artifact Type is available as a condition, so you can scope a segment to specific artifact types. + - Only the fields shared by every artifact type are offered. Fields of the parent inventory record and Segment are not available as conditions here. + - Shared Calculation fields can be used as conditions. They are evaluated against the stored values, which refresh in the background, and they offer the same operators as in the artifact filters, including **has error**.^[[Filter by calculated and aggregation fields](/guide/validation/view-filter-artifacts.qmd#filter-by-calculated-and-aggregation-fields)] + +::: {.callout-button .pl4 .nt2} +::: {.callout collapse="true" appearance="minimal"} +### How do I create effective filters? + +{{< include /guide/shared/_work-with-filters.qmd >}} +::: +::: + +3. Click **Apply Filters**. + + Your conditions appear as chips next to Filtered by, and the list of matching artifacts updates live along with the matching artifact count. + +4. In the page header, click **Save Changes** to save the conditions to the segment, or **Cancel** to discard your edits. + +::: {.callout-important title="Saving conditions to a published segment changes its results for everyone."} +A published segment is evaluated live wherever it is used, including the Artifacts listing, artifact filters, and analytics datasets. When you save condition changes to a published segment, confirm the change by clicking **Yes, Save Changes**. +::: + +## Publish segments + +Publishing makes a segment available to everyone in your organization. You can continue editing a segment after it is published. + +1. In the left sidebar, click **{{< fa gear >}} Settings**. + +2. Under {{< fa expand >}} Artifacts, select **Artifact Segments**. + +3. On the actions menu for your segment, click **Publish Segment**. + +4. Click **Publish Segment** to confirm. + +Each segment shows one of the following statuses: + +| Status | Description | +|--------|-------------| +| [Draft]{.bubble} | Personal to you, visible only to you and not yet offered where segments are used. | +| [Published]{.bubble} | Available to everyone in your organization. | +| [Archived]{.bubble} | Permanently retired. An archived segment cannot be edited, published, or restored. | + +: Artifact segment statuses {.hover} + +## Edit segments + +To rename a segment or update its description: + +1. In the left sidebar, click **{{< fa gear >}} Settings**. + +2. Under {{< fa expand >}} Artifacts, select **Artifact Segments**. + +3. On the actions menu for your segment, click **Edit Segment**. + +4. Update the **Segment Name** or **Description**, then click **Save Changes**. + +To edit the conditions of a segment, open the segment and update its filters.[^5] To see the artifacts a segment currently matches, select **View Matching Artifacts** on its actions menu. + +## Unpublish, archive, or delete segments + +::: {.callout-important} +Archiving and deletion of segments are permanent. +::: + +1. In the left sidebar, click **{{< fa gear >}} Settings**. + +2. Under {{< fa expand >}} Artifacts, select **Artifact Segments**. + +3. On the actions menu for your segment, click one of: + + - **Unpublish Segment** — Returns the segment to a personal draft. The segment is no longer offered where segments are used. Click **Yes, Unpublish Segment** to confirm. + - **Archive Segment** — Permanently retires the segment. An archived segment cannot be edited, published, or restored. Click **Yes, Archive Segment** to confirm. + - [**Delete Segment**]{.red} — Permanently deletes the segment. The artifacts it matched are not affected. Click **Yes, Delete Segment** to confirm. + +## View a segment as the Artifacts scope + +Once a segment is published, anyone in your organization can open it as the scope of the Artifacts listing and work with every matching artifact across artifact types: + +1. In the left sidebar, click **{{< fa border-all >}} Artifacts**. + +2. Click the page title to open the scope selector. Options are grouped under **Artifact Type** and **Segments**. + +3. Select a segment. + + The listing shows every matching artifact you have permission to view, across all artifact types, with the shared fields as columns plus an **Artifact Type** column. Filter, Group By (including by Artifact Type), sorting, and CSV export are available on the shared fields. + +Switching between an artifact type and a segment resets the filters, sorting, and grouping, and the listing remembers your last selected scope. Saved views are not available in segment scope. If a segment you open is no longer available to you, for example because it was unpublished or deleted, the listing tells you so and returns to the artifact type view. + +## Apply segments as artifact filters + +Within a single artifact type's listing, a published segment can also be used as a filter rule: + +1. In the left sidebar, click **{{< fa triangle-exclamation >}} Validation Issues** or **{{< fa border-all >}} Artifacts**, and select the artifact type to filter. + +2. Click **{{< fa filter >}} Filter**. + +3. Click **{{< fa plus >}} Add Rule**, then select **Segment** from the field selector. + +4. Select one or more segments to filter by, and combine the rule with other conditions as needed.[^6] + +5. Click **Apply Filters**. + +## Use segments in analytics + +Published artifact segments are available as datasets for visualization widgets on your analytics pages, listed under Artifact Segments in the dataset selector.[^7] A widget built on a segment can be grouped by Artifact Type, and clicking a chart section opens the Artifacts listing in that segment's scope with the matching artifacts. + +## What's next + +- [Working with artifacts](working-with-artifacts.qmd) +- [View and filter artifacts](view-filter-artifacts.qmd) +- [Manage inventory segments](/guide/inventory/manage-inventory-segments.qmd) + + + +[^1]: [Working with artifacts](working-with-artifacts.qmd) + +[^2]: [Manage permissions](/guide/configuration/manage-permissions.qmd) + +[^3]: [Manage inventory segments](/guide/inventory/manage-inventory-segments.qmd) + +[^4]: [Manage artifact types](manage-artifact-types.qmd) + +[^5]: [Define segment conditions](#define-segment-conditions) + +[^6]: [View and filter artifacts](view-filter-artifacts.qmd#filter-and-sort-artifacts) + +[^7]: [Working with analytics](/guide/reporting/working-with-analytics.qmd) + +[^8]: [Manage custom artifact views](customize-artifact-layouts.qmd#manage-custom-artifact-views) + +[^9]: [View and filter artifacts](view-filter-artifacts.qmd#group-artifacts) diff --git a/site/guide/validation/managing-validation.qmd b/site/guide/validation/managing-validation.qmd index 1c5e1c857..d0a66a53c 100644 --- a/site/guide/validation/managing-validation.qmd +++ b/site/guide/validation/managing-validation.qmd @@ -24,6 +24,7 @@ listing: - manage-artifact-types.qmd - manage-artifact-severities.qmd - manage-artifact-fields.qmd + - manage-artifact-segments.qmd aliases: - /guide/model-validation/managing-model-validation.html --- diff --git a/site/guide/validation/view-filter-artifacts.qmd b/site/guide/validation/view-filter-artifacts.qmd index bac5dee36..03ec8f2d0 100644 --- a/site/guide/validation/view-filter-artifacts.qmd +++ b/site/guide/validation/view-filter-artifacts.qmd @@ -87,7 +87,7 @@ c. Click on any artifact for more information. - By default, artifacts for all records are listed by creation date in descending order. - To sort artifacts by a column in ascending ({{< fa angle-down >}}) or descending ({{< fa angle-up >}}) order, click on the column header. -To narrow down artifacts, you can apply some filters: +To narrow down artifacts, you can apply some filters. Published artifact segments, named reusable filters managed by your organization's administrators, can also be applied as a **Segment** filter rule within an artifact type, or opened as the scope of the Artifacts listing to view matching artifacts across all artifact types.[^artifact-segments] ::: {.panel-tabset} @@ -193,4 +193,6 @@ If the grouped field can no longer be grouped by — for example, because the fi [^10]: [Manage custom artifact views](customize-artifact-layouts.qmd#manage-custom-artifact-views) +[^artifact-segments]: [Manage artifact segments](manage-artifact-segments.qmd) + [^calc-art-fields]: [Manage artifact fields](manage-artifact-fields.qmd#artifact-field-types)