Yes

A key to identify this module.

This key must be unique relative to the add on, with the exception of Confluence macros: Their keys need to be globally unique.

Keys must only contain alphanumeric characters and dashes.

The key is used to generate the url to your add-on's module. The url is generated as a combination of your add-on key and module key. For example, an add-on which looks like:

{ "key": "my-addon", "modules": { "configurePage": { "key": "configure-me", } } }

Will have a configuration page module with a URL of /plugins/servlet/ac/my-addon/configure-me.

Yes

A human readable name.

Represents a string that can be resolved via a localization properties file. You can use the same i18n Property key and value in multiple places if you like, but identical keys must have identical values.

Example

1
2
{
  "value": "My text"
}

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

Yes

Defines where the blueprint template is located and the context for variable substitution.
For more about how to define variables in blueprint template and template context please follow the example in Blueprint Template Context.

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

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

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
{
  "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
<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
[
  {
    "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
<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.

• edit
• EDIT
• view
• VIEW

Defines the screen to go to when creating this type of Blueprint. A value of view causes Confluence to bypass the editor page and automatically create the page content. The user lands in the view of the created page. When edit, the user is sent to the editor which is pre-filled with the template content.

Defines a short description for this Blueprint, to be shown in the Create Content dialog.

Represents a string that can be resolved via a localization properties file. You can use the same i18n Property key and value in multiple places if you like, but identical keys must have identical values.

Example

1
2
{
  "value": "My text"
}

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

Defines an icon for this Blueprint, to be shown in the Create Content dialog.

Defines an icon to display.

Example

1
2
{
  "icon": {
    "width": 16,
    "height": 16,
    "url": "/my-icon.png"
  }
}