---
title: "increment-metadata macro"
canonical: "https://support.appfire.com/space/CDML/650250264/increment-metadata%20macro"
format: markdown
---
> Macro (aura-html)


## Overview

> Macro (excerpt)
> 
> Increment a metadata value to support custom versions (available from v6.11+)

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 <span style="color: #172b4d">be specified or default to a simple increment of the last element of the metadata value.</span>

<span style="color: #172b4d">A non-numerical character can be used to separate the numbers e.g.1‡2-4.</span>

For example, the macro is used to increment a metadata value for a custom version:

- <span style="color: #172b4d">simple (e.g. </span>`VERSIONNUMBER`<span style="color: #172b4d">)</span>
- <span style="color: #172b4d">composite versioning (e.g. </span>`MAJOR.MINOR`<span style="color: #172b4d">  or </span>`MAJOR.MINOR.PATCH)`

> 📝 `increment-metadata` macro is available from [v6.11+](https://appfire.atlassian.net/wiki/spaces/CDML/pages/650248713)

## Where to use it?

One or more `increment-metadata` macros can be put in a [trigger macro](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649859133).

The metadata value <span style="color: #172b4d">must have been already set e.g. at page creation </span>using the [set-metadata](https://appfire.atlassian.net/wiki/spaces/CDML/pages/650251172) macro.

## Parameters

| **Parameter** | **Required** | **Default** | **Notes** |
| --- | --- | --- | --- |
| metadata name | :check_mark: | *none* | The metadata item. The metadata item value is numeric and can be:<br>- simple (e.g. whole number)
- composite (eg 2.1 or 2.1.1)<br><span style="color: #172b4d">A non-numerical character can be used to separate "</span><span style="color: #172b4d">**-**</span><span style="color: #172b4d">" the metadata numeric values e.g. 1__2-4. The separator can be any non-numeric character.</span><br><span style="color: #172b4d">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).</span> |
| `increment` |  | <span style="color: #172b4d">*increment last numeric element by 1*</span> | <span style="color: #172b4d">The increment expression, if specified, is a numeric expression to increment element(s) of the numeric value. </span><br><span style="color: #172b4d">If no increment value is specified the last numeric element of the current metadata value is incremented by 1.</span><br><span style="color: #172b4d">The expression can be:</span><br>- <span style="color: #172b4d">a simple integer number (e.g. </span>`2`<span style="color: #172b4d">)</span>
- <span style="color: #172b4d">composite number (e.g. </span>`1.2`<span style="color: #172b4d">  or </span>`1.2.3`)<br>A composite number cannot be more than 3 numeric elements e.g. 1.2.3.4 is not supported.<br>When defining the increment expression the format **MUST** match the metadata item value format including any separators and suffix identifiers.<br>- 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

<span style="color: #172b4d">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</span>

- <span style="color: #172b4d">incrementing the metadata value 1.1.4 using the increment expression 1.0.0 results in the value being set to 2.0.0</span>

<span style="color: #172b4d">If the expression includes increments for each element of a composite numeric value, each element is incremented by the appropriate value. For example</span>

- <span style="color: #172b4d">incrementing 1.1.4 using the increment expression 1.1.1 results in the value being set to 2.2.5</span>

<span style="color: #172b4d">The increment expression format including any separator characters and the suffix identifier </span><span style="color: #172b4d">**MUST**</span><span style="color: #172b4d"> match the metadata item value being incremented. </span>

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

```plaintext
{increment-metadata:my-version}
```

###   
Simple Increment Example

```plaintext
{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](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649859133)** macro and the **[set-metadata](https://appfire.atlassian.net/wiki/spaces/CDML/pages/650251172)** 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](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649826804)** macro to display the metadata `my-version`
- a second **[get-metadata](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649826804)** macro to display the Confluence `version` on a page

![image](media://79c59c8f-d24c-4960-bed4-568c9be63975)

The [page-activity macro](https://appfire.atlassian.net/wiki/spaces/CDML/pages/650315245) (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-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 but only one version has been approved in the workflow.

## Setting metadata when using a content label filter workflow

> Macro (excerpt-include)



## Other examples

> 📝 A metadata value is linked to a page not a page version. Viewing a previous page version shows the current metadata value.

> Macro (contentbylabel)


## See also

[Workflow Authoring Guide](https://appfire.atlassian.net/wiki/spaces/CDML/pages/648611901):

- [Notifications](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649957056)
- [Events](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649759655)
- [Triggers](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649563178)
- [Actions](https://appfire.atlassian.net/wiki/spaces/CDML/pages/649858941)