Come for the products,
stay for the community

The Atlassian Community can help you and your team get more value out of Atlassian products and practices.

Atlassian Community about banner
4,298,880
Community Members
 
Community Events
165
Community Groups

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.

10 comments

Kishan Sharma Community Leader Jul 27, 2021

Great article @Esther Strom i'll try this!

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

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 Jul 29, 2021

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

Esther Strom Community Leader Jul 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

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 :)

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 Oct 20, 2021

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

@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 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)".

Comment

Log in or Sign up to comment
TAGS

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