Dashboards SPI

On this page:

1 SPI API reference
2 Get started
3 DashboardGadgetHandler
4 Configuration serialization and versioning
5 Collect references
6 Resolve references
7 Registering the Handler with Configuration Manager

SPI API reference

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

Get started

The Jira application development platform allows applications to introduce dashboard gadgets and dashboard items via the gadget and dashboard item modules. Each dashboard gadget or item may store an arbitrary configuration in the form of key-value pairs. The Service Provider Interface for dashboard gadgets provides the facilities for moving such configurations between different Jira instances. Configuration Manager will handle all the heavy load around moving the right configuration elements which are referenced in the properties of а dashboard gadget - for example, custom fields, users and groups, etc.

This integration point is available since SPI version 1.3.0

DashboardGadgetHandler

The SPI for dashboard gadgets consists of only one interface - com.botronsoft.cmj.spi.configuration.gadget.DashboardGadgetHandler.

/**
 * Implement this interface to handle export/import of user preferences in a dashboard gadget or item.
 */
@PublicSpi
public interface DashboardGadgetHandler {

	/**
	 * Invoked when a configuration is being exported. This method will be called by Configuration Manager for each dashboard gadget or item
	 * which is handled by this handler.
	 * <p>
	 * Implementers may call {@link com.botronsoft.cmj.spi.configuration.ConfigurationReferenceCollector} methods to handle references to
	 * other configuration objects.
	 *
	 * @param uriOrModuleKey
	 *            the URI of the currently exported dashboard gadget or the module key of the currently exported dashboard item
	 * @param userPreferences
	 *            a map of user preferences that are configured for the currently exported dashboard gadget.
	 * @param exportContext
	 *            the context of the export operation.
	 * @return a map of the transformed user preferences - these can be the same user preferences which were passed to this method or
	 *         enhanced set of user preferences. This map will be passed to
	 *         {@link #transformUserPreferencesForImport(String, Map, ImportContext)} when the configuration is being deployed.
	 * @see ExportContext
	 */
	Map<String, String> transformUserPreferencesForExport(String uriOrModuleKey, Map<String, String> userPreferences,
			ExportContext exportContext);

	/**
	 * Invoked when a configuration is being imported. This method will be called by Configuration Manager for each dashboard gadget or item
	 * which is handled by this handler.
	 * <p>
	 * Implementers can call {@link com.botronsoft.cmj.spi.configuration.ConfigurationReferenceLookup} methods to retrieve the respective
	 * matching configuration objects referred with {@link com.botronsoft.cmj.spi.configuration.ConfigurationReferenceCollector}.
	 *
	 * @param uriOrModuleKey
	 *            the URI of the currently exported dashboard gadget or the module key of the currently exported dashboard item
	 * @param userPreferences
	 *            the map which was returned by the invocation of {@link #transformUserPreferencesForExport(String, Map, ExportContext)}.
	 * @param importContext
	 *            the context of the import operation.
	 * @return a map of the transformed user preferences - these are the user preferences that will be effectively stored for the
	 *         corresponding dashboard gadget.
	 * @see ImportContext
	 */
	Map<String, String> transformUserPreferencesForImport(String uriOrModuleKey, Map<String, String> userPreferences,
			ImportContext importContext);

}

The different methods of this interface will be invoked by Configuration Manager when:

The configuration for a dashboard gadget or item is exported on the source system - this happens when a snapshot is created.
The configuration for a dashboard gadget or item is imported into the target system - this happens when a snapshot is being deployed and a new dashboard is created or an existing one is being updated.

Each dashboard gadget is uniquely identified by its URI, which will be provided as a first argument to the methods for export and import.

Each dashboard item is uniquely identified by its module key, which will be provided as a first argument to the methods for export and import.

The configuration for each gadget or item is stored in Jira as a key-value property map. This key-value property map can be moved by Configuration Manager as is, or apps may choose to transform these properties and/or store additional data if needed.

Configuration serialization and versioning

The SPI does not impose any restrictions about how the configuration in each property value is serialized, only that the end result should be a String.

When you are implementing the SPI, it is very important to think about configuration versioning in advance. Consider the following situation - source Jira has version 1.2 of your app, while target Jira has version 1.3 and there is a change in the number and/or semantics of stored configuration properties (the key-value map). To ensure smooth user experience, make sure the SPI implementation in your app is backwards compatible with previous versions.

Collect references

Each property (key-value pair) may contain references to other configuration elements in Jira, such as custom fields, saved filters, etc. It is important that during export, Configuration Manager is notified about these references because the IDs of these elements may be different between the source and the target instance, and Configuration Manager will match them and provide the correct IDs during import.

This can be achieved by invoking the methods of the ConfigurationReferenceCollector interface, accessible via the ExportContext interface. The key must be a unique identifier, which will be used when importing the configuration to resolve the reference on the target instance. The keys need to be unique only within the type of the configuration element - i.e. you can use the same key for a resolution or a status. In this sense, the Jira internal identifiers can be used as keys as well.

Resolve references

When deploying a snapshot, all collected references to other configuration elements must be resolved, because the identifiers of these elements are most probably different on the target system.

Use the ConfigurationReferenceLookup interface, accessible via the ImportContext interface. It provides convenient methods for resolving references by the same keys which were provided when collecting these references. The methods return java.util.Optional, because, in certain situations, references may be unresolvable. SPI implementations should be developed to handle this possibility.

Registering the Handler with Configuration Manager

There are two options for registering the handler with Configuration Manager:

Via Java annotations

Registering the handler with Configuration Manager via Java annotations is available since SPI version 1.7.0.

Annotate the handler class with the ConfigurationManagerSpiHandler annotation and the HandlesDashboardGadget or HandlesDashboardItem annotations, providing the gadget URI or item key respectively:

@ConfigurationManagerSpiHandler
@HandlesDashboardGadget(
		URI = "rest/gadgets/1.0/g/com.mycompany.app:sample-jira-gadget/gadgets/sample-jira-gadget.xml")
@HandlesDashboardItem(key = "com.mycompany.app:sample-jira-dashboard-item")
public class SampleAnnotatedDashboardGadgetHandler implements DashboardGadgetHandler {
...
}

In addition, the following entry needs to be added to the atlassian-plugin.xml which specifies the Java packages which contain the handlers:

<!-- Configuration Manager SPI Handler Packages -->
<configurationManagerSpiHandler key="configuration-manager-spi-handler-packages">
  <package>com.mycompany.app.handlers</package>
</configurationManagerSpiHandler>

Only one entry is needed per app - multiple packages may be defined if needed. The classes in these packages will be scanned by Configuration Manager for the SPI annotations.

Via atlassian-plugin.xml

Another approach is to declare the handler in atlassian-plugin.xml directly - create a <dashboardGadgetHandler> tag with the attributes and elements below.

Here is the list of supported attributes:

Attribute	Purpose

Attribute

Purpose

The unique key of the SPI implementation.

Required: yes

The implementation class - must extend the com.botronsoft.cmj.spi.configuration.gadget.DashboardGadgetHandler interface.

Required: yes

Here is the list of supported elements:

Element	Purpose

Element	Purpose
	The URI of the dashboard gadget which is managed by this DashboardGadgetHandler implementation. Multiple "gadget" elements may be defined for a single handler. Use this element if your gadget is declared using the gadget plugin module type. Follow these steps to get the proper value to put in the "URI" attribute.

Or:

Element	Purpose

Element	Purpose
	The module key of the dashboard item which is managed by this DashboardGadgetHandler implementation. Multiple "item" elements may be defined for a single handler. Use this element if your gadget is declared using the dashboard-item module type. Follow these steps to get the proper value to put in the "key" attribute.

Required: At least one element of one of the two types of elements must be provided.

Get the URI of a dashboard gadget

To get the URI of a dashboard gadget so you can put it in the "URI" attribute of the gadget element, follow these steps:

Install the app which contains the gadget in Jira.
Open a dashboard.
Click the "Add gadget" button.
Find your gadget - there will be a "Show XML link" link, click on it.
The link displayed there minus the hostname is the gadget URI.

For example, for the Pie Chart gadget, the URI is:

So in this example, the dashboardGadgetHandler will look like this:

Get the key of a dashboard item

The key of a dashboard item is a combination of the app key and the dashboard-item key.

For example, if we have the following dashboard-item declaration in atlassian-plugin.xml:

in the app with key com.mycompany.app, the dashboardGadgetHandler will look like this: