Configure Events

• Ad-Hoc events
  • Configuration
  • Parameters
  • Configuration
• Periodic Events
  • Parameters
  • Configuration
  • Cron Schedule
    • Timezone Configuration
      • Event-Specific Timezone Control
      • Example
    • Common Examples
• Runtime Configuration Changes
  • Changing Initialization Configuration at Runtime
  • Changing Event Configuration at Runtime
  • Limitation
  • Blocking Events
  • Blocking/Unblocking based on configuration
  • Blocking/Unblocking based on callback
  • Unsubscribe Handler
• Delete Processed Events
• Priority of Events

Ad-Hoc events

Ad-hoc events are one-time events that are either processed directly or with a defined delay. The purpose of such events is to process asynchronous loads, such as sending email notifications or compressing uploaded attachments, where you don’t want the user to wait until the process is finished. These events have various configurations to determine how they should be processed.

Configuration

The configuration YAML file is where all the required information regarding event processing should be maintained.

Parameters

Configuration

Below are two examples of ad-hoc event configurations. The first example demonstrates a simple configuration, while the second example showcases the full complexity of the configuration.

events:
  - type: Notification
    subType: Email
    impl: ./srv/util/mail-service/EventQueueNotificationProcessor
    load: 1
    parallelEventProcessing: 5

  - type: Attachment
    subType: Compress
    impl: ./srv/common/process/EventQueueClosingTaskSync
    load: 3
    parallelEventProcessing: 2
    selectMaxChunkSize: 5
    checkForNextChunk: true
    transactionMode: alwaysRollback
    retryAttempts: 1

Periodic Events

Periodic events in the event-queue framework are events processed at pre-defined intervals, similar to cron jobs. This feature is particularly useful for regular business processes such as checking if a task is overdue. Just like ad-hoc events, these events are managed efficiently across all available application instances, ensuring no single instance is overloaded.

Parameters

Configuration

The following demonstrates a configuration for a periodic event with a default load of 1 and an interval of 30 seconds. This means the periodic event is scheduled to execute every 30 seconds, if the provided capacity is sufficient on any application instance. If capacity is unavailable, the execution is delayed, but subsequent attempts will aim to adhere to the originally planned schedule plus the defined interval.

periodicEvents:
  - type: HealthCheck
    subType: DB
    impl: ./test/asset/EventQueueHealthCheckDb
    load: 1
    transactionMode: alwaysRollback
    interval: 30

Cron Schedule

Periodic events in the Event-Queue framework can now be scheduled using cron expressions for greater precision and flexibility. When a cron expression is used (with the cron and utc parameters defined), the interval parameter cannot be specified, and vice versa. Cron jobs in the framework support granular scheduling down to seconds ( e.g., * * * * * *), allowing for highly specific timing control. However, to prevent system overload, the minimum allowed interval between two executions is 10 seconds.

The event’s next execution time is calculated only after the current event has been executed. This approach ensures that the system dynamically adapts to real-world conditions but also means that the execution might not strictly follow the cron schedule. For example, if the CAP application is not running or if there is a high load on the system causing delays, the event might not execute exactly as scheduled.

Timezone Configuration

The Event-Queue framework provides flexibility in handling timezones for periodic events. A central setting, cronTimezone, can be configured to define the global timezone used when calculating the cron schedule for all events. This allows events to execute according to specific local time zones rather than Coordinated Universal Time (UTC), which is useful for applications operating across different regions.

Event-Specific Timezone Control

In addition to the global cronTimezone setting, each event can independently control its timezone behavior using two parameters:

1. useCronTimezone: This parameter controls whether the global cronTimezone should be applied to an event. If useCronTimezone is set to true (the default), the event will use the global cronTimezone. If set to false, the event will ignore the global setting and fall back to its own configuration.

2. UTC: If no timezone is set, the UTC parameter on an event level determines whether the event should run in Coordinated Universal Time (UTC) or in the server’s local time. When UTC is set to true, the event will execute based on UTC time.

Example

If cronTimezone is set to Europe/Berlin and useCronTimezone is true for an event, a cron expression like 0 8 * * * will trigger at 8:00 AM in Berlin time. If useCronTimezone is set to false, the event will either use its own timezone (if defined) or revert to the UTC setting to decide whether it should follow UTC time or the server’s local time.

Common Examples

The following table provides examples of cron expressions that can be used to schedule periodic events. These expressions offer flexibility in specifying when and how often events should occur, ranging from precise intervals to specific days or months. Please note that the minimum interval allowed between two executions is 10 seconds, ensuring that the system maintains stability and avoids overloading.

Runtime Configuration Changes

In certain scenarios, it may be necessary to change configurations during runtime. The event-queue has two main configuration sections: one for all ad-hoc and periodic events (explained on this wiki page), and another for the initialization configuration. However, not all parameters can be modified at runtime. To identify which parameters can be altered, please refer to the corresponding parameter tables in the documentation. Note that any configuration change needs to be implemented for every application instance. For instance, if a configuration change is made via an HTTP-Handler, the change will only be reflected in the instance that processed the HTTP request.

Changing Initialization Configuration at Runtime

The initialization configuration can be changed by setting the value of the corresponding setter parameter from the config class instance. Here is an example:

const { config } = require("@cap-js-community/event-queue");

config.runInterval = 5 * 60 * 1000; // 5 minutes

Changing Event Configuration at Runtime

To change the configuration of a specific event, you can refer to the example below:

const { config } = require("@cap-js-community/event-queue");

const eventConfig = config.getEventConfig("HealthCheck", "DB");
eventConfig.load = 5;

Limitation

The current implementation of config does not persistently store runtime configuration changes. This means that e.g. the block/unblock list is only available until the next restart of the application. If you want this information to be persistent, it is recommended to use the callback API. This allows for accessing persistent information.

Blocking Events

In certain scenarios, it may be necessary to prevent specific events from executing. This could be due to various reasons such as:

• An event causing the application to crash
• A specific event leading to performance issues
• Other reasons specific to a project

You can block events for all or just for certain tenants. The example below demonstrates how this can be accomplished.

Blocking/Unblocking based on configuration

const { config } = require("@cap-js-community/event-queue");

// Block type: HealthCheck and subType: DB for tenant 123
const isPeriodicEvent = true;
config.blockEvent("HealthCheck", "DB", isPeriodicEvent, 123);

// Block type: HealthCheck and subType: DB for all tenants
config.blockEvent("HealthCheck", "DB", isPeriodicEvent);

// Unblock works the same way - unblock for all tenants
config.unblockPeriodicEvent("HealthCheck", "DB", isPeriodicEvent);

Tenant-specific blockings/unblockings take precedence over the all-tenant blocking. This means if a certain event is blocked for all tenants, it can still be unblocked for one or more tenants.

Blocking/Unblocking based on callback

For greater flexibility, the decision to block an event can be determined based on the result of a callback. The example below shows how to register the callback.

const { config } = require("@cap-js-community/event-queue");

config.isEventBlockedCb = async (type, subType, isPeriodicEvent, tenant) => {
  // Perform custom check and return true or false
};

Unsubscribe Handler

The event-queue listens for unsubscribe events from cds-mtxs and stops processing events for an unsubscribed tenant. Additionally, the event-queue federates the unsubscribe event to all application instances bound to the same Redis instance. To react to unsubscribe events across all application instances, the event-queue allows the registration of callbacks that are triggered when a tenant is unsubscribed. Follow the code example below:

const { config } = require("@cap-js-community/event-queue");

config.attachUnsubscribeHandler(async (tenantId) => {
  try {
    cds.log("server").info("received unsubscribe event via event-queue", { tenantId });
    await cds.db.disconnect(tenantId);
  } catch (err) {
    logger.error("disconnect db failed!", { tenantId }, err);
  }
});

This ensures that your application can handle tenant unsubscription events consistently, even in a distributed environment.

Delete Processed Events

The parameter deleteFinishedEventsAfterDays defines the number of days after which processed events are automatically deleted from the system, regardless of their processing status. Here, “processed” refers to events that have been processed, whether successfully or unsuccessfully. If this parameter is set to 0, it indicates that processed events will not be deleted from the database table.

From a technical standpoint, the event queue utilizes its own periodic event to conduct a daily check for events that are eligible for deletion.

Priority of Events

The assignment of priorities to events determines the order in which different event types are processed. The available priority levels are as follows:

• Low
• Medium (Default)
• High
• Very High

To ensure that event types with low priorities are not left unprocessed during periods of high system load, an automatic adjustment is made for event types in the queue for more than three minutes. The pre-defined rule is: if an event type remains in the queue for more than three minutes, its priority is temporarily bumped up by one level (i.e., from Low to Medium).