User Macro Parameters

User macro parameters (or Macro Input Parameter) allow for dynamic content customization, enabling users to tailor macro behavior through the Confluence interface:

Defined when the macro is created or edited on Admin page.
Edited with input fields that will be displayed in the macro edit interface when rendering.
Access in template through velocity variable $<parameterKey>.
Note that variable name could be overwritten in the template using #set directive.

User Parameters

Type	Confluence Entity	Multiple	Default value	Options
String
Int
Boolean
Enum
Confluence Content
Space Key
Username
Attachment
Label
Url

Working with empty values

It's good practice to validate macro parameters, as you can't be sure a user has provided them. If a parameter is missing, your macro can assign a fallback value to ensure it runs correctly.

However, if your macro parameter is defined with a default value, the system will automatically apply that default if the user leaves the field empty. In that case, an explicit #if check within the macro body for that specific parameter is not necessary.

The following code demonstrates manually setting defaults for parameters that might not have a pre-defined default value.

#set($pageId = $parameters.pageId)
#set($itemCount = $parameters.ItemCount)
#set($charLimit = $parameters.CharLimit)

## Use the current space if a specific scope isn't provided.
#if (!$pageId)
  #set($pageId = $page.id)
#end

## Set a default item count if none is specified.
#if (!$itemCount)
  #set($itemCount = 10)
#end

## Establish a default character limit for the preview if it's not set.
#if (!$charLimit)
  #set($charLimit = 80)
#end

Parameters with Multiple values

Returned values in the render output will be a string or a number for the INT type. For parameters allowing multiple selections, the selected values are returned as a comma-separated string.

To process these values in a Velocity template, convert comma-separated parameters into an array:

#set ( $statesAsList = $StringUtils.split($parameters.States, ",") )
#foreach ( $item in $statesAsList )
  $StringUtils.trim($statesAsList[$foreach.index]))
#end

Parameters for Confluence entity values

Allow to integrate directly with Confluence entities.

Attachment
Autocomplete search for attachment filenames.
Confluence Content
Autocomplete search for pages and blog titles.
Label
Autocomplete field to select or search for page labels.
Space Key
Autocomplete field for searching space names.
Username
Autocomplete field for usernames and full names.

Parameters for custom values

Allow users to enter values directly in the macro configuration.

Boolean
Checkbox for selecting true/false.
Enum
Dropdown menu with predefined options.
Int
Numeric input field.
String
Single-line text input.
Url
Input field for entering a web address.

Properties

Field	Description	Allowed Values/Details
Name	Display name of the parameter, shown in the UI for users. Required field.	Any string value. 3-100 characters.
Key	Unique identifier for the parameter, used in templates. Required field.	Allowed: a-z, A-Z, digits, _ (underscore). Must not start with a digit. Auto-generated if not provided. 3-100 characters.
Description	Brief description of the parameter’s purpose, shown in the UI. Required field.	Any string value. Max length 500 characters.
Type	Defines the type of input expected for the parameter. Required field.	`string` `int boolean` `enum` `attachment` `username` `spacekey` `confluence-content` `label` `url`
Required	Indicates whether the parameter must have a value.	`true` or `false`
Hidden	Hides the parameter from the user interface but allows server access.	`true` or `false`
Multiple	Determines if multiple values can be selected.	`true` or `false`
Indexing	Indicates whether the parameter should be indexed for Confluence site search.	`{"enabled": true}` by default
Default Value	Predefined value that populates the parameter if the user doesn’t provide one.	Based on the parameter type (string or integer). Max length 1000 characters.
Values	List of options for enum.	A list of predefined values as strings.

{"timestamp":1792799681291,"msg":"A unknown Exception Occurred","errorMsg":"The provided AtlassianHostUser did not specify a user to act as.","code":"500"}

Define parameters

There are two ways to define parameters on the User Macro admin page:

Manual Creation Use the + Add User Parameter button to define parameters through the interface.
Automatic Conversion Paste a template with parameters into the editor and use the Convert feature.

Manually Through the Interface

Click the + Add User Parameter button in the Variables menu.
Configure the parameter and its properties.
- Validation is applied to ensure the correctness of fields Name, Key, and Description.
- During creation, the key value can be edited.
- The key is autogenerated following Atlassian's rules:
  - It can contain only alphanumeric characters and underscores.
  - It cannot start with a number.
Click the Add button to save the parameter in memory. To permanently add this parameter to the macro, the macro must be saved. Press CTRL+S to save it or Save button to save and escape.

Auto-convert with Code Editor

During the migration from Data Center macros to Cloud, user parameters can be added to the macro automatically using the auto-convert functionality in the code editor. To do this, copy and paste the template with the defined parameters into the editor input, then click Convert & Save.

Screen Recording 2026-05-05 at 15.52.26.gif

The parameter will appear in the Variables menu, and the code will be updated to remove deprecated syntax. Access to the parameters will continue to work as before through the key variable.

Parameters edit & preview

Parameters can be edited, except for the keyproperty. To edit a defined parameter, click the 🖊️ button against the parameter name.