Maintenance Events

Maintenance events schedule maintenance periods for a set of data sources or data points. Events raised by those sources and points while the period is active are suppressed: depending on the configured behavior they are dropped, automatically acknowledged, or logged without running their event handlers. This keeps planned work such as a controller firmware update or a sensor swap from generating a flood of alarms and notifications.

The maintenance event itself raises an event when it starts, and that event returns to normal when the maintenance period ends. Maintenance events are usually scheduled, but a manual maintenance event can also be started and stopped by hand.

The module is provided by the maintenanceEvents module and is managed from Events > Maintenance Events in the main navigation menu.

Creating a Maintenance Event

1. Open Maintenance Events and click Add maintenance event. To edit an existing event, click its description in the maintenance events list.
2. Fill in the details, schedule, behavior and maintenance sections described below.
3. Save. The status display and manual controls only appear once the event has been saved.

Details

Setting	Description
XID	Unique identifier used by import/export. Any value unique among maintenance events, up to 50 characters.
Name	Optional. Used as the event's description throughout the system; otherwise an automatically generated description is used.
Alarm level	Whether the maintenance event raises an alarm while active, and its severity. See Alarms and Alarm Management.
Enabled	A disabled maintenance event does not run and cannot be started manually. Useful to keep an event without letting it run.
Show banner	Shows a banner at the top of the web UI while the event is active. Only users with read permission for the maintenance event see it.

Schedule

The Schedule type sets the base period of the event: hourly, daily, weekly, monthly, yearly, a cron pattern, or manual. An hourly schedule runs once every hour; to run twice a day, define two daily events, one per time. A cron pattern can run several times within a period.

Active and inactive time fields depend on the schedule type and follow the Gregorian calendar. Active and inactive times may straddle the period: an hourly schedule can become active at minute 55 and inactive at minute 05, for ten minutes of maintenance each hour. Cron patterns that activate several times before deactivating are allowed but rarely useful.

Behavior

Choose how events from the selected sources and points are treated while the maintenance period is active:

• Drop events — events are discarded entirely. They are neither logged nor processed. This takes precedence over the other two options.
• Auto-acknowledge events — events are logged and acknowledged automatically. An optional Auto-acknowledge message is recorded with the acknowledgement.
• Suppress event handlers — events are logged but no event handlers run, so no notifications or other actions occur.

Changed in Mango 5.5

Before Mango 5.5.0, events during a maintenance period were always auto-acknowledged with their handlers suppressed. Starting in 5.5.0 the behavior is configurable with the three options above.

Maintenance

The Maintenance type selects which points the event applies to:

• Static — a fixed set of data sources and data points chosen when the event is configured.
• Watch list — every point in the chosen watch list, resolved dynamically each time the event becomes active. A data source cannot be selected in this mode.

Changed in Mango 5.7.6

In Mango 5.7.5 and earlier, a watch list maintenance event resolved its points as superadmin, so it could affect far more points than the user who set it up could see. Starting in 5.7.6 the event has a Roles used to resolve watch list points setting and affects only the points from the watch list that those roles can read. Existing events are assigned the superadmin role on upgrade, so they keep working as before; new events default to the roles of the user who creates them. Saving reports an error when the selected roles cannot read the watch list, or when the watch list is tag based.

Anyone who can edit the watch list controls which points the event affects, so assign roles for watch lists whose editors you trust. See Watch Lists for how watch lists are built and shared.

Status and Manual Control

After saving, the event's current status is shown at the top of the page. An active event shows as Running.

Only manual maintenance events can be started and stopped by hand, using the toggle switch. A manual event stays active until it is stopped manually or its Timeout period elapses.

Start Time

When activating a manual maintenance event you can set a Start time, so the event is considered to have started at that moment rather than when you clicked. The start time:

• Is only available when activating, not when stopping.
• Cannot be in the future.
• Is sent to the server as UTC.
• Does not retroactively acknowledge or otherwise affect events that already occurred. It only records when the maintenance period began.

If no start time is entered, the current time is used.

Modifying Point Values from a Maintenance Period

Modify point values deletes or overwrites logged point values for the time a maintenance event was active, for example to remove readings taken while a sensor was disconnected. Select the event, set the value to apply to every affected point, and run it. The results list each data point and the number of modifications made.

caution

Deleted values cannot be recovered. Once you delete the values from a maintenance period there is nothing left to modify.

Related Pages

• Alarms and Alarm Management — Alarm levels and acknowledgement
• Event Handlers — The actions that maintenance events suppress
• Watch Lists — Building the watch lists that a watch list maintenance event uses
• Advanced Scheduler — Recurring schedules for other automation