Last updatedApr 16, 2021

Rate this page:

Build a Connect on Forge app

This functionality is an alpha release

The features described in this tutorial are available for research and feedback, and are not production-ready. See the known limitations and known issues section for more information.

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.

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.

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

Step 1: Get the sample app

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.

  1. Clone the sample app from Bitbucket.
  2. Open the repository in your editor.

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.

FilenameDescription
connect-app.js

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 .json files in a data/ directory.

Notably absent is the Connect add-on descriptor. This is because Connect features of the app are described alongside Forge features in the manifest.yml.

manifest.yml

The manifest describes your app. The following sections that have changed to support Connect functionality:

  • connectModules contains the parts of the app that map to connect modules.

    Jira-specific modules are prefixed with jira: and Confluence-specific modules are prefixed with confluence:. Modules common to either product can have either prefix.

    This app has a general page and handlers for installation and uninstallation events. enabled and disabled events are currently not fired by the Forge platform.


  • remotes contains the Connect base URL. This section is limited to a single entry, but the value of the key doesn't matter.


  • permissions contains the app's scopes.

    Connect scopes appear in the Forge manifest as 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, as long as the suffix contains connect in it. 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.

src/index.js

This contains the source of the workflow validator function.

Notably absent from the manifest.yml is a developer-specified Connect key. See the known limitations and known issues section below.

Step 2: Start your Connect app server

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.

  1. Navigate to the top-level directory of the sample app.
  2. Start the app server by running:

    1
    node connect-app.js

    Note, on Linux you can directly execute the app ./connect-app.js.

  3. Open a separate terminal window and start your internet-facing tunnel by running:

    ngrok http --bind-tls=true 49998

  4. Copy the HTTPS URL from the ngrok output into the baseUrl in the manifest.yml. The URL contains a random ID followed by the ngrok domain. For example, https://<random ID>.ngrok.io.

Step 3: Deploy and test your Forge app

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.

  1. Open another terminal window, and navigate to the top-level directory of the sample app.
  2. Register the sample app by running:

    1
    forge register

    a. Enter a name for your app. For example, My Connect app on Forge.

  3. Deploy the app by running:

    1
    forge deploy
  4. Install your app by running:

    1
    forge install
  5. Select Jira using the arrow keys and press the enter key.

  6. 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.

Optional steps

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.

Add more modules

You can experiment with adding other Forge and Connect modules to your app.

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 jira or confluence prefix, but should otherwise be able to copy and paste the Connect module syntax directly into the manifest.yml since YAML is a superset of JSON.

Intermediate: Experiment with calling from Connect to Forge

You can use web triggers to use a Forge feature from your Connect app. Note, web trigger URLs must be generated per installation.

Advanced: Experiment with calling from Forge to Connect

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 clientKey in which the function is being invoked.

Known limitations and known issues

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.

Alpha release

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.

Issues granting access to restricted resources

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.

Uninstall/reinstall required to reflect module changes

When updating the modules, scopes, and baseURL 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.

Communication issues between Forge and Connect

An app has no communication path between the Forge and Connect parts of an app.

Randomly generated app key

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 key 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.

  1. Follow the tutorial with the sample app and a separate development site.

  2. Locate the key in the standalone app server logs or installation files.

  3. Configure the key in your Connect app server instance.

  4. Update the manifest of the sample app to point to your Connect app server instance.

  5. Redeploy the sample app, and install it on your development site.

Key per-app, not per-environment

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.

i18n

Forge does not support Connect apps with internationalized content.

Data residency

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

Dynamic modules

Forge does not support dynamic modules.

ACT_AS_USER

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

Giving feedback

We're excited to hear your feedback. Please join us in the Forge developer community.

Rate this page: