Prefix the title with an automatically incremented identifier.

Audience: Documentation Architect, Template Author

For some document types there is a natural tendency to provide a unique identifier. This include documents that specify requirements or issues on an issue tracker.

To administrate these values by hand is a bit cumbersome. Therefore the projectdoc Toolbox provides some support to manage identifiers and add them to the title of generated documents.

Use Cases in Action

The following screencasts show typical uses cases using the Auto Increment Feature to place a unique ID in the title of a projectdoc document.

Create Requirements with Auto ID

Shows how to configure and use Auto IDs for requirement documents.

Create_Requirements.mp4

Customize the ID Prefix

Change the ID Prefix before creating your first Requirement to REQ-Component1 (instead of the default ID).

Change_ ID_ Prefix.mp4

Skip some Numbers

How to skip some numbers using the Confluence-REST-API (or change the ID Prefix after pages have been created).

Skip_Some_ Numbers.mp4

In this video we are using the free Confluence REST API Browser.

While viewing the "Page Information" (see image below) the PageID can be copied from the URL. This ID will be needed to use the REST-API.

Configuration

The space property named Doctype Auto ID Pattern controls for which doctype auto-increments for IDs is enabled.

Template Variable

The blueprint context is provided with the Auto Identifier (projectdoc.doctype.common.autoIdentifier) variable that contains the generated identifier.

Artificial Property

The projectdoc Toolbox generates an artificial property named Auto ID that contains the generated identifier.

Sequences

The sequences are stored as content properties with the parent page. This makes the generation process quick, even if there are more than a few hundred siblings.

Please note that sequences are not incremented atomically. In case of a sequence clash, a single identifier is used twice. These clashes need to be resolved manually.

If you need to adjust the value, please use the REST API for content properties.

/rest/api/content/{id}/property/{key}

{
  "value": "ID-10010-00010",
  "version": {
    "number": 2,
    "minorEdit": false
  }
}

A sequence id is compared by splitting it into its parts. Parts are delimited by the dash ('-') character. Each part which represents an integer is compared as a number. Non-numbers are considered strings and are compared lexicographically. Shorter strings that are prefixes of other strings are considered smaller.

Please note that the natural sort order of titles in Confluence is not changed. So although the Auto Increment service understands that REQ-COMP1-123 is larger than REQ-COMP1-23, the natural sort order of documents being displayed in a list, sorted by the title will still be REQ-COMP1-23, REQ-COMP1-123. To compensate this, you could add leading zeros: REQ-COMP1-00123, REQ-COMP1-00023.

Resources

Auto Increment: A feature of the projectdoc Toolbox to prepend a unique identifier to the title of a page.
Doctype Auto ID Pattern: Specifies the pattern for auto increments for a given doctype.
Auto Identifier: A template variable for an auto-generated identifier.
Auto ID: The automatically generated identifier for a document. The services needs to be configured per doctype with a space property.

Auto Increment in Title