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.
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:
- RFC-10: Confluence Whiteboards
- RFC-23: Confluence Databases
- RFC-37: Embeds as a New Confluence Content Type
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:
- 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 - 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 late June. 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.
