workflow_flutter

A powerful Flutter workflow management plugin supporting iOS, Android, Web, Windows, and Linux platforms, providing complete workflow creation, execution, monitoring, and management capabilities.

Features

✅ Complete Workflow Lifecycle Management: Create, update, delete, execute, and cancel workflows
✅ Real-time Event Listening: Receive various events during workflow execution through Stream
✅ Cross-platform Compatibility: Supports iOS, Android, Web, Windows, and Linux
✅ Layered Architecture Design: Dart API layer, business logic layer, platform adaptation layer, native SDK layer
✅ Asynchronous Execution: Runs workflows in background threads without blocking UI
✅ Type Safety: Uses strongly typed models to ensure data consistency
✅ Rich Step Types: Supports Action, Condition, Parallel, Delay, Loop, Approval, Subworkflow, Webhook, Custom, and more
✅ Error Handling: Comprehensive error handling mechanism with detailed error information
✅ Version Compatibility: Supports multi-platform version checking
✅ Testability: Supports Mock testing and unit testing

Installation

Add the dependency to your pubspec.yaml file:

dependencies:
  workflow_flutter: ^1.0.0

Then run:

flutter pub get

Quick Start

1. Initialize Workflow Manager

import 'package:workflow_flutter/workflow_flutter.dart';

// Workflow manager is a singleton, use instance directly
final workflowFlutter = WorkflowFlutter.instance;

2. Create Workflow

import 'package:workflow_flutter/models/workflow_models.dart';

// Create workflow
final workflow = Workflow(
  id: '', // Empty ID for plugin to generate automatically
  name: 'Sample Workflow',
  description: 'This is a sample workflow',
  steps: [
    WorkflowStep(
      id: 'step1',
      name: 'Data Processing',
      type: WorkflowStepType.action,
      parameters: {
        'actionName': 'processData',
        'config': {
          'field': 'value',
          'operation': 'uppercase'
        }
      },
      nextSteps: ['step2']
    ),
    WorkflowStep(
      id: 'step2',
      name: 'Condition Check',
      type: WorkflowStepType.condition,
      parameters: {
        'condition': 'data.value.length > 10'
      },
      onSuccess: ['step3'],
      onFailure: ['step4']
    ),
    WorkflowStep(
      id: 'step3',
      name: 'Success Path',
      type: WorkflowStepType.action,
      parameters: {
        'actionName': 'sendSuccessNotification'
      }
    ),
    WorkflowStep(
      id: 'step4',
      name: 'Failure Path',
      type: WorkflowStepType.action,
      parameters: {
        'actionName': 'sendFailureNotification'
      }
    )
  ],
  status: WorkflowStatus.pending
);

// Save workflow
final createdWorkflow = await workflowFlutter.createWorkflow(workflow);
print('Created workflow ID: ${createdWorkflow.id}');

3. Execute Workflow

// Prepare input data
final inputData = {
  'param1': 'value1',
  'param2': 123,
  'param3': true
};

// Execute workflow
final executionResult = await workflowFlutter.executeWorkflow(
  createdWorkflow.id,
  inputData
);

print('Workflow execution started, execution ID: ${executionResult.executionId}');

4. Listen to Workflow Events

// Listen to workflow events
final subscription = workflowFlutter.listenWorkflowEvents().listen((event) {
  print('Received event: ${event.eventType} (${event.executionId})');
  
  switch (event.eventType) {
    case WorkflowEventType.workflowStarted:
      print('Workflow started execution: ${event.executionId}');
      break;
    case WorkflowEventType.stepStarted:
      print('Step started execution: ${event.stepId}');
      break;
    case WorkflowEventType.stepCompleted:
      print('Step execution completed: ${event.stepId}');
      print('Step result: ${event.data}');
      break;
    case WorkflowEventType.stepFailed:
      print('Step execution failed: ${event.stepId}');
      print('Error message: ${event.error}');
      break;
    case WorkflowEventType.workflowCompleted:
      print('Workflow execution completed: ${event.executionId}');
      break;
    case WorkflowEventType.workflowFailed:
      print('Workflow execution failed: ${event.executionId}');
      print('Error message: ${event.error}');
      break;
    case WorkflowEventType.workflowCancelled:
      print('Workflow execution cancelled: ${event.executionId}');
      break;
  }
});

// Cancel subscription when no longer needed
// subscription.cancel();

5. Get Execution Result

// Get execution result
final result = await workflowFlutter.getWorkflowExecutionResult(
  executionResult.executionId
);

print('Execution status: ${result.status}');
print('Execution result: ${result.result}');
if (result.error != null) {
  print('Execution error: ${result.error}');
}

6. Cancel Workflow Execution

// Cancel workflow execution
await workflowFlutter.cancelWorkflowExecution(executionResult.executionId);

API Documentation

WorkflowFlutter Class

WorkflowFlutter is the main entry class of the plugin, providing all workflow management functions.

Create Workflow

Future<Workflow> createWorkflow(Workflow workflow)

Get Workflow

Future<Workflow> getWorkflow(String workflowId)

Update Workflow

Future<Workflow> updateWorkflow(Workflow workflow)

Delete Workflow

Future<bool> deleteWorkflow(String workflowId)

List All Workflows

Future<List<Workflow>> listWorkflows()

Execute Workflow

Future<WorkflowExecutionResult> executeWorkflow(
  String workflowId, {
  Map<String, dynamic>? inputData,
})

Cancel Workflow Execution

Future<bool> cancelWorkflowExecution(String executionId)

Get Workflow Execution Result

Future<WorkflowExecutionResult> getWorkflowExecutionResult(String executionId)

Get Workflow Execution History

Future<List<WorkflowExecutionResult>> getWorkflowExecutions(String workflowId)

Listen to Workflow Events

Stream<WorkflowEvent> listenWorkflowEvents()

Close Event Stream

Future<void> closeEventStream()

Check Platform Compatibility

Future<bool> checkPlatformCompatibility()

Get Minimum Platform Version Requirements

Map<String, String> getMinimumRequiredPlatformVersions()

Data Models

Workflow

Represents a complete workflow definition:

class Workflow {
  final String id;
  final String name;
  final String description;
  final List<WorkflowStep> steps;
  final String? startStepId;
  final Map<String, dynamic>? initialData;
  final WorkflowStatus status;
  final DateTime? createdAt;
  final DateTime? updatedAt;
  final String? version;
  final int? priority;
  final bool? isEnabled;
  final List<String>? tags;
  final Map<String, String>? metadata;
  final Map<String, dynamic>? triggerConditions;
  final int? maxRetries;
  final Duration? executionTimeout;
}

WorkflowStep

Represents a step in a workflow, supporting multiple types:

class WorkflowStep {
  final String id;
  final String name;
  final WorkflowStepType type;
  final Map<String, dynamic> parameters;
  final List<String>? nextSteps;
  final List<String>? onSuccess;
  final List<String>? onFailure;
  final int? timeout;
  final String? description;
  final bool? isOptional;
  final Map<String, dynamic>? inputMapping;
  final Map<String, dynamic>? outputMapping;
  final Map<String, String>? metadata;
  final List<String>? tags;
}

WorkflowStepType

Supports multiple workflow step types:

enum WorkflowStepType {
  action,      // Execute action
  condition,   // Condition check
  parallel,    // Parallel execution
  delay,       // Delay
  loop,        // Loop
  approval,    // Approval
  subworkflow, // Subworkflow
  webhook,     // Webhook
  custom,      // Custom
}

WorkflowExecutionResult

Represents the result of workflow execution:

class WorkflowExecutionResult {
  final String workflowId;
  final String executionId;
  final WorkflowStatus status;
  final Map<String, dynamic>? result;
  final String? error;
  final DateTime startedAt;
  final DateTime? completedAt;
}

WorkflowEvent

Represents an event during workflow execution:

class WorkflowEvent {
  final String executionId;
  final WorkflowEventType eventType;
  final String? stepId;
  final Map<String, dynamic>? data;
  final String? error;
  final DateTime timestamp;
}

WorkflowEventType

Defines event types during workflow execution:

enum WorkflowEventType {
  stepStarted,      // Step started execution
  stepCompleted,    // Step execution completed
  stepFailed,       // Step execution failed
  workflowStarted,  // Workflow started execution
  workflowCompleted,// Workflow execution completed
  workflowFailed,   // Workflow execution failed
  workflowCancelled,// Workflow execution cancelled
}

Platform-specific Configurations

Web

Web platform support runs in browser environments without additional configuration. Workflow data uses in-memory storage and will be lost after page refresh.

Windows

Windows platform supports desktop applications without additional configuration. Workflow data uses in-memory storage.

Linux

Linux platform supports desktop applications without additional configuration. Workflow data uses in-memory storage.

iOS

Ensure necessary permissions are enabled in Xcode, no additional configuration required.

Android

Ensure necessary permissions are added in AndroidManifest.xml, no additional configuration required.

Example Application

The plugin includes a complete example application demonstrating how to use all features of workflow_flutter:

cd example
flutter run

The example application includes the following features:

Create new workflows
Execute workflows
Cancel workflow execution
Delete workflows
Real-time event listening
Execution result display

Error Handling

workflow_flutter provides comprehensive error handling mechanisms. All methods may throw the following errors:

INVALID_PARAMETER: Invalid parameter
WORKFLOW_NOT_FOUND: Workflow not found
EXECUTION_NOT_FOUND: Execution not found
WORKFLOW_ERROR: Workflow execution error
PLATFORM_ERROR: Platform-specific error

It is recommended to catch these errors when using:

try {
  await workflowFlutter.executeWorkflow(workflowId, inputData);
} catch (e) {
  print('Failed to execute workflow: $e');
}

Performance Optimization

Workflow execution runs in background threads without blocking UI
Uses ConcurrentHashMap (Android) and efficient Swift Dictionary for workflow storage
Event sending uses main thread to ensure UI update safety
Comprehensive memory management to avoid memory leaks

Contributions

Contributions are welcome! Feel free to submit issues and pull requests.

License

MIT License

Author

QuantumLeap丶 - CSDN Blog

Version History

1.1.0

Added Web platform support
Added Windows platform support
Added Linux platform support
Improved cross-platform architecture design
Used conditional imports to avoid cross-platform conflicts
Enhanced workflow step type support
Improved testing framework

1.0.0

Initial release
Complete workflow management functionality
Support for iOS and Android platforms
Real-time event listening
Comprehensive API documentation

Contact

If you have any questions or suggestions, please contact us through:

Happy Coding! 🚀