System Events

dotCMS System Events (such as Notifications) use a websocket connection to provide a low latency event notification. This both ensures high performance and low overhead in the dotCMS backend, and allows you to implement JavaScript or web applications to receive and process dotCMS notifications.

Event Management

System events are automatically managed by two jobs which run periodically on the dotCMS server. The System Events Job sends event notifications to subscribers, and the Delete Old System Events Job removes old system events from the system events table to maintain performance and limit storage space needs.

The System Events Job

The System Events Job monitors the System Events message queue for events generated by dotCMS processes or custom services added via static or dynamic plugins. When the System Events Job runs, notifications will be generated for any events which require them.

The following properties control the execution of the system events job (and thus the frequency of notifications from the system):

Special Note: Even if the ENABLE_SYSTEM_EVENTS is changed to false, system events will still be stored in the system events table. However, the cron job will be turned off and long polling will be used to retrieve the events from the table. To learn how to configure the long polling retrieval interval, please see Websockets vs. Long Polling, below.

The Delete Old System Events Job

System events are enabled by default and each event triggered in the system is saved to the system events table. Over time, this table will grow - the more system events triggered, the faster the table will grow. When the table is large, it may impact performance.

You can enable the Delete Old System Events job to automatically delete old system events from the table. This job runs periodically, and deletes all system events older than a specified number of days, helping to minimize the system events table size, which both improves performance and avoids storing unnecessary information.

The following properties control the Delete Old System Events job:

Cron Expressions

Both the System Events Job and the Delete Old System Events job are run periodically based on the cron expressions defined in the appropriate properties (SYSTEM_EVENTS_CRON_EXPRESSION and DELETE_OLD_SYSTEM_EVENTS_CRON_EXPRESSION, respectively).

Frequency and Performance

By default, the System Events Job runs ever 5 seconds, and the Delete Old System Events Job runs every 3 days. You can increase the frequency of these jobs by changing the cron expressions in the properties. However it's important to understand that running either of these jobs can cause an impact on performance, especially on large sites with a great deal of activity. Therefore it's important to balance the need for updates with site performance capacity and site requirements.

For more information on how to configure cron expressions, please see the Quartz cron documentation.

Websockets vs. Long Polling

By default dotCMS is configured to use websockets. However, if the system property is set to false, then long polling will be used to retrieve system events from the system events table. Long polling will also be used if the website browser version being used is too old or does not support the websocket (ws/wss) protocol.

By default, long polling system event requests are checked every 15 seconds (15000 milliseconds), but this time interval can be changed by adding the following property and changing the time in milliseconds:

system.events.longpolling.defaultmillis=15000

As long as the `ENABLE_SYSTEM_EVENTS' is not changed to false, and the user's browser supports the Websocket protocol (ws/wss), then websockets will be used to retrieve system events from the system events table. To maintain open dotCMS system events communications, use the following documentation to configure a websocket connection.

Configuration

By default, the URL used to access the system events websocket is ws://server.domain.com:port/api/ws/v1/system/events. This URL is constructed from 3 different strings: The websocket protocol (ws://), the base URL (server.domain.com:port), and the REST API Endpoint (/api/ws/v1/system/events). Each of these 3 strings is configurable via properties in the dotmarketing-config.properties file.

Note: It is strongly recommended that all changes to the dotmarketing-config.properties file be made through a properties file extension.

The following configuration properties determine the values used to construct the websocket URL:

dotcms.websocket.protocol=ws
dotcms.websocket.baseurl=localhost:8082
websocket.systemevents.endpoint=/api/ws/v1/system/events

Websocket Protocol

The websocket specification supports both a standard (ws:) and secure (wss:) protocol. dotCMS supports both of these standard and secure websocket protocols. The default websocket protocol is the standard (non-secure) ws protocol.

To change to the secure websocket protocol (wss):

1. Change the dotcms.websocket.protocol property to wss.
2. Ensure the wss protocol is configured on your application/proxy server.
   • The Tomcat server that ships with the dotCMS distribution supports the wss protocol.
   • To enable support of the wss protocol in any other application server, ensure that your application server is also configured to support HTTPS.

Base URL

By default, the base URL (and port) used to construct the websocket URL is the URL and port of the dotCMS host being accessed. For example, if you wish to access the system events for host which is accessible on server1.domain.com:8082, then the websocket URL for that host is ws://server1.domain1.com:8082/api/ws/v1/system/events.

However you can explicitly specify a base URL to use for all your websocket connections on the same dotCMS host. If you set the value of the dotcms.websocket.baseurl property to a specific host and port, the websocket URL for all hosts on your dotCMS instance will be constructed using that base URL, instead of the base URL of the host being accessed.

REST API Endpoint

The default endpoint used to construct the websocket URL is /api/ws/v1/system/events. You may change the endpoint by modifying the websocket.systemevents.endpoint property.

Note: The default endpoint conforms to the standard REST API Endpoint format used by dotCMS. It is recommended that you do not change the end point unless you have a specific need (such as a limitation imposed by another application that must access the websocket).

Connecting and Processing Events

The following Javascript code example demonstrates how to connect to the system events websocket and how to process received events:

<script type="text/javascript">
    var wsocket;

    function connect() {         
        wsocket = new WebSocket("ws://server.domain.com/api/ws/v1/system/events");
        wsocket.onmessage = onMessage;          
    }

    function onMessage(evt) {             
        document.getElementById("info").innerHTML+=evt.data + "<br />";
    }

    window.addEventListener("load", connect, false);
</script>

Note:

• The above example subscribes to system events as an unauthenticated user.
  • See below for information about how to subscribe as a specific user.
• The system events websocket uses the default SOAP protocol, so no protocol parameter needs to be passed to when instantiating the WebSocket().
• System event data is returned as a string.

Event Types

Each system event is specified as one of 3 types, based upon who the event is visible to:

Connecting as an Unauthenticated User

By default (when you use only the standard websocket URL), the system events websocket connection is initiated as an unauthenticated user.

wsocket = new WebSocket("ws://server.domain.com/api/ws/v1/system/events");

When you initiate the connection this way, you will only receive GLOBAL system events.

User Validation

Websockets only works when you are logged into the system. Websocket requests take the user id set in the session, so all requests include user validation by default, and are simply denied automatically if the user session information does not accompany the request.

References

For more information on the websocket protocol, please see the Websocket protocol specification (RFC 6455).