feat: add workflow tag management and enable tag-based execution for workflows and chatflows by qiaofenlin · Pull Request #23827 · langgenius/dify

qiaofenlin · 2025-08-12T13:40:23Z

Important

Make sure you have read our contribution guidelines
Ensure there is an associated issue and you have been assigned to it
Use the correct syntax to link this PR: Fixes #<issue number>.

Summary

Note

We believe this feature will greatly improve workflow management in enterprise-scale and multi-user collaboration scenarios.
This PR is open to discussion and we are happy to adjust the implementation based on feedback to ensure maximum compatibility and usability.

This PR implements a comprehensive workflow alias management system that enhances the extensibility of Dify's workflow execution capabilities. The implementation consists of two main components:

1. Workflow Alias Management System

Database Schema: Added workflow_aliases table with tenant_id, app_id, workflow_id, alias_name and alias_type fields
Backend API: Implemented complete CRUD operations for workflow alias management
Frontend UI: Added alias management modal with list view, creation, editing, and deletion capabilities
Internationalization: Added Chinese and English translations for all alias management features
Code Quality: Optimized code structure and removed unused components

2. Alias-Based Workflow & Chatflow Execution Update

2.1 Execution Mode Separation

Workflow Execution: /workflows/:identifier/run now supports both workflow_id and Alias execution modes
Chatflow Execution: /chat-messages now accepts a new workflow_alias parameter to trigger Chatflow by alias

2.2 Unified Endpoint Enhancement

Backward Compatibility: Preserves the original workflow_id execution logic while adding Alias support
Priority Resolution: Execution order is:
1. Alias
2. workflow_id
3. Latest published workflow
Error Handling: Improved error messages and response structure for alias resolution failures and execution errors
Code Refactoring: Extracted alias resolution logic into reusable private methods to reduce duplication
Chatflow Compatibility: Added alias resolution logic to the existing /chat-messages flow while keeping the original interface functional

Motivation

Problem Statement

Although Dify supports version history, it currently lacks structured support for multi-environment workflows (e.g., development / testing / release).
In enterprise-scale applications, this limitation can create challenges in collaboration, quality assurance, and safe deployment.

Potential issues in enterprise use cases:

When a workflow needs to be tested, it often must be published first, which introduces the risk of impacting production environments.
To avoid production risks, teams may create duplicate apps for testing purposes, which can lead to:
- Fragmented application management
- Manual API key updates
- Error-prone migration or release processes
QA teams may be unable to easily test a specific version unless it is published, creating a bottleneck in the release cycle.

This leads to slow iterations, duplicated efforts, and deployment errors.

Solution

We propose adding workflow aliases that can control workflow routing, environment binding, and trigger automations.

✅ Key Features:

Alias Types & Rules:
- System aliases (production, staging) are unique per app and cannot be deleted to prevent production disruption, but can be reassigned
- Custom aliases (e.g., dev, feature-xxx) support full CRUD operations and are unique per app
Environment Binding: App can bind API endpoints to specific aliases (e.g., production uses production alias)
Safe Testing: QA can test aliased versions directly without affecting current production
Zero-Downtime Deployment: Changing alias bindings effectively "releases" new versions without API key changes
Execution Priority:
- Workflow API (/workflows/:identifier/run): Aliases have higher priority than workflow_id. If both are empty, returns 400 error
- Chat API (/chat-messages): Aliases have higher priority than workflow_id. If both are empty, uses latest published workflow

🎯 Benefits:

No need to duplicate Apps for testing or rollout
No need to update API Keys in config center
Safe QA testing without affecting production
Centralized collaboration within one app
Better traceability, audit, and rollback control

Key Features

Alias Resolution: Intelligent identifier resolution with priority-based fallback
Backward Compatibility: Maintains full compatibility with existing UUID-based workflow execution
Error Handling: Comprehensive error handling for alias not found, invalid formats, etc.
Documentation: Updated API documentation for all affected endpoints
Code Quality: Clean, maintainable code with proper separation of concerns

Technical Implementation

Database Migration: Single consolidated migration file for workflow alias schema
Service Layer: Dedicated WorkflowAliasService for alias management operations
API Controllers: Enhanced workflow and completion controllers with alias support
Frontend Components: React-based alias management UI with TypeScript support
Testing: Comprehensive testing for alias resolution and execution flows

Screenshots

UI Components

Version History Panel

Before	After

Alias List View

Workflow Execution Examples

Executing by Alias

Executing by Workflow ID

doc

Before	After

Chatflow Execution Examples

Executing by Alias

Executing by Workflow ID

doc

Before	After

Checklist

This change requires a documentation update, included: Dify Document
I understand that this PR may be closed in case there was no previous discussion or issues. (This doesn't apply to typos!)
I've added a test for each change that was introduced, and I tried as much as possible to make a single atomic change.
I've updated the documentation accordingly.
I ran dev/reformat(backend) and cd web && npx lint-staged(frontend) to appease the lint gods

…s-management

- Add workflow alias management functionality with CRUD operations - Implement batch query support for efficient alias retrieval - Optimize cache strategy to reduce network requests - Add alias management UI components and modal dialogs - Support system and custom alias types (production, staging, etc.) - Add comprehensive i18n support for multiple languages - Include database migrations and model definitions - Add unit tests and integration tests for alias functionality - Clean up unused code and improve maintainability

Copilot

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

…back - Use StrEnum instead of Enum for AliasType - Remove explicit primary key constraint naming - Use mapped_column index parameter for single field indexes - Optimize identifier resolution priority (UUID > alias) - Simplify validation logic by removing redundant checks - Update API docs to reflect correct priority order

- Replace bulk loading with pagination for better performance - Use Pydantic models for parameter validation and error handling - Implement infinite query pattern for frontend data fetching - Standardize pagination logic across the application - Optimize default limits for production use

…e/workflow-alias-management # Conflicts: # web/app/components/workflow/nodes/_base/hooks/use-toggle-expend.ts

Kevin9703 · 2025-12-15T09:27:54Z

I’m really looking forward to this feature.

- Resolved merge conflicts - Updated workflow alias feature to work with latest main - Migrated i18n from .ts to .json format

- Changed down_revision from d57accd375ae to 3334862ee907 - Removed unnecessary merge migration file

- Add validation for workflow_id/workflow_alias in chat-messages endpoint - Return 400 BadRequest instead of 404/500 for invalid workflow identifiers - Verify workflow existence when UUID format is valid - Fix i18n translation calls in alias-management-modal and use-context-menu - Add missing fetchWorkflowRunHistory export in service/workflow.ts

- Move tag.* entries to correct alphabetical position - Unify Chinese translations from '别名' to '标签' - Remove duplicate tag entries at end of file

- Rename add_workflow_alias_management to add_workflow_tag_management - Remove separate rename migration file (a7b3c9d2e1f4) - Create workflow_name_tags table directly instead of creating and renaming

- Fix antfu/if-newline errors by adding newlines after if statements - Fix react-hooks-extra/no-direct-set-state-in-use-effect by using setTimeout - Fix ts/no-explicit-any errors by replacing 'any' with 'unknown' type Files modified: - web/app/components/workflow-app/hooks/use-workflow-init.ts - web/app/components/workflow-app/components/workflow-header/index.tsx - web/app/components/workflow/panel/version-history-panel/tag-management-modal/index.tsx Result: 0 errors, 1523 warnings (warnings only, no blocking errors)

laipz8200 · 2026-05-08T09:30:23Z

Thank you for your contribution!

However, this PR appears to be outdated, so I will be closing it. If you still need this change, please feel free to resubmit a new PR.

qiaofenlin added 2 commits August 12, 2025 20:33

feat: build version alias management system

212bfd5

feat: support executing workflow and chatflow by alias

492494a

dosubot Bot added size:XL This PR changes 500-999 lines, ignoring generated files. 💪 enhancement New feature or request 📚 documentation Improvements or additions to documentation labels Aug 12, 2025

remove badsmell

3b74a69

qiaofenlin force-pushed the feature/workflow-alias-management branch from cf6753a to 3b74a69 Compare August 12, 2025 14:54

Merge remote-tracking branch 'origin/main' into feature/workflow-alia…

92911b2

…s-management

qiaofenlin force-pushed the feature/workflow-alias-management branch 7 times, most recently from a52cd87 to b6eb424 Compare August 13, 2025 05:22

qiaofenlin force-pushed the feature/workflow-alias-management branch from 05633af to f36fef1 Compare August 13, 2025 05:34

crazywoola requested a review from Copilot August 13, 2025 05:56

Copilot AI reviewed Aug 13, 2025

crazywoola requested review from Nov1c444 and laipz8200 August 13, 2025 05:56

qiaofenlin changed the title ~~feat: implement workflow alias management system and support alias-based execution~~ feat: add workflow alias management and enable alias-based execution for workflows and chatflows Aug 13, 2025

laipz8200 requested changes Aug 14, 2025

View reviewed changes

qiaofenlin force-pushed the feature/workflow-alias-management branch from dc38953 to b975e51 Compare August 15, 2025 04:38

qiaofenlin requested a review from laipz8200 August 15, 2025 04:39

laipz8200 requested changes Aug 17, 2025

View reviewed changes

Comment thread api/services/workflow_alias_service.py Outdated

Comment thread api/services/workflow_alias_service.py Outdated

qiaofenlin requested a review from laipz8200 August 18, 2025 03:23

Merge branch 'main' of https://github.com/langgenius/dify into featur…

8a5a124

…e/workflow-alias-management # Conflicts: # web/app/components/workflow/nodes/_base/hooks/use-toggle-expend.ts

qiaofenglin and others added 3 commits December 9, 2025 19:41

fixed workflow_alias

795d2ee

fix: improve workflow alias service dependency injection and type safety

750f221

[autofix.ci] apply automated fixes

42349b9

qiaofenglin added 3 commits January 16, 2026 17:38

Merge branch 'main' into feature/workflow-alias-management

b9aef2a

- Resolved merge conflicts - Updated workflow alias feature to work with latest main - Migrated i18n from .ts to .json format

chore: rebase workflow_alias migration to latest main

191ca33

- Changed down_revision from d57accd375ae to 3334862ee907 - Removed unnecessary merge migration file

qiaofenlin requested a review from MRZHUH as a code owner January 16, 2026 11:09

qiaofenlin and others added 4 commits January 16, 2026 19:10

Merge branch 'main' into feature/workflow-alias-management

4895ecd

[autofix.ci] apply automated fixes

5d1b5d1

chore(i18n): organize tag translations and unify terminology

185d733

- Move tag.* entries to correct alphabetical position - Unify Chinese translations from '别名' to '标签' - Remove duplicate tag entries at end of file

style: sort import statements alphabetically

ef8b326

qiaofenlin changed the title ~~feat: add workflow alias management and enable alias-based execution for workflows and chatflows~~ feat: add workflow tag management and enable tag-based execution for workflows and chatflows Jan 16, 2026

autofix-ci Bot and others added 6 commits January 16, 2026 12:48

[autofix.ci] apply automated fixes

2f293ef

refactor(migration): merge workflow tag migration files into single file

dea2790

- Rename add_workflow_alias_management to add_workflow_tag_management - Remove separate rename migration file (a7b3c9d2e1f4) - Create workflow_name_tags table directly instead of creating and renaming

docs: update workflow API documentation terminology from '别名' to '标签'

db14add

fixed web tests

c42fd14

Merge branch 'main' into feature/workflow-alias-management

f4a8272

qiaofenlin requested review from Yeuoly and laipz8200 January 18, 2026 14:11

qiaofenlin and others added 4 commits January 19, 2026 10:38

Merge branch 'main' into feature/workflow-alias-management

ace989b

Merge branch 'main' into feature/workflow-alias-management

8627f6c

update migration

4341462

Merge branch 'main' into feature/workflow-alias-management

eddc56d

github-actions Bot added the web This relates to changes on the web. label Jan 29, 2026

qiaofenlin and others added 2 commits January 29, 2026 10:19

Add migration for workflow tag management

901b4b5

[autofix.ci] apply automated fixes

4472b62

laipz8200 closed this May 8, 2026

Navigation Menu

Repository navigation

feat: add workflow tag management and enable tag-based execution for workflows and chatflows - #23827

feat: add workflow tag management and enable tag-based execution for workflows and chatflows#23827
qiaofenlin wants to merge 213 commits into
langgenius:mainfrom
qiaofenlin:feature/workflow-alias-management

qiaofenlin commented Aug 12, 2025 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Kevin9703 commented Dec 15, 2025

Uh oh!

laipz8200 commented May 8, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

Conversation

qiaofenlin commented Aug 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

1. Workflow Alias Management System

2. Alias-Based Workflow & Chatflow Execution Update

2.1 Execution Mode Separation

2.2 Unified Endpoint Enhancement

Motivation

Problem Statement

Potential issues in enterprise use cases:

Solution

✅ Key Features:

🎯 Benefits:

Key Features

Technical Implementation

Screenshots

UI Components

Workflow Execution Examples

Chatflow Execution Examples

Checklist

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Kevin9703 commented Dec 15, 2025

Uh oh!

laipz8200 commented May 8, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

qiaofenlin commented Aug 12, 2025 •

edited

Loading