Background Processes

Engine can have several processes running in the background performing different tasks, like processing event messages or forwarding xAPI statements. Normally, it's not necessary to change their behavior, but it is possible to deactivate individual processors or customize their rest times. For reference, the table below contains a complete list of processor names, descriptions, and legacy settings:

Note: Both the RegistrationPostbackQueueProcessor and ImportPostbackQueueProcessor processors are from Engine's previous postback system. For more information, see the Webhooks page.

To modify one or more processors, BackgroundProcessors is a system-level setting that takes an array of serialized BackgroundProcessorConfigurationList objects. Keep in mind that you must stringify the JSON to send it as part of a SetApplicationConfiguration request.

An example with one BackgroundProcessorConfigurationList item is as following:

[{
    "instance": "EngineInstance4",
    "processors": [
        {
            "processor": "EventMessageProcessor",
            "activated": true,
            "restTime": "600000"
        }
    ]
}]

• instance - [required] The application instance name. Use the ApplicationInstanceId setting to configure an application instance name.
• processors - [required] The list of different processors to configure for an instance.
  • processor - [required] The background processor name. See the table above for the complete list.
  • activated - Setting this to false deactivates the processor.
  • restTime - In milliseconds, the amount of time to rest in between process runs.

Customizing Processors on All Instances

To apply processor configuration to all available Engine instances, simply set the instance property value to "All". This avoids having to create the same list item for each instance. Similarly, if the environment contains just one Engine instance, it isn't really necessary to identify it with ApplicationInstanceId, so setting instance to "All" would also be appropriate in this situation.

For example, the configuration below sets a restTime value of "3600000" milliseconds (or 1 hour) for the EventMessageProcessor and xApiTokenDeletionProcessor processors for all available Engine instances:

[
    {
        "instance": "All",
        "processors": [
            {
                "processor": "EventMessageProcessor",
                "restTime": "3600000"
            },
            {
                "processor": "xApiTokenDeletionProcessor",
                "restTime": "3600000"
            }
        ]
    }
]

Customizing Processors for a Specific Application Instance

Running multiple Engine instances in a load balanced environment could introduce some unique use cases, and you may want the Engine instances executing their background processes differently from one another.

First, each instance must be uniquely named with with the ApplicationInstanceId setting. These are the identifers used for the instance property in the BackgroundProcessors configuration.

Although it's possible to hard code each instance's ApplicationInstanceId setting in its respective RusticiEngineSettings.propertiesconfig file, using an environment variable for the setting value is recommended. Using an environment variable is especially critical if you instead use SetApplicationConfiguration to configure ApplicationInstanceId. Engine saves configuration settings set through the REST API in its system database. Consequently, if you use SetApplicationConfiguration to set ApplicationInstanceId without using an environment variable, then each application instance will have the same identifier at runtime!

For the next example, assume you have three different application instances identified as Node1, Node2, and Node3, and you want Node1 exclusively dedicated to processing event messages and Node3 exclusively dedicated to processing xAPI pipes. The configuration below deactivates the EventMessageProcessor on Node2 and Node3 and deactivates xApiStatementPipeProcessor on Node1 and Node2.

[
    {
        "instance": "Node1",
        "processors": [
            {
                "processor": "xApiStatementPipeProcessor",
                "activated": false
            }
        ]
    },
    {
        "instance": "Node2",
        "processors": [
            {
                "processor": "EventMessageProcessor",
                "activated": false
            },
            {
                "processor": "xApiStatementPipeProcessor",
                "activated": false
            }
        ]
    },
    {
        "instance": "Node3",
        "processors": [
            {
                "processor": "EventMessageProcessor",
                "activated": false
            }
        ]
    }
]

After this, the EventMessageProcessor process will only run on Node1, and xApiStatementPipeProcessor will only run on Node3.

Legacy Settings

Some processors perform tasks that were previously enabled with dedicated, system-level settings (see table above). Processors with such a legacy setting are inactive by default. Although these settings will be removed in a future Engine release, a processor can still be activated by changing its legacy setting's default boolean value. However, the activated property in the BackgroundProcessors configuration will override the processor's legacy setting.

Launch History Expiration

LaunchHistoryExpirationProcessor does represent a special case. This processor is on by default, but it relies on two tenant-level settings, ShouldExpireLaunchHistory and ExpireLaunchHistoryAfterDays. Although LaunchHistoryExpirationProcessor can only be activated and deactivated through the BackgroundProcessorssetting, ShouldExpireLaunchHistory must also be enabled for the processor to actually delete expired launch history records.

Additionally, if you have accumulated a lot of data in Engine's ScormLaunchHistory table, LaunchHistoryExpirationProcessor could execute several long-running DELETE statements the first time it runs (one for each tenant). This could potentially lead to locks on the table and disrupt registration launches. Consequently, if you plan on enabling ShouldExpireLaunchHistory, it may be preferrable to manually purge the table before beforehand. If you're unsure of the right approach, feel free to reach out to Rustici's support.