Blueprint Template

Defines where the blueprint template is located and the context for variable substitution.

1
2
3
4
5
6
7
8
9
{
  "template": {
    "url": "/blueprints/blueprint.xml",
    "blueprintContext": {
      "url": "/blueprints/context"
    }
  }
}

Properties

url
Type
Format
uri
Required
Yes
Description

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.

blueprintContext
Type
Description

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: Blueprint context error

Backwards compatibility of the identifier field

A blueprint template containing variables may change as the add-on evolves over time. However, because end users can customize blueprint templates, it's possible for the customized version of the template to differ from the version in the add-on. This difference won't cause an error as long as the variables used in the template are still being returned as part of the context url.

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.

Properties

url
Type
Format
uri
Required
Yes
Description

A URL to which a POST request will be made during the rendering of the blueprint (see 'Example of the request POST body' below for an example of what will be POSTed to this resource). The response is then used for blueprint variable substitution, to enable blueprints to create pages that have dynamic content.

Expected response format

The expected response from the context URL is a JSON array of objects with certain fields:

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"
  }
]

The identifier field

The identifier field refers to the name attribute of the var element in a blueprint template. If the identifier is matched with a template variable, the value is used in the substitution. If a template contains a variable, but there is no matching identifier in the context, an error is generated. An identifier with no matching template variable is regarded as a no-op.

The identifier field for each context object must be unique. It is an error to have more than one context object with the same identifier, and it is undefined which will get picked during substitution.

Some identifier names are reserved for use with special meaning during substitution. They must have a representation field with the value plain. The list below describes the meaning of each existing reserved identifier.

Using reserved identifiers as part of your template is possible, but these identifiers may change in the future, so best practice is to only use non-reserved identifiers in your template. See Backwards compatibility for more information on identifiers.

The representation field

The representation field must be one of the following values. If unset, it will default to plain.

  • plain
  • wiki
  • storage

The value field

The value field must be in the same format as the representation field. If the format is incorrect (such as mismatched tags in storage format), an error message will be displayed in the resulting page. Here's an explanation of what each format means:

Example of the request POST body

The context url may need some information to produce a more individually suitable response. Confluence will send some information related to the blueprint in the body of the request during the creation process. Here's an example of what will be sent in the body of the POST request:

1
2
3
4
5
6
7
8
{
  "addonKey": "addon-key",
  "blueprintKey": "blueprint-key",
  "spaceKey": "SPACEKEY",
  "userKey": "edd16ba6-0d41-4313-8bb9-84dc82cf6e7c",
  "userLocale": "fr_FR"
}

  • addonKey: the key of the add-on that the blueprint is part of.
  • blueprintKey: the key of the blueprint that triggered this context request.
  • spaceKey: the space to create the page in (this is selected by the user in the Create dialog).
  • userKey: the user key of the user creating the page from blueprint.
  • userLocale: the locale of the user creating the page from blueprint.
Note that userKey and userLocale will not be available in the POST request after GDPR deprecation period.

Rate this page: