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
"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
{
  "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
string
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
i18n Property
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
{
  "value": "My text"
}

Properties

value
Type
string
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
string
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
string
Allowed values
  • attachment
  • ATTACHMENT
  • boolean
  • BOOLEAN
  • confluence-content
  • CONFLUENCE-CONTENT
  • enum
  • ENUM
  • int
  • INT
  • label
  • LABEL
  • spacekey
  • SPACEKEY
  • string
  • STRING
  • url
  • URL
  • username
  • USERNAME
    • Required
    Yes
    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
    [string, ...]
    Description

    Aliases for the macro parameter.

    defaultValue

    Type
    string
    Max length
    1000
    Description

    The default value for the parameter.

    description

    Type
    i18n Property
    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
    {
  "value": "My text"
}

    Properties

    value
    Type
    string
    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
    string
    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
    boolean
    Defaults to
    false
    Description

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

    indexing

    Type
    Macro Parameter Indexing
    Description

    Defines how this macro parameter will be indexed

    Defines how this macro parameter will be indexed for site search

    1
2
3
    {
  "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
    boolean
    Description

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

    multiple

    Type
    boolean
    Defaults to
    false
    Description

    Whether it takes multiple values.

    required

    Type
    boolean
    Defaults to
    false
    Description

    Whether it is a required parameter.

    values

    Type
    [string, ...]
    Description

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