Skip to main content

Single-Server Mode

In the single-server mode, a single instance of the Workflow Engine (or Workflow Server) works with a single database. Multiple instances can be launched at the same time, it will not lead to errors, but such a system will work inefficiently due to the competition between instances. If you need horizontal scaling, use the multi-server mode.

Configuring Workflow Engine

When initializing WorkflowRuntime in the single-server mode, there are two things to be noted.

var workflowRuntime = new WorkflowRuntime()

First, the parameterless constructor - WorkflowRuntime() - is used here. The single-server runtime cannot have a customized runtime identifier.

After calling .AsSingleServer(), the runtime switches to the single-server mode, which primarily affects the system timer operation and the recovery procedure after a failure. On calling, this parameterless method sets the default settings (the settings are described below). Options with customized settings are also available:

  • .AsSingleServer(new SingleServerSettings() {TimerPeriod = 500}) - settings can be customized, part of them can be changed.
  • workflowRuntime.AsSingleServer(new DefaultSingleServerSettingsSource(workflowRuntime)) - a source that stores the settings in the global parameters table can be used.

With custom initialization settings, the single-server mode can look as follows:

var workflowRuntime = new WorkflowRuntime()
.AsSingleServer(new SingleServerSettings() {TimerPeriod = 500});

For timers to work in the single-server mode, the workflowRuntime.Start() method should be called.

When shutting down the server, it is highly advisable to call workflowRuntime.Shutdown() or workflowRuntime.ShutdownAsync(); it will correctly disable the runtime API and stop its timers. Then, if you want to start the server anew, call workflowRuntime.Start() again.

Configuring Workflow Server

Configuring Workflow Server is much easier. For the Workflow Server instance to work in the single-server mode, the config either should not contain the IsMultiServer setting, or it should be set to false. Therefore, this mode is default for Workflow Server.

"IsMultiServer": false


The rest of single-server settings can be changed in the Runtimes tab in the Dashboard page. There you can see the list of settings and their values.

Single-server Settings

The single-server settings can be customized and passed to the WorkflowRuntime constructor for Workflow Engine, or to the Runtimes tab in the Dashboard page for Workflow Server. The following settings are available:

  • int TimerPeriod = 1000 - period for the system timer to start work with process timers, in milliseconds.
  • int TimerMaxSequentialFailCount = 5 - if an unhandled exception is detected during the system timer operation, the timer will turn off after the exception occurs successively the number of times specified by this setting.
  • bool DoNotRestoreOnStart = false - when launched in the single-server mode, by default, the recovery process after a failure launches after the restart. You can turn it off using this setting.
  • int TimerBatchSize = 100 - the system timer works with a batch of process timers; it is the size of such a batch.
  • int MaxDegreeOfParallelismMultiplier = 1 - the server tries to process timers and recovery processes in parallel, the level of parallelism is defined as the number of available processor cores multiplied by this value.

Features of Timers

Immediately after the start, the server finds the database and reads the timers scheduled to work at the given time. The timers are processed in parallel, in batches of the size specified by the TimerBatchSize parameter. The processing keeps on going until all of the timers, scheduled to work at the current moment, end. Then, the system timer is set to restart after the TimerPeriod interval. The timers are processed in a separate thread, thus, calls to other methods are not blocked.

Service Timer and Recovery Procedure

If the server stops incorrectly, there can appear processes stuck in the Running status (the statuses of processes are described here). The Running status will prevent further manipulation of the process, therefore, it must be reset. The reset procedure starts once at the server startup. It can be disabled by setting DoNotRestoreOnStart.

The recovery procedure and its customization are described here.