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 plus all YAML and properties files from the configuration directory of the old installation directory to the configuration directory of the new installation.

  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 “Engine Configuration UI” (See “System Database”). Or set autoConvert property to true in the “ivy.yaml” of 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 the Elasticsearch section in the “ivy.yaml” of the configuration directory.

  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. Run the Axon.ivy Engine as Service which runs automatically after a reboot.

  2. Integrate Axon.ivy Engine into web servers if necessary.

  3. Deploy workflow 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 admin and password admin.

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 “Cluster ”. 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 UI” 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 UI” 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.

For Debian based operating systems there is a convenient installer package available.

The following platforms are supported:

CPUArchitectureOperation SystemInstallation File
Intelx64Debian (Ubuntu/Mint)axonivy-engine-V_X.Y.Z.deb
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
 defaults/Documentation and templates for ivy.yaml files
 demo.licDemo licence file
 “ivy.yaml”Main configuration file of the Axon.ivy Engine. Configures environments such as the system database, e-mail servers, administrators and more.
 “ivy.cache.properties”System database cache configurations
 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.xml”Logging 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)
 visualvmThe 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
 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 “ Control Center”.
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 “Engine Configuration UI”.
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 “Windows Service”.

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.conf”Java virtual machine configuration (Xms, Xmx, JMX, ...) for the Engine.
AxonIvyEngineConfigProgram to configure the Axon.ivy Engine. For more information see section “Engine Configuration UI”.
AxonIvyEngine.serviceTemplate systemd script of the Linux service. It will be copied to /etc/systemd/system/ by running InstallService.sh.
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 “ Control Center”.
InstallService.shScript to install the Axon.ivy Engine as a daemon. For more information see section “Linux Service (systemd)”.
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.

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

MariaDB

Information

MariaDB is an Open Source database. For more information go to mariadb.org. MariaDB is a drop-in replacement for MySQL. The documentation for MySQL often applies to MariaDB as well.

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 MariaDB The database system to use.
Driver MariaDB 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 requests.
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.9. MariaDB 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 MariaDB database system:

Field NameValue(s)Description
Database NameAxonIvy, AxonIvyEngine, AxonIvySystemDatabase, ...The name of the database to create
Engine Type InnoDb The type of the MariaDB database engine to use. At the moment only InnoDb is possible.

Table 3.10. MariaDB Creation Parameter

Driver

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

JDBC Driver Nameorg.mariadb.jdbc.Driver
JDBC Connection URL Formatjdbc:mariadb://<host>[:<port>]/<database name>

Table 3.11. MariaDB 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 = "AXONIVYSYSTEMDATABASE" AND table_name = "iwa_case" AND column_name = "name"

If you need to change the collation look at the official MariaDB 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 MariaDB 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.12. MariaDB Default Database Configuration

Oracle

Information

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

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 requests.
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.13. 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. It can be set in the “Launch Configuration”.

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.14. 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.15. 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.

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 or Microsoft SQL Server The database JDBC driver to use.
Hostlocalhost, testdbserv, ...The name of the host where the database system is running.
Port1433, 1434, 1435, ...The IP port where the database system is listening for requests.
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.16. Microsoft SQL Server 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/instanceName 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.17. Microsoft SQL Server Creation Parameter

Driver

The following table shows information about the JDBC drivers 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.18. 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.19. Microsoft SQL Server Default Database Configuration

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

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 requests.
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.20. 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.21. 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.22. 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.23. PostgreSQL Default Database Configuration