Process Engines

This page describes how to customize settings for the Appian Process Engine Server.

Overview

You can customize settings for the Appian Process Engine Server by editing custom properties in the Appian CR configuration file. You can change these fields while Appian is running; no restart is required.

Process execution properties

AUTOARCHIVE_DELAY

Property

Description

server.conf.exec.AUTOARCHIVE_DELAY

By default, completed and canceled processes are archived every 7 days after they have completed or been canceled (when AUTOARCHIVE is set to 1). The archive interval value can be changed by setting AUTOARCHIVE_DELAY to the desired number of days. Each completed or canceled process is automatically archived after the time set for this parameter has elapsed. It is set to 7 by default. See also: Archiving and Unarchiving Processes.

CHAINED_EXECUTION_NODE_LIMIT

Property	Description
server.conf.exec.CHAINED_EXECUTION_NODE_LIMIT	This parameter lists the maximum number of unattended nodes that can be executed while searching for the next attended node during activity-chaining. By default, this is set to 50 nodes.

Common Process settings

Common Process settings can be modified by setting the values of the following parameters in the Appian CR configuration file.

NOTES_SRC_DIR

Property	Description
server.conf.processcommon.NOTES_SRC_DIR	This property lists the directory where process notes are stored. The default directory is <APPIAN_HOME>/_admin/process_notes/.

MAX_EXEC_ENGINE_LOAD_METRIC

Property	Description
server.conf.processcommon.MAX_EXEC_ENGINE_LOAD_METRIC	This metric limits the amount of memory that a single execution engine will use. On production systems, raise this setting to a value of 120 or higher.

Through a sampling technique, an approximation of the RAM utilized by a single execution engine is calculated as the Execution Engine Load Metric. The MAX_EXEC_ENGINE_LOAD_METRIC setting is intended to cap the RAM usage of the Execution Engine according to the calculated Load Metric. When the calculated metric value reaches 100% of the specified maximum, no new process can be started (on the affected execution engine) without raising the cap. It is also highly recommended that you archive your completed process instances.

Warn Nearing Load Metric Limit

Warnings are generated when the calculated value for engine load reaches 75% of the MAX_EXEC_ENGINE_LOAD_METRIC setting. If you receive a warning, you should contact Appian Technical support for assistance. This warning might indicate that you need to increase the amount of available RAM on the server or reevaluate your process design.

• The status script lists a warning when the calculated value for engine load reaches 75% of the MAX_EXEC_ENGINE_LOAD_METRIC setting.

• If the MAX_EXEC_ENGINE_LOAD_METRIC limit is reached, the status script states Engine [engine name] on [host] has a load metric of [load metric] and the configured limit is [MAX_EXEC_ENGINE_LOAD_METRIC]. New processes cannot be started on an execution engine where the calculated load metric limit reaches or exceeds the MAX_EXEC_ENGINE_LOAD_METRIC

On production systems, the maximum metric value should be raised from its default value of 40 to a value of 120 or higher. It can be further raised (above 120) according to the amount of RAM available to the execution engines. As a general rule of thumb, if you have installed more RAM than the minimum system requirement of 4GB you can raise the value for this metric by a number that equals the GB of additional RAM on your system multiplied by the number 60. The maximum setting for this metric on a 64 bit machine is 2145.

MAXIMUM_REPORT_MS

Property

Description

server.conf.processcommon.MAXIMUM_REPORT_MS

This property sets the maximum amount of time that can be taken by the server to process and return report data, in milliseconds. The most complex reports should only take 2000 milliseconds to generate. If you must raise this setting for a report, never set this parameter above 15000 milliseconds. This property can also be lowered to reduce the load on the Analytics engine. In all cases, reports that take longer than the defined number of milliseconds will not complete.

All custom replacement values (except for the MAXIMUM_REPORT_MS property) must be higher than the default value. Otherwise, application errors may occur.

Configuring checkpointing

Appian engines are real-time in-memory (RAM) databases that also persist all data (database and transaction log) in a file on disk. These database files have the extension .kdb. We refer to them as KDB files, which must be treated as a set. Each write transaction is applied immediately to the engine in memory and saved to the transaction log.

When a checkpoint completes, the engine state in memory is written to disk as a KDB file and the current point in the transaction log is marked to note the new starting point for replaying transactions. Each checkpoint writes out a new KDB file with a new number appended to the KDB file name. For example, the name of a personalization engine KDB file that has not been checkpointed is ag0.kdb, but after checkpointing there will be a new KDB file named ag1.kdb. KDB file numbers may increase by more than one for each checkpoint. Files with a higher number are guaranteed to have come after earlier numbered files. When a checkpoint occurs, the old KDB file is left unmodified but is compressed and moved to the services/data/archived/ directory. By default, the two most recent KDB files for each engine are kept. Any older versions are deleted to preserve disk space. The number of KDB files that are kept can be configured using the property serviceManager.checkpoint.archives.keep in the Appian CR configuration file. If the number of archived KDB files to keep is configured to fewer than two, the configured value will be ignored and two will be kept instead.

During a KDB checkpoint, a temporary *.writing file is created in the services/data/temporary/, which gets deleted when the checkpoint is completed. If the checkpoint fails for any reason, the *.writing file may remain on the file system. All pending transactions wait in the queue or timeout, depending on how checkpointing is configured.

While an engine is checkpointing, that engine is unavailable to service transactions from the application server and transactions wait in the queue until the checkpoint is completed or the transaction times out. If there are multiple instances of an engine, only one of them will become unavailable because of the checkpoint, leaving the remaining copies to service requests. If you see transactions timeout during checkpointing, Appian recommends adding more copies of the relevant engines.

For sites that only run one instance of each engine, Appian recommends checkpointing outside of regular business hours to avoid disruption of service. For sites that have multiple instances of each engine, Appian recommends keeping the default checkpoint scheduling configurations.

A proper shutdown of the engines automatically completes a checkpoint. An improper shutdown (such as an abrupt stop using the kill command, a power outage, or an OS shutdown) of the engines does not complete a checkpoint.

When an Appian engine starts up, it loads the KDB file into memory and applies any transactions from the transaction log that had not already been applied to that KDB file.

If there has been a long duration since the last checkpointing of the engines, a large number of transactions may need to be loaded upon start-up, which can lead to increased startup time.

The memory consumed by the engine is utilized both for storing data and for processing data.

Automatic engine restarts

For long-running systems, it's normal for cached data to accumulate in the engine over time. In order to keep engine execution lean and avoid this accumulation of stale data, engines automatically restart during checkpointing given the proper, safe conditions. These restarts will occur without any noticeable change in behavior or system outages. Automatic restarts occur on all highly available sites including those which are self-managed.

Manually creating a checkpoint

The checkpoint script can be executed manually whenever there is a need.

Configuring checkpointing frequency

Appian schedules checkpoints automatically based on the amount of time since the last checkpoint and the estimated amount of time it would take to replay the transactions since the last checkpoint.

To adjust the thresholds, set the following values in the Appian CR configuration file:

Threshold	Field	Default Value	Min Value	Max Value
Time since last successful checkpoint	serviceManager.checkpoint.automatic.boundary.time	22 hours	12 hours	30 hours
Estimated time to replay transaction log from last successful checkpoint	serviceManager.checkpoint.automatic.boundary.replay	20 minutes	2 minutes	30 hours

The time-based configurations in the table above should be specified in the format "number units." So "5 minutes" or "12 hours." If no units are specified the assumed unit is milliseconds.

A restart is required for changes to these properties to take effect.

While automatic checkpointing cannot be disabled, it is possible to configure these thresholds to avoid triggering checkpoints during business hours. Raise the values in the table above to their max value (30 hours) and run the checkpoint script at an off-peak time of day using a cron job or a scheduled task, which will reset the criteria the automatic checkpoint scheduler uses to trigger checkpoints.

Feedback