# User Story

**As a** project team member

**I want t**o see my project calendar in my personal calendar

**So that** I don't have to maintain two different calendars to organize my work.

# Use case examples

1. Release dates and other project milestones
2. Submission deadlines of artefacts that require collaboration with other team members
3. Extend certificats (e.g. SSL, SMIME)

While trying to introduce OpenProject in a team that I’m part of, I realised that there is no way to integrate the calendar with MS Outlook, Apple Calendar, Google Calendar, and the likes. It would greatly increase the visibility of project planning if people were able to see changes in their preferred calendar apps, instead of having to check the OpenProject calendar webpage. Export functionality would provide a very natural means to integrate OpenProject with existing planning and coordination routines established in teams (most of which will be using a calendar app of sorts).

# Acceptance criteria

* Separate project permission
* Menu entry to create and copy URL with the label "**Subscribe to iCalendar"**
* This menu entry opens a modal with an explanation, an input field with a placeholder text that allows the user to name the iCalendar and a warning banner. In the action bar of the modal there is the "**Copy URL**" action which will trigger the creation of the token. Once the user clicks on the button the modal closes and a toast appears on top of the screen to indicate the success or error to create and copy the token URL.
* The input field in the modal can present an error if the user tries to **"Copy URL"** without introducing a name or if the name is already taken.
* Caching
* The calendar invite includes the main information of the work package organised in this order:
* **LOCATION:** For the work package _**URL**_
* **SUMMARY:** For the work package _**subject**_. We've decided to not display the _**work package ID**_.
* **DESCRIPTION:** Containing this elements:
1. _**Project**_
2. _**Type**_
3. _**Status**_
4. _**Assignee**_
5. _**Priority**_
6. _**Description:**_ up to 240 characters of the description
* **ORGANIZER:** For the Begin of the insertion_**author**_End of the insertion Begin of the deletion _**author, assignee or accountable (TBD)**_End of the deletion of the work package.
* **DTSTART:** For the work package _**start date**_.
* **DTEND:** For the work package _**finish date**_.
* The event should not be editable in the calendar client side.
* All iCalendar tokens can be revoked in "My account -> Access tokens"
* The permission to subscribe to iCalendars is set as a part of the project roles settings. For the migration path, all the roles that has the setting "**View calendars**" active will also by default have "**Subscribe to iCalendars**" active (and the other way around).
* On top of the role a admin setting checkbox will be available in &quot;**Administration &gt; Calendar and dates &gt; Working days**&quot; which will be available once <mention class="mention" data-id="47341" data-type="work_package" data-text="#47341">#47341</mention> is completed.
* Each iCalendar tokens generated will contain the information of which calendar is shared and its project in order to display them one by one in the access tokens page.

# Mockups

#### Calendar view

<img class="op-uc-image op-uc-image_inline" src="/api/v3/attachments/53507/content">

<img class="op-uc-image op-uc-image_inline" src="/api/v3/attachments/55823/content"><img class="op-uc-image op-uc-image_inline" src="/api/v3/attachments/55824/content"><img class="op-uc-image op-uc-image_inline" src="/api/v3/attachments/55826/content"><img class="op-uc-image op-uc-image_inline" src="/api/v3/attachments/55825/content">

#### Access tokens

#### <img class="op-uc-image op-uc-image_inline" src="/api/v3/attachments/55811/content">

#### Permissions and roles

#### <img class="op-uc-image op-uc-image_inline" src="/api/v3/attachments/53510/content">

#### iCalendar admin settings

<img class="op-uc-image op-uc-image_inline" src="/api/v3/attachments/53511/content"><img class="op-uc-image op-uc-image_inline" src="/api/v3/attachments/53711/content">

# Figma link

https://www.figma.com/file/0XYbNtiBhnGWYHtzmynWI8/iCalendar-subscription?node-id=0-1

# ToDo

* [x] Investigate all the possibilities of iCal and what can we display:
* [x] If we can use the field &quot;status&quot; for any work package status such as &quot;scheduled&quot;
* [x] Create an ideal example of iCal txt
* [x] Benchmark on how are the iCal parameters displayed in the calendar clients
* [x] OX
* [x] Thunderbird
* [x] Mailbox
* [x] Outlook
* [x] Yahoo
* [x] Google Calendar
* [x] Google Calendar (Android)
* [x] Calendar (Mac)
* [x] Calendar (iOS)
* [x] Basecamp
* [x] 30 Boxes
* [x] Trumba
* [x] BusyCal
* [x] OneCalendar
* [x] Fantastical
* [x] Structured
* [x] Update mockups
* [x] URL: [https://openproject.example.com/projects/demo-project/calendars/27.ics?ical\_token=c6ec6fea407cb0eca52db380daefacbe](https://openproject.example.com/projects/demo-project/calendars/27.ics?ical_token=c6ec6fea407cb0eca52db380daefacbe)
* [x] Screen to revoke all tokens (not separately)
* [x] Permissions screen (admin settings)
* [x] Decide what info is mapped in the iCal event
* [x] Calendar entry in multiple calendar clients
* [x] Add link to mockup here: https://www.figma.com/file/fIFszjTJWyd0p94SXjih58/Calendar-view?node-id=111%3A7801
* [x] Specify permissions
* [x] Investigate the capabilities to use emojis to visualise content
* [x] Work package type
* [x] Status
* [x] Priority

# Out of scope

* CalDAV (we focus on ics-files for now)
* Update calendar entries in the calendar applications (read-only, no bi-directional sync)
* Revoke iCalendar tokens individually