- Created by Robert Reiner, last modified on 25. Mar 2019
Shows how the Apptools Maven Plugin supports Unique Snapshot Versions.
- Since
- 0.10.0
If snapshot versions are deployed to a Confluence server, it may difficult for administrators to determine which version is actually running. If the build sets a timestamp to the snapshot version in the atlassian-plugin.xml, the administration has a much easier job to determine the version of the deployed app. Using the REST API, this version information is also useful to prevent deploying a version that is already deployed.
This use case shows the configuration for working with Unique Snapshot Versions. There are many alternative approaches to achieve the same result. Please consider this only as one option among many.
Unique Snapshot Versions
Unique Snapshot Versions are not really unique in a broad sense. The snapshot version has its qualifier SNAPSHOT replaced by a formatted timestamp (yyyyMMdd.HHmmss).
If the build of versions is a sequential process this timestamp at seconds precision is typically unique.
Adding Unique Snapshot Versions
To use Unique Snapshot Versions you need to replace the version in snapshot build with a formatted timestamp for the version specified in the atlassian-plugin.xml.
<version>${project.atlassian.plugin.version}</version>
Per default, that is on every build that is not a release build, the property is set with the version information.
<project.atlassian.plugin.version>
${build.version.major}.${build.version.minor}.${build.version.micro}-${build.timestamp.custom}
</project.atlassian.plugin.version>
The properties shown above are provided by the Buildmetadata Maven Plugin (please use version 1.7.0 or later). You may use other tools. What is important that the property you specified in the atlassian-plugin.xml is provided by the build process.
In case of a release build, the version provided by the POM should be set. Otherwise the administrator could not easily determine, if the app is in a released or snapshot version.
Specify a profile you activate with the Maven Release Plugin.
<profile>
<id>release-doctype-add-on</id>
<properties>
<project.atlassian.plugin.version>${project.version}</project.atlassian.plugin.version>
</properties>
</profile>
This seems simple, but the only why we accomplished that for version 2.5.3 is using the arguments parameter.
<pluginManagement>
<plugins>
...
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-release-plugin</artifactId>
<version>2.5.3</version>
<configuration>
<useReleaseProfile>false</useReleaseProfile>
<arguments>-P release-doctype-add-on</arguments>
</configuration>
</plugin>
...
</plugins>
</pluginManagement>
atlassian-plugin.xml in app archive
The generated archive contains the atlassian-plugin.xml with the timestamped version for snapshot builds.
<?xml version="1.0" ?>
<atlassian-plugin
key="de.smartics.atlassian.confluence.smartics-doctype-addon-services"
name="projectdoc for Service Management" plugins-version="2">
<plugin-info>
<description>projectdoc Blueprints for managing services and systems.</description>
<version>1.0.1-20190325.160036</version>
...
For releases, the version does not contain the timestamp.
<?xml version="1.0" ?>
<atlassian-plugin
key="de.smartics.atlassian.confluence.smartics-doctype-addon-services"
name="projectdoc for Service Management" plugins-version="2">
<plugin-info>
<description>projectdoc Blueprints for managing services and systems.</description>
<version>1.0.1</version>
...
Using Unique Snapshot Versions
The qualifier of a deployed app is parsed with the date format specified by the qualifierDatePattern (which defaults to yyyyMMdd.HHmmss) and compared to the version of the app configured with the Apptools Maven Plugin.
The timestamp must be provided by the app's artifact. The Apptools Maven Plugin looks at the following locations (in the given order):
| File in Archive | Type | Element in File | Format |
|---|---|---|---|
atlassian-plugin.xml | XML | First element with name 'version'. | As specified by the qualifierDatePattern. |
META-INF/build.properties | Properties | Property with name 'build.timestamp.millis'. | long (ms) |
META-INF/buildmetadata.xml | XML | First element with name 'timestamp'. | long (ms) |
META-INF/MANIFEST.MF | JAR Manifest | Last modified time of the file. | long (ms) |
Since 0.11.0
The lookup in atlassian-plugin.xml is provided since version 0.11.0.
In case the Apptools Maven Plugin could evaluate the timestamp and determine that the deployed app is up-to-date the following is rendered:
[INFO] App 'de.smartics.atlassian.confluence.smartics-doctype-addon-services'
with version '1.0.1-SNAPSHOT/1.0.1-20190325.160036 (local/deployed)' is up-to-date.
Use -DforceDeloy to override.
If -DdryRun is used and the local version is new, then the console shows the following:
[INFO] If not in dryRun mode, app 'smartics-doctype-addon-services-1.0.1-SNAPSHOT.jar'
would be deployed to 'https://example.com/confluence/rest/plugins/1.0/'.
