>> 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.