Migrate an app from Connect to Forge

See the known limitations and known issues section to see if migration is right for your app at this time.

This tutorial describes how to migrate your app from Connect to Forge via the following steps:

Prepare a Connect app for migration
Migrate your Connect app functionality by re-writing with new Forge modules.
Register your Forge app as the successor to your Connect app.
Use the forge CLI to test migrating an existing installation.

If you already have a migrated and tested app, you can proceed to upload this Forge app to your marketplace listing as the next version.

Before you begin

You'll need to set up your Forge development environment and a development site. See Getting started for step-by-step instructions on setting up Forge.

You'll also need a tool to tunnel your local app server to the internet. This tutorial will use ngrok, which can be downloaded for free from ngrok.

It's not necessary to log in with an ngrok account to use the basic tunneling features.

Step 1: Prepare your Connect app for migration

Create a new migration branch in a local clone of your connect app.

If you have an established practice for starting up a local instance of your Connect app, you can skip to step 4.

If you don’t have an app of your own to test migrating to Forge, clone the migration branch of this simple sample connect app:
```
1
2
git clone git@bitbucket.org:atlassian/connect-on-forge-alpha.git -b migration
```
Start your internet-facing tunnel. If you’re using ngrok with the sample app, run ngrok http --bind-tls=true 49998
In a separate terminal window, start your app.

If you’re using the sample app, first edit the baseUrl variable value near the top of the connect-app.js file to match your internet-facing tunnel URL, then run node connect-app.js
Install the app on a test site, so that you can test migrating the installation once the app has been migrated on to Forge. If you don’t know how to set up a test site, follow this step to get a cloud development site, and this step to install your locally-running Connect app on to your development site.

Everything is now in place to begin the migration of your Connect app’s functionality to Forge.

Step 2: Migrate your Connect app’s functionality

You can migrate your Connect app functionality by making use of connectModules, re-writing with new Forge modules, or a combination of the two.

For more details on states of app migration, see this blog post.

Option A: Re-writing with Forge modules

An in-depth discussion of how to approach swapping your Connect modules for Forge modules is beyond the scope of this tutorial, but Connect module equivalents is a good place to start.

Re-writing with Forge modules is more work, but brings with it the convenience, increased security, and trust of Atlassian hosting and running your code for you, while taking care of authentication.

To see the sample app re-written with Forge modules, run the following commands:

1
2
git merge origin/migration-rewritten-with-forge-modules
npm install

Option B: Using Connect modules on Forge

Forge also has backwards-compatibility with Connect modules, but please note there are currently gaps in what is supported. See the known limitations and known issues section for more information.

Migrating Connect modules on Forge is a more mechanical process of copying data from the Connect descriptor to the Forge manifest.yml file.

The app server can remain as it is.
modules move from the Connect descriptor to connectModules in the Forge manifest.yml.
Jira specific modules are prefixed with jira: and Confluence specific modules are prefixed with confluence:. Modules common to either product can have either prefix.
lifecycle handlers move from their own place in the Connect descriptor to connectModules in the Forge manifest.yml. They should exist in the first and only mapping under the sequence jira:lifecycle or confluence:lifecycle. This mapping should include the key-value pair key: lifecycle-events.
scopes move to permissions.scopes in the Forge manifest.yml, are lower-cased, with underscores converted to dashes, and with a suffix of either :connect-jira or :connect-confluence. It makes no difference which of the two is used. For example, the Connect READ scope becomes read:connect-jira or read:connect-confluence, and PROJECT_ADMIN becomes project-admin:connect-jira or project-admin:connect-confluence.
"authentication": { type: "none" } is not supported in a Forge app. If your Connect app does not use JWT authentication, skip registering lifecycle events.
apiMigrations is not supported in a Forge app. If you’re using lifecycle hooks, they will be asymmetrically-signed.

To see the sample app migrated using Connect modules on Forge, run the following commands:

1
2
git merge origin/migration-with-connect-modules

Step 3: Register your Forge app as the successor to your Connect app

Regardless of which method you choose, you will need to register your Forge app and set the app.connect.key to match.

Run the forge register command and provide a name for your app. This adds an app.id to the Forge manifest.yml.

Edit the Forge manifest as per the example below. Adding a connect.key field indicates to Forge and Connect that this Forge app is the successor to your Connect app with the same key.

1
2
app:
  id: <the-unique-id-of-your-app>
  connect:
    key: <your-connect-key>

If you’re using Connect modules, you’ll also need to configure a base url. This is done by adding an entry under the top-level remotes field of your manifest, then referencing its key under app.connect.remote. Also, you can define the authentication type to use when making requests from the connect app server to the host application, either jwt or oauth2. For example:

1
2
remotes:
 - key: connect
   baseUrl: https://hello-world-app.example.com
 app:
   id: ari:cloud:ecosystem::app/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
   connect:
     key: hello-world
     remote: connect
     authentication: jwt

Run the forge deploy command, so that Forge picks up the changes to your app and creates a new version.

Your Forge app has three environments, development, staging and production, and each can have its own Connect key. It is recommended you edit app.connect.key to add a suffix to the key of the development and staging environments before deployment, so that the different environments do not clash with one another on a test site. See this script for one way to automate this step.

Step 4: Test migrating an existing installation

You’re now ready to migrate an existing connect installation over to the Forge version. This is as simple as running forge install and targeting the existing Atlassian site. The sync process will note the matching keys and replace your Connect app with the Forge successor. In testing, some care is required to avoid overwriting the wrong app by unintentionally setting a matching key. In production, this is less of an issue because Atlassian Marketplace ensures that each app’s key is unique.

Once you have run forge install, you can visit the test site to inspect the result.

From this point, you can proceed to upload this Forge app to your marketplace listing as the next version.

Known limitations and known issues

Although these issues are known to us, we're excited to hear your feedback about how you would prefer these features work or which are the most troublesome for you.

Migrating saved modules from Connect to Forge types

There is no support for migrating saved modules from their Connect types to their Forge equivalents. For example, if a Connect-based Confluence macro is removed and a Forge-based macro added, all existing instances of the macro saved in pages will stop working.

Follow this Jira issue for updates on our plans to address this issue for macros.

Uninstall/reinstall required to reflect connect module changes

When updating the connectModules of your app, simply redeploying your app will not reflect these changes where the app is currently installed. You must uninstall and reinstall the app via the Forge CLI for these changes to be reflected.

Follow this Jira issue to be updated when work to support rolling updates is begun and completed.

Changes to scopes and baseUrl require a re-installation, but this is expected behavior because such changes require approval by an administrator.

Communication issues between Forge and Connect

An app has no direct communication path between the Forge and Connect parts, although they may share data via entity or content properties. Also, in Jira, Forge apps published on the Marketplace can access the properties of Connect apps from which they were migrated.

Follow this Jira issue for updates.

Managing different environments

app.connect.key can and should be set differently in different environments, but the field in the manifest is not environment-specific. This means app.connect.key needs to be changed to the appropriate key before deploying to a different environment. See deploy.js in the sample app for one way to automate this.

app.connect.key can be changed in the development and staging environments at any time, and in production up until the app is listed on the Atlassian Marketplace.

app.connect.key is used by a number of Atlassian Connect features as an identifier, and these are affected by the change. For example, the app loses access to:

Any app properties it has written, such as the /rest/atlassian-connect/1/addons/{addonKey}/properties resource.
Certain existing configured modules identified by the key, such as workflow post functions.
Bookmarked urls that include the app key, such as links to general pages, space tools tabs, or reports.

i18n

Forge does not support Connect apps with internationalized content.

Follow this Jira issue for updates.

Dynamic modules

Forge does not support dynamic modules. Follow this Jira issue for updates.

ACT_AS_USER

Forge does not support user impersonation for Connect Apps. The oauthClientId supplied in the installation hook payload is not compatible.

Follow this Jira issue for updates.

Data residency

Forge does not support Connect apps using the new data residency API.

Follow this Jira issue for updates.

No handling of license state changes

A paid connect app (enableLicensing: true in the descriptor) must be replaced by a paid Forge app (app.licensing.enabled: true), and an unpaid Connect app by an unpaid Forge app.

The licensing status of the app can not be changed until all installations have migrated to Forge.

There are currently no plans to address this, as it only affects apps that are in the process of migrating.

Update to Forge shown as a new installation in the UPM audit log

An update that migrates the app from Connect to Forge shows as a new installation in the audit log.

There are currently no plans to address this.

Feedback and next steps

If you would like assistance in migrating your app from Connect to Forge, have feedback about Connect-to-Forge migrations, or if you discover anything unexpected during your testing, please get in touch under the Forge topic and forge-connect tag on the Atlassian Developer Community.