Create
cancel
Showing results for 
Search instead for 
Did you mean: 
Sign up Log in
Deleted user
0 / 0 points
Next:
badges earned

Your Points Tracker
Challenges
Leaderboard
  • Global
  • Feed

Badge for your thoughts?

You're enrolled in our new beta rewards program. Join our group to get the inside scoop and share your feedback.

Join group
Recognition
Give the gift of kudos
You have 0 kudos available to give
Who do you want to recognize?
Why do you want to recognize them?
Kudos
Great job appreciating your peers!
Check back soon to give more kudos.

Past Kudos Given
No kudos given
You haven't given any kudos yet. Share the love above and you'll see it here.

It's not the same without you

Join the community to find out what other Atlassian users are discussing, debating and creating.

Atlassian Community Hero Image Collage

How to create simple custom macros in Confluence Cloud

Back in 2014, I made a presentation at Atlassian Summit that I hoped would challenge people's assumptions that Confluence Cloud was limited and inflexible as a solution. In it, I talk about core Confluence features (templates, macros, permissions, and space architecture) and also the possibilities of Atlassian Connect.

Some details and features have changed since then, but for the most part, the concepts in the presentation are still valid. In particular, you can still use the Atlassian Connect framework to make simple custom macros, and you don't need to be a professional programmer either.

I thought it might be worthwhile re-sharing this again.

But I'm not a developer or programmer, how could I use Atlassian Connect?

For a simple, static content macro that doesn't have any logic or configuration required (i.e. reusable blocks of content) you only need these three things:

  1. Admin access to your Confluence Cloud instance
  2. Access to web hosting that supports HTTPS - e.g. Amazon S3 hosting is good enough https://aws.amazon.com/s3/
  3. Your custom macro code, made up of three files:
    • A special configuration file ("atlassian-connect.json")
    • A file that contains your content (e.g. "macro.xml" in the example below)
    • An image or icon to represent your macro (e.g. "icon.png" in the example below)

Those 3 files are uploaded to your hosting then installed into your Confluence Cloud instance.

The file that contains your content will be a snippet of HTML / Storage Format text. An easy way to create your content snippet is to draft it on a Confluence page, then use the view storage format tool. E.g. this content 

example-storage-format.pnglooks like this in Confluence's storage format:

<p>Hello, world!</p><ac:structured-macro ac:name="info" ac:schema-version="1" ac:macro-id="b1298625-64bf-42e8-b3bc-e3489526e9bc"><ac:rich-text-body>
<p>This is an info panel</p></ac:rich-text-body></ac:structured-macro>

An atlassian-connect.json template

You don't need to really know much about the atlassian-connect.json file, although there are lots of different configuration options if you want to learn more about it.

Here is a template you can use – I have added comments where you need to make changes to this base configuration. Once you have made you changes, you can check that your atlassian-connect.json is right using this online validation tool created by Atlassian, which is hosted at https://atlassian-connect-validator.herokuapp.com/validate

If you want to make this a block rather than inline macro, change the outputType parameter to "block".

{
"key": "A unique key for your – e.g. com-yourdomain-anameforyourmacro",
"name": "A human friendly name for your of macro",
"description": "Describe your macro – e.g. Demo add-on for the Atlassian Summit 2014.",
"baseUrl": "This is the URL where you macro code is hosted - e.g. https://mymacros3domain.s3.amazonaws.com/",
"vendor": {
"name": "Your organisation’s name",
"url": "Your organisation’s URL e.g. http://yourdomain.com"
},
"authentication": {
"type": "none"
},
"modules": {
"staticContentMacros": [
{
"url": "/macro.xml",
"outputType": "inline",
"icon": {
"width": 80,
"height": 80,
"url": "/icon.png"
},
"key": "A unique key for your macro – e.g. static-macro-homepage",
"name": {
"value": "The name of your macro"
}
}
]
}
}

How do I install and test my macro?

Initially, you can install directly by using development mode in Confluence Cloud.

However, you can then deploy as a private app via the marketplace.

You can also request a free development instance of Confluence Cloud, so you can test separately before making it available to your users.

5 comments

Useful, thank you

Like James Dellow likes this
James Dellow Community Leader Mar 02, 2021

PS since I wrote this article, Atlassian has released a new cloud development platform, called Forge:

https://developer.atlassian.com/platform/forge/

The biggest hurdle for non-developers or power users will be installing the Forge CLI (command line interface) and using it to install your add-on. But if you can master that, you'll be able to build simple macros there instead.

Like # people like this

@James Dellow I love the direction that Atlassian is taking with regards to making it easier to build apps, macros, etc.

However, I thought that the following was a little bit disappointing:

"Forge apps can't be viewed by anonymous users. To use a Forge app, you must be logged in to Confluence."

(Build a Confluence hello world app (atlassian.com))

hope that that is a temporary situation while Forge is developed, otherwise I'll have to write my custom macro with Connect and then end up with multiple development platforms still.

Like James Dellow likes this

It is also worth reading Forge pricing update: free through 2023 - Forge / Forge Announcements - The Atlassian Developer Community

I sincerely hope that Forge remains free. I appreciate that there is infrastructure behind the scenes that Atlassian is paying for in order for Forge to work but I would be very disappointed if Atlassian is taking a stance of encouraging developers to move over to Forge and then suddenly starts charging for it.

Like James Dellow likes this
James Dellow Community Leader Mar 05, 2021

@Philip Colmer I don't have any inside information, but as it is built on top of Amazon Web Service's Lambda function, any pricing would have to be relative to that cost? You would have to think it would then be hard to justify this for private apps with low (relative) usage. A more likely scenario might be they fine-tune their usage limits. But if you are a marketplace vendor with a popular and resource-intensive app, that would be something different.

BTW you can track support for anonymous users here https://ecosystem.atlassian.net/browse/FRGE-189 (although doesn't look like much is happening on that front).

Comment

Log in or Sign up to comment
TAGS
Community showcase
Published in Confluence Cloud

Confluence Bingo Round 3!

That’s right! Grandma’s back at it again, and this time she’s brought all her friends. In honor of Team '21, this Bingo round is dedicated to all things team-related, and the prizes are no exception....

2,996 views 31 22
Read article

Community Events

Connect with like-minded Atlassian users at free events near you!

Find an event

Connect with like-minded Atlassian users at free events near you!

Unfortunately there are no Community Events near you at the moment.

Host an event

You're one step closer to meeting fellow Atlassian users at your local event. Learn more about Community Events

Events near you