RFC-37: Embeds as a New Confluence Content Type

[KaiMunechika]

Summary of Project:

We are planning to launch Confluence Embeds to our customers. At the end of March 2024, we’ll be integrating Embeds as a new content type within Confluence that will exist within the current navigation and creation structures, including the content tree. Users would be able to add an embedded view of a smart link directly from the Create buttons and in the content tree. This update would 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 and databases.

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

Publish : 23 February 2023
Discuss : ~1 March 2023
Resolve : ~20 March 2023

Problem/Opportunity

The fundamental user problem that we are trying to solve - “Teams’ success depends on easily finding and accessing the right information needed to do their work.”

We have a strong belief that users desire a unified platform for all their content across various applications, and Confluence is an absolute right fit to be that connected workspace for users and their team.

Proposed Solution

To solve the above problem, we are introducing Embeds as a new content type. Basically any user can add an embedded view of a Smart Link in the content tree. This can be an existing confluence page, a loom recording, a google sheet, figma file, etc.

This would 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.

In this post, we will provide important details about this upcoming change and what you need to know as an ecosystem developer.

What is changing in the upcoming release?

In one of the upcoming releases, Embeds will be added to Confluence’s current navigation structure.

Important Note: The changes are very similar to those associated with the introduction of Whiteboards & Databases to Confluence, so the adjustments needed to your app(s) may be similar as well ( previous posts on Whiteboards RFC-10: Confluence Whiteboards and Embeds RFC-23: Confluence Databases ).

Here are the most relevant upcoming changes:

Embeds Creation

• Embeds can be created similarly to pages’ creation mechanism

• Embeds can be created both through the top navigation ‘Create’ button and clicking on “Smart Link”
  

• Embeds can be created through the “+” button next to Content in the sidebar.
  

  

When will this change take place?

The feature will be released to customers in a measured rollout process starting at the end of March 2024 to be completed over 4 weeks or so. Enterprise customers would be able to control the availability of the feature through Release tracks.

Actions

How might this affect you?

With the upcoming changes, some of our APIs will be updated to include Embeds-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 expand parameters will be affected. E.g.
   i. ancestors - will now return Embeds in the response.
   ii. childTypes.all - this will not be affected immediately but will include Embeds in the future.
   b. Endpoints under Content - children and descendants will not be affected immediately but we will include Embeds in the response in the future.
   /wiki/rest/api/content/{id}/child
/wiki/rest/api/content/{pageId}/move/{position}/{targetId}
/wiki/rest/api/content/{id}/child/{type}
/wiki/rest/api/content/{id}/descendant
/wiki/rest/api/content/{id}/descendant/{type}
/wiki/rest/api/content/{id}/pagehierarchy/copy
/wiki/rest/api/content/{id}/copy
   c. Content body expand will be empty for Embeds /wiki/rest/api/content/{id}/expand=body.storage
2. GraphQL APIs
   i. ConfluencePage.ancestor

Note: Support for v2 CRUD APIs for embeds will be available soon!

How can you help?

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

As we prepare to go live with the upcoming changes, 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 Feb 26, 2024. 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 fo you to test.

If your application is 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 Embeds enabled on your tenant, please raise a support ticket and comment in the RFC here so we can help enable embeds on your site.

Reiterating, this change is very similar to those made when introducing Whiteboards and Databases, so it should be easy to validate. We highly urge you to make your apps generic enough to accept any new content types in the future to avoid any disruption.

[remie]

@KaiMunechika this is not an RFC. This is an EAP announcement in which you are asking us to make sure our apps work before you go GA.

If you are ever wondering what marketplace partners might think at the stage of the drawing board, please do reach out to us again using the RFC format. Otherwise, please don’t bother.

cc: @ibuchanan @Anthony

[david]

Will the content type be reflected in the context provided by AP for Atlassian Connect apps that use the atl.footer extension location? Will the atl.footer location even be available for an embed content type?

Has this been thoroughly thought through or rush released, like my comment?

[aragot]

I think you meant to ask “Do you have comments before we close this request-for-comments” so I’ll optimistically assume that we can comment:

Do Smart Links have an API to build smart links for any kind of web content, not just Miro boards and Google Docs? Smart Links seem to have a limited list of built-in apps, and default to pulling the tags of webpages, but unauthenticated, which is useless in the context of documents. In other words, apps can’t provide the snippets for smart links.

If not, then it reinforces the dominance of dominant players and prevents new entrants (in addition to blocking many usecases which would be possible with apps).

Also, if it breaks an API, it’s a breaking change with 6 months of deprecation period.

[AbhinavSingh]

Hi Remie,

I am Abhinav, PM for Confluence Content Types, and I work with Kai. I truly appreciate your feedback and apologize if our message seemed more like an announcement rather than the intended RFC.

Here’s a quick rundown of key points that I want to call out - hope it adds more color to the picture.

• Priority (foundational milestone): Introducing Smart Link embeds in the Content Tree is a foundational milestone as we think about bringing more 1P/2P/3P content for our users. Our top priority today is ensuring no negative impact on our marketplace partners and shared customers through any breaking API change with the introduction.

• Why we still have time to test for all these changes:

  • Rollout Schedule:
    • Phased: Aiming for a measured rollout starting by the end of March, extending to the end of April.
    • Enterprise Access: Enterprises will access this feature via Release checks, likely starting in May, which gives us additional buffer time.
  • Adoption Rate: We anticipate gradual adoption for the feature, aligning with users adjusting to a new way of working.
  • Fallback Plans: If any critical issues arise, we have fallback plans ready to prevent any disruptions on a per-tenant or per-app basis.
  • [Important] Changes similar to Whiteboards and Databases: The changes are very similar to those introduced while we added whiteboards & databases, and hence we are fairly confident on very low API impact this time.

• Future Development (the more collaborative phase ):

  • As users gradually adopt Smart Link embeds, we plan to enhance the feature with support for more 1P/2P/3P content, diverse display options, and expanded functionality within embeds, working on more extensibility for our partners.
  • This is where we look forward to partnering with you all for these enhancements, ensuring we have ample time for collaboration and integration.

We absolutely acknowledge your concerns but want to keep this RFC focused on identifying and testing potential API changes. Thank you for your understanding and support as we navigate introducing Smart Link embeds and making it awesome it over time.

[remie]

Hi @AbhinavSingh ,

Thank you for responding, but I’m afraid even with your valiant try there is no way that this is an actual RFC. Al the highlights you have selected are normal parts of EAP announcements.

You are not asking us for any input with regard to the problem space, nor with regard to the chosen solution. You are only asking us to make sure to check whether the chosen, and already developed, solution will impact our apps.

This is not an RFC, no matter how much lipstick you try to put on it.

[scott.dudley]

Since at least the APIs are considered on-topic, let’s talk about those:

@KaiMunechika

Note: Support for v2 CRUD APIs for embeds will be available soon!
[…]
We highly urge you to make your apps generic enough to accept any new content types in the future to avoid any disruption.

Without intending to sound like a broken record, while it’s great that the absence of V.2 APIs has been acknowledged in the announcement, shouldn’t this really have been considered a gating feature before rolling this out to any customer instances?

If Atlassian is going to say that the V.2 API is the end-all of APIs and that all apps should be using it, apps simply need to be able to navigate the entire content tree using accessible APIs.

If you create a scenario where new content types can have children and ancestors, but apps cannot navigate the content tree down (or particularly up) from wherever the app is used, this is a breaking change.

The request to make our apps “generic enough to accept any new content types” ends up being rather unfortunate because Atlassian hasn’t released the V.2 APIs needed to do that…and this is the third feature in recent memory where this has happened.

Even if these V.2 APIs were magically released today, you also need to give app developers enough time to implement these changes…and the four weeks proposed between announcement and rollout is simply not enough.

The implicit message that this sends to app developers is that we should not even bother trying to migrate anything to V.2 until all of this gets sorted out, with no end date in sight. I don’t think that is what Atlassian really wants, right?

Atlassian needs to:

1. Bake in V.2 API support from ground zero for new projects, and alert any preexisting projects that this needs to happen, and add it as a requirement to complete before even the EAP, and

2. Recognize that all these new content types require an entirely new set of endpoints to be coded from the app vendor side, and provide three months of notice before rolling out a new content type to any customer. (Or officially decide not to deprecate the existing V.1 generic endpoint that * cough * provides access to all content types in a really clean manner and which would solve all of these problems at once.)

[jens]

@KaiMunechika could you please confirm if instances of this new content type show up in the V2 API at /pages/{ID}/ancestors, similar to how whiteboards are represented there?

Our apps require the ancestor line to be complete for correct operation.

Also I was wondering what the plans are for making the content of these objects available to apps via the REST APIs. Atlassian keeps adding functionality that is invisible to us and our customers are (rightfully) requesting compatibility with smart links but we can do nothing without proper support in the REST APIs.
Currently we have to tell them ‘Yes we know it’s not working, don’t use it’, which is not satisfactory for anybody.

Thanks,
Jens

[Anthony]

Thanks for the comments here everyone, they’re appreciated. My team continues its work to educate teams on how and when (earlier!) to best leverage the full value of RFCs. This is a good example of a team genuinely trying to do the right thing by sharing with the community but missing the mark. A reminder of the work still to be done by my team!

We agree the stage this project is at is better suited as a Partner EAP. Based on that, the team has announced it as an EAP via the Changelog. There’s a new open CDAC topic where anyone who wants to participate in the conversation + give feedback can do so. We’ll close this RFC to direct the conversation there. Thanks!

This feature team is very keen on identifying any impact on apps so it can be scoped. The feature will be available any instances currently participating in the Developer Canary Program.