ALM Works

This is part three in an ongoing series of posts on Structure integration with Portfolio for JIRA.

The structures referred to here are explained in previous posts:

• Track Portfolio Plans in Real Time with Structure
  (general introduction to Structure-Portfolio integration)
• Track Multiple Portfolio Plans in Real Time
  (methods for combining multiple Portfolio plans in Structure)

In this post we'll look at embedding those structures (Portfolio plans) into Confluence pages using the Structure gadget, and also look in close detail at how to configure the gadget.

Portfolio Plans in Confluence via Structure Gadget

Structure comes with a Confluence gadget for embedding structures in Confluence pages. It requires some initial setup, so if you haven't already enabled it, please consult the documentation for instructions.

The quickest way to add any macro to Confluence is to type { and then start typing the name of the macro you want to add:

Select the Structure macro from the list and the macro configurator will appear:

Now let's configure.

Structure Confluence Gadget Configuration

The options in the left hand column control the layout of the gadget in the page:

• Width - width of the gadget on the page, defines the CSS width property.
• Border - 1px soft gray border. Purely aesthetic, looks better with the border.

We'll set our width to 100% or auto and keep the pretty border.

Now we'll configure the structure itself in the preview pane on the right.

First we select the structure that we want to embed. In this case I'll select our Multiple Portfolio Plan Overview structure from the previous post.

We need to specify a view (a saved configuration of columns) for our embedded structure. Confluence users browsing the page will not be able to switch between views, but they will be able to add, remove and rearrange columns and revert to the original configured view. Changes they make in this way will not be visible to other users.

I'm going to create a new view by pressing the New View... button. This creates and saves a basic view (with only Summary and Progress columns) which can later be configured via the main Structure interface in JIRA.

It's best to make the new view public so that everyone will be able to see it (do it now by clicking on the link that says Let everyone use this view) and call it something more imaginative than the generated default name so it will be easier to find and edit later.

By additionally specifying a Filter we can limit the results displayed in the structure gadget. This is particularly useful for reports, and especially personalised reports using the currentAssignee() JQL function. In this example we don't need a filter, but if we did we could choose from plain text, JQL, S-JQL or a saved JQL filter.

The Title field only appears on printed pages as a 'placeholder' for your structure. The structure gadget can't be printed (I'd like to say this is out of concern for the environment, but it's more complicated than that), so you could perhaps use this field to inform your viewers why they can't see structure on the page they just printed, or direct them to these instructions on how to print a structure in JIRA.

The Visible Rows field controls the maximum height of the gadget (thereby controlling the maximum number of rows visible at once).

When there are fewer rows in the structure the gadget will minimise its height to contain them. As more rows are added, the gadget will grow until it hits this limit, at which point a vertical scroll bar will appear in the gadget itself.

If the gadget has already outgrown the viewport, your viewer will have to contend with two vertical scrollbars in order to view the whole structure, and that won't be fun. I would experiment with values of no more than 20 - this is the maximum that will fit comfortably in most browsers on displays with around 1000px vertical resolution.

If Allow changes (subject to permissions) is checked, any user who has permission to edit the structure in JIRA will be able to edit it in Confluence (everything from editing JIRA fields inline to rearranging issues in the hierarchy). If you want your Portfolio plan in Confluence to be read-only, uncheck this.

The Alternative settings when maximized checkbox only applies to the gadget when it's used on a JIRA dashboard (yes, you can put your Portfolio plans on JIRA dashboard with this too) so we leave it unchecked.

Now save your configuration before inserting the macro, otherwise all these settings will be lost.

And now you have a Portfolio Plan in a Confluence Page:

What you can do with your Portfolio Plan in Confluence

The Confluence gadget features a stripped-down version of the Structure interface. You can edit some of the fields in the gadget.

Drag and drop editing of the hierarchy is fully supported.

Track updates (to hierarchy or field values) in near real time.

Clicking the 'Open' link in the footer of the gadget opens the structure in JIRA.

Troubleshooting

Structure gadget doesn't show up in the macro picker - probably need to restart Confluence while the connected JIRA instance is up and running.

Arrows for expanding/collapsing branches don't show up - you need to apply the CORS filter in JIRA.

Next: Structure Gadget as a Wallboard (With Bonus Hacks)

Wallboards and dashboards are great for communicating and tracking all manner of important metrics.

While the Structure gadget is fully at home in Confluence pages and on JIRA dashboards, it's not entirely compatible with JIRA's wallboard mode. But evolution gave us opposable thumbs for a reason.

With just a tiny bit of hacking minor tweaking, I'll show you how you can make stunning full-screen, real-time Portfolio dashboards and be the hero of your team...

Stay tuned for the next instalment: JIRA Portfolio Dashboard.