diff --git a/.gitignore b/.gitignore index c251a36eb1..cc3fd7d70e 100644 --- a/.gitignore +++ b/.gitignore @@ -6,3 +6,5 @@ apps/backend/node_modules apps/frontend/src/generated apps/backend/generated .DS_Store +documentation/.venv +documentation/site/ diff --git a/documentation/docs/assets/images/scheduler_calendar.png b/documentation/docs/assets/images/scheduler_calendar.png new file mode 100644 index 0000000000..dcca911813 Binary files /dev/null and b/documentation/docs/assets/images/scheduler_calendar.png differ diff --git a/documentation/docs/assets/images/scheduler_filters.png b/documentation/docs/assets/images/scheduler_filters.png new file mode 100644 index 0000000000..7cfb83fb3e Binary files /dev/null and b/documentation/docs/assets/images/scheduler_filters.png differ diff --git a/documentation/docs/assets/images/scheduler_menu.png b/documentation/docs/assets/images/scheduler_menu.png new file mode 100644 index 0000000000..1635d3e4ae Binary files /dev/null and b/documentation/docs/assets/images/scheduler_menu.png differ diff --git a/documentation/docs/assets/images/scheduler_new_event.png b/documentation/docs/assets/images/scheduler_new_event.png new file mode 100644 index 0000000000..d2cd924fc3 Binary files /dev/null and b/documentation/docs/assets/images/scheduler_new_event.png differ diff --git a/documentation/docs/assets/images/scheduler_plan.png b/documentation/docs/assets/images/scheduler_plan.png new file mode 100644 index 0000000000..cf02b33554 Binary files /dev/null and b/documentation/docs/assets/images/scheduler_plan.png differ diff --git a/documentation/docs/assets/images/scheduler_plan_down.png b/documentation/docs/assets/images/scheduler_plan_down.png new file mode 100644 index 0000000000..e0b2ba6d2c Binary files /dev/null and b/documentation/docs/assets/images/scheduler_plan_down.png differ diff --git a/documentation/docs/assets/images/scheduler_plan_drag.png b/documentation/docs/assets/images/scheduler_plan_drag.png new file mode 100644 index 0000000000..cd52e9d4ca Binary files /dev/null and b/documentation/docs/assets/images/scheduler_plan_drag.png differ diff --git a/documentation/docs/assets/images/scheduler_planned.png b/documentation/docs/assets/images/scheduler_planned.png new file mode 100644 index 0000000000..d2ee47a983 Binary files /dev/null and b/documentation/docs/assets/images/scheduler_planned.png differ diff --git a/documentation/docs/assets/images/scheduler_pre_allocate.png b/documentation/docs/assets/images/scheduler_pre_allocate.png new file mode 100644 index 0000000000..8afc62d466 Binary files /dev/null and b/documentation/docs/assets/images/scheduler_pre_allocate.png differ diff --git a/documentation/docs/assets/images/scheduler_pre_status.png b/documentation/docs/assets/images/scheduler_pre_status.png new file mode 100644 index 0000000000..b44ac7a6ce Binary files /dev/null and b/documentation/docs/assets/images/scheduler_pre_status.png differ diff --git a/documentation/docs/assets/images/scheduler_view_calendar.png b/documentation/docs/assets/images/scheduler_view_calendar.png new file mode 100644 index 0000000000..1d55b9c6c0 Binary files /dev/null and b/documentation/docs/assets/images/scheduler_view_calendar.png differ diff --git a/documentation/docs/assets/images/scheduler_view_table.png b/documentation/docs/assets/images/scheduler_view_table.png new file mode 100644 index 0000000000..3bd87703f0 Binary files /dev/null and b/documentation/docs/assets/images/scheduler_view_table.png differ diff --git a/documentation/docs/assets/images/scheduler_view_timeline.png b/documentation/docs/assets/images/scheduler_view_timeline.png new file mode 100644 index 0000000000..15558edc93 Binary files /dev/null and b/documentation/docs/assets/images/scheduler_view_timeline.png differ diff --git a/documentation/docs/assets/images/scheduler_wf.png b/documentation/docs/assets/images/scheduler_wf.png new file mode 100644 index 0000000000..3de30d3aa5 Binary files /dev/null and b/documentation/docs/assets/images/scheduler_wf.png differ diff --git a/documentation/docs/assets/images/scheduler_wf_rabbit.png b/documentation/docs/assets/images/scheduler_wf_rabbit.png new file mode 100644 index 0000000000..ef14cf59a1 Binary files /dev/null and b/documentation/docs/assets/images/scheduler_wf_rabbit.png differ diff --git a/documentation/docs/assets/images/scheduler_wf_status.png b/documentation/docs/assets/images/scheduler_wf_status.png new file mode 100644 index 0000000000..463810a9be Binary files /dev/null and b/documentation/docs/assets/images/scheduler_wf_status.png differ diff --git a/documentation/docs/stylesheets/extra.css b/documentation/docs/stylesheets/extra.css new file mode 100644 index 0000000000..43590dbd55 --- /dev/null +++ b/documentation/docs/stylesheets/extra.css @@ -0,0 +1,3 @@ +img { + box-shadow: 0 4px 8px rgba(0, 0, 0, 0.1); +} diff --git a/documentation/docs/user-guide/scheduler.md b/documentation/docs/user-guide/scheduler.md new file mode 100644 index 0000000000..b8e192893d --- /dev/null +++ b/documentation/docs/user-guide/scheduler.md @@ -0,0 +1,155 @@ +# Scheduler :material-calendar-month: + +--- + +## What is the Scheduler? + +The Scheduler helps Instrument Scientists plan and manage experiment time on instruments and equipment. + +With the calendar interface, they can: + +- Create, view, organize, and adjust scheduled time slots (also called experiments) +- Filter by instrument, equipment, or local contact for efficient planning + +This ensures clear visibility of upcoming work and streamlined allocation of beam time. + +--- + +## Accessing the Scheduler Interface + +The scheduling service is not available by default within the core User Office Application. Instead, it runs as a separate microservice. As a dedicated application, the User Office Scheduler has its own URL, typically different from the User Office Core URL. The exact URL depends on the infrastructure setup. + +--- + +## Prerequisites + +### System Requirements + +- Docker-enabled environment + +### Essential Configuration + +- The scheduling service must be deployed and activated to allow access. +- Users must have appropriate permissions as Instrument Scientists or administrators (User Officer) to access and modify scheduling data. + +### Scheduling Proposals + +- Not all proposals show up in the Scheduler. A proposal becomes eligible for scheduling only when it enters a specific status (done via User Office Core). You can define this status using the **UPSERT_PROPOSAL_BOOKING_TRIGGER_STATUSES** environment variable for the scheduler service (e.g. SCHEDULING) + Example: + +``` +UPSERT_PROPOSAL_BOOKING_TRIGGER_STATUSES="SCHEDULING" + +``` + +Hint: Use comma to add more than one status + +``` +UPSERT_PROPOSAL_BOOKING_TRIGGER_STATUSES="SCHEDULING, ALLOCATED" + +``` + +In the example above, proposals in **SCHEDULING** status will appear in the planning sidebar, and administrators can assign time slots (experiments) accordingly. There are two ways to set a proposal to the **SCHEDULING** status: + +1. **Through Workflow**: Configure the workflow to automatically transition proposals to **SCHEDULING** status based on predefined criteria. For more details on configuring the **SCHEDULING** status, refer to the [Creating Workflow guide](../user-guide/user-officer/creating_workflow.md). +2. **Manual Status Change**: The User Officer can manually change the status of a proposal to **SCHEDULING** within the User Office Core application. + +- Proposals need to be **Accepted** by the User Officer in order to be scheduled. +- It is necessary to check the **RabbitMQ** box in the **SCHEDULING** status of the Call Workflow to allow the proposal to be processed in the scheduler. To enable this: + + 1. Open your workflow. + ![scheduler_wf](../assets/images/scheduler_wf.png) + + 2. Click on the path that leads to **SCHEDULING** status workflow tree. + + ![scheduler_wf_status](../assets/images/scheduler_wf_status.png) + + 3. Click on **Status Actions** and check the **RabbitMQ** box. + + ![scheduler_wf_rabbit](../assets/images/scheduler_wf_rabbit.png) + +Ensure the proposal is **Accepted** and its status matches the configured trigger status (e.g. **SCHEDULING**). Once these two conditions are met, you can allocate time slots, and they will appear in the scheduler. + +![scheduler_pre_status](../assets/images/scheduler_pre_status.png) + +![scheduler_pre_allocate](../assets/images/scheduler_pre_allocate.png) + +--- + +## Interface + +### Left Panel + +The left panel displays the menus available in the Scheduler interface. The default page is **Calendar**, where all planned time slots are visualized. Additional menus, such as **Equipment List** and **Equipment Request**, will be added to manage equipment and related requests. + +![scheduler_menu](../assets/images/scheduler_menu.png) + +### Calendar Page + +The calendar interface is designed for **Instrument Scientists**, allowing them to view planned time slots. +**NOTE:** Instrument Scientists can only schedule operations for the instruments they are assigned to. + +![scheduler_calendar](../assets/images/scheduler_calendar.png) + +#### Calendar Features: + +- **Default Display**: The calendar defaults to **Calendar mode**, providing a classic view of the schedule. + +#### Available Filters: + +- **By instrument**: Filters time slots by specific instruments (e.g., beamlines like **ROCK**). +- **By equipment**: Filters by the equipment in use (details available in the Equipment List menu). +- **By local contact**: Displays time slots by the associated Instrument Scientist. + +![scheduler_filters](../assets/images/scheduler_filters.png) + +#### Display Types: + +The right panel allows you to change the calendar display type using three options: + +1. **Calendar**: Classic view (default). + +![scheduler_view_calendar](../assets/images/scheduler_view_calendar.png) + +2. **Table**: Structured tabular view of time slots. + +![scheduler_view_table](../assets/images/scheduler_view_table.png) + +3. **Timeline**: Chronological view similar to Outlook, providing a linear and intuitive representation of time slots. + +![scheduler_view_timeline](../assets/images/scheduler_view_timeline.png) + +--- + +## Event Management + +A **NEW EVENT** button is available to create new events, such as: + +- **Maintenance**: Scheduling a time period for instrument or equipment maintenance. +- **Shutdown**: Scheduling machine downtime. + +![scheduler_new_event](../assets/images/scheduler_new_event.png) + +![scheduler_plan_down](../assets/images/scheduler_plan_down.png) + +### Time Slots to Plan + +Time slots are directly linked to proposals. When a proposal reaches the **SCHEDULING** status (or other configured status), it appears in the planning sidebar and can be assigned time. + +Example: + +- Proposal is in SCHEDULING +- Currently scheduled for 2 days and 3 hours + +This section provides a clear overview of planning and managing beam time for instruments and equipment. + +Drag proposal onto the calendar to specify desired start date +![scheduler_plan_drag](../assets/images/scheduler_plan_drag.png) + +Edit the experiment details (e.g duration and Local Contanct) and activate the Experiment time +![scheduler_plan](../assets/images/scheduler_plan.png) + +You should now see the experiment time in the callendar +![scheduler_planned](../assets/images/scheduler_planned.png) + +--- diff --git a/documentation/mkdocs.yml b/documentation/mkdocs.yml index f89752b72e..23d850df00 100644 --- a/documentation/mkdocs.yml +++ b/documentation/mkdocs.yml @@ -10,6 +10,8 @@ theme: palette: primary: indigo accent: light blue +extra_css: + - stylesheets/extra.css extra: generator: false version: @@ -64,6 +66,7 @@ nav: - Settings: - Proposal workflows: user-guide/user-officer/settings/proposal_workflow.md - Features: user-guide/user-officer/settings/features.md + - Scheduler: user-guide/scheduler.md - Developer Guide: - Contributing: developer-guide/CONTRIBUTING.md - Architecture: developer-guide/architecture.md