Bring your processes to life by deploying them on an Axon.ivy Engine. Deployment simply means to install an Axon.ivy project on an Axon.ivy Engine. Proceed as follows to deploy a project.
Get a prepared ivy project from your developer.
Deploy the project by e.g. simply dropping the file in the deployment directory.
Check the result of the deployment on the server info page.
Before deployment, the Axon.ivy project must be available as ivy-archive (IAR) or packed as a zip-archive (ZIP). It is also possible to pack multiple Axon.ivy projects in one single zip-archive. All project dependencies must be resolved, either already installed in the application or part of the deployment.
We recommend to build a zip-archive, which contains all projects of an application.
You are able to configure the application within a full application zip-archive. Also, proper versioning is important.
Our file based deployment mechanism makes the deployment very easy, just by dropping the file in the deployment directory, the deployment will be started immediately if the Axon.ivy Engine is running. Otherwise, the deployment is executed when the engine is starting.
There are subdirectories in the deployment directory for each application. The project can be copied to the corresponding subdirectory. It is also possible to create a subdirectory manually. In this case a new application will be created. Alternatively, the project can also be placed in the deployment directory itself. It is then deployed into the application with the same name as the filename.
We strongly recommend to automate the deployment in a CI/CD pipeline. For
this purpose we offer a REST API which is
accessible via HTTP/HTTPS. If you don’t have the possibility to connect to the
Axon.ivy Engine in this way you can use the file based deployment mechanism (e.g.
via SSH) as described above. For both scenarios you can use well-known command
line tools like
scp to build such an automated pipeline.
If you have Maven available in your environment, you can use our
Maven Plugin, which supports both deployment types. If you are
not interested in automation, you can also use the User
Additionally, the deployment behavior can be influenced with deployment options.
Check the results
Go to the server info page, which is by default http://localhost:8080. You should see now your new processes available. If you think there is missing something you better check the deployment logs.
The engine cockpit provides direct feedback on the user interface, the REST API by the HTTP response and the deployment directory creates new files in the same directory where you have dropped the deployment file:
Last deployed file to the engine in case of a successful deployment
Last not deployed file to the engine in case of error while deployment
Contains the log output which is written during the deployment
Contains the error cause and is only written when the deployment fails
To fully automate your CI/CD pipeline, you may want to further configure your target application of your deployment and also influence the deployment behavior.
If you are deploying a full application zip-archive you can optionally add an app.yaml in the root of your zip-archive, which contains the configuration of the application.
1# sample app.yaml which can be part of the full application zip-archive 2StandardProcess: 3 DefaultPages: ch.ivyteam.ivy.project.portal:portalTemplate 4 MailNotification: ch.ivyteam.ivy.project.portal:portalTemplates
This file should always contain configurations which are the same for all
installations of the application or serve as good defaults like configuration of
The reason is that this
app.yaml will be deployed in the root folder of the
application itself and serves as additional configuration for the application
but with a lower priority than the regular app-<APPNAME>.yaml
app-myApp.yaml) in the
It is highly recommended that you increase the version of your project each time you want to deploy a new version of your project on the engine. This ensures that you will not break currently running cases, and you have the possibility to go back to the previous version if the new version does not work as expected.
Even though overwriting an already deployed process model version with running cases is possible. It is at your own risk and should only be done if you are aware of the possible consequences and ready to accept them.
With deployment options you can influence the deployment behavior:
1# Example of a deployment options file using YAML format. 2# See http://axonivy.github.io/project-build-plugin/release/deploy-to-engine-mojo.html for 3# more information about deployment options parameters. 4# All parameters are set to their default values and listed in [brackets]. 5 6# Indicates whether project test users should be deployed to the engine or not. 7deployTestUsers: AUTO # [AUTO], TRUE, FALSE 8 9# Defines how project deployment should affect engine configuration. 10configuration: 11 overwrite: false # [false], true 12 cleanup: DISABLED # [DISABLED], REMOVE_UNUSED, REMOVE_ALL 13 14# Deployment target settings. 15target: 16 version: AUTO # [AUTO], RELEASED, (version values, e.g. 2.5 or (2.0,3.0]) 17 state: ACTIVE_AND_RELEASED # [ACTIVE_AND_RELEASED], ACTIVE, INACTIVE 18 fileFormat: AUTO # [AUTO], PACKED, EXPANDED
See the Axon Ivy Project Build Plugin deploy documentation for more information about the deployment properties.
There are three distinct locations where you can put your options file:
Deployment specific options file - If you want to provide options for a single deployment simply create a file that has the same prefix as the file you want to deploy with a suffix of
.options.yaml. E.g. if the file you want to deploy is
myProject.iarthen create an options file that is called
myProject.iar.options.yaml. Note, that after the deployment the
myProject.iar.options.yamlfile will be removed automatically.
Global options file - Create a file called
deploy.options.yamlin the deployment directory of an application. This global options file control all deployments inside the application.
Inside the file that you are deploying - Put a
deploy.options.yamlfile inside your project directory,
*.zipthat you want to deploy.
If there are multiple options files available, then only the options file with the highest location priority is considered, other options files will be ignored.
The Axon.ivy Engine comes with REST deployment API which can be used to deploy new applications or projects. It can be inspected in the API Reference (http://localhost:8080/ivy/api).
The REST deployment API is makes highly customized deployment chains possible. However, the Engine-Cockpit and the Maven Plugin provide simpler interfaces for well known use-cases.
- POST /system/apps/(applicationName)
Deploy a project
.iarfile or multiple projects in a
.zipfile to an application.
curl -X POST \ http://localhost:8080/ivy/api/system/apps/test \ -u admin:admin \ -H 'X-Requested-By: curl' \ -F fileToDeploy=@/home/user/Documents/Test.zip \ -F deploymentOptionsfirstname.lastname@example.org
14:14:51.708 Info: Start deploying project(s) of file 'Test.iar' to application 'test'. 14:14:51.710 Info: Using DeploymentOptions[overwriteConfiguration=false,cleanupConfiguration=DISABLED,deployTestUsers=FALSE,targetVersion=AUTO,targetState=ACTIVE_AND_RELEASED,targetFileFormat=AUTO] 14:14:51.728 Info: Synchronize project directory ... 14:14:51.729 Info: - Cleaning target archive ... 14:14:51.729 Info: - Copying new project to test/Test/1.zip ... 14:14:51.730 Info: Successful synchronized. 14:14:51.730 Info: Project(s) of file 'test.iar' successful deployed to application 'test' in 22 ms.
applicationName – (required) name of the target application
- Form Parameters
fileToDeploy – (required) project
.iarfile or multiple projects in a
deploymentOptions – (optional; if given the form parameters below are ignored) deployment options as yaml file
deployTestUsers – (optional; ignored if deploymentOptions is given) deploy test users
overwriteConfig – (optional; ignored if deploymentOptions is given) overwrite configuration
cleanupConfig – (optional; ignored if deploymentOptions is given) cleanup configuration
targetVersion – (optional; ignored if deploymentOptions is given) target version
targetState – (optional; ignored if deploymentOptions is given) target state
targetFileFormat – (optional; ignored if deploymentOptions is given) target file format
- Request Headers
Basic Authentication – (required) administrator user and password
X-Requested-By – (required) see REST CSRF Protection
- Status Codes
200 OK – deployment successfully
401 Unauthorized – authorization error
500 Internal Server Error – deployment failed - response contains reason
The Maven project-build-plugin makes automated continuous deployment to an Axon.ivy Engine possible. The Maven plugin can deploy projects file based or via HTTP. The file based mechanism is the default.
For the file based deployment the deployment folder must be available on the same machine on which the build is executed. You may use Windows-Shares or SMB-Configurations.
On the other hand the HTTP deployment is based on the REST API service of the Axon.ivy Engine. For the deployment you need the credentials of an administrator.
Command line deployment
deploy-to-engine goal can be execute on the command line. The
following two examples deploys the project
myProject.iar to the
application portal of the Axon.ivy Engine.
# file based deployment to c:/axonivy/engine mvn com.axonivy.ivy.ci:project-build-plugin:7.4.0-SNAPSHOT:deploy-to-engine \ -Divy.deploy.file=myProject.iar \ -Divy.deploy.engine.dir=c:/axonviy/engine \ -Divy.deploy.engine.app=portal
# http based deployment to http://localhost:8080/ivy # default credentials admin/admin used for demo engine mvn com.axonivy.ivy.ci:project-build-plugin:7.4.0-SNAPSHOT:deploy-to-engine \ -Divy.deploy.file=myProject.iar \ -Divy.deploy.method=HTTP \ -Divy.deploy.engine.url=http://localhost:8080/ivy \ -Divy.deploy.engine.app=portal
The http based deployment method uses the internal REST API rest api.
Goal execution with POM
deploy-to-engine goal can also be executed with a given
The configuration where to deploy the project can then be configured in the
pom.xml snippet deploys the current project to the
application portal of the Axon.ivy Engine at
1<plugin> 2 <groupId>com.axonivy.ivy.ci</groupId> 3 <artifactId>project-build-plugin</artifactId> 4 <extensions>true</extensions> 5 <configuration> 6 <deployToEngineApplication>Portal</deployToEngineApplication> 7 <deployEngineDirectory>c:/axonivy/engine</deployEngineDirectory> 8 </configuration> 9</plugin>
deploy-to-engine goal in the directory where the
pom.xml file is located:
The next example deploys the current project to the application portal to an
Axon.ivy Engine which is accessible at http://localhost:8080. You
need to configure the credentials of an administrator user in the maven
settings.xml file. Your custom defined
serverId must match with
1<plugin> 2 <groupId>com.axonivy.ivy.ci</groupId> 3 <artifactId>project-build-plugin</artifactId> 4 <extensions>true</extensions> 5 <configuration> 6 <deployToEngineApplication>portal</deployToEngineApplication> 7 <deployMethod>HTTP</deployMethod> 8 <deployServerId>serverId</deployServerId> 9 <deployEngineUrl>http://localhost:8080/ivy</deployEngineUrl> 10 </configuration> 11</plugin>
1<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" 2 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 3 xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 https://maven.apache.org/xsd/settings-1.0.0.xsd"> 4 <servers> 5 <server> 6 <id>serverId</id> 7 <username>admin</username> 8 <password>admin</password> 9 </server> 10 </servers> 11</settings>
Bind to Maven Lifecycle
To deploy an ivy-archive (IAR) during it’s maven build lifecycle,
execution which binds the
deploy-to-engine goal to a lifecycle phase.
1<plugin> 2 <groupId>com.axonivy.ivy.ci</groupId> 3 <artifactId>project-build-plugin</artifactId> 4 <extensions>true</extensions> 5 <configuration> 6 <deployToEngineApplication>Portal</deployToEngineApplication> 7 <deployEngineDirectory>c:/axonivy/engine</deployEngineDirectory> 8 </configuration> 9 <executions> 10 <execution> 11 <id>deploy.to.engine</id> 12 <goals><goal>deploy-to-engine</goal></goals> 13 <!-- Bind goal to maven site-deploy phase --> 14 <phase>site-deploy</phase> 15 </execution> 16 </executions> 17</plugin>
Execute the maven lifecycle in the directory where the
pom.xml file is located:
Further examples are documented on GitHub in the project-build-examples repository.