Last updated Oct 5, 2024

Confluence Connect patterns

Confluence Connect patterns are common ways for you to extend the functionality of Confluence Cloud. They group together related extension points and design guidelines to help you provide a consistent experience for users.

Typically your app will be based on one of these patterns, but it may use elements from multiple patterns depending on your target use-case and the design guidelines.

You can access the design guidelines and technical references for Confluence Connect and REST APIs without using the pattern descriptions, but the descriptions provide more context and link to related design and technical references.

Macros

Macros provide custom content inside Confluence pages and blog posts. The content can be sourced from an external service (an integration), custom generated by your app (a diagram macro, for example), or it can render other Confluence content (generate a chart based on data in a table within the macro itself).

Page extensions

Page extensions can display page metadata, related content, add page actions, and more. They're for when you want to show users information from your app in the page byline, or allow them to take actions via the ellipsis (More Actions) menu.

Search extensions

A search extension assigns custom properties to Confluence content and enables search filtering using those properties.

Blueprints

A blueprint is a single or multiple page template accessible via the Create dialog. Create your blueprint with placeholder text and a pre-defined layout to help users take shortcuts in creating content. Your app can also automatically create an index page, like the built-in Meeting Notes template, which lists all pages created using your blueprint in a space.

Custom content

Is there a new content type you'd like to add to Confluence to go along with the standard content types, like pages, blog posts, and comments? Create your own content type, style it, and decide where users should see it and how they interact with it. A good example is Confluence Questions. The Question content type can exist globally or within a space, and allows users to answer, comment, vote, and more.

Theming

Change the way users see and experience Confluence, by developing a theme app. Themes change the look and feel of the user interface, from the Confluence header, to spaces, pages, and blog posts.

Confluence Connect design principles

Our patterns are based on a set of design principles aligned with our vision for Confluence. While some extension zones give developers freedom to provide any user experience, the best user experience is a consistent one across the product and apps. With that in mind, please take into consideration both the high level principles listed here and the specific design guidance provided in the documentation of each pattern.

Enrich the experience

Consider the user's workflow. Understand what they're trying to achieve, and give them what they need to help them get there. Anything added to the parent product needs to be contextually relevant and allow users to focus on their work. Don't add random features, and don't embed whole products for the sake of it. Know when to leave the context of the parent product for complex tasks.

Provide meaningful actions

People need to be able to respond and make decisions no matter what product or platform they are working on. Make it easy for them by letting them take meaningful actions from the context of the parent product. Let them assign a Jira ticket from a Hipchat conversation, follow up a conversation from a Confluence page, or start a screen recording from a Service Desk ticket.

Be harmonious

Design apps to be harmonious with the Atlassian product suite and ecosystem. Users are more comfortable and engaged when they recognize interactions that are familiar and when they know how things work. Consider asking others outside your team where, when reading a Confluence page, they would expect or want a particular action to reside? Take note of where similar patterns sit within the products, and use the Atlassian design guidelines to create seamless and professional integrations. When in doubt, be consistent.

Where to from here?

Rate this page: