feat: add workflow alias management and enable alias-based execution for workflows and chatflows

[qiaofenlin]

[!IMPORTANT]

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

Fixes https://github.com/langgenius/dify/issues/23639

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

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

[laipz8200]

Because we switched to Flask-RESTX recently, please sync your code with the main branch.

[qiaofenlin]

Because we switched to Flask-RESTX recently, please sync your code with the main branch.

Thanks, I’ll update my branch accordingly.

[qiaofenlin]

Sorry for being late, I have some suggestions for you.

@laipz8200 Thanks a lot for your suggestions! I’ve made the changes based on your feedback. Could you please take another look and let me know if there’s anything else we can improve together? 🙂

[laipz8200]

Sorry for being late, I have some suggestions for you.

@laipz8200 Thanks a lot for your suggestions! I’ve made the changes based on your feedback. Could you please take another look and let me know if there’s anything else we can improve together? 🙂

It's better to resolve conflicts first:)

[qiaofenlin]

Sorry for being late, I have some suggestions for you.

@laipz8200 Thanks a lot for your suggestions! I’ve made the changes based on your feedback. Could you please take another look and let me know if there’s anything else we can improve together? 🙂

It's better to resolve conflicts first:)

@laipz8200 Thanks for the reminder! I’ve resolved the conflicts as suggested and updated the changes. Could you please take another look and let me know if anything else needs to be adjusted? 🙂

[laipz8200]

Hi @qiaofenlin, we've updated our workflow engine and RAG system recently, and it seems some conflicts arose—would you mind resolving them again?

[DavideDelbianco]

is there a release date for this feature?

[qiaofenlin]

Hi @qiaofenlin, we've updated our workflow engine and RAG system recently, and it seems some conflicts arose—would you mind resolving them again?

Hi @laipz8200 , thanks for your patience! I’ve resolved the conflicts and updated the PR. Please take another look when you have a chance.

[qiaofenlin]

is there a release date for this feature?

Hi @DavideDelbianco，Sorry for the delay — I’ve been quite busy recently and couldn’t handle it earlier. The issue has now been fixed, and the feature is ready. As for the release date, there isn’t a confirmed schedule yet, but I’ll try to help push the merge as soon as possible. I’ll update here once there’s more info.

[qiaofenlin]

/gemini review

[qiaofenlin]

/gemini review

[qiaofenlin]

/gemini review

[qiaofenlin]

/gemini review

[qiaofenlin]

Hi @qiaofenlin, please check my comments, thank you.

Hi @laipz8200 , I've made the revisions as per your feedback. Could you kindly review it again when you have a moment? Thanks!