Introduction

This guide is for administrators who configure and operate Trustable Workflow Manager (TWM). Admins have every capability agents have (start runs, queue, history) plus full access to settings, definitions, counterparties, users, and diagnostics.

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

Administrator responsibilities

As an admin you typically:

1. Connect TWM to Digital Trust Foundry and optional SendGrid email.
2. Configure Pinata IPFS for workflow file attachments.
3. Define artifact templates and workflow definitions.
4. Maintain counterparties and authorized signers.
5. Manage users and roles.
6. Monitor outbound API traffic in the Inspector.
7. Brand the tenant and complete first-run onboarding for new deployments.

TWM is deployed one instance per customer (single tenant). All workflows and counterparties in your deployment share the Foundry and Pinata settings you configure.

Signing in and navigation

After login, you land on the Dashboard. The sidebar includes everything agents see (Dashboard, New workflow, Workflow history) plus:

Wallet sign-in (login page)

If your user account has a wallet AID linked on the Users page, the login form switches to Sign in with wallet after you enter your username and leave the field (tab out or click elsewhere). Password sign-in remains available via Use password instead.

Wallet sign-in is separate from workflow signing: it only proves you control the linked AID to open TWM. Demo deployments without Foundry can still complete wallet login using a server-side mock signer; production tenants should link real Foundry AIDs.

Administrators configure wallet AIDs on the Users page (see Users ).

First-run onboarding

On a new deployment, TWM may redirect you to the onboarding wizard (/onboarding):

1. Brand — product name, tagline, primary colour.
2. Demo data — optional seed of sample counterparties and signers.
3. Complete — marks onboarding done and sends you to workflow definitions.

To walk through onboarding again without deleting data, go to Settings → Re-run first-run onboarding.

Settings

Open Settings (labeled Foundry tenant in the page header).

Digital Trust Foundry API

Configure:

• Foundry API endpoint — Trustables API base URL.
• Foundry API key — tenant API key.

Use Test connection before saving. The test calls GET /api/v1/trustables/signers on your endpoint to confirm the API key and route are reachable. If Foundry is unreachable or unset, TWM falls back to a local mock signer suitable for demos only — not for production.

Foundry signer pickers throughout TWM (counterparty import, new user wallet link) use the same Trustables signers API and normalize the tenant response into a flat list of display names and AIDs.

Product brand

Set product name, tagline, primary colour, and optional logo URL. Branding appears on the login page, app header, exported JSON bundles, and public verification pages.

The logo URL also drives the browser tab icon (favicon). After you save, reload the tab to see it. Use a square PNG or SVG (ideally 32×32 or larger) for a crisp tab icon; wide header logos may look cropped in the tab. When no logo is set, TWM generates a coloured monogram from your product name and primary colour.

The server exposes /favicon.ico for bookmarks and browsers that load the icon before the app starts.

Notify email (SendGrid)

Workflow notify steps send email through SendGrid:

If SendGrid is not configured, notify steps may fall back to log-only simulation in development.

When a run has IPFS attachments, notify emails include compact links to those files in addition to the verification link.

Pinata IPFS (workflow attachments)

Agents can attach supporting files to prepared runs. Configure:

Use Test connection before saving. Attachments are stored with SHA-256 hashes and CIDs; at artifact creation, TWM merges file name and gateway URL into the Trustable content.

Uploads use Pinata’s public IPFS pinning — anyone with the gateway URL or CID can fetch the file. Treat attachments as shareable supporting documents, not confidential storage.

Allowed file types: PDF, PNG, JPEG, DOCX, TXT — up to 5 files, 25 MB each per run.

Workflow runtime

Foundry signing poll interval controls how often open screens poll while a step awaits a signature (default 5 seconds). This affects the Dashboard (workflows in progress), run detail, and Inspector log refresh.

Workflow runs (maintenance)

The Workflow runs card lets you permanently delete instance data from the database. Workflow definitions, artifact templates, counterparties, and queue drafts are not affected. Trustables already issued on Foundry are not revoked.

Both actions are irreversible. Use before demos, after test cycles, or when resetting operational data while keeping configuration.

Artifact templates

Artifact templates define the structured form submitted when a workflow starts. TWM stores them as JSON Schema for agents, queue drafts, and Foundry artifact creation.

Creating a template

1. Go to Artifact templates → New template (or use a starter such as Property Tax change request).
2. Set name, slug, content type, schema ID, and schema version for Foundry. Slug and content type auto-fill from the name until you edit them manually.
3. Define payload fields in the visual field list (see below), or expand Advanced JSON Schema to edit raw JSON when you need features outside the field list.
4. Optionally choose an Instance title field so run titles are taken from a payload answer at start.
5. Optionally configure wallet display defaults for signing apps.
6. Use the interactive Form preview at the bottom of the editor to check the start form before saving.

Versioning

Each save of an existing template creates a new version (v2, v3, …) under the same slug. The previous version is deactivated but kept in the database so workflow runs that already started against it are unchanged.

• The template list shows only the latest version per slug, with a v number in the description.
• New workflow runs use the latest active template version linked from the workflow definition you save after editing.
• Import update also creates a new version rather than overwriting rows in place.

Payload field list (visual editor)

Each row is one form field:

Property keys are generated automatically from labels in camelCase (for example Project name → projectName). Duplicate labels get numeric suffixes (projectName2, …). You do not enter keys manually in the visual editor.

Field types:

Expand Advanced JSON Schema under the field list to see the compiled schema (read-only). Use Edit JSON Schema directly when you need to switch to the raw JSON editor. If a saved schema uses features the field list cannot represent, TWM opens it in Advanced JSON Schema mode and shows a banner explaining why.

Instance title field

When the template has at least one title-eligible field (short text, long text, date, email, or URL), choose Instance title field to copy that answer into the workflow run title at start. Choose None to keep a separate title field on the start page.

Renaming a field label updates its property key; if that field was the title source, TWM remaps the title setting automatically.

Wallet display (optional)

Some templates support wallet display metadata so signers see a friendly summary in signing apps. Defaults apply to every sign step using the template; individual sign steps can override fields.

Import and export

• Export downloads a portable JSON bundle (template fields only, no database IDs).
• Import creates or updates a template from a bundle file.

When importing, choose what happens if the slug already exists:

Use export/import to move templates between environments or tenants.

Workflow definitions

Workflow definitions describe a linear sequence of steps bound to one artifact template.

List page

From Workflow definitions you can:

• New Workflow Definition — create a new definition bound to an artifact template
• Open an existing definition for editing
• Activate or deactivate a definition (inactive definitions cannot be started)
• Export / Import portable workflow bundles (definition + embedded template snapshot)

Versioning

Saving metadata or steps on an existing definition creates a new version (v2, v3, …) with a new internal ID. The prior version is deactivated; in-progress and completed runs keep using the definition version they started with.

• The list shows the latest version per slug (v number in the card).
• After save, the editor navigates to the new version automatically.
• Opening an older version URL shows a read-only banner — use Open latest version to edit.
• Queue import and Start workflow resolve definitions by slug to the latest active version.
• Slug cannot be changed when saving; create a new definition for a new slug.

Definition detail

Edit:

• Name and description
• Terminal state — lifecycle state when the workflow completes (for example settled)
• Require signer assignment at start — when enabled, agents must pick signers before starting (select-signer steps are managed automatically in the step list)
• Automatic artifact creation — optional counterparty / role / default signers for the implicit create step

Click Save metadata and Save steps separately. Unsaved step changes are highlighted until you save.

Step types

Each step has:

• Name and optional description
• Event name — Foundry event identifier (must be unique within the workflow)
• Target state — lifecycle state after the event (where applicable)
• Step-specific config — signers, signing threshold, prompt templates, notify recipients, and so on
• Enabled for new runs — when unchecked, the step is disabled by default on the start page (agents can re-enable it per run)

Create artifact and Sign steps support multiple authorized signers with a signing threshold (for example “2 of 3”). On each such step in the definition editor:

1. Choose Counterparty slot and OOR role code (when applicable).
2. Select one or more default signers in the signer picker (multi-select from that counterparty’s authorized signers).
3. Set Signing threshold — minimum signatures required on that step (cannot exceed the number of signers selected in the pool).

At run start, agents choose a subset of each step’s configured pool using checkboxes (at least the threshold count). Order at runtime follows the order signers were configured on the step. Signatures are collected sequentially — one wallet at a time in pool order until the threshold is met. TWM does not fan out parallel signature requests for a single step.

The same pool-and-threshold rules apply on the in-run Assign signers step when a workflow definition includes Select signers / requires assignment before continuing.

Create artifact and Sign steps include Email signer when approval is requested (on by default). When each signer is dispatched to Foundry and awaits a wallet signature, TWM sends a short notification to that signer’s email on file (if any). This uses the same Notify email (SendGrid) settings as notify steps. Missing email or SendGrid configuration does not block signing — the step still waits in Foundry/KATE as usual.

Saving steps

Click Save steps after editing. TWM validates:

• Unique step order and event names
• Valid sequence (for example sign steps must follow artifact creation)

Fix any error message before saving.

Export and import

Export produces a bundle with the definition, steps (including disabledForNewRuns), and embedded artifact template snapshot.

Import merges or creates definitions in your tenant. Choose Upsert, Create only, or Update only when the definition slug may already exist — useful for promoting configuration from dev to production.

Counterparties and signers

Counterparties represent organisations or teams (vendor, customer, internal group, and so on).

For each counterparty:

1. Set name, kind, and optional metadata.
2. Add authorized signers — display name, role code (OOR), email, and Foundry actor AID.

Signing thresholds are configured per workflow step (create artifact and sign steps), not on the counterparty record. Counterparty signing policy is no longer shown or edited in the UI; legacy policy values may remain in the database but do not drive workflow behaviour.

Use Import from Foundry on the counterparty Signers tab to pull signers from your Foundry tenant via GET /api/v1/trustables/signers. TWM lists each tenant signer with display name, role, and AID. You can filter by the counterparty’s enterprise LEI when set on the Overview tab. You can also Add manually when a signer is not yet in Foundry. Click the pencil icon on any signer to edit email, phone, notes, and other details after import.

Sign steps reference counterparties and roles so the right authority attests each event.

Deactivate vs delete permanently

• Deactivate a counterparty or signer (clear Counterparty is active or signer active flag) to hide them from new assignments while preserving history.
• Delete permanently removes the counterparty and all its signers, or removes an individual signer. Deletion is blocked if that signer is assigned to a draft, scheduled, or in progress workflow.

Ensure signers have accurate email addresses — queue import matches exported signer assignments by email or counterparty name + role.

Kinds

Kinds categorise counterparties (for example Internal, Vendor, Customer). Manage kinds from the Kinds page; inactive kinds are hidden from new counterparty forms.

Users

Go to Users to create and manage TWM operator accounts (admins, agents, viewers). These are separate from Foundry tenant users, but you can link a TWM account to a Foundry wallet AID for wallet sign-in.

User rows show a Wallet linked badge when an AID is set.

Creating a user

1. Click New user and fill in name, email, username, role, and temporary password.
2. Under Foundry wallet (optional), when Foundry is configured TWM loads signers from the tenant and shows a selectable list (display name, role, and AID). Choose No wallet link (demo AID) to let TWM assign a demo AID automatically, or pick a Foundry signer to store that AID on the account. Full name may pre-fill from the signer’s display name.
3. Use Paste AID manually if you need to enter an AID without using the Foundry list.
4. Optionally require a password change on first sign-in (wallet sign-in skips this once the user signs in with a wallet).

Share temporary passwords out-of-band when creating password-only users.

Editing a user

Open a user from the list to update email, name, role, assigned workflow, wallet AID, or temporary password. Clear the AID to disable wallet sign-in for that account.

Wallet sign-in (behaviour)

When a user record has a wallet AID, the login page detects this after the username field loses focus and offers Sign in with wallet instead of password. A one-time challenge is pre-staged; the user confirms with a wallet signature (demo mode uses a server-side mock signer when Foundry is not configured). Password sign-in remains available via Use password instead.

Clear the AID on a user to require password-only login. Wallet sign-in clears any pending must change password flag on success.

Role summary

Running workflows as admin

Admins use the same Dashboard, New workflow, and Workflow history flows as agents, with extra options on the New workflow page.

The Dashboard shows Workflows in progress and Workflows queue (light blue panels). Use Add New Workflow to Queue in the queue panel header, Add to queue on the full queue page (/workflows/queue), or New workflow in the sidebar to prepare a run.

On New workflow, after filling in the form, choose Add to Queue, Run now, or Schedule for later (with a schedule time at least 5 minutes ahead).

From Workflow history or an in-progress run detail page, Clone to queue copies a completed or active run’s payload (and related settings) into a new queue draft for re-use.

Queue export and import

From the Workflows queue panel on the Dashboard, the full queue page (/workflows/queue), or each queue row:

• Export — download a portable JSON bundle for a prepared draft
• Import — upload a bundle to create a new draft (requires the workflow definition slug to already exist in this tenant)

Bundles include the payload, title, external reference, signer assignments (matched on import by email or counterparty name + role), disabled step orders, and IPFS attachment metadata (CID, gateway URL, file name — not a re-upload of file bytes). Imported drafts reference the same pinned files on Pinata.

Use this to move prepared work between environments after promoting definitions, or to share a filled-in draft with another agent.

Save signer defaults

When assigning signers at start (or on an in-run Assign signers step), agents and admins pick from each step’s configured pool using checkboxes — at least the step’s signing threshold must be selected. Admins can opt to save signer choices as defaults on the workflow definition so future runs pre-select those signers from each pool.

Queue export includes one row per selected signer per step; import merges them back into multi-signer assignments for the draft.

Save disabled step defaults

When disabling steps for a run, admins can check Save disabled steps as defaults on the workflow definition. Future starts pre-uncheck those steps (agents can still re-enable them per run).

These options are not available to non-admin agents.

Inspector

The Inspector shows outbound and inbound API calls (Foundry, SendGrid, Pinata, and related services).

Use it to:

• Diagnose failed signatures, attachment uploads, or notify email
• Filter by service, status, and time range
• Enable workflow run debug logging and export a JSON debug bundle for a specific run

Poll interval follows the Workflow runtime setting in Settings.

Integration tests

Integration tests runs automated cases against your deployment (API, engine, and configuration smoke tests).

• View the test catalog and past run results
• Run all tests after upgrades or configuration changes
• Review per-case pass/fail details and error messages

Requires a healthy database and (for some cases) Foundry or mock mode as configured.

Public verification pages

Notify steps generate links to /verify/\{token\} — an unauthenticated page where recipients review prior approvals, supporting file links (when attachments exist), and run Foundry verification before implementing a change.

Ensure Public app URL in Settings matches the hostname recipients can reach.

Operational checklist

Before go-live:

• Foundry endpoint and API key tested
• SendGrid configured and test notify sent
• Pinata configured and test upload succeeded
• Public app URL set correctly
• Branding applied
• Artifact templates and workflow definitions active
• Counterparties and signers registered with correct AIDs and emails
• Agent and viewer accounts created; wallet AIDs linked where wallet sign-in is required
• Multi-signer steps configured with correct pools and thresholds; end-to-end sequential signing verified
• End-to-end test run completed; trust report reviewed

After changes:

• Export definitions/templates before major edits
• Export queue drafts you want to preserve before clearing in-progress runs
• Run integration tests on staging
• Communicate new workflows or disabled default steps to agents

Troubleshooting