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:
-Dorg.kie.deployment.desc.location=file:/path/to/file/company-deployment-descriptor.xml
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.
| Configuration | XML Entry | Permissible Values | Default Value |
|---|---|---|---|
| Persistence unit name for runtime data | persistence-unit | Any valid persistence package name | org.jbpm.domain |
| Persistence unit name for audit data | audit-persistence-unit | Any valid persistence package name | org.jbpm.domain |
| Persistence mode | persistence-mode | JPA, NONE | JPA |
| Audit mode | audit-mode | JPA, JMS or NONE | JPA |
| Runtime Strategy | runtime-strategy | SINGLETON, PER_REQUEST or PER_PROCESS_INSTANCE | SINGLETON |
| List of Event Listeners to be registered | event-listeners |
Valid listener class names as | No default value |
| List of Task Event Listeners to be registered | task-event-listeners |
Valid listener class names as | No default value |
| List of Work Item Handlers to be registered | work-item-handlers |
Valid Work Item Handler classes given as | No default value |
| List of Globals to be registered | globals |
Valid Global variables given as | No default value |
| Marshalling strategies to be registered (for pluggable variable persistence) | marshalling-strategies |
Valid | No default value |
| Required Roles to be granted access to the resources of the KJAR | required-roles | String role names | No default value |
| Additional Environment Entries for KIE session | environment-entries |
Valid | No default value |
| Additional configuration options of KIE session | configurations |
Valid | No default value |
| Classes used for serialization in the remote services | remoteable-class |
Valid | 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 Menu
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.
Procedure
-
To open the project deployment descriptors configuration in Business Central, open Menu
Design $PROJECT_NAME Settings Deployments. - From the list of configuration settings, click Required Roles, then click Add Required Role.
- 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.
- To add more roles with permission to access the deployment, repeat the previous steps.
- When you have finished adding all required roles, click Save.
