Expose API for facility admins

[MKyhos]

Is your idea or feature request related to a problem? Please describe.

It's hard to communicate the status of single shifts to organizers on the ground who do not have the time to check the website constantly. Ideally, we would like to use existing channels (e.g. telegram) to communicate this.

Describe the solution you'd like

As a facility admin, I'd like to be able to generate an API token for myself such that I can conveniently export data for my facility/facilities. As far as we understand this would imply:

• integration of the Django REST framework
• exposing a GET endpoint for shifts (e.g. helpdesk/hbf-arrival-support/shifts) for facilities that the user has admin access to
• ideally possible to only query shifts for a certain date

Describe alternatives you've considered

• manually copy-paste or screenshot the shift table(s) --> very tiresome and time-consuming
• web scraping, e.g. Selenium --> working around the system instead of improving the system itself. extra maintenance needed

Additional context

At arrival support Berlin, we have been using simple google forms as a "registration system". While not perfect in many ways, it allows us to process the data to generate important insights such as the bar plot here: https://status.arrivalsupport.berlin/, which was very helpful to quickly communicate the demand at a station in the early days.

So potentially, with this data available, one could build on volunteer-planner as shift system and communicate the needs more effectively also by other means. :pray:

Thank you very much for your work!

cc @friep

[pitpalme]

There already is a link for every single shift.

It's not REST exposed, so not yet ready for automatic consumption by other software, but nevertheless provides information for staff "on the ground".

The idea of "Volunteer Planner" was not (yet) to be TG-Bot compatible. ;)

Introducing REST API will have implications. We'll have to consider it's benefits and costs.

[MKyhos]

Hello, I hope you are all doing well! I just wanted to ask what the outcome of the considerations are (though I see that they are low priority).

To make the above point a bit broader: from administrative perspective, I personally see it as a real pain point that there are no options for data export whatsoever (or have I simply missed them? in that case: mea culpa).

Assuming that there are indeed not options to easily export current and historic data, analysis and planned calls for volunteers are harder than they should be, unless either the amount of shifts are very easy to grasp (thus, "manual counting" is feasible), or one invests time to scrape the data out of the user interface.

[christophmeissner]

Hey, sorry for the delay. Can you elaborate the intended workflow a bit more and what data you need in what format? PDF, xls(x), csv, json, ics, all of the above? Who is the intended consumer? Thanks!

[cyroxx]

I represent another initiative, Notunterkunft HerzJesu/St. Adalbert. What I would need is an endpoint to retrieve upcoming shifts and details on the assigned helpers (at least the nickname as it is displayed on the webpage).

What we want

All our shifts are staffed properly, no gaps, no (or only slight) overbooking. If we are short on volunteers, we choose to create shifts on e.g. VolunteerPlanner to reach new people.

Context

We do have an internal shift plan (Google Docs - meh, but it is how it is) and we have/had created shifts in VolunteerPlanner and vostel in order to reach new volunteers. In order to do shift management and handle those three sources, I need them to be human- and machine-readable, so that I can

1. create an integrated shift plan that contains the volunteers from all three sources, to see gaps and overbookings easily
2. write a bot for the team that cares about shift management in order to inform them about changes (new assignments/cancellations), gaps, overbookings
3. make sure that that the above-mentioned team can meet the above-mentioned goals ("What we want") ;)

Idea for VolunteerPlanner

Just a rough idea:

• shifts - all shifts,ever
• shifts/upcoming - only shifts starting in the future
• tasks/1337/shifts - all shifts for a single task
• tasks/1337/shifts/upcoming - all upcoming shifts for a single task
• tasks - basic info about the different tasks (id, name, ...)

Shift info

Required shift info:

• task id
• task name
• shift time(s)
• assigned users

Security

For all of the above, a user should only be able to see the same tasks/shifts as he/she* can on the web UI (e.g. facility admins can only see the shifts/tasks of their own facility).

Data Format

At least

• JSON
• XLSX (e.g. for cases where you need non-techical humans to overlook the current shift/staffing situation)

Prior art

At vostel, we have the possibility to download an excel file for all upcoming shifts. You can choose between shifts from all tasks or shifts from just a single task (task: using the VolunteerPlanner lingo here). Additionally, you can also choose between shifts

• from your own "engagement offers" (=tasks in VolunteerPlanner)
• from all engagement offers of the org
• from engagement offers that are not your own

I have already written a script for vostel that downloads the shift info and outputs the changes/diff since the last run.