A boolean value indicating if the add-on is enabled for editions.

An alias for the app key, which is used for those operations which impose a limit on the length of app keys. For other operations, the longer key value will be used.

The alias key must be <= 32 characters in length.

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.

NOTE This field is reserved for Atlassian Marketplace. Any value provided will be ignored.

The version of the add-on. Upon registration of a new add-on version in Atlassian Marketplace, a value for this field is generated and subsequently provided to the Universal Plugin Manager.

Gives apps data residency information on realm persistence.

Example

Copy
1
2
3
4
5
6
{
  "dataResidency": {
    "realmPersistenceDays": 9,
    "maxMigrationDurationHours": 2.0
  }
}

Allows an add-on 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 add-on, whereas the remaining lifecycle events are essentially webhooks.

Each property in this object is a URL relative to the add-on's base URL.

Lifecycle attribute example

Copy
1
2
3
4
5
6
{
  "installed": "/installed",
  "uninstalled": "/uninstalled",
  "enabled": "/enabled",
  "disabled": "/disabled"
}

Lifecycle HTTP request payload

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "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://jira.example.net",
  "productType": "jira",
  "description": "Atlassian Jira at https://example.atlassian.net",
  "serviceEntitlementNumber": "SEN-number",
  "eventType": "installed",
  "displayUrlServicedeskHelpCenter": "https://servicedesk.jira.example.net"
}

Request query parameters

When this payload information is POSTed to your Atlassian Connect service you may receive the user\_key and user\_id query parameters; these query parameters are both deprecated. Deprecated If you wish to find out which user enabled your add-on then you should extract the context.user.userKey or context.user.userName data from the JWT token on the enabled lifecycle event.

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 or upgrading to a new version. 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.

Allows an add-on to opt-into an active api migration.

Goal of this feature is to support API changes that could not be made backward compatible. Such changes will break existing apps that do not yet support new API version. The opt-in mechanism allows app vendors to communicate to host product what API changes they support.

See active migrations page for the list of currently active API migrations.

Copy
1
{"apiMigrations":{"gdpr":true}}

For more info about this feature see API migration Opt-in documentation.

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)

The regions and respective url this app is hosted on.

Copy
1
2
3
4
5
6
{
  "regionBaseUrls": {
    "EU": "https://eu.test.atlassian.com",
    "US": "https://us.test.atlassian.com"
  }
}

Gives basic information about the plugin vendor.

Example

Copy
1
2
3
4
5
6
{
  "vendor": {
    "name": "Atlassian",
    "url": "http://www.atlassian.com"
  }
}

Defines the locations of any translation files for your add-on. A translation file maps the localization keys for UI modules in your add-on descriptor to translated strings. You will need one translation file per language. To learn more, read Internationalization.

Example

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
{
  "paths": {
    "en-US": "/i18n/1.0/en_US.json",
    "en-UK": "/i18n/1.0/en_UK.json",
    "zh-CN": "/i18n/1.0/zh_CN.json",
    "zh-TW": "/i18n/1.0/zh_TW.json",
    "tr-TR": "/i18n/1.0/tr_TR.json",
    "cs-CZ": "/i18n/1.0/cs_CZ.json",
    "da-DK": "/i18n/1.0/da_DK.json",
    "nl-NL": "/i18n/1.0/nl_NL.json",
    "et-EE": "/i18n/1.0/et_EE.json",
    "fi-FI": "/i18n/1.0/fi_FI.json",
    "fr-FR": "/i18n/1.0/fr_FR.json",
    "de-DE": "/i18n/1.0/de_DE.json",
    "hu-HU": "/i18n/1.0/hu_HU.json",
    "is-IS": "/i18n/1.0/is_IS.json",
    "it-IT": "/i18n/1.0/it_IT.json",
    "ja-JP": "/i18n/1.0/ja_JP.json",
    "ko-KR": "/i18n/1.0/ko_KR.json",
    "no-NO": "/i18n/1.0/no_NO.json",
    "pl-PL": "/i18n/1.0/pl_PL.json",
    "pt-PT": "/i18n/1.0/pt_PT.json",
    "pt-BR": "/i18n/1.0/pt_BR.json",
    "ro-RO": "/i18n/1.0/ro_RO.json",
    "ru-RU": "/i18n/1.0/ru_RU.json",
    "sk-SK": "/i18n/1.0/sk_SK.json",
    "es-ES": "/i18n/1.0/es_ES.json",
    "sv-SE": "/i18n/1.0/sv_SE.json"
  }
}

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

The human-readable name of the add-on

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

Copy
1
2
3
4
5
6
{
  "links": {
    "self": "https://addon.domain.com/atlassian-connect.json",
    "documentation": "https://addon.domain.com/docs"
  }
}

Set of scopes requested by this add on

Copy
1
2
3
4
5
6
{
  "scopes": [
    "read",
    "write"
  ]
}

A unique key to identify the add-on. This key must only contain alphanumeric characters, dashes, underscores, and dots. A key without an alias key value must be <= 64 characters in length. Where an alias key is provided, the length limit is increased to 90 characters

Settings used for server to cloud app migrations

Defines the authentication type to use when signing requests from the host application to the Connect add-on.

Example

Copy
1
2
3
4
5
{
  "authentication": {
    "type": "jwt"
  }
}