Connect app descriptor

The app descriptor is a JSON file (atlassian-connect.json) that describes the app to the Atlassian application. The descriptor includes general information for the app, as well as the modules that the app wants to use or extend.

If you're familiar with Java app development with previous versions of the Atlassian Plugin Framework, you may already be familiar with the atlassian-plugin.xml descriptors. The atlassian-connect.json serves the same function.

The descriptor serves as the glue between the remote app and the Atlassian application. When an administrator for a cloud instance installs an app, what they are really doing is installing this descriptor file, which contains pointers to your service. You can see an example below.

For details and application-specific reference information on the descriptor please refer to the Jira modules and Confluence modules sections of this documentation. But we'll call out a few highlights from the example here.

App descriptor updates

Since Atlassian Connect apps are remote and largely independent from the Atlassian application, they can be changed at any time, without manually creating a new version or reporting the changes to the Atlassian instance. The changes are reflected in the Atlassian instance immediately (or at least at page reload time).

Some app changes require a change to the descriptor file itself. For example, an app could be modified to have a new page module. Since this requires a page module declaration in the descriptor, it means making an updated descriptor available.

Updates to the app descriptor are published to the Marketplace automatically a few minutes after you publish changes to your descriptor file. We regularly poll the app descriptor URL that you included when you submitted your listing. When a change is detected, we update your app in the Atlassian Marketplace with a new version.

The Marketplace will automatically inform administrators of the change and install the available update. See Upgrades for more details.

Descriptor JSON schemas

The descriptor format for apps to each product is defined by a JSON schema.

• Confluence
• Jira

Validator tool

The app descriptors can be validated using our interactive JSON schema validation tool, with the above descriptors.

• Confluence schema validator
• Jira schema validator

The validator will check that your descriptor is syntactically correct. Just paste the JSON content of your descriptor in the interactive editor, and any issues with the schema will be shown inline in the editor view.

App descriptor structure

1
2
{
  "modules": {},
  "key": "my-app-key",
  "name": "My Connect App",
  "description": "A connect app that does something",
  "vendor": {
    "name": "My Company",
    "url": "http://www.example.com"
  },
  "links": {
    "self": "http://www.example.com/connect/jira/atlassian-connect.json"
  },
  "lifecycle": {
    "installed": "/installed",
    "uninstalled": "/uninstalled"
  },
  "baseUrl": "http://www.example.com/connect/jira",
  "authentication": {
    "type": "jwt"
  },
  "enableLicensing": true,
  "scopes": [
    "read",
    "write"
  ],
  "cloudAppMigration": {
    "migrationWebhookPath" : "/app-migration-events-webhook"
  }
}

Authentication

Defines the authentication type to use when signing requests from the host application to the Connect app.

Example

1
2
{
  "authentication": {
    "type": "jwt"
  }
}

Properties

Lifecycle

Allows an app to register callbacks for events that occur in the lifecycle of an installation. When a lifecycle event is fired, a POST request will be made to the appropriate URL registered for the event.

The installed lifecycle callback is an integral part of the installation process of an app, whereas the remaining lifecycle events are essentially webhooks.

Each property in this object is a URL relative to the app's base URL.

Lifecycle attribute example

1
2
{
  "installed": "/installed",
  "enabled": "/enabled",
  "disabled": "/disabled",
  "uninstalled": "/uninstalled"
}

Note: Authentication for installed/uninstalled lifecycle requests

Lifecycle HTTP request payload

Lifecycle callbacks contain a JSON data payload with important tenant information that you will need to store in your app in order to sign and verify future requests. The payload contains the following attributes:

1
2
{
  "key": "installed-addon-key",
  "clientKey": "unique-client-identifier",
  "sharedSecret": "a-secret-key-not-to-be-lost",
  "serverVersion": "server-version",
  "pluginsVersion": "version-of-connect",
  "baseUrl": "https://example.atlassian.net",
  "displayUrl": "https://docs.example.com",
  "productType": "jira",
  "description": "Atlassian Jira at https://example.atlassian.net",
  "serviceEntitlementNumber": "SEN-number",
  "entitlementId": "Entitlement-Id",
  "entitlementNumber": "Entitlement-Number",
  "eventType": "installed",
  "installationId": "ari:cloud:ecosystem::installation/uuid-of-forge-installation-identifier"
}

App vendor

Gives basic information about the app vendor

1
2
{
  "vendor": {
    "name": "Atlassian",
    "url": "http://www.atlassian.com"
  }
}

Properties

Cloud App Migration

Defines settings to be used for App Migration

1
2
{
  "cloudAppMigration": {
    "migrationWebhookPath" : "/app-migration-events-webhook"
  }
}

Properties