Import and export Work Items

Import and export Work Items

Open Organization settings → Import / export for project CSV exports and the staged CSV or native archive import flow. The destination Organization comes from the authenticated session, not from uploaded file contents. Project Admins can use project-scoped CSV import and native Project export; Organization administrators and owners can also use Organization-wide native import and export. Preserving retained Attribute values requires Organization administrator authority.

CSV

CSV is a current Work Item state format. It does not include comments, attachments, full Project configuration, Attribute definition history, audit events, or lifecycle history. Use a native .hamstik archive when that configuration and history must be retained.

Exports are UTF-8 with a byte-order mark, CRLF record endings, and RFC 4180 quoting. Text is protected against spreadsheet formula execution. Attribute columns use the canonical Attribute:<definition-key> header; for example, Attribute:customer. The machine key stays stable after a name or label change. A display label is never used as an identifier.

Attribute type	Cell encoding	Empty and clear behavior
Single-select	One option key, such as acme	Blank means no assignment; !clear explicitly clears.
Multi-select	JSON array of option keys, such as ["web","mobile"]	Blank means no assignment; [] explicitly clears.
Boolean	Exact lowercase true or false	Blank means no assignment; !clear clears, and false is a real value.

CSV quoting handles commas, double quotes, Unicode, newlines, and JSON quotes inside a cell. Attribute columns are additive: older templates without them remain valid. Import preview resolves keys and options against the destination Organization and explicitly selected Project. It reports unknown definitions, disabled or unenabled definitions, retired options, invalid values, duplicate columns, and type/cardinality errors. Headers never create definitions or options; this differs from the additive Label import behavior.

Confirmation re-reads the staged CSV and revalidates authorization, definitions, options, and Project enablement inside the import transaction. A normal import cannot create a new assignment to a disabled, retired, opted-out, or retired-option value. When exported rows contain such retained values, an Organization administrator can choose Preserve retained Attribute values in the preview. The preview identifies the affected columns and rows; each preserved value is recorded as an import restoration in Work Item activity. This choice cannot create schema and is unavailable to normal assignment APIs.

Native .hamstik archives

Native archives use format version 4. The importer supports legacy versions 1, 2, and 3, which contain no Attribute data, and rejects unsupported newer versions before import writes. Archives do not include credentials, secrets, or cross-Organization references.

An Organization archive includes its governed definitions and options, including unused and retired records, along with the included Projects’ enablement and Work Item assignments. A Project archive includes only the definitions/options needed to interpret that Project’s enablement and retained assignments; it does not export other Projects’ Work Items, enablement, or usage. A Project that opted out can still export a retained assignment so its meaning is not lost.

Native archives also carry elapsed-effort data: both minute-estimate fields on each Work Item and every worklog with its stable archive-local identity, work date, minutes, recorded author identity, and correction metadata. The estimate and worklog fields are additive and optional, so an export produced before time tracking remains valid and imports with unknown estimates and no worklogs. Re-importing a worklog with the same identity in the same trusted import source is idempotent when its source content is identical. Reusing that identity with changed minutes, date, comment, or attribution is reported as a conflict; the existing log is preserved. Destination ID remapping does not turn an identical retry into a conflict. A log whose author cannot be resolved to an authorized Organization member is imported with its recorded name but no attributed user, never as someone else’s. An importer cannot choose another source’s namespace or probe its identifiers.

Import creates fresh destination records and Work Item keys. Attribute and option machine keys stay unchanged. Before confirmation, the preview checks definition key collisions. A destination definition is reused only when its type, display name, lifecycle, option keys, labels, ordering, and lifecycle states all match. Label differences are treated as incompatible; Hamstik does not guess whether a relabeled vocabulary is equivalent, rename immutable keys, or mutate existing Organization governance. Resolve an incompatible collision before importing.

Native restoration is a separate administrator operation. It can restore inactive definitions/options and their historical assignments from a validated archive. Confirmation and the transaction recheck administrator authority, import-session state, and collisions; a failure rolls back the Attribute governance and assignment writes with the rest of the import. The actor and import session are included in Attribute audit/activity records.

CSV and native archives serve different purposes: CSV is a convenient, current-state Work Item interchange; native archives preserve compatible Hamstik configuration and relationships.