From 062134299e5acc10f081c86085fdf7b81b1e83a3 Mon Sep 17 00:00:00 2001 From: Juan Date: Thu, 13 Aug 2026 15:24:03 +0200 Subject: [PATCH 1/4] Document the Create Artifact workflow step Adds the step type entry with its configuration table, and a worked example for the case nobody derives unaided: the step creates a new artifact every time it is reached, which is right for a recurring event and wrong for a continuing state. The example covers guarding the step with its own condition over an aggregate field counting open artifacts, and when a Condition Branch is needed instead. Co-Authored-By: Claude Opus 5 (1M context) --- site/guide/workflows/_workflow-step-types.qmd | 31 ++++++++++++ .../workflow-configuration-examples.qmd | 47 +++++++++++++++++++ 2 files changed, 78 insertions(+) diff --git a/site/guide/workflows/_workflow-step-types.qmd b/site/guide/workflows/_workflow-step-types.qmd index 044bd8ab29..31dd8bbed3 100644 --- a/site/guide/workflows/_workflow-step-types.qmd +++ b/site/guide/workflows/_workflow-step-types.qmd @@ -41,6 +41,37 @@ SPDX-License-Identifier: AGPL-3.0 AND ValidMind Commercial --> Typical **Manual review** pattern: earlier in the intake workflow, a reviewer chooses the path (for example with a **{{< fa arrow-pointer >}} User Action** or **{{< fa maximize >}} Condition Branch**). Configure each path's **Inventory Record Type Change** step with the matching fixed target type and **Manual review** so activity labels the conversion as after manual review. ::: +### {{< fa expand >}} Create Artifact + + +- Creates an artifact on the inventory record the workflow is running against. +- Available on **inventory record workflows only**. An artifact created by this step starts its own artifact workflow, so artifact workflows cannot themselves create artifacts. +- Requires an artifact type that applies to the workflow's inventory record type.^[[Manage artifact types](/guide/validation/manage-artifact-types.qmd)] + +| Field | Description | +|---:|---| +| **When These Conditions Are Met** (optional) | Add conditional requirements to qualify for this step.^[ [Conditional step requirements](/guide/workflows/conditional-step-requirements.qmd#create-artifact)] | +| **Artifact Type** (required) | The type of artifact to create. | +| **Title** (required) | The artifact's title. | +| **Description** (required) | The artifact's description. | +| **Severity** (optional) | The severity assigned to the artifact. | +| **Assignee** (optional) | Who the artifact is assigned to. Defaults to the user the workflow runs as. | +| **Field Values** (optional) | Values for the artifact type's fields. | +: **{{< fa expand >}} Create Artifact** step configuration {.hover tbl-colwidths="[40,60]"} + +::: {.callout-important title="This step creates a new artifact every time it is reached"} +If the workflow runs repeatedly while the same situation persists, each run creates another artifact. + +Whether that is right depends on what your condition means: + +- **A continuing state** — such as *no validator is assigned* — stays true until someone fixes it. A monthly workflow would raise the same artifact every month, so you want only the first one. +- **A recurring event** — such as *the quarterly attestation was missed* — happens separately each time. Two missed quarters are two separate failures, each closed on its own terms, so you want one artifact per occurrence. + +To raise only one artifact while a state persists, add a **When These Conditions Are Met** condition on this step that checks a field counting open artifacts of that type — see [Raise only one artifact while a condition persists](/guide/workflows/workflow-configuration-examples.qmd#raise-only-one-artifact-while-a-condition-persists). +::: + +An artifact created by this step shows the workflow as its creator in the activity feed, and its detail page shows a **Source** section naming the workflow that raised it. + ### {{< fa tag >}} Artifact Status Change diff --git a/site/guide/workflows/workflow-configuration-examples.qmd b/site/guide/workflows/workflow-configuration-examples.qmd index 7dcf7a8ee9..b64ac122d9 100644 --- a/site/guide/workflows/workflow-configuration-examples.qmd +++ b/site/guide/workflows/workflow-configuration-examples.qmd @@ -259,8 +259,55 @@ In this example, the workflow is designated to stop after running an additional :::: +## Raise only one artifact while a condition persists + + +The **{{< fa expand >}} Create Artifact** step creates a new artifact every time the workflow reaches it. When your workflow runs on a schedule and the situation it detects has not been resolved yet, that means a new artifact on every run. + +Whether you want that depends on what your condition means: + +| Your condition describes | Example | What you want | +|---|---|---| +| A **state** that stays true until fixed | *This inventory record has no validator assigned* | One artifact, until it is resolved | +| An **event** that happens separately each time | *The Q1 attestation was missed* | A new artifact each time it happens | + +For the **event** case, no extra configuration is needed — the step already behaves this way. + +For the **state** case, tell the step to run only when there is not already an open artifact. This takes two parts, and the first is usually done by an administrator: + +**1. Add a field that counts open artifacts** + +Add an aggregate inventory field[^20] on the inventory record that counts its artifacts, filtered to the ones you care about — for example: + +> **Open Validator Issues** — count of *Validator Issue* artifacts with status *Open* + +Every inventory record now carries that count, and ValidMind keeps it up to date as artifacts are created and closed. + +**2. Add the condition to the step** + +Open the **{{< fa expand >}} Create Artifact** step and, under **When These Conditions Are Met**, add: + +> **Open Validator Issues** is **0** + +The workflow now creates the artifact the first time the situation is detected. On later runs, while that artifact is still open, the count is no longer `0`, the condition does not pass, the step does not run, and no duplicate is created. Once someone closes the artifact, the count returns to `0` and a fresh artifact can be raised if the situation happens again. + +::: {.callout-tip} +Because this is an ordinary condition, you are not limited to "none open". You can require that fewer than a certain number are open, or combine the count with other inventory record fields. +::: + +### When to use a Condition Branch instead + +The condition on the step decides whether *that step* runs. When it does not pass, the workflow does not continue past that point — it stops there without reaching an **{{< fa circle-stop >}} End** step. + +That is usually fine for a workflow whose only job is to raise an artifact when needed. Use a **{{< fa maximize >}} Condition Branch** ahead of the step instead when: + +- something else should happen when no artifact is raised — a notification, a field update, another step; or +- you want the workflow to finish cleanly on both paths, by routing the other branch to an **{{< fa circle-stop >}} End** step. + +[^20]: [Manage inventory fields](/guide/inventory/manage-inventory-fields.qmd) + [^1]: ![Adding a workflow that initiates on model registration](example_model-registration.png){fig-alt="A screenshot showing the modal for adding a workflow that initiates on model registration" .screenshot group="model-registration"} **Workflow steps used:** From a64732e482a0d12779e5d42f23be98b81841aa00 Mon Sep 17 00:00:00 2001 From: Juan Date: Mon, 17 Aug 2026 11:03:17 +0200 Subject: [PATCH 2/4] Drop the repeat-artifact guidance from the workflow docs The suggested guard was a condition over an aggregate field counting open artifacts, but the workflow condition builder excludes aggregate fields, so it cannot be authored in the UI at all. Removing the section rather than documenting a workaround that does not exist. Keeps the factual warning that the step creates an artifact every time it is reached, and the note that a blocked condition parks the execution without reaching an End step. Renames the Field Values config row to Artifact Fields to match the panel. Co-Authored-By: Claude Opus 5 (1M context) --- site/guide/workflows/_workflow-step-types.qmd | 9 ++-- .../workflow-configuration-examples.qmd | 47 ------------------- 2 files changed, 4 insertions(+), 52 deletions(-) diff --git a/site/guide/workflows/_workflow-step-types.qmd b/site/guide/workflows/_workflow-step-types.qmd index 31dd8bbed3..923b986d1f 100644 --- a/site/guide/workflows/_workflow-step-types.qmd +++ b/site/guide/workflows/_workflow-step-types.qmd @@ -56,18 +56,17 @@ Typical **Manual review** pattern: earlier in the intake workflow, a reviewer ch | **Description** (required) | The artifact's description. | | **Severity** (optional) | The severity assigned to the artifact. | | **Assignee** (optional) | Who the artifact is assigned to. Defaults to the user the workflow runs as. | -| **Field Values** (optional) | Values for the artifact type's fields. | +| **Artifact Fields** (optional) | Values for the artifact type's fields. | : **{{< fa expand >}} Create Artifact** step configuration {.hover tbl-colwidths="[40,60]"} ::: {.callout-important title="This step creates a new artifact every time it is reached"} If the workflow runs repeatedly while the same situation persists, each run creates another artifact. -Whether that is right depends on what your condition means: +This suits conditions describing a **recurring event** — such as *the quarterly attestation was missed* — where each occurrence is a separate failure closed on its own terms, and one artifact per occurrence is what you want. -- **A continuing state** — such as *no validator is assigned* — stays true until someone fixes it. A monthly workflow would raise the same artifact every month, so you want only the first one. -- **A recurring event** — such as *the quarterly attestation was missed* — happens separately each time. Two missed quarters are two separate failures, each closed on its own terms, so you want one artifact per occurrence. +Take more care with conditions describing a **continuing state** — such as *no validator is assigned* — which stays true until someone fixes it. A monthly workflow would raise the same artifact every month. -To raise only one artifact while a state persists, add a **When These Conditions Are Met** condition on this step that checks a field counting open artifacts of that type — see [Raise only one artifact while a condition persists](/guide/workflows/workflow-configuration-examples.qmd#raise-only-one-artifact-while-a-condition-persists). +Note also that when a condition on this step does not pass, the workflow does not continue past that point — it stops there without reaching an **{{< fa circle-stop >}} End** step. Use a **{{< fa maximize >}} Condition Branch** ahead of the step when something else should happen on the other path, or when you want the workflow to finish cleanly either way. ::: An artifact created by this step shows the workflow as its creator in the activity feed, and its detail page shows a **Source** section naming the workflow that raised it. diff --git a/site/guide/workflows/workflow-configuration-examples.qmd b/site/guide/workflows/workflow-configuration-examples.qmd index b64ac122d9..7dcf7a8ee9 100644 --- a/site/guide/workflows/workflow-configuration-examples.qmd +++ b/site/guide/workflows/workflow-configuration-examples.qmd @@ -259,55 +259,8 @@ In this example, the workflow is designated to stop after running an additional :::: -## Raise only one artifact while a condition persists - - -The **{{< fa expand >}} Create Artifact** step creates a new artifact every time the workflow reaches it. When your workflow runs on a schedule and the situation it detects has not been resolved yet, that means a new artifact on every run. - -Whether you want that depends on what your condition means: - -| Your condition describes | Example | What you want | -|---|---|---| -| A **state** that stays true until fixed | *This inventory record has no validator assigned* | One artifact, until it is resolved | -| An **event** that happens separately each time | *The Q1 attestation was missed* | A new artifact each time it happens | - -For the **event** case, no extra configuration is needed — the step already behaves this way. - -For the **state** case, tell the step to run only when there is not already an open artifact. This takes two parts, and the first is usually done by an administrator: - -**1. Add a field that counts open artifacts** - -Add an aggregate inventory field[^20] on the inventory record that counts its artifacts, filtered to the ones you care about — for example: - -> **Open Validator Issues** — count of *Validator Issue* artifacts with status *Open* - -Every inventory record now carries that count, and ValidMind keeps it up to date as artifacts are created and closed. - -**2. Add the condition to the step** - -Open the **{{< fa expand >}} Create Artifact** step and, under **When These Conditions Are Met**, add: - -> **Open Validator Issues** is **0** - -The workflow now creates the artifact the first time the situation is detected. On later runs, while that artifact is still open, the count is no longer `0`, the condition does not pass, the step does not run, and no duplicate is created. Once someone closes the artifact, the count returns to `0` and a fresh artifact can be raised if the situation happens again. - -::: {.callout-tip} -Because this is an ordinary condition, you are not limited to "none open". You can require that fewer than a certain number are open, or combine the count with other inventory record fields. -::: - -### When to use a Condition Branch instead - -The condition on the step decides whether *that step* runs. When it does not pass, the workflow does not continue past that point — it stops there without reaching an **{{< fa circle-stop >}} End** step. - -That is usually fine for a workflow whose only job is to raise an artifact when needed. Use a **{{< fa maximize >}} Condition Branch** ahead of the step instead when: - -- something else should happen when no artifact is raised — a notification, a field update, another step; or -- you want the workflow to finish cleanly on both paths, by routing the other branch to an **{{< fa circle-stop >}} End** step. - -[^20]: [Manage inventory fields](/guide/inventory/manage-inventory-fields.qmd) - [^1]: ![Adding a workflow that initiates on model registration](example_model-registration.png){fig-alt="A screenshot showing the modal for adding a workflow that initiates on model registration" .screenshot group="model-registration"} **Workflow steps used:** From 52a5359afda39448ec5005afec883538643112d1 Mon Sep 17 00:00:00 2001 From: Juan Date: Wed, 19 Aug 2026 18:05:29 +0200 Subject: [PATCH 3/4] Document what the Create Artifact step actually does now MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Three things the page did not say, all of them behaviour that landed while it sat in draft. The assignee fallback was one sentence short. Leaving it empty assigns the artifact to the user the workflow runs as, and which user that is depends on how the run started: the workflow's author on a schedule, the person whose action triggered it otherwise. That distinction is the whole reason the fallback is defensible, so it belongs where someone is deciding whether to set an assignee. Field values now say what happens with a field the artifact type marks required on registration. The step cannot create an artifact without one, and the workflow no longer saves without it — before, a step could be configured, saved, and then fail on every single run with nothing on the page to warn against it. The Source section grew a trigger, a raised date and a link to the run. The page described only the workflow name, which understates what an artifact now carries about where it came from. Co-Authored-By: Claude Opus 5 --- site/guide/workflows/_workflow-step-types.qmd | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/site/guide/workflows/_workflow-step-types.qmd b/site/guide/workflows/_workflow-step-types.qmd index 923b986d1f..2c271a27ff 100644 --- a/site/guide/workflows/_workflow-step-types.qmd +++ b/site/guide/workflows/_workflow-step-types.qmd @@ -55,8 +55,8 @@ Typical **Manual review** pattern: earlier in the intake workflow, a reviewer ch | **Title** (required) | The artifact's title. | | **Description** (required) | The artifact's description. | | **Severity** (optional) | The severity assigned to the artifact. | -| **Assignee** (optional) | Who the artifact is assigned to. Defaults to the user the workflow runs as. | -| **Artifact Fields** (optional) | Values for the artifact type's fields. | +| **Assignee** (optional) | Who the artifact is assigned to. Leave it empty and the artifact is assigned to the user the workflow runs as — the workflow's author on a scheduled run, or the person whose action triggered it. | +| **Artifact Fields** (optional) | Values for the artifact type's fields. If the artifact type marks a field as required on registration, give it a value here — the workflow cannot be saved until you do, because an artifact cannot be created without it. | : **{{< fa expand >}} Create Artifact** step configuration {.hover tbl-colwidths="[40,60]"} ::: {.callout-important title="This step creates a new artifact every time it is reached"} @@ -69,7 +69,7 @@ Take more care with conditions describing a **continuing state** — such as *no Note also that when a condition on this step does not pass, the workflow does not continue past that point — it stops there without reaching an **{{< fa circle-stop >}} End** step. Use a **{{< fa maximize >}} Condition Branch** ahead of the step when something else should happen on the other path, or when you want the workflow to finish cleanly either way. ::: -An artifact created by this step shows the workflow as its creator in the activity feed, and its detail page shows a **Source** section naming the workflow that raised it. +An artifact created by this step shows the workflow as its creator in the activity feed, and its detail page shows a **Source** section naming the workflow that raised it, what triggered that workflow, when the artifact was raised, and a link to the run that created it. ### {{< fa tag >}} Artifact Status Change From ba49942030e9d9e09b899ca69f12a8dbdb91ddcb Mon Sep 17 00:00:00 2001 From: Juan Date: Wed, 19 Aug 2026 22:34:45 +0200 Subject: [PATCH 4/4] Note that a severity a step uses cannot be deleted Deleting a severity renumbers the remaining ones, so a step configured with it is now refused in settings rather than silently repointed. Says so where the severity is configured, and links the page that manages them. Co-Authored-By: Claude Opus 5 (1M context) --- site/guide/workflows/_workflow-step-types.qmd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/site/guide/workflows/_workflow-step-types.qmd b/site/guide/workflows/_workflow-step-types.qmd index 2c271a27ff..1ae39b6f7c 100644 --- a/site/guide/workflows/_workflow-step-types.qmd +++ b/site/guide/workflows/_workflow-step-types.qmd @@ -54,7 +54,7 @@ Typical **Manual review** pattern: earlier in the intake workflow, a reviewer ch | **Artifact Type** (required) | The type of artifact to create. | | **Title** (required) | The artifact's title. | | **Description** (required) | The artifact's description. | -| **Severity** (optional) | The severity assigned to the artifact. | +| **Severity** (optional) | The severity assigned to the artifact. While a step uses a severity, that severity cannot be deleted in settings.^[[Manage artifact severities](/guide/validation/manage-artifact-severities.qmd)] | | **Assignee** (optional) | Who the artifact is assigned to. Leave it empty and the artifact is assigned to the user the workflow runs as — the workflow's author on a scheduled run, or the person whose action triggered it. | | **Artifact Fields** (optional) | Values for the artifact type's fields. If the artifact type marks a field as required on registration, give it a value here — the workflow cannot be saved until you do, because an artifact cannot be created without it. | : **{{< fa expand >}} Create Artifact** step configuration {.hover tbl-colwidths="[40,60]"}