Integrate server apps with Server SPI

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.

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.

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 configurations provided by the app:

• Custom fields SPI

• Custom field data SPI

Workflows

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

• Workflows SPI

• SPI Tools for workflows

Project configuration and data

App configuration attached to a project.

• Project configuration SPI

• Project issue data SPI

App data

App data not attached to a Jira object (project, custom field, workflow, etc.). Use this endpoint when the app data does not fit 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.

• App Data SPI

Dashboards

Custom dashboard gadgets provided by the app:

• Dashboards SPI

• SPI Tools for dashboards

App’s Global Configuration

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

• Global App Configuration SPI

License

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