Go to start of metadata
- Created by Robert Reiner, last modified on 11. Mar 2019
You are viewing an old version of this page. View the current version.
Compare with Current View Page History
« Previous Version 8 Next »
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 Expand source
[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 Expand source
[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 Expand source
[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 Expand source
[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.
- No labels
