In this page, you'll learn how to migrate Jira modules from Connect to Forge.
By module migration, we mean the process when an existing Connect app is migrated to Forge and retains its identity and data.
As the migration process for the majority of modules will be similar, in the following sections we'll provide a general guide on how to migrate Jira modules from Connect to Forge. In the dedicated pages, we'll provide more detailed information on how to migrate specific modules.
At the moment, the following Jira modules are supported:
The first step is to adopt Forge for your Connect app.
For information on how to do this, follow the Adopting Forge from Connect guide. After following the process in How to adopt Forge from Connect, you should have a Forge app that is ready to be extended with Forge Jira modules.
The expectation is that at the end of the process the Forge module will replace the Connect module.
What does it mean? For example, you might have a Connect app that defines a dashboard items module. After you implement those gadgets in Forge, you wish to retain the existing dashboard's configuration - The Forge gadget should simply replace the Connect dashboard item on every dashboard it was configured on. It will also be available in Dashboard editor and be returned by the Jira REST API instead of the old Connect dashboard item.
In the Forge app manifest manifest.yml, you define the Forge module that you want to migrate.
Note that the Forge module should have the same key as the Connect module that you want to replace.
However, the module keys within the app's manifest must be unique.
If you try to deploy your app at this point, you'll get a validation error due to the duplicate key.
To fix it, comment out or remove the Connect module and run forge deploy command again.
In the example below, we've commented out the jira:jiraDashboardItems section:
1 2modules: jira:dashboardGadget: - key: connect-dashboard-item-module title: Connect gadget after migration description: Connect gadget after migration to Forge thumbnail: https://developer.atlassian.com/platform/forge/images/icons/issue-panel-icon.svg function: main edit: function: edit # ... app: id: ari:cloud:ecosystem::app/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee connect: key: connect-dashboard-item-app remote: connect # ... connectModules: # jira:jiraDashboardItems: # - name: # value: Connect dashboard item # i18n: issues.in.project.i18n # url: >- # /issues-in-project?dashboard={dashboard.id}&dashboardItem={dashboardItem.id} # key: connect-dashboard-item-module # description: # value: Connect dashboard item # i18n: issues.in.project.description.i18n # thumbnailUrl: /thumbnail # configurable: true
After running the forge deploy command, the Forge module will be available in Jira and should replace the existing Connect module.
Referring to our previous example, the Forge gadget should be displayed on the dashboard instead of the Connect dashboard item.
Of course, it is the app's responsibility to ensure that the Forge module behaves as expected and offers the same functionality that the Connect module did!
Rate this page: