Automating the creation of a Confluence page linked to a Jira ticket

One of the questions I've seen frequently is how can you use native Jira automation to create a Confluence page and link it to a Jira ticket. It's something that I was struggling with myself; we had a requirement from a new team to automatically create a new Confluence page for every story that is created.

I spent some time with ScriptRunner, but eventually found a native way to do it. It's not the prettiest, and there's a lot you could do to extend this as far as content of the page, but this will give you the basic action of creating a page and linking it to a newly-created ticket.

  1. Go to Project Settings -> Automation and create a new rule.
  2. Choose your trigger. In my example, I'm using the Issue Created trigger, but this should work with any of the available Jira triggers.
    automationStep1.png


  3. Add any conditions you'd like to have; in this case I'm having the rule run only when tasks are created.
    automationStep2.png
  4. Add your action, which will be Send Web Request.
    automationStep3b.png

Here's where the fun starts. You'll need to enter the following information:

  1. REST API call to create a page; it will be https://<your-instance-url>/wiki/rest/api/content

  2. A Basic Authorization header. Detailed instructions for creating this are here. The quick format is to base-64 encode a string composed of "useremail:usertoken".

  3. The HTTP method; it will be POST for creation.

  4. The webhook body. Because we're going to want to create a link, we're going to choose Custom Data.
    automationStep3.png

Now you'll need to get some information from Confluence. Create a new page using the old editor (this is important*) and insert a Jira macro that displays a single ticket (or find an existing page that has one.)

In Read mode, click the three dots menu, then go to Advanced Details -> View Storage Format.
automation6.png

You'll see a page that looks like this:
automationMacro.png

Copy the text into a text editor. You're going to have to do some formatting to make it work with the webhook, and it's easier to do your editing in a full screen app than the small text box on the automation rule screen.

You'll need to add escape slashes to all the quoted values, add newline characters after each line break, and replace the "key" parameter with the smart value your automation rule has in context. If you're using the Issue Create trigger, this would be {{issue.key}}.

You'll then copy all of it into the storage value element of the json block that will be your webhook body. The entire chunk goes inside double quotes (which is why you need to escape all the existing quotes in the macro code.) Mine looks like this.

{
"type":"page",
"title":"{{issue.key}} {{issue.summary}}",
"space":{"key":"MPS2U"},
"body":{
"storage":{
"value":"<ac:structured-macro ac:name=\"jira\" ac:schema-version=\"1\" ac:macro-id=\"71c4c2a3-db0b-499f-816d-64395f485435\">\n <ac:parameter ac:name=\"server\">System JIRA</ac:parameter>\n <ac:parameter ac:name=\"columns\">key,summary,type,created,updated,due,assignee,reporter,priority,status,resolution</ac:parameter>\n <ac:parameter ac:name=\"serverId\">c5a16fc3-0742-303f-b02a-822c531694b6</ac:parameter>\n <ac:parameter ac:name=\"key\">{{issue.key}}</ac:parameter>\n </ac:structured-macro>",
"representation": "storage"}
}
}

 

You can also add more page content, set page parent, etc. by adding key/value pairs to the json; documentation is in the API reference.

If you want to check whether your setup will work without actually generating pages, you can use the Validate module at the bottom of the setup screen. Just enter a valid ticket number, and the code will run and return a response with expandable entries for response code, payload, etc. This can be helpful in debugging.

automationValidation.png

And that's it! It's a lot of steps, but once you've done it once, you can just copy the rule and change parts as necessary for different projects and requirements.

*The Jira macro that's generated by a page created with the new editor will not display the necessary details when using View Storage Format. If you create a page via automation using the old editor, the link will remain if you later convert the page to the new editor.

31 comments

Kishan Sharma
Community Leader
Community Leader
Community Leaders are connectors, ambassadors, and mentors. On the online community, they serve as thought leaders, product experts, and moderators.
July 27, 2021

Great article @Esther Strom i'll try this!

Erik Buchholz
Rising Star
Rising Star
Rising Stars are recognized for providing high-quality answers to other users. Rising Stars receive a certificate of achievement and are on the path to becoming Community Leaders.
July 27, 2021

Hi @Esther Strom ,

is there no possibility to use application links? I've done some other connections between Confluence and Jira with ConfiForms and connections from Jira to Confluence with Scriptrunner using the existing application links.

This seems more comfortable and much more secure than using basic authentication.

An additional advantage is, that the current user creates the Confluence page instead of you.

Regards

Like Alex Lock likes this
AW July 27, 2021

The issue with this solution is that anyone who can view your automation configuration now has access to your API token and can do whatever the REST API can do, with your credentials.

Like # people like this
Esther Strom
Community Leader
Community Leader
Community Leaders are connectors, ambassadors, and mentors. On the online community, they serve as thought leaders, product experts, and moderators.
July 29, 2021

@Erik Buchholz I'm sure that's possible. This was intended as the most basic setup instructions.

Esther Strom
Community Leader
Community Leader
Community Leaders are connectors, ambassadors, and mentors. On the online community, they serve as thought leaders, product experts, and moderators.
July 29, 2021

@AW yes, I'm aware, which is why we have an automation bot account with limited permissions that we use, rather than a Jira admin's credentials. Our system is also set up to have very strict controls at the project level, so very few people have project admin access and therefore access to view automation rules. 

Like # people like this
Armand Luziau_Elements_
Marketplace Partner
Marketplace Partners provide apps and integrations available on the Atlassian Marketplace that extend the power of Atlassian products.
August 16, 2021

Hi @Esther Strom ,


I'm with Elements, and we just released a new app Elements Publish to Confluence that might meet this kind of issues. The app allows the users to create pages from Jira with issue data.

2021-08-12 14_14_02-Start creating Confluence pages from Jira - Elements Apps.png
Check out this article that explains how to create Confluence pages linked to Jira issues with the app.

Let me know if you have any questions!

Armand :)

Ido Sellinger October 20, 2021

Hi, I tried doing this and it seems like when I go to 'View Storage Format' it shows me only partial data compared to what you are getting here. I have tried to insert it in Jira the same way you did and it didn't work, raising a 'Bad Request' error.

Do you have any ideas about what am I missing or doing wrong? 

Thanks.

Esther Strom
Community Leader
Community Leader
Community Leaders are connectors, ambassadors, and mentors. On the online community, they serve as thought leaders, product experts, and moderators.
October 20, 2021

Hi, @Ido Sellinger can you clarify what you mean by "partial data"? 

abby.kaske May 16, 2022

@Esther Strom would something like this work if we wanted to create a confluence page for a list of Jira tickets, or does this only work for a 1 jira ticket to 1 confluence page ratio?

Context: We currently use the webhook automation to update a list of tickets all at once. When we update those tickets, we add a date stamp on them so we can then create a Confluence page documenting which tickets were updated (the confluence page displays all tickets with a specific date on them.)

Esther Strom
Community Leader
Community Leader
Community Leaders are connectors, ambassadors, and mentors. On the online community, they serve as thought leaders, product experts, and moderators.
May 19, 2022

@abby.kaske It might work with a list of jira tickets, if you have a page already that uses the Jira macro and displays multiple results in a table. If you know the issue keys (or have some other JQL that will find the specific tickets) you could try setting the json "value" property to something like this (yanked from one of my Confluence pages that has a table of Jira tickets via the /jira macro.)

 

<ac:structured-macro ac:name="jira" ac:schema-version="1" data-layout="full-width" ac:local-id="<your local Id>" ac:macro-id="<your macro id>">
<ac:parameter ac:name="server">System JIRA</ac:parameter>
<ac:parameter ac:name="columns">key,summary,type,status</ac:parameter>
<ac:parameter ac:name="maximumIssues">20</ac:parameter>
<ac:parameter ac:name="jqlQuery">project = jira and issuetype = &quot;New User Access&quot; and status not in (Closed, Done) </ac:parameter>
<ac:parameter ac:name="serverId">your server id</ac:parameter>
</ac:structured-macro>

If you know the keys of all your tickets, you should replace the jqlQuery value with something like "issuekey in (jira-1, jira-2, jira-3)".

Alexis Evans August 18, 2022

@Esther Strom Is this using Server or Cloud? It looks like it could accomplish at least part of what I want to do.

Also, was there a specific reason you decided to use the automation rule rather than ScriptRunner? Was it just that it was easier? Did you have any ideas about how to make it work with ScriptRunner?

Thanks!

mhoyosga August 26, 2022

Hello.
I want to create an automation rule that sends a request from Jira to Confluence, to create pages with data from a Jira issue.
But when I try to connect to read or create data in Confluence, Jira won't let me connect:
{
"message": "Current user not permitted to use Confluence",
"statusCode": 403
}
Or Basic Authentication is not allowed.
How can I make this connection in Jira?
Thank you

Like Yana likes this
E Hanumanthu September 9, 2022

Hi @Esther Strom 

 

Will the same configuration works in Data center as well? Please let me know.

Yatish Madhav
Rising Star
Rising Star
Rising Stars are recognized for providing high-quality answers to other users. Rising Stars receive a certificate of achievement and are on the path to becoming Community Leaders.
October 5, 2022

@Esther Strom  you are a star! Thank you for this! This opens up so much of possibility ...

Like Esther Strom likes this
Sakina
Rising Star
Rising Star
Rising Stars are recognized for providing high-quality answers to other users. Rising Stars receive a certificate of achievement and are on the path to becoming Community Leaders.
October 16, 2022

@Esther Strom these doesn't work for me i am not getting any error, but it doesn't even create page in confluence tempsnip.png

Esther Strom
Community Leader
Community Leader
Community Leaders are connectors, ambassadors, and mentors. On the online community, they serve as thought leaders, product experts, and moderators.
October 17, 2022

@E Hanumanthu I'm sorry; I don't have access to data center products, so I don't know.

Like E Hanumanthu likes this
Esther Strom
Community Leader
Community Leader
Community Leaders are connectors, ambassadors, and mentors. On the online community, they serve as thought leaders, product experts, and moderators.
October 17, 2022

@Sakina off the top of my head, without seeing your full configuration, all I can say is that the post request looks wrong. It should look like this:

automationValidation.png

Your webhook that you entered in your action setup should be pointing to https://<your_site>.atlassian.net/wiki/rest/api/content, not to a specific page, as yours appears to be doing.

Like Hana Kučerová likes this
Sakina
Rising Star
Rising Star
Rising Stars are recognized for providing high-quality answers to other users. Rising Stars receive a certificate of achievement and are on the path to becoming Community Leaders.
October 17, 2022

@Esther Strom  if i update the webhook it gives me 500 errorsecond screen shot.png

Esther Strom
Community Leader
Community Leader
Community Leaders are connectors, ambassadors, and mentors. On the online community, they serve as thought leaders, product experts, and moderators.
October 18, 2022

What is the error message if you expand the response section?

Bilel Arfaoui October 26, 2022

Thanks for this amazing tutorial.

But i want to ask if there is any possibility to create the confluence page under a specific parent ??

Alexis Evans October 26, 2022

@Bilel Arfaoui I was actually able to figure out how to do this. Before I had the page created under a parent, it was difficult to find the newly created page without knowing the id and just pasting that into the url.

This tutorial was helpful, but ultimately, I ended up doing something similar, except I did use Scriptrunner for Jira. Still, my method also used json to pass in the information. We have the storage attribute inside the body. But then, as a sibling of the body, we have one called ancestors. Inside that is an attribute called id, and the value is the numerical id of the page that you want to use as the parent. You might have to mess with the syntax you're using for the json, but you should be able to pass this information in through the json the same way I did. It was also a bit tricky to locate the id of the parent page, but once you find that, it should work. Hope this helps!

Bilel Arfaoui October 26, 2022

@Alexis Evans i was able to figured it out like this :

i added this line to the custom data field of the web request component : "ancestors":[{"id":123456}],

Like # people like this
Ludvig Hede November 18, 2022

Hi, How do I create a new page using the old editor?

Naresh G November 29, 2022

 

@Esther Strom  Coul you please help me on below error?

Screenshot 2022-11-30 at 12.25.32 PM.png

Esther Strom
Community Leader
Community Leader
Community Leaders are connectors, ambassadors, and mentors. On the online community, they serve as thought leaders, product experts, and moderators.
December 1, 2022

@Naresh Gantala I'm sorry, I've never seen that error. Offhand, is the user who is listed as the Actor (in the Rule Details section) a licensed Confluence user? Do they have access to create pages in the specific space you're trying to create your page in?

Comment

Log in or Sign up to comment
TAGS
AUG Leaders

Atlassian Community Events