**As a** project member,
**I want to** be able to visualise work packages in a weekly calendar view across multiple sub-projects, and order them by assignee
**so that** I have a clear vision of who does what and when, and have a clear view of resource availability.

**Note**
The Team planner is an initial (first stage) implementation a larger evolution the planning that will be implemented in a multi-step process. At this stage, it will only display the planner in a weekly view.

_This work package is a work in progress, specification is not yet complete._

####

#### **Acceptance Criteria**

**The module**

There is a new module called "Team planner".

* This has to be enabled and has its own permissions.
* Begin of the insertionAs withEnd of the insertion Begin of the deletion **Open -** Which permissions shall exist? For work packages, there is (only those deemed relevant): "View work packages", "Save views", "Manage public views". ForEnd of the deletion boards, Begin of the insertionwe'll have aEnd of the insertion Begin of the deletion there isEnd of the deletion "View Begin of the deletion boards" and "Manage boards". We can probably use the later model and add "ViewEnd of the deletion team planner" and "Manage team planner". That would mean Begin of the deletion though,End of the deletion that all team planners are public all the time. There is no possibility to configure a team planner and save it for oneself Begin of the insertiononly (for now).End of the insertion Begin of the deletion only, then.End of the deletion
Begin of the insertionTheEnd of the insertion Begin of the deletion Currently, theEnd of the deletion work package module will have to be active whenever the team planner is activate.
* Is also based on fullcalendar.io but is separate from the Calendar module.

This new module, once enabled, is visible in the sidebar as "Team planner":

* Begin of the insertion~~NowEnd of the insertion Begin of the deletion NowEnd of the deletion loads a table of team planners (similar to boards) in the main Begin of the insertionview.~~End of the insertion Begin of the deletion view.End of the deletion
* Begin of the insertion~~InEnd of the insertion Begin of the deletion Drills intoEnd of the deletion the Begin of the deletion "Team planner" item in the sidebar with previously saved planners,
* In theEnd of the deletion main view, the table has these columns: "Name", "Created on", Begin of the insertion"Assignees":~~End of the insertion Begin of the deletion "Assignees":End of the deletion
* Begin of the insertion~~TheEnd of the insertion Begin of the deletion TheEnd of the deletion assignees column will list the number of assignees added to that Begin of the insertionplanner.~~End of the insertion Begin of the deletion planner.End of the deletion
* Begin of the insertion~~EachEnd of the insertion Begin of the deletion EachEnd of the deletion column has a "Delete" button as the last item of that Begin of the insertionrow.~~End of the insertion Begin of the deletion row.End of the deletion
* Begin of the insertionDrills into the "Team planner" itemEnd of the insertion Begin of the deletion There is a create buttonEnd of the deletion in the Begin of the insertionsidebarEnd of the insertion Begin of the deletion top right corner,End of the deletion with Begin of the insertionpreviously saved planners.End of the insertion Begin of the deletion the title "Create new planner"End of the deletion
* Begin of the deletion **Open -** Niels and I (Jens) discussed the option of not having an overview as described above. Upon clicking on the "Team planner" menu item, the first team planner would load right away. This would be similar to how it is handled in the work package module.End of the deletion "The first" Begin of the insertionon that listEnd of the insertion would then be the first when sorted alphabetically allowing users to also prepend numbers to govern this. Begin of the insertionThis top-most plannerEnd of the insertion Begin of the deletion The advantage of thisEnd of the deletion is Begin of the insertionloaded automatically. To navigate to other saved planners, the user has to pickEnd of the insertion Begin of the deletion that less clicks are necessary and thatEnd of the deletion a Begin of the insertiondifferentEnd of the insertion Begin of the deletion defaultEnd of the deletion planner Begin of the insertionfrom the sidebar.
* ThereEnd of the insertion Begin of the deletion can be displayed fast. The downside of thisEnd of the deletion is Begin of the deletion thatEnd of the deletion a Begin of the insertionsidebar entry atEnd of the insertion Begin of the deletion new place forEnd of the deletion the Begin of the insertionend of the list with the title "Create new planner". ThisEnd of the insertion Begin of the deletion "Create"-buttonEnd of the deletion is Begin of the insertionessentially the "Create" function (now that we don't have an index/list view for this v1).End of the insertion Begin of the deletion necessary.End of the deletion

**Create new calendar**

Clicking on "Create new planner" loads an empty planner.

* The top header is by default in edit mode, much like when the user creates a new board; the user is able to type a name for the calendar and click on the save icon to save the calendar.
* There is no back button (as is the case when a new board is created; this should also be changed in the boards).
* The right side of the top header has two buttons:
* The standard "filter" action (with the "assignee" filter disabled)
* The "more" action with three vertically-stacked dots (contents to be determined)
* The secondary toolbar has these elements, and is common to new and existing calendars:
* On the left edge:
* Left/right buttons to go forwards and backwards in time (in increments of week or month, depending on the current view)
* A "today" button to return to today
* The standard filter button (that works like filters elsewhere, notably in work packages list view)
* Centered:
* The current date range visible, either the month ("August 2021") or a week ("6–10 August 2021")
* ~~On the right edge:~~
* ~~A switch to select between "Planning view" and "Month view" (please note that the planning view is limited to a weekly view for the moment)~~

~~**Changes to the existing calendar module**~~ **(to be migrated to another work package)**

~~The month calendar view is similar to the current view, with notably these differences:~~

* ~~The work package "strips" have been upgraded with new functionalities and behaviour:~~
* ~~The ability to drag them to change start/end dates (keeping the duration the same)~~
* ~~Extend left and right edges to change start/end dates~~
* ~~A hover displays work package information in an overlay (current behaviour)~~
* ~~A click opens the work package in a split screen view~~
* ~~The colour of the strip corresponds to... **FILL**~~
* ~~Each calendar date has four possible states, each visually distinct form one another:~~
* ~~Inactive (not part of the current month), with a grey background, without day numbers~~
* ~~Active (part of the current month), with a light blue background, with day numbers~~
* ~~Today, highlighted with a yellow background, with day number~~
* ~~Hover, with a light blue background, with day number~~

**Main view**

The calendar week view is the main view:

* There is an "Assignee" column on the left edge
* The other columns are dates, displayed as "{day name} - {date number}", as in "Monday - 9". This is shortened to "Mon - 9" in smaller windows when the cell is not wide enough to display the full version.
* The current date is highlighted also in the column header, with the same yellow highlight.
* Only work packages assigned to assignees that the user adds to the calendar will be visible. This means:
* By default, an empty calendar will have zero assignees
* There is an empty state that reminds the user to add assignees. ("Add assignees to set up your team planner.")
* There is an "Add assignee" button at the bottom, to the left.

**Add assignee button (to be updated)**

Clicking the "Add assignee" button displays an overlay with:

* A title ("Add assignee")
* A close button on the top right edge
* A search bar
* As the user starts typing, a list of users who correspond to the search terms displayed as:
* An avatar and
* Their full name
* Clicking on a particular user adds a row to the Planning view for that assignee, in an alphabetical order **(or order of adding?)**
* Begin of the insertionIf addingEnd of the insertion Begin of the deletion **Open -** AreEnd of the deletion groups Begin of the deletion selectableEnd of the deletion as assignee Begin of the insertionrows is relatively easy (from a dev pov), this should be possible. In this case, individuals in thatEnd of the insertion Begin of the deletion rows? If they are, can the individual members of theEnd of the deletion group Begin of the insertioncan neverthelessEnd of the insertion be added Begin of the insertionseparately. (This allows the user to takeEnd of the insertion Begin of the deletion additionally. WithinEnd of the deletion a Begin of the deletion group assignee row, will onlyEnd of the deletion work Begin of the insertionpackageEnd of the insertion Begin of the deletion packagesEnd of the deletion assigned to Begin of the insertiona group and assign it to a particular member ofEnd of the insertion that Begin of the insertiongroup). The work packages in theEnd of the insertion group Begin of the insertionrow then only showEnd of the insertion Begin of the deletion be displayed or alsoEnd of the deletion those Begin of the insertionexplicitlyEnd of the insertion assigned to Begin of the insertionthe group, not those assigned toEnd of the insertion members of that Begin of the deletion group?
For the sake of the MVP,End of the deletion group Begin of the deletion assignee rows should be ignored.End of the deletion

**Features specific to planning view (to be updated)**

Planning view, once assignees have been added, affords the users more functionalities than is available in month view:

* Hovering on the cell with the name and avatar of the assignee displays a "remove" icon, that allows users to remove that assignee from the current view.
* "Today" is no longer one cell, but an entire column, all of which is highlighted with a light yellow background.
* Work packages are arranged by assignees. They can be stacked, up to 5 per assignee. ("Error handling and exceptions" describes behaviour for when there are more than 5 work packages for any assignee).
* As in the month view, work package strips can be extended on either end (left or right) to change start/end dates but they can also
* Be dragged from one row to another to assign it to another user
* **Open -** Drag and drop to alter the start/end date is not described
* **Open -** When dragging a work package that spans more than the week, so that the start and end date is not displayed. How is feedback provided to the user when dragging the work package?
* **Open -** The row will have a min height of x but can grow almost arbitrarily (see Open in "Error handing")
* **Open -** If the height of taken up by the assignee rows is more than the available screen height, scrolling is to be applied. On which element is the vertical scrolling applied?
* **Open -** In case two work packages displayed on the same planning calendar at the same time are in a follows/precedes relationship. How does the software communicate the changes to the following relationship upon changing the dates of the preceding work package?
* **Open -** How are changes to the dates via the split view reflected in the calendar?
* **Open -** How to communicate that a work package cannot be dragged e.g. because of:
* the user not having the permission to edit work packages (the permissions might be different for two work packages within the same team planner if they are in different projects)
* the work package being a parent
* the work package having a locked status
* a constraint imposed by relationships on the start date is violated
* **Open -** Are milestone work packages displayed differently? How to communicate that the duration cannot be changed but the date and assignee can.

**For individual day cells:**

* Right-clicking (or clicking) on a date cell, which will be in its hover state, will load a "Quick add" overlay:
* A title ("Quick Add")
* A close button on the top right edge
* A search bar
* As the user starts typing, a list of work packages that correspond to the search terms displayed, one per row with:
* The avatar of the author
* Type
* Title/subject
* Project
* #ID
* Status
* **Open -** It was discussed whether we rather use the split view for creating new work packages. On choosing to add a new work package, the split view could be opened with the assignee and the dates already filled in. This would allow to handle the edge case of e.g. mandatory custom fields.

**Enterprise edition**

* The team planner will be an enterprise only feature.
* The calendar module will be kept non enterprise with all improvements carried over from team planner included (e.g. persisting filters)

#### **Error handling and exceptions (to be completed)**

**Exceptions**

* In both month and planning views, when any row has more than 5 work packages that need to be displayed, only those 5 are displayed initially.
* A "And {x} more..." strip communicates to the users that there are additional work packages that are hidden
* Clicking on this will expand the row and also display those additional work packages (so that that row now has than 5 maximum work packages)
* There is currently no defined upper limit to the number of work packages that can be displayed in one row with this mechanism.
* **Open -** the proposal to show all the work packages has been discussed and agreed upon. There might still be the need for an upper limit though (e.g. 100 work packages in a cell).
* **Open -** it might not be possible using FullCalendar means to display the "And {x} more ..." strip spanning the complete line. Possibly, this can only be displayed per date cell.

**Error management** (to be completed)

* When adding new work packages
* Assignee already set
* Dates already set
* Assignee/dates already set
* The work package has been invalid before, e.g. a required custom field is not set
* When dragging work packages
* The work package has been invalid before, e.g. a required custom field is not set
* Moving the work package would violate a constraint (e.g. a preceding work package limiting the start date)

**Mobile**

* **Open -** There will not be support for this on mobile. How do we hide the feature?

**Visuals**
_To be added after discussion/exchange within the product team_

**Out of scope**

* Views other than weekly (including the two-week view)
* The ability to identify assignees with overdue work packages (and view those in an overlay)
* More detailed work package strips that display important attributes without needing a hover
* Work package planning stages (done, planned, overdue)
* Altering the order of assignees by dragging-and-dropping entire assignees rows
* A shortlist of work packages form which the user can drag and drop work packages to the calendar (and a way to filter this shortlist)
* Any form of automation (associating certain work package status with certain planning stages)

**Mockups in Figma**
https://www.figma.com/file/409d6qR685SzZLXez4TPl7/?node-id=614%3A26487

_(Please note that the relevant screens are on the "Team planner" page; the above links takes you to the correct page)._