Forge migration API | App migration platform

Forge migration API helps you migrate your server app using your Forge app.

Import the migration API package and use its methods, for example:

1
2
import { migration } from "@forge/migrations";

export function getMigrationMappings() {
  return migration
    .getMappings(transferId, "jira/classic:appCustomField")
    .getMany(); // => {"results":[{"key":"10004","value":"10011"}, ...]}
}

The migration object contains helper functions to conduct your app migration e.g. retrieve mappings and app data.

Method signature

1
2
export interface Migration {
    getMappingById: (transferId: string, namespace: string, keys: Array<string>) => Promise<MappingResponse>;
    getAppDataList: (transferId: string) => Promise<AppDataListResponse>;
    getAppDataPayload: (key: string) => Promise<APIResponse>;
    messageProcessed: (transferId: string, messageId: string) => Promise<void>;
    getMappings: (transferId: string, namespace: string) => DefaultQueryBuilder;
    getContainers: (transferId: string, containerType: string) => DefaultQueryBuilder;
    addLog: (transferId: string, logMessage: string) => Promise<void>;
}

export interface MappingResponse {
    result: Map<string, string>;
}

export interface AppDataListResponse {
    result: Set<AppData>;
}

export interface AppData {
    s3Key: string;
    key: string
    label: string;
}

export declare type APIResponse = Pick<Response, 'json' | 'text' | 'arrayBuffer' | 'ok' | 'status' | 'statusText' | 'headers'>;

export interface DefaultQueryBuilder {
    limit(limit: number): DefaultQueryBuilder;
    cursor(cursor: string): DefaultQueryBuilder;
    getOne(): Promise<Result | undefined>;
    getMany(): Promise<ListResults>;
}

export interface Result {
    key: string;
    value: object;
}

export interface ListResults {
    results: Result[];
    nextCursor?: string;
}

export class MigrationAPIError extends Error {
    status: number | undefined
    message: string
}

Parameters

Name	Type	Description
`transferId`	`string`	An ID (UUID) that the app migration platform uniquely generates per migration.
`key`	`string`	An ID (UUID) to uniquely identify the data your server app uploads to cloud storage.
`namespace`	`string`	Mapping namespace to fetch mappings for.
`containerType`	`string`	Type of container, valid values are `ConfluenceSpace`, `JiraProject`, `Site`.
`keys`	`Array<string>`	List of server keys to query for.
`messageId`	`string`	An ID (UUID) to uniquely identify Forge event for the app migration platform.
`logMessage`	`string`	Message to display to customers that will be visible in progress logs.

Error handling

Any non 200 response status will result in the function throwing MigrationAPIError. You can handle it like so:

1
2
import { migration, MigrationAPIError } from '@forge/migrations'

function getMigrationMappings() {
    return migration.getMappings(transferId, namespace)
        .getMany()
        .catch((error) => {
            if (error instanceof MigrationAPIError && error.status !== undefined) {
                console.error('Unexpected status code', error.status)
            } else {
                console.error('Something went wrong')
            }
        })
}