Macro Input Parameter

Describes a parameter input field for a macro.

Any declared parameters must also be included in the URL value of the macro in order to serialise this value, for example, for a macro with a parameter view it should be added to the macro url as follows:

1
2
3
4
5
6
7

 "dynamicContentMacros": [{
   ...
   "url": "/render-map?pageTitle={page.title}&viewChoice={view}",
   ...
 }]

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
{
  "dynamicContentMacros": {
    "renderModes": {},
    "url": "/my-macro",
    "categories": [],
    "outputType": "block",
    "bodyType": "none",
    "aliases": [],
    "parameters": [
      {
        "identifier": "view",
        "name": {
          "value": "Map View"
        },
        "description": {
          "value": "Allows switching between view types"
        },
        "type": "enum",
        "required": true,
        "multiple": false,
        "defaultValue": "Map",
        "values": [
          "Map",
          "Satellite"
        ],
        "hidden": false,
        "indexing": {
          "enabled": true
        }
      }
    ],
    "name": {
      "value": "My macro with placeholder"
    },
    "key": "my-macro-key"
  }
}

Properties

identifier
Type
Required
Yes
Pattern
[-_a-z0-9\.]+
Description

A unique identifier for the parameter. It must only contain lowercase alphanumeric characters, dashes, underscores, dots and must not contain any spaces. This identifier will be used in the query parameters of the add-on URL.

name
Type
Required
Yes
Description

The human readable name of the parameter which will be displayed in the UI.

Represents a string that can be resolved via a localization properties file. You can use the same i18n Property key and value in multiple places if you like, but identical keys must have identical values.

Example

1
2
3
4
{
  "value": "My text"
}

Properties

value
Type
Max length
1500
Required
Yes
Description

The human-readable default value. This will be used if no translation exists. Only the following HTML tags are supported: b, i, strong, em, and code.

i18n
Type
Max length
300
Description

The localization key for the human-readable value. Translations for the keys are defined at the top level of the add-on descriptor.

type
Type
Required
Yes
Allowed values
  • attachment
  • ATTACHMENT
  • boolean
  • BOOLEAN
  • confluence-content
  • CONFLUENCE-CONTENT
  • enum
  • ENUM
  • int
  • INT
  • label
  • LABEL
  • spacekey
  • SPACEKEY
  • string
  • STRING
  • url
  • URL
  • username
  • USERNAME
Description

The type of parameter.

Currently the following parameter types are supported in the macro browser's UI:

* attachment: displays an autocomplete field for search on attachment filenames. * boolean: displays a check box. * confluence-content: displays an autocomplete field for search on page and blog titles. * enum: displays a select field. * spacekey: displays an autocomplete field for search on space names. * string: displays an input field (this is the default if unknown type). * 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.

aliases
Type
Description

Aliases for the macro parameter.

defaultValue
Type
Max length
1000
Description

The default value for the parameter.

description
Type
Description

The description of the parameter

Represents a string that can be resolved via a localization properties file. You can use the same i18n Property key and value in multiple places if you like, but identical keys must have identical values.

Example

1
2
3
4
{
  "value": "My text"
}

Properties

value
Type
Max length
1500
Required
Yes
Description

The human-readable default value. This will be used if no translation exists. Only the following HTML tags are supported: b, i, strong, em, and code.

i18n
Type
Max length
300
Description

The localization key for the human-readable value. Translations for the keys are defined at the top level of the add-on descriptor.

hidden
Type
Defaults to
false
Description

Determines if the parameter will be displayed in the macro editor.

indexing
Type
Description

Defines how this macro parameter will be indexed

Defines how this macro parameter will be indexed for site search

1
2
3
4
{
  "enabled": true
}

The macro parameter indexing property allows apps to hook into the mechanism by which Confluence populates its search index for site search. Each time macro is created or updated in Confluence, the value that is stored in the macro parameter will be added to the search index. 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 bodyType: none. The app can still provide meaningful search text for this content by storing the extracted information to the macro parameter. The data in this macro parameter will get indexed as is without any modification.

Properties

enabled
Type
Defaults to
false
Description

Defines whether this macro parameter should be indexed for site search.

multiple
Type
Defaults to
false
Description

Whether it takes multiple values.

required
Type
Defaults to
false
Description

Whether it is a required parameter.

values
Type
Description

Describes the enum values - only applicable for enum typed parameters.

Rate this page: