Adopting Connect on Forge for app migrations

With the introduction of the ability to incrementally adopt Forge features with your Connect app (Connect on Forge) understanding its impact on your server-to-cloud migrations is important. We aim to make it easier to understand in the following guide.

Existing Connect migrations

Your Connect on Forge app will continue to receive migration events. Refer to this guide to understand how your app will receive these events.

To achieve the same functionality as a webhook in your Connect descriptor, it is recommended to add the cloudAppMigration webhook under connectModules in your manifest file. Migration events will then be sent to your Connect app using the migrationWebhookPath as the relative path.

Replacing your Connect migration path with a Forge one

If you prefer not to maintain your Connect migration path, you can completely transition to a Forge one. Start by implementing a Forge migration path. When you're ready release your Forge migration path by updating the cloudMigrationAssistantCompatibilityRanges to the server app version that implements DiscoverableForgeListener. This change will direct new migrations to use your Forge migration path instead of the Connect one i.e. migration events will be sent to your Forge functions instead of your Connect app migration webhook endpoint.

Keep your Connect app migration code active until all customer migrations are complete. Since app migrations timeout after 14 days, use this as a guideline for how long to maintain your migration code. You can clean up your manifest file by removing the cloudAppMigration module from it since it is no longer needed.

Prefer a Forge migration path over a Connect one

You maybe adopting the App migration platform for the first time and wondering if you should implement a Connect or Forge migration for your Connect on Forge app. To simplify the transition to using all Forge modules we recommend you implement a Forge migration path. Additionally Forge offers a better developer experience with a migrations package and hosting and running your code with Forge functions.

Should you build a Forge migration path if you already have a Connect one?

This depends on your specific needs. If you plan to completely transition to Forge modules or want to migrate Forge custom fields, then you should create a Forge migration path and phase out your Connect migration path. Otherwise you do not have to rebuild your migration path in Forge.

Module migrations

If you use our workflow rule migrations or custom field migrations, ensure that your migration listener matches the module type in the cloud. For instance, if you are using Connect workflow rules or Connect issue fields (custom fields), your migration listener must implement the DiscoverableListener interface for Connect. Conversely, if you are using Forge modules, your listener should implement the DiscoverableForgeListener interface.

Limitations

• If you are using both Connect and Forge module of the same type we can only migrate to either the Forge or Connect one (depending on the listener interface you implement) not both.

• For Server to Forge migration path:

  • Workflow rules are not supported - MIG Ticket
  • Name of locked Forge custom fields must remain the same between server and cloud - MIG Ticket
  • Migrating macros to new editor format is not supported - by default we will migrate to the legacy editor format

• For Server to Connect migration path:

  • Only locked custom fields are supported - MIG Ticket

Please vote on the corresponding MIG ticket or contact us if any of the these limitations impact you.

Customer Scenarios

To better understand all the scenarios your customers could be in when migrating with your Connect on Forge app refer to the matrix below.

Additional Links

Connect on Forge documentation

MIG ticket to track custom field type migration support

MIG ticket to track workflow rule migration support

MIG ticket to track locked Forge custom field name migration support