comfyui

Seamlessly integrate ComfyUI AI workflows into your Drupal site with dynamic forms, intelligent dependency management, secure media handling, execution history, and Layout Builder support.

-  Alpha Release Notice This module is currently in alpha development and has only been tested on limited workflows. While functional, it may have bugs and incomplete features. Use with caution in production environments and please report any issues you encounter.

Introduction

ComfyUI Integration transforms your Drupal site into an AI content generation platform by bridging Drupal and ComfyUI, the powerful node-based AI interface. Create interactive workflow forms that allow users to generate AI content directly from your Drupal site, with full execution history, provenance tracking, and regulatory compliance support built in.

• Intelligent dependency resolution (custom nodes & models)
• Dynamic field mapping to ComfyUI workflow parameters
• Secure, tokenized media handling with native Drupal integration
• Complete execution history and provenance tracking for regulatory compliance
• Layout Builder support for custom form interfaces
• Stateless architecture for load-balanced and multi-server deployments

Requirements

• Drupal 11
• Media (core module, required) - native media library integration, asset management, and feedback collection
• Layout Builder (core module, required) - building workflow form interfaces
• Access to a ComfyUI server instance (local or cloud-hosted)

Recommended Modules

• Key - required if using ComfyUI-Login Bearer token authentication
• ComfyUI-Login - ComfyUI custom node for authenticated API access in public or multi-user deployments

Installation

1. Download the module from drupal.org/project/comfyui
2. Enable the module:
   

   drush en comfyui
   

3. If upgrading from a previous version, run database updates:
   

   drush updb -y
   

4. Proceed to Configuration

Upgrading: Always run drush updb -y after any version update. Releases regularly include update hooks that install required configuration (State API settings, view updates, schema changes). Check release notes for any BREAKING notices.

Configuration

Initial Setup

1. Navigate to /admin/structure/comfyui-workflow/settings
2. Enter your ComfyUI server URL
3. Configure State API settings (TTL and cleanup batch size) - see State API & Scaling
4. Optionally enable Media Feedback collection

Workflow Setup

1. Create a workflow entity at /admin/structure/comfyui-workflow
2. Upload your ComfyUI workflow.json and workflow_api.json files
3. REQUIRED: Click "Discover Node Definitions"
   • Parses the workflow to identify all nodes and their input/output types
   • Must be completed before field mapping is available
   • Repeat after any workflow file update
4. Re-open the workflow edit form after node discovery
   • Known alpha limitation: the form must be re-opened to reflect newly discovered nodes before you can proceed to field configuration
5. Create Drupal Fields via the Manage Fields interface
   • Add fields matching your workflow inputs - for example:
     • Text fields for prompts
     • Number fields for seeds and numeric parameters
     • Media fields for image inputs
     • Boolean fields for bypass controls
   • Fields must exist before they can be mapped to workflow nodes
6. Configure Field Mappings
   • Map Drupal fields to ComfyUI workflow nodes
   • Mark each field as input (user-editable) or output (workflow-produced)
   • Configure bypass mappings: map Boolean fields to node groups or individual nodes
7. Build your form UI using Layout Builder:
   • Add ComfyUI Dynamic Field Blocks for each input (media, text, numbers, toggles)
   • Add the ComfyUI Form Container Block for the execution button and results display
8. OPTIONAL: Configure dependency discovery - see Dependency Management
9. OPTIONAL: Enable Media Feedback - see Media Feedback
10. View execution history at /admin/comfyui/executions
11. Publish and let users generate AI content

State API & Scaling

Execution tracking uses Drupal's State API instead of PHP sessions, enabling stateless and horizontally scaled deployments.

Benefits:

• Works with load balancers - no session affinity required
• Supports multi-server deployments without shared session storage
• Automatic cleanup of expired state entries via cron

Configuration at /admin/structure/comfyui-workflow/settings:

Setting Description Default State TTL How long to retain execution context 24 hours Cleanup Batch Size Expired entries removed per cron run 50

Ensure cron is running regularly to prevent state table bloat.

Dependency Management (Optional)

For automating ComfyUI environment setup (installing custom nodes, downloading models):

1. Click "Discover Custom Nodes" - fetches from ComfyUI Manager database (cached)
2. Click "Discover Models" - parses model database and fetches metadata (cached)
3. Access dependency data via JSON:API for startup scripts: /jsonapi/comfyui_workflow/comfyui_workflow/{uuid}

This is optional and intended for infrastructure provisioning, not required for workflow execution.

Media Feedback (Optional)

1. Visit /admin/structure/comfyui-workflow/settings
2. Enable "Media Feedback"
3. Users can rate generated results (thumbs up/down) and leave optional comments immediately after generation
4. Feedback can be edited later via the media entity edit form

ComfyUI-Login (Optional)

For public or multi-user deployments requiring authenticated API access:

1. Install ComfyUI-Login as a custom node in your ComfyUI instance
2. Retrieve your Bearer token from ComfyUI startup logs
3. Enable the comfyui_login submodule in Drupal
4. Store your token using the Key module
5. Select the key in ComfyUI Integration settings

All API requests will automatically include Bearer token authentication.

Key Features

Workflow Management

• Workflow Entities - create reusable ComfyUI workflows as Drupal entities with version management
• Dynamic Field Mapping - map Drupal fields to ComfyUI workflow nodes and parameters with full field type support
• Node Definition Discovery - automatically parses workflows to identify all nodes, inputs, outputs, and types
• Layout Builder Integration - build custom workflow interfaces with drag-and-drop field blocks
• Multiple Display Modes - form mode (interactive UI), API mode (headless/programmatic), batch processing
• Queue Processing - handle long-running workflows with Drupal's queue system for async execution, with automatic fallback polling via cron

Execution History & Provenance

• Complete Execution Records - every workflow execution stored as a comfyui_execution entity with full parameter, user attribution, and timestamp data
• Recursive Lineage Tracking - parent-child relationships span multiple generations; trace any generated image back to its original source through a complete audit trail
• Interactive Lineage Visualization - collapsible tree view with color-coded depth levels, input media thumbnails, and workflow parameters; AJAX lazy-loading for deep chains (3 levels shown by default, expandable on demand)
• Dual-Format Workflow Downloads - download the exact workflow used in any execution:
  • API Format (.json) - exact payload sent to ComfyUI, immediately reproducible via the /prompt endpoint
  • UI Format (.json) - drag-and-drop compatible for the ComfyUI web interface, with applied field mappings and correctly rewired bypass nodes
• Execution Browser - default Views page at /admin/comfyui/executions with sortable columns, status indicators, author attribution, input/output thumbnails, inline lineage trees, and download buttons
• Broken Chain Handling - gracefully preserves and displays metadata when parent executions or associated media are deleted, maintaining historical context without breaking the UI
• Reference-Based Storage - shared references prevent data duplication and exponential storage growth (approx. 100KB vs 6.7MB per execution at scale)

Advanced Workflow Control

• Dynamic Node Bypass - enable or disable entire node groups or individual nodes via Boolean form fields; automatically rewires the workflow to skip bypassed nodes with intelligent iterative handling of cascading dependencies; type-agnostic and works with any custom node or input/output combination; this is the only known implementation of dynamic workflow rewiring through ComfyUI's API
• Smart Seed Management - Random Seed Widget with Fixed/Random/Use Last modes; reproducible generation with persistent seed history for replicating results
• Generic Output Node Detection - pattern-based detection for SaveImage, PreviewImage, custom nodes, and variants including SaveImage_NoWorkflow; automatic recognition of image, video, and text outputs
• Field Validation - configurable validation rules with pre-submission feedback

Media Handling & Security

• Native Drupal Media Library Integration - generated content stored as media entities with rich metadata; full integration with Drupal's media module; reusable across multiple workflows and content types; comprehensive media browser with grid preview
• Dual-Mode Media Browsing - select from existing media library or upload new; thumbnail previews with image resolution display (e.g. 1920-1080px); user-authored filtering to restrict to current user's uploads
• Image Proxy & Streaming - tokenized image proxy with HMAC-SHA256 validation; serves input images from Drupal filesystem with secure token verification; streams output images directly from ComfyUI; supports PNG, JPG, GIF, WebP with automatic CORS headers; cache-based access control with configurable expiration
• Secure Filename Protection - 32-character random hash prefixes prevent sequential enumeration attacks on generated content; automatic injection into SaveImage nodes with audit trail for prompt ID to filename mapping
• Auto-Save on Completion - generated media auto-saved as Drupal media entities after workflow completion; configurable per-workflow; preserves workflow context, prompt ID, and metadata; user-controlled save/discard options

Author Feedback & Quality Control

• Built-in Feedback Collection - thumbs up/down rating with optional comment field; feedback form appears immediately after generation; works with both auto-save and manual save modes
• Quality Insights - track author satisfaction with generated results; feedback stored directly on media entities for easy filtering and analysis; globally configurable via admin settings
• Smart Save Flow - auto-save mode uses a "Save Feedback" button to update existing media; manual mode uses "Save Image and Feedback" to create media and feedback simultaneously; feedback is always optional

Container Orchestration

REST API endpoints designed for stateless ComfyUI container deployments:

• GET /api/comfyui/workflows/uuids - compact list of enabled workflow UUIDs
• GET /api/comfyui/workflows/enabled - full workflow data with stats

Enables Docker containers to automatically fetch and deploy all platform workflows without persistent configuration storage. Access is controlled by the view comfyui workflows permission with entity-level access checks.

Dependency Management

• Custom Node Discovery - automatically detects required custom nodes; dynamically fetches repositories from ComfyUI Manager database (cached); conflict resolution for node overrides; manual override for private/unlisted nodes
• Model Discovery & Mapping - automatically identifies all model dependencies (checkpoints, LoRAs, VAEs, ControlNets, upscalers, etc.); parses ComfyUI Manager model database (cached); provides download URLs, installation paths, and multi-source support (HuggingFace, CivitAI, etc.)
• JSON:API Export - all dependency data accessible via JSON:API for automated startup scripts and environment provisioning

Regulatory Compliance

The execution history and provenance tracking features are designed to support organizations operating under AI regulations. Particularly relevant for enterprise and government deployments.

EU AI Act

Requirement Article How This Module Helps Automatic record-keeping and traceability Art. 12 Every execution stored with full parameter and user data Transparency and explainability Art. 13 Lineage trees show exactly how content was generated Quality management documentation Art. 17 Reproducible execution records with dual-format downloads Audit trails for high-risk systems Art. 9 Multi-generation lineage with broken chain handling

GDPR

Requirement Article How This Module Helps Right to explanation Art. 22 Users can see exactly how and why AI content was generated Records of processing activities Art. 30 Automatic documentation of all AI generation events Transparency principle Art. 5 Complete provenance visibility for all generated content Data minimization Art. 5(1)(c) Reference-based storage prevents unnecessary data duplication

Note: This module provides technical capabilities to support compliance. Legal compliance requires appropriate policies, procedures, and risk assessments for your specific use case and jurisdiction.

REST API

All endpoints support key_auth, cookie, and basic_auth authentication.

Inference

Method Endpoint Description POST /api/comfyui/inference Execute a workflow asynchronously GET /api/comfyui/status/{prompt_id} Poll execution status and retrieve results

Orchestration

Method Endpoint Description GET /api/comfyui/workflows/uuids Compact list of enabled workflow UUIDs GET /api/comfyui/workflows/enabled Full workflow data with stats

Orchestration endpoints require the view comfyui workflows permission.

Perfect For

• Content creators building AI-powered websites
• Developers integrating AI workflows into client projects
• DevOps teams managing ComfyUI deployments with automated dependency installation
• Artists and designers creating AI content management systems
• Agencies offering AI content generation services
• Site builders providing AI tools to users without technical complexity
• Organizations requiring full AI content audit trails and provenance tracking
• Content teams needing to reproduce exact AI generation results
• Enterprise and government deployments requiring regulatory compliance

Troubleshooting & FAQ

After uploading workflow files, field mapping options are not appearing. This is a known alpha limitation. After clicking "Discover Node Definitions", you must re-open the workflow edit form before the discovered nodes appear in the field mapping interface. This will be resolved in a future release.

I upgraded the module and something is broken. Always run drush updb -y after upgrading. Several releases include update hooks that install required configuration changes (State API settings, view updates, schema changes). Check the release notes for BREAKING notices before upgrading.

My State API table is growing very large. Ensure cron is running regularly. You can increase the Cleanup Batch Size in settings to process more expired entries per cron run. Only entries older than the configured TTL are removed.

Executions are not completing when the browser is closed. Enable the ComfyUI Execution Polling queue worker. It automatically polls and completes executions via cron as a fallback when browser-based polling is interrupted.

The lineage tree is showing "deleted" entries. This is expected behavior. When a parent execution or its associated media is deleted, the module preserves and displays the retained metadata rather than breaking the display. Workflow, prompt ID, and parameter history are always kept.

Roadmap

• Workflow Default Values - set ComfyUI node defaults across all workflows
• Chainable Workflows - visual workflow chaining (BPMN/n8n-style) for agentic AI pipelines
• Complete API Submodule - full REST API with OAuth2 authentication
• Multiple Endpoints - queue and process across multiple ComfyUI instances
• External Provider Support - Runpod.io, Vast.ai, etc. with auto-startup
• Dynamic Output Blocks - place image/video/text outputs anywhere in Layout Builder
• Field Workflows - trigger AI generation for any content field (translations, images, etc.)
• Advanced Caching - cache warming and intelligent token invalidation

Maintainers

• Alexander Renfert (NWOM) - alexander-renfert

This module is actively maintained with dedicated sponsorship support. Bug reports, testing feedback, and community contributions are welcome - please submit issues in the project queue.

Partnership Opportunities:

Interested in sponsorship, custom development, or specific feature development? Contact the maintainer to discuss collaboration opportunities.