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):
|If set to true the System Events Job is enabled.|
(once every 5 seconds)
|Specifies how often dotCMS will check for new incoming System Events in the queue.|
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:
|If set to true, the Delete Old System Events job is enabled and will be run.|
(every 3 days, starting
the first day of each month)
|Specifies how often to run the Delete Old System Events job.|
|Integer||31||Specifies the age (in days) of events that will be deleted by the Delete Old System Events job.|
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 (
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:
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.
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
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)
To change to the secure websocket protocol (
- Change the
dotcms.websocket.protocolproperty to wss.
- 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.
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
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
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 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
- System event data is returned as a string.
Each system event is specified as one of 3 types, based upon who the event is visible to:
|GLOBAL||Visible by all users (even non-authenticated users).|
|ROLE||Visible only to users who are assigned to specific Roles.|
|USER||Visible only to specific users.|
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.
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.
For more information on the websocket protocol, please see the Websocket protocol specification (RFC 6455).