Schedules
Last updated
Last updated
A is a representation of a recurrence rule, compatible with the , designed to be extrapolated by the data user into individual occurrences.
A , by contrast, must not be extrapolated by the data user, and is for information only.
Schedule
to a feedA must be included in the SessionSeries
feed for systems that display occurrences of a sessions directly from a recurrence rule (as opposed to first materialising them into a database).
ScheduledSession
sIt is recommended that a ScheduledSession
feed be published alongside any SessionSeries
feed that contains Schedule
s, and that this ScheduledSession
feed also includes remainingAttendeeCapacity
. If implementing the Open Booking API, such a complementary feed is required.
When ScheduledSession
s are included in a feed or subEvent
, they must not include all occurrences that are generated from the recurrence rule, and instead must only include those events that either:
Have bookings associated (i.e. where remainingAttendeeCapacity
< maximumAttendeeCapacity
)
Are an exception to the recurrence rule defined in the Schedule
.
Have any other properties that differ from those defined in SessionSeries
.
Such events would need to have been materialised in a database within the booking system already, so under no circumstances should new occurrence records be generated for the sole purpose of outputting them to an OpenActive ScheduledSession
s feed.
This constraint is necessary to prevent recurrence rules from creating a high volume of redundant data in its ScheduledSession
feed. For example: if a SessionSeries
has a recurrence rule for a weekly event with an endDate
in 2050, only the ScheduledSession
s that have been booked at least once or have been manually edited would appear in the ScheduledSession
feed.
When such ScheduledSession
s are included, the Schedule
must also include an idTemplate
, such as the below, which matches the pattern of the @id
of the ScheduledSession
s (noting the startDate
placeholder must use a string format of YYYY-MM-DDThh:mm:ssZ
(e.g. 1997-07-16T19:20:00Z
):
A urlTemplate
may also be included in the Schedule
using the same startDate
placeholder.
Also note that if a Schedule
is updated, it must include exceptDates
for any overlaps with any explicitly defined occurrences created from previous Schedule
s, as they might have been rescheduled based on a previous @id
.
Schedule
found in a feedGenerate all occurrences from a Schedule
in the future, taking into account the exceptDate
property.
Take the scheduledEventType
, property and use it for the @type
property of each occurrence.
For the avoidance of doubt: the startDate
and startTime
of the Schedule
are in "local time" based on the scheduleTimezone
.
Use the duration
of the Schedule
to calculate the endDate
of each occurrence.
Render the calculated startDate
and endDate
for each occurrence to UTC using a string format of YYYY-MM-DDThh:mm:ssZ
(e.g. 1997-07-16T19:20:00Z
) for placeholder replacement.
Take the idTemplate
property (if provided) and substitute the startDate
placeholder with the calculated string value of startDate
(and do the same with endDate
). Use the resulting string as the value of the @id
property for the occurrence.
Take the urlTemplate
property (if provided) and substitute the startDate
placeholder with the calculated string value of startDate
(and do the same with endDate
). Use the resulting string as the value of the url
property for the occurrence.
To account for any changes in the Schedule
since the last time it was updated, store the generated occurrences as follows:
Upsert all generated occurrences, marking them with the modified
RPDE timestamp associated with the Schedule
. Ensure that any explicitly defined occurrences that may have been generated from a previous run of Step 3 (below) are not overwritten by this step.
Delete all generated occurrences that do not have an older modified RPDE timestamp associated with the Schedule.
Ensure the generated occurrences are hidden by any matching explicitly defined occurrences (e.g.ScheduledSession
s found in a subEvent
or ScheduledSession
feed), using the explicitly defined occurrence in its entirety based on its @id
.
Extract from SessionSeries
feed:
Extract from ScheduledSession
feed:
Illustration of resulting opportunities presented to the end user:
Note that if a single ScheduledSession
that was previously generated by a Schedule
is rescheduled to a different start time, its original @id
must be retained (which contains the original start time), to ensure that it still hides the same generated occurrence (see below), and to ensure that are still triggered.
In order to process a together with complimentary ScheduledSession
s, the data user must do the following:
Use an library to calculate the startDate
of the occurrences based on the contents of the Schedule
. DTSTART
must be determined by using the startDate
, startTime
, and scheduleTimezone
of the Schedule
together, for example: