Fork me on GitHub
Built by Maven

ivy:deploy-to-engine

Full name:

com.axonivy.ivy.ci:project-build-plugin:8.0.7: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.

Local engine (using DIRECTORY deploy method):

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

Remote Engine (using HTTP deploy method):

mvn com.axonivy.ivy.ci:project-build-plugin:8.0.0:deploy-to-engine 
-Divy.deploy.file=myProject.iar 
-Divy.deploy.method=HTTP 
-Divy.deploy.server.id=AxonIvyEngine
-Divy.deploy.engine.url=http://ivyhost:8080/ivy 
-Divy.deploy.engine.app=portal

Attributes:

  • Since version: 7.1.0.

Required Parameters

Name Type Since Description
<deployToEngineApplication> String 7.1.0 The name of an ivy application to which the file is deployed.
User property is: ivy.deploy.engine.app.
<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: 8.0.26.
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.
<deployEngineUrl> String 7.4 Engine url for deployment over HTTP or HTTPS
Default value is: http://localhost:8080/ivy.
User property is: ivy.deploy.engine.url.
<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.
<deployMethod> String 7.4 The deploy method

Possible values:

  • DIRECTORY: use filesystem to deploy to local engine
  • HTTP: use HTTP or HTTPS to deploy to a remote engine

Default value is: DIRECTORY.
User property is: ivy.deploy.method.
<deployOptionsFile> File 7.1.0 The file that contains deployment options.
Example options file content: 

deployTestUsers: auto
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.
<deployServerId> String 7.4 Id of server configured in settings.xml that specifies the administrator user name and password used to authenticate in case of HTTP deployment. If you're using an encrypted maven password with a settings-security.xml, you may need to define the location of this file with the property 'settings.security' (default location is ~/.settings-security.xml)
User property is: ivy.deploy.server.id.
<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> String 7.1.0 If set to true then test users defined in the projects are deployed to the engine. If set to auto then test users will only deployed when engine runs in demo mode. Should only be used for testing.

This option is only in charge if security system is set to Ivy Security System. This means if the security system is Active Directory or Novell eDirectory test users will never deployed.


Default value is: AUTO.
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.
<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.
<testEngine> String 8.0.4 Configure if the test engine gets copied to the maven target folder. With this you can start each test cycle with a clean engine. Integration tests may leave resources like deployed projects behind which may lead to unwanted side effects on the next test cycle.
  • COPY_FROM_CACHE = copy the engine if it comes from the engineCacheDirectory.
  • MODIFY_EXISTING = don't copy the engine, this could lead to unforeseen behaviour if the same engine is used multiple times.
  • COPY_FROM_TEMPLATE = always copy the engine. If you have a preconfigured engine in the engineDirectory it will be copied as well.
    • Note: that we advise you to move the configuration of such engine to the build cycle itself instead of using a preconfigured one.

Default value is: COPY_FROM_CACHE.
User property is: ivy.test.engine.

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}

<deployEngineUrl>

Engine url for deployment over HTTP or HTTPS
  • Type: java.lang.String
  • Since: 7.4
  • Required: No
  • User Property: ivy.deploy.engine.url
  • Default: http://localhost:8080/ivy

<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

<deployMethod>

The deploy method

Possible values:

  • DIRECTORY: use filesystem to deploy to local engine
  • HTTP: use HTTP or HTTPS to deploy to a remote engine
  • Type: java.lang.String
  • Since: 7.4
  • Required: No
  • User Property: ivy.deploy.method
  • Default: DIRECTORY

<deployOptionsFile>

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

deployTestUsers: auto
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

<deployServerId>

Id of server configured in settings.xml that specifies the administrator user name and password used to authenticate in case of HTTP deployment. If you're using an encrypted maven password with a settings-security.xml, you may need to define the location of this file with the property 'settings.security' (default location is ~/.settings-security.xml)
  • Type: java.lang.String
  • Since: 7.4
  • Required: No
  • User Property: ivy.deploy.server.id

<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. If set to auto then test users will only deployed when engine runs in demo mode. Should only be used for testing.

This option is only in charge if security system is set to Ivy Security System. This means if the security system is Active Directory or Novell eDirectory test users will never deployed.

  • Type: java.lang.String
  • Since: 7.1.0
  • Required: No
  • User Property: ivy.deploy.test.users
  • Default: AUTO

<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: Yes
  • User Property: ivy.deploy.engine.app

<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: 8.0.26

<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

<testEngine>

Configure if the test engine gets copied to the maven target folder. With this you can start each test cycle with a clean engine. Integration tests may leave resources like deployed projects behind which may lead to unwanted side effects on the next test cycle.
  • COPY_FROM_CACHE = copy the engine if it comes from the engineCacheDirectory.
  • MODIFY_EXISTING = don't copy the engine, this could lead to unforeseen behaviour if the same engine is used multiple times.
  • COPY_FROM_TEMPLATE = always copy the engine. If you have a preconfigured engine in the engineDirectory it will be copied as well.
    • Note: that we advise you to move the configuration of such engine to the build cycle itself instead of using a preconfigured one.
  • Type: java.lang.String
  • Since: 8.0.4
  • Required: No
  • User Property: ivy.test.engine
  • Default: COPY_FROM_CACHE