Flow Versioning – Branch-Based History

Overview

Flow Versioning – Branch-Based History keeps a structured version history of a flow. Every save and every import is recorded as a version in the format X.Y.Z. Versions are grouped into branches in the format X.Y. The active working copy of the flow is the tip of one branch, called the Current Working Version (CWV).

Users can:

• compare a historical version with the current working copy

• restore a previous version

• export a version to a portable yflow file

• import a yflow file into version history

---

What problem it solves

1. Protects Work During Iteration

• Flow designers can make changes with confidence, knowing that previous working states are preserved.

• Every save automatically creates a recoverable version, allowing users to revert if needed.

2. Supports Parallel Development

• Branches enable teams to maintain and develop multiple versions of a flow independently.

• This makes it easier to experiment with new changes while preserving existing work.

3. Eliminates the Need for Manual Backups

• Version history reduces the need to create duplicate flows for backup purposes.

• All changes are automatically tracked and stored within the versioning system.

4. Enhances Recovery and Traceability

• A complete version history provides visibility into the evolution of a flow.

• Users can review:

  • Who made changes

  • When changes were made

  • What changes were introduced

  • Which versions can be restored

This improves accountability, simplifies troubleshooting, and makes recovery from unintended changes much easier.

---

Why use Flow Versioning

Flow Versioning helps teams manage flow changes safely and efficiently by maintaining a complete history of versions and branches.

Key Benefits

• Protect Changes Every save creates a version, ensuring previous working states can be recovered if needed.

• Restore with Confidence Easily roll back to an earlier version when a change causes issues or an older state needs to be revisited.

• Compare Versions Review differences between historical versions and the Current Working Version (CWV) to understand what has changed.

• Support Parallel Development Use branches to maintain multiple lines of development, such as testing new ideas while preserving a stable version.

• Reduce Manual Backups Eliminate the need to create duplicate flows for backup purposes, as version history automatically preserves changes.

• Improve Traceability Maintain a clear record of when changes were made, who made them, and which versions can be restored.

• Enable Easy Sharing and Migration Export versions as .yflow files and import them into version history when needed.

Overall, Flow Versioning provides a safer, more organized way to manage flow development, track changes, and recover from mistakes.

---

Core Concepts

1. Version Format

Every saved or imported flow state is captured as a version using the X.Y.Z format.

• Example: 2.1.3

• Versions are grouped under a branch, identified by the X.Y format.

  • Example: 2.1

• The Final number (Z) represents a specific saved state or revision within that branch.

2. Current Working Version (CWV)

The Current Working Version (CWV) is the active, editable version of a flow.

• Represents the latest version at the tip of the active branch.

• Serves as the primary working copy for ongoing development.

• The runtime executes the current working copy directly.

3. Branches

Branches organize versions into separate lines of development.

• Enable teams to iterate and experiment without losing previous work.

• Preserve historical versions while allowing ongoing changes.

• Function as logical version paths rather than separate copies of a flow.

4. Version Descriptions

Each version can include an optional description to provide additional context.

• Descriptions are free-text and intended for documentation purposes.

• They help users understand the purpose of a change or version.

• Descriptions do not affect flow behavior or versioning logic.

• Flow Versioning does not support named versions; versions are identified solely by their version number.

---

How the feature works

1. Save behavior

• Every time a flow is saved, a new version is created.

• The new version becomes the latest patch on the current branch.

2. Import behavior

• A '.yflow' file can be imported into a flow’s version history.

• Importing creates a new version record.

• Importing does not automatically replace the current working copy.

• The imported version must be restored before it becomes active.

3. Compare behavior

• Users can compare any stored version against the current working copy.

• This helps review differences before restoring a version.

• Compare is part of the current feature scope.

4. Restore behavior

• Restoring a version does not switch the flow to that historical record directly.

• Instead, the restored content is applied as a new patch on the current branch.

• The working copy is replaced in place.

• The system:

  • Reuses the existing flowId

  • Preserves node IDs

  • Preserves integration IDs

  • Does not remap those objects

5. Export behavior

• Any version can be exported to a portable '.yflow' file.

• This allows movement, backup, or later import of a version snapshot.

---

User workflow

1. View version history

• Open the flow and access its version history.

• Review versions organized by branch.

2. Review the current working version

• Identify the Current Working Version (CWV).

• This is the active working copy currently being served by runtime.

3. Save changes

• Make edits to the flow and save.

• Each save creates a new patch version on the active branch.

4. Compare a prior version

• Select a historical version and compare it against the current working copy.

• Review differences before deciding whether to restore.

5. Export a version

• Select a version and export it as a '.yflow' file.

• Store the file for backup, transfer, or future reuse.

6. Import a '.yflow' file

• Import a '.yflow' file into the flow’s version history.

• The imported file becomes a version in history but does not replace the working copy immediately.

7. Restore a version

• Choose a version to restore.

• The system restores that content as a new live patch on the current branch.

• The working copy is updated in place.

8. Re-validate after restoring

• After restore, the flow is re-validated before continued use.

---

Restore Behavior

The Restore action allows you to revert a flow to the content of a previous version while keeping the flow's identity and configuration intact.

What Restore Does

When a version is restored:

• The content from the selected historical version is retrieved.

• That content is applied as a new patch version on the current branch.

• The current working copy is updated and replaced with the restored content.

This approach preserves version history while making the selected version's content the active working copy.

What Restore Does Not Do

Restore updates the flow's content only. It does not:

• Create a new flow

• Generate a new flowId

• Remap node IDs

• Remap integration IDs

The restored version remains associated with the same flow and existing resources.

What Is Preserved

During a restore operation, the following identifiers remain unchanged:

• Flow ID (flowId)

• Node IDs

• Integration IDs

Maintaining these identifiers ensures continuity across integrations, references, and runtime operations.

Runtime Impact

Because runtime execution uses the current working copy directly, a restore takes effect immediately after it is completed. Any new traffic routed to the flow will use the restored version.

For flows that are actively receiving live traffic, users should be notified before completing a restore operation.

Warning: Restoring a version on a live-routed flow can immediately impact active traffic. Review the selected version carefully and ensure stakeholders are aware of the change before proceeding.

---

Integration handling during restore

1. If an integration definition has changed

• When a restored flow references an integration, whose definition has changed, the user chooses for each affected integration whether to:

  • keep the current definition (default)

  • or *revert to the restored definition

2. Default behavior

• The default option is to keep the current integration definition.

3. Important warning

• Reverting an integration definition may affect other flows that use the same integration.

4. Missing references

• If references are missing, they are flagged during the restore process.

5. Validation step

• After restore, the flow is re-validated to detect any remaining issues.

---

Example use cases

1. Recover from a bad release

• A change introduces an issue into the working copy.

• The team compares the current version with a prior stable version.

• They restore the stable version.

• The restore creates a new patch on the current branch and becomes active immediately.

2. Maintain separate lines of work

• One branch holds the current production-ready line.

• Another branch can hold a new release path or design direction.

• Teams can compare versions without duplicating the entire flow.

3. Import and activate a shared flow version

• A designer receives a '.yflow' file.

• They import it into version history.

• They review it and compare it to the working copy.

• They restore it only when ready to make it active.

---

Example from the demo

Complete flow of the Demo refer to this document

1. Save creates versions

• Each save creates a new version.

2. Compare versions

• Users can compare a historical version with the live/current version.

• The comparison highlights flow changes while hiding unchanged groups for readability.

3. Restore and staging behavior

• The demo showed that older versions can be restored or staged through import before being made active.

4. Based on the current implementation:

• Only one version can be live at any given time.

• A version cannot be tested directly in isolation without first making it the active version.

• For isolated testing scenarios, users can export a flow as a .yflow file and import it into a separate environment or flow instance for validation and experimentation.

Note: Exporting and importing a flow is currently the recommended approach when you need to evaluate a version without affecting the live flow.