Workflow Manager Administrator Guide

Introduction

This guide is for administrators who configure and operate Trustable Workflow Manager. Administrators can do everything agents can do (start runs, use the queue, review history) and also manage settings, artifact templates, workflow definitions, counterparties, users and diagnostics.

For day-to-day running of workflows, see the User Guide.

Administrator responsibilities

As an administrator you typically:

1. Connect Workflow Manager to Digital Trust Foundry and set up SendGrid email.
2. Configure Pinata IPFS for workflow file attachments.
3. Define artifact templates and workflow definitions.
4. Maintain counterparties and their authorized signers.
5. Manage users, roles and wallet sign-in.
6. Monitor activity on the Control Plane and API traffic in the Inspector.
7. Brand the deployment and complete first-run onboarding.

Workflow Manager is deployed as one instance per customer. All workflows and counterparties in your deployment use the Foundry and Pinata settings you configure.

Navigation

After sign-in you land on the Dashboard. The sidebar shows everything agents see (Dashboard, New workflow, Workflow history) plus these administrator pages:

The bottom of the sidebar shows your name and role, and Sign out.

Signing in

Sign-in is two steps. Enter your username and select Sign in. What happens next depends on the account:

• Account with a linked wallet, Foundry configured: Workflow Manager sends a sign-in request to the user’s Foundry Wallet. The login page shows Waiting for wallet… until the user approves it on any connected device.
• Account without a linked wallet, or Foundry not configured: a Password box appears. Enter the password and select Sign in again.

If the wallet request is not approved within the Wallet sign-in timeout (see Workflow runtime), or it fails, the login page shows a message and a Password box so the user can sign in with their password instead.

Wallet sign-in only proves that the user controls the linked wallet. It is separate from signing workflow steps. A successful wallet sign-in also clears any pending password change.

First-run onboarding

On a new deployment, administrators are taken to the onboarding wizard until it is finished:

1. Brand: product name, tagline and primary colour. Select Save & continue.
2. Demo data: optionally select Seed demo data to add a sample counterparty with demo signers, or select Skip.
3. Finish setup: marks onboarding complete and opens Workflow definitions.

To walk through the wizard again without deleting data, go to Settings and select Re-run onboarding on the Re-run first-run onboarding card.

Settings

Open Settings from the sidebar. The page header reads Foundry tenant.

Digital Trust Foundry API configuration

Select Test connection before Save tenant. The test checks that the endpoint is reachable. A response that rejects the key (HTTP 401 or 403) still counts as reachable, so a successful test does not prove the key is valid. To confirm the key, open a counterparty, select Import from Foundry and check that your workspace’s signers are listed.

When the endpoint or the key is empty, Workflow Manager runs in Mock-signer mode:

• A Mock-signer mode banner appears at the top of every page.
• Run pages offer Simulate signer approval so demo runs can complete without a wallet.
• Wallet sign-in is not available; every account signs in with a password.

Mock-signer mode is for demonstrations only. Production deployments must have both fields set.

Product brand

Set Product name, Tagline, Primary colour and an optional Logo URL, then select Save brand. The brand appears in the app header, on the login page and in exported JSON bundles. Changes apply on the next page load.

The Logo URL is also used as the browser tab icon. Use a square PNG or SVG (32 × 32 pixels or larger); wide logos may look cropped in the tab. When no logo is set, Workflow Manager generates a coloured monogram from your product name and primary colour.

Notify email (SendGrid)

Notify steps, signer requests and status notifications send email through SendGrid:

Select Save email settings. If SendGrid is not configured, email goes through your deployment’s default mail service when one is set up; otherwise the message is recorded as simulated email in the Inspector and is not delivered.

Pinata IPFS (workflow attachments)

Agents can attach supporting files to queued and scheduled runs. Configure:

Select Test connection (it uploads a small test file), then Save Pinata settings. When a run starts, its attachments are linked to the run’s Trustable.

Uploads use Pinata’s public IPFS pinning: anyone with a file’s link can download it. Treat attachments as shareable supporting documents, not confidential storage.

Each run accepts up to 5 files of up to 25 MB each. Allowed types are PDF, PNG, JPEG, DOCX, TXT and Outlook MSG.

Workflow runtime

Select Save runtime settings. Workflow signing requests do not time out: a step waits until enough signers approve or a signer declines. Use status notifications to remind signers.

Workflow runs (maintenance)

The Workflow runs card permanently deletes run data. Workflow definitions, artifact templates and counterparties are kept. Trustables already issued on Foundry are not revoked.

Both actions ask for confirmation and cannot be undone.

Control Plane

Control Plane gives an overview of how the deployment is set up and used:

• Setup gaps: shown when something blocks end-to-end runs, such as no workflow definitions, no counterparties, or Foundry not configured. Each item links to the page that fixes it.
• Configured controls: tiles for Workflow definitions, Artifact templates, Counterparties, Counterparty kinds, Users and Foundry integration. Select a tile to see the details.
• Workflow activity: counts for the last 24h, 7d or 30d: Started, Prepared, Scheduled, Signers assigned, Completed, Failed, Schedule failed and Governance changes (definition, template, user and settings changes), with a list of recent events.
• Open right now: current counts of Prepared, Scheduled, In progress and Awaiting signature runs, and the most recently updated open runs.

Artifact templates

Artifact templates define the form an agent fills in when a workflow starts. The answers become the content of the run’s Trustable.

Creating a template

1. Go to Artifact templates and select New template, or select a starter under Start from a template (for example Property Tax change request).
2. Set Name, Slug, Trustable content type, Description, Schema ID and Schema version. Slug and content type fill in from the name until you edit them.
3. Define the fields in Payload fields, or expand Advanced JSON Schema when you need features the field list does not support.
4. Optionally choose an Instance title field so run titles come from an answer in the form.
5. Optionally set Wallet display defaults for the signing request shown in the wallet.
6. Check the start form in the interactive Form preview, then save.

Use Activate or Deactivate on the template list to control availability. Workflows whose template is inactive do not appear on New workflow.

Versioning

Each save of an existing template creates a new version (v2, v3 and so on) under the same slug. The previous version is kept, so runs that already started are unchanged.

• The template list shows the latest version of each slug.
• New runs use the latest active version.
• Import also creates a new version instead of overwriting.

Payload fields

Each row is one form field:

Field keys are generated from labels in camelCase (for example “Project name” becomes projectName). Duplicate labels get a number suffix. You do not enter keys yourself.

Advanced JSON Schema shows the compiled schema read-only. Select Edit JSON Schema directly to switch to the raw JSON editor. If a saved schema uses features the field list cannot show, the editor opens in JSON mode and a banner explains why.

Instance title field

When the template has at least one short text, long text, date, email or URL field, you can choose it as the Instance title field. Its answer becomes the run title at start. Choose None to show a separate title box on the start form instead.

If you rename the label of the title field, the title setting follows the new key.

Wallet display

Wallet display sets what signers see in their wallet: Card title, Subtitle, Approve button, Reject button and Callout severity. Template values are defaults for every sign step that uses the template; each sign step can override them.

Import and export

• Export downloads a portable JSON file with the template fields.
• Import creates or updates a template from such a file. Under When slug already exists, choose Upsert (create or update, the default), Create only (fail if the slug exists) or Update only (fail if the slug is missing).

Use export and import to move templates between environments.

Workflow definitions

A workflow definition is a sequence of steps bound to one artifact template.

List page

From Workflow definitions you can:

• New Definition: create a definition. Enter Name, Slug, Artifact template, Description, Lifecycle model and Terminal state, then select Create & configure steps. You need at least one active artifact template.
• Clone: copy a definition (see Cloning a definition).
• Export: download the definition with its steps and template.
• Configure: open the definition to edit it.
• Import: load a definition file. The bundled template is imported or updated first.

Badges on the list show Inactive, Template inactive and Not on Start workflow when something stops agents from starting the workflow.

Versioning

Saving metadata, steps or status notifications creates a new version (v2, v3 and so on). The earlier version is kept, and runs that already started keep using the version they started with.

• The list shows the latest version of each slug.
• After you save, the editor opens the new version.
• An older version opens read-only with Open latest version.
• Queue import uses the latest version of the slug in the file.
• The slug cannot be changed. Clone the definition to get a new slug.

Activating a definition

When the latest version of a definition is inactive, its page shows Workflow definition is inactive with an Activate button. There is no control to deactivate a definition. To take a workflow off the New workflow page, deactivate its artifact template; this affects every workflow that uses that template.

A definition appears on New workflow only when it is active, its steps have been saved, and its artifact template is active.

Cloning a definition

Select Clone on the list, enter a New name and select Clone definition. The copy starts at version 1 with a slug made from the new name, and opens for editing. Names must be unique.

Definition detail

The definition page has these sections:

• Artifact creation: shown when the steps do not include a create artifact step. The parent Trustable is then created automatically from the start form. Set Counterparty slot, OOR role code and Default proposing signer.
• Metadata: Name, Description, Terminal state (the lifecycle state when the workflow completes, for example settled) and Enforce OOR role matching. Select Save metadata.
• Status notifications: email rules for completed, failed and slow runs. Select Save status notifications.
• Steps: the step list. Select Save steps.

Unsaved step changes are highlighted, and a bar at the bottom of the page offers Discard and Save steps.

Enforce OOR role matching

Enforce OOR role matching is off by default.

• Off: for each sign step, agents can choose any active authorized signer of the step’s counterparty. This lets someone else sign when the usual signer is unavailable.
• On: agents can only choose signers whose OOR role code matches the step’s OOR role code, and Foundry only accepts signatures from officers with that role.

Status notifications

Turn a rule on with its switch and tick the users to notify under Notify these TWM users. Workflow completed and Workflow failed send only when at least one user is selected. Stale signature wait always reminds the signers who have not yet signed; users ticked under Also notify these TWM users are copied.

Notifications use the Notify email (SendGrid) settings. Runs already in progress follow the latest saved rules for the workflow.

Steps

Each step row shows its order, name and kind, an Enabled for new runs checkbox, buttons to move or delete the step, and Configure. Select Add step to add one.

Configure opens the step settings:

• Step kind
• Trustable event name: must be unique in the workflow. When the parent Trustable is created automatically, propose is reserved for that.
• Target state: the lifecycle state after the step
• Description (optional)
• Settings for the step kind (below)

When Enabled for new runs is cleared, the step is skipped by default on the start form. Agents can turn it back on for a run.

Step kinds

The Step kind list also shows process, append event and verify. Workflow Manager does not run these kinds: a run fails when it reaches one. Do not use them.

Create artifact and sign step settings:

Notify step settings: Recipient emails (comma-separated), Subject template and Body template.

How signatures are collected

When a run reaches a create artifact or sign step, every selected signer gets the signing request at the same time. Any of them can sign. The step completes as soon as the number of signatures reaches the Signing threshold. The run page shows who is still awaited, for example “Waiting for 2 of 3 signers”, and who signed.

If a signer declines, the run stops and ends as Declined. Signing requests do not expire; use Stale signature wait to remind signers.

On the start form, agents choose the signers for each step under Review signers. The list shows every active authorized signer of the step’s counterparty (only those with the matching role when Enforce OOR role matching is on). The definition’s default signers are pre-selected and marked Default. Agents must select at least the threshold number.

Saving steps

Select Save steps after editing. Workflow Manager checks that:

• Each step has a unique Trustable event name.
• The sequence is valid (for example, sign steps come after the Trustable is created).

Fix any error shown before saving again.

Counterparties and signers

Counterparties are organisations or teams whose people sign workflow steps (a vendor, a customer, an internal group).

Counterparty details

Select New counterparty, or open a counterparty and use the Overview tab:

• Counterparty name, Kind, Enterprise name, Enterprise LEI
• Aliases (comma separated, used when suggesting signers from artifact content)
• Notes
• Counterparty is active (shown to agents)

Clear Counterparty is active to hide a counterparty from new work while keeping its history. Delete counterparty permanently removes it and all its signers.

Authorized signers

On the Authorized signers tab:

• Import from Foundry lists the signers in your Foundry workspace with name, role and wallet AID. When the counterparty has an Enterprise LEI, only signers with that LEI are shown; clear the LEI on the Overview tab to see all.
• Add manually adds a signer with Display name, Actor AID, OOR role code (optional), Enterprise name, Enterprise LEI, Email and Phone.
• The pencil icon (Edit signer) edits a signer’s details, including email, phone and notes.
• The delete icon (Delete signer) removes a signer permanently.

Keep signer email addresses accurate: signers receive request and reminder emails there, and queue import matches signers by email.

Signing thresholds are set on each workflow step, not on the counterparty.

Request test signatures

Use Request test signatures to check that signers’ wallets receive signing requests. It sends a test request to every active signer of the counterparty who has a wallet AID; the icon on a signer row (Request test signature) sends to that signer only. Inactive signers and signers without a wallet AID are skipped. Foundry must be configured. A message shows how many requests were sent and skipped.

Deleting counterparties and signers

Deleting a counterparty or a signer is blocked while a signer is assigned to a draft, scheduled or in progress run.

Kinds

Kinds (page title Counterparty kinds) categorise counterparties, for example Internal, Vendor or Customer. Select New kind to add one. Deactivated kinds are not offered when creating or editing counterparties.

Users

Go to Users to manage Workflow Manager accounts. These accounts are separate from Foundry workspace users, but you can link an account to a Foundry wallet for wallet sign-in.

User rows show badges such as Wallet linked, Foundry OK, Not in Foundry and Must change password.

Creating a user

1. Select New user and enter Full name, Email and Username.
2. Under Foundry wallet (optional), when Foundry is configured, pick a wallet signer from your Foundry workspace, or keep No wallet link (password only). No wallet link (password only) leaves the account without a wallet; the user signs in with a password. Use Paste AID manually to type a wallet AID instead.
3. Choose the Role and, for non-administrators, the Assigned workflow.
4. Enter a Temporary password (at least 8 characters).
5. Leave Require password change on next sign-in ticked (the default) to make the user set their own password, then select Create user.

Share temporary passwords through a separate channel.

Editing a user

Open a user to change Full name, Email, Wallet AID, Role, Assigned workflow or set a New password (optional). Saving a new password also requires a change on the next sign-in. Clear the Wallet AID to make the account password only.

Deactivating and deleting users

Use the deactivate icon on a user row to block access while keeping history. Inactive users appear under Inactive users, with Reactivate and a delete icon. Delete permanently removes the account; it is not possible for users who started workflows or uploaded attachments.

Verify wallet AIDs

Select Verify wallet AIDs to check every user’s linked wallet against your workspace’s signer list. The Wallet AID verification card shows, for each user, In Foundry or Not in Foundry, and flags duplicate AIDs. When a user has paired a new wallet, the card shows the match and a button such as Relink 1 to current wallet AID that points those users at their current wallet AID. Foundry must be configured.

Role summary

Running workflows as an administrator

Administrators use the same Dashboard, New workflow and Workflow history pages as agents. See the User Guide for the full flow. Administrators also:

• See queue drafts, runs and history for every user.
• Can tick Save selected signers as defaults on the workflow definition under Review signers, so future runs pre-select the same signers.
• Can tick Save disabled steps as defaults on the workflow definition under Steps for this run, so future runs skip the same steps by default.

Clone to queue

Clone to queue is available on completed, failed and cancelled runs, in Workflow history and on the run page. It creates a queue draft with the same form answers, signers and attachments, titled with “(copy)”, and opens it for editing. The Clone button on a queue row does the same for a draft.

Queue export and import

On the Workflows queue panel of the Dashboard:

• Export (on a row) downloads a JSON file of the draft.
• Import (in the panel header) creates a new draft from such a file. The workflow definition slug must already exist in this deployment.

The file holds the title, form answers, external reference, signer choices (matched on import by email, or by counterparty name and role), skipped steps and references to the attached files. Files are not uploaded again; the imported draft points to the same files.

Use this to move prepared work between environments after promoting definitions, or to hand a prepared request to another agent.

Declined and failed runs

A run that stops ends in one of two ways:

• Declined: a signer declined the request in their wallet. Workflow history shows a Declined badge and a View outcome button. The run page shows Signing declined, the step where it stopped, who declined, any signer comment and the steps completed before.
• Failed (technical problem): the run stopped because of a technical or configuration error. Workflow history shows View problem, and the run page shows Run problem with What went wrong.

Both pages offer Export audit JSON. The Workflow failed status notification covers both cases.

Inspector

The Inspector lists the API calls and emails Workflow Manager makes, in time order. Use it to diagnose signatures, attachment uploads and email.

Filters, which combine:

• Direction: outbound calls or inbound webhooks
• Service: Foundry, SendGrid, Mailgun or simulated email
• Kind: the type of call, for example signing requests, status checks or email sends
• Workflow instance id: paste a run’s id to trace one run

The list refreshes at the Foundry signing poll interval; select Refresh to update at once.

For deeper diagnosis, turn on Record workflow run debug log. While it is on, every workflow engine action is recorded with the related calls. Download a JSON bundle with Download current run, Download last completed or, after filtering by run, Download filtered instance.

Integration tests

Integration tests runs the built-in regression suite against your deployment.

• Test catalog lists the test cases.
• Run all tests starts a run; the page refreshes every 2 seconds while it runs.
• Recent runs and Run details show each case’s status, duration and errors.

The tests create temporary workflow runs that are cleaned up afterwards, and they do not send real signing requests. Run them after upgrades or configuration changes.

Public verification pages

When a notify step follows signed steps, its email links to a Pre-implementation verification page. The page needs no sign-in, and the link stays valid for 90 days. Recipients see the request, Prior approvals (each sign step with its signer), supporting file links and a Verification result: Safe to implement or Do not implement yet. Re-verify runs the check again.

Make sure Public app URL in Settings is an address recipients can reach.

Operational checklist

Before go-live:

• Foundry endpoint and API key set, and signers listed under Import from Foundry
• SendGrid configured and a test notify email received
• Pinata configured and Test connection passed
• Public app URL set correctly
• Branding applied
• Artifact templates and workflow definitions active, with no Not on Start workflow badge
• Counterparties and signers registered with correct wallet AIDs and email addresses
• Request test signatures sent and approved by each signer
• Agent and viewer accounts created; wallet AIDs linked where needed and checked with Verify wallet AIDs
• Signing thresholds and default signers set on every create artifact and sign step
• Status notifications set for each workflow
• A full test run completed and its trust report reviewed

After changes:

• Export definitions and templates before major edits
• Export queue drafts you want to keep before clearing runs
• Run Integration tests on a staging deployment
• Tell agents about new workflows and steps that are skipped by default

Troubleshooting