---
title: "Design document workflows and automate their transitions"
description: "Build a workflow's states and transitions, then attach actions that notify people, distribute controlled copies, update the knowledge base, record audit entries and call other systems when documents move."
url: https://helpcenter.complytrain.net/en/articles/27-design-document-workflows-and-automate-their-transitions
collection: "Documents"
updated: 2026-09-22
language: en
---

# Design document workflows and automate their transitions

Build a workflow's states and transitions, then attach actions that notify people, distribute controlled copies, update the knowledge base, record audit entries and call other systems when documents move.

Build a workflow's states and transitions, then attach actions that notify people, distribute controlled copies, update the knowledge base, record audit entries and call other systems when documents move.

A workflow defines the states a document moves through, such as Draft, In Review and Approved, and the transitions people use to move it. Actions attached to a transition run automatically when a document takes that transition. Viewing workflows needs **vaults:view-configuration**; changing them needs **vaults:configure**.

## Open the workflows

Product location: `/document-vault/workflows`. Open Workflows in Documents.

Open **Workflows** in **Documents**. The list shows each workflow with its **Source** (**From template** or **Created here**), the number of states and transitions, and whether it is the **Default** or **Inactive**. Use **Show inactive** to include retired workflows.

A workflow provided by a template follows that template: its states and transitions cannot be changed here, but its actions can still be configured.

## Create a workflow

Product location: `/document-vault/workflows/{workflowId}` (fallback: `/document-vault/workflows`). Choose Design on the workflow.

1.  Choose **New workflow**, enter a **Name** and **Description**, and choose **Create**.
    
2.  Choose **Design**. Add states with **Add state**: enter the **Name**; the **Code** fills in automatically and is used by transitions, so avoid renaming it once documents use the workflow. Mark exactly one state **New documents start in this state**, and mark the final state or states **This state ends the workflow**.
    
3.  Add transitions with **Add transition**. The **Name** is the button label people will see, for example “Submit for review”. Choose **From**, which can be the entry point for a new document, and **To**. Choose what the transition requires: **Require an electronic signature**, **Require a comment**, a reason, biometric confirmation or membership of specific groups.
    
4.  Point a document type at the workflow. In the vault, open **Document Types**, edit the type and choose it under **Workflow**. Until then, no document follows it.
    

A warning appears when no state is marked as the start, because documents cannot enter the workflow. You can edit or remove states and transitions later. A state that documents are in, or that transitions reference, cannot be removed.

## Add actions to a transition

Product location: `/document-vault/workflows/{workflowId}/actions` (fallback: `/document-vault/workflows`). Choose Configure actions.

Choose **Configure actions**. Each transition appears as a card with its actions. Choose **Add Action**, pick the **Action Type**, give it an **Action Name** and complete its configuration.

<table style="min-width: 75px;"><colgroup><col style="min-width: 25px;"><col style="min-width: 25px;"><col style="min-width: 25px;"></colgroup><tbody><tr><th colspan="1" rowspan="1"><p>Action type</p></th><th colspan="1" rowspan="1"><p>What it does</p></th><th colspan="1" rowspan="1"><p>Settings</p></th></tr><tr><td colspan="1" rowspan="1"><p>Send Notification</p></td><td colspan="1" rowspan="1"><p>Sends an in-app notification from a template.</p></td><td colspan="1" rowspan="1"><p><strong>Notification Template ID</strong>, <strong>Recipients</strong> (one per line), <strong>Include a link to the document</strong></p></td></tr><tr><td colspan="1" rowspan="1"><p>Send Email</p></td><td colspan="1" rowspan="1"><p>Sends an email.</p></td><td colspan="1" rowspan="1"><p><strong>Email Recipients</strong> (empty means whoever made the transition), <strong>Subject</strong>, <strong>Body</strong>, <strong>Include a link to the document</strong></p></td></tr><tr><td colspan="1" rowspan="1"><p>Notify Stakeholders</p></td><td colspan="1" rowspan="1"><p>Notifies the document's owner, reviewers and approvers.</p></td><td colspan="1" rowspan="1"><p><strong>Include the document owner</strong>, <strong>Include reviewers</strong>, <strong>Include approvers</strong>, <strong>Also send by email</strong></p></td></tr><tr><td colspan="1" rowspan="1"><p>Update Knowledge Base</p></td><td colspan="1" rowspan="1"><p>Adds the document to, or removes it from, the vault's primary knowledge base.</p></td><td colspan="1" rowspan="1"><p><strong>Action</strong>: <strong>Add to / update in index</strong> or <strong>Remove from index</strong></p></td></tr><tr><td colspan="1" rowspan="1"><p>Generate Controlled Copy</p></td><td colspan="1" rowspan="1"><p>Issues tracked, recallable copies.</p></td><td colspan="1" rowspan="1"><p><strong>Recipients</strong> (empty means the document's distribution list), <strong>Location</strong>, <strong>Department</strong></p></td></tr><tr><td colspan="1" rowspan="1"><p>Create Audit Entry</p></td><td colspan="1" rowspan="1"><p>Writes an entry to the organisation's <a target="_blank" rel="noopener noreferrer nofollow" class="linktype-link link" data-linktype="link" href="https://help.complytrain.net/en/settings/audit-trail/">audit trail</a>, with the <strong>Event Type</strong> as its action.</p></td><td colspan="1" rowspan="1"><p><strong>Event Type</strong>, <strong>Message Template</strong></p></td></tr><tr><td colspan="1" rowspan="1"><p>Update Metadata</p></td><td colspan="1" rowspan="1"><p>Sets metadata on the document.</p></td><td colspan="1" rowspan="1"><p><strong>Fields (JSON)</strong>, merged into existing metadata; <strong>Add Tags</strong>; <strong>Record the time of the transition</strong></p></td></tr><tr><td colspan="1" rowspan="1"><p>Archive Previous Version</p></td><td colspan="1" rowspan="1"><p>Supersedes older versions.</p></td><td colspan="1" rowspan="1"><p><strong>Versions to keep</strong> (default 1)</p></td></tr><tr><td colspan="1" rowspan="1"><p>Request Signature</p></td><td colspan="1" rowspan="1"><p>Asks named people to sign.</p></td><td colspan="1" rowspan="1"><p><strong>Signers</strong> (empty means the transition's approvers), <strong>Signature Type</strong>: <strong>Electronic</strong> or <strong>Biometric</strong></p></td></tr><tr><td colspan="1" rowspan="1"><p>Trigger Webhook</p></td><td colspan="1" rowspan="1"><p>Calls another system with the transition data.</p></td><td colspan="1" rowspan="1"><p><strong>Webhook URL</strong>, <strong>HTTP Method</strong> (POST, PUT or PATCH), <strong>Timeout (ms)</strong> from 1,000 to 60,000</p></td></tr></tbody></table>

Actions run in the order shown. Use the arrows to reorder them, the switch to enable or disable one without deleting it, and **Edit** or **Delete** to change it.

On an ordinary transition, the actions run before the document changes state. If an action fails, the transition does not happen and the error names the failing action. On a signed transition, the actions run after the signed state change is recorded. Test a new action on a practice document before relying on it.

## Example: release an SOP and let everything follow

Product location: `/document-vault/workflows/{workflowId}/actions` (fallback: `/document-vault/workflows`)

Suppose a standard operating procedure moves from **In Review** to **Approved** through an **Approve** transition that requires an electronic signature. Attach these actions:

1.  **Archive Previous Version**, keeping 1 version, so only the approved version stays current.
    
2.  **Generate Controlled Copy** with the production supervisors as **Recipients** and **Department** set to Production, so each receives a tracked copy. The copies of the previous version are superseded and must be withdrawn; see [controlled copies](https://help.complytrain.net/en/document-vault/controlled-copies/).
    
3.  **Update Knowledge Base** with **Add to / update in index**, so the assistant answers from the approved text.
    
4.  **Notify Stakeholders** with the owner and reviewers, and **Also send by email**.
    
5.  **Trigger Webhook** to another system, for example your ERP, so it knows which procedure version is now in force.
    

A second transition, **Retire**, from **Approved** to **Obsolete**, can use **Update Knowledge Base** with **Remove from index** and **Create Audit Entry** to record the retirement.

Check the result on a practice document: its state and **History**, the new controlled copies, the knowledge-base content and the notification. Then use the workflow for real documents.
