Exporting retrospectives to Confluence

This guide assumes that you have configured the Confluence integration.

Add a new Runbook step to export retrospectives to Confluence

To get started we will add a new step to your runbook for Confluence. On the left side, you should have a runbook step for ‘Export retrospective to Confluence’. Adding this step will append it to your list of Runbook steps on the right side. This Runbook step has a couple of different configuration options. 


Configuring the Runbook step details

Parent Page: This refers to the main page that the new Confluence page will be created within. Here, you can see we have a demo page for retrospectives that we create in Confluence.

Retro Title: This is the name of the new Confluence page that is created under the parent page, as you can see this field supports our template variable to dynamically name your retro. Reference Using template variables in Runbooks to learn more.

Template: This is the body of the page that we will create in Confluence. This field also accepts variables, so you can automatically include details such as when the incident started, the incident summary, severity, roles involved, and much more. See Using template variables in Runbooks to learn more.

Note: If you leave the Template field blank, FireHydrant will create a default page with all of the information available on the retro page pre-formatted.

Configuring conditions and scheduling

Note: In setting runbook execution conditions, keep in mind that for the export to Confluence runbook step to successfully execute, the step must run after the retrospective has started.

  • Like other Runbook steps, you can configure when this step is executed. For us at FireHydrant, we leverage Confluence to store completed retros, so on the conditions and scheduling tab we have included a condition of ‘Retrospective Completed’ for when this step will run.
  • If you have multiple destinations where you store retros depending on severity, services, or functionality impacted, you can create additional steps for each of those scenarios.
  • If you’d like to send incident/retro information to Confluence before a retrospective is completed, you can also specify a condition to create the page when the retro has started.

When a Confluence page is created, FireHydrant will automatically include a link to that page within the incident details so you can quickly find it.


Troubleshooting Confluence export issues

Runbook conditions

The most common reason why Confluence runbook steps fail is due to runbook conditions.  In order for the Confluence export step to run, the milestone state needs to be either Retrospective Started or Retrospective Completed.  Here's an example of a valid configuration:


Atlassian converting ADF to storage format error

The Atlassian Confluence API occasionally returns the following error when a Confluence runbook export is initiated:  


This intermittent error has been reported on the Confluence developer forum.  The current workaround is to create a separate manual runbook that contains this step, run /fh add runbooks to add this workaround runbook and "retry" the export step within.


Last updated on 3/28/2023