Administration

Deployment

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. Our file based deployment mechanism makes the deployment very easy, just by dropping the file at the right place. This mechanism is perfectly suitable for a CI/CD pipeline and forms the basis for the deployment feature of our maven plugin.

  1. Get a prepared ivy project from your developer.

  2. Deploy the project by simply dropping the file in the deployment directory.

  3. Check the result of the deployment on the server info page.

Prepare

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.

Sample full application zip-archive

Figure 7.1. Sample full application zip-archive

You are able to configure the application within a full application zip-archive. Also, proper versioning is important during deployment.

Deploying

Drop 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.

If you want to influence the deployment behavior, you can do this with deployment options.

Check the results

Go to the server info page, which is by default http://localhost:8080/ivy. You should see now your new processes available. If you think there is missing something you better check the deployment logs, which can be found in the same directory where you have dropped the deployment file.

File suffixDescription
.deployedLast deployed file to the engine in case of a successful deployment
.notDeployedLast not deployed file to the engine in case of error while deployment
.deploymentLogContains the log output which is written during the deployment
.deploymentErrorContains the error cause and is only written when the deployment fails

Table 7.1. Deployment marker files

Advanced Deployment

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.

Configure Application

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.

# sample app.yaml which can be part of the full application zip-archive
SecuritySystem: ActiveDirectoryOfMyCompany
EMailNotification:  
  DailySummaryOn: monday, tuesday, wednesday, thursday, friday
  OnNewTasks: true
StandardProcess: 
  DefaultPages: ch.ivyteam.ivy.project.portal:portalTemplate
  MailNotification: ch.ivyteam.ivy.project.portal:portalTemplates

Versioning

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.

Deployment Options

With deployment options you can influence the deployment behavior:

# Example of a deployment options file using YAML format.
# See http://axonivy.github.io/project-build-plugin/release/deploy-to-engine-mojo.html for
# more information about deployment options parameters.
# All parameters are set to their default values and listed in [brackets].

# Flag indicating if project test users should be deployed to the engine.
deployTestUsers: false           # [false], true

# Defines how project deployment should affect engine configuration.
configuration:
  overwrite: false               # [false], true
  cleanup: DISABLED              # [DISABLED], REMOVE_UNUSED, REMOVE_ALL

# Deployment target settings.
target:
  version: AUTO                  # [AUTO], RELEASED, (version values, e.g. 2.5 or (2.0,3.0])
  state: ACTIVE_AND_RELEASED     # [ACTIVE_AND_RELEASED], ACTIVE, INACTIVE
  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:

  1. 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.iar then create an options file that is called myProject.iar.options.yaml. Note, that after the deployment the myProject.iar.options.yaml file will be removed automatically.

  2. Global options file - Create a file called deploy.options.yaml in the deployment directory of an application. This global options file control all deployments inside the application.

  3. Inside the file that you are deploying - Put a deploy.options.yaml file inside your project directory, *.iar or *.zip that 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.

Maven Plugin

The Maven project-build-plugin makes automated continuous deployment to an Axon.ivy Engine possible. The Maven plugin itself uses the file based deployment capability of the Axon.ivy Engine. This means that the deployment folder must be available on the same machine on which the build is executed. You may use Windows-Shares or SMB-Configurations.

An Axon.ivy project can be deployed by invoking Maven with the deploy-to-engine goal of the project-build-plugin. To customize the deployment parameters, consult the goal documentation.

Command line deployment

The deploy-to-engine goal can be execute on the command line. The following example deploys the project myProject.iar to the application 'Portal' of the Engine location under c:/axonivy/engine:

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

Build goal execution

To deploy an ivy-archive (IAR) during it's Maven build lifecycle configured an execution which binds the deploy-to-engine goal to a phase in the projects pom.xml.

The following POM snippet deploys the current project to the application 'Portal' of the Axon.ivy Engine under c:/axonivy/engine.

<plugin>
	<groupId>com.axonivy.ivy.ci</groupId>
	<artifactId>project-build-plugin</artifactId>
	<extensions>true</extensions>
	<executions>
		<execution>
			<id>deploy.to.engine</id>
			<goals><goal>deploy-to-engine</goal></goals>
			<phase>deploy</phase>
			<configuration>
				<deployToEngineApplication>Portal</deployToEngineApplication>
				<deployEngineDirectory>c:/axonivy/engine</deployEngineDirectory>
			</configuration>
		</execution>
	</executions>
</plugin>

Further examples are documented on GitHub in the project-build-examples repository.

Standard Processes

With standard processes you can change the default workflow behaviour by simply providing a custom implementation in your ivy project.

For example: Once a user has completed a task, he will be redirected to his personal task list. The default task list is workflow driven and maybe to technical for your end user. With a standard process you could easily provide a branded and use case driven task list that fits perfectly into your domain.

We distinguish between two types of standard processes:

Implementation

To customize a standard process you need to do the following:

  1. Implement a process with a predefined process start signature in an ivy project. See the following sub chapters for more information.

  2. Deploy the ivy project with the customized standard processes in the application.

  3. Finally, the project with the standard processes must be activated in “app.yaml”:

    # app.yaml located in <application-directory>/app.yaml which actives the portal default processes 
    # To enable these custom processes, the library id of the ivy project must be specified here.
    # The library id is <group-id>:<project-id> from the ivy project deployment defintion.
    StandardProcess: 
      DefaultPages: ch.ivyteam.ivy.project.portal:portalTemplate
      MailNotification: ch.ivyteam.ivy.project.portal:portalTemplate

Default Pages

To customize default pages, you must implement processes with a predefined process start signature. Checkout the process Processes/Workflow/Home in the JsfWorkflowUI which also overrides all types of default pages. The JsfWorkflowUI can be found in [engineDir]/projects/JsfWorkflowUi.iar.

The following default pages can be customized:

Default PageProcess Start Signature
Application Home Page as the entry page to the application.DefaultApplicationHomePage()
Task List with all tasks the current user can work on.DefaultTaskListPage()
Process Start List with all processes which the current user can start.DefaultProcessStartListPage()
End Page which will be displayed to the user after a task or process is completed.DefaultEndPage(Number endedTaskId)
Login Page which comes up whenever authentication is needed.DefaultLoginPage(String originalUrl)
Error Page which visualizes error on the front endno signature: globally defined in “web.xml”

Table 7.2. Default Pages

Task List provided by JsfWorkflowUI

Figure 7.2. Task List provided by JsfWorkflowUI

Email Notifications

To customize the content of the email notification, you must implement processes with a predefined process start signature. Checkout the processes Processes/NewTaskMailContent and Processes/DailyTaskSummaryMailContent in the JsfWorkflowUI which also provides standard processes for email notification. The JsfWorkflowUI can be found in [engineDir]/projects/JsfWorkflowUi.iar.

Mail notifications require a configured mail server and enabled notification settings as described in “Email”.

The following email notifications can be customized:

Email NotificationProcess Start Signature
New Task page with the new assigned task. This is done everytime a new task is created, an existing task expires or the creator of an existing tasks changes. These events affect the user directly, via his role or his substitution. MailNotification_NewTask(Number notificationUserId, Number notificationTaskId)
Daily Task Summary page with all open tasks for the user. This notification is executed once a day for each user.MailNotification_DailyTaskSummary(Number notificationUserId)

Table 7.3. Email Notification

New Task Mail provided by JsfWorkflowUI

Figure 7.3. New Task Mail provided by JsfWorkflowUI

Implementation hints

  • Subject : The <title> html tag is re-used as email subject

  • Images : can be referred in the html either from CMS or the file system. These resources will be embedded as mime parts. External images will not be embedded and the links will not be modified at all.

  • Skip : you can avoid the standard mail sending procedure by custom conditions (e.g. do not send mails to technical users). To do so implement an alternative process flow without displaying any User Dialog or Html Page activity.

  • API: some API hints to implement email notification processes:

    • get the user you can use ivy.session.getSecurityContext().findUser(notificationUserId)

    • get the task you can use ivy.wf.findTask(notificationTaskId)

    • get the current open task for a user ivy.wf.findWorkTasks(...)

Miscellaneous

GC Optimization

The GC (Garbage Collection) of Java cleans up the unused memory of the JRE. Normally the GC completes in a few milliseconds. If it takes longer (and leads to serious issues for running applications) the optimization below can help to optimize the GC time.

Default GC configuration

By default, the GC strategy is optimized for RIA Applications and an explicit full concurrent GC runs every 10 minutes.

Note

Why a periodical GC is required for RIA Applications?

Normally a GC is triggered in the background when a considerable amount (e.g. 80%) of the available memory is used. Then the GC cleans up all unused memory so that the application can always address new memory as required.

Now comes RIA into play. A RIA application creates each UI widget on server- and client-side to share the UI-state on both sides. To clean this up on both sides the widget must be cleaned first on server-side before it can be cleaned on the client-side. But with the default GC configuration the memory on server-side will not be cleaned until a considerable amount of the available memory is used. But the available memory on server-side is usually considerably higher than on client-side, so this can lead to low memory problems on client side (OutOfMemoryException).

To prevent this situation Axon.ivy Engine triggers a full concurrent GC every 10 minutes. This cleans up the memory on server-side and allows the client-side to clean up its memory too.

Optimization for JSF

In JSF applications you only need a Browser on client side. Therefore, no periodical full concurrent GC is required and you can optimize the GC on low latency.

To change the GC accordingly comment out the following line in the corresponding ilc-file or AxonIvyEngine.conf for Linux:

# * GC optimized for JSF
ivy.garbage.collector.options=-XX:+UseConcMarkSweepGC -XX:+UseParNewGC -XX:+CMSParallelRemarkEnabled -XX:+CMSClassUnloadingEnabled -XX:+DisableExplicitGC

System Database Encryption

User passwords are stored encrypted in the system database. Passwords of Axon.ivy users are hashed by using the bcrypt algorithm. Passwords of technical users that are used to communicate with external systems are encrypted using the AES algorithm. The secret key for the AES algorithm is by default created automatically by using a secure random generator. However, it is possible to provide an own secret key as follows:

  1. Create your own AES secret key and store it in a key store file by using the Java keytool:

    keytool -genseckey -alias aes -keyalg AES -keysize 128 -storepass changeit -storetype JCEKS -keystore keystore.jceks
  2. Configure the following Java system properties in the launcher configuration:

    Java System PropertyDescription
    ch.ivyteam.ivy.persistence.keystore.fileThe path to the key store that holds the AES secret key. E.g. keystore.jceks.
    ch.ivyteam.ivy.persistence.keystore.passwordThe password needed to read the key store file. Default value changeit.
    ch.ivyteam.ivy.persistence.keystore.aliasThe name of the key to read from the key store file. Default value aes.
    ch.ivyteam.ivy.persistence.keystore.typeThe type of the key store. Default value JCEKS.

    Table 7.4. AES Secret Key System Properties

Warning

If you configure to use an own AES secret key after you have already stored technical passwords for external system then those passwords can no longer be decrypted and are useless. You have to reconfigure all those passwords again!

Replacing Java Runtime with newer version

If you want to use profiling tools such as VisualVM it may be required to replace the bundled Java Runtime (JRE) with a newer one. To do so, just perform the following steps:

  1. Download the full Java Development Kit (JDK) that suits best for your OS and Ivy-Installation (a 32 bit Ivy Engine cannot be run with a 64 bit runtime). It is important that you download the JDK and not the JRE. You will find the JDK at the Sun/Oracle Java website

  2. Install the downloaded JDK on the server (or on any computer with the same OS)

  3. Move the whole content of the directory jre in the installation folder of your Axon.ivy Engine to some other folder (to have a backup).

  4. Copy the whole content of the folder jre in the installation directory of the JDK to the jre folder in the installation folder of your Axon.ivy Engine (the one you moved in the step above)

Warning

Changing the Java Runtime that is packaged with Axon.ivy Engine is not recommended and should only be done when requested by Axon.ivy support or when required for testing purposes.