Key-Value Store & Custom Entity Store

Alternatively to the unopinionated data upload provided by the App Migration Platform, you can use a feature that's tailored for Key-Value & Custom Entity Store.

That allows the values to be exported without the introduction of an intermediate format, and moreover, enables two important facilitations: auto-import on Forge Storage, and opt-in data transformations.

Auto-import on Forge Storage

While supplying KeyValueParameters to the sendKeyValuePair() method, you can set the property importOnForgeStorage=true. That will instruct the App Migration Platform to automatically import the data into the Key-Value Store or Custom Entity Store in Forge Storage for the respective app installation.

In case you don't opt to use the Auto-import feature (importOnForgeStorage=false), your Forge app will be responsible to perform the data ingestion and subsequently acknowledge the payload with messageProcessed(transferId, messageId), just like with the unopinionated data upload.

Data Transformations

The App Migration Platform now supports data transformers that can automatically transform your data during the migration process. This significantly reduces the transformation effort required from app vendors.

The first available transformer is MriIdMapping, which handles ID mapping by replacing Migration Resource Identifiers (MRI) with their corresponding cloud IDs. For example, {mri:v1:mig:jira:issue:001} would be replaced with the actual cloud issue ID.

To use transformers, include them in the transformers parameter when calling sendKeyValuePair():

1
2
List<String> transformers = Arrays.asList("MriIdMapping");
KeyValueParameters parameters = new KeyValueParameters("my-entity-name", true, transformers);

For detailed information about available transformers and how to use them, see Data transformers.

Code example (Key-Value Store)

1
2
KeyValueParameters parameters = new KeyValueParameters(null, true); // Leaving the first parameter (entityName) null indicates that the values should be stored on the global schema.

Map<String, String> kvs = new HashMap<>();
kvs.put(entityKey1, entityValue1);
kvs.put(entityKey2, entityValue2);
kvs.put(entityKey3, entityValue3);
gateway.sendKeyValuePair(kvs, parameters);

gateway.completeExport();

Code example (Custom Entity Store)

1
2
KeyValueParameters parameters = new KeyValueParameters("my-entity-name", true); 

Map<String, String> entities = new HashMap<>();
entities.put(entityKey1, entityValue1);
entities.put(entityKey2, entityValue2);
entities.put(entityKey3, entityValue3);
gateway.sendKeyValuePair(entities, parameters);

gateway.completeExport();

Code considerations

You can invoke the method sendKeyValuePair() as many times as you need, and they may or may not be used in combination with different KeyValueParameters.

The maps can be of any size, however the migration platform will group the items in workable sizes (approximately 240KB each).

Atlassian Connect Support

Since in Atlassian Connect apps the destination of the exported data might be outside Atlassian's cloud, the auto-import feature won't be available for those apps.

However, Atlassian Connect apps can still be notified about key-value pairs upload through the event avi:ecosystem.migration:uploaded:key_value_pair and retrieve the data for their own consumption through the App data retrieval API

Have your say

We want to make the most out of the EAP and would love to hear your feedback on this feature. Please fill out this form to share your thoughts, suggestions, or any issues you encounter while using the Key-Value Store and Custom Entity Store in the App Migration Platform.