Planner APIs in Microsoft Graph

Planner APIs in Microsoft Graph


>>Hi, my name is Eray. I’m a Program Manager working
on Microsoft Planner. I’m excited to tell you all about the Planner APIs that we’ve exposed on the Microsoft Graph. Today, we’re going to go and do a little bit of an overview on Planner and then
talk about the APIs. I’m also going to cover some of the recent API updates we’ve made in the past couple
of months, and then from there, I’d spent a bunch of time demoing just to
give you a sense of how the API works and walk
through some simple examples. For those of you who are not
that familiar with Planner, Planner is a collaborative
task management tool that’s included as
part of Office 365. Any time that you’re
working with a team of people and want to
go and track work, know who’s doing what, what needs to get done, and are we on track, Planner is a great tool
for you to go and use. Whenever you use Planner,
you create a plan, and within that plan, you
have a collection of tasks. We provide a couple of
different visualizations for each of these tasks. We have a task
board where you can see all of the tasks
organized by buckets. We also provide
some out-of-the-box charts as well as a schedule view. One of the recent
changes that we’ve made with Planner
during the past year is doing deeper integration
across Office 365. And so, any time
that you’re thinking about a collaboration experience, Planner should be there for you. So in addition to
the Planner clients, we have now integrated
Planner into Microsoft Teams as
well as to SharePoint. Now, let’s go and
step into some of the core concepts of Planner. So as I noted in
the previous slide, Planner has built off of
the Group Service in Office 365. What Groups are is
that Groups go and define a named
collection of members. Each Group owns
a collection of plans, and then within
the plans themselves, you also have buckets
as well as the tasks. I’ll go and walk through all of these
during the API later. That’s kind of the basic
concepts of all Planner is. When you’d go and drill
into any of the tasks, you also have the notion
of task details. This is where we store additional metadata about the task. So you can have things like a description as
well as checklists. Next is that you also have
the ability to attach files and attach links to a task. This is also associated on task details and then
finally having comments and conversations on a
task and these are all powered by Outlook
Group Conversations. The cool thing about all
of these things is that Planner itself is
also built using the Microsoft Graph
and we go and call the very same API that you call to go and power
these experiences. And if you’re not that familiar
with the Microsoft Graph, I’m glad that you’re here
watching this video. So, the Microsoft Graph is the unified REST
API that we use to access all of the data
that’s stored within Office 365 as well as
its other services. As I noted, Planner itself uses a lot of the Graph APIs
to build its experiences. You can see on this slide that any of the items
that are highlighted green are actual APIs
that Planner uses. In addition to the other
services we integrate with, we also expose all of the Planner data via
the Graph itself, and so you could actually
go and build an app as rich as Planner using
just the Graph APIs, too. Some of the key APIs that we’ve exposed related to
Planner are around the tasks and plans that
Planner stores and its service. Some of the key things are
just getting all of the tasks that belong to me as a user, getting all the tasks
in a particular plan, and of course, seeing
all the plans that are associated with
a particular group. A couple of the main
API updates that we’ve made since exposing plans across a lot of these
different contexts and these different collaboration experiences wanted to provide additional capabilities
to help make it easier for you and users to
manage the plans. Some of the new APIs that we’ve recently released onto
the beta endpoint from Microsoft Graph include Favorite Plans and Recent Plans. So now, you have
the ability to specify specific plans that you want to favorite and see that in your UI. This is a slight change
from the past where you were leveraging
favorite groups as that proxy. In addition to Favorite Plans, now that with the plans
show up in different spots, we also expose the notion of a planned context on
plan details and this gives you a little bit of additional information
of where that plan’s being used or where
that plan is being created. And with that, let me go
and show you on a demo. We’ll start the demo from the Planner web
browser experience. So what you’re seeing
here is the Planner hub, and you can see all of the
Favorite Plans that I have as well as my Recent Plans and
a list of all the plans. Whenever I click into
any of these plans, you can go and see that I have my different buckets
like engineering, manufacturing, and so on, as well as each of the
task cards themselves. And then as before,
when I click through, I can go and see all the metadata associated with that given task. In addition to the board, charts, and schedules that I mention, we also have another view
called My Tasks. My Tasks shows you all of
the tasks that are assigned to you across all of
your different plans. Let me show you what
that looks like within the Graph API. So, I’m going to hop over
to the Graph Explorer here and then the whole structure for Planner’s pretty
straightforward. In order to go and
see any of the tasks that are assigned to me,
I can just go and say, “me/planner/tasks” and hit “Run” and that shows me all
of the same tasks that are currently
assigned to me below. If I want to see the tasks that belong to a specific plan, I can do that pretty
easily as well. Just from Planner,
I’ll go and grab the plan ID and then if
I go back over here, I can go and see all of the tasks for that particular plan, and I can also do things
like see all the buckets. And then as I noted before, one of the newer
features that we have is adding more details and
context to each of the plans. And so, this particular plan
is actually also used within the context of SharePoint as well as in Teams. And so, when I go and look
at the details of it, off of the beta endpoint, you’ll see some of the additional information
associated there. And so, if you look down here, you can actually see that it has the notion of contact details, and so, it can say that here, this is one that we created
from the Teams context, and here’s another one
that we created from the SharePoint context. And in each of these cases, we also store a URL
that gives you access to that particular plan
within that context. And so, for example, if I wanted to open
this in Teams, you can just go and
access that URL and the same with the URL that
you have for SharePoint. Next, I’m going to go and show you actually going and
creating a plan from scratch. There’s a couple of steps
involved in doing this. And so, let me go and walk
through each of these. As I noted in
the presentation before, every plan today is
owned by a group. And so, the first step
that you need to do is to actually go and
create that group. In order to create a group, all you have to do is post
to the groups endpoint. There are some basic metadata that you need to fill out about a group and I’ve kind of copied over some of it here already, and you can see that you can name the group whatever you want, so I’ll just name it API Group, and then you can specify a couple of other things like
the mail nickname and so on. When I go and run this query, that’ll go and create the group. So let me do that. Okay, great. And so, now that I
have my group below, I’m going to grab
the ID for that group because I’m going to use it for a couple of the remaining steps. After I’ve created the group, it’s important to go and add the current user to be a member
of that group as well. So by default, whenever
you create a group, the person who created it, is added as an owner of that group. But we also want to make
sure that they’re a member, so they can participate in the actual collaboration there. In order to add
a member to a group, you post to that navigation. And then in this case, I’m
going to add the current user. And so, I happened to copy over the current users
ID previously, but you could always use
the samples here just get that user’s ID
and add that in. So when I go and run that query, now, I’ve succeeded
and I’ve added that user to the group. To check that everything
worked out correctly, you can always go and do quick read on that same group and
look at the members list. And if it all went well, I should see myself in that list. And so, correct, I see Alex Wilbur is now a member
of that same group. Next, I’m going to
go and show creating a plan for that given group. In order to create a plan, you need to just specify a title and then the group
that it’s owned by. This is a common question
that people have, is that when they
see the owner field, they think that, “This should be the owner like a user for it.” But in this particular case, because we’re talking
at the API level, this is the owner from
a group perspective, and so it’s the group that’s
containing that plan. And so, what I’m going
to do here is copy over the ideas specified before, and then I’m going to have
a plan called “API Demo Plan”, and then I’m going to run-
make sure this is the post. And I’m going to go and
create that now as well. Okay. And now that
I’ve completed that, you can see that it does say success and I have a plan
ID that I can use. The next thing I’m going to show is actually adding
that plan to “My Favorites” collection for
easier access going forward. So let me go and copy that over. So, the first thing I want to do is actually look at all of the favorites that I have so far. And so, if you go to
Beta/me/planner/favoritePlans, you could see all
of the favorites that I currently
have for this user. This basically maps to
that same call that you saw on the hub previously. You can also look at
all of these both the “Favorites” and
“Recent”in one call by just removing that last segment. So if I go like this, you could see kind of
an abbreviated version of “My Favorites” as well as
my “Recent Plans”. This is actually useful if you want to go and
render just the list of plans in one quick call without a lot of
the extra amount of data. Okay. So, in order to go
and add something to this, what I’m going to do is
do a “Patch” and let me grab the stuff I
want to patch here. And then I’m also going to
add the request header for-. So, I need to grab the “ETag”. Then, I’ll grab the “ETag” just to make sure
I have the most recent. Okay. Then going back
to the “Request”. I need to go and actually take the plan ID and add
that to “My Favorites”. So this is the plan
ID from the plan I had in the previous step. And then, I’m going to
have an “Order Head”, this is specifying that it
should be the last one there. And then finally, I’m going to have the “Plan Title” here. And so, one thing
that you’ll notice is that while you
specify a plan title, when you go set the “Favorites” the plan or
clients will always go and fix this up whenever
you navigate to those plans to make sure that the plan titles
are up to date. And so in this case, I do have the API demo plan, and let me just go and run that. Okay. So that succeeded. So now, when I go back to
the planner side of things, do click “Refresh” because
it might take a second. I can see that that new
API demo plan that I created is now included in
my “Favorites” as well. Next, I can show a little bit
of how to go and add “Buckets” and “Tasks”
to that same plan. So I start back over here, and then grab the plan ID, and then I’m going to now start posting to
create the buckets. So, creating buckets is pretty
straightforward as well. Let me switch back to “V1”. Sorry. Okay. So if I want to go
and create “Buckets” now, all they do is specify
for each “Bucket”, what the order is and then
the plan that belongs to, as well as the name
of the bucket itself. And so, I’m going to do
that a couple of times. So grabbing that plant idea
again, click over here. So, that’s “Bucket One”. Let me run this. I’m going
to do this two more times, “Bucket Two” and
then “bucket Three”. Okay. And I’m going to now
grab the bucket ID for that last bucket, and we can put a couple
of tasks into it too. Okay. So, if I click over here I should see
my three buckets. Great. And so now, I’m going to go out some
task it that last bucket. So the add tasks, you just post to planner/tasks. And then in this case, you have to specify the title, the plan, the bucket
of that task, and you can also
assign it to people if you want to as well. And so for example, if
I wanted that assign it to the user early on, you can go and do that too. I’m just actually just
remove that for now. And then go and update all
of these to the right info. So, I grabbed my plan ID
from earlier. Now, I’m going to
grab my bucket ID. Then task from API
one, run the query, do that one or two more
times and then three. Okay. And so now,
if I hop back to “Planner”, it might
take a second, but you should be able
to see that I don’t have three tasks pumping
and then “Refresh”. And I have my three tasks
from the API there as well. And now you can go and start
planning as you see “Fit”. That was just a
really quick overview of what you can do with the API. You know, one of
the common things that we see a lot is that if you want to go and set up a plan to
match your structure, a lot of folks have
been using the API to go and specify a set of tasks on a set of buckets to use to go and create
new plans with. Other common scenarios
people also used is to try to go and create task from
other systems within planner, and then you can easily go and collaborate them within
the planner experiences as well as our experiences
within teams and SharePoint. Well, thanks for
taking the time to hear a little bit about
planner API today. Hope you liked what you
saw and want to go and start trying out the
API. Happy planning.

3 thoughts on “Planner APIs in Microsoft Graph”

  1. Could you make a video where you connect to Microsoft Graph through a script without using the Graph Explorer?

    Something like pulling information from the planner maybe

Leave a Reply

Your email address will not be published. Required fields are marked *