**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 Begin of the insertionthree permissions:End of the insertion Begin of the deletion its own permissions.End of the deletion
* Begin of the deletion As with boards, we'll have aEnd of the deletion "View team planner" Begin of the insertion
* End of the insertion Begin of the deletion andEnd of the deletion "Manage team Begin of the insertionplanner"End of the insertion Begin of the deletion planner". That would mean that all team planners are public all the time. There is no possibility to configure a team plannerEnd of the deletion and Begin of the insertion
* MakeEnd of the insertion Begin of the deletion saveEnd of the deletion it Begin of the insertionpublic/private (phrasing to be confirmed)
* End of the insertion Begin of the deletion for oneself only (for now).
End of the deletion The work package module will have to be active Begin of the insertionforEnd of the insertion Begin of the deletion wheneverEnd of the deletion the team planner Begin of the insertionto be active.End of the insertion Begin of the deletion is activate.End of the deletion
* 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 insertionClicking on "Team planner"End of the insertion Begin of the deletion ~~Now loads a table of team planners (similar to boards)End of the deletion in the Begin of the insertionproject sidebar drills into the "Team planner" sub-menu.End of the insertion Begin of the deletion main view.~~End of the deletion
* Begin of the insertionThe first item is a back button withEnd of the insertion Begin of the deletion ~~InEnd of the deletion the Begin of the insertiontitle "Team planner"
* In this sub-menu, there are four possible headers inEnd of the insertion Begin of the deletion main view,End of the deletion the Begin of the insertionsidebars:End of the insertion Begin of the deletion table has these columns: "Name", "Created on", "Assignees":~~End of the deletion
* Begin of the insertion"Favorite team planners" visible only if there are team plannersEnd of the insertion Begin of the deletion ~~The assignees column will list the number of assignees added toEnd of the deletion that Begin of the insertionhave been favouritedEnd of the insertion Begin of the deletion planner.~~End of the deletion
* Begin of the insertion"Public team planners" lists all saved team planners that are public
* "Private team planners" lists all team planners that are markedEnd of the insertion Begin of the deletion ~~Each column has a "Delete" buttonEnd of the deletion as Begin of the insertionnot public
* The "Create team planner" only ever has onEnd of the insertion Begin of the deletion the lastEnd of the deletion item Begin of the insertion(New team planner)
* The "first" team planner (so the firstEnd of the insertion of Begin of the insertioneither the favorited ones, public ones or the private ones, inEnd of the insertion that Begin of the insertionorder) will the one that will be automatically loaded.End of the insertion Begin of the deletion row.~~End of the deletion
* Begin of the insertionIf there are no existing team planners,End of the insertion Begin of the deletion Drills intoEnd of the deletion the Begin of the insertion'New team planner'End of the insertion Begin of the deletion "Team planner"End of the deletion item Begin of the insertionunder "Create team planner" is loaded automatically.End of the insertion Begin of the deletion in the sidebar with previously saved planners.End of the deletion
* Begin of the insertionWithin each view,End of the insertion Begin of the deletion "The first" on that list would then beEnd of the deletion the Begin of the insertionlist of team planners is arranged alphabetically,End of the insertion Begin of the deletion first when sorted alphabeticallyEnd of the deletion allowing users to also prepend numbers to govern Begin of the insertionthis
* End of the insertion Begin of the deletion this. This top-most planner is loaded automatically.End of the deletion To navigate to other saved planners, the user has to pick a different planner from the sidebar.
* Begin of the insertionThe last headerEnd of the insertion Begin of the deletion There is a sidebar entry at the end of the list with the titleEnd of the deletion "Create new Begin of the insertionplanner" has only one item, "New teamEnd of the insertion planner". This is essentially the "Create" function (now that we don't have an index/list view for this v1).

Begin of the insertion**A basic (empty calendar)**End of the insertion Begin of the deletion **Create new calendar**End of the deletion

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. Begin of the insertion
End of the insertion Begin of the deletion
End of the deletion * Begin of the insertion_Note: thereEnd of the insertion Begin of the deletion ThereEnd of the deletion is no back button Begin of the insertionatEnd of the insertion Begin of the deletion (as isEnd of the deletion the Begin of the insertionlevel of this top header (unlikeEnd of the insertion Begin of the deletion caseEnd of the deletion when a new board is created; this should Begin of the insertioneventuallyEnd of the insertion also be changed in the Begin of the insertionboards)._End of the insertion Begin of the deletion boards).End of the deletion
* The right side of the top header has Begin of the insertionthreeEnd of the insertion Begin of the deletion twoEnd of the deletion buttons:
* The standard "filter" Begin of the insertionaction, with two specifities
* The assignee attribute is disabled/not available
* The time frame attribute is disabled/not availableEnd of the insertion Begin of the deletion action (with the "assignee" filter disabled)End of the deletion
* The Begin of the insertionfull-screen icon.
* TheEnd of the insertion "more" action with three vertically-stacked Begin of the insertiondots, with these functions (that exist already today in the context of work package list/table view).
* Rename
* Save
* Save as
* Delete
* Visibility settingsEnd of the insertion Begin of the deletion dots (contents to be determined)End of the deletion
* 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)~~ Begin of the insertion
End of the insertion Begin of the deletion

~~**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:~~

End of the deletion * Begin of the insertionNo filters are enabled by defaultEnd of the insertion Begin of the deletion ~~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 informationEnd of the deletion in Begin of the deletion an overlay (current behaviour)~~
* ~~A click opens the work package inEnd of the deletion a Begin of the insertionnew team plannerEnd of the insertion Begin of the deletion split screen view~~
* ~~The colour of the strip corresponds to... **FILL**~~End of the deletion
* Begin of the insertionTheEnd of the insertion Begin of the deletion ~~EachEnd of the deletion calendar Begin of the insertionarea is empty inEnd of the insertion Begin of the deletion date has four possible states, each visually distinct form one another:~~
* ~~Inactive (not part of the current month), withEnd of the deletion a Begin of the insertionnew team planner (no work packages are visible since no assignees are added yet)End of the insertion Begin of the deletion grey background, without day numbers~~End of the deletion
* Begin of the insertionThere isEnd of the insertion Begin of the deletion ~~Active (part of the current month), withEnd of the deletion a Begin of the insertionmessage on the calendar that says "Add assignees to set up your team planner."
End of the insertion Begin of the deletion light blue background, with day numbers~~
End of the deletion * Begin of the insertionAn "Add assignee" button allows users to add assignees to get started (this button is described below).End of the insertion Begin of the deletion ~~Today, highlighted with a yellow background, with day number~~
* ~~Hover, with a light blue background, with day number~~End of the deletion

**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". Begin of the insertion
* End of the insertion 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 Begin of the insertionhighlight as in the currect calendar.End of the insertion Begin of the deletion highlight.End of the deletion
* Begin of the insertionAs soon as assignees are added (and filters optionally enabled),End of the insertion Begin of the deletion OnlyEnd of the deletion work packages Begin of the insertionare displayed as strips (as they are currently inEnd of the insertion Begin of the deletion assigned to assignees thatEnd of the deletion the Begin of the insertionCalendar module),End of the insertion Begin of the deletion user adds to the calendar will be visible. This means:End of the deletion
* Begin of the insertionPlease see next section "Work package strips" for details.
End of the insertion Begin of the deletion By default, an empty calendar will have zero assignees
End of the deletion * There is Begin of the insertionno upper limitEnd of the insertion Begin of the deletion an empty state that reminds the userEnd of the deletion to Begin of the insertionhow many strips are displayed per assignee row. (**Open:** there should probably be a technical upper limit).End of the insertion Begin of the deletion add assignees. ("Add assignees to set up your team planner.")End of the deletion
* There is an "Add assignee" button at the bottom, Begin of the insertiononEnd of the insertion Begin of the deletion toEnd of the deletion the Begin of the insertionleft edge.End of the insertion Begin of the deletion left.End of the deletion

Begin of the insertion**Work package strips**End of the insertion Begin of the deletion **Add assignee button (to be updated)**End of the deletion

Begin of the insertion* A work package strip is a visual representation ofEnd of the insertion Begin of the deletion ClickingEnd of the deletion the Begin of the insertionwork package in the calendar part of the team planner.
End of the insertion Begin of the deletion "Add assignee" button displays an overlay with:

End of the deletion * A Begin of the insertionbasic strip is almost identical to a work package strip in the current Calendar view.
* It starts on the start date and extends till the end date (either of which can be out of view)
* There is one line of text that represents the work package name
* The background colour represents the work package typeEnd of the insertion Begin of the deletion title ("Add assignee")End of the deletion
* A Begin of the insertionmilestone is displayed:
* As a strip spanning a single day, that can be dragged around to change date or assignee, but does not have the drag edges (and thus cannot be resized; the duration is always 1 day).
* This strip has additional features not yet available in calendar view:
* Small "drag handles"End of the insertion Begin of the deletion close buttonEnd of the deletion on Begin of the insertioneither end that allowEnd of the insertion the Begin of the insertionuser to extend the work package to the left or to the  right, in order to to change start/end
* The ability to drag an existing work package horizontally, to adjust the start and end dates (whilst keeping the duration constant)
* The ability to drag a work package from one row to another to assign it to another user (can also be done simulaneously with a horizotal scroll, ie., one can move the start date and change assignee in one drag-and-drop movement).
* Clicking on a work package strip opens it in a classic split screen view (see below).

**Split screen view**

The split screen view is invoked either when:

* a new work package is created
* a work package strip is clicked to view its details

The split screen behaves like it does in a work package list view:

* It anchors itself to theEnd of the insertion Begin of the deletion topEnd of the deletion right Begin of the deletion edgeEnd of the deletion
* Begin of the insertionIt pushes the main view (secondary header + calendar) to the left, and introduces a horizontal scrollEnd of the insertion Begin of the deletion A search barEnd of the deletion
* Begin of the insertionAllows the user to change any attributes that they have the permission to change
* Any changes to the start/end dates or assignee are reflected immediately (**Open:** how immediately?) on the calendar view.

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

Clicking on it adds a row to the calendar, with focus on the the assignee name search input:

* End of the insertion 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 Begin of the insertionassigns the newly addedEnd of the insertion Begin of the deletion adds aEnd of the deletion row to the Begin of the deletion Planning view for thatEnd of the deletion assignee, Begin of the insertionkeeping its position (last row).
End of the insertion Begin of the deletion in an alphabetical order **(or order of adding?)**
End of the deletion * Begin of the insertionOn refresh, theEnd of the insertion Begin of the deletion If adding groups asEnd of the deletion assignee rows Begin of the insertionare re-organised alphabetically? 
**Open:**End of the insertion is Begin of the deletion relatively easy (from a dev pov),End of the deletion this Begin of the insertiona good idea? Or shall we keep the orderEnd of the insertion Begin of the deletion should be possible. In this case, individualsEnd of the deletion in Begin of the insertionwhich assignees were added?
* It is possible to add aEnd of the insertion Begin of the deletion thatEnd of the deletion group Begin of the insertionas an assignee.End of the insertion Begin of the deletion can nevertheless be added separately.End of the deletion (This allows the user to take a work package assigned to a group and assign it to a particular member of that group). Begin of the insertion
* Individuals in that group can nevertheless be added separately.
* End of the insertion The work packages in the group row then only show those explicitly assigned to the group, not those assigned to members of that group

**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.
* Begin of the deletion "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
* End of the deletion **Open -** Begin of the deletion Drag and drop to alter the start/end date is not described
* **Open -**End of the deletion 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 Begin of the deletion are changesEnd of the deletion to Begin of the deletion the dates via the split view reflected in the calendar?
* **Open -** How toEnd of the deletion 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 Begin of the deletion
* **Open -** Are milestone work packages displayed differently? How to communicate that the duration cannot be changed but the date and assignee can.End of the deletion

**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. Begin of the insertion_(**Note:** Challenged by comment by <mention class="mention" data-id="9177" data-type="user" data-text="@Oliver Günther">@Oliver Günther</mention> on <mention class="mention" data-id="40038" data-type="work_package" data-text="#40038">#40038</mention>)._End of the insertion
* The calendar module will be kept non enterprise with all improvements carried over from team planner included (e.g. persisting filters)

Begin of the insertion~~**Changes to the existing calendar module**~~ **(toEnd of the insertion Begin of the deletion #### **Error handling and exceptions (toEnd of the deletion be Begin of the insertionmigrated to another work package)**End of the insertion Begin of the deletion completed)**End of the deletion

Begin of the insertion~~The month calendar view is similar to the current view, with notably these differences:~~End of the insertion Begin of the deletion **Exceptions**End of the deletion

* Begin of the insertion~~TheEnd of the insertion Begin of the deletion In both month and planning views, when any row has more than 5End of the deletion work Begin of the insertionpackage &quot;strips&quot; have been upgraded with new functionalities and behaviour:~~End of the insertion Begin of the deletion packages that need to be displayed, only those 5 are displayed initially.End of the deletion
* Begin of the insertion~~The abilityEnd of the insertion Begin of the deletion A &quot;And {x} more...&quot; strip communicatesEnd of the deletion to Begin of the insertiondrag them to change start/end dates (keepingEnd of the insertion the Begin of the insertionduration the same)~~End of the insertion Begin of the deletion users that there are additional work packages that are hiddenEnd of the deletion
* Begin of the insertion~~Extend leftEnd of the insertion Begin of the deletion Clicking on this will expand the rowEnd of the deletion and Begin of the insertionright edges to change start/end dates~~End of the insertion Begin of the deletion also display those additional work packages (so that that row now has than 5 maximum work packages)End of the deletion
* Begin of the insertion~~A hover displaysEnd of the insertion Begin of the deletion There is currently no defined upper limit to the number ofEnd of the deletion work Begin of the insertionpackage informationEnd of the insertion Begin of the deletion packages that can be displayedEnd of the deletion in Begin of the insertionan overlay (current behaviour)~~End of the insertion Begin of the deletion one row with this mechanism.End of the deletion
* Begin of the insertion~~A click opensEnd of the insertion Begin of the deletion **Open -**End of the deletion the Begin of the deletion proposal to show all theEnd of the deletion work Begin of the insertionpackageEnd of the insertion Begin of the deletion packages has been discussed and agreed upon. There might still be the need for an upper limit though (e.g. 100 work packagesEnd of the deletion in a Begin of the insertionsplit screen view~~End of the insertion Begin of the deletion cell).End of the deletion
* Begin of the insertion~~The colour ofEnd of the insertion Begin of the deletion **Open -** it might not be possible using FullCalendar means to displayEnd of the deletion the Begin of the deletion &quot;And {x} more ...&quot;End of the deletion strip Begin of the insertioncorresponds to... **FILL**~~
* ~~Each calendarEnd of the insertion Begin of the deletion spanning the complete line. Possibly, this can only be displayed perEnd of the deletion date Begin of the insertionhas 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~~End of the insertion Begin of the deletion cell.End of the deletion

Begin of the insertion####End of the insertion **Error Begin of the insertionhandling and exceptions (to be completed)**



**ErrorEnd of the insertion 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** Begin of the insertion

_Figma mock-ups might not yet have been updated to reflect changes described in this work package:_End of the insertion
https://www.figma.com/file/409d6qR685SzZLXez4TPl7/?node-id=614%3A26487

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