Prepare your cloud app for Forge migration

This page explains how to prepare your cloud app for migration by processing events.

Events

The Forge function and trigger modules that you implement will allow the app migration platform to send information about specific migration events that take place on your server app.

Add Forge function and trigger to the manifest

Define a function and trigger to process migration events.

See an example

1
2
modules:
  function:
    # Function to handle migration events
    - key: migration-fn-key
      handler: index.run
  trigger:
    # Migration events that will invoke your function
    - key: migration-trigger
      function: migration-fn-key
      events:
        - avi:ecosystem.migration:triggered:listener
        - avi:ecosystem.migration:uploaded:app_data

Our sample app provides a complete implementation.

Refer to the events API for all the events that you can listen for and their associated payloads.

Processing events

When processing events it is important to keep in mind the following:

• Event acknowledgement - you must call messageProcessed(transferId, messageId) for avi:ecosystem.migration:uploaded:app_data events within 15 minutes of either
  • Sending a success message for any event in a migration
  • Uploading new data from the server app.
• Events are not ordered - the platform may send events in a different order e.g. avi:ecosystem.migration:uploaded:app_data may appear before avi:ecosystem.migration:triggered:listener.
• Similarly, apps are not required to acknowledge events in any particular order. If they need to process data in a particular order, they may acknowledge events as processing of the contained data is completed, rather than when the message is received. This is better than acknowledging events as they are received, and then doing lengthy processing at the end, because it avoids timeouts and provides more accurate status information back to customers.
• Validate the event payloads and throw an exception if validation fails - this will help you monitor for failed function invocations and failed function invocations will be retried.

Example timeline for event processing

Event types

You can add the following events to your Forge trigger.

Payload

This is the data that is passed to your Forge function when it is invoked.

Example payload

1
2
{
  "eventType": "avi:ecosystem.migration:uploaded:app_data",
  "transferId": "3f3a47f2-a6a2-4204-84bb-d0fc504c9dc6",
  "migrationDetails": {
    "migrationId": "403c4f71-a0d1-4a63-97a8-487d18691c46",
    "migrationScopeId": "0ba07dd9-3804-4600-9102-fa6e1efeab08",
    "createdAt": 1723111376499,
    "cloudUrl": "https://your-customer-cloud-site.atlassian.net",
    "name": "Migration Plan Name"
  },
  "key": "e094ca53-3747-4541-b263-0bf7b56a5bca",
  "label": "file-label-you-used",
  "serverAppVersion": "1.0",
  "messageId": "53f88ea7-a2d2-4dd2-9f36-2d8c43401b11"
}

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>;
    messageFailed: (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

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')
            }
        })
}

Forge migration REST API

This documentation has moved. See REST API documentation instead.