RefractTrack Export and Import: Difference between revisions

Latest revision as of 22:57, 11 September 2026

Export and Import

A project's tickets can be backed up as a single .zip file and brought back in later — whether that's to restore from a backup, move a project onto a new server, or hand a project's history off to someone else. This is the one export/import format RefractTrack offers; there's no separate spreadsheet-style option, since a real backup needs to carry more than a spreadsheet can hold anyway (see below).

What's included

A project's backup is genuinely everything about it, all in one file:

Every ticket's title, type, priority, column, review status, assignee, due date, description, groups, bug details (if any), and full comment/activity history — plus who created it and when. Whether a ticket is archived comes along too, so an archived ticket is still archived after being brought back in.
Every ticket's attachments — the actual files, not just a note that they existed.
The project's full set of Stages, Groups, and saved bulk-create lists — every one the project has, not just the ones a ticket in this particular backup happens to use. That means a project's saved lists are backed up and restored right along with everything else, even ones that haven't been used to create a ticket yet.

Bringing a backup back in

When you import a backup into a project, RefractTrack gives every ticket a fresh number in that project rather than reusing the old ones, so there's never a numbering collision — and any task-code references between tickets (like a description mentioning FE-12) are automatically rewritten to point at the new numbers.

Stages and groups are matched up by name against whichever project you're importing into. If a stage or group a ticket refers to doesn't already exist there, RefractTrack creates it for you automatically (using the color and description from the backup where available) rather than dropping the reference or leaving it blank — newly-created stages land at the front of the board with a note that they may need reordering. Saved lists are matched by name too, but handled a little more carefully: if a same-named list already exists in the project you're importing into, the existing one is left alone rather than overwritten, since it might be a different, already-in-use list that just happens to share a name.

A backup can only be restored into a project that already has at least one ticket in it, or brought in as a brand-new project — an entirely empty project (nothing but a name and some saved lists) can't yet be exported at all, so there's nothing to import in that case either.

Backups for very large projects

A project with a lot of attachments can add up to a genuinely large file — hundreds of megabytes to a few gigabytes isn't unusual for a project with years of reference art and screenshots attached. Restoring a backup that big through a browser upload can run into your web server's own upload-size limit before RefractTrack ever gets a chance to look at it.

For exactly this situation, there's a command-line import tool your server admin can run directly on the server: scripts/import_backup.php. It reads the backup straight off local disk (get it there however you'd normally move a file onto your server — scp, sftp, and so on), so there's no upload-size ceiling to run into at all. It's the same import logic as the regular in-browser version underneath, just fed a file path instead of a browser upload, so a backup restored this way ends up identical either way.

A note on safety

Because a backup is just a zip file, RefractTrack checks it carefully before trusting anything inside it — verifying the total size it would expand to before extracting anything (so an unexpectedly huge or malicious file is rejected up front, not partway through), and making sure nothing inside it can write outside of where it's supposed to go. None of this needs any thought on your part; it's just there so a shared or downloaded backup file can't do anything unexpected.

Related pages

@@ Line 1: / Line 1: @@
 == Export and Import ==
-A project's tickets can be exported and re-imported as either '''JSON''' (the default format) or '''CSV''', gated by <code><nowiki>backups:export</nowiki></code> and <code><nowiki>backups:import</nowiki></code> respectively. Both are project-scoped permissions — see [[RefractTrack_Permissions_and_Roles|Permissions and Roles]].
+A project's tickets can be backed up as a single '''.zip file''' and brought back in later — whether that's to restore from a backup, move a project onto a new server, or hand a project's history off to someone else. This is the one export/import format RefractTrack offers; there's no separate spreadsheet-style option, since a real backup needs to carry more than a spreadsheet can hold anyway (see below).
-=== Exported fields ===
+=== What's included ===
-Both formats export the same set of fields, in the same order, from a single shared definition (<code><nowiki>export_field_definitions()</nowiki></code>), so the two formats can never drift out of sync with each other:
+A project's backup is genuinely everything about it, all in one file:
-* Task code (<code><nowiki>old_code</nowiki></code>)
+* Every ticket's title, type, priority, column, review status, assignee, due date, description, groups, bug details (if any), and full comment/activity history — plus who created it and when. Whether a ticket is archived comes along too, so an archived ticket is still archived after being brought back in.
-* Title
+* Every ticket's '''attachments''' — the actual files, not just a note that they existed.
-* Type
+* The project's full set of [[RefractTrack_Stages|Stages]], [[RefractTrack_Groups|Groups]], and [[RefractTrack_Bulk_Task_Creation_and_Saved_Lists|saved bulk-create lists]] — every one the project has, not just the ones a ticket in this particular backup happens to use. That means a project's saved lists are backed up and restored right along with everything else, even ones that haven't been used to create a ticket yet.
-* Priority
-* Stage (by name)
-* Review status
-* Assignee (by username)
-* Due date
-* Description
-* Expected behavior / Actual behavior / Steps to reproduce (bug fields)
-* Groups (by name)
-* Created-by (by username)
-* Created-at timestamp
-* Archived-at timestamp
-* Activity — the full comment and system activity log for the task (see [[RefractTrack_Comments_and_Activity_Log|Comments and Activity Log]])
-CSV serializes the activity log into a single JSON-encoded cell; JSON keeps it as a native nested array.
+=== Bringing a backup back in ===
-=== Import behavior ===
+When you import a backup into a project, RefractTrack gives every ticket a fresh number in that project rather than reusing the old ones, so there's never a numbering collision — and any task-code references between tickets (like a description mentioning ''FE-12'') are automatically rewritten to point at the new numbers.
-* '''Code rewriting''': imported tasks are assigned fresh task numbers in the target project rather than reusing the source instance's numbers, avoiding collisions.
+Stages and groups are matched up by name against whichever project you're importing '''into'''. If a stage or group a ticket refers to doesn't already exist there, RefractTrack creates it for you automatically (using the color and description from the backup where available) rather than dropping the reference or leaving it blank — newly-created stages land at the front of the board with a note that they may need reordering. Saved lists are matched by name too, but handled a little more carefully: if a same-named list already exists in the project you're importing into, the existing one is left alone rather than overwritten, since it might be a different, already-in-use list that just happens to share a name.
-* '''Archived status is preserved''' through the round-trip — an archived task stays archived after import.
-* '''Stage and group matching is scoped to the import's target project''' — an imported task's stage/group names are matched against the ''destination'' project's own stages and groups (see [[RefractTrack_Stages|Stages]] and [[RefractTrack_Groups|Groups]]), not the source project's.
-* '''Activity log included''' — comments and system history come along with each task.
-* A dropped or renamed field only needs to be added or removed from the shared field-definition map once; both export formats and the CSV header-row validation on import derive from that single map automatically.
-=== CSV-specific handling ===
+A backup can only be restored into a project that already has at least one ticket in it, or brought in as a brand-new project — an entirely empty project (nothing but a name and some saved lists) can't yet be exported at all, so there's nothing to import in that case either.
-CSV export/import includes a formula-injection guard (<code><nowiki>csv_unsafe_cell()</nowiki></code>) that neutralizes cell values starting with characters like <code><nowiki>=</nowiki></code>, <code><nowiki>+</nowiki></code>, <code><nowiki>-</nowiki></code>, or <code><nowiki>@</nowiki></code> that spreadsheet software could otherwise interpret as a formula. This guard currently runs unconditionally on both the CSV and JSON import paths, even though JSON export never applies it — a harmless no-op in practice except for the rare case of real content that happens to start with one of those characters, which is a known, low-priority inconsistency rather than a security gap.
+=== Backups for very large projects ===
+A project with a lot of attachments can add up to a genuinely large file — hundreds of megabytes to a few gigabytes isn't unusual for a project with years of reference art and screenshots attached. Restoring a backup that big through a browser upload can run into your web server's own upload-size limit before RefractTrack ever gets a chance to look at it.
+For exactly this situation, there's a command-line import tool your server admin can run directly on the server: <code>scripts/import_backup.php</code>. It reads the backup straight off local disk (get it there however you'd normally move a file onto your server — scp, sftp, and so on), so there's no upload-size ceiling to run into at all. It's the same import logic as the regular in-browser version underneath, just fed a file path instead of a browser upload, so a backup restored this way ends up identical either way.
+=== A note on safety ===
+Because a backup is just a zip file, RefractTrack checks it carefully before trusting anything inside it — verifying the total size it would expand to '''before''' extracting anything (so an unexpectedly huge or malicious file is rejected up front, not partway through), and making sure nothing inside it can write outside of where it's supposed to go. None of this needs any thought on your part; it's just there so a shared or downloaded backup file can't do anything unexpected.
 === Related pages ===
@@ Line 41: / Line 33: @@
 * [[RefractTrack_Tasks|Tasks]]
 * [[RefractTrack_Projects|Projects]]
+* [[RefractTrack_Attachments|Attachments]]
+* [[RefractTrack_Bulk_Task_Creation_and_Saved_Lists|Bulk Task Creation]]
 * [[RefractTrack_Permissions_and_Roles|Permissions and Roles]]
-* [[RefractTrack_Known_Limitations|Known Limitations]]
+* [[RefractTrack_Upgrading|Upgrading]]
+[[Category:RefractTrack]]

Nerdofepic (talk | contribs)