RFC-52: Folders as a New Confluence Content Type

RFCs are a way for Atlassian to transparently share what we’re working on with our valued developer community. Please respect our community guidelines: keep it welcoming and safe by commenting on the idea not the people (especially the author); keep it tidy by keeping on topic; empower the community by keeping comments constructive. Thanks!

Summary of Project

We are adding folders to Confluence in order to provide our customers with another way of organizing their content. We will launch a beta of the experience in late June or early July. Folders will exist within the current navigation, including the content tree. Users will be able to create a Folder directly from the Create button in the content tree.

This update will impact API responses for some of our existing APIs, and we’re mindful of the potential effects on your apps. These changes are very similar to the ones that you might have previously tested with whiteboards, databases, and embeds/smart links.

Your collaboration and feedback are essential to us as we work together to deliver a seamless experience to our mutual customers.

Publish : 15 May 2024
Discuss : 3 June 2024
Resolve : 17 June 2024

Problem/Opportunity

Confluence’s parent page model has served us well to date and has provided Confluence users with more flexibility, interconnectedness, and relationship visibility than they would have gotten from a more traditional folder construct.

However, the addition of new content types to Confluence has really stretched parent pages out of their comfort zone. Instead of one dual-purpose content type and container, we now have a higher number of dual-purpose content types and containers, which complicates Confluence’s organizational model.

Proposed solution

Folders are an extremely familiar construct in the world of file management, and they provide users with an alternative way to organize their content and manage permissions.

Therefore, we are looking to introduce Folders as a new content type. This will exist as a native content type within Confluence, with functionality and behaviors similar to other existing content types. These include but are not limited to existing in the tree, and being able to be created from the create button.

The permission model for Folders will also be the same as the existing parent/child permission model. That is, any content in a Folder will inherit view permission from the view permission of the Folder.

Proposed timeline

We are looking to release Folders to customers as a Beta in late June or early July 2024. Confluence site administrators will have the ability to opt-in and enable Folders for users on their instance.

Customers who chose not to opt-in for the Folders Beta will not see the changes until later in the year with an official General Availability (GA) release.

Proposed changes

Folders will be added to Confluence’s navigation structure and can be created in the content tree, similar to pages, whiteboards, and other content types.

image

:information_source: Important Note: The changes are very similar to those associated with the introduction of Whiteboards, Databases, and Embeds to Confluence, so the adjustments needed to your app(s) may be similar as well.

Previous RFCs for reference:

Potential effects on APIs

With the upcoming changes, some of our APIs will be updated to include Folder-related information in the response. Examples of such APIs are:

  1. Rest APIs.
    a. Endpoints that return children/descendants and ancestors for a Content that support the following expansion parameters will be affected. E.g.
        i. ancestors - will now return Folders in the response.
        ii. childTypes.all - this will not be affected immediately but will include Folders in the future.
    b. Endpoints under Content - children and descendants will not be affected immediately but we will include Folders in the response in the future.
        i. /wiki/rest/api/content/{id}/child
        ii. /wiki/rest/api/content/{pageId}/move/{position}/{targetId}
        iii. /wiki/rest/api/content/{id}/child/{type}
        iv. /wiki/rest/api/content/{id}/descendant
        v. /wiki/rest/api/content/{id}/descendant/{type}
        vi. /wiki/rest/api/content/{id}/pagehierarchy/copy
        vii. /wiki/rest/api/content/{id}/copy
    c. Content body expand will be empty for Folders
        i. /wiki/rest/api/content/{id}/expand=body.storage
  2. GraphQL APIs
    a. ConfluencePage.ancestor

Note: Support for v2 CRUD APIs for folders will be available soon.

How can you help?

Apps that directly use content tree (fka page tree) in their functionality may be affected. We highly urge those app developers to proactively test when the changes are available through DCP in your test tenants.

We would like to seek your collaboration in validating and mitigating any potential impact that these changes may have on your applications.

  • To facilitate this process, all required changes will be available through your Developer Canary Program in the week of June 10. This will allow you to thoroughly test your applications and report back any impact or issues that you may encounter. We will update the RFC as soon as it is live for you to test.

If your application will be impacted by the changes, we are looking forward to working together with you to resolve any issues before releasing the new content type to our shared customers. If you do not see Folders enabled on your tenant after the Developer Canary Program starts, please raise a support ticket and comment in the RFC here so we can help enable folders on your site.

To reiterate, this change will be very similar to those made when introducing Whiteboards, Databases, and Embeds, so the validation process should look similar to before. We highly urge you to make your apps generic enough to accept any new content types in the future to avoid any disruption.

2 Likes

Hi @NickBourlier, thanks for the RFC!

Could you please also provide some info on how the folders will be represented in the main view (where pages display their ‘body’)?
Will it be possible for end users to customize this body?
Will we be able to navigate to a folder itself when clicking it in the tree or will they be ‘passive’ tree nodes just for grouping content?

Thanks,
Jens

4 Likes

When you write about the REST API, you mention the generic (non-typed) “/wiki/rest/api/content/…” URL namespace. So far I had the impression that this approach is considered legacy, and with v2 you are going after providing typed end-points like “/wiki/api/v2/pages/…” and such.

I am now confused. What’s the current plan?

4 Likes

Please don’t forget the webhooks for CRUD events in your concept.
This will enable us a vendor to react on tree changes.

6 Likes

Hello, this is an interesting addition, but you only seem to be telling part of the story here.

Some initial question spring to mind. I might edit this and add more :wink:

  • How are folders rendered in the UI?
    • on web?
    • on mobile?
    • in native apps?
  • Can a folder be thought of as just like a page but without any content?
    • So you can expand it in the navigation, but not “view it”?
  • Can a folder have attachments?
    • Including nested folders?
  • What can go in a folder?
    • Any file type?
    • Specific file types?
    • Or just current confluence content types?
  • Is Confluence now competing with Sharepoint to have huge piles of documents in random nested folders?

What’s the grand vision here?

11 Likes

Hi all,

Is this really an RFC, or is it an EAP in disguise?

Other questions:

  • Will atl.general and atl.footer webpanels be rendered on folders?
  • How will a folder be represented in calls to AP.context.getContext()?
5 Likes

Hi @NickBourlier, thank you for this RFC. Folders seem to be a useful feature for organizing content, but the lack of API support for the new content types is increasingly becoming a problem for our users. We offer apps that allow users to interact with content trees and we are unable to display content hierarchies below whiteboards, databases, smart links, and folders.

Nesting content below non-page content is probably not that common, but I’m sure this will change when folders are available and users no longer have to create empty “container pages” to structure their content.

To make our apps compatible with these changes, we need API endpoints that return all children of a specific piece of content, regardless of their type. Unless I’m missing something, such APIs are not yet available in either REST v1 or v2.

6 Likes

Hi David — my name is Ned, and I’m the product manager on this feature. Answers to a few of your questions:

How are folders rendered in the UI?

Folders are an organizational construct, so they will not render anything in the editor UI. Instead, they will expand/collapse in the content tree and will show up in views like All Content, Search, etc. The experience should feel similar to folders on Mac OS. Folders are purely additive, meaning parent pages will still be available if you prefer to add content to your containers.

Can a folder be thought of as just like a page but without any content?

Yes, precisely!

Can a folder have attachments?

Attachment is kind of a term of art so I’ll disambiguate here for clarity. You cannot upload e.g. PDFs to a folder in Confluence. Folders can only parent object that you can create in Confluence, meaning they can contain pages, whiteboards, databases, smart links, or other folders.

What can go in a folder?

Answered above. Folders can only parent objects that can be created in Confluence.

Is Confluence now competing with Sharepoint to have huge piles of documents in random nested folders?

Confluence is not a file storage product. We’re adding folders purely to provide our users with another way to organize their content,

Hi @klaussner , thanks for the feedback! The team is working on an API that will return children of all types for a piece of content. It should be available in the coming weeks!

2 Likes

In short, there aren’t any high level changes to the current plan.

Much of the V1 APIs under wiki/rest/api/content are indeed deprecated, and we encourage everyone to move towards using the V2 APIs. The decision to move to typed endpoints in the V2 APIs was intentional as we are moving towards different content types as discrete entities.

I referenced the V1 APIs in the RFC for completeness in case any apps are using the V1 APIs still.

Hey @jens! Thanks for the question. My name’s Ned, and I’m the product manager on this feature. Please see my response to @david’s question below, which should satisfy most of your question.

1 Like

Thanks for the feedback! We’ll plan to emit webhooks for the CRUD operations on Folders.

Hi @NickBourlier, how will be migrate pages which act like folder but also with a body? Is the body will be mvoe in a new page inside the folder? What about Page Tree macro for example?

Hi Scott,

As outlined in Ned’s response, we are not planning to have a full screen view for individual folders. As such, webpanels or JS modules that are available when viewing other content types won’t be available for folders.

2 Likes

Hi @PierrickChevallay1 - for the beta, we won’t be migrating parent pages that act like folders. As mentioned in some of the other comments, Folders are an organizational construct, so they won’t have a body.