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
Jira apps may store configuration data that does not belong to any project but applies to all projects - i.e., "global" configuration. The Service Provider Interface for global app configuration provides the facilities for moving such configuration between different Jira instances. Configuration Manager will handle all the heavy load around moving the right configuration elements which are referenced in the global configuration - for example, custom fields, users and groups, etc. When creating a snapshot, users will be allowed to choose whether to include a global app configuration. You can learn more about migrating global app data with CMJ from this document.
...
The SPI for global app configuration consists of only one interface - com.botronsoft.cmj.spi.configuration.global.GlobalConfigurationHandler.
|
Info |
---|
An app may declare only one implementation of this interface. |
...
Info |
---|
Why is the exportConfiguration methodcalled during deployment? A major phase of the deployment process in CMJ is the deep change and impact analysis. To perform it, CMJ compares Jira's configuration between the source and the target instances. The snapshot being imported is a model of the source Jira configuration built at the time when it was exported. So, CMJ creates another model of the target instance by exporting Jira configuration on that instance at the time of the deployment. The exportConfiguration method is called during deployment so that the global app configuration of the apps on the target instance is included in the target instance model and compared to the global app configuration of the apps in the snapshot during the Analyze phase. |
Configuration
...
serialization and
...
versioning
The SPI does not impose any restrictions on how the configuration in each property value is serialized, only that the end result should be a String.
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 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
The global app data may contain references to other configuration elements in Jira, such as custom fields, saved filters, etc. It is essential 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.
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 global app configuration that already exists on the target system and only adds what is new. In restore mode, the whole 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 or via the atlassian-plugin.xml
...
Another approach is to directly declare the handler in atlassian-plugin.xml and create a <globalConfigurationHandler> tag with the attributes below.
|
Here is the list of supported attributes:
Attribute | Purpose | ||
---|---|---|---|
| The unique key of the SPI implementation. Required: yes | ||
| The implementation class - must extend the com.botronsoft.cmj.spi.configuration.global.GlobalConfigurationHandler. Required: yes |