Chapter 12. Deployment descriptors

Processes and rules are stored in Apache Maven based packaging and are known as knowledge archives, or KJAR. The rules, processes, assets, and other project artifacts are part of a JAR file built and managed by Maven. A file kept inside the META-INF directory of the KJAR called kmodule.xml can be used to define the KIE bases and sessions. This kmodule.xml file, by default, is empty.

Whenever a runtime component such as KIE Server is about to process the KJAR, it looks up kmodule.xml to build the runtime representation.

Deployment descriptors supplement the kmodule.xml file and provide granular control over your deployment. The presence of these descriptors is optional and your deployment will proceed successfully without them. You can set purely technical properties using these descriptors, including meta values such as persistence, auditing, and runtime strategy.

These descriptors allow you to configure the KIE Server on multiple levels, including server level default, different deployment descriptor per KJAR, and other server configurations. You can use descriptors to make simple customizations to the default KIE Server configuration, possibly per KJAR.

You can define these descriptors in a file called kie-deployment-descriptor.xml and place this file next to your kmodule.xml file in the META-INF folder. You can change this default location and the file name by specifying it as a system parameter:


12.1. Deployment descriptor configuration

Deployment descriptors allow the user to configure the execution server on multiple levels:

  • Server level: The main level and the one that applies to all KJARs deployed on the server.
  • KJAR level: This enables you to configure descriptors on a per KJAR basis.
  • Deploy time level: Descriptors that apply while a KJAR is being deployed.

The granular configuration items specified by the deployment descriptors take precedence over the server level ones, except in case of configuration items that are collection based, which are merged. The hierarchy works like this: deploy time configuration > KJAR configuration > server configuration.


The deploy time configuration applies to deployments done via the REST API.

For example, if the persistence mode (one of the items you can configure) defined at the server level is NONE but the same mode is specified as JPA at the KJAR level, the actual mode will be JPA for that KJAR. If nothing is specified for the persistence mode in the deployment descriptor for that KJAR (or if there is no deployment descriptor), it will fall back to the server level configuration, which in this case is NONE (or to JPA if there is no server level deployment descriptor).

What Can You Configure?

High level technical configuration details can be configured via deployment descriptors. The following table lists these along with the permissible and default values for each.

Table 12.1. Deployment Descriptors

ConfigurationXML EntryPermissible ValuesDefault Value

Persistence unit name for runtime data


Any valid persistence package name


Persistence unit name for audit data


Any valid persistence package name


Persistence mode




Audit mode




Runtime Strategy




List of Event Listeners to be registered


Valid listener class names as ObjectModel

No default value

List of Task Event Listeners to be registered


Valid listener class names as ObjectModel

No default value

List of Work Item Handlers to be registered


Valid Work Item Handler classes given as NamedObjectHandler

No default value

List of Globals to be registered


Valid Global variables given as NamedObjectModel

No default value

Marshalling strategies to be registered (for pluggable variable persistence)


Valid ObjectModel classes

No default value

Required Roles to be granted access to the resources of the KJAR


String role names

No default value

Additional Environment Entries for KIE session


Valid NamedObjectModel

No default value

Additional configuration options of KIE session


Valid NamedObjectModel

No default value

Classes used for serialization in the remote services


Valid CustomClass

No default value


Do not use the Singleton runtime strategy with the EJB Timer Scheduler (the default scheduler in KIE Server) in a production environment. This combination can result in Hibernate problems under load. Per process instance runtime strategy is recommended if there is no specific reason to use other strategies. For more information about this limitation, see Hibernate issues with Singleton strategy and EJBTimerScheduler.

12.2. Managing deployment descriptors

Deployment descriptors can be configured in Business Central in MenuDesign$PROJECT_NAMESettingsDeployments.

Every time a project is created, a stock kie-deployment-descriptor.xml file is generated with default values.

It is not necessary to provide a full deployment descriptor for all KJARs. Providing partial deployment descriptors is possible and recommended. For example, if you need to use a different audit mode, you can specify that for the KJAR only, all other properties will have the default value defined at the server level.

When using OVERRIDE_ALL merge mode, all configuration items must be specified, because the relevant KJAR will always use specified configuration and will not merge with any other deployment descriptor in the hierarchy.

12.3. Restricting access to the runtime engine

The required-roles configuration item can be edited in the deployment descriptors. This property restricts access to the runtime engine on a per-KJAR or per-server level by ensuring that access to certain processes is only granted to users that belong to groups defined by this property.

The security role can be used to restrict access to process definitions or restrict access at run time.

The default behavior is to add required roles to this property based on repository restrictions. You can edit these properties manually if required by providing roles that match actual roles defined in the security realm.


  1. To open the project deployment descriptors configuration in Business Central, open MenuDesign$PROJECT_NAMESettingsDeployments.
  2. From the list of configuration settings, click Required Roles, then click Add Required Role.
  3. In the Add Required Role window, type the name of the role that you want to have permission to access this deployment, then click Add.
  4. To add more roles with permission to access the deployment, repeat the previous steps.
  5. When you have finished adding all required roles, click Save.