SDLC in Atlassian: Speed up Functional Specs and Traceability (Without Excel or Scripts)

[#1]

In today's development environment, we want to complete release documents at lightning speed, even in highly regulated fields such as GxP. Here's a practical approach:

1. Manage your requirements in Jira as custom work item types, such as functional specifications.
2. Use Xray to integrate your test management into Jira.
3. Incorporate Snapshots for Jira Data into your Confluence setup, along with Snapshots integration with Xray.
4. Create your release documents in Confluence, utilizing the Snapshots App to consolidate requirements and test information. This method allows for the efficient aggregation of Jira data into your release documents in Confluence.

Check out the page on that video: it's accessible to anybody on our sanbox here.

Here is a step-by-step example of how to create a Functional Specification and Traceability document in Confluence:

1. Start by creating a dedicated page for the Functional Specification.
2. Populate the Page: Fill the page with the required textual sections that your organization expects to see. Common sections include Purpose, Scope, and References.
3. Add snapshot macros: In each section where the document requires data from Jira, insert a snapshot macro. For instance:
   1. Functional Specifications List: This is a list of Jira work items. Create a snapshot macro in this section to display the relevant information. See below for detailed instructions on configuring the snapshot macro to retrieve the exact data you need.
   2. Traceability Table: This table should illustrate the links between functional specifications, tests, and test results. All of this data is available in Jira, including functional specification work items linked to Xray test work items and Xray test runs. Create a second snapshot in this section to capture the necessary traceability data. Again, See below for detailed instructions on configuring the snapshot macro to retrieve the exact data you need.

Publish the page and trigger snapshots to retrieve the latest data.

Your Functional Specification is now ready for review.

Has your Jira data changed? For instance, have the team added tests or fixed defects? There's no need for manual edits. Just click the button to trigger snapshots and fetch the updated data. The new version of the page will be available within minutes.

Configuring the snapshot macro for a simple list of functional specification work items from Jira

Here are the macro parameters:

Configuration parameter
Level 1	Each snapshot macro starts with the first level. Add new levels if needed to display linked issues; this is not required in this use case.
Level title	Choose free text to show in the table header.
Search JQL	This is the JQL clause that defines the scope of work items in Jira. Any JQL clause that is recognised by your Jira instance can be used. In this example: project = GAL AND issuetype = "Functional specification" order by created ASC
Add fields to display	a list of fields to include in the table. Any field and custom field that exists in your Jira can be chosen. Fields can be reordered (to define their order in the snapshots table)
Layout (tab)	Contains various options impacting the layout of the table
Automation (tab)	Use this tab to automatically trigger the snapshot. It is useful, for example, where the page needs to be refreshed each time that you run your automated tests pipeline.

Configuring the snapshot macro for traceability of functional specification to tests and test runs 

Here are the macro parameters:

Configuration parameter
Level 1, Level 2, Level 3	Each snapshot macro starts with the first level. The traceability is achieved by adding more levels- Level 2 aggregates the Xray tests that are linked with each functional specification item. Level 3 aggregates test runs
Level title	Choose free text to show in the table header. When there are three levels- each part of the table has their header
Search JQL	This is the JQL clause that defines the scope of work items in Jira. Any JQL clause that is recognised by your Jira instance can be used. The 1st level has a regular JQL. In this example: project = GAL AND issuetype = "Functional specification" order by created ASC The 2nd level has a JQL that include the term $key- to express the relations to the upper level. In our example: issue in linkedissues($key,"Is tested by") order by key ASC The 3rd level is not filtered by JQL, because test runs cannot be retrieved with JQL. Several filter criteria exist: Search JQL that filters based on Test Executions (where the test run exist) Latest or All Fix version Test environment
Add fields to display	a list of fields to include in the table. Any field and custom field that exists in your Jira can be chosen. Fields can be reordered (to define their order in the snapshots table)
Layout (tab)	Contains various options impacting the layout of the table
Automation (tab)	Use this tab to automatically trigger the snapshot. It is useful, for example, where the page needs to be refreshed each time that you run your automated tests pipeline.

Tips and follow-up notes:

1. Use Confluence templates to standardize the structure of release documents across your teams.
2. You can process Confluence pages through official review sign-offs within Confluence. You'll need to configure Confluence further, though (but it's worth it).
3. If you need to export a Confluence page into an attractive PDF that includes metadata and adheres to your branding guidelines, I recommend using the Scroll PDF Exporter. It's my preferred tool for any formal Confluence environment.
4. Interested to learn more about SDLC in Atlassian? Read on about it in my series: "Ready for an SDLC shakeup? The good, the bad, and the ugly of managing requirements and tests in Atlassian"