Calendar Widget Node Configuration Guide

The Calendar Widget Node displays scheduled events in a dashboard interface and allows workflows to match current time to the schedule. It outputs the start and end time of the matching event—or a fallback value

What Is a Calendar Widget?

The Calendar Widget Node acts as a passive scheduler. Users define a set of known events (e.g., shifts, breaks), each with start/end times and precedence. At runtime, the widget checks the current time against these events and outputs details of the active event with the highest priority.

This enables workflows to:

Log contextual time-of-day activities (e.g., "Night Shift", "Lunch Break")
Adjust logic or display content based on the current event
Enrich payloads with scheduling metadata

It’s ideal for time-based control, auditing, monitoring, or interface personalization based on current schedule state.

Step-by-Step: How to Configure the Calendar Widget Node

Add the node to your workflow
- Drag the Calendar Widget Node from the Controls section onto the canvas.
- Connect the widget to the data source
  - Connect the Bar Chart Widget Node to the upstream node that sends the relevant data.
  - The source node must emit a JSON payload containing the field specified in the Y-Axis Field.
  - Without this connection, the chart will not receive or display any data.
Open configuration
- Double-click the node to access its settings window.
Configure Widget Basics
- Widget Name: Set a clear name (e.g., Shift Calendar, Operating Window).
- Widget Subtitle (optional): Add a description below the title.
- Show UID / Label Name: Choose whether to show the device label or UID on the dashboard.
- Widget Header: Optionally show or hide the calendar’s header.
Configure Output Fields
- Output JSON Key: The main field in the workflow payload that will hold the event name.
- Output JSON Key for START time: Field name to store the event’s start time.
- Output JSON Key for END time: Field name to store the event’s end time.
- Value for Output JSON Key if No Event is Found: A fallback value (e.g., "none" or "inactive") when no event matches the current time.
Define Schedules
- Add one or more schedule rows using the + button:
  - Schedule Type Display Name: What appears in the UI (e.g., Morning Shift)
  - Schedule Type Value: What is output in the JSON (e.g., "shift_1")
  - Schedule Type Precedence: A numeric value to resolve overlaps (1 = highest priority)
⚠ Only one event will be returned per time match. Precedence values must be unique where overlap is possible.
Add Tooltip (optional)
- Enable tooltip support and enter Tooltip Text to provide hover guidance.
Group and Display Widgets
- Select Label: Choose a device label for grouping (e.g., “Team”, “Zone”).
- Grouped Display Mode:
  - No Grouping: One widget per device
  - Group by Label Value: One widget per label value
  - Group by Label Name: One widget for all devices under the selected label
- Number of Widgets to Display: Optionally limit widget count when grouping.

🔧 Configuration Fields

General Settings

Field	Requirement	Description
Widget Name*	Required	Title of the calendar widget on the dashboard.
Widget Subtitle	Optional	Supporting text under the title.
Show UID / Label Name	Optional	Toggle to display associated UID or label name.
Widget Header	Optional	Show or hide the built-in calendar header interface.

Output Behavior

Field	Requirement	Description
Output JSON Key*	Required	Field name for the active event’s value.
Output JSON Key for START time*	Required	Field name for the matched event's start time.
Output JSON Key for END time*	Required	Field name for the matched event's end time.
Value if No Event is Found	Required	Fallback value when no scheduled event is active.

Schedule Definitions

Field	Requirement	Description
Schedule Type Display Name*	Required	Label shown to the user (e.g., `Break Time`).
Schedule Type Value*	Required	Value passed in the JSON payload when this event is matched.
Schedule Type Precedence*	Required	Numeric priority (1 = highest); resolves overlapping events.

You must define at least one schedule entry to activate the calendar functionality. Add more using Add Value.

Tooltip Settings

Field	Requirement	Description
Enable Tooltip	Optional	Show help text when hovering over the widget.
Tooltip Text	Optional	Description shown in the tooltip popup.

Grouping & Display Logic

Field	Requirement	Description
Select Label	Mandatory (if grouping)	Choose a label to filter or group the widget.
Grouped Display Mode	Mandatory	- No Grouping: One widget per device - Group by Label Value: One widget per label value - Group by Label Name: One widget for all devices
Number of Widgets to Display	Optional	Limit the number of calendar widgets shown.

Use Cases

Logging shift schedules or break times
Enriching workflow data with current operating periods
Auditing and historical analysis with schedule context
Displaying the currently active schedule to dashboard users

Best Practices

Assign clear precedence values to prevent overlaps from causing unexpected behavior.
Use fallback values (like "none" or 0) to simplify downstream logic.
Add tooltips to clarify what the widget does and what its output values mean.
Group calendar widgets by Zone, Team, or Process Line for organized layout.

Frequently Asked Questions (FAQ)

Q: Does the calendar trigger events in real time?

A: No. The Calendar Widget Node is passive—it only adds matched event data to the payload when triggered by workflow logic.

Q: What happens if two events occur at the same time?

A: The event with the lowest precedence value will be returned. Only one event is emitted.

Q: What if no event is active at the current time?

A: The node will output the default fallback value you configured.

Q: Can I track multiple overlapping events?

A: No. Only the event with the highest precedence is returned. If others are important, track them separately using logic in downstream nodes.