Last updated Jun 20, 2025

Key-Value Store & Custom Entity Store

This is an experimental feature in Early Access Program (EAP) and is subject to change. In fact, we'd love to hear your feedback on it through the form at the bottom of this page.

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 soon, opt-in data transformations.

Currently this feature is only available for entity schemas created after 20/Jun/2025. Entity schemas are created during app deployment. In future, we will backfill permissions for existing entity schemas.

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.

If the migrated key already exists in the Key-Value Store or Custom Entity Store, it will be overwritten.

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 (upcoming)

In order to reduce the transformation effort in App Migrations, we'll soon be enabling Id Mappings and possibly other transformations as part of the migration pipeline.

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).

Once all data is exported, including the binary data uploaded via gateway.createAppData(), it is important to call gateway.completeExport() to enable progress reporting and to notify the platform that the export is complete.

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.