On this page:
|
...
|
SPI API reference
If you need more technical information on the latest SPI packages and interfaces, please read the complete API reference.
Get
...
started
Apps may store configuration configurations that is are associated with a project. The Service Provider Interface for projects provides the facilities for moving such configuration configurations between different Jira instances. Configuration Manager will handle all the heavy load around, moving the right configuration elements which that are referenced in the project configuration - for example, custom fields, users and groups, etc.
Info |
---|
This integration point is has been available since SPI version 1.2.0 |
ProjectConfigurationHandler
The SPI for projects consists of only one interface - com.botronsoft.cmj.spi.configuration.project.ProjectConfigurationHandler.
|
The different methods of this interface will be invoked by Configuration Manager when:
The configuration for a project is exported on the source system - this happens when a snapshot is being created.
The configuration for a project is imported into the target system - this happens when a snapshot is being deployed and a new project is created or an existing one is being updated.
The configuration for a project is deleted - this happens when a project is being deleted, usually when a snapshot is deployed in Restore mode.
Configuration
...
serialization and
...
versioning
The SPI does not impose any restrictions about how the configuration of the project is serialized, only that the end result should be a String (see the return value of method exportConfiguration). Internally you can use XML, JSON, or whatever format is needed, as long as the app can deserialize it when the configuration is imported (see the method importConfiguration).
Warning |
---|
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 semantics of the stored configuration string. To ensure smooth user experience, make sure the SPI implementation in your app is backwards compatible with previous versions. |
...
Collect references
Your project configuration may contain references to other configuration elements in Jira, such as other fields, JQLs, Saved Filters, etc. It is important that during export Configuration Manager is notified about these references during export because the IDs of these elements may be different between the source and target instance and instances. 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, that 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 a snapshot is being deployed, 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 implemented to handle this possibility.
Merge vs
...
restore
Info |
---|
This API is available since SPI version 1.6.1. |
When a configuration is imported, it may be necessary to distinguish between the merge and restore modes in which Configuration Manager operates. In merge mode, a handler may choose to keep the configuration for the project which already exists on the target system and only to add what is new. In restore mode, the whole project configuration may be overwritten. A handler may check the current mode by retrieving the ImportMode value via ImportContext.getImportMode().
...
Register the
...
handler with Configuration Manager
There are two options for registering the handler with Configuration Manager:
Via Java annotations
Info |
---|
Registering the handler with Configuration Manager via Java annotations is available since SPI version 1.7.0. |
...
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 <projectConfigurationHandler> tag with the attributes below.
|
Here is the list of supported attributes:
Attribute | Purpose | ||
---|---|---|---|
name | The name of the SPI implementation. Required: no | ||
| The unique key of the SPI implementation. Required: yes | ||
| The implementation class - must extend the com.botronsoft.cmj.spi.configuration.project.ProjectConfigurationHandler interface. Required: yes |