Calendar Services

Calendar Services

The clockwork integration provides services for managing calendar events programmatically. These services allow you to retrieve, create, update, and delete events in your calendars.

Available Services

clockwork.delete_event

Delete a single event from the calendar.

Parameters:

• calendar_id (required): The entity ID of the calendar (e.g., calendar.my_calendar)
• event_id (required): The unique ID of the event to delete
• recurrence_id (optional): For recurring events, the specific instance to delete
• recurrence_range (optional): How to delete recurring events:
  • THIS: Delete only this instance
  • THIS_AND_FUTURE: Delete this and all future instances

Example:

service: clockwork.delete_event
data:
  calendar_id: calendar.my_calendar
  event_id: "event_uid_12345"

Deleting a Recurring Event Instance:

service: clockwork.delete_event
data:
  calendar_id: calendar.my_calendar
  event_id: "recurring_event_uid"
  recurrence_id: "20240226T100000Z"
  recurrence_range: "THIS"

---

clockwork.update_event ⭐ NEW

Update an existing event in the calendar.

Parameters:

• calendar_id (required): The entity ID of the calendar
• event_id (required): The unique ID of the event to update
• event (required): Object containing the event data to update. Can include:
  • summary: Event title
  • description: Event description
  • location: Event location
  • start: Start datetime
  • end: End datetime
  • rrule: Recurrence rule for repeating events
• recurrence_id (optional): For recurring events, the specific instance to update
• recurrence_range (optional): How to update recurring events:
  • THIS: Update only this instance
  • THIS_AND_FUTURE: Update this and all future instances

Example - Update Event Title and Description:

service: clockwork.update_event
data:
  calendar_id: calendar.my_calendar
  event_id: "event_uid_12345"
  event:
    summary: "Updated Meeting Title"
    description: "New description with important details"
    location: "Conference Room A"

Example - Update Event Time:

service: clockwork.update_event
data:
  calendar_id: calendar.my_calendar
  event_id: "event_uid_12345"
  event:
    start: "2024-02-26 14:00:00"
    end: "2024-02-26 15:00:00"

Example - Update Recurring Event Instance:

service: clockwork.update_event
data:
  calendar_id: calendar.my_calendar
  event_id: "recurring_event_uid"
  recurrence_id: "20240226T100000Z"
  recurrence_range: "THIS"
  event:
    summary: "Rescheduled Meeting"

---

clockwork.delete_events_in_range

Delete all events within a specified date range.

Parameters:

• calendar_id (required): The entity ID of the calendar
• start_date (required): Start date (e.g., 2024-02-26)
• end_date (required): End date (e.g., 2024-02-28)

Note: This service deletes all events that fall within the specified range, including partial overlaps.

Example:

service: clockwork.delete_events_in_range
data:
  calendar_id: calendar.my_calendar
  start_date: "2024-02-26"
  end_date: "2024-02-28"

---

Usage in Automations

You can use these services in automations to manage calendar events dynamically:

Update Event on Condition

alias: Update Meeting Location
trigger:
  platform: state
  entity_id: sensor.meeting_room
action:
  service: clockwork.update_event
  data:
    calendar_id: calendar.work
    event_id: "meeting_uid"
    event:
      location: "{{ states('sensor.meeting_room') }}"

Clean Up Old Events

alias: Delete Past Events
trigger:
  platform: time
  at: "00:00:00"
action:
  service: clockwork.delete_events_in_range
  data:
    calendar_id: calendar.my_calendar
    start_date: "{{ (now() - timedelta(days=30)).strftime('%Y-%m-%d') }}"
    end_date: "{{ (now() - timedelta(days=1)).strftime('%Y-%m-%d') }}"

---

Notes

• Timezone Handling: All datetime values are automatically converted to your Home Assistant timezone
• Event Features: Not all calendar entities support all operations. The service will error if an operation is not supported by the calendar
• Recurring Events: Use recurrence_id and recurrence_range carefully to target specific instances of recurring events
• Event IDs: Event IDs (UIDs) are unique identifiers assigned by the calendar provider