# Import / export

> Bulk Excel import and export for every entity, plus per-entity CSV / JSON export.

Source: https://productos.ca/documentation/pages/settings/import-export (last reviewed 2026-10-08)

The Import / Export section is where you bulk-move data into or out of ProductOS. One Excel workbook is both the import template and the export format, so an export can be edited and re-imported.

## The workbook

- **One tab per entity.** Feedback, Themes, Features, External Links, Initiatives, Releases, Outcomes, Outcome Metrics, Accounts, Personas, Products, Modules, Teams, Team Members, Vision & Mission, Objectives, Key Results, SWOT, Positioning, Pricing Tiers, Competitors, Market Trends, Market Signals, Channels, Messaging Frameworks, Launch Plans, Deal Blockers, Win-Loss Records, Battle Cards, DS Components, DS Patterns, DS Tokens. The first tab, Instructions, lists every allowed value.
- **Links live in columns, not tabs.** Golden Thread links are semicolon-separated names in columns such as `Linked Themes`, `Linked Features`, `Assigned Members` and `Depends On`. They resolve by exact title or name on import, so a misspelled title silently drops the link.
- **Releases** list shipped features by title in `Linked Features`. `Items` holds the other release lines that are not features.
- **Outcomes** list the features linked to them directly by title in `Linked Features`. Features an outcome only reaches through its initiative are not repeated there.
- **Outcome Metrics** (measured outcomes, a preview) hold an outcome's guardrails, supporting metrics and measured primary. Each names its outcome by the `ID` on the Outcomes tab of the same file, because outcomes have no unique name. A metric measured from Amplitude comes in with its event and windows; its numbers are fetched again once Amplitude is connected in the workspace you import into.
- **Objectives** list the initiatives that serve them by title in `Linked Initiatives`, which fills the objective's `initiative_ids` on import. A title that matches no initiative drops that one link.
- **Team Members** never carries who is a signed-in user versus a roster-only placeholder; that link (a team member's account) isn't a portable file value. **Replace all data** preserves it anyway: before wiping, ProductOS remembers each linked member's email, and reconnects the freshly-imported row with the same email to the same account. A row whose email matches more than one imported row is left unlinked rather than guessing.
- **External Links** is the exception: one row per link attached to a feature (GitHub PR, issue or branch, Claude Code session, Notion page, Figma file, pinned repo path). `Feature` is the feature's title, `Kind` is one of the seven kinds, `URL` is required, and `Metadata` is the link's JSON as exported. Leave `Metadata` blank when adding links by hand.
- **Is Draft** appears on every tab except Teams, Vision & Mission and External Links. Exports write `true` for drafts so they come back as drafts. Blank means published.
- **IDs are file-local.** The `ID` column (`FEAT-000001`, `LINK-000001`) numbers rows within the file. It is ignored on import, and the app assigns its own numbers, so an export does not preserve the `FEAT-42` style references you see in the app.
- **The template is workspace-aware.** Enum columns carry in-cell dropdowns, and the Features tab's `Type` dropdown lists *your* [Work-Item Types](https://productos.ca/documentation/pages/settings/work-item-types), including custom ones. Re-download the template after adding types.

## Import

- **Owner only.** The Import panel (both modes below) appears only for the workspace owner. Admins and members can export and download the template, but not import.
- **Drag and drop** a `.xlsx` or `.xls` file. The preview shows row counts and validation problems per tab before anything is written. Rows that still fail on the server (an unknown feature title on External Links, for example) are skipped rather than failing the import.
- **Add to existing data** inserts everything in the file alongside what is already there. Nothing is de-duplicated, so importing the same file twice creates duplicates.
- **Replace all data** deletes the workspace's entity data first, then imports. Confirmed in a dialog, and irreversible. Export first.
- **All or nothing.** If any tab fails to insert, the import is rolled back and the error names the tab.
- **Sprints import by reference.** The Features tab's `Sprint` column accepts a label or number (`Sprint 12` or `12`). Sprints are computed from your [Sprint Cadence](https://productos.ca/documentation/pages/settings/overview) rather than stored, so the importer writes that sprint window's midpoint as the Target Date when Target Date is blank. Exports fill the column with the computed label, so round-trips preserve sprint placement.
- **Align the cadence anchor before importing sprint references.** Sprint numbers are relative to your workspace's anchor date. If the file was numbered for another system, the preview warns you with both numbers before you commit. Fix the Sprint Cadence anchor, then re-upload the same file.
- **Per-integration import** (Linear backfill, Intercom history and so on) lives under [Integrations](https://productos.ca/documentation/pages/settings/integrations), not here.

There is no JSON import surface.

## Export

- **Export all data** downloads a timestamped workbook with every tab filled from your workspace. It uses the same columns as the template, so it re-imports cleanly.
- **The Trash is not exported.** Restore an item first if it belongs in the file.
- **Not yet included:** custom field values, comments, roadmap curation, battle card scorecard ratings, and Claude Code session transcripts. The audit log and integration settings are never part of the workbook.
- **From Claude.** A Claude client connected to ProductOS can ask for the same workbook with the `export_workspace` [MCP tool](https://productos.ca/documentation/api/v1/mcp). It returns a download link that works for 15 minutes without signing in, so treat it like a password. Disconnecting that Claude connection, or leaving the workspace, stops the link early. The file is built when the link is opened, and its timestamp is in UTC.
- **Per-entity export** is available on each entity's list page as CSV or JSON, served by `GET /api/v1/{entity}/export?format=csv|json`.

Exports are **not** scheduled by ProductOS. For regular backups, call the export endpoint from a cron in your own infrastructure.

## Common pitfalls

- Each tab's first data column (`Title`, `Name`, `Version`, `Feature`) is required. Rows without it are flagged in the preview.
- Enum values are lowercase (`new` works, `New` fails). The Instructions tab lists them all.
- The sample row on each tab is removed automatically. A real row is only dropped if every one of its cells matches the sample.
- Links resolve by name, so two features with the same title (or two members with the same name) collapse into one target on import. Give entities distinct titles before exporting if their links matter.
- Links resolve by exact title. Rename an entity in the file and every column that referenced the old title stops resolving.

## Related

- [Work-Item Types](https://productos.ca/documentation/pages/settings/work-item-types): the Features tab's `Type` column
- [Pagination](https://productos.ca/documentation/api/v1/pagination): how the per-entity export endpoint paginates