Data transformers

Data transformers are a powerful feature of the app migration platform that help reduce the transformation effort required during app migrations. By leveraging transformers, you can offload common data transformation tasks from your app to the migration platform, making migrations more efficient and reliable.

Overview

Data transformers work with specific Forge Storage data planes to automatically transform your app data during the migration process. The platform currently supports transformers for:

• Key-Value Store
• Custom Entity Store

Transformers are executed as part of the migration pipeline, ensuring reliable and scalable data processing.

How transformers work

When exporting data using the Key-Value Store or Custom Entity Store data planes, you can specify transformers to be applied to your data by including them in the transformers parameter. The platform will:

1. Process your exported data through the specified transformers
2. Apply transformations in the order you specify (though Atlassian reserves the right to modify the order if required)
3. Store the transformed data in the destination Forge Storage

Available transformers

MriIdMapping

The MriIdMapping transformer solves the ID mapping problem through simple string replacement. It uses as a marker Migration Resource Identifiers (MRI) to update references to migrated entities.

How MriIdMapping works

The transformer looks for strings in MRI format within your data and replaces them with the corresponding cloud IDs. For example:

• Server reference: {mri:v1:mig:jira/classic:project:123}
• After transformation: 456 (the corresponding cloud ID)

For the transformer to work, it's imperative that all your exported data that requires transformation has been marked with MRI's.

MRI format

MRI (Migration Resource Identifier) uses the following format:

1
2
{mri:<version>:mig:<namespace>:<server-id>}

However, we recommend using the provided helpers to generate MRI strings, as they ensure the correct format and versioning. The MRI format is designed to be stable and consistent across migrations.

Helper available on atlassian-app-cloud-migration-listener:1.7.1 and later:

• com.atlassian.migration.app.gateway.AppCloudForgeMigrationGateway#convertIdToMappingId

Supported entities

The MriIdMapping transformer supports the entities listed in the mappings namespaces and entities documentation.

Use cases

MriIdMapping is particularly useful for:

• Custom entities that reference Jira issues, Confluence pages, or other migrated entities
• Unstructured data that contains entity references
• Configuration data that includes references to cloud migrated entities

Code example

Here's how to use transformers with the Key-Value Store:

1
2
// Configure parameters with MriIdMapping transformer
List<String> transformers = Arrays.asList("MriIdMapping");
KeyValueParameters parameters = new KeyValueParameters("my-forge-custom-entity", true, transformers);

// Prepare data with MRI references
Map<String, String> kvs = new HashMap<>();
kvs.put("config", "{\"defaultIssue\": " + gateway.convertIdToMappingId("jira:issue", "001") + "}");
kvs.put("settings", "{\"linkedPage\": " + gateway.convertIdToMappingId("confluence:page", "002") + "}");

// Send data for transformation and posterior ingestion
gateway.sendKeyValuePair(kvs, parameters);
gateway.completeExport();