Atlassian uses cookies to improve your browsing experience, perform analytics and research, and conduct advertising. Accept all cookies to indicate that you agree to our use of cookies on your device. Atlassian cookies and tracking notice, (opens new window)
increment-metadata macro
Overview
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.
For example, the macro is used to increment a metadata value for a custom version:
simple (e.g.
VERSIONNUMBER)composite versioning (e.g.
MAJOR.MINORorMAJOR.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.
Parameters
Parameter | Required | Default | Notes |
|---|---|---|---|
metadata name | none | The metadata item. The metadata item value is numeric and can be:
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 composite number cannot be more than 3 numeric elements e.g. 1.2.3.4 is not supported. When defining the increment expression the format MUST match the metadata item value format including any separators and suffix identifiers.
|
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. For example
incrementing the metadata value 1.1.4 using the increment expression 1.0.0 results 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. For example
incrementing 1.1.4 using the increment expression 1.1.1 results 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 Value | Increment Expression | Resulting Value |
|---|---|---|
1 | <empty> | 2 |
1.0 | <empty> | 1.1 |
1.0 | 0.1 | 1.1 |
1.0 | 1.0 | 2.0 |
3.5.1 | <empty> | 3.5.2 |
3.5.1 | 0.0.1 | 3.5.2 |
3.5.1 | 0.2.0 | 3.7.0 |
3.5.1 | 0.2.1 | 3.7.2 |
3.5.1 | 1.0.0 | 4.0.0 |
3.5.1 | 1.1.1 | 4.6.2 |
3.5.1-Beta | 1.0.0-Beta | 4.0.0-Beta |
An <empty> increment expression only includes the name of the metadata value to increment.
{increment-metadata:my-version}
Simple Increment Example
{workflow:name=Simple Increment Metadata}
{state:Draft|submit=Review}
{state}
{state:Review|approved=Approved}
{approval:Review|assignable=true}
{state}
{state:Approved|final=true|submit=Draft}
{state}
{trigger:pagecreated}
{set-metadata:my-version}
0
{set-metadata}
{trigger}
{trigger:statechanged|state=Approved}
{increment-metadata:my-version}
{trigger}
{workflow}
This example 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.
{set-metadata:my-version}0{set-metadata}
A version change occurs on a state change to the Approved state using a trigger with the following action macro
{increment-metadata:my-version}
The metadata is associated with the page. At any one point in time, the metadata value will be 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 is 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 differ if the page has been updated or edited in one of the workflow states.
This occurs in the simple increment example, when using
one get-metadata macro to display the metadata
my-versiona second get-metadata macro to display the Confluence
versionon a page
The page-activity macro (or document activity macro) added to the page displays the workflow events and actions. In our example
there has been only one approval event
the metadata
my-versionvalue has only been incremented oncethe
my-versionvalue is 1
The Confluence version value is currently 9. This reflects that there have been multiple edits on the content but only one version has been approved in the workflow.
Setting metadata when using a content label filter workflow
Other examples
A metadata value is linked to a page not a page version. Viewing a previous page version shows the current metadata value.
-
Use metadata to increment a content version — Increment a composite version number for example, major.minor.patch metadata value each time a reviewer approves the content
-
Use metadata to increment composite major, minor, patch content version on an approval decision requiring a parameter — Use the increment-metadata
macroto increment the major, minor, and patch metadata values for a single approval using three triggers.
See also
Need support? Create a request with our support team.