Rate this page:
This tutorial describes how to integrate a Connect app with Forge, and install and use the resultant app on a Jira site. You'll build new modules in your Connect app using the UI kit and use Forge functions to execute your app logic.
With your app deployed to Forge, your Connect app retains the flexibility of remote-hosted compute and UI, while benefiting from Forge-only modules, such as Jira workflow validators and Jira custom fields.
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.
Note, it's not necessary to log in with an ngrok account to use the basic tunneling features.
In this step, you'll clone the example code from Bitbucket and explore the file and code structure that enables Connect modules on a Forge app.
The app has the following file structure:
1 2 3 4
├── connect-app.js ├── manifest.yml └── src └── index.js
The table below shows the purpose for each file in detail.
This is a standalone Atlassian Connect app server, which handles installations, makes authenticated requests, and returns the HTML to display a general page. Installation data is stored as files in a directory.
Notably absent is the Connect add-on descriptor. This is because Connect features of the app are described alongside Forge features in the .
The manifest describes your app. The following sections that have changed to support Connect functionality:
This contains the source of the workflow validator function.
Notably absent from the is a developer-specified Connect . See the known limitations and known issues section below.
Unlike a Forge app, Connect apps are served from a remote HTTP server. For development purposes, you'll start up a local HTTP server embedded in the example app.
Start the app server by running:
Note, on Linux you can directly execute the app .
Open a separate terminal window and start your internet-facing tunnel by running:
Copy the HTTPS URL from the ngrok output into the in the . The URL contains a random ID followed by the ngrok domain. For example, .
In this section, you'll deploy a Forge app that calls the local HTTP server over the internet via the ngrok tunnel to connect to your local Connect app.
Register the sample app by running:
a. Enter a name for your app. For example, My Connect app on Forge.
Deploy the app by running:
Install your app by running:
Select Jira using the arrow keys and press the enter key.
Enter the URL for your development site. For example, example.atlassian.net.
Once the successful installation message appears, your app is installed and ready to use on the specified site. You should see a Connect installation logged in the output of the app server started at step 2.
You can now see the app in action on your development site by transitioning an issue or clicking on the Apps drop-down in the Jira top nav, then clicking Connect on Forge: My Jira projects.
With your functioning basic app, you can continue to explore what's possible with Connect modules in a Forge app. Below are some ideas to get you started.
You may have an existing Connect app you wish to experiment with porting to Forge. If so, we recommend you set up a separate instance of the app with its own data store to avoid conflicts. Because the ported version will have a different, randomly generated key, this version will not clash with the original version on the development site. See the known limitations and known issues section below.
Connect modules have the same format in Forge. You'll need to specify the or prefix, but should otherwise be able to copy and paste the Connect module syntax directly into the since YAML is a superset of JSON.
You can use web triggers to use a Forge feature from your Connect app. Note, web trigger URLs must be generated per installation.
It may be possible to make a JWT authenticated call from a Forge function to your app server. However, this hasn't been tested and and we foresee the following issues:
Possible lack of a crypto polyfill in the Forge app runtime.
No way to access the in which the function is being invoked.
We're working on broadening the support for Forge apps with Connect modules. In its current early state, it has some limits and issues you should be aware of.
Although these issues are known to us, we're excited to hear your feedback about how you would prefer these features to work or which are the most troublesome for you.
Connect features in Forge are still a work in progress. At the moment, it’s not yet possible to list a Forge/Connect app on the Atlassian Marketplace.
Despite having the required scopes, your app may not be able to access restricted resources, such as team-managed projects with custom permissions, or operations, such as deleting projects. This is due to reliability issues with Connect app permission provisioning.
When updating the , , and 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 reflect.
An app has no communication path between the Forge and Connect parts of an app.
A Connect app is assigned a randomly generated app key by Forge. You cannot set the value to match that of an existing Connect app.
Migrating an app from Connect to Forge with the same key and Marketplace listing is an ongoing area of investigation for us.
To access the key, you need to inspect the field of the installed lifecycle hook payload.
App servers hosting an existing Connect app, as well as a Forge app with the Connect app configured appear as separate apps due to the randomized keys. This may cause conflicts in the app server's installation records if the apps are both installed on the same site.
To avoid this issue, we recommend setting up a separate instance of your app server with a separate data store to investigate adding Forge, rather than using the main staging or production server of an existing Connect app.
If your Connect app server needs to have its key statically configured, you could try the following to extract the Forge assigned key.
Follow the tutorial with the sample app and a separate development site.
Locate the key in the standalone app server logs or installation files.
Configure the key in your Connect app server instance.
Update the manifest of the sample app to point to your Connect app server instance.
Redeploy the sample app, and install it on your development site.
The Forge app key is the same across development, staging, and production app environments. This limits apps to only one environment on a site at a time.
Forge does not support Connect apps with internationalized content.
Forge does not support Connect apps using the new data residency API.
Forge does not support dynamic modules.
Forge does not support user impersonation for Connect Apps. The supplied in the installation hook payload is not compatible.
We're excited to hear your feedback. Please join us in the Forge developer community.
Rate this page: