Prepare your cloud app for Forge remote migration

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

Events

The Forge remote, endpoint, 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 remote and trigger to the manifest

Define a remote and trigger to process migration events.

See an example

1
2
modules:
  trigger:
    - key: migration-trigger
      endpoint: remote-event
      events:
        - avi:ecosystem.migration:uploaded:app_data
        ...

  endpoint:
    - key: remote-event
      remote: remote-app
      route:
        path: /<relative-url-to-your-self-hosted-app>
      auth:
        appSystemToken:
          enabled: true

  remotes:
    - key: remote-app
      baseUrl: "${YOUR_SELF_HOSTED_APP_BASE_URL}"
      auth:
        appSystemToken:
          enabled: true
      operations:
        - compute

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 status API for avi:ecosystem.migration:uploaded:app_data events within 15 minutes of processing the last event or uploading new data from the server app (whichever occurs later).
• 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.
• Validate the event payloads and throw an exception if validation fails - this will help you monitor for failed remote calls and failed remote calls will be retried.

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 REST API

Refer to the REST API documentation for the available endpoints and their usage.

Authentication

For authentication refer to Calling Atlassian APIs from a Forge remote.

It is important to verify requests to your Forge remote.

Using Connect libraries

Atlassian Connnect Spring Boot and Atlassian Connnect Express can handle request verification and authentication for you.

An example Forge remote may look like this:

1
2
@ForgeRemote
@RestController
@RequestMapping("/api/forge")
public class ForgeRemoteController {
    private static final Logger log = LoggerFactory.getLogger(ForgeRemoteController.class);
    private final AtlassianForgeRestClients atlassianForgeRestClients;


    public ForgeRemoteController(AtlassianForgeRestClients atlassianForgeRestClients) {
        this.atlassianForgeRestClients = atlassianForgeRestClients;
    }

    @RequestMapping(value = "/events", consumes = "application/json", produces = "application/json")
    public ResponseEntity<RemoteDto> postRemote(@RequestBody ForgeMigrationEventDto event) {
            MigrationStatusDto statusDto = MigrationStatusDto.builder().status("SUCCESS").messageIds(Collections.singletonList(event.getMessageId())).build();
            atlassianForgeRestClients
                    .asApp()
                    .request()
                    .exchange(
                            "/app/migration/forge/v1/message/{transferId}/status",
                            HttpMethod.POST,
                            statusDto,
                            String.class,
                            event.getTransferId());
            return ResponseEntity.ok(RemoteDto.builder().message("Successfully processed " + event.getMessageId()).build());
    }
}

Error handling