{"id":2227,"date":"2018-11-27T11:00:43","date_gmt":"2018-11-27T18:00:43","guid":{"rendered":"https:\/\/developer.microsoft.com\/en-us\/office\/blogs\/?p=2227"},"modified":"2018-11-27T11:00:43","modified_gmt":"2018-11-27T18:00:43","slug":"30daysmsgraph-day-27-use-case-create-a-team","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/microsoft365dev\/30daysmsgraph-day-27-use-case-create-a-team\/","title":{"rendered":"30DaysMSGraph \u2013 Day 27 \u2013 Use case: Create a Team"},"content":{"rendered":"

List of all posts in the #30DaysMSGraph series<\/a><\/p>\n

-Today’s post written by Nick Kramer<\/p>\n

In Day 26<\/a> we concluded calling Microsoft Graph using Flow.\u00a0 Today, we’ll show how to create teams and automate team lifecycles.<\/p>\n

\"\"<\/p>\n

Introduction to Microsoft Teams<\/h2>\n

Microsoft Teams allows people to work together and get projects done by collaborating through chat, calls, and online meetings. Each team has members and owners, channels that contain chat messages, files (stored in SharePoint by default), apps, and tabs. Some of the apps and tabs you might use in a team include OneNote notebooks, Planner plans, and SharePoint lists.<\/p>\n

Teams and Groups<\/h2>\n

Every team is part of a Group. (But not every group has a team!) Some of the information you think of as part of the team is actually part of the Group object, such as the name of the team\/group and its members and owners. When you create a new team, you typically create a new group as well. (But it’s also possible to add a team to an existing group)<\/p>\n

When creating teams and groups, you need the Group.ReadWrite.All scope. Both user delegated permissions and application permissions are supported.<\/p>\n

Clone the Sample Application<\/h2>\n

To follow along with the code please clone the sample application from the contoso-airlines-teams-sample repo<\/a> and follow the instructions in the readme.md file to build the project. The interesting code is in GraphService.cs<\/a>.<\/p>\n

In the Contoso Airlines sample, we create new teams every day for each flight that Contoso Airlines flies — and then archive the team after the flight is over.<\/p>\n

\"\"<\/p>\n

Creating the team<\/h2>\n

Before we create a team, we need the IDs of the team members. Given the user’s universal principle name (UPN), we can retrieve the user’s data, including their ID:<\/p>\n

String userId = (await HttpGet<User>($\"\/users\/{upn}\")).Id;\n\n<\/pre>\n
When we add a user to a team, Graph needs to know the full URL to that user:<\/p>\n
String fullUrl = $\"https:\/\/graph.microsoft.com\/v1.0\/users\/{userId}\";\n\n<\/pre>\n
We repeat that for all the users in the flight crew:<\/p>\n
List<string> ownerIds = await GetUserIds(ownerUpns);\nList<string> memberIds = await GetUserIds(flight.crew);\n\n<\/pre>\n
Armed with that list of users, we can now create the group by providing the display name, mail nickname, description, visibility, owners, and members:<\/p>\n
\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 Group group =\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 (await HttpPost($\"\/groups\",\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 \u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0new Group()\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 {\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 DisplayName = \"Flight \" + flight.number,\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 MailNickname = \"flight\" + GetTimestamp(),\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 Description = \"Everything about flight \" + flight.number,\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 Visibility = \"Private\",\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 Owners = ownerIds,\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 Members = memberIds,\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 GroupTypes = new string[] { \"Unified\" }, \/\/ same for all teams\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 MailEnabled = true,\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 \/\/ same for all teams\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 SecurityEnabled = false,\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 \/\/ same for all teams\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 \u00a0\u00a0\u00a0\u00a0}))\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 .Deserialize<Group>();\n\n<\/pre>\n
This generates a JSON payload of the form:<\/p>\n
{\n\u00a0\u00a0\u00a0 \"displayName\":\"Flight 157\",\n\u00a0\u00a0\u00a0 \"mailNickname\":\"flight157\",\n\u00a0\u00a0\u00a0 \"description\":\"Everything about flight 157\",\n\u00a0\u00a0\u00a0 \"visibility\":\"Private\",\n\u00a0\u00a0\u00a0 \"groupTypes\":[\"Unified\"],\n\u00a0\u00a0\u00a0 \"mailEnabled\":true,\n\u00a0\u00a0\u00a0 \"securityEnabled\":false,\n\u00a0\u00a0\u00a0 \"members@odata.bind\":[\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 \"https:\/\/graph.microsoft.com\/v1.0\/users\/bec05f3d-a818-4b58-8c2e-2b4e74b0246d\",\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 \"https:\/\/graph.microsoft.com\/v1.0\/users\/ae67a4f4-2308-4522-9021-9f402ff0fba8\",\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 \"https:\/\/graph.microsoft.com\/v1.0\/users\/eab978dd-35d0-4885-8c46-891b7d618783\",\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 \"https:\/\/graph.microsoft.com\/v1.0\/users\/6a1272b5-f6fc-45c4-95fe-fe7c5a676133\"\n\u00a0\u00a0\u00a0 ],\n\u00a0\u00a0\u00a0 \"owners@odata.bind\":[\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 \"https:\/\/graph.microsoft.com\/v1.0\/users\/6a1272b5-f6fc-45c4-95fe-fe7c5a676133\",\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 \"https:\/\/graph.microsoft.com\/v1.0\/users\/eab978dd-35d0-4885-8c46-891b7d618783\"\n\u00a0\u00a0\u00a0 ]\n}\n\n<\/pre>\n
(Note the members@odata.bind syntax to provide references to existing resources, in this case users)<\/p>\n
The next step is to create a team within the group:<\/p>\n
await HttpPut($\"\/groups\/{group.Id}\/team\",\n\u00a0\u00a0\u00a0 new Team()\n\u00a0\u00a0  {\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 GuestSettings = new TeamGuestSettings()\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0{\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 AllowCreateUpdateChannels = false,\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 AllowDeleteChannels = false\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0}\n\u00a0\u00a0\u00a0 },\nretries: 3, retryDelay: 10);\n\n<\/pre>\n
We could pass an empty body to PUT \/groups\/{group.Id}\/team, but we prefer to change some of the default settings \u2013 we don’t want guests to be able to create, update, or delete channels. Note also that sometimes when the team is created immediately after the group, that request can fail with a 404 because the necessary data hasn’t replicated to all data centers, so we retry in that case after a 10 second delay.<\/p>\n
Note that the team has the same ID as the group:<\/p>\n
string teamId = group.Id; \/\/ always the same<\/pre>\n
Channels<\/h2>\n
Teams contain a list of channels, which contain the team’s chat messages. Channels also have a Files tab (typically linked to SharePoint), as well as any additional tabs you want to add to the team. Let’s create a channel for pilot talk:<\/p>\n
Channel channel = (await HttpPost(\n\u00a0\u00a0\u00a0 $\"\/teams\/{teamId}\/channels\",\n\u00a0\u00a0\u00a0\u00a0new Channel()\n\u00a0\u00a0\u00a0\u00a0{\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0 DisplayName = \"Pilots\",\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0Description = \"Discussion about flightpath, weather, etc.\"\n\u00a0\u00a0\u00a0 }\n)).Deserialize<Channel>();\n\n<\/pre>\n
When you create a channel with POST \/teams\/{teamId}\/channels, Graph returns the created channel so you know its ID.<\/p>\n
Tabs<\/h2>\n
Let’s add a tab to channel that shows a map of the airport. Every tab has an associated app, for a map we can use the Website app. We know from documentation<\/a> that the app ID for the Website app is “com.microsoft.teamspace.tab.web”. Graph will want that as a reference:<\/p>\n
var appReference = $\"https:\/\/graph.microsoft.com\/v1.0\/appCatalogs\/teamsApps\/{appid}\";\n\n<\/pre>\n
Using that, we can create the tab:<\/p>\n
await HttpPost($\"\/teams\/{teamId}\/channels\/{channel.Id}\/tabs\",\nnew TeamsTab()\n{\n\u00a0\u00a0\u00a0\u00a0DisplayName = \"Map\",\n\u00a0\u00a0\u00a0\u00a0TeamsApp = appReference, \/\/ It's serialized as \"teamsApp@odata.bind\" : appReference\n\u00a0\u00a0\u00a0\u00a0Configuration = new TeamsTabConfiguration()\n\u00a0\u00a0\u00a0\u00a0{\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0EntityId = null,\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0ContentUrl = \"https:\/\/www.bing.com\/maps\/embed?h=800&w=800&cp=47.640016~-122.13088799999998&lvl=16&typ=s&sty=r&src=SHELL&FORM=MBEDV8\",\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0WebsiteUrl = \"https:\/\/binged.it\/2xjBS1R\",\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0RemoveUrl = null,\n\u00a0\u00a0\u00a0 }\n});\n\n<\/pre>\n
In the configuration section of the tab, there’s four properties that every tab has \u2013 the EntityID, the ContentURL, the WebsiteUrl, and the RemoveURL. At its core, a tab is an HTML rendering surface \u2013 and ContentURL is the HTML the render. WebsiteUrl is the HTML the show if the user clicks the “Go to website” button. RemoveUrl is the HTML shown when the user clicks the Remove button. And EntityId is a string that means something only to the app that powers the tab (in this case, the website app leaves it null) \u2013 again, see the docs<\/a> for your favorite app.<\/p>\n
Create a SharePoint list<\/h2>\n
Next, let’s create a SharePoint list of the problem passengers on the flight, and pin it to a tab. We’ll need some additional permission scopes in order to use SharePoint: Sites.ReadWrite.All and Sites.Manage.All. With those, we can get to the SharePoint site using the group:<\/p>\n
var teamSite = await HttpGet<Site>($\"\/groups\/{groupId}\/sites\/root\",\nretries: 3, retryDelay:30);\n\n<\/pre>\n
(Again, there can be replication issues if you access the site to quickly after creating the group, so we put in some retries)<\/p>\n
Once we have the site, we can create a new SharePoint List with 3 columns, Name, SeatNumber, and Notes:<\/p>\n
var list = (await HttpPost($\"\/sites\/{teamSite.Id}\/lists\",\nnew SharePointList\n{\n    DisplayName = \"Challenging Passengers\",\n    Columns = new List<ColumnDefinition>()\n    {\n        new ColumnDefinition\n        {\n            Name = \"Name\",\n            Text = new TextColumn()\n        },\n        new ColumnDefinition\n        {\n            Name = \"SeatNumber\",\n            Text = new TextColumn()\n        },\n        new ColumnDefinition\n        {\n            Name = \"Notes\",\n            Text = new TextColumn()\n        }\n    }\n}))\n.Deserialize<SharePointList>();\n\n<\/pre>\n
That creates an empty list with those columns. Next we add some data to it:<\/p>\n
await HttpPost($\"\/sites\/{teamSite.Id}\/lists\/{list.Id}\/items\",\n    challengingPassenger\n    );<\/pre>\n
 <\/p>\n
Then we add a tab to the channel we created earlier:<\/p>\n
await HttpPost($\"\/teams\/{groupId}\/channels\/{channelId}\/tabs\",\n    new TeamsTab\n    {\n        DisplayName = \"Challenging Passengers\",\n        TeamsApp = appReference, \/\/ It's serialized as \"teamsApp@odata.bind\" : appReference\n        Configuration = new TeamsTabConfiguration\n        {\n            ContentUrl = list.WebUrl,\n            WebsiteUrl = list.WebUrl\n        }\n    });\n\n<\/pre>\n
And now we have a fully functioning team, with members, channels, and tabs.<\/p>\n
\"\"<\/p>\n
Apps<\/h2>\n
With user delegated permissions, you can also add an app to the team. (We are working on application permissions) Let’s add the SurveyMonkey bot to the team. We need to know the app ID of the app we want, we can figure that out by running this in Graph Explorer:<\/p>\n
GET<\/strong> https:\/\/graph.microsoft.com\/beta\/teams\/{sampleTeam.id}\/installedApps?$expand=teamsAppDefinition&filter=teamsAppDefinition\/displayName eq 'SurveyMonkey'\n\n<\/pre>\n
where {sampleTeam.id} is a test team that you added SurveyMonkey to using Microsoft Teams. Look for the teamsAppId in the response.<\/p>\n
Now, using that value, we install survey monkey to the new team:<\/p>\n
await HttpPost($\"\/teams\/{team.Id}\/installedApps\",\n    \"{ \\\"teamsApp@odata.bind\\\" : \\\"\" + graphV1Endpoint + \"\/appCatalogs\/teamsApps\/\" + teamsAppId + \"\\\" }\");\n<\/pre>\n
\"\"<\/p>\n
Clone a team<\/h2>\n
Alternately, instead of creating a team from scratch, we can make a copy of an existing team. This is a good way to allow admins and end users to change the structure of the team you’re creating without having to update code. Clone Team also supports application permissions, so it’s a great way to get new teams with apps preinstalled.<\/p>\n
When you clone a team, you get to pick which parts you want to clone. Your choices are apps, settings, channels, tabs, and members. We’ll choose “apps,settings,channels”:<\/p>\n
var response = await HttpPostWithHeaders($\"\/teams\/{flight.prototypeTeamId}\/clone\",\n    new Clone()\n    {\n        displayName = \"Flight 4\" + flight.number,\n        mailNickName = \"flight\" + GetTimestamp(),\n        description = \"Everything about flight \" + flight.number,\n        teamVisibilityType = \"Private\",\n        partsToClone = \"apps,settings,channels\"\n    });\n\n<\/pre>\n
Clone is a long-running operation, so we are actually creating a clone request and getting back a handle to check on its status. The critical part of the response is the Location header:<\/p>\n
string operationUrl = response.Headers.Location.ToString();\n\n<\/pre>\n
We query that operationUrl to see if the cloning is done. If it’s not, we wait 10 seconds and repeat.<\/p>\n
for (; ; )\n{\n    TeamsAsyncOperation operation = await HttpGet<TeamsAsyncOperation>(operationUrl);\n    if (operation.Status == AsyncOperationStatus.Failed)\n        throw new Exception();\n\n    if (operation.Status == AsyncOperationStatus.Succeeded)\n    {\n        teamId = operation.targetResourceId;\n        break;\n    }\n\n    Thread.Sleep(10000); \/\/ wait 10 seconds between polls\n}\n\n<\/pre>\n
Then, because we chose not to clone the membership, we need to add some people to the team:<\/p>\n
\/\/ Add the crew to the team\nforeach (string id in flight.crew)\n{\n    string payload = $\"{{ '@odata.id': '{graphV1Endpoint}\/users\/{id}' }}\";\n    await HttpPost($\"\/groups\/{teamId}\/members\/$ref\", payload);\n    if (upn == flight.captain)\n        await HttpPost($\"\/groups\/{teamId}\/owners\/$ref\", payload);\n}<\/pre>\n
And that gives us a fully functioning team, with members and apps.<\/p>\n
Archive<\/h2>\n
Finally, after the flight is over and we are done with the team, we can archive it. This will put the team into a read-only state and hide it from our list of teams so our UI doesn’t get cluttered, but we can still read the contents of the team via the gear icon at the bottom of the screen:<\/p>\n
\"\"<\/p>\n
Like clone, archiving is a long-running operation, so we will create an archiving request and monitor its status:<\/p>\n
HttpResponse response = await HttpPostWithHeaders($\"\/teams\/{teamId}\/archive\", \"{}\");\nstring operationUrl = response.Headers.Location.ToString();\n\n<\/pre>\n
And like clone, we query that operationUrl to see if the archiving is done:<\/p>\n
for (; ; )\n{\n    var operation = await HttpGet<TeamsAsyncOperation>(operationUrl);\n\n    if (operation.Status == AsyncOperationStatus.Failed)\n        throw new Exception();\n\n    if (operation.Status == AsyncOperationStatus.Succeeded)\n        break;\n\n    Thread.Sleep(10000); \/\/ wait 10 seconds between polls\n}\n\n<\/pre>\n
And there we go \u2013 we’ve shown how to create a new team, set it up with channels, tabs, and apps, and when the team has outlived its usefulness, how to archive it to make room for the next team.<\/p>\n
Try it Out<\/h2>\n
Day 27 repo link<\/a><\/p>\n