The Problem

Happen to see this message as a response to your request to save a Confluence page?

And this in the log on the server?

com.mysql.jdbc.MysqlDataTruncation:
Data truncation: Data too long for column 'STRINGVAL' at row 1

Not being able to save a page is quite annoying.

Serenity now!

A Cause

You may have hit CONFSERVER-52504 where the number and order of the macros on your page hits the magic number to prevent Confluence from saving your page.

This is an issue for pages with a larger number of macros. Since the projectdoc Toolbox provides blueprints that already employ a large number of macros, chances are that you hit this problem sooner.

A Workaround

Unfortunately the issues is rated with severity minor. So there is a good chance for this problem to not go away any time soon.

What you need to do to get your page saved is changing the number and order of your macros. Note that for the calculation that produces the issue the occurrence number of the same macro is not important. Each type of macro is only considered once. What counts is the length of the macro name and its position in the list of macros of this page. So you need to adjust the name and position to work around the problem.

What often works for me is adding the Cheese Macro (since this is typically not already on the page) within a macro that hides it (since I do not want to have the cheese macro rendered on my page).

Principles

In the past we have come up with some simple observations that we like when using blueprints.

1. Have sets of blueprints that work together, using existing blueprints
2. Have at least one space that provides a basic structure for the domain of the blueprint set
3. Create navigation by dynamic linking
   1. Provide a type blueprint for most of the blueprints
   2. Show pages of a given type
   3. Show child pages and a reference to the parent
   4. After the creation of a new space or new page, everything should be ready to work - no remove this, paste that

The Mission

To create a blueprint you need to touch a number of files.

1. There is the XML file containing the template,
2. the Soy file to specify the wizard.
3. A JavaScript file for the validators for the wizard,
4. probably a Java file to manipulate the blueprint context.
5. Add localized resource files for one or more languages,
6. create one or more index pages,
7. and finally a number of edits to the atlassian-plugin.xml file.

So the basic course of events is this:

> mvn doctype:create 
  -DshortId=services 
  -DprojectName="Service Management Doctypes" 
  -DprojectDescription="Provides Blueprints for System Management."
  -DcreateExamples=false
> [add your descriptor files]
> mvn doctype:generate
> atlas-run

> mvn doctype:create -DshortId=my-sandbox
> mvn doctype:generate
> atlas-debug

Types of Pages

To make this simplification we define some constraints.

First, we think of pages as documents with properties (key-value pairs) and sections (a title with text, possibly nested). We call this a projectdoc document. With this in mind, we define a document type with a doctype descriptor (there is also a descriptor for spaces and one for the context of the add-on).

When we create new doctype add-ons there are typically three kind of documents:

1. Documents that contain information of a given type (e.g. a doctype to document systems)
2. Documents that categorize this type (e.g. system type documents)
3. Documents that categorize this and other types (e.g. documents that specify phases in a lifecycle)

The Tool

We created a first beta version of the Doctypes Maven Plugin that should make it a lot easier to create these three kinds of pages.

Everything starts with the archetype project. But you control the archtetype for doctype add-ons with the doctype:create goal which sets some defaults and makes creating new add-on projects quite easy.

> mvn doctype:create 
  -DshortId=services 
  -DprojectName="Service Management Doctypes" 
  -DprojectDescription="Provides Blueprints for System Management."
  -DcreateExamples=false

To simplify this process of blueprint creation, we do specify one descriptor per document and space type (currently there can only be one space).

<doctype
  xmlns="http://smartics.de/xsd/projectdoc/doctype/1"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  id="it-system"
  base-template="standard"
  provide-type="standard-type"
  category="operations">
  <resource-bundle>
    <l10n>
      <name>IT System</name>
      <description>
        Provide information on an IT system to be deployed to.
      </description>
      <about>
        IT systems are part of environments where products are deployed to.
      </about>
    </l10n>
    <l10n locale="de">
      <name>IT-System</name>
      <description>
        Erstellen Sie eine Akte zu einem IT-System.
      </description>
      <about>
        IT-Systeme stellen Funktionalität bereit, die von Services genutzt werden.
      </about>
      <type plural="IT-Systemtypen">IT-Systemtyp</type>
    </l10n>
  </resource-bundle>

  <properties>
    <property key="projectdoc.doctype.common.type">
      <value>
        <macro name="projectdoc-name-list">
          <param name="doctype">it-system-type</param>
          <param
            name="property"
            key="projectdoc.doctype.common.type" />
          <param name="render-no-hits-as-blank">true</param>
        </macro>
      </value>
    </property>

    <property key="projectdoc.doctype.it-system.lifecycle-phase">
      <value>
        <macro name="projectdoc-name-list">
          <param name="doctype">lifecycle-phase</param>
          <param
            name="property"
            key="projectdoc.doctype.it-system.lifecycle-phase" />
          <param name="render-no-hits-as-blank">true</param>
        </macro>
      </value>
      <resource-bundle>
        <l10n>
          <name>Lifecycle Phase</name>
        </l10n>
        <l10n locale="de">
          <name>Lifecycle-Phase</name>
        </l10n>
      </resource-bundle>
    </property>
  </properties>
</doctype>

provide-type="standard-type"

<doctype
  xmlns="http://smartics.de/xsd/projectdoc/doctype/1"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  id="lifecycle-phase"
  base-template="type"
  provide-type="none"
  category="reference">
  <resource-bundle>
    <l10n>
      <name>Lifecycle Phase</name>
      <description>
        Define a lifecycle phase.
      </description>
      <about>
        Lifecycle Phases define phases that are bound to a lifecycle.
      </about>
    </l10n>
    <l10n locale="de">
      <name>Lifecycle-Phase</name>
      <description>
        Definieren Sie eine Phase.
      </description>
      <about>
        Phasen von Lifecycles dokumentieren einen Abschnitt im Zyklus von Ressourcen.
      </about>
      <type plural="Lifecycle-Phasentypen">Lifecycle-Phasentyp</type>
    </l10n>
  </resource-bundle>

  <properties>
    <property key="projectdoc.doctype.lifecycle-phase.lifecycle">
      <value>
        <macro name="projectdoc-name-list">
          <param name="doctype">lifecycle</param>
          <param
            name="property"
            key="projectdoc.doctype.lifecycle-phase.lifecycle" />
          <param name="render-no-hits-as-blank">true</param>
        </macro>
      </value>
      <resource-bundle>
        <l10n>
          <name>Lifecycle</name>
        </l10n>
        <l10n locale="de">
          <name>Lifecycle</name>
        </l10n>
      </resource-bundle>
    </property>
  </properties>
</doctype>

Then generate all the blueprint related stuff (note there are XML schema files to support writing these). And startup Confluence with the Atlas SDK.

> mvn doctype:generate
> atlas-run

Limitations

We started our internal beta (although the sources are already published on Bitbucket) to check how it is working. Needless to say that at this early stage it has some limitations:

• The syntax for defining sections is not final - property values (with alternate forms as seen above) and whole sections (without alternatives if you need to specify more than a placeholder) are specified in their storage format within an xml element
• Only one space blueprint can be defined
• There are grammatical problems with the boiler plate texts (especially in German), so there is the need to run over the generated localization bundles
• No roundtrip: You should not need to edit the generated files (or if you do, should not use the descriptor again)
• Very simple wizards currently
• No support to add CSS or JavaScript
• Currently the localized resources need to be written to the descriptor
• There is also a redundancy specifying the central base templates - but you won't see this until you need to create your own base template

We'll work to improve the tools to remove these limitations.

What is next?

As stated above the tools have some rough edges. So we need to run this internally first. If you are interested to use this tool, it is available at Bitbucket and available from our Nexus server.

Please check out the documentation for the Doctypes Maven Plugin to get everything set up. Do not hesitate to get in touch, if you have questions or are being interested in this topic!

Hopefully we can soon truthfully say: Creating Blueprints is fun!