Sharing references between SPI handlers

SPI API reference

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

Introduction

More complex apps will need to implement more than one of the SPI interfaces - for example, if an app stores both project-level configuration and issue data or contributes a complex custom field with its own configuration and values. In these cases, there is a need to share the mapping of IDs of objects created by the app during import between the different SPI handlers registered by the app.

AppMappingContext

The AppMappingContext interface is designed to solve this problem. It’s a very straightforward interface that allows an app to record the mappings between a configuration object ID on the source system and the corresponding configuration object ID on the target system after that object is persisted in a configuration SPI handler. Handlers that are invoked later in the chain (e.g., Project Issue Data Handler) can lookup this mapping.

The AppMappingContext implementation can be accessed via ImportContext or IssueImportContext.

Example

To illustrate how this interface can be used, let’s look at a very simple example.

An app stores a set of “categories” per project in Active Objects - each category has its own internal ID. An app provides a custom field that allows users to select and display the category for each issue. The app stores the ID of the selected category as a custom field value.

In this case, the app needs to implement two SPI interfaces:

• The Projects SPI moves the set of categories associated with the project.

• The Custom Field Data SPI moves the values of the fields that show the selected category.

When a snapshot is created

The ProjectConfigurationHandler exports all categories associated with the project. The ID of each category is included in the serialized result.

The CustomFieldDataHandler exports the stored custom field values, each of which contains the ID of the category associated with an issue without any transformation.

When a snapshot is deployed

When the ProjectConfigurationHandler is invoked during import, it will create the categories for the project. These categories will have new IDs on the target system. The handler must record the mapping between the ID on the source system and the ID on the target system using the AppMappingContext instance.

Later, when CustomFieldDataHandler transforms the custom field values for import, it can look up the ID for each category on the target system via the AppMappingContext and use that for the custom field value.