As we have seen, JIRA Agile is able to leverage many JIRA features to add more value to simply running and managing your tasks on a board. Another great tool JIRA Agile integrates with very tightly is Confluence.
Confluence is a team collaboration solution from Atlassian (the maker of JIRA and JIRA Agile) that enables teams to collaborate and create content together. Organizations often use it to create and share information related to projects such as functional and design specifications. JIRA Agile works seamlessly with Confluence to provide you with a complete agile experience. In the following sections, we will look at how you can integrate JIRA Agile with Confluence to:
- Create epics and user stories with design documentation
- Manage and view your sprints on a calendar
- Capture meeting notes for your sprint planning sessions
- Create retrospective reports at the end of each sprint
- Share and publish release information
If you have not already integrated JIRA and Confluence together, you need to create a new application link. To create an application link with Confluence, perform the following steps:
- Click on the cog icon from top right-hand corner and select the Add-ons option.
- Select the Application Links option from the left navigation panel.
- Enter the URL to your Confluence instance and click on the Create new link button, as show in the next screenshot:
- Tick the The servers have the same set of users and usernames option if both JIRA and Confluence share the same user repository, for example, LDAP.
- Tick the I am an administrator on both instances option if you have an administrator account on both JIRA and Confluence. This will let you also create a reciprocal link from Confluence to JIRA.
- Click on the Continue button:
- Verify that the onscreen information is correct. If both applications are able to communicate with each other successfully, it will display the URLs and application name and type, as shown in the following screenshot. Then, click on the Continue button:
- Continue with the onscreen wizard, and once the application link is successfully created, you will see a success message and the new application link listed for Confluence:
JIRA Agile is a great tool to track and manage your day-to-day activities for your project, but it is not the best tool to capture detailed information for your tasks, such as design documentation and functional specifications for your epics.
With Confluence as a documentation platform, there are a few ways you can create design documents and link them to your epics.
The first option is to create your documents called Confluence pages, directly from your backlog:
- Browse to your Scrum board and go to its backlog.
- Open up the Epics panel from the left-hand side.
- Select and expand the epic you want to create a Confluence page for.
- Click on the Links pages link from the epic.
- Click on the Create page button from the dialog, as shown in the following screenshot:
After you click on the Create page button, you will be taken to Confluence in a new browser tab with the Create dialog displayed, as shown in the following screenshot. By default, the dialog will have the Project requirements template (also called blueprint) pre-selected for you, but you can choose to use a different template if you want. Also note that the Select space field at the top will have the last Confluence space you have visited pre-selected, so make sure you select the correct space to create your new page in.
- Click on the Create button after you have selected the correct space to create your new page in:
- If this is the first time you have used the product requirements template, you will get a Let's get started information dialog, as seen in the following screenshot. Simply tick the Don't show this again option at the bottom and click on the Create button to create your new page:
- Click on the Create button again to start working on the new page.
Confluence will present you with a new page and editor, with a pre-defined template. You can simply fill in the templates with information such as goals and requirements. A few important things to note:
- Make sure you give your page a title. A good practice is to name it after the linked epic.
- Reference the epic in JIRA by clicking on the Link to related JIRA epic of feature text label from the Epic field. This way, a reference link will be created between the requirement page and the epic issue.
With the page created, if you go back to JIRA, the Linked pages link for the epic will change to 1 linked page, and clicking on that will show you the actual linked page, as shown in the following screenshot:
If you already have requirement pages created for the project, instead of creating new ones from the epics, you can simply link to those pages by clicking on the Link page button. After clicking on it, you will get a search box, and you can type in your page's title, find the page you want, and select it to create a link. This is illustrated in the next screenshot:
Note
If you cannot see the linked pages, make sure Confluence has remote API enabled. See https://confluence.atlassian.com/x/vEsC for more details.
If you are using the product requirements blueprint, as we have seen earlier, there is a section on the page for you to list out all the requirements for the feature. Once you have defined all the requirements with the team, you can create JIRA Agile user stories directly on the page. To do this, perform the following steps:
- Go to your product requirements page in Confluence.
- Highlight the text of the requirement you want to create a user story with. The text you highlight will become the summary of the user story, as shown in the following screenshot:
- Click the JIRA icon. This will open up the Create Issue dialog, as shown in the following screenshot.
- Make sure the project and issue type selection is correct. You can click on the Edit link to change that.
- Enter a description for the user story.
- If the Product Requirements page is already linked to an epic in JIRA Agile, you will see a Link to epic option. Uncheck this option if you do not want the user story to be added to the epic.
- Click on the Create button to create the user story:
After you have created the user stories, you will see a JIRA issue added next to each of the requirements, showing their key and status. Their status will be automatically updated as the issues are being worked on. You will also see a JIRA links button at the top of the page next to the breadcrumbs. Clicking on that will display all the JIRA issues currently linked to this page, including any epics and user stories. Refer to the following screenshot:
As you and your team work on the sprint, it is often helpful to see how your sprints fit in with other activities your team might have. For example, if there are team members going on a vacation or having travel plans half way through a sprint, or if there are other delivery commitments that might interfere with the sprint.
Again, the key to solve this is to have all this information visually displayed on a single calendar, viewable and shared by the entire team, so everyone can stay well informed, just like having tasks plotted on an agile board. To do this, perform the following steps:
Once you have created the event, Team Calendar will get all the sprints you have for the selected project, and display them on the calendar. As shown in the following screenshot, we have two sprints, Sprint 2 and Sprint 3. We can also see that Tom Johnson will be away at the start of Sprint 2, which might have an impact on the team's ability to complete everything in the sprint on time. Also, if you have all team members' vacation plans on the calendar, then during your sprint planning sessions, you will have all the information you need when deciding how much work should go into the sprint and how long the sprint should be:
With the calendar all set up, you can also share and embed it. A good way to use this feature is to create a new Confluence page in the same project space where you have all your requirement documentation, call it something like Project Calendar, and then embed the calendar into the page. To embed the calendar into a page:
- Click on the Create button at the top of the page.
- Select the project space for the Select space field.
- Now select the Blank page option and click on the Create button.
- Name the page Project Calendar.
- Select and add the Team Calendar macro into the page.
- Click on the Add Existing Calendar option.
- Search for the calendar you have created, and click on the Add button.
- Click on the Save button to create the page:
After you have created the page, you will have all the information about the project in a single place, along with the Confluence space for the project, for easy access. One additional step you can take is to create a quick shortcut link on your Scrum board to the Project Calendar page, so it is just a click away when you need it.
To create a link to the page:
- Browse to your Scrum board.
- Click on the Add link option from the left-hand side.
- Enter the URL for the Project Calendar page.
- Enter a label for the link, that is, Project Calendar.
- Click on the Add button to create the link.
The link will be displayed under the Project Shortcuts section on the left-hand side, as shown in the following screenshot. So during your sprint planning sessions, or work sessions on the active sprint, you can easily access Project Calendar and get the most up-to-date information:
As we have seen, you can plan and visualize your sprints with Confluence's Team Calendar. Another important part of your sprint planning session is to keep records of the meetings, capturing what was discussed, decisions made, and being able to reference back to those meeting notes in the context of your sprints.
Just like requirement documents, Confluence is also a great place to capture and store this information. From inside your Scrum board, you can create and link each sprint to pages in Confluence, just like with epics.
To create a meeting note for a sprint:
- Browse to your Scrum board.
- Click on Backlog on the left-hand side to display all your sprints.
- Click on the Linked pages link for the sprint that you want to create a meeting note for.
- Click on the Create page button if you want to create a new meeting note page, or the Link page button if you already have the meeting note ready:
If you click on the Create page button, you will be taken to Confluence, with the Create dialog showing. It will have the Meeting notes blueprint pre-selected. Make sure the correct space is selected and click on the Create button; you will be able to start entering your meeting information. Once you have created and saved the meeting note, the page will have a JIRA link referencing the sprint it has been created for, as shown in the following screenshot, and the sprint will also list all the meeting notes it has:
Other than creating meeting notes, another great feature is being able to create retrospective sprint reports at the end of each sprint. Remember, one of the key ideas behind agile is continuous improvement, so it is important that at the end of each sprint, the entire team comes together and discusses what they did well, and what went wrong during the sprint; also, to summarize lessons learnt, and discuss how to improve the process in the next sprint as a team.
To create a retrospective report for your sprint, perform the following steps:
- Browse to your Scrum board.
- Click on Reports from the left-hand side.
- Select the sprint to be reported on and select Sprint Report.
- Click on the Linked pages link.
- Click on the Create page button:
- Click on the Next button in the Confluence Create dialog.
- Enter a title for the report or leave the default.
- Add all the team members present in the retrospective meeting.
- Click on the Create button to start work on the report.
Just like all other reports created with JIRA Agile, a reference link will be created between the report and the sprint, so you can easily go back and forth between the two.
The last integration feature between JIRA Agile and Confluence is to create reports on the project based on specific versions. There are two types of reports you can create:
- Change log report: The change log report lists out all the issues that are part of a selected version. This saves you the hassle of manually compiling a list of issues and entering them. This is a great way to communicate changes within a given version to your customers and other stakeholders.
- Status report: The status report is a live report that shows the status of the project in a number of pie charts.
To create these reports, you will start in Confluence instead of JIRA Agile:
- Log in to Confluence and browse to your project space.
- Click on the Create button at the top or press the C key on your keyboard.
- Select JIRA Report from the Create dialog and click on Create.
- Choose the report you want to create and click the Next button. In our example, we are creating a status report:
- Select the project and version to report on. These fields are auto populated based on data coming from JIRA.
- Enter a title for the report.
- Click on the Create button to start work on the report.
The default report template will be auto populated based on the information you have provided, so you can simply click on the Save button to create the report without any further changes. The following screenshot shows a default status report:
