RFC-10: Confluence Whiteboards

I’m assuming whiteboards will show up in search results via /content/search - if we need to filter them out, will whiteboard as a type be available in CQL or will we have to filter the result itself?

TBH for my app, it will be easier to filter them via CQL not from the result, so I hope this is the case.

Please let us read and write the content of whiteboards programatically. Is it ADF format? A usecase is if a plugin’s job is to find-and-replace a keyword with another, on all pages/blogs/whiteboards of a space.

1 Like

Hi @AbhinavSingh ,
If I’m not mistaken, the whiteboard API uses deprecated v1 API endpoints.
When can we expect v2 endpoints?

2 Likes

Hi @AbhinavSingh ,

Thanks for the RFC. I have some questions:

  1. Can whiteboards have direct children of the “attachment” or “comment” content types?

  2. Are webhooks available for actions taken with whiteboards? If so, which ones and what is their expected payload?

  3. Can you please describe the API responses in more detail for whiteboards in the (deprecated) V1 REST API? What should we expect to see if the app tries to fetch a whiteboard?

  4. Even in the absence of rolling out an immediate REST API V2 equivalent, can you clarify how whiteboards will be represented in the existing V2 API calls that handle different types of content? For example, with whiteboards being integrated into the page tree, a page could now have a whiteboard as a parent. The V2 endpoint currently returns a “parentId” for an existing page. How do we know if that parent is a whiteboard or a page?

Scott

2 Likes

Hi @bobbergman1 - All v2 APIs would continue to return payloads as is. Whiteboards related content is not expected to be added in the APIs for our EAP customers or Beta customers. The APIs with whiteboard content (additive changes) will be supported before GA.

1 Like

Hi @marc : Changes (additive) to v2 endpoints are not supported for Beta and will be made available before GA (timeline: TBD). We will give sufficient time to test as introduce whiteboards are introduced in v2 APIs.

1 Like

H @AbhinavSingh ,
Thanks for the v2 API information.

We’ve got 2 followup question related to whiteboards:

  1. Will whiteboards get content properties?

  2. Will static and dynamic content macros work in whiteboards?

2 Likes

Hi @AbhinavSingh,

are you thinking about a way to let apps access / export the content of whiteboards? It would be nice if there was an endpoint to e.g. get the whiteboard as a PNG.

Cheers,
Sven

3 Likes

As far as I understood, one of the main goals of the V2 REST API was to split up the “Content” type and have separate endpoints for everything.

Now, adding Whiteboards into the mix, how is that going to pan out for endpoints such as the pages one? Will there be an endpoint to get children / descendants of all types, or will apps have to call multiple children endpoints and stitch together the actual page tree as it is in Confluence of their own?

Maybe @TylerBrown can shed some light on how the API team plans to deal with this?

3 Likes

Hi @SvenSchatter - currently for EAP/Beta, exports are not supported for whiteboards. However, the team would be working to expose whiteboard content in future (potentially around GA)

1 Like

:mega: Added Context:
Hi All,
Totally appreciate your comments and asks for getting whiteboards data through v2 APIs. Love the excitement to add them in your apps today :slight_smile:

Currently, our product team is concentrating on launching the whiteboard beta version for customers while ensuring that our partners’ existing apps remain unaffected (through any intentional/unintentional changes). We are not actively working on updating/adding APIs to expose whiteboard content before Beta.

Post-Beta and before GA, we’ll strive to have the appropriate APIs in place to provide access to whiteboard content and properties for your apps.

We would greatly appreciate your help in testing for any potential impacts before Beta, especially as whiteboards become available in your environments soon.

Hi @marc,

  1. Currently, whiteboards will have some content properties, but no editor properties (full-width, content-state, emoji-title, etc.). The existing content properties are not user changeable.
  2. There will not be any macros in whiteboards for EAP.
2 Likes

Hi @james.dellow,

Whiteboards will appear in search, and they will be available through CQL.

2 Likes

Hi @aragot - Whiteboards are not defined using an ADF format. We have yet to define a format which ecosystem partners can use (Will not be supported for public Beta though), but will let you know when we kick that process off, including updating the content of whiteboards via API. Let us know if you have any other use cases, we’d love to know of them!

Hi @scott.dudley - Answering your questions

  1. No, whiteboards won’t have comment/attachments as children for Whiteboards Beta
  2. We are not planning to provide webhooks for whiteboards beta.
  3. Whiteboards will still be returned in the Content API model, with all of the same fields and expands. The values of those may be different, ex: body will be null as of release. I can update this again closer to the us releasing whiteboards in your ecosystem environment.

Hi @marc - answering your questions here -

  1. No typical editor properties, but users will be able to set and retrieve their own content properties, like they can with pages.
  2. Macros are not supported in whiteboards beta.

Hi @SvenSchatter - we have not made a specific decision on whether additional expands would be added to existing APIs or new APIs dedicated to each content type would be added. Will keep you all posted as we decide and build them for GA.

4 Likes

:loudspeaker: Important Update:

For those who have the Developer Canary Program App installed and enabled on your tenants, you will begin to see the new whiteboard features and accompanying updates. These include whiteboards in content tree, search features, and more. Please refer to our above post for a detailed overview.

Urgent Next Steps:
We ask that you now test these updates within your apps and notify us of any potential impacts. Over the next two weeks, until June 28, if any issues arise, please comment below and we will provide a temporary fix while together we can work towards updating your app to work with the changes.

We will be launching an whiteboards beta program in July where any customer can opt-in and enable whiteboards on their tenant. Hence your feedback, especially from those directly impacted, is crucial. This will help us identify any impacted apps and develop a suitable contingency plan before customers enable the whiteboard features.

We appreciate your patience and cooperation during this period, and look forward to your valuable input.

Thank you!

6 Likes

Dear Atlassians,
Dear @KaiMunechika,

First of all, congratulations to the team! I think it’s really cool that we will be getting whiteboards within Confluence and having everything in one place, instead of having to switch between Miro or Figjam and Confluence.

However, I have some concerns and questions regarding the API v2 Development, and I would be interested in your input regarding migration strategies or suggestions.

Current state:
Currently, we are using API v1 (DEPRECATED GET /wiki/rest/api/space/{spaceKey}/content) in our Confluence app, which is set to be deprecated at the end of this year.

We are in the process of making plans on how to replace it and evaluating whether and how we should include the new whiteboards within our Confluence app.

With the rollout of the EAP, our existing functionality is being severely affected because the whiteboards are included in the page hierarchy as children, but not at the root level (results array of REST response) with the “/wiki/rest/api/space/{spaceKey}/content” endpoint that we are currently using.

There are further problems with Atlaskit tree component not being able to handle the response without code changes from our side.

Questions we have:

  • Why are the whiteboards currently included as children but not at the root level in the existing v1 endpoint (“/wiki/rest/api/space/{spaceKey}/content”)?
  • When is the official rollout of this functionality planned?
  • When will we be informed about it as an app vendor?
  • Will there be any v2 entry points specifically for whiteboards or will they be combined with the existing page’s rest endpoint?
  • Will there be more guidance provided in terms of an API v1 to v2 Migration guide in general?

Thank you very much in advance.

Best regards,
Martin

2 Likes

Hi @MartinKistnerDecadis - thanks for sharing the context and your questions! We’re glad to hear that your team is considering how to move forward with our APIs. To answer your questions:

Why are the whiteboards currently included as children but not at the root level in the existing v1 endpoint (“/wiki/rest/api/space/{spaceKey}/content”)?

Whiteboards were included as children but not at the root level due to technical limitations with introducing whiteboards into the content tree (f.k.a. page tree). We are planning on making minimal updates to the v1 endpoints, as our focus moving forward will on building on top of our new v2 API.

A quick question for you: Why & how does having whiteboards returned as children from other endpoints, but not returned from this endpoint severely affect your app? Looking for your feedback here to help inform our v2 API development.

Will there be any v2 entry points specifically for whiteboards or will they be combined with the existing page’s rest endpoint?

Yes, we will have whiteboard specific endpoints, that will be separate from page ones, and part of the v2 API.

When is the official rollout of this functionality planned?

When will we be informed about it as an app vendor?

Will there be more guidance provided in terms of an API v1 to v2 Migration guide in general?

We don’t yet have the answers for these questions; getting whiteboards fully supported in our APIs is still a work in progress. We want to keep you informed and provide accurate information, so we will update you as soon as we gather more data and have specific details to share.

3 Likes

:star: Overall for all of our partners here, to handle any breaking change with this latest release, we currently recommend:

  1. To minimize API usage specific to whiteboards (ex. whiteboards specific expands) as much as possible; the existing APIs exposing them are prone to further changes and we are not yet ready to support apps integrating with whiteboards via our API just yet.
  2. If possible, update the app(s) to handle errors related to whiteboards gracefully.
    • For example: previously, apps might have assumed certain requests only returned content of type Page, but this assumption will no longer hold true with whiteboards. A couple of places where we can see this are content ancestors and children.
    • Note: Functionality tied to archiving or copying whiteboards or subtrees containing whiteboards are not supported at this time - and will be available in an upcoming release.
  3. Reach out to us if both 1. and 2. are not sufficient for handling the breaking changes – the team will work with you to resolve this.

Thanks!

3 Likes