Appointments support

[sumnerevans]

As a user I want to define appointment slots where someone can book a meeting with me.

Basics

• [x] #3482
• [x] #3481
• [x] #3477
• [x] #3478
• [x] #3483
• [x] #3542
• [x] #3484
• [x] #3541
• [x] #3653

Planned improvements

• [x] #3634
• [x] #3637

Design Review Details

Some polishing

• [x] #3621
• [x] #3605
• [x] #3723
• [x] #3625
• [x] #3628

Edit view:

• [x] Lets try to use a different size of the modal or make it less wide
• [x] Add navigation bar (to be done when we have more element on the modal)
• [x] #3724
• [x] In the future have the save button as sticky
• [x] #3606
• [x] Make availability section collapsible (if we have a component for this) we don't
• [x] Actions menu has tiny space between menu and triangle
• [x] https://github.com/nextcloud/calendar/issues/3694
• [x] Use 9-5 Mo-Fr otherwise
• [x] #3691

Overview page:

• [x] #3623

• [x] #3644

• [x] #3642

  Booking page(select date, select slot):

• [x] It should start at the first possible date for an appointment (by the config). Despite any booking conflicts. https://github.com/nextcloud/calendar/pull/3631

  • Make the days before today not active https://github.com/nextcloud/calendar/pull/3631

• [x] #3725

• [x] Show only the possible days (available days) https://github.com/nextcloud/calendar/pull/3631

• [x] #3641

• [x] #3726

• [x] The slots should be sticky and we should only scroll them when its too long(low priority)

• [x] #3654

When you click a time(hour)

• [x] #3667
• [x] #3656
• [x] #3657
• [x] #3658
• [x] #3668
• [x] #3686
• [x] #3684
• [x] #3685
• [x] #3688
• [x] #3687

Possible enhancements in the future

• https://github.com/nextcloud/calendar/issues/3589
• https://github.com/nextcloud/calendar/issues/3604
• https://github.com/nextcloud/calendar/issues/3630

• 3479

• https://github.com/nextcloud/calendar/issues/3722

• 3480

---

Original request

Google Calendar for Business has a feature where you can set up "Appointment Slots". It works as follows: Create an event on a calendar, and select the "Appointment slots" option. You can configure the slots to have a certain duration, or be a single slot. See screenshot:  Then, you can share a link to the calendar where people can book time on your calendar in those appointment slots:  I would like this feature in Nextcloud. I know that the calendar is backed by CalDAV and I have a feeling that this is not an actual feature of CalDav, so it would require some significant changes to the calendar app itself, or possibly not even be part of the calendar app at all? Is this a feature that would be welcome in the default Nextcloud calendar? If so, I am willing to help implement it (I will need guidance though, I have no familiarity with developing Nextcloud apps).

[dgsiegel]

Just found a small project, which works with Nextcloud: https://github.com/samjaninf/appointment-planer

[georgehrke]

Some possible requirements:

Freebusy and selfbooking module

The idea of this module is to enable my customers to do booking of appointments with me (the operator of the cloud) on their own. For that

• they need to see which are free time slots
• they need to reserve their appointments

To do so, that module has to run on the cloud server and needs to provide two web interfaces:

• configuration interface, where the operator can adjust preferences for the booking
• customer interface, where customers actually do the booking

The result should be a browser interpretable calendar view, which can be integrated to a web page - as well as CalDAV client readable output.

Config interface needs at least these controls:

• display time period x days/weeks/monts back & y days/weeks/months forward in time
• choose display one week / two weeks / one month
• choose days of the week shown
• time slots which form the "office hours" in general https://github.com/nextcloud/server/issues/27422
• existing calendars to be summed up to represent the "busy" blocks
• calendar(s) into which customers should insert their desired appointments
• personal data customers have to provide (Name, email, phone #, postal address - obligatory or optional)
• period of time customers are allowed to book (choose multiple of quarters, half, full hours, discrete number of minutes, time limit for an appointment)
• booking raster which should be observed - appointments start every x minutes, every quarter, third, half, full, even or odd hour)
• minimum free time between appointments (can be 0)
• text boxes for customers' comments (yes/no/max characters)
• confirmation by email to customer and operator (yes or no)
• text / image bits, sent within confirmation to customer booking ID, required to change/cancel the appointment

User interface therefore needs these entries:

• period of time desired
• personal data according prefs

[jancborchardt]

@dgsiegel is this issue basically what is similar to Calendly? If you can share any screenshots of the Calendly flow or how you use it, that would be great :)

[jancborchardt]

Here is an example of how Outlook does it on mobile, starting in Mail:

[dgsiegel]

@dgsiegel is this issue basically what is similar to Calendly? If you can share any screenshots of the Calendly flow or how you use it, that would be great :)

Yes, that's about right. Ideally, instead of sending out an invite I could send a link, where people not registered on my Nextcloud instance can select a time and date for a meeting.

[sumnerevans]

I haven't really used Calendy, but from my understanding, it dosen't seem like Calendy has as much control over which blocks of time are available for people to book.

A lot of times I don't want people to be able to book my time, even if I don't have an official event on my calendar (for example, maybe that is my "get in the flow" time, and I don't want that to necessarily be on my calendar, but I don't want people to book appointments in the middle of it). I couldn't figure out how to do that in Calendy, which is why I ended up using Google Calendar instead.

[nolens]

I have placed a 250 USD bounty on this. Expiring in 6 months. Anyone?

[small1]

I have missed this bug. I got thinking about this last year. Being able to assign a subset of slots from the calendar and the recipient can choose by himself on what to use. It is used in a few CRM apps for sales people to book appointments

Here is screenshots from pipedrive. One of the options is to schedule fixed slots.

These are for my calendar and creating a visible slot:

This is for the recipient:

[small1]

I might have clients that would be able to chip in for this feature.

[small1]

@jancborchardt now you have screenshots from pipedrive (which works like calendly)

[small1]

A good thing would be if you could setup several different links with different type of slots.

[georgehrke]

Let me repost something from another ticket here so it doesn't get lost: It's best if we tackle this issue incrementally:

• [ ] To allow people to book themselves an appointment, we first need write support for public calendars: https://github.com/nextcloud/server/issues/3509
• [ ] To only show busy spots and not the actual event names, we need sharing / publishing of calendars as "show busy only": https://github.com/nextcloud/server/issues/11214

Once those two things are implemented, adding slot support will be much easier.

[nolens]

I might have clients that would be able to chip in for this feature.

@small1 : They might want to add on my bounty - or claim it? ;=)

[small1]

@nolens im going to check if they would like to add to it :)

[SergeyMosin]

Can this be closed and continued at https://github.com/SergeyMosin/Appointments

[georgehrke]

As long as your app is relying on private APIs and might hence break with any update of Nextcloud, I cannot accept it as a solution.

If we want to implement this properly, using only public supported APIs, there is no way around implementing the server changes i discussed further above.

[kiwy42]

I know it's not a solution integrated with Nextcloud and it will probably take time to achieve a production ready solution. But open source project such as https://github.com/alextselegidis/easyappointments could help to get some inspiration. I would really like to see such tool integrated to Nextcloud.

[SergeyMosin]

@georgehrke RE: public supported APIs

NC public APIs do not support creating/updating events from public pages, however this can be done without private APIs via sabre/dav plugin and \Sabre\CalDAV\Backend\BackendInterface (https://github.com/nextcloud/3rdparty/blob/a70e51b4cce278e006090d91cf26d616cb73e911/sabre/dav/lib/CalDAV/Backend/BackendInterface.php#L6) interface, which is public and well documented.

info.xml:

...
    <sabre>
        <plugins>
            <plugin>OCA\Appointments\SabrePlugin</plugin>
        </plugins>
        <collections>
            <collection>OCA\Appointments\SabreCollection</collection>
        </collections>
    </sabre>
...

ref: https://github.com/nextcloud/server/blob/dc0ee357a42763738cb13d368b25c1b94619cbca/apps/dav/lib/Server.php#L304

SabrePlugin.php

...
$this->server = $server;
$server->on('method:GET', function(RequestInterface $request, ResponseInterface $response) {

    $url = $request->getPath();
    if(strpos($url,"appointments")===0){

        $user=$this->getUserFromPath($url);

        /** @var \OCA\DAV\CalDAV\CalendarHome */
        $calendarHome=$this->server->tree->getNodeForPath('calendars/'.$user);

        if($calendarHome instanceof \OCA\DAV\CalDAV\CalendarHome) {

            /** @var \Sabre\CalDAV\Backend\BackendInterface */
            $backend = $calendarHome->getCalDAVBackend();

            if($backend instanceof \Sabre\CalDAV\Backend\BackendInterface){

                \OC::$server->getLogger()->debug(var_export(
                    $backend->getCalendarsForUser('principals/users/'.$user),
                    true));
//              $backend->updateCalendarObject(...)
//              ...
            }
        }
    }
});
...

This way my app would not directly use your private APIs (unless you are planing to get rid of sabre).

If implemented this way, does this resolve the "Private API" issue ?

This would be so much easier if the BackendInterface would be exposed somewhere, maybe in ICalendar perhaps.

[SergeyMosin]

@georgehrke Public APIs - New Plan:

I can actually just set up an authentication backend for requests from my public form page as per https://github.com/nextcloud/server/blob/dc0ee357a42763738cb13d368b25c1b94619cbca/apps/dav/lib/Server.php#L115 and then just send AJAX requests directly to ...remote.php/dav/calendars/... before the form is submitted.

This solution uses zero private APIs and once implemented should satisfy the "no private APIs" requirement. Please confirm.

[georgehrke]

@SergeyMosin That would still require largely refactoring your app, so it's using the CalDAV interface via javascript, right?

[georgehrke]

Generally speaking, this is also a feature i would like to see directly in the calendar app, not in the 3rdparty app.

[tcitworld]

I want to push for basic write support in OCP instead so that we avoid this kind of issues (Polls app also would be interested, and probably many more).

Generally speaking, this is also a feature i would like to see directly in the calendar app, not in the 3rdparty app.

I would like this as well, but I feel like we wouldn't want to have as much as features and options @SergeyMosin app has.

[georgehrke]

I want to push for basic write support in OCP instead so that we avoid this kind of issues (Polls app also would be interested, and probably many more).

I'm totally in favour of adding write-support for \OCP\Calendar as well, but that will require us to break our current simple event format. It just takes the first VEVENT block and turns it into a simple key-value array. So it doesn't support calendar-objects with multiple events (like recurrence-exceptions, etc.)

Let me create a tech-debt ticket in the server for that: https://github.com/nextcloud/server/issues/20154

[SergeyMosin]

That would still require largely refactoring your app, so it's using the CalDAV interface via javascript, right?

Yes, it would become some sort of hybrid of two sabre plugins (one for custom auth from public pages and one for updating calendar objects) and the nextcloud frontend.

[georgehrke]

Let me create a tech-debt ticket in the server for that. Will link it later.

Here we go: https://github.com/nextcloud/server/issues/20154

[brymut]

Hi @jospoortvliet , just a heads up that there's no bounty on this on bountysource's website here

[georgehrke]

@brymut I believe it was a six-month limited bounty, but I'm not 100% sure. The bounty source website does not provide much information about it:

[brymut]

Yep, quite possibly

[jospoortvliet]

Sorry guys, I have no idea how this works exactly... These changes are done by a bot using my account so I actually am clueless ;-)

[ChristophWurst]

We are planning a possible integration of this feature right inside Nextcloud Calendar.

For reference we looked into some of the commercial solutions as well as @SergeyMosin's app.

The way I imagine this feature in Calendar is that we might not directly need/use https://github.com/nextcloud/server/issues/3509 because I think there should be some logic that ensures users are only inserting events to slots that are bookable by the appointments logic and not write at arbitrary times. This way a user's personal calendar stays protected from malicious action when they chose that calendar to be the destination for booked slots.

For the configured slots I'd say it's best if we store the rules and preferences in our database and then only show them on the calendar grid as something like a "virtual" calendar that doesn't actually exist on DAV, because right now I don't think one needs a DAV calendar with all available but not yet booked slots.

I'm also unsure if we really need https://github.com/nextcloud/server/issues/11214. The reasoning is that we can likely do this query internally like @SergeyMosin did if I understand the app's code correctly. We just have to see how doable that is when we want to keep the API usage clean.

All in all this seems like from an architectural perspective the browser window that books an appointment would not directly interact with DAV, but only with dedicated APIs of Calendar. The Calendar APIs then use the slot information from its own DB in combination with the user's calendar data via Sabre to do the free/blocked handling. Data will be written back through Sabre or a OCP API. The Calendar front-end fetches the slots from an API as well and shows them similar to real calendars (but likely some distinct design/icons).

End of brain dump :v:

Edit: here are some first technical details on how this could be done conceptually

Additional data stored in Calendar

Slot configurations

Add new database structure for slots and their preferences. This includes

• A name [string]
• Description [null|string]
• Length [int]
• Increments [int]
• Target calendar [string] -> URI of the calendar to write the booked slot to
• Calendar(s) for conflict handling [string array] -> URIs of calendars to check for conflicts, uses all calendars (regular free-busy) otherwise
• Location [null|string]
  • Later on this could be also a talk link, that can go into a separate property
• Availability, either … [enum with value]
  • https://github.com/nextcloud/server/issues/27422
  • Custom schedule
• Date range, either … [enum with value]
  1. Indefinitely
  2. For x days
  3. For a date range
• Preparation time [null|int]
• Follow-up time [null|int]
• Minimum time before next available slot [null|int]
• Maximum slots per day [int]
• Timezone [null|string]
• Visibility [enum]
  • Public -> shown somewhere on the user's profile
  • Registered users
  • Private -> only visible for people who get a link

[jancborchardt]

Design-wise, this is how Google now does it since the Workspace update:

• We could use the right sidebar for setting up the schedule (where they use the left area) so you can see the calendar view representation https://blog.google/products/workspace/google-workspace-everyone/ (Gif on the bottom)

[miaulalala]

So, short explanation of the way the logic currently works:

Appointment Config:

Sets the different parameters, such as name, start time, end time, increment, preparation time etc which will be used to generate slots later. The RRule allows more sophisticated configuration, such as days of the week etc.

Booking: 1) Slots are defined via an RRule. 2) We generate all possible slots within the constraints set by the RRule. 3) The max amount of bookable slots per week is generated 4) The slots are then intersected with one or more calendars to remove any unavailable times.

• This should also take into account transparency of a calendar 5) Slots are returned.

Related PRs are https://github.com/nextcloud/server/pull/29188 and https://github.com/nextcloud/server/pull/28970

I'll add more documentation as I go.

[GretaD]

Some polishing

• [ ] Add icons(event icon) for appointments (left sidebar, calendar view) - [ ] On the action menu of the appointments add "copy link" (this is important)
• [ ] Make the name of the appointment not clickable

Edit view:

• [ ] Lets try to use a different size of the modal or make it less wide
• [ ] Add navigation bar (to be done when we have more element on the modal)
• [ ] On the duration field try to add "minutes" inside the input field.
• [ ] In the future have the save button as sticky. - [ ] Add a confirmation after we save. (this is important)

Overview page:

• [ ] Make the appointment as a button with the grey area. It would be nice to have boxes around the appointment like in dashboard.

• [ ] Lets remove the arrow on the right, and use the event icon on all of them.

• [ ] The name should be in bold and h2 and desc not bold. Add text "Book an appointment with {{name}}"

  Booking page(select date, select slot):

• [ ] It should start at the first possible date for an appointment (by the config). Despite any booking conflicts. If no slots, it should show a text why theres no slots.

• [ ] Make the days before today not active.

• [ ] Show only the possible days (available days).

• [ ] The avatar is small make it double the size.

• [ ] When theres no slots the container its a bit far down. Give it a bit of bottom padding.

• [ ] The slots should be sticky and we should only scroll them when its too long(low priority)

• [ ] Fix the jumb for the timezone.

When you click a time(hour)

• [ ] The time should be in a new line.
• [ ] Remove the padding on top(above the avatar) and both columns should start at the same height.
• [ ] Decs should be auto size, name and email should be as long as the text and add a scroll on the modal.
• [ ] Remove header "enter details", the text for name and email should be "your name" and "you email"
• [ ] After you click book the appointment should say some text(feedback) - Your appointment is booked, we sent you an email with details.

[miaulalala]

Also please change the default options for the (greyed out) preparation and follow up duration to 0 Minutes. Firstly, 0 minutes to be sent should be fine anyway, secondly, having 5 minutes as default, even when it's greyed out could be confused to mean "always have at least 5 minutes of prep / follow up"

[miaulalala]

• [ ] Check all principal calendar URIs (for the X-NC-APPOINTMENT property) when calculating MAX DAY.