Working with the POM

This page describes the Project Object Model (POM) file generated by the SDK.

Overview

When you use the Atlassian Plugin SDK to create a plugin project, the SDK generates a Maven POM file for your project based on values you provided when running the create plugin script. Similarly, when you add modules to the project using the SDK, the SDK makes the corresponding changes to the POM files, for example, adding dependency declarations.

If you are just starting plugin development, it's helpful to understand how the POM works and how the SDK generates it. For simple or test projects, you may not need to modify the POM directly. However, most projects will require you to modify the POM yourself. Typically, you would do so to take advantage of Maven features outside the scope of the SDK functions, to customize build or Maven settings, or to specify dependencies manually.

Example of the SDK-Generated POM

The following listing shows a POM generated by the SDK. This POM happens to be for a Confluence plugin, but shows the basic elements in the POM for any type of Atlassian plugin project. So far, no additional modules have been added to the plugin project.

1
2
<?xml version="1.0" encoding="UTF-8"?>

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">

    <modelVersion>4.0.0</modelVersion>
    <groupId>com.example.plugins.tutorial.confluence</groupId>
    <artifactId>HelloWorld</artifactId>
    <version>1.0-SNAPSHOT</version>
    <organization>
        <name>Example Company</name>
        <url>http://www.example.com/</url>
    </organization>
    <name>HelloWorld</name>
    <description>This is the com.example.plugins.tutorial.confluence:HelloWorld plugin for Atlassian Confluence.</description>
    <packaging>atlassian-plugin</packaging>
    <dependencies>
        <dependency>
            <groupId>junit</groupId>
            <artifactId>junit</artifactId>
            <version>4.10</version>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>com.atlassian.confluence</groupId>
            <artifactId>confluence</artifactId>
            <version>${confluence.version}</version>
            <scope>provided</scope>
        </dependency>
        <!-- WIRED TEST RUNNER DEPENDENCIES -->
        <dependency>
            <groupId>com.atlassian.plugins</groupId>
            <artifactId>atlassian-plugins-osgi-testrunner</artifactId>
            <version>${plugin.testrunner.version}</version>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>javax.ws.rs</groupId>
            <artifactId>jsr311-api</artifactId>
            <version>1.1.1</version>
            <scope>provided</scope>
        </dependency>
        <dependency>
            <groupId>com.google.code.gson</groupId>
            <artifactId>gson</artifactId>
            <version>2.2.2-atlassian-1</version>
        </dependency>
    </dependencies>
    <build>
        <plugins>
            <plugin>
                <groupId>com.atlassian.maven.plugins</groupId>
                <artifactId>confluence-maven-plugin</artifactId>
                <version>${amps.version}</version>
                <extensions>true</extensions>
                <configuration>
                    <productVersion>${confluence.version}</productVersion>
                    <productDataVersion>${confluence.data.version}</productDataVersion>
                    <allowGoogleTracking>false</allowGoogleTracking>
                </configuration>
            </plugin>
            <plugin>
                <artifactId>maven-compiler-plugin</artifactId>
                <configuration>
                    <source>1.8</source>
                    <target>1.8</target>
                </configuration>
            </plugin>
        </plugins>
    </build>
    <properties>
        <confluence.version>7.13.0</confluence.version>
        <confluence.data.version>7.13.0</confluence.data.version>
        <amps.version>8.2.3</amps.version>
    </properties>
</project>

How the SDK generates POM values

In general, our sample POM uses standard Maven object model syntax, as described here maven.apache.org/pom.html. However, it's worth looking at how the SDK generates the POM for a specific project:

• The modelVersion element refers to the object model version used by the SDK. You should not need to change this value.

• The groupId, artifactId, and version elements reflect values you supplied at the prompts presented by the create plugin script:

  1
  2
  Define value for groupId: : com.example.plugins.tutorial.confluence
  Define value for artifactId: : HelloWorld
  Define value for version:  [1.0-SNAPSHOT]: 
  Define value for package:  [com.example.plugins.tutorial.confluence]: 
  

  These identify the package, classname and refer to the version of the plugin itself. These values are visible to the administrators of the host application where the plugin is deployed from within UPM.

• The groupId and artifactId are concatenated to make up the add-on key. The add-on key is the unique ID that the Atlassian framework uses to identify the add-on.

• The SDK adds default values for the project name, description, and organization values, which also appear in the details view for the add-on. This view is particularly important if you're developing a plugin for distribution on the Atlassian Marketplace. However, even if you are developing a plugin for internal consumption only, it's helpful to provide a meaningful project name, description, and other details of the add-on. You may even choose to include additional assets, such as a screenshot. For more information on customizing the add-on view in the Manage Add-ons page, see Plugin metadata files used by UPM and Marketplace.
  

• packaging should always be atlassian-plugin.

• dependencies specify the libraries that your plugin needs. For more about managing dependencies with the POM, see Managing Dependencies.

• build describes detailed build settings. Note that the SDK adds the following plugins to Maven:

  • com.atlassian.maven.plugins
  • maven-compiler-plugin
    The plugins offer numerous configuration options you can use to control the build environment for your project. For details on the configuration options, see Using the AMPS Maven Plugin Directly.

• httpPort is the port that the plugin or product will listen to, if you would like to set the port in the POM please do so using the properties (set out below). Warning: If you set the <httpPort> in the <configuration> section, then you won't be able to dynamically set your own port using the -p (or -http-port) option when you use atlas-run later. Instead, you should set it using the <httpPort.value> in the section as follows:

1
2
<?xml version="1.0" encoding="UTF-8"?>

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">

    ...
    <dependencies>
        ...
    </dependencies>
    <build>
        <plugins>
            <plugin>
                <groupId>com.atlassian.maven.plugins</groupId>
                <artifactId>confluence-maven-plugin</artifactId>
                <version>${amps.version}</version>
                <extensions>true</extensions>
                <configuration>
                    <productVersion>${confluence.version}</productVersion>
                    <productDataVersion>${confluence.data.version}</productDataVersion>
                    <allowGoogleTracking>false</allowGoogleTracking>
                    <httpPort>${httpPort.value}</httpPort>
                </configuration>
            </plugin>
            ...
            ...
    <properties>
        <httpPort.value>2000</httpPort.value>
        <confluence.version>7.13.0</confluence.version>
        <confluence.data.version>7.13.0</confluence.data.version>
        <amps.version>8.2.3</amps.version>
    </properties>
</project>

• properties specifies the target host application and version and the version of the SDK used to generate the project. These determine the environment that the SDK starts up when you enter the atlas-run command in the project home directory. They do not affect the final artifact of the project, the JAR file that can be installed to the host application.