Migrate to Foundation from Structure, BigPicture, or CSV

Foundation ships with one-click migration from every major Jira portfolio app. Direct API import from Structure Cloud or BigPicture Cloud. CSV Import Wizard with hierarchy auto-detection. Keep your existing licenses running in parallel until cutover.

Foundation Import wizard showing Structure, BigPicture, CSV, and Data Center options

How do I migrate from Structure Cloud?

Foundation reads Structure Cloud through its public REST API using an API token you generate inside Tempo's Structure UI. Paste the token into Foundation's Import wizard, pick the structures you want to bring over, and Foundation rebuilds each one as a Lens in Forge SQL. Your Structure data stays untouched; this is a read-only copy.

What carries over cleanly: the hierarchy tree, Jira issue links (matched by issue key), Structure folders (rebuilt as Foundation Flex Items), JQL-based generators (translated to Foundation's JQL Insert Sync Agents), parent/sub-task extenders (mapped to Child Extend), standard Jira columns, saved views, and ACL grants where the grantees are Atlassian users or groups.

What doesn't carry over, called out explicitly in the import summary so you can plan around it: Structure's Expr formula columns (Foundation's formula engine ships Q1 2027), custom attribute transformations, and transformation chains more than one level deep. See the full Structure import doc for field-by-field behavior.

How do I migrate from BigPicture Cloud?

The BigPicture Cloud flow mirrors the Structure flow: generate an API token in BigPicture, paste it into Foundation's Import wizard, pick the Boxes to migrate, and Foundation creates one Lens per Box. Scope items (your Jira issues) stay linked by key. Custom BigPicture-only items become Foundation Flex Items, which you can later promote to real Jira issues with the Copy to Jira action.

What carries over: Box scope and tasks, custom parent-child hierarchy, Gantt-friendly fields (start date, due date, dependencies when present), and standard agile Box templates (which map to Foundation's Agile Hierarchy preset).

What doesn't — honest call-out: BigPicture's Risks and Resources modules have no Foundation equivalent in the MVP. BigPicture-specific SAFe constructs (Program Increments, Agile Release Trains, ROAM) are skipped. Baselines beyond the current snapshot don't transfer. If resource allocation or PI Planning is central to your workflow, run both apps in parallel and plan for a longer cutover. See Foundation vs. BigPicture for the full trade-off map.

How do I import from CSV or Excel?

For teams whose plan lives in a spreadsheet — or who want to stage a migration outside the source app's API — Foundation ships a six-step CSV Import Wizard. The file is parsed in your browser; nothing leaves your session until you confirm the import.

The six steps: (1) Upload a CSV or Excel file; (2) Map columns — Foundation auto-detects Summary, Issue Key, Status, and Assignee, and you override anything wrong; (3) Detect hierarchy — the wizard proposes one of three modes (parent-key column, indentation, or flat) and you accept or override; (4) Preview the first 20 rows to verify the tree; (5) Map issue types — decide which rows become real Jira issues versus Foundation Flex Items; (6) Commit — Foundation writes the hierarchy in chunks with a live progress bar.

Rows with a valid Jira issue key link to the existing issue. Foundation never re-creates an issue that already exists. Rows without a key become Flex Items so your tree structure survives regardless of Jira coverage. See the CSV import doc for the clean-file checklist.

How do I handle Jira Data Center exports?

Teams still on Jira Data Center (or Server) need an extra hop, since Foundation is a Forge app and runs on Jira Cloud only. The Foundation Data Center Extractor is a Java plugin you install on your DC instance. It reads your DC issue hierarchy and exports a structured file (CSV with a parent-key column plus a JSON sidecar for Structure/BigPicture-style generators) that the Cloud-side Foundation Import wizard consumes.

The intended workflow: migrate your Jira site from DC to Cloud using Atlassian's own Cloud Migration Assistant, then run the Extractor against your DC instance (while still available) to pull your portfolio structure, and finally feed the export into Foundation Cloud. This keeps issue keys stable across DC and Cloud so the hierarchy re-links automatically on the Cloud side.

The Extractor is a one-time tool — you don't keep it installed on DC. It does not modify your DC data; it only reads. Install instructions ship with the plugin JAR.

Can I run Foundation and my current PPM app in parallel?

Yes — this is the safe migration pattern we explicitly support. Structure, BigPicture, and Foundation all read from the same Jira source of truth (your issues), so the same issue can appear in a Structure structure, a BigPicture Box, and a Foundation Lens at the same time without conflict. Changes made in any one tool — edit an assignee, transition a status, move a date — show up in all three because the write goes to Jira, not to the tool's own store.

Practical rollout: install Foundation, import one or two representative structures or Boxes, share the Lenses with a small pilot group, and run both tools for a sprint or two. When the pilot group confirms Foundation covers their workflow, expand the rollout and only then consider cancelling the old license. There is no forced cutover, no data deletion, and no irreversible step. If Foundation doesn't work for you, uninstall it and your original app is untouched.

What happens to my existing licenses?

Nothing, until you choose. Structure, BigPicture, and Jira Premium (for Jira Plans) are all billed by Atlassian or the vendor independently of Foundation. Installing Foundation doesn't touch those subscriptions, doesn't notify the vendor, and doesn't trigger a renewal change. You keep paying for your current app exactly as before.

Recommended schedule: run in parallel for one to three sprints; migrate additional structures or Boxes in waves; cancel the old app at your next renewal date rather than mid-cycle, so you don't lose pre-paid time. Most teams switching from Structure use the parallel period to validate Expr-dependent reports against Foundation's native columns — that's the one gap where running both tools pays off.

What gets migrated and what doesn't?

Below is the honest field-by-field picture across the three main import paths. If a capability is missing from Foundation's MVP, we say so here and in the import summary — no surprises.

Feature	From Structure	From BigPicture	From CSV
Jira issue links (by key)	Yes	Yes	Yes
Hierarchy tree	Yes	Yes	Yes (parent-key or indentation)
Non-Jira nodes	Folders to Flex Items	Custom items to Flex Items	Rows w/o key to Flex Items
Standard Jira columns	Yes	Yes	Yes (mapped in wizard)
Custom fields	Yes (if in Jira site)	Yes (if in Jira site)	Yes (mapped in wizard)
Generators / automation	JQL + extenders to Sync Agents	Partial (scope filters)	N/A
Formula columns	No (Expr not supported)	No	No
Saved views / column sets	Yes	Yes	One per import
Permissions / ACL	Yes (Atlassian users/groups)	Partial	Inherits Lens default
Gantt dependencies	Yes	Yes	Via dependency column
Baselines (historical)	No	Current snapshot only	No
SAFe PI Planning constructs	N/A	No (patterns supported manually)	N/A
Resource / capacity data	N/A	No	N/A

Four import paths, one destination. Structure Cloud, BigPicture Cloud, CSV/Excel, and Bulk Add by Issue Key all land in the same Foundation Lens data model — so you can mix and match (for example, import a Structure tree, then paste in a list of issue keys from a different project) without a second tool.

Frequently asked questions

How long does migration take for 10,000 issues?

Plan on 20 to 45 minutes of wall-clock time for a 10,000-issue import, though most of that is the async job running in the background — you can close the wizard and come back. Structure Cloud and BigPicture Cloud imports are bound by the source app's API rate limits (their servers, not Jira's), which is why the exact number varies. CSV imports of the same size typically finish in 8 to 15 minutes because Foundation parses the file in-browser and writes to Forge SQL in chunks without touching an external API. Bulk Add by Issue Key is the fastest path for small ad-hoc imports (up to ~500 keys).

Do I need Jira admin access to migrate?

Not for the Structure Cloud, BigPicture Cloud, or CSV imports — those only require a Foundation install and a read-capable token from the source app (for Structure and BigPicture) or the ability to read your own Jira issues (for CSV). You do need Jira admin access to install Foundation itself from the Marketplace, and Jira admin is required for the Data Center Extractor plugin since it reads directly from your DC instance. If your admin has installed Foundation, a regular user with browse and edit permissions can run all four import paths.

Will my Jira users be disrupted during migration?

No. Migration is read-only against Jira — Foundation imports your hierarchy metadata from the source app (Structure, BigPicture) or your CSV file, and caches Jira issues it finds along the way. It never modifies a Jira issue during import. Users continue working in Jira normally. If you run Structure or BigPicture in parallel during cutover (the recommended pattern), both apps will keep showing the same Jira data, because both read from the same Jira source of truth. Foundation only writes to Jira when a user explicitly edits a cell or drags a bar in a Lens.

Can I test-migrate first before committing?

Yes, and we recommend it. Every import creates a new Foundation Lens — it does not overwrite or merge into an existing one. You can import a single small structure from Structure Cloud, review the result, delete the Lens, and try again. Your Structure or BigPicture source is untouched throughout. For CSV, you can import into a test Lens, inspect the tree, and re-import with an adjusted column mapping. Foundation never deletes or modifies a source record during import, so there is no destructive step to worry about.

What if I find a mapping error post-migration?

You have three options. First, fix it inline: Foundation's grid lets you rename Flex Items, reparent nodes via drag-and-drop, and edit cell values directly — most mapping errors are faster to repair manually than to re-import. Second, delete the Lens and re-run the wizard with corrected column mappings (for CSV) or a different filter (for Structure/BigPicture). Third, for systematic issues, email [email protected] and include the import summary — we treat mapping bugs as P1 and ship fixes weekly. Running your old app in parallel gives you a fallback until the Lens is verified.