The identifier field
\n The identifier field refers to the name attribute of the var element in a blueprint\n template. If the identifier is matched with a template variable, the value is used in the substitution.\n If a template contains a variable, but there is no matching identifier in the context, an error is generated.\n An identifier with no matching template variable is regarded as a no-op.\n \n The identifier field for each context object must be unique. It is an error to have more than one context object with\n the same identifier, and it is undefined which will get picked during substitution.\n
\n
\n Some identifier names are reserved for use with special meaning during substitution. They\n must have a representation field with the value plain. The list below describes the meaning\n of each existing reserved identifier.\n\n
- \n
- \n
ContentPageTitle: allows the blueprint template to set the page title. It must not contain any\n characters that cannot be used as a Confluence page title. If this reservedidentifieris not\n found in the context, the page created from the blueprint will not have a title set and\n will require the user to set it before it can be saved. The blueprint module must also specify\n 'edit' as the value of thecreateResultfield in this case. Note: the capital 'C'\n in the name is not a mistake or typo.\n \n - \n
labelsString: A space separated list of labels. The labels will be added to the page being created\n by this blueprint. See \n the Confluence docs about labels for more information.\n \n
identifiers.\n\n The representation field
\n \n The representation field must be one of the following values. If unset, it will default to plain.\n
- \n
plain\n wiki\n storage\n
The value field
\n \n The value field must be in the same format as the representation field.\n If the format is incorrect (such as mismatched tags in storage format), an error message will be displayed\n in the resulting page. Here's an explanation of what each format means:\n\n
- \n
- \n
plain: Plain text, which is HTML escaped during variable substitution. Use this for simple textual substitution.\n \n - \n
wiki: Valid \n Confluence Wiki Markup. The wiki markup will be rendered into html during substitution into the page.\n The resulting page will not contain any wiki markup. Use this format when simple styling\n is required (such as emphasis, underlines or and tables etc).\n \n - \n
storage: Valid \n Confluence Storage Format. This value is substituted into the page directly, before the page is rendered. Use this format\n to insert Confluence macros dynamically as part of your blueprint. See Macros\n for a list of available Confluence macros, including storage format examples.\n \n
Example of the request POST body
\n The context url may need some information to produce a more individually suitable response. Confluence\n will send some information related to the blueprint in the body of the request during the creation process.\n Here's an example of what will be sent in the body of the POST request:\n\n {\n \"addonKey\": \"addon-key\",\n \"blueprintKey\": \"blueprint-key\",\n \"spaceKey\": \"SPACEKEY\",\n \"userKey\": \"edd16ba6-0d41-4313-8bb9-84dc82cf6e7c\",\n \"userLocale\": \"fr_FR\"\n }\n\n\n\n- \n
addonKey: the key of the add-on that the blueprint is part of. \n blueprintKey: the key of the blueprint that triggered this context request. \n spaceKey: the space to create the page in (this is selected by the user in the Create dialog). \n userKey: the user key of the user creating the page from blueprint. \n userLocale: the locale of the user creating the page from blueprint. \n
\n
Expected response format
\n The expected response from the context URL is a JSON array of objects with certain fields:\n\n\n\n [\n {\n \"identifier\": \"ContentPageTitle\",\n \"value\": \"Unique Page Title 1\",\n \"representation\": \"plain\"\n },\n {\n \"identifier\": \"custom-key1\",\n \"value\": \"custom value 1\",\n \"representation\": \"plain\"\n },\n {\n \"identifier\": \"custom-key2\",\n \"value\": \"The identifier field
\n The identifier field refers to the name attribute of the var element in a blueprint\n template. If the identifier is matched with a template variable, the value is used in the substitution.\n If a template contains a variable, but there is no matching identifier in the context, an error is generated.\n An identifier with no matching template variable is regarded as a no-op.\n \n The identifier field for each context object must be unique. It is an error to have more than one context object with\n the same identifier, and it is undefined which will get picked during substitution.\n
\n
\n Some identifier names are reserved for use with special meaning during substitution. They\n must have a representation field with the value plain. The list below describes the meaning\n of each existing reserved identifier.\n\n
- \n
- \n
ContentPageTitle: allows the blueprint template to set the page title. It must not contain any\n characters that cannot be used as a Confluence page title. If this reservedidentifieris not\n found in the context, the page created from the blueprint will not have a title set and\n will require the user to set it before it can be saved. The blueprint module must also specify\n 'edit' as the value of thecreateResultfield in this case. Note: the capital 'C'\n in the name is not a mistake or typo.\n \n - \n
labelsString: A space separated list of labels. The labels will be added to the page being created\n by this blueprint. See \n the Confluence docs about labels for more information.\n \n
identifiers.\n\n The representation field
\n \n The representation field must be one of the following values. If unset, it will default to plain.\n
- \n
plain\n wiki\n storage\n
The value field
\n \n The value field must be in the same format as the representation field.\n If the format is incorrect (such as mismatched tags in storage format), an error message will be displayed\n in the resulting page. Here's an explanation of what each format means:\n\n
- \n
- \n
plain: Plain text, which is HTML escaped during variable substitution. Use this for simple textual substitution.\n \n - \n
wiki: Valid \n Confluence Wiki Markup. The wiki markup will be rendered into html during substitution into the page.\n The resulting page will not contain any wiki markup. Use this format when simple styling\n is required (such as emphasis, underlines or and tables etc).\n \n - \n
storage: Valid \n Confluence Storage Format. This value is substituted into the page directly, before the page is rendered. Use this format\n to insert Confluence macros dynamically as part of your blueprint. See Macros\n for a list of available Confluence macros, including storage format examples.\n \n
Example of the request POST body
\n The context url may need some information to produce a more individually suitable response. Confluence\n will send some information related to the blueprint in the body of the request during the creation process.\n Here's an example of what will be sent in the body of the POST request:\n\n {\n \"addonKey\": \"addon-key\",\n \"blueprintKey\": \"blueprint-key\",\n \"spaceKey\": \"SPACEKEY\",\n \"userKey\": \"edd16ba6-0d41-4313-8bb9-84dc82cf6e7c\",\n \"userLocale\": \"fr_FR\"\n }\n\n\n\n- \n
addonKey: the key of the add-on that the blueprint is part of. \n blueprintKey: the key of the blueprint that triggered this context request. \n spaceKey: the space to create the page in (this is selected by the user in the Create dialog). \n userKey: the user key of the user creating the page from blueprint. \n userLocale: the locale of the user creating the page from blueprint. \n
\n A blueprint template is static - the same template will produce the same Confluence page. To produce Confluence\n pages dynamically (to create a different page for a different user), the template needs to\n use variable substitution to produce the dynamic parts. Variable substitution requires the add-on to provide data\n for substitution. Collectively, this data is called the context for substitution.\n
\n The context is made up of a list of objects which are retrieved from the context url specified by the blueprint\n context url field in this module descriptor. See Properties for the definition of each field in the context.\n\n
Substituting dynamic variables in a blueprint
\n\n Let's say we have a blueprint template module /blueprints/blueprint.xml:\n
<h2 id="static1">Hello Blueprint</h2>\n <h2 id="custom1"><at:var at:name="ContentPageTitle"/></h2>\n <h2 id="custom2"><at:var at:name="custom-key1"/></h2>\n <h2 id="custom3"><at:var at:rawxhtml="true" at:name="custom-key2"/></h2>\n \n And an add-on server resource \n During blueprint page creation, Confluence sends a POST request to \n The final, variable substituted, storage format will look like this:\n \n This is then used as the Confluence page to be saved to the database and displayed to the user according to the\n \n An error message appears in the Content Create Dialog if Confluence has any problems accessing the blueprint\n template or context URL (for example if your add-on server failed to respond in 10 seconds or the JSON\n returned is invalid). A detailed error and/or stacktrace may be accessible by Atlassian support, but the end user will see an\n error like the one shown here:\n \n Add-ons wanting to retain backwards compatibility for their blueprint templates should ensure that any variables\n used in a template are always returned in the context url, even if a new version of the blueprint template no\n longer uses it (for example if users are relying on an old or customized version of the template). This ensures that the template\n continues to function when the add-on updates the template.",
"fieldDescription": "\n\nDefines the add-on server endpoint that provides the JSON objects used for substituting variables in the blueprint template.\n \n \n For more information on defining variables in blueprint templates, check out the examples in\n Blueprint Template Context.\n\n"
},
"url": {
"format": "uri",
"type": "string",
"fieldDescription": "\n\nThe URL of the add-on resource that provides the blueprint template content. This URL has to be relative\n to the add-on base URL.\n\n",
"description": "\n\nThe URL of the add-on resource that provides the blueprint template content. This URL has to be relative\n to the add-on base URL.\n\n"
}
},
"required": [
"url"
],
"shortClassName": "blueprintTemplateBean",
"type": "object",
"title": "Blueprint Template",
"description": "\n\nDefines where the blueprint template is located and the context for variable substitution.\n\n\n\n {\n \"template\": {\n \"url\": \"/blueprints/blueprint.xml\",\n \"blueprintContext\": {\n \"url\": \"/blueprints/context\"\n }\n }\n }\n\n\n",
"fieldDescription": "\n\nDefines where the blueprint template is located and the context for variable substitution. \n This key must be unique relative to the add on, with the exception of Confluence macros: Their keys need to be\n globally unique.\n \n Keys must only contain alphanumeric characters and dashes.\n \n The key is used to generate the url to your add-on's module. The url is generated as a combination of your add-on\n key and module key. For example, an add-on which looks like:\n \n {\n \"key\": \"my-addon\",\n \"modules\": {\n \"configurePage\": {\n \"key\": \"configure-me\",\n }\n }\n }\n \n Will have a configuration page module with a URL of `/plugins/servlet/ac/my-addon/configure-me`.\n\n",
"description": "\n\nA key to identify this module.\n \n This key must be unique relative to the add on, with the exception of Confluence macros: Their keys need to be\n globally unique.\n \n Keys must only contain alphanumeric characters and dashes.\n \n The key is used to generate the url to your add-on's module. The url is generated as a combination of your add-on\n key and module key. For example, an add-on which looks like:\n \n {\n \"key\": \"my-addon\",\n \"modules\": {\n \"configurePage\": {\n \"key\": \"configure-me\",\n }\n }\n }\n \n Will have a configuration page module with a URL of `/plugins/servlet/ac/my-addon/configure-me`.\n\n"
}
},
"required": [
"template",
"name",
"key"
],
"shortClassName": "blueprintModuleBean",
"type": "object",
"title": "Blueprint",
"description": "\n\nBlueprints allow your connect add on to provide content creation templates.\n\n\n\n {\n \"modules\": {\n \"blueprints\": [\n {\n \"template\": {\n \"url\": \"/blueprints/blueprint.xml\",\n \"blueprintContext\": {\n \"url\": \"/blueprints/context\"\n }\n },\n \"createResult\": \"edit\",\n \"description\": {\n \"value\": \"This is a description.\"\n },\n \"icon\": {\n \"width\": 48,\n \"height\": 48,\n \"url\": \"/my-blueprint-icon.png\"\n },\n \"name\": {\n \"value\": \"Simple Remote Blueprint\"\n },\n \"key\": \"remote-blueprint\"\n }\n ]\n }\n }\n\n\n"
},
"type": "array",
"fieldDescription": "\n\nBlueprints allow your connect add on provide content creation templates.\n\n",
"description": "\n\nBlueprints allow your connect add on provide content creation templates.\n\n"
},
"spaceToolsTabs": {
"items": {
"$ref": "#/definitions/spaceTools"
},
"type": "array",
"fieldDescription": "\n\nThe Space Tools Tab module allows you to add new tabs to the Space Tools area of Confluence.\n\n",
"description": "\n\nThe Space Tools Tab module allows you to add new tabs to the Space Tools area of Confluence.\n\n"
},
"confluenceContentProperties": {
"items": {
"properties": {
"name": {
"$ref": "#/definitions/i18nProperty",
"fieldDescription": "\n\nA human readable name.\n\n",
"description": "\n\nA human readable name.\n\n"
},
"key": {
"pattern": "^[a-zA-Z0-9-]+$",
"maxLength": 100,
"type": "string",
"fieldDescription": "\n\nA key to identify this module.\n \n This key must be unique relative to the add on, with the exception of Confluence macros: Their keys need to be\n globally unique.\n \n Keys must only contain alphanumeric characters and dashes.\n \n The key is used to generate the url to your add-on's module. The url is generated as a combination of your add-on\n key and module key. For example, an add-on which looks like:\n \n {\n \"key\": \"my-addon\",\n \"modules\": {\n \"configurePage\": {\n \"key\": \"configure-me\",\n }\n }\n }\n \n Will have a configuration page module with a URL of `/plugins/servlet/ac/my-addon/configure-me`.\n\n",
"description": "\n\nA key to identify this module.\n \n This key must be unique relative to the add on, with the exception of Confluence macros: Their keys need to be\n globally unique.\n \n Keys must only contain alphanumeric characters and dashes.\n \n The key is used to generate the url to your add-on's module. The url is generated as a combination of your add-on\n key and module key. For example, an add-on which looks like:\n \n {\n \"key\": \"my-addon\",\n \"modules\": {\n \"configurePage\": {\n \"key\": \"configure-me\",\n }\n }\n }\n \n Will have a configuration page module with a URL of `/plugins/servlet/ac/my-addon/configure-me`.\n\n"
},
"keyConfigurations": {
"items": {
"properties": {
"propertyKey": {
"maxLength": 100,
"type": "string",
"fieldDescription": "\n\nThe key of the property from which the data is indexed. Only alphanumeric and underscore ( \n Important: Must be globally unique. Prefixing it with the name of your add-on is the best way\n to ensure this.\n\n",
"description": "\n\nThe key of the property from which the data is indexed. Only alphanumeric and underscore ( \n Important: Must be globally unique. Prefixing it with the name of your add-on is the best way\n to ensure this.\n\n"
},
"extractions": {
"items": {
"properties": {
"uiSupport": {
"$ref": "#/definitions/uiSupport",
"fieldDescription": "\n\n \n Note: You need to define an \n Note: You need to define an \n For instance, for JSON \n Currently, specifying indexes for JSON arrays is not supported.\n\n",
"description": "\n\nThe \n For instance, for JSON \n Currently, specifying indexes for JSON arrays is not supported.\n\n"
},
"alias": {
"type": "string",
"fieldDescription": "\n\nA CQL field name alias for this content property. Only alphanumeric and underscore ( \n By defining an alias you are exposing it to CQL and allow other macros and search features to easily use\n your content property in their search.\n \n Important: Must be globally unique. Prefixing it with the name of your add-on is the best way\n to ensure this.\n\n",
"description": "\n\nA CQL field name alias for this content property. Only alphanumeric and underscore ( \n By defining an alias you are exposing it to CQL and allow other macros and search features to easily use\n your content property in their search.\n \n Important: Must be globally unique. Prefixing it with the name of your add-on is the best way\n to ensure this.\n\n"
},
"type": {
"enum": [
"number",
"NUMBER",
"string",
"STRING",
"text",
"TEXT",
"date",
"DATE"
],
"type": "string",
"fieldDescription": "\n\nThe type of the referenced value.\n \n The type can be one of the following values:\n \n * \n The type can be one of the following values:\n \n * \n An extraction recipe defines which values within your JSON content property will be added to the search\n index and made available to CQL queries as a field. This can allow you to track custom information\n and make it look like a simple field on the content object.\n \n You can further extend the field definition by including\n UI support.\n \n See the content property key documentation for\n a complete example.\n\n Example \n Each content property key will define one or more\n extractions which will\n allow for multiple values from your JSON content property to be used in CQL. Each extraction defines a single field\n that will be queryable using the relevant CQL syntax as seen below.\n \n In the wordcount example, we store details of the page\n that describe the word and character counts.\n \n After storing this JSON object as a content property:\n\n \n We then define a series of extractions to allow access to the 'wordCount' and 'characterCount'\n properties.\n\n \n You can access this property in your CQL queries as:\n\n \n This is constructed using the following:\n\n \n You can simplify the CQL syntax even further by defining an alias for the extraction:\n\n \n This allows you to refer to your data using the alias:\n\n Example \n Content properties are one of the forms of persistence available for Confluence Connect add-ons, allowing you\n to store key-value pairs against a piece of content, where the value must be well formed JSON. Content Properties are\n stored as JSON objects, and allow you to track extra information that your add-on needs, without the use of a\n backing data-store. Values from these JSON objects can be extracted, indexed and made available to CQL queries.\n\n \n To start creating and manipulating content properties, you don't need to declare anything in your descriptor. Just use the\n REST API\n to store your JSON data against a piece of content.\n \n To integrate with search, you'll need to define some\n extractions to declare what fields and nested data you want to be\n indexable by Confluence. You can also optionally define an alias\n for simpler CQL querying, and UI support for your fields to be filterable by\n users on the search screen and in the CQL query builder.\n \n Once you've done that, you can use CQL\n to query content based on your custom content property.\n\n Example \n This key must be unique relative to the add on, with the exception of Confluence macros: Their keys need to be\n globally unique.\n \n Keys must only contain alphanumeric characters and dashes.\n \n The key is used to generate the url to your add-on's module. The url is generated as a combination of your add-on\n key and module key. For example, an add-on which looks like:\n \n {\n \"key\": \"my-addon\",\n \"modules\": {\n \"configurePage\": {\n \"key\": \"configure-me\",\n }\n }\n }\n \n Will have a configuration page module with a URL of `/plugins/servlet/ac/my-addon/configure-me`.\n\n",
"description": "\n\nA key to identify this module.\n \n This key must be unique relative to the add on, with the exception of Confluence macros: Their keys need to be\n globally unique.\n \n Keys must only contain alphanumeric characters and dashes.\n \n The key is used to generate the url to your add-on's module. The url is generated as a combination of your add-on\n key and module key. For example, an add-on which looks like:\n \n {\n \"key\": \"my-addon\",\n \"modules\": {\n \"configurePage\": {\n \"key\": \"configure-me\",\n }\n }\n }\n \n Will have a configuration page module with a URL of `/plugins/servlet/ac/my-addon/configure-me`.\n\n"
},
"apiSupport": {
"$ref": "#/definitions/apiSupport",
"fieldDescription": "\n\nThis property allows you to specify the container types your custom content can appear in, and its supported child content types.\n It also allows you to enable indexing of your custom content.\n\n",
"description": "\n\nThis property allows you to specify the container types your custom content can appear in, and its supported child content types.\n It also allows you to enable indexing of your custom content.\n\n"
}
},
"required": [
"uiSupport",
"name",
"key",
"apiSupport"
],
"shortClassName": "customContentModuleBean",
"type": "object",
"title": "Custom Content",
"description": "\n\n You can declare custom content in Confluence. This content behaves like built-in Confluence content types, such as page, blog post, or comment. Custom content can be: \n You can also find a step by step tutorial series covering all the aspects of custom content here:\n Custom Content with Confluence Connect\n\n\n\n {\n \"modules\": {\n \"customContent\": [\n {\n \"uiSupport\": {\n \"contentViewComponent\": {\n \"addonKey\": \"addon-key\",\n \"moduleKey\": \"dialog-module-key\"\n },\n \"icons\": {\n \"item\": {\n \"width\": 16,\n \"height\": 16,\n \"url\": \"/item.png\"\n }\n }\n },\n \"apiSupport\": {\n \"bodyType\": \"storage\",\n \"supportedContainerTypes\": [\n \"space\",\n \"page\"\n ],\n \"supportedChildTypes\": [\n \"attachment\",\n \"comment\"\n ],\n \"supportedSpacePermissions\": [],\n \"preventDuplicateTitle\": false,\n \"indexing\": {\n \"enabled\": true\n }\n },\n \"name\": {\n \"value\": \"My Content Type Name\"\n },\n \"key\": \"my-custom-content\"\n }\n ]\n }\n }\n\n\n\n\n\n The above snippet defines your custom content: The content type key for custom content is defined in 3 parts: Content type key When this payload information is POSTed to your Atlassian Connect service you may receive the See active migrations page for the list of currently active API migrations. Example Example See this guide for more information See this guide for more information Example The add-on descriptor is a JSON file ( If you're familiar with Java add-on development with previous versions of the Atlassian Plugin Framework, you may already be\n 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\n cloud instance installs an add-on, what they are really doing is installing this descriptor file, which\n 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\"\n 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\n at any time, without having to create a new version or report the change to the Atlassian instance. The changes are\n 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\n to have a new page module. Since this requires a page module declaration in the descriptor, it means making an updated\n descriptor available. Until that updated descriptor is re-installed into the Atlassian Product that change in the descriptor\n file will not take effect. To propagate a change in the descriptor to the Atlassian products, you need to create a new version\n of the add-on in its Marketplace listing. The Marketplace will take care of the rest: informing administrators\n and automatically installing the available update. See [Upgrades](/platform/marketplace/upgrading-and-versioning-cloud-apps/) for more details. Example Example Example \n This field is required if the \n This field is required if the An object containing options which vary based on the type of web item target you are implementing. Currently-allowed options are: The key of a Dialog module declared in this Connect add-on. \n The dialog module will include the Dialog Options\n that would otherwise need to be specified directly in this options object.\n The key of a Dialog module declared in this Connect add-on. \n The dialog module will include the Dialog Options\n that would otherwise need to be specified directly in this options object.\n \n This option is used instead of the 'height' and 'width' options.\n \n This option is used instead of the 'height' and 'width' options.\n \n These options are a subset of those available via the JavaScript API.\n Deprecated due to poor user experience. Determines whether the Inline Dialog can be opened by a mouseenter event on the trigger, as well as the default click. Deprecated due to poor user experience. Determines whether the Inline Dialog can be opened by a mouseenter event on the trigger, as well as the default click. An object containing options which vary based on the type of web item target you are implementing. Currently-allowed options are: More details for this use-case can be found on the Dialog Module page. Example Example Adds a web item to a specified location in the application interface. A web item is a hyperlink\n that's inserted into some standard place in the Atlassian application interface, such as the\n administration menu. The form that the link takes can vary depending on the location. For instance, a web item in the header bar\n (with a location section of `system.top.navigation.bar`) adds a link to the navigation bar across the top of the\n interface. On the other hand, a web item in the `opsbar-operation` location section in Jira adds an item to the\n issue operation buttons. A web item link can open a new page in the application or a dialog, depending on your configuration. Web items are a simple and useful way to extend Atlassian applications. If you want to extend an Atlassian\n application and don't know where to start, a web item may be all you need. Your add-on can receive [additional context](../../context-parameters/) from the application by\n using variable tokens in the `url` attribute. Example Location in the application interface for this panel. Location in the application interface for this panel. Example Example Example Example \n This option is used instead of the 'height' and 'width' options.\n \n This option is used instead of the 'height' and 'width' options.\n \n These options are a subset of those available via the JavaScript API.\n Example Example \n To invert a condition, add the attribute ``invert=\"true\"`` to the condition element.\n This is useful where you want to show the section if a certain condition is not satisfied.\n\n Determines the order in which the web section appears in the menu or list. The \"lightest\" weight (i.e., lowest number) appears first, rising relative to other items, while the \"heaviest\"\n weights sink to the bottom of the menu or list. Built-in web sections have weights that are incremented by numbers that leave room for additional sections, such\n as by 10 or 100. Be mindful of the weight you choose for your item, so that it appears in a sensible order given\n existing items. Determines the order in which the web section appears in the menu or list. The \"lightest\" weight (i.e., lowest number) appears first, rising relative to other items, while the \"heaviest\"\n weights sink to the bottom of the menu or list. Built-in web sections have weights that are incremented by numbers that leave room for additional sections, such\n as by 10 or 100. Be mindful of the weight you choose for your item, so that it appears in a sensible order given\n existing items. Example Example Example An object containing options for this dialog. An object containing options for this dialog. A common dialog definition that may be referenced by other Connect modules and from JavaScript API calls. \n For example, take the following dialog module:\n \n This common dialog might be referenced from a web item target, so that\n triggering the web item launches the dialog:\n \n The common dialog might also be referenced when creating a Dialog manually with the\n JavaScript API:\n Deprecated due to poor user experience. Determines whether the Inline Dialog can be opened by a mouseenter event on the trigger, as well as the default click. Deprecated due to poor user experience. Determines whether the Inline Dialog can be opened by a mouseenter event on the trigger, as well as the default click. Example Example Page modules allow add-ons to insert new pages into Atlassian products. These can be automatically resized to the width\n and height of your add-on's content. The location attribute defines where links to the new page appear. Each type of page displays differently: You can also define a page module to be shown when a user is administering your add-on via the\n [Universal Plugin Manager](https://confluence.atlassian.com/x/z4Q5Eg). An add-on can only define a single page of\n this type. It should each be defined in the descriptor as a single JSON object, not as a JSON array like\n other modules. The content for a page module is injected into the Atlassian application in the form of a \"seamless\" iframe.\n Seamless iframes are regular HTML iframes but with the characteristics described below. As implied here, for most page content modules, you do not need to be concerned with iframe sizing.\n It's all handled for you. However, an exception exists for inline macros. Example Example Example Admin Pages display in the administration area. Appropriate menus and other styling appear around your content.\n Use these pages in order to provide extra administration functionality. You can also define admin page modules to be shown when a user is administering your add-on via the\n [Universal Plugin Manager](https://confluence.atlassian.com/x/z4Q5Eg). An add-on can only define a single page of\n each of these types. They should each be defined in the descriptor as a single JSON object, not as a JSON array like\n other modules. The content for an admin page module is injected into the Atlassian application in the form of a \"seamless\" iframe.\n Seamless iframes are regular HTML iframes but with the characteristics described below. As implied here, for most admin page content modules, you do not need to be concerned with iframe sizing.\n It's all handled for you. However, an exception exists for inline macros. The key of a Dialog module declared in this Connect add-on. \n The dialog module will include the Dialog Options\n that would otherwise need to be specified directly in this options object.\n The key of a Dialog module declared in this Connect add-on. \n The dialog module will include the Dialog Options\n that would otherwise need to be specified directly in this options object.\n \n For example: \n For example: \n Confluence will provide the breadcrumbs, title input, submit and cancel button on the edit component.\n Add-on needs to supply the editor area like the screenshot shown below in a general page module. \n Confluence will provide the breadcrumbs, title input, submit and cancel button on the edit component.\n Add-on needs to supply the editor area like the screenshot shown below in a general page module. \n The view component is displayed in these places:\n \n The view component is displayed in these places:\n \n And we have following custom content created in the Confluence:\n \n By using the Relation API we can create following relations between these content:\n \n Since we have let \n Similarly the site search will display the breadcrumbs as well:\n \n And also the general page is used as a view component in ui support section.\n\n {\n \"contentViewComponent\": {\n \"moduleKey\": \"my-viewer\"\n }\n }\n\n\n\n \n When a user clicks the title of the corresponding custom content in the search result.\n \n The \"lightest\" weight (i.e., lowest number) appears first, rising relative to other items,\n while the \"heaviest\" weights sink to the bottom of the menu or list.\n \n Built-in web items have weights that are incremented by numbers that leave room for additional\n items, such as by 10 or 100. Be mindful of the weight you choose for your item, so that it appears\n in a sensible order given existing items.\n\n",
"defaultValue": "100",
"description": "\n\nDetermines the order in which the page's link appears in the menu or list.\n \n The \"lightest\" weight (i.e., lowest number) appears first, rising relative to other items,\n while the \"heaviest\" weights sink to the bottom of the menu or list.\n \n Built-in web items have weights that are incremented by numbers that leave room for additional\n items, such as by 10 or 100. Be mindful of the weight you choose for your item, so that it appears\n in a sensible order given existing items.\n\n"
},
"location": {
"maxLength": 100,
"type": "string",
"fieldDescription": "\n\nThe sub-section where this Space Tools Tab should appear. The primary section for Space Tabs is\n `system.space.tools`, and the location specified here will be beneath that. e.g setting a location of\n \"contenttools\" will result in a final location of `system.space.tools/contenttools`.\n \n Confluence comes the following standard sections in Space Tools:\n \n * system.space.tools/overview\n * system.space.tools/permissions\n * system.space.tools/contenttools\n * system.space.tools/lookandfeel\n * system.space.tools/integrations\n * system.space.tools/addons\n \n In future, Connect add-ons will be able to define new web sections, which will enable add-ons to define new\n sub-sections for Space Tools.\n \n Legacy Space Admin section cannot be defined, and is always system.space.admin/spaceops\n\n",
"description": "\n\nThe sub-section where this Space Tools Tab should appear. The primary section for Space Tabs is\n `system.space.tools`, and the location specified here will be beneath that. e.g setting a location of\n \"contenttools\" will result in a final location of `system.space.tools/contenttools`.\n \n Confluence comes the following standard sections in Space Tools:\n \n * system.space.tools/overview\n * system.space.tools/permissions\n * system.space.tools/contenttools\n * system.space.tools/lookandfeel\n * system.space.tools/integrations\n * system.space.tools/addons\n \n In future, Connect add-ons will be able to define new web sections, which will enable add-ons to define new\n sub-sections for Space Tools.\n \n Legacy Space Admin section cannot be defined, and is always system.space.admin/spaceops\n\n"
},
"conditions": {
"items": {
"type": "object",
"anyOf": [
{
"properties": {
"conditions": {
"items": {
"type": "object",
"anyOf": [
{
"$ref": "#"
},
{
"$ref": "#/definitions/singleCondition"
}
]
},
"type": "array",
"fieldDescription": "\n\nThe conditions to compose using the specific logical operator.\n\n",
"description": "\n\nThe conditions to compose using the specific logical operator.\n\n"
},
"type": {
"enum": [
"and",
"AND",
"or",
"OR"
],
"type": "string",
"fieldDescription": "\n\nDefines what logical operator is used to evaluate its collection of condition elements.\n\n",
"description": "\n\nDefines what logical operator is used to evaluate its collection of condition elements.\n\n"
}
},
"shortClassName": "compositeConditionBean",
"type": "object",
"title": "Composite Condition",
"description": "\n\nComposite Conditions are composed of a collection of [Single Condition](../single-condition/) / Composite Conditions\n and a type attribute.\n\n Example Example \n To invert a condition, add the attribute ``invert=\"true\"`` to the condition element.\n This is useful where you want to show the section if a certain condition is not satisfied.\n\n Example Example \n This key must be unique relative to the add on, with the exception of Confluence macros: Their keys need to be\n globally unique.\n \n Keys must only contain alphanumeric characters and dashes.\n \n The key is used to generate the url to your add-on's module. The url is generated as a combination of your add-on\n key and module key. For example, an add-on which looks like:\n \n {\n \"key\": \"my-addon\",\n \"modules\": {\n \"configurePage\": {\n \"key\": \"configure-me\",\n }\n }\n }\n \n Will have a configuration page module with a URL of `/plugins/servlet/ac/my-addon/configure-me`.\n\n",
"description": "\n\nA key to identify this module.\n \n This key must be unique relative to the add on, with the exception of Confluence macros: Their keys need to be\n globally unique.\n \n Keys must only contain alphanumeric characters and dashes.\n \n The key is used to generate the url to your add-on's module. The url is generated as a combination of your add-on\n key and module key. For example, an add-on which looks like:\n \n {\n \"key\": \"my-addon\",\n \"modules\": {\n \"configurePage\": {\n \"key\": \"configure-me\",\n }\n }\n }\n \n Will have a configuration page module with a URL of `/plugins/servlet/ac/my-addon/configure-me`.\n\n"
}
},
"required": [
"name",
"url",
"key"
],
"shortClassName": "spaceToolsTabModuleBean",
"type": "object",
"title": "Space Tools Tab",
"description": "\n\nSpace Tools Tab modules enable add-ons to insert tabs into Confluence Space Tools area. These can be automatically\n resized to the width and height of your add-on's content. The location attribute defines which section the tab will\n appear.\n \n Spaces page with the Documentation Theme do not support the Space Tools area, and instead display the\n legacy Space Admin area. This module will insert a tab in a pre-defined location in Space Admin (look below for a\n complete list of existing locations).\n\n Example The macro parameter indexing property allows apps to hook into the mechanism by which Confluence populates its\n search index for site search. Each time macro is created or updated in Confluence, the value that is stored in\n the macro parameter will be added to the search index.\n The value of this macro parameter will also be used in displaying the excerpt text for search result. This is useful when the body of the macro is not searchable, for example: macros with \n The type of body content, if any, for this macro.\n \n __Note:*__ \n The type of body content, if any, for this macro.\n \n __Note:*__ \n Defining a Macro Editor allows you to implement a custom UI for the macro, by specifying a\n URL to a page in your add-on which will be shown in the dialog iFrame.\n \n In order to persist custom data in your macro editor, use the Javascript\n [Confluence API](../../jsapi/confluence/) and the [Dialog API](../../jsapi/dialog/).\n For example:\n \n \n AP.require([\"confluence\", \"dialog\"], function (confluence, dialog) {\n function onSubmit() {\n var macroParams = {\n myParameter: value\n };\n confluence.saveMacro(macroParams);\n confluence.closeMacroEditor();\n return true;\n }\n \n dialog.getButton(\"submit\").bind(onSubmit);\n });\n \n In order to retrieve the custom data again when the editor is opened, use `confluence.getMacroData` (see\n [Confluence API](../../jsapi/confluence/)):\n \n AP.require(\"confluence\", function (confluence) {\n var macroData = confluence.getMacroData(function(macroParams) {\n doSomethingWith(macroParams.myParameter);\n });\n });\n\n Example \n Additional context parameters can be passed as variables in the URL:\n \n Since macro bodies can be of arbitrary size and may contain sensitive data, care must be taken\n as to how its passed to your connect add-on. You have three options to gain access to the body:\n \n - If you can predict the size of your body and it is consistently less than 128 characters, you\n can include it in the GET request using the `{macro.body}` parameter. \n \n __Note:__ If you include the `{macro.body}` in your URL you are potentially leaking sensitive data\n to any intermediate host on the internet. This may result in the body being cached or indexed\n by a third party. If you are concerned about the security of your macro, you should always use\n the `{macro.id}` and use the Confluence REST API to collect the body.\n \n Here's an example:\n \n Declare the variables that are later required to fetch the macro content in the URL:\n \n Then use the Confluence REST API to collect the body, for example directly from the iframe:\n \n __Preview Mode:__ If you use the `{macro.id}` in your URL, the REST api will not return the macro body during\n a preview request, because the page has not been saved yet. You can use the `{output.type}` parameter to detect\n whether the macro is rendered in preview mode and adapt the response accordingly.\n \n __Note:__ `macro.body` will not be truncated when `renderingMethod` field was set to `POST` in static content macro.\n Refer to the [`Static Content Macros`](../static-content-macro/) for information on\n how to set this field.\n \n Currently supported variables for macros are:\n \n - `macro.hash`: The hash of the macro body (deprecated, use the macro.id) \n Context parameters for macros are also required in the URL. Please see the\n [Macro Input Parameter](../macro-input-parameter/) documentation for details.\n\n",
"description": "\n\nThe link to the add-on resource that provides the macro content.\n This URL has to be relative to the add-on base URL.\n \n Additional context parameters can be passed as variables in the URL:\n \n Since macro bodies can be of arbitrary size and may contain sensitive data, care must be taken\n as to how its passed to your connect add-on. You have three options to gain access to the body:\n \n - If you can predict the size of your body and it is consistently less than 128 characters, you\n can include it in the GET request using the `{macro.body}` parameter. \n \n __Note:__ If you include the `{macro.body}` in your URL you are potentially leaking sensitive data\n to any intermediate host on the internet. This may result in the body being cached or indexed\n by a third party. If you are concerned about the security of your macro, you should always use\n the `{macro.id}` and use the Confluence REST API to collect the body.\n \n Here's an example:\n \n Declare the variables that are later required to fetch the macro content in the URL:\n \n Then use the Confluence REST API to collect the body, for example directly from the iframe:\n \n __Preview Mode:__ If you use the `{macro.id}` in your URL, the REST api will not return the macro body during\n a preview request, because the page has not been saved yet. You can use the `{output.type}` parameter to detect\n whether the macro is rendered in preview mode and adapt the response accordingly.\n \n __Note:__ `macro.body` will not be truncated when `renderingMethod` field was set to `POST` in static content macro.\n Refer to the [`Static Content Macros`](../static-content-macro/) for information on\n how to set this field.\n \n Currently supported variables for macros are:\n \n - `macro.hash`: The hash of the macro body (deprecated, use the macro.id) \n Context parameters for macros are also required in the URL. Please see the\n [Macro Input Parameter](../macro-input-parameter/) documentation for details.\n\n"
},
"propertyPanel": {
"properties": {
"controls": {
"items": {
"type": "object",
"anyOf": [
{
"properties": {
"macroParameter": {
"maxLength": 100,
"type": "string",
"fieldDescription": "\n\nThe Macro Parameter identifier used to store the text\n\n",
"description": "\n\nThe Macro Parameter identifier used to store the text\n\n"
},
"type": {
"enum": [
"text",
"TEXT"
],
"type": "string",
"fieldDescription": "\n\nThe type field must be set to 'text'\n\n",
"description": "\n\nThe type field must be set to 'text'\n\n"
},
"key": {
"pattern": "^[a-zA-Z0-9-]+$",
"maxLength": 100,
"type": "string",
"fieldDescription": "\n\nA key to identify this module.\n \n This key must be unique relative to the add on, with the exception of Confluence macros: Their keys need to be\n globally unique.\n \n Keys must only contain alphanumeric characters and dashes.\n \n The key is used to generate the url to your add-on's module. The url is generated as a combination of your add-on\n key and module key. For example, an add-on which looks like:\n \n {\n \"key\": \"my-addon\",\n \"modules\": {\n \"configurePage\": {\n \"key\": \"configure-me\",\n }\n }\n }\n \n Will have a configuration page module with a URL of `/plugins/servlet/ac/my-addon/configure-me`.\n\n",
"description": "\n\nA key to identify this module.\n \n This key must be unique relative to the add on, with the exception of Confluence macros: Their keys need to be\n globally unique.\n \n Keys must only contain alphanumeric characters and dashes.\n \n The key is used to generate the url to your add-on's module. The url is generated as a combination of your add-on\n key and module key. For example, an add-on which looks like:\n \n {\n \"key\": \"my-addon\",\n \"modules\": {\n \"configurePage\": {\n \"key\": \"configure-me\",\n }\n }\n }\n \n Will have a configuration page module with a URL of `/plugins/servlet/ac/my-addon/configure-me`.\n\n"
}
},
"required": [
"macroParameter",
"type",
"key"
],
"shortClassName": "textControlBean",
"type": "object",
"title": "TextControl",
"description": "\n\nDefines a text field which may appear in control extension points such as the property panel\n\n Example Example Example Example Example Example \n In order to persist custom data using your property panel, use the Javascript\n Confluence API.\n For example:\n \n AP.require([\"confluence\"], function (confluence) {\n var macroParams = {\n myParameter: value\n };\n confluence.saveMacro(macroParams);\n });\n \n In order to retrieve the custom data again when the property panel is opened, use `confluence.getMacroData` (see\n Confluence API):\n \n AP.require(\"confluence\", function (confluence) {\n var macroData = confluence.getMacroData(function(macroParams) {\n doSomethingWith(macroParams.myParameter);\n });\n });\n \n Dialogs may also be created. Use `dialog.create` (see\n Dialog API):\n \n AP.require('dialog', function(dialog) {\n dialog.create({\n key: 'my-module-key',\n width: '500px',\n height: '200px',\n chrome: true\n }).on(\"close\", callbackFunc);\n });\n\n",
"fieldDescription": "\n\nThe configuration of a property panel. Specify a hidden iframe to be loaded in the macro's property panel.\n\n"
},
"autoconvert": {
"$ref": "#/definitions/autoconvert",
"fieldDescription": "\n\nURL patterns associated with this macro. If a URL matching a defined pattern is pasted into the editor, this macro\n will be created and will replace the URL string.\n\n",
"description": "\n\nURL patterns associated with this macro. If a URL matching a defined pattern is pasted into the editor, this macro\n will be created and will replace the URL string.\n\n"
},
"imagePlaceholder": {
"$ref": "#/definitions/imagePlaceholder",
"fieldDescription": "\n\nThe image rendered in the editor as the macro placeholder. It can only be used with bodyless macros and will behave\n just like a regular macro placeholder. Any parameter changes in the macro browser will cause the image\n to be reloaded - so that changes can be seen.\n\n",
"description": "\n\nThe image rendered in the editor as the macro placeholder. It can only be used with bodyless macros and will behave\n just like a regular macro placeholder. Any parameter changes in the macro browser will cause the image\n to be reloaded - so that changes can be seen.\n\n"
},
"renderingMethod": {
"enum": [
"get",
"GET",
"post",
"POST"
],
"type": "string",
"fieldDescription": "\n\nHTTP method that will be used in the HTTP request.\n \n For example: \n Then Confluence will send a POST request to \n For example: \n Then Confluence will send a POST request to \n Currently, the following categories are supported by Confluence:\n \n \n Currently, the following categories are supported by Confluence:\n \n \n Currently the following parameter types are supported in the macro browser's UI:\n \n * `attachment`: displays an autocomplete field for search on attachment filenames.\n * `boolean`: displays a check box.\n * `confluence-content`: displays an autocomplete field for search on page and blog titles.\n * `enum`: displays a select field.\n * `spacekey`: displays an autocomplete field for search on space names.\n * `string`: displays an input field (this is the default if unknown type).\n * `username`: displays an autocomplete field for search on username and full name currently, and will be overridden by Atlassian AccountId after GDPR deprecation period ends. During the deprecation only, a companion parameter with \".accountId\" suffix of the original parameter name will be added.\n\n",
"description": "\n\nThe type of parameter.\n \n Currently the following parameter types are supported in the macro browser's UI:\n \n * `attachment`: displays an autocomplete field for search on attachment filenames.\n * `boolean`: displays a check box.\n * `confluence-content`: displays an autocomplete field for search on page and blog titles.\n * `enum`: displays a select field.\n * `spacekey`: displays an autocomplete field for search on space names.\n * `string`: displays an input field (this is the default if unknown type).\n * `username`: displays an autocomplete field for search on username and full name currently, and will be overridden by Atlassian AccountId after GDPR deprecation period ends. During the deprecation only, a companion parameter with \".accountId\" suffix of the original parameter name will be added.\n\n"
},
"required": {
"type": "boolean",
"fieldDescription": "\n\nWhether it is a required parameter.\n\n",
"defaultValue": "false",
"description": "\n\nWhether it is a required parameter.\n\n"
}
},
"required": [
"identifier",
"name",
"type"
],
"shortClassName": "macroParameterBean",
"type": "object",
"title": "Macro Input Parameter",
"description": "\n\nDescribes a parameter input field for a macro.\n \n Any declared parameters must also be included in the URL value of the macro in order to serialise this value, for\n example, for a macro with a parameter `view` it should be added to the macro url as follows:\n\n \n Please consult Confluence Storage Format\n for additional information about how to construct valid storage format XML.\n\n \n Because any calls to the macro rendering service happen synchronously during page load, we strongly encourage the\n implementations to take advantage of HTTP's caching mechanisms: Often, the rendered content only depends on the macro's\n body and parameters. A good approach for this specific case is to prevent Connect from retrieving the content again, unless\n the parameters or body have actually changed:\n\n \n This response header tells the cache to use the response for an hour without asking the service again.\n Because we declare the macro hash and parameters as URL variables, the URL will automatically change when the macro is changed.\n This change will cause Connect to bypass the cache and to fetch the content from the add-on again.\n So doing non-conditional caching works very well for this case. If the content of the macro varies with other data,\n you could use \n Also keep in mind that the calls are made from the Confluence server to the add-on host. If you need to prevent any caching on the server, use\n\n Example \n When the macro is created in the editor, the URL string that triggered the autoconvert will be captured and inserted\n as a parameter on the macro body. You must define the name of this parameter by providing a string value for 'urlParameter'.\n This allows you to access the URL that triggered the autoconvert.\n\n Example \n This example inserts a macro into the editor when a user pastes in certain simple Facebook links.\n\n\n\n {\n \"renderModes\": {},\n \"url\": \"/dynamic-macro?url={url}\",\n \"categories\": [],\n \"outputType\": \"block\",\n \"bodyType\": \"none\",\n \"aliases\": [],\n \"parameters\": [\n {\n \"identifier\": \"url\",\n \"name\": {\n \"value\": \"URL\"\n },\n \"type\": \"string\",\n \"required\": false,\n \"multiple\": false,\n \"hidden\": false\n }\n ],\n \"autoconvert\": {\n \"urlParameter\": \"url\",\n \"matchers\": [\n {\n \"pattern\": \"https://www.facebook.com/{}/about\"\n },\n {\n \"pattern\": \"https://www.facebook.com/{}/music\"\n },\n {\n \"pattern\": \"https://www.facebook.com/{}/movies/{}\"\n }\n ]\n },\n \"name\": {\n \"value\": \"Dynamic Macro With Autoconvert\"\n },\n \"key\": \"dynamic-macro-with-autoconvert\"\n }\n\n\n"
},
"imagePlaceholder": {
"properties": {
"applyChrome": {
"type": "boolean",
"fieldDescription": "\n\nSet to true if the image should have the macro placeholder chrome applied to it.\n\n",
"defaultValue": "false",
"description": "\n\nSet to true if the image should have the macro placeholder chrome applied to it.\n\n"
},
"width": {
"type": "integer",
"fieldDescription": "\n\nThe width in pixels of the image placeholder. Defaults to the natural image width if not specified.\n\n",
"description": "\n\nThe width in pixels of the image placeholder. Defaults to the natural image width if not specified.\n\n"
},
"url": {
"format": "uri",
"type": "string",
"fieldDescription": "\n\nThe URL of the image placeholder. Your image placeholder needs to be hosted remotely at a web-accessible location.\n You can specify the URL as an absolute URL or relative to the add-on's base URL. \n The url here doesn't support context parameters. However all the macro parameters will be passed as query parameters to the request. \n Suppose you have a macro defined like this:\n\n\n\n {\n \"dynamicContentMacros\": {\n \"renderModes\": {},\n \"url\": \"/my-macro\",\n \"categories\": [],\n \"outputType\": \"block\",\n \"bodyType\": \"none\",\n \"aliases\": [],\n \"parameters\": [\n {\n \"identifier\": \"param1\",\n \"name\": {\n \"value\": \"Parameter 1\"\n },\n \"type\": \"string\",\n \"required\": false,\n \"multiple\": false,\n \"hidden\": false\n },\n {\n \"identifier\": \"param2\",\n \"name\": {\n \"value\": \"Parameter 2\"\n },\n \"type\": \"string\",\n \"required\": false,\n \"multiple\": false,\n \"hidden\": false\n }\n ],\n \"imagePlaceholder\": {\n \"url\": \"/images/placeholder.png\",\n \"applyChrome\": false\n },\n \"name\": {\n \"value\": \"My macro with placeholder\"\n },\n \"key\": \"my-macro-key\"\n }\n }\n\n\n\n \n The Confluence editor will pass the parameter values when requesting the placeholder image:\n \n The url here doesn't support context parameters. However all the macro parameters will be passed as query parameters to the request. \n Suppose you have a macro defined like this:\n\n\n\n {\n \"dynamicContentMacros\": {\n \"renderModes\": {},\n \"url\": \"/my-macro\",\n \"categories\": [],\n \"outputType\": \"block\",\n \"bodyType\": \"none\",\n \"aliases\": [],\n \"parameters\": [\n {\n \"identifier\": \"param1\",\n \"name\": {\n \"value\": \"Parameter 1\"\n },\n \"type\": \"string\",\n \"required\": false,\n \"multiple\": false,\n \"hidden\": false\n },\n {\n \"identifier\": \"param2\",\n \"name\": {\n \"value\": \"Parameter 2\"\n },\n \"type\": \"string\",\n \"required\": false,\n \"multiple\": false,\n \"hidden\": false\n }\n ],\n \"imagePlaceholder\": {\n \"url\": \"/images/placeholder.png\",\n \"applyChrome\": false\n },\n \"name\": {\n \"value\": \"My macro with placeholder\"\n },\n \"key\": \"my-macro-key\"\n }\n }\n\n\n\n \n The Confluence editor will pass the parameter values when requesting the placeholder image:\n Example \n Wildcards (parts of the url that should always match, such as as a unique ID) can be defined using a single open and close\n curly bracket such as '{}'. Use a new brace pair for each separate wildcard.\n \n Keep in mind that you'll need to define a separate matcher for each relevant internet protocol (such as http vs https).\n\n Example \n These embedded static content macros are used to define render mode mappings for your dynamic content macro.\n\n Example \n Setting a \n Setting a \n The type can be one of the following values:\n\n \n The type can be one of the following values:\n\n \n When you define UI support for a field, then the CQL builder will include it in all CQL features\n in Confluence, including other CQL based macros.\n \n See the content property key\n documentation for a complete content property example.\n\n Example Example Example \n An optional Content Property key\n that this Byline Item will be bound to.\n \n The key must only contain alphanumeric characters and dashes.\n \n When a key is supplied, the:\n \n for this Byline item will be overwritten with the property's corresponding value (if present), and the rendered item\n will be updated as the value changes in the browser.\n \n This requires the stored Content Property to have the following format: \n Note that only fields present in the original bean will be respected when substituting values from a\n Content Property later. This means that to show a Content-Property-based \n An optional Content Property key\n that this Byline Item will be bound to.\n \n The key must only contain alphanumeric characters and dashes.\n \n When a key is supplied, the:\n \n for this Byline item will be overwritten with the property's corresponding value (if present), and the rendered item\n will be updated as the value changes in the browser.\n \n This requires the stored Content Property to have the following format: \n Note that only fields present in the original bean will be respected when substituting values from a\n Content Property later. This means that to show a Content-Property-based \n This field is required if the \n Your add-on can receive [additional context](../../context-parameters/) from the application by\n using variable tokens in the URL attribute.\n\n",
"description": "\n\nSpecifies the destination of the web item. The interpretation of this field depends on the value of the\n \n This field is required if the \n Your add-on can receive [additional context](../../context-parameters/) from the application by\n using variable tokens in the URL attribute.\n\n"
},
"key": {
"pattern": "^[a-zA-Z0-9-]+$",
"maxLength": 100,
"type": "string",
"fieldDescription": "\n\nA key to identify this module.\n \n This key must be unique relative to the add on, with the exception of Confluence macros: Their keys need to be\n globally unique.\n \n Keys must only contain alphanumeric characters and dashes.\n \n The key is used to generate the url to your add-on's module. The url is generated as a combination of your add-on\n key and module key. For example, an add-on which looks like:\n \n {\n \"key\": \"my-addon\",\n \"modules\": {\n \"configurePage\": {\n \"key\": \"configure-me\",\n }\n }\n }\n \n Will have a configuration page module with a URL of `/plugins/servlet/ac/my-addon/configure-me`.\n\n",
"description": "\n\nA key to identify this module.\n \n This key must be unique relative to the add on, with the exception of Confluence macros: Their keys need to be\n globally unique.\n \n Keys must only contain alphanumeric characters and dashes.\n \n The key is used to generate the url to your add-on's module. The url is generated as a combination of your add-on\n key and module key. For example, an add-on which looks like:\n \n {\n \"key\": \"my-addon\",\n \"modules\": {\n \"configurePage\": {\n \"key\": \"configure-me\",\n }\n }\n }\n \n Will have a configuration page module with a URL of `/plugins/servlet/ac/my-addon/configure-me`.\n\n"
},
"target": {
"properties": {
"options": {
"type": "object",
"fieldDescription": "\n\n An object containing options which vary based on the type of web item target you are implementing. Currently-allowed options are: Deprecated due to poor user experience. Determines whether the Inline Dialog can be opened by a mouseenter event on the trigger, as well as the default click. Deprecated due to poor user experience. Determines whether the Inline Dialog can be opened by a mouseenter event on the trigger, as well as the default click. The key of a Dialog module declared in this Connect add-on. \n The dialog module will include the Dialog Options\n that would otherwise need to be specified directly in this options object.\n The key of a Dialog module declared in this Connect add-on. \n The dialog module will include the Dialog Options\n that would otherwise need to be specified directly in this options object.\n \n This option is used instead of the 'height' and 'width' options.\n \n This option is used instead of the 'height' and 'width' options.\n \n These options are a subset of those available via the JavaScript API.\n An object containing options which vary based on the type of web item target you are implementing. Currently-allowed options are: More details for this use-case can be found on the Dialog Module page. \n The URL attribute used for Publish Conditions does not support [context parameters](../../context-parameters/).\n However, the [Connect JavaScript API](../../about-the-connect-javascript-api/) can be used to gain the following\n [context](../../jsapi/context/): `content.id`, `content.type`, and `space.key`.\n\n",
"description": "\n\nSpecifies the destination of the dialog content. The interpretation of this field depends on the value of the\n `context` field.\n \n The URL attribute used for Publish Conditions does not support [context parameters](../../context-parameters/).\n However, the [Connect JavaScript API](../../about-the-connect-javascript-api/) can be used to gain the following\n [context](../../jsapi/context/): `content.id`, `content.type`, and `space.key`.\n\n"
},
"height": {
"maxLength": 10,
"type": "string",
"fieldDescription": "\n\nSets how high the dialog is in pixels\n\n",
"description": "\n\nSets how high the dialog is in pixels\n\n"
}
},
"required": [
"url"
],
"shortClassName": "publishConditionDialog",
"type": "object",
"description": "\n\n The dialog allows you to display their custom content within iFrame in the dialog during publish button click. An error message will help you to understand the issue and take necessary action to satisfy the publish condition. \n Note: If `dialog` property is missing, it will be displayed as a notification in Confluence.\n An error message will help you to understand the issue and take necessary action to satisfy the publish condition. \n Note: If `dialog` property is missing, it will be displayed as a notification in Confluence.\n Example Example \n This key must be unique relative to the add on, with the exception of Confluence macros: Their keys need to be\n globally unique.\n \n Keys must only contain alphanumeric characters and dashes.\n \n The key is used to generate the url to your add-on's module. The url is generated as a combination of your add-on\n key and module key. For example, an add-on which looks like:\n \n {\n \"key\": \"my-addon\",\n \"modules\": {\n \"configurePage\": {\n \"key\": \"configure-me\",\n }\n }\n }\n \n Will have a configuration page module with a URL of `/plugins/servlet/ac/my-addon/configure-me`.\n\n",
"description": "\n\nA key to identify this module.\n \n This key must be unique relative to the add on, with the exception of Confluence macros: Their keys need to be\n globally unique.\n \n Keys must only contain alphanumeric characters and dashes.\n \n The key is used to generate the url to your add-on's module. The url is generated as a combination of your add-on\n key and module key. For example, an add-on which looks like:\n \n {\n \"key\": \"my-addon\",\n \"modules\": {\n \"configurePage\": {\n \"key\": \"configure-me\",\n }\n }\n }\n \n Will have a configuration page module with a URL of `/plugins/servlet/ac/my-addon/configure-me`.\n\n"
}
},
"required": [
"errorMessage",
"name",
"key"
],
"shortClassName": "publishConditionModuleBean",
"type": "object",
"title": "Publish Conditions",
"description": "\n\n Example \n The type of body content, if any, for this macro.\n \n __Note:*__ \n The type of body content, if any, for this macro.\n \n __Note:*__ \n Defining a Macro Editor allows you to implement a custom UI for the macro, by specifying a\n URL to a page in your add-on which will be shown in the dialog iFrame.\n \n In order to persist custom data in your macro editor, use the Javascript\n [Confluence API](../../jsapi/confluence/) and the [Dialog API](../../jsapi/dialog/).\n For example:\n \n \n AP.require([\"confluence\", \"dialog\"], function (confluence, dialog) {\n function onSubmit() {\n var macroParams = {\n myParameter: value\n };\n confluence.saveMacro(macroParams);\n confluence.closeMacroEditor();\n return true;\n }\n \n dialog.getButton(\"submit\").bind(onSubmit);\n });\n \n In order to retrieve the custom data again when the editor is opened, use `confluence.getMacroData` (see\n [Confluence API](../../jsapi/confluence/)):\n \n AP.require(\"confluence\", function (confluence) {\n var macroData = confluence.getMacroData(function(macroParams) {\n doSomethingWith(macroParams.myParameter);\n });\n });\n\n Example \n Dynamic Content Macros can include style sheets and javascript, allowing the development of rich interactive\n applications. When your macro is rendered in a web browser this can provide a modern, interactive web experience.\n \n When your macro is rendered to static formats such as PDF, or word, these interactive modes are\n often undesirable, or technically impossible.\n \n Macro Render Modes allow you to map a render mode to a static content macro. This allows you to\n provide an implementation of your macro for these formats, that will render safely to static formats.\n\n Example \n Additional context parameters can be passed as variables in the URL:\n \n Since macro bodies can be of arbitrary size and may contain sensitive data, care must be taken\n as to how its passed to your connect add-on. You have three options to gain access to the body:\n \n - If you can predict the size of your body and it is consistently less than 128 characters, you\n can include it in the GET request using the `{macro.body}` parameter. \n \n __Note:__ If you include the `{macro.body}` in your URL you are potentially leaking sensitive data\n to any intermediate host on the internet. This may result in the body being cached or indexed\n by a third party. If you are concerned about the security of your macro, you should always use\n the `{macro.id}` and use the Confluence REST API to collect the body.\n \n Here's an example:\n \n Declare the variables that are later required to fetch the macro content in the URL:\n \n Then use the Confluence REST API to collect the body, for example directly from the iframe:\n \n __Preview Mode:__ If you use the `{macro.id}` in your URL, the REST api will not return the macro body during\n a preview request, because the page has not been saved yet. You can use the `{output.type}` parameter to detect\n whether the macro is rendered in preview mode and adapt the response accordingly.\n \n __Note:__ `macro.body` will not be truncated when `renderingMethod` field was set to `POST` in static content macro.\n Refer to the [`Static Content Macros`](../static-content-macro/) for information on\n how to set this field.\n \n Currently supported variables for macros are:\n \n - `macro.hash`: The hash of the macro body (deprecated, use the macro.id) \n Context parameters for macros are also required in the URL. Please see the\n [Macro Input Parameter](../macro-input-parameter/) documentation for details.\n\n",
"description": "\n\nThe link to the add-on resource that provides the macro content.\n This URL has to be relative to the add-on base URL.\n \n Additional context parameters can be passed as variables in the URL:\n \n Since macro bodies can be of arbitrary size and may contain sensitive data, care must be taken\n as to how its passed to your connect add-on. You have three options to gain access to the body:\n \n - If you can predict the size of your body and it is consistently less than 128 characters, you\n can include it in the GET request using the `{macro.body}` parameter. \n \n __Note:__ If you include the `{macro.body}` in your URL you are potentially leaking sensitive data\n to any intermediate host on the internet. This may result in the body being cached or indexed\n by a third party. If you are concerned about the security of your macro, you should always use\n the `{macro.id}` and use the Confluence REST API to collect the body.\n \n Here's an example:\n \n Declare the variables that are later required to fetch the macro content in the URL:\n \n Then use the Confluence REST API to collect the body, for example directly from the iframe:\n \n __Preview Mode:__ If you use the `{macro.id}` in your URL, the REST api will not return the macro body during\n a preview request, because the page has not been saved yet. You can use the `{output.type}` parameter to detect\n whether the macro is rendered in preview mode and adapt the response accordingly.\n \n __Note:__ `macro.body` will not be truncated when `renderingMethod` field was set to `POST` in static content macro.\n Refer to the [`Static Content Macros`](../static-content-macro/) for information on\n how to set this field.\n \n Currently supported variables for macros are:\n \n - `macro.hash`: The hash of the macro body (deprecated, use the macro.id) \n Context parameters for macros are also required in the URL. Please see the\n [Macro Input Parameter](../macro-input-parameter/) documentation for details.\n\n"
},
"propertyPanel": {
"properties": {
"controls": {
"items": {
"type": "object",
"anyOf": [
{
"properties": {
"label": {
"$ref": "#/definitions/i18nProperty",
"fieldDescription": "\n\nText which will appear inside the button\n\n",
"description": "\n\nText which will appear inside the button\n\n"
},
"type": {
"enum": [
"button",
"BUTTON"
],
"type": "string",
"fieldDescription": "\n\nThe type field must be set to 'button'\n\n",
"description": "\n\nThe type field must be set to 'button'\n\n"
},
"key": {
"pattern": "^[a-zA-Z0-9-]+$",
"maxLength": 100,
"type": "string",
"fieldDescription": "\n\nA key to identify the control. Keys must only contain alphanumeric characters and dashes, and must be unique",
"description": "\n\nA key to identify the control. Keys must only contain alphanumeric characters and dashes, and must be unique"
}
},
"required": [
"label",
"type",
"key"
],
"additionalProperties": true,
"shortClassName": "buttonControlBean",
"type": "object",
"title": "ButtonControl",
"description": "\n\nDefines a button which may appear in control extension points such as the property panel\n\n Example Example Example Example Example \n This key must be unique relative to the add on, with the exception of Confluence macros: Their keys need to be\n globally unique.\n \n Keys must only contain alphanumeric characters and dashes.\n \n The key is used to generate the url to your add-on's module. The url is generated as a combination of your add-on\n key and module key. For example, an add-on which looks like:\n \n {\n \"key\": \"my-addon\",\n \"modules\": {\n \"configurePage\": {\n \"key\": \"configure-me\",\n }\n }\n }\n \n Will have a configuration page module with a URL of `/plugins/servlet/ac/my-addon/configure-me`.\n\n",
"description": "\n\nA key to identify this module.\n \n This key must be unique relative to the add on, with the exception of Confluence macros: Their keys need to be\n globally unique.\n \n Keys must only contain alphanumeric characters and dashes.\n \n The key is used to generate the url to your add-on's module. The url is generated as a combination of your add-on\n key and module key. For example, an add-on which looks like:\n \n {\n \"key\": \"my-addon\",\n \"modules\": {\n \"configurePage\": {\n \"key\": \"configure-me\",\n }\n }\n }\n \n Will have a configuration page module with a URL of `/plugins/servlet/ac/my-addon/configure-me`.\n\n"
}
},
"required": [
"macroParameter",
"type",
"key"
],
"shortClassName": "textControlBean",
"type": "object",
"title": "TextControl",
"description": "\n\nDefines a text field which may appear in control extension points such as the property panel\n\n Example \n In order to persist custom data using your property panel, use the Javascript\n Confluence API.\n For example:\n \n AP.require([\"confluence\"], function (confluence) {\n var macroParams = {\n myParameter: value\n };\n confluence.saveMacro(macroParams);\n });\n \n In order to retrieve the custom data again when the property panel is opened, use `confluence.getMacroData` (see\n Confluence API):\n \n AP.require(\"confluence\", function (confluence) {\n var macroData = confluence.getMacroData(function(macroParams) {\n doSomethingWith(macroParams.myParameter);\n });\n });\n \n Dialogs may also be created. Use `dialog.create` (see\n Dialog API):\n \n AP.require('dialog', function(dialog) {\n dialog.create({\n key: 'my-module-key',\n width: '500px',\n height: '200px',\n chrome: true\n }).on(\"close\", callbackFunc);\n });\n\n",
"fieldDescription": "\n\nThe configuration of a property panel. Specify a hidden iframe to be loaded in the macro's property panel.\n\n"
},
"autoconvert": {
"$ref": "#/definitions/autoconvert",
"fieldDescription": "\n\nURL patterns associated with this macro. If a URL matching a defined pattern is pasted into the editor, this macro\n will be created and will replace the URL string.\n\n",
"description": "\n\nURL patterns associated with this macro. If a URL matching a defined pattern is pasted into the editor, this macro\n will be created and will replace the URL string.\n\n"
},
"imagePlaceholder": {
"$ref": "#/definitions/imagePlaceholder",
"fieldDescription": "\n\nThe image rendered in the editor as the macro placeholder. It can only be used with bodyless macros and will behave\n just like a regular macro placeholder. Any parameter changes in the macro browser will cause the image\n to be reloaded - so that changes can be seen.\n\n",
"description": "\n\nThe image rendered in the editor as the macro placeholder. It can only be used with bodyless macros and will behave\n just like a regular macro placeholder. Any parameter changes in the macro browser will cause the image\n to be reloaded - so that changes can be seen.\n\n"
},
"refDataSchema": {
"properties": {
"outputType": {
"maxLength": 255,
"type": "string"
},
"inputType": {
"maxLength": 255,
"type": "string"
}
},
"shortClassName": "macroRefDataSchemaBean",
"type": "object",
"description": "\n\nDefines what a dynamic content macro can consume and produce to interoperate with other macros.\n\n\n\n {\n \"inputType\": \"table\",\n \"outputType\": \"chart\"\n }\n\n\n\n\n \n This is useful to chain multiple macros with each other. For example a macro can provide adf table data\n which can be used to produce a chart with it.\n To use this feature, you need to define the input and output types of your macro, of which two are supported: \"table-adf\" and \"table-json\".\n The inputType of a macro is the type of data it consumes; and the outputType of a macro is the type of data it produces.\n The inputType of a macro must match the outputType of another macro to be able to chain them together.\n For example, if a macro produces \"table-adf\" data, it can be chained with another macro that consumes \"table-adf\" data.\n If a macro produces \"table-json\" data, it can be chained with another macro that produces \"table-json\" data.\n By default, a Confluence Native Table produces \"table-adf\" data and a Confluence Native Chart consumes \"table-adf\" data, allowing the Native Table data to be consumeable by the Native Chart.\n Other Connect macros can be created to produce and consume \"table-json\" data, allowing them to be chained together within the Editor.\n \n Currently, the following categories are supported by Confluence:\n \n \n Currently, the following categories are supported by Confluence:\n \n \n Currently the following parameter types are supported in the macro browser's UI:\n \n * `attachment`: displays an autocomplete field for search on attachment filenames.\n * `boolean`: displays a check box.\n * `confluence-content`: displays an autocomplete field for search on page and blog titles.\n * `enum`: displays a select field.\n * `spacekey`: displays an autocomplete field for search on space names.\n * `string`: displays an input field (this is the default if unknown type).\n * `username`: displays an autocomplete field for search on username and full name currently, and will be overridden by Atlassian AccountId after GDPR deprecation period ends. During the deprecation only, a companion parameter with \".accountId\" suffix of the original parameter name will be added.\n\n",
"description": "\n\nThe type of parameter.\n \n Currently the following parameter types are supported in the macro browser's UI:\n \n * `attachment`: displays an autocomplete field for search on attachment filenames.\n * `boolean`: displays a check box.\n * `confluence-content`: displays an autocomplete field for search on page and blog titles.\n * `enum`: displays a select field.\n * `spacekey`: displays an autocomplete field for search on space names.\n * `string`: displays an input field (this is the default if unknown type).\n * `username`: displays an autocomplete field for search on username and full name currently, and will be overridden by Atlassian AccountId after GDPR deprecation period ends. During the deprecation only, a companion parameter with \".accountId\" suffix of the original parameter name will be added.\n\n"
},
"required": {
"type": "boolean",
"fieldDescription": "\n\nWhether it is a required parameter.\n\n",
"defaultValue": "false",
"description": "\n\nWhether it is a required parameter.\n\n"
}
},
"required": [
"identifier",
"name",
"type"
],
"shortClassName": "macroParameterBean",
"type": "object",
"title": "Macro Input Parameter",
"description": "\n\nDescribes a parameter input field for a macro.\n \n Any declared parameters must also be included in the URL value of the macro in order to serialise this value, for\n example, for a macro with a parameter `view` it should be added to the macro url as follows:\n\n \n Since Dynamic Content Macros are rendered in an iframe, you are able to include your own style sheets and javascript.\n You can use these to create a rich, interactive experience for your users.\n \n If the macro allows for arbitrary nested content and uses the Confluence content body conversion endpoint to render the\n nested content within the macro's iframe; then the macro must request the dependent web resources and inject them into the iFrame\n context before displaying the result. See the [content body conversion API documentation](https://developer.atlassian.com/cloud/confluence/rest/api-group-content-body/#api-wiki-rest-api-contentbody-convert-to-post)\n for more details.\n\n Example: rendering nested content \n When your macro is exported to a static format such as PDF or Word, you can use the `renderModes` property to define\n a mapping between a certain type of output device and a static macro implementation. This will allow you to create a\n static view of your macro's data where an interactive model is not appropriate.\n \n For most modules, you do not need to be concerned with iframe sizing. It's all handled for you. However, an exception\n exists for inline macros.\n \n An inline macro is a type of macro that generates content within the text flow of a paragraph or other text element\n in which the macro appears, such as a status lozenge. To implement an inline macro, follow these general guidelines:\n\n Example \n Otherwise the default permissions will be used.\n\n",
"description": "\n\nDefines the space permissions that this custom content supports.\n Allowable values are : \n Otherwise the default permissions will be used.\n\n"
},
"preventDuplicateTitle": {
"type": "boolean",
"fieldDescription": "\n\nDefines whether Confluence should prevent content with duplicate title from being created in the same space or container.\n\n",
"defaultValue": "false",
"description": "\n\nDefines whether Confluence should prevent content with duplicate title from being created in the same space or container.\n\n"
},
"indexing": {
"$ref": "#/definitions/indexing",
"fieldDescription": "\n\nDefines how this content type will be indexed\n\n",
"description": "\n\nDefines how this content type will be indexed\n\n"
},
"supportedContainerTypes": {
"items": {
"maxLength": 100,
"type": "string"
},
"type": "array",
"fieldDescription": "\n\nDefines types that this custom content can be contained in. In the above example, you'll see we specify content type keys in the \n Content with a raw body looks like this:\n /blueprints/context which returns this JSON response as the context:\n\n [\n {\n \"identifier\": \"ContentPageTitle\",\n \"value\": \"Unique Page Title 1\",\n \"representation\": \"plain\"\n },\n {\n \"identifier\": \"custom-key1\",\n \"value\": \"custom value 1\",\n \"representation\": \"plain\"\n },\n {\n \"identifier\": \"custom-key2\",\n \"value\": \"/blueprints/context to retrieve\n the context. The context retrieved is parsed as a JSON array of objects and used in the substitute of\n the variables in the blueprint template above (custom-key1, custom-key2 are the variables).\n
\n <h2>Hello Blueprint</h2>\n <h2>Unique Page Title 1</h2>\n <h2>custom value 1</h2>\n <h2><ac:structured-macro ac:name="cheese" ac:schema-version="1" /></h2>\n createResult field of the blueprint module (see Blueprint Template Module).\n ![\"Blueprint](\"/cloud/connect/images/confluence-blueprint-context-error.png\")
\n\n Backwards compatibility of the
\n A blueprint template containing variables may change as the add-on evolves over time. However, because end users\n can customize blueprint templates, it's possible for the customized version of the template to differ from\n the version in the add-on. This difference won't cause an error as long as the variables used in the template are\n still being returned as part of the context url.\n identifier field
\n For more about how to define variables in blueprint template and template context please follow the example in\n Blueprint Template Context.\n\n"
},
"icon": {
"$ref": "#/definitions/icon",
"fieldDescription": "\n\nDefines an icon for this Blueprint, to be shown in the Create Content dialog.\n\n",
"description": "\n\nDefines an icon for this Blueprint, to be shown in the Create Content dialog.\n\n"
},
"name": {
"$ref": "#/definitions/i18nProperty",
"fieldDescription": "\n\nA human readable name.\n\n",
"description": "\n\nA human readable name.\n\n"
},
"description": {
"$ref": "#/definitions/i18nProperty",
"fieldDescription": "\n\nDefines a short description for this Blueprint, to be shown in the Create Content dialog.\n\n",
"description": "\n\nDefines a short description for this Blueprint, to be shown in the Create Content dialog.\n\n"
},
"createResult": {
"enum": [
"edit",
"EDIT",
"view",
"VIEW"
],
"type": "string",
"fieldDescription": "\n\nDefines the screen to go to when creating this type of Blueprint. A value of `view` causes Confluence to bypass the\n editor page and automatically create the page content. The user lands in the view of the created page. When `edit`,\n the user is sent to the editor which is pre-filled with the template content.\n\n",
"defaultValue": "edit",
"description": "\n\nDefines the screen to go to when creating this type of Blueprint. A value of `view` causes Confluence to bypass the\n editor page and automatically create the page content. The user lands in the view of the created page. When `edit`,\n the user is sent to the editor which is pre-filled with the template content.\n\n"
},
"key": {
"pattern": "^[a-zA-Z0-9-]+$",
"maxLength": 100,
"type": "string",
"fieldDescription": "\n\nA key to identify this module.\n _)\n characters are allowed.\n _)\n characters are allowed.\n uiSupport can be used to define how your aliased field will be displayed in the CQL query builder.\n By defining uiSupport, your content property will appear in the CQL query builder for all macros and search\n features built on CQL. For example, your property will become usable in the\n Content By Label macro, and\n filterable by users on the Confluence search screen.\n alias to use uiSupport.\n\n",
"description": "\n\nuiSupport can be used to define how your aliased field will be displayed in the CQL query builder.\n By defining uiSupport, your content property will appear in the CQL query builder for all macros and search\n features built on CQL. For example, your property will become usable in the\n Content By Label macro, and\n filterable by users on the Confluence search screen.\n alias to use uiSupport.\n\n"
},
"objectName": {
"maxLength": 1000,
"type": "string",
"fieldDescription": "\n\nThe objectName of the JSON data which should be indexed. The objectName is the key of a flattened JSON object with '.' as the path separator.\n \"{\"label\": {\"color\": \"red\", \"text\":\"connect\"}} the valid objectName\n referencing the color is label.color.\n objectName of the JSON data which should be indexed. The objectName is the key of a flattened JSON object with '.' as the path separator.\n \"{\"label\": {\"color\": \"red\", \"text\":\"connect\"}} the valid objectName\n referencing the color is label.color.\n _)\n characters are allowed.\n _)\n characters are allowed.\n number - The extracted number will be indexed as a double value for efficient range filtering and sorting.\n * text - The extracted value will be tokenized before indexing, allowing searching for particular words.\n * string - The entire extracted value will be indexed as a single token, without any filtering. When the extraction\n expression evaluates to a JSON array, each element will be indexed separately. This Enables searching for an exact value, e.g. a unique identifier.\n * date - Two representations are possible: either a string following the ISO 8601 datetime format,\n or a long value in Unix time. This enables efficient range filtering and sorting.\n\n",
"description": "\n\nThe type of the referenced value.\n number - The extracted number will be indexed as a double value for efficient range filtering and sorting.\n * text - The extracted value will be tokenized before indexing, allowing searching for particular words.\n * string - The entire extracted value will be indexed as a single token, without any filtering. When the extraction\n expression evaluates to a JSON array, each element will be indexed separately. This Enables searching for an exact value, e.g. a unique identifier.\n * date - Two representations are possible: either a string following the ISO 8601 datetime format,\n or a long value in Unix time. This enables efficient range filtering and sorting.\n\n"
}
},
"required": [
"objectName",
"type"
],
"shortClassName": "contentPropertyIndexExtractionConfigurationBean",
"type": "object",
"title": "Content Property Index Extraction Configuration",
"description": "\n\nAn extraction recipe for a single value within a content property JSON object.\n
\n \n {\n \"wordCount\": 5\n \"characterCount\": 22\n }\n
\n \n {\n \"propertyKey\": \"wordcount_addon\",\n \"extractions\": [\n { \"objectName\": \"wordCount\", \"type\": \"number\" },\n { \"objectName\": \"characterCount\", \"type\": \"number\" }\n ]\n }\n
\n \n space = currentSpace() and content.property[wordcount_addon].wordCount <= 1000\n
\n \n content.property[propertyKey].objectName\n
\n \n {\n \"propertyKey\": \"wordcount_addon\",\n \"extractions\": [\n { \"objectName\": \"wordCount\", \"type\": \"number\", alias: \"wordcount\" }\n ]\n }\n
\n\n Important: Both the \n space = currentSpace() and wordcount <= 1000\n propertyKey and the alias must be\n globally unique. Prefixing it with the name of your add-on is the best way to ensure this.\n\n Using Content Properties
\n \n
\n Create custom content via the Confluence REST API
\n my-custom-content.\n You can create a new piece of content with this type by posting the following JSON to the Confluence /rest/api/content endpoint.
\n\n\n \n {\n \"type\":\"ac:my-addon-key:my-custom-content\",\n \"title\":\"My content title\",\n \"space\":{\n \"key\":\"ds\"\n },\n \"body\":{\n \"storage\":{\n \"value\":\"This is my content body\",\n \"representation\":\"storage\"\n }\n }\n }\n The content type key
\n \n
\n\n ac
\n This is always the same, indicating that this content type is defined in a Connect add-on.\n my-addon-key
\n The key of the Connect add-on.\n my-custom-content
\n The key of the module which defines the custom content.\n For example:
\n ac:my-addon-key:my-custom-content should be used for\n creating custom content that's defined in a Connect add-on with the key of my-addon-key\n and module key of my-custom-content200 OK or 204 No Content status.\n\n\n\n",
"description": "\n\nWhen a Connect add-on is installed, a synchronous request is fired to this URL to initiate the installation\n handshake. In order to successfully complete installation, the add-on must respond with either a\n 200 OK or 204 No Content status.\n\n\n\n"
},
"disabled": {
"format": "uri",
"type": "string",
"fieldDescription": "\n\nFires when an add on has been successfully disabled. This is an asynchronous notification event.\n\n",
"description": "\n\nFires when an add on has been successfully disabled. This is an asynchronous notification event.\n\n"
},
"dare-migration": {
"type": "string",
"fieldDescription": "\n\nUsed DaRe app migration service to trigger migrations events\n\n",
"description": "\n\nUsed DaRe app migration service to trigger migrations events\n\n"
},
"uninstalled": {
"format": "uri",
"type": "string",
"fieldDescription": "\n\nFires when an add on has been successfully un-installed. This is an asynchronous notification event.\n\n",
"description": "\n\nFires when an add on has been successfully un-installed. This is an asynchronous notification event.\n\n"
},
"enabled": {
"format": "uri",
"type": "string",
"fieldDescription": "\n\nFires when an add on has been successfully enabled. This is an asynchronous notification event.\n\n",
"description": "\n\nFires when an add on has been successfully enabled. This is an asynchronous notification event.\n\n"
}
},
"shortClassName": "lifecycleBean",
"type": "object",
"title": "Lifecycle",
"description": "\n\nAllows an add-on to register callbacks for events that occur in the lifecycle of an installation. When a lifecycle\n event is fired, a POST request will be made to the appropriate URL registered for the event.\n\n The installed lifecycle callback is an integral part of the installation process\n of an add-on, whereas the remaining lifecycle events are essentially webhooks.\n\n Each property in this object is a URL relative to the add-on's base URL.\n\n Lifecycle attribute example
\n\n\n\n {\n \"installed\": \"/installed\",\n \"uninstalled\": \"/uninstalled\",\n \"enabled\": \"/enabled\",\n \"disabled\": \"/disabled\"\n }\n\n\n\n\n Lifecycle HTTP request payload
\n Lifecycle callbacks contain a JSON data payload with important tenant information that you will need to store in your\n add-on in order to sign and verify future requests. The payload contains the following attributes:\n\n {\n \"key\": \"installed-addon-key\",\n \"clientKey\": \"unique-client-identifier\",\n \"sharedSecret\": \"a-secret-key-not-to-be-lost\",\n \"serverVersion\": \"server-version\",\n \"pluginsVersion\": \"version-of-connect\",\n \"baseUrl\": \"https://example.atlassian.net\",\n \"displayUrl\": \"https://jira.example.net\",\n \"productType\": \"jira\",\n \"description\": \"Atlassian Jira at https://example.atlassian.net\",\n \"serviceEntitlementNumber\": \"SEN-number\",\n \"eventType\": \"installed\",\n \"displayUrlServicedeskHelpCenter\": \"https://servicedesk.jira.example.net\"\n }\n\n\n\n\n\n
\n\n \n \n \n Attribute \n Description \n \n \n keyAdd-on key that was installed into the Atlassian Product, as it appears in your add-on's descriptor. \n \n \n clientKeyIdentifying key for the Atlassian product instance that the add-on was installed into. This will never change for a given\n instance, and is unique across all Atlassian product tenants. This value should be used to key tenant details\n in your add-on. The one time the clientKey can change is when a backup taken from a different instance is restored onto the instance.\n Determining the contract between the instance and add-on in this situation is tracked by\n AC-1528 in the Connect backlog. \n \n \n sharedSecretUse this string to sign outgoing JWT tokens and validate incoming JWT tokens. Optional: and may not\n be present on non-JWT add-on installations, and is only sent on the \n installed event.\n \n serverVersionThis is a string representation of the host product's version. Generally you should not need it. \n \n \n pluginsVersionThis is a semver compliant version of Atlassian Connect which is running on the host server, for example: \n 1.1.15.\n \n baseUrlURL prefix for this Atlassian product instance. All of its REST endpoints begin with this `baseUrl`. \n \n \n productTypeIdentifies the category of Atlassian product, e.g. \n jira or confluence.\n \n descriptionThe host product description - this is customisable by an instance administrator. \n \n \n serviceEntitlementNumber\n (optional)Also known as the SEN, the service entitlement number is the add-on license id. This attribute will only be included\n during installation of a paid add-on. \n \n \noauthClientIdThe OAuth 2.0 client ID for your add-on. For more information, see OAuth 2.0 - JWT Bearer token authorization grant type \n Request query parameters
\n\n user\\_key and user\\_id\n query parameters; these query parameters are both deprecated. Deprecated\n If you wish to find out which user enabled your add-on then you should extract the context.user.userKey or context.user.userName\n data from the JWT token on the enabled lifecycle event.atlassian-connect.json) that describes the add-on to the Atlassian application.\n The descriptor includes general information for the add-on, as well as the modules that the add-on wants to use or\n extend.context
field.\n\n target of the item is not a\n Dialog Module.\n context
field.\n\n target of the item is not a\n Dialog Module.\n \n
\n\n",
"anyOf": [
{
"properties": {
"key": {
"maxLength": 100,
"type": "string",
"fieldDescription": "\n\nExample
\n\n\n\n {\n \"target\": {\n \"type\": \"dialogmodule\",\n \"options\": {\n \"key\": \"dialog-module-key\"\n }\n }\n }\n\n\n"
},
{
"properties": {
"size": {
"enum": [
"small",
"SMALL",
"medium",
"MEDIUM",
"large",
"LARGE",
"x-large",
"X-LARGE",
"fullscreen",
"FULLSCREEN",
"maximum",
"MAXIMUM"
],
"type": "string",
"fieldDescription": "\n\nSets the size of the dialog.\n\n Web Item Example
\n\n\n\n {\n \"target\": {\n \"type\": \"dialog\",\n \"options\": {\n \"height\": \"100px\",\n \"width\": \"200px\"\n }\n }\n }\n\n\n\n\n Dialog Example
\n\n {\n \"modules\": {\n \"dialogs\": [\n {\n \"url\": \"/my-dialog-content\",\n \"options\": {\n \"size\": \"fullscreen\",\n \"header\": {\n \"value\": \"Example Dialog\"\n }\n },\n \"key\": \"dialog-module-key\"\n }\n ]\n }\n }\n\n\n"
},
{
"properties": {
"offsetX": {
"maxLength": 10,
"type": "string",
"fieldDescription": "\n\nSets an offset distance of the inline-dialog from the trigger element along the x-axis in pixels\n\n",
"description": "\n\nSets an offset distance of the inline-dialog from the trigger element along the x-axis in pixels\n\n"
},
"offsetY": {
"maxLength": 10,
"type": "string",
"fieldDescription": "\n\nSets an offset distance of the inline-dialog from the trigger element along the y-axis in pixels\n\n",
"description": "\n\nSets an offset distance of the inline-dialog from the trigger element along the y-axis in pixels\n\n"
},
"width": {
"maxLength": 10,
"type": "string",
"fieldDescription": "\n\nSets how wide the dialog is in pixels.\n\n",
"description": "\n\nSets how wide the dialog is in pixels.\n\n"
},
"onTop": {
"type": "boolean",
"fieldDescription": "\n\nDetermines if the dialog should be shown above the trigger or not. If this option is true but there is insufficient room above the trigger the inline-dialog will be flipped to display below it\n\n",
"description": "\n\nDetermines if the dialog should be shown above the trigger or not. If this option is true but there is insufficient room above the trigger the inline-dialog will be flipped to display below it\n\n"
},
"showDelay": {
"type": "integer",
"fieldDescription": "\n\nDetermines how long in milliseconds after a show trigger is fired (such as a trigger click) until the dialog is shown\n\n",
"description": "\n\nDetermines how long in milliseconds after a show trigger is fired (such as a trigger click) until the dialog is shown\n\n"
},
"closeOthers": {
"type": "boolean",
"fieldDescription": "\n\nDetermines if all other dialogs on the screen are closed when this one is opened\n\n",
"description": "\n\nDetermines if all other dialogs on the screen are closed when this one is opened\n\n"
},
"persistent": {
"type": "boolean",
"fieldDescription": "\n\nThis option, ignores the 'closeOthers' option\n\n",
"description": "\n\nThis option, ignores the 'closeOthers' option\n\n"
},
"onHover": {
"type": "boolean",
"fieldDescription": "\n\nExample
\n\n\n\n {\n \"target\": {\n \"type\": \"inlinedialog\",\n \"options\": {\n \"onHover\": true,\n \"offsetX\": \"30px\",\n \"offsetY\": \"20px\"\n }\n }\n }\n\n\n"
}
],
"description": "\n\n\n
\n\n"
},
"type": {
"enum": [
"page",
"PAGE",
"dialog",
"DIALOG",
"inlinedialog",
"INLINEDIALOG",
"dialogmodule",
"DIALOGMODULE"
],
"type": "string",
"fieldDescription": "\n\nDefines how the web-item content should be loaded by the page. By default, the web-item is loaded in the same\n page. The target can be set to open the web-item url as a modal dialog or an inline dialog.\n\n",
"defaultValue": "page",
"description": "\n\nDefines how the web-item content should be loaded by the page. By default, the web-item is loaded in the same\n page. The target can be set to open the web-item url as a modal dialog or an inline dialog.\n\n"
}
},
"shortClassName": "webItemTargetBean",
"type": "object",
"title": "Web Item Target",
"description": "\n\nDefines the way a web item link is opened in the browser, such as in a modal or inline dialog.\n\n Inline Dialog Example
\n\n\n\n {\n \"target\": {\n \"type\": \"inlinedialog\",\n \"options\": {\n \"onHover\": true,\n \"offsetX\": \"30px\",\n \"offsetY\": \"20px\"\n }\n }\n }\n\n\n\n\n Dialog Example
\n\n {\n \"target\": {\n \"type\": \"dialog\",\n \"options\": {\n \"height\": \"100px\",\n \"width\": \"200px\"\n }\n }\n }\n\n\n\n\n Common Dialog Module Example
\n\n {\n \"target\": {\n \"type\": \"dialogmodule\",\n \"options\": {\n \"key\": \"dialog-module-key\"\n }\n }\n }\n\n\n\n\n \n
\n\n",
"defaultValue": "addon",
"description": "\n\nThe context for the URL parameter. Not applicable if an absolute URL is specified. Possible values\n \n
\n\n"
},
"name": {
"$ref": "#/definitions/i18nProperty",
"fieldDescription": "\n\nA human readable name.\n\n",
"description": "\n\nA human readable name.\n\n"
},
"location": {
"maxLength": 100,
"type": "string",
"fieldDescription": "\n\nThe location in the application interface where the web item should appear. For the Atlassian application\n interface, a location is something like the coordinates on a map. It points to a particular drop-down menu or\n navigation list in the UI.\n\n Places in the Atlassian UI are identified by what are known as \"well-known locations\".\n For example, the `system.admin/globalsettings` location is in the administrative\n menu on the left side of the Administration Console.\n\n Find product locations with the Extension Point Finder\n\n \n\n",
"description": "\n\nThe location in the application interface where the web item should appear. For the Atlassian application\n interface, a location is something like the coordinates on a map. It points to a particular drop-down menu or\n navigation list in the UI.\n\n Places in the Atlassian UI are identified by what are known as \"well-known locations\".\n For example, the `system.admin/globalsettings` location is in the administrative\n menu on the left side of the Administration Console.\n\n Find product locations with the Extension Point Finder\n\n \n\n"
},
"cacheable": {
"type": "boolean",
"fieldDescription": "\n\nReturns whether the URL should be cacheable. Cacheable URLs are taken directly from the add-on descriptor, and\n lack all additional query parameters:\n \n
\n\n",
"defaultValue": "false",
"description": "\n\nReturns whether the URL should be cacheable. Cacheable URLs are taken directly from the add-on descriptor, and\n lack all additional query parameters:\n \n
\n\n"
},
"conditions": {
"items": {
"type": "object",
"anyOf": [
{
"properties": {
"conditions": {
"items": {
"type": "object",
"anyOf": [
{
"$ref": "#/definitions/singleCondition"
},
{
"properties": {
"conditions": {
"items": {
"type": "object",
"anyOf": [
{
"$ref": "#/definitions/singleCondition"
},
{
"$ref": "#"
}
]
},
"type": "array",
"fieldDescription": "\n\nThe conditions to compose using the specific logical operator.\n\n",
"description": "\n\nThe conditions to compose using the specific logical operator.\n\n"
},
"type": {
"enum": [
"and",
"AND",
"or",
"OR"
],
"type": "string",
"fieldDescription": "\n\nDefines what logical operator is used to evaluate its collection of condition elements.\n\n",
"description": "\n\nDefines what logical operator is used to evaluate its collection of condition elements.\n\n"
}
},
"shortClassName": "compositeConditionBean",
"type": "object",
"title": "Composite Condition",
"description": "\n\nComposite Conditions are composed of a collection of [Single Condition](../single-condition/) / Composite Conditions\n and a type attribute.\n\n Example
\n\n\n\n {\n \"conditions\": [\n {\n \"or\": [\n {\n \"condition\": \"can_attach_file_to_issue\",\n \"invert\": false\n },\n {\n \"condition\": \"is_issue_assigned_to_current_user\",\n \"invert\": false\n }\n ]\n },\n {\n \"condition\": \"user_is_logged_in\",\n \"invert\": false\n }\n ]\n }\n\n\n"
}
]
},
"type": "array",
"fieldDescription": "\n\nThe conditions to compose using the specific logical operator.\n\n",
"description": "\n\nThe conditions to compose using the specific logical operator.\n\n"
},
"type": {
"enum": [
"and",
"AND",
"or",
"OR"
],
"type": "string",
"fieldDescription": "\n\nDefines what logical operator is used to evaluate its collection of condition elements.\n\n",
"description": "\n\nDefines what logical operator is used to evaluate its collection of condition elements.\n\n"
}
},
"shortClassName": "compositeConditionBean",
"type": "object",
"title": "Composite Condition",
"description": "\n\nComposite Conditions are composed of a collection of [Single Condition](../single-condition/) / Composite Conditions\n and a type attribute.\n\n Example
\n\n\n\n {\n \"conditions\": [\n {\n \"or\": [\n {\n \"condition\": \"can_attach_file_to_issue\",\n \"invert\": false\n },\n {\n \"condition\": \"is_issue_assigned_to_current_user\",\n \"invert\": false\n }\n ]\n },\n {\n \"condition\": \"user_is_logged_in\",\n \"invert\": false\n }\n ]\n }\n\n\n"
},
{
"properties": {
"condition": {
"maxLength": 100,
"type": "string",
"fieldDescription": "\n\nA string indicating the name of the condition\n\n",
"description": "\n\nA string indicating the name of the condition\n\n"
},
"invert": {
"type": "boolean",
"fieldDescription": "\n\nA flag indicating whether to invert the boolean result of the condition.\n\n",
"defaultValue": "false",
"description": "\n\nA flag indicating whether to invert the boolean result of the condition.\n\n"
},
"params": {
"additionalProperties": true,
"type": "object",
"fieldTitle": "Object",
"fieldDescription": "\n\nThis object represents a map of key/value pairs, where each property name and value corresponds to the parameter name and value respectively.\n\n Example
\n\n\n\n {\n \"condition\": \"user_is_logged_in\",\n \"invert\": false\n }\n\n\n"
}
]
},
"type": "array",
"fieldDescription": "\n\nConditions can be added to display only when all the given conditions are true.\n\n",
"description": "\n\nConditions can be added to display only when all the given conditions are true.\n\n"
},
"key": {
"pattern": "^[a-zA-Z0-9-]+$",
"maxLength": 100,
"type": "string",
"fieldDescription": "\n\nA key to identify this module.\n\n This key must be unique relative to the add on, with the exception of Confluence macros: Their keys need to be\n globally unique.\n\n Keys must only contain alphanumeric characters and dashes.\n\n The key is used to generate the url to your add-on's module. The url is generated as a combination of your add-on\n key and module key. For example, an add-on which looks like:\n\n {\n \"key\": \"my-addon\",\n \"modules\": {\n \"configurePage\": {\n \"key\": \"configure-me\",\n }\n }\n }\n\n Will have a configuration page module with a URL of `/plugins/servlet/ac/my-addon/configure-me`.\n\n",
"description": "\n\nA key to identify this module.\n\n This key must be unique relative to the add on, with the exception of Confluence macros: Their keys need to be\n globally unique.\n\n Keys must only contain alphanumeric characters and dashes.\n\n The key is used to generate the url to your add-on's module. The url is generated as a combination of your add-on\n key and module key. For example, an add-on which looks like:\n\n {\n \"key\": \"my-addon\",\n \"modules\": {\n \"configurePage\": {\n \"key\": \"configure-me\",\n }\n }\n }\n\n Will have a configuration page module with a URL of `/plugins/servlet/ac/my-addon/configure-me`.\n\n"
}
},
"required": [
"name",
"location",
"key"
],
"shortClassName": "webItemModuleBean",
"type": "object",
"title": "Web Item",
"description": "\n\n\n
\n\n",
"defaultValue": "false",
"description": "\n\nReturns whether the URL should be cacheable. Cacheable URLs are taken directly from the add-on descriptor, and\n lack all additional query parameters:\n \n
\n\n"
},
"supportsNative": {
"type": "boolean",
"fieldDescription": "\n\nSpecifies whether the web panel will be shown in the native apps. As of now, this will only support the Jira\n mobile and desktop clients. The web panel is required to have atl.jira.view.issue.right.context or\n atl.jira.view.issue.left.context as the location.\n\n Web panels with the atl.jira.view.issue.right.context location will be shown in Jira for iOS/Mac\n version 109 or later and Jira for Android version 55 or later.\n\n Web panels with the atl.jira.view.issue.left.context location will be shown in Jira for Android\n version 63 or later. It is not yet available in Jira for iOS/Mac but we will update this documentation when it is.\n\n Read about [enabling your addon for the Jira mobile and desktop clients](/cloud/jira/platform/developing-apps-for-jira-cloud-mobile/).\n\n",
"defaultValue": "false",
"description": "\n\nSpecifies whether the web panel will be shown in the native apps. As of now, this will only support the Jira\n mobile and desktop clients. The web panel is required to have atl.jira.view.issue.right.context or\n atl.jira.view.issue.left.context as the location.\n\n Web panels with the atl.jira.view.issue.right.context location will be shown in Jira for iOS/Mac\n version 109 or later and Jira for Android version 55 or later.\n\n Web panels with the atl.jira.view.issue.left.context location will be shown in Jira for Android\n version 63 or later. It is not yet available in Jira for iOS/Mac but we will update this documentation when it is.\n\n Read about [enabling your addon for the Jira mobile and desktop clients](/cloud/jira/platform/developing-apps-for-jira-cloud-mobile/).\n\n"
},
"conditions": {
"items": {
"type": "object",
"anyOf": [
{
"$ref": "#/definitions/singleCondition"
},
{
"$ref": "#/definitions/compositeCondition"
}
]
},
"type": "array",
"fieldDescription": "\n\nConditions can be added to display only when all the given conditions are true.\n\n",
"description": "\n\nConditions can be added to display only when all the given conditions are true.\n\n"
},
"params": {
"additionalProperties": true,
"type": "object",
"fieldTitle": "Object",
"fieldDescription": "\n\nThis object represents a map of key/value pairs, where each property name and value corresponds to the parameter name and value respectively.\n\n addon\\_is\\_licensed condition.\n\n",
"description": "\n\nList of conditions which must be true for the webhook to fire.\n Currently, we only support the addon\\_is\\_licensed condition.\n\n"
},
"propertyKeys": {
"items": {
"type": "string"
},
"type": "array",
"fieldDescription": "\n\nSpecifies entity properties which will be returned inside JSON body. If not specified no properties will be returned.\n\n Currently this is supported only in Jira webhooks, for all events that support Entity Properties.\n Note that properties won't be returned for entity-deleted events, since the properties are already deleted by the time the webhook is sent.\n\n",
"description": "\n\nSpecifies entity properties which will be returned inside JSON body. If not specified no properties will be returned.\n\n Currently this is supported only in Jira webhooks, for all events that support Entity Properties.\n Note that properties won't be returned for entity-deleted events, since the properties are already deleted by the time the webhook is sent.\n\n"
},
"key": {
"pattern": "^[a-zA-Z0-9-]+$",
"maxLength": 100,
"type": "string",
"fieldDescription": "\n\nA key to identify this module. Required when registering the module [dynamically](../../dynamic-modules/), otherwise ignored.\n\n",
"description": "\n\nA key to identify this module. Required when registering the module [dynamically](../../dynamic-modules/), otherwise ignored.\n\n"
},
"url": {
"format": "uri-template",
"type": "string",
"fieldDescription": "\n\nSpecifies your add-on's POST webhook handler URL. This property must be a URL relative to the add-on's baseUrl.\n\n",
"description": "\n\nSpecifies your add-on's POST webhook handler URL. This property must be a URL relative to the add-on's baseUrl.\n\n"
}
},
"required": [
"event",
"url"
],
"shortClassName": "webHookModuleBean",
"type": "object",
"title": "Webhook",
"description": "\n\nA webhook is a standard mechanism for an add-on to listen to in-product events via HTTP callbacks. An add-on can register\n a webhook in the Atlassian Connect descriptor to listen to events that are fired by Jira or Confluence.\n\n Just to give you an idea of how you can use them in add-ons, here are a few sample webhook events:\n\n \n
\n\n If your add-on uses webhooks, you must declare the \"read\" scope\n in your atlassian-connect.json descriptor.\n\n Handling the webhook event
\n\n To receive webhook events, your add-on needs to include the webhook module declaration in its JSON descriptor. The\n declaration indicates the add-on relative URL at which it will receive the notification. In other\n words, the Atlassian application will send an HTTP POST to this resource in response to an application event. The\n add-on code that handles the POST should process any information passed in the body of the message, as appropriate.\n Each webhook POST sent to the add-on will also include the authentication headers that allow the add-on to validate\n the authenticity of that request. Specifically, the JWT token can be found in the \"Authorization\" HTTP header.\n\n Note that if using Apache and mod\\_wsgi to serve files to a Django application, the Authentication header is stripped\n out by default. Extra configuration\n is required to ensure the Authentication header is visible.\n\n Important: It must be noted that webhook delivery is not guaranteed; it is best effort. When a webhook\n event is triggered in Jira or Confluence instance then a single HTTP POST is sent to your add-on. If your add-on is down,\n or there is any network problems between the Atlassian product and your add-on, then you will never receive the\n webhook event. In general, webhooks are quite reliable; however you must always keep in mind that delivery is not guaranteed.\n\n Variable Substitution
\n\n Jira webhooks also provide a way to add and substitute variables in the url. This is similar to context parameters for add-ons. See\n context parameters.\n\n For example, if we register to listen for one of the project events with a url containing {project.id}, a POST message will\n be sent to the address with the {project.id} replaced by the id of the project that the event was triggered for.\n\n Filtering
\n Additional filters may be specified to trigger webhooks only for events satisfying certain conditions.\n How the filter value is supposed to look like exactly, and whether filtering is available at all, depends on the event type.\n The following sections describe all the possibilities.\n\n JQL
\n\n Issue-related events may be filtered with JQL. Webhooks will be sent only for issues matched by the provided JQL query.\n Here is an example JQL query that can be put into the \"filter\" property: \"project = TEST AND fixVersion = future\".\n\n JQL filtering is supported only by the following event types:\n\n \n
\n\n jira:issue\\_createdjira:issue\\_deletedjira:issue\\_updatedcomment\\_createdcomment\\_updatedcomment\\_deletedissue\\_property\\_setissue\\_property\\_deletedworklog\\_createdworklog\\_updatedworklog\\_deletedWebhook event types
\n\n Below is a list of all available webhook events.\n\n Add-on and system events
\n \n
\n\n connect\\_addon\\_disabledconnect\\_addon\\_enabledIssue events
\n \n
\n\n jira:issue\\_createdjira:issue\\_deletedjira:issue\\_updated\n\n The supported context parameters are {project.id}, {project.key}, {issue.key}, {issue.id}.Issue link events
\n \n
\n\n issuelink\\_createdissuelink\\_deleted\n Filter events
\n \n
\n\n filter\\_createdfilter\\_updatedfilter\\_deleted\n\n There is one supported context parameter: {filter.id}.Issue properties events
\n \n
\n\n issue\\_property\\_setissue\\_property\\_deleted\n\n The supported context parameters are {project.id}, {project.key}, {issue.key}, {issue.id}.Issue Type events
\n \n
\n\n issuetype\\_createdissuetype\\_updatedissuetype\\_deleted\n\n The supported context parameters are {project.id}, {project.key}, {issuetype.id}.Attachment events
\n \n
\n\n attachment\\_createdattachment\\_deleted\n\n The supported context parameters are {attachment.id}, {project.id}, {project.key}, {issue.key}, {issue.id}.Version events
\n \n
\n\n jira:version\\_createdjira:version\\_deletedjira:version\\_mergedjira:version\\_updatedjira:version\\_movedjira:version\\_releasedjira:version\\_unreleased\n\n The supported context parameters are {project.id}, {project.key}, {version.id}.\n\n Special context parameter for version\\_merged event is {mergedVersion.id}.Project events
\n \n
\n\n project\\_createdproject\\_updatedproject\\_deleted\n\n The supported context parameters are {project.id}, {project.key}Project App Events
\n \n
\n\n project\\_app\\_enabledproject\\_app\\_disabled\n\n The supported context parameters are {project.id}, {project.key}, {app.key}User events
\n \n
\n\n user\\_createduser\\_deleteduser\\_updated\n\n The supported context parameters are {modifiedUser.accountId}, {modifiedUser.name} (deprecated), {modifiedUser.key} (deprecated)Feature status events
\n \n
\n\n option\\_voting\\_changedoption\\_watching\\_changedoption\\_unassigned\\_issues\\_changedoption\\_subtasks\\_changedoption\\_issuelinks\\_changedoption\\_timetracking\\_changedComment events
\n \n
\n\n comment\\_createdcomment\\_updatedcomment\\_deleted\n\n The supported context parameters are {project.id}, {project.key}, {issue.key}, {issue.id}, {comment.id}.Worklog events
\n \n
\n\n worklog\\_createdworklog\\_updatedworklog\\_deleted\n\n The supported context parameters are {project.id}, {project.key}, {issue.key}, {issue.id}, {worklog.id}.Confluence Webhook events
\n\n \n
\n\n attachment\\_archivedattachment\\_createdattachment\\_removedattachment\\_restoredattachment\\_trashedattachment\\_unarchivedattachment\\_updatedattachment\\_viewedblog\\_createdblog\\_removedblog\\_restoredblog\\_trashedblog\\_updatedblog\\_viewedblueprint\\_page\\_createdcomment\\_createdcomment\\_removedcomment\\_updatedconnect\\_addon\\_disabledconnect\\_addon\\_enabledcontent\\_createdcontent\\_removedcontent\\_restoredcontent\\_trashedcontent\\_updatedcontent\\_permissions\\_updatedgroup\\_createdgroup\\_removedlabel\\_addedlabel\\_createdlabel\\_deletedlabel\\_removedpage\\_archivedpage\\_children\\_reorderedpage\\_createdpage\\_copiedpage\\_movedpage\\_removedpage\\_restoredpage\\_trashedpage\\_unarchivedpage\\_updatedpage\\_viewedrelation\\_createdrelation\\_deletedsearch\\_performedspace\\_createdspace\\_logo\\_updatedspace\\_permissions\\_updatedspace\\_removedspace\\_updatedtheme\\_enableduser\\_followeduser\\_reactivateduser\\_removedExample request
\n\n
\n\n \n POST /jira-issue\\_created?user\\_id=admin&user\\_key=admin HTTP/1.1\n Authorization: JWT ...\n Atlassian-Connect-Version: x.x\n Content-Type: application/json\n {\n timestamp: 1426661049725,\n webhookEvent: 'jira:issue\\_created',\n ...\n }\n Example responses
\n\n All webhooks will post JSON data to the listening add-on. The structure of this JSON differs based on the Atlassian\n product that sent the event and the event itself. Here are some example webhook events:\n\n Jira issue-related webhook event structure
\n\n All webhook events that are sent because of Jira issue updates will have the following structure.\n\n
\n\n This is fully documented in Webhooks: Example callback for an issue-related event.\n\n \n {\n \"timestamp\"\n \"event\"\n \"user\": {\n // See User shape in the linked document\n },\n \"issue\": {\n // See Issue shape in the linked document\n },\n \"changelog\" : {\n // See Changelog shape in the linked document\n },\n \"comment\" : {\n // See Comment shape in in the linked document\n }\n }\n Confluence page\\_created
\n\n
\n\n \n {\n \"userAccountId\": \"ff80808154510724015451074c160001\",\n \"accountType\": \"customer\",\n \"page\": {\n \"creatorAccountId\": 'ff80808154510724015451074c160001',\n \"spaceKey\": \"~admin\",\n \"modificationDate\": 1471926079631,\n \"lastModifierAccountId\": \"ff80808154510724015451074c160001\",\n \"self\": \"https://cloud-development-environment.atlassian.net/wiki/display/~admin/Some+random+test+page\",\n \"id\": 16777227,\n \"title\": \"Some random test page\",\n \"creationDate\": 1594752539309,\n \"contentType\": \"page\",\n \"version\": 1\n },\n \"timestamp\": 1471926079645\n }\n Confluence comment\\_created
\n\n
\n\n \n {\n \"userAccountId\": \"ff80808154510724015451074c160001\",\n \"accountType\": \"customer\",\n \"comment\": {\n \"creatorAccountId\": \"ff80808154510724015451074c160001\",\n \"spaceKey\": \"~admin\",\n \"parent\": {\n \"creatorAccountId\": \"ff80808154510724015451074c160001\",\n \"spaceKey\": \"~admin\",\n \"modificationDate\": 1471926079631,\n \"lastModifierAccountId\": \"ff80808154510724015451074c160001\",\n \"self\": \"https://cloud-development-environment.atlassian.net/wiki/display/~admin/Some+random+test+page\",\n \"id\": 16777227,\n \"title\": \"Some random test page\",\n \"creationDate\": 1471926079631,\n \"contentType\": \"page\",\n \"version\": 1\n },\n \"modificationDate\": 1471926091465,\n \"lastModifierAccountId\": \"ff80808154510724015451074c160001\",\n \"self\": \"https://cloud-development-environment/wiki/display/~admin/Some+random+test+page?focusedCommentId=16777228#comment-16777228\",\n \"id\": 16777228,\n \"creationDate\": 1471926091465,\n \"contentType\": \"comment\",\n \"version\": 1\n },\n \"timestamp\": 1471926091468\n }\n Inspecting webhook contents
\n\n Each type of webhook event includes information specific to that event in the body content of the POST message. The\n add-on resource that listens for webhook posts should receive and process the content as appropriate for the add-on.\n To understand what type of content each webhook generates, you can use the Connect inspector tool.\n\n The Connect inspector is a service that generates temporary\n Atlassian Connect add-on's that you can install in your development environment to inspect the content of event messages.\n The Connect inspector subscribes to every webhook event type available on the running instance of the Atlassian application,\n and prints the body posted by the instance to your web browser.\n\n Web Item Example
\n\n\n\n {\n \"target\": {\n \"type\": \"dialog\",\n \"options\": {\n \"height\": \"100px\",\n \"width\": \"200px\"\n }\n }\n }\n\n\n\n\n Dialog Example
\n\n {\n \"modules\": {\n \"dialogs\": [\n {\n \"url\": \"/my-dialog-content\",\n \"options\": {\n \"size\": \"fullscreen\",\n \"header\": {\n \"value\": \"Example Dialog\"\n }\n },\n \"key\": \"dialog-module-key\"\n }\n ]\n }\n }\n\n\n"
},
"icon": {
"properties": {
"width": {
"type": "integer",
"fieldDescription": "\n\nThe width in pixels of the icon image.\n\n",
"description": "\n\nThe width in pixels of the icon image.\n\n"
},
"url": {
"format": "uri",
"type": "string",
"fieldDescription": "\n\nThe URL of the icon. Your icon needs to be hosted remotely at a web-accessible location. You can specify the\n URL as an absolute URL or relative to the add-on's base URL.\n\n",
"description": "\n\nThe URL of the icon. Your icon needs to be hosted remotely at a web-accessible location. You can specify the\n URL as an absolute URL or relative to the add-on's base URL.\n\n"
},
"height": {
"type": "integer",
"fieldDescription": "\n\nThe height in pixels of the icon image.\n\n",
"description": "\n\nThe height in pixels of the icon image.\n\n"
}
},
"required": [
"url"
],
"shortClassName": "iconBean",
"type": "object",
"title": "Icon",
"description": "\n\nDefines an icon to display.\n\n Example
\n\n\n\n {\n \"icon\": {\n \"width\": 16,\n \"height\": 16,\n \"url\": \"/my-icon.png\"\n }\n }\n\n\n"
},
"singleCondition": {
"properties": {
"condition": {
"maxLength": 100,
"type": "string",
"fieldDescription": "\n\nA string indicating the name of the condition\n\n",
"description": "\n\nA string indicating the name of the condition\n\n"
},
"invert": {
"type": "boolean",
"fieldDescription": "\n\nA flag indicating whether to invert the boolean result of the condition.\n\n",
"defaultValue": "false",
"description": "\n\nA flag indicating whether to invert the boolean result of the condition.\n\n"
},
"params": {
"additionalProperties": true,
"type": "object",
"fieldTitle": "Object",
"fieldDescription": "\n\nThis object represents a map of key/value pairs, where each property name and value corresponds to the parameter name and value respectively.\n\n Example
\n\n\n\n {\n \"condition\": \"user_is_logged_in\",\n \"invert\": false\n }\n\n\n"
},
"webPanelLayout": {
"properties": {
"width": {
"maxLength": 10,
"type": "string"
},
"height": {
"maxLength": 10,
"type": "string"
}
},
"shortClassName": "webPanelLayout",
"type": "object",
"title": "Web Panel Layout",
"description": "\n\nExample
\n\n\n\n {\n \"layout\": {\n \"width\": \"100\",\n \"height\": \"200\"\n }\n }\n\n\n"
},
"webSection": {
"properties": {
"tooltip": {
"$ref": "#/definitions/i18nProperty",
"fieldDescription": "\n\nThe internationalised text to be used in the link's tooltip.\n\n",
"description": "\n\nThe internationalised text to be used in the link's tooltip.\n\n"
},
"name": {
"$ref": "#/definitions/i18nProperty",
"fieldDescription": "\n\nA human readable name.\n\n",
"description": "\n\nA human readable name.\n\n"
},
"weight": {
"type": "integer",
"fieldDescription": "\n\nExample
\n\n\n\n {\n \"value\": \"My text\"\n }\n\n\n"
},
"compositeCondition": {
"properties": {
"conditions": {
"items": {
"type": "object",
"anyOf": [
{
"$ref": "#"
},
{
"$ref": "#/definitions/singleCondition"
}
]
},
"type": "array",
"fieldDescription": "\n\nThe conditions to compose using the specific logical operator.\n\n",
"description": "\n\nThe conditions to compose using the specific logical operator.\n\n"
},
"type": {
"enum": [
"and",
"AND",
"or",
"OR"
],
"type": "string",
"fieldDescription": "\n\nDefines what logical operator is used to evaluate its collection of condition elements.\n\n",
"description": "\n\nDefines what logical operator is used to evaluate its collection of condition elements.\n\n"
}
},
"shortClassName": "compositeConditionBean",
"type": "object",
"title": "Composite Condition",
"description": "\n\nComposite Conditions are composed of a collection of [Single Condition](../single-condition/) / Composite Conditions\n and a type attribute.\n\n Example
\n\n\n\n {\n \"conditions\": [\n {\n \"or\": [\n {\n \"condition\": \"can_attach_file_to_issue\",\n \"invert\": false\n },\n {\n \"condition\": \"is_issue_assigned_to_current_user\",\n \"invert\": false\n }\n ]\n },\n {\n \"condition\": \"user_is_logged_in\",\n \"invert\": false\n }\n ]\n }\n\n\n"
},
"dialog": {
"properties": {
"options": {
"$ref": "#/definitions/dialogOptions",
"fieldDescription": "\n\n\n
\n\n",
"defaultValue": "false",
"description": "\n\nReturns whether the URL should be cacheable. Cacheable URLs are taken directly from the add-on descriptor, and\n lack all additional query parameters:\n \n
\n\n"
},
"url": {
"format": "uri-template",
"type": "string",
"fieldDescription": "\n\nSpecifies the URL of the content displayed in the dialog. The URL can be absolute or relative to either the\n product URL or the add-on's base URL, depending on the _context_ attribute.\n\n Your add-on can receive additional context from the application by\n using variable tokens in the URL attribute.\n\n",
"description": "\n\nSpecifies the URL of the content displayed in the dialog. The URL can be absolute or relative to either the\n product URL or the add-on's base URL, depending on the _context_ attribute.\n\n Your add-on can receive additional context from the application by\n using variable tokens in the URL attribute.\n\n"
},
"key": {
"pattern": "^[a-zA-Z0-9-]+$",
"maxLength": 100,
"type": "string",
"fieldDescription": "\n\nA key to identify this module.\n\n This key must be unique relative to the add on, with the exception of Confluence macros: Their keys need to be\n globally unique.\n\n Keys must only contain alphanumeric characters and dashes.\n\n The key is used to generate the url to your add-on's module. The url is generated as a combination of your add-on\n key and module key. For example, an add-on which looks like:\n\n {\n \"key\": \"my-addon\",\n \"modules\": {\n \"configurePage\": {\n \"key\": \"configure-me\",\n }\n }\n }\n\n Will have a configuration page module with a URL of `/plugins/servlet/ac/my-addon/configure-me`.\n\n",
"description": "\n\nA key to identify this module.\n\n This key must be unique relative to the add on, with the exception of Confluence macros: Their keys need to be\n globally unique.\n\n Keys must only contain alphanumeric characters and dashes.\n\n The key is used to generate the url to your add-on's module. The url is generated as a combination of your add-on\n key and module key. For example, an add-on which looks like:\n\n {\n \"key\": \"my-addon\",\n \"modules\": {\n \"configurePage\": {\n \"key\": \"configure-me\",\n }\n }\n }\n\n Will have a configuration page module with a URL of `/plugins/servlet/ac/my-addon/configure-me`.\n\n"
}
},
"required": [
"url",
"key"
],
"shortClassName": "dialogModuleBean",
"type": "object",
"title": "Dialog",
"description": "\n\n
"
},
"inlineDialogOptions": {
"properties": {
"offsetX": {
"maxLength": 10,
"type": "string",
"fieldDescription": "\n\nSets an offset distance of the inline-dialog from the trigger element along the x-axis in pixels\n\n",
"description": "\n\nSets an offset distance of the inline-dialog from the trigger element along the x-axis in pixels\n\n"
},
"offsetY": {
"maxLength": 10,
"type": "string",
"fieldDescription": "\n\nSets an offset distance of the inline-dialog from the trigger element along the y-axis in pixels\n\n",
"description": "\n\nSets an offset distance of the inline-dialog from the trigger element along the y-axis in pixels\n\n"
},
"width": {
"maxLength": 10,
"type": "string",
"fieldDescription": "\n\nSets how wide the dialog is in pixels.\n\n",
"description": "\n\nSets how wide the dialog is in pixels.\n\n"
},
"onTop": {
"type": "boolean",
"fieldDescription": "\n\nDetermines if the dialog should be shown above the trigger or not. If this option is true but there is insufficient room above the trigger the inline-dialog will be flipped to display below it\n\n",
"description": "\n\nDetermines if the dialog should be shown above the trigger or not. If this option is true but there is insufficient room above the trigger the inline-dialog will be flipped to display below it\n\n"
},
"showDelay": {
"type": "integer",
"fieldDescription": "\n\nDetermines how long in milliseconds after a show trigger is fired (such as a trigger click) until the dialog is shown\n\n",
"description": "\n\nDetermines how long in milliseconds after a show trigger is fired (such as a trigger click) until the dialog is shown\n\n"
},
"closeOthers": {
"type": "boolean",
"fieldDescription": "\n\nDetermines if all other dialogs on the screen are closed when this one is opened\n\n",
"description": "\n\nDetermines if all other dialogs on the screen are closed when this one is opened\n\n"
},
"persistent": {
"type": "boolean",
"fieldDescription": "\n\nThis option, ignores the 'closeOthers' option\n\n",
"description": "\n\nThis option, ignores the 'closeOthers' option\n\n"
},
"onHover": {
"type": "boolean",
"fieldDescription": "\n\n\n AP.require('dialog', function(dialog){\n dialog.create({\n key: 'dialog-module-key'\n }).on(\"close\", callbackFunc);\n });\n Example
\n\n\n\n {\n \"target\": {\n \"type\": \"inlinedialog\",\n \"options\": {\n \"onHover\": true,\n \"offsetX\": \"30px\",\n \"offsetY\": \"20px\"\n }\n }\n }\n\n\n"
},
"pageModule": {
"properties": {
"icon": {
"$ref": "#/definitions/icon",
"fieldDescription": "\n\nAn optional icon to display with the link text or as the link, specified by URL to its hosted location.\n You can specify a particular width and height for the icon. Most link icons in Atlassian applications\n are 16 by 16 pixels.\n\n",
"description": "\n\nAn optional icon to display with the link text or as the link, specified by URL to its hosted location.\n You can specify a particular width and height for the icon. Most link icons in Atlassian applications\n are 16 by 16 pixels.\n\n"
},
"name": {
"$ref": "#/definitions/i18nProperty",
"fieldDescription": "\n\nA human readable name.\n\n",
"description": "\n\nA human readable name.\n\n"
},
"weight": {
"type": "integer",
"fieldDescription": "\n\nDetermines the order in which the page's link appears in the menu or list.\n\n The \"lightest\" weight (i.e., lowest number) appears first, rising relative to other items,\n while the \"heaviest\" weights sink to the bottom of the menu or list.\n\n Built-in web items have weights that are incremented by numbers that leave room for additional\n items, such as by 10 or 100. Be mindful of the weight you choose for your item, so that it appears\n in a sensible order given existing items.\n\n",
"defaultValue": "100",
"description": "\n\nDetermines the order in which the page's link appears in the menu or list.\n\n The \"lightest\" weight (i.e., lowest number) appears first, rising relative to other items,\n while the \"heaviest\" weights sink to the bottom of the menu or list.\n\n Built-in web items have weights that are incremented by numbers that leave room for additional\n items, such as by 10 or 100. Be mindful of the weight you choose for your item, so that it appears\n in a sensible order given existing items.\n\n"
},
"cacheable": {
"type": "boolean",
"fieldDescription": "\n\nReturns whether the URL should be cacheable. Cacheable URLs are taken directly from the add-on descriptor, and\n lack all additional query parameters:\n \n
\n\n",
"defaultValue": "false",
"description": "\n\nReturns whether the URL should be cacheable. Cacheable URLs are taken directly from the add-on descriptor, and\n lack all additional query parameters:\n \n
\n\n"
},
"location": {
"maxLength": 100,
"type": "string",
"fieldDescription": "\n\nThe location in the application interface where the page's link should appear. For the Atlassian application\n interface, a location is something like the coordinates on a map. It points to a particular drop-down menu or\n navigation list in the UI.\n\n Places in the Atlassian UI are identified by what are known as \"well-known locations.\"\n For example, the \"system.admin/globalsettings\" location is in the administrative\n menu link on the left side of the Administration Console.\n\n Find product locations with the Extension Point Finder:\n\n \n\n If the location property is not specified, a default location is used:\n\n Jira:\n\n \n
\n\n Confluence:\n\n generalPage: system.top.navigation.baradminPage: advanced\\_menu\\_section/advanced_section\n
\n\n You may wish to have no link to the page shown anywhere - for example, if you are using the page as the\n target of a JavaScript API dialog.\n In this case, set the value of generalPage: system.help/pagesadminPage: system.admin/marketplace_confluencelocation to \"none\".\n\n",
"description": "\n\nThe location in the application interface where the page's link should appear. For the Atlassian application\n interface, a location is something like the coordinates on a map. It points to a particular drop-down menu or\n navigation list in the UI.\n\n Places in the Atlassian UI are identified by what are known as \"well-known locations.\"\n For example, the \"system.admin/globalsettings\" location is in the administrative\n menu link on the left side of the Administration Console.\n\n Find product locations with the Extension Point Finder:\n\n \n\n If the location property is not specified, a default location is used:\n\n Jira:\n\n \n
\n\n Confluence:\n\n generalPage: system.top.navigation.baradminPage: advanced\\_menu\\_section/advanced_section\n
\n\n You may wish to have no link to the page shown anywhere - for example, if you are using the page as the\n target of a JavaScript API dialog.\n In this case, set the value of generalPage: system.help/pagesadminPage: system.admin/marketplace_confluencelocation to \"none\".\n\n"
},
"conditions": {
"items": {
"type": "object",
"anyOf": [
{
"$ref": "#/definitions/singleCondition"
},
{
"$ref": "#/definitions/compositeCondition"
}
]
},
"type": "array",
"fieldDescription": "\n\nConditions can be added to display only when all the given conditions are true.\n\nThe supported conditions for pages are:\n\nCommon conditions\n\n\n
\n\nJira conditions\n\naddon_property_existsaddon_property_equal_toaddon_property_equal_to_contextaddon_property_contains_anyaddon_property_contains_alladdon_property_contains_contextaddon_property_contains_any_user_groupuser_is_adminuser_is_logged_inuser_is_sysadminaddon_is_licensedfeature_flag\n
\n\nConfluence conditions\n\nentity_property_existsentity_property_equal_toentity_property_equal_to_contextentity_property_contains_anyentity_property_contains_allentity_property_contains_contextentity_property_contains_any_user_groupcan_use_applicationproject_typehas_global_permission\n
",
"description": "\n\nConditions can be added to display only when all the given conditions are true.\n\nThe supported conditions for pages are:\n\nCommon conditions\n\ncontent_property_existscontent_property_equal_tocontent_property_equal_to_contextcontent_property_contains_anycontent_property_contains_allcontent_property_contains_contextcontent_property_contains_any_user_groupspace_property_existsspace_property_equal_tospace_property_equal_to_contextspace_property_contains_anyspace_property_contains_allspace_property_contains_contextspace_property_contains_any_user_group\n
\n\nJira conditions\n\naddon_property_existsaddon_property_equal_toaddon_property_equal_to_contextaddon_property_contains_anyaddon_property_contains_alladdon_property_contains_contextaddon_property_contains_any_user_groupuser_is_adminuser_is_logged_inuser_is_sysadminaddon_is_licensedfeature_flag\n
\n\nConfluence conditions\n\nentity_property_existsentity_property_equal_toentity_property_equal_to_contextentity_property_contains_anyentity_property_contains_allentity_property_contains_contextentity_property_contains_any_user_groupcan_use_applicationproject_typehas_global_permission\n
"
},
"params": {
"additionalProperties": true,
"type": "object",
"fieldTitle": "Object",
"fieldDescription": "\n\nThis object represents a map of key/value pairs, where each property name and value corresponds to the parameter name and value respectively.\n\n content_property_existscontent_property_equal_tocontent_property_equal_to_contextcontent_property_contains_anycontent_property_contains_allcontent_property_contains_contextcontent_property_contains_any_user_groupspace_property_existsspace_property_equal_tospace_property_equal_to_contextspace_property_contains_anyspace_property_contains_allspace_property_contains_contextspace_property_contains_any_user_group\n
\n\n generalPages - have no extra styling and by default a link to the page is displayed in the main navigation menu.\n Use these pages in order to display general content.jiraProjectPages - (Jira only) appear in the project sidebar.\n Use these pages in order to provide project-specific content. The project page module has a separate documentation page here:\n [Project Page](https://developer.atlassian.com/cloud/jira/platform/modules/project-page/).\n
\n\n\n \n\n postInstallPage - A \"Get Started\" button will link to this page from both the add-on's entry in Manage Add-ons\n and from the dialog that the user is shown when they successfully install the add-on. Use this page to provide introductory\n information about the add-on to the user.\n
\n\n data-options attribute \"sizeToParent:true\" in the script tag for all.js. It is also possible to hide footer for such pages.\n<script src="{{hostScriptUrl}}"\n type="text/javascript"\n data-options="sizeToParent:true;hideFooter:true">\n</script>\n \n
\n\n",
"defaultValue": "false",
"description": "\n\nAllows the add-on to explicitly request any product-added header, margins or padding be removed.\n Currently only takes affect on:\n \n
\n\n"
},
"cacheable": {
"type": "boolean",
"fieldDescription": "\n\nReturns whether the URL should be cacheable. Cacheable URLs are taken directly from the add-on descriptor, and\n lack all additional query parameters:\n \n
\n\n",
"defaultValue": "false",
"description": "\n\nReturns whether the URL should be cacheable. Cacheable URLs are taken directly from the add-on descriptor, and\n lack all additional query parameters:\n \n
\n\n"
},
"location": {
"maxLength": 100,
"type": "string",
"fieldDescription": "\n\nThe location in the application interface where the page's link should appear. For the Atlassian application\n interface, a location is something like the coordinates on a map. It points to a particular drop-down menu or\n navigation list in the UI.\n\n Places in the Atlassian UI are identified by what are known as \"well-known locations.\"\n For example, the \"system.admin/globalsettings\" location is in the administrative\n menu link on the left side of the Administration Console.\n\n Find product locations with the Extension Point Finder:\n\n \n\n If the location property is not specified, a default location is used:\n\n Jira:\n\n \n
\n\n Confluence:\n\n generalPage: system.top.navigation.baradminPage: advanced\\_menu\\_section/advanced_section\n
\n\n You may wish to have no link to the page shown anywhere - for example, if you are using the page as the\n target of a JavaScript API dialog.\n In this case, set the value of generalPage: system.help/pagesadminPage: system.admin/marketplace_confluencelocation to \"none\".\n\n",
"description": "\n\nThe location in the application interface where the page's link should appear. For the Atlassian application\n interface, a location is something like the coordinates on a map. It points to a particular drop-down menu or\n navigation list in the UI.\n\n Places in the Atlassian UI are identified by what are known as \"well-known locations.\"\n For example, the \"system.admin/globalsettings\" location is in the administrative\n menu link on the left side of the Administration Console.\n\n Find product locations with the Extension Point Finder:\n\n \n\n If the location property is not specified, a default location is used:\n\n Jira:\n\n \n
\n\n Confluence:\n\n generalPage: system.top.navigation.baradminPage: advanced\\_menu\\_section/advanced_section\n
\n\n You may wish to have no link to the page shown anywhere - for example, if you are using the page as the\n target of a JavaScript API dialog.\n In this case, set the value of generalPage: system.help/pagesadminPage: system.admin/marketplace_confluencelocation to \"none\".\n\n"
},
"conditions": {
"items": {
"type": "object",
"anyOf": [
{
"$ref": "#/definitions/compositeCondition"
},
{
"$ref": "#/definitions/singleCondition"
}
]
},
"type": "array",
"fieldDescription": "\n\nConditions can be added to display only when all the given conditions are true.\n\nThe supported conditions for pages are:\n\nCommon conditions\n\n\n
\n\nJira conditions\n\naddon_property_existsaddon_property_equal_toaddon_property_equal_to_contextaddon_property_contains_anyaddon_property_contains_alladdon_property_contains_contextaddon_property_contains_any_user_groupuser_is_adminuser_is_logged_inuser_is_sysadminaddon_is_licensedfeature_flag\n
\n\nConfluence conditions\n\nentity_property_existsentity_property_equal_toentity_property_equal_to_contextentity_property_contains_anyentity_property_contains_allentity_property_contains_contextentity_property_contains_any_user_groupcan_use_applicationproject_typehas_global_permission\n
",
"description": "\n\nConditions can be added to display only when all the given conditions are true.\n\nThe supported conditions for pages are:\n\nCommon conditions\n\ncontent_property_existscontent_property_equal_tocontent_property_equal_to_contextcontent_property_contains_anycontent_property_contains_allcontent_property_contains_contextcontent_property_contains_any_user_groupspace_property_existsspace_property_equal_tospace_property_equal_to_contextspace_property_contains_anyspace_property_contains_allspace_property_contains_contextspace_property_contains_any_user_group\n
\n\nJira conditions\n\naddon_property_existsaddon_property_equal_toaddon_property_equal_to_contextaddon_property_contains_anyaddon_property_contains_alladdon_property_contains_contextaddon_property_contains_any_user_groupuser_is_adminuser_is_logged_inuser_is_sysadminaddon_is_licensedfeature_flag\n
\n\nConfluence conditions\n\nentity_property_existsentity_property_equal_toentity_property_equal_to_contextentity_property_contains_anyentity_property_contains_allentity_property_contains_contextentity_property_contains_any_user_groupcan_use_applicationproject_typehas_global_permission\n
"
},
"params": {
"additionalProperties": true,
"type": "object",
"fieldTitle": "Object",
"fieldDescription": "\n\nThis object represents a map of key/value pairs, where each property name and value corresponds to the parameter name and value respectively.\n\n content_property_existscontent_property_equal_tocontent_property_equal_to_contextcontent_property_contains_anycontent_property_contains_allcontent_property_contains_contextcontent_property_contains_any_user_groupspace_property_existsspace_property_equal_tospace_property_equal_to_contextspace_property_contains_anyspace_property_contains_allspace_property_contains_contextspace_property_contains_any_user_group\n
\n\n\n \n\n configurePage - a \"Configure\" button will link to this page from the add-on's entry in Manage Add-ons.\n Use this page to provide configuration of the add-on itself.\n
\n\n data-options attribute \"sizeToParent:true\" in the script tag for all.js. It is also possible to hide footer for such pages.\n<script src="{{hostScriptUrl}}"\n type="text/javascript"\n data-options="sizeToParent:true;hideFooter:true">\n</script>\n Admin page example
\n\n\n\n {\n \"modules\": {\n \"adminPages\": [\n {\n \"url\": \"/my-admin-page\",\n \"name\": {\n \"value\": \"My Admin Page\"\n },\n \"key\": \"my-admin-page\"\n }\n ],\n \"configurePage\": {\n \"url\": \"/my-config-page\",\n \"name\": {\n \"value\": \"My Configure Page\"\n },\n \"key\": \"my-config-page\"\n }\n }\n }\n\n\n"
},
"dialogModuleOptions": {
"properties": {
"key": {
"maxLength": 100,
"type": "string",
"fieldDescription": "\n\nExample
\n\n\n\n {\n \"target\": {\n \"type\": \"dialogmodule\",\n \"options\": {\n \"key\": \"dialog-module-key\"\n }\n }\n }\n\n\n"
},
"customContentUISupport": {
"properties": {
"editComponentTitlePlaceholder": {
"$ref": "#/definitions/i18nProperty",
"fieldDescription": "\n\nDefines a placeholder for title input box that will be used in the edit component.\n Following variables will be replaced at runtime:\n \n
\n {spaceName}: Name of the current space{spaceKey}: Key of the current space{contentTypeName}: Name of the current custom content
\n \"What do you want to know about {SpaceName}\" will become \"What do you want to know about Demonstration Space\"\n if user is creating a new piece of custom content in \"Demonstration Space\" space.\n\n",
"description": "\n\nDefines a placeholder for title input box that will be used in the edit component.\n Following variables will be replaced at runtime:\n \n
\n {spaceName}: Name of the current space{spaceKey}: Key of the current space{contentTypeName}: Name of the current custom content
\n \"What do you want to know about {SpaceName}\" will become \"What do you want to know about Demonstration Space\"\n if user is creating a new piece of custom content in \"Demonstration Space\" space.\n\n"
},
"listViewComponent": {
"$ref": "#/definitions/componentReference",
"fieldDescription": "\n\nDefines a module that will be used when a user clicks the navigation link displayed in the space sidebar.
\n The module referenced must be a generalPage.\n A default list view will be provided if no view component was specified in this field.\n\n",
"description": "\n\nDefines a module that will be used when a user clicks the navigation link displayed in the space sidebar.
\n The module referenced must be a generalPage.\n A default list view will be provided if no view component was specified in this field.\n\n"
},
"editComponent": {
"$ref": "#/definitions/componentReference",
"fieldDescription": "\n\nDefines a module for adding or editing custom content.
\n The module referenced must be a generalPage.\n Following context variable will be provided to the edit component URL\n \n
\n Please consult Context Parameters for how to use a context variable.\n customcontent.create: Indicates whether user is creating or editing a piece of custom content
\n Please refer to the Custom Content JavaScript API\n for how to intercept the edit component events and override the default behavior.\n\n ![\"Custom](\"/cloud/connect/images/confluence-customcontent-edit.png\")
\n\n",
"description": "\n\nDefines a module for adding or editing custom content.
\n The module referenced must be a generalPage.\n Following context variable will be provided to the edit component URL\n \n
\n Please consult Context Parameters for how to use a context variable.\n customcontent.create: Indicates whether user is creating or editing a piece of custom content
\n Please refer to the Custom Content JavaScript API\n for how to intercept the edit component events and override the default behavior.\n\n \n\n"
},
"icons": {
"properties": {
"item": {
"$ref": "#/definitions/icon",
"fieldDescription": "\n\nDefines an icon that used for displaying a single custom content item in:\n \n
\n The icon resource provided in this field must be larger or equals to 16x16 pixels.
\n\n",
"description": "\n\nDefines an icon that used for displaying a single custom content item in:\n \n
\n The icon resource provided in this field must be larger or equals to 16x16 pixels.
\n\n"
},
"create": {
"$ref": "#/definitions/icon",
"fieldDescription": "\n\nDefines an icon that is used for custom content items in the create dialog.
\n The icon resource provided in this field must be larger or equals to 48x48 pixels.
\n It will fallback to item icon if this field is not specified.\n In that case, please ensure the item icon is larger or equals to 48x48 pixels.\n\n",
"description": "\n\nDefines an icon that is used for custom content items in the create dialog.
\n The icon resource provided in this field must be larger or equals to 48x48 pixels.
\n It will fallback to item icon if this field is not specified.\n In that case, please ensure the item icon is larger or equals to 48x48 pixels.\n\n"
},
"list": {
"$ref": "#/definitions/icon",
"fieldDescription": "\n\nDefines an icon that used for displaying list of custom content items in:\n \n
\n The icon resource provided in this field must be larger or equals to 20x20 pixels.
\n It will fallback to item icon if this field is not specified.\n In that case, please ensure the item icon is larger or equals to 20x20 pixels.\n\n",
"description": "\n\nDefines an icon that used for displaying list of custom content items in:\n \n
\n The icon resource provided in this field must be larger or equals to 20x20 pixels.
\n It will fallback to item icon if this field is not specified.\n In that case, please ensure the item icon is larger or equals to 20x20 pixels.\n\n"
}
},
"required": [
"item"
],
"shortClassName": "customContentIconsBean",
"type": "object",
"title": "Custom Content Icons",
"description": "\n\nDefines icons that used for displaying the custom content.\n\n\n\n {\n \"item\": {\n \"width\": 16,\n \"height\": 16,\n \"url\": \"/item.png\"\n }\n }\n\n\n",
"fieldDescription": "\n\nDefines icons used for displaying the content.\n\n"
},
"contentViewComponent": {
"$ref": "#/definitions/componentReference",
"fieldDescription": "\n\nDefines a module for viewing custom content.
\n The module referenced must be a generalPage.\n \n
\n\n",
"description": "\n\nDefines a module for viewing custom content.
\n When a user clicks the title of a custom content entry in site search result.\n
\n When a user clicks the title of a custom content entry in the space list view.\n
\n When a user clicks the title of a custom content entry in the page list view.\n
\n The module referenced must be a generalPage.\n \n
\n\n"
},
"editComponentSubmitButtonLabel": {
"$ref": "#/definitions/i18nProperty",
"fieldDescription": "\n\nDefines the label for submit button on edit component\n\n",
"description": "\n\nDefines the label for submit button on edit component\n\n"
},
"editComponentCancelButtonLabel": {
"$ref": "#/definitions/i18nProperty",
"fieldDescription": "\n\nDefines the label for cancel button on edit component\n\n",
"description": "\n\nDefines the label for cancel button on edit component\n\n"
},
"breadcrumbs": {
"properties": {
"relations": {
"items": {
"properties": {
"name": {
"maxLength": 100,
"type": "string",
"fieldDescription": "\n\nName of the content relation\n\n",
"description": "\n\nName of the content relation\n\n"
}
},
"shortClassName": "customContentRelationBean",
"type": "object",
"title": "Custom Content Relation",
"description": "\n\nA reference to a custom content relation\n\n\n\n {\n \"name\": \"worksFor\"\n }\n\n\n"
},
"type": "array",
"fieldDescription": "\n\nDefines the list of content relations used for generating breadcrumbs
\n When a user clicks the title of a custom content entry in site search result.\n
\n When a user clicks the title of a custom content entry in the space list view.\n
\n When a user clicks the title of a custom content entry in the page list view.\n
\n Following sorting orders will apply:\n \n
\n\n",
"description": "\n\nDefines the list of content relations used for generating breadcrumbs
\n Following sorting orders will apply:\n \n
\n\n"
}
},
"shortClassName": "customContentBreadcrumbsBean",
"type": "object",
"title": "Custom Content Breadcrumbs",
"description": "\n\nDefines the breadcrumbs for this content
\n\n Use Relation API to generate breadcrumbs
\n An add-on can specify multiple content relationships for generating the breadcrumbs.\n Suppose we have ac:add-on-key:employee defined with following breadcrumbs setting:\n
\n \n ...\n \"breadcrumbs\": {\n \"relations\": [\n {\n \"name\": \"worksFor\"\n }\n ]\n }\n ...\n \n
\n \n \n Content ID \n Content Type \n Title \n \n \n 1 \n ac:add-on-key:organization \n Company A \n \n \n 2 \n ac:add-on-key:organization \n Company B \n \n \n 3 \n ac:add-on-key:employee \n Charlie \n \n
\n ac:add-on-key:employee to use worksFor relation to generate the breadcrumbs.\n Confluence will fetch the relations that were created under name worksFor,\n then display the titles in the creation order of their relations in the search result like this:\n ![\"Quick](\"/cloud/connect/images/confluence-quick-search-breadcrumbs.png\")
\n ![\"Quick](\"/cloud/connect/images/confluence-search-breadcrumbs.png\")
\n\n",
"fieldDescription": "\n\nDefines the breadcrumbs used in\n \n
\n\n"
}
},
"required": [
"icons",
"contentViewComponent"
],
"shortClassName": "customContentUISupportBean",
"type": "object",
"title": "Custom Content UI Support",
"description": "\n\nDeclares information related for rendering the custom content in the UI.
\n Add-ons have the ability to control the UI components for user to view the custom content.\n\n\n\n {\n \"contentViewComponent\": {\n \"addonKey\": \"addon-key\",\n \"moduleKey\": \"general-page-module-key\"\n }\n }\n\n\n\n\n View component example
\n Suppose we already defined a general page module like following:\n\n {\n \"url\": \"/my-general-page?content.plugin={content.plugin}&content.id={content.id}&content.version={content.version}&space.key={space.key}&customParameter={ac.customData}\",\n \"name\": {\n \"value\": \"My viewer page\"\n },\n \"key\": \"my-viewer\"\n }\n\n\n\n /my-general-page will be rendered in a iframe with following context parameters being passed.
\n \n
\n Note, that if an optional custom value is defined in the url string, such as content.plugin: The content type key of the content. eg: ac:addon-key:module-keycontent.id: The id of the contentcontent.version: The version of the contentspace.key: The key of the space which content is contained in{ac.customData} in the example above, it will be substituted with the value\n of the ac.customData parameter that will be taken from the Confluence's current URL. Add-on developers can specify any number of custom parameters, provided that they\n have names that follow this convention: ac.parameter_name.\n If more than one custom parameter with the same name is defined in Confluence's current URL, only the first value will be used.\n For additional information on custom parameters see Context Parameters.\n\n Context Parameters
\n View components support Confluence context parameters. When rendering the view component\n the context variables will be passed to the URL that is defined in the corresponding view component module.
\n You can retrieve the content or space information with these parameters via Confluence REST API\n and render it according to your needs.
\n Please consult Context Parameters for what parameters are currently supported."
},
"spaceTools": {
"properties": {
"name": {
"$ref": "#/definitions/i18nProperty",
"fieldDescription": "\n\nA human readable name.\n\n",
"description": "\n\nA human readable name.\n\n"
},
"weight": {
"type": "integer",
"fieldDescription": "\n\nDetermines the order in which the page's link appears in the menu or list.\n Example
\n\n\n\n {\n \"conditions\": [\n {\n \"or\": [\n {\n \"condition\": \"can_attach_file_to_issue\",\n \"invert\": false\n },\n {\n \"condition\": \"is_issue_assigned_to_current_user\",\n \"invert\": false\n }\n ]\n },\n {\n \"condition\": \"user_is_logged_in\",\n \"invert\": false\n }\n ]\n }\n\n\n"
},
{
"properties": {
"condition": {
"maxLength": 100,
"type": "string",
"fieldDescription": "\n\nA string indicating the name of the condition\n\n",
"description": "\n\nA string indicating the name of the condition\n\n"
},
"invert": {
"type": "boolean",
"fieldDescription": "\n\nA flag indicating whether to invert the boolean result of the condition.\n\n",
"defaultValue": "false",
"description": "\n\nA flag indicating whether to invert the boolean result of the condition.\n\n"
},
"params": {
"additionalProperties": true,
"type": "object",
"fieldTitle": "Object",
"fieldDescription": "\n\nThis object represents a map of key/value pairs, where each property name and value corresponds to the parameter name and value respectively.\n\n Example
\n\n\n\n {\n \"condition\": \"user_is_logged_in\",\n \"invert\": false\n }\n\n\n"
}
]
},
"type": "array",
"fieldDescription": "\n\nConditions can be added to display only when all the given conditions are true.\n\n",
"description": "\n\nConditions can be added to display only when all the given conditions are true.\n\n"
},
"params": {
"additionalProperties": true,
"type": "object",
"fieldTitle": "Object",
"fieldDescription": "\n\nThis object represents a map of key/value pairs, where each property name and value corresponds to the parameter name and value respectively.\n\n bodyType: none.\n The app can still provide meaningful search text for this content by storing the extracted information to\n the macro parameter. The data in this macro parameter will get indexed as is without any modification.Example
\n\n\n\n {\n \"link\": {\n \"url\": \"/go-somewhere\",\n \"title\": \"Go Somewhere\",\n \"altText\": \"somewhere\"\n }\n }\n\n\n"
},
"staticContentMacro": {
"properties": {
"bodyType": {
"enum": [
"rich-text",
"RICH-TEXT",
"multi-body-rich-text",
"MULTI-BODY-RICH-TEXT",
"plain-text",
"PLAIN-TEXT",
"none",
"NONE"
],
"type": "string",
"fieldDescription": "\n\n\n
\n \n \n Value \n Description \n \n \n rich-text RICH-TEXTThe macro will contain a body that can include other Confluence elements. \n \n \n multi-body-rich-text* MULTI-BODY-RICH-TEXT*The macro will contain multiple \n rich-text bodies.\n \n plain-text PLAIN-TEXTThe macro will contain a body that can include plain text. \n \n \n none NONEThe macro won't have a body. \n multi-body-rich-text and MULTI-BODY-RICH-TEXT values can only be accessed through\n [EAP](/cloud/confluence/changelog/#CHANGE-1434).\n \n
\n \n \n Value \n Description \n \n \n rich-text RICH-TEXTThe macro will contain a body that can include other Confluence elements. \n \n \n multi-body-rich-text* MULTI-BODY-RICH-TEXT*The macro will contain multiple \n rich-text bodies.\n \n plain-text PLAIN-TEXTThe macro will contain a body that can include plain text. \n \n \n none NONEThe macro won't have a body. \n multi-body-rich-text and MULTI-BODY-RICH-TEXT values can only be accessed through\n [EAP](/cloud/confluence/changelog/#CHANGE-1434).\n \n
\n\n",
"defaultValue": "false",
"description": "\n\nReturns whether the URL should be cacheable. Cacheable URLs are taken directly from the add-on descriptor, and\n lack all additional query parameters:\n \n
\n\n"
},
"url": {
"format": "uri-template",
"type": "string",
"fieldDescription": "\n\nThe URL to the macro configuration page in the add-on.\n\n",
"description": "\n\nThe URL to the macro configuration page in the add-on.\n\n"
},
"height": {
"maxLength": 10,
"type": "string",
"fieldDescription": "\n\nThe preferred height of the edit dialog, e.g. ``300px``.\n\n",
"description": "\n\nThe preferred height of the edit dialog, e.g. ``300px``.\n\n"
}
},
"required": [
"url"
],
"shortClassName": "macroEditorBean",
"type": "object",
"title": "Macro Editor",
"description": "\n\nMacro Parameters go a long way when it comes to macro configuration, but there are cases\n when a macro add-on needs more control over the UI.\n
\n \n {\n \"url\": \"/macro-renderer?body={macro.body}&space_id={space.id}&page_id={page.id}\"\n }\n
\n - If you know your macro contains a body that will often exceed the 128 character threshold\n (or is known to contain sensitive data), then you can include the `{macro.id}` parameter and\n use the Confluence REST api to call back to collect the body.
\n - If you want, you can include, `{macro.body}`, `{macro.id}`, and `{macro.truncated}`. This way\n your plugin can call back to confluence only if `{macro.truncated}` is '`true`'. This will allow\n you to skip the callback if it's not needed. This would be useful for macros that don't\n contain sensitive data of an unpredictable size.\n
\n \n {\n \"url\": \"/render-macro?pageId={page.id}&pageVersion={page.version}¯oId={macro.id}\"\n }\n
\n \n AP.require(\"request\", function(request) {\n var pageId = getUrlParameter(\"pageId\");\n var pageVersion = getUrlParameter(\"pageVersion\");\n var macroId = getUrlParameter(\"macroId\");\n request({\n url: \"/rest/api/content/\" + pageId +\n \"/history/\" + pageVersion +\n \"/macro/id/\" + macroId,\n success: function(response) {\n var macro = JSON.parse(response);\n process(macro.body);\n }\n });\n });\n
\n - `macro.id`: The id of the macro
\n - `macro.body`: The macro body, truncated to 128 characters
\n - `macro.truncated`: True if the macro body was truncated, false of not
\n - `page.id`: The page ID, e.g. `1376295`
\n - `page.title`: The page title, e.g. `My Page`
\n - `page.type`: The page type, e.g. `page`
\n - `page.version`: The page version, e.g. `6`
\n - `space.id`: The space ID, e.g. `65537`
\n - `space.key`: The space key, e.g. `AC`
\n - `user.id`: The user ID, e.g. `admin` (deprecated in GDPR mode)
\n - `user.key`: The user key, e.g. `ff80808143087d180143087d3a910004` (deprecated in GDPR mode)
\n - `output.type`: The output type, e.g. `display` or `preview`
\n
\n \n {\n \"url\": \"/macro-renderer?body={macro.body}&space_id={space.id}&page_id={page.id}\"\n }\n
\n - If you know your macro contains a body that will often exceed the 128 character threshold\n (or is known to contain sensitive data), then you can include the `{macro.id}` parameter and\n use the Confluence REST api to call back to collect the body.
\n - If you want, you can include, `{macro.body}`, `{macro.id}`, and `{macro.truncated}`. This way\n your plugin can call back to confluence only if `{macro.truncated}` is '`true`'. This will allow\n you to skip the callback if it's not needed. This would be useful for macros that don't\n contain sensitive data of an unpredictable size.\n
\n \n {\n \"url\": \"/render-macro?pageId={page.id}&pageVersion={page.version}¯oId={macro.id}\"\n }\n
\n \n AP.require(\"request\", function(request) {\n var pageId = getUrlParameter(\"pageId\");\n var pageVersion = getUrlParameter(\"pageVersion\");\n var macroId = getUrlParameter(\"macroId\");\n request({\n url: \"/rest/api/content/\" + pageId +\n \"/history/\" + pageVersion +\n \"/macro/id/\" + macroId,\n success: function(response) {\n var macro = JSON.parse(response);\n process(macro.body);\n }\n });\n });\n
\n - `macro.id`: The id of the macro
\n - `macro.body`: The macro body, truncated to 128 characters
\n - `macro.truncated`: True if the macro body was truncated, false of not
\n - `page.id`: The page ID, e.g. `1376295`
\n - `page.title`: The page title, e.g. `My Page`
\n - `page.type`: The page type, e.g. `page`
\n - `page.version`: The page version, e.g. `6`
\n - `space.id`: The space ID, e.g. `65537`
\n - `space.key`: The space key, e.g. `AC`
\n - `user.id`: The user ID, e.g. `admin` (deprecated in GDPR mode)
\n - `user.key`: The user key, e.g. `ff80808143087d180143087d3a910004` (deprecated in GDPR mode)
\n - `output.type`: The output type, e.g. `display` or `preview`
\n \n
\n\n",
"defaultValue": "false",
"description": "\n\nReturns whether the URL should be cacheable. Cacheable URLs are taken directly from the add-on descriptor, and\n lack all additional query parameters:\n \n
\n\n"
},
"url": {
"format": "uri-template",
"type": "string",
"fieldDescription": "\n\nThe URL of the add-on endpoint which will be served as a hidden iframe inside the property panel\n\n",
"description": "\n\nThe URL of the add-on endpoint which will be served as a hidden iframe inside the property panel\n\n"
}
},
"required": [
"url"
],
"shortClassName": "macroPropertyPanelBean",
"type": "object",
"title": "Macro Property Panel",
"description": "\n\nDefining a Macro Property panel allows you to add a hidden iframe to your macro's\n property panel. The iframe is loaded as soon as the property panel is opened.\n
\n If the rendering method was set to POST like this:\n
\n \n {\n \"renderingMethod\": \"POST\",\n \"url\": \"/macro-renderer?body={macro.body}\"\n }\n /macro-renderer like:
\n
\n\n Note: All the parameters will be sent via POST payload in\n \n POST /macro-renderer HTTP/1.1\n Authorization: JWT <JWT token>\n Content-Type: application/x-www-form-urlencoded\n Transfer-Encoding: chunked\n Host: <host>\n User-Agent: Atlassian HttpClient <atlassian http client version> / Confluence-<confluence version> / Atlassian-Connect/<connect version>\n\n body=<macro body>&<some value>&pageVersion=<some value>&tz=<some value>&lic=<some value>&user_key=<some value>&xd&_e=<some value>&cp=<some value>&xdm_c=<some value>&cv=<some value>&user_id=<some value>\n application/x-www-form-urlencoded instead of URL query parameters.
\n The latest version of Atlassian Connect Express and Atlassian Connect Spring Boot\n have built-in support for verifying requests sent by POST. However you might need to implement the query hash\n verification if the framework you are using doesn't support it.\n\n",
"defaultValue": "get",
"description": "\n\nHTTP method that will be used in the HTTP request.\n
\n If the rendering method was set to POST like this:\n
\n \n {\n \"renderingMethod\": \"POST\",\n \"url\": \"/macro-renderer?body={macro.body}\"\n }\n /macro-renderer like:
\n
\n\n Note: All the parameters will be sent via POST payload in\n \n POST /macro-renderer HTTP/1.1\n Authorization: JWT <JWT token>\n Content-Type: application/x-www-form-urlencoded\n Transfer-Encoding: chunked\n Host: <host>\n User-Agent: Atlassian HttpClient <atlassian http client version> / Confluence-<confluence version> / Atlassian-Connect/<connect version>\n\n body=<macro body>&<some value>&pageVersion=<some value>&tz=<some value>&lic=<some value>&user_key=<some value>&xd&_e=<some value>&cp=<some value>&xdm_c=<some value>&cv=<some value>&user_id=<some value>\n application/x-www-form-urlencoded instead of URL query parameters.
\n The latest version of Atlassian Connect Express and Atlassian Connect Spring Boot\n have built-in support for verifying requests sent by POST. However you might need to implement the query hash\n verification if the framework you are using doesn't support it.\n\n"
},
"name": {
"$ref": "#/definitions/i18nProperty",
"fieldDescription": "\n\nA human readable name.\n\n",
"description": "\n\nA human readable name.\n\n"
},
"categories": {
"items": {
"maxLength": 100,
"type": "string"
},
"type": "array",
"fieldDescription": "\n\nThe categories the macro should appear in. A macro with no category will show up in the default 'All' category.\n \n
\n\n",
"description": "\n\nThe categories the macro should appear in. A macro with no category will show up in the default 'All' category.\n \n
\n\n"
},
"parameters": {
"items": {
"properties": {
"identifier": {
"pattern": "[-_a-z0-9\\.]+",
"type": "string",
"fieldDescription": "\n\nA unique identifier for the parameter.\n It must only contain lowercase alphanumeric characters, dashes, underscores, dots and must not contain any spaces.\n This identifier will be used in the query parameters of the add-on URL.\n\n",
"description": "\n\nA unique identifier for the parameter.\n It must only contain lowercase alphanumeric characters, dashes, underscores, dots and must not contain any spaces.\n This identifier will be used in the query parameters of the add-on URL.\n\n"
},
"aliases": {
"items": {
"maxLength": 100,
"type": "string"
},
"type": "array",
"fieldDescription": "\n\nAliases for the macro parameter.\n\n",
"description": "\n\nAliases for the macro parameter.\n\n"
},
"hidden": {
"type": "boolean",
"fieldDescription": "\n\nDetermines if the parameter will be displayed in the macro editor.\n\n",
"defaultValue": "false",
"description": "\n\nDetermines if the parameter will be displayed in the macro editor.\n\n"
},
"indexing": {
"$ref": "#/definitions/indexing",
"fieldDescription": "\n\nDefines how this macro parameter will be indexed\n\n",
"description": "\n\nDefines how this macro parameter will be indexed\n\n"
},
"defaultValue": {
"maxLength": 1000,
"type": "string",
"fieldDescription": "\n\nThe default value for the parameter.\n\n",
"description": "\n\nThe default value for the parameter.\n\n"
},
"values": {
"items": {
"maxLength": 1000,
"type": "string"
},
"type": "array",
"fieldDescription": "\n\nDescribes the ``enum`` values - only applicable for enum typed parameters.\n\n",
"description": "\n\nDescribes the ``enum`` values - only applicable for enum typed parameters.\n\n"
},
"name": {
"$ref": "#/definitions/i18nProperty",
"fieldDescription": "\n\nThe human readable name of the parameter which will be displayed in the UI.\n\n",
"description": "\n\nThe human readable name of the parameter which will be displayed in the UI.\n\n"
},
"multiple": {
"type": "boolean",
"fieldDescription": "\n\nWhether it takes multiple values.\n\n",
"defaultValue": "false",
"description": "\n\nWhether it takes multiple values.\n\n"
},
"description": {
"$ref": "#/definitions/i18nProperty",
"fieldDescription": "\n\nThe description of the parameter\n\n",
"description": "\n\nThe description of the parameter\n\n"
},
"type": {
"enum": [
"attachment",
"ATTACHMENT",
"boolean",
"BOOLEAN",
"confluence-content",
"CONFLUENCE-CONTENT",
"enum",
"ENUM",
"int",
"INT",
"label",
"LABEL",
"spacekey",
"SPACEKEY",
"string",
"STRING",
"url",
"URL",
"username",
"USERNAME"
],
"type": "string",
"fieldDescription": "\n\nThe type of parameter.\n
\n\n \n \"dynamicContentMacros\": [{\n ...\n \"url\": \"/render-map?pageTitle={page.title}&viewChoice={view}\",\n ...\n }]\n Example
\n\n\n\n {\n \"dynamicContentMacros\": {\n \"renderModes\": {},\n \"url\": \"/my-macro\",\n \"categories\": [],\n \"outputType\": \"block\",\n \"bodyType\": \"none\",\n \"aliases\": [],\n \"parameters\": [\n {\n \"identifier\": \"view\",\n \"name\": {\n \"value\": \"Map View\"\n },\n \"description\": {\n \"value\": \"Allows switching between view types\"\n },\n \"type\": \"enum\",\n \"required\": true,\n \"multiple\": false,\n \"defaultValue\": \"Map\",\n \"values\": [\n \"Map\",\n \"Satellite\"\n ],\n \"hidden\": false,\n \"indexing\": {\n \"enabled\": true\n }\n }\n ],\n \"name\": {\n \"value\": \"My macro with placeholder\"\n },\n \"key\": \"my-macro-key\"\n }\n }\n\n\n"
},
"type": "array",
"fieldDescription": "\n\nThe list of parameter input fields that will be displayed.\n\n",
"description": "\n\nThe list of parameter input fields that will be displayed.\n\n"
},
"key": {
"pattern": "^[a-zA-Z0-9-]+$",
"maxLength": 100,
"type": "string",
"fieldDescription": "\n\nA key to identify the macro. Keys must only contain alphanumeric characters and dashes, and must be globally unique. Prefixing it with the name of your add-on is the best way to ensure this.",
"description": "\n\nA key to identify the macro. Keys must only contain alphanumeric characters and dashes, and must be globally unique. Prefixing it with the name of your add-on is the best way to ensure this."
}
},
"required": [
"name",
"url",
"key"
],
"additionalProperties": true,
"shortClassName": "staticContentMacroModuleBean",
"type": "object",
"title": "Static Content Macro",
"description": "\n\nA Confluence macro that returns XHTML in the Confluence storage format. Note, unlike most\n Connect modules, this content is not displayed in an iframe. Instead, your macro is responsible for returning valid\n Storage Format XML to the confluence page, which Confluence will render for you at view time.\n Use Caching
\n
\n \n res.set('Cache-Control', `public, max-age=3600`);\n ETag and If-None-Match to render the macro conditionally.\n
\n\n \n Cache-Control: no-cache\n
\n
\n You can use these parameters to dynamically generate the placeholder image.
\n /images/placeholder.png?param1=value1¶m2=value2",
"description": "\n\nThe URL of the image placeholder. Your image placeholder needs to be hosted remotely at a web-accessible location.\n You can specify the URL as an absolute URL or relative to the add-on's base URL.
\n
\n You can use these parameters to dynamically generate the placeholder image.
\n /images/placeholder.png?param1=value1¶m2=value2"
},
"height": {
"type": "integer",
"fieldDescription": "\n\nThe height in pixels of the image placeholder. Defaults to the natural image height if not specified.\n\n",
"description": "\n\nThe height in pixels of the image placeholder. Defaults to the natural image height if not specified.\n\n"
}
},
"required": [
"url"
],
"shortClassName": "imagePlaceholderBean",
"type": "object",
"title": "Image Placeholder",
"description": "\n\nDefines a macro image placeholder to display in the Confluence editor.\n\n
\n\n NOTE: since the call to this URL will be made from the user's browser, you need to enable\n CORS headers for responses to this resource.\n \n [\n {\"id\": \"value1\", \"text\": \"First Option\"},\n {\"id\": \"value2\", \"text\": \"Second Option\"}\n ]\n Access-Control-Allow-Origin header to the URL of the Atlassian Cloud instance where\n this add-on is installed is usually enough to satisfy the CORS requirements. This can be done by tracking\n the client key and its url in your /installed callback, then looking up the url when the request\n is made.\n\n",
"description": "\n\nIf provided, the CQL builder will provide a drop down and use this url to find the list of value values. This\n URL should return a json array of objects describing the valid options.\n\n
\n\n NOTE: since the call to this URL will be made from the user's browser, you need to enable\n CORS headers for responses to this resource.\n \n [\n {\"id\": \"value1\", \"text\": \"First Option\"},\n {\"id\": \"value2\", \"text\": \"Second Option\"}\n ]\n Access-Control-Allow-Origin header to the URL of the Atlassian Cloud instance where\n this add-on is installed is usually enough to satisfy the CORS requirements. This can be done by tracking\n the client key and its url in your /installed callback, then looking up the url when the request\n is made.\n\n"
},
"valueType": {
"enum": [
"space",
"SPACE",
"label",
"LABEL",
"user",
"USER",
"contentid",
"CONTENTID",
"contenttype",
"CONTENTTYPE",
"date",
"DATE",
"string",
"STRING",
"number",
"NUMBER"
],
"type": "string",
"fieldDescription": "\n\nAs well as providing a text field and allowing any entry, the UI support system provides a number of\n build in components that can enrich the user experience. These provide extra user interface components\n to allow setting or picking their value in an intuitive way.\n \n
\n\n",
"description": "\n\nAs well as providing a text field and allowing any entry, the UI support system provides a number of\n build in components that can enrich the user experience. These provide extra user interface components\n to allow setting or picking their value in an intuitive way.\n space - provides a space picker and stores the result space key as the result.label - provides a label picker and stores the list of labels as the result.user - provides a user picker and stores the username as the result.contentId - provides a content picker and stores the content id as the result.contentType - provides a content type picker.date - provides a date pickerstring - provides a free form text fieldnumber - provides a free form text field\n
\n\n"
},
"name": {
"$ref": "#/definitions/i18nProperty",
"fieldDescription": "\n\nThe name of this field as used by the CQL builder UI components.\n\n",
"description": "\n\nThe name of this field as used by the CQL builder UI components.\n\n"
},
"tooltip": {
"$ref": "#/definitions/i18nProperty",
"fieldDescription": "\n\nThe tooltip of this field as used by the CQL builder UI components.\n\n",
"description": "\n\nThe tooltip of this field as used by the CQL builder UI components.\n\n"
}
},
"required": [
"valueType",
"name"
],
"shortClassName": "uISupportBean",
"type": "object",
"title": "User Interface Support",
"description": "\n\nThe UI Support element allows you to define how your content property field will be presented in\n the CQL Builder.\n space - provides a space picker and stores the result space key as the result.label - provides a label picker and stores the list of labels as the result.user - provides a user picker and stores the username as the result.contentId - provides a content picker and stores the content id as the result.contentType - provides a content type picker.date - provides a date pickerstring - provides a free form text fieldnumber - provides a free form text field\n
\n\n",
"defaultValue": "addon",
"description": "\n\nThe context for the URL parameter. Not applicable if an absolute URL is specified. Possible values\n \n
\n\n"
},
"tooltip": {
"$ref": "#/definitions/i18nProperty",
"fieldDescription": "\n\nThe internationalised text to be used in the link's tooltip.\n\n",
"description": "\n\nThe internationalised text to be used in the link's tooltip.\n\n"
},
"icon": {
"$ref": "#/definitions/icon",
"fieldDescription": "\n\nAn optional icon to display with the link text or as the link, specified by URL to its hosted location.\n You can specify a particular width and height for the icon. Most link icons in Atlassian applications\n are 16 by 16 pixels.\n\n",
"description": "\n\nAn optional icon to display with the link text or as the link, specified by URL to its hosted location.\n You can specify a particular width and height for the icon. Most link icons in Atlassian applications\n are 16 by 16 pixels.\n\n"
},
"name": {
"$ref": "#/definitions/i18nProperty",
"fieldDescription": "\n\nA human readable name.\n\n",
"description": "\n\nA human readable name.\n\n"
},
"cacheable": {
"type": "boolean",
"fieldDescription": "\n\nReturns whether the URL should be cacheable. Cacheable URLs are taken directly from the add-on descriptor, and\n lack all additional query parameters:\n \n
\n\n",
"defaultValue": "false",
"description": "\n\nReturns whether the URL should be cacheable. Cacheable URLs are taken directly from the add-on descriptor, and\n lack all additional query parameters:\n \n
\n\n"
},
"conditions": {
"items": {
"type": "object",
"anyOf": [
{
"$ref": "#/definitions/singleCondition"
},
{
"$ref": "#/definitions/compositeCondition"
}
]
},
"type": "array",
"fieldDescription": "\n\nConditions can be added to display only when all the given conditions are true.\n\n",
"description": "\n\nConditions can be added to display only when all the given conditions are true.\n\n"
},
"params": {
"additionalProperties": true,
"type": "object",
"fieldTitle": "Object",
"fieldDescription": "\n\nThis object represents a map of key/value pairs, where each property name and value corresponds to the parameter name and value respectively.\n\n
\n\n\n\n {\n \"name\": {\n \"value\": \"Item Text\"\n },\n \"icon\": {\n \"width\": 16,\n \"height\": 16,\n \"url\": \"/my-icon.png\"\n },\n \"tooltip\": {\n \"value\": \"Item Tooltip\"\n }\n }\n\n\n\n tooltip, this Content\n Byline Item module must specify a tooltip. Likewise for a Content-Property-based\n icon, this module must specify an icon.\n
\n\n\n\n {\n \"name\": {\n \"value\": \"Item Text\"\n },\n \"icon\": {\n \"width\": 16,\n \"height\": 16,\n \"url\": \"/my-icon.png\"\n },\n \"tooltip\": {\n \"value\": \"Item Tooltip\"\n }\n }\n\n\n\n tooltip, this Content\n Byline Item module must specify a tooltip. Likewise for a Content-Property-based\n icon, this module must specify an icon.\n context
field.\n\n target of the item is not a\n Dialog Module.\n context
field.\n\n target of the item is not a\n Dialog Module.\n \n
\n\n",
"anyOf": [
{
"properties": {
"offsetX": {
"maxLength": 10,
"type": "string",
"fieldDescription": "\n\nSets an offset distance of the inline-dialog from the trigger element along the x-axis in pixels\n\n",
"description": "\n\nSets an offset distance of the inline-dialog from the trigger element along the x-axis in pixels\n\n"
},
"offsetY": {
"maxLength": 10,
"type": "string",
"fieldDescription": "\n\nSets an offset distance of the inline-dialog from the trigger element along the y-axis in pixels\n\n",
"description": "\n\nSets an offset distance of the inline-dialog from the trigger element along the y-axis in pixels\n\n"
},
"width": {
"maxLength": 10,
"type": "string",
"fieldDescription": "\n\nSets how wide the dialog is in pixels.\n\n",
"description": "\n\nSets how wide the dialog is in pixels.\n\n"
},
"onTop": {
"type": "boolean",
"fieldDescription": "\n\nDetermines if the dialog should be shown above the trigger or not. If this option is true but there is insufficient room above the trigger the inline-dialog will be flipped to display below it\n\n",
"description": "\n\nDetermines if the dialog should be shown above the trigger or not. If this option is true but there is insufficient room above the trigger the inline-dialog will be flipped to display below it\n\n"
},
"showDelay": {
"type": "integer",
"fieldDescription": "\n\nDetermines how long in milliseconds after a show trigger is fired (such as a trigger click) until the dialog is shown\n\n",
"description": "\n\nDetermines how long in milliseconds after a show trigger is fired (such as a trigger click) until the dialog is shown\n\n"
},
"closeOthers": {
"type": "boolean",
"fieldDescription": "\n\nDetermines if all other dialogs on the screen are closed when this one is opened\n\n",
"description": "\n\nDetermines if all other dialogs on the screen are closed when this one is opened\n\n"
},
"persistent": {
"type": "boolean",
"fieldDescription": "\n\nThis option, ignores the 'closeOthers' option\n\n",
"description": "\n\nThis option, ignores the 'closeOthers' option\n\n"
},
"onHover": {
"type": "boolean",
"fieldDescription": "\n\nExample
\n\n\n\n {\n \"target\": {\n \"type\": \"inlinedialog\",\n \"options\": {\n \"onHover\": true,\n \"offsetX\": \"30px\",\n \"offsetY\": \"20px\"\n }\n }\n }\n\n\n"
},
{
"properties": {
"key": {
"maxLength": 100,
"type": "string",
"fieldDescription": "\n\nExample
\n\n\n\n {\n \"target\": {\n \"type\": \"dialogmodule\",\n \"options\": {\n \"key\": \"dialog-module-key\"\n }\n }\n }\n\n\n"
},
{
"properties": {
"size": {
"enum": [
"small",
"SMALL",
"medium",
"MEDIUM",
"large",
"LARGE",
"x-large",
"X-LARGE",
"fullscreen",
"FULLSCREEN",
"maximum",
"MAXIMUM"
],
"type": "string",
"fieldDescription": "\n\nSets the size of the dialog.\n\n Web Item Example
\n\n\n\n {\n \"target\": {\n \"type\": \"dialog\",\n \"options\": {\n \"height\": \"100px\",\n \"width\": \"200px\"\n }\n }\n }\n\n\n\n\n Dialog Example
\n\n {\n \"modules\": {\n \"dialogs\": [\n {\n \"url\": \"/my-dialog-content\",\n \"options\": {\n \"size\": \"fullscreen\",\n \"header\": {\n \"value\": \"Example Dialog\"\n }\n },\n \"key\": \"dialog-module-key\"\n }\n ]\n }\n }\n\n\n"
}
],
"description": "\n\n\n
\n\n"
},
"type": {
"enum": [
"page",
"PAGE",
"dialog",
"DIALOG",
"inlinedialog",
"INLINEDIALOG",
"dialogmodule",
"DIALOGMODULE"
],
"type": "string",
"fieldDescription": "\n\nDefines how the web-item content should be loaded by the page. By default, the web-item is loaded in the same\n page. The target can be set to open the web-item url as a modal dialog or an inline dialog.\n\n",
"defaultValue": "page",
"description": "\n\nDefines how the web-item content should be loaded by the page. By default, the web-item is loaded in the same\n page. The target can be set to open the web-item url as a modal dialog or an inline dialog.\n\n"
}
},
"shortClassName": "webItemTargetBean",
"type": "object",
"title": "Web Item Target",
"description": "\n\nDefines the way a web item link is opened in the browser, such as in a modal or inline dialog.\n\n Inline Dialog Example
\n\n\n\n {\n \"target\": {\n \"type\": \"inlinedialog\",\n \"options\": {\n \"onHover\": true,\n \"offsetX\": \"30px\",\n \"offsetY\": \"20px\"\n }\n }\n }\n\n\n\n\n Dialog Example
\n\n {\n \"target\": {\n \"type\": \"dialog\",\n \"options\": {\n \"height\": \"100px\",\n \"width\": \"200px\"\n }\n }\n }\n\n\n\n\n Common Dialog Module Example
\n\n {\n \"target\": {\n \"type\": \"dialogmodule\",\n \"options\": {\n \"key\": \"dialog-module-key\"\n }\n }\n }\n\n\n\n\n
\n If not present, the module is assumed to be defined within the same add-on.\n\n",
"description": "\n\nThe add-on key that referenced module was defined in.
\n If not present, the module is assumed to be defined within the same add-on.\n\n"
},
"moduleKey": {
"maxLength": 100,
"type": "string",
"fieldDescription": "\n\nModule key of the referenced module.\n\n",
"description": "\n\nModule key of the referenced module.\n\n"
}
},
"required": [
"moduleKey"
],
"shortClassName": "moduleReferenceBean",
"type": "object",
"title": "Module Reference",
"description": "\n\nA reference to a module defined in either this or another add-on\n\n\n\n {\n \"addonKey\": \"addon-key\",\n \"moduleKey\": \"general-page-module-key\"\n }\n\n\n"
},
"publishCondition": {
"properties": {
"dialog": {
"properties": {
"width": {
"maxLength": 10,
"type": "string",
"fieldDescription": "\n\nSets how wide the dialog is in pixels.\n\n",
"description": "\n\nSets how wide the dialog is in pixels.\n\n"
},
"header": {
"$ref": "#/definitions/i18nProperty",
"fieldDescription": "\n\nThe header text for the dialog\n\n",
"description": "\n\nThe header text for the dialog\n\n"
},
"conditions": {
"items": {
"type": "object",
"anyOf": [
{
"$ref": "#/definitions/compositeCondition"
},
{
"$ref": "#/definitions/singleCondition"
}
]
},
"type": "array",
"fieldDescription": "\n\nConditions can be added to display only when all the given conditions are true.\n\n",
"description": "\n\nConditions can be added to display only when all the given conditions are true.\n\n"
},
"url": {
"format": "uri-template",
"type": "string",
"fieldDescription": "\n\nSpecifies the destination of the dialog content. The interpretation of this field depends on the value of the\n `context` field.\n Trigger dialog close using postMessage
\n You can close dialog by sending postMessage with action = closeConditionalPublishDialog\n
\n\n",
"fieldDescription": "\n\nTriggers the dialog on click of Publish button.\n\n"
},
"errorMessage": {
"$ref": "#/definitions/i18nProperty",
"fieldDescription": "\n\n\n $(function(){\n setTimeout(() => {\n window.top.postMessage({\n action: \"closeConditionalPublishDialog\"\n }, AP._data.origin)\n }, 10000);\n })\n \n
\n\n",
"defaultValue": "addon",
"description": "\n\nThe context for the URL parameter. As of now only supported value is `addon`.\n \n
\n\n"
},
"name": {
"$ref": "#/definitions/i18nProperty",
"fieldDescription": "\n\nA human readable name.\n\n",
"description": "\n\nA human readable name.\n\n"
},
"conditions": {
"items": {
"type": "object",
"anyOf": [
{
"$ref": "#/definitions/compositeCondition"
},
{
"$ref": "#/definitions/singleCondition"
}
]
},
"type": "array",
"fieldDescription": "\n\nConditions can be added to display only when all the given conditions are true.\n\n",
"description": "\n\nConditions can be added to display only when all the given conditions are true.\n\n"
},
"params": {
"additionalProperties": true,
"type": "object",
"fieldTitle": "Object",
"fieldDescription": "\n\nThis object represents a map of key/value pairs, where each property name and value corresponds to the parameter name and value respectively.\n\n publishConditions module allows you to block content publishing until conditions specified in this module are satisfied.\n All existing connect conditions are supported by this module.\n
\n \n \n Value \n Description \n \n \n rich-text RICH-TEXTThe macro will contain a body that can include other Confluence elements. \n \n \n multi-body-rich-text* MULTI-BODY-RICH-TEXT*The macro will contain multiple \n rich-text bodies.\n \n plain-text PLAIN-TEXTThe macro will contain a body that can include plain text. \n \n \n none NONEThe macro won't have a body. \n multi-body-rich-text and MULTI-BODY-RICH-TEXT values can only be accessed through\n [EAP](/cloud/confluence/changelog/#CHANGE-1434).\n \n
\n \n \n Value \n Description \n \n \n rich-text RICH-TEXTThe macro will contain a body that can include other Confluence elements. \n \n \n multi-body-rich-text* MULTI-BODY-RICH-TEXT*The macro will contain multiple \n rich-text bodies.\n \n plain-text PLAIN-TEXTThe macro will contain a body that can include plain text. \n \n \n none NONEThe macro won't have a body. \n multi-body-rich-text and MULTI-BODY-RICH-TEXT values can only be accessed through\n [EAP](/cloud/confluence/changelog/#CHANGE-1434).\n \n
\n\n",
"defaultValue": "false",
"description": "\n\nReturns whether the URL should be cacheable. Cacheable URLs are taken directly from the add-on descriptor, and\n lack all additional query parameters:\n \n
\n\n"
},
"url": {
"format": "uri-template",
"type": "string",
"fieldDescription": "\n\nThe URL to the macro configuration page in the add-on.\n\n",
"description": "\n\nThe URL to the macro configuration page in the add-on.\n\n"
},
"height": {
"maxLength": 10,
"type": "string",
"fieldDescription": "\n\nThe preferred height of the edit dialog, e.g. ``300px``.\n\n",
"description": "\n\nThe preferred height of the edit dialog, e.g. ``300px``.\n\n"
}
},
"required": [
"url"
],
"shortClassName": "macroEditorBean",
"type": "object",
"title": "Macro Editor",
"description": "\n\nMacro Parameters go a long way when it comes to macro configuration, but there are cases\n when a macro add-on needs more control over the UI.\n
\n \n {\n \"url\": \"/macro-renderer?body={macro.body}&space_id={space.id}&page_id={page.id}\"\n }\n
\n - If you know your macro contains a body that will often exceed the 128 character threshold\n (or is known to contain sensitive data), then you can include the `{macro.id}` parameter and\n use the Confluence REST api to call back to collect the body.
\n - If you want, you can include, `{macro.body}`, `{macro.id}`, and `{macro.truncated}`. This way\n your plugin can call back to confluence only if `{macro.truncated}` is '`true`'. This will allow\n you to skip the callback if it's not needed. This would be useful for macros that don't\n contain sensitive data of an unpredictable size.\n
\n \n {\n \"url\": \"/render-macro?pageId={page.id}&pageVersion={page.version}¯oId={macro.id}\"\n }\n
\n \n AP.require(\"request\", function(request) {\n var pageId = getUrlParameter(\"pageId\");\n var pageVersion = getUrlParameter(\"pageVersion\");\n var macroId = getUrlParameter(\"macroId\");\n request({\n url: \"/rest/api/content/\" + pageId +\n \"/history/\" + pageVersion +\n \"/macro/id/\" + macroId,\n success: function(response) {\n var macro = JSON.parse(response);\n process(macro.body);\n }\n });\n });\n
\n - `macro.id`: The id of the macro
\n - `macro.body`: The macro body, truncated to 128 characters
\n - `macro.truncated`: True if the macro body was truncated, false of not
\n - `page.id`: The page ID, e.g. `1376295`
\n - `page.title`: The page title, e.g. `My Page`
\n - `page.type`: The page type, e.g. `page`
\n - `page.version`: The page version, e.g. `6`
\n - `space.id`: The space ID, e.g. `65537`
\n - `space.key`: The space key, e.g. `AC`
\n - `user.id`: The user ID, e.g. `admin` (deprecated in GDPR mode)
\n - `user.key`: The user key, e.g. `ff80808143087d180143087d3a910004` (deprecated in GDPR mode)
\n - `output.type`: The output type, e.g. `display` or `preview`
\n
\n \n {\n \"url\": \"/macro-renderer?body={macro.body}&space_id={space.id}&page_id={page.id}\"\n }\n
\n - If you know your macro contains a body that will often exceed the 128 character threshold\n (or is known to contain sensitive data), then you can include the `{macro.id}` parameter and\n use the Confluence REST api to call back to collect the body.
\n - If you want, you can include, `{macro.body}`, `{macro.id}`, and `{macro.truncated}`. This way\n your plugin can call back to confluence only if `{macro.truncated}` is '`true`'. This will allow\n you to skip the callback if it's not needed. This would be useful for macros that don't\n contain sensitive data of an unpredictable size.\n
\n \n {\n \"url\": \"/render-macro?pageId={page.id}&pageVersion={page.version}¯oId={macro.id}\"\n }\n
\n \n AP.require(\"request\", function(request) {\n var pageId = getUrlParameter(\"pageId\");\n var pageVersion = getUrlParameter(\"pageVersion\");\n var macroId = getUrlParameter(\"macroId\");\n request({\n url: \"/rest/api/content/\" + pageId +\n \"/history/\" + pageVersion +\n \"/macro/id/\" + macroId,\n success: function(response) {\n var macro = JSON.parse(response);\n process(macro.body);\n }\n });\n });\n
\n - `macro.id`: The id of the macro
\n - `macro.body`: The macro body, truncated to 128 characters
\n - `macro.truncated`: True if the macro body was truncated, false of not
\n - `page.id`: The page ID, e.g. `1376295`
\n - `page.title`: The page title, e.g. `My Page`
\n - `page.type`: The page type, e.g. `page`
\n - `page.version`: The page version, e.g. `6`
\n - `space.id`: The space ID, e.g. `65537`
\n - `space.key`: The space key, e.g. `AC`
\n - `user.id`: The user ID, e.g. `admin` (deprecated in GDPR mode)
\n - `user.key`: The user key, e.g. `ff80808143087d180143087d3a910004` (deprecated in GDPR mode)
\n - `output.type`: The output type, e.g. `display` or `preview`
\n \n
\n\n",
"defaultValue": "false",
"description": "\n\nReturns whether the URL should be cacheable. Cacheable URLs are taken directly from the add-on descriptor, and\n lack all additional query parameters:\n \n
\n\n"
},
"url": {
"format": "uri-template",
"type": "string",
"fieldDescription": "\n\nThe URL of the add-on endpoint which will be served as a hidden iframe inside the property panel\n\n",
"description": "\n\nThe URL of the add-on endpoint which will be served as a hidden iframe inside the property panel\n\n"
}
},
"required": [
"url"
],
"shortClassName": "macroPropertyPanelBean",
"type": "object",
"title": "Macro Property Panel",
"description": "\n\nDefining a Macro Property panel allows you to add a hidden iframe to your macro's\n property panel. The iframe is loaded as soon as the property panel is opened.\n \n
\n\n",
"defaultValue": "false",
"description": "\n\nReturns whether the URL should be cacheable. Cacheable URLs are taken directly from the add-on descriptor, and\n lack all additional query parameters:\n \n
\n\n"
},
"categories": {
"items": {
"maxLength": 100,
"type": "string"
},
"type": "array",
"fieldDescription": "\n\nThe categories the macro should appear in. A macro with no category will show up in the default 'All' category.\n \n
\n\n",
"description": "\n\nThe categories the macro should appear in. A macro with no category will show up in the default 'All' category.\n \n
\n\n"
},
"parameters": {
"items": {
"properties": {
"identifier": {
"pattern": "[-_a-z0-9\\.]+",
"type": "string",
"fieldDescription": "\n\nA unique identifier for the parameter.\n It must only contain lowercase alphanumeric characters, dashes, underscores, dots and must not contain any spaces.\n This identifier will be used in the query parameters of the add-on URL.\n\n",
"description": "\n\nA unique identifier for the parameter.\n It must only contain lowercase alphanumeric characters, dashes, underscores, dots and must not contain any spaces.\n This identifier will be used in the query parameters of the add-on URL.\n\n"
},
"aliases": {
"items": {
"maxLength": 100,
"type": "string"
},
"type": "array",
"fieldDescription": "\n\nAliases for the macro parameter.\n\n",
"description": "\n\nAliases for the macro parameter.\n\n"
},
"hidden": {
"type": "boolean",
"fieldDescription": "\n\nDetermines if the parameter will be displayed in the macro editor.\n\n",
"defaultValue": "false",
"description": "\n\nDetermines if the parameter will be displayed in the macro editor.\n\n"
},
"indexing": {
"$ref": "#/definitions/indexing",
"fieldDescription": "\n\nDefines how this macro parameter will be indexed\n\n",
"description": "\n\nDefines how this macro parameter will be indexed\n\n"
},
"defaultValue": {
"maxLength": 1000,
"type": "string",
"fieldDescription": "\n\nThe default value for the parameter.\n\n",
"description": "\n\nThe default value for the parameter.\n\n"
},
"values": {
"items": {
"maxLength": 1000,
"type": "string"
},
"type": "array",
"fieldDescription": "\n\nDescribes the ``enum`` values - only applicable for enum typed parameters.\n\n",
"description": "\n\nDescribes the ``enum`` values - only applicable for enum typed parameters.\n\n"
},
"name": {
"$ref": "#/definitions/i18nProperty",
"fieldDescription": "\n\nThe human readable name of the parameter which will be displayed in the UI.\n\n",
"description": "\n\nThe human readable name of the parameter which will be displayed in the UI.\n\n"
},
"multiple": {
"type": "boolean",
"fieldDescription": "\n\nWhether it takes multiple values.\n\n",
"defaultValue": "false",
"description": "\n\nWhether it takes multiple values.\n\n"
},
"description": {
"$ref": "#/definitions/i18nProperty",
"fieldDescription": "\n\nThe description of the parameter\n\n",
"description": "\n\nThe description of the parameter\n\n"
},
"type": {
"enum": [
"attachment",
"ATTACHMENT",
"boolean",
"BOOLEAN",
"confluence-content",
"CONFLUENCE-CONTENT",
"enum",
"ENUM",
"int",
"INT",
"label",
"LABEL",
"spacekey",
"SPACEKEY",
"string",
"STRING",
"url",
"URL",
"username",
"USERNAME"
],
"type": "string",
"fieldDescription": "\n\nThe type of parameter.\n
\n\n \n \"dynamicContentMacros\": [{\n ...\n \"url\": \"/render-map?pageTitle={page.title}&viewChoice={view}\",\n ...\n }]\n Example
\n\n\n\n {\n \"dynamicContentMacros\": {\n \"renderModes\": {},\n \"url\": \"/my-macro\",\n \"categories\": [],\n \"outputType\": \"block\",\n \"bodyType\": \"none\",\n \"aliases\": [],\n \"parameters\": [\n {\n \"identifier\": \"view\",\n \"name\": {\n \"value\": \"Map View\"\n },\n \"description\": {\n \"value\": \"Allows switching between view types\"\n },\n \"type\": \"enum\",\n \"required\": true,\n \"multiple\": false,\n \"defaultValue\": \"Map\",\n \"values\": [\n \"Map\",\n \"Satellite\"\n ],\n \"hidden\": false,\n \"indexing\": {\n \"enabled\": true\n }\n }\n ],\n \"name\": {\n \"value\": \"My macro with placeholder\"\n },\n \"key\": \"my-macro-key\"\n }\n }\n\n\n"
},
"type": "array",
"fieldDescription": "\n\nThe list of parameter input fields that will be displayed.\n\n",
"description": "\n\nThe list of parameter input fields that will be displayed.\n\n"
},
"key": {
"pattern": "^[a-zA-Z0-9-]+$",
"maxLength": 100,
"type": "string",
"fieldDescription": "\n\nA key to identify the macro. Keys must only contain alphanumeric characters and dashes, and must be globally unique. Prefixing it with the name of your add-on is the best way to ensure this.",
"description": "\n\nA key to identify the macro. Keys must only contain alphanumeric characters and dashes, and must be globally unique. Prefixing it with the name of your add-on is the best way to ensure this."
},
"height": {
"maxLength": 10,
"type": "string",
"fieldDescription": "\n\nThe preferred height of the macro content, e.g. ``10px``,``100%``.\n\n",
"description": "\n\nThe preferred height of the macro content, e.g. ``10px``,``100%``.\n\n"
}
},
"required": [
"name",
"url",
"key"
],
"additionalProperties": true,
"shortClassName": "dynamicContentMacroModuleBean",
"type": "object",
"title": "Dynamic Content Macro",
"description": "\n\nA Confluence macro that loads remote content as an iframe. Dynamic Content Macros render content on every page\n request and are suitable for add-ons that need to display content that changes over time, that calls for dynamic\n interaction, or that is specific to the authenticated user.\n // app.js\n\n httpClient.post(\n { url: '/rest/api/contentbody/convert/view?expand=webresource.uris.js,webresource.uris.css,webresource.superbatch.uris.js,webresource.superbatch.uris.css',\n json: {...} }\n ).then(renderResponse -> {\n var wr = renderResponse.body.webresource;\n var jsDependencies = wr.superbatch.uris.js.concat(wr.uris.js || []);\n var cssDependencies = wr.superbatch.uris.css.concat(wr.uris.css || []);\n res.render(\"template\", {\n \"body\": renderResponse.body.value,\n \"css\": cssDependencies,\n \"js\": jsDependencies\n });\n });\n\n // template.hbs\n\n {{#each css}}\n <link rel=\"stylesheet\" href=\"{{this}}\" media=\"all\" />\n {{/each}}\n {{#each js}}\n <script src=\"{{this}}\" type=\"text/javascript\" />\n {{/each}}\n \n
\n\n \n
\n\n",
"defaultValue": "storage",
"description": "\n\nDefines the content body type of this custom content.\n Currently supported content body types are:\n storage: This is Confluence's default storage representation which can be rendered using the Content Body Conversion APIraw: This representation is used for storing raw data in the body that is not storage format, this format is opaque to Confluence\n
\n\n"
},
"supportedChildTypes": {
"items": {
"maxLength": 100,
"type": "string"
},
"type": "array",
"fieldDescription": "\n\nDefines types that can be contained in this custom content.storage: This is Confluence's default storage representation which can be rendered using the Content Body Conversion APIraw: This representation is used for storing raw data in the body that is not storage format, this format is opaque to Confluence
\n Currently supported content types:\n \n
\n\n",
"description": "\n\nDefines types that can be contained in this custom content.attachment: This custom content can contain attachment.comment: This custom content can contain comment.
\n Please refer to The content type key\n for how to construct the content type key.\n
\n Currently supported content types:\n \n
\n\n"
},
"supportedSpacePermissions": {
"items": {
"maxLength": 100,
"type": "string"
},
"type": "array",
"fieldDescription": "\n\nDefines the space permissions that this custom content supports.\n Allowable values are : attachment: This custom content can contain attachment.comment: This custom content can contain comment.
\n Please refer to The content type key\n for how to construct the content type key.\n read, create and delete.\n It is required that these permissions be granted through the\n space permissions UI in order to perform the given operation.\n read, create and delete.\n It is required that these permissions be granted through the\n space permissions UI in order to perform the given operation.\n
\n The supported content types are:\n \n
\n\n",
"description": "\n\nDefines types that this custom content can be contained in.space: This custom content can be contained in a space.page: This custom content can be contained in a page.blogpost: This custom content can be contained in a blog post.
\n Any other custom content type defined in the same app.
\n Please refer to The content type key\n for how to construct the content type key.\n
\n The supported content types are:\n \n
\n\n"
}
},
"required": [
"supportedContainerTypes"
],
"shortClassName": "customContentAPISupportBean",
"type": "object",
"title": "Custom Content API Support",
"description": "\n\nThis property allows you to specify the container types your custom content can appear in, and its supported child content types.\n It also allows you to enable indexing of your custom content.\n\n\n\n {\n \"bodyType\": \"storage\",\n \"supportedContainerTypes\": [\n \"space\",\n \"page\"\n ],\n \"supportedChildTypes\": [\n \"attachment\",\n \"comment\"\n ],\n \"supportedSpacePermissions\": [],\n \"preventDuplicateTitle\": false,\n \"indexing\": {\n \"enabled\": true\n }\n }\n\n\n\n\n space: This custom content can be contained in a space.page: This custom content can be contained in a page.blogpost: This custom content can be contained in a blog post.
\n Any other custom content type defined in the same app.
\n Please refer to The content type key\n for how to construct the content type key.\n supportedContainerTypes and supportedChildTypes fields.\n There are 2 categories of content type you can reference \\u2013 built-in content and custom content.Built-in content types example
\n The following snippet shows the content type we're defining can:\n \n
\n\n {\n \"bodyType\": \"storage\",\n \"supportedContainerTypes\": [\n \"space\",\n \"page\"\n ],\n \"supportedChildTypes\": [\n \"attachment\",\n \"comment\"\n ],\n \"supportedSpacePermissions\": [],\n \"preventDuplicateTitle\": false,\n \"indexing\": {\n \"enabled\": true\n }\n }\n\n\n\n\n\n space or a pagecomment or a child attachmentCustom content example
\n The following snippet shows the content type we're defining can:\n \n
\n\n {\n \"bodyType\": \"storage\",\n \"supportedContainerTypes\": [\n \"ac:my-first-addon:type2\",\n \"ac:my-first-addon:type1\"\n ],\n \"supportedChildTypes\": [\n \"ac:my-second-addon:type1\",\n \"ac:my-second-addon:type2\"\n ],\n \"supportedSpacePermissions\": [],\n \"preventDuplicateTitle\": false,\n \"indexing\": {\n \"enabled\": true\n }\n }\n\n\n\n\n type1 or type2, defined in the app with the key my-first-addontype1 or type2, defined in the app with the key my-second-addonRaw body type custom content example
\n You can define custom content to support a content body with a type of raw.
\n This is useful when you want to store, for example, stringified JSON to the content.\n\n {\n \"bodyType\": \"raw\",\n \"supportedContainerTypes\": [\n \"space\"\n ],\n \"supportedChildTypes\": [],\n \"supportedSpacePermissions\": [],\n \"preventDuplicateTitle\": false,\n \"indexing\": {\n \"enabled\": true\n }\n }\n\n\n\n
"
},
"vendor": {
"properties": {
"name": {
"maxLength": 100,
"type": "string",
"fieldDescription": "\n\nThe name of the plugin vendor.\n Supply your name or the name of the company you work for.\n\n",
"description": "\n\nThe name of the plugin vendor.\n Supply your name or the name of the company you work for.\n\n"
},
"url": {
"pattern": "^((https|http):\\/\\/.+|[^:]+|)$",
"maxLength": 200,
"format": "uri",
"type": "string",
"fieldDescription": "\n\nThe url for the vendor's website\n\n",
"description": "\n\nThe url for the vendor's website\n\n"
}
},
"shortClassName": "vendorBean",
"type": "object",
"title": "Plugin Vendor",
"description": "\n\nGives basic information about the plugin vendor.\n\n \n {\n \"title\": \"My title\",\n \"space\": {\"key\": \"DS\"},\n \"type\": \"ac:add-on-key:module-key\",\n \"body\": {\n \"raw\": {\n \"value\": \"{\\\"field\\\": \\\"value\\\"}\",\n \"representation\": \"raw\"\n }\n }\n }\n Example
\n\n\n\n {\n \"vendor\": {\n \"name\": \"Atlassian\",\n \"url\": \"http://www.atlassian.com\"\n }\n }\n\n\n"
},
"dataResidency": {
"properties": {
"realmPersistenceDays": {
"maximum": 30,
"minimum": 0,
"exclusiveMaximum": false,
"exclusiveMinimum": false,
"type": "integer"
}
},
"shortClassName": "dataResidencyBean",
"type": "object",
"title": "App Data Residency",
"description": "\n\nGives apps data residency information on realm persistence.\n\n Example
\n\n\n\n {\n \"dataResidency\": {\n \"realmPersistenceDays\": 9\n }\n }\n\n\n"
}
}
}