Showing results for 
Search instead for 
Did you mean: 
Sign up Log in

It's not the same without you

Join the community to find out what other Atlassian users are discussing, debating and creating.

Atlassian Community Hero Image Collage

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!

Monique vdB Community Manager Dec 21, 2017

@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 Sign up to comment
Community showcase
Published in Confluence

🏑 Atlympic Event: Confluence

Hello Community!  Quick disclaimer: We are running a contest on Community (The Atlympics!) from July 23rd - August 8th of 2021. If you are interested in participating in this contest (prizes! ...

494 views 18 17
Read article

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