Confluence import

Confluence is one of five import sources. For the others (Linear, Jira Cloud, Asana, and GitHub Issues, which import issues into a project) and the shared mechanics, see the Imports overview. This guide covers the Confluence pages import in depth.

What it does

• Connects to a Confluence Cloud site with OAuth, then imports into a destination Ithura project you choose.
• Recreates the page hierarchy as an Ithura page tree (parent / child relationships are rebuilt after all pages exist).
• Fetches attachment binaries and rewrites the inline references in page bodies to point at the imported Ithura assets.
• Rewrites internal links between Confluence pages to point at the new Ithura pages. Links to pages that were not imported are counted as unresolved in the report.
• Maps common Confluence macros to Ithura blocks: code, info / note / warning / tip / panel callouts, status badges, expand / collapse, table of contents, child pages, attachments, Jira links, and Mermaid. Any macro without a mapping is preserved as a labeled "[Unsupported macro: name]" block so nothing is silently dropped and you can repair it by hand.
• Maps Confluence page permissions onto Ithura's page access model (see below), and flags anything that could not be matched for admin review.
• Produces a per-run report showing pages, spaces, attachments, restricted pages, unresolved links, and any grantees that need review.

Before you start

• You need workspace access to the Imports settings and a Confluence Cloud site you can authorize.
• You need an existing Ithura project to import into. The importer requires a destination project; imported pages are linked to it.

Where it lives

Open Workspace settings -> Imports at /{workspace}/settings/imports. The Imports page lists the available sources (Linear, Jira Cloud, Asana, GitHub Issues, and Confluence Cloud) and a history of recent import jobs. Select Confluence Cloud to start the wizard.

Run an import

1. On the Imports page, click Confluence Cloud.
2. Click Connect Confluence (OAuth). You are redirected to Confluence to authorize the connection. This stores an encrypted access token for your workspace, so you only need to connect once per workspace.
3. Back in the wizard, choose a Destination project. Imported pages are linked to this project's wiki. Connect Confluence first if you have not already.
4. Click Run import. The job starts in the background and appears in the Recent imports list.

While it runs

Imports run in the background; you can leave the page. The Recent imports list refreshes on its own and each job shows its status and progress. Expand a job to see:

• A progress bar and the current stage (connecting, spaces, pages, hierarchy, attachments, permissions).
• A Cancel button while the job is pending or running.
• The import report once the job completes.
• Any errors recorded during the run, grouped by stage.

The import report

When a job completes, expand it to read the report. It shows:

• Pages imported across how many spaces.
• Attachments imported.
• Pages made private because they carried Confluence restrictions.
• Unresolved internal links (links to pages that were not imported).
• Any restriction grantees that need review, listed by email, because they could not be matched to an Ithura account.

How permissions are mapped

Confluence permissions are richer than Ithura's, so the mapping is deliberately conservative and fails closed:

• A page with any read or update restriction in Confluence is made private in Ithura.
• For each restricting user, a page access grant is created: read maps to view access and update maps to edit access. Group restrictions are expanded to their members.
• A restricted page is always made private even if none of its grantees can be matched, so a restricted page never becomes broadly visible by accident. When no grantee matches, only the person who ran the import retains access as the page owner.
• Grantees are matched to Ithura accounts by email. Anyone who does not match an active workspace member is listed in the report as needing review so an admin can grant access by hand.
• Confluence group membership is read up to 500 members per group. If a group is larger, the run records that membership was truncated and some grants may be missing, again surfaced for admin review.

Because the mapping is lossy by design, review the report's flagged grantees and restricted pages after each import and re-assign access where needed.

Attachments and links

• Attachment binaries are fetched during the attachments stage and stored through Ithura's asset path. Inline references in page bodies are rewritten to the imported assets.
• Internal links between imported pages are rewritten to the new Ithura pages. A link whose target page was not part of the import is left unresolved and counted in the report.

What is not imported

• Blog posts (only pages are imported).
• Page comments and version history (the current page content comes across, not its comment thread or past versions).
• Confluence labels on pages.
• Jira issue macros come across as a plain link, not a live issue reference.
• Unsupported macros are kept as a labelled block with their text preserved, rather than rendered as the original macro. Common macros (code, panels, status, expand, task lists, table of contents) are converted.

Troubleshooting

• "Workspace is not connected" or the import fails at connecting. The Confluence OAuth connection is missing or expired. Reopen the Confluence source and click Connect Confluence (OAuth) again.
• "A destination project is required." The import needs a destination project. Reopen the wizard and select an existing project before running.
• Run import is disabled. Choose a destination project first; the button stays disabled until one is selected.
• The report lists grantees needing review. Those users could not be matched to an Ithura account by email. Grant them access manually on the affected pages. The pages were kept private, so no unintended access was granted.
• The report shows unresolved links. Those links pointed at Confluence pages that were not imported (for example, pages in a space you did not include). Import the missing pages, or fix the links by hand.
• A macro shows as "[Unsupported macro: name]". That macro has no mapping. Its original content is preserved in the block; replace it with the equivalent Ithura block manually.
• A job is stuck pending or running. Expand the job and use Cancel. You can start a new import afterward.