AMPS build configuration reference

This page describes build configuration settings you can use with AMPS. AMPS, which stands for the Atlassian Maven Plugin Suite, is built into the Atlassian Plugins SDK. It defines Maven archetypes and goals specifically for creating Atlassian product plugins.

You can use the following configuration parameters with AMPS. Values to use for a given parameter may vary depending on the host application.

banningExcludes

Specifies what Maven artifacts to ignore when checking for banned dependencies.

1
2
<configuration>
  <banningExcludes>
    <exclude>com.example.group.id:artifact.id</exclude>
  </banningExcludes>
</configuration>

compressResources

Specifies whether web resources in your plugin (eg. JavaScript) are automatically minified as part of the build process. The default value is true.

closureJsdocWarningsEnabled

Specifies whether the closure compiler warnings for JS Docs are enabled or disabled. The warnings are enabled by default (default value is ‘true’).

containerId

Specifies the Cargo container that should be used when starting and hosting the product.

dataSources

It is possible to declare JNDI datasources for the product, but this is not available as a direct child of <configuration>. It is available as a child of a <product> in the <products> tag. See Declaring JNDI Datasources in AMPS for examples.

ajpPort

Specifies the AJP port used by Cargo to communicate with the container.

httpPort

Specifies the port that the container should listen on. The default value varies by product. See the table here.

httpsPort

Like httpPort, but used when SSL (HTTPS) is enabled.

useHttps

Whether the product should be started with HTTPS. In most local development scenarios, this shouldn't be needed. The default value is false.

httpsKeystoreFile

The path of the keystore file used for HTTPS.

httpsKeystorePass

The password to use to access the keypass store (can also be specified with the -Dhttps.keystorePass parameter).

httpsSslProtocol

If SSL is enabled, specifies which protocol to use (defaults to TLS).

contextPath

Specifies the context path at which the product should be deployed. The default value varies by product; see the table here.

jvm

Specifies the command used to start the forked Java VM that will host the container. This can be useful if you need to launch a product with a specific Java version that differs from the system default.

jvmArgs

Specifies arguments to the forked Java VM that will host the container. The default value is blank.

log4jProperties

Specifies a custom log4j.properties file to be used by the product, replacing the one shipped inside the product. Generally, there is no reason to do this, but it can be useful for debugging sometimes.

log4j2Config

Specifies a custom log4j2.xml file to be used by the product, replacing the one shipped inside the product. Generally, there is no reason to do this, but it can be useful for debugging sometimes.

productDataPath

Specifies a path on the local filesystem to a custom product data archive. This allows you to start the product prepopulated with data of your choice. For more details, see the atlas-create-home-zip SDK command.

If you need to also make changes to the webapp directory, see overriding the application's webapp when developing your plugin.

productDataVersion

Specifies the version of the test data resources the product will use at startup. The test data includes a developer license valid for three hours, a default product home directory, and a simple, pre-provisioned, in-memory or on-disk data store (usually provided via HSQL). These files are supplied by Atlassian with the product. The default value is defined for each product in the com.atlassian.amps:atlassian-amps-parent POM file version that corresponds to the version of AMPS being used in your configuration, for example, for version 8.2.3 it would be the .pom file found in this location.

If you'd like to override the default data with data from your own product installation, see the productDataPath parameter.

productVersion

Specifies the version of the product that should be run. This value must correspond to the version number of a set of Maven artifacts available from the Atlassian Maven repositories. The default value is defined for each product in the com.atlassian.amps:atlassian-amps-parent POM file that corresponds to the version of AMPS used in your configuration.

server

Specifies the hostname of the machine on which the container should be started. The default value is localhost.

systemPropertyVariables

Specifies system properties that should be set in the forked Java VM that will host the container. The default values are blank. For example:

1
2
<configuration>
  <systemPropertyVariables>
    <property1Name>property1Value</property1Name>
    <property2Name>property2Value</property2Name>
  </systemPropertyVariables>
</configuration>

pluginArtifacts

Specifies other Atlassian plugins that your plugin depends on to work properly. These plugin artifacts will be installed into the product along with your plugin.

All plugins specified here must be installed in a repository your Maven installation can access through settings.xml.

Example:

1
2
<configuration>
  <pluginArtifacts>
    <pluginArtifact>
      <groupId>com.mycompany.atlassian.plugins</groupId>
      <artifactId>our-business-services-plugin</artifactId>
      <version>1.0.3</version>
    </pluginArtifact>
  </pluginArtifacts>
</configuration>

libArtifacts

Specifies arbitrary Java libraries that your plugin depends on to work properly. These libraries will be installed alongside the product's core libraries in WEB-INF/lib.

All libraries specified here must be installed in a repository your Maven installation can access through settings.xml.

Accessing these libraries from your plugin is a product-specific process, and usually you won't want to do this anyway, as this defeats the purpose of the plugin system. This feature is only useful for legacy code or very old plugins that you're not able to upgrade to version 2 of the plugin system.

To depend on a third-party library, add it to the <dependencies> in your plugin POM, which protects you from changes out of your control.

Example:

1
2
<configuration>
  <libArtifacts>
    <libArtifact>
      <groupId>com.mycompany.ancient.plugins</groupId>
      <artifactId>our-business-services-plugin</artifactId>
      <version>1.0.3</version>
    </libArtifact>
  </libArtifacts>
</configuration>

bundledArtifacts

Specifies other Atlassian plugins that your plugin depends on to work properly. These plugin artifacts will be treated as bundled by the product, meaning they can be disabled but not removed. The product will always make a bundled plugin available at startup, even if it was removed previously. By contrast, plugin artifacts can be removed after installation at any time, and they will stay gone until they are manually reinstalled.

All plugins specified here must be installed in a repository your Maven installation can access through settings.xml.

Unless you're working with a forked version of a plugin normally bundled in the product, you will not need to use this.

To depend on another second- or third-party plugin, add it to the <pluginArtifacts> above.

Example:

1
2
<configuration>
  <bundledArtifacts>
    <bundledArtifact>
      <groupId>com.mycompany.atlassian.plugins</groupId>
      <artifactId>our-forked-bundled-product-plugin</artifactId>
      <version>4.1-mycompany-fork</version>
    </bundledArtifact>
  </bundledArtifacts>
</configuration>

pluginDependencies

Specifies other plugins or OSGi bundles that will be bundled into an OBR archive. OBRs can be installed via the UPM, and the UPM will automatically install any dependencies that are packaged in the OBR which are not installed yet.

All dependencies specified here must be defined in the standard <dependencies> section of the pom.xml, and should be set to a <scope> of either test or provided.

Example:

1
2
<configuration>
  <pluginDependencies>
    <pluginDependency>
      <groupId>com.mycompany.atlassian.plugins</groupId>
      <artifactId>our-osgi-bundle</artifactId>
    </pluginDependency>
  </pluginDependencies>
</configuration>

For more information about dependencies, see Managing Plugin Dependencies.

installPlugin

Specifies whether to install the current plugin when the product is started. The default value is true.

You can set this flag to false to start a product without being in a plugin working directory. This is useful for quickly starting a product with a specific configuration for testing or experimentation. For example, the command:

1
2
atlas-mvn confluence:run -DproductVersion=7.13.0 -Dinstall.plugin=false

Starts Confluence 7.13 with the default test data.

output

Specifies a file to pipe the container's output to. The container output includes the startup logs, messages sent to System.out and System.err while the product is running, and AMPS-specific messages. By default, container output is sent to the standard output stream.

This is useful for comparing your plugin's log output (and possible error messages) between different products or different versions of the same product. It's also useful when reporting bugs with AMPS.

jvmDebugPort

Specifies the port on which the product should listen for a debugger connection. The default value is 5005.

jvmDebugSuspend

Specifies whether the product, when started in debug mode, should wait for a debugger to connect before proceeding with startup. The default value is false.

skipTests

Specifies whether testing should be skipped in this invocation. The default value is false.

functionalTestPattern

Specifies the pattern to use for finding integration tests to run. The default value is \it/**/*Test.java (relative to src/test/java). If any <testGroup> elements are specified, this value will be ignored.

products

Defines a product that can be referenced in a testGroup. Test groups allow you to run a subset of tests on a specific product configuration. For example, if your plugin has been designed is for both Jira and Confluence, you can have a test group with Jira-specific tests, another group with Confluence-specific tests, and a third with tests common to both configurations.

See Create and Run Traditional Integration Tests for examples of the products element configuration.

testGroup

Defines a test group to run on one or more <product> configurations.

See Create and Run Traditional Integration Tests for examples of using the testGroup element.

testGroups

Specifies which test groups should be run in this invocation. Test groups should be referenced by ID and separated by commas. The default is for all test groups to run.

Example:

1
2
atlas-mvn crowd:integration-test -DtestGroups=loginTests,authTests,cookieTests

See Create and Run Traditional Integration Tests for examples of defining test groups.

parallel

Starts up the Atlassian applications in parallel mode. This may be useful if you use test groups in your plugin configuration to launch multiple products at start up, a possible scenario if your plugin is intended to work with more than one type of Atlassian application.

By enabling the parallel option in the POM or by specifying it at the command line, you direct AMPS to initialize the applications simultaneously rather than sequentially. This can reduce the start up time of the test group on faster computers.

By default, the parallel option is off. To enable it, specify it at the command line by passing the -Dparallel switch to the AMPS startup command, or by setting the parallel element in the POM to true, as follows:

1
2
<configuration>
   <parallel>true</parallel>
...
</configuration>

This option has no effect on Studio-Crowd, FishEye or Studio-FeCru.

For more information about test groups, see Create and Run Traditional Integration Tests.

noWebapp

Specifies whether the product(s) required by <products> should actually be started, or if the tests should run blind and assume that the needed products are already running. The default value is false, which starts all required <product> instances.

This can be valuable if you are debugging integration tests and the product's state is not relevant to the tests being debugged; this will save you the wait of a product starting and stopping before you can see the test results.

Example:

1
2
atlas-mvn jira:integration-test -DtestGroups=jiraTests,pluginTests -Dno.webapp=true

enableDevToolbox

Specifies whether the Dev Toolbox (dev only tools at the bottom of the web page) should be enabled. Disabling this may be useful in some debugging or testing scenarios. The default value is true.

enableQuickReload

Specifies whether or not the QuickReload plugin is enabled. The default value is false.

For more information, see Automatic Plugin Reinstallation with QuickReload.

quickReloadVersion

Specifies QuickReload version. If you don't specify this configuration property, AMPS will use the default version of QuickReload.

instructions

Specifies OSGi bundling instructions, interpreted by the Maven BND plugin and used to generate the OSGi manifest inside the plugin JAR. BND instructions give you complete control over the expression of your plugin's runtime dependencies, including package name and version; they communicate to the plugin system (and the product) exactly what is required for your plugin to operate correctly.

This configuration is essential when creating plugins designed to operate in more than one product, but is usually unnecessary in other cases.

testInstructions

Serves a similar purpose to 'instructions' described above, except the test instructions would be used to generate the OSGi manifest inside the plugin's test JAR i.e. JAR built from the test source tree, typically including integration tests.

skipManifestValidation

Specifies whether AMPS should attempt to validate the OSGi manifest (whether explicitly specified by the user or auto-generated). The default value is false.

This can be useful when debugging an OSGi validation problem or forcing the plugin to load in the container to see which bundles can not be located. However, in most cases the warnings suppressed by this flag indicate actual problems that need to be fixed before the plugin can be successfully installed.

writePropertiesToFile

Enables writing properties used by the plugin to an amps.properties file. This may be useful in some testing scenarios, for example, when an external tool needs to determine which ports have been assigned for the started products. The default value is false.

Here's an example of what the output might look like for a Confluence plugin:

1
2
http.confluence.port=1990
baseurl.confluence=http\://localhost\:1990/confluence
context.path=/confluence
context.confluence.path=/confluence
http.port=1990

platformVersion

Specifies the platform version used to check banned dependencies, defaults to the latest version if not specified.

Example

1
2
<configuration>
   <platformVersion>6.5.4</platformVersion>
...
</configuration>

RELATED TOPICS

Create and Run Traditional Integration Tests

Declaring JNDI Datasources in AMPS