Documentation

Add-On Descriptor

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

If you're familiar with Java add-on 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 add-on and the Atlassian application. When an administrator for a cloud instance installs an add-on, 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.

Since Atlassian Connect add-ons are remote and largely independent from the Atlassian application, they can be changed at any time, without having to create a new version or report the change to the Atlassian instance. The changes are reflected in the Atlassian instance immediately (or at least at page reload time).

However, some add-on changes require a change to the descriptor file itself. For example, an add-on 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. Until that updated descriptor is re-installed into the Atlassian Product that change in the descriptor file will not take effect. To propagate a change in the descriptor to the Atlassian products, you need to create a new version of the add-on in its Marketplace listing. The Marketplace will take care of the rest: informing administrators and automatically installing the available update. See Upgrades for more details.

Validating your descriptor

You can validate your descriptor using this handy tool.

Example

{
  "modules": {},
  "key": "my-addon-key",
  "dependencies": {},
  "name": "My Connect Addon",
  "description": "A connect addon that does something",
  "vendor": {
    "name": "My Company",
    "url": "http://www.example.com"
  },
  "links": {
    "self": "http://www.example.com/connect/jira"
  },
  "lifecycle": {
    "installed": "/installed",
    "uninstalled": "/uninstalled"
  },
  "baseUrl": "http://www.example.com/connect/jira",
  "authentication": {
    "type": "jwt"
  },
  "enableLicensing": true,
  "scopes": [
    "read",
    "write"
  ],
  "translations": {
    "paths": {
      "en-US": "/i18n/1.0/en_US.json",
      "en-UK": "/i18n/1.0/en_UK.json",
      "fr-FR": "/i18n/1.0/fr_FR.json",
      "de-DE": "/i18n/1.0/de_DE.json",
      "pt-PT": "/i18n/1.0/pt_PT.json",
      "es-ES": "/i18n/1.0/es_ES.json",
      "ja-JP": "/i18n/1.0/ja_JP.json",
      "ko-KR": "/i18n/1.0/ko_KR.json",
      "ru-RU": "/i18n/1.0/ru_RU.json"
    }
  }
}

Properties

authentication

Required
Yes
Description

Defines the authentication type to use when signing requests between the host application and the connect add on.

baseUrl

Type
string

uri
Required
Yes
Character Limit

200
Description

The base url of the remote add-on, which is used for all communications back to the add-on instance. Once the add-on is installed in a product, the add-on's baseUrl cannot be changed without first uninstalling the add-on. This is important; choose your baseUrl wisely before making your add-on public.

The baseUrl must start with https:// to ensure that all data is sent securely between our cloud instances and your add-on.

Note: each add-on must have a unique baseUrl. If you would like to serve multiple add-ons from the same host, consider adding a path prefix into the baseUrl.

key

Type
string
Required
Yes
Character Limit

80
Description

A unique key to identify the add-on. This key must be <= 80 characters, must only contain alphanumeric characters, dashes, underscores, and dots.

apiVersion

Type
integer
Description

The API version is an OPTIONAL integer. If omitted we will infer an API version of 1.

The intention behind the API version is to allow vendors the ability to beta test a major revision to their Connect add-on as a private version, and have a seamless transition for those beta customers (and existing customers) once the major revision is launched.

Vendors can accomplish this by listing a new private version of their add-on, with a new descriptor hosted at a new URL.

They use the Atlassian Marketplace's access token facilities to share this version with customers (or for internal use). When this version is ready to be taken live, it can be transitioned from private to public, and all customers will be seamlessly updated.

It's important to note that this approach allows vendors to create new versions manually, despite the fact that in the common case, the versions are automatically created. This has a few benefits-- for example, it gives vendors the ability to change their descriptor URL if they need to (the descriptor URL will be immutable for existing versions)

description

Type
string
Character Limit

1400
Description

A human readable description of what the add-on does. The description will be visible in the Manage Add-ons section of the administration console. Provide meaningful and identifying information for the instance administrator.

enableLicensing

Type
boolean
Defaults to
false
Description

Whether or not to enable licensing options in the UPM/Marketplace for this add on

lifecycle

Description

Allows the add on to register for plugin lifecycle notifications

links

Type
object
Description

A set of links that the add-on wishes to publish

{
  "links": {
    "self": "https://addon.domain.com/atlassian-connect.json",
    "documentation": "https://addon.domain.com/docs"
  }
}

modules

Type
object
Description

The list of modules this add-on provides.

name

Type
string
Character Limit

80
Description

The human-readable name of the add-on

scopes

Type
string, … ]
Description

Set of scopes requested by this add on

{
  "scopes": [
    "read",
    "write"
  ]
}

translations

Description

Translations for this add-on.

{
  "translations": {
    "paths": {
      "en-US": "/i18n/1.0/en_US.json",
      "en-UK": "/i18n/1.0/en_UK.json",
      "fr-FR": "/i18n/1.0/fr_FR.json",
      "de-DE": "/i18n/1.0/de_DE.json",
      "pt-PT": "/i18n/1.0/pt_PT.json",
      "es-ES": "/i18n/1.0/es_ES.json",
      "ja-JP": "/i18n/1.0/ja_JP.json",
      "ko-KR": "/i18n/1.0/ko_KR.json",
      "ru-RU": "/i18n/1.0/ru_RU.json"
    }
  }
}

vendor

Description

The vendor who is offering the add-on