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": "decorated",
        "weight": 100,
        "target": {
          "type": "page",
          "options": {}
        },
        "name": {
          "value": "Web Item"
        }
      }
    ]
  },
  "scopes": []
}

Kitchen Sink:

{
  "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": "decorated",
        "weight": 100,
        "target": {
          "type": "page",
          "options": {}
        },
        "name": {
          "value": "Web Item"
        }
      }
    ],
    "webPanels": [
      {
        "location": "com.atlassian.jira.plugin.headernav.left.context",
        "layout": {},
        "url": "/my-web-panel",
        "weight": 100,
        "name": {
          "value": "Web Panel"
        }
      }
    ],
    "webhooks": [
      {
        "event": "jira:issue_created",
        "url": "/issue-created"
      }
    ],
    "generalPages": [
      {
        "url": "my-general-page",
        "name": {
          "value": "General Page"
        }
      }
    ],
    "adminPages": [
      {
        "url": "my-admin-page",
        "name": {
          "value": "Admin Page"
        }
      }
    ],
    "configurePage": {
      "url": "my-configure-page",
      "name": {
        "value": "Config Page"
      }
    },
    "jiraComponentTabPanels": [
      {
        "url": "my-component-tab-panel",
        "weight": 100,
        "name": {
          "value": "Component Tab"
        }
      }
    ],
    "jiraIssueTabPanels": [
      {
        "url": "my-issue-tab-panel",
        "weight": 100,
        "name": {
          "value": "Issue Tab"
        }
      }
    ],
    "jiraProjectTabPanels": [
      {
        "url": "my-project-tab-panel",
        "weight": 100,
        "name": {
          "value": "Project Tab"
        }
      }
    ],
    "jiraVersionTabPanels": [
      {
        "url": "my-version-tab-panel",
        "weight": 100,
        "name": {
          "value": "Version Tab"
        }
      }
    ],
    "jiraProfileTabPanels": [
      {
        "url": "my-profile-tab-panel",
        "weight": 100,
        "name": {
          "value": "Profile Tab"
        }
      }
    ],
    "jiraSearchRequestViews": [
      {
        "url": "/searchRequest",
        "weight": 100,
        "description": {},
        "name": {
          "value": "Search View"
        }
      }
    ],
    "jiraWorkflowPostFunctions": [
      {
        "description": {},
        "create": {
          "url": "/create"
        },
        "name": {
          "value": "Workflow Function"
        }
      }
    ],
    "dynamicContentMacros": [
      {
        "url": "/dynamic-macro",
        "description": {},
        "categories": [],
        "outputType": "block",
        "bodyType": "none",
        "aliases": [],
        "featured": false,
        "name": {
          "value": "Dynamic Macro"
        }
      }
    ],
    "profilePages": [
      {
        "url": "my-confluence-profile-page",
        "name": {
          "value": "Profile Page"
        }
      }
    ],
    "staticContentMacros": [
      {
        "method": "get",
        "url": "/static-macro",
        "description": {},
        "categories": [],
        "outputType": "block",
        "bodyType": "none",
        "aliases": [],
        "featured": false,
        "name": {
          "value": "Static Macro"
        }
      }
    ]
  },
  "scopes": []
}

Properties

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