Integrate Server Apps with Server SPI

Owned by Rosen Marinkov
Last updated: May 04, 2023
3 min read

Who can use this information?

Follow these instructions if you’re an app vendor, developer, or Jira user integrating a Jira Server or DC app with Configuration Manager for Jira (CMJ) through the Service Provider Interface.

 

On this page:

API Reference

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

Integrate your server app with the Server SPI

The SPI for Jira Server/DC is a set of REST interfaces implemented by server apps and invoked by Configuration Manager for Jira/Cloud Migration Tool during migration when app data is found.

Throughout our documentation, we will refer to the SPI for CMJ Server as Server SPI or CMJ Server SPI.

To implement the Server SPI, follow these steps:

  1. Initial setup of the Server Service Provider Interface (SPI).

  2. Implement app-specific REST endpoints of the Server SPI.

Step 1: Initial SPI setup

This part aims to guide you through the initial setup of the Service Provider Interface (SPI).

  1. Аdd the SPI as a maven dependency in your pom.xml:

    <!-- CMJ SPI library --> <dependency> <groupId>com.botronsoft.cmj.spi</groupId> <artifactId>configuration-manager-spi</artifactId> <version>${cmj.spi.version}</version> <scope>provided</scope> </dependency>

     

  2. You need to add the SPI package dependency:

    <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>

  3. 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+, you also need to add the instruction “!com.botronsoft.cmj.spi.*” to Import-Package.

Step 2: Implement app-specific SPI endpoints

Next, implement the SPI Endpoints from the list below for the types of configurations your app includes. For example, if your app deals with workflows or modifying workflows in Jira, you will need to implement the Workflows SPI Endpoints.

Server SPI Endpoints

Custom Fields

Custom fields with specific configuration provided by the app.

Workflows

Custom conditions, validators, and post-functions, provided by the app.

Project Configuration and Data

App configuration attached to a project.

App Data

App data which is not attached to a Jira object (project, custom field, workflow, etc.). Use this endpoint when the app data does not fit any of the boundaries of existing Jira objects and extend standard Jira functions.

Using this endpoint, you can enumerate the types of app data that can be migrated and the different objects of each type that exist on the Jira instance.

ScriptRunner example

The ScriptRunner app provides functions such as:

  • Listeners, which are “listening” for a specific event and triggering an action, and,

  • Behaviors customizing how fields “behave” based on the context, etc.

This type of app functionality is not categorized and guided by the Jira application development platform. Yet, the App Data SPI endpoint provides the tools to move such configuration between different Jira instances.

Dashboards

Custom dashboard gadgets provided by the app.

App’s Global Configuration

The global configuration of the app, not specific to any project or other Jira object.

License

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