Skip to main content

Workflows Framework

This section provides technical documentation for developers who want to integrate workflows into their applications, extend the engine with custom functionality, or understand the underlying architecture.

For Developers​

Getting Started​

  • Architecture - Understand the workflow engine design, event sourcing, and state machine model
  • Services - Integrate workflows via REST API and TypeScript services
  • Testing - Write unit and integration tests for workflow implementations

Advanced Topics​

  • Extending - Create custom activities, step handlers, and signal processors

Integration Guides​

Start workflows, send signals, and complete tasks programmatically:

Extension Points​

Extend the workflow engine with custom functionality:

Architecture Deep Dive​

Understand how the workflow engine works:

Example: Starting a Workflow​

import { apiFetch } from '@saasframe/ui/backend/utils/api'

async function startApprovalWorkflow(orderId: string, amount: number) {
  const response = await apiFetch('/api/workflows/instances', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      workflowId: 'purchase-approval-v1',
      initialContext: {
        orderId,
        amount,
        requesterEmail: '[email protected]',
        approverEmail: '[email protected]'
      },
      correlationKey: orderId
    })
  })

  if (!response.ok) {
    throw new Error('Failed to start workflow')
  }

  return await response.json()
}

Example: Custom Activity​

import { ActivityDefinition, ActivityExecutionContext, ActivityResult } from '../types'

export async function executeSendSmsActivity(
  definition: ActivityDefinition,
  context: ActivityExecutionContext
): Promise<ActivityResult> {
  const { to, message } = definition.config

  try {
    const smsService = context.container.resolve('smsService')
    const result = await smsService.send({ to, message })

    return {
      success: true,
      output: { messageId: result.messageId }
    }
  } catch (error: any) {
    return {
      success: false,
      error: error.message,
      retryable: true
    }
  }
}

User Documentation​

For non-technical users and business users, see the User Guide.

API Reference​

REST Endpoints​

  • POST /api/workflows/instances - Start workflow
  • POST /api/workflows/instances/{id}/signal - Send signal
  • GET /api/workflows/instances/{id} - Get instance details
  • GET /api/workflows/instances - List instances
  • POST /api/workflows/tasks/{id}/complete - Complete task

Service Interfaces​

  • WorkflowService - Core workflow operations
  • WorkflowExecutor - State machine execution
  • ActivityExecutor - Activity execution
  • TaskService - User task management

View full API documentation →

Next Steps​

  1. Understand the Architecture: Read the architecture guide to learn how the engine works
  2. Integrate via API: Follow the services guide to start workflows programmatically
  3. Extend the Engine: Use the extending guide to add custom functionality
  4. Test Your Implementation: Follow the testing guide to write comprehensive tests

See Also​