Versioning

Versioning enables you to manage changes, track progress, and collaborate effectively by capturing snapshots of your project’s state at any point in time. The versioning system ensures that resources are grouped and tracked as part of the project, providing a comprehensive and structured approach to development.

​

Project version

A Project Version is an editable snapshot of your project at a specific moment. It contains all resources (e.g., processes, integrations, templates) and configurations grouped under the project.

• Project: The main project entity that contains all your resources (processes, integrations, templates, etc.)
• Project Branch: Branches within a project (similar to Git branches) that allow parallel development
• Project Version: Individual versions within branches that track the state of your project

Each version can have one of the following statuses:

• WIP (Work In Progress): Draft versions that are actively being edited
• COMMITTED: Finalized versions that have been submitted with a commit message
• MERGE_IN_PROGRESS: Versions currently being merged between branches

The tab above provides a summary of all accessible project versions and branches available in the current environment.

---

​

Version details

• State: Displays the current state of the version (e.g., draft, committed).
• Branch: Indicates the currently selected branch (e.g., main).
• Last Saved By: Shows the username of the person who last saved changes (e.g., “JS”).
• Last Saved At: Displays the timestamp of the most recent save (e.g., “23 Jan 2025 at 10:11 AM”).
• ID: A unique identifier for the version, with a copy button for convenience.
• Resources Changed: Displays a summary of modified, added, or deleted resources compared with the previous version (visible only for draft versions with changes).

​

Resources changed

The Resources Changed section provides a clear overview of all modifications made in the current draft version compared to the last committed version. This helps you track exactly what has been modified before committing your changes. The list groups changes by resource type, including:

• CMS \ Enumerations: Modified enumeration values (for example, country lists, dropdown options)
• Processes: Changed process definitions
• Project Data Model: Updates to the data model structure
• CMS \ Substitution Tags: Modified substitution tags
• CMS \ Media Library: Added, modified, or deleted media assets
• Task Manager \ Views: Changes to task manager view configurations
• Dependencies: Updated project dependencies
• Resource Overrides: Modified resource override configurations

Each resource is color-coded to indicate the type of change:

​

Compare versions

The Compare Versions feature allows you to select two versions and view the differences between them. This is useful for understanding what changes were made between any two points in your project’s history. To compare versions:

1. Select a version in the branch graph
2. Click on the Compare with current version button at the bottom of the graph to quickly compare any committed version with the current draft version.

The comparison view displays:

• Comparing current version: Shows the first selected version with its branch, state, and last edited timestamp
• with: Shows the second selected version being compared against
• Resources changed: Lists all resources that differ between the two versions

​

Viewing detailed resource changes

To inspect the specific changes made to a resource, hover over any item in the Resources changed list and click the eye icon that appears. This opens a detailed comparison modal. The Changes modal provides a side-by-side JSON comparison:

• Left panel: Shows the version you are comparing with (the previous/committed version)
• Right panel: Shows the current draft version
• Highlighted lines: Added or modified content is highlighted in green, making it easy to identify what changed

​

Resource history

The Resource History feature lets you view the version history for a specific resource, showing which project versions included changes to that resource. To access it, right-click any resource (process, enumeration, substitution tag, media asset, integration, etc.) and select View History. This opens the Resource History modal. The modal displays a table with the following columns: For each version in the list, you can:

• See changes — Opens a comparison view showing what changed in this resource between the selected version and the previous one
• Open version in new tab — Navigates to the full project version in a new browser tab

​

Branch and commit graph

The graph visually organizes the project’s versioning structure, showing relationships between branches and commits.

• Graph View:
  • Provides a visual representation of branches and commits.
  • Main Branch (blue): The main development branch.
  • Secondary Branches (yellow): Feature or development branches such as branch3, branch4, and secondary_branch.
  • Markers:
    • Dotted Circles: Represent draft versions.
    • Solid Circles: Represent committed versions.

​

Commit history

• Displays a chronological list of commit messages for the selected branch.
• Details:
  • Commit messages (e.g., v1, commit_secondary_branch) are aligned with their respective branches.
  • Each commit shows:
    • The user responsible (e.g., “JS”).
    • The state of the commit (e.g., draft, commited).

​

Header and version block

The header at the top of the page shows the project name, the Config and Runtime switch, and Run project (the play icon). Run project starts the project’s entry point. On Config, it starts the entry point of the selected version, drafts included. On Runtime, it starts the build that the active build policy serves. A UI flow runs only from a build: when a version’s entry point is a UI flow, Run project on Config offers Run from Runtime instead. If the version has no entry point, you see Entry Point not set. Run project isn’t shown for libraries or on a running process instance. The version block sits at the start of the footer on every Config page of a version:

• Branching (the branch icon) opens the branching graph.
• Version head shows the branch name, the state, and the version label: the build tag, Draft version for a work-in-progress version, or the commit message. Click it to open the branch picker: search branches, filter by owner (All branches or My branches), pick a branch to switch to its latest version or pick one of its versions, or select View all branches.
• Commit Changes on a work-in-progress version, or Start New Version on a committed version that is the last one on its branch.

---

​

Core versioning operations

The table below summarizes key versioning operations and their functions:

​

Detailed steps for operations

---

​

Lifecycle of a project version

1. Create Project: Automatically starts with a draft (work-in-progress) project version.
2. Modify Resources: Draft (WIP) resources can be edited directly, while COMMITTED resources are cloned into draft (WIP) before editing.
3. Commit Changes: Promotes the project version and its resources to COMMITTED status.
4. Start New WIP: Allows iterative development by creating a new draft version.
5. Create Branch: Enables parallel development with isolated draft versions.

---

​

Starting a new draft version

You can initiate a new draft (work-in-progress) version while keeping the committed version intact. A draft version is automatically created under the following circumstances:

• New Project: When you create a new project, a corresponding draft version is initiated. This ensures that ongoing changes are tracked separately from the committed version.

• New Branch Creation: The creation of a new branch in the system also triggers the creation of a draft version (from a committed version only). This simplifies the process of branching and development, allowing for parallel progress without impacting the main committed version.

• Manual Draft Version Creation: You have the flexibility to initiate a new draft version manually. This is particularly useful when building upon the latest version available on a branch.

---

​

Advanced features

​

Committing changes

You can commit changes exclusively on work-in-progress (WIP) versions. Commit changes with Commit Changes in the version block at the start of the footer. Upon triggering the commit action, a modal window appears, prompting you to provide a commit message. The placeholder indicating work-in-progress is replaced with a “committed” state within the graph view. The commit modal also checks the version for problems and shows what it found next to each changed resource. The findings do not block the commit. See Checking a version for issues.

​

Updating commit messages

You have the flexibility to modify commit messages after changes are committed. This can be accomplished using the action available in the version menu.

​

Commit descriptions and details

A commit can carry a longer description next to its short commit message. The commit message stays the short label you see in the branch graph and commit history, and the description records what changed and why. When you commit, the Commit Changes modal has two fields:

• Commit Message: required, between 2 and 200 characters. Punctuation such as commas is accepted.
• Description: optional, up to 2000 characters. A counter under the field shows how many characters you have used.

Click Commit to create the version. Spaces at the start and end of both fields are trimmed, and a description left empty is not saved. The Merge Branch modal has the same optional Description field under Merge Message, with the same 2000-character limit, so a merge can explain what it brings in. To read the message and description of a committed version: To change the message or description of a committed version, open its Commit details view and click the pencil icon (Rename Commit Message) in the header. The Edit Commit Message modal opens with the same Commit Message and Description fields. Click Save to apply the change. The icon is shown only if you can edit the project.

​

Creating a new branch

Using versioning you can work on a stable copy of the project, isolated from ongoing updates by other users. You can create a new branch starting from a specific commit point. The initiation of new branches is achieved using the dedicated action located in the left menu of the chosen commit point (used as the starting point for the branch).

​

Merging changes

You can incorporate updates made on a secondary branch into the main branch or another secondary branch. To ensure successful merging of changes, adhere to the following criteria:

• You can merge the latest version from a secondary branch into either its direct or indirect parent branch.

• Upon triggering the merge action, a modal window appears, giving the possibility to make the following selection:
  • Branch: Displays the branches to which the current branch is a child (direct or indirect).
  • Message: Required, between 2 and 50 characters. Punctuation such as commas is accepted.

The graph representation is updated to display the new version on the selected parent branch and the merged version is automatically selected, facilitating further development and tracking.

​

Managing branches

Branch management grew a set of operations of its own, available from the branching overlay and the branch info panel:

• Merge to any branch: the merge modal’s Branch list now offers every branch the current branch can merge into, not only its direct or indirect parents.
• Archive Branch: retire a branch you are done with. A Reason is required (“Why is this being archived?”), and the branch’s info panel then shows who archived it and why. Versions already merged into other branches are kept there. An archived branch can be restored with Unarchive Branch.
• Delete Branch: permanently remove a branch from the branching overlay. Deleting is blocked while the branch has child branches, an uncommitted draft, or a merge in progress, and if unmerged commits would be lost you must type the branch name to confirm. It requires its own permission, so not everyone who can edit a project can delete its branches.
• Branch info panels: selecting a branch or a version in the branching overlay opens an info panel with its Branch Summary, and versions merged from another branch show where they came from, including whether that source branch has since been archived.

​

Managing conflicts

The Conflict Resolution and Version Comparison feature provides a mechanism to identify and address conflicts between two process versions that, if merged, could potentially disrupt the integrity of a project. The system displays both the version to be merged and the current version on a single screen, providing a clear visual representation of the differences. Conflicts and variations between the two versions are highlighted, enabling users to readily identify areas requiring attention.

​

Merging without conflicts

Easily merge secondary branches into the main branch or other branches when no conflicts are detected. The updated merge modal includes:

• A clean interface for branch selection.
• A mandatory, validated commit message field (max 50 characters).
• Real-time feedback for successful merges and updates to the branching graph.

The merge modal also takes an optional Description of up to 2000 characters next to the merge message. See Commit descriptions and details.

​

Advanced conflict detection

The new Conflicts Detected Modal provides a detailed overview of conflicting changes, with features such as:

• Clear grouping by resource type (e.g., Processes, Enumerations, Media Library).
• Scrollable lists and clickable entries to resolve conflicts efficiently.
• A comprehensive comparison of source and target branch differences for context.

​

Resource-level conflict resolution

Resolve conflicts directly at the resource level with an intuitive interface:

• JSON Comparisons: Visualize differences with color-coded highlights (source: yellow, target: blue).
• Navigation Support: Quickly jump between differences for efficient resolution.
• Progress Tracking: Mark resources as “Reviewed” or “Seen” to monitor resolution progress.

​

Substitution tag conflicts

Substitution tag conflicts are resolved per tag and per language. Each tag appears under its key, and its values per language appear under Translations:

• Deleted on one branch, changed on the other: select the tag to open its Translations and choose a side. The tag is kept or deleted to match the side the Translations end on.
• Renamed differently on each branch: the merged version keeps both names as two separate tags.

​

Flexible merge overrides

Handle unresolved conflicts with the Merge Anyway option, which provides flexibility while maintaining control over outcomes:

• A confirmation modal explains how unresolved conflicts will be handled (e.g., prioritizing source branch changes).
• Allows merging to continue even when some conflicts remain unresolved.

​

Merging empty User Task nodes

Adding components to the same User Task node on two parallel branches, when that node was empty at the point the branches diverged, is a special case the merge can’t resolve as a conflict. Each branch creates its own root container with a distinct ID, so there is no shared resource to compare and the system doesn’t flag a conflict. Starting with FlowX.AI 5.9.2, when this happens the merge keeps the source branch container together with all of its content and removes any other root containers. To review or recover removed content, open the previous version from the Resource history.

​

Node layout after merging

Node positions and swimlane sizes are not part of conflict detection. A merge never flags layout differences, and it reports success even when the resulting diagram needs manual cleanup. Which layout the merge keeps depends on whether the process also changed on the target branch after the branch was created:

• Process unchanged on the target branch: the merge applies the source branch layout as is.
• Process changed on both branches: the merge keeps the node positions and swimlane size of the target branch. Nodes that were repositioned on the source branch return to their target-branch positions (a node moved to a different swimlane keeps its source-branch position), while nodes added on the source branch keep their source-branch coordinates. New nodes can therefore end up on top of existing nodes or outside the swimlane, shown in a red error state.

Any committed change to the process on the target branch counts as a change here, including a layout-only rearrangement. If a node has a genuine conflict and you resolve it by keeping the source version, that node also takes its source-branch position, so a merged diagram can mix positions from both branches. Only the placement is affected: sequences, node configuration, and the other merged changes are applied correctly, and the process still commits and runs.

​

Read-only state

The Read-Only State feature allows you to access and view committed versions of your projects while safeguarding the configuration from unintended modifications. By recognizing the visual indicators of the read-only state, you can confidently work within a controlled environment, ensuring the integrity of project’s process definitions.

---

​

Builds

A build is a deployable snapshot of a committed project version, packaged and prepared for deployment to a runtime environment. Builds enable you to create immutable, versioned packages that can be deployed consistently across different environments.

​

Creating a build

To create a build from a committed project version:

​

Managing builds

The Builds section provides a centralized interface for viewing and managing all builds for your project.

​

Builds list

The builds list displays all builds created for the project, showing:

• Build name and version: Displays the build name and tag version (e.g., Update_process_variables 1.0.0)
• Build actions: Each build entry provides quick access to:
  • Play/Run:
    • Test build
    • Test endpoint
    • Test workflow
    • Test operation
  • Export:
    • Export the build
  • More options: Additional actions via the context menu
    • View contents
    • Workflow test instances
    • Audit log
    • Apply indexes

​

Searching builds

Use the Search by build tag field to quickly find specific builds by their version tag or name.

​

Exporting versions

You can export project versions for backup, migration, or sharing across environments. The export process includes an option to include binary files.

​

Build immutability

Once a build is created, it becomes immutable—you cannot modify its contents. This ensures:

• Consistency: The same build behaves identically across all environments
• Traceability: You can always identify exactly which project version is running
• Stability: Prevents accidental changes that could affect production systems

To incorporate changes into a build:

1. Make your changes in the project (creating a new draft version)
2. Commit the changes to create a new project version
3. Create a new build from the updated committed version

---

​

Audit view

The “Open Audit View” provides you with a detailed audit log of actions related to work-in-progress (WIP) versions of a process. The primary goal is to ensure transparency and accountability for actions taken before the commit or save process. You can quickly access and review the history of WIP versions, facilitating efficient decision-making and collaboration.