A quick step-by-step tutorial to create a model project from scratch.

Summary

This step-by-step tutorial guides you through the configuration steps to create a doctype add-on project for the projectdoc Toolbox for Confluence. It shows how to create your build environment and how to use the Doctype Maven Plugin to create a new model project.

The sources can be accessed on Bitbucket at https://bitbucket.org/smartics/scoopee-doctype-model-mydoctypes.

Prerequisites

You need to install Java, Maven and the Atlassian SDK.

With the Atlassian SDK a Maven installation is bundled and instructions on how to install the Java Development Kit (JDK) is covered. So we start with the Atlassian SDK.

Atlassian SDK

The Atlassian SDK needs to be installed in an appropriate version. We recommend to install the latest stable version.

For more information on how to get started with the Atlassian SDK, please read Getting started.

Configuration

After successful installation of the Atlassian SDK you need to configure Maven and the Doctype Maven Plugin.

Maven

To configure the build process we recommend to provide a Maven Settings file (settings.xml) with the following information.

Please adjust the local repository path according to your environment!

You may also want to add the repository information not to your settings file, but to your artifact server. Alternatively you may want to add your local repository server to fetch most of the dependencies locally.

<?xml version="1.0"?>

<settings>
  <localRepository>D:\projects\repositories\external</localRepository>

  <servers>
    <server>
      <id>smartics</id>
      <username>anonymous</username>
      <password>anonymous</password>
    </server>
    <server>
      <id>smartics-snapshot</id>
      <username>anonymous</username>
      <password>anonymous</password>
    </server>
  </servers>

  <profiles>
    <profile>
      <id>view-from-outside-of-smartics</id>
      <repositories>
        <repository>
          <id>smartics</id>
          <url>https://www.smartics.eu/nexus/content/repositories/public</url>
          <releases>
            <enabled>true</enabled>
          </releases>
          <snapshots>
            <enabled>false</enabled>
          </snapshots>
        </repository>
        <repository>
          <id>smartics-snapshot</id>
          <url>https://www.smartics.eu/nexus/content/repositories/public-snapshot</url>
          <releases>
            <enabled>false</enabled>
          </releases>
          <snapshots>
            <enabled>true</enabled>
          </snapshots>
        </repository>
      </repositories>
      <pluginRepositories>
        <pluginRepository>
          <id>smartics</id>
          <url>https://www.smartics.eu/nexus/content/repositories/public</url>
          <releases>
            <enabled>true</enabled>
          </releases>
          <snapshots>
            <enabled>false</enabled>
          </snapshots>
        </pluginRepository>
        <pluginRepository>
          <id>smartics-snapshot</id>
          <url>https://www.smartics.eu/nexus/content/repositories/public-snapshot</url>
          <releases>
            <enabled>false</enabled>
          </releases>
          <snapshots>
            <enabled>true</enabled>
          </snapshots>
        </pluginRepository>
      </pluginRepositories>
    </profile>
  </profiles>

  <activeProfiles>
    <activeProfile>view-from-outside-of-smartics</activeProfile>
  </activeProfiles>

  <pluginGroups>
    <pluginGroup>de.smartics.maven.plugin</pluginGroup>
  </pluginGroups>
</settings>

The main part is that the smartics repositories are accessible.

We assume that you create a separate settings.xml and a separate configuration for the Doctype Maven Plugin. Therefore the following commands provide an explicit settings file (by the -s flag) and a explicit project settings file (by the -DprojectSettingsId system property).

Sample files can be found at src/etc/config in the sample project on Bitbucket.

If you use the default files, just omit this additional parameters on your command line.

To check if everything is in place, run the following command:

mvn -s C:\Users\test-user\.m2\settings-external.xml de.smartics.maven.plugin:doctype-maven-plugin:1.0.0:help

It simply shows the information on how to use the mojos of the Doctype Maven Plugin.

Provide the projectdoc Toolbox Artifact

The projectdoc Toolbox add-on is not available in a public repository currently. You need to download the OBR, extract the JAR for the add-on and place it in your repository manually.

Download the OBR for the projectdoc Toolbox from the Atlassian Marketplace. You'll find the download links on the Version history page.

The coordinates are found in the artifact at smartics-projectdoc-confluence-2.4.1.jar\META-INF\maven\de.smartics.atlassian.confluence\smartics-projectdoc-confluence\pom.properties.

Now install the projectdoc Toolbox JAR to your local artifact directory.

mvn -s C:\Users\test-user\.m2\settings-external.xml install:install-file \
  -Dfile=smartics-projectdoc-confluence-2.4.1.jar \
  -DgroupId=de.smartics.atlassian.confluence \
  -DartifactId=smartics-projectdoc-confluence \
  -Dversion=2.4.1 \
  -Dpackaging=jar

For more information on installing JARs, read Usage of the Maven Install Plugin.

Since the JAR of the projectdoc Toolbox you use already contains everything you need, do not add a POM file. Use the one generated by Maven per default.

Doctype Maven Plugin

The Doctype Maven Plugin allows to add some static information to your build environment that is used for every build run with this plugin.

The information is defined in the Project Settings. Here is an example:

<?xml version='1.0'?>

<project-settings
  xmlns="http://smartics.de/xsd/projectdoc/project-settings/1"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

  <coordinates>
    <groupId>de.scoopee.projectdoc</groupId>
    <artifactIdPrefix>scoopee-doctype-addon-</artifactIdPrefix>
    <modelArtifactIdPrefix>scoopee-doctype-model-</modelArtifactIdPrefix>
  </coordinates>

  <keys>
    <packagePrefix>de.scoopee.projectdoc</packagePrefix>
    <organizationSignature>Kronseder &amp; Reiner GmbH, scooopee</organizationSignature>
  </keys>

  <references>
    <reference
      name="addon-documentation"
      type="confluence">http://www.smartics.eu/confluence/display/PDAC1</reference>
  </references>
</project-settings>

Please adjust the information according to your needs.

Per default this file resides in the same folder as the settings.xml (which is the .m2 folder) and is named project-settings.xml. For this tutorial we assume you create a separate file and name it project-settings-external.xml.

Create Project

Run the following command (on a single line) to create a new project containing example models for a space and two doctypes:

mvn -s C:\Users\testuser\.m2\settings-external.xml \
     de.smartics.maven.plugin:doctype-maven-plugin:1.0.0:create-model \
     -DprojectSettingsId=project-settings-external \
     -DshortId=mydoctypes \
     -DprojectName="My Doctypes" \
     -DprojectDescription="A project with generated example models."

You'll see a prompt that requests your consent that the properties provided to the Archetype from your environment are correct.

[INFO] Using property: groupId = de.scoopee.projectdoc
[INFO] Using property: artifactId = scoopee-doctype-model-mydoctypes
[INFO] Using property: version = 0.1.0-SNAPSHOT
[INFO] Using property: package = de.scoopee.projectdoc.mydoctypes
[INFO] Using property: addon-documentation = http://www.smartics.eu/confluence/display/PDAC1
[INFO] Using property: copyright = Copyright ${year} Kronseder & Reiner GmbH, scooopee
[INFO] Using property: inceptionYear = 2018
[INFO] Using property: modelsFolder = /src/main/resources/projectdoc-models
[INFO] Using property: obrArtifactIdPrefix = scoopee-doctype-addon-
[INFO] Using property: organizationSignature = Kronseder & Reiner GmbH, scooopee
[INFO] Using property: organizationSignatureXml = Kronseder &amp; Reiner GmbH, scooopee
[INFO] Using property: packagePrefix = de.scoopee.projectdoc
[INFO] Using property: projectDescription = A project with generated example models.
[INFO] Using property: projectName = My Doctypes
[INFO] Using property: shortId = mydoctypes
Confirm properties configuration:
groupId: de.scoopee.projectdoc
artifactId: scoopee-doctype-model-mydoctypes
version: 0.1.0-SNAPSHOT
package: de.scoopee.projectdoc.mydoctypes
addon-documentation: http://www.smartics.eu/confluence/display/PDAC1
copyright: Copyright ${year} Kronseder & Reiner GmbH, scooopee
inceptionYear: 2018
modelsFolder: /src/main/resources/projectdoc-models
obrArtifactIdPrefix: scoopee-doctype-addon-
organizationSignature: Kronseder & Reiner GmbH, scooopee
organizationSignatureXml: Kronseder &amp; Reiner GmbH, scooopee
packagePrefix: de.scoopee.projectdoc
projectDescription: A project with generated example models.
projectName: My Doctypes
shortId: mydoctypes
 Y: :

Please hit return to accept the configuration.

[INFO] ----------------------------------------------------------------------------
[INFO] Using following parameters for creating project from Archetype: smartics-projectdoc-doctype-model-archetype:1.0.0
[INFO] ----------------------------------------------------------------------------
[INFO] Parameter: groupId, Value: de.scoopee.projectdoc
[INFO] Parameter: artifactId, Value: scoopee-doctype-model-mydoctypes
[INFO] Parameter: version, Value: 0.1.0-SNAPSHOT
[INFO] Parameter: package, Value: de.scoopee.projectdoc.mydoctypes
[INFO] Parameter: packageInPathFormat, Value: de/scoopee/projectdoc/mydoctypes
[INFO] Parameter: shortId, Value: mydoctypes
[INFO] Parameter: organizationSignatureXml, Value: Kronseder &amp; Reiner GmbH, scooopee
[INFO] Parameter: groupId, Value: de.scoopee.projectdoc
[INFO] Parameter: obrArtifactIdPrefix, Value: scoopee-doctype-addon-
[INFO] Parameter: packagePrefix, Value: de.scoopee.projectdoc
[INFO] Parameter: modelsFolder, Value: /src/main/resources/projectdoc-models
[INFO] Parameter: inceptionYear, Value: 2018
[INFO] Parameter: organizationSignature, Value: Kronseder & Reiner GmbH, scooopee
[INFO] Parameter: addon-documentation, Value: http://www.smartics.eu/confluence/display/PDAC1
[INFO] Parameter: projectDescription, Value: A project with generated example models.
[INFO] Parameter: version, Value: 0.1.0-SNAPSHOT
[INFO] Parameter: copyright, Value: Copyright ${year} Kronseder & Reiner GmbH, scooopee
[INFO] Parameter: package, Value: de.scoopee.projectdoc.mydoctypes
[INFO] Parameter: artifactId, Value: scoopee-doctype-model-mydoctypes
[INFO] Parameter: projectName, Value: My Doctypes
[WARNING] The directory D:\Projekte\repositories\git\scoopee-doctype-model-mydoctypes already exists.
[INFO] Project created from Archetype in dir: D:\Projekte\repositories\git\scoopee-doctype-model-mydoctypes
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 01:10 min
[INFO] Finished at: 2018-11-18T17:30:08+01:00
[INFO] Final Memory: 16M/180M
[INFO] ------------------------------------------------------------------------

The project is created successfully.

Manual Adjustments

Apply the following changes to the generated code:

Versions

The versions of the Doctype Maven Plugin and the version of the projectdoc Toolbox need to be updated to the latest versions.

    <version.smartics-projectdoc-confluence>2.4.1</version.smartics-projectdoc-confluence>
    <version.doctype-maven-plugin>1.0.0</version.doctype-maven-plugin>

Copyright Notice

Due to a bug in version 1.0 of the Doctype Maven Plugin you need to manually fix the inception year in the COPYRIGHT.txt. Simply replace the placeholder ${year} with the current year (e.g. 2018).

Skip this step if you discard this test project anyway.

License Header

The default configuration uses the License Maven Plugin to add license information to the header files.

To create the correct headers run the following command:

mvn initialize license:format

You will encounter the following message if the headers do not match the required format:

[INFO] --- maven-license-plugin:1.9.0:check (default) @ scoopee-doctype-model-mydoctypes ---
[INFO] Checking licenses...
[INFO] Missing header in: D:\Projekte\repositories\git\scoopee-doctype-model-mydoctypes\src\main\resources\projectdoc-models\add-on.xml
[INFO] Missing header in: D:\Projekte\repositories\git\scoopee-doctype-model-mydoctypes\src\etc\config\settings-external.xml
[INFO] Missing header in: D:\Projekte\repositories\git\scoopee-doctype-model-mydoctypes\src\main\resources\projectdoc-models\doctypes\sample-doctype.xml
[INFO] Missing header in: D:\Projekte\repositories\git\scoopee-doctype-model-mydoctypes\src\etc\config\project-settings-external.xml
[INFO] Missing header in: D:\Projekte\repositories\git\scoopee-doctype-model-mydoctypes\src\main\resources\projectdoc-models\spaces\main-space.xml
[INFO] ------------------------------------------------------------------------
[INFO] BUILD FAILURE
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 11.591 s (Wall Clock)
[INFO] Finished at: 2018-11-18T19:14:53+01:00
[INFO] Final Memory: 75M/346M
[INFO] ------------------------------------------------------------------------
[ERROR] Failed to execute goal com.mycila.maven-license-plugin:maven-license-plugin:1.9.0:check (default) on project scoopee-doctype-model-mydoctypes: Some files do not have the expected license header -> [Help 1]

Package Doctype Add-on

Run the following command (on a single line):

mvn -s C:\Users\testuser\.m2\settings-external.xml \
     clean package \
     -DprojectSettingsId=project-settings-external

If you encounter the following error message with a failed build, you skipped the configuration step where the projectdoc Toolbox artifact has been deployed to your build environment.

[ERROR] Failed to execute goal 
de.smartics.maven.plugin:doctype-maven-plugin:1.0.0:build (build-obr) 
on project scoopee-doctype-model-mydoctypes: Cannot build project! 
[org.apache.maven.lifecycle.LifecycleExecutionException: Failed to 
execute goal on project scoopee-doctype-addon-mydoctypes: Could not 
resolve dependencies for project 
de.scoopee.projectdoc:scoopee-doctype-addon-mydoctypes:atlassian-plugin:0.1.0-SNAPSHOT: 
Could not find artifact 
de.smartics.atlassian.confluence:smartics-projectdoc-confluence:jar:2.4.1 
in atlassian-public (https://maven.atlassian.com/repository/public)]

Run Confluence with your Doctype Add-on

After successful build change to the target folder and run the Confluence server.

cd target\scoopee-doctype-model-mydoctypes
atlas-debug

Provide a Developer License

Go to the add-on administration page and show system add-ons. This lists the projectdoc Toolbox with a blue button named "Free trial". Click this button in case you have not already a license you can use for your development box.

Create a Space

Launch the space wizard and create a new space provided by your add-on.

Seems broken on the left side?

The navigation links are activated when a copy of the Core Doctype Add-on is deployed to the server.

Simply download the artifact from the Atlassian Marketplace. No license required on the Confluence server since this add-on is licensed under the Apache License and can be used free of charge.

The rest of the tutorial will work regardless of installing the add-on or not.

Create a Document

Working with your Project

Check your model project to your version control. The add-on project, which is created in the target folder, can always be created from the model files.

So typically you

make changes to your files,
package them,
change to the generated project in the target folder and
start the Confluence server with the Atlassian SDK.

In projectdoc Model Descriptors the descriptors for add-on, spaces, and doctypes are specified.

Resources

The projectdoc Toolbox for Atlassian Confluence: The projectdoc Toolbox supports agile teams in writing project documentation collaboratively. This is an introduction to use cases for and features of the projectdoc Toolbox.
projectdoc Toolbox Online Manual: The online manual for version 1 of the projectdoc Toolbox for Confluence.
Doctype Maven Plugin: Create doctype add-ons (OBRs) for the projectdoc Toolbox with Confluence Blueprints based on XML model descriptions easily!
projectdoc Model Descriptors: Provides an overview over the model descriptors to describe the add-on, spaces, and doctypes.

Space shortcuts

Page tree

Docs

Support

Free Blueprints

Tooling for Blueprints

Free Extensions

Spaces

Plugins for Maven

Incubator

Libraries for Java