Changes between Initial Version and Version 1 of User Guide/Portal/Scheduler

Timestamp:

Mar 30, 2026, 5:53:59 PM (6 hours ago)

Author:

editor

Comment:

New: Scheduler sub-page

User Guide/Portal/Scheduler

@@ +1 @@
+[[Include(WikiToC)]]
+= Scheduler =
+
+The Scheduler is a calendar-based reservation system that gives you exclusive access to COSMOS/ORBIT testbed domains during your reserved time slots. Reservations are essential for running experiments — they guarantee that no other user can power on, image, or interact with nodes in your reserved domain during your time.
+
+Access the Scheduler from the '''Scheduler''' link in the portal sidebar.
+
+----
+
+== Calendar View ==
+
+The Scheduler displays a calendar showing all reservations across all testbed domains. You can customize the view using the controls at the top:
+
+'''View mode''' — switch between '''Day''' view (one day at a time, all domains visible) and '''Week''' view (seven days, scrollable). Day view is best for seeing all available domains at a glance; Week view is best for planning ahead.
+
+'''Time format''' — toggle between '''12h''' (AM/PM) and '''24h''' format using the button at the top. Your preference is saved in your browser and persists across sessions.
+
+'''Date navigation''' — use the left/right arrows to move forward and backward in time. The '''Today''' button jumps to the current date. You can also click the date display to open a date picker for jumping to a specific date.
+
+'''Clock bar''' — a reference bar at the top shows the current time in three zones: your local timezone, UTC, and COSMOS Eastern Time (US/Eastern). This helps when coordinating with collaborators in different time zones.
+
+'''Resources''' — testbed domains are listed vertically on the left side. Each row represents one domain (e.g., grid.orbit-lab.org, sb1.cosmos-lab.org). Time slots (30-minute intervals) are arranged horizontally. Hover over a domain name to see a tooltip with its description and location.
+
+Past time slots are grayed out and cannot be clicked. Only future slots can be reserved.
+
+[[Image(wiki:UserGuide/Portal:portal-scheduler.png, width=30%)]]
+
+----
+
+== Reservation Colors ==
+
+The Scheduler uses distinct colors to help you quickly identify reservation ownership and status at a glance:
+
+||= Color =||= Meaning =||
+|| '''Green''' || Your approved reservation — confirmed and ready to use. You will have full access to the testbed domain during this time. ||
+|| '''Purple''' || Your pending reservation — submitted, waiting for automatic or manual approval. ||
+|| '''Blue''' || Another user's approved reservation — this slot is taken. ||
+|| '''Yellow''' || Another user's pending reservation — not yet confirmed, you may compete for this slot. ||
+|| '''Red''' || Conflict — overlapping pending reservations from different users. The auto-approver will resolve this based on the fairness algorithm. ||
+|| '''Dark gray''' || Blackout period — the testbed is unavailable, typically for planned maintenance. ||
+|| '''Orange''' || Scheduled maintenance window — testbed may be partially available. ||
+
+----
+
+== Creating a Reservation == #Create
+
+To create a new reservation:
+
+1. '''Click an empty time slot''' on the calendar for the resource you want. The slot must be in the future (not grayed out) and not already occupied by another user's approved reservation.
+
+2. '''Configure the reservation''' in the dialog that appears:
+   * '''Start date and time''' — pre-filled based on where you clicked. Adjust using the date picker and time dropdown.
+   * '''End date and time''' — set when your experiment will end. The minimum and maximum durations vary by resource and are displayed in the dialog (for example, minimum 30 minutes, maximum 6 hours).
+   * '''Summary''' (optional) — a short description of your experiment. This is visible to administrators and helps with scheduling coordination.
+   * '''Invite users''' (optional) — search by name or username to add other users who should have SSH access to the testbed during your reservation. Invited users can log into the console server and access nodes as if they had made the reservation themselves.
+   * '''Group reservation''' (optional) — toggle this to grant access to all members of a selected organization. Useful for classroom exercises or team experiments.
+   * '''Recurrence''' (optional) — create a series of reservations that repeat on a weekly or monthly schedule. Set an end date for the series. Each occurrence is treated as an independent reservation for approval purposes.
+
+3. '''Click Submit''' to create the reservation.
+
+Your new reservation appears immediately on the calendar as '''pending''' (purple). It will progress to '''approved''' (green) based on the automatic approval schedule described below.
+
+=== Automatic Approval ===
+
+The Scheduler uses an automatic approval system that processes reservations at two checkpoints each day:
+
+* '''Early approval''' — reservations submitted before noon Eastern Time for the following day are approved at approximately 2:00 PM Eastern Time.
+* '''Just-in-time approval''' — all other reservations are approved at the moment their reserved time slot begins.
+
+This two-phase system ensures that (a) users who plan ahead know their reservation is confirmed by the afternoon before, and (b) last-minute reservations are still possible for available slots.
+
+If there are no conflicts, approval is automatic and requires no human intervention.
+
+----
+
+== Competing for a Slot == #Compete
+
+If another user has a '''pending''' reservation on a time slot you want:
+
+1. Click on their reservation (shown in yellow)
+2. Select '''Compete for this slot'''
+3. Your competing reservation is created with the same time range
+
+When multiple users compete for the same slot, the auto-approver resolves the conflict using a '''fairness algorithm'''. The algorithm considers:
+* How many hours of testbed time each user has consumed in the past two weeks
+* Users with fewer recent hours are given priority
+* This prevents any single user from monopolizing popular testbed resources
+
+'''Best practice:''' To ensure fair resolution, submit competing reservations at least 2 hours before the slot begins. Competitions submitted with less than 2 hours' notice may not be resolved before the slot starts.
+
+You '''cannot''' compete for slots that another user has already had '''approved'''. Only pending (yellow) reservations can be contested.
+
+----
+
+== Modifying or Canceling Reservations == #Modify
+
+Click on any of your reservations to view its details. You can:
+
+'''Edit''' — change the start time, end time, participants, or summary. Note that editing a reservation resets its status to '''pending''' and it must go through the approval process again. If you are making a minor time adjustment to an already-approved reservation, be aware that it will temporarily lose its approved status.
+
+'''Cancel''' — remove a single reservation. The time slot immediately becomes available for other users. Canceled reservations cannot be recovered.
+
+'''Delete Series''' — if the reservation is part of a recurring series, you can cancel all future occurrences at once while preserving past records.
+
+----
+
+== My Reservations == #MyReservations
+
+The '''My Reservations''' page (accessible from the sidebar under Scheduler) provides a consolidated view of all your reservations:
+
+* '''Usage summary''' — total reservation hours over the last 28 days, helping you track your utilization
+* '''Reservation table''' — a sortable list of all your upcoming and recent reservations showing the resource name, start/end time, duration, status, and any invited users
+* '''Quick cancel''' — each reservation row has a cancel button for immediate removal
+
+This page is particularly useful when you have multiple reservations across different domains and want to manage them all in one place.
+
+[[Image(wiki:UserGuide/Portal:portal-my-reservations.png, width=30%)]]
+
+----
+
+== Resource Information ==
+
+Each testbed domain has specific characteristics that affect your experiment:
+
+||= Resource =||= Nodes =||= Description =||= Max Duration =||
+|| grid.orbit-lab.org || ~400 || Main 400-node indoor grid || 2 hours ||
+|| sb1.orbit-lab.org || varies || General purpose sandbox || 2 hours ||
+|| sb2.orbit-lab.org || varies || General purpose sandbox || 2 hours ||
+|| sb3.orbit-lab.org || varies || USRP/GNURadio development || 4 hours ||
+|| sb4.orbit-lab.org || varies || RF Attenuator Matrix (topology control) || 2 hours ||
+|| sb9.orbit-lab.org || varies || OpenFlow/SDN development || 2 hours ||
+|| outdoor.orbit-lab.org || ~22 || Outdoor wireless network || 4 hours ||
+|| bed.cosmos-lab.org || varies || COSMOS Testbed (West Harlem, NYC) || 6 hours ||
+|| sb1.cosmos-lab.org || varies || COSMOS Sandbox 1 (NJ) || 6 hours ||
+|| sb2.cosmos-lab.org || varies || COSMOS Sandbox 2 (Columbia University) || 6 hours ||
+|| weeks.cosmos-lab.org || varies || Weeks Hall — Industry 4.0 setup (NJ) || 6 hours ||
+
+Minimum and maximum reservation durations are displayed when you create a reservation. If you need longer access for multi-day experiments, contact testbed support at `problems@cosmos-lab.org`.