# Shift Assignment MIDAS Page

## Contents

- [Shift Assignment MIDAS Page](#shift-assignment-midas-page)
  - [Contents](#contents)
  - [Setup](#setup)
    - [Initial Setup](#initial-setup)
    - [Change Default ODB Settings](#change-default-odb-settings)
    - [Add some shifters](#add-some-shifters)
  - [Basic Usage](#basic-usage)
  - [Testing](#testing)
  - [Developer Notes](#developer-notes)

## Setup

### Initial Setup

First, clone this repository somewhere on the host computer. $HOME/packages is a good place. 

Run

```
./setup.bash
```

which will set up the ODB with the proper keys and make the soft links needed to access the pages, create the python virtual environment and install dependencies in that environment. You can re-run `setup.bash` later as needed to fix any missing keys in the ODB.

### Change Default ODB Settings

In the ODB, navigate to `/Shifts/ShiftSetup` and change the `name`, `start_offset_mins`, `stop_offset_mins`, `roles`, and `shiftid` arrays as needed. 

You should also change the database type to something appropriate: `/Shifts/Settings/database`.

Details on ODB keys: 

* `name`: shift name. This is what is displayed on the page in the leftmost column. HTML is permitted for additional formatting. For example, use `<br>` to introduce a line break. Please do not include underscores `_` in your shift names.  
* `shiftids`: these are used to identify which shift is which in the databases. Each shiftid should be unique. It is suggested to simply increment these from the maximum to avoid duplicating shifts in the future. Shifts with an id of zero are ignored.
* `start_offset_mins` and `stop_offset_mins`: The timing offsets for shift start and stop are denoted from midnight for each day. Thus, if today is July 1,
    * `start_offset_mins = 60` means that shift starts on July 1, 01:00
    * `start_offset_mins = 900` means that shift starts on July 1, 15:00
    * `start_offset_mins = -60` means that shift starts on June 30, 23:00
* `roles`: Names of roles available to shifters. A blank role is always allowed. Please do not set a role of `.` (period).
* `database`: Currently only `csv` and `parquet` are supported database types. In theory, parquet files are more efficient than csv files, especially when the database starts to get big. In practice, I have yet to see the csv file get large enough that it becomes less efficient than the parquet file. To seamlessly transition between the two, change the `/Shifts/Settings/database` ODB key to either `csv` or `parquet`. The database files will be written in the new format on changes. I would recommend starting with the csv setup and transition to parquet if the program starts to get slow. 
 
The order of the entries in the `shiftids`, `names`, `stop_offset_mins`, and `start_offset_mins` arrays should correspond to each other. The order also sets the display order of the shifts in the scheduler. 

### Add some shifters

In your new custom page, click on the "+ New Shifter" button to add shifters to the schedule. Shifters are ID'd in the database by their name.

## Basic Usage

* You must have at least one shifter in /Shifts/ContactInfo ODB directory to do anything.
* Click on a cell in the "Schedule" table to start assigning shifts. 
  * Pick a role for that shifter - cells with this role will be highlighted
  * Selecting a shifter or mousing away will close the dropdown menu. 
  * Mousing over each shifter will highlight the shifts they have and their availabilities
* Select a shifter from the lower dropdown menu to start setting availabilities for that shifter
  * Click and drag to quickly set multiple times
  * If the "Shifts may only be assigned to available shifters" to reduce the available options on assignment.

## Testing

The tests drive the page in a real browser with [playwright](https://playwright.dev/python/). Install what they need with

```
./setup.bash --test
```

which adds the test packages and downloads the browser on top of the usual setup. Then run the suite from the `tests` directory:

```
source venv/bin/activate
cd tests
pytest
```

The tests need `mhttpd` running on port 8080, since they drive the custom page through it. The browser runs hidden by default; pass `--headed` to watch it.

**Running the tests wipes the `/Shifts` ODB tree and the `data` directory.** Save anything you want to keep first with `odbedit -c "save mybackup.json"` and a copy of `data`.

See [tests/README.md](tests/README.md) for more.

## Developer Notes

* Databases are saved in numeric subdirectories in the `shiftschedule/data` directory. Values start from zero.
  * Up to 50 past versions of the database are saved
  * Pressing back/undo then making changes deletes future databases
*  The ODB is pinged every 500 ms to check the current state. If it does not match, then the shifts, availabilities, and notes are updated
* There are three database files: shift assignments, availabilities, and notes.