Rate this page:
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:
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.
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.
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 2git 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.
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.
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 2git merge origin/migration-rewritten-with-forge-modules npm install
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.
modules
move from the Connect descriptor to connectModules
in the Forge manifest.yml
.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
,
under either jira:lifecycle
or confluence:lifecycle
.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 2git merge origin/migration-with-connect-modules
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 2app: 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 2remotes: - 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.
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.
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.
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.
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.
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.
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:
/rest/atlassian-connect/1/addons/{addonKey}/properties
resource.Forge does not support Connect apps with internationalized content.
Follow this Jira issue for updates.
Forge does not support dynamic modules. Follow this Jira issue for updates.
Connect-on-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.
Forge does not support Connect apps using the new data residency API.
Follow this Jira issue for updates.
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.
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.
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.
Rate this page: