← Back to Documentation Home

User Documentation

Draft Workflow User Guide

Overview

The Draft Workflow feature allows you to safely design and test process flows before publishing them to production. Think of it as a "sandbox mode" where you can experiment with process designs without affecting your live architecture.

Why Use Drafts?

Benefits:

  • 🧪 Safe Experimentation - Test process designs without polluting your production models
  • 🔄 Version Control - Create multiple draft versions of the same process
  • 👥 Collaboration - Work on different draft versions simultaneously
  • ✅ Quality Assurance - Review and refine before merging to production
  • 📝 Documentation - Keep a history of design iterations

Key Concepts

Draft vs. Merged

Draft Process:

  • Status: draft
  • Editable workspace for design
  • Can contain temporary elements
  • Orange badge indicator: 🟠 DRAFT MODE
  • Changes don't affect production

Merged Process:

  • Status: merged
  • Published to production
  • Elements reference canonical entities
  • Green badge indicator: 🟢 MERGED
  • Visible to all users

Draft-Local vs. Canonical Elements

Draft-Local Elements:

  • Created within a draft process
  • Marked with isDraft: true
  • Temporary placeholders during design
  • Appear with dashed borders in the graph

Canonical Elements:

  • Exist in your core architecture (Actors, Features, Systems)
  • Referenced by merged processes
  • Shared across multiple processes
  • Appear with solid borders

Creating a Draft Process

Step 1: Navigate to Process Landscape

  1. Open the Processes perspective
  2. Click on a Process Landscape to view its processes

Step 2: Start New Draft

  1. Click the "Start Draft Process" button (top-right corner)
  2. Fill in the draft creation form:
    • Draft Name (required): e.g., "Order Processing v2"
    • Based on Process (optional): Clone from existing process
    • Description (optional): Notes about this draft

Step 3: Create Draft

Click "Create Draft" - you'll see:

  • Orange 🟠 DRAFT MODE badge
  • Your draft name displayed
  • Empty canvas (or cloned elements if based on another process)

Working in Draft Mode

Flow-First Creation

The recommended way to build process flows is edge-to-empty-space:

  1. Click on an existing element (or create your first one)

  2. Drag a connection to empty space

  3. Select element type from the popup:

    • 🎭 Actor - Person or system interacting
    • ⚙️ Feature - System functionality
    • 📋 Process - Sub-process
    • 📦 DataObject - Data entity (intermediate step)

  4. Fill in the step creation form:

    • Step Action: What happens (e.g., "submits", "validates")
    • DataObject: Optional intermediate data (e.g., "Order")
    • Target: Where the flow goes next

  5. Choose creation mode:

    • "Create New": Create a new draft-local element
    • "Select Existing": Link to an existing canonical entity (for merged mode)

Adding Process Steps

Each connection in your process is a Process Step:

  • Source: Where the flow starts
  • Target: Where the flow goes
  • Action: What happens (the edge label)
  • DataObject (optional): Intermediate data

Example Flow:

Customer → [submits] → Order → [validates] → OrderSystem

Draft Element Indicators

Visual Cues:

  • Dashed borders = Draft-local elements
  • Solid borders = Canonical elements (referenced)
  • Orange badge = You're in draft mode
  • DataObject labels = Show on process step edges

Managing Multiple Versions

Version Switcher

When you have multiple draft versions of the same process:

  1. Look for the "Switch Version" button next to the draft badge

  2. Click to see all versions:

    • 🟢 Merged - Production version
    • 🟠 Draft v1, v2, v3... - All draft versions
    • ✓ Current - Highlighted in blue

  3. Click any version to switch to it instantly

Use Cases:

  • Compare different design approaches
  • Return to a previous iteration
  • Work on parallel variations

Merging to Production

When to Merge

Merge your draft when:

  • ✅ Design is finalized and tested
  • ✅ All stakeholders have reviewed
  • ✅ You're ready to publish to production

Merge Wizard (3 Steps)

Step 1: Map Elements

For each draft-local element, choose:

Create New Canonical Entity:

  • Creates a new Actor/Feature/DataObject in your core architecture
  • Use for brand new elements

Map to Existing Entity:

  • Links the draft element to an existing canonical entity
  • Use when the element already exists

Example:

Draft Element          | Action               | Canonical Entity
--------------------- | -------------------- | ----------------
"New Customer Portal" | → Create New         | → actor-customer-portal-123
"Order System"        | → Map to Existing    | → system-order-mgmt-456

Step 2: Review Changes

Preview:

  • Elements to be created
  • Elements to be mapped
  • Process steps that will be published

Validation:

  • All draft elements must be mapped or created
  • No dangling references
  • All required fields present

Step 3: Confirm Merge

  • Process status changes: draft → merged
  • Draft badge changes: 🟠 → 🟢
  • Draft name removed
  • Elements updated with refId to canonical entities
  • Draft-local elements become canonical (if "Create New" was selected)

After Merging

Changes:

  • Process is now in production
  • Visible to all users
  • Elements reference canonical entities
  • Can be used in reports, exports, etc.

Draft versions:

  • Original draft is merged (no longer editable)
  • Other draft versions remain (if any)
  • Can create new drafts based on merged version

Best Practices

Design Workflow

  1. Start with a Draft

    • Always use drafts for new process designs
    • Don't modify merged processes directly

  2. Use Descriptive Names

    • Include version numbers: "Order Processing v2"
    • Add context: "Order Processing - Mobile Flow"

  3. Clone for Variations

    • Base new drafts on existing processes
    • Experiment with different approaches

  4. Review Before Merging

    • Validate all connections
    • Check element naming consistency
    • Verify data flow logic

Element Management

  1. Prefer Canonical Entities

    • Create canonical Actors/Features in their respective perspectives first
    • Reference them in process flows
    • Reduces duplication

  2. Use Draft-Local Sparingly

    • Only for truly temporary elements
    • Plan to create canonical versions during merge

  3. Consistent Naming

    • Match canonical entity names
    • Use clear, business-friendly terms

Collaboration

  1. Communicate Version Purpose

    • Add descriptions to drafts
    • Use meaningful names
    • Document design decisions

  2. Parallel Development

    • Create separate drafts for different approaches
    • Use version switcher to compare
    • Merge the best solution

  3. Review Process

    • Share draft versions for feedback
    • Iterate before merging
    • Document changes in descriptions

Common Workflows

Scenario 1: New Process from Scratch

1. Click "Start Draft Process"
2. Name: "Customer Onboarding v1"
3. Create blank draft
4. Add first actor (Customer)
5. Drag connection to empty space
6. Create steps using flow-first approach
7. Review and test flow
8. Merge to production

Scenario 2: Improve Existing Process

1. Open existing merged process
2. Click "Start Draft Process"
3. Select "Based on Process" → Choose process
4. Name: "Customer Onboarding v2 - Enhanced"
5. Draft is created with cloned elements
6. Modify flow (add/remove steps)
7. Compare with version switcher
8. Merge when ready

Scenario 3: Parallel Variations

1. Create draft: "Checkout Flow - Option A"
2. Design first approach
3. Create another draft: "Checkout Flow - Option B"
4. Design alternative approach
5. Use version switcher to compare
6. Merge preferred version
7. Delete or archive others

Scenario 4: Incremental Development

1. Create draft: "Release 1.0"
2. Add basic flow
3. Merge to production
4. Create new draft: "Release 1.1" (based on merged)
5. Add additional features
6. Merge when tested
7. Repeat for 1.2, 1.3, etc.

Troubleshooting

"Cannot merge - unmapped elements"

Problem: Some draft-local elements haven't been mapped to canonical entities.

Solution:

  • Review Step 1 of Merge Wizard
  • For each element, choose "Create New" or "Map to Existing"
  • All draft elements must have a mapping

"Version switcher not showing"

Problem: Can't see the version switcher dropdown.

Solution:

  • Version switcher only appears when there are 2+ versions
  • Create another draft or check if process has a base version
  • Refresh the page if you just created a new draft

"Dashed borders on elements"

Explanation: This is normal! Dashed borders indicate draft-local elements.

To fix (if unintended):

  • These elements need refId to canonical entities
  • Use "Map to Existing" during merge to link them
  • Or create new canonical entities via "Create New"

"Lost my draft version"

Problem: Can't find a draft you created earlier.

Solution:

  • Navigate to the Process Landscape
  • Drafts appear alongside merged processes
  • Look for 🟠 status indicator
  • Use search/filter if many processes exist

"Can't edit merged process"

Explanation: Merged processes are read-only to protect production.

Solution:

  • Create a new draft based on the merged process
  • Make changes in the draft
  • Merge when ready to publish updates

FAQ

Q: Can I delete a draft?

A: Yes! Drafts can be deleted without affecting production. Use the delete button in the process list (when viewing a landscape).

Q: What happens to draft elements when I merge?

A: They become references to canonical entities:

  • "Create New" → New canonical entity is created
  • "Map to Existing" → Reference is created to existing entity
  • Draft element is replaced with canonical reference

Q: Can I merge multiple times?

A: A draft can only be merged once. After merging, it becomes a merged process. Create a new draft to make further changes.

Q: How many draft versions can I have?

A: Unlimited! Each draft is independent. However, for clarity, we recommend:

  • Maximum 5-10 active drafts per process
  • Archive or delete outdated drafts
  • Use clear naming conventions

Q: Do drafts affect performance?

A: No significant impact. The system is optimized for handling hundreds of drafts:

  • Lazy loading for version switcher
  • Efficient database indexes
  • Only active draft is loaded in memory

Q: Can others see my drafts?

A: Yes, drafts are visible to all users (not private). However:

  • They're clearly marked as drafts (🟠 indicator)
  • Only merged processes are considered "production"
  • Use naming conventions to indicate ownership/status

Q: What if I make a mistake during merge?

A: Unfortunately, merges cannot be undone. However:

  • The merged process becomes the new baseline
  • You can create a new draft to fix issues
  • Consider reviewing carefully before merging
  • Test in draft mode first

Tips & Tricks

Keyboard Shortcuts

(Coming soon - keyboard shortcuts for draft operations)

Performance Optimization

For large processes (100+ elements):

  • Create elements in batches
  • Use "Select Existing" instead of creating many new elements
  • Merge frequently to avoid huge drafts

For many draft versions:

  • Archive completed drafts (export to YAML)
  • Delete unnecessary versions
  • Keep active drafts under 10 per process

Advanced Features

DataObject Visualization:

  • DataObject names appear on edge labels
  • Shows data flow through your process
  • Helps identify data dependencies

Process Cloning:

  • "Based on Process" creates a full copy
  • All elements are cloned
  • Great for creating variations

Version History:

  • Version switcher shows creation dates
  • Oldest to newest sorting
  • Helps track design evolution

Next Steps

Need help? Open an issue on GitHub or consult the full documentation.