Learn how to transfer projects between environments using the export and import functionality in FlowX.AI Designer.
Moving projects between environments is a common requirement in enterprise software development. FlowX.AI provides export and import functionality to help you promote your projects from development to testing and production environments.
In recent versions of FlowX.AI, the export/import functionality has moved from the process definition level to the project level, allowing for more comprehensive and consistent transfers between environments.
Export and import are driven from the Designer UI. There is no public REST API to import a process definition or project programmatically â drive the workflow through the Designer.
Modern versions of FlowX.AI use project-level export and import operations rather than process-level ones. This approach ensures that the resources and configurations belonging to the project are transferred together, maintaining the integrity of your application.
Whether the libraries a project depends on travel with the export depends on what you export:
Project version export: records library dependencies only as references to specific library builds. The libraries themselves are not included, so the target environment must already contain those library builds â otherwise the import succeeds but the dependencies land as broken references.
Build export: also packages the builds of the libraries the project depends on, including transitive dependencies. Importing the build imports those library builds as well; library builds that already exist in the target environment are skipped.
This documentation covers the updated project export/import approach. If youâre using an older version of FlowX.AI that still handles exports at the process definition level, some details may differ.
You can export projects from the version details panel. This allows you to export specific committed versions with granular control over whatâs included in the export.
1
Navigate to Version Details
Open FlowX.AI Designer and go to the Projects section
Select the project you want to export
Navigate to the version details panel for the specific committed version you want to export
2
Initiate Export
In the version details panel, locate the Export Version button
Click Export Version to start the export process
Export Version Modal
3
Configure Binary Files Option
When exporting, a modal appears asking whether to include binary files:
Include: Includes binary files (for example, images, documents, media assets) in the export. This may increase the export file size and the time required to import the version in another environment.
Donât include: Exports only the project structure and configurations without binary files. This results in a smaller export file and faster import times.
Including binary files may significantly increase the export file size and the time required to import the version in another environment. Only include binary files if they are necessary for the target environment.
Include Binary Files modal
4
Complete the Export
Select your preferred binary files option
Click Continue to proceed with the export
The system will generate a downloadable file containing your project version
Save this file to your local system
Use a clear naming convention for your export files to help identify their contents later, such as [project-name]_[version]_[environment]_[date].zip.
For more information about versioning and managing project versions, see the Versioning documentation.
You can also export builds directly from the Builds section. This is useful when you want to transfer a specific build (rather than a version) between environments.
1
Navigate to Builds Section
Open FlowX.AI Designer and go to the Projects section
Select your project and navigate to Runtime and then to the Builds section
2
Select Build to Export
Locate the build you want to export in the builds list
Click the Export icon (box with upward arrow) for the desired build
3
Complete Export
The build export follows the same process as version export, including the binary files option. The exported build can be imported into other environments or workspaces.
Builds are immutable snapshots of committed project versions. When exporting a build, youâre exporting a deployable package that can be directly used in runtime environments. For more information about builds, see the Builds documentation.
Open FlowX.AI Designer in the target environment and go to the Projects section.
2
Open the Import menu
Click the three-dots (kebab) menu at the top right of the Projects list and choose one of:
Import Version â restores a project version (and its full version history) into the target environment. Use this when promoting work between environments.
Import Build â imports a build (an immutable snapshot of a committed version) into the Builds section. Use this when promoting a deployable package.
The menu only shows the items you have permission for.
You can also start an Import Version from inside an open project: open the All Branches view in the Version Details panel and click the upload icon in the panel header. This is functionally equivalent to Import Version from the Projects list.
3
Select the .zip file
The Designer opens your operating systemâs file chooser. Select the .zip you exported earlier and confirm.
4
Wait for the import to complete
The import runs asynchronously. A toast notification confirms success or reports an error. There is no in-app preview, no confirmation dialog, and no manual conflict-resolution step between picking the file and the import completing â see Import scenarios below for what happens when the target environment already has the project.
If the target environment has versions on the same lineage as the import file, those versions are silently stashed during the import. There is no preview or confirmation step before this happens. See Existing project with additional versions for the consequences and the recommended workflow.
When importing a project, you may encounter different scenarios depending on whether the project already exists in the target environment and what versions are present.
If the project does not exist in the target environment, it will be created with all its resources, and youâll see all versions from the export file.
If the project exists but doesnât have versions beyond those in the import file, the system will update the existing project with any changes from the import file.
Importing restores the version history and parentâchild relationships exactly as they exist in the import file. There is no merge functionality on import.
Versions become stashed, not merged
If the target environment has versions on the same lineage that are not in the import file, those versions become stashed: they remain in the database but are no longer accessible in the Designer. There is no UI to retrieve stashed versions â recovery requires direct database intervention by FlowX support and is not always feasible.
Importing on top of diverged work is destructive. If two environments committed different versions on the same branch, importing one over the other stashes the target version. The previous content cannot be restored from the Designer. Always export the target project before importing on top of it, and contact FlowX support if recovery is needed.
Recommended workflow: Use a separate branch per environment. On import, new branches are added alongside existing ones instead of overwriting versions on a shared lineage.
You can import the same project into multiple workspaces on the same environment. This removes the previous limitation that restricted a project (identified by its UUID) to exist in only one workspace per environment.
Cross-Workspace Import
Import a project build (and optionally a version) into a different workspace on the same environment. The imported project maintains its own independent lifecycle with separate active policies and access controls.
Key behaviors for cross-workspace import:
Aspect
Behavior
Lifecycle
The imported project has its own independent lifecycle in the new workspace
Active Policy
The imported build is automatically set as the active policy, regardless of what was active in the original workspace
Access Controls
Separate access controls and policies are defined for each workspace
No Impact on Original
The import does not affect the original projectâs settings, policies, or process instances
User Access
Workspace users must be granted appropriate project rights (for example, project viewer) to interact with the imported project
Process Instances
Process instances are workspace-specific; the imported project starts with no instances until processes run in the new workspace
Database
Projects across workspaces on the same environment share the same database
Use case: Use this feature to represent different operational environments (UAT, Staging, Pre-production) as separate workspaces on a single FlowX deployment, reducing infrastructure and DevOps costs.
Workspaces documentation
Learn more about cross-workspace project management
Plan your promotion path - Establish a clear workflow for moving from development to testing to production
Use consistent naming - Name your projects, versions, and export files consistently across environments
Pre-stage library dependencies for version imports - A project version export records its library dependencies only as references to specific library builds; unlike a build export, it does not bundle the libraries themselves. Make sure those library builds already exist in the target environment before importing a version, or the import succeeds but the dependencies land as broken references.
Test after import - Always validate your project in the new environment after import
Version control - Consider using external version control systems in addition to FlowX.AIâs built-in versioning
Incremental imports - For large projects, consider importing incrementally rather than all at once
Export the target project before importing - Importing on top of diverged work stashes the target version, and stashed versions cannot be recovered from the Designer. Exporting the target first gives you a recovery point.
Issue: Import fails due to version incompatibility between environments.Solution: Ensure all environments are running compatible versions of FlowX.AI. If necessary, upgrade the older environment before attempting import.
Missing Dependencies
Issue: Imported project references libraries or resources not present in the target environment.Solution: Import the required library builds into the target environment before importing the project version (a version archive references library builds but does not contain them; a build archive does include them), or update the project to use libraries already available in the target. Dependencies that canât be resolved on import are flagged as broken references, and resources that use them become broken links.
Conflict Resolution
Issue: Conflicts between imported versions and existing versions.Solution: Carefully review the differences and decide whether to overwrite or preserve existing versions. Consider merging changes manually for complex conflicts.
Environment-Specific Configurations
Issue: Hard-coded environment-specific values in processes or configurations.Solution: Use environment variables and configuration parameters instead of hard-coded values to ease transitions between environments.
