Documentation · Safe Tree Copier

Before you start

You need Confluence Cloud. The app is built on Atlassian Forge, so it doesn’t run on Confluence Data Center or Server.
A site admin installs the app once for the whole site.
To copy, you need permission to view the source pages and to add pages in the destination space. Your site admin can also limit copying to admins of the destination space.
Copies happen between spaces on the same Confluence site.

Install the app

A Confluence site admin installs Safe Tree Copier from the Atlassian Marketplace. During installation, Atlassian asks the admin to approve what the app can access:

Read pages, spaces and the page tree, to plan a copy.
Create and update pages, to write the copies.
Read and add attachments and labels, to copy them across and verify them.
Page permission checks, so every copy, including scheduled ones, only does what the person behind it is allowed to do.
App storage, to keep copy plans, reports and saved jobs.

The app never deletes or trashes pages, and it never changes space or page permissions. It has no way to: those calls aren’t in its code.

Copy a page tree

Open the page at the top of the tree you want to copy.
Open the page’s ••• menu and choose Copy tree (preview first). The Copy page tree dialog shows how many pages, attachments and labels are in the tree.
Under Destination, choose the Space (only spaces where you can add pages are listed) and the Parent page the copy should go under. Leave the parent as Space home (top level) to copy to the top of the space.
Check the options (see Copy options). The defaults are the safe choice.
Choose Preview. There’s no way to copy without seeing the plan first.

Copy options

Include the root page (on): copies the page you started from as well as the pages below it. Turn it off to copy only its children, placed straight under the parent you picked.
Copy attachments (on) and Copy labels (on).
Only copy pages with these labels: copy only pages that carry the labels you list. With two or more labels, choose Match any label or Match all labels. The dialog shows how many pages match. Pages whose parent is left out attach to their nearest included ancestor, so the shape of the tree is kept.
If a page already exists with the same title under the destination parent:
- Skip it (the default): the existing page is left exactly as it is.
- Copy with a suffix: a new page is created next to it, with (copy) added to its title. You can change the suffix.
- Overwrite as a new version: the existing page gets a new version with the source content. Earlier versions stay in its page history.
Quiet mode (on by default, under Notifications): updates and attachment uploads are saved as minor edits, and because the app writes the pages itself, the person copying isn’t added as a watcher of every page. That keeps watcher emails down during big copies, but it can’t switch Confluence notifications off: people watching the destination space may still get one notification for each new page.

Read the copy plan

Review the copy plan lists every page in tree order with what will happen to it (Create, Overwrite, Rename or Skip, with the reason for a skip), how many attachments come with it, and its labels. Totals sit at the top, with the number of attachments to copy. The plan also warns you about attachments over the size limit, which won’t be transferred, and pages left out by the label filter.

Every screen of the copy says the same thing: nothing in the destination will be deleted or moved to trash, and space permissions won’t change.

Tick I reviewed this plan, then choose Confirm and copy. You can also go Back to options, or Save as job to reuse the copy later.

If anything in the source tree changed after the preview, confirming copies nothing. The app tells you the source changed and offers Preview again, so you always confirm the plan that will actually run.

Follow progress

The copy runs in the background, one page at a time, in the source’s order. The progress view shows pages and attachments done (and failed), the page and step being worked on, and any problems in plain language with the page, the step and the reason.

If Confluence asks the app to slow down, the copy waits as long as Confluence asks and continues. If it’s interrupted, it resumes from the last finished page instead of starting over, and never creates a page twice. Pages are created with their final titles straight away, so nothing is left behind marked as “copy in progress”.

Links between pages inside the copied tree are pointed at the new copies. Links to pages outside the tree keep pointing at the originals.

Stop after current page stops the run cleanly. Pages already copied stay where they are.

Check the attachment report

After each page is copied, the app compares its attachments with the source by name and size. The Attachment check shows totals and, for every page, how many attachments matched, are missing, have a size mismatch, were too large to transfer, or failed. Expand a page to see each file, and choose Open copy to open the copied page.

Retry failed items runs the copy again for just the pages that failed, or whose attachments failed, went missing or didn’t match. Copy summary puts a plain-text summary on your clipboard for a ticket or a page.

Saved and scheduled jobs

Saved copies live on the Copy jobs page, under Apps in Confluence. It lists the saved jobs on your site with their source, destination, schedule, last run and next run. For each job you can:

Run now. You always get a fresh copy plan to review first.
Edit it from the job’s ••• menu: its name, destination, options and Schedule (None, Daily or Weekly, at an Hour (UTC) you choose, and a Weekday for weekly runs).
Turn on Skip pages unchanged since last run, so repeat runs only touch pages whose source changed.
Pause schedule and Resume schedule.
Open its Run history: each run’s start time, trigger (manual, schedule or retry), status, pages, duration and report.

Combined with Overwrite as a new version, a scheduled job keeps a destination tree refreshed from its source, one way.

Scheduled runs act on behalf of the job’s owner: whoever last saved the job. Before each run, the app checks that the owner can still view the source and edit the destination, and stops with a clear reason if not. After a job is saved, preview it once with Run now before its first scheduled run.

Remove job deletes the job’s saved settings and run history from the app. It never touches any pages in Confluence.

Settings for site admins

Under Safe copy settings in Confluence’s app settings, a site admin can:

Turn on Restrict copies to destination space admins.
Set the Maximum attachment size (MB) the app will transfer: 100 MB by default, from 1 to 250 MB. Larger files are listed as “too large” and skipped.
Set the Days of run detail to keep (30 by default, 1 to 365) and the Runs kept per job (20 by default, 1 to 100).
Choose whether quiet mode starts on: Quiet mode on by default.

Other people can open these settings from Copy jobs to see how copies are configured, but can’t change them.

What isn’t copied

Comments, blog posts, page history, page restrictions, space settings, themes and permissions aren’t copied, and the app doesn’t copy between different Confluence sites. Macros are copied exactly as they are.

Licensing

If the app’s license on your site is inactive, the app says so: copies, previews and scheduled jobs pause until a site admin renews it in Manage apps. You can still open the reports of earlier runs.

Troubleshooting

The menu item is missing. Ask a site admin to check that the app is installed and its license is active.
“You don’t have permission to create pages in…” Ask that space’s admin for the “Add page” permission, or pick another destination.
“The source changed after this preview.” Someone edited the source tree. Choose Preview again and confirm the new plan.
A page failed because its title is already used. Confluence titles are unique within a space, so a page with the same title elsewhere in the destination space blocks the copy. Run it again with Copy with a suffix.
An attachment shows as too large. A site admin can raise the limit in Safe copy settings, up to 250 MB.
A scheduled job didn’t run. Open its Run history: a blocked run says why (license or permissions). A job that hasn’t been previewed since it was last saved waits for a Run now first.
Something else. See Support.