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 2import { 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.
1 2export 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 }
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. |
Any non 200 response status will result in the function throwing MigrationAPIError
. You can handle it like so:
1 2import { 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: