Templates - Penbox Documentation

A Case Template is the blueprint that defines the structure, workflow, and behavior of cases in Penbox. Templates determine what information is collected, how it’s organized, what steps are available, and how cases progress through your process. Templates are especially powerful for admin-intensive industries where consistency, compliance, and proper documentation are critical.

For Administrators & Creators: This documentation is for users who design and create case templates. If you just need to work with existing cases, see Introduction to Cases.

Understanding Case Templates

Think of a Case Template as a master mold. Every case created from a template copies its structure, including:

Fields and their types
Sections and organization
Contact types
Available statuses
Workflow steps
Default values
Automation rules
Compliance requirements and documentation

Important: Templates define the starting structure. Individual cases can be customized by adding, modifying, or removing fields, sections, and contacts. These case-level changes do not affect the template - future cases created from the template will still use the original structure. This allows templates to provide consistency while giving teams flexibility to adapt cases for unique situations.

Templates Are Cases

In Penbox, templates are themselves cases with a special flag (is_template: true). This design means:

You use the same interface to design templates as you do to work with cases
Templates can be tested like real cases
The template editor and case view are consistent
What you see when designing is what users see when working

Creating a Case Template

Basic Template Information

Every template needs:

Field	Description	Required
Title	Name of the template (what users see)	Yes
Description	What this template is for, when to use it, and any regulatory requirements	Optional but recommended
Locale	Default language (e.g., `en`, `fr`)	Yes
Reference	Auto-generated unique identifier	Auto
is_template	Flag marking this as a template	Yes (true)

Template Description Best Practice: For compliance-heavy workflows, use the description to document what this case type is for:

"Customer Onboarding - Complex Sale to Contract

This template manages the complete customer acquisition workflow:
- Initial qualification and data collection
- Quote generation and negotiation
- Contract preparation and signature
- Post-sale compliance verification

Regulatory: This process must maintain audit trail of all approvals and signatures per SOX requirements."

Template Status

Templates start as draft and can progress through the same statuses as regular cases. This lets you test the template workflow before publishing it for use.

Designing the Schema

The schema is the heart of your template - it defines what data the case will collect and how it’s structured.

Adding Fields

Each field in your schema has:

{
  "key": "company_name",           // Unique identifier (lowercase, underscores)
  "type": "text",                   // Field type
  "name": "Company Name",           // Display label
  "description": "Legal company name", // Help text
  "visibility": "always-visible",   // Visibility setting
  "section": "uuid-of-section",     // Optional section grouping
  "options": {}                     // Type-specific options
}

Field Properties

Key (required)

Unique identifier for the field
Format: lowercase letters, numbers, and underscores only
Max 120 characters
Example: company_name, date_of_birth, contract_value
Important: Use meaningful keys for regulatory compliance and system integration

Type (required)

Determines how data is collected and stored
Available types: text, number, date, file, checkbox, checkboxes, choices, signature, http

Name (required)

Label shown to users
Can contain any characters
Should be clear and descriptive

Description (optional)

Help text explaining what this field is for
Shown as a hint to users filling out the case
Use for regulatory guidance: “This field is required for AML compliance”

Visibility (optional, default: always-visible)

always-visible: Field always appears
hide-when-empty: Only shows when it has a value
always-hide: Hidden from view (but data is stored for compliance/integrations)

Section (optional)

UUID of the section this field belongs to
Fields without a section appear at the top

Options (optional)

Type-specific configuration
Example: For choices, this would include the available options

Field Type Details

Text Fields

Type: textCollect text input - single line or multi-line.Options:

{
  "multiline": true,        // Allow multiple lines
  "placeholder": "Enter text here",
  "maxLength": 500
}

Best for: Names, addresses, descriptions, notesCompliance use: Legal entity names, regulatory identifiers

Number Fields

Type: numberCollect numeric values.Options:

{
  "min": 0,
  "max": 1000000,
  "step": 0.01,             // For decimals
  "prefix": "$",            // Currency symbol
  "suffix": "USD"
}

Best for: Amounts, quantities, ages, scoresCompliance use: Financial amounts, asset values for reporting

Date Fields

Type: dateCollect dates with a date picker.Options:

{
  "minDate": "today",
  "maxDate": "2025-12-31",
  "format": "YYYY-MM-DD"
}

Best for: Birthdates, deadlines, start dates, expiration datesCompliance use: Contract dates, expiration dates for compliance tracking

Checkbox Fields

Type: checkboxSingle yes/no checkbox.Best for: Agreements, confirmations, boolean flagsCompliance use: Consent checkboxes, compliance confirmations (must be timestamped in audit trail)

Multiple Checkboxes

Type: checkboxesMultiple options that can be selected simultaneously.Options:

{
  "choices": [
    { "value": "service_a", "label": "Service A" },
    { "value": "service_b", "label": "Service B" },
    { "value": "service_c", "label": "Service C" }
  ]
}

Best for: Multi-select lists, service selections, featuresCompliance use: Risk assessment checkboxes, regulatory requirement selections

Choice Fields (Dropdown/Radio)

Type: choicesSingle selection from multiple options.Options:

{
  "choices": [
    { "value": "option1", "label": "Option 1" },
    { "value": "option2", "label": "Option 2" }
  ],
  "display": "dropdown"  // or "radio"
}

Best for: Country selection, category, status, typeCompliance use: Entity type classification, risk rating selection

File Upload Fields

Type: fileAllow file uploads and document attachments.Options:

{
  "maxSize": 10485760,      // 10MB in bytes
  "accept": [".pdf", ".jpg", ".png"],
  "multiple": true,         // Allow multiple files
  "maxFiles": 5
}

Best for: Documents, images, contracts, identificationCompliance use: Legal documents, proof documents, evidence files (all tracked with timestamps)

Signature Fields

Type: signatureCapture digital signatures.Options:

{
  "method": "handwritten",  // or "typed"
  "requireName": true
}

Best for: Approvals, authorizations, contractsCompliance use: Contract signatures, approval signatures (maintains full audit trail with timestamps)

HTTP Fields (External Data)

Type: httpFetch data from external APIs.Options:

{
  "url": "https://api.example.com/data",
  "method": "GET",
  "headers": {},
  "mapping": {}            // How to map response to fields
}

Best for: Credit checks, company data, verification servicesCompliance use: Real-time compliance checks, regulatory database lookups

Creating Sections

Sections organize related fields together. Each section has:

{
  "id": "uuid",                    // Unique identifier
  "name": "Company Information"    // Display name
}

Fields reference their section by the section’s id. Example structure for complex compliance case:

Applicant Information section
- Full Name (text)
- Date of Birth (date)
- Government ID (file)
Company Information section
- Company Name (text)
- Registration Number (text)
- Industry (choices)
Beneficial Ownership section (compliance section)
- Ultimate Beneficial Owners (checkboxes)
- Ownership percentages (numbers)
Risk Assessment section
- Risk Level (choices)
- Risk Factors (checkboxes)
- Compliance Notes (text)

Use sections to organize data logically AND to group information by compliance domain. This makes it easier to ensure all required fields are collected.

Defining Contact Types

Contact types specify which types of contacts your cases need.

{
  "key": "main_contact",
  "name": "Primary Contact",
  "description": "Main point of contact for this case"
}

Common contact types:

main_contact - Primary contact
billing_contact - Billing/payment contact
legal_contact - Legal representative
technical_contact - Technical liaison
beneficial_owner - Beneficial owner (compliance)
authorized_signatory - Person authorized to sign documents

Each case can have one contact per contact type. If you need multiple contacts of the same type, create separate contact types (e.g., contact_1, contact_2, beneficial_owner_1, beneficial_owner_2).

Defining Workflow Steps

Workflow steps define actions and tasks within your case process.

Step Types

Type	Description	Use Case
form	Send a form to collect data	Request information from contacts, signatures, approvals
email	Send an email	Notify, request, or communicate
sms	Send an SMS	Quick notifications or alerts
note	Internal note	Document decisions or information

Step Configuration

{
  "key": "request_kyc",
  "type": "form",
  "assigned_to": {
    "type": "contact",       // or "user"
    "key": "main_contact"    // or "owner" for users
  },
  "properties": {
    "flow_customization": "uuid-of-form-preset"
  },
  "notifications": {
    // Email and SMS notification config
  }
}

Step Assignment

Steps can be assigned to: Contacts

"assigned_to": {
  "type": "contact",
  "key": "main_contact"      // Must match a contact type
}

Team Members

"assigned_to": {
  "type": "user",
  "key": "owner"             // Case owner
}

Learn more about workflow steps in Case Automations.

Email Configuration

Set the default email sender for communications from cases created with this template:

{
  "email_from": {
    "email": "[email protected]",
    "name": "Your Company Cases"
  }
}

This email address is used for:

Workflow step emails
Automated notifications
Case-related communications

Use a professional sender address. For compliance workflows, consider using “[Department Name] - [Company Name]” to make it clear who is sending the communication.

Intelligence Features

Enable AI-powered assistance for cases created from this template:

Email Drafting

{
  "intelligence": {
    "email_drafting": "You are helping draft professional emails for client onboarding cases. Be friendly but formal."
  }
}

When enabled, Penbox AI can help team members draft emails based on the context and instructions provided.

Case Title Generation

{
  "intelligence": {
    "case_title": "Generate a concise title based on the company name and case type"
  }
}

AI automatically generates meaningful case titles based on the case data.

Auto-Draft Mode

Enable auto-draft to automatically create cases from triggers:

{
  "auto_draft": true
}

When enabled:

Cases can be created automatically from form submissions
Cases start in “draft” status
Team can review and activate when ready

This is useful for complex workflows where you want to review data before activating the case.

Best Practices for Complex Workflows

Design from your actual process, not an idealized one

Document your real workflow including all loops, approvals, and exceptions. Your template should match what actually happens, not what should happen.

Use clear, compliance-aware field naming

Field keys should be descriptive and consistent with regulatory terminology. Use date_of_birth not dob, beneficial_owner_1 not owner. This makes data exports and compliance audits clearer.

Group data into logical sections

Use sections to organize fields by business process, compliance requirement, or customer journey stage. This makes cases easier to navigate and helps ensure nothing is missed.

Use visibility strategically

Use always-visible for critical required fields
Use hide-when-empty for optional fields to keep the interface clean
Use always-hide for technical IDs, compliance tracking fields, system integration data

Design status flow to match your workflow

Map out your actual workflow with all decision points and loops before creating statuses. Example for insurance claims: submitted → initial_review → investigation → decision → approved/denied → appeal_available → closed.

Build in compliance tracking from the start

Create hidden fields to track: timestamps, approval IDs, regulatory check status, data validation results. These support compliance audits without cluttering the UI.

Create contact types for all stakeholders

Identify everyone involved: primary contact, billing, legal, technical, beneficial owners, authorized signatories. Document why each contact type is needed.

Test templates thoroughly with realistic data

Create test cases from your template using real-world scenarios: complex edge cases, approval workflows, long timelines. Verify the workflow supports your actual process.

Document regulatory requirements in the template

Add to the template description which regulations apply (SOX, GDPR, GLBA, AML/KYC, etc.) and what this template’s role is in compliance. This guides team members and supports audit responses.

Plan for data retention and archival

Consider which fields must be retained for compliance, how long, and how they should be archived. Document this in the template description so the team knows what data to maintain.

Template Versioning

Unlike Form Templates, Case Templates don’t have explicit versioning. When you modify a template:

Changes don’t affect existing cases (they keep their original structure inherited from the template)
New cases created from the template use the latest structure
Individual cases can always be customized independently, regardless of template changes
If you need major changes, consider creating a new template with a version suffix (e.g., “Customer Onboarding v2”)

How case customization interacts with versioning: If a case was created from “Customer Onboarding v1” and the template is later updated:

The case keeps its current structure and data
The case can be customized further with additional fields or modifications
These customizations don’t affect the v1 template or other cases
If you create a new case from “Customer Onboarding v2”, it will get the v2 structure

When updating a template that’s in use, remember that existing cases won’t change their structure automatically. The template changes only apply to new cases. However, existing cases can always be customized individually if needed.

Next Steps

Case Statuses

Configure status workflows

Case Data

Understand fields and sections

Forms

Use forms in case workflows

Case Automations

Automate case workflows (Coming soon)

Get Started

Cases

Forms

​Understanding Case Templates

​Templates Are Cases

​Creating a Case Template

​Basic Template Information

​Template Status

​Designing the Schema

​Adding Fields

​Field Properties

​Field Type Details

​Creating Sections

​Defining Contact Types

​Defining Workflow Steps

​Step Types

​Step Configuration

​Step Assignment

​Email Configuration

​Intelligence Features

​Email Drafting

​Case Title Generation

​Auto-Draft Mode

​Best Practices for Complex Workflows

​Template Versioning

​Next Steps

Case Statuses

Case Data

Forms

Case Automations

Understanding Case Templates

Templates Are Cases

Creating a Case Template

Basic Template Information

Template Status

Designing the Schema

Adding Fields

Field Properties

Field Type Details

Creating Sections

Defining Contact Types

Defining Workflow Steps

Step Types

Step Configuration

Step Assignment

Email Configuration

Intelligence Features

Email Drafting

Case Title Generation

Auto-Draft Mode

Best Practices for Complex Workflows

Template Versioning

Next Steps