The {increment-metadata} macro increments a numeric metadata value. 

The metadata value to be incremented can be a simple whole number value (e.g. 3) or a composite number (e.g. 1.0 or 1.0.0).

The increment can be specified or default to a simple increment of the last element of the metadata value.

A non-numerical character can be used to separate the numbers e.g.1‡2-4.

The macro can be be used to increment a metadata value to support custom versions:

  • simple (e.g. VERSIONNUMBER)
  • composite versioning (e.g. MAJOR.MINOR  or MAJOR.MINOR.PATCH)

increment-metadata macro is available from v6.11+

Where to use it?

One or more {increment-metadata} macros can be put in a {trigger} macro.

The metadata value must have been already set e.g. at page creation using the {set-metadata} macro.


metadata name(tick)none

The metadata item.

The metadata item value is numeric and can be:

  •  simple (e.g. whole number)
  • composite (eg 2.1 or 2.1.1)

A non-numerical character can be used to separate "-" the metadata numeric values e.g. 1__2-4. The separator can be any non-numeric character.

A suffix may be used after the last numeric element e.g. 2.1.1-BETA. This can be any set of characters (including letters, symbols, and numbers).

increment last numeric element by 1

The increment expression, if specified, is a numeric expression to increment element(s) of the numeric value.

If no increment value is specified the last numeric element of the current metadata value is incremented by 1.

The expression can be:

  • a simple integer number (e.g. 2)
  • composite number (e.g. 1.2  or 1.2.3)

A composite number cannot be more than 3 numeric elements e.g. is not supported.

When defining the increment expression the format MUST match the metadata item value format including any separators and suffix identifiers.

  • increment or a change for non-numeric elements is not supported.
  • incrementing a single higher-order element of a composite numeric value will reset any lower-order elements to zero e.g. a metadata value of 1.2.3 with an increment expression of 1.0.0 will update the value to 2.0.0.

Increment expression examples

If the expression increments a single higher-order element of a composite numeric value the lower order element values are updated to zero

  • e.g. incrementing the metadata value 1.1.4 using the increment expression 1.0.0 will result in the value being set to 2.0.0.

If the expression includes increments for each element of a composite numeric value each element is incremented by the appropriate value

  • e.g. incrementing 1.1.4 using the increment expression 1.1.1 will result in the value being set to 2.2.5.

The increment expression format including any separator characters and the suffix identifier MUST match the metadata item value being incremented. 

Metadata ValueIncrement ExpressionResulting Value

An <empty> increment expression simply includes the name of the metadata value to increment.


Simple Increment Example

{workflow:name=Simple Increment Metadata}

The example shown uses the increment-metadata macro to support the custom versioning of a page using a simple numeric metadata value.

The metadata name and initial value are set on the creation of the page using a trigger macro and the set-metadata action macro.


A version change will occur:

  • on a state change to the Approved state.

Note that the metadata is associated with the page. At any one point in time, the metadata value is the same in any workflow state.

In our example

  •  the my-version metadata value for a user viewing the content currently in a draft state (if that content has been previously published), is the value set by the increment-metadata action on the last transition to the workflow final state, Approved. It will be the same metadata value seen for the content by a view-only user when viewing the final state content

The Confluence version metadata value may however be different if the page has been updated or edited in one of the workflow states.

In the simple increment example, this can be seen if you use a get-metadata macro to display the metadata version and a second get-metadata macro to display the Confluence version on a page.

Add the page-activity macro to the page to see the workflow activity

  • there has been only one approval event
  • the metadata my-version value has only been incremented once
  • the my-version value is 1

The Confluence version value is currently 9. This reflects that there have been multiple edits on the content.

Other examples

(info) A metadata value is linked to a page, not a page version. Viewing a previous page version will show the current metadata value.

See also

Workflow Authoring Guide: