Schedule of a resource

A branch has no opening hours. Each resource (see Resources) has its own schedule, and a visit is booked only into open time. A day with no open time is a day off.

A day consists of segments of two kinds: open (open for booking) and busy (taken without a booking, with a Note such as lunch or training, up to 60 characters). An open segment that touches or overlaps another open one merges with it. Busy time over busy time with a different note is refused.

Usual cycle

The usual cycle repeats while its days go on. A week is a cycle of seven days. The schedule of a resource lives on its card, in the section Masters, places and devices: in the Schedule block a person presses Set up schedule (later Change), and the window “Usual cycle” opens:

• Works from (today unless changed) and Until;
• Length of the cycle; for a cycle that is not seven days there is also a choice of which day of the cycle the “Works from” date is (“27 November is Day 1 · working”); a usual week doesn’t ask, the weekday is visible by the date;
• the segments of each day (Day 1, Day 2, and so on).

Copy from… takes them from another resource of the branch. The schedules that end within 14 days or are not set at all are listed by Schedule is ending in the panel of the section: the list shows until which day each schedule goes, and it is extended on the card.

The cycle does not act by itself: days are laid out at once, up to the date in Until, and at most a year ahead. Show what changes lists the days that change before anything is saved. Past days are never laid out again, and days changed by hand stay as they are unless they are marked for overwriting in the preview.

Lay out until… extends the schedule to a new date by the same cycle, and it needs a cycle to exist. The schedule shows the last laid-out day, and after it nobody can be booked.

A day and a segment

• Press a day in the week of the card: the window of the day changes a whole day, including a past one. The day becomes "changed by hand", and a new cycle does not touch it until it is marked. Make it a day off empties it at once, without a second window, and Undo stays in the notice.
• Add time and Remove work on one segment; the Calendar grid has Open time and Block without booking.

Time is not taken from under a visit. A change that would leave a booked or confirmed visit outside open time is refused, with the number of such visits; move or cancel them first. A visit that took place keeps its time open: it was worked.

Clock changes and time zone

The cycle is written in the local time of the branch. When clocks go forward, a time that does not exist is skipped: a segment edge falls on the moment of the change, and a segment wholly inside the gap is dropped. When clocks go back, the first occurrence of a repeated time is taken. The day of the change is 23 or 25 hours long.

When the time zone of a branch changes, segments from today onward keep the same local time in the new zone and the past does not move. The change is refused while visits ahead would fall outside the schedules. A deactivated resource loses its schedule ahead.

Who can do it

Schedules are a branch-level right of the Administrator role; the Accountant role does not see them. A role limited to own sees and changes only the schedule of the resource the person works as.

Tools and refusals

• talemo_get_schedule reads one resource for a period: every day is working, day_off (no open time) or not_scheduled (no schedule, so it cannot be booked), with its open and busy times and notes, whether it was changed by hand, the usual cycle and the day it is laid out to. talemo_list_schedules reads every resource of a branch and shows up to which day each schedule is laid out.
• A cycle and a day are set in the wall-clock time of the branch, like 10:00; a single time is an instant in RFC 3339. Intervals are half-open: time until 10:00 does not overlap time from 10:00.
• talemo_set_usual_schedule sets the usual cycle (cycle_days, a week is 7, with times and, only when needed, anchor_day) and lays it out from effective_from to until, at most a year ahead. For a week leave anchor_day out: day 1 of times is then a Monday and day 7 a Sunday, so Tuesday to Saturday is days 2 to 6; a named anchor_day is the first day of the cycle and shifts every day with it, and for a cycle that is not a week, left out, it is the day the cycle starts. The first schedule of a place in a branch is when all the services of the branch start to need a place (see Services, prices and currency). Leave both out for a schedule that starts today and runs the whole year: a master set up on a request without a start works from today, and a later effective_from is only for a person who asked for the schedule to start later, because the days before it have no schedule and nobody can be booked on them. Days changed by hand stay unless listed in overwrite, and past days are never laid out again. talemo_apply_usual_schedule moves the last laid-out day: later lays the cycle out to it, earlier takes the cycle days after it away. Without a cycle it is refused with status 409, code schedule.no_cycle.
• In the calendar a resource whose schedule the role may not see comes with days empty (null), not with days of not_scheduled: that is “schedule not shown”, and it says nothing about whether the schedule exists.
• The cycle never extends by itself. After the last laid-out day the resource has no schedule and cannot be booked, so tell the person the date.
• talemo_set_schedule_day sets one day as a whole, a past day too: all its open and busy times, and no times means a day off. The day becomes changed by hand, and a new cycle keeps it.
• talemo_add_schedule_time adds open time or busy time with a note; open time merges with open time it touches. talemo_remove_schedule_time removes one by time_id. Busy time over busy time with another note is refused with status 409, code schedule.overlap.
• Time is not taken from under a visit. A change that would leave a booked or confirmed visit outside open time is refused with status 409, code schedule.has_bookings, params.count for booked or confirmed visits and params.done for visits that took place. Move or cancel the first ones; the time of the done ones stays open. dry_run shows the days that change and those bookings.
• The tools that change a lot at once (talemo_set_usual_schedule, talemo_apply_usual_schedule) are called with dry_run first, and the real call goes after the person has seen it and said yes.
• Booking at a time that is not open is one movement: open the time with talemo_add_schedule_time, find and book; if the booking is refused, remove the time you added.