Configuration

The Axon.ivy Engine is configured by files. They are located in the /configuration directory of the engine.

Files

The ivy.yaml file contains the most important entries that define the environment and runtime behaviour of the Axon.ivy Engine.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
# sample ivy.yaml with some often used entries defined
SystemDb:
  Driver: org.mariadb.jdbc.Driver
  Url: jdbc:mariadb://myDbHost:3306/AxonIvySystemDatabase
  UserName: root
  Password: 1234
EMail:
  Server:
    Host: smtp.gmail.com
    Port: 25
Administrators:
  admin:
    Password: 1234
    Email: info@localhost
  devop:
    Password: "${encrypt:4321}"
    Email: dev@axonivy.com
Frontend:
  HostName: workflow.acme.com
  Port: 80

Craft you own configuration

To craft your own configuration you would typically copy values from our reference files, located under [engineDir]/configuration/reference or see te Configuration File Reference and adjust them according to your needs. Alternative, you can also copy and modify whole templates, which are provided under [enginDir]/configuration/templates. Of course, most settings can also be adjusted in our Engine Cockpit.

System Database

An untouched Axon.ivy Engine runs in demo mode. In consequence workflow data is never stored, but kept in a memory database. To run a productive engine an external system database must be connected, where workflow data will be stored.

To define the database of the Axon.ivy Engine, the SystemDb entries must be set.

1
2
3
4
5
6
# sample ivy.yaml that configures a MySQL database as data store
SystemDb:
  Driver: org.mysql.jdbc.Driver
  Url: jdbc:mysql://myOtherMysql:3306/AxonIvySystemDatabase
  UserName: theUser
  Password: myPassword

To run the Axon.ivy Engine with a System Database a license is required. See Installing a Licence.

The schema of the Axon.ivy System Database must exist on the referenced database system. The Engine Configuration UI and EngineConfigCli simplify the creation of the SystemDb connection.

Users

Users are kept in a so-called security system which can be defined in ivy.yaml. Each application defines in app.yaml which security system is used. There are two types of security systems:

  • Internal Security System: Used to manage the users directly on the Axon.ivy Engine. There is only one Internal Security System, which is called Ivy Security System. No further settings are available for this Security System. This is also the default Security System for application which has no security system defined.

  • External Security System: Used to synchronize users from a name and directory service such as Active Directory. The example below shows a simple connection to an Active Directory. Have a look at the ivy.securitysystem.yaml for all supported name and directory services and further settings.

     1
     2
     3
     4
     5
     6
     7
     8
     9
    10
    11
    12
    # sample ivy.yaml that define an Active Directory as security system
    SecuritySystems:
      # Custom definied name of your security system
      ActiveDirectoryOfMyCompany:
        Provider: "Microsoft Active Directory"
        Connection:
          Url: "ldap://activedirectory.axonivy.com:389"
          UserName: "activedirectory_user@axonivy.com"
          Password: "${encrypt:1234}"
        Binding:
          DefaultContext: "DC=axonivy,DC=com"
          ImportUsersOfGroup: "CN=AXON Ivy IT,DC=axonivy,DC=com"
    
    1
    2
    # app.yaml located in e.g. <configuration>/app-myApp.yaml
    SecuritySystem: ActiveDirectoryOfMyCompany
    

Email

The Axon.ivy engine sends emails for different purposes:

  • Emails that are sent within a process via the mail step.

  • New task assignment and daily task summaries to users.

  • License expiration reminders to the administrators.

For this you have to configure an email server in ivy.yaml:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
# sample ivy.yaml that configures an email server:
EMail:
  Server:
    Host: mail.axonivy.com
    Port: 25
    MailAddress: noreply@axonivy.com
    User: someuser
    Password: somepassword

  DailyTaskSummary:
    # Time of day when the task summary mails will be sent.
    TriggerTime: "02:00"

You can configure task email notification settings for new task assignments and daily task summaries at application level in app.yaml:

1
2
3
4
5
# app.yaml located in e.g. <configuration>/app-myApp.yaml
EMailNotification:  
  DailySummaryOn: monday, tuesday, wednesday, thursday, friday
  OnNewTasks: true
  Language: de

Users are able to customize their notification settings in a workflow ui like the Portal. The content of the task email notifications can be customized by providing Standard Processes.

Advanced Configuration

Passwords

You may want to encrypt sensitive data like a password in your configuration files. To do this you can enclose any value with "${encrypt:}". The Axon.ivy Engine will automatically encrypt and replace that value in file, when the configuration will be loaded. The system database password can be encrypted as follows:

1
2
3
# ivy.yaml
SystemDb:
  Password: "${encrypt:myPassword}"

There is a smooth Secrets integration, which is very useful in container environments such as Docker.

Business Calendar

A business calendar defines the official business hours and business days. These settings are used for business calendar calculations, e.g. what date will it be in three business days. See at Designer Guide and IBusinessCalendar for more information.

It is defined in the application’s app.yaml. An application contains at least one business calendar; if none is defined, a default calendar is automatically generated.

Here is an example of a business calendar definition; see app.businesscalendar.yaml for more detailed information.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
# Business Calendar
# [engineDir]/configuration/app-<APPNAME>.yaml
BusinessCalendars:

  # Company wide calendar definition
  AxonIvy:
    FirstDayOfWeek: monday

    WorkingTimes:
      morning: 8:00-12:00
      afternoon: 13:00-17:00

    FreeDays:
      WeekendStart: saturday
      WeekendEnd: sunday
      "New Year": 01-01
      "Christmas Day": 12-25

  # Calendar definition for Switzerland
  Switzerland:
    Parent: AxonIvy
    FreeDays:
      "Good Friday": easter - 2
      "Easter Sunday": easter
      "Easter Monday": easter + 1
      "Ascension Day": easter + 39
      "Swiss National Day": 08-01

  # Calendar definition for Zurich region, inheriting from Switzerland and AxonIvy calendar
  Zurich:
    Parent: Switzerland
    FreeDays:
      "Day after New Year": 01-02
      "Labour Day": 05-01
      "Pentecost Monday": easter + 50
      "Saint Stephens Day": 12-26

  # Calendar definition for Zug region, inheriting from Switzerland and AxonIvy calendar
  Zug:
    Parent: Switzerland
    FreeDays:
      "Ascension Day": easter + 39
      "Pentecost Monday": easter + 50
      "Corpus Christi": easter + 60
      "Maria Assumption Day": 08-15
      "All Saints Day": 11-01
      "Immaculate Conception Day": 12-08
      "Saint Stephens Day": 12-26

  # Calendar definition for IvyTeam, with an additional special celebration day
  IvyTeam:
    Parent: Zug
    FreeDays:
      "50 Years Ivyteam": 2043-04-07

Html Theme

The look and feel of Html Dialogs is defined by its theme. You can change the appearance of any dialog on several scopes:

  • Globally for all Html Dialogs via web.xml.

  • For a single application in the app.yaml.

1
2
3
# app.yaml located in e.g. <configuration>/app-myApp.yaml
Jsf:
  primefaces.theme: modena-ivy

Overriding Configuration

Environment variables

Configuration entries of YAML files can be overridden with environment variables of the operating system. Configuration keys in YAML are hierarchic object trees separated by : characters. While the environment variable must be written uppercase and separated by _ characters. You need also to prefix the environment variable with IVY_.

So to overwrite the SystemDb:Url of the ivy.yaml file, the environment variable IVY_SYSTEMDB_URL must be set.

Docker Containers

Container technology empowers you to pull up reproducible, documented and complete isolated infrastructures. Axon.ivy fully supports container environments such as Docker, Kubernetes or OpenShift. You can easily customize the configuration of an Axon.ivy engine by using system environment variables or by providing configuration files like the ivy.yaml file.

The following example will override the url of the system database configuration using environment variables:

docker run -e "IVY_SYSTEMDB_URL=jdbc:mysql://db:3306/AxonIvySystemDatabase" ...

Instead of using environment variables, you can simply provide an ivy.yaml file.

1
2
3
# ivy.yaml
SystemDb:
  Url: jdbc:mysql://db:3306/AxonIvySystemDatabase

And let’s run the container with this configuration

docker run -v $(pwd)/ivy.yaml:/etc/axonivy-engine/ivy.yaml ...

Tip

On Windows use %cd%/ivy.yaml instead of $(pwd)/ivy.yaml

For further docker examples have a look at our docker-samples GitHub repository.

Secrets

You can use Docker Secrets to store passwords. Simply create a file in /run/secrets which has the same name as the configuration entry. For example, to provide SystemDb:Password as secret file you need to create the file /run/secrets/ivy.SystemDb.Password