Axon.ivy 7.0 Engine Guide

User Manual:

Open the PDF directly: View PDF PDF.
Page Count: 159

DownloadAxon.ivy 7.0 - Engine Guide
Open PDF In BrowserView PDF
Axon.ivy 7.0
Engine Guide

Axon.ivy 7.0: Engine Guide
Publication date 16.07.2018
Copyright © 2008-2018 AXON IVY AG

1. Introduction .............................................................................................................................................. 1
What is Axon.ivy .................................................................................................................................. 1
About this guide ................................................................................................................................... 2
Installation Environment ........................................................................................................................ 2
Engine Types ....................................................................................................................................... 3
2. Getting Started .......................................................................................................................................... 6
Introduction ......................................................................................................................................... 6
Windows (with UI tools) ........................................................................................................................ 6
Linux (with console tools only) ............................................................................................................. 18
3. Installation .............................................................................................................................................. 25
Upgrading from an older version ........................................................................................................... 25
Standard Edition Installation ................................................................................................................. 26
Enterprise Edition Installation ............................................................................................................... 27
Install Axon.ivy Engine ........................................................................................................................ 28
System Database ................................................................................................................................. 31
Elasticsearch installation ....................................................................................................................... 40
4. Configuration .......................................................................................................................................... 42
How to start the Engine Configuration application .................................................................................... 42
Engine Configuration ........................................................................................................................... 42
Control Center ................................................................................................................................... 48
Configure Tomcat ............................................................................................................................... 51
Additional Security Configuration .......................................................................................................... 53
Error Handling .................................................................................................................................... 53
GC Optimization ................................................................................................................................. 55
System Database Encryption ................................................................................................................. 55
5. Integration .............................................................................................................................................. 57
Introduction ........................................................................................................................................ 57
Apache Integration .............................................................................................................................. 58
Microsoft IIS Integration ...................................................................................................................... 60
Axon.ivy Cluster Integration ................................................................................................................. 86
Web Application Firewall ..................................................................................................................... 88
6. Administration ........................................................................................................................................ 90
Opening the administration tool ............................................................................................................. 90
Applications ....................................................................................................................................... 91
Application Default Settings ................................................................................................................. 94
Process Models and Process Model Versions ........................................................................................... 96
Project Deployment ............................................................................................................................. 98
Business Calendar .............................................................................................................................. 104
Environments .................................................................................................................................... 106
Users and Roles ................................................................................................................................ 114
System Properties .............................................................................................................................. 119
Engine infos ..................................................................................................................................... 121
HTML Workflow UI .......................................................................................................................... 123
Email Notification ............................................................................................................................. 127
7. Monitoring ............................................................................................................................................ 132
Logging ........................................................................................................................................... 132
Process Element Performance Statistic and Analysis ................................................................................ 135
Java Management Extensions (JMX) .................................................................................................... 137
VisualVM ......................................................................................................................................... 141
Engine Administration ........................................................................................................................ 142
8. Miscellaneous ........................................................................................................................................ 143
Rich Dialogs ..................................................................................................................................... 143
HTML Dialogs .................................................................................................................................. 147
Replacing Java Runtime with newer version .......................................................................................... 147
Update Notification ............................................................................................................................ 147
Tool Reference .................................................................................................................................. 148
9. Troubleshooting ..................................................................................................................................... 153
Introduction ...................................................................................................................................... 153

iii

Axon.ivy 7.0

Program / Engine start problems .......................................................................................................... 153
Blocking Application/UI ..................................................................................................................... 155

iv

Chapter 1. Introduction
What is Axon.ivy
Axon.ivy is a Digital Business Platform that simplifies and automates the interaction of humans with their digital systems.
The platform typically is in charge in the most precious business cases where companies produces value. Here is how we do it:
1.

Visualize: Our platform allows you to document business processes fast and intuitive. A shared view on users, roles,
departments and technical systems that are involved in a business process improves your work. HR recruitment profiles
become clearer, bottle necks become obvious, ideas for effective improvements arise by anyone who is involved in the
process.

2.

Automate: Documented processes are good. But what you really want is to drive your highly valuable processes
automatically. Often the daily work of employees that are involved is distracted into searching and filtering data from
various tools and feed these data into other technical systems. Even tough value is produced in a well-known business
case, there is a lack of a clear interface which guides the involved users through the process. Highly valuable data is often
divided and stored in various dedicated technical systems. With Axon.ivy you can drive your process automatically.
People, data and technical systems can easily be orchestrated by our platform. An initial application that leads users
through the process can be generated without the need to hire a software engineer. People can contribute to the process
by using their favourite device such as a smartphone or workstation.

3.

Improve: The digitalization of your company can evolve over time, we favour small predictable improvements over
big bang solutions. The Axon.ivy Digital Business Platform allows you to start simple and fast with your existing
environment. You may just start by task notifications that are sent to users that should contribute to a running process.
And eventually the Platform becomes your single interface for all your business interactions. You will be able to measure
KPIs based on the highly valuable data that is produced during the execution of your business processes. Based on
these insights, you can advance your business constantly and effective. The cost of business transformations become
reasonable and predictable.

The Axon.ivy Digital Business Platform consists of:
• The Axon.ivy Designer - where you draw, simulate and implement automated business processes.
• The Axon.ivy Engine - an application server that executes your business cases and provides a shared interface to process
users.

Why Axon.ivy?
Axon.ivy is exciting for everyone that partakes on your digital transformation journey.
• Business: we enable you to start your personal digital transformation journey and make new business opportunities possible.
You are still the captain of your ship, start with simple automations and transform essential parts of your business when
you gain trust and confidence.
• Business Analysts: it has never been easier to document processes fast and intuitive. The process simulation allows you to
verify that you have a shared view how processes should be executed. Setup a simple structure for the data of a processes
and you even get a simple executable application with generated front ends that are meaningful. No software engineer is
required to create an already powerful application from scratch.
• Developers: develop your application on a rich stack of Java frameworks that stood the test of time. We minimize your
technology evaluation effort by giving you a set of libraries and an IDE that match perfectly together. This allows you to
quickly jump into projects and deliver value. While you always have the ability to break out of our predefined tooling and
use advanced features of Tomcat, JPA, JSF, JAX-RS or whatever you require.
• Operations: we deliver packages for popular Platforms (Linux, Windows). No big change, we orchestrate your existing
systems. We support many DB vendors (Oracle, Microsoft SQL Server, MySQL, PostgreSQL). Effective monitoring and
logging interfaces are provided to give you a safety that the application is healthy and accessible.

1

Introduction

About this guide
You are now reading Axon.ivy Engine documentation.
In case you want to know more on
• Getting the latest Axon.ivy version: Go to http://developer.axonivy.com/download/
• System requirements: Please read Readme.html in the installation directory.
• Working with Axon.ivy Engine: Start with the Getting Started chapter.
• Demo projects: The Axon.ivy Designer ships with several demo projects, which can be deployed to the Axon.ivy Engine.
• How to draw, simulate and implement automated business processes: Please read the Designer Guide (in the installation
folder of an Axon.ivy Designer)
• Upgrading an existing installation: Please read MigrationNotes.html (located in the installation folder).
All above mentioned documentations are brief and tend to describe only necessary functionality. We highly encourage reading
these documentations to speed up your development, to get to know new features or to eliminate potential problems.

Installation Environment
The following diagram shows the installation environment of an Axon.ivy Engine:

Figure 1.1. Axon.ivy Engine Installation
The Axon.ivy Engine needs a system database to store its configuration, users, roles and assigned permissions and the states,
cases, tasks from the deployed applications. Next, it needs file directories where the deployed projects are stored. The Axon.ivy
Engine integrates a Tomcat Servlet Engine that is responsible to receive HTTP or HTTPS requests from client applications

2

Introduction

and to send back appropriate responses (similar to a web server). The client applications itself are either Web Applications that
run in a web browser or Rich Internet Applications that run in a Java Virtual Machine (JVM). Both kind of client applications
communicate over HTTP or HTTPS directly with the Servlet Engine. In a productive environment, normally a Microsoft
Internet Information Server (IIS), Apache Web Server, NGINX reverse proxy or a web application firewall (WAF) often
combined with an identity and access management (IAM) system is put in front of the Axon.ivy Engine. The front-end servers
are then responsible to forward the requests to the Axon.ivy Engine Servlet Container. Also, the users are imported from an
external security system like a Microsoft Active Directory or Novell eDirectory. Axon.ivy applications can integrate with third
party external systems like databases, web services or application servers. Axon.ivy Engine also integrates an Elasticsearch
server. Instead using the integrated Elasticsearch server also an external Elasticsearch server can be used..

Tip
It is good practice to separate the data directory where you store the deployed project and other data files from
the Engine installation directory. This will later simplify a migration to newer Engine versions.
Example:

Path

Description

.../AxonIvyEngine/Data/Applications/HRM/...

Directory where the deployed projects for the HRM
application are stored.

.../AxonIvyEngine/Data/Applications/FinTech/...

Directory where the deployed projects for the FinTech
application are stored.

.../AxonIvyEngine/Data/ElasticSearch/...

Directory where the Business Data search indexes are
stored.

.../AxonIvyEngine/6.0.1/...

Installation directory of Axon.ivy Engine version 6.0.1
(can be removed if no longer needed)

.../AxonIvyEngine/6.1.0/...

Installation directory of Axon.ivy Engine version 6.1.0
(can be removed if no longer needed)

.../AxonIvyEngine/6.2.0/...

Installation directory of Axon.ivy Engine version 6.2.0

Table 1.1. How to organize data and installation directory

Engine Types
There are two different Axon.ivy Engine types:
• Standard Edition (formerly known as "Standard ")
• Enterprise Edition (Clustered Engine, formerly known as "Cluster ")

Axon.ivy Engine Standard Edition
The Axon.ivy Engine Standard Edition is installed on a single machine. A DBMS that can hold the Axon.ivy system database
is the only special infrastructure it needs. The deployed projects can be stored on a local harddisk on same machine that the
Axon.ivy Engine Standard Edition is running on.

3

Introduction

Figure 1.2. Axon.ivy Engine Standard Edition

Axon.ivy Engine Enterprise Edition
The Axon.ivy Engine Enterprise Edition is a cluster of multiple Axon.ivy Engine instances. It is built on a load balancer
that receives requests from the clients and forwards them to multiple Axon.ivy Engine nodes typically running on different
machines. The different nodes of an Axon.ivy Engine Enterprise Edition all share the same system database which is normally
stored on a dedicated database. The deployed projects are stored on a file system that can be accessed by all nodes.

Figure 1.3. Axon.ivy Engine Enterprise Edition
Axon.ivy Engine Nodes are typically installed on multiple server machines, but it is also possible to install more than one
Axon.ivy Engine Node on a single server machine. The load balancer can be realized either by a hardware load balancer or
by an IIS or Apache web server that distributes the incoming requests to the installed Axon.ivy Engine Nodes.

What engine edition do I need?
The Axon.ivy Engine Enterprise Edition has two major advantages compared to the Standard Edition:

4

Introduction

• Performance and scalability: An Axon.ivy Engine Enterprise Edition can serve more clients than the Axon.ivy Engine
Standard Edition. If your number of clients increases, you can add another Engine node to your Axon.ivy Engine cluster.
If you have a lot of sessions it may even be better to have two Axon.ivy Engine nodes on the same server machine instead
of having a single Standard Edition. Because each session needs memory on the engine and Axon.ivy can handle two
processes with medium memory footprints (i.e. Engine nodes) faster than one process with a large memory footprint (i.e.
Standard Edition).
• High availability: In an Axon.ivy Engine Enterprise Edition installation, a single node may crash without affecting the
other nodes, which still serve clients. However, if you require high availability of your Axon.ivy Engine you also need
to ensure that all other components the engine is depending on (Load Balancer, Database Server, File Share) have a high
availability.
The disadvantages of the Axon.ivy Engine Enterprise Edition compared to the Standard Edition are:
• higher complexity of the system
• higher hardware costs
• higher licence fees

5

Chapter 2. Getting Started
Introduction
This chapter helps you getting started with the Axon.ivy Engine. You will learn how to install and configure the Engine and
finally, how to deploy your Axon.ivy projects. If you are a Windows user and used to install and configure software using the
UI then the first section Windows is a good starting point for you. If you are an experienced Linux user and you are used to
install and configure software using the console then the second section Linux is the right starting point for you. Note, that
on both systems, Windows and Linux, Axon.ivy Engine can be installed and configured using the UI or the console.

Windows (with UI tools)
Download the Engine
Open a web browser and navigate to http://developer.axonivy.com. Press on the Download button to navigate to the download
page. Press the Download Axon.ivy Engine button:

Save the AxonIvyEngine*.zip file to your temporary download folder.

Install the Engine
We suggest that you install Axon.ivy Engine into a new folder called ivy\engine on one of your drives (e.g. c:\ivy\engine). To
do so open a Windows Explorer and navigate to C:\ and create those new folders. Then, navigate to your temporary download
folder and copy the file AxonIvyEngine*.zip to the newly created folder.

6

Getting Started

Right click the AxonIvyEngine*.zip file and press Extract All ... from the context menu.

On the appearing dialog press the Extract button. After the AxonIvyEngine*.zip is extracted navigate into the new
AxonIvyEngine* folder. The content of the installation folder looks like this:

The most important sub folders in the Axon.ivy Engine installation folder are:
• the bin folder which contains all the executables
• the configuration folder which contains the configuration files.

Start the Engine
Navigate to the bin folder and double click on the ControlCenter.exe file to start the Control Center. You can use this tool to
start and stop the Axon.ivy Engine in different ways (as Windows Service, as normal user process, with a console window).
Select the Axon.ivy Engine and press the green play button to start the Axon.ivy Engine as a normal user process:

7

Getting Started

You can use the Control Center also to register Axon.ivy Engine as Windows Service. Moreover, you can add other
existing Windows Services to the list of Engines to start and stop them with the Control Center. For example, if you
have installed your database server on the same machine you can add the Windows Service of the database server.
After the Axon.ivy Engine has started a web browser is opened and the main page of the Axon.ivy Engine is displayed.

Use the Engine
The main page of the Axon.ivy Engine looks like this:

The Axon.ivy Engine is running in Demo Mode. This is because you did not install a valid license yet nor did you configure
a system database. Note, that everything that you do with the Axon.ivy Engine running in Demo Mode is lost when you shut
down the engine. However, you can use the engine also in Demo Mode and tryout the pre-installed Portal application by
clicking on the Portal Home link. To login use one of the predefined demo users: demo, guest or admin. The passwords of
the demo users are equal to the user names (E.g. demo for the demo user). Login as demo user and try to create a TODO
task for the guest user using the Axon.ivy Selfservice process:

8

Getting Started

Configure the TODO task as follows:

9

Getting Started

Start the workflow by pressing the Start Workflow button. After that, logout, then login again as guest user. On the task
list, you now see the new TODO task that you created before. Try to work on the task by clicking on the arrow located on
the right side of the task:

Go ahead and play around with the Selfservice process. Try out different types of tasks.
In Axon.ivy a task is a piece of work (a part of a process) that is assigned to a user or role. A user to whom a task is
assigned or who has the role to which a task is assigned can work on the task. When a user works on a task the task
disappears from the task list of other users who might also able to work on the task. This means only one user can really
work on a task at the same time. In a process, it is possible to define parallel tasks. Therefore, it is possible that two or
more users work parallel on different tasks of the same process instance. In Axon.ivy a process instance is called a case.

Configure the Engine
Now, let's configure the Axon.ivy Engine with a license and system database.
To start with that you must first request a valid Axon.ivy Engine license. Either you get a license for your productive system
through one of our sales personal or contact our support for time limited tryout licenses. If you do not have a license you can
skip this section and continue with the next section.
Moreover, you need to have a supported database server up and running with a database user that has the rights to create new
databases. The configuration and creation of the system database differs a little bit depending on the database system you
use. We will use a PostgreSQL database server.
You can start the configuration on the main page of the Axon.ivy Engine (e.g. http://localhost:8081/ivy) by clicking on the
Config menu.

10

Getting Started

On the first page use the Upload Licence button to install your license file.

Some information of your license will be displayed on the page as soon as you have installed it. Press the Next button to
continue.
On the next screen choose the correct Database and Driver (in our case PostgreSQL). Configure the Host and Port where
your database server is running and listening. Configure the Username and Password of a database user that has the right
to create a new database on the database server.

Press the Create Database button. On the appearing dialog configure the name of the Axon.ivy system database. Press the
Create Database button to create the system database.

11

Getting Started

As soon as the database creation is finished the following dialog appears:

Press the Save and connect button to save the configuration and connect to the newly created system database.
The system database is used by the Axon.ivy Engine to store configurations, users, roles, process instances, tasks and
process data.
Press the Next button.
On the next page, you can configure system administrators.

Fill in the form and press the Add Administrator button.
Administrators can administrate the Axon.ivy Engine. For example, they can add or remove users, assign user to roles,
deploy projects, etc.
Therefore, you need at least one administrator to administrate the Axon.ivy Engine.
The Email addresses of administrators are used to send mail notifications if license problems occur.

12

Getting Started

Press the Next button.
On the next page configure which protocol connectors and ports the Axon.ivy Engine internal web server should provide.
You do not need the AJP protocol. So let's disable it.

The Axon.ivy Engine internal web server provides connectors for the following protocols:
HTTP

Protocol used by web browser to communicate with a web server. This protocol is not secure since the
communication is not encrypted. Axon.ivy Engine uses port 8080 by default.

HTTPS Like HTTP but secure. It uses TLS to encrypt the communication between the web browser and server.
Axon.ivy Engine uses port 8443 by default.
AJP

This protocol is used to communicate with a Microsoft IIS or Apache httpd front-end server. AJP means
Apache Jakarta Protocol. Axon.ivy Engine uses port 8009 by default.

Press the NEXT button.
On the next page, the configuration is summarized.

Press the Save button to save the configuration. Switch back to the Control Center and restart the Axon.ivy Engine by
stopping and starting it again.
Note, that the HTTP port of the Axon.ivy Engine may have changed. If you did not change the HTTP settings it is now 8080
and no longer 8081! So open again a web browser and navigate to http://localhost:8080/ivy. Have you seen that the header
with the demo mode message is gone? You now have a production ready Axon.ivy Engine.

13

Getting Started

The Config menu is only available in demo mode. If you want to reconfigure an Axon.ivy Engine not running in demo
mode use the AxonIvyEngineConfig.exe tool in the bin folder instead.

Deploy an Axon.ivy project to the Engine
Let's deploy an Axon.ivy project to the Axon.ivy Engine. To do so install an Axon.ivy Designer first so that you have demo
projects available that you can deploy. Simple download it from our download page and extract the AxonIvyDesigner*.zip
file to the folder c:\ivy\designer.
Now start the Admin UI tool by clicking on the Admin menu on the Axon.ivy Engine main page. This will start Java Web
Start. A dialog may appear asking if you want to run and trust the Axon.ivy Rich Internet Application . Press the Run button
to proceed. After a few seconds, the Axon.ivy Engine Admin UI appears.

Use the credentials of the administrator that you have added in the configuration section to login. If you are still running in
demo mode you can use AxonIvy/AxonIvy as credentials.
Then, press the Deployment Wizard button on the toolbar of the Applications section on the left side.

14

Getting Started

On the deployment wizard press the Browse button.

15

Getting Started

Choose the file WorkflowDemos.iar in the applications/demos folder of the Axon.ivy Designer installation folder and press
the Open button.

Select the WorkflowDemos project and press the Next button.

16

Getting Started

An Axon.ivy Project is normally stored in a folder. However, the deployment wizard also supports to deploy *.iar files.
An *.iar file is more or less a packed (zipped) Axon.ivy Project folder.
On the next page select the target application Portal.

An Axon.ivy Engine can manage multiple applications. Each application has its own independent user and task
management. A user of one application can only work in that application and not in another application. A task of one
application will never be visible in another application. Therefore, applications can be used either to build multi tenancy
systems or run staging environments (DEV, Q&A, PROD) on the same Axon.ivy Engine.

Press the Next button.
On the next two pages press also the Next button and on the final page press the Deploy button. The project WorkflowDemos
is now deployed to the application Portal. Press the button Finish to close the deployment wizard after the deployment has
finished. The WorkflowDemos is now visible in the Applications tree on the left side of the Admin UI.

17

Getting Started

Close the Admin UI and go back to the web browser. Refresh the main page of the Axon.ivy Engine. There is now a new
section called WorkflowDemos available with new links to start processes.

Congratulations you have installed and configured your first Axon.ivy Engine and deployed your first Axon.ivy project. If
you are interested in how to do the same but only with a console then read the next section. In the next chapter, you will learn
the main concept of the Axon.ivy Engine and the details of how to configure, administrate and monitor it.

Linux (with console tools only)
In this section, you will learn how to install and configure an Axon.ivy Engine on a Linux server only using the console.
On the Linux machine no windowing system has to be installed. However, to test your configuration a client machine with
a web browser is needed.

18

Getting Started

Prepare your Machine
Before starting with the installation of Axon.ivy Engine prepare your Linux machine with the necessary tools and software
needed for the installation (wget, unzip, Java 8 runtime). Most distribution may have pre-installed these tools but especially
certain Docker images may have not. On Debian (e.g. Ubuntu, etc.) based system use:
apt update
apt install sudo wget unzip openjdk-8-jre-headless

Install the Engine
We suggest that you install the Axon.ivy Engine into a new folder called /opt/ivy/engine. Create the directory and change
the owner to your current user:
cd /opt
sudo mkdir ivy
sudo chown myuser:myuser ivy
Replace myuser with the name of your current user.
Instead of using your current user we suggest that on a productive system you use a special user called ivy. First, create
a new user and group called ivy. Then, change the owner of the folder ivy to the user ivy. After that, login as user ivy
and work with the new user.
sudo mkdir ivy
adduser ivy
...
sudo chown ivy:ivy ivy
ls -al
...
drwxr-xr-x 3 ivy ivy
...
login ivy
...

4096 Sep 15 11:26 ivy

Download the latest engine:
cd ivy
mkdir engine
cd engine
wget https://developer.axonivy.com/download/stable/Engine-All-x64.zip -O engine.zip
To install Axon.ivy Engine simply unzip the downloaded file AxonIvyEngine*.zip into a new AxonIvyEngine* folder:
unzip engine.zip -d latest
rm engine.zip
cd latest
The most important folders in the Axon.ivy Engine installation folder are:
• the bin folder which contains all the executables.
• the configuration folder which contains the configuration files.
• the deploy folder which is used to deploy Axon.ivy projects.

19

Getting Started

Start the Engine
Start the Axon.ivy Engine by navigation to the bin folder and executing the AxonIvyEngine binary:
cd bin
./AxonIvyEngine
This will start the Axon.ivy Engine as a user process. On the last lines of the output a URL is displayed:
[100%] Service ProcessModelVersion Portal/AxonIvyExpress$1 started [0ms]
Go to http://yourservername:8081/ivy to see the info page of Axon.ivy Engine.
Axon.ivy Engine is running and ready to serve. [9375ms]
Type 'shutdown' and confirm with ENTER to stop the running engine instance
Copy this URL. On your client machine open a web browser and navigate to that URL. This will display the Axon.ivy Engine
main page.
Normally, you want to run Axon.ivy Engine as a daemon process and not as a user process. You can register and manage
the Axon.ivy Engine daemon using systemd.

Use the Engine
The main page of the Axon.ivy Engine looks like this:

The Axon.ivy Engine is running in Demo Mode. This is because you did not install a valid license yet nor did you configure
a system database. Note, that everything that you do with the Axon.ivy Engine running in Demo Mode is lost when you shut
down the engine. However, you can use the engine also in Demo Mode and tryout the pre-installed Portal application by
clicking on the Portal Home link. To login use one of the predefined demo users: demo, guest or admin. The passwords of
the demo users are equal to the user names (E.g. demo for the demo user). Login as demo user and try to create a TODO
task for the guest user using the Axon.ivy Selfservice process:

20

Getting Started

Configure the TODO task as follows:

21

Getting Started

Start the workflow by pressing the Start Workflow button. After that, logout, then login again as guest user. On the task
list, you now see the new TODO task that you created before. Try to work on the task by clicking on the arrow located on
the right side of the task:

Go ahead and play around with the Selfservice process. Try out different types of tasks.
In Axon.ivy a task is a piece of work (a part of a process) that is assigned to a user or role. A user to whom a task is
assigned or who has the role to which a task is assigned can work on the task. When a user works on a task the task
disappears from the task list of other users who might also able to work on the task. This means only one user can really
work on a task at the same time. In a process, it is possible to define parallel tasks. Therefore, it is possible that two or
more users work parallel on different tasks of the same process instance. In Axon.ivy a process instance is called a case.

Configure the Engine
Now, let's configure the Axon.ivy Engine with a license and system database.
To start with that you must first request a valid Axon.ivy Engine license. Either you get a license for your productive system
through one of our sales personal or contact our support for time limited tryout licenses. If you do not have a license you can
skip this section and continue with the next section.
Moreover, you need to have a supported database server up and running with a database user that has the rights to create new
databases. The configuration and creation of the system database differs a little bit depending on the database system you
use. We will use a PostgreSQL database server.
Shutdown the Axon.ivy Engine first by typing shutdown and Y:
...
Go to http://ivy1:8081/ivy to see the info page of Axon.ivy Engine.

22

Getting Started

Axon.ivy Engine is running and ready to serve. [11596ms]
Type 'shutdown' and confirm with ENTER to stop the running engine instance
shutdown
Should 'Axon.ivy Engine' be stopped? ([Y]es / [N]o): Y
Stopping Axon.ivy Engine ...
[ 0%] Stopping Server
...
Let's install the license. You can do this by simple copy the license *.lic file into the configuration folder:
cp ~/license.lic /opt/ivy/engine/latest/configuration
To configure the system database, use the config-db command of the EngineConfigCli tool. Replace yourdatabasserver
with the name of the host where your PostgreSQL server is running. Replace dbuser and password with the credentials of a
database user that has the rights to create a new database on the database server.
./EngineConfigCli config-db org.postgresql.Driver \
jdbc:postgresql://yourdatabaseserver:5432/AxonIvySystemDatabase \
dbuser password
Now, let's create the system database with the create-db command:
./EngineConfigCli create-db
The system database is used by Axon.ivy Engine to store configurations, users, roles, process instances, tasks and
process data.
Next, create an administrator using the create-admin command:
./EngineConfigCli create-admin admin nimda Administrator admin@axonivy.com
The first parameter admin is the name of the administrator. The second parameter nimda is the password.
Administrators can administrate the Axon.ivy Engine. For example, they can add or remove users, assign user to roles,
deploy projects, etc.
Therefore, you need at least one administrator so that you can later administrate the Axon.ivy Engine.
The Email address of administrators are used to send mail notifications if license problems occur.
Lastly, disable the AJP protocol connector of the Axon.ivy Engine internal web server by using the set-property command.
./EngineConfigCli set-property WebServer.AJP.Enabled=false
The Axon.ivy Engine internal web server provides connectors for the following protocols:
HTTP

Protocol used by web browser to communicate with a web server. This protocol is not secure since the
communication is not encrypted. Axon.ivy Engine uses port 8080 by default.

HTTPS Like HTTP but secure. It uses TLS to encrypt the communication between the web browser and server.
Axon.ivy Engine uses port 8443 by default.
AJP

This protocol is used to communicate with an Microsoft IIS or Apache httpd frontend server. AJP=Apache
Jakarta Protocol. Axon.ivy Engine uses port 8009 by default.

There are a lot of system properties available to configure these connectors. The name of the properties starts with
WebServer. as prefix then the name of the protocol HTTP., HTTPS. or AJP. followed by the name of the connector
property. The property Enabled controls where the connector is started or not. The property Port controls the port on
which the connector is listening.

23

Getting Started

Now, start the Axon.ivy Engine again as background process.
nohup ./AxonIvyEngine &
Note, that the HTTP port of the Axon.ivy Engine may have changed. If you did not change the http settings it is now 8080
and no longer 8081! So open again a web browser and navigate to http://yourservername:8080/ivy. Note, that the header with
the demo mode message is gone. You now have a production ready Axon.ivy Engine.

Deploy an Axon.ivy project to the Engine
Let's deploy an Axon.ivy project to the Axon.ivy Engine. We use demos that are shipped with the Axon.ivy Designer.

cd /opt/ivy/engine/deploy/Portal
wget https://developer.axonivy.com/download/stable/Designer-Linux-x64.zip -O designer.zip
unzip -j designer.zip applications/samples/WorkflowDemos.iar applications/samples/Connecti
rm designer.zip
An Axon.ivy Project is normally stored in a folder. However, you can also deploy *.iar files. An *.iar file is more or
less a packed (zipped) Axon.ivy Project folder.
Start the deployment now by creating a file called WorkflowDemos.iar.doDeploy:
touch WorkflowDemos.iar.doDeploy
You can monitor the deployment with:
tail -f WorkflowDemos.iar.deploymentLog
As soon as the deployment is finished the file WorkflowDemos.iar.doDeploy disappears.
An Axon.ivy Engine can manage multiple applications. Each application has its own user and task management. A user
of one application can only work in that application and not in another application. A task of one application will never
be visible in another application. Therefore, applications can be used to build multi tenancy or stages (DEV, Q&A,
PROD) without to install multiple Axon.ivy Engines.
Refresh the main page of the Axon.ivy Engine. There is now a new section called WorkflowDemos available with new links
available to start processes.

Congratulations you have installed and configured your first Axon.ivy Engine and also deployed your first Axon.ivy project.
If you are interested in how to do the same but with UI tools read the previous section. In the next chapter, you will learn the
main concept of the Axon.ivy Engine and the details of how to configure, administrate and monitor it.

24

Chapter 3. Installation
Upgrading from an older version
Warning
Upgrading from Xpert.ivy Server 3.x to Axon.ivy Engine 5.x and later is not supported.
If you upgrade to a new update release within the same Long Term Support (LTS) or Leading Edge (LE) version (e.g. 7.0.3 to
7.0.4) then follow the steps in the section Preparation and Upgrade. A project migration and system database conversion are
normally not needed if not explicit communicated otherwise in the Migration Notes. Therefore, you can skip section Project
Migration and steps 2 and 4 in the section Upgrade.

Preparation
Warning
Before upgrading of an Axon.ivy Engine read the Migration Notes document of the new version. This document
will tell you exactly what has changed since the last version and will list any additional steps to be undertaken,
which might not be described here.
1.

Install the new Axon.ivy Engine version to a new installation directory (See section Install Axon.ivy Engine).

2.

Read the Migration Notes document of the new version.

3.

If necessary (according to the Migration Notes), request a new licence (see section Installing a Licence).

4.

Back up the system database and the application file directories of the old installation.

5.

Copy the file serverconfig.xml from the configuration directory of the old installation directory to the configuration
directory of the new installation. This file contains the system database configuration and connection parameters.

6.

Unless a new licence is required (see 3.) you should also copy the old licence file to the new installation.

7.

Modifications on any other configuration files located in the configuration, elasticsearch/config, webapps/ivy/WEB-INF
or webapps/ivy/META-INF directories of the old installation may be ported over to the corresponding files in the new
installation, if required. To see what has been changed, we recommend the usage of some diff tool to compare the
individual config files of old and new installation.

8.

If you have installed additional extension plugins into the dropins directory then copy them to the dropins directory of
the new installation directory if they are compatible with the new Engine version. For those which are not compatible
try to get new compatible versions and install them.

Project Migration
Project migration is only necessary if mentioned in the Migration Notes. If migration is required, all projects deployed
to process model versions in state PREPARED, RELEASED, DEPRECATED and ARCHIVED must be converted. The
following steps are necessary for every process model version:
1.

Copy the project from the process model version file directory on the engine to a local directory on your developer
machine.

2.

Import the project into your Designer workspace.

3.

Migrate the project according the Migration Notes of the Designer. Usually this is achieved by invoking the project
conversion action on each project (see Designer Guide for more information). Some manual adaptions may be necessary.

25

Installation

4.

Test the migrated project in the Designer.

All migrated projects must be redeployed to the new, upgraded engine version (see next section).

Upgrade
1.

Stop the engine of the old version (See section Start / Stop Engine).

2.

Either convert the system database with the Axon.ivy Engine Configuration Application (see section System Database).
Or set autoConvert property to true in the serverconfig.xml in the configuration directory.

3.

Start the engine of the new version (see section Start / Stop Engine).

4.

Redeploy all converted/migrated Axon.ivy projects using the Axon.ivy Engine Administration (see section Deploying
a Project).

5.

You may now delete the old engine installation directory, unless the following warning applies to your installation:

Warning
Please note that the new, upgraded engine installation will still refer to the application file directories that were
used by the old installation. As a consequence, you must never delete the directory of an old installation, if it
contains application file directories (you can check the file directory by displaying the application information
inside the Axon.ivy Engine Administration). If the application file directories of your installation are stored
elsewhere, then the deletion of the old engine installation will not cause any problems.

Standard Edition Installation
It is recommended to read the Introduction chapter before installing an Axon.ivy Engine. The following list shows the
necessary steps that are required to install and run an Axon.ivy Engine:
1.

Gather all the information you need:
• The server platform the engine will be installed on.
• The database system used to host the system database.
• Order a licence file for your installation. You need to know the host name of the machine you want to install the
Axon.ivy Engine on. More information about the licence can be found in the section Install a Licence of the Installation
chapter.
• If an integration with a web server is planned, then get all the necessary configuration information of the web server.
• If an integration with an external security system is planned, then get all the necessary configuration information of
the external security system (e.g. Active Directory or Novell eDirectory).
• Ivy uses a bundled Elasticsearch server to search through Business Data. If the use of an external Elasticsearch server is
planned, then get the necessary configuration information for it. When running an Axon.ivy Engine Enterprise Edition
the use of an external Elasticsearch server is mandatory. See Elasticsearch installation for more information.

2.

Install all required operating systems, web servers and database systems.

3.

Install the Axon.ivy Engine

4.

Install your licence file

5.

Configure the Axon.ivy Engine

6.

Start the Axon.ivy Engine and test if it is running.
26

Installation

If everything is fine so far, you can perform the following optional configuration steps:
1.

Install Axon.ivy Engine as Windows Service or Linux systemd service if desired.

2.

Integrate Axon.ivy Engine into web servers if necessary.

3.

Configure Axon.ivy Engine system properties and create and configure applications.

Demo Mode
Axon.ivy Engine offers a demo mode for demonstration purposes. The demo mode allows you to install and start the Axon.ivy
Engine without configuration and without a productive licence. To install and start an Axon.ivy Engine in demo mode simply
execute the steps 3 and 6 from the list above.

Warning
The Axon.ivy Engine uses a memory database as system database in demo mode. This means that everything you
configure and all cases that are created by any sessions in demo mode are lost when you shut down the engine.

Tip
In demo mode you can login to the Engine Administration using with the predefined user AxonIvy and password
AxonIvy.

Enterprise Edition Installation
The installation process of an Axon.ivy Engine Enterprise Edition node is very similar to the standard installation process. To
save time you can copy the configuration from the first node you have installed to other nodes. See the next chapters to learn
how to install the first node, and how to proceed to install further nodes either on different machines or on the same machine.
Once you've installed all Axon.ivy Engine Enterprise Edition nodes you may want to integrate them into a web server that
will act as single frontend. The web server can be configured to work as a load balancer that distributes the incoming requests
evenly to the Axon.ivy Engine Enterprise Edition nodes. Consult the chapter Web Server Integration for more information.

Installation of the first engine node
Follow the standard installation process to install the first Axon.ivy Engine Enterprise Edition node.
For an Axon.ivy Engine Enterprise Edition installation an external Elasticsearch server installation is mandatory. See
Elasticsearch installation for more information.
At point 4 you must make sure that you install an Axon.ivy Enterprise Edition licence.
At point 5 an additional Cluster configuration tab will be displayed in the Engine Configuration. Inside this tab use the Add
local node button to add the new node to the list of nodes of the Axon.ivy Engine Enterprise Edition.

Installation of another engine node on a different machine
To install further Axon.ivy Engine Enterprise Edition nodes on other machines proceed as follows:
1.

Install the Axon.ivy Engine

2.

Copy the configuration directory inside the installation directory of the first Axon.ivy Engine Enterprise Edition node to
the installation directory of the currently installing node. Overwriting all existing files.

3.

Replace the licence file from the first Axon.ivy Engine Enterprise Edition node with the Axon.ivy Enterprise Edition
licence for this node in the configuration directory.

27

Installation

4.

Start the Engine Configuration program. The system database and administrators and web server tab should display the
values you have configured on the first node. Change to the Cluster tab and use the Add local node button to add the
node to the list of nodes of the Axon.ivy Engine Enterprise Edition. Save your changes.

5.

Start the Axon.ivy Engine Enterprise Edition node and test if it is running.

Installation of another engine node on the same machine
To install further engine nodes on the same machine where a node is already installed proceed as follows:
1.

Install the Axon.ivy Engine

2.

Copy the configuration directory inside the installation directory of the first engine node to the installation directory of
the currently installing node. Overwrite all existing files.

3.

Replace the licence file from the first engine node with the Axon.ivy Enterprise Edition licence for this node in the
configuration directory.

Note
Every cluster node needs its own licence file even if nodes run on the same machine.
4.

Start the Engine Configuration program. The system database and administrators tab should display the values you have
configured for the first node.
Change to the WebServer tab and specify different port numbers than those you have specified for the other nodes on
this machine.
Change to the Cluster tab and use the Add local node button to add the node to the list of nodes of the Axon.ivy Engine
Enterprise Edition. Save your changes.

5.

Start the Axon.ivy Engine Enterprise Edition node and test if it is running.

Install Axon.ivy Engine
To install the Axon.ivy Engine extract the correct zip file for your platform to the directory where you want to install the
Axon.ivy Engine.
The following platforms are supported:
CPU

Architecture Operation System Installation ZIP File

Intel

x64

Windows

Intel

x64

Linux
Windows*

and AxonIvyEngineX.Y.Z_All_x64.zip

Intel

x64

Linux
Windows*

and AxonIvyEngineX.Y.Z_Slim_All_x64.zip

AxonIvyEngineX.Y.Z_Windows_x64.zip

Table 3.1. Supported Axon.ivy Engine Platforms
* The 'All' and 'Slim_All' engines are delivered with launchers for Linux and Windows, but without a JRE. To use the slim
engine set up the IVY_JAVA_HOME environment variable pointing to a supported x64 Oracle JRE, or the JAVA_HOME
environment variable pointing to a supported x64 Oracle JDK. The Slim engine comes without projects like the Portal.

Note
Note, that the installation procedure implies sufficient administration and access rights on the system. For
example the access to drive C: on a Windows Server 2008 system is very restrictive that you might install the
programs on drive D: instead.

28

Installation

Installed Files and Directories
After the installation the following files and folders are located in the Axon.ivy Engine installation folder:
Folder or File Name

Description

bin/

Contains programs to start and configure the Axon.ivy Engine

clientlib/

Contains libraries that are deployed to the client machines

signed/linux/

Linux specific libraries

signed/linux_native/

Native Linux libraries

signed/windows/

Windows specific libraries

signed/windows_native/

Native Windows libraries

configuration/

Contains the Axon.ivy Engine configuration data

demo.lic

Demo licence file

keystore.jks

Keystore with the default signature of the Axon.ivy Engine (for https/ssl)

truststore.jks

Empty truststore can be used to add trusted server certificate for SSL
connection clients

log4jconfig.xml

Logging configuration

serverconfig.xml

System database configuration

servercontrolcenter.configuration

Control Center configuration

html/

Axon.ivy Engine Guide as HTML documentations

pdf/

Axon.ivy Engine Guide as PDF document

newAndNoteworthy/

Contains new and noteworthy features of the latest Axon.ivy Engine and
Designer releases

migrationNotes/

Contains migration notes of the latest Axon.ivy Engine and Designer releases

doc/

dropins/

Third party extension libraries that contribute to the Axon.ivy runtime

elasticsearch/

Bundled Elasticsearch server

jre/

Java Runtime Environment for Axon.ivy Engine

logs/

Contains the log files

misc/
apache

Files to integrate Axon.ivy into an Apache web server

iis

Files to integrate Axon.ivy into a Microsoft Internet Information Server (IIS)

visualvm

The Axon.ivy VisualVM plugin file

system/

The OSGi system

applications/

The system provided applications

configuration/

The OSGi configuration

features/

Installed OSGi features

lib/boot/

OSGi boot classpath libraries

plugins/

Installed OSGi plugins. Basically all default or automatically installed java
libraries of the Axon.ivy Engine

projects/

Contains deployable Axon.ivy projects

webapps/
ivy/

Contains the Axon.ivy Engine web interface

ivy/info/

Contains the info web pages

ivy/WEB-INF/

Contains the web.xml file

29

Installation

Folder or File Name

Description

ivy/META-INF/

Contains the context.xml file

ivy/wf/

Contains the workflow web interface

work/

Contains temporary files that are created and used by the Axon.ivy Engine

NewAndNoteworthy.html

Overview / entry point for list of new and noteworthy features in this release

MigrationNotes.html

Overview / entry point for migration of last to current release

Readme.html

Important information about this engine release

ReleaseNotes.txt

Release notes with bug fixes and new features

Table 3.2. Installed Files and Directories

Windows Programs
The bin folder of a windows installation contains the following native dynamic link libraries and executable files:
File

Description

Example.ilc

Example of an ivy launch control file. For more information see section Windows
Program Launcher Configuration .

JavaWindowsServiceHandler.dll

Library that contains native methods to register, unregister, configure, start and
stop windows services

JVMLauncher.dll

Library containing code to launch the Java virtual machine.

NTEventLogAppender.dll

Library that implements native methods to log into the windows event log (32 Bit
only).

ControlCenter.exe

Program that allows to configure, start and stop the Axon.ivy Engine. It also
permits to configure the Windows services. For more information see section
ControlCenter .

ControlCenterC.exe

Same as ControlCenter.exe but additionally logs any output to a console window.

AxonIvyEngine.exe

Starts the Axon.ivy Engine. For more information see section AxonIvyEngine .

AxonIvyEngineC.exe

Same as AxonIvyEngine.exe but additionally logs any output to a console window.

AxonIvyEngineConfig.exe

Program to configure the Axon.ivy Engine. For more information see section
AxonIvyEngineConfig .

AxonIvyEngineConfigC.exe

Same as AxonIvyEngineConfig.exe but additionally logs any output to a console
window.

AxonIvyEngineService.exe

Executable of the Windows service. For more information see section
AxonIvyEngineService .

Table 3.3. Windows Programs

Linux Programs
The bin folder of a Linux installation contains the following script files:
File

Description

AxonIvyEngine

Starts the Axon.ivy Engine. For more information see section AxonIvyEngine .

AxonIvyEngine.conf

Java virtual machine configuration (Xms, Xmx, JMX, ...) for the Engine.

AxonIvyEngineConfig

Program to configure the Axon.ivy Engine. For more information see section
AxonIvyEngineConfig .

AxonIvyEngine.service

Template systemd script of the Linux service. It will be copied to /etc/systemd/
system/ by running InstallService.sh.

30

Installation

File

Description

AxonIvyEngineService.sh

Helper scripts for systemd to start and stop the Axon.ivy Engine service.

control.conf

Java virtual machine configuration (Xms, Xmx, JMX, ...) for the control tools
(ControlCenter & AxonIvyEngineConfig)

ControlCenter

Program that allows to configure, start and stop the Axon.ivy Engine. For more
information see section ControlCenter .

InstallService.sh

Script to install the Axon.ivy Engine as a daemon. For more information see section
InstallService.

launcher.sh

Helper script to launch a Java program.

Table 3.4. Linux Programs

Installing a Licence
By default a demo licence is installed that allows you to run the Axon.ivy Engine in demo mode. You have to install a licence
in order to run Axon.ivy Engine in a production environment.

Note
The licence file contains the name of the host where the engine is installed on. The licence will only work if the
name of the machine exactly matches the name stored in the licence file.
To install a licence file follow the steps below:
1.

Copy the licence file *.lic to the directory configuration/.

2.

Change the extension of your old licence files to anything, but *.lic (e.g. from foo_bar_another_licence.lic to
foo_bar_another_licence.lic.old ).

Tip
You may leave demo.lic in the configuration folder, because this licence is taken only if no other licence files
are found.

System Database
The Axon.ivy Engine system database is used by the server to store configuration, security, content and workflow information.
See chapter Configuration to find out how you can create and configure Axon.ivy Engine system databases. Axon.ivy Engine
supports the following database systems to host the system database:
• MySQL
• Oracle
• Microsoft SQL Server
• DB2 for iSeries (AS400)
• Postgre SQL

Password Encryption
Passwords are stored encrypted in the system database using state of the art encryption algorithms. More information can be
found in the chapter System Database Encryption.

31

Installation

Character set and collation
All characters in databases are encoded with a specific charset (e.g. utf8, latin1, cp1257). Lastly it defines which kind of
characters can be stored at all.
The collation is a set of rules that defines how the database management system compares and orders the data (e.g.
utf8_unicode_ci, latin2_general_ci). Common abbreviations in the name of the collations are the following:
• ci = case insensitive
• cs = case sensitive
• ai = accent insensitive
• as = accent sensitive
As well as the character set the collation can be defined mostly on several levels: server, database, table or column. Everything
about this subject is very dependent on the actual database management system.

Support case insensitive searches
If a case insensitive search is required, it must be guaranteed that the affected column has a case insensitive collation.
• 1. Check character set & collation of the column
• 2. Change character set & collation if necessary
Look at the specific chapters for your database below.

MySQL
Information
MySQL is an Open Source database. For more information go to www.mysql.com. You can download the latest mysql JDBC
driver (Connector/J) from www.mysql.com.

Compatibility
You have to use at least MySQL Version 5.1 and the database engine InnoDb.

Configuration
The following table explains the fields you have to configure on System Database tab in the Axon.ivy Engine Configuration
program:
Field Name

Value(s)

Description

Database

MySQL

The database system to use.

Driver

MySQL

The database JDBC driver to use.

Host

localhost, testdbserv, ...

The name of the host where the database
system is running

Port

3306, 3307, 3308, ...

The IP port where the database system is
listening for request

Database Name

AxonIvy,
AxonIvyEngine, The name of the Axon.ivy Engine system
AxonIvySystemDatabase, ...
database

32

Installation

Field Name

Value(s)

Description

User Name

root, admin, AxonIvy, ...

The name of the database user who is
used to connect to the database system

Password

****

The password of the database user who
is used to connect to the database system

Table 3.5. MySQL Configuration

Creation
The following table explains the additional creation parameters you have to configure on System Database tab in the Axon.ivy
Engine Configuration program, if you want to create a new system database on a MySQL database system:
Field Name

Value(s)

Description

Database Name

AxonIvy,
AxonIvyEngine, The name of the database to create
AxonIvySystemDatabase, ...

Engine Type

InnoDb

The type of the MySQL database engine
to use. At the moment only InnoDb is
possible.

Table 3.6. MySQL Creation Parameter

Driver
The following table shows information about the JDBC driver that Axon.ivy Engine uses to connect to MySQL database
systems:
JDBC Driver Name

com.mysql.jdbc.Driver

JDBC Connection URL Format

jdbc:mysql://[:]/

Table 3.7. MySQL Driver

Character set & collation
If you want to check the collation of a specified column you can use the following query:
SELECT character_set_name, collation_name FROM information_schema.columns WHERE
table_schema = "AXON_IVY_SYSTEM_DATABASE" AND table_name = "iwa_case" AND column_name
= "name"
If you need to change the collation look at the official MySQL reference for all supported character sets and collations. The
simplest way is to use a case insensitive collation of the current character set. The following code will apply a new collation.
ALTER TABLE iwa_case
utf8_general_ci;

MODIFY

name

VARCHAR(200)

CHARACTER

SET

utf8

COLLATE

You can find more information about modifying the column in the MySQL reference.
If the Axon.ivy Engine Configuration creates a new database, the following parameters will be automatically applied. If you
want to use different charset or collation create an empty database manually with your configuration and then use the Axon.ivy
Engine Configuration to create the tables, views and indexes in that database.
Parameter

Value

Charset

utf8

33

Installation

Parameter

Value

Collation

utf8_unicode_ci

Table 3.8. MySQL Default Database Configuration

Oracle
Information
Oracle database is a database management system from the Oracle Corporation. For more information go to www.oracle.com

Compatibility
You have to use at least Oracle 10g.

Configuration
The following table explains the fields you have to configure on the System Database tab in the Axon.ivy Engine Configuration
program:
Field Name

Value(s)

Description

Database

Oracle

The database system to use.

Driver

Oracle Thin, Oracle Oci

The database JDBC driver to use. Either
Thin or OCI driver.

Host

localhost, testdbserv, ...

The name of the host where the database
system is running

Port

1521, 1522, 1523, ...

The IP port where the database system is
listening for request

Oracle Service ID (SID)

oracle, db, ...

The identifier of the oracle service

User Name

root, admin, AxonIvy, ...

The name of the database user who is
used to connect to the database system

Password

****

The password of the database user who
is used to connect to the database system

Table 3.9. Oracle Configuration

Tip
On all (reused) oracle database connections the maximum number of open cursors is set to 1000, independently
from the default setting that may be set on the database itself. Those cursors are needed to cache all prepared
statements and also for PL/SQL blocks.
It may turn out that the number of open cursors is exceeded, which is indicated by an error message similar
to the following:

ch.ivyteam.ivy.persistence.PersistencyException: java.sql.SQLException:
ORA-00604: error occurred at recursive SQL level 1
ORA-01000: maximum open cursors exceeded
If this should happen, then you may customize (and increase) the number of open cursors per connection with the
Java system property ch.ivyteam.ivy.persistence.db.oracle.MaxOpenCursors. This must
be done in either the .ilc file (on Windows) or the shell script (on Linux) of the server instance that you're starting.
34

Installation

System
properties
are
set
as
additional
Java
VM
properties,
e.g.
Dch.ivyteam.ivy.persistence.db.oracle.MaxOpenCursors=2000 to set the maximum
number of open cursors to 2000. See Java VM help if you need further information.

Creation
Note
With Oracle database the Axon.ivy Engine Configuration program will not create a new database instance for
Axon.ivy Engine instead it will create only the user/schema and the tables into a given tablespace.
Before you can create the system database tables on a Oracle Database you have to do the following steps:
1.

You may want to create a new Oracle database where the Axon.ivy Engine System Database is located. This is optional
you can use an already existing Oracle database.

2.

Create a new user (e.g. AxonIvy). Grant all necessary permissions to the user so that he can create and alter tables,
indexes, sequences. Of course the user must be able to insert, update, delete and select data from the tables of the system
database. This is optional you can use an already existing Oracle user or let the Axon.ivy Engine create one for you with
the Axon.ivy Engine Configuration.

3.

You may want to create a new tablespace (e.g. AxonIvy) where the Axon.ivy Engine System Database can store the table
data. This is optional you can use an already existing tablespace.

Warning
Be sure that the configuration of the database connection uses the new database and the Oracle Service ID
reflecting the database you want to create the system database tables in.
The following table explains the additional creation parameters you have to configure on the System Database tab in the
Axon.ivy Engine Configuration program if you want to create a new system database on Oracle database system:
Field Name

Value(s)

Description

Tablespace

AxonIvy,
AxonIvyEngine, The name of the tablespace where the
AxonIvySystemDatabase, ...
system database tables will store their
data in.

User

AxonIvy, ...

The name of the user which will be
created if she is not already existing.
Tables, indexes and views are created in
the schema of this user.

Password

***

The password for the given user.

Table 3.10. Oracle Creation Parameter

Driver
The following table shows information about the JDBC driver Axon.ivy Engine uses to connect to Oracle database systems:
JDBC Driver Name

oracle.jdbc.OracleDriver

JDBC Connection URL Format

jdbc:oracle:thin:@::

Table 3.11. Oracle Driver

Character set & collation
The character set is defined with the CREATE DATABASE statement which is part of the customer configuration (look
at creation). We recommend to use AL32UTF8 (unicode) or at least WE8ISO8859P1, which supports Western European
languages. By the use of AL32UTF8 all text fields like VARCHAR or CHAR supports unicode characters.

35

Installation

Oracle databases works with session parameters for sorting and comparing data. The concept is called Linguistic Sorting and
Matching. In the Oracle Database Manager you can configure the initialization parameters. For case insensitive sorting and
comparing you can set NLS_SORT to AMERICAN (select an appropriate language) and NLS_COMP to LINGUISTIC. At the
moment, you can't override the NLS_LANGUAGE and NLS_TERRITORY which is set to AMERICAN.

Microsoft SQL Server
Information
Microsoft SQL Server is a database system from Microsoft. For more information go to www.microsoft.com. We support
two different JDBC Drivers for Microsoft SQL Server. First, the official JDBC Driver from Microsoft that provides support
for the latest SQL Server features like high availability with multi subnet fail-over. Second, the matured and long-time used
jTDS JDBC Driver.

Compatibility
You have to use at least Microsoft SQL Server 2005.

Configuration
The following table explains the fields you have to configure on the System Database tab in the Axon.ivy Engine Configuration
program:
Field Name

Value(s)

Description

Database

Microsoft SQL Server

The database system to use.

Driver

jTDS

The database JDBC driver to use.

Host

localhost, testdbserv, ...

The name of the host where the database
system is running

Port

3306, 3307, 3308, ...

The IP port where the database system is
listening for request

Database Name

AxonIvy,
AxonIvyEngine, The name of the Axon.ivy Engine system
AxonIvySystemDatabase, ...
database

User Name

sa, root, admin, AxonIvy, ...

The name of the database user who is
used to connect to the database system

Password

****

The password of the database user who
is used to connect to the database system

Table 3.12. Microsoft SQL Configuration

Important
If you want to connect to an existing instance of a MS SQL Server you have to configure an additional connection
property that is called instance containing the name of the corresponding database instance.

Creation
The following table explains the additional creation parameters you have to configure on the System Database tab in the
Axon.ivy Engine Configuration program if you want to create a new system database on Microsoft SQL Server database
system:
Field Name

Value(s)

Description

Database Name

AxonIvy,
AxonIvyEngine, The name of the database to create
AxonIvySystemDatabase, ...

Table 3.13. Microsoft SQL Server Creation Parameter
36

Installation

Driver
The following table shows information about the JDBC driver Axon.ivy Engine uses to connect to Microsoft SQL Server
database systems:
Driver Name

Connection URL Format

Documentation

net.sourceforge.jtds.jdbc.Driver

jdbc:jtds:sqlserver://[:]/


jTDS JDBC Driver Documentation

com.microsoft.sqlserver.jdbc.SQLServerDriver
jdbc:sqlserver://
Microsoft SQL Server JDBC Driver
[:];DatabaseName=

Table 3.14. Microsoft SQL Server Driver

Character set & collation
MSSQL Server supports different (one byte-) character sets with the COLLATE parameter. If you need a unicode character
set you have to modify the text fields to type NVARCHAR, NCHAR or NTEXT. First create a new column of this type, copy
data from the old column, drop the old column and rename the new column to the old column.
If you want to check the collation of a specific column you can use the following query:
SELECT columns.collation_name FROM information_schema.columns WHERE table_name =
'iwa_case' AND column_name = 'name';
Probably you need to change the collation. Look at the official MSSQL reference for all supported character sets and collations.
The simplest way is to use a case insensitive collation of the current character set. The following code will apply a new
collation.
ALTER TABLE iwa_case ALTER COLUMN name VARCHAR(200) COLLATE Latin1_General_CS_AI;
If the Axon.ivy Engine Configuration creates a new database, the following parameters will be automatically applied. If you
want to use different collation create an empty database manually with your configuration and then use the Axon.ivy Engine
Configuration to create the tables, views and indexes in that database.
Parameter

Value

COLLATE

Latin1_General_CI_AI

Table 3.15. Microsoft SQL Server Default Database Configuration

DB2 for iSeries (AS400)
Information
IBM calls its database products DB2. It is important to understand that DB2 for z/OS is not the same as DB2 for LUW (Linux,
Unix, Windows) and not the same as DB2 for iSeries. This chapter describes DB2 for iSeries (formally AS400). For more
information go to www.ibm.com.

Compatibility
You have to use at least DB2 for iSeries V6R1M0.

Configuration
The following table explains the fields you have to configure on the System Database tab in the Axon.ivy Engine Configuration
program:

37

Installation

Field Name

Value(s)

Description

Database

DB2 iSeries (AS400)

The database system to use.

Driver

DB2 iSeries (AS400)

The database JDBC driver to use.

Host

localhost, testdbserv, ...

The name of the host where the database
system is running

Port

50000, 50001, 50002, ...

The IP port where the database system is
listening for request

Schema Name

AxonIvy, AxonIvyEngine, ....

The name of the SQL schema (library) to
use.
Name with more than 10 characters are
not supported.

User Name

sa, root, admin, AxonIvy, ...

The name of the database user who is
used to connect to the database system

Password

****

The password of the database user who
is used to connect to the database system

Table 3.16. DB2 for iSeries Configuration

Creation
The following table explains the additional creation parameters you have to configure on the System Database tab in the
Axon.ivy Engine Configuration program if you want to create a new system database on a DB2 for iSeries database system:
Field Name

Value(s)

Description

Schema

AxonIvy, Ivy, ...

The name of the database schema that
will be created and where the Axon.ivy
Engine system database tables will be
created in.

Table 3.17. DB2 for iSeries Creation Parameter

Driver
The following table shows information about the JDBC driver used by Axon.ivy Engine to connect to DB2 database systems:
JDBC Driver Name

com.ibm.as400.access.AS400JDBCDriver

JDBC Connection URL Format

jdbc:as400://[:]/

Table 3.18. DB2 for iSeries Driver

Character set & Collation
DB2 for iSeries (AS400) uses CCSID (coded character set identifier) for encoding definitions which can be configured on
system level. To influence the sorting and comparing you can configure the additional connection properties in the engine
config ui. The supported properties are listed in the IBM Toolbox for Java JDBC properties. Especially the sort properties
sort, sort language and sort weight are interesting for case insensitive searches.

PostgreSQL
Information
PostgreSQL is an Open Source database. For more information go to www.postgresql.org. You can download the latest
PostgreSQL JDBC driver from jdbc.postgresql.org

38

Installation

Compatibility
You have to use at least PostgreSQL 8.3.

Configuration
The following table explains the fields you have to configure on the System Database tab in the Axon.ivy Engine Configuration
program:
Field Name

Value(s)

Description

Database

PostgreSQL

The database system to use.

Driver

PostgreSQL

The database JDBC driver to use.

Host

localhost, testdbserv, ...

The name of the host where the database
system is running

Port

5432, 5433, 5434, ...

The IP port where the database system is
listening for request

Database Name

AxonIvy,
AxonIvyEngine, The name of the database to use.
AxonIvySystemDatabase, ...

User Name

sa, root, admin, AxonIvy, ...

The name of the database user who is
used to connect to the database system

Password

****

The password of the database user who
is used to connect to the database system

Table 3.19. PostgreSQL Configuration

Creation
The following table explains the additional creation parameters you have to configure on the System Database tab in the
Axon.ivy Engine Configuration program if you want to create a new system database on PostgreSQL database system:
Field Name

Value(s)

Description

Database Name

AxonIvy,
AxonIvyEngine, The name of the database to create
AxonIvySystemDatabase, ...

Table 3.20. PostgreSQL Creation Parameter

Driver
The following table shows information about the JDBC driver Axon.ivy Engine uses to connect to PostgreSQL database
systems:
JDBC Driver Name

org.postgresql.Driver

JDBC Connection URL Format

jdbc:postgresql://[:]/

Table 3.21. PostgreSQL Driver

Character set & collation
The character set can only be defined by the CREATE DATABASE statement.
If you want to know the collation of a column you can use the following query:

39

Installation

SELECT character_set_name, collation_name FROM information_schema.columns
table_name = 'iwa_case' and column_name = 'name';

WHERE

Maybe there is no collation defined, so PostgreSQL won't show you any value. Ask the DBMS for the default value:
SELECT datname, datcollate FROM pg_database;
Propably you need to change the collation. Look at the official PostgreSQL reference for all supported character sets and
collations. Look also at Collation Support and ALTER TABLE for more information about collations in PostgreSQL.
ALTER TABLE iwa_case ALTER COLUMN name varchar(200) COLLATE "de_DE.utf8";
If the Axon.ivy Engine Configuration creates a new database, the following parameters will be automatically applied. If you
want to use different charset or collation create an empty database manually with your configuration and then use the Axon.ivy
Engine Configuration to create the tables, views and indexes in that database.
Parameter

Value

ENCODING

UTF8

Table 3.22. PostgreSQL Default Database Configuration

Elasticsearch installation
To quickly search through Business Data, ivy makes use of the powerful Elasticsearch search engine. You can use the bundled
Elasticsearch server or use an external Elasticsearch cluster.

Bundled Elasticsearch server
By default an Elasticsearch server is bundled with the Axon.ivy Engine. This Elasticsearch instance is started when the Engine
starts and runs in an own process. The default Elasticsearch installation is reachable only on localhost and is unprotected.
The following System properties can be customized to configure the bundled Elasticsearch servers. The
Elasticsearch.BundledServer.DataPath should be set to a directory outsite of the Engine installation directory.
Typically, there's no need to change the other ones.
System Property name

Description

Elasticsearch.BundledServer.DataPath

The path to the directory where the bundled Elasticsearch
server stores data. By default the data is store in
the elasticsearch/data directory inside the Engine
installation directory. We recommend to use a seperate data
directory that is located outsite of the Engine installation
directory to ease the Engine migration.

Elasticsearch.BundledServer.ClusterName

The name of the cluster of the bundled Elasticsearch server.

Table 3.23. System properties for the bundled Elasticsearch server
The Java virtual machine arguments used to start the bundled Elasticsearch server can be configured in the file elasticsearch/
config/jvm.options.

External Elasticsearch server
If you perform an Axon.ivy Engine Enterprise Edition installation or choose to install an external Elasticsearch server, you
can follow the Elasticsearch installation steps. Currently we support Elasticsearch server versions in the 5.5.x range. If your
Elasticsearch server is running on another server instance you have to secure the access to that instance.
You have to let the engine know where your Elasticsearch server instance is running by configuring the following System
properties:

40

Installation

System Property name

Description

Elasticsearch.ExternalServer.Url

The URL of the external Elasticsearch server.

Elasticsearch.ExternalServer.UserName

Name of the user to use to authenticate in the external
Elasticsearch server.

Elasticsearch.ExternalServer.Password

Password of the user to use to authenticate in the external
Elasticsearch server.

Elasticsearch.IndexNamePrefix

The name prefix of the indices to use to store
business data. If multiple ivy Engines use the same
Elasticsearch server instance, you need to change this
property, that every ivy Engine has an unique indices. For
every business data type an Elasticsearch index will be
created. E.g. for type ch.ivy.Dossier the index name
is -ch.ivy.dossier. Default:
ivy.businessdata

Table 3.24. System properties for an external Elasticsearch server

Disk Space
The disk space needed to store business data on the Elasticsearch and system database server depends on the size and number
of values that are stored. The following table shows how much space is needed for business data values with a size between
2 and 4 KB.
Number of Values

System Database (MySQL)

Elasticsearch

20'000

150 MB

110 MB

100'000

720 MB

230 MB

1'000'000

6.9 GB

2.2 GB

Table 3.25.

41

Chapter 4. Configuration
How to start the Engine Configuration application
There are several possibilities to launch the Axon.ivy Engine Configuration application:

Note
Note, that the configuration procedure implies sufficient administration and access rights. For example on a
Windows Server 2008, you have to run the Engine Configuration tool with the "Run as Administrator" option.

Launch from Control Center
After starting the ControlCenter, select a server entry from the server list on the left side and press the Server button in the
configuration area to start the configuration program.
Windows: Start the ControlCenter.exe program in the bin directory of the Axon.ivy Engine installation directory.
Linux: Start the ControlCenter program in the bin directory of the Axon.ivy Engine installation directory to start the
ControlCenter program.

Direct Launch
You can start the Axon.ivy Engine Configuration program directly.
Windows: Start the AxonIvyEngineConfig.exe program in the bin directory of the Axon.ivy Engine installation directory.
Linux: Start the AxonIvyEngineConfig program in the bin directory of the Axon.ivy Engine installation directory.

Launch in Headless Mode
You can start the Axon.ivy Engine Configuration with the option -headless to start the program in the headless mode.
Headless mode is useful if you operate in a non-graphical user interface environment. If you start the program with the headless option, a rich dialog application engine is started. Once the engine is up and running, it prints out a URL to
the console. You can now use another computer, to start a web browser and type in the provided URL to start the Axon.ivy
Engine Configuration user interface. You can use it to configure the Axon.ivy Engine as explained in this chapter. When
you are finished with the configuration, switch back to your server and press a key in your console to stop the rich dialog
application engine.
Windows: Use the AxonIvyEngineConfigC.exe program in the bin directory of the Axon.ivy Engine installation directory
with the option -headless to start the Axon.ivy Engine Configuration in headless mode.
Linux: Use the AxonIvyEngineConfig program in the bin directory of the Axon.ivy Engine installation directory with the
option -headless to start the Axon.ivy Engine Configuration in headless mode.

Engine Configuration
The Axon.ivy Engine Configuration application's user interface is divided into tabs. On the Licence tab you can upload a
licence. On the System Database tab the system database can be configured, created or converted. On the Administrators tab
system administrators can be registered. This tab is only enabled if a valid system database is configured. On the Web Server
tab the web server protocols and ports can be configure. This tab is also only enabled if a valid system database is configured.
Click Save to store the modified data on all tabs. Hit Discard Changes to reload the configuration from the filesystem and
database. The Cluster tab is only visible if you have installed an Enterprise Edition Licence.

42

Configuration

The configuration on the System Database tab is stored in the configuration file configuration/serverconfig.xml. The
configurations on the other tabs are stored in the system database that is configured in its own tab.

Note
The changes that you make with the Engine Configuration do not become active unless you restart the engine.

Licence
On the Licence tab you have to upload a valid licence:

Figure 4.1. Axon.ivy Engine Configuration Licence Tab
Use the Upload Licence button to open the file browser and select the licence which should be used.

Note
It is possible to configure the engine without a valid licence, but the engine will always start in the demo mode
if you do not have a valid licence and therefore does not use your configuration.

System Database
On the System Database tab the Axon.ivy Engine system database can be configured, created and converted:

43

Configuration

Figure 4.2. Axon.ivy Engine Configuration System Database Tab
First choose the database system and the JDBC driver you want to use. At the moment the Axon.ivy Engine supports the
following database systems:
• MySQL
• Oracle
• Microsoft SQL Server
• DB2 for iSeries (AS400)
• Postgre SQL
The choice of the second step depends on the database system and JDBC driver you have chosen in the first section. Click on
the database system links above to find information about how to configure the connection settings.
In a third step you can configure additional connection properties. When clicking on the Additional Propertiesbutton a dialog
will show, where you can add, edit or delete the properties. See database system specific chapter (links above) to find
information which additional connection properties are available for the database system that you have chosen.

44

Configuration

At the top of the page the state of the connection is visible. Use the button on the right to try to connect to the system database.

Create new System Database
If the system database does not exist, use the create button at the bottom to create a new system database. During the creation of
a new database the configured connection parameters are used. For some database system additional information is necessary.
It must be provided in a pop-up dialog before the new database can be created. See database system specific chapter (links
above) to find what additional information is necessary for the chosen database system.

Note
You can previously create an empty database/schema. In this case the server configuration tool will only create
the necessary tables into the given database/schema. If the database/schema doesn't exist already, the server
configuration tool creates it with a best practice configuration. The best practice configurations are documented
in chapter System Database.

Convert an old System Database
Warning
We strongly recommend to backup your database before you convert it to a newer version. Be sure that you have
enough disk/table space on your database server. Most conversions add new fields to existing database tables
which will enlarge the used database space.
If the system database has an older version, use the convert button at the bottom to convert it to the latest version.

Warning
Depending on the conversion steps and your database system it may be necessary to cut all connections to
the system database to avoid problems. If you have problems with the conversion, please disconnect all other
database management tools, clients or other tools that has a connection to the system database and try again.

System Administrators
On the Administrators tab you can configure users that have the right to administrate the Axon.ivy Engine:

45

Configuration

Figure 4.3. Axon.ivy Engine Configuration Administrator Tab

Defining an email address for the administrators is recommended. Notifications of critical events like licence limits
reached are sent to these email addresses.

Warning
This tab is only enabled if you have configured a connection to a valid system database.

Web Server Ports
On the Web Server tab you can configure which protocols the internal web server of Axon.ivy Engine should support and
on which IP ports the web server is listening:

46

Configuration

Figure 4.4. Axon.ivy Engine Configuration WebServer Tab
The following protocols are supported:
Protocol

Description

HTTP

HTTP protocol .

HTTPS

HTTP protocol over secure socket layer (SSL).

AJP

Apache Jakarta Protocol. This protocol is used for the
communication of the embedded Servlet Engine with external
WebServers like IIS or Apache.

Table 4.1. Web Server Protocols

Warning
This tab is only enabled if you have configured a connection to a valid system database.

Note
In case you disable HTTP port, then the specified port will still opened by the engine for internal purposes. Even
though the engine will refuse connections from remote hosts.

Cluster
Note
This tab is only visible if you have installed an Axon.ivy Enterprise Edition licence.
On the Cluster tab you have to configure some information according the local cluster node:

47

Configuration

Figure 4.5. Axon.ivy Engine Configuration Cluster Tab
Use the Add local node button to add this installation as a new Engine cluster node to the list of cluster nodes in your Axon.ivy
Engine Enterprise Edition. You have to configure an IP Address and an IP Port that will be used by the cluster to communicate
with this node.

Note
An Engine cluster node is uniquely identify by the host it is running on and a local identifier. The local identifier
is a unique number that identifies nodes running on the same host (machine). Both values are provided by the
installed licence. Therefore, every Engine cluster node needs its own licence file.

Control Center
The Control Center integrates all tools to configure the engine, the (Windows) service and to start/stop the installed Axon.ivy
Engine.
To open the Control Center application, go to your Axon.ivy Engine installation directory and launch the ControlCenter.exe
or the ControlCenter program located in the bin folder.

Start / Stop
To start the Axon.ivy Engine, simply choose the Axon.ivy Engine in the list on the left side and then press the green start
button.
Alternatively, you can choose the Axon.ivy Engine [Console] from the list to start the engine within a console to which some
information about the engine is logged. Please note that closing this console window will terminate the Axon.ivy Engine
without shutting it down properly.
To stop the engine, click the red stop button.

48

Configuration

Figure 4.6. The Control Center

Configuring Windows Service (Windows only)
If you've installed the Axon.ivy Engine under a Windows operating system, you can register it as a Windows service. To do
so, select the entry Axon.ivy Engine [Windows Service] from the list on the left and press the button Windows Service on
the right. A dialog will open, prompting you for additional configuration data:

Figure 4.7. Configuring Axon.ivy Engine as Windows service
First of all press Register Service to register the service and to enable the rest of the configuration sections.

Tip
Service operations (register, unregister, start, stop) may fail because the current user does not own the necessary
rights. In this case close the Control Center and start it again by right clicking on the ControlCenter.exe and

49

Configuration

choose the command Run as administrator from the context menu. After that, the service operation should
work.
Now you may configure the user under which the service (and therefore the Axon.ivy Engine) will be executed. This can be
either the system user or any other user with sufficient rights to start services and access the Axon.ivy Engine installation
directory (read and write).
By default, the service start kind is Manually. To start the engine each time Windows is booted, choose the setting
Automatically
The last thing that can be configured are the services that the Axon.ivy Engine depends on. This might be the database
management system on which the system database is located or the web server in which Axon.ivy is integrated (IIS or Apache).
All the services that you add in this list will be started before Axon.ivy and if any of these services fail to start, Axon.ivy
won't start too.
After you have finished the configuration, click Ok. Now you will be able to start the engine from the control center or you
may also use the Windows Service Management Console.

Testing the Engine
Once you've started the Axon.ivy Engine, try to open the following address in your preferred web browser: http://
ServerName:Port/ivy. If a web page with the Axon.ivy logo appears, the installation and configuration of the Axon.ivy
Engine was successful and you may continue with the next chapter.

Server List Configuration
The list with the engine types on the right may be extended by users. You may add other Axon.ivy Engine installations and
you even can integrate other third party tools to start them from the Control Center.

Note
The indication whether the program behind an entry in the server list is running or not is only shown for
the Axon.ivy Engine binaries of the installation the Control Center belongs to and for any Windows services
(including the Axon.ivy Engine services). This applies too for the show console setting because only Axon.ivy
Engine binaries can be started in a console (third party applications cannot).
Add opens a dialog to choose the type for the new entry. For integration of another Axon.ivy Engine binary or a third party
tool, choose the first option (ivyTeam based Server), if you intend to integrate an Axon.ivy Engine as a Windows service or
any other Windows service, then choose the second option (Windows Service based server.

Figure 4.8. Create a new server in the server list
In the configuration dialog for a normal application you can set the base name and/or refine with the instance name (in the
server list the instance name is printed in brackets after the name). Add the server binary (or your third party tool) in the server
start executable and the configuration utility in the field configuration program (or the configuration program of your third

50

Configuration

party application). If and only if you choose the console based binaries (the ones with "C" at the end of the file name, e.g.
AxonIvyEngineC.exe) then tick the check box Show console. It has no effect on all other binaries.

Figure 4.9. Create a new service in the server list
In the configuration dialog for adding/editing a service entry, you can choose an already existing service from the combo box
or set the service name when you did not already register the service. Set the configuration program and the service binary
similarly to the description above. For simply starting/stopping existing services from the Control Center, it is not necessary
to define the service binary

Note
The name in this dialog must be exactly the same name that is used to register the service. Otherwise the lookup
will not work.
Remove removes the selected entry from the list and Edit allows to edit the configuration for the selected entry in the server list.

Configure Tomcat
The directory webapps/ivy/WEB-INF/ contains the web.xml file which is the webapp configuration file of the embedded
Tomcat application server. See the Apache Tomcat documentation for more information.

Warning
Be very careful when changing the contents of this file. A wrong configuration or an invalid syntax in the file
may harm the stability and correctness of your Axon.ivy Engine installation.

Note
After a change in the web.xml a restart of the Engine is required to apply the new configuration.
Below is a description of settings often adjusted in an ivy web.xml

Session Timeout
In the web.xml you can set the timeout for the session. If a session (i.e. a user interaction with an application) is inactive for
this amount of time, then the session will be closed. To adapt the default value look for the section below in the web.xml file
and change the value accordingly:

30


Error Pages
It is possible to defined customized error pages, see chapter Custom Error Pages.

51

Configuration

Security Headers
The ivy Engine comes with predefined HTTP Security headers for the /ivy web application. These Security Headers are added
on the HTTP Responses to the Client Browser.
These security headers can be switched off or modified in the web.xml.
Header name

Value

X-Frame-Options

SAMEORIGIN

X-XSS-Protection

1; mode=block

X-Content-Type-Options

nosniff

Table 4.2. Default Values of the Security Headers

Note
Not all Security Headers are supported by all Web browsers.

Secure Session Cookies
If the Engine is accessed over HTTPS only (strongly recommended). The cookie should only be transported over HTTPS. To
enable this behavior (or disable the transport over HTTP) uncomment following lines in the session-config part of the web.xml:

true


Valves and Realms
The directory webapps/ivy/META-INF/ contains the context.xml file which is the context configuration file of the embedded
Tomcat application server. See the Apache Tomcat context documentation for more information. In there you can add realms
and valves, see the Apache Tomcat documentation about realms or valves for more information.
The following valves are provided by Axon.ivy Engine:
Class

Documented in Chapter

ch.ivyteam.ivy.webserver.internal.PerformanceLogValve

“Request/Performance Logging”

ch.ivyteam.ivy.webserver.security.SingleSignOnValve

“Single Sign On”

Table 4.3. Valves provided by Axon.ivy Engine

Warning
Be very careful when changing the contents of this file. A wrong configuration or an invalid syntax in the file
may harm the stability and correctness of your Axon.ivy Engine installation.

Custom Valve
You can configure any third party valve or even your own implementation of a valve. A custom valve implementation can
only be loaded by the Axon.ivy Engine if its classes are accessible by the engines OSGi environment. This can be reached
as follows:
1.

The valve JAR must be implemented as OSGi bundle. This means that the standard JAR manifest (META-INF/
MANIFEST.MF) must also contain headers to declare the id, name and version of this bundle. These headers will be set
automatically if the bundle is created within the Axon.ivy Designer via File > New > Other... > Plug-in Project

52

Configuration

2.

Your bundle must require the bundle with the id ch.ivyteam.tomcat of the Axon.ivy Engine.

3.

Your bundle must register itself as buddy of the tomcat bundle by setting the MANIFEST.MF header: EclipseRegisterBuddy: ch.ivyteam.tomcat

4.

The package that contains the custom valve must be exported in the MANIFEST.

5.

Export the bundle as JAR: Menu Export > Deployable Plug-ins and Fragments.

6.

The custom bundle must be copied into the dropins directory of the Axon.ivy Engine.
Troubleshooting: If your valve is not working as expected, consult the dropins/README.html.

Sample META-INF/MANIFEST.MF:
Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-Name: ProcessingValve
Bundle-SymbolicName: com.acme.ProcessingValve;singleton:=true
Bundle-Version: 1.0.0.qualifier
Require-Bundle: ch.ivyteam.tomcat
Eclipse-RegisterBuddy: ch.ivyteam.tomcat
Export-Package: com.acme.valve

Tip
A full valve sample implementation can be found on GitHub: https://github.com/ivy-samples/tomcatValve

Additional Security Configuration
Additional Security Headers
Following additional security headers are recommended. Preferably set them on the Front-End Server (e.g. IIS, nginx,
Apache).
Header name

Description

Strict-Transport-Security

Set this header if the Engine should only be accessed over
HTTPS (strongly recommended). For more information, see:
Strict-Transport-Security

Content-Security-Policy

Set this header if you want to reduce the risk of having an
exploitable Cross-site scripting (XSS) vulnerability. With a
Content-Security-Policy you can define from which locations
external resources can be loaded and if scripts embedded in
HTML can be executed. For more information, see: Content
Security Policy (CSP)

Referrer-Policy

Set this header if you want to control how or if the referrer is
disclosed to other sites. For more information, see: ReferrerPolicy

Table 4.4. Additional Security Headers

Error Handling
When an error occurs while processing a user request an error screen is displayed to the user.

53

Configuration

Show Error Details to End Users
By default, stacktraces, detailed error reports, etc. are not shown to end users because of security concerns when a application is
running on the Engine. Instead only a unique Error Id is shown. In development or pre-production environments this behaviour
is unnecessary. By changing the System Property Errors.ShowDetailsToEndUser to true this behaviour could be
changed, so that all information are displayed to the user, like on the Designer.

Error Id
When 'Show Error Details to End Users' is deactivated then an error screen with an unique Error Id is shown to the user. This
Error Id can be used to find the error in the log files.

Custom Error Page
An error page is used to display information about the error to the user. The content and appearance of the ivy error page can
be customized. To do so, you can adjust the existing error page webapps/ivy/ivy-error-page.xhtml and its resources.
You are free to create your own error page(s), place them into webapps/ivy/ and add them to web.xml as follows:

/custom-error-page.xhtml

By adding the  tag to the  configuration it is also possible to configure a specific error page
for status codes or kind of exceptions as described in Servlet 3.0 JSR in chapter 10.9.2 Error Pages.

java.lang.Throwable
/custom-exception-error-page.xhtml


404
/custom-404-error-page.xhtml


Tip
To retrieve information about the thrown exception and the environment during the request the Public API
of ch.ivyteam.ivy.webserver.ErrorPageMBean could be used. An instance will be available as
managed bean on the error page. Check the default error page ivy-error-page.xhtml for an example
usage.

Error Report
On a error screen it is possible to generate an error report. This report contains information about the error, the system
environment and the current state of the Engine.

Tip
To create a report without an explicit error navigate to the following URL http://{server}:{port}/
ivy/error.

IIS Error Handling
If the engine is running behind an IIS web server and an error occurs on the Engine the IIS shows its own error page and hides
the error page coming from the Engine. This is the default IIS configuration.

54

Configuration

Since Axon.ivy 5.1 the IIS integration script configures the IIS to show the detailed error page of the Engine (see Step
'Configure Error Page' of the IIS integration chapter). With the following steps the setting could be reset the default IIS
behavior. This could make sense to hide error details because of security concerns:
1.

Open the IIS manager

2.

Select the virtual directory ivy and on its Features View, double click on Error Pages

3.

Right click and select the Edit Feature Settings... or select the same from the Actions pane (in the right
hand side)

4.

Select the “Detailed errors for local requests ...” radio button and click on OK.

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 serverside 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

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
55

Configuration

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 J
2.

Configure the following Java system properties in the launcher configuration:
Java System Property

Description

ch.ivyteam.ivy.persistence.keystore.file

The path to the key store that holds the AES secret key. E.g.
keystore.jceks.

ch.ivyteam.ivy.persistence.keystore.password

The password needed to read the key store file. Default
value changeit.

ch.ivyteam.ivy.persistence.keystore.alias

The name of the key to read from the key store file. Default
value aes.

ch.ivyteam.ivy.persistence.keystore.type

The type of the key store. Default value JCEKS.

Table 4.5. 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!

56

Chapter 5. Integration
Introduction
We recommend to run Axon.ivy Engine behind a web front-end server (Apache httpd, Microsoft IIS, Reverse Proxy, Web
Application Firewall, etc.).
In those cases the web front-end server receives all requests from the clients and forwards them to the Axon.ivy Engine which
handles them. This allows to integrate the processes and applications that you are running on an Axon.ivy Engine into a
company or web portal. Some web front-end server provide Single Sign On (SSO) functionality. The front-end server then
is responsible to identify the user (either automatically or by login). After that the user is able to operate on all web sites that
are integrated into the web front-end server.

Figure 5.1. Web Front-End Server
The integration for Apache httpd and Microsoft IIS is technically solved by using Tomcat Connectors. More technical details
about those connectors can be found on the Apache Tomcat web site.

Integration Directory
All necessary files that you need to integrate an Axon.ivy Engine into a Web Server can be found in the following directories
inside the Axon.ivy Engine installation directory:
• Apache HTTP Server for Windows (x64): misc/apache/
• Apache HTTP Server for Linux (x64): misc/apache/
• IIS for Windows (x64): misc/iis/
The directory that matches the platform and webserver where you plan to integrate the Axon.ivy Engine will be called
integration directory in this chapter.
The integration binaries for Linux are not delivered with the Axon.ivy Engine as it is best practice to use the Tomcat Connector
binaries that are provided by the Linux distribution. See “Linux example configuration”

57

Integration

Update external base URL
Update the System properties with your external base URL after the web server integration. Those properties are required for
creating external links (e.g. links in task mails):
• WebServer.ExternalProtocol(e.g. https)
• WebServer.ExternalHostName(The external host name)
• WebServer.ExternalPort(e.g. 443 for https)

Apache Integration
An Apache HTTP Server 2.x can be configured as web frontend of an Axon.ivy Engine. The communication between the
Apache HTTP Server and the Tomcat from Axon.ivy is possible by using the Apache Tomcat Connector.

Windows example configuration
1.

If your Apache HTTP Server is not running on the same host as the Axon.ivy Engine then the integration directory
content must be copied to the host where your Apache HTTP Server is running.
• Copy the mod_jk binaries and the sample configuration files from the directory that matches your OS in [[Axon.ivy
Engine install dir]]/misc/apache to the Apache Host under C:\Program Files\ivy
All next steps have to be done on the host where the Apache HTTP Server is running on.

2.

Include the copied jk_module configuration in the [[Apache Install Dir]]/conf/httpd.conf. Add the following lines to
do so:
# Axon.ivy Engine Integration
Include C:/Program Files/ivy/mod_jk.conf

3.

Replace all  strings in the file C:\Program Files\ivy\mod_jk.conf so that the file reflects your local paths:
# Load mod_jk module
LoadModule
jk_module c:/program files/ivy/mod_jk-1.2.42-httpd-2.4.so
# Where to find workers.properties
JkWorkersFile c:/program files/ivy/workers.properties
# Where to put jk shared memory
JkShmFile
c:/program files/ivy/mod_jk.shm
# Where to put jk logs
JkLogFile
c:/program files/ivy/mod_jk.log
# Set the jk log level [debug/error/info]
JkLogLevel
info
# Select the timestamp log format
JkLogStampFormat "[%a %b %d %H:%M:%S %Y] "
# Mount the uri "/ivy/*" to the worker AxonIvyEngine.
JkMount /ivy/* AxonIvyEngine

4.

If you have configured virtual hosts in your apache configuration you have to map the URI /ivy/* in all virtual host
you want to integrate Axon.ivy Engine into. This can be done by copying the following line from the mod_jk.conf file
to the appropriate virtual host definitions:
JkMount /ivy/* AxonIvyEngine
Copy this to the appropriate virtual host definitions, e.g.:
58

Integration


ServerAdmin webmaster@ivy.soreco.wan
DocumentRoot "C:/Program Files (x86)/Apache Software Foundation/Apache2.2/docs/ivy.soreco.wan"
ServerName ivy.soreco.wan
ServerAlias www.ivy.soreco.wan
ErrorLog "logs/ivy.soreco.wan-error.log"
CustomLog "logs/ivy.soreco.wan-access.log" common
JkMount /ivy/* AxonIvyEngine


5.

Define the hostname and port, where the Axon.ivy Engine is running. Adjust the content of the file C:\Program Files
\ivy\worker.properties to do so.
worker.list=AxonIvyEngine
worker.AxonIvyEngine.type=ajp13
worker.AxonIvyEngine.port=8009
worker.AxonIvyEngine.host=ivyserver

6.

Update the external base URL in the Admin UI

7.

Restart the Apache HTTP Server and the Axon.ivy overview page should be accessible under http://apacheHostName/ivy

Linux example configuration
Within this example an Apache HTTP Server is configured so that it can connect to the Tomcat of an Axon.ivy Engine. The
configuration step descriptions are generic and can be used under any Linux distribution. But the concrete examples assume
that an Ubuntu distribution is installed as Operating System.
1.

Install the latest Tomcat Connector (mod_JK) by console.
sudo apt-get install libapache2-mod-jk

2.

Enable the new module
sudo a2enmod jk

3.

Update the worker.properties file according to the examples in the [[Axon.ivy Engine install path]]/misc/apache/. The
following example content would connect to an Axon.ivy Engine on the host "ivyserver" under the default AJP port 8009.
/etc/libapache2-mod-jk/worker.properties:
worker.list=AxonIvyEngine
worker.AxonIvyEngine.type=ajp13
worker.AxonIvyEngine.port=8009
worker.AxonIvyEngine.host=ivyserver

4.

Mount the Axon.ivy Engine in the virtual host definition of the Apache HTTP Server. The context URI must match the
context of the Axon.ivy Engine.
/etc/apache2/sites-available/default:

...
#Mounts the URI /ivy/* to the worker AxonIvyEngine
JkMount /ivy/* AxonIvyEngine


Tip
If the Apache HTTP Server is used as Load Balancer for a clustered Axon.ivy Engine installation, the
JK Status Manager can be used to display debugging informations. The Manager is accessible when it is
mounted in the virtual host definition configuration.

59

Integration


...
#Mounts the URI /jkmanager/* to the JK Status Manager interface.
JkMount /jkmanager/* jkstatus


5.

Update the external base URL in the Admin UI

6.

Restart the Apache HTTP Server and the Axon.ivy overview page should be accessible under http://apacheHostName/ivy

Change context URI /ivy/
The context URI /ivy/ can be changed inside the Axon.ivy Engine by changing the system property
WebServer.IvyContextName (See chapter System Properties to learn about how to change a system property).
However, if you change the context URI on the Axon.ivy Engine you also have to change the context URI in the Apache
HTTP Server integration. This can be done by changing the last line of the mod_jk.conf configuration file:
JkMount

/ivy/* AxonIvyEngine

If you want to have /xpertline/ as the context URI change this line to the following:
JkMount

/xpertline/* AxonIvyEngine

If you have a virtual host configuration, the JkMount command with the new context URI must also be applied to the virtual
host definition:

...
JkMount /xpertline/* AxonIvyEngine


Microsoft IIS Integration
Important
To successfully integrate Axon.ivy Engine into Microsoft Internet Information Server (IIS) it is important that
you exactly execute all the integration steps described below. If the integration does not work verify each
integration step again.

IIS 7 (Windows Server 2008)
Note
There is a batch script autoconfig.bat in the folder misc\iis of your engine installation, which installs and
configures the IIS automatically on a Windows 2008 Server.
If you are setting up a new IIS Server you can use this script instead of following the instructions below.
1.

If your Microsoft Internet Information Server is not running on the same host as the Axon.ivy Engine then copy the
integration directory to the host where your IIS is running. All next steps have to be done on the host the IIS is running on.

2.

Allow the user groups Authenticated Users and IUSR to have Full control permission on the integration
directory.

60

Integration

3.

Install Features

Note
Instead of installing the features manually you can run the following command which ensures that all
necessary IIS Features are installed:
PKGMGR.EXE /iu:IIS-WebServerRole;IIS-WebServer;IIS-CommonHttpFeatures;IISStaticContent;IIS-DefaultDocument;IIS-DirectoryBrowsing;IIS-HttpErrors;IISApplicationDevelopment;IIS-CGI;IIS-ISAPIExtensions;IIS-ISAPIFilter;IISHealthAndDiagnostics;IIS-HttpLogging;IIS-RequestMonitor;IIS-Security;IISWindowsAuthentication;IIS-RequestFiltering;IIS-Performance;IIS-HttpCompressionStatic;IISWebServerManagementTools;IIS-ManagementScriptingTools;IIS-ManagementService
Open the Server Manager (Start > Control Panel > Administrative Tools > Server Manager). Navigate to the node Server
Manager > Roles > Web Server (IIS) and select it. Validate that under the Role Services the services CGI, ISAPI
Extensions and ISAPI Filters are installed. If this is not the case select the menu Add Role Services
to install the missing services.

61

Integration

4.

Feature delegation

Note
The following command automatically sets the feature delegation:
powershell -ExecutionPolicy unrestricted -ImportSystemModules Set-WebConfiguration //
System.webServer/handlers -metadata overrideMode -value Allow -PSPath IIS:/
Open the Internet Information Services (IIS) Manager (Start > Control Panel > Administrative Tools > Internet
Information Services (IIS) Manager). In the Connections pane select the node that represent your machine. In the
Feature View open the Feature Delegation entry.

62

Integration

Ensure that the Delegation of the Handler Mappings are set to Read/Write. Use the menu Read/Write
on the Actions pane to change the Delegation to Read/Write.

5.

Virtual ivy directory

Note
The following commands automatically creates the virtual directory ivy:
set path=%path%;%windir%\system32\inetsrv

appcmd.exe add vdir /app.name:"Default Web Site/" /path:/ivy /physicalPath:

63

Integration

In the Connections pane navigate to the Web Site you want integrate the Axon.ivy Engine into. Use the context
menu Add Virtual Directory ... of the Web Site to add a new Virtual Directory. A dialog opens. Configure
the Alias of the Virtual Directory with ivy and the Physical path of the Virtual Directory with the path of the
integration directory. Click OK to close the dialog and create the Virtual Directory:

6.

Handler Mapping Permissions

Note
The following command automatically sets the feature permission for the ivy virtual directory:
appcmd.exe set config "Default Web Site/ivy" /section:system.webServer/handlers /
accessPolicy:Read,Write,Execute
Select the new created Virtual Directory ivy in the Connections pane and open the Handler Mappings entry
in the Feature View:

In the Actions pane select the Edit Feature Permissions ... menu:

64

Integration

On the Edit Feature Permission dialog select all three permission and click OK:

7.

Configure Error Page

Note
The following command automatically configures that the detailed error page of the Engine is shown:
appcmd.exe set config "Default Web Site/ivy" /section:system.webServer/httpErrors /
errorMode:Detailed

Tip
See chapter Error Handling for more information about this configuration.
Select the new created Virtual Directory ivy in the Connections pane and open the Error Pages entry in the
Feature View:

65

Integration

Right click and select the Edit Feature Settings... or select the same from the Actions pane (in the right
hand side)

Select the Detailed errors radio button and click on OK

8.

Install ISAPI filter

Note
The following command automatically adds the ISAPI Filter:
appcmd.exe set config /section:isapiFilters /+[@start,name='Tomcat',path='\isapi_redirect-1.2.42.dll']
Select the Web Site in the Connections pane and open the ISAPI Filters entry in the Feature View:

In the Actions pane select the Add ... menu:

66

Integration

On the Add ISAPI Filter dialog configure the Filter name with Axon.ivy Engine and the Executable
with the path of the isapi_redirect-1.2.42.dll located in the integration directory. Click OK to add the ISAPI Filter:

9.

Change ISAPI filter restriction

Note
The following command automatically adds the ISAPI Restriction:
appcmd.exe set config /section:isapiCgiRestriction /+[@start,description='Tomcat',path='\isapi_redirect-1.2.42.dll',allowed='true']
In the Connections pane select the node that represent your machine and open the ISAPI
Restrictions entry in the Features View:

67

and

CGI

Integration

In the Actions pane select the Add ... menu:

On the Add ISAPI or CGI Restriction dialog configure the ISAPI or CGI path with the path of the
isapi_redirect-1.2.42.dll located in the integration directory. As Description use Axon.ivy Engine. Select the
Allow extension path to execute check box. Click OK to add the ISAPI or CGI Restriction:

68

Integration

10. If your Microsoft Internet Information Server is not running on the same host as the Axon.ivy Engine or if you have
changed the AJP port of the Axon.ivy Engine then open the file worker.properties inside the integration directory in a
text editor. Change the following line if you have changed the AJP port to another value than 8009:
worker.AxonIvyEngine.port=8009
Change the value localhost in the following line to the host where your Axon.ivy Engine is running if your Microsoft
Internet Information Server is not running on the same host as the Axon.ivy Engine:
worker.AxonIvyEngine.host=localhost
11. Update the external base URL in the Admin UI
12. Check if the integration is working by opening a web browser on the address http:///ivy/

IIS 8 (Windows Server 2012)
Note
There is a batch script autoconfig.bat in the folder misc\iis of your engine installation, which installs and
configures the IIS automatically on a Windows 2012 Server.
If you are setting up a new IIS Server you can use this script instead of following the instructions below.
1.

If your Microsoft Internet Information Server is not running on the same host as the Axon.ivy Engine then copy the
integration directory to the host where your IIS is running. All next steps have to be done on the host the IIS is running on.

2.

Allow the user groups Authenticated Users and IUSR to have Full control permission on the integration
directory.

3.

Install Features

Note
Instead of installing the features manually you can run the following command which ensures that all
necessary IIS Features are installed:
PKGMGR.EXE /iu:IIS-WebServerRole;IIS-WebServer;IIS-CommonHttpFeatures;IISStaticContent;IIS-DefaultDocument;IIS-DirectoryBrowsing;IIS-HttpErrors;IIS-

69

Integration

ApplicationDevelopment;IIS-CGI;IIS-ISAPIExtensions;IIS-ISAPIFilter;IISHealthAndDiagnostics;IIS-HttpLogging;IIS-RequestMonitor;IIS-Security;IISWindowsAuthentication;IIS-RequestFiltering;IIS-Performance;IIS-HttpCompressionStatic;IISWebServerManagementTools;IIS-ManagementScriptingTools;IIS-ManagementService
Open the Server Manager (Start > Server Manager). Select the Web Server (IIS). Validate that under the Role
Services the services CGI, ISAPI Extensions and ISAPI Filters are installed. If this is not the case select
the menu Add Role Services to install the missing services.

4.

Feature delegation

Note
The following command automatically sets the feature delegation:
powershell -ExecutionPolicy unrestricted -ImportSystemModules Set-WebConfiguration //
System.webServer/handlers -metadata overrideMode -value Allow -PSPath IIS:/
Open the Internet Information Services (IIS) Manager (Start > Internet Information Services (IIS) Manager). In the
Connections pane select the node that represent your machine. In the Feature View open the Feature
Delegation entry.

70

Integration

Ensure that the Delegation of the Handler Mappings are set to Read/Write. Use the menu Read/Write
on the Actions pane to change the Delegation to Read/Write.

5.

Virtual ivy directory

Note
The following commands automatically creates the virtual directory ivy:
set path=%path%;%windir%\system32\inetsrv

appcmd.exe add vdir /app.name:"Default Web Site/" /path:/ivy /physicalPath:

71

Integration

In the Connections pane navigate to the Web Site you want integrate the Axon.ivy Engine into. Use the context
menu Add Virtual Directory ... of the Web Site to add a new Virtual Directory. A dialog opens. Configure
the Alias of the Virtual Directory with ivy and the Physical path of the Virtual Directory with the path of the
integration directory. Click OK to close the dialog and create the Virtual Directory:

6.

Handler Mapping Permissions

Note
The following command automatically sets the feature permission for the ivy virtual directory:
appcmd.exe set config "Default Web Site/ivy" /section:system.webServer/handlers /
accessPolicy:Read,Write,Execute
Select the new created Virtual Directory ivy in the Connections pane and open the Handler Mappings entry
in the Feature View:

In the Actions pane select the Edit Feature Permissions ... menu:

72

Integration

On the Edit Feature Permission dialog select all three permission and click OK:

7.

Configure Error Page

Note
The following command automatically configures that the detailed error page of the Engine is shown:
appcmd.exe set config "Default Web Site/ivy" /section:system.webServer/httpErrors /
errorMode:Detailed

Tip
See chapter Error Handling for more information about this configuration.
Select the new created Virtual Directory ivy in the Connections pane and open the Error Pages entry in the
Feature View:

73

Integration

Right click and select Edit Feature Settings... or select the same from the Actions pane (in the right
hand side)

Select the Detailed errors radio button and click on OK

8.

Install ISAPI filter

Note
The following command automatically adds the ISAPI Filter:
appcmd.exe set config /section:isapiFilters /+[@start,name='Tomcat',path='\isapi_redirect-1.2.42.dll']
Select the Web Site in the Connections pane and open the ISAPI Filters entry in the Feature View:

In the Actions pane select the Add ... menu:

74

Integration

On the Add ISAPI Filter dialog configure the Filter name with Axon.ivy Engine and the Executable
with the path of the isapi_redirect-1.2.42.dll located in the integration directory. Click OK to add the ISAPI Filter:

9.

Change ISAPI filter restriction

Note
The following command automatically adds the ISAPI Restriction:
appcmd.exe set config /section:isapiCgiRestriction /+[@start,description='Tomcat',path='\isapi_redirect-1.2.42.dll',allowed='true']
In the Connections pane select the node that represent your machine and open the ISAPI
Restrictions entry in the Features View:

75

and

CGI

Integration

In the Actions pane select the Add ... menu:

On the Add ISAPI or CGI Restriction dialog configure the ISAPI or CGI path with the path of the
isapi_redirect-1.2.42.dll located in the integration directory. As Description use Axon.ivy Engine. Select the
Allow extension path to execute check box. Click OK to add the ISAPI or CGI Restriction:

76

Integration

10. If your Microsoft Internet Information Server is not running on the same host as the Axon.ivy Engine or if you have
changed the AJP port of the Axon.ivy Engine then open the file worker.properties inside the integration directory in a
text editor. Change the following line if you have changed the AJP port to another value than 8009:
worker.AxonIvyEngine.port=8009
Change the value localhost in the following line to the host where your Axon.ivy Engine is running if your Microsoft
Internet Information Server is not running on the same host as the Axon.ivy Engine:
worker.AxonIvyEngine.host=localhost
11. Update the external base URL in the Admin UI
12. Check if the integration is working by opening a web browser on the address http:///ivy/

Change context URI /ivy/
The context URI /ivy/ can be changed inside the Axon.ivy Engine by changing the system property
WebServer.IvyContextName (See chapter System Properties to learn about how to change a system property).
However, if you change the context URI on the Axon.ivy Engine you also have to change the context URI in the Microsoft
IIS integration. This can be done by changing the last line of the uriworkermap.properties configuration file:
/ivy/*=AxonIvyEngine
If you want to have /xpertline/ as the context URI change this line to the following:
/xpertline/*=AxonIvyEngine

Access multiple Axon.ivy Engines through one IIS
Multiple Axon.ivy Engine instances can be accessed through a single IIS server. This is especially useful if multiple Axon.ivy
versions must be accessible during a migration phase. The following explanation shows a solution for the scenario, where a
legacy Xpert.ivy 3.9 Server and an Axon.ivy 5.x Engine must be accessible through a single IIS host.
1.

Make the newer Axon.ivy Engine accessible through the IIS as if only one engine would be behind the IIS. For detailed
instructions follow “Microsoft IIS Integration”.
In our scenario the integration directory from the Axon.ivy 5.x Engine was used to make the engine instance accessible
under http://localhost/ivy.

2.

The contexts of the Axon.ivy Engines must be unique. By default the context is set to /ivy/ . If different versions of
ivy engines are accessed from the same IIS host, it's useful to change the contexts so that it matches the ivy version. For
detailed explanation see “Change context URI /ivy/”
In our scenario the context URI of the Axon.ivy 5.x Engine was changed to /ivy5/ and the Xpert.ivy 3.9 Server kept
his default context /ivy/.

3.

All Axon.ivy Engines, which are accessed from the same IIS, must listen on a different port for AJP communication.
Therefore the AJP port must be changed. For detailed explanation see “Web Server Ports”.
In our scenario the AJP port of the Axon.ivy 5.x Engine was changed to 8010 and the Xpert.ivy 3.9 Server kept his
default AJP port 8009.

4.

The Axon.ivy Engines must be declared in the worker.properties file of the integration directory. It's important that each
worker has a unique name and that they are listed in the worker.list property.
In our scenario the worker.properties looks as follows:
worker.XpertIvyServer3x.type=ajp13
77

Integration

worker.XpertIvyServer3x.port=8009
worker.XpertIvyServer3x.host=ivyhostname39
worker.AxonIvyEngine5x.type=ajp13
worker.AxonIvyEngine5x.port=8010
worker.AxonIvyEngine5x.host=ivyhostname50
worker.list=XpertIvyServer3x,AxonIvyEngine5x
5.

The contexts of the Axon.ivy Engines must be registered in the uriworkermap.properties file of the integration directory.
In our scenario we make Axon.ivy 5.x available under http://localhost/ivy5/ and Xpert.ivy 3.9 under
http://localhost/ivy. So the uriworkermap.properties file looks as follows:
/ivy/*=XpertIvyServer3x
/ivy5/*=AxonIvyEngine5x

Single Sign On
Axon.ivy Engine supports single sign on in Windows environments. The following preconditions must be fulfilled for single
sign on:
• The application on the Axon.ivy Engine must use Active Directory Security System
• The Axon.ivy Engine must be integrated into a Microsoft Internet Information Server (IIS)

IIS 6 (Windows Server 2003)
To activate the single sign on open the Internet Information Services (IIS) Manager (Start > Control Panel > Administrative
Tools > Internet Information Services (IIS) Manager). On the left pane select the context menu Properties on the ivy
Virtual Directory node. A dialog appears. On the tab Directory Security click on the Edit ... button in section
Authentication and access control. A new dialog appears.
Select the check box Integrated Windows authentication. Make sure that all other authentication modes such as
Enable anonymous access or Digest authentication for Windows domain servers are disabled,
otherwise IIS will use those authentication modes and Single Sign On will not work.
Click OK again to close the Properties dialog.
To use only NTLM as security provider for the whole IIS, change into the InetPub\Adminscripts\ directory and execute
following command:
Cscript adsutil.vbs set w3svc/NTAuthenticationProviders "NTLM"

78

Integration

IIS 7 (Windows Server 2008)
Note
There is a batch script autoconfigSSO.bat in the folder misc\iis of your engine installation. This script
automatically sets up SSO on a Windows 2008 Server.
If you are setting up a new IIS Server you can use this script instead of following the instructions below.
1.

Install Windows Authentication

Note
The following command automatically installs the Windows Authentication:
PKGMGR.EXE /iu:IIS-WindowsAuthentication
Open the Server Manager (Start > Control Panel > Administrative Tools > Server Manager). Navigate to the node
Server Manager > Roles > Web Server (IIS) and select it. Validate that under the Role Services the service Window
Authentication is installed. If this is not the case select the menu Add Role Services to install the missing
service.

79

Integration

2.

Deactivate Anonymous Authentication

Note
The following command automatically deactivates the Anonymous Authentication:
set path=%path%;%windir%\system32\inetsrv

appcmd.exe set config "Default Web Site/ivy" -section:system.webServer/security/authentication/
anonymousAuthentication /enabled:"False" /commit:apphost
Open the Internet Information Services (IIS) Manager (Start > Control Panel > Administrative Tools > Internet
Information Services (IIS) Manager). In the Connections pane select the ivy Virtual Directory node. In the
Feature View open the Authentication entry. Select the Windows Authentication and use the menu
Enable in the Actions pane to enable Windows Authentication.
Make sure that all other authentication modes such as Anonymous
Authentication or Digest
Authentication are disabled, otherwise IIS will use those authentication modes and Single Sign On will not work.

80

Integration

3.

Activate Windows Authentication

Note
The following command automatically activates the Windows Authentication:
appcmd.exe set config "Default Web Site/ivy" -section:system.webServer/security/authentication/
windowsAuthentication /enabled:"True" /-"providers.[value='Negotiate']" /commit:apphost
Remove all providers expect NTLM from Windows Authentication, otherwise Single Sign On may not work with the
RIA clients.
IIS 7.5 (Windows Server 2008 R2)
Select the Windows Authentication and use the menu Providers ... in the Actions pane to configure
the enabled providers. Remove all providers expect NTLM from this list.

81

Integration

IIS 8 (Windows Server 2012)
Note
There is a batch script autoconfigSSO.bat in the folder misc\iis of your engine installation. This script
automatically sets up SSO on a Windows 2012 Server.
If you are setting up a new IIS Server you can use this script instead of following the instructions below.
1.

Install Windows Authentication

Note
The following command automatically installs the Windows Authentication:
PKGMGR.EXE /iu:IIS-WindowsAuthentication
Open the Server Manager (Start > Server Manager). Select the Web Server (IIS). Validate that under the Role
Services the service Window Authentication is installed. If this is not the case select the menu Add Role
Services to install the missing service.

82

Integration

2.

Deactivate Anonymous Authentication

Note
The following command automatically deactivates the Anonymous Authentication:
set path=%path%;%windir%\system32\inetsrv

appcmd.exe set config "Default Web Site/ivy" -section:system.webServer/security/authentication/
anonymousAuthentication /enabled:"False" /commit:apphost
Open the Internet Information Services (IIS) Manager (Start > Internet Information Services (IIS) Manager). In the
Connections pane select the ivy Virtual Directory node. In the Feature View open the Authentication
entry. Select the Windows Authentication and use the menu Enable in the Actions pane to enable Windows
Authentication.
Make sure that all other authentication modes such as Anonymous
Authentication or Digest
Authentication are disabled, otherwise IIS will use those authentication modes and Single Sign On will not work.

83

Integration

3.

Activate Windows Authentication

Note
The following command automatically activates the Windows Authentication:
appcmd.exe set config "Default Web Site/ivy" -section:system.webServer/security/authentication/
windowsAuthentication /enabled:"True" /-"providers.[value='Negotiate']" /commit:apphost
Remove all providers expect NTLM from Windows Authentication, otherwise Single Sign On may not work with the
RIA clients.

Troubleshooting
See “Request Entity Too Large”

Basic Authentication
In the following situations Basic Authentication is required:
• to use the Axon.ivy Mobile App
• to provide REST services which require authentication

IIS 8 (Windows Server 2012)
Note
There is a batch script autoconfigBasicAuth.bat in the folder misc\iis of your engine installation. This script
automatically sets up Basic Authentication on a Windows 2012 Server.
If you are setting up a new IIS Server you can use this script instead of following the instructions below.
1.

Install Basic Authentication

Note
The following command automatically installs Basic Authentication:

84

Integration

PKGMGR.EXE /iu:IIS-BasicAuthentication
Open the Server Manager (Start > Server Manager). Select the Web Server (IIS). Validate that under the Role
Services the service Basic Authentication is installed. If this is not the case select the menu Add Role
Services to install the missing service.

2.

Activate Basic Authentication

Note
The following command automatically activates the Basic Authentication:
set path=%path%;%windir%\system32\inetsrv

appcmd.exe set config "Default Web Site/ivy" -section:system.webServer/security/authentication/
basicAuthentication /enabled:true /commit:apphost
Open the Internet Information Services (IIS) Manager (Start > Internet Information Services (IIS) Manager). In the
Connections pane select the ivy Virtual Directory node. In the Feature View open the Authentication
entry. Select the Basic Authentication and use the menu Enable in the Actions pane to enable Basic
Authentication.

85

Integration

Axon.ivy Cluster Integration
Axon.ivy Engine Enterprise Edition (Cluster) works with sticky sessions. This means that the load balancer must forward all
requests from a session to the same cluster node. Of course if a cluster node is no longer available then the request can be sent
to another cluster node. Note, that this will cause that the user gets a new session and he loses his current work.

Load Balancing with Tomcat connector (IIS, Apache)
The Tomcat connector can be configured to act as a load balancer for multiple Axon.ivy Engine Enterprise Edition nodes. The
load balancer and the cluster nodes can be configured in the workers.properties file that is located in the integration directory.
An example load balancer configuration can be found in the file cluster_loadbancer_workers.properties. In this file one
worker is configured called AxonIvyEngine that is a load balance worker (type=lb). The property balance_workers
of the AxonIvyEngine worker defines the workers between which the load balance worker will balance the load. Here
one worker per each Axon.ivy Engine Node should be configured. In the example file three workers are configured
AxonIvyEngineNode1, AxonIvyEngineNode2 and AxonIvyEngineNode3.
The node workers are similar to a normal standalone worker. You can use the attributes hostname and port as explained
above. Additionally they have two extra attributes called lbfactor and route. With the lbfactor attribute you can
influence how the load balancer distributes the load to the workers. The higher the lbfactor of a worker relative to the
other workers is the more load the worker gets.
The route attribute is necessary for realizing sticky sessions. An Axon.ivy Engine Enterprise Edition will only work
correctly, if the load balancer sends all request of the same http session to the same node (sticky sessions). To support this
requirement, each Axon.ivy Engine Enterprise Edition node will add a special identifier called jvm route to the http session
identifier. The jvm route identifier is calculated from the host name and the Local Cluster Node Identifier. The route
attribute configured on a node worker must be equal with the jvm route of the node:
worker.AxonIvyEngineNode1.route=
worker.AxonIvyEngineNode2.route=
The JVM route identifier of a cluster node can be found on the cluster node detail page for an Axon.ivy Cluster Node. This
information can be retrieved as follows:
1.

Using a web browser, navigate to the main page (http://:/ivy) of an Axon.ivy Engine installation.

86

Integration

2.

Select the Cluster link in the page header.

3.

In the appearing list of cluster nodes press the name of a cluster node to see it's details.

Figure 5.2. Axon.ivy Cluster Node Details page
More technical details about load balancing and sticky sessions can be found on the Apache Tomcat web site.

Example
Let's assume that we have an Axon.ivy Engine Enterprise Edition with two Cluster Nodes. Node 1 is installed on host
ivynode1 and the AJP port is configured to 8009. Node 2 is installed on host ivynode2 and the AJP port is configured to
8010. ivynode1 is a new machine with a lot of power. ivynode2 is an old machine and we want that ivynode1 is working
twice as hard as ivynode2. The jvm route of the nodes are ivynode1.soreco.ch and ivynode2.soreco.ch.
The workers.properties file must then look like this:
worker.list=XIvy
# Load Balanced Cluster Worker
worker.AxonIvyEngine.type=lb
worker.AxonIvyEngine.balance_workers=AxonIvyEngineNode1,AxonIvyEngineNode2
# 1st Axon.ivy Engine Cluster Node
worker.AxonIvyEngineNode1.type=ajp13
worker.AxonIvyEngineNode1.port=8009
worker.AxonIvyEngineNode1.host=ivynode1
worker.AxonIvyEngineNode1.route=ivynode1.soreco.ch
worker.AxonIvyEngineNode1.lbfactor=2
# 2nd Axon.ivy Engine Cluster Node
worker.AxonIvyEngineNode2.type=ajp13
worker.AxonIvyEngineNode2.port=8010
worker.AxonIvyEngineNode2.host=ivynode2
worker.AxonIvyEngineNode2.route=ivynode2.soreco.ch
worker.AxonIvyEngineNode2.lbfactor=1

Load Balancing with other Load Balancer Products
As described above the load balancer must ensure that all requests from the same user session is forwarded to the same cluster
node. This can be done by configuring the load balancer so that all requests sent by one client IP address is always forwarded
to the same cluster node (IP based stickiness). Another possible configuration is to use the Axon.ivy Session Id to provide
session stickiness. The session id is provided by Axon.ivy Engine Enterprise Edition with two different methods. Either as

87

Integration

HTTP session cookie with the name JSESSIONID or at the end of request URLs as ;jsessionid= parameter. The load
balancer must be able to read the session id with both methods otherwise RIA clients will not work correctly.

Warning
Some load balancer provide session stickiness using their own HTTP session cookie. If you use this method
then RIA clients will fail to start.

Web Application Firewall
A web application firewall (WAF) or web shield is a firewall which protects web applications against attacks over the HTTP
protocol. Combined with an Identity and Access Management (IAM) System it also protects against unauthorized access and
supports single sign on (SSO).

Single Sign On
Most WAF or IAM systems allow to configure a way how the user name of the identified user is transmitted to the web
applications. With Axon.ivy Engine a typical system landscape will look like this:

Figure 5.3. Single Sign On Infrastructure using a Web Application Firewall, Identity and Access
Management and Active Directory
The only available access point must be the WAF. Any traffic has to be routed over it. The WAF tries to protect the web
application behind it (e.g. Axon.ivy Engine) from attacks. The WAF uses the IAM to identify users and to protect certain
resources from unauthorized access. The IAM itself may use a directory server like Microsoft Active Directory to know users.
The WAF can be configured to provide the name of the identified user either as HTTP header or HTTP cookie to the web
application (Axon.ivy Engine).
On the other side Axon.ivy Engine provides a Valve that reads the user name from a HTTP header. If Axon.ivy Engine knows
the user it automatically authenticates the user to the current Axon.ivy Engine session. This works best if Axon.ivy Engine
also uses a directory server like Microsoft Active Directory to synchronize users. The Valve that reads the user name from a
HTTP header is disabled by default. To enable it, open the file webapps/ivy/META-INF/context.xml from the Axon.ivy Engine
installation directory and uncomment the following line:

88

Integration

 will show the default Axon.ivy pages.
HtmlWfUi will show up, if you have deployed the "Axon.ivy Workflow UI (Html
Version)".
Any process model deployed, which contains a request start with a signature for at
least one page will be shown in the dropdown. Instead of showing the default pages,
the corresponding process of the selected process model is started. If the process start
signature of the default page is not available in the selected project, the default page
from Axon.ivy will be used.

Process Models and Process Model Versions
An application can have multiple process models. Each process model can have different versions. A process model
corresponds to the concept of a project on the Axon.ivy Designer. A process model version corresponds to a versioned snapshot
of that project at some point of time.

The Concept of Versions
A process model can exist in multiple versions called process model versions. These versions allow you to make changes in
a project and deploy it again without having to worry about the compatibility of currently running cases. If the new version
is not working as expected, you can always go back to a previous working version.

Creating Process Models and Process Model Versions
To create a new process model, you have to select the application in which you would like to create it. Press the new process
model button in the toolbar ( ). You will be asked for a name (typically you chose the name to be the same as the name of
the project you intend to deploy within this process model) and an optional description.
Once you have created the process model, you can continue with adding a first process model version. To do so, select the
process model from the tree on the left hand side and press the new process model version button (
to enter a name and an optional description again.

). You will be prompted

Tip
It is recommended to use the description field of the new process model version to document the major changes
from the previous version.

Manage Activation and Release State
Applications, process models and process model versions all have an activation state. The process model version additionally
has a release state.

Figure 6.5. Managing the activation state
To bring a process model version into the Active state, the process model version itself, the parent process model and the
parent application have to be in the state Active. Furthermore, the release state of the process model version has to be in
RELEASED or DEPRECATED. The same is necessary for all required libraries of that process model version.

96

Administration

When looking at the details of an application, process model or process model version you will always see a Configured
state and a State. The Configured state is the one you can freely change and the State is the actual state that depends on the
states of the parent process model and application and of the release state.

Figure 6.6. Managing the release state

Release States
Name

Description

PREPARED

The process model version has been created and a project may
already be deployed. However, the process model version is
not used yet.

RELEASED

The process model version is the currently released version.
This means that all new cases will be started within this
version. Only one version in a process model may be in this
state.

DEPRECATED

The process model version has previously been in state
RELEASED. But another process model version was
released and activated recently. All cases that were started
in this process model version will finish in this version. As
soon as there are no more running cases in this version and
all process model versions that are using it are not in state
RELEASED nor DEPRECATED, the state will change to
ARCHIVED automatically.

ARCHIVED

The process model version has previously been in state
RELEASED or DEPRECATED. There are now no more
cases that are running in this version, it is safe to delete
it. Process model versions in this state are not started and
therefore only use minimal resources. You may set it back
again to RELEASED.

DELETED

The process model version has been deleted. All data that
belong to this version are deleted too.

Table 6.1. Release states

Activation states
Name

Description

INACTIVE

No new process in this process model version can be started
and all running cases and tasks have been suspended.

ACTIVE

New processes in this version can be started and all tasks are
active.

LOCKED

No new process can be started, but the currently running tasks
can continue to their next savepoint.

DEACTIVATING

The state is changing to INACTIVE.

ACTIVATING

The state is changing to ACTIVE.

LOCKING

The state is changing to LOCKED.

Table 6.2. Activation states
97

Administration

Project dependencies
Projects can depend on each other. The dependencies are configured in the deployement descriptor of the project. This
dependencies are evaluated and resolved during the deployment of a project. On the process model version detail page you
can press Dependencies... to see the resolved dependencies of the project deployed to the process model version. You see the
process model versions that the current process model version requires. And also vice versa which process model versions
require the current process model version.
To change a resolved dependency select the dependency and press Edit Selection. You can then select another version that
fullfils the dependency requirements.

Figure 6.7. Project Dependencies

Project Deployment
Project deployment means to take a project created in the Axon.ivy Designer and to load it into a process model version, so
that you can execute the project on the engine.
Before you begin with the deployment of a project make sure that you also have all required projects either already deployed
to the engine or available in the same folder or in the same *.zip file as the major project.

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

98

Administration

Even though overwriting an already deployed project version (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 wizard
The deployment wizard can be started on the toolbar.

Figure 6.8. Command to Start the Deploment Wizard on the Toolbar
On the first page of the wizard select the projects that you want deploy. The projects can either be located on the server or
on the client. If you select a folder then the wizard searches all packed (ivy archive) or unpacked projects located below that
folders. If you select a *.zip file then the wizard searches all projects located inside the *.zip file. The found projects will be
displayed. Select the projects you want to deployed and press Next.

Tip
Read the chapter Deployment in the Axon.ivy Designer Guide to find out how to create a zip file that contains
all files of a project.

Tip
Read the chapter Projects in the Axon.ivy Designer Guide to find information about ivy archives and how to
export them.

99

Administration

Figure 6.9. Deployment Wizard - Source
On the second page of the wizard select the applications to which you want to deploy your projects and press Next.

Figure 6.10. Deployment Wizard - Target
100

Administration

On the third page of the wizard you see a preview of the actions the wizard will perform. Note, that the wizard automatically
choose the process model and process model version where it deploys a project to. If everything is as you expect press Next.
If you do not like the automatically default behaviour press Previous and then on the previous page Details to choose another
configuration. More information about process model and process model version can be found in the previous chapter.

Figure 6.11. Deployment Wizard - Preview
On the fourth page of the wizard the projects are validated. If no errors are found you can press Next. If you get warnings
please read them carefully and then decide if you want to proceed or not.

101

Administration

Figure 6.12. Deployment Wizard - Validate
On the last page of the wizard the projects are deployed. During the deployment a log is written which contains information
about the tasks that are executed. Press Finish to close the wizard.

102

Administration

Figure 6.13. Deployment Wizard - Deploy

Deployment directory
Makes simple deployment of Axon.ivy projects to an Axon.ivy Engine possible by copying the project into the deployment
directory.
The deployment directory is by default the directory with the name 'deploy' in the Axon.ivy Engine root directory. It can be
altered trough the system property 'Deployment.Directory'.

File based deployment
1.

Ensure that the Axon.ivy Engine, to which the Axon.ivy project should be deployed, is up and running.

2.

Navigate to the sub directory in the deployment directory which matches the name of an already created Application
on the Axon.ivy Engine.

3.

Copy an Axon.ivy project to deploy into the created application directory. The project must either be packed as ivyarchive (IAR) or ZIP or be contained in a file directory.

4.

Initialize the deployment by creating a new empty file with the name of the project file or directory plus the suffix
'.doDeploy'. E.g. If you the project /deploy/MyApp/JsfWorkflowUi.iar has been copied in the previous step, the creation
of the file /deploy/MyApp/JsfWorkflowUi.iar.doDeploy initializes the deployment.

5.

Wait until the file with the suffix '.doDeploy' disappears, it indicates that the deployment has finished.

6.

Determine whether the deployment was successful. If no file with suffix '.deploymentError' was created, the deployment
has finished successfully. The detailed log is available in the file with suffix '.deploymentLog'.
File suffix

Description

.doDeploy

Initializes the deployment and is deleted when the deployment process has finished

.deploymentLog

Contains the log output which is written during the deployment

103

Administration

File suffix

Description

.deploymentError

Contains the error cause and is only written when the deployment fails

Table 6.3. Deployment marker files

Maven deployment
The Maven project-build-plugin makes automated continuous deployment to an Axon.ivy Engine possible.
An Axon.ivy project can be deployed by invoking Maven with the deploy-iar goal of the project-build-plugin. To
customize the deployment parameters, consult the goal documentation.

Command line deployment
The 'deploy-iar' 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:6.1.0-SNAPSHOT:deploy-iar -Divy.deploy.iarFile

Build goal execution
To deploy an ivy-archive (IAR) during it's Maven build lifecycle configured an execution which binds the 'deploy-iar' 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'.

com.axonivy.ivy.ci
project-build-plugin
true


deploy.to.engine
deploy-iar
deploy

Portal
c:/axonivy/engine




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

Business Calendar
A business calendar defines the following three things:
• Days which are free of work. E.g. 25. December.
• Period in a Day which is working time. E.g. 08:00-17:00
• First Day of the Week. E.g. Monday
Business calendars are used to calculate time periods in working time. For example a period of 3 working days starting on
Friday would end on Tuesday if Saturday and Sunday are defined as free days. For more information consult the documentation
of ch.ivyteam.ivy.application.calendar.IBusinessCalendar in the Public API.

104

Administration

Every application has at least one business calendar. The business calendars can be configured using the Configure Calendar
Settings Button on the Application Configuration screen.
Every environment can have its own default business calendar (see chapter Environment Business Calendar ).

Business Calendar Definition
Business calendars are defined in a hierarchy. The children inherit all definitions of all its parents. All business calendars must
directly or indirectly inherit from the Default business calendar.

Start of Week
The Start of Week defines the first day of a week. In Switzerland and its neighbour countries this is Monday. In other countries
like Great Britain the week starts on Sunday.

Working Time
The Working Time defines which time of a day is working time. E.g. 08:00-12:00, 13:00-17:00
The working time applies to all days which are not defined as free days. It is not possible to define different Working Times
for different days.

Free Days of Week
The Free Days of Week define at which days of the week no work is done. E.g. Saturday, Sunday

Free Days of Year
The Free Days of Year define at which days of the year no work is done. These free days of the year will be free every year
at the same day. E.g. 1.1. (New Years Day), 25.12 (Christmas).

105

Administration

Free Easter Relative Days
The Free Easter Relative Days define days of the year no work is done. These free easter relative days will be free every year
at another day depending on the easter day. E.g. 0 (Easter Day), 1 (Easter Monday), -2 (Good Friday).

Free non-recurring Dates
The Free non-recurring Dates define non-recurring days when no work is done. These free non-recurring days will only be
free once. E.g. 7.12.1931.

Environments
This section briefly discusses the usage of environments in your projects .Developers should have the possibility to configure
multiple environments (pointing to an infrastructure) and decide at runtime which environment should be used for the
application. For instance you can have a development environment, a test environment and a productive environment. Here
are some examples where environments can be used
• Companies provide different environments for their software products, like Development, Test and Productive. Each
environment has its own infrastructure including databases, web services and other connections used by the project.
• Multi Client Capability. When the user logged into the system he can choose the mandant (e.g. Company 1, Company 2,
etc.) and works with the data of the selected company. In the background the right databases connections, web services and
other services for the selected environment will be used.
If your projects use environments, you have to configure the respective environment configurations on the engine. The first
time you deploy an application that uses environments, the environments of the project will automatically be added on the
engine as well. Each application manages his own environments. If you already define your different environments in your
project on the designer, you don't need to reconfigure these environments on the engine again. This has the advantage that
you can already test different environments at design time, before you deploy your projects on the engine. Each application
contains a Default environment where all default values of the global variables and default database configurations are defined.
In addition to the default environment, each application has one ore more user defined environments.
In order to change the environment for an application at runtime you must go to the details of an application and change the
active environment for that application and press Set

Figure 6.14. Set active environment for an application
Environments acts as a container for
• Global Variables
• External Database Configurations
• Web Service Configurations

106

Administration

• REST Client Configurations
• Business Calendar Configurations

Configuration of environments
Environment configurations can be changed by double-click on the environment entry in the list. You will see that the
environment acts as a container for global variables and external database configurations. The description of the environment
can be used to provide important infrastructure information about the server, databases and other stuff, which can be relevant
to other users.

Figure 6.15. Environment details

Global Variables
Global Variables acts as global constants which can be used in your application. Global Variables are simple Key/Value pairs
which can be specified by the developer. Some examples for global variables are:
• Company data (name, address, contacts)
• Simple Rule Values (e.g. credit account)
• Path values for saving files
• Path values for 3rd party systems and some other variables
Global variables must be defined at design time. It is not possible to create new variables on the engine. Each variable has
a default value, configured at design time or in the default environment. In order to override the values of global variables for
a environment just double-click the variable entry and override the values in the detail dialog. The default value of a global
variable must be set in the Default environment.

107

Administration

Figure 6.16. Details of a global variable
If the global variable is a default one, the system asks you to override the value for the environment. If you press "yes" the
value of the global variable is overridden for the environment. You can always reset the global variable, by pressing Reset
to Default.

Figure 6.17. Question to override the default value of the global variable

External Databases
If your projects use external databases, you have to configure the respective database connections on the engine. The first
time you deploy a project that uses external databases, the database configurations of the project will automatically be added
on the engine as well. Also available environment configurations which already done at design time, will be added. Since
you probably use a test database during development and you want to use your production database on the engine, you can
use the different environments to set a different configurations. Overridden Database configurations for an environment will
be displayed with the icon . Default database configurations or database configurations which are not overridden for the
environment will be displayed with the icon .
To change the connection settings, select on the entry for a database in the list. You will see the connection URL used to
connect to the database in the selected environment, the maximum number of connections, all currently open connections
and the last executed statements.
If the selected environment is not the default environment, and you select a database configuration, which has no environment
connection settings, you only can configure it. If you press Configure, the system asks you to override the database
configuration for the selected environment. Press Yes to override the database configuration for the environment. You can
always reset the database configuration to the default one, by pressing the button Restore to Default in the detail dialog, or
right click on the database in the list and use the Menu item Restore to Default.

108

Administration

Figure 6.18. Databases
You can directly edit the maximum number of connections that may be simultaneously used.
To change the connection settings, press the Configure button next to the driver and connection URL fields. This will bring
up a dialog in which you can configure the database product, driver, hostname, database, username, password and additional
connection properties.

Figure 6.19. Configuring the connection of an external database

Web Services
If your projects use web services, you have to configure the respective Web Service on the engine. The first time you deploy
a project that uses Web Services, the Web Service configurations of the project will automatically be added on the engine

109

Administration

as well. Also available environment configurations which already done at design time, will be added. Since you probably
use a test environment during development and you want to use your production environment on the engine, you can use the
different environments to set a different configurations. Overridden Web Service configurations for an environment will be
displayed with the icon:

. Default Web Service configurations or Web Service configurations which are not overridden for

the environment will be displayed with the icon

.

In order to edit a Web Service configuration just select the Web Service from the list and the details of the selected Web
Service will be displayed in the detail panel.
Name

The name of the Web Service. This attribute can not be modified on the engine.

Description

An optional description of the Web Service. This attribute can note be modified on
the engine

Use Authentication

The directory on the file system where all the files of this application and its process
models will be stored. You can specify an absolute directory (e.g. C:/Data/IvyApps/
App1 or /var/ivy/apps/app1) or a directory relative to the engine's installation directory
(e.g. apps/App1). The directory may already exist, but it must be empty.

Session Handling Mode

You can chose session handling mode for current configuration. There are 3 modes
available now:
• NO there will be no session handling when you use this configuration
• WSELEMENT invoking the same service from the same "WS step" process entry
existing sessions will be reused
• APPLICATION Within ivy applications whenever you invoke the same service
existing session will be reused

Authentication Type

You can chose a authentication Mode for current configuration. There are 3 types
available now:
• HTTP BASIC Use the HTTP basic authentication for the Web Service call
• HTTPS Use HTTPS transport
110

Administration

• DIGEST Use DIGEST authentication
Username

When authentication is used, this username will be applied to get access to this web
service. You can use IvyScripts in this field.

Tip
When you specify authentication in "WS step" process element, these
settings (Username and Password) will be overridden. Use Scripts like
"in.user" carefully, since you might use this WS entry in multiple
processes with different data types.
Password

When authentication is used, the username above and this password will be applied to
get access to web service. IvyScript is also interpreted in this field.

Endpoint Addresses for Port Types

The name of the Web Service. This attribute can not be modified on the engine.

REST Clients
If your projects use REST Clients, you have to configure the respective REST Clients on the engine. The first time you deploy
a project that uses REST Clients, the REST Client configurations of the project will automatically be added on the engine
as well. Also available environment configurations which already done at design time, will be added. Since you probably
use a test environment during development and you want to use your production environment on the engine, you can use the
different environments to set a different configurations. Overridden REST Client configurations for an environment will be
displayed with the icon: . Default REST Client configurations or REST Client configurations which are not overridden for
the environment will be displayed with the icon

.

In order to edit a REST Client configuration just select the REST Client from the list and the details of the selected REST
Client will be displayed in the detail panel.
UUID

Universal unique identifier of the REST Client. The REST Client can be referenced by this uuid.
Cannot be modified.

Name

The name of the REST Client. The REST Client can be referenced by this name. Can be modified.
Note that references using the name will break if you change it.

111

Administration

Description

Description of the REST Client.

URI

The base URI under which the remote service publishes its resources (e.g. https://api.twitter.com/1.1).
The URI can contain template placeholders which are resolved later by the client user (e.g. https://
api.twitter.com/{version}).
ivy.rest.client("twitter").resolveTemplate("version", "1.1").get()

Tip
To consume a REST service running in the same Axon.ivy Engine / Application
as the client a set of Axon.ivy placeholders can be used. These placeholders are
automatically resolved: {ivy.engine.host}, {ivy.engine.http.port}, {ivy.engine.context},
{ivy.request.application}.
E.g.
http://{ivy.engine.host}:}{ivy.engine.http.port}/
{ivy.engine.context}/api/{ivy.request.application}/my/
service
Authentication

Features

Properties

HTTP Basic

Adds support for HTTP Basic authentication.

HTTP Digest

Adds support for HTTP Digest authentication.

Username

The name of the user used to authenticate the client.

Password

The password of the user used to authenticate the client.

JSON

Adds a feature so that responses in JSON are mapped to Java Objects and Java
Objects in requests are mapped to JSON.

Features List

Shows the configured "features" classes. The classes configured here are
registered in the WebTarget using the method register(Class). The
classes needs to implement a JAX-RS contract interface and must have a default
constructor.

Add

Adds a new feature class.

Remove

Removes the selected feature.

Properties Table

Properties can customize the settings of the REST Client or one of
its features. Well known properties of the client are documented here:
org.glassfish.jersey.client.ClientProperties.
The properties configured here are registered in the WebTarget using the
method property(String, Object).

Add

Adds a new property.

Add Password

Adds a new password property. The value of a password property is not
visible in the table and is stored decrypted in the configuration file.

Remove

Removes the selected property.

Business Calendar
Each environment can define its own default business calendar which is going to be used to calculate time periods in working
time if the environment is active. By default the global default business calendar is set.
Business calendars are defined on the Application (see chapter Application Business Calendar)
112

Administration

Export/Import Environment(s)
One or multiple environments can be exported into or be imported from a XML file. All configurations that belong to the
selected environments will be exported or imported (see previous sub chapters). This can be used to transfer environment
configurations from one Axon.ivy Engine installation to another. It is even possible to modify the exported XML before it
is re-imported on the same or another engine.

The files can be chosen from the local computer that the user is working on or from the server.
Note, that the export/import log file does not have to be set. In any case, you will see an graphical log of the results during
the export or import.

Note
The imported environment data has always precedence over the data in any existing environments. Exactly
speaking, the following rules apply:
• If a configuration exists both in the import file and in the target environment, then the data for this
configuration will be taken from the import file.
• If a configuration exists in the import file but in the target environment, then the configuration from the import
file will be created in the target environment.
• If a configuration does not exist in the import file but exists in the target environment, then the configuration
in the target environment will be deleted.
• If a configuration is defined in the import file but does not have a corresponding default configuration in the
target application then nothing happens.
• If the import file contains an environment that does not exist in the target application, this environment is
not imported.

113

Administration

Users and Roles
Roles and users are always configured per application. On the application details panel, you will find a group Security System.
There the number of all existing users and roles are shown.
If you are using an external security system such as Microsoft Active Directory you can force a synchronization with the
directory using the Synchronize button. To change the connection and import configuration, press the Edit... button.

Figure 6.20. Overview of roles and users

User list
When clicking the Show... button next to number of users, you will be presented with a list of all existing users. You can
create, edit and delete users. You can also set roles and permissions of any users individually.

Note
When using Microsoft Active Directory or Novell eDirectory as security system, you will not be able to create,
edit or delete users. All these tasks need to be performed on the Active Directory or eDirectory directly and will
then be synchronized with Axon.ivy.

Figure 6.21. List of all users

Creating a New User
To create a new user press the Create... button. Enter the information for the new user (the username must be unique within
the application). All other fields are optional.

114

Administration

Figure 6.22. Creating a new user
For the email notification settings you can decide whether the user uses the defaults defined by the application (they are shown
in light gray if you choose so) or whether you want to define specific settings for the user. Note that each user can manipulate
these settings in the Workflow UI.

Email Notification Settings
It is possible to be notified if a new task is created that is related to you (either by direct assignment or by assignment to a role
you own). Furthermore, a daily digest mail with a summary of all open tasks can be sent to you by Axon.ivy.
Which language should be used for
the emails

Choose in which language you would like to receive the emails. If your preferred
language is not contained, please contact your Axon.ivy administrator.

Never (disable email notification)

You can switch off the sending of all notification mails by ticking this checkbox. If
you do so, you cannot set the other options.

When a new task for me or one of
my roles is created

If this is set, you will receive a notification email whenever a new task is created that
is assigned either directly to you or to one of the roles you own.

Daily Summary on

Choose the days on which you want to receive an email with a summary of all your
open tasks.

Tip
If you want that temporary no mails are sent (e.g. for holidays), then just tick the Never checkbox. The email
sending is now switched off, but the previous settings are still stored. As soon as you untick the Never check
box, your standard configuration is back again.

Editing an Existing User
You can change the details of an existing user by pressing the Edit... button. You can change all fields except the username.
If the password field is left blank, it will not be changed. Otherwise the password of the user will be overwritten with the
new value of the password field.

Deleting a User
To delete a user, press the Delete... button and confirm the deletion.

115

Administration

Warning
Deleting a user will change the state of all tasks, for which the user is currently responsible, to UNASSIGNED!
All those tasks must be reassigned to another user or role by a workflow administrator or they will never be
finished.

Edit roles
Click the Roles... button to change the roles of a user.
You can add a role to a user by selecting the role from the list and then pressing Add. To remove a role, select it and press
Remove.
Some roles may not be editable. This can have multiple reasons:
• The role may be inherited (indicated by a grey checkbox and the text Inherited). A role is inherited if it is not explicitly set,
but the user owns a sub role (see example: Role 1 is inherited because user owns Role 1.1 and Role 1.3).
• You are using an external security system (e.g. ADS). In this case, you can not edit roles that are linked to a group on the
directory server. To add such a role, add the user to the corresponding group on the directory server.

Figure 6.23. Manage roles of a user

Properties
In this dialog it is possible to manipulate the properties of all users. Properties are key/value pairs that can be accessed at
runtime trough IvyScript. If using the internal security system of Axon.ivy (see Configuring an External Security System for
more information), then creation, editing and deletion are supported for all properties. If the users are synchronized with an
external data source such as an MS Active Directory and a mapping between attributes from the corresponding user in the
external system to the properties of the Axon.ivy user is configured, then editing and deletion of such properties is usually
prohibited by the external security system and therefore not possible within Axon.ivy. Just use the interface to the external
security system to manipulate the attributes directly there.

116

Administration

Figure 6.24. User properties
Just use the Add button to create new properties, the Edit button to manipulate the property value and the Delete button to
remove the property again. Note, that editing of the value can be done directly in the table.

Edit Permissions / System Permissions
You can edit the permissions of a user by selecting the user and clicking Permissions... or System Permissions... respectively.
See section Permissions for more information.

Roles
Press the Show... button next to the number of roles on the Security System section of an application to see a list of all
existing roles.
The roles are defined in the projects that you deploy in your application. You can not add or delete roles on the engine!
The list shows the roles with their name plus, if available, the external security name in square brackets.

Figure 6.25. List of all roles

Users of a Role
To add or remove users of a role, click the Users... button. You should now see a list of users not owning the role on the left
and a list of user that do own the role on the right. You can move users with the buttons in the middle from one list to another.

117

Administration

Note
When a user only inherits a role by owning a sub role thereof, the user will appear in the list of users not owning
the role.
When a role is linked to a group in an external security system, you will not be able to edit the users of a role.

Figure 6.26. Users of a role

Edit Permissions / System permissions
You can edit the permissions of a role by selecting a role and clicking Permissions... or System Permissions... respectively.
See section Permissions for more information.

External Security Name
If you are using an external security system (e.g. Microsoft Active Directory) then you can link an Axon.ivy role to a group or
another structural node (e.g. Organisation Unit) on the directory server. If a group is selected then all users that are members
of this group will automatically receive the associated Axon.ivy role. If a structural node is selected then all users located
below the structural node will automatically receive the associated Axon.ivy role.
Press External security name to edit or browse the name of the group or structural node whose users should receive the
selected Axon.ivy role.

Permissions
Permission Kinds
There are two kinds of permissions:
System Permissions

System permissions are valid system wide, e.g. on the whole engine.

Permissions

Regular permissions are valid only within the application for which they are defined.

Assignment of Permissions
You can assign different permissions and system permissions to each user or role.
A permission can either be granted, denied or unspecified (not granted). The actual permissions of an user depend on the
permissions set on the user itself and the permissions set on all roles that the user owns.
Grant permissions take precedence over Deny permissions, if set on the same level. On a user, inherited permissions can be
overridden with an explicit Grant or Deny.
118

Administration

Warning
Inherited Deny permissions have no effect if the user has an explicit Grant permission or another role on which
the permission is Granted. Explicit permissions always take precedence over inherited permissions.

Figure 6.27. Editing the permissions of a user

System Properties
System properties are engine wide settings and are therefore valid for all applications. Be careful when changing those settings,
since some particular combinations of settings may stop the engine from working properly.
The system properties can be accessed through the button System Properties in the Engine section of the left navigation bar.

Figure 6.28. Overview of system properties
To change any properties, select the corresponding row in the table and press the Edit button or simply double-click on the row.

119

Administration

Figure 6.29. Editing a system property

Note
Some settings may not take effect until you restart the engine.

Data Cache
Use the system property DataCache.InvalidationJob.Interval to configure the time in seconds between two
executions of the job that invalidates expired data cache entries.

Email Server
Use the system properties EMail.Server.* to configure a SMTP mail server that is used to send mails. The available
properties are similar to the Email preferences of the designer. For more information see Designer Guide > Introduction >
Axon.ivy Preferences (Workspace Preferences) > Email Settings.

Errors
Use the system property Errors.ShowDetailsToEndUser to configure wether details about an error should be shown to
an end user. For security reasons no details should be shown. For debugging reasons this option could be turned on temporary.
For more information see Show Error Details to End Users.

Process Engine Firing Statistic
Use the system properties ProcessEngine.FiringStatistic.* to configure the process element performance
statistic. For more details see Process Element Performance Statistic and Analysis.

SSL Client
Use the system properties SSL.Client.* to configure the key and trust store used for the client side of SSL connections.
The available properties are similar to the SSL Client preferences of the designer. For more information see Designer Guide
> Introduction > Axon.ivy Preferences (Workspace Preferences) > SSL Client Settings.

System Work Directory
Use the system property System.WorkDirectory to configure the directory where temporary work files are stored.

System Database Cache
Use the system properties SystemDb.Cache.* to configure how many and how long entities from the system database
are cached in memory.

System Tasks
Use the system property SystemTask.SearchJob.Interval to configure the time in seconds between two executions
of the System Task Search Job. The job searches system tasks that were not executed because of failures and initiate their
execution.

120

Administration

Use the system property SystemTask.Failure.Behaviour to configure the behaviour in case a System Task execution
fails. A system task is a task that is executed by the system.

Thread Pool
Use the system property ThreadPool.*.CorePoolSize to configure the number of threads that are at least used in
the thread pool.
Use the system property ThreadPool.*.MaximumPoolSize to configure the maximum number of threads that are used
in the thread pool. This property is not available for fixed sized thread pools.

Update Checker
Use the system property UpdateChecker.Enabled to configure if the update checker is enabled or disabled. The update
checker checks if a new update release is available. It also sends some statistic information to the vendor. For more details
see Update Notification.

Web Server
Use the system properties WebServer.AJP.* to configure the AJP protocol used for the communication between IIS or
Apache web server and the Axon.ivy Engine. For more information see Integration.
Use the system properties WebServer.HTTP.* to configure the HTTP protocol used for the communication with Web
Browsers and Rich Dialog clients.
Use the system properties WebServer.HTTPS.* to configure the HTTPS protocol used for the communication with Web
Browsers and Rich Dialog clients.
Use the system properties WebServer.External* and WebServer.IvyContextName to configure the external host
name, port and protocol used to provide links in mails. For more information see Update external base URL.
Use the system property WebServer.WellKnownServerPorts to configure additionally well known external web
servers that forwards requests to Axon.ivy engine. Format is host:protocol=port, host:protocol=port, ...
. Example: developer.axonivy.com:http=80, developer.axonivy.com:https=443.

Elasticsearch configuration
Use the system properties Elasticsearch.* to configure the bundled or external Elasticsearch server installation. For
more details, see Elasticsearch installation.

Engine infos
Runtime information
Pressing the button Information in the Engine section of the left navigation bar will provide you with runtime information
about the engine. This includes memory usage and stack-traces for all running threads.

121

Administration

Figure 6.30. Runtime information

About
Pressing the button About in the Engine section of the left navigation bar will provide you with information about the version
of Axon.ivy Engine and your operating system.

122

Administration

Figure 6.31. About

HTML Workflow UI
Axon.ivy does not provide a User Interface to manage tasks. There are APIs to access and manipulate the tasks of an
application. But the user interface to access the tasks must be implemented according to the needs of the application.
This chapter describes the possibilities which can be used in a HTML based Axon.ivy web application. For RIA based task
management please consult the RIA Workflow UI documentation.

Replacement Project
In a HTML based workflow application there are certain pages displayed depending on the state of your application and/or
workflow. You can override these default pages for each of your applications, to adopt it to your needs.
For each kind of page there is a predefined process start signature, which allows you to render the page in your own process
instead of using the default page. The following table shows which signature is needed to override each type of page.
Page

Description

Process Start Signature

Application
Home

Home Page of the application.

DefaultApplicationHomePage()

Task List

Contains a list of all Tasks the currently logged in user can work on.

DefaultTaskListPage()

Process Start Contains a list of all Processes the currently logged in user can work on.
List

123

DefaultProcessStartListPage()

Administration

Page

Description

Process Start Signature

End

Is displayed whenever a Task or Process ends

DefaultEndPage(Number
endedTaskId)

Login

Is displayed whenever an authenticated user is required and none is DefaultLoginPage(String
available
originalUrl)

Table 6.4. Default Pages
How to override the default pages:
1.

To override the pages create one project containing all processes with the overriding signatures.

2.

Deploy this project to the application for which you want to override the behaviour.

3.

Configure the application to use the deployed project to override the default pages. For more details see Application
Default Settings.

Application Home Page replacement
By default Axon.ivy shows a page which simply says hello to the user.
Use a Request Start with the signature DefaultApplicationHomePage() to overwrite this behaviour.

This Request Start must either lead to an Web Page Element or an End Page Element.

Task List Page replacement
By default this page displays all tasks the currently logged in user can work on. You can override this page to adopt it to your
look and feel or to display your own list of tasks.
Use a Request Start with the signature DefaultTaskListPage() to overwrite this behaviour.

124

Administration

This Request Start must either lead to an Web Page Element or an End Page Element.

Process Start List Page replacement
By default this page displays all Processes the currently logged in user can work on. You can override this page to adopt it
to your look and feel or to display your own list of process starts.
Use a Request Start with the signature DefaultProcessStartListPage() to overwrite this behaviour.

This Request Start must either lead to an Web Page Element or an End Page Element.

125

Administration

End Page replacement
By default Axon.ivy will show a page which says "You have successfully finished the task", when a task is finished and the
process does not define a specific End Page.
Use a Request Start with the signature DefaultEndPage(Number endedTaskId) to overwrite this behaviour

This Request Start must either lead to an Web Page Element or an End Page Element.

Login Page replacement
By default Axon.ivy will show a simple login page, whenever a login is required. The page allows you to login with username
and password and then redirects you to the original URL requested.
Use a Request Start with the Signature DefaultLoginPage(String originalUrl) to overwrite this behaviour

126

Administration

This Request Start must lead to an activity which does login a user. Normally this is done using a dialog which asks for
username and password. But you are free to do anything to identify the user.
Normally the process should lead to an End Page which redirects to the original requested url. But you are free to do anything
after the user is logged in.

Sample HTML Workflow UI Project
Axon.ivy Engine is delivered with a sample HTML Workflow UI project. You can find it in the installation directory in the
folder projects/HtmlWfUi.

Tip
We suggest to adopt the sample project to your needs and use it as described above instead of creating a new
project from scratch.
If you want to use the sample project as it is, consult the section create a new application.

Email Notification
Overview
Axon.ivy Engine can send out email notifications on user task changes. These emails contain information on tasks that are
available for users to work on. Notification subscriptions are configurable and the email content can be highly customized. In
order to understand how it generally works it is recommended to read this section. This feature works only on engine versions,
not in the Axon.ivy Designer. There are two types of notification emails:
New Task

One email is sent when a new task is available (created, inherited, assigned) for a given user

Daily Summary

One email is sent daily with a summary of all open tasks are available (created, inherited, assigned)
for given user

Whether a user receives email notifications or not depends on application and user configurations. Engine administrators can
set up initial settings for both notification types at user creation (see Application Default Settings). Later, users can specify
their own notification settings using WorkflowUI (see WorkflowUI documentation). Email notification messages are created
by the system and sent as email messages. Therefore make sure, that SMTP settings are set up correctly, check it in the System
properties of your application.
Axon.ivy supports own email notification processes to influence the content of the emails. In case you set up such a notification
process, then this process will be executed before the notification email is sent. There are two types of email notification
processes:
New Task Mail Notification
Process

This process provides the email content for new task notification emails.

Daily Summary Mail Notification
Process

This process provides the email content for daily summary notification emails.

127

Administration

Mentioned notification processes will be executed, and their HTML result will be used as email content.

Process Design
Email Notification Process are used to customize the design and contnet of the mails sent if the standard mail notification
is not proper for your company. It is advised to prepare the important details you want to display in the notification mails
and prepare some screen designs as well.
Quick overview how to create notification processes:
Open designer

Start Axon.ivy designer

Create mail notification process

Create new process(-es) which provide email content for your notification mail.

Deploy

Deploy project library as process model and PMV on your Axon.ivy Engine

Configure notification

Configure Axon.ivy Engine to use notification process(-es) for mail notification. For
more details see Application Default Settings.

Backup

Make sure that your process models and PMV-s are backuped, just like your System
DB, so that in case of some hardware failure your Axon.ivy Engine can be restored
easily.

More detailed description of non trivial steps are documented in the following section.
Create mail notification process
Create a normal process within your fresh Axon.ivy project. Place some process start element(-s), and put a simple process
together. This process should display an HTML page, preferably using an Endpage process element to save engine resources.
The HTML page defines the content of the notification mail while the  tag in the <header> section will be used as
mail subject.

Figure 6.32. Example for both email notification process types
Notification process start elements must follow some naming and parameter conventions in order to be recognised by Axon.ivy
Engine as potential email notification processes. Please create process starts as follows:
New Task Mail Notification
Process Start

This process has to accept the new task you want to notify about and the user to which
the notification will be sent to.
The name of the Process start must be:
• MailNotification_NewTask
128

Administration

Process start parameters:
• notificationUserId : Number (java.lang.Number) - The ID of the recipient that the
new task notification is created for
• notificationTaskId : Number (java.lang.Number) - The ID of the task that is ready
to be processed by the user

Figure 6.33. Correct declaration of process start element for a "New
task" email notification

Tip
You can get a user object (IUser) using a userID calling the method
findUser(int) on ivy.session.getSecurityContext()
(see ISecurityContext interface in the PublicAPI documentation
for more details)

Tip
You can get a task object (ITask) using a taskID using the method
findTask(int) on ivy.wf (see IWorkflowContext interface
in the PublicAPI documentation for more details)
Daily Summary Mail Notification
Process Start

This process has to accept only the user we want to send the daily summary to, therefore
define the process start element as follows:
The name of the Process start must be:
• MailNotification_DailyTaskSummary
Process start parameters:
• notificationUserId : Number (java.lang.Number) - The ID of the recipient that the
new task notification is created for

129

Administration

Figure 6.34. Correct declaration of process start element for a "Daily
summary" email notification
It is not supported to create multiple processes or process starts within the same project (PMV) for the same notification type
(daily/new task). In case you create multiple matching process starts then it cannot be forecasted which process start will be
used within the project (PMV library).
Created notification processes will be executed, and their HTML result - the page they display - will be used as content in
the notification email.
Deploy
Start the Engine Administrator, deploy your project library as a process model and a PMV. It is important to deploy your
notification project within the application you want to use it for.
Configure notification
Having deployed your notification process model in the application where you want to customize the notification make sure
that the PMV is active. Go to the Application Default Settings, refresh GUI if necessary, and select the library ID of the PMV
that implements the notification process you want to use for email notification. In case you implemented the process start
properly, and the project including the notification process is deployed properly, you should see the library ID.

Tip
Should you have difficulties implementing an email notification process, open a WorkflowUI project. It contains
two example email notification processes.

Tip
In a Daily notification mail you might need a task list for a user that she may activate and work on. The method
findWorkTasks(..) on ivy.wf does this job. It uses even substitutions and absences to collect the correct
task list (see IWorkflowContext interface in the PublicAPI documentation for more details)

Email Notification Summary
Having customized your email notification process(-es) users of specific application should receive their email notification
prepared by your notification process.
You might still have some questions left:
How can a process provide email
content?

Defined process should look like a simple process with an HTML dialog end. This
process will be executed and the HTML dialog will be taken as content for notification
email. In case you use normal HTML Page Step process element(s), then the process

130

Administration

will be executed only up to the first HTML Page and this page will be sent as
notification email.
What can be customized exactly?

These processes going to "display" an HTML page. Whatever is included in this HTML
page, will be sent as content of the specific notification email.

How often is this process executed?

Processes for "new task" notification are executed whenever a new task is created (e.g.
with a trigger), an existing task expires and needs to be escalated, or the creator of an
existing task is changed. On mentioned events the process is executed separately for
each user that is responsible for the given task directly, indirectly by his roles or by
substitutions (e.g. if a task is created for the role secretary, then the process is executed
for each user that own the role secretary, or substitutes an absent secretary over her
role).
Processes for "daily summary" notification are executed once a day for each user that
is subscribed for notification on that day.

When is the daily summary process
executed?

You can setup the execution time in the engine's System properties, under the
property:EMail.DailyTaskSummary.TriggerTime

What happens with images of
the HTML page used for email
notification?

In case this page includes some local images (e.g. CMS, ivy file), then they will be
downloaded by Axon.ivy Engine, attached as MIME parts, and re-linked to the email
to look just like the HTML page would look in an Internet browser.
You may also include images from remote hosts. If you do so, then Axon.ivy does
not download and attach these images, but leaves the links as they are. Some Email
clients will block these images (protecting their user from phishing attacks) until the
user explicitly says to download external images.

How notification processes can be
set?

Notification processes can be set for each application independently. First of all you
have to deploy a notification process, then select notification process in the Application
Default Settings dialog.

Can I cancel a notification?

Yes, in case your process terminates normally without displaying any HTML page.

Tip
Use EndPage process element to reduce resource usage of your email notification process(-es).

131

Chapter 7. Monitoring
Logging
Axon.ivy uses a library called Log4j from Apache Foundation to log certain events. The logging configuration file is located
in the {Axon.ivy Install Directory}/configuration directory and is called log4jconfig.xml. By default log events are written to
the console and to log files. The log files are written to the {Axon.ivy Install Directory}/logs directory.
Logging type

Log level

Console log

WARN

File log

INFO

Windows Event Log

FATAL

Table 7.1. Default settings for logging
The log levels are used as follows:
FATAL

This level is used to report problems that may cause the engine not to work correctly.

ERROR

This level is used to report problems that something has not worked as expected and may cause that the user gets
an error message on the UI.

WARN

This level is used to report problems that have to be solved because it can lead to errors later.

INFO

This level is used to report that something was done. (E.g. for example a database call)

DEBUG

This level is used to report internal events. Most of these events are only interessting for developers. However, some
of them may also be interessting for troubleshooting.

Feel free to change the logging configuration to your needs.

Log Message Format
A log message looks like the following:
10:19:14.173 INFO [ch.ivyteam.ivy.richdialog.exec.internal.panel.RichDialogPanelImpl] [http-8082-4]
[application=0, client=127.0.0.1, task=4, pmv=System$Administration$1, session=4, request=Ulc over HTTP POST
115D746C75FAF428/start1.ivp, executionContext=SYSTEM]
Can not restore UI state. No user is logged in.

The first entry of a log message is the exact time it was written (10:19:14.173).
Followed
by
the
log
level
of
the
message
(INFO).
Next
is
the
log
category
([ch.ivyteam.ivy.richdialog.exec.internal.panel.RichDialogPanelImpl]). Then the name of the
thread in whichs context the log message was written follows ([http-8082-4]). The next section conains a lot of Axon.ivy
context information. For example the user session or the process model version that were active when the log message was
written. The content of the context information can change depending on the context the log message was written. The
following context information exists:
application

The identifier of the current application.

client

The IP address and maybe the host name of the current web client.

executionContext

The security execution context that is used to check permissions. This can be the current session
or SYSTEM if security is disabled.

request

Information about the current request is written to the log.

requestId

The identifier of the current request. Can be used to filter all messages that are written in the context
of the same request.

pmv

The identification string of the current process model version.

132

Monitoring

processElement

The process element that is currently executed.

rd

The fully qualified name of the current Rich Dialog.

session

The current Axon.ivy session. The identifier of the session and the user name (if a user is logged in).

task

The identifier of the current task.

On the next line the message that was logged follows. In case of errors a java exception stack trace may follow on the next lines.

Runtime Log
On the Axon.ivy Designer certain events of processes are logged to the runtime log view. The process designer itself can write
to the runtime log using the ivy.log object. On the Axon.ivy Engine all information written to the runtime log is handled by
Log4j. It is written to the console, to log files and to the Windows Event Log.
The runtime log entries are written to special log categories which names start with runtimelog followed by
the application name, the process model name, and the runtime log category. For example: the category name
runtimelog.app.hrm.user_code represents the runtime log of the application called app, with the process model called hrm
and the runtime log category user_code.

Example
The following xml snip can be added to the Log4j configuration file so that the runtime log of the process model hrm of the
application app is written to its own log file called runtimelog.app.hrm.log:
<!-- Defines a log file called runtimelog.app.hrm.log -->
<appender name="RuntimeLog" class="org.apache.log4j.DailyRollingFileAppender">
<param name="File" value="${user.dir}/logs/runtimelog.app.hrm.log"/>
<param name="DatePattern" value="'.'yyyy-MM-dd"/>
<layout class="org.apache.log4j.IvyLog4jLayout">
<param name="DateFormat" value="HH:mm:ss"/>
</layout>
</appender>
<!-- Configures that the log category runtimelog.app.hrm has priority DEBUG and is
written to the RuntimeLog file -->
<category name="runtimelog.app.hrm" class="ch.ivyteam.log.Logger">
<appender-ref ref="RuntimeLog"/>
<priority value="DEBUG"/>
</category>

Request/Performance Logging
If you want to know the time when a request was received from the Axon.ivy Engine and at what time the request processing
of the engine was done, then you use the following log category:
ch.ivyteam.ivy.webserver.internal.PerformanceLogValve
Configuration Example (configuration/log4jconfig.xml):
<!-- Configures that the log category
ch.ivyteam.ivy.webserver.internal.PerformanceLogValve has priority DEBUG
<category name="ch.ivyteam.ivy.webserver.internal.PerformanceLogValve"
class="ch.ivyteam.log.Logger">
<priority value="DEBUG"/>
</category>

-->

The log category logs the entry of a request right after the internal web server has received it. The exit is logged after the
request was processed by the web server. In the exit log message you find the duration of the request in microseconds.

133

Monitoring

The log level of the these messages is DEBUG. Change the threshold of the appenders to DEBUG so that log messages with
this priority are written to the appender's destination.
Configuration Example (configuration/log4jconfig.xml):
<appender name="FileLog" class="org.apache.log4j.DailyRollingFileAppender">
<param name="Threshold" value="DEBUG"/>
<param name="File" value="${user.dir}/logs/ch.ivyteam.ivy.log"/>
<param name="DatePattern" value="'.'yyyy-MM-dd"/>
<layout class="org.apache.log4j.IvyLog4jLayout">
<param name="DateFormat" value="HH:mm:ss.SSS"/>
</layout>
</appender>
If you want to know what the Axon.ivy Engine has done between the entry and exit of the request you can use the context
information requestId which you can find on every log message. A unique request identifier is assigned to every request.
By filtering the log for messages with the same requestId you find out what kind of operations Axon.ivy Engine has done
during the request.
Example:
10:49:40.904 DEBUG [...rformanceLogValve] [http-8081-1] [requestId=43]
Entry url=http://localhost:8081/ivy/pro/designer/OpenEditor/13224891E742EE17/start4.ivp
client=0:0:0:0:0:0:0:1 session=null httpsession=C900A5BC35251533DEB5B36E4316EE98
10:49:41.020 INFO [...nEditor.user_code] [http-8081-1] [application=2147483647,
client=0:0:0:0:0:0:0:1, requestId=43, task=1, pmv=designer$OpenEditor$1, processElement=13224891E742EE17-f26t, session=1, request=HTTP GET test.mod/start4.ivp(1.1.0.0), executionContext=1]
This is my log message
10:49:41.050 INFO [...ner.OpenEditor.db] [Process Extension Thread 1] [application=2147483647,
client=0:0:0:0:0:0:0:1, requestId=43, task=1, pmv=designer$OpenEditor$1, processElement=13224891E742EE17-f29bean, session=1, request=HTTP GET test.mod/start4.ivp(1.1.0.0), executionContext=SYSTEM]
Execute database statement SELECT * FROM IWA_ACCESSCONTROL
10:49:41.050 INFO [...ner.OpenEditor.db] [Process Extension Thread 1] [application=2147483647,
client=0:0:0:0:0:0:0:1, requestId=43, task=1, pmv=designer$OpenEditor$1, processElement=13224891E742EE17-f29bean, session=1, request=HTTP GET test.mod/start4.ivp(1.1.0.0), executionContext=SYSTEM]
Executed database statement successfully in 0 milli seconds
10:49:41.100 DEBUG [...rformanceLogValve] [http-8081-1] [requestId=43]
Exit url=http://localhost:8081/ivy/pro/designer/OpenEditor/13224891E742EE17/start4.ivp
client=0:0:0:0:0:0:0:1 session=1 httpsession=C900A5BC35251533DEB5B36E4316EE98 duration=194181 us

In the example above you see the log messages when the request with the id 43 has entered and exited the web server. There
was also one user runtime log message written in the same request and one database call that has lasted 0 milliseconds. The
whole request needed 19.418 ms to be processed.

Configure ULC logging on server and client
It is possible to log ULC communication and status messages both on client and server side. Both a default log level and
a log level per known Ivy user can be configured, as well as a log file path/name where the log of an ULC session should
be stored permanently.
To configure ULC logging, the files configuration/jnlpconfig.any and configuration/ulclogconfig.any within the Axon.ivy
Engine installation folder must be edited. The former one controls the client-side logging, the latter one the server-side logging.
The log configurations are similar in both cases and edited with Anything notation.
To modify the client logging properties locate the following section in jnlpconfig.any:
...
/log-level {
/user-specific {
/johndoe FINER
}
/default WARNING
/log-to-file
"C:/temp/xpertivy_ulc_client.log"
}

134

Monitoring

...
To modify the server logging properties locate the following section in ulclogconfig.any:
{
/user-specific {
/johndoe FINER
}
/default WARNING
/log-to-file "xpertivy_ulc_server.log"
}
To enable user-specific logging on server side and/or client side, enter the known name of the Ivy user (or AD user) to log
for in the /user-specific section, followed by a valid log level (one of SEVERE, WARNING, INFO, FINE, FINER,
FINEST) just as specified in the example configurations with the user johndoe. Use double quotes around the Ivy user name
if it contains special (i.e. non-ASCII) characters or white space.
To set the default log level (which will be used for all sessions) set the log level for the key /default.
Finally, to enable logging to a file, enter a filename in double quotes for the key /log-to-file as shown above. If the /
log-to-file slot is omitted altogether or if it's value is a *, then no logfile will be created.

Note
Changes in log configurations take place immediately for all new sessions or client application starts; a restart
of the engine is not necessary. However, you have to restart any running client applications for the new log
settings to take effect.
The created log files will automatically include the user name (if user-specific logging is enabled), the HTTP
session ID and an ID for the application. The two ID's mentioned are part of the client and the engine log file,
so it is easy to find the two logs related to a client-server communication.

Tip
For reasonable results a default level of WARNING or INFO is recommended. For error analysis, FINER on the
client and FINER on the server is recommended, on a per-user basis.
If you enable ULC logging, it is recommended to specify the /log-to-file parameter. This way the log
output is redirected to a file, otherwise the logs are written to the console.

Warning
Please bear in mind that the logfile path that you specify may not be in correct format for every client platform
(Linux/Windows). If this should be the case then the logfiles will be created in the client system's default
temporary directory.
Be aware that log files can become very large (up to several hundred MB per day and user if FINE /FINER/
FINEST is used as log level).

Process Element Performance Statistic and
Analysis
Configure Process Element Performance Statistic on
Axon.ivy Engine
On an Axon.ivy Engine it is possible to dump out performance statistic informations, periodically into a CSV formatted file.
This allows to analyse the performance of the engine and to detect long running and performance intensive process elements
and processes. The file contains detailed informations of each executed process element since the last dump.

135

Monitoring

After activation the informations are collected and written to the log-directory of the Axon.ivy
Engine installation. The file contains the following name: performance_statistic_jjjj-mm-tt_hh-mm-tt.csv (e.g.
performance_statistic_2011-03-15_09-21-05.csv)
All configurations are administered by the following System Properties:
Property

Description

ProcessEngine.FiringStatistic.Active

True for activation, otherwise false. An activation may slow down the
engine performance!
A restart is not required after de-/activation. The setting take effect,
maximum after the duration of the defined interval (System Property:
ProcessEngine.FiringStatistic.Interval).

ProcessEngine.FiringStatistic.Interval

Interval in seconds the statistic is written to the log directory. Default value
is 300 seconds (5 minute). After each interval the statistic informations are
cleaned after the dump out.
A restart is required after a value change.

Table 7.2. System properties to configure the firing statistic

Analyse the Performance Statistic
All time values are in milliseconds. The execution of some process elements are separated in two categories internal and
external.
Internal Category

The internal category is used for the execution time in the process engine itself without the external
exection.

External Category

The external category is used for execution time in external systems. In the table below the process
elements are listed which use the external category.
Process Element

Internal Category

Database Step

Parameter-mapping, caching, The execution of the SQL
output-mapping and ivyScript statement on the database
execution.
server.

Web Service Call Step

Parameter-mapping, caching, The execution of the Web
output-mapping and ivyScript Service on the web server.
execution.

E-Mail Step

Parameter-mapping

Program Interface

External Category

The interaction with the MailServer.
The execution of the defined
Java-Class.

Table 7.3. Process elements with usage of external category
For each executed process element one entry in the view is created. See the table below which information is available.
Name

Description

Entry ID

Entry ID, useful to order the entries by its first exection.

Application

Application of the process element.

Process Model

Process Model of the process element.
136

Monitoring

Name

Description

PM Version

Process Model Version of the process element.

Process Path

The path to the process.

Element ID

The identifier of the process element.

Element Name

The first line of the process element name (display name).

Element Type

The type of the process element.

Total Time

Total time [ms] of internal and external execution.

Int. Executions

Total internal executions of the process element.

Total Int. Time

Total internal time [ms] of process engine executions.

Min. Int. Time

Minimum internal process engine execution time [ms].

Avg. Int. Time

Avarage internal process engine execution time [ms].

Max. Int. Time

Maximum internal process engine execution time [ms].

Ext. Executions

Total external execution count.

Total Ext. Time

Total external execution time [ms].

Min. Ext. Time

Minimum external execution time [ms].

Avg. Ext. Time

Average external execution time [ms].

Max. Ext. Time

Maximum external execution time [ms].

Table 7.4. Column Description

Tip
To find a process element by its Element ID, use the search dialog Find process or element in the Axon.ivy
Designer. Use menu Axon.ivy > Debug > Find process or element.

Java Management Extensions (JMX)
Java Management Extensions (JMX) is a technology to read and write runtime information from a java processes. This allows
monitoring tools to monitor the state the Axon.ivy Engine, e.g. with VisualVM, Java Mission Control or Nagios. A monitoring
tool that runs on the same machine and with the same user as the Axon.ivy Engine can connect to Axon.ivy Engine without
any additional configuration.

Activate Remote Access
If the Axon.ivy Engine is running under another user or on a remote host than the monitoring tool, then JMX remote access
has to be activated. Remote access is protected by a user name and password of an Axon.ivy Engine Administrator, so all
Axon.ivy Engine Administrator have access.
On Windows uncommenting the following line in an ivy launch control file *.ilc (See chapter Windows Program Launcher
Configuration) to activate remote access:
ivy.management.port=9003
On other operating systems the below options must be added to the launch configuration script of the engine
(AxonIvyEngine.conf):
-Dcom.sun.management.jmxremote.port=9003
-Dcom.sun.management.jmxremote.login.config=jmx
-Djava.security.auth.login.config=configuration/jaas.config
-Dcom.sun.management.jmxremote.ssl=false
-Djava.rmi.server.hostname=<IP of the machine>

137

Monitoring

Auto Discovery (JDP)
Some monitoring tools can auto discover running JMX servers in the network. If so the user does not have to know the server
host and JMX IP port. Instead he can simple click on the auto discovered server.
Axon.ivy Engine supports auto discovery by default if JMX is activated on Windows. However, you can disable this feature
by uncommenting the following line in the *.ilc file::
ivy.management.autodiscovery=false
On other operating systems the following option must be set to the launch configuration script of the engine
(AxonIvyEngine.conf) to activate it:
-Dcom.sun.management.jmxremote.autodiscovery=true

Provided MBeans
The Axon.ivy Engine provides performance and management information by a set of MBeans. These allow to monitor the
Axon.ivy Engine. Most monitoring tools provide a user interface to browse the available MBeans. MBeans are mostly shown
in a tree which is built with the information provided in the names of MBeans.

Figure 7.1. MBeans Tree of Axon.ivy shown in MBeans Plugin of VisualVM
The names of MBeans provided by Axon.ivy are structured so that the name contains the Application, Process Model, Process
Model Version or Environment where this is reasonable.

Note
Examples of typical Axon.ivy MBean names:

138

Monitoring

• Axon.ivy Engine:type=External Web Service,application=MyApplication,environment=Default,name=Echo
(43838347ABCD)
• Axon.ivy Engine:type=Job Manager
• Axon.ivy
Engine:type=Process
Start
Event
Bean,application=MyApplication,pm=MyProcessModel,pmv=1,name="MyStartEventBean (3485471349/
start.ivp)"
The name and description of a MBean can be found in its meta information (see the Metadata tab in the MBeans tab of
VisualVM). MBeans provide information through attributes and operations. The description of the attributes and operations
can also be found in its meta information (see too the tool tips in the Attributes and Operations tab of the MBeans tab of
VisualVM).

Warning
Manipulating attribute values or calling operations on MBeans will immediately change the configuration of
your system and can therefore harm your running applications.
If not mentioned otherwise, a manipulation only affects the currently running engine. The manipulation will not
survive a engine restart.
Manipulations that survive a engine restart contain the following text in the description of the attribute or
operation: (Persistent).
In addition to the MBeans provided by Axon.ivy some third party libraries included in Axon.ivy provide their own MBeans.
One of them is Apache Tomcat that is used as internal web server. Its MBeans provide information about the handling of
HTTP requests like request count, errors, execution time, sessions, etc. Moreover, the Java virtual machine also provides some
MBeans that provide information about the used memory (Java heap), CPU usage, uptime, etc.
Below a not complete list of provided information:
• External Database (connections, transactions, errors, execution time, etc.)
ivy Engine:type=External Database,application=*,environment=*,name=*
• Web Service (calls, errors, execution time, etc.)
ivy Engine:type=External Web Service,application=*,environment=*,name=*
• REST Web Service (calls, errors, execution time, slow calls, etc.)
ivy Engine:type=External REST Web Service,application=*,environment=*,name=*
• System Database (connections, transactions, errors, execution time, etc.)
ivy Engine:type=Database Persistency Service
• HTTP Requests (count, errors, execution time, etc.)
*:type=GlobalRequestProcessor,name=*
• Number of Sessions (HTTP sessions, Axon.ivy sessions, licence relevant sessions, Rich Dialog client sessions, etc.)
ivy Engine:type=Security Manager
ivy Engine:type=Rich Dialog Execution Manager
*:type=Manager,context=*,host=*
• Background jobs (name, next execution time, etc.)

139

Monitoring

ivy Engine:type=Job Manager
ivy Engine:type=Daily Job,name=*
ivy Engine:type=Periodical Job,name=*
• Process Start Event Beans (polls, executions, errors, execution time, etc.)
ivy Engine:type=Process Start Event Bean,,application=*,pm=*,pmv=*,name=*
• Process Intermediate Event Beans (polls, firings, errors, execution time, etc.)
ivy Engine:type=Process Intermediate Event Bean,application=*,pm=*,pmv=*,name=*
• Application, Process Model and Process Model Version, Library information (activity state, release state, name, description,
etc.)
ivy Engine:type=Application,name=*
ivy Engine:type=Process Model,application=*,name=*
ivy Engine:type=Process Model Version,application=*,pm=*,name=*
• Cluster, Cluster Nodes and Cluster Communication information (received and sent message, errors, execution time, etc.)
ivy Engine:type=Cluster Manager
ivy Engine:type=Cluster Channel
• Thread Pool information (core, maximum and current pool size, active threads, queue size)
ivy Engine:type=Thread Pool, name=Background Operation Executor
ivy Engine:type=Thread Pool, name=Immediate Job Executor
ivy Engine:type=Thread Pool, name=Scheduled Job Executor
• System Database and CMS Cache
ivy Engine type=CacheClassPersistencyService,name=* [clearCache()]
ivy Engine type=CacheClassPersistencyService,name=*,strategy=CacheAll [maxBytesToCache, maxCharactersToCache]
ivy Engine type=CacheClassPersistencyService,name=*,strategy=CacheAllRemoveUnused
maxCharactersToCache, countLimit, usageLimit]
ivy Engine type=CacheClassPersistencyService,name=*,cache=LongBinaries
cachedLongValues, clearCache()]
ivy Engine type=CacheClassPersistencyService,name=*,cache=LongCharacters
cachedLongValues, clearCache()]

[readHits,

[readHits,

[maxBytesToCache,

readMisses,

writes,

readMisses,

writes,

ivy
Engine
type=CacheClassPersistencyService,name=*,cache=ObjectsAndAssociations
[objectReadHits,
objectReadMisses, objectWrites, cachedObjects, associationReadHits, associationReadMisses, associationWrites,
cachedAssociations, clearCache()]
• Memory (Java Heap, Perm Gen)
java.lang:type=Memory
• CPU Usage, Uptime
140

Monitoring

java.lang:type=Runtime
java.lang.type=OperatingSystem

VisualVM
We recommend to use VisualVM to monitor Axon.ivy Engine processes. VisualVM allows you to monitor the memory and
CPU usage of the Axon.ivy Engine process. It can be used to analyze problems in your Axon.ivy projects like memory leaks
or thread dead locks.

VisualVM can connect to all Java processes running on the same host and with the same user. In addition you can use JMX
(See section Java Management Extension for more information) to connect VisualVM to processes that run with another user
(e.g. as Windows Service) or on remote machines.
VisualVM is available from https://visualvm.github.io/ or as jvisualvm in the bin directory of a JDK (Java Developer Kit).

Axon.ivy Plugin for VisualVM
In the delivery of Axon.ivy we provide a dedicated plugin for VisualVM that allows you to monitor some of the technical
aspects of an Axon.ivy Engine or Designer. For example you can observe the current transactions on the System Database,
whether you violate the licence or how many requests are running at an Axon.ivy Engine at any given time. And in the same
tool you can still observe the heap or CPU usage or create thread dumps.

Note
VisualVM is a tool to observe the current state of the monitored engine. It is not intended for long-time
observation, recording or even alarming. If you want to do that, make use of the JMX extensions of Axon.ivy.
in combination with tools like Nagios or IBM Tivoli.
The plugin itself should be mostly self explanatory. It consists of multiple tabs for the different aspects. Most of the tabs
contain a number of charts that always have a similar structure:

141

Monitoring

Installation
1.

Make sure that you have an installation of VisualVM. If you use a standalone version of VisualVM, please make sure
that you use at least version 1.3.7.

2.

Run VisualVM (in JDK go to the bin folder and start jvisualvm)

3.

Go to the Tools/Plugins menu

4.

Change to Downloaded tab and click on the Add Plugins... button

5.

In the file chooser that appears, navigate to the subfolder misc/visualvm in your engine installation directory and choose
the visualvm-plugin.nbm.

6.

Follow the instructions in the installation wizard.

7.

Choose the option to restart VisualVM at the end of the installation wizard.

Engine Administration
In the Engine Administration application you can use the Runtime Information page to view information about the java heap
memory and all running java threads with their current call stack. Another important page is the About page where you find
information about the Axon.ivy Engine version, Java version and the Java system properties.
For each external database you can find information about the last SQL statements that have been executed on the database
and the open connections to the database.

142

Chapter 8. Miscellaneous
Rich Dialogs
Provide Custom ULC Widgets
The chapter Concepts > Extensions > Rich Dialog Clientside Libraries > Provide custom ULC Widgets in the Axon.ivy
Designer Guide explains how to provide Custom ULC Widgets.

Provide Customer Rich Dialog Client Certificate
If a client starts the first time a Rich Dialog a security information dialog box pops up showing information about the publisher
of Axon.ivy and its certificate. For some clients it may be confusing that a certificate from the provider of Axon.ivy is displayed
instead of the certificate of the web site or the company they working for.
The chapter Extensions > Rich Dialog Clientside Libraries > Provide Customer Certificate in the Axon.ivy Designer Guide
explains how to provide customer Rich Dialog client certificate.

Rich Dialog Session Timeout
The normal session timeout has no effect to Rich Dialogs because they send recurring requests to the server in shorter intervals
than the session timeout. Therefore you can configure a special timeout feature for Rich Dialogs. It detects if an open Rich
Dialog was not touched for the configured time and stops that Rich Dialog application. The user will receive a message so
that he knows why the Rich Dialog has been closed. You can choose whether you want to have a Rich Dialog message box
or if you want to see the message in your browser. With the former, the Rich Dialog and the session is closed only after the
user confirmed the message. With the latter, the Rich Dialog and the session is closed immediately when the timeout happens
thus freeing the server side memory. In this case you can even adapt the HTML file that is used. It is the file webapps/ivy/
info/time_out.jsp.
To configure the Rich Dialog session timeout just go to the file configuration/jnlpconfig.any and adapt the settings for it.

Rich Dialog Look and Feel
The look and feel that is used for Rich Dialogs can be configured per applications. To change it open in the AdminUI the
application and change the configuration property ria.lookandfeel.

Compressed client libraries
Rich Dialog clients download many jars during the first startup. If the network connection of the client is poor, it is possible
to speed-up the download by sending compressed pack200 jars. It will speed-up the download time, but the client will require
more resources to unpack the downloaded jars.
In order to send compressed jars they must be provided within the /clientlib directory of the engine. The following
sample script will create these pack.gz files. The script must be run within the engines clientlib directory. Note that the pack200
binary comes from a JRE or JDK.
On Windows:
for /R %f in (.\*.jar) do pack200 "%f.pack.gz" "%f"
On Linux:
for f in `find signed -name '*.jar'`; do
echo "packing $f"
pack200 $f.pack.gz $f

143

Miscellaneous

done
If the script runs successfully the clientlib directory contains files ending with pack.gz next to the normal jars.

ULC Load Tests
ULC Load is a product from Canoo Engineering AG to make load tests on ULC Applications (such as Rich Dialogs are). This
chapter describes how to use ULC Load together with an Axon.ivy Engine.

Requirements
• Axon.ivy Designer installation
• Axon.ivy Engine installation
• ULC Load 3.0.4
• Java Runtime Environment (JRE) 1.6

Note
ULC Load is not shipped with Axon.ivy and needs a separate licence. It can be obtained from Canoo Engineering
AG (http://www.canooo.com).
IvyTeam AG does not provide any support for ULC Load. Please contact Canoo Engineering AG to get support
for ULC Load.

Note
If you run ULC Load with JRE 1.7 you cannot save your test plan. Ensure you have installed a JRE
1.6. If it is not possible to uninstall JRE 1.7 reconfigured the property lax.nl.valid.vm.list=1.5+
to lax.nl.valid.vm.list=1.6 in the property file bin/ULC Load 3.0.4 UI.lax of your ULC Load
installation directory.

Install ULC Load
• Start the installation of ULC Load.
• At the Step Named Choose Canoo RIA Suite select the ulc directory of your Axon.ivy Designer Installation.

144

Miscellaneous

Note
The Axon.ivy Designer must have been started at least one time. Otherwise the ulc directory needed for the
ULC Load installation is not available.
• Finish the installation of ULC Load
• Edit the File ULC Load 3.0.4 UI.lax in the bin directory of your UlcLoad installation.
Look for the line which starts with lax.class.path=.
Add an entry to the end of this line which points to the ivyUlcExtension-*.jar file in the clientlib/signed folder of your
engine installation.
Add an entry to the end of this line for each library in the clientlib/signed/windows_64_native folder of your engine
installation. If you are using an other operating system than Windows 64 bit, use the libraries of the operating system you
are running ULC Load with.

Prepare Engine
ULC Load will only work correctly with Axon.ivy Engine (Designer) if you change the following line in the context.xml file
in the directory webapps/ivy/META-INF/ of the engine/designer installation directory:
<Context antiResourceLocking="false" privileged="true">
change to:
<Context antiResourceLocking="false" privileged="true" useHttpOnly="false">

Record a Test Scenario
• Start ULC Load
• Create a Recorder

• Configure the Recorder
• Add all jars in the clientlib/signed folder of your Axon.ivy Engine installation to the classpath.
• Choose the IvyClientCoderRegistryProvider as Client Coder Registry Provider

145

Miscellaneous

• Copy the URL of the process you want to start to the Application URL Field and replace the prefix /ivy/pro with /ivy/
ulcload.
Example: If you want to test the process with the URL http://localhost:8080/ivy/pro/abc/
IvyDemos/1215975017F13818/demoRunner.ivp you have to use the Application URL http://localhost:8080/ivy/ulcload/
abc/IvyDemos/1215975017F13818/demoRunner.ivp

• Click the Record button. This starts the application and records every action you do. The recording automatically stops
when the application is closed.

Note
It's not possible to change the look and feel for recording tests. The application will always start with the default
swing look and feel. As ULC Load does not run any client side code when executing the tests, the look and feel
wouldn't have any effect on the testruns anyway.

Warning
It's not possible to test processes which use Html Pages. When the process comes to an Html Page step ULC
Load will display an error.

146

Miscellaneous

Run Load Test
• There are no special configuration necessary to run a Load Test.
• When recording a test, ULC Load creates a Thread Group which contains all recorded actions. With the menu Run -> Start
these actions can be replayed.
• On the Thread Group itself its possible to configure how often the actions are replayed and with how many concurrent users.

HTML Dialogs
Primefaces Theme
The default Primefaces theme that is used in Html Dialogs can be configured in the web.xml. It can also
be configure per application. To change it open in the AdminUI the application and change the configuration
property jsf.primesface.theme. Moreover, the theme can also be set per session. See Java class
ch.ivyteam.ivy.jsf.primefaces.theme.IvyPrimefacesThemeResolver in Public API for details.

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.

Update Notification
When newer Axon.ivy versions are available a message will be displayed on the Axon.ivy Engine main web page. The message
contains information about the new versions and where those can be downloaded.

Note
While checking for new versions the following statistic information are sent to the update server. These
information are only used to improve the product.
• Engine (version, up time)
• Configuration (number of: cluster nodes, users, licenced users, applications, process model, process model
version, deleted process model version, running cases, running tasks)
• Licence information (number, organisation, individual)

147

Miscellaneous

• Operating system information (name, version, architecture, number of processors)
• System database (product name and version, driver, identification number)
• Java memory information (maximum heap memory, maximum non heap memory)
• JVM (Java virtual machine) information (version, vendor, name)
• Host information (host name, SHA-256 hashes of IP address and MAC address to identify the host without
being able to read the original IP address and MAC address itself)

Note
If you do not want that update notification messages are shown or that statistic information are sent to the update
server then you can set the system property UpdateChecker.Enabled in the Admin UI to false. This will
turn of the whole update checker service.

Tool Reference
AxonIvyEngine
Axon.ivy Engine program. This program starts an instance of the Axon.ivy Engine.

Tip
On Windows Axon.ivy Engine can also be started as a Windows Service. More information about Axon.ivy
Engine Windows Service can be found in the section AxonIvyEngineService tool reference chapter.

Tip
On Linux an instance of Axon.ivy Engine can also be started as a systemd service. More information how to
install Axon.ivy Engine as a systemd service can be found in the section InstallService of the tool reference
chapter.

Options
The following options are available for the Axon.ivy Engine program:
Option

Description

Mandatory

-start

Starts the engine. Same behaviour as if no
no options are given. Allows to stop the
engine by pressing a key in the console
if a console is available.

-startdaemon

Starts the engine. Does not allow to no
stop the engine by pressing a key in the
console.

-stop

Stops the engine. Only initiate the stop no
but will not wait until the engine has
really stopped.

-stopdaemon

Stops the engine. Will wait until the no
engine has really stopped.

-status

Prints the current status of the engine.

Table 8.1. AxonIvyEngineConfig Options

148

no

Miscellaneous

Launchers
The following program launchers are available for the Axon.ivy Engine program:
Platform

Console support

Launcher

Windows

no

bin/AxonIvyEngine.exe

Windows

yes

bin/AxonIvyEngineC.exe

Linux

yes

bin/AxonIvyEngine

Table 8.2. AxonIvyEngine Launchers

AxonIvyEngineConfig
Axon.ivy Engine Configuration program. The program is used to configure the Axon.ivy Engine. The program supports two
modes:
• graphical user interface mode and
• headless mode which needs no graphical user interface on the server machine.

Note
More information can be found in the chapter Configuration

Options
The following options are available for the Axon.ivy Engine Configuration program:
Option

Description

Mandatory

-headless

Activates the headless mode. Useful if no graphical user interface is installed on the server no
machine.

Table 8.3. AxonIvyEngineConfig Options

Launchers
The following program launchers are available for the Axon.ivy Engine Configuration program:
Platform Console support

Launcher

Windows no

bin/AxonIvyEngineConfig.exe

Windows yes

bin/AxonIvyEngineConfigC.exe

Linux

bin/AxonIvyEngineConfig

yes

Table 8.4. AxonIvyEngineConfig Launchers

AxonIvyEngineService
Axon.ivy Engine Windows Service. This program is the implementation of the Axon.ivy Engine Windows Service. But it can
also be used to register, unregister, start and stop Axon.ivy Engine as Windows Service.

Note
You can also register, unregister, start and stop the Axon.ivy Engine Windows Service with the Control Center.

149

Miscellaneous

Options
The following options are available for Axon.ivy Engine Service program:
AxonIvyEngineService [-start|-stop|-register [username password]|-unregister]
Options

Parameters Description

Mandatory

-start

Starts the Axon.ivy Engine Windows Service

no

-stop

Stops the Axon.ivy Engine Windows Service

no

-register

Registers the Axon.ivy Engine Windows Service within Windows

no

username

The user name of the user in which context the windows service should run

no

password

The password of the user in which context the windows service should run

yes, if username is
specified

Unregisters the Axon.ivy Engine Windows Service from Windows

no

-unregister

Table 8.5. AxonIvyEngineService Options

Launchers
The following program launcher is available for the Axon.ivy Engine Service program:
Platform

Launcher

Windows

bin/AxonIvyEngineService.exe

Table 8.6. AxonIvyEngineService Launchers

EngineConfigCli
The console program is used to configure the Axon.ivy Engine. E.g. configure, create or convert the database.

Options
Option

Description

help

Shows which commands and options are possible.

<command> help

Get help to a specific command e.g. EngineConfigCli config-db help

Table 8.7. EngineConfigCli Options

ControlCenter
The Control Center program. With Control Center program you can start and stop the different Axon.ivy Engine types. The
Control Center allows you to change the configuration of the Axon.ivy Engine and on Windows even the configuration of
Axon.ivy Engine Windows Service.

Note
More information can be found in the section Control Center of chapter Configuration

Launchers
The following program launchers are available for the Control Center program:

150

Miscellaneous

Platform Console support

Launcher

Windows no

bin/ControlCenter.exe

Windows yes

bin/ControlCenterC.exe

Linux

bin/ControlCenter

yes

Table 8.8. ControlCenter Launchers

InstallService
The install service program helps to install the Axon.ivy Engine as a systemd Linux daemon. To install the service:
1.

cd to the bin/ directory of your Engine

2.

Run following command as root: ./InstallService.sh

3.

Accept the directory of your engine installation.

4.

Set the user and group under which the Engine service should run. Must not be root. Typically, a special user with
limited access right should be used.

5.

Start the Engine service with systemctl start AxonIvyEngine.service to check if it works.

6.

Check the current status of the service with systemctl status AxonIvyEngine.service

7.

If you want to start the Engine service on the system start, execute following command: systemctl enable
AxonIvyEngine.service

Tip
For more information about systemd services consult man systemd and man systemctl.

Launchers
Platform

Console support

Launcher

Linux

yes

bin/InstallService.sh

Table 8.9. InstallService Launchers

Windows Program Launcher Configuration
All windows program launchers can be reconfigured with an additional ivy launch control file (*.ilc). The ivy launch control
file must have the same name like the launcher itself but instead of the extension *.exe it must use an extension *.ilc.

Tip
If you want to reconfigure the AxonIvyEngine.exe launcher, then copy the Example.ilc file and rename it to
AxonIvyEngine.ilc.
The ivy launch control file is a text-based property file. The file has the following format:
# comment line
property=value
property=value
Open the file with a text editor to reconfigure it. Most properties found in the ivy launch control file are used to modify java
virtual machine options. The following list shows all available options and explains them:

151

Miscellaneous

Property

JVM Description
Option

ivy.heap.max.ratio

yes

The maximum heap size (-Xmx) in percentage of the physical memory of the
machine.

ivy.heap.max.size

yes

The maximum heap size (-Xmx) in megabytes.

ivy.heap.start.size

yes

Start heap size (-Xms) in mega bytes.

ivy.heap.free.max.ratio

yes

The maximum free heap memory (-XX:MaxHeapFreeRatio) in percentage of the
current heap size.

ivy.heap.free.min.ratio

yes

The minimum free heap memory (-XX:MinHeapFreeRatio) in percentage of the
current heap size.

ivy.heap.young.max.size

yes

The maximum young heap size (-XX:MaxNewSize) in megabytes.

ivy.heap.young.min.size

yes

The minimum young heap size (-XX:NewSize) in megabytes.

ivy.heap.eden.survivor.ratio

yes

The survivor heap size as ratio between the eden and the survivor heap size (XX:SurvivorRatio)

ivy.heap.tenured.young.ratio yes

The young heap size as ratio between the tenured and the young heap size (XX:NewRatio).

ivy.jvm.type

yes

The Java virtual machine type to use (ClientHotspotJVM, ServerHotspotJVM).

ivy.dir.aux

no

The directory where the ivyTeam jars are located.

ivy.dir.jre

no

The directory where the java runtime environment is located.

ivy.java.main.class

no

An own Java class to launch instead of ivy engine's main starter class.

ivy.java.main.method

no

Another Java static method to launch on the ivy.java.main.class instead of the default
main method. The called method should take the same arguments as a Java main
method.

ivy.vm.additional.options

yes

Additional Java virtual machine arguments

ivy.garbage.collector.options yes

Additional garbage collector arguments. See too GC Optimization.

ivy.windows.service.name

no

The name of the Windows service (only for Windows service launcher).

ivy.application.name

no

The name of the application (only for application launcher).

ivy.application.singleton

no

Is the application a singleton (true, false; only for application launcher).

Table 8.10. Ivy Launch Control Properties
The properties that are bold are the most used properties.

Linux Launcher Configuration
The Java virtual machine (JVM) options for the Engine are configured in the AxonIvyEngine.conf file. For all other helper
programs the JVM options are configured in the control.conf file.

Tip
If you want to configure the memory (-Xmx, -Xms, etc.) or optimize any other JVM options of the Engine then
edit the AxonIvyEngine.conf file.

152

Chapter 9. Troubleshooting
Introduction
Here you will find solutions to some of the most common problems related to Axon.ivy Engine. If you can't find your solution
here there are some other sources which could help:
Axon.ivy Q&A

The Axon.ivy Q&A contains a considerable amount of questions and answers related to Axon.ivy
Designer and Engine.

Stack Overflow

Problems related to common technologies like Java, JSF, Primefaces are answered on the web, e.g.
on Stack Overflow.

Support

You can get support via ivy@axonivy.com (support may be subject to charging, depending on your
licence agreement).

Program / Engine start problems
If a program or engine does not start, execute it in a console and look at the console output. In most cases error messages are
written to the console output giving you an idea about the problem.

JVM cannot allocate enough Memory
Effect
If the program or engine cannot be started and in the console the following error message is written:
>Error occurred during initialization of VM
Could not reserve enough space for object heap
Create registry entry 'SYSTEM\CurrentControlSet\Services\EventLog\Application\AxonIvyEngineConfig
Launchers' for event log if it does not exists
Error: Could not initialize java virtual machine (-4)

Cause
The JVM tries to allocate memory for the Java heap, but it does not succeed. The amount of memory the JVM tries to allocate
is too large for the operating system. Consequently the JVM cannot be started.

Solution
On Windows use an Ivy launch control file to set the maximum heap size to a lower value (smaller or equal to 1 GByte).
On Linux modify the AxonIvyEngine.conf script to set the maximum heap size to a lower value. The maximum heap size
can be configured with the Java option -Xmx.

Socket name not available on this system
Effect
If the Enterprise Edition engine cannot be started and in the console the following error message is written:
Error while starting Axon.ivy Engine org.jgroups.ChannelException:
failed to start protocol stack
...
Caused by: java.net.SocketException:

153

Troubleshooting

The socket name is not available on this system
...

Cause
This happens if your system supports IPv6 and you try to bind a cluster node to a IPv4 address.

Solution
Set the following java option
-Djava.net.preferIPv4Stack=true
On Windows use an Ivy launch control file. Change the line
#ivy.vm.additional.options=
to
ivy.vm.additional.options=-Djava.net.preferIPv4Stack=true
On Linux modify the serverLauncher.sh script to set java option.

Request Entity Too Large
Effect
If the following error message appears in the browser:

Request Entity Too Large! - The HTTP method does not allow the data transmitted, or the da

Cause
If your Active Directory contains large user groups and dependencies among them then it may occur that single sign on for
some users that are members in a lot of user groups does not work. This is because the packet size of the AJP13 protocol that
is used for the communication between IIS and Axon.ivy Engine is to small to hold all the necessary security information.

Solution
The problem can be solved by increasing the packet size (default value 8192) of the AJP13 protocol. The packet size must
be configured with the same value on the IIS and Axon.ivy Engine side. If one side is not configured to the same size as the
other, then the communication may fail. On the IIS side the packet size can be configured in the workers.properties file by
setting the worker attribute max_packet_size.
Example:
worker.AxonIvyEngine.max_packet_size=16384
On the Axon.ivy Engine side the packet size can be set by changing the value of the system property
WebServer.AJP.PacketSize (See chapter System Properties to learn about how to change a system property).

Install a secure random provider
Effect
In the log the following warning appears:

Failed to generate random number within 10 seconds. This could slow down the JSF runtime d

154

Troubleshooting

Cause
The Engine is running on a highly virtualized cloud host and can not provide enough random data trough hardware interrupts
(e.g. keyboard input or mouse moves).

Solution
Install and run an alternative random provider like 'haveged'. See the installation instructions here https://
www.digitalocean.com/community/tutorials/how-to-setup-additional-entropy-for-cloud-servers-using-haveged

Blocking Application/UI
If an application periodically does not answer for a couple of seconds, then the reason can be a long running full GC. Visit
the chapter GC Optimization for possible solutions.

155

</pre><hr>Source Exif Data: <br /><pre>File Type                       : PDF
File Type Extension             : pdf
MIME Type                       : application/pdf
Linearized                      : No
Page Count                      : 159
Profile CMM Type                : Little CMS
Profile Version                 : 2.1.0
Profile Class                   : Display Device Profile
Color Space Data                : RGB
Profile Connection Space        : XYZ
Profile Date Time               : 1998:02:09 06:49:00
Profile File Signature          : acsp
Primary Platform                : Microsoft Corporation
CMM Flags                       : Not Embedded, Independent
Device Manufacturer             : Hewlett-Packard
Device Model                    : sRGB
Device Attributes               : Reflective, Glossy, Positive, Color
Rendering Intent                : Perceptual
Connection Space Illuminant     : 0.9642 1 0.82491
Profile Creator                 : Little CMS
Profile ID                      : 0
Profile Copyright               : Copyright (c) 1998 Hewlett-Packard Company
Profile Description             : sRGB IEC61966-2.1
Media White Point               : 0.95045 1 1.08905
Media Black Point               : 0 0 0
Red Matrix Column               : 0.43607 0.22249 0.01392
Green Matrix Column             : 0.38515 0.71687 0.09708
Blue Matrix Column              : 0.14307 0.06061 0.7141
Device Mfg Desc                 : IEC http://www.iec.ch
Device Model Desc               : IEC 61966-2.1 Default RGB colour space - sRGB
Viewing Cond Desc               : Reference Viewing Condition in IEC61966-2.1
Viewing Cond Illuminant         : 19.6445 20.3718 16.8089
Viewing Cond Surround           : 3.92889 4.07439 3.36179
Viewing Cond Illuminant Type    : D50
Luminance                       : 76.03647 80 87.12462
Measurement Observer            : CIE 1931
Measurement Backing             : 0 0 0
Measurement Geometry            : Unknown
Measurement Flare               : 0.999%
Measurement Illuminant          : D65
Technology                      : Cathode Ray Tube Display
Red Tone Reproduction Curve     : (Binary data 2060 bytes, use -b option to extract)
Green Tone Reproduction Curve   : (Binary data 2060 bytes, use -b option to extract)
Blue Tone Reproduction Curve    : (Binary data 2060 bytes, use -b option to extract)
Format                          : application/pdf
Title                           : Axon.ivy 7.0 - Engine Guide
Language                        : en
Date                            : 2018:07:16 14:22:23+02:00
Producer                        : Apache FOP Version 1.1
PDF Version                     : 1.4
Creator Tool                    : DocBook XSL Stylesheets with Apache FOP
Metadata Date                   : 2018:07:16 14:22:23+02:00
Create Date                     : 2018:07:16 14:22:23+02:00
Page Mode                       : UseOutlines
Creator                         : DocBook XSL Stylesheets with Apache FOP
</pre>
<small>EXIF Metadata provided by <a href="https://exif.tools/">EXIF.tools</a></small>

<div id="ezoic-pub-ad-placeholder-110">
<script async src="//pagead2.googlesyndication.com/pagead/js/adsbygoogle.js"></script>
<!-- usermanual link ad -->
<ins class="adsbygoogle"
     style="display:block"
     data-ad-client="ca-pub-0545639743190253"
     data-ad-slot="6172135303"
     data-ad-format="link"></ins>
<script>
(adsbygoogle = window.adsbygoogle || []).push({});
</script>
</div>
</div>
				<div id="catlinks" class="catlinks catlinks-allhidden" data-mw="interface"></div>				<div class="visualClear"></div>
							</div>
		</div>
		<div id="mw-navigation">
			<h2>Navigation menu</h2>

			<div id="mw-head">
									<div id="p-personal" role="navigation" class="" aria-labelledby="p-personal-label">
                                                 <!--                              <div id="p-search" role="search">

                                                <form action="https://usermanual.wiki/search.php" id="searchform">
                                                        <div id="simpleSearch">
                                                        <input type="search" name="search" placeholder="Search UserManual.wiki" title="Search UserManual.wiki [ctrl-option-f]" accesskey="f" id="searchInput" tabindex="1" autocomplete="off"><input type="hidden" value="Special:Search" name="title"><input type="submit" name="go" value="Go" title="Find a User Manual" id="searchButton" class="searchButton">                                                 </div>
                                                </form>
                                        </div>-->
                                                <ul>
<li id="pt-mycontris"><a href="https://usermanual.wiki/upload" title="Upload User Manual" accesskey="y">Upload a User Manual</a></li>
</ul>
					</div>
									<div id="left-navigation">
										<div id="p-namespaces" role="navigation" class="vectorTabs" aria-labelledby="p-namespaces-label">
						<h3 id="p-namespaces-label">Versions of this User Manual:</h3>
						<ul>
 <li id="ca-nstab-main"><span><a href="https://usermanual.wiki/Document/EngineGuide.621109724" title="User Manual Wiki" accesskey="c">Wiki Guide</a></span></li> <li id="ca-nstab-main"><span><a href="https://usermanual.wiki/Document/EngineGuide.621109724/html" title="HTML" accesskey="c">HTML</a></span></li> <li id="ca-nstab-main" class="selected" ><span><a href="https://usermanual.wiki/Document/EngineGuide.621109724/help" title="Discussion / FAQ / Help" accesskey="c">Download & Help</a></span></li>
													</ul>
					</div>
									</div>
				<div id="right-navigation">
										<div id="p-views" role="navigation" class="vectorTabs" aria-labelledby="p-views-label">
						<h3 id="p-views-label">Views</h3>
						<ul>
													
		<li id="ca-view"><span><a href="#">User Manual</a></span></li>

                                                                                                                        <li  class="selected"  id="ca-edit"><span><a href="https://usermanual.wiki/Document/EngineGuide.621109724/help" title="Ask a question" accesskey="e">Discussion / Help</a></span></li>

													</ul>
					</div>
									</div>
			</div>
			<div id="mw-panel">
				<div id="p-logo" role="banner"><a class="mw-wiki-logo" href="https://usermanual.wiki/Main_Page" title="Visit the main page"></a></div>
						<div class="portal" role="navigation" id="p-navigation" aria-labelledby="p-navigation-label">
			<h3 id="p-navigation-label">Navigation</h3>

		</div>
			<div class="portal" role="navigation" id="p-tb" aria-labelledby="p-tb-label">


		</div>
				</div>
		</div>
		<div id="footer" role="contentinfo">
							<ul id="footer-info">
											<li id="footer-info-lastmod">© 2021 UserManual.wiki</li>
									</ul>
							<ul id="footer-places">
											<li id="footer-places-privacy"><a href="https://usermanual.wiki/ContactUs" title="UserManual.wiki:Contact Us">Contact Us</a></li>
											<li id="footer-places-about"><a href="https://usermanual.wiki/DMCA" title="UserManual.wiki:DMCA">DMCA</a></li>
									</ul>
										<ul id="footer-icons" class="noprint">
											<li id="footer-poweredbyico">

</li>
									</ul>

		</div>

</div></body></html>