Maintenance calendar

Who it’s for

The Maintenance calendar is for maintenance planners, shift leads and service technicians who plan work on equipment that already reports to ThingsBoard. They want to see on one screen what is due this month, what slipped past its date, and who is doing what, without opening a separate CMMS. The question they would type is “what maintenance is overdue on my machines?”

What it does

A planner drags across Wednesday to Friday on the month view and fills in Line 2 planned shutdown, type Preventive, priority High, assignee Maintenance crew. The dialog saves the event on the Line 2 asset itself, and the calendar draws it as one bar across the three days. On Friday evening nobody has marked it done, so the bar turns red and the Overdue count above the calendar goes up by one.

• Shows a month of maintenance across every device or asset in the data source, with the day’s work drawn on each date. Click a day number, or the +2 more link, to open that day hour by hour.
• Plans work of any length: a one-hour check, a three-hour repair, or a shutdown that runs for several days.
• Repeats an event every week, month, three months or year, with an optional end date. Each occurrence keeps its own status, so marking this week’s safety walk done leaves next week’s planned.
• Tracks every event as Planned, In progress or Done, and marks it Overdue by itself once its time has passed without being marked done. The legend beside the title counts all four for the month on screen.
• Saves each event as an attribute on its own entity, so the plan travels with the equipment and anything that reads attributes can read it.
• Opens the add and edit dialog as an ordinary widget action. Add a field, remove one or restyle the form on the widget’s Actions tab, and the calendar keeps whatever the dialog saves.
• Is a planner, not a work order system: it sends no notifications, keeps no history of who changed what, and does not lock an event while someone else is editing it.

How to set up

Data keys

The widget needs one attribute that holds the events. Use the same key name on every entity the widget covers. maintenanceEvents reads well.

• Events attribute: Attribute. A JSON list of the entity’s events, read and written by the widget. The key does not have to exist yet, and usually will not. Type the name into the data key field instead of picking it, and the first event you save creates it. An entity without the attribute simply has no events.
• Several entities: add a datasource per device or asset, or one alias that resolves to many. All their events share one calendar, and the dialog asks which equipment a new event belongs to.
• No key at all: the calendar shows Add the attribute the events are stored in as the data key and saves nothing.

Actions

Adding and editing go through two widget actions. Both ship with a ready Event dialog custom action, so the calendar works as soon as it is dropped on a dashboard.

• On add event: fired by the New event button, by a click on a day, and by dragging across several days or several hours. The dialog opens with those dates already filled in.
• On event click: fired by a click on an event. The dialog opens in edit mode with Delete, or Delete this date and Delete series for a repeating event.
• Remove an action to take that ability away. With no On add event action, the New event button disappears and clicking a day does nothing.

Calendar

• Save to: Server attributes by default. Where the events attribute is written. Shared attributes makes the plan visible to the device as well.

Event types

• Event types: six by default, Inspection, Preventive, Repair, Calibration, Replacement and Cleaning. The types offered in the dialog, each with a Name, an Icon and an Icon color. The icon marks the event on the calendar. An event keeps its type name even if you later remove the row.

How to customize

• To start the week on Sunday: set First day of week to Sunday, from Monday.
• To hide the status chips and the event count beside the title: turn off Show legend, on by default.
• To stop events moving when someone drags them: turn off Drag to reschedule, on by default. With it on, a single event can be dragged to another day or stretched to change its length, and the change is saved at once. Repeating events always change through the dialog.
• To match your status colors: set Overdue color, red by default, In progress color, orange by default, and Done color, green by default. Planned events and the buttons take the platform’s primary color, so they follow your theme.
• To change the dialog itself: open the widget’s Actions tab and edit the Event dialog action’s HTML, CSS or JavaScript. Any extra field it puts on the event is stored with it and kept on later saves.

Tips

• Give the widget enough height for a month view: about nine grid rows. On a small card the calendar switches to a compact layout and shortens +2 more to +2.
• Point one widget at a whole site through a single alias. Every machine’s plan then appears together, while each event is still stored on its own machine.
• Use Shared attributes when a device or gateway should know about upcoming maintenance, for example to hold back automatic restarts during a planned shutdown.
• A rule chain can write the same attribute. A JSON list of { "title", "date", "endDate", "time", "endTime", "type" } objects appears on the calendar like events added by hand.
• Turn off Drag to reschedule on dashboards shown on a wall display or a shared touch screen, where a stray touch could move an event.