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.
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, .
With a running local HTTP server, you'll deploy a Forge app that calls back over the internet via the ngrok tunnel connecting to your local Connect app.
In this section, you'll define properties in the manifest file. is environment specific. In production environments, we recommend setting it to your Connect app key. In development and staging environments, set an appropriate variation of your key.
Open another terminal window, and navigate to the top-level directory of the sample app.
Register the sample app by running:
a. Enter a name for your app. For example, My Connect app on Forge.
Add a field nested under the field, with its own and fields, like so:
1 2 3 4
app: connect: key: hello-world remote: connect
should correspond to the desired connect key of the app in production, and should correspond to the key of the entry that holds the connect app baseUrl.
Deploy the app by running:
A custom deploy script is used in order to update the for the environment being deployed to.
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.
If certain modules (such as or ) contain context parameters (such as ) in their , they will fail to deploy due to a validation error. This is due to differences in how Forge and Connect validate urls within such modules against the module schema.
An app has no communication path between the Forge and Connect parts of an app.
can be changed in the and environments at any time, and in up until the app is listed on the Atlassian Marketplace.
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:
can and should be set differently in different environments, but the field in the manifest is not environment specific, meaning it will need 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.
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: