Fork me on GitHub

project-build:deploy-to-engine

Full name:

com.axonivy.ivy.ci:project-build-plugin:7.1.0:deploy-to-engine

Description:

Deploys a single project (iar) or a full application (set of projects as zip) to a running AXON.IVY Engine.

Command line invocation is supported. E.g.

mvn com.axonivy.ivy.ci:project-build-plugin:7.1.0:deploy-to-engine
-Divy.deploy.file=myProject.iar
-Divy.deploy.engine.dir=c:/axonivy/engine
-Divy.deploy.engine.app=Portal

Attributes:

  • Since version: 7.1.0.

Required Parameters

Name Type Since Description
ivyVersion String 7.1.0 The ivy Engine version or version-range that must be used. Must be equal or higher than MINIMAL_COMPATIBLE_VERSION Examples:
  • "6.1.2" means ivyVersion = 6.1.2
  • "[6.1.0,7.0.0)" means 6.1.0 <= ivyVersion < 7.0.0
  • "(6.0.0,]" means ivyVersion > 6.0.0

Default value is: 7.1.0.
User property is: ivy.engine.version.

Optional Parameters

Name Type Since Description
deployConfigCleanup String 7.1.0 Controls whether all configurations (global variables, external database, web services, REST clients) should be cleaned.

Possible values:

  • DISABLED: all configurations will be kept on the application.
  • REMOVE_UNUSED: all configurations that are not used by any projects deployed on the application will be removed after the deployment.
  • REMOVE_ALL: all configurations of the application are removed before the deployment.
    Should only be used for development or test engines.
    Do not use in productive systems because it could break already deployed projects!

Default value is: DISABLED.
User property is: ivy.deploy.configuration.cleanup.
deployConfigOverwrite boolean 7.1.0 If set to true then configurations (global variables, external database, web services, REST clients) defined in the deployed projects overwrite the configurations that are already configured on the engine.
Default value is: false.
User property is: ivy.deploy.configuration.overwrite.
deployDirectory String 7.1.0 The auto deployment directory of the engine. Must match the ivy engine system property 'deployment.directory'
Default value is: deploy.
User property is: ivy.deploy.dir.
deployEngineDirectory File 7.1.0 The path to the AXON.IVY Engine to which we deploy the file.
The path can reference a remote engine by using UNC paths e.g. \\myRemoteHost\myEngineShare
Default value is: ${ivy.engine.directory}.
User property is: ivy.deploy.engine.dir.
deployFile File 7.1.0 The file to deploy. Can either be a *.iar project file or a *.zip file containing a full application (set of projects). By default the packed IAR from the IarPackagingMojo.GOAL is used.
Default value is: ${project.build.directory}/${project.artifactId}-${project.version}.iar.
User property is: ivy.deploy.file.
deployOptionsFile File 7.1.0 The file that contains deployment options.
Example options file content:

deployTestUsers: true
configuration:
 overwrite: true
 cleanup: REMOVE_UNUSED
target:
 version: RELEASED
 state: ACTIVE_AND_RELEASED

Inside the options file you can use property placeholders. The options file may look like this:


deployTestUsers: ${ivy.deploy.test.users}
configuration:
 overwrite: true
 cleanup: REMOVE_UNUSED
target:
 version: AUTO
 state: ${ivy.deploy.target.state}

All options in this file are optional. You only need to specify options that overwrite the default behavior.

If configured, all Maven properties are ignored and only values in this file are used.


User property is: ivy.deploy.options.file.
deployTargetFileFormat String 7.1.0 The target file format as which the project will be deployed into the process model version (PMV).
  • AUTO: Keep the format of the origin project file if possible. Deploys IAR or ZIP projects into a ZIP process model version.
    But if the target PMV already exists as expanded directory, the new version will be expanded as well.
  • PACKED: Enforce the deployment of a project as zipped file. Normal (expanded) project directories will be compressed into a ZIP during deployment.
  • EXPANDED: Enforce the deployment of a project as expanded file directory.
    This is recommended for projects that change the project files at runtime. E.g. projects that use the Content Management (CMS) write API.
    The expanded format behaves exactly like projects deployed with Axon.ivy 7.0 or older. You might choose to deploy expanded projects in order to avoid ReadOnlyFileSystemException at runtime.
    Warning: Expanded projects will perform slower at runtime and are therefore not recommended.

Default value is: AUTO.
User property is: ivy.deploy.target.file.format.
deployTargetState String 7.1.0 The target state of all process model versions (PMVs) of the deployed projects.
  • ACTIVE_AND_RELEASED: PMVs are activated and released after the deployment
  • ACTIVE: PMVs are activated but not released after the deployment
  • INACTIVE: PMVs are neither activated nor released after the deployment

Default value is: ACTIVE_AND_RELEASED.
User property is: ivy.deploy.target.state.
deployTargetVersion String 7.1.0 The target version controls on which process model version (PMV) a project is re-deployed.

Matching:

  • In all cases the library identifier (group id and project/artifact id) of the PMV and the project has to be equal.
  • If multiple PMVs match the target version then the PMV with the highest library version is chosen.
  • If no PMV matches the target version then a new PMV is created and the project is deployed to the new PMV.

Possible values:

  • AUTO: a project is re-deployed if the version of the PMV is equal to the project's version.
  • RELEASED: a project is re-deployed to the released PMV. The version of the PMV and the project does not matter
  • Maven version range: a project is re-deployed if the version of the PMV matches the given range. Some samples:
    • , - Matches all version.
    • ,2.5] - Matches every version up to 2.5 inclusive.
    • (2.5, - Matches every version from 2.5 exclusive.
    • [2.0,3.0) - Matches every version from 2.0 inclusive up to 3.0 exclusive.
    • 2.5 - Matches every version from 2.5 inclusive.

Default value is: AUTO.
User property is: ivy.deploy.target.version.
deployTestUsers boolean 7.1.0 If set to true then test users defined in the projects are deployed to the engine. Only works if the current security system allows to create users. Should only be used for testing.
Default value is: false.
User property is: ivy.deploy.test.users.
deployTimeoutInSeconds Integer 7.1.0 The maximum amount of seconds that we wait for a deployment result from the engine
Default value is: 30.
User property is: ivy.deploy.timeout.seconds.
deployToEngineApplication String 7.1.0 The name of an ivy application to which the file is deployed.
Default value is: SYSTEM.
User property is: ivy.deploy.engine.app.
engineCacheDirectory File 7.1.0 Location where ivy engines in required version can be extracted to.

If the Engine does not yet exist, it can be automatically downloaded.


Default value is: ${settings.localRepository}/.cache/ivy.
User property is: ivy.engine.cache.directory.
engineDirectory File 7.1.0 Location where an unpacked (may pre-configured) ivy Engine in the required version exists.

If parameter is not set it will be a sub-directory of the engineCacheDirectory.

If the Engine does not yet exist, it can be automatically downloaded.


User property is: ivy.engine.directory.
skipDeploy boolean 7.1.0 Set to true to skip the deployment to the engine.
Default value is: false.
User property is: ivy.deploy.skip.

Parameter Details

deployConfigCleanup:

Controls whether all configurations (global variables, external database, web services, REST clients) should be cleaned.

Possible values:

  • DISABLED: all configurations will be kept on the application.
  • REMOVE_UNUSED: all configurations that are not used by any projects deployed on the application will be removed after the deployment.
  • REMOVE_ALL: all configurations of the application are removed before the deployment.
    Should only be used for development or test engines.
    Do not use in productive systems because it could break already deployed projects!
  • Type: java.lang.String
  • Since: 7.1.0
  • Required: No
  • User Property: ivy.deploy.configuration.cleanup
  • Default: DISABLED

deployConfigOverwrite:

If set to true then configurations (global variables, external database, web services, REST clients) defined in the deployed projects overwrite the configurations that are already configured on the engine.
  • Type: boolean
  • Since: 7.1.0
  • Required: No
  • User Property: ivy.deploy.configuration.overwrite
  • Default: false

deployDirectory:

The auto deployment directory of the engine. Must match the ivy engine system property 'deployment.directory'
  • Type: java.lang.String
  • Since: 7.1.0
  • Required: No
  • User Property: ivy.deploy.dir
  • Default: deploy

deployEngineDirectory:

The path to the AXON.IVY Engine to which we deploy the file.
The path can reference a remote engine by using UNC paths e.g. \\myRemoteHost\myEngineShare
  • Type: java.io.File
  • Since: 7.1.0
  • Required: No
  • User Property: ivy.deploy.engine.dir
  • Default: ${ivy.engine.directory}

deployFile:

The file to deploy. Can either be a *.iar project file or a *.zip file containing a full application (set of projects). By default the packed IAR from the IarPackagingMojo.GOAL is used.
  • Type: java.io.File
  • Since: 7.1.0
  • Required: No
  • User Property: ivy.deploy.file
  • Default: ${project.build.directory}/${project.artifactId}-${project.version}.iar

deployOptionsFile:

The file that contains deployment options.
Example options file content:

deployTestUsers: true
configuration:
 overwrite: true
 cleanup: REMOVE_UNUSED
target:
 version: RELEASED
 state: ACTIVE_AND_RELEASED

Inside the options file you can use property placeholders. The options file may look like this:


deployTestUsers: ${ivy.deploy.test.users}
configuration:
 overwrite: true
 cleanup: REMOVE_UNUSED
target:
 version: AUTO
 state: ${ivy.deploy.target.state}

All options in this file are optional. You only need to specify options that overwrite the default behavior.

If configured, all Maven properties are ignored and only values in this file are used.

  • Type: java.io.File
  • Since: 7.1.0
  • Required: No
  • User Property: ivy.deploy.options.file

deployTargetFileFormat:

The target file format as which the project will be deployed into the process model version (PMV).
  • AUTO: Keep the format of the origin project file if possible. Deploys IAR or ZIP projects into a ZIP process model version.
    But if the target PMV already exists as expanded directory, the new version will be expanded as well.
  • PACKED: Enforce the deployment of a project as zipped file. Normal (expanded) project directories will be compressed into a ZIP during deployment.
  • EXPANDED: Enforce the deployment of a project as expanded file directory.
    This is recommended for projects that change the project files at runtime. E.g. projects that use the Content Management (CMS) write API.
    The expanded format behaves exactly like projects deployed with Axon.ivy 7.0 or older. You might choose to deploy expanded projects in order to avoid ReadOnlyFileSystemException at runtime.
    Warning: Expanded projects will perform slower at runtime and are therefore not recommended.
  • Type: java.lang.String
  • Since: 7.1.0
  • Required: No
  • User Property: ivy.deploy.target.file.format
  • Default: AUTO

deployTargetState:

The target state of all process model versions (PMVs) of the deployed projects.
  • ACTIVE_AND_RELEASED: PMVs are activated and released after the deployment
  • ACTIVE: PMVs are activated but not released after the deployment
  • INACTIVE: PMVs are neither activated nor released after the deployment
  • Type: java.lang.String
  • Since: 7.1.0
  • Required: No
  • User Property: ivy.deploy.target.state
  • Default: ACTIVE_AND_RELEASED

deployTargetVersion:

The target version controls on which process model version (PMV) a project is re-deployed.

Matching:

  • In all cases the library identifier (group id and project/artifact id) of the PMV and the project has to be equal.
  • If multiple PMVs match the target version then the PMV with the highest library version is chosen.
  • If no PMV matches the target version then a new PMV is created and the project is deployed to the new PMV.

Possible values:

  • AUTO: a project is re-deployed if the version of the PMV is equal to the project's version.
  • RELEASED: a project is re-deployed to the released PMV. The version of the PMV and the project does not matter
  • Maven version range: a project is re-deployed if the version of the PMV matches the given range. Some samples:
    • , - Matches all version.
    • ,2.5] - Matches every version up to 2.5 inclusive.
    • (2.5, - Matches every version from 2.5 exclusive.
    • [2.0,3.0) - Matches every version from 2.0 inclusive up to 3.0 exclusive.
    • 2.5 - Matches every version from 2.5 inclusive.
  • Type: java.lang.String
  • Since: 7.1.0
  • Required: No
  • User Property: ivy.deploy.target.version
  • Default: AUTO

deployTestUsers:

If set to true then test users defined in the projects are deployed to the engine. Only works if the current security system allows to create users. Should only be used for testing.
  • Type: boolean
  • Since: 7.1.0
  • Required: No
  • User Property: ivy.deploy.test.users
  • Default: false

deployTimeoutInSeconds:

The maximum amount of seconds that we wait for a deployment result from the engine
  • Type: java.lang.Integer
  • Since: 7.1.0
  • Required: No
  • User Property: ivy.deploy.timeout.seconds
  • Default: 30

deployToEngineApplication:

The name of an ivy application to which the file is deployed.
  • Type: java.lang.String
  • Since: 7.1.0
  • Required: No
  • User Property: ivy.deploy.engine.app
  • Default: SYSTEM

engineCacheDirectory:

Location where ivy engines in required version can be extracted to.

If the Engine does not yet exist, it can be automatically downloaded.

  • Type: java.io.File
  • Since: 7.1.0
  • Required: No
  • User Property: ivy.engine.cache.directory
  • Default: ${settings.localRepository}/.cache/ivy

engineDirectory:

Location where an unpacked (may pre-configured) ivy Engine in the required version exists.

If parameter is not set it will be a sub-directory of the engineCacheDirectory.

If the Engine does not yet exist, it can be automatically downloaded.

  • Type: java.io.File
  • Since: 7.1.0
  • Required: No
  • User Property: ivy.engine.directory

ivyVersion:

The ivy Engine version or version-range that must be used. Must be equal or higher than MINIMAL_COMPATIBLE_VERSION Examples:
  • "6.1.2" means ivyVersion = 6.1.2
  • "[6.1.0,7.0.0)" means 6.1.0 <= ivyVersion < 7.0.0
  • "(6.0.0,]" means ivyVersion > 6.0.0
  • Type: java.lang.String
  • Since: 7.1.0
  • Required: Yes
  • User Property: ivy.engine.version
  • Default: 7.1.0

skipDeploy:

Set to true to skip the deployment to the engine.
  • Type: boolean
  • Since: 7.1.0
  • Required: No
  • User Property: ivy.deploy.skip
  • Default: false