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.

  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.

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.

  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:

CPUArchitectureOperation SystemInstallation ZIP File
Intelx64WindowsAxonIvyEngineX.Y.Z_Windows_x64.zip
Intelx64Linux and Windows*AxonIvyEngineX.Y.Z_All_x64.zip
Intelx64Linux and Windows*AxonIvyEngineX.Y.Z_Slim_All_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.

Installed Files and Directories

After the installation the following files and folders are located in the Axon.ivy Engine installation folder:

Folder or File NameDescription
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.licDemo licence file
 keystore.jksKeystore with the default signature of the Axon.ivy Engine (for https/ssl)
 truststore.jksEmpty truststore can be used to add trusted server certificate for SSL connection clients
 log4jconfig.xmlLogging configuration
 serverconfig.xmlSystem database configuration
 servercontrolcenter.configurationControl Center configuration
doc/ 
 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
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/ 
 apacheFiles to integrate Axon.ivy into an Apache web server
 iisFiles to integrate Axon.ivy into a Microsoft Internet Information Server (IIS)
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
 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.htmlOverview / entry point for list of new and noteworthy features in this release
MigrationNotes.htmlOverview / entry point for migration of last to current release
Readme.htmlImportant information about this engine release
ReleaseNotes.txtRelease 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:

FileDescription
Example.ilcExample of an ivy launch control file. For more information see section Windows Program Launcher Configuration .
JavaWindowsServiceHandler.dllLibrary that contains native methods to register, unregister, configure, start and stop windows services
JVMLauncher.dllLibrary containing code to launch the Java virtual machine.
NTEventLogAppender.dllLibrary that implements native methods to log into the windows event log (32 Bit only).
ControlCenter.exeProgram 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.exeSame as ControlCenter.exe but additionally logs any output to a console window.
AxonIvyEngine.exeStarts the Axon.ivy Engine. For more information see section AxonIvyEngine .
AxonIvyEngineC.exeSame as AxonIvyEngine.exe but additionally logs any output to a console window.
AxonIvyEngineConfig.exeProgram to configure the Axon.ivy Engine. For more information see section AxonIvyEngineConfig .
AxonIvyEngineConfigC.exeSame as AxonIvyEngineConfig.exe but additionally logs any output to a console window.
AxonIvyEngineService.exeExecutable 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:

FileDescription
AxonIvyEngineStarts the Axon.ivy Engine. For more information see section AxonIvyEngine .
AxonIvyEngine.confJava virtual machine configuration (Xms, Xmx, JMX, ...) for the Engine.
AxonIvyEngineConfigProgram to configure the Axon.ivy Engine. For more information see section AxonIvyEngineConfig .
AxonIvyEngine.serviceTemplate systemd script of the Linux service. It will be copied to /etc/systemd/system/ by running InstallService.sh.
AxonIvyEngineService.shHelper scripts for systemd to start and stop the Axon.ivy Engine service.
control.confJava virtual machine configuration (Xms, Xmx, JMX, ...) for the control tools (ControlCenter & AxonIvyEngineConfig)
ControlCenterProgram that allows to configure, start and stop the Axon.ivy Engine. For more information see section ControlCenter .
InstallService.shScript to install the Axon.ivy Engine as a daemon. For more information see section InstallService.
launcher.shHelper 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:

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.

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 NameValue(s)Description
Database MySQL The database system to use.
Driver MySQL The database JDBC driver to use.
Hostlocalhost, testdbserv, ...The name of the host where the database system is running
Port3306, 3307, 3308, ...The IP port where the database system is listening for request
Database NameAxonIvy, AxonIvyEngine, AxonIvySystemDatabase, ...The name of the Axon.ivy Engine system database
User Nameroot, 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 NameValue(s)Description
Database NameAxonIvy, AxonIvyEngine, AxonIvySystemDatabase, ...The name of the database to create
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 Namecom.mysql.jdbc.Driver
JDBC Connection URL Formatjdbc:mysql://<host>[:<port>]/<database name>

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 MODIFY name VARCHAR(200) CHARACTER SET utf8 COLLATE utf8_general_ci;

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.

ParameterValue
Charsetutf8
Collationutf8_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 NameValue(s)Description
Database Oracle The database system to use.
DriverOracle Thin, Oracle OciThe database JDBC driver to use. Either Thin or OCI driver.
Hostlocalhost, testdbserv, ...The name of the host where the database system is running
Port1521, 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 Nameroot, 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.

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 NameValue(s)Description
TablespaceAxonIvy, AxonIvyEngine, AxonIvySystemDatabase, ...The name of the tablespace where the system database tables will store their data in.
UserAxonIvy, ...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 Nameoracle.jdbc.OracleDriver
JDBC Connection URL Formatjdbc:oracle:thin:@<host>:<port>:<service id>

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.

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 NameValue(s)Description
Database Microsoft SQL Server The database system to use.
Driver jTDS The database JDBC driver to use.
Hostlocalhost, testdbserv, ...The name of the host where the database system is running
Port3306, 3307, 3308, ...The IP port where the database system is listening for request
Database NameAxonIvy, AxonIvyEngine, AxonIvySystemDatabase, ...The name of the Axon.ivy Engine system database
User Namesa, 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 NameValue(s)Description
Database NameAxonIvy, AxonIvyEngine, AxonIvySystemDatabase, ...The name of the database to create

Table 3.13. Microsoft SQL Server Creation Parameter


Driver

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

Driver NameConnection URL FormatDocumentation
net.sourceforge.jtds.jdbc.Driverjdbc:jtds:sqlserver://<host>[:<port>]/<database name>jTDS JDBC Driver Documentation
com.microsoft.sqlserver.jdbc.SQLServerDriverjdbc:sqlserver://<host>[:<port>];DatabaseName=<database name>Microsoft SQL Server JDBC Driver Documentation

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.

ParameterValue
COLLATELatin1_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:

Field NameValue(s)Description
Database DB2 iSeries (AS400) The database system to use.
Driver DB2 iSeries (AS400) The database JDBC driver to use.
Hostlocalhost, testdbserv, ...The name of the host where the database system is running
Port50000, 50001, 50002, ...The IP port where the database system is listening for request
Schema NameAxonIvy, AxonIvyEngine, ....

The name of the SQL schema (library) to use.

Name with more than 10 characters are not supported.

User Namesa, 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 NameValue(s)Description
SchemaAxonIvy, 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 Namecom.ibm.as400.access.AS400JDBCDriver
JDBC Connection URL Formatjdbc:as400://<host>[:<port>]/<schema name>

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

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 NameValue(s)Description
DatabasePostgreSQLThe database system to use.
DriverPostgreSQLThe database JDBC driver to use.
Hostlocalhost, testdbserv, ...The name of the host where the database system is running
Port5432, 5433, 5434, ...The IP port where the database system is listening for request
Database NameAxonIvy, AxonIvyEngine, AxonIvySystemDatabase, ...The name of the database to use.
User Namesa, 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 NameValue(s)Description
Database NameAxonIvy, AxonIvyEngine, AxonIvySystemDatabase, ...The name of the database to create

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 Nameorg.postgresql.Driver
JDBC Connection URL Formatjdbc:postgresql://<host>[:<port>]/<database system>

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:

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

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.

ParameterValue
ENCODINGUTF8

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 nameDescription
Elasticsearch.BundledServer.DataPathThe 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.ClusterNameThe 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:

System Property nameDescription
Elasticsearch.ExternalServer.UrlThe URL of the external Elasticsearch server.
Elasticsearch.ExternalServer.UserNameName of the user to use to authenticate in the external Elasticsearch server.
Elasticsearch.ExternalServer.PasswordPassword of the user to use to authenticate in the external Elasticsearch server.
Elasticsearch.IndexNamePrefixThe 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 <IndexNamePrefix>-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 ValuesSystem Database (MySQL)Elasticsearch
20'000150 MB110 MB
100'000720 MB230 MB
1'000'0006.9 GB2.2 GB

Table 3.25.