Skip to content

Volunteer planning proposals

Volunteer coordinators review proposed assignments at /vrijwilligers/voorstellen. Generating a proposal leaves shifts unchanged and sends no member assignment mail. Only publication creates assignments and queues their existing confirmation flow.

VolunteerPlanner schedules rondo_volunteer_planner for Wednesday at 09:00 in the WordPress timezone. It creates at most one normal proposal per ISO week. Voorstel vernieuwen / gaten aanvullen combines open drafts and partial proposals into one current proposal, retaining valid pending choices and manually open slots. It drops filled, deleted or changed duties and rechecks candidates before retaining them. Retained choices reserve time and quota before the planner fills new gaps. Old snapshots remain intact, read as closed and expose superseded_by; the new snapshot records supersedes. An interrupted publication must finish before refresh. The selection starts now and ends on the Sunday four calendar weeks ahead: Monday of the current week plus five weeks is the exclusive cutoff.

The coordinator receives a link to a non-empty proposal. An hourly rondo_volunteer_planner_reminders check sends one reminder when an open proposal is at least two days old. rondo_volunteer_planner_email stores the recipient; when that option is absent it falls back to the general mailing overview address. An explicitly empty value disables proposal notices. Configure both addresses on the volunteer mailing card. Notice state is reserved before sending and records accepted, failed or uncertain; it prevents automatic duplicate sends after a timeout.

Member cancellation schedules rondo_volunteer_planner_repair after one minute to refresh the current reviewable proposal with replacement choices. The person who declined that shift is excluded from automatic selection for it. Theme deactivation clears all three planner hooks.

The planner uses the existing season obligation calculator and exemption policy. It subtracts completed, pending and already proposed work from each eligible unit. Family candidates are responsible adults, excluding the children who trigger the family duty. A playing parent’s personal duty takes precedence over family work. Candidates need volunteer eligibility, a contactable primary email and access to every person in their obligation unit when a logged-in manager generates the plan.

Finite-capacity, published future shifts with status open or vol are considered. Unlimited shifts produce an unresolved row asking for a capacity first. IVA-required shifts come first, then earlier dates. Pending proposals reserve both quota and time across open plans, within the season of the proposed shift.

Volunteer coordinators use Vrijwilligers → Uitsluitlijst to exclude a person from automatic planning until they lift the exclusion. Adding a person requires a reason. Other eligible family members can still be proposed. The volunteer obligation remains in force. Existing assignments stay in place, and the person can still sign up under the usual rules. The planner rechecks exclusions when it generates, edits or publishes a proposal, including for candidates already in a draft.

For July–December shifts, a person must have no completed, scheduled or proposed duty in that sports season. A scheduled January–June duty also counts. Each person’s count includes both their own and family duties. It includes cancelled shifts that earned credit and excludes no-shows. Completed work still counts when a shift has an invalid end time. Administrative duty credits count as completed workload in the season half of the credited date.

From January, candidates with fewer duties come first. At equal personal load, an IVA-required shift prefers someone with valid IVA, unless that shift waives IVA. Next come the season-half target, a lower fulfilled share and a stable weekly tie-break. Editing and publishing use these same rules.

Within the best fairness tier, the planner prefers pairs sharing a current player team. Parents can match through any eligible child’s team; two adults from the same family obligation cannot form a pair. It first matches an unpaired existing assignee or retained candidate, then looks ahead for two teammates when space allows. Completed pairs do not pull in a third teammate. Eligibility, availability and quotas still take precedence; otherwise normal ranking fills the place.

The planner excludes candidates under 18 on the shift’s local start date if the shift ends after 22:00 in the WordPress timezone. A shift ending at 22:00 is allowed. A shift ending after midnight exceeds the cutoff on its start date. The age restriction lifts on the person’s eighteenth birthday. The planner applies this rule only when it can determine age from a valid birth date.

VOG and required-commissie checks reuse ShiftSignupEligibility. Missing IVA allows a proposal, but publication requires the coordinator’s explicit approval below. Members still need IVA to claim an IVA-required shift themselves. Existing assignments and proposals block overlapping intervals. For a current player team, PlannerAvailability also checks the active training schedule and team match feed:

SourceBlocked time
TrainingTraining duration plus 30 minutes before and after
Match with known time and durationMatch duration plus two hours before and after
Match with unknown time or durationThe whole match day
Provisional matchdayIts recorded date interval

Missing current player-team data for age groups 17 and older, missing season/team training, and missing, stale or unmatched current-season match feeds block selection. Cancelled matches and dated training cancellations for that team do not block. Parents without a current player-team role do not inherit their children’s team schedule. Unfilled rows show issues and aggregate blocking reasons; missing information never becomes assumed availability.

Bar proposals keep the same duty type, even when the chosen person still needs IVA. Such rows return iva_missing: true and show IVA nog nodig voor deze bardienst. Before publishing selected assignments with this warning, the coordinator must check the confirmation for assignments without approved IVA proof. The publish button stays disabled until that confirmation is checked. The assignment remains a bardienst.

Confirmation applies to the current proposal, revision, selected candidates and flagged rows. Changing that scope requires fresh approval. Saving a candidate change or switching proposals also clears the confirmation. Refreshing an older draft checks its proposed bar-to-luik changes again, using the shift’s actual duty type.

Coordinators can choose a currently valid replacement candidate or leave a pending row open with person_id: 0. Candidate reads and publication rebuild eligibility. Editing, publishing and closing require the current revision; stale revisions return HTTP 409. A 15-minute option lock serializes planner mutations.

Select assignments with Deze kandidaat indelen. Candidates for different places on the same shift can be published separately. All proposed candidates start selected. Deselected candidates and their reservations stay in the proposal for later publication. Selected legacy conversions still require accept_conversions: true. Refresh the proposal to recalculate them.

Publication saves the exact row selection in publish_row_indices before making assignments. It attempts up to ten selected assignments per request. The selection stays fixed while publication is in progress, and the planner blocks editing, closing and regenerating during that time. After an interruption, resume with the saved selection and current revision.

Each row rechecks the shift snapshot, current obligation, VOG, required pool, availability, capacity and status inside the existing shift write lock. Successful rows become explicit assigned duties and queue assignment mail. Invalid rows remain pending with an issue; successful rows stay published. publish_more tells the client to continue using the returned revision. The interface performs those follow-up requests itself.

Phases are draft, partial, published and closed; row states are pending, publishing and published. Stored plan provenance allows an interrupted commit to finish its confirmation queue without assigning or queuing the person twice. Closing a proposal releases its unpublished reservations while retaining published assignments. Explicit duties can be cancelled until 21 days before the start, with no 30-minute signup grace inside that deadline.

Proposals are private rondo_shift_plan posts. _planner_data stores rows, revision, phase, time range, notice outcomes and publication progress, including the saved row indices and shift IDs. Open plans are derived from snapshot phase and replacement links; _planner_week prevents a duplicate normal weekly generation. Per-shift _shift_plan_id_{person_id} records provenance. There are no custom tables or generic WordPress REST routes for this post type. Its capability map uses do_not_allow with meta-cap mapping disabled; access goes through the dedicated controller and its existing person-visibility checks.

All paths below are relative to /wp-json/rondo/v1. They require manage_options or vrijwilligers and return Cache-Control: private, no-store.

MethodPathContract
GET/volunteer-plansLatest 30 visible summaries, next_at and notification_email
POST/volunteer-plansRefresh one current proposal, retaining valid open choices
GET/volunteer-plans/{id}Revision, phase, rows (including iva_missing), coverage, notice outcomes, publish_more, publish_row_indices, publish_shift_ids and superseded_by
GET/volunteer-plans/{id}/rows/{index}/candidatesCurrent candidates: person_id, name, opaque unit, remaining
PUT/volunteer-plans/{id}/rows/{index}Required integer revision and nonnegative integer person_id
POST/volunteer-plans/{id}/publishRequired revision; optional row_indices or shift_ids; accepted_iva_rows defaults to []; boolean accept_conversions, default false
POST/volunteer-plans/{id}/closeRequired revision; retain existing assignments

Send row_indices as a nonempty array of zero-based index values from the proposal response. Existing clients can use shift_ids, a nonempty array of positive shift IDs that selects every row for those shifts. Sending both fields or an invalid selection returns HTTP 400. Sending neither starts with all rows or resumes the saved scope. A continuation that changes the saved scope returns HTTP 409.

During publication, publish_row_indices gives the exact saved selection and publish_shift_ids gives its shift IDs. For a legacy batch with only saved shift IDs, the planner derives the selection from those shifts. Both fields return null after the batch finishes, even if unselected rows remain pending.

Use the same zero-based indices in accepted_iva_rows. Include every selected pending row whose iva_missing is true. The server checks IVA status before assigning any selected row. Missing approval returns HTTP 409 volunteer_plan_invalid. If the warning is absent, refresh the proposal before confirming.

Send the approved indices with each continuation request alongside its current revision. The assignment write lock checks IVA approval again. Deselected rows do not require approval. This approval is separate from accept_conversions for older bar-to-luik proposals.

Proposal errors use volunteer_plan_invalid, normally HTTP 409; missing plans return 404 and unreadable stored data returns 500. Inaccessible people block a detail response with 403; listing omits plans that cannot be viewed in full.

VolunteerPlannerTest.php covers season limits, IVA ranking and warnings, missing or incorrect approval indices, duty types and old bar-to-luik proposals. It also covers private drafts, quotas, revisions, changed requirements, merged drafts and team pairing. Publication tests cover selecting one candidate on a shared shift, rejecting invalid indices and resuming the exact selection across batches. Further checks cover recovery, notices and cancellation. VolunteerPlannerAvailabilityTest.php covers training/match margins, unknown times, stale feeds, missing data and overlaps. ShiftAssignmentByCoordinatorTest.php covers the assigned-duty cancellation deadline.