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.

30 comments

Velizar Borisov
Community Leader
Community Leader
Community Leaders are connectors, ambassadors, and mentors. On the online community, they serve as thought leaders, product experts, and moderators.
April 1, 2021

That goes straight to the bookmarks! 

Really, I would position this one somewhere in my personal top 3 of most useful articles at the community!

Thank you @Esther Strom ! 

Like # people like this
Mykenna Cepek
Community Leader
Community Leader
Community Leaders are connectors, ambassadors, and mentors. On the online community, they serve as thought leaders, product experts, and moderators.
April 2, 2021

Thanks for this, Esther!

Like Esther Strom likes this
Linda Milne_Togetha Group_
Solutions Partner
Solution Partners provide consulting, sales, and technical services on Atlassian products.
April 2, 2021

Great work!

Like Esther Strom likes this
Alexander Bondarev
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.
April 3, 2021

Excellent article! @Esther Strom , Thank you for useful instruction!

Like Esther Strom likes this
Bill Sheboy
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.
April 5, 2021

Thanks for the article, @Esther Strom This is great information!

I find using the REST API solves several needs which are currently only long-term ideas in the automation backlog, like this one to add Confluence integration: https://codebarrel.atlassian.net/browse/AUT-269

Best regards,

Bill

Like # people like this
Desi Nikolova April 6, 2021

Thanks @Esther Strom ! This was very detailed and helpful. 

Like Esther Strom likes this
rekha Velur April 6, 2021

Nice work! Thanks for Sharing!!

Like Esther Strom likes this
Charlie Misonne
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 17, 2021

Very useful! Thanks @Esther Strom

Like Esther Strom likes this
Adam Falklind June 2, 2021

😍

 

Do you think that a similar process can be used for a case to dynamically/automatically create Spaces when creating a new Teams in MS teams? 

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.
June 2, 2021

@Adam Falklind Welcome to the Community! I think it might be possible, depending on a few things.

If you're using a Jira automation rule with a MS Teams webhook to create new Teams based on an Atlassian trigger, you could certainly add an additional step to create a space. 

If you're creating Teams manually in MS Teams, you'd need to use a Teams-based app to trigger the creation of the Space. Teams does have a webhook app; whether it's available depends on your messaging admin/policies. If you have the webhook app, you could probably pass in a Confluence endpoint (/wiki/rest/api/space).

Like Adam Falklind likes this
Jacob Rosenfeld July 29, 2021

Any tips for doing this in reverse? I want a new Jira issue for every new page I create. 

My use case is to use Jira as a Workflow and approval system for each Confluence page added to our Space.

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

@Jacob Rosenfeld I'm not sure it's possible at this time, since there is no automation in Confluence, and you'd need the creation of a Confluence page to be the trigger. If you have ScriptRunner for both Jira and Confluence it might be doable, but it's not something I have an answer to.

If you have serious development skills and want to take it this far, you might look into Forge . Here are a few samples:

Create Jira tickets from Confluence (video)

Feedback collector app

Jacob Rosenfeld July 29, 2021

@Esther Strom Thanks, that's what I'm finding. Atlassian claims the automation and linking is coming. 

Related, is there a way to pull the confluence page name in Jira automation? My use would be:

1) create issue on confluence page

2) use Jira automation to add the confluence page name to the summary/title of the issue. 

Mykenna Cepek
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

@Jacob Rosenfeld - A hack approach you could explore would be creating a new Confluence user, setting that user to watch the space, and routing (forwarding) their email to a Jira email handler.

https://support.atlassian.com/jira-cloud-administration/docs/create-issues-and-comments-from-email/

I've not done it, but it might work.

Peter Yoon September 7, 2021

@Esther Strom Thank you for the post! It's very well written and thorough. I was able to walk through the steps relatively easily.

When I got to the validation step, I'm returned a 500 Internal Server Error response. Any thoughts?

Thank you!

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.
September 8, 2021

@Peter Yoon Hmm. I'll need to look into that - we have this automation in production and I haven't received any failure notifications on ours that would indicate deprecation. 

Do you get any kind of message in your audit log aside from just the 500 code? Is there a message along with it? You may be able to get more info by using an additional action to add the response to the audit log; you can get that info like this in the webhook action:

2021-09-08 16_16_07-Project automation - Jira.png

David Loszewski January 21, 2022

 

<please disregard>

Marco Doebert April 7, 2022

Hi @Esther Strom , thanks for this great article!

Is there a possibility to link to an existing confluence page too?

Thanks a lot!

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.
April 11, 2022

@Marco Doebert I honestly hadn't tried it. I just did, and sort of got it to work; the webhook doesn't seem to like smart values. I was able to get this setup to work with a hard-coded issue key, using the remotelink endpoint.

2022-04-11 15_00_40-Automation - Jira.png

I got the link data by manually linking a specific Confluence page to an existing ticket, then calling the GET endpoint in my browser (just copied the json response) on the ticket for remoteissuelink.

If anyone knows how to make the web request URL accept a smart value, I'd love to know! I tried this and it errored out as an invalid request:

https://<mysite>.atlassian.net/rest/api/3/issue/{{issue.key}}/remotelink

However, with the announcement of Automation for Confluence coming soon, there might be easier ways to create links.

Bill Sheboy
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.
April 11, 2022

Hi @Esther Strom 

To make the request URL dynamic for Jira Cloud, have you tried building the URL in a created variable, and then referencing that variable in the web request action?

Kind regards,
Bill

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.
April 11, 2022

Thanks, @Bill Sheboy - no, I spent 10 minutes on it in response to Marco's question; I didn't have time to really dive into it since it's not something I currently need to do for my instance. I'll give it a shot, though, just out of curiosity.

Like Bill Sheboy 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.
April 11, 2022

OK, @Bill Sheboy I gave it a shot, but am still getting errors. I may have completely misunderstood what you meant by "building the URL" in a variable, as we haven't had much need for created variables in our automation thus far. I come from a programming background, and assumed I could insert a smart value into the middle of a text string to create the variable, like this:

2022-04-11 17_26_14-Automation - Jira.png

I have this set up as a manual rule, not triggered on create, so issue.key already exists. But when I try to use the validation, I'm still getting an error, even though the log action (not shown in the above screenshot) is generating the correct URL.

2022-04-11 17_57_06-Automation - Jira.png

2022-04-11 17_50_11-Automation - Jira.png

2022-04-11 17_53_09-Automation - Jira.png

Thoughts?

Bill Sheboy
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.
April 11, 2022

Hi @Esther Strom 

My bad...Didn't work for me either, so it is not the encoding or the created variable.  It appears to be an defect/design limitation with the Send Web Request action.

Even when I put a literal issue key in a simple Jira REST API call, it failed with a permission error when it makes the request.  I confirmed calling a different function which does not require the key/data in the URL works okay...even putting that URL in a created variable worked.

I'm checking to see if there is an open defect for this in the public backlog, and will update this information if I find it.

Thanks,
Bill

Like Esther Strom 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.
April 11, 2022

It worked for me with the literal issue key, as long as the entire URL was a static string. It's only when trying to include smart values in the request URL that I run into problems.

Like Bill Sheboy likes this
Ruud Ravensbergen April 26, 2022

Hi @Esther Strom 

To be clear, I'm not a programmer or anything like that.
I like to try things, often manage to get it right, but not this time.

Your explanation of how it works is perfect. Followed step by step and it works.
However, try bringing the "Dicription" field from the jira isseu to the Confluence page as well.

And I try to put it under the right page as well. But no matter where I search and no matter what I try I can't seem to get it right.

Can you give me some tips, or code, of how I should go about it.
Thank you in advance.

Greating
Ruud

TAGS
AUG Leaders

Atlassian Community Events