Skip to main content
Every case has a status that indicates its current state in the workflow. Statuses help teams understand where each case is in the process and what needs to happen next. For admin-intensive industries, statuses are critical for ensuring nothing falls through the cracks and for maintaining regulatory compliance visibility.

​
Default Statuses

Penbox provides four default statuses that serve as the foundation for all case workflows:

Draft

Case is being prepared, not yet activeCommon uses: Initial setup, gathering preliminary info, preparing case before activation

Pending

Case is waiting to be started or for an external triggerCommon uses: Awaiting documents, awaiting customer action, scheduled to start later

In Progress

Case is actively being worked onCommon uses: Data collection, verification, processing, review

Closed

Case is completeCommon uses: Approved, completed, rejected, cancelled

​
Status Hierarchy

Cases use a hierarchical status system where custom statuses are grouped under the four default parent statuses.

​
Why Hierarchical?

This system provides:
  • Flexibility: Create specific statuses for your workflow
  • Consistency: All statuses map to standard states
  • Filtering: Filter by parent status to see all “in progress” cases
  • Reporting: Group by parent status for high-level metrics

​
Example Hierarchy

📁 draft
   └─ preparing
   └─ review_needed

📁 pending
   └─ awaiting_documents
   └─ awaiting_approval
   └─ awaiting_payment

📁 in_progress
   └─ collecting_data
   └─ verification
   └─ compliance_review
   └─ final_approval

📁 closed
   └─ approved
   └─ completed
   └─ rejected
   └─ cancelled

​
Custom Statuses

Case Templates can define custom statuses specific to their workflow.

​
Creating Custom Statuses

Each custom status is defined with: 
{
  "key": "awaiting_documents",
  "label": "Awaiting Documents",
  "parent_status": "pending",
  "auto_transition_when": {
    "watch": ["data.documents_uploaded"],
    "condition": {":defined": "{data.documents_uploaded}"},
    "execute_once": false
  }
}

​
Status Properties

Key (required)
  • Unique identifier for the status
  • Format: lowercase letters, numbers, underscores
  • Max 120 characters
  • Example: awaiting_documents, compliance_review, final_approval
Label (required)
  • Display name shown to users
  • Can contain any characters
  • Should be clear and action-oriented
  • Example: “Awaiting Documents”, “Compliance Review”, “Final Approval”
Parent Status (required)
  • Must be one of: draft, pending, in_progress, closed
  • Groups custom statuses under main categories
  • Determines case lifecycle stage
Auto Transition When (optional)
  • Defines conditions for automatic status changes
  • Object containing:
    • watch (optional): Array of data keys to monitor for changes (format: data.*)
    • condition (required if auto_transition_when is set): JSON expression that evaluates to true to trigger transition
    • execute_once (optional): Boolean - if true, transition only happens once even if condition remains true

​
Status Design Guidelines

Status names should indicate what’s happening or what’s needed.Good: “Awaiting Customer Response”, “Under Review”, “Ready for Approval”Avoid: “Status 1”, “Phase 2”, “Step A”
Choose parent statuses that match the actual case state.
  • Use pending when waiting for something external
  • Use in_progress when team is actively working
  • Use closed only for final terminal states
Each status should represent a meaningful stage in your process.Recommended: 5-10 custom statuses per templateToo many: Every small action gets its own statusToo few: Hard to track progress
If your workflow has clear stages, make statuses follow that sequence.Example: Onboarding → Verification → Review → Approval → Closed

​
Status Transitions

Cases move through statuses either manually or automatically.

​
Manual Status Changes

Team members can change status:
  • Select new status from dropdown
  • Status updates immediately
  • Change is logged in timeline
  • Can trigger automations

​
Automatic Status Transitions

Statuses can change automatically based on conditions: 
{
  "key": "ready_for_review",
  "label": "Ready for Review",
  "parent_status": "in_progress",
  "auto_transition_when": {
    "watch": ["data.all_documents_uploaded", "data.form_completed"],
    "condition": {":and": ["{data.all_documents_uploaded}", "{data.form_completed}"]},
    "execute_once": true
  }
}
Common auto-transition triggers:
  • All required fields filled
  • Documents uploaded
  • Forms completed
  • External data received
  • Time elapsed

​
Status Change Events

When a status changes:
  1. Case status is updated
  2. Timeline event is created
  3. Parent status is updated
  4. Automations may be triggered
  5. Team notifications may be sent
  6. “Waiting For” status may change

​
Next Steps

Case Templates

Configure statuses in templates

Case Automations

Automate status transitions (Coming soon)

Case Introduction

Back to Cases overview

Case Data

Understand case fields and data