Information on use scenarios of the Apptools Maven Plugin.

You can use the macro either as part of an app project or define an environment with a POM file. This page shows a collection of usage scenarios for the Apptools Maven Plugin.

Online Help

While on the console use the help goal by typing the following:

mvn apptools:help

[INFO] Apptools Maven Plugin
  Tools to manage apps on a Confluence server remotely via the UPM REST API
  based on Maven.

This plugin has 8 goals:

apptools:check-deployed
  Check which apps are deployed on the Confluence server.
  Compare the artifacts on the Confluence server with those on the artifact
  server.

apptools:check-latest
  Check if there are newer versions of the specified apps.
  Compare the artifacts in the local folder with those on the artifact server. *

apptools:deploy
  Deploy apps to the Confluence server.

apptools:enable
  Enable apps on the Confluence server.
  Either specify the apps you want to enable explicitly by their plugin keys
  (using the 'pluginKeys' parameter) or choose to find the keys in the artifacts
  found in the folder specified by the 'sourceFolder' parameter.

apptools:help
  Display help information on apptools-maven-plugin.
  Call mvn apptools:help -Ddetail=true -Dgoal=<goal-name> to display parameter
  details.

apptools:list
  List information on the locally stored artifacts.
  This lists all artifact files in the source folder with the the keys of the
  contained apps.

apptools:undeploy
  Remove deployed apps from the Confluence server.

apptools:usage
  Display usage information on apptools-maven-plugin.

Get detailed information on the parameters of a goal by specifying its name:

mvn apptools:help -Ddetail -Dgoal=help

[INFO] Apptools Maven Plugin
  Tools to manage apps on a Confluence server remotely via the UPM REST API
  based on Maven.

apptools:help
  Display help information on apptools-maven-plugin.
  Call mvn apptools:help -Ddetail=true -Dgoal=<goal-name> to display parameter
  details.

  Available parameters:

    detail (Default: false)
      If true, display all settable properties for each goal.
      User property: detail

    goal
      The name of the goal for which to show help. If unspecified, all goals
      will be displayed.
      User property: goal

    indentSize (Default: 2)
      The number of spaces per indentation level, should be positive.
      User property: indentSize

    lineLength (Default: 80)
      The maximum length of a display line, should be positive.
      User property: lineLength

The example shows the documentation for the help tool. To get information about any other of the goals of this plugin, just replace the name of the help goal in the example above.

You may also use the details parameter to render the parameters with all goals like this:

mvn apptools:help -Ddetail

[INFO] Apptools Maven Plugin
  Tools to manage apps on a Confluence server remotely via the UPM REST API
  based on Maven.

This plugin has 8 goals:

apptools:check-deployed
  Check which apps are deployed on the Confluence server.
  Compare the artifacts on the Confluence server with those on the artifact
  server.

  Available parameters:

    allowSnapshots (Default: true)
      If set to false only releases are considered. Otherwise snapshots are
      taken into account.
      User property: allowSnapshots

    artifactServerId
      The server ID to lookup additional credentials in the settings.xml. This
      is used when wagon needs extra authentication information.
      User property: artifactServerId

    dryRun (Default: false)
      A simple flag to populate the source, but without actually deploying to
      the target.
      User property: dryRun

    excludes
      Strings to match in app key to be excluded. If empty, nothing is excluded.
      Suffix searches are supported by appending the dollar character ($) to the
      include string.
      User property: excludes

    includes
      Strings to match apps keys to be listed. If empty, everything is included.
      Suffix searches are supported by appending the dollar character ($) to the
      include string.
      User property: includes

    password
      The password of the user to authenticate to the remote server.
      User property: password

    rulesUri
      URI of a ruleSet file containing the rules that control how to compare
      version numbers. The URI could be either a Wagon URI or a classpath URI
      (e.g. classpath:///package/sub/package/rules.xml).
      User property: rulesUri

    serverId
      The identifier for the server to fetch credentials in case username or
      password are not set explicitly. The credentials are used to connect to
      the REST API of the remote server.
      User property: serverId

    serverUrl
      The base server URL to locate services. This value is required, and is
      probably set via a profile in case more than one environment is targeted.
      Per convention, profiles containing a environment specific configuration,
      do not contain lower case letters.
      User property: serverUrl

    servicePath (Default: /rest/plugins/1.0/)
      The path to the service on the server.
      User property: servicePath

    settingsSecurityLocation (Default: ${user.home}/.m2/settings-security.xml)
      The location of the settings-security.xml.

    skip (Default: false)
      A simple flag to skip the deployment process.
      User property: skip

    timeoutMs (Default: 5000)
      The timeout in milliseconds for any connection issues accessing the remote
      service.
      User property: timeout

    tokenServicePath (Default: /rest/plugins/1.0/)
      The path to a service to fetch a token on the server.
      User property: tokenServicePath

    username
      The name of the user to authenticate to the remote server.
      User property: username

    verbose (Default: false)
      A simple flag to log verbosely.
      User property: verbose

apptools:check-latest
  Check if there are newer versions of the specified apps.
  Compare the artifacts in the local folder with those on the artifact server. *

  Available parameters:

    allowSnapshots (Default: true)
      If set to false only releases are considered. Otherwise snapshots are
      taken into account.
      User property: allowSnapshots

    artifacts
      List of specification strings to locate artifacts on the artifact server.
      User property: artifacts

    dryRun (Default: false)
      A simple flag to populate the source, but without actually deploying to
      the target.
      User property: dryRun

    rulesUri
      URI of a ruleSet file containing the rules that control how to compare
      version numbers. The URI could be either a Wagon URI or a classpath URI
      (e.g. classpath:///package/sub/package/rules.xml).
      User property: rulesUri

    serverId
      The server ID to lookup additional credentials in the settings.xml. This
      is used when wagon needs extra authentication information.
      User property: artifactServerId

    skip (Default: false)
      A simple flag to skip the deployment process.
      User property: skip

    verbose (Default: false)
      A simple flag to log verbosely.
      User property: verbose

apptools:deploy
  Deploy apps to the Confluence server.

  Available parameters:

    acceptedFilenameExtensions
      Specify the file name extensions to accept.
      User property: acceptedFilenameExtensions

    allowSnapshots (Default: true)
      If set to false only releases are considered. Otherwise snapshots are
      taken into account.
      User property: allowSnapshots

    artifacts
      List of specification strings to locate artifacts on the artifact server
      and download them to the configured source repository.
      User property: artifacts

    artifactServerId
      The server ID to lookup additional credentials in the settings.xml. This
      is used when wagon needs extra authentication information.
      User property: artifactServerId

    checkEnablement
      Specify the apps that need to be checked to be successfully enabled.
      User property: check

    checkerServicePath (Default: /rest/plugins/1.0/enablement-state/)
      The path to the checker service to check the status of a deployed app on
      the server.
      User property: checkerServicePath

    checkMaxCount (Default: 5)
      Specify the number of times should be conducted. The total wait for a
      finally failed enablement check would be checkWaitMs times checkMaxCount
      milliseconds.
      User property: checkMaxCount

    checkWaitMs (Default: 3000)
      Specify the time the enablement check should wait if failed.
      User property: checkWait

    dryRun (Default: false)
      A simple flag to populate the source, but without actually deploying to
      the target.
      User property: dryRun

    excludes
      Strings to match in app file names for exclusion. If empty, nothing is
      excluded. Suffix searches are supported by appending the dollar character
      ($) to the include string.
      User property: excludes

    failOnNonEmptySourceFolder (Default: true)
      If the source folder is not empty, the build will be terminated with an
      fail message. This prevents the user to deploy artifacts in an existing
      folder.
      User property: failOnNonEmptySourceFolder

    includes
      Strings to match in app file names for inclusion. If empty, everything is
      included. Suffix searches are supported by appending the dollar character
      ($) to the include string.
      User property: includes

    order
      Allows to impose a sort order on the list of artifacts to be deployed. The
      list represents stages (1, 2, 3, ...) that will deploy all matching
      artifacts.
      User property: order

    password
      The password of the user to authenticate to the remote server.
      User property: password

    rulesUri
      URI of a ruleSet file containing the rules that control how to compare
      version numbers. The URI could be either a Wagon URI or a classpath URI
      (e.g. classpath:///package/sub/package/rules.xml).
      User property: rulesUri

    serverId
      The identifier for the server to fetch credentials in case username or
      password are not set explicitly. The credentials are used to connect to
      the REST API of the remote server.
      User property: serverId

    serverUrl
      The base server URL to locate services. This value is required, and is
      probably set via a profile in case more than one environment is targeted.
      Per convention, profiles containing a environment specific configuration,
      do not contain lower case letters.
      User property: serverUrl

    servicePath (Default: /rest/plugins/1.0/)
      The path to the service on the server.
      User property: servicePath

    settingsSecurityLocation (Default: ${user.home}/.m2/settings-security.xml)
      The location of the settings-security.xml.

    skip (Default: false)
      A simple flag to skip the deployment process.
      User property: skip

    sourceFolder (Default: target/apps)
      The folder with application files to process.
      User property: source

    timeoutMs (Default: 5000)
      The timeout in milliseconds for any connection issues accessing the remote
      service.
      User property: timeout

    tokenServicePath (Default: /rest/plugins/1.0/)
      The path to a service to fetch a token on the server.
      User property: tokenServicePath

    useLatest
      Override any specified versions in the POM with the latest version. Use
      SNAPSHOT for the latest snapshot release, RELEASE for the latest public
      release.
      User property: useLatest

    username
      The name of the user to authenticate to the remote server.
      User property: username

    verbose (Default: false)
      A simple flag to log verbosely.
      User property: verbose

apptools:enable
  Enable apps on the Confluence server.
  Either specify the apps you want to enable explicitly by their plugin keys
  (using the 'pluginKeys' parameter) or choose to find the keys in the artifacts
  found in the folder specified by the 'sourceFolder' parameter.

  Available parameters:

    acceptedFilenameExtensions
      Specify the file name extensions to accept.
      User property: acceptedFilenameExtensions

    allowSnapshots (Default: true)
      If set to false only releases are considered. Otherwise snapshots are
      taken into account.
      User property: allowSnapshots

    artifacts
      List of specification strings to locate artifacts on the artifact server
      and download them to the configured source repository.
      User property: artifacts

    artifactServerId
      The server ID to lookup additional credentials in the settings.xml. This
      is used when wagon needs extra authentication information.
      User property: artifactServerId

    deployedAppsServicePath (Default: /rest/plugins/1.0/monitor/installed)
      The path to the service on the server to check which apps are deployed.
      User property: deployedAppsServicePath

    dryRun (Default: false)
      A simple flag to populate the source, but without actually deploying to
      the target.
      User property: dryRun

    excludes
      Strings to match in app file names for exclusion. If empty, nothing is
      excluded. Suffix searches are supported by appending the dollar character
      ($) to the include string.
      User property: excludes

    failOnNonEmptySourceFolder (Default: true)
      If the source folder is not empty, the build will be terminated with an
      fail message. This prevents the user to deploy artifacts in an existing
      folder.
      User property: failOnNonEmptySourceFolder

    includes
      Strings to match in app file names for inclusion. If empty, everything is
      included. Suffix searches are supported by appending the dollar character
      ($) to the include string.
      User property: includes

    mode (Default: LOCAL)
      Specify whether to extract keys from the local artifacts (LOCAL), fetch
      keys from the remote server (REMOTE) or both (BOTH). Note that includes
      and excludes are applied in either case.
      User property: mode

    order
      Allows to impose a sort order on the list of artifacts to be deployed. The
      list represents stages (1, 2, 3, ...) that will deploy all matching
      artifacts.
      User property: order

    password
      The password of the user to authenticate to the remote server.
      User property: password

    pluginKeys
      List of key for plugins to enable. If plugins are explicitly specified,
      local artifacts in the source folder are not checked.
      User property: pluginKeys

    rulesUri
      URI of a ruleSet file containing the rules that control how to compare
      version numbers. The URI could be either a Wagon URI or a classpath URI
      (e.g. classpath:///package/sub/package/rules.xml).
      User property: rulesUri

    serverId
      The identifier for the server to fetch credentials in case username or
      password are not set explicitly. The credentials are used to connect to
      the REST API of the remote server.
      User property: serverId

    serverUrl
      The base server URL to locate services. This value is required, and is
      probably set via a profile in case more than one environment is targeted.
      Per convention, profiles containing a environment specific configuration,
      do not contain lower case letters.
      User property: serverUrl

    servicePath (Default: /rest/plugins/1.0/enablement-state/)
      The path to the service on the server.
      User property: servicePath

    settingsSecurityLocation (Default: ${user.home}/.m2/settings-security.xml)
      The location of the settings-security.xml.

    skip (Default: false)
      A simple flag to skip the deployment process.
      User property: skip

    sourceFolder (Default: target/apps)
      The folder with application files to process.
      User property: source

    timeoutMs (Default: 5000)
      The timeout in milliseconds for any connection issues accessing the remote
      service.
      User property: timeout

    tokenServicePath (Default: /rest/plugins/1.0/)
      The path to a service to fetch a token on the server.
      User property: tokenServicePath

    useLatest
      Override any specified versions in the POM with the latest version. Use
      SNAPSHOT for the latest snapshot release, RELEASE for the latest public
      release.
      User property: useLatest

    username
      The name of the user to authenticate to the remote server.
      User property: username

    verbose (Default: false)
      A simple flag to log verbosely.
      User property: verbose

apptools:help
  Display help information on apptools-maven-plugin.
  Call mvn apptools:help -Ddetail=true -Dgoal=<goal-name> to display parameter
  details.

  Available parameters:

    detail (Default: false)
      If true, display all settable properties for each goal.
      User property: detail

    goal
      The name of the goal for which to show help. If unspecified, all goals
      will be displayed.
      User property: goal

    indentSize (Default: 2)
      The number of spaces per indentation level, should be positive.
      User property: indentSize

    lineLength (Default: 80)
      The maximum length of a display line, should be positive.
      User property: lineLength

apptools:list
  List information on the locally stored artifacts.
  This lists all artifact files in the source folder with the the keys of the
  contained apps.

  Available parameters:

    acceptedFilenameExtensions
      Specify the file name extensions to accept.
      User property: acceptedFilenameExtensions

    allowSnapshots (Default: true)
      If set to false only releases are considered. Otherwise snapshots are
      taken into account.
      User property: allowSnapshots

    artifacts
      List of specification strings to locate artifacts on the artifact server
      and download them to the configured source repository.
      User property: artifacts

    artifactServerId
      The server ID to lookup additional credentials in the settings.xml. This
      is used when wagon needs extra authentication information.
      User property: artifactServerId

    dryRun (Default: false)
      A simple flag to populate the source, but without actually deploying to
      the target.
      User property: dryRun

    excludes
      Strings to match in app file names for exclusion. If empty, nothing is
      excluded. Suffix searches are supported by appending the dollar character
      ($) to the include string.
      User property: excludes

    failOnNonEmptySourceFolder (Default: true)
      If the source folder is not empty, the build will be terminated with an
      fail message. This prevents the user to deploy artifacts in an existing
      folder.
      User property: failOnNonEmptySourceFolder

    includes
      Strings to match in app file names for inclusion. If empty, everything is
      included. Suffix searches are supported by appending the dollar character
      ($) to the include string.
      User property: includes

    order
      Allows to impose a sort order on the list of artifacts to be deployed. The
      list represents stages (1, 2, 3, ...) that will deploy all matching
      artifacts.
      User property: order

    password
      The password of the user to authenticate to the remote server.
      User property: password

    rulesUri
      URI of a ruleSet file containing the rules that control how to compare
      version numbers. The URI could be either a Wagon URI or a classpath URI
      (e.g. classpath:///package/sub/package/rules.xml).
      User property: rulesUri

    serverId
      The identifier for the server to fetch credentials in case username or
      password are not set explicitly. The credentials are used to connect to
      the REST API of the remote server.
      User property: serverId

    serverUrl
      The base server URL to locate services. This value is required, and is
      probably set via a profile in case more than one environment is targeted.
      Per convention, profiles containing a environment specific configuration,
      do not contain lower case letters.
      User property: serverUrl

    settingsSecurityLocation (Default: ${user.home}/.m2/settings-security.xml)
      The location of the settings-security.xml.

    skip (Default: false)
      A simple flag to skip the deployment process.
      User property: skip

    sourceFolder (Default: target/apps)
      The folder with application files to process.
      User property: source

    timeoutMs (Default: 5000)
      The timeout in milliseconds for any connection issues accessing the remote
      service.
      User property: timeout

    tokenServicePath (Default: /rest/plugins/1.0/)
      The path to a service to fetch a token on the server.
      User property: tokenServicePath

    useLatest
      Override any specified versions in the POM with the latest version. Use
      SNAPSHOT for the latest snapshot release, RELEASE for the latest public
      release.
      User property: useLatest

    username
      The name of the user to authenticate to the remote server.
      User property: username

    verbose (Default: false)
      A simple flag to log verbosely.
      User property: verbose

apptools:undeploy
  Remove deployed apps from the Confluence server.

  Available parameters:

    acceptedFilenameExtensions
      Specify the file name extensions to accept.
      User property: acceptedFilenameExtensions

    allowSnapshots (Default: true)
      If set to false only releases are considered. Otherwise snapshots are
      taken into account.
      User property: allowSnapshots

    artifacts
      List of specification strings to locate artifacts on the artifact server
      and download them to the configured source repository.
      User property: artifacts

    artifactServerId
      The server ID to lookup additional credentials in the settings.xml. This
      is used when wagon needs extra authentication information.
      User property: artifactServerId

    deployedAppsServicePath (Default: /rest/plugins/1.0/monitor/installed)
      The path to the service on the server to check which apps are deployed.
      User property: deployedAppsServicePath

    dryRun (Default: false)
      A simple flag to populate the source, but without actually deploying to
      the target.
      User property: dryRun

    excludes
      Strings to match in app file names for exclusion. If empty, nothing is
      excluded. Suffix searches are supported by appending the dollar character
      ($) to the include string.
      User property: excludes

    failOnNonEmptySourceFolder (Default: true)
      If the source folder is not empty, the build will be terminated with an
      fail message. This prevents the user to deploy artifacts in an existing
      folder.
      User property: failOnNonEmptySourceFolder

    includes
      Strings to match in app file names for inclusion. If empty, everything is
      included. Suffix searches are supported by appending the dollar character
      ($) to the include string.
      User property: includes

    mode (Default: LOCAL)
      Specify whether to extract keys from the local artifacts (LOCAL), fetch
      keys from the remote server (REMOTE) or both (BOTH). Note that includes
      and excludes are applied in either case.
      User property: mode

    order
      Allows to impose a sort order on the list of artifacts to be deployed. The
      list represents stages (1, 2, 3, ...) that will deploy all matching
      artifacts.
      User property: order

    password
      The password of the user to authenticate to the remote server.
      User property: password

    pluginKeys
      List of key for plugins to remove.
      User property: pluginKeys

    rulesUri
      URI of a ruleSet file containing the rules that control how to compare
      version numbers. The URI could be either a Wagon URI or a classpath URI
      (e.g. classpath:///package/sub/package/rules.xml).
      User property: rulesUri

    serverId
      The identifier for the server to fetch credentials in case username or
      password are not set explicitly. The credentials are used to connect to
      the REST API of the remote server.
      User property: serverId

    serverUrl
      The base server URL to locate services. This value is required, and is
      probably set via a profile in case more than one environment is targeted.
      Per convention, profiles containing a environment specific configuration,
      do not contain lower case letters.
      User property: serverUrl

    servicePath (Default: /rest/plugins/1.0/${plugin.key}-key)
      The path to the service on the server.
      User property: servicePath

    settingsSecurityLocation (Default: ${user.home}/.m2/settings-security.xml)
      The location of the settings-security.xml.

    skip (Default: false)
      A simple flag to skip the deployment process.
      User property: skip

    sourceFolder (Default: target/apps)
      The folder with application files to process.
      User property: source

    timeoutMs (Default: 5000)
      The timeout in milliseconds for any connection issues accessing the remote
      service.
      User property: timeout

    tokenServicePath (Default: /rest/plugins/1.0/)
      The path to a service to fetch a token on the server.
      User property: tokenServicePath

    useLatest
      Override any specified versions in the POM with the latest version. Use
      SNAPSHOT for the latest snapshot release, RELEASE for the latest public
      release.
      User property: useLatest

    username
      The name of the user to authenticate to the remote server.
      User property: username

    verbose (Default: false)
      A simple flag to log verbosely.
      User property: verbose

apptools:usage
  Display usage information on apptools-maven-plugin.

  Available parameters:

The usage shows some essential use cases and provides pointers to more information found online on our server:

mvn apptools:usage

[INFO] Usage information for the Apptools Maven Plugin
=== Detailed Descriptions ===
Use
   apptools:help
to list all available goals.
Use
   apptools:help -Ddetail -Dgoal=<goal-name>
to fetch more detailed information on a particular goal.

=== General tips ===
 G1. Use Dry Run:
   If you are unsure what will happen, use -DdryRun.
 G2. Select:
   Use -Dincludes=aaa,bbb,ccc and -Dexcludes=aaaa,bbbb to select on artifacts or depoyed apps.
 G3. More chatty?
   Use -Dverbose to get more on INFO level, use -X to get DEBUG information.

=== Tips for App Projects ===
Find more information online: https://www.smartics.eu/confluence/x/FwCiBg
 A1. Deploy local Artifact:
   Use apptools:deploy -P<DESTINATION> to deploy the artifact in the target folder to the DESTINATION specified by a profile.
 A2. Check version:
   Use apptools:check-deployed -P<DESTINATION> to check the deployed version on the DESTINATION specified by a profile.

=== Tips for POM Projects ===
Find more information online: https://www.smartics.eu/confluence/x/HQCiBg
 P1. Download artifacts locally:
   The plugin deploys artifacts from a local directory. Use 'mvn clean' to start with an empty folder.
 P2. Check latest versions:
   Use -DuseLatest=RELEASE or -DuseLatest=SNAPSHOT to override the configured version with the latest release or snapshot version.

Find more information online:
   https://www.smartics.eu/confluence/x/twF8Bg

Use Cases

While on Plugin Documentation you see a list of a goals and can access information on all supported parameters, the following use cases go into a little more detail on how particular goals can be used in common use cases.

Use in App Project: Shows how to add the Apptools Maven Plugin to your Confluence add-on project.
Use in POM Project: Shows how to use the Apptools Maven Plugin in a separate POM project.
Display Configurations: Shows how to use the Apptools Maven Plugin to display information about apps on the Confluence server, the artifact server, or the local source folder.
Manage Configurations: Shows how to use the Apptools Maven Plugin to manage apps on a Confluence server, including deployment, undeployment, and enablement.
Unique Snapshot Versions: Shows how the Apptools Maven Plugin supports Unique Snapshot Versions.

Live Examples

We use the Apptools Maven Plugin in our own projects.

For a live example see the POM of the Core Doctypes on Bitbucket.

Space shortcuts

Page tree

Docs

Support

Free Blueprints

Tooling for Blueprints

Free Extensions

Spaces

Plugins for Maven

Incubator

Libraries for Java

Incubator

Add-ons for Confluence

Tools

Support

Team

Legal

Online Help

Use Cases

About

Keep up-to-date!

Powered by