Documentation

What you need

• Confluence Cloud.
• Treewright installed on your site. Installing an app needs a Confluence site administrator.
• Permission to view the pages you copy and to create pages in the destination space.

Treewright acts as you. It can read and change only what you can read and change in Confluence, so it does not give anyone access to a page they could not already reach. The one exception is the optional restriction rule, described below.

The first time you use Treewright, Atlassian shows a consent screen. Approve it once. It lets the app act on your behalf.

Copy a page tree in five steps

1. Open the page at the top of the tree you want to copy.
2. Open the ••• menu of the page and choose Copy page tree….
3. Under Where should the copy go?, choose a Destination space. Optionally choose a page under Under this page; leave it empty to copy to the root of the space.
4. Choose what comes along and how the new titles are made (both explained below), then choose Preview.
5. Read the preview. If it looks right, choose Start copying.

You can close the window as soon as the copy has started. The job continues in the background. Open Apps, then Treewright, then Jobs to follow it and to read the report.

Copy options

Destination

Choose the Destination space, then search for the page the copy should go under (type at least two letters). The copy becomes a child of that page. If you choose the same space as the original, use a prefix or a different parent so the titles differ. A destination inside the tree you are copying is refused in the preview.

What should be copied

Each of these is a checkbox. All are ticked at first except Page restrictions: tick it if the copies should get the restrictions of the originals.

• Attachments
• Labels
• Page properties (page width and other settings)
• Page restrictions, applied last so that links can still be fixed
• Update links so they point to the copies

Restrictions are applied after the links have been rewritten, so a restriction can never lock Treewright out of a page it still has to fix.

Page titles

Choose Keep the titles, Add a prefix or Find and replace. Find and replace works on literal text, not on patterns.

Then choose what happens If a title already exists in the destination space: add a number, for example "Plan (2)", or stop and let you change the settings.

There is also a checkbox to copy page by page. It is slower but gives exact control. The preview tells you when page by page copying is used anyway.

The preview

Nothing is created until you start the copy. The preview shows:

• the number of pages and how deep the tree is
• the title of every copy next to the original page (the first 200 pages for a big tree, with a note), and which titles were renamed because they already exist
• the copy method that will be used, and why
• warnings for content that cannot be copied (whiteboards, databases, folders, smart links used as pages, archived pages)
• warnings for very large trees, and an error if the destination is inside the source tree
• a note that pages you are not allowed to see are not listed

If you are not allowed to create pages in the destination, if the source or destination cannot be read, or if the destination is inside the tree you are copying, the preview says so and the copy cannot start.

Two copy methods

Treewright chooses the method for you and tells you which one it picked.

• Confluence copies the whole tree on its servers. This is the fast route. It is used when the destination is a page, there are no title conflicts, nothing in the tree is uncopyable and the title rule can be expressed in Confluence's own settings.
• Page by page. Used for the top of a space, title conflicts, templates, trees with uncopyable content, and as a fallback: if the fast route fails, the job stops, and Resume continues page by page. Pages are copied one after another so that the order of siblings is kept, which takes longer.

Links in the copy

After the copy, Treewright builds a map from every original page to its copy and rewrites each copied page from the content of its source page. Only the parts that need to change are changed. Everything else stays exactly as it was.

Links to pages outside the copied tree keep pointing at the originals. When the copy lands in another space, a link by title that has no space key is fixed to the source space, so it keeps its meaning.

If Treewright finds something it cannot safely rewrite, for example an unknown macro that still contains the ID of a source page, it adds a warning to the report instead of guessing.

Jobs and reports

Open Apps, then Treewright. There are three tabs: Jobs, Templates and Edit restriction rules.

The Jobs tab lists your 50 latest jobs from the last 90 days with their status. Choose Details on a job to see:

• the new pages, with links
• every rewritten link, before and after
• warnings
• pages that had problems, and pages that were copied without their restrictions

A job ends as succeeded, succeeded with warnings, failed or cancelled.

Stop and resume

Choose Stop on a running job to cancel it. A stopped or failed job can be continued with Resume. Pages that an earlier attempt already created are recognised and reused, so a resumed job does not copy them again.

Templates with variables

A template is a page tree with placeholders in the titles and the text.

Save a template

1. Open the top page of the tree (a space just for templates works well) and choose Save page tree as template… in the ••• menu.
2. Treewright looks for placeholders written as {{Variable}} in every title and every page. If the search cannot finish in the time available, it says how many pages it could search, and you can add the missing variables by hand.
3. Give the template a Name of the template and, optionally, a description.
4. Review the variables. For each one you can set the Question to ask, the Type (text, date or choice from a list), a Default value and whether it is Required. Choose Not a variable to drop something that only looks like one.
5. Choose Save as template.

{{Today}} and {{SpaceKey}} are built in: today's date and the key of the destination space.

If a placeholder is split by formatting, for example with bold or a link inside the braces, Treewright warns you. Retype it without formatting, or it is not replaced.

The template list is kept by Treewright. The tree itself stays in Confluence, so attachments, labels and restrictions are still there when you use the template.

Use a template

1. Open Apps, Treewright, Templates and choose Use on a template.
2. Fill in the form and choose the target space.
3. Choose Preview to see the titles with your values filled in, then Create the pages.

Values are inserted safely. Text is escaped properly, so a client called Acme & Sons works in titles and in page text, and values that end up in code blocks or links are handled according to where they appear. Placeholders that Treewright does not know are left untouched and reported.

If a page with a resulting title already exists, the new title gets a number, as with copying.

Edit restrictions that follow the tree

Apply to existing pages

1. Set the edit restrictions of the top page in Confluence, with the padlock at the top right of the page.
2. Open the ••• menu and choose Apply edit restrictions to child pages….
3. Choose All pages below this page or Direct child pages only.
4. Read the preview. It tells you who may edit the page, how many pages below it would change and how many already match. It also warns you if you are not on the edit list yourself.
5. Choose Apply to the number of pages shown.

Only edit restrictions are copied. View restrictions of the child pages are not changed. A page without edit restrictions cannot be used as the source, so nothing is removed by accident.

Keep doing this (the rule)

Tick Keep doing this in the same dialog. Pages that are created, copied or moved below the page then get its edit restrictions automatically.

• Choose the scope with the radio buttons: all pages below the page, or its direct children only.
• If several rules apply to a page, the closest one wins.
• The change is made as the person who created, copied or moved the page. If Atlassian cannot act as that person, for example because the account was deactivated, Treewright uses its own identity for that one change.
• Pages created by a Treewright copy job are skipped on purpose, so a running job does not lock itself out. Afterwards you can apply the restrictions to the copies with one click.
• Confluence can deliver page events up to three minutes late, so a new page may need a moment.

The Edit restriction rules tab lists every rule, lets you turn it on or off or remove it, and shows the recent activity of the last 14 days.

Permissions, licensing and data

• Every request goes through Confluence as you, or, for background work, as the user who started the job. Confluence permissions decide what is possible.
• Production sites need an active license. When the license is not active, the features show a message, but you can still read the job history and stop running jobs.
• Page bodies are not stored. Jobs, reports, templates and rules are kept in Forge storage on your site, and a template keeps a few short excerpts of text where a placeholder could not be read. See Security for the full list and retention, and the Privacy Policy.

Limits

• Treewright copies page trees. Space settings, permissions, blogs and the theme are not copied, and there is no one-click space copy yet. Copy the top pages of a space one by one.
• Whiteboards, databases, folders, smart links used as pages and archived pages are skipped, together with everything below them. They are listed in the preview, and the report counts them.
• Pages you are not allowed to see cannot be listed by any API. They are not copied, and the preview can only mention this in general terms. When Confluence copies the whole tree itself, Treewright compares the number of pages with the number Confluence reports.
• A job copies up to 2,000 pages. Page by page copying is sequential, so large trees take minutes, not seconds.
• Edit restrictions are inherited as edit restrictions. Groups cannot be looked up, so the warning that you are not on the list applies to named people only.
• Confluence Cloud only.

Need help?

See the support page for how to reach us, what to include and answers to common questions.