Overview Documentation About Us Contact Us Support
Quick Suggest Macros for JIRA
Version 1.0

Installation Guide

Introduction

The Quick Suggest Macros Plugin is intended for novice and advanced JIRA users alike.
It removes the complexity of adding macros to your issues via a convenient new auto complete feature, and adds several new macros to JIRA for things like advanced issue links, more icons, status badges, and announcement messages.

The autocomplete dialog keeps track of all the various macros and their options, and provides you with easy choices for everything.

Add-on Requirements

The Quick Suggest Macros add-on requires Atlassian JIRA 6.3 or later and Universal Plugin Manager 2.2 or later.

Note: if you need support for JIRA 5.x, send us a note via email, and we'll be happy to to include you in the beta we are currently running.

Installation

The Quick Suggest Macros plugin doesn't require any special configuration to work. Simply install it via the Atlassian Marketplace, or one of the other methods detailed below, and you're ready to use it the moment the install finished.

You must have the JIRA System Administrators global permission toinstall add-ons.

Installation via Atlassian Marketplace

  1. Go to the Quick Suggest Macros Atlassian Marketplace page.
  2. Buy or evaluate the add-on with a free 30 day trial.
  3. Login to your JIRA account, if required, to proceed installation of the add-on. The license key is automatically configured into the add-on configuration for free trial licenses.

Installation via JIRA Plugin Manager

  1. In JIRA, go to Administration > Add-ons.
    The Find New Add-ons page is displayed.
  2. Search the Marketplace with 'macros' as the search phrase.
  3. Buy the add-on or start the free trial for 30 days.
  4. Login to your JIRA account, if required, to proceed installation of the add-on. The license key is automatically configured into the add-on configuration for free trial licenses.

Manual Installation

Use manual install if you have a specific version of Quick Suggest Macros downloaded from the marketplace or sent by some other file sharing method:

  1. In JIRA, go to Administration > Add-ons.
  2. Once the "Find new add-ons" page shows, go to Manage add-ons
  3. Click and navigate to the jar file that you already have.
  4. Click Upload, and wait for the confirmation dialog that the install finished.
  5. Buy the add-on or start the free trial for 30 days.
  6. Login to your JIRA account, if required, to proceed installation of the add-on. The license key is automatically configured into the add-on configuration for free trial licenses.

Working with Macros & Autocomplete

The autocomplete dialog can be triggered by simply typing a curly ({) brace anywhere in an issue field that uses the JIRA Wiki Markup Renderer. As soon as the curly is started, the dialog will popup and present you with the available macros.

You can scroll through the options in the dialog either via mouse wheel or via keyboard up & down arrows. Alternatively, you can also continue typing, and the autocomplete dialog will automatically begin filtering the list of macros to match what you're typing. Macros are matched by name, and by keywords.

Once you've identified the macro you want to add, either select it via mouse click, or if it is currently selected in the dialog, simply hit enter, and the macro will be inserted into the Issue field.

Some macros have additional options to customize them. In such a case, once the macro has been inserted, the autocomplete dialog will immediately launch into customizing the macro. The available options in the autocomplete dialog will switch from the macros to the list of options. Once you select an option, it will continue and show you the list of available values for an option.
Here you can see a panel being configured:

Some macros don't have any additional options (like {loremipsum} or {quote}), in which case, the macro is inserted into the issue field, and the cursor is moved to the macro body right away, so you can continue typing.

The {noformat} macro is an exception to the above. It shares the same options as the {panel} macro, but from our experience, the most common use we've encountered is without any additional options. Thus, the {noformat} macro will not trigger autocomplete for the macro customization until you specifically trigger it.
You can begin customizing the noformat macro by adding a colon (:) after the noformat like this:

Some macro options are free-form, and don't have pre-defined values. One such example would be the title of a {panel}. When you selec the title in the autocomplete dialog, the cursor will move to the right spot for you to enter the title automatically. Once you're done, you can resume the autocomplete part by typing a pipe (|). This will bring up the autocomplete again, showing you which options have not yet been added.

If you move the cursor to an existing macro, the autocomplete dialog will come up automatically, showing you available options to customize the macro.

The autocomplete dialog can be dismissed either by clicking away and moving the cursor out of the macro, or by hitting the ESC key on the keyboard.

If you're wondering how to tell whether an Issue field supports the JIRA Wiki Markup, keep an eye out for these icons . If you see them, the field has Wiki Markup enabled, and autocomplete and macros will work.

In this screen, you can see that the "Environment" and "Description" field show the help and preview icons, which indicates that Wiki Markup is enabled.

If you don't see Wiki Markup enabled, you can follow the steps Atlassian provided here for making the necessary changes to your JIRA instance.

Autocomplete Limitations

The autocomplete dialog currently only includes standard JIRA macros and the advanced macros that ship with the Quick Suggest Macros plugin. Any additional 3rd party macros installed on your JIRA instance will not automatically show up.

If there are any 3rd party macros you would like to see added into the autocomplete dialog, send us a request at support@tss.io

Built-In Macros vs Custom Macros

JIRA ships with a few content macros by default.


These are always available, and are part of the native JIRA functionality. For detailed information about their functionality, take a look at the Atlassian documentation here

The Quick Suggest Macros Plugin extends JIRA to include the following advanced macros:
For more details about each, visit the respective section in this doc to see an overview, sample screenshots, and details.

Issue Macro

The issue macro creates more detailed links to your JIRA issues.

The default JIRA issue link is in the form of [ABC-1], and only shows the issue key as the link. Quite frequently however, it can be useful to include additional fields in the link like current assignee, or status, or due date. The issue macro allows you to do just that.

The syntax for the issue macro is:

{issue:key=ABC-1|fields=summary,assignee,status}

Where key represents the issue key to link to, and fields represents the issue fields to show in the link.

The issue macro allows you to show any of the standard JIRA issue fields.


Note: custom fields, and fields added by 3rd-party plugins are currently not supported. If there is a particular field that you feel is missing and should be added, let us know at support@tss.io

The following are a few samples of the issue macro, along with how they are configured, and what the end result looks like.

Simple Issue Macro without any additional fields

{issue:key=ABC-1}
Issue Macro with summary, issue type, priority, status, and resolution

{issue:key=ABC-1|fields=summary,issueType,priority,status,resolution}
Issue Macro without the key, but with the summary, assignee, and status

{issue:key=ABC-1|fields=-key,summary,assignee,status}
Issue Macro with assignee, time remaining, due date, and fix versions

{issue:key=ABC-1|fields=assignee,timeRemaining,dueDate,fixVersions}
Issue Macro with summary, time estimated, components, and labels

{issue:key=ABC-1|fields=summary,timeEstimated,components,labels}
The same macros as above, within other text

Note: the issue macro automatically shows the issue key.
You can hide the issue key by specified "-key" as one of the fields.
If you do that, it will automatically show the summary, even if it isn't specifically listed. This is to prevent instances where an issue link could be empty, and thus confusing to the end-user.

To make adding an issue link easier, the autocomplete dialog supports a lookup on the issue key, and tracks the available fields that can be listed.
When entering the key, JIRA is queried for matches based on the key or the text you enter. Simply select the issue you want to link to, and the key will automatically be inserted into the macro.
Here is an issue macro being added via autocomplete:

Issue List Macro

The issuelist macro inserts a list of issues wherever the macro is placed, making it easy to dynamically reference other issues in bulk based on an existing JIRA filter, or JQL query.
The list is loaded dynamically every time the page is loaded, and thus always contains the latest issues matching your search criteria.
Visually, the Issue List is like a set of individual Issue Links, and allows for the same definition of which fields to show.

The end result looks like this:

By default, each issue link is rendered on a separate row. For added flexibility, you can change it to render the issue links as combined rows like this:



Do note however that depending on how many fields you include on each issue link, it might require too much space, and end up showing separately anyways becaus of line breaks.

The syntax for the issue list macro is:

{issuelist:filter=10000|fields=issueType,assignee}

{issuelist:jql="project = ABC and priority = Major"|fields=issueType,assignee|inline=true|title=Major Tickets}

The allowable fields are the same as the issue macro supports.
The title is optional, and if provided will be displayed above the list of issues.

The autocomplete dialog will automatically show you your available filters and fields to select. Due to some limitations with the JIRA API, the available filters will not include the "My Open Issues" and "Reported By Me" default filters.

When using a JQL query, you can either write it yourself, or copy/paste one from the advanced JIRA search screen. After typing the JQL query, if you want to resume with the autocomplete dialog, simply type a pipe (|) and the dialog will trigger again and continue with the next available issue list option.

Some of the common uses for the issue list include overviews and reviews, specifications, or epics that reference many other issues based on labels, or priority, or other dynamic criteria.

Issue Table Macro

The issue table macro inserts a table of issues wherever the macro is placed. The table supports showing issues based on existing JIRA filters, or custom JQL queries, making it ideal to dynamically reference other issues in bulk based on your own criteria. The contents of the table are reloaded every time the page is refreshed, and thus always reflects the latest issues matching your query.

Just like the issue macro and the issue list, the issue table allows definining which issue fields should be displayed. The major difference to the other two issue related macros is that the issue table provides separate columns for each issue field, as well as a convenient inline search, to allow users to filter the table to quickly find any issue.

As with the issue list, the issue table allows for an optional title can be provided for the table, which will show above the issue rows.

The syntax for the issue list macro is:

{issuetable:filter=10000|fields=issueType,assignee}

{issuetable:jql="project = ABC and priority = Major"|fields=issueType,assignee|inline=true|title=Major Tickets}

The allowable fields are the same as the issue macro supports.
The title is optional, and if provided will be displayed above the list of issues.

The autocomplete dialog will automatically show you your available filters and fields to select. Due to some limitations with the JIRA API, the available filters will not include the "My Open Issues" and "Reported By Me" default filters.

When using a JQL query, you can either write it yourself, or copy/paste one from the advanced JIRA search screen. After typing the JQL query, if you want to resume with the autocomplete dialog, simply type a pipe (|) and the dialog will trigger again and continue with the next available issue table option.

Some of the common uses for the issue table include overviews and reviews, specifications, or epics that reference many other issues based on labels, or priority, or other dynamic criteria.

Icon Macro

The icon macro provides over 150 icons for you to use in your JIRA issues.
They can be shown within your text in one of two sizes, and can be used for providing visual aid and other indicators.

The syntax for the icon macro is:

{icon:type=approve|size=large}

Where type determines which icon to show, and size determines the size of the icon.
The default size is "small", and doesn't have to be included in the macro definition.

Here are a few different icons definitions and what they look like:

{icon:icontype=approve}
{icon:icontype=comment}
{icon:icontype=calendar}
{icon:icontype=star}


Icons don't cause any line breaks within your text, and thus render nicely within descriptions or alongside headers.

When using the autocomplete dialog to add an icon, you can search for icons based on their name, and see a preview of all the icons right inside the dialog.

Status Macro

The status macro allows showing simple colored status badges within your JIRA issues.



The status renders alongside other text without a line break, and can thus be easily placed alongside other markup, like bulleted lists and headers. Just like typical JIRA status indicators, the status macro will automatically convert the status text to all caps.

Statuses have 6 different types, (which indicate the color), and can be either solid or see-through.

The syntax for the status macro is:

{status:type=success|solid=true}DONE{message}

Where type represents one of 6 different types, and determines the color, and solid determines whether the status should be solid or see-through.

Note: The status macro currently only allows for plain text to placed inside of it. Adding any other macros, user mentions, or issue links inside of a statuc macro will simply render them as text.

Message Macro

The message macros allow you to place colored messages inside your JIRA issues, which are ideal to communicate announcements, events, or other important information.

They come in different types, each of which brings with it a different background color and icon. Messages can be combined with other macros, to embed additional icons, tables, or even text expanders, in case you have a large message.

Messages can have a title, a message body, a type (which determines the color and icon), and an indicator whether the message should be solid or see-through.

The syntax for the messages macro is:

{message:type=success|title=hello world} Your Message Goes Here {message}

There are 4 types of messages, each of which has it's own color and icon. Solid messages show with the entire message body colored in, while see-through messages show with a colored strip on the left side.

success : green color with a checkmark icon
hint : blue color with an info icon
warning : yellow color with a warning icon
error: red color with an exclamation mark icon

The title of the message is optional, and if none is supplied, it will simply render the message body only.
Unlike the status macro, the message macro allows you to place other macros and markup inside of the message body.

Expander Macro

The expander macro wraps other content within an issue field or comment, and automatically collapses the text, and shows an "expand" link.

The syntax for the expander macro is:

{expander}
   your text and other macros go here
{expander}


There are no additional options for it.

Some of the typical uses for this include:

Lorem Ipsum Macro

The lorem ipsum macro simply adds a "lorem ipsum" text where the macro is placed.

It turns this:

{loremipsum}

Into this:

There are no additional options for it.

The main use for this would be dummy data for testing and placeholders.

Localization

Currently, only English is supported.

Russian and German language localization are coming soon.

Terms / Glossary

Macro

Macros are part of JIRA's Wiki Markup, and allow inserting addititional functionality or content into JIRA issues beyond the typical text formatting.
Macro refers to any built-in JIRA macro as well as advanced macros added by the Quick Suggest Macros plugin

Issue Link

An Issue Link allows you reference another issue via the issue key. Typically, issue keys use bracket notation [ABC-1], and only show the issue key as the link. Advanced issue links (one of the macros in the Quick Suggest Macros Plugin) allows you to define which fields (summary, status, assignee, ...etc) should show for an issue link.

Issue List

Issue List refers to the {issuelist} macro, which allows showing a list of multiple issues, based on an existing JIRA filter, or JQL Query. Like the advanced issue link, you can define which field should show.

Issue Table

Issue Table refers to the {issuetable} macro, which allows showing a table of issues, based on an existing JIRA filter, or JQL Query. You can define which issue fields should show as columns.

JIRA Filter

JIRA allow you to perform complex searches for issues and save them as named filters, so you can easily return back to your search without having to go through all the steps again.
Filters can be shared with other users, and are needed for some of the dashboard widgets and other JIRA functionality. For more details, see the Atlassian Documentation

JQL Query

JQL stands for JIRA Query Language, and allows for advanced searches of JIRA issues for any issue field.
For more details on how to use JQL, take a look at the Atlassian Documentation

Licensing Notice

The Quick Suggest Macros Plugin for JIRA add-on contains some code that covers this license:

Copyright (c) 2013, Atlassian Pty Ltd
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.