> ## Documentation Index > Fetch the complete documentation index at: https://docs.flowx.ai/llms.txt > Use this file to discover all available pages before exploring further. # Versioning > Easily track and manage your project's evolution with comprehensive versioning features. 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 ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-01-22%20at%2019.09.53.png) The tab above provides a summary of all accessible project versions and branches available in the current environment. > [!NOTE] > > Resources within a project (e.g., processes, integrations, templates) are versioned as part of the project, not individually. > [!NOTE] > > Certain resources are considered **global** and are not included in project-specific versioning. These resources are shared across projects and environments to maintain consistency and simplify their management. Examples of such global resources include: > > * **Themes**: Predefined design themes used across multiple projects. > * **Fonts**: A library of fonts accessible globally. > * **Global Media Files**: Shared media assets. > * **Out of Office Settings**: Configurations for user availability and auto-responses that are managed at the platform level. *** ## Version details ![Version Details panel for a draft version](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.6/version_details_draft.png) * **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. ![Resources Changed](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/version_details_resources_changed.png) 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: | Color | Meaning | | - | - | | **Yellow** | Modified resource | | **Green** | Added resource | | **Red** | Deleted resource | > [!TIP] > > Use the Resources Changed list to review all pending modifications before committing. This ensures you have a complete understanding of what will be included in the commit. ### 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. ![Compare Versions](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/compare_v.png) 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. ![View Resource Changes](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/Screenshot%202025-11-27%20at%2017.49.50.png) 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 Changes Modal](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/Screenshot%202025-11-27%20at%2017.50.19.png) > [!NOTE] > > This feature helps you track changes across multiple commits, review what was modified before a specific release, or understand the evolution of your project over time. ### 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: | Column | Description | | - | - | | **Version** | The project version that included a change to this resource | | **Last edited by** | The user who last modified the resource in that version | | **Last edited at** | The timestamp of the last modification | 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 > [!NOTE] > > Resource history tracks changes at the project version level. Individual resources do not have their own independent version history — they are always versioned as part of the project. ### 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: | Operation | Description | | - | - | | **Create Project** | Creates a project and its initial draft version. | | **Create Resource** | Adds a new resource in draft status to the current project version. | | **Edit Resource** | Creates a deep copy of a resource for editing if the original is COMMITTED. | | **Commit Project** | Updates the statuses of the project, its manifest, and resources to COMMITTED. | | **Discard draft** | Deletes draft resources and the draft project version. | | **Start New draft** | Creates a new draft version by copying the last COMMITTED project version. | | **Create Branch** | Creates a new branch and a corresponding draft project version from the selected commit. | ### Detailed steps for operations **1. Create Project** * A new project is created in draft (WIP) state. * An initial draft project version is automatically generated. **2. Create Resource** * Adds a resource in draft status to the current project version. * Updates the project manifest to include: * **UUID** of the new resource. * `last_change_time`: Set to the current timestamp. * `last_committed_time`: Null (since the resource is WIP). **3. Edit Resource** * **Scenario A**: Editing a draft Resource * No new resource version is created. * Updates the project manifest: * `last_change_time`: Current timestamp. * **Scenario B**: Editing a `COMMITTED` Resource * A deep copy of the `COMMITTED` resource is created as draft. * Updates the project manifest: * Links to the new draft resource. * `last_change_time`: Current timestamp. **4. Commit Project** * Commits the current draft project version: 1. **draft Resources**: * Status: Updated to `COMMITTED`. * `last_change_time` and `last_committed_time`: Set to the current timestamp. 2. **Project Version**: * Status: Updated to `COMMITTED`. **5. Discard Draft** * Deletes draft resources and the draft project version. * Available only when there are changes after the last commit. **6. Start New Draft** * Creates a new draft project version by copying: * The last `COMMITTED` project version. * Its manifest, linking to `COMMITTED` resources. **7. Create Branch** * Creates a new branch and draft project version: * Copies the selected `COMMITTED` project version. * Updates the manifest to reference existing `COMMITTED` resources. *** ## 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. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/2025-01-28%2013.35.54.gif) * **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. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-01-28%20at%2013.39.50.png) * **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. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/2025-01-28%2013.47.04.gif) *** ## 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. > [!NOTE] > > A commit message is mandatory, between 2 and 200 characters. Punctuation such as commas is accepted; see [Commit descriptions and details](#commit-descriptions-and-details). 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](https://docs.flowx.ai/6.x/docs/projects/managing-applications/checking-for-issues.md). #### 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 ![Commit Changes modal with a commit message and a longer description filled in, character counters under both fields, and the list of changed resources](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/versioning-commit-changes-description.png) ![Commit details in the branching overlay Details panel, showing the commit date, editor, version ID, commit message, and description](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.9/versioning-commit-details.png) 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: **1. Select a committed version** In the branching overlay, select a committed version. Its commit message appears as a button in the **Details** panel. **2. Open the commit details** Click the commit message button. The **Commit details** view opens and shows the version state, **Edited by**, **Version ID**, the full **Commit message**, and the **Description**. When a version has no description, a dash is shown instead. **3. Go back to the version details** Click the back arrow in the **Commit details** header to return to the **Details** panel and its list of changed resources. 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). > [!WARNING] > > A branch name is mandatory. It can be up to 40 characters long and can use letters, digits, and the characters `[ ] ( ) . - _ /`. ### 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. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/2025-01-28%2015.42.30.gif) * 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. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/release34/merge_changes.png) 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. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/2025-01-28%2015.54.48.gif) > [!TIP] > > Unless specified otherwise, changes from the source branch will be prioritized. > [!NOTE] > > Not all changes are considered conflicts, changes in node positions are not treated as conflicts. Primary causes lie in identifying differences within business rules, expressions, and other scripts. For how the merge decides which layout to keep, see [Node layout after merging](#node-layout-after-merging). #### 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. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Pre-merge.png) The merge modal also takes an optional **Description** of up to 2000 characters next to the merge message. See [Commit descriptions and details](#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. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Merge%20Modal%20%281%29.png) #### 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. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Screenshot%202024-11-20%20at%2016.23.03.png) ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Merge%20Modal%20%282%29.png) #### 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. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.5/Confirm%20Merging%20without%20checking%20all.png) #### 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](#resource-history). > [!WARNING] > > As a best practice, avoid this pattern: add at least one component to a **User Task** node before branching, so both branches modify the same container instead of creating separate root containers. In releases before 5.9.2, merging two branches that each added a root container to the same empty User Task node can leave the merged screen unable to render, and starting the process returns an error. #### 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. > [!TIP] > > After merging a branch where the same process changed on both sides, review the diagram and rearrange any overlapping nodes, by hand or with **Arrange** on the process canvas, which previews a tidied layout before you apply it. If new nodes ended up outside the swimlane, resize the swimlane in a single drag that makes it large enough to contain every node at once; a resize that still leaves nodes outside its bounds is rejected. ### 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. ![](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/4.6/Screenshot%202025-01-28%20at%2011.54.39.png) *** ## 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. > [!NOTE] > > You can create multiple versions of a project before creating a build. You can create a build for any committed project version. Once created, a build cannot be edited—you'll need to create a new project version and generate a new build to incorporate changes. ### Creating a build To create a build from a committed project version: **1. Navigate to Version Details** Access the version details panel for the committed version you want to build. You can only create builds from committed versions, not from draft (WIP) versions. **2. Open Create Build Dialog** Click the **Create Build...** button in the version details panel. This opens the build creation modal. ![Create Build](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/create_build.png) Create Build **3. Configure Build Settings** In the **Create build** modal, configure the following settings: * **Name**: The build name (defaults to the project name). This helps identify the build in the builds list. * **Build Tag Version**: Set the semantic version for this build: * **Major**: Major version number (e.g., `1`) * **Minor**: Minor version number (e.g., `0`) * **Patch**: Patch version number (e.g., `0`) The build tag follows semantic versioning format (e.g., `1.0.0`) and helps track different builds of the same project version. **4. Save the Build** Click **Save** to create the build. The build is now available in the Builds section and can be deployed to runtime environments. ![Create Build Modal](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/create_build_modal.png) ### Managing builds The **Builds** section provides a centralized interface for viewing and managing all builds for your project. ![Builds Interface](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/builds_interface.png) #### 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. **1. Select Version to Export** Navigate to the version details panel and select the version you want to export. **2. Initiate Export** Click the **Export Version** button in the version details panel. **3. Choose Binary Files Option** When exporting, a modal appears asking whether to include binary files: * **Include**: Includes binary files (e.g., images, documents) in the export. This may increase the export size and import time. * **Don't include**: Exports only the project structure and configurations without binary files. > [!WARNING] > > Including binary files may significantly increase the export file size and the time required to import the version in another environment. **4. Complete Export** Click **Continue** to proceed with the export. The exported file can be imported into other environments or workspaces. ![Export Version Modal](https://s3.eu-west-1.amazonaws.com/docx.flowx.ai/5.x/export_version.png) > [!NOTE] > > For detailed information about importing exported versions and builds, see the [Export/Import documentation](https://docs.flowx.ai/6.x/docs/flowx-designer/managing-a-project-flow/export-import-a-process-definition.md). ### 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