Page Comparison

...

SPI API reference

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

Get

...

started

This integration endpoint is designed for apps that provide new custom field types via the customfield-type module.

...

The custom field SPI endpoint will assure ensure the custom field integrity is intact since the IDs of such referenced objects will be different differ between instances of Jira.

Apps do not need to implement this endpoint for custom field types, which:

• implement MultipleSettableCustomFieldType

• or store data, which does not contain references to other objects and does not need to change between instances of Jira

In both cases above, Configuration Manager for Jira will automatically take care of such custom field values.

CustomFieldDataHandler

The SPI for custom field data consists of only one interface - com.botronsoft.cmj.spi.issue.CustomFieldDataHandler.

...

This interface has one type parameter that should be set to the same class, which . This class is used for the implementation of implementing the CustomFieldType interface and is defined as the Transport Object type. If this is a multi-valued field type, T should be set to the collection, which defines the Transport Object.

...

• transformIssueValueForExport - a project with issues is exported on the source system and there is a stored issue value for the field of the registered custom field type. The method will receive the custom field, issue, and value as parameters.

• transformChangeLogValueForExport - a project with issues is exported on the source system and there is stored value for the field of the registered custom field type in the issue history (changelog). The format of this value may be different than the one used for issue value, and that’s why a separate SPI method is needed. The parameters parameter's value and valueString represent the value as stored in the changelog (see getChangelogString and getChangelogValue).

• transformIssueValueForImport - a project with issues is imported into the target system. This method will receive the value as String and must return a Transport Object. The same method is invoked when importing history data.

If any of those methods return an empty java.util.Optional, the field value will be transferred as is.

Configuration

...

serialization and

...

versioning

The SPI does not impose any restrictions on how the custom field value is serialized, only that the result should be a String (see the return value of method transformIssueValueForExport and transformChangeLogValueForExport). 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 method transformIssueValueForImport).

...

Collect references

Custom field values may contain references to configuration elements - either standard Jira configuration such as fields, custom field options, saved filters, etc., or custom configuration provided by the app and handled by some of the Configuration SPI endpoints.

...

Collect references to standard Jira configuration elements

Configuration Manager must be notified about all references to standard Jira configuration elements during export because:

• Configuration Manager must include these elements in the snapshot.

• The IDs of these elements may be different differ between the source and target instance and instances, but Configuration Manager will match them and provide the correct IDs during import.

Collecting all references can be achieved by invoking the methods of the ConfigurationReferenceCollector interface, accessible via the IssueExportContext interface. The key must be a unique identifier that will be used when importing the issue data 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.

...

Collect references to app configuration elements

The custom field values may also contain references to a configuration that is specific to the app and is handled by some of the Configuration SPI endpoints. There is no need to collect these references in this case, as the app itself will migrate them, but care must be taken to resolve them correctly when the values are being imported. More information on this is available in the next section.

...

Resolve references

When a snapshot is being deployed, all collected references to other configuration elements (either standard or custom) must be resolved , because the identifiers of these elements are most probably different on the target system.

...

Resolve references to standard Jira configuration elements

Use the ConfigurationReferenceLookup interface, accessible via the IssueImportContext 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.

...

Resolve references to app configuration elements

Use the AppMappingContext to lookup look up and resolve the IDs of the app-specific configuration elements that have been created as part of the import by any Configuration SPI endpoints. More information on using the AppMappingContext can be found in Share references between SPI handlers.

...

Register the

...

handler with Configuration Manager

There are two options for registering the handler with Configuration Manager:

Via Java annotations

...

Only one entry is needed per app - multiple packages may be defined if needed. The necessary. Configuration Manager will scan 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 <customFieldDataHandler> tag and the attributes below.

The configuration needed in atlassian-plugin.xml is fairly simple - create a <customFieldDataHandler> tag and the attributes below. Only one custom field data handler per custom field type is allowed.

<!-- Configuration Manager SPI -->
<customFieldDataHandler
      name="Configuration Manager SPI Implementation"
      key="my-app-custom-field-data-handler"
      typeKey="com.mycompany.appkey:custom-field-type-key"
      class="com.mycompany.app.CustomFieldDataHandlerImpl"/>

Here is the list of supported attributes:

name

key

typeKey

class