Service Provider Interface

On this page:

 

The information presented in this section is intended for app vendors integrating their apps with Configuration Manager through the Service Provider Interface.

Introduction

Configuration Manager is designed to enable admins to seamlessly capture and move the entirety of their Jira configuration and data between instances. The snapshots, both project & system, ensure that neither the configuration nor the data contained within will be compromised during the migration process. The deployment is executed in a protected transaction with a built-in rollback mechanism, which ensures your production system is protected at all times. Learn more about Configuration Manager’s configuration deployment features.

The data capturing capabilities of the Configuration Manager allows admins to quickly capture and transfer a diverse set of Jira configuration and data, including third-party apps and new custom field types.

Purpose

The Jira platform's powerful extension model has lead to the emergence of hundreds of apps that augment Jira's functionality in various ways. Often these apps store configuration and data, which is an essential part of the processes implemented in Jira. Configuration Manager has been built to support seamless migration of Jira configuration and data between instances, and to support the same level of consistency, integrity, and ease of use for app data, we introduce the Configuration Manager Service Provider Interface (SPI). This interface provides the tools necessary for moving app configuration and data between different instances of Jira.

The configuration may be arbitrary but may also contain references to other configuration elements in Jira (priorities, resolutions, custom fields, filters, etc.). The SPI provides the means for collecting such references on the source instance and properly resolving them on the target instance. The diagram below illustrates the collect-and-resolve process.



Get Started

The first step is to add the SPI as a maven dependency in your pom.xml:

1 2 3 4 5 6 7 <!-- CMJ SPI library --> <dependency> <groupId>com.botronsoft.cmj.spi</groupId> <artifactId>configuration-manager-spi</artifactId> <version>${cmj.spi.version}</version> <scope>provided</scope> </dependency>

Then, a dependency on the SPI package is needed:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 <build> <plugins> <plugin> <groupId>com.atlassian.maven.plugins</groupId> <artifactId>maven-jira-plugin</artifactId> <version>${amps.version}</version> <configuration> ..... <instructions> <DynamicImport-Package> com.botronsoft.cmj.spi.*;version="${cmj.spi.version}";resolution:=optional, </DynamicImport-Package> <Import-Package> .... !com.botronsoft.cmj.spi.*, .... </Import-Package> </instructions> ..... </configuration> </plugin> </plugins> </build>

 

Set the Maven property cmj.spi.version to the lowest possible version of the SPI - for example, 1.0.0. Increment the version when you need new features of the SPI. This will ensure compatibility with a large set of Configuration Manager releases, as older releases come with an older version of the SPI. There is no need to compile to a newer version unless you need some new features, as the SPI is backward compatible.

DynamicImport-Package Usage

Important

Make sure that DynamicImport-Package is used instead of Import-Package otherwise, the SPI-related packages may not be correctly resolved at runtime.

If building with Atlassian SDK 8.0.0+, the instruction “!com.botronsoft.cmj.spi.*” also needs to be added to Import-Package.

 

SPI Interfaces

Next, implement any of the SPI interfaces to support your configuration and data:

Custom Fields

Workflows

Project Configuration and Data

Dashboards

Global Configuration

License

The Configuration Manager SPI is licensed under the Creative Commons license (CC BY 4.0).