Structure to Foundation: The 10-Minute Migration Guide

If your Structure Cloud install is under ~2,000 issues, you can be fully migrated to Foundation in under 10 minutes. Generate an API token, run the wizard, verify the resulting Lens, flip your team. This guide walks the exact sequence — and calls out the one gotcha most teams miss (formula columns).

What do you need before you start?

Five things. Gather all five before you open the wizard and you will hit the 10-minute mark without rushing.

Foundation installed on your Jira site. One-click install from the Atlassian Marketplace. Requires Jira admin for the one-time install. Takes about 45 seconds. Free for the first 10 users, no feature gates.
Structure admin access on the source Structure Cloud instance, sufficient to generate an API token and read the structures you want to migrate.
Your Atlassian cloud region (usually obvious from your Jira site URL — for example, yoursite.atlassian.net). The Foundation wizard asks for this so it calls the correct Structure Cloud endpoint.
A 10-minute uninterrupted window. The async import runs in the background, but you want 10 focused minutes for the wizard, the verify pass, and the cutover message to your team.
A target install under ~2,000 issues for the 10-minute claim. Above that, the async job runs 20 to 45 minutes, but your hands-on time stays under 10 — you just close the browser and come back to the summary.

Need the deeper context on what does and doesn't migrate? The pillar migration guide covers the field-by-field breakdown, pricing rationale, and Expr formula trade-offs. This page is the tight walkthrough.

Step 1 — Generate a Structure Cloud API token

Open Structure Cloud inside Jira. Click your profile avatar in the top-right, then choose API Tokens from the dropdown. Click Create Token, give it a name like “Foundation migration,” select read scope, and click Create. Structure displays the token string once — copy it immediately to a scratch buffer. If you close the dialog without copying, generate a new one; Tempo doesn't show it twice.

The token inherits your Structure access. If you can read a structure in the Structure UI, the token can read it during import. Write scope is not required because the migration is strictly one-way into Foundation. See the Structure Cloud REST API docs if you want the full token-management reference.

Step 2 — Open Foundation's Import wizard

Switch to Foundation. If you just installed it, Foundation appears in the Jira app switcher as “Foundation.” On the Foundation Home screen, find the Import button in the top-right header. Click it and choose Import from Structure from the menu.

The wizard asks for two inputs on the first screen: your Atlassian cloud region (a dropdown — pick the region that matches your Jira site) and the API token you copied in Step 1. Paste the token and click Validate. Foundation makes a lightweight API call to Structure Cloud to confirm the token works. If the token is malformed or scoped wrong, the wizard shows the specific error inline — no silent failures.

Step 3 — Pick which structures to migrate

Once the token validates, Foundation queries Structure for every structure the token can read and displays a list. Each row shows the structure name, item count, last-modified date, and owner. Tick the structures you want to migrate. Foundation creates one Lens per selected structure by default.

For your first run, pick one small structure — a test structure, or a retired portfolio with a few dozen issues. A small first run lets you verify the end-to-end pattern before committing the big production structures. You can come back and run the wizard again for the big ones after you confirm the output looks right.

Step 4 — Configure per-structure options

For each selected structure, the wizard shows a per-structure options panel. Four toggles, all on by default:

Hierarchy — required; always on. Imports the full tree including any nested sub-items.
Generators — imports Structure generators and translates them to Foundation Sync Agents. JQL-based generators translate cleanly; exotic generators are flagged for manual review.
Saved views — imports column sets as Foundation views inside the new Lens.
ACL grants — imports permission grants when the grantees are Atlassian users or groups.

On your first run, leave all four on and accept the defaults. If anything looks wrong in the verify pass, delete the Lens and re-run with different toggles. See the license-management guide for how to coordinate the parallel-run period so your team is not blocked between structures.

Step 5 — Run the import

Click Start Import. Foundation kicks off an async job with a per-structure progress bar. For an install under ~2,000 issues with a handful of generators, typical wall-clock is under 10 minutes — most of that is waiting on the Structure Cloud API, not Foundation. The progress UI updates live.

You don't have to stare at the progress bar. Close the browser, grab coffee, check email. Foundation persists the job state in Forge SQL, so the summary page shows the completed results whenever you come back. For larger imports (above ~2,000 issues), plan on 20 to 45 minutes of background time per the product migration overview.

Step 6 — Verify the Lens and cut over

When the async job finishes, Foundation shows a summary page with links to each new Lens, plus a review-needed list highlighting anything that was flagged (most commonly, Expr formula columns). Open the smallest new Lens and run through this five-item check:

Row count — does the total match the source structure? Small discrepancies (1 to 3 rows) usually mean a non-issue node type didn't translate — check the summary.
Tree expansion — expand the hierarchy 3 or 4 levels deep. Does the parent-child shape match what you see in Structure?
Inline edit — click a Status cell and transition one issue. Confirm the change lands in Jira within seconds.
Sync Agent refresh — right-click a generator node and choose Refresh. Verify the expected issues appear.
Permissions — confirm the imported ACL grants apply, especially for shared Lenses.

If everything checks out, post a team-wide message: Foundation is now the default portfolio tool, with a link to the new Lens. Leave Structure running in parallel for one sprint — both tools read from the same Jira issues, so there's zero risk. Then cancel Structure on your next Tempo renewal date so you don't forfeit pre-paid time.

What's the one gotcha most teams hit?

Expr formula columns. Everything else in a Structure-to-Foundation migration translates cleanly — hierarchy, generators, ACLs, saved views, Jira issue links. Formula columns are the single item that surprises teams, because they look identical to normal columns inside Structure.

When the wizard encounters an Expr column, it flags the column in the review-needed list with a specific note: “Expr formula not supported.” The column is not imported — only the data columns it depended on. If your portfolio reports lean on Expr math (weighted rollups, custom conditionals, scripted aggregations), you have real work to do before cutting over.

The fix isn't hard, but it takes thought. The dedicated guide on replacing Structure's Expr formula engine walks through how to rebuild the most common Expr patterns using Foundation's Sync Agents, saved views, and conditional formatting — usually without losing any reporting fidelity. Read it before you cancel your Tempo subscription if you have more than a handful of Expr columns in production.

Frequently asked questions

Can I really migrate Structure to Foundation in under 10 minutes?

Yes, if your Structure Cloud install is under about 2,000 issues with a handful of generators. We clock the full sequence — install, token, wizard, verify, cut over — at 7 to 10 minutes on typical small-to-mid portfolios. Above 2,000 issues the async import job runs longer (20 to 45 minutes in our tests), but your hands-on time stays under 10 minutes because the job runs in the background and you can close the browser.

What if the wizard says my API token is invalid?

Three common causes. First, the token was copied with a trailing space or newline — regenerate and paste carefully. Second, the token lacks read scope for the structures you picked; regenerate with read scope on the target structures. Third, the Atlassian cloud region selected in the wizard does not match your Structure instance — double-check the region dropdown before hitting Validate. Foundation never silently fails on a bad token; the wizard shows a specific error message with the likely cause.

Do I need to pause my team during the import?

No. The import is strictly read-only against both Structure and Jira. Your team keeps working in Structure and in Jira while Foundation pulls metadata in the background. No issues are edited, no structures are modified, no writes go back to Tempo. The only side effect is a small amount of Structure Cloud API traffic bounded by Tempo's rate limits, which does not affect interactive use of Structure.

One of my Structure columns is flagged as an Expr formula. What do I do?

Expr formula columns do not port — Structure's Expr language has no equivalent in Foundation MVP. The wizard flags them in the review-needed list so you can decide. Most formulas fall into two buckets: counts or rollups (replaceable with a JQL Insert Sync Agent plus a standard column) and status filters (replaceable with a saved view plus conditional formatting). See the companion guide on replacing Structure's formula engine for the exact recipe.

Can I re-run the wizard if something looks wrong?

Yes, and you should. Each import creates a new Foundation Lens — it never overwrites an existing one. If the first import looks off, delete the Lens from Foundation Home and run the wizard again with different per-structure options. Your Structure source is untouched between runs. Most teams run the wizard two or three times on a test structure before pushing the big import through.

What is the one gotcha most teams miss?

Expr formula columns. Everything else — hierarchy, generators, ACLs, saved views, Jira links — translates cleanly. Formula columns are the single item that surprises teams, because they look like normal columns in Structure. If your team has portfolio reports that depend on Expr math, budget an extra 30 to 60 minutes to replan those reports before you cancel Structure. See the dedicated formula-migration guide linked below.