Approval Workflows

ProBeya's Approval Workflow engine provides configurable multi-step approval chains for any entity in the system. Workflows define ordered steps with designated approvers, support three approval modes (all, any, sequential), and integrate with electronic signatures for 21 CFR Part 11 compliance. When a workflow completes, the system automatically transitions the originating entity to its target status.

This feature is essential in pharma and regulated manufacturing environments where status changes (closing a CAPA, verifying an action, releasing a batch) require formal multi-level authorization.

Overview

In regulated environments, certain status changes must not happen without formal approval. A quality action cannot be marked "verified" by just anyone -- it requires sign-off from designated quality reviewers, sometimes in a specific sequence with documented justification.

ProBeya's approval system solves this by separating the workflow definition (who must approve, in what order, under what conditions) from the approval request (the specific instance being approved). This allows a single workflow to be reused across many entities while maintaining a complete audit trail for each individual approval.

Getting Started

1. Navigate to a project board and open Board Settings > Approval Workflows.
2. Click Create Workflow and provide a name (e.g., "CAPA Verification Approval").
3. Define steps in the approval chain, specifying approvers and approval mode for each step.
4. Optionally configure a trigger condition (e.g., when an action's status changes to "done").
5. Save the workflow. It is immediately active and available for use.
6. When an entity triggers the workflow (manually or via trigger condition), an approval request is created.
7. Approvers receive notifications and can approve or reject from the Pending Approvals inbox (/approvals).

Key Concepts

Term	Definition
Approval Workflow	A reusable definition of an approval chain: name, ordered steps, trigger conditions. Associated with a specific board.
Approval Step	One level in the approval chain. Specifies which users can approve and the approval mode.
Approval Mode	How approvals are collected at a step: all (unanimous), any (first-wins), or sequential (ordered chain).
Approval Request	A specific instance of a workflow applied to an entity. Tracks the current step and overall status.
Decision	An individual approver's action: "approved" or "rejected," with an optional comment.
Trigger Condition	A JSONB rule that automatically initiates the workflow when a field changes to a specific value (e.g., status = "done").
E-Signature	An electronic signature attached to a decision for 21 CFR Part 11 compliance. Includes meaning, re-authentication, and optional MFA.

How It Works

Workflow Definition

Each workflow belongs to a board and defines an ordered array of steps. Each step specifies:

• stepIndex -- Zero-based position in the chain (step 0 executes first)
• approverIds -- Array of user IDs authorized to approve at this step (minimum 1)
• approvalType -- How approvals are collected:
  • "all" -- Every listed approver must approve (unanimous consent)
  • "any" -- Any single approver can approve (first-wins)
  • "sequential" -- Approvers must approve in the order listed

Approval Request Lifecycle

Request Created (step 0, pending)
  ├── Step 0 approved → advance to step 1
  │     ├── Step 1 approved → advance to step 2
  │     │     └── Final step approved → request status = "approved"
  │     │           └── Entity status transition executed
  │     └── Step 1 rejected → request status = "rejected"
  │           └── Entity status reverted
  └── Step 0 rejected → request status = "rejected"
        └── Entity status reverted

Key behaviors:

• Rejection at any step terminates the entire workflow immediately. No further steps are processed.
• Approval advances to the next step. When the final step is approved, the request status becomes "approved."
• Post-approval: The system automatically executes the entity status transition defined in the trigger condition (e.g., action status changes to "done").
• Post-rejection: The entity status reverts to a safe default (e.g., "open" for actions). The requester receives a notification with the rejection reason.

Authorization

Only users listed in the current step's approverIds can record a decision. The system verifies the caller's user ID against the step's approver list before accepting any decision. This prevents unauthorized approvals.

Electronic Signatures

For GxP-regulated steps, decisions can include electronic signature data:

• Meaning -- A statement of what the signature represents (minimum 5 characters)
• Password -- Re-authentication credential to verify the signer's identity
• TOTP Code -- Optional MFA token for accounts with two-factor authentication enabled

E-signatures are processed via the createESignature helper, which computes a content hash for tamper detection. This implements the 21 CFR Part 11 requirement for attributable, non-repudiable electronic records.

Pending Approvals Inbox

The /approvals page provides an inbox-style view of all approval requests awaiting the current user's decision across all boards and workflows. Each row shows:

• Entity link (navigate to the item being approved)
• Workflow name
• Current step progress (step X of Y)
• Requested date
• Quick-action approve/reject buttons with inline decision forms

Notifications

The system sends notifications at key lifecycle points:

• Approval completed -- The requester is notified that the workflow finished successfully.
• Approval rejected -- The requester is notified with the rejection reason.

Activity Logging

All mutations (workflow creation, request initiation, decision recording) are logged via the shared logActivity helper for audit trail compliance.

Configuration

Setting	Description
Board Association	Each workflow belongs to a specific board.
Step Count	Minimum 1 step. No maximum limit, but typical workflows have 1-3 steps.
Trigger Condition	Optional JSONB rule for automatic workflow initiation. Field + value pattern.
isActive	Boolean flag to enable/disable a workflow without deleting it. Inactive workflows cannot receive new requests.

Permissions

Role	Capabilities
Board Member	View workflows, view request status
Designated Approver	Record approve/reject decisions for assigned steps
Board Admin	Create, update, and manage workflow definitions
Organization Admin	Full access across all boards and workflows

The approval system uses a polymorphic entity design: entityType + entityId identify what is being approved, allowing the same workflow engine to serve actions, items, documents, and any future entity type.

Tips & Best Practices

Use "any" mode for speed, "all" mode for compliance

For routine approvals where any qualified person can sign off, use "any" mode. For regulated activities requiring unanimous consent (e.g., CAPA verification), use "all" mode.

Keep workflows short

Most approvals need 1-2 steps. Three or more steps create bottlenecks. If you find yourself adding many steps, consider whether you are mixing approval with review.

Set meaningful trigger conditions

Automatic workflow triggers eliminate the risk of someone forgetting to request approval before changing a status. Configure trigger conditions for all regulated status transitions.

Use comments on every decision

Even when approving, a brief comment ("Reviewed test results, all within specification") provides valuable audit trail context that regulators appreciate.

Troubleshooting

Issue	Resolution
Cannot create approval request	Verify the workflow exists, is active, and belongs to your organization. Inactive workflows reject new requests.
"Not authorized to approve" error	Only users listed in the current step's approverIds can decide. Verify your user ID is in the step's approver list.
Entity status did not change after approval	Check the workflow's trigger condition. If no trigger condition is set, automatic status transitions are skipped.
Rejection did not revert entity status	Reversion only applies to entities in "pending_approval" status. If the entity was already reverted manually, the system skips the revert.
E-signature validation failed	Ensure the password matches the account's current credentials. For MFA-enabled accounts, a valid TOTP code is required.

Related Features

• Action Log -- Actions are the primary entity type that uses approval workflows for CAPA verification and status gating.
• Standard Operating Procedures -- SOPs have their own built-in review/approval workflow; combine with the approval engine for additional gate complexity.
• Governance Framework -- Governance gate processes may trigger approval workflows for portfolio-level decisions.
• Escalation Engine -- When approvals are delayed, the escalation engine can auto-escalate to ensure timely resolution.
• Email Notifications -- Approval notifications are delivered via the platform notification system.