RFC-32: Confluence Content Customization

General Request for Comments (RFC)
,
1

RFCs are a way for Atlassian to share what we’re working on with our valued developer community.

It’s a document for building shared understanding of a topic. It expresses a technical solution, but can also communicate how it should be built or even document standards. The most important aspect of an RFC is that a written specification facilitates feedback and drives consensus. It is not a tool for approving or committing to ideas, but more so a collaborative practice to shape an idea and to find serious flaws early.

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’re planning to launch a series of content customization updates, with the goal of giving teams more ways to personalize and bring their workspaces to life.

In January, we’ll be bringing a portion of this functionality to a small group of customers and marketplace partners via an Early Access Program (EAP). Based on that feedback, we would be aiming to set a wider beta release and GA target date.

This update does not impact the API responses on any of our existing APIs, such as the theming API.

RFC Dates:

  • Publish: December 5th
  • Discuss: January 5th
  • Resolve : January 18th

Problem/Opportunity

Customers have consistently highlighted a desire for Confluence to offer more robust content customization options.

To meet these needs, we’re planning to build the following:

  • Header and Title Refresh: All users will get a modernized title and header experience for pages (all users)
  • A Confluence Front Cover: Admins will get a new, home-like surface to curate the most authoritative content for their entire company (premium+ only)
  • Premium Macros:
    • Users will get new, powerful premium macros to build that surface, like Cards (premium+ only)
    • These can be used in other places where content is created, such as pages and space overviews

We’ll go into more detail on each of these below.

We’re starting with the minimum scope possible for our EAP, and expect customer feedback and appetite to guide the next set of investments from there. Please note naming, scope, and packaging are not finalized and may change.

Proposed Solution

In this post, we will provide important details about this upcoming change and what you need to know as an ecosystem developer. Please note these are preliminary mocks versus finalized specs, and are subject to evolve.

Header and Title Refresh: Pages will shift to support a full-width title and header

Header and title
Header and title1520×614 172 KB

  • The title component will have more customization options, including center alignment and overlay
  • The header component will expand to become full-width
  • An emoji or logo added to a title can be added to a title, and optionally sit above the title text

Note: this change will be released to all Confluence users, irrespective of edition type.

A Confluence Front Cover: a new home-like surface and associated setup experience

Hub
Hub890×1082 55.6 KB

  • The entry point to create this surface will be available to admins only, within admin settings
  • The surface will function most similarly to a page, in that users can add additional macros, text, etc. including those developed by third-party developers
  • This surface is not like a space, or a space overview page in that it has no child or parent objects
  • This surface, once published, will be accessible via a navigation item in the top left of the instance
  • There is only one surface per instance

In the setup wizard of this surface, admins will be prompted to upload a favicon (mandatory), select a name for the surface (mandatory), and select a color scheme that will propagate into the navigation menu (optional).

Note: this feature will only be available for premium editions and up.

Premium Macros: Creation of new content transformers, such as Cards

macros
macros532×828 175 KB

Premium macros will be the building blocks that make up the new surface but are extensible to other creation areas such as space overviews and pages.

  • Premium macros will be available to users via the slash command on a page, or the + button in the editor
  • Premium macros to start will include Cards, with the next set of premium macros being prioritized

Note: this feature will only be available for premium editions and up.

When will this change take place?

A subset of these changes – specifically the new header and title, and cards macro – will be seen first by a cohort of pre-selected EAP customers starting in January. All marketplace developers are welcome to join the EAP.

Currently, we are targeting March / April for an open beta and May / June for GA. These are highly tentative, and will be refined over the coming months.

Actions

How might this affect you?.

While we are not changing any REST APIs such as the theming API in conjunction with our changes, we would like to hear from developers about ways these changes may impact your apps that we’re not anticipating.

How can you help?

  • Extensibility Ideation:

    • We need to hear from you! We’d love your feedback on specific areas of this experience where you’d like extensibility to exist.
      • What extension points do you imagine needing/wanting to use for your existing apps?
      • What kinds of new apps might you want to build? How could we support that use case better?
      • What should we keep in mind when imagining extensibility for this feature?

  • Participate in the EAP:

    • Ensure that you’re signed up with the Developer Canary Program. This ensures that you have first access to changes.
    • We will update this post with additional details once the changes are ready and available. While dates are being finalized, we anticipate that to be around mid to late January.
2 Likes
2

Could you please clarify whether Forge macros will work as intended? Can we consider this home-like surface as a somewhat regular page?

Many vendors, including us, already offer header/title macros similar to what you’re proposing, albeit with a broader range of features. Our customers currently utilize our tools to create custom headers for their pages. Your new header provides advantages that we, as a vendor, cannot offer due to the lack of APIs, such as a truly full-width experience with no additional space on any side – a feature our customers have desired for a long time. This puts our existing customers in a dilemma between adopting your new page title with fewer customization options or sticking with our macros and sacrificing the ability to go truly full-width.

Is there a possibility of obtaining an API or providing the page editor with the option to replace the header with another third-party macro, allowing us to offer the best of both worlds?

Thank you!
Philip

11 Likes
3

Hi,

we have some questions in regards to how this would affect some of our apps:

Confluence Front Cover

I would also be interested if this surface can be treated similar to a “normal” page/blogpost since, at least from the current mockup shared, it looks very similar to a page for the user. More specifically:

  • Will this surface be accessible via any of the content (page/blogpost) REST APIs, so could we for example read/write:
  • Will the usual page extension points apply to it? I’m mostly thinking about Content Actions for Forge or the system.content.action/secondary web item for Connect apps

Premium macros

  • Will these new macros also offer support for view formats (view and export_view) when converted to HTML via the REST API? In the recent past other new features in the editor like this have often not supported this which is terrible for most apps that publish content from Confluence to other formats.

Thanks,
Thomas

10 Likes
4

The description of the new Confluence Front Cover mentions that it can include third-party macros or text, but that it’s not like a space or space overview page, and also that it has no parent or child objects. Finally, it mentions that no REST APIs will be changed.

  1. From an app point of view, how is this Front Cover represented? Apps are accustomed to working with spaces and pages. If, for example, a dynamic macro includes parameters in its URL such as “&spaceid={space.id}&pageid={page.id}”, how will the new Front Cover be represented, given that the APIs are not being changed?
  2. Can images be added to the Front Cover? If so, are these going to be represented as attachments? In that case, would that mean that the Front Cover actually does have child objects?
  3. How can apps expect the Front Cover to be represented when calling AP.context.getContext() and AP.navigator.getLocation()?
5 Likes
5

This mockup is pretty, but confusing:

image
image1380×556 61.2 KB

I’m assuming that either:

  1. you will be able to layer multiple backgrounds with the confluence UI being placed within an outer container centralised in a padded manner
  2. the browser chrome has been missed from this mockup and the choice of desktop image is unfortunate.
4 Likes
6

A question regarding the Premium Macros you will be providing to Premium+ users… How did you decide what Macros to invest in and what was the overall goal with providing it? For example, you’ve created a cards macro, which a few vendors already provide, including ourselves, what was the rationale behind creating a “native” cards macro? Also, is it possible to get a list of candidates of other macros you’ll be considering?

9 Likes
7

Hi @Alli_S , thanks for bringing this set of features to the community.

I have to voice my disappointment with the way that Atlassian has chosen to approach this initiative. Theming and content formatting are markets that are very well established and supported in the marketplace. This initiative steps into both and arguably overlaps with existing functionality of a number of the top selling cloud apps. Put another way, by not working with marketplace partners in order to explore options on how to grow these markets, and by adding functionality that a number of apps already have, partner sales will likely be impacted and Atlassian’s cut of those sales will also be. It feels like a no-win situation from this side of the fence.

Regarding extensibility ideation, this also is a very well established area. You only need to look at the dev community or the Connect/Forge Jira backlogs for ideas on this. Vendors have been asking for years for improvements/greater extensibility in both theming and macros on Connect, Forge and on the Fabric Editor of which very few have been invested in. A good example of this is @SvenSchatter 's 3 year old post that has a lot of contribution and a lot of silence from Atlassian’s side.

This line also makes it very difficult to have a business with apps that have formatting macros. Please could you provide a full roadmap with details of which features you will be sherlocking, so that we can plan accordingly?

Overall, I/and our teams would be very happy to work with Atlassian on extensibility for these features but we really need better clarity on the state of these markets and how we can build our mutual businesses.

8 Likes
8

Thanks David, good point. It’s #2. There is no outer layer UI planned. We’ll circle back with an edit to make that more clear.

1 Like
9

I am fully supportive of this. What is particularly concerning is that most vendors with formatting apps have built complex workarounds for simple problems, as Atlassian has not delivered many APIs that one would consider basic. There is a significant backlog of feature requests from our customers that we cannot address due to the lack of better APIs or workarounds. What worries me about this is not that Atlassian is now building the 100th card app, but that they can simply deliver features that we as vendors are unable to build. Not only is this frustrating for us as vendors, but our customers will also be confused about why our apps offer a broader range of features compared to Atlassian’s macros but cannot provide the same basic WYSIWYG features. This makes formatting apps feel like they are of lower quality, and unfortunately, we cannot do anything about this. It creates a confusing landscape for customers and proves frustrating for vendors.

While I don’t hold hope that Atlassian will refrain from releasing these macros, my request is for Atlassian to not implement many more formatting macros after this. Instead, the focus should be on developing new and better APIs for theming, improving the WYSIWYG experience, and refining formatting APIs in general. This would allow customers to avoid compromising between the experience that Atlassian offers and the broader options that third-party apps provide.

8 Likes
11

I would greatly appreciate receiving feedback from @Alli_S regarding ALL the comments.

2 Likes
12

Thanks, Scott, for these questions.

  1. The Front Cover is stored as a page, so there will be page id, space id, and space key associated with it. The space in that instance is a new entity called a system space, which you can think of as an invisible container for the Front Cover versus a space how you might traditionally think of one. It won’t show up in search, or spaces tab, for example.

  2. Since the Front Cover is effectively a page, yes, images can be added to it as they are to a page today. It’s using the same editor.

  3. Will circle back on this one.

3 Likes
13

Hi Phillip, thanks for these questions!

Yes, Forge apps will work on the Front Cover as they currently do on regular pages.

We’re considering an API that would allow vendors to replace the header so customers still have a deeper set of customization options. Do you have an example in mind, where you think this would be especially beneficial for customers? This would be a helpful input for us in thinking deeper on prioritization.

1 Like
14

Thank you for these questions!

The native content customization options have been introduced based on valuable feedback from our customers. As one example, we have heard this request from customers who are considering migrating to the cloud but have grown accustomed to the Home entity and CSS customization available in server/DC environments.

Additionally, while marketplace developers will continue to offer a ton more advanced content customization options, we do have many very large enterprise customers who are not able to use marketplace developers due to internal processes or compliance restrictions.

We haven’t explored macros beyond the two mentioned here, yet. We would expect to learn more from customers in the EAP and to be forthcoming with this group on our plans, for our mutual benefit.

15

To be honest, this really sounds like the perfect reason for Atlassian to invest in extensibility through Forge.

The whole premise of Forge was to unlock in-house development of features. Just like very large enterprise customers now rely on JS/CSS customisations in their on-premise instances, they should be able to leverage Forge to bring those customisations to Cloud.

So the argument that very large enterprise customers are not able to install Marketplace apps is not applicable, because with Forge, they could make those apps themselves, similar to they way they are currently customising their on-premise instance.

Instead of making their own implementations of these features, incl. the limitation that there is not a one-size fits all solution, Atlassian should focus on extensibility of their platform to support Cloud migration. Not in the least to make sure that the product is not altered based on the desire of the happy few very large enterprise customers that apparently are so important to Atlassian that they get to determine the roadmap and dictate the solution.

In early days, Atlassian made the smart move to focus on the 80% and enable Marketplace Partners and in-house developers to create solutions for the remaining 20%. It increasingly seems that it has lost her way, and is bound to loose Marketplace revenue as a result.

5 Likes
16

I had the exact same thought. The major blocker for all formatting apps is certainly the missing custom ui configuration..
With this blocker out of the way, we could migrate both of our formatting solutions (7000+ installs in total) to forge easily, removing ALL of the concerns mentioned by @Alli_S .
Before this arguably simple ticket isn’t solved, none of the affected vendors will even consider migrating to forge, no matter how much you invest in a better database, a cache, or forge remotes. I feel like it’s a no-brainer to just give us this simple feature and just get forge macros to at least the same capabilities as connect macros. If I remember correctly, macros are the most used integration type for Confluence, but it feels like they are completely left out from any improvements when it comes to forge.
To me, it feels like the fact that we’ve not been given custom ui macro configuration for forge is purely a politic choice, rather than a technical one.

3 Likes
17

Atlassian has announced the Cards and Carousel macros for Confluence Cloud. More content macros are said to be delivered. We have some macros for the content organization in Handy Macros for Confluence, so this news can affect our app. Can we get any idea about the future content macro development being considered? The post announces new macros only for Premium users and up. Are there any plans to deliver Cards and Carousel to standard users as well?

18

Thanks for chiming in and sharing your thoughts here. We hear you on the concerns with the theming API, and are considering improvements to that API.

At this point, the teams don’t have concrete timelines to share but if you’re interested in speaking with the team about specific theming needs, you can schedule some time with the team here.

19

Hi Anastasia, right now these are scoped only to premium+ editions. We haven’t explored macros beyond the two mentioned here, yet. We would expect to learn more from customers in the EAP and to be forthcoming with this group on our plans, for our mutual benefit.

1 Like
20

Hey @Alli_S
can you clarify when an EAP will be available and how to participate?

Thank you
Philip

1 Like
21

Regardless of any of the comments on this RFC, this is another RFC that makes a mockery of the process. Before the RFC Resolve date the EAP rolls out https://developer.atlassian.com/cloud/confluence/changelog/#CHANGE-1388

When using RFCs as a release announcement, please be honest enough to say so.

11 Likes