Basics

Learn about the terms that are used in this documentation and get an overview about the common basics of the Release Info and the Release Info Diff.

User Interface Components

The Release Info user interface is composed of the following components:

  1. headline

  2. table with artifacts and versions

  3. footer with links to pom.xml files and a refresh-cache button

When editing a page, the Release Info interface changes like so:

  1. macro name and parameters

  2. no macro body

  3. double click to edit settings of macro

Terms

The Terms describe the different parts of your Release Info input. Your input is a pom.xml file in XML format.

parent pom / release pom

The parent pom.xml of your release. It points to differen child pom.xml files. See 'Release pom.xml format' for more details.

child pom / module pom

Represents a module of your software described by a separate pom.xml file. See 'Release pom.xml format' for more details.

artifact

A piece of software described in a module pom. Usually described by groupId, artifactId and version.

property

A piece of information inside a module pom. Via a property you can describe anything. It can be plaintext or an URL.

Release pom.xml format

The Release Info is intended to work with pom.xml files used for Software Delivery hereinafter known as release pom.xml. Have a look at the infographic below to make sure, using the right kind of pom.xml file:

  • release pom.xml - Software Delivery
    Describes how your Release is composed. References your release artifacts that are already built and ready to be deployed.
  • pom.xml - Software Development
    Describes how your App is built. It contains all its dependencies, build plugins a.s.o; once built you will have a release artifact of your app which you can deploy to a maven repository (jar/war).

Note: Inheritance of e.g. artifactId or groupId from master pom.xml files are not supported. Please use well formed pom.xml files as described below.

Provide your release pom.xml files only in the flat multi module format. If you're not sure how your release pom.xml should be structured, download the full example (zip) or look at the simplified examples below.

You can store your release pom.xml anywhere as long as it is accessible via http, for example a subversion repository.

Example how a directory layout should be structured:

http://srv/dir1/myapp-release/pom.xml                            //  ⇐ parent pom
http://srv/dir1/myapp-release/myapp-frontend-release/pom.xml     //  ⇐ module #1
http://srv/dir1/myapp-release/myapp-backend-release/pom.xml      //  ⇐ module #2
http://srv/dir1/myapp-release/some-other-module-release/pom.xml  //  ⇐ module #3

Example of a parent pom.xml:

pom.xml
<project>
    <groupId>io.codeclou</groupId>
    <artifactId>myapp-release</artifactId>
    <packaging>pom</packaging>
    <name>MyApp Release</name>
    <version>1.5</version>

    <modules>
        <module>myapp-frontend-release</module>
        <module>myapp-backend-release</module>
        <module>some-other-module-release</module>
    </modules>
</project>

A module pom.xml should have one or more dependencies and can also have properties which will also be displayed in the Release Info:

pom.xml
<project>

    <parent>
        <groupId>io.codeclou</groupId>
        <artifactId>myapp-release</artifactId>
        <version>1.5</version>
    </parent>

    <groupId>io.codeclou</groupId>
    <artifactId>myapp-backend-release</artifactId>
    <packaging>pom</packaging>
    <name>MyApp Release - MyApp-Backend</name>

    <description>Some random text on MyApp Backend</description>

    <dependencies>
        <dependency>
            <groupId>io.codeclou</groupId>
            <artifactId>myapp-backend</artifactId>
            <type>war</type>
            <version>1.5.8</version>
            <scope>runtime</scope>
        </dependency>
    </dependencies>

    <properties>
        <some.api.url>https://someserver/myapibase/</some.api.url>
    </properties>
</project>

Troubleshooting

You might get errors when your input is incorrect, the remote file is too large or your license is expired. An error will look like so:

Usually error occur when the XML of pom.xml files is malformed, if wrong URLs are used or wrong credentials are entered.

Error Codes and Description

404
Not Found

File not found.

Cause

The URL to your parent pom.xml file or module pom.xml files might be wrong.

Solution

Check the following:

  • Check if all files you reference are downloadable via your Browser directly.

401
Unauthorized

File is password protected.

Cause

You are trying to access an URL that is basic Auth proteced.

Solution

Check your input:

  • Is the HTTP username and password set?

403
Forbidden

File is password protected and credentials are wrong.

Cause

You are trying to access an URL that is password protected and credentials are wrong.

Solution

Check your input:

  • Is the HTTP username and password correct?

unexpected
filesystem error

Size of remote file is larger than 400KB, download cancelled.

Cause

You are trying to access an URL that references a file that is larger than 400KB.

Solution

Check your input:

  • Files larger than 400KB cannot be downloaded. Reduce the filesize.

error
Allowlist Problem

The URL you are using is not allowlisted by your Confluence Administrator.

Cause

The URL you are using is not allowlisted by your Confluence Administrator.

Solution

Ask your Confluence Administrator to put your URL on the Allowlist.

Read Only Mode (Data Center)

Since Release Info v1.8.0 and for Confluence Data Center versions higher or equal 6.10 the Read-only mode for Confluence Data Center is supported.

When the Read-only mode is activated, both macros will render with disabled refresh cache buttons, since they would perform a write operation on the global cache. The user will see the message read-only mode active at the bottom right corner to indicate this.

If you for some reason call the refresh-button URL during enabled Read Only Mode you will see this page.