Cache and cache-related settings
In IBM® Business Process Manager, there are numerous cache and cache-related settings. If your data indicates a problem with the settings, you can edit the 100Custom.xml files for many of the settings or configure the property in the WebSphere administrative console for others and override the problematic default values of the settings.
When you specify new values for the cache and cache-related settings in the 100Custom.xml files, the new values will override the existing default values for the settings (which are typically located in other XML configuration files, such as the 00Static.xml files). For information about the use and location of the 100Custom.xml files and the associated XML configuration files, see the topic The 100Custom.xml file and configuration and its subtopics. For general information about performance tuning in IBM BPM, see the IBM Redbook IBM Business Process Manager V8.5 Performance Tuning and Best Practices.
The cache and cache-related settings that you might want to override in the 100Custom.xml files are described in the following sections:
- PO factory cache settings
- Repository cache settings
- Script cache settings
- ManagedAsset cache settings
- User-related cache settings
- Other cache settings
- Cache configuration settings
In some of these sections, the settings are reflected in the Instrumentation monitor of the Process Admin Console and they are described in detail in the topic Using process instrumentation data for cache tuning.
If you have symptoms where XPath expressions are not found in the cache, follow the instructions in the XPath cache settings section to increment the cache setting.
PO factory cache settings
For information about the PO factory cache settings that are reflected in the PO Factory section of the Instrumentation monitor, see the topic Using process instrumentation data for cache tuning.Repository cache settings
For information about the repository cache settings that are reflected in the Repository section of the Instrumentation monitor, see the topic Using process instrumentation data for cache tuning.Script cache settings
The following table lists script cache settings that are not reflected in the Instrumentation monitor. In some situations, you might need to override the settings to tune and enhance performance. All settings are enabled in the XML configuration files unless indicated otherwise.
Name | Setting and description | Setting to add or update in the 100Custom.xml file |
---|---|---|
JavaScript engine |
shared-scope-optimization-level The JavaScript engine configuration settings are used with JavaScript server-side script processing, but they can also be used to tune the performance of JavaScript code in Coaches. For those configuration settings that accept a numeric value between -1 and 9, a value of -1 means that the setting is interpreted, whereas a value from 0 to 9 specifies a level of optimization (with 9 being the level of most optimization with faster execution but slower compilation). A value of -1 is recommended and tests have demonstrated that any value other than -1 will generally hinder performance rather than help it. Important: Changing the default values may lead to a serious
degradation in performance.
The shared-scope-optimization-level setting specifies the optimization level for shared JavaScript code, such as the function library (which is loaded from process-server/resources/js). Large scripts can cause compilation failures. The default value is -1. The script-component-optimization-level setting specifies the optimization level for script components in Teamworks services. Large scripts can cause compilation failures, which results in scripts being executed in interpretive mode. The default value is -1. The default-script-cache-optimization-level setting specifies the default optimization level for most of the JavaScript code. This includes the JavaScript that is used for parameter mappings, UCA invocation components, integration components, exception handling components, etc. Generally, the JavaScript code is not large and should not cause compilation failures. In the event of compilation failures, scripts are executed in interpretive mode. The default value is -1. The coach-optimization-level setting specifies the optimization level for the JavaScript code generated for coaches, including custom server-side JavaScript blocks that are inserted by authors. Large generated scripts can cause compilation failures, which results in coach scripts being executed in interpretive mode. The default value is -1. The use-embeded-jscript-with-buff setting specifies whether the EmbededJScriptWithBuff setting should be used everywhere instead of the deprecated EmbededJScript setting. The default value is true. The cached-scope-size setting specifies the maximum size for the runtime scope cache. The default value is 50. If you set a value that is smaller than 5, your setting will be ignored and the default value will be used instead. The JavaScript engine configuration settings are all located in the applicable 00Static.xml files, but updates to the default values of the settings must be made by adding the settings to the 100Custom.xml files. |
|
ManagedAsset cache settings
The following table lists ManagedAsset cache settings that are not reflected in the Instrumentation monitor. In some situations, you might need to override the settings to tune and enhance performance. All settings are enabled in the XML configuration files unless indicated otherwise.
Name | Setting and description | Setting to add or update in the 100Custom.xml file |
---|---|---|
ManagedAssetClassloader cache |
classloader-cache-size Depending on the number of IBM BPM managed files and the number of process applications that use managed files, you might experience slow performance when you work with the managed files. If the managed asset class loader cache, managed asset cache, or both caches are small, the cache must be refreshed often, which decreases performance. However, you can use the ManagedAssetClassloader settings to define the cache sizes for managed files. The classloader-cache-size setting can be used to stop class loader instances from being swapped out of the cache too frequently. There is one class loader instance for each version of a process application. To prevent these instances from being swapped out of the cache too often, set the value to a number that is higher than the number of active process application versions on your system. For example, if you have n process applications and each process application has m active snapshots, set the value to (n*m). The default value is 1000. The classloader-resource-map-size setting defines the number of Java classes that are inside managed files and cached over all process applications and versions. The default value is 5120. When you use huge JAR files
as managed assets, increase the numeric value of the classloader-resource-map-size setting.
The classloader-resource-map-size is a JVM-wide
setting, which means that the specified value should be high enough
to cache all managed assets that are used on the JVM. For example,
assume that you have the following three JAR files as managed assets:
The settings are located in the applicable 00Static.xml files, but updates to the default values of the settings must be made by adding the settings to the 100Custom.xml files. Detailed information about the classloader-cache-size and classloader-resource-map-size settings is found in the topic Configuring managed asset and managed asset classloader cache sizes. |
|
User-related cache settings
The following table lists user-related cache settings that are not reflected in the Instrumentation monitor. In some situations, you might need to override the settings to tune and enhance performance. All settings are enabled in the XML configuration files unless indicated otherwise.
Name | Setting and description | Setting to add or update in the 100Custom.xml file |
---|---|---|
default-webapi-userid-cache-size |
default-webapi-userid-cache-size This setting has a default value of 500. The setting is located in the applicable 00Static.xml files, but updates to the default value of the setting must be made in the 100Custom.xml files. |
|
UserAttribute cache |
cache-expiration-time These three settings are UserAttribute cache settings. The cache-expiration-time setting has a default value of 30000 milliseconds. The cache-max-size setting has a default value of 200. The query-performance-threshold setting has a default value of 3000. The settings are all located in the applicable 00Static.xml files, but updates to the default values of the settings must be made by adding the settings to the 100Custom.xml files. |
|
team-task-user-cache-minutes-to-live The team-task-user-cache-minutes-to-live setting specifies the cache life for user and team information used on dashboards. It has a default value of 15 minutes. The setting is located in the applicable 98Local.xml files, but updates to the default value of the setting must be made by adding the setting to the 100Custom.xml files. |
|
Other cache settings
The following table lists some other cache settings that are not reflected in the Instrumentation monitor. In some situations, you might need to override the settings to tune and enhance performance. All settings are enabled in the XML configuration files unless indicated otherwise.
Name | Setting and description | Setting to add or update in the 100Custom.xml file |
---|---|---|
LRU cache |
bpm-repo-max-cached-snapshots This setting specifies the maximum number of cached snapshots in the BPM repository. The default value is 1000. The setting is located in the applicable 00Static.xml files, but updates to the default value of the setting must be made by adding the setting to the 100Custom.xml files. |
|
TWObject Class cache |
twobject-class-cache-size When a process or service accesses the value of a variable, it needs to load its business object definition. This lookup is initially performed in the snapshot of the running process or service and in its toolkit references. If a business object type has not yet been found, the lookup is performed from the process application snapshot in which the process instance was started. The TWObject Class cache remembers how a business object type is determined from a snapshot. You can change the size of this cache with the twobject-class-cache-size setting in the 100Custom.xml files. The default value for the setting is 5000. Generally, the setting should be adjusted whenever you continuously see cache misses for TWClass in the Instrumentation monitor or logs. An exact starting value is difficult to calculate because it requires deep knowledge about the process applications that run. You can start with a value of 5000 and then vary this value during performance tests. If you have a deep understanding of the process applications, you can perform the following calculation for each process application snapshot to get a starting value: (1 + N) * B In this calculation, the variable N is the number of included toolkits that contain runnable artifacts (services or processes). (Those do not necessarily need to be exposed. If the same toolkit snapshot is used by multiple process applications, then it only needs to be included once in the calculation.) The variable B is the total number of business object types used within the process application. You can create a sum of the value for all process application snapshots and then use it as the starting value for the twobject-class-cache-size setting. Although the setting is located in the applicable 00Static.xml files, updates to the default value of the setting must be made by adding the setting to the 100Custom.xml files. |
|
BusinessDataAliases cache |
use-business-aliases-for-process-instances Business process definition (BPD) variables that are configured to be available for search are assigned alias names and are cached in the business data alias cache. To improve performance, you can configure the cache to receive the business data aliases for only the snapshots that have associated instances, rather than keeping the default setting that returns all the aliases for all the snapshot definitions. You can use the BusinessDataAlias cache settings to configure the cache. The use-business-aliases-for-process-instances setting impacts how the alias cache is loaded. You can build some saved searches from the complete list of aliases, and then switch to the instance-based list of aliases to get better performance. If the setting is set to its default value of false, all the BPDs are searched and the cache is loaded once with all the defined aliases in all the snapshots. If the setting is set to true, a list of searchable business data aliases is returned that is based on the aliases within existing BPD instances. The bdac-refresh-interval setting specifies the interval between automatic cache refreshes. However, it is effective only when the value of the property use-business-aliases-for-process-instances is set to true. You might want to change the cache refresh interval when there are a small number of instances in the system or when instances start and are deleted before the cache is refreshed. This setting should have a shorter value in Process Center than in Process Server because Process Center tends to have fewer BPD instances running and the BPDs change much more frequently. The default value is 1800 seconds (30 minutes). The init-bdac-on-startup setting controls when the cache is initially loaded. The setting is only effective when the use-business-aliases-for-process-instances setting is set to false. If the setting is set to the default value of true, the cache is initialized when the server starts. If the setting is set to false, the cache is initialized when it is first accessed, which generally means that the first user will experience a long delay. The use-business-aliases-for-process-instances and init-bdac-on-startup settings are located in the applicable 99Local.xml files. The bdac-refresh-interval setting is located in the applicable 00Static.xml files. Updates to the default values of the settings must be made by adding the settings to the 100Custom.xml files. Detailed information about the settings and how to set them in the 100Custom.xml files is found in the topic Business data alias cache configuration. |
|
Transformations |
xsl-cache-max-size This setting specifies the maximum XSLT cache size for teamworks.XSLConnector. The default value is 512. The setting is located in the applicable 99Local.xml files, but updates to the default value of the setting must be made by adding the setting to the 100Custom.xml files. |
|
Service result cache |
service-result-cache-size This setting specifies the maximum size for the service result cache. The default value is 4096. The setting is located in the applicable 99Local.xml files, but updates to the default value of the setting must be made by adding the setting to the 100Custom.xml files. |
|
Task activity measures |
max-cache-size The max-cache-size setting has a default value of 100. The max-cache-entry-update-count setting has a default value of 20. The value should be at least 1. The cache-entry-removal-policy setting has a default value of Lru. The alternative value is Random. The settings are located in the applicable 98Local.xml files, but updates to the default values of the settings must be made by adding the settings to the 100Custom.xml files. |
|
task-authorization-invite-cache-size This setting has a default value of 500. The setting is located in the applicable 98Local.xml files, but updates to the default value of the setting must be made by adding the setting to the 100Custom.xml files. |
|
|
enable-process-instance-activity-tracking The enable-process-instance-activity-tracking setting specifies whether process tracking is enabled, which is used for obtaining process at-risk information for display in the Process Portal. If the setting is set to the default value of true, process tracking is enabled and the tracking daemon is started to synchronize tracking information from the database to the caches. If the setting is set to false, process tracking is disabled and the tracking daemon is not started. The cache-synchronization-interval setting determines the interval of time between each run of the tracking daemon. The default interval value is 300 seconds. Both settings are located in the applicable 99Local.xml files, but updates to the default values of the settings must be made by adding the settings to the 100Custom.xml files. |
|
|
Web service integration | use-pre856-wsdl-cache When you create an integration service in Process Designer, IBM BPM caches the files when the following conditions are true:
The use-pre856-wsdl-cache setting specifies whether the WSDL and XSD files from the web service provider are cached in the server memory before the integration service is initially called during each restart of the server. The default value is false. However, for migrated process applications, a value of true is generally specified. The wsdl-cache-size setting specifies the number of WSDL files that are held in the cache. To balance memory cost and performance, you can use the setting to adjust the number of WSDL files in the cache. The default value is 25. For additional information, see the topic WSDL and XSD cache algorithm for web service integration. |
|
EpvVarValueCache | enable-epv-var-value-cache By default, EPV variable values are retrieved from a cache named EpvVarValueCache. If this cache is disabled, EPV variable values are retrieved from the BPM DB instead. This can result in high data traffic and high CPU load, which decreases the performance of the system. The enable-epv-var-value-cache setting is used to enable or disable EpvVarValueCache. The default value is true. To disable EpvVarValueCache, change the value to false. The default-epv-var-value-cache-size setting is used to specify the size of EpvVarValueCache. The default value is 1000. Updates to the default values of one or both settings must be made by adding the settings to the 100Custom.xml files. |
|
EnvVarValueCache | enable-env-var-value-cache By default, environment variable values are retrieved from a cache named EnvVarValueCache. If this cache is disabled, environment variable values are retrieved from the BPM DB instead. This can result in high data traffic and high CPU load, which decreases the performance of the system. The enable-env-var-value-cache setting is used to enable or disable EnvVarValueCache. The default value is true. To disable EnvVarValueCache, change the value to false. The default-env-var-value-cache-size setting is used to specify the size of EnvVarValueCache. The default value is 1000. Updates to the default values of one or both settings must be made by adding the settings to the 100Custom.xml files. |
|
Rule Language services | When a decision is executed, edited or exported, a rule language service is required. The rule language service contains information about the vocabulary that can be used by the decision. Because the vocabulary depends on the variables and types that are used by the process and the locale of the decision, a rule language service is stored in the cache for each service flow version and locale on first access. You can change the size of this cache with the rule-language-cache-size setting in the 100Custom.xml files. The default value for the setting is 15. Based on the number of service flows that contain decisions you should adjust the size of the cache. For example, if you have 20 service flows that contain decisions you could increase the size to 20. Updates to the default value of the setting must be made by adding the setting to the 100Custom.xml files. |
|
Cache configuration settings
The following table lists cache configuration settings that are not reflected in the Instrumentation monitor. In some situations, you might need to override the settings to tune and enhance performance. All settings are enabled in the XML configuration files unless indicated otherwise.
Name | Setting and description | Setting to add or update in the 100Custom.xml file |
---|---|---|
cache-task-categories The cache-task-categories setting applies specifically to the code that is used to populate the legacy Task Manager folder list (from TW5.0.x and earlier). It specifies whether Task Manager should use a single cached list of categories for all folders (where each folder contains the same list of categories). This setting has a default value of false. If a value of true is specified, the cache will be refreshed every 300 seconds (unless the default value of 300 seconds has been changed in the category-cache-refresh-interval setting). Otherwise, TeamWorks obtains the list of categories for each folder as usual. If you enable this setting, you will reduce database traffic and increase overall throughput. However, when the setting is enabled, certain categories may not appear until the cache refreshes and all categories will appear under each folder (even if no tasks in the folder are assigned to those categories). The category-cache-refresh-interval setting specifies the number of seconds between each refresh of the category cache. The default value is 300 seconds (5 minutes). The settings are located in the applicable 00Static.xml files, but updates to the default value of the setting must be made by adding the setting to the 100Custom.xml files. |
|
|
unversioned-po-caching-enable This setting is used to enable persistent object (PO) caching. The default value of true is recommended. The setting is located in the applicable 00Static.xml files, but updates to the default value of the setting must be made in the 100Custom.xml files. |
|
|
Group member cache |
group-member-cache-source This setting specifies whether members of a group are only retrieved from the IBM BPM database and not from the user registry; for example, LDAP. This setting significantly increases the speed at which group members are loaded into the cache and it reduces the number of cache reloads. By default, the value is unset (null), but it can be set to the value DB in the 100Custom.xml file. The system uses an in-memory group member cache to keep track of the members of a group. When the system is adding a group to a team, it retrieves the members of the group from both LDAP and the IBM BPM database. For large groups, LDAP access for retrieving group members can take many minutes, which can make the system appear to hang. If LDAP connection timeout values are not high enough, the connection might terminate without any data retrieval. To help resolve this problem, add the group-member-cache-source setting to the 100Custom.xml files to specify that the members of a group are determined from the database only. For more information, see the topic Specifying that members of a group member cache are retrieved from the database. |
|
XPath cache settings
If an XPath expression that is used in a BPEL process is not found in the cache, the expression must be compiled. This compilation happens either if the cache is too small or the expression is evaluated for the first time.
You set the cache size by configuring a custom property ProcessXPathIntermediateResultCacheSize in the WebSphere® Application Server administrative console. ProcessXPathIntermediateResultCacheSize defaults to 100, which can be too small for some environments and might impact performance or in rare cases cause transaction timeouts.
The right size of the cache depends on the number of XPath expressions that exist across all processes. If you cannot determine the right number, it is recommended that you increase the cache size in steps and monitor your system performance. For example, start with 500, then gradually increase in multiples of 200. The larger the cache, the better the reuse, but keep in mind that the cache is kept in memory and increases memory consumption.
- In the WebSphere Application Server administrative console, click .
- Verify whether the ProcessXPathIntermediateResultCacheSize property exists. If it does not exist, click New to create it. Enter the Name and the Value to be set for the custom property. Click Apply or OK, and then click Save in the Messages box that appears. Restart the server for the custom property to take effect.