ivy.yaml

[engineDir]/configuration/reference/ivy.yaml

# yaml-language-server: $schema=https://json-schema.axonivy.com/ivy/0.0.10/ivy.json
#
# -------------------------------------------
# Axon Ivy Engine Configuration
# -------------------------------------------
# 
# This file shows configurations of the Axon Ivy Engine and its external systems.
# https://developer.axonivy.com/doc/11.2/engine-guide/configuration/
#
# Copy contents of this reference file to 'configuration/ivy.yaml' before adjusting
# them to your needs.
# https://developer.axonivy.com/doc/11.2/engine-guide/configuration/files/ivy-yaml.html
#
# By default, the engine is pre-configured to run in demo mode.
# To run an engine in a productive environment, at least the system database
# has to be configured.
#
# SECRETS / PASSWORDS:
# Any configuration value can be encrypted just by enclosing it with "${encrypt:}".
# This applies a reversible encryption private to this Ivy Engine.
# You cannot copy the encrypted values from one engine to another.
# Example:
# * to encrypt the string "myPassword", write "${encrypt:myPassword}"
#   https://developer.axonivy.com/doc/11.2/engine-guide/configuration/advanced-configuration.html#passwords
#
# OVERRIDING:
# Any configuration value provided here can be set in alternative sources. 
# * environment variables: of the operating system can set app config entries. 
#    Their key must be prefixed with 'IVY_'. 
#    For instance, use 'IVY_SYSTEMDB_URL' to override the jdbc driver url.
#    https://developer.axonivy.com/doc/11.2/engine-guide/configuration/advanced-configuration.html#overriding-configuration
#



# == System Database Settings == 
#
# Axon Ivy requires a System Database to store the state of running workflow applications.
#
# Unless you run the engine in Demo mode, a valid System DB driver, url and the user+password credentials
# that are able to connect to the database, are mandatory.
# 
# [restart required]
SystemDb:
  # JDBC URL
  Url: ""
  # Name of the technical user to connect to system database on behalf of the engine. E.g. ivy, AxonIvy, workflowengine
  # e.g. ivy
  UserName: ""
  # Password for above technical user.
  # e.g. "${encrypt:1234}"
  # [password]
  Password: ""
  # Defines if the creation of the system database should be made automatically. 
  Creation:
    # If set to true, the system database will be created on startup, if it does not exist.  
    Enabled: true
    # Tablespace which will be used (only for Oracle).
    Tablespace: ""
    # Username which will be taken to create the system database (only for Oracle).
    UserName: ""
    # Password which will be taken to create the system database (only for Oracle).
    # [password]
    Password: ""
  # If set to true, the system database is automatically converted to the latest version during startup of the Axon Ivy Engine if needed.
  Autoconvert: false
  # Defines how long ivy should wait (in seconds) at startup for the db server to be available
  BootTimeout: 60
  # JDBC Driver. If not set, it is auto determined based on the JDBC URL.
  Driver: ""
  # Additional driver specific connection properties.
  DriverProperties: {}
  # Maximum number of connections to the system database.
  MaxConnections: 50



# == Adminstrators ==
#
# Administrators can configure, monitor and manage the Axon Ivy Engine.
#
# Email is used to send info mails like license expiration
# FullName is used to display a nice name for this user.
# 
# For security reasons, please hash the password(s) using "${hash:mySecret}".
# The real password cannot be recovered from the hash.
#
# Default administrator in demo mode is 'admin' with password 'admin'
#Administrators:
#  #Example admin user with username james and password mySecret
#  james: 
#    Password: "${hash:mySecret}"
#    Email: info@localhost
#    FullName: James David



# == Security Systems ==
#
# List of Security Systems. 
# A security system defines how users and roles are managed.
# Security systems that are configured here can be used by applications.
# !! If you change a security system then all users that are no longer defined by the changed security system will be disabled.
# !! Switching from an Identity Provider e.g. Azure Active Directory to Ivy Security System keeps all synchronized users, but
#    requires that you set (new) passwords for them. Before, passwords have been managed and kept by the Identity Provider for 
#    all managed users.
#
SecuritySystems:
  
  # 'default' security system which exists always
  default:
    # The security system slug name which will be used in URL as prefix for all resources
    # which are part of the security system.
    # If not set, then the security system name will be choosen. Only for the default security
    # context this is empty, by default.
    #UrlPath: ""

    IdenitityProvider:
      # The Security System manages the user and roles in the system database. 
      # For the Ivy Security System, no additional configuration is needed. 
      # For any other Security System, further configuration is need to integrate such a system. 
      # See https://developer.axonivy.com/doc/11.2/engine-guide/identity-provider
      # [enum: ivy, microsoft-active-directory, novell-edirectory, azure-active-directory]
      Name: ivy
    
    # == Notification Settings ==
    #
    # These notification settings allow enabling or disabling specific notification channels.
    # They also allow to configure the default subscription settings which will be applied to all users of a security system.
    # Users still have the option to customize their notification settings for enabled channels for themselves.
    # Applications can override the standard options.
    #
    Notification:
      # Contains the settings for cleaning up notifications.
      Cleanup:
        # Notifications older than this will be deleted on a daily basis.
        DaysUntilDeletion: 90
      # Contains the settings for each individual channel identified by the channels id.
      Channels:
        web:
          # The name of the channel
          Name: web
          # Each channel can be enabled or disabled.
          Enabled: true
          # The default subscription settings which will be applied to all users of a security system.
          Events:
            # If enabled, all events are subscribed.
            # Otherwise, only events mentioned under 'Kinds' are subscribed.
            AllKinds: enabled
            Kinds: []
        mail:
          Name: mail
          Enabled: false
          Events:
            AllKinds: enabled
            Kinds: []
        microsoft-teams:
          Name: microsoft-teams
          Enabled: false
          Events:
            AllKinds: enabled
            Kinds: []
    
    # == Document Storage ==
    #
    # Where to store the workflow documents. 
    #
    DocumentStorage:
      # The document storage define where the workflow documents should be stored.
      # [enum: local, s3]
      Name: local
    
    # == Language Settings ==
    # 
    # The default language settings, which apply to all users who have not explicitly set this
    # in their profile settings.
    #
    Language:
      # Content is displayed in this language if the content exists in this language. A locale (language[_COUNTRY])
      # must be specified for example de, de_CH, de_AT, de_DE, en, en_GB, en_US, fr, vi
      Content: en
      # Data like numbers, dates, times and much more are formatted according to this language. A locale (language[_COUNTRY])
      # must be specified for example de, de_CH, de_AT, de_DE, en, en_GB, en_US, fr, vi
      Formatting: en_GB



# == Base Url ==
#
# Web address of the Axon Ivy Engine installation, such as https://yourdomain/.
# This value is used to let ivy know how to refer to itself, ie. to create links in emails.
# This is necessary because ivy cannot reliably detect such a URL from within itself.
BaseUrl: ""



# == Single Sign-on ==
#
# Single Sign-on allows to auto login users. A reverse proxy has to be installed 
# in front of the Axon Ivy Engine. It is responsible for authenticating
# the user. The name of the user must then be transmitted as a HTTP header.
# !! Assert exclusive access to the Axon Ivy Engine otherwise
#    attackers can easily login as another user.
# https://developer.axonivy.com/doc/11.2/engine-guide/integration/single-sign-on
# [restart required]
SSO:
  # Shall SSO be enabled?
  Enabled: false
  # name of the HTTP header with the username that has to be provided by the reverse proxy
  UserHeader: X-Forwarded-User



# == Deployment Setting ==
#
Deployment:
  # Directory where the server watches for files to deploy.
  # https://developer.axonivy.com/doc/11.2/engine-guide/deployment
  #
  # You can speficy a remote network location using a UNC path:
  # Linux: //servername/share/file
  # Windows: \\servername\share\file
  #
  Directory: deploy
  
  Backup:
    # The number of backups of deployed projects that are kept on disk 
    # n < 0: infinite number of backups are kept
    # n = 0: No backups are made or kept
    # n > 0: Number of backups that are kept.
    Keep: 5



# == Data Settings ==
#
Data:
  #-----------------------------------------------------------------------------------------------
  # !! STOP YOUR ENGINE before changing these settings !!
  #
  # For all paths below, 
  # - absolute and relative paths (to the engine root directory) are supported
  # - we recommend to use locations outside the engine root directory to facilitate migrations.
  #-----------------------------------------------------------------------------------------------
  #
  # Folder where runtime data will be stored.
  #
  # [restart required]
  Directory: data
  #
  # Folder where applications are stored, unless otherwise defined in application specific configuration. 
  #
  # In demo mode: not configurable and set to: [Data.WorkDirectory]/demo-applications
  #
  # [restart required]
  AppDirectory: applications
  #
  # Root folder where application data files are stored.
  #
  # A change in this setting will NOT move existing application files to the new location.
  # You have to move existing files manually to the new directory.
  #
  # If not set, the files will be stored beneath each application's file directory.
  #
  # [restart required]
  FilesDirectory: ""
  #
  # Directory where the server writes temporary working files to.
  #
  # [restart required]
  WorkDirectory: work


# == Data Cache Settings ==
#
DataCache:
  # Invalidate data cache groups and entries. Checks if the lifetime of caches has ended and invalidates them.
  # You can set the delay in milliseconds between each check. This delay has to be greater than 0.
  #
  InvalidationInterval: 60000


# == Elasticsearch Settings ==
#
# Axon Ivy uses an Elasticsearch instance to provide scalable full text search capabilities.
# The bundled instance is started on demand, in a separate JVM, when an API request needs it.
#
# You can operate Axon Ivy with the bundled Elasticsearch server or with your own external Elasticsearch cluster.
#
# [restart required] except for UserName and Password of ExternalServer
Elasticsearch:
  # The bundled Elasticsearch server...
  # - is started in a separate JVM when a feature requires Elasticsearch.
  # - reachable only on 'localhost' but the access is unprotected. 
  # - JVM arguments used to start the bundled Elasticsearch server can be 
  #   configured in the 'elasticsearch/config/jvm.options' file.
  BundledServer:
    #
    # Path to the directory where the bundled Elasticsearch server stores data.
    # It is recommended to configure a data directory that is located outsite of the Engine 
    # installation directory to ease the Engine migration to newer versions.
    DataPath: elasticsearch/data
    #
    # Name of the cluster of the bundled Elasticsearch server.
    ClusterName: ivy-elasticsearch-{uid}
    #
    # Port to communicate with bundled Elasticsearch server
    #
    # AUTO: A free port in port range 19200-19299 is searched automatically.
    # <integer>: A fixed port number that you define. We recommend to use a number > 10000. 
    #            Make sure it is free.
    #
    Port: AUTO
  
  #
  # Configure access to your own Elasticsearch server if you want to use it instead of the bundled server.
  #
  # To install your own Elasticsearch server follow these steps
  # https://www.elastic.co/guide/en/elasticsearch/reference/7.17/setup.html
  #
  # Currently, Axon Ivy supports Elasticsearch server versions in the 7.17.x range. 
  # If your Elasticsearch server is running on another host, the access to that instance has to be protected.
  # You can achieve that with a front-end webserver like NGINX for Elasticsearch that enforces basic authentication.
  #
  ExternalServer:
    # Configure the URL of your own Elasticsearch server if you want to use it instead of the bundled server.
    Url: ""
    # Name of the user to use to authenticate in the external Elasticsearch server
    UserName: ""
    # Password of the user to use to authenticate in the external Elasticsearch server.
    # e.g. "${encrypt:}"
    # [password]
    Password: ""
  #
  # Settings for the indexes that are created in Elasticsearch.
  Index:
    # The name prefix for the indexes.
    # If multiple Ivy Engines use the same Elasticsearch server instance, you need to define unique NamePrefixes per engine.
    # You might add the engine host name as part of the name prefix, i.e. "servername"
    NamePrefix: ivy
    Reindex:
      # The number of objects that Ivy reads in one batch from the system database
      ReadWindowSize: 1000
      # The number of objects that Ivy writes in one batch to Elasticsearch
      WriteWindowSize: 1000
      # The size of the queue that is used to store objects read from the database 
      # until they are written to the Elasticsearch
      QueueSize: 10000
    # If BusinessData are not well modeled for Elasticsearch, you may have to increase the 'total_fields.limit' of the mapping.
    # Performance may decrease. If you change this setting, you need to reindex all business data in Engine Cockpit.
    TotalFieldsLimit: 4000
  #
  # Configures the Elasticsearch client. The client is the ivy engine which communicates with Elasticsearch.
  Client:
    # Maximum seconds to wait until a connection to Elasticsearch can be established.
    ConnectTimeout: 10
    # Maximum seconds to wait for data to be sent by Elasticsearch. 
    # Raise this value if large datasets are expected.
    ReadTimeout: 30



# == EMail Settings ==
#
EMail:
  Server:
    Host: ""
    Port: -1
    # Email address that will be used for emails sent by the server (e.g. task notification emails)
    MailAddress: noreply@ivyserver.local
    User: guest
    # [password]
    Password: ""
    # [enum: NONE, START_TLS, SSL]
    EncryptionMethod: NONE
    # Additional properties which will be set on the mail session
    # Read https://javaee.github.io/javamail/docs/api/com/sun/mail/smtp/package-summary.html
    SessionProperties:
    #  mail.smtp.auth.xoauth2.disable: false
    #
    # certificates are to be stored in the Ivy keystore (default: configuration/keystore.p12; see below at SSL / Client), with the alias defined below.
    SSL:
      KeyAlias: ""
      UseKey: false



# == Show Error Messages To End Users Settings ==
#
# When an error occurs while processing a user request, an error screen is displayed to the user. 
# 
# The displayed error page can be customized for your needs: 
# https://developer.axonivy.com/doc/11.2/engine-guide/configuration/files/web-xml.html
#
Errors:
  #
  # Shall the end user see detailed error information (stacktraces, detailed error reports, etc.)?
  #
  # By default (false) we only show a unique 'Error Id'. This 'Error Id' can be used to find the error in the log files.
  # 
  # For security reasons, normal users should not see technical implementation details.
  # But in development or pre-production environments, it might be safe to show the full error
  # details directly to the end user.
  # 
  ShowDetailsToEndUser: false



# == Persistence Settings ==
#
Persistence:
  JPA:
    # Persist ivyScript auto initialized fields with NULL values. Affects types:
    #  - ch.ivyteam.ivy.scripting.objects.Date
    #  - ch.ivyteam.ivy.scripting.objects.DateTime
    #  - ch.ivyteam.ivy.scripting.objects.Time
    # If this option is set to false, auto initialized values are stored as before Axon Ivy 6.4.
    defaultInitializedAsNull: true



# == Process Element Firing Statistic Settings ==
#
ProcessEngine:
  FiringStatistic:
    #
    # If set to true, a process element statistic is written periodically to the log directory. 
    #                 May impact server performance.
    Active: false
    #
    # Interval in seconds the 'process element statistic' is written to the log directory
    #
    Interval: 300



# == SSL Client Settings ==
#
SSL:
  Client:
    # Manipulates the JVMs default SSLSocketFactory, so that untrusted (self signed or outdated) certificates are silently accepted. 
    # This could for instance be useful to generate a Webservice stub from an insecure WSDL location.
    EnableInsecureSSL: false
    #
    # A key store is used to read client keys (certificates). 
    # This is only required if a remote server requests a client certificate in order to authenticate the client. 
    KeyStore:
      UseCustom: false
      # [password]
      KeyPassword: changeit
      Algorithm: SunX509
      File: configuration/keystore.p12
      # [password]
      Password: changeit
      Provider: ""
      Type: PKCS12
    #
    # A trust store is used to specify trusted server certificates or certificates of certification authorities. 
    # An SSL client autenticates a server by using the certificates in a trust store. 
    # Self signed or signed by an unknown certification authority can be added to this trustore. 
    TrustStore:
      File: configuration/truststore.p12
      Algorithm: PKIX
      # [password]
      Password: changeit
      Provider: ""
      Type: PKCS12



# == Workflow Settings ==
#
Workflow:
  # Can completed cases and tasks be seen by substitutes of the user who worked on them?
  # [enum: VISIBLE, INVISIBLE]
  History.ForSubstitutes: VISIBLE


# == Failure Behaviour ==
#
SystemTask:
  #
  # Defines the behaviour in case a system task fails. 
  #
  # [enum: FAIL_TASK_DO_RETRY, FAIL_TASK_DO_NOT_RETRY, DESTROY_TASK, DESTROY_CASE]
  Failure.Behaviour: FAIL_TASK_DO_RETRY
  #
  # Interval in seconds between executions of the search job for system tasks.
  # The job searches system tasks that were not executed because of failures.
  #
  SearchJob.Interval: 900



# == Thread Pools Settings ==
#
ThreadPool:
  #
  # Executes process engine background operations like Database, WebService calls, etc.
  BackgroundOperationExecutor:
    # Minimum number of threads
    CorePoolSize: 5
    # Maximum number of threads
    MaximumPoolSize: 200
  # Executes unscheduled jobs
  ImmediateJobExecutor:
    # Minimum number of threads
    CorePoolSize: 5
    # Maximum number of threads
    MaximumPoolSize: 50
  # Executes scheduled jobs
  ScheduledJobExecutor:
    # Minimum number of threads
    CorePoolSize: 5



# == Update Checker Settings ==
#
# When newer Axon Ivy versions are available, a message will be displayed on the Axon Ivy Engine main web page. 
# The update message contains information about the new versions and where those can be downloaded. 
#
# While checking for new versions the following statistic information is sent to the update server. 
# This information is 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)
# - 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)
#
UpdateChecker:
  #
  #  Shall update notification messages be shown and statistic information sent to the update server?
  Enabled: true
  #
  # Time of day when a update check will be executed
  # The engine must be running at this time otherwise the update check will not be executed.
  # Format is hh:mm. e.g. "02:00" or "14:15"
  # [daytime]
  ExecutionTime: ""


Boot:
  # Switch to maintencance mode if a configuration problem is detected during startup.
  # If set to DISABLED you can explicit start the engine in maintenance mode by using the command line option '-maintenance'.
  # [enum: AUTO, DISABLED]
  MaintenanceMode: AUTO


Cluster:
  #
  # The name of this node. 
  # If not configured, a random name is generated.
  # The name of a node is also used as jvm route identifier that is used by some load balancers to provide sticky sessions.
  # https://developer.axonivy.com/doc/11.2/engine-guide/integration/cluster
  # [restart required] 
  NodeName: ""
  #
  # The name of the cluster. 
  # It is used to find and communicate with other nodes of the same cluster.
  # Multiple clusters located in the same network must have different cluster names. 
  # Otherwise the nodes of both clusters find each other and build one cluster instead of two.  
  # [restart required]
  Name: "IvyCluster"