Retrieving the Connect clientKey in Forge

During migration from Connect to Forge, your app may need the Connect clientKey — the unique identifier for a Connect installation in a context — to look up existing installation data stored against it. This page describes two ways to retrieve the clientKey in a Forge context so you can migrate away from clientKey-keyed data.

Option 1: Using the Connect installed lifecycle webhook

If your Forge manifest includes the Connect lifecycle module in connectModules, the installed payload already includes the clientKey. No additional trigger or API call is needed.

Manifest

1
2
connectModules:
  confluence:lifecycle:
    - key: lifecycle-events-confluence
      installed: /installed
  jira:lifecycle:
    - key: lifecycle-events-jira
      installed: /installed

Payload

1
2
{
  "key": "app.connect.key",
  "clientKey": "unique-connect-identifier",
  "sharedSecret": "a-secret-key",
  "baseUrl": "https://example.atlassian.net",
  "productType": "jira",
  "eventType": "installed",
  "installationId": "ari:cloud:ecosystem::installation/uuid-of-forge-installation"
}

This gives you the clientKey at installation time, allowing you to correlate the Forge installation with the prior Connect installation. Use it to migrate away from clientKey-keyed data in your data store.

The official Atlassian Connect frameworks can retrieve the clientKey from the installed lifecycle payload:

• Atlassian Connect Express (Node.js): stores the clientKey in its settings database
• Atlassian Connect Spring Boot (Java): stores the clientKey in its AtlassianHostMappingRepository as an AtlassianHostMapping with the Forge installationId.

Option 2: Using a Forge install trigger with the app properties API

If you want to remove the Connect lifecycle module from your Forge manifest, you can retrieve the reserved app property by combining a Forge install trigger through the app properties API.

To use this approach, your app must declare app.connect.key in the Forge manifest to access this property.

Implementation

This approach has two parts:

1. Set up a trigger on the avi:forge:installed:app event so your code runs at install time.

2. In the trigger handler, call the app properties API using a reserved property key to fetch the clientKey.

Once migration is complete for all installations, you can remove the trigger from your manifest.

Manifest examples

1
2
modules:
  trigger:
    - key: migrate-client-keys
      function: migrate-handler
      events:
        - avi:forge:installed:app
  function:
    - key: migrate-handler
      handler: migration.run
      timeoutSeconds: 120

Handler examples

In the trigger handler, make a GET request to the app properties API using the reserved property key.

For Jira:

GET /rest/atlassian-connect/1/addons/{app.connect.key}/properties/connect_client_key_019cdff3-8bfb-71fe-9628-875b700aebb8

For Confluence:

GET /wiki/rest/atlassian-connect/1/addons/{app.connect.key}/properties/connect_client_key_019cdff3-8bfb-71fe-9628-875b700aebb8

A successful response returns the clientKey as the property value:

1
2
{
  "key": "connect_client_key_019cdff3-8bfb-71fe-9628-875b700aebb8",
  "value": "unique-connect-identifier"
}

1
2
// migration.js
import api, { route } from '@forge/api';

const ADDON_KEY = 'app.connect.key';
const RESERVED_KEY = 'connect_client_key_019cdff3-8bfb-71fe-9628-875b700aebb8';

export const run = async ({ context }) => {
  const response = await api.asApp().requestConfluence(
    route`/wiki/rest/atlassian-connect/1/addons/${ADDON_KEY}/properties/${RESERVED_KEY}`
  );

  if (!response.ok) {
    console.error(`Failed to fetch clientKey: ${response.status}`);
    return;
  }

  const { value: clientKey } = await response.json();

  // TODO: Look up existing data keyed by clientKey
  // TODO: Migrate data away from clientKey
};

References

For full API details, see the Confluence and Jira app properties API documentation.

The Atlassian Connect Express and Atlassian Connect Spring Boot frameworks also provide Atlassian App API clients that can call the app properties API to fetch the clientKey using the reserved app property key. See respective READMEs for details.