13.3 · Import / Export

JSON Project Backup

JSON export produces a full, round-trippable backup of a single project. It preserves every field, formula, custom column, note, and relationship. Use JSON for backups, project migration between installations, and diff-friendly version control.

Exporting

To memory — ExportProjectToJsonAsync(projectId, options) returns a byte[].
To disk — ExportProjectToJsonFileAsync(projectId, path, options) streams to file (safer for very large projects).

ProjectExportOptions

Option	Purpose
DirectCosts	Include item schedule.
Overheads	Include overheads.
Resources	Include project resources.
CarbonEmissions	Include emissions.
ProjectSettings	Include markup, currency, tax.
CodeSets	Include code sets and allocations.
GlobalDefines	Include parametrics.
CustomColumns	Include custom column definitions and values.
Notes	Include notes and images.
Templates	Include project-scope templates.
Documents	Include attachments.
ProjectStructure	Sections, folders, tags.
Client	Include linked client record.
CompressOutput	gzip the JSON.
StoreImagesAsSeparateFiles	Extract note images to sibling files instead of embedding base64.

Importing

ImportProjectFromJsonAsync(bytes, options) recreates the project.

ProjectImportOptions

Option	Purpose
NewProjectName / Number	Rename on import.
ConflictResolution	Skip / Overwrite / Rename / Fail for name conflicts.
ImportAsTemplate	Mark the imported project as a template.
RegenerateIds	Generate new GUIDs — prevents any collision.
TargetFolderId	Drop the imported project into a specific folder.

Round-Trip Fidelity

A JSON export → import should produce a byte-identical project except for:

New IDs if RegenerateIds = true.
New timestamps (CreatedAt unchanged; ModifiedAt updated to import time).
User attribution updated to the importing user if the original user doesn't exist in the target install.

Version Control Tips

Pretty-print option makes JSON diff-able in Git.
Export with StoreImagesAsSeparateFiles so images don't bloat the JSON blob.
Don't check in CompressOutput files — gzip doesn't diff.

Typical Uses

Scenario	Approach
Daily backup	JSON gz to a network drive.
Sharing with partner using TX1	JSON file (or `.tx1`).
Manual review of changes	Pretty-printed JSON with git diff.
Migrating a project to a new install	JSON with `RegenerateIds = true`.

Image Handling

Notes often include images. When StoreImagesAsSeparateFiles = true, TX1 writes:

project.json — the main data.
images/ — a folder of binary image files referenced by ID.

Import pulls the images back in automatically.

Limitations

JSON is a single-project artefact. For organisation-wide backup, use the underlying SQLite file.
Master library references are preserved by name, not ID — if the import target doesn't have the same master resources, links become unlinked.