Confluence and JIRA - best practices

I am new to Confluence and new to the "epics" feature in JIRA- there are now requirements which are called or were once called "features"-- is anyone else having a hard time keeping it straight?

Would like to know:

1. How are you using Confluence? Meeting Notes? Requirements?

2. How are you using the requirements blueprint in Confluence- using one page per sprint? One page per epic? Per individual requirement?


Hi Rachel,

I think of JIRA epics as features in the traditional sense. In an Agile JIRA world a story is something that can be completed in a sprint, and an epic is something that should be completed after a number of sprints (if you use a model as SAFe, this would be a PI, e.g.)

Regarding your questions:

1) I use Confluence for all type of the documentation (except for code comments, code review annotations and the like).  We use it for process documents, feature design documents, requirement documents, meeting notes, as a repository for our team retrospective, and even as a knowledge base! One of the most visited documents is the team handbook with a summary of the team processes and guidelines.


2) I've created a template in Confluence for requirements, and created different sections for epics (or features).  Each section is linked to a specific JIRA epic, and actually I insert a link to the JIRA epic in the page (which works really well, since the Confluence page will reflect the status of the JIRA epic in real time) In the same section, I have a table where the requirement in a column is linked to a number of stories (or tasks) in another column.  When you select the story/task, Confluence offers you the option to enter a comment or to create a JIRA story, which is what I do for each story in the Confluence page. That way I have a Confluence page with the requirements in one column, the corresponding stories in another column in the same row, and all stories linked to the epic in the same section.

Hope it helps,


Hi Carlos- thank you so much for the info!!

Are you using the new cloud Version of JIRA? We just converted and now when I click on "requirements" in the top menu- a page of "features" opens. We have features from previous sprints -- so we have scenarios (acceptance criteria) attached to those features - as well as- completed stories.

We also have "epics" created and those epics have assigned "stories." I do not see a connection between the new features/requirements and the epics. 

With that being said- are you using "features" or are you just using Epics? The more I look into it- it seems that Epics are useful but the "features" feature seems confusing -- I would like to not use it. 

Also, the "requirements" you mentioned you have in confluence- what do they link back to in JIRA? Stories, Features, or Epics?

I hope I havent confused you too much. I am really excited about using these two tools together- I just have to figure out how!


I have attached two screenshots. Click to see screenshots from Rachel

Hi Rachel,

I only use epics, stories and sub-tasks. This is an example:

1) First I create a Confluence page.  I add a sentence referencing the JIRA epic (in a more real case I would have a whole paragraph describing the picture).  I use the insert (+)-> JIRA issue filter to select the epic:

Screen Shot 2017-12-19 at 10.03.03 PM.png

Screen Shot 2017-12-19 at 10.03.47 PM.png

2) I publish the page.

3) After that, I select the text of one of the requirement summary. Immediately a JIRA icon and a comment icon show up. I select the JIRA icon:

Screen Shot 2017-12-19 at 10.04.05 PM.png

4) Then I select my project  (e.g.'Carlos Project O'Fun') and the issue type in JIRA (e.g. 'story'). Confluence detects that there is a link referenced in the page so it automatically offers to link to that epic.

Screen Shot 2017-12-19 at 10.04.38 PM.png

- I also select 'Create multiple issues from table'.  Confluence allows mapping two columns from the table to 'Summary' and 'Description' on the JIRA tickets to be created:

Screen Shot 2017-12-19 at 10.05.04 PM.png

- The Confluence page contains links/references to the requirements in JIRA.  Change on statuses in JIRA will reflect automatically in Confluence.

Screen Shot 2017-12-19 at 10.05.52 PM.png

Hope it helps.


Awesome! Thank you. 

One more quick question- in your screenshot above-- is it going to pull in the same description as in the JIRA story? If so, is there a way to do this after the story was already created- created directly in JIRA- not from confluence? 

We had a planning meeting today - and I tried to introduce this to the team- it was immediately veto'ed then blamed for permission issues that were happening- and then the whole documentation task was taken from me! Therefore stories go into JIRA that I dont have in my documentation. 

You can create the story in JIRA first and then add it to the Confluence page using the insert JIRA issue filter.  But by doing it this way the description text won't be added to Confluence, only an icon with a hyperlink to the JIRA issue in the JIRA project.

Screen Shot 2017-12-20 at 2.59.36 PM.png

Screen Shot 2017-12-20 at 2.59.54 PM.png

Also, the original text in Confluence from which you created a ticket doesn't stay in sync with the JIRA ticket summary, but even so, it's working very well for me and the team here.

Hope it helps,


That helps. Yes I wouldnt expect the text to change in Confluence if someone edited in JIRA_ maybe in a year or two -that will work!

It all depends what you want to use the data for. Some reports need structured data, so Jira is a good match. Other collaboration can work well with Confluence's less-structured data. Go with whatever gives you the results you want with the least friction for your teams.

Oh My! I just found something called "JIRA Report" when you create a new page- some options come up- if you click the "more" button and then select the JIRA report option you can select your project and it will pull in all of the stories, task,s epics, etc. 


This is awesome because yesterday I was trying to do this manually. 


Be sure to check it out!

@Rachel Wilson this sounds like exactly what I need (yesterday I was working from a printed off list of my project items). Thanks for the tip! 


Log in or Join to comment
Community showcase
Kesha Thillainayagam
Posted Mar 05, 2018 in Confluence

We want to know what templates you're using in Confluence!

Hi Community!  My name is Kesha (kay-sha not Ke$ha) and I'm on the Confluence Product Marketing team. We are trying to understand and improve template use cases in Confluence, and are intereste...

2,523 views 25 4
Join discussion

Atlassian User Groups

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

Find a group

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

Find my local user group

Unfortunately there are no AUG chapters near you at the moment.

Start an AUG

You're one step closer to meeting fellow Atlassian users at your local meet up. Learn more about AUGs

Groups near you
Atlassian Team Tour

Join us on the Team Tour

We're bringing product updates and pro tips on teamwork to ten cities around the world.

Save your spot