# Events

An event is a channel-scoped time window that groups the ad breaks belonging to one scheduled occurrence, such as a live game, a show, or a tournament. It gives you a single handle for the breaks around that occurrence: an event lists the breaks that fall inside its window. Breaks are not tied to an event by id, so creating, moving, or deleting an event never changes a break.

Events also anchor the [break punching](https://docs-preview.optiview.dolby.com/pr-894/ads/concepts/breaks.md#break-punching) workflow: ahead of a live occurrence you prepare a break without a start time, and during the broadcast you fire it at the exact moment.

## Event identity

Every event has an `id` that is unique within its channel. The `id` is optional when creating an event: if you omit it, OptiView Ads generates one for you. When you supply your own, we recommend using a UUID. For a human-readable label, use the `name` property instead — it is shown in the dashboard.

## Time window

An event is defined by a `startDate` and an `endDate`, both UTC ISO 8601 timestamps. `startDate` must be before `endDate`, and the events of a channel cannot overlap.

The window is how an event finds its breaks: `GET /channels/{channelId}/events/{eventId}/breaks` returns the breaks of the channel whose start falls inside the window — `startDate` inclusive, `endDate` exclusive. The window is not enforced on breaks: a break is never validated against an event, and a break that starts inside the window may run past the event's `endDate`.

## Breaks under an event

Breaks carry no reference to an event. An event resolves its breaks from its time window:

* A break scheduled on the timeline belongs to the event whose window contains its start. On **wallclock** channels this is the break's `start`; on **PTS** channels, where a break has no wall-clock start, the time the break was created is used instead.
* A [cued break](https://docs-preview.optiview.dolby.com/pr-894/ads/concepts/breaks.md#cued-breaks) has no start yet. While it waits to be punched, it is listed under the event that is in progress at the time of your request. Once punched, it belongs to the event whose window contains its start.
* [Event-triggered breaks](https://docs-preview.optiview.dolby.com/pr-894/ads/concepts/breaks.md#event-based-triggers) — pre-roll, pause, and post-roll — have no position on the timeline and are listed under every event of the channel.

Because the lookup is purely time-based, a break can exist on the channel without falling under any event, and a break automatically shows up under a new event whose window covers its start.

> **Deleting an event keeps its breaks**
>
> Deleting an event removes only the event. Its breaks stay on the channel and keep being served to players; they simply no longer appear under that event.

## Templates for an event

[Templates](https://docs-preview.optiview.dolby.com/pr-894/ads/concepts/templates.md) can be linked to one or more events through their `eventIds`, so a reusable break preset can be surfaced for quick scheduling under those events. Instead of creating your breaks before the event, prepare templates ahead of time and schedule breaks from them during the event.

## Break punching during an event

For a live occurrence you usually do not know the exact break times in advance, but you want the break fully prepared so it can fire instantly. This is what [break punching](https://docs-preview.optiview.dolby.com/pr-894/ads/concepts/breaks.md#break-punching) is for:

1. Create the event with a window that covers the occurrence, for example kickoff through the final whistle.
2. Ahead of the occurrence, create the [templates](https://docs-preview.optiview.dolby.com/pr-894/ads/concepts/templates.md) describing the breaks you want to run.
3. During the event, create a cued break from a template, without a `start`. OptiView Ads prepares it (including any ad decisioning) and it waits in the `CUED` state.
4. Punch the break whenever it needs to go — for example, at half-time. Its start is set and it is announced to players right away.
5. Repeat for the next break: cue it from a template, then punch it at the right moment.

A channel holds only one cued break at a time, so punch the current cued break before cueing the next one. Do not delete a cued break unless you have cued the wrong one.

Because a punch uses the current time as the break's start, punch a cued break while the event is in progress: its start then falls inside the event's window, so the break is listed under the event.

## Related resources

| Resource                                                                                  | Relationship                                                                                        |
| ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| [Channels](https://docs-preview.optiview.dolby.com/pr-894/ads/concepts/channels.md)       | The parent of an event. An event always belongs to one channel.                                     |
| [Breaks](https://docs-preview.optiview.dolby.com/pr-894/ads/concepts/breaks.md)           | Resolved from the event's window: the breaks that start inside it, plus all event-triggered breaks. |
| [Templates](https://docs-preview.optiview.dolby.com/pr-894/ads/concepts/templates.md)     | Reusable break presets that can be linked to events for quick scheduling.                           |
| [Integrations](https://docs-preview.optiview.dolby.com/pr-894/ads/integrations/google.md) | Channel-level delivery integrations, such as Server-Side Ad Insertion with Google DAI.              |