Blueprint

The human-readable default value. This will be used if no translation exists. Only the following HTML tags are supported: b, i, strong, em, and code.

The localization key for the human-readable value. Translations for the keys are defined at the top level of the add-on descriptor.

The URL of the add-on resource that provides the blueprint template content. This URL has to be relative to the add-on base URL.

Defines the add-on server endpoint that provides the JSON objects used for substituting variables in the blueprint template.

For more information on defining variables in blueprint templates, check out the examples in Blueprint Template Context.

Defines the context of the blueprint template.

1
2
3
4
5
6
7
8
9

{
  "template": {
    "url": "/blueprints/blueprint.xml",
    "blueprintContext": {
      "url": "/blueprints/context"
    }
  }
}

A blueprint template is static - the same template will produce the same Confluence page. To produce Confluence pages dynamically (to create a different page for a different user), the template needs to use variable substitution to produce the dynamic parts. Variable substitution requires the add-on to provide data for substitution. Collectively, this data is called the context for substitution.

The context is made up of a list of objects which are retrieved from the context url specified by the blueprint context url field in this module descriptor. See Properties for the definition of each field in the context.

Substituting dynamic variables in a blueprint

Let's say we have a blueprint template module /blueprints/blueprint.xml:

1
2
3
4
5

<h2 id="static1">Hello Blueprint</h2>
 <h2 id="custom1"><at:var at:name="ContentPageTitle"/></h2>
 <h2 id="custom2"><at:var at:name="custom-key1"/></h2>
 <h2 id="custom3"><at:var at:rawxhtml="true" at:name="custom-key2"/></h2>
 

And an add-on server resource /blueprints/context which returns this JSON response as the context:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

[
  {
    "identifier": "ContentPageTitle",
    "value": "Unique Page Title 1",
    "representation": "plain"
  },
  {
    "identifier": "custom-key1",
    "value": "custom value 1",
    "representation": "plain"
  },
  {
    "identifier": "custom-key2",
    "value": "<ac:structured-macro ac:name=\"cheese\" ac:schema-version=\"1\"/> ",
    "representation": "storage"
  }
]

During blueprint page creation, Confluence sends a POST request to /blueprints/context to retrieve the context. The context retrieved is parsed as a JSON array of objects and used in the substitute of the variables in the blueprint template above (custom-key1, custom-key2 are the variables).

The final, variable substituted, storage format will look like this:

1
2
3
4
5

<h2>Hello Blueprint</h2>
 <h2>Unique Page Title 1</h2>
 <h2>custom value 1</h2>
 <h2><ac:structured-macro ac:name="cheese" ac:schema-version="1" /></h2>
 

This is then used as the Confluence page to be saved to the database and displayed to the user according to the createResult field of the blueprint module (see Blueprint Template Module).

An error message appears in the Content Create Dialog if Confluence has any problems accessing the blueprint template or context URL (for example if your add-on server failed to respond in 10 seconds or the JSON returned is invalid). A detailed error and/or stacktrace may be accessible by Atlassian support, but the end user will see an error like the one shown here:

Backwards compatibility of the identifier field

Add-ons wanting to retain backwards compatibility for their blueprint templates should ensure that any variables used in a template are always returned in the context url, even if a new version of the blueprint template no longer uses it (for example if users are relying on an old or customized version of the template). This ensures that the template continues to function when the add-on updates the template.

The human-readable default value. This will be used if no translation exists. Only the following HTML tags are supported: b, i, strong, em, and code.

The localization key for the human-readable value. Translations for the keys are defined at the top level of the add-on descriptor.

The URL of the icon. Your icon needs to be hosted remotely at a web-accessible location. You can specify the URL as an absolute URL or relative to the add-on's base URL.

The height in pixels of the icon image.

The width in pixels of the icon image.