Skip to main content

Workflow Documentation

Complete guide to the GoDezk workflow system for creating, configuring, and managing continuous camera recording and other automation workflows.

📚 Documentation Structure​

This section provides comprehensive documentation on the workflow engine:

1. Overview​

Get started with workflow concepts, architecture, and lifecycle. Understand the three execution modes (Event, Continuous, Scheduled) and how workflows are designed, published, and consumed.

Topics covered:

  • What is a workflow?
  • Execution modes
  • Architecture overview
  • Workflow lifecycle (Design → Publish → Install → Configure → Activate)
  • Database schema

2. Continuous Recording Workflow ⭐​

Step-by-step guide to create a camera recording workflow that captures RTSP streams in 5-minute segments and stores them in MinIO/S3.

Complete implementation includes:

  • SQL seed scripts for catalog, parameters, and requirements
  • Backend activation flow explanation
  • Frontend configuration UI
  • Monitoring and troubleshooting
  • Storage verification
  • Advanced multi-camera setup

Perfect for: First-time workflow creators

3. Node Types Reference​

Complete reference for all 12+ node types with configuration examples.

Node categories:

  • Sources: data_source, trigger
  • Processing: collector, transform, ai_node
  • Logic: condition, delay
  • Actions: mcp_action, module_trigger, notification
  • Output: storage, broadcast

Each node includes:

  • Purpose and use cases
  • Configuration fields with types and validation
  • Output schema
  • Real-world examples
  • Template variable support

4. Execution Modes​

Deep dive into the three execution modes with architecture diagrams and implementation details.

Modes covered:

  • Event Mode: Real-time reactions (face detected → mark attendance)
  • Continuous Mode: Always-on processes (24/7 camera recording)
  • Scheduled Mode: Cron-based tasks (daily reports)

For each mode:

  • How it works (sequence diagrams)
  • Characteristics and use cases
  • Configuration steps
  • Activation flow code walkthrough
  • Monitoring approach

5. Configuration Guide​

Learn parameter management, secrets handling, and multi-tenant configuration.

Topics:

  • Parameter definition (catalog layer)
  • Org-specific configuration (org layer)
  • Runtime resolution and template variables
  • Secrets management (current + production recommendations)
  • Multi-tenant isolation
  • Dynamic form generation
  • Configuration validation
  • Versioning and rollback

6. Best Practices​

Design patterns, optimization tips, and production guidelines.

Sections:

  • Design principles (single responsibility, fail fast, idempotent operations)
  • Performance optimization (minimize nodes, avoid redundant calls)
  • Security best practices (never hardcode credentials, validate inputs)
  • Reliability patterns (health checks, timeouts, retries, circuit breakers)
  • Scalability considerations (stateless workflows, resource quotas)
  • Testing workflows (manual, dry-run, validation)
  • Monitoring & observability
  • Common pitfalls to avoid

7. Quick Reference ⚡​

Cheat sheet for developers - common patterns, SQL commands, API calls.

Includes:

  • Common workflow patterns (recording, alerts, reports)
  • Node cheat sheet
  • Template variables reference
  • Condition operators
  • Cron expressions
  • SQL quick commands
  • API reference
  • Validation rules examples
  • Path templates
  • Troubleshooting commands
  • Performance benchmarks

🎯 Quick Start Paths​

I want to create a continuous recording workflow​

  1. Read Overview (10 min)
  2. Follow Continuous Recording step-by-step (30 min)
  3. Reference Node Types as needed
  4. Use Quick Reference for SQL/API commands

I want to understand workflow architecture​

  1. Read Overview - Architecture section
  2. Read Execution Modes - Deep dive
  3. Study Configuration Guide - How configs work
  4. Review Best Practices - Design patterns

I want to build a custom workflow​

  1. Read Overview - Understand concepts
  2. Study Node Types - Available building blocks
  3. Choose execution mode in Execution Modes
  4. Define parameters using Configuration Guide
  5. Follow Best Practices - Optimize design
  6. Use Quick Reference - Implementation

I want to troubleshoot an issue​

  1. Check Quick Reference - Troubleshooting section
  2. Review Continuous Recording - Troubleshooting
  3. Verify config in Configuration Guide
  4. Check Best Practices - Common pitfalls

📖 Example Workflows​

Camera Recording (Continuous)​

Pipeline: data_source → collector → storage
Mode: continuous
Interval: Every 5 minutes
Output: MP4 segments in MinIO

📄 Full Guide

Face Recognition → Attendance (Event)​

Pipeline: trigger → condition → mcp_action → notification
Mode: event
Trigger: face_recognized
Action: Mark attendance + notify admin

📄 Overview Example

Daily Report (Scheduled)​

Pipeline: trigger → transform → mcp_action → notification
Mode: scheduled
Schedule: 0 18 * * * (6 PM daily)
Action: Generate & email attendance report

📄 Execution Modes - Scheduled

🛠️ Developer Resources​

API Endpoints​

# Catalog
GET    /api/workflows/catalog
GET    /api/workflows/catalog/:catalogId
GET    /api/workflows/catalog/:catalogId/params

# Installation
POST   /api/workflows/catalog/:catalogId/install
POST   /api/workflows/installations/:id/configure
POST   /api/workflows/installations/:id/activate
POST   /api/workflows/installations/:id/deactivate

# Execution
POST   /api/workflows/trigger
GET    /api/workflows/executions
GET    /api/workflows/jobs

Database Tables​

-- Catalog (GoDezk-owned)
workflow_catalog
workflow_catalog_params
workflow_catalog_requirements

-- Engine (Org-scoped)
workflow_org_installations
workflow_org_configs
workflow_org_executions
workflow_running_jobs
workflow_schedules

Key Files​

Backend:
├── src/orchestrator/index.js    - Lifecycle management
├── src/runner/index.js           - Node execution
├── src/dispatcher/index.js       - Event listening
├── src/jobs/index.js             - Continuous jobs
└── src/scheduler/index.js        - Cron scheduling

Frontend:
├── WorkflowBuilder.tsx           - Visual designer
├── WorkflowCatalog.tsx          - Browse workflows
└── WorkflowConfiguration.tsx     - Config panel

📊 Workflow Statistics​

MetricCount
Node Types12+
Execution Modes3
Event Types17+
Supported ProtocolsRTSP, HTTP, ONVIF, MQTT
Storage BackendsMinIO, S3, Local
AI Services5+ (face, fire, vehicle, etc.)

🎓 Learning Path​

Beginner (1-2 hours)

  1. ✅ Read Overview
  2. ✅ Follow Continuous Recording guide
  3. ✅ Test with one camera

Intermediate (3-4 hours)

  1. ✅ Study all node types
  2. ✅ Understand execution modes
  3. ✅ Configure multi-camera setup
  4. ✅ Review best practices

Advanced (5+ hours)

  1. ✅ Design custom workflows
  2. ✅ Implement event-driven automations
  3. ✅ Set up scheduled reports
  4. ✅ Optimize for production
  5. ✅ Configure monitoring & alerts

🤝 Contributing​

To add or improve workflow documentation:

  1. Follow the existing structure
  2. Include code examples with syntax highlighting
  3. Add diagrams (Mermaid) for complex flows
  4. Provide real-world use cases
  5. Test all commands and SQL scripts
  6. Update the Quick Reference cheat sheet

📞 Support​

🔄 Updates​

DateChange
2026-04-17Initial workflow documentation created
- Overview with architecture diagrams
- Continuous recording step-by-step guide
- Complete node types reference
- Execution modes deep dive
- Configuration management guide
- Best practices and patterns
- Quick reference cheat sheet

Next: Start with Overview or jump directly to Continuous Recording Guide