RefractTrack Export and Import - Revision history

Nerdofepic at 22:57, 11 September 2026

2026-09-11T22:57:52Z

← Older revision		Revision as of 22:57, 11 September 2026
Line 1:		Line 1:
	== Export and Import ==		== Export and Import ==

	A project's ~~entire set of tasks~~ can be ~~exported~~ as a ~~backup or spreadsheet,~~ and ~~re-imported~~ later — whether that's to restore from a backup, move ~~tasks into~~ a new ~~project~~, or ~~just work with~~ the ~~data in~~ a ~~tool like Excel~~.		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).

	~~Two formats~~ are ~~available:~~		=== 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 [[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.

	* '''JSON''' — the default, best for backing up and restoring a ~~project exactly as it was, since it keeps everything (including full comment and history threads)~~ in ~~its original shape.~~		=== Bringing a backup back in ===
	* '''CSV''' — a plain spreadsheet format, handy for opening in Excel, Google Sheets, or similar tools.

	~~Both formats always export the exact same information~~, in the ~~exact same order~~, so ~~switching~~ between ~~them never means losing anything~~.		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.

	=== ~~What's included~~ ===		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.

	~~Every task~~'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 ~~task is archived comes along too~~, so ~~an archived task is still archived after being brought back in~~.		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.

	=== ~~Bringing tasks back in~~ ===		=== A note on safety ===

	~~When you import tasks into~~ a ~~project~~, RefractTrack ~~gives them fresh task numbers in that project rather than reusing~~ the ~~old ones, so there~~'~~s never a numbering collision. Column names and tags on the imported tasks are matched up against whichever project you~~'~~re importing~~ '''~~into~~''' — so if a ~~column~~ or ~~tag doesn~~'t ~~already exist there, make sure to create it first (or rename things to match) before importing~~.		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 ===		=== Related pages ===
Line 22:		Line 33:
	* [[RefractTrack_Tasks\|Tasks]]		* [[RefractTrack_Tasks\|Tasks]]
	* [[RefractTrack_Projects\|Projects]]		* [[RefractTrack_Projects\|Projects]]
			* [[RefractTrack_Attachments\|Attachments]]
			* [[RefractTrack_Bulk_Task_Creation_and_Saved_Lists\|Bulk Task Creation]]
	* [[RefractTrack_Permissions_and_Roles\|Permissions and Roles]]		* [[RefractTrack_Permissions_and_Roles\|Permissions and Roles]]
			* [[RefractTrack_Upgrading\|Upgrading]]

	[[Category:RefractTrack]]		[[Category:RefractTrack]]

Nerdofepic at 03:35, 3 September 2026

2026-09-03T03:35:29Z

← Older revision		Revision as of 03:35, 3 September 2026
Line 23:		Line 23:
	* [[RefractTrack_Projects\|Projects]]		* [[RefractTrack_Projects\|Projects]]
	* [[RefractTrack_Permissions_and_Roles\|Permissions and Roles]]		* [[RefractTrack_Permissions_and_Roles\|Permissions and Roles]]

			[[Category:RefractTrack]]

Nerdofepic at 00:14, 29 August 2026

2026-08-29T00:14:00Z

← Older revision		Revision as of 00:14, 29 August 2026
Line 1:		Line 1:
	== Export and Import ==		== 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 entire set of tasks can be exported as a backup or spreadsheet, and re-imported later — whether that's to restore from a backup, move tasks into a new project, or just work with the data in a tool like Excel.

	~~=== Exported fields ===~~		Two formats are available:

	~~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:~~		* '''JSON''' — the default, best for backing up and restoring a project exactly as it was, since it keeps everything (including full comment and history threads) in its original shape.
			* '''CSV''' — a plain spreadsheet format, handy for opening in Excel, Google Sheets, or similar tools.

	* Task code (<code><nowiki>old_code</nowiki></code>)		Both formats always export the exact same information, in the exact same order, so switching between them never means losing anything.
	* Title
	* Type
	* 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.~~		=== What's included ===

	~~=== Import behavior ===~~		Every task'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 task is archived comes along too, so an archived task is still archived after being brought back in.

	* '''Code rewriting''': imported tasks ~~are assigned fresh task numbers~~ in ~~the target project rather than reusing the source instance's numbers, avoiding collisions.~~		=== Bringing tasks back in ===
	* '''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 ===~~		When you import tasks into a project, RefractTrack gives them fresh task numbers in that project rather than reusing the old ones, so there's never a numbering collision. Column names and tags on the imported tasks are matched up against whichever project you're importing '''into''' — so if a column or tag doesn't already exist there, make sure to create it first (or rename things to match) before importing.

	~~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~~.

	=== Related pages ===		=== Related pages ===
Line 42:		Line 23:
	* [[RefractTrack_Projects\|Projects]]		* [[RefractTrack_Projects\|Projects]]
	* [[RefractTrack_Permissions_and_Roles\|Permissions and Roles]]		* [[RefractTrack_Permissions_and_Roles\|Permissions and Roles]]
	* [[RefractTrack_Known_Limitations\|Known Limitations]]

Nerdofepic: Created page with "== Export and Import == A project's tickets can be exported and re-imported as either '''JSON''' (the default format) or '''CSV''', gated by `backups:export` and `backups:import` respectively. Both are project-scoped permissions — see Permissions and Roles. === Exported fields === Both formats export the same set of fields, in the same order, from a single shared definitio..."

2026-08-27T23:26:15Z

Created page with "== 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 Permissions and Roles. === Exported fields === Both formats export the same set of fields, in the same order, from a single shared definitio..."

New page

== 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]].

=== Exported fields ===

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:

* Task code (<code><nowiki>old_code</nowiki></code>)
* Title
* Type
* 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.

=== Import behavior ===

* '''Code rewriting''': imported tasks are assigned fresh task numbers in the target project rather than reusing the source instance's numbers, avoiding collisions.
* '''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 ===

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.

=== Related pages ===

* [[RefractTrack_Tasks|Tasks]]
* [[RefractTrack_Projects|Projects]]
* [[RefractTrack_Permissions_and_Roles|Permissions and Roles]]
* [[RefractTrack_Known_Limitations|Known Limitations]]