Forge migration API

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

NameTypeDescription
transferIdstringAn ID (UUID) that the app migration platform uniquely generates per migration.
keystringAn ID (UUID) to uniquely identify the data your server app uploads to cloud storage.
namespacestringMapping namespace to fetch mappings for.
containerTypestringType of container, valid values are ConfluenceSpace, JiraProject, Site.
keysArray<string>List of server keys to query for.
messageIdstringAn ID (UUID) to uniquely identify Forge event for the app migration platform.
logMessagestringMessage 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')
            }
        })
}

Rate this page: