SPI Tools for dashboards

Available since SPI tools version 1.2.0

On this page:

1 SPI Tools API reference
2 Usage
3 Unhandled arguments
4 Error handling

SPI Tools API reference

If you need more technical information on the latest SPI Tools packages, please read the complete API reference.

Usage

Dashboard gadgets may have preferences that hold identifiers of different configuration elements in Jira. When these gadgets are moved from one instance of Jira to another, those identifiers will most likely differ. It is also possible that the referenced configuration element may not even exist on the Jira instance where the Configuration Manager snapshot is being deployed. Let's take a look at an example of how to describe such preferences using SPI Tools, which will allow Configuration Manager to take care of all the hard work of creating the configuration elements and storing the correct identifiers or names.

The first thing we need to do is extend the AbstractDashboardGadgetHandler class from SPI Tools and implement describeUserPreferences(). This is an abstract implementation of DashboardGadgetHandler, which provides the DSL for describing user preferences.

@Override
protected void describeArguments() {
    gadget("rest/gadgets/1.0/g/com.atlassian.jira.gadgets:pie-chart-gadget/gadgets/piechart-gadget.xml").
        hasMultiValueUserPreference("statusIds").ofType(UserPreferenceType.STATUS).byId().
            .withSeparator(",").withLiteralValues("none").and().
        hasSingleValueUserPreference("user").ofType(UserPreferenceType.USER).byKey().and().
        hasSingleValueUserPreference("filterId").ofType(UserPreferenceType.SEARCH_REQUEST).byId().withPrefix("filter-");
}

In the example above, we instruct Configuration Manager that there is a gadget with URI "rest/gadgets/1.0/g/com.atlassian.jira.gadgets:pie-chart-gadget/gadgets/piechart-gadget.xml" and it has two user preferences:

statusIds, which holds a comma-separated list of status identifiers and can also hold the value "none," which must be treated as a literal and not as a status identifier.
user which holds the key of a user in Jira.
filterId, which holds the id of a saved filter, prefixed by the string “filter-.”

Configuration Manager will take care of parsing the user preference values on export and re-constructing them on import. Notice the usage of and() to chain the syntax declaration for the different arguments.

The last step is to declare the class in the atlassian-plugin.xml. For more details, you can check out the Via atlassian-plugin.xml section on the Dashboards SPI page.

Unhandled arguments

If you need specific handling for a given argument, you can always override the transformUnhandledUserPreferencesForExport() and transformUnhandledUserPreferencesForImport() methods.

Error handling

The method handleError() will be invoked for any exception caught during a transformation of user preferences. The default implementation will simply log the error. In this case, the untransformed value will be used for this user preference.