Confluence Template for Service Applications

[#1]

We've been using Confluence for years and have found it to be a great place to document our service applications. Recently, we started using Jira. The first project we created was an operations log to track tasks, changes, and incidents for all things IT. The second project we created was to track our physical assets(servers, workstations, network gear, etc.) We've found that Jira is a great place to track things where the data required is repeatable. For instance we want to know the same build specs on all our servers. However, Confluence is great for documenting things where the data is variable ... for instance application install and configuration. But when the two are combined ... Pow! Whiz! Bang! (yes, I really heard that) We have found that we can track our applications and their unique aspects and also get a look into the repeatable aspects such as disruptions, upgrades, and configuration changes to get a holistic picture of our service application portfolio.

Huh? Give me the goods.

Yeah, so that last part sounded a little sales-pitchy. Now for the good stuff ... some screencaps, setup, and a little code ... very little code I promise!

The first step was to create a couple user macros. Ack, you say!! Go ahead say it. I'll wait. Yes, this is the code part ... very little code. In fact so little that I will put those in another article as it would bloat this one a bit. These user macros simply are wrappers around the built-in Jira macro and supply it with some dynamic JQL. The dynamic part of the JQL simply pulls back issues that link to the page that the macro is placed on. And since that could be any page I wanted to make the "page" portion of the JQL dynamic. One of the user macros gets Jira issues linked to "this" page that are of the type "Server" in our assets project and the other gets issues linked to "this" page from our operations log project. And that's it code-wise. The rest is all Confluence macro goodness.

Phew!! Code out of the way, now for the fun stuff.

The second step was to create a template that we wanted our services application to adhere to. I also wanted to be able to roll-up some of that template info to a report page. Thus, the page properties macro. <said in a loud-boomy-echoy voice> The template below is fairly simple. The Jira Server Links user macro is inside the page properties so that we could quickly see which servers are associated with our service applications. I put that in an expand macro because some of our service applications have A LOT of servers associated with them and the report table would be super long and look wonky if I didn't. Lastly, the template was given a label of "it-service".

Things are starting to take shape. Now for the report page. This page is pretty simple. It has a Create from template macro that creates a page from, you guessed it, the above template. The other macro is the Page Properties Report macro that rolls up the relevant service application properties onto one page. It simply looks for pages with the label it-service in a couple different space and orders the report by page title (which, handily,  is the name of the service application).

The last step is to go into Jira and use the link functionality to link our servers and operations issue to the service application page.

Drum roll please ...

The final result looks like this for the individual pages.

And the report roll-up page looks like this.

 The results are that at a high level we can quickly get information about any of our service applications and then drill down to the service page to see more detailed information such a configuration or Jira operational issues.

If you would like to see how to create the user macros those are in a follow up article entitled Confluence Template for Service Applications - The Macros.

[dbaker6]

Davin,

    This looks great! As a newer user of Confluence, I am still trying to learn how to build templates like this. I see your link that has the configs for the Jira link, do you have anywhere that has the technical details for building the confluence template and rollup page? We don't use Jira unfortunately, but this confluence page for documenting applications and their owners would help me so much!