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
{
  "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
      }
    ],
    "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.

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.

    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.

    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.