Addon 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 an Atlassian OnDemand 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.

The version element identifies the version of the add-on itself. Note that versioning works differently for Atlassian Connect add-ons than it does for traditional, in-process add-ons.

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 do require a change in the descriptor file itself. For example, say you modify the add-on to have a new page module. Since this requires a page module declaration in the descriptor, it means making an updated descriptor available, which instances will have to re-register. To propagate this change, 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.

Example

{
  "key": "my-addon-key",
  "name": "My Connect Addon",
  "version": "1.0",
  "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,
  "modules": {
    "webItems": [
      {
        "url": "/my-web-item",
        "location": "system.preset.filters",
        "context": "addon",
        "weight": 100,
        "target": {
          "type": "page",
          "options": {}
        },
        "key": "my-web-item",
        "name": {
          "value": "Web Item"
        }
      }
    ]
  },
  "scopes": [
    "read",
    "write"
  ]
}

Properties

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

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