How to deploy from Bitbucket to Confluence (user macro) via Bamboo?

Question

Good evening,

maybe somebody of you has dealt with a scenario like mine before or can provide hints. I have some experience in using the Atlassian tools including the creation of user macros on this side of Chrome. What I don't know and / or understand properly is what happens under the hood and therefore in what form those macros persist.

In my case a repository (Bucket) has code of Confluence user macros. The challenge is to have them deployed when master is updated, so that they replace previously existing code in the user macro section.

Thank you in advance for any hint where to point my admin :)

Ben

voisard · Answer

Hi Rafael,

thank you very much for your detailed answer :)  Very kind of you, really! I appreciate the help you've given, though I don't know how to do it myself, I will look into it with our operations guy to get it working.

Thanks again,
Ben

Rafael Pinto Sperafico · Answer

Hi @voisard ,

I am sorry for the delay on getting back to you and thank you very much for taking the time to explain - in details - what you are trying to achieve.

I understand what you are trying to do and, unfortunately, there is no solution available out-of-the-box provided by Atlassian. You could perhaps make use of 3rd party plugins, e.g BobSwift or ScriptRunner and work on a script to automate the step 3 in your description.

It seems there is no REST API available to list User Macros in Confluence.

When creating a User Macro

* consume Confluence's action

When updating existent User Macro

* gather this information from Confluence's database
* web scrape /admin/usermacros.action parsing the HTML response and build the list of user macros
* if you know the name of user macro, update it consuming Confluence's action

The payload for a user macro is:

showInMacroBrowser: true

userMacro.name: macro-name

userMacro.title: Macro Title

userMacro.description: Macro Description

userMacro.categories: admin
userMacro.categories: communication

userMacro.iconLocation: http://mysite.com/myimage.png

userMacro.documentationUrl: http://mysite.com/documentation.html

userMacro.bodyType: none

userMacro.template: ## Macro title: My Macro...

Since the payload will be used as a web from, the payload provided must be encoded. As a result, the payload above would look like:

showInMacroBrowser=true&userMacro.name=macro-name&userMacro.title
=Macro+Title&userMacro.description=Macro+Description&userMacro.ca
tegories=admin&userMacro.categories=communication&userMacro.iconL
ocation=http%3A%2F%2Fmysite.com%2Fmyimage.png&userMacro.documenta
tionUrl=http%3A%2F%2Fmysite.com%2Fdocumentation.html&userMacro.bo
dyType=none&userMacro.template=%23%23+Macro+title%3A+My+Macro%0D%
0A%23%23+Macro+has+a+body%3A+Y+or+N%0D%0A%23%23+Body+processing%3
A+Selected+body+processing+option%0D%0A%23%23+Output%3A+Selected+
output+option%0D%0A%23%23%0D%0A%23%23+Developed+by%3A+My+Name%0D%
0A%23%23+Date+created%3A+dd%2Fmm%2Fyyyy%0D%0A%23%23+Installed+by%
3A+My+Name%0D%0A%0D%0A%23%23+This+is+an+example+macro%0D%0A%23%23
+%40param+Name%3Atitle%3DName%7Ctype%3Dstring%7Crequired%3Dtrue%7
Cdesc%3DYour+name%0D%0A%23%23+%40param+Colour%3Atitle%3DFavourite
+Colour%7Ctype%3Denum%7CenumValues%3Dred%2Cgreen%2Cblue%7Cdefault
%3Dred%7Cdesc%3DChoose+your+favourite+colour%0D%0A%0D%0AHello%2C+
%3Cfont+color%3D%22%24paramColour%22%3E%24paramName%3C%2Ffont%3E%
21&confirm=Save

In order to make it more readable, I have added a breakline in character 66 (but payload should be passed as a single-line). Btw, the payload above is the default Macro example that Confluence gives when creating a User Macro.

# Create a user macro

curl -k -u admin:admin \
-H 'X-Atlassian-Token: no-check' \
-H 'Upgrade-Insecure-Requests: 1' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Accept: text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8' \
-H 'Accept-Encoding: gzip, deflate' \
-H 'Accept-Language: en-GB,en-US;q=0.9,en;q=0.8' \
-H 'Cookie: JSESSIONID=6A2003686FC2B62384DBDD485F4F662A; mywork.tab.tasks=false' \
--data 'userMacro.name=macro-name&showInMacroBrowser=true&userMacro.title=Macro+Title&userMacro.description=Macro+Description&userMacro.categories=admin&userMacro.categories=communication&userMacro.iconLocation=http%3A%2F%2Fmysite.com%2Fmyimage.png&userMacro.documentationUrl=http%3A%2F%2Fmysite.com%2Fdocumentation.html&userMacro.bodyType=none&userMacro.template=%23%23+Macro+title%3A+My+Macro%0D%0A%23%23+Macro+has+a+body%3A+Y+or+N%0D%0A%23%23+Body+processing%3A+Selected+body+processing+option%0D%0A%23%23+Output%3A+Selected+output+option%0D%0A%23%23%0D%0A%23%23+Developed+by%3A+My+Name%0D%0A%23%23+Date+created%3A+dd%2Fmm%2Fyyyy%0D%0A%23%23+Installed+by%3A+My+Name%0D%0A%0D%0A%23%23+This+is+an+example+macro%0D%0A%23%23+%40param+Name%3Atitle%3DName%7Ctype%3Dstring%7Crequired%3Dtrue%7Cdesc%3DYour+name%0D%0A%23%23+%40param+Colour%3Atitle%3DFavourite+Colour%7Ctype%3Denum%7CenumValues%3Dred%2Cgreen%2Cblue%7Cdefault%3Dred%7Cdesc%3DChoose+your+favourite+colour%0D%0A%0D%0AHello%2C+%3Cfont+color%3D%22%24paramColour%22%3E%24paramName%3C%2Ffont%3E%21&confirm=Save' --compressed \
-X POST 'http://localhost:8090/confluence/admin/addusermacro.action'

There are a few things to consider in the example above:

* admin:admin is the username:password given to authenticate as a Confluence administrator (required to create User Macros as specified in Writing User Macros documentation)
* Cookie: JSESSIONID=6A2003686FC2B62384DBDD485F4F662A; you must consume another Confluence REST API endpoint to get a valid JSESSIONID and replace it in the example given.
* --data provided is just an example. In relation to properties in payload, you can refer to its definition in Writing User Macros documentation.
* http://localhost:8090/confluence is the Confluence Base URL given in this example, yours may be different

When updating a User Macro, the same example as above can be used. However, the URL to be consumed is:

-X POST 'http://localhost:8090/confluence/admin/updateusermacro.action'

Hope the information provided help you with your automation. When I have another solution to this inquire, I will be commenting on this thread.

If you find the information given relevant to your inquire, I would appreciate if you could mark accept it as positive answer.

Kind regards,

Rafael

voisard · Answer

Hi @Rafael Pinto Sperafico , it took me a while to answer your question, sorry for that. One example for a user macro that I have written follows: ## Macro title: KxDivWrapper ## Macro has a body: Y ## Body processing: Selected body processing option ## Output: Selected output option ## ## Developed by: Benjamin Wasner ## Date created: 18/11/2016 ## Installed by: Benjamin Wasner ## This is an example macro ## @param class:title=CSS Class|type=string|required=true|desc=Specifiy the classes to encapsulate Macro body

$!body

This is a real plain and basic user macro that doesn't do anything other than wrapping its content into a div which class can be specified in the parameters. I have "written" or "assembled" some more advanced stuff. Since we are already using these concepts and tools to shape our Confluence (250 users), it is my goal to professionalize the macros with the help of our developers, because I am the Agile Coach that doesn't know how to code :) What would help me be more convincing is a way to do the following: 1. Keep user macro code in a repository 2. Let Bamboo be triggered by a merge into production 3. Bamboo replaces the current user macro in Confluence by the current repo version 1 and 2 are no problem after all, the last step is where I need your help. How to make code be replaced? Sorry if this question may look stupid, but I tried very hard to phrase it understandably... Thank you in advance!