Chapter 10. Deployment descriptors
Chapter 10. 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 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 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: 10.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 . Note 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 10.1. Deployment Descriptors 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 ObjectModel No default value List of Task Event Listeners to be registered task-event-listeners Valid listener class names as ObjectModel No default value List of Work Item Handlers to be registered work-item-handlers Valid Work Item Handler classes given as NamedObjectHandler No default value List of Globals to be registered globals Valid Global variables given as NamedObjectModel No default value Marshalling strategies to be registered (for pluggable variable persistence) marshalling-strategies Valid ObjectModel classes 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 NamedObjectModel No default value Additional configuration options of KIE session configurations Valid NamedObjectModel No default value Classes used for serialization in the remote services remoteable-class Valid CustomClass No default value Warning 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 . 10.2. Managing deployment descriptors Deployment descriptors can be configured in Business Central in Menu Design USDPROJECT_NAME Settings Deployments . 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. 10.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 USDPROJECT_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 steps. When you have finished adding all required roles, click Save .
-Dorg.kie.deployment.desc.location=file:/path/to/file/company-deployment-descriptor.xml