From Jira to Confluence with few clicks and BOOM x 15! (Part 1)

[#1]

Maximizing the use of Atlassian Marketplace Apps

On my previous article about The Purpose of the Atlassian Marketplace I mentioned that the main challenge for those trying to get a new app purchase approved is to justify the Return on Investment. Furthermore, considering that the app price is based on the platform number of users, and not based on the users that actually justify the business case, the goal of the person looking for approval is to find a way to extend the application usage beyond those that are the primary target audience. Of course, budget will be always a barrier, but if we find the "extra leg to the table" we will increase our chances.

In this article, to support the concept of extending the use of the app beyond original design, I picked one of the apps that I mentioned on my comments to the February Challenge,  it is called Automated Release Notes for Jira. Based on the name you will think that it is just an app for Jira to automatically generate Release Notes. However, i could tell you that with few tricks you can do more than that, you can create pages in Confluence, send emails, notifications to Jira Service Desk and more. I will explain how to use the app and where you can find additional elements to increase the users base. I am sure that each one of the apps on the marketplace could be used in more ways than on the original scope. A liitle bit of effort and imagination could get the extra justification to get your app purchase approved.

Jira and Confluence, Better together

While we track product development in Jira we can add power and increase our productivity and performance by bringing Confluence to the game. I will show you how to combine the power of both tools to deliver faster and better software or products. But before that let's have some fun with this Atlassian video.

To accomplish our goal we start with the first step, to evaluate the business need: "How to improve the out of the box Jira release notes experience", requested by one of our Director of Product Management

Due diligence: we evaluated internal solutions and Atlassian Marketplace. Then, after founding one of the potential solutions, we contacted the vendor to measure the level of response and commitment. The experience fulfill our expectations and we decided to move forward.

Considering that the cost is based in the number of users of our Atlassian platform, we look in how we can maximize the benefits opening the app to other users. As we implemented the solution, and new app version were released, we found additional usage of the new functionalities. 

Let's Imagine...

You are tracking your products in Jira and then in "that" Monday mid morning you receive one of "those" emails... just enough to warm up your week (or burn it...)

 The next steps

 Well, it sounds like a good and compelling call to action. The question here is: what type of action? Let's explore a couple of options.

As I am sure you are familiar with the option A, I will focus on the option B so you can have more time to relax with your team.

Let's talk about Automated Release Notes (ARN) for Jira

This app will add a new menu option in your Jira project visible based on project permission. In order to start using it you will need to master some key concepts: JQL, Templates, Rules and Actions.

First step, Create the ARN Templates

One of the main reasons of why we selected this app was because the flexibility provided on the templates because they are purely based on Jira Query Language (JQL). Personally, I think it is the core power that adds flexibility to basic functionalities and allowed me to find additional use for it.

There are Global Templates and Local Templates. This is a good feature but it could generate some confusion among your team members.

• Local Templates: are visible only in the project that is hosting the template, it could be cloned from a Global Template and customized to meet our "project needs". Keep in mind that if you use the parameter [ProjectID] your will include information from this project only, but, as it is based on JQL, you will be able to grab information from other Jira projects ( I will explain that later on this article).
• Global Templates: This is a good functionality and it was released just in time for our implementation as we manage more than 100 products in Jira. All the templates need to have a Jira Project that host the template. In addition, you are able to add modifications only to the template located on the source project.   To address this need, I created an ARN Global Templates Jira project, that contains test data and host all the Global ARN Templates that will be broadcast  to all Jira project admins. If you try to edit a Global Template without cloning it, the system will display a message with space Key indicating the location of the Global Template.

In spite of having multiple type of templates, all of them follow a similar process during creation. I will use, as example, the generation of Confluence Templates that are used to create pages in Confluence directly from Jira with content from the projects and based on the JQL statement.

Key elements of the ARN Template

The option to Create new templates is under the tab Templates. There are some parameters that the user needs to provide.

• Template name, type of template (Local or Global), action to perform with empty results
• Page title: this will be the name of the Confluence page to be created. Be cautious here as Confluence accepts pages with unique names on the spaces, so if you don't include a variable as part of the title that will make it unique, the second time running the template will generate an error. To overcome this issue I added the variable "timeStamp" as part of the title, like "... generated on /[timeStamp]"
• The gray boxes on he body are called JQL Functions and this is were the magic happens, master this one, combine it with a good knowledge of JQL and your reports won't have limits!
  • Provide a name to the JQL Section that is indicative of the content
  • The Description will be added under the title on the final outcome
  • JQL, we made it! Here is your power. The example on the picture depicts a simple JQL that will get information from the host project (by using as parameter projetID and related to the triggered version (versionName) selected during execution of the rule that contains the template.
• Other parameters needed are related to the actions to perform when no results are returned and the variables to add as outcome of the section.
• Columns: in this are you will specify which data you will expose from the JQL results. You can add here any field captured in Jira including custom fields, they can be grouped and organized by type. A recommendation here is to be sure that you don't select too many fields for a table view. If there is a need for multiple fields use the layout option to present your information.

The Power of the JQL in this context

The example above shows alternative JQL stateemnts that could be used on the template JQL sections, all of them could be combined in the same template that will end in a Confluence page.

• Standard JQL: the first group contains the three JQL statement used for each section, the only difference is just the issueType to separate in our page Stories, Bugs and Tasks. These JQL are for the information available on the host project and only for the version selected. We could say that this is the normal use of ARN as expected
• Alternative use of ARN: here is how I found a way to maximize the Return On Investment on this app.
  • PMO Release Notes: this JQL statement is based on the host project and related version but adding other fields as part of the query like Customer Organization. Information needed by the PMO office that is looking for elements released that are affecting specific customers or for custom development
  • Team Reports: if you check the JQL statement you will see that we are not adding projectId and versionName, instead a generic statement that will grab information based on filters. Those pre-defined filters contain information from multiple Jira projects. When this JQL section is triggered it will grab information from all those projects, without considering the host project, in other words this particular ARN template could be triggered from any project.

Cloning your Global Templates

Despite of the effort of the developers of Global Templates you might need to customize it to meet your needs, a change of a title, additional fields, different sorting, changing tables to layout to add more information, etc. Fortunately, this action is just one click away.

On previous version it was easier to clone the Global Templates from any project, unfortunately on the just released version 2.2.4 the vendor change that and the templates can be cloned only on the host project, which is a problem for the user as they might not have admin access to the host project. I personally don't like this decision made by the vendor because it is generating silos and not helping fostering the sharing of best practices. I will show a workaround to this option. It was a product design decision and I am not sure the reason behind it but it will requires an extra step to clone templates from other projects.

Now with version 2.2.4 of ARN you can clone a template from the host project by clicking on the icon (highlighted on the screen capture)

Unfortunately, if you access from a different project you won't be able to clone the global template.

Workaround to clone the template from a different Jira Project

If you desire to use a Global Template as the baseline for a new template, but you don't have admin access to the Jira project hosting the Global Template, you can still grab the source code and paste it into a new empty template in your own project.

The key to the vault is on the Source Code Icon from the toolbar, once you click it the window will pop up with the whole template code, select all, copy it and then open the target template and paste it replacing existing code.

Ctrl+A | Ctrl+C | Ctrl+V will solve the problem and voila! you can start changing the template from there, starting from a pre defined global template.

Creating Rules to use the Templates

There are a lot of more flexibility for ARN Templates, please consult the product documentation for details, for now, I will explain how to use them. 

Templates are useless without rules that trigger the action referring the template. For instance, with your templates created we need to build the rules that will use those templates, in this case our Confluence Template that will be part of the actions triggered when a rule condition is met.

Each type of action will require specific parameters, in the case of Confluence Action you will need to provide the "demographics", basically the target location of the new page that will be created. Both Space and Parent Page is needed. Caution call here!, if you are planning to run this rule manually or multiple times be sure you add a variable on the template on the name of the page field so the page generated is unique, I decided to add timestamp.

 

To "obtain the Parent Page Id :

1. Ensure that the current user has permissions to View and Edit the page

2. Navigate to a specific page

3. Go to the ellipses at the top right of the page
4. Choose Page Information
5. The URL in the address bar will change

6. Page ID will be displayed as a parameter in the URL

   e.g.: When entering Edit Mode, the URL will change to http://my.domain.com/pages/viewinfo.action?pageId=65541

   In the example above, 65541 is the Page ID."

The Potential of ARN Rules

Each Rule could contain multiple actions and a mix of them, so it might create many confluence pages as needed, send emails or create Jira Service Desk announcements

In this example above I have 12 Confluence pages generated and one email sent with just two clicks. And here is where the Click, Click, Click = Boom x 15 happens! This could be reduced to ZERO (0) click if you select the option Version Release for trigger. The rule will be executed when  a version is released from the Jira Release section. 

1. Run the manual Rule | 2. Version Drop Down | 3. Select a version

Here are the parent pages in Confluence with the corresponding reports generated from Jira using this app called Automated Release Notes (ARN)

Some tricks to extend the use of this Jira app

1. Jira Query Languages (JQL) statements and filters

   1. Maximize the power of the templates by adding JQL statements and use filters if needed. Test JQL and filters in the Jira Issue Navigator and then replace it with the ARN Variables if needed.

      Consider the use of variables as parameters in your template JQL like projectID or versionName

Please follow this Article Part 2 to learn more about how to maximize the use of this Marketplace App, used as an example to obtain better Return on Investment on purchased Atlassian Apps.

[Jodi LeBlanc]

Interesting article, I love your enthusiasm!

[Deleted user]

Comprehensive write up.  Nicely done and very informative.

[Mario Abud]

Muy interesante el artículo, ansioso por escuchar la presentación!

[_Fabian A. Lopez]

Good News about Automated Release Notes.. it is now ... NO CLICKS needed to generate the monthly reports as you can have the rule triggered by a schedule managed with CRON expression on server and with a simplistic interface in Cloud.