Changes to Planner Task API

Hello, we are making a few changes to the Planner Task API on the Microsoft Graph REST API Beta endpoint.  These changes add support for recently released features (multi-assign tasks) and puts us on a path to finalize the initial version of the Planner API and move it from Beta to V1.0.  These changes will be available on the Beta endpoint starting on April 13, 2017. 

The changes to the Planner API include:

1. New /planner/ segment for all Planner resources

This update will add a /planner/ segment to every URL. This segment is used for organizational purposes only and does not contain usable properties. The follow table shows the changes to URLs. 

2. API Support for tasks assigned to multiple people

Planner recently announced support for assigning a task to multiple people. To support this in the API, the task’s assignedTo field will be removed and replaced with an open type that represents a collection of assignments. For more information, see plannerAssignments.

As part of this change, the taskBoardTaskFormat will be split into 3 distinct types representing the views supported by the Board in Planner clients.  For more information, see plannerAssignedToTaskBoardTaskFormat, plannerBucketTaskBoardTaskFormat, and plannerProgressTaskBoardTaskFormat.

3. Service generated order hints

Clients can sort Planner objects by their order hint.  Previously, clients could set order hints to any string value.  With this update, the Planner service will now generate order hints for all objects and require clients to follow the format and scheme described in Using Order Hints in Planner.  

4. Additional properties on task resource

We’ve added the following properties to the task resource that provide summary information on collections in taskDetails:

• activeChecklistItemCount: number of active checklist items
• checklistItemCount: total number of checklist items
• referenceCount: total number of external references for tasks, such as attachments and links

 5. Sortable ETags

ETags for all objects will now be sortable by the ordinal values of its characters.  You can compare the ETag values to determine which object versions are newest, with the newer versions sorting after older ones.

6. Read-only user identity fields will return an identitySet instead of a string

This change is limited to read only fields that represent users. Editable fields will not be impacted.  The impacted fields include:

• completedBy
• createdBy
• modifiedBy
• assignedBy

Thank you for using and providing feedback on the Planner Task API, and happy coding. 

FAQ:

What happens to the existing Planner Task API? When will it stop working?

The current Planner API (without the /planner/ segment) is now deprecated and will be removed on May 26, 2017. Client applications must be updated before May 26, 2017 or they will no longer function. 

Until then, basic functionality in the current API will continue to work side-by-side with the new API, to help transition applications to the new API. However, applications using the current Planner API may cause issues such as:

o   Removing additional assignees on a multi-assigned task

o   Specifying an incorrect orderHint

Why add the /planner/ segment to the API?

The new API introduces several breaking changes as described above. The segment helps existing applications continue to function while transitioning to the new API. 

In the coming months, we plan to make other service-specific Task related APIs available on Microsoft Graph. This segment provides a way to distinguish between each service’s API surface. 

It is important to note that we are also working on a converged Task API story for Microsoft and will have more details to share in the future.