How to add an existing or new Whiteboard to a team channel using Graph API

When you use out of the box feature to add a Whiteboard app to team channel it always creates a new Whiteboard. Using Graph API it is possible to add an existing or a new Whiteboard to team channel. This enables to re-use Whiteboards or recovering an accidentally removed Whiteboard tab.

In my earlier blog post I explained how you can add a Whiteboard to a team channel as a tab (app). It is something anyone can do since you just click around the UI. I recently got a question (could a whiteboard be added using Graph API) I went and checked out would it be possible.

Some key things you need to have there are:

Adding an existing Whiteboard to a team using Graph API

In addition to info above you need

  • Whiteboard ID is identifying your whiteboard. You can retrieve it in the easiest way by opening the whiteboard in web version and looking at URL. The whiteboard ID is following /whiteboards/
  • displayName: name of your tab.
  • Content URL is a link to the whiteboard + instructions how to open the Whiteboard inside a tab embed=1&isOpenInTab=1
  • Website URL is needed when the user clicks on the globe to open the tab app in a browser

This is the JSON you need to put to Graph API POST request payload:

{
             ”displayName”: ”Whiteboard via Graph API”,
             ”teamsApp@odata.bind”: ”https://graph.microsoft.com/v1.0/appCatalogs/teamsApps/95de633a-083e-42f5-b444-a4295d8e9314”,
             ”configuration”: {
                          ”entityId”: ”whiteboard.microsoft.com”,
                          ”contentUrl”: ”https://app.whiteboard.microsoft.com/me/whiteboards/[yourwhiteboardid]?embed=1&isOpenInTab=1”,
                          ”removeUrl”: null,
                          ”websiteUrl”: ”https://app.whiteboard.microsoft.com/me/whiteboards/[yourwhiteboardid]”
             }
}

To add the tab you need to use the good old Add a tab to a channel. You need to know the team and channel ID before calling POST https://graph.microsoft.com/v1.0/teams/{id}/channels/{id}/tabs
This call requires several permissions, check up to date ones from the Add a tab documentation. Of course if you are adding tabs to team channels then you have these set up already.

I used delegated permissions during testing this out – using Graph Explorer.

There are still some more permissions to add..

Of course the board will work very well.. for you. But concerning other members of the team they see the following if you don’t do anything else..

You need to open Whiteboard Desktop application and add all team members as participants to the Whiteboard separately.

You can alternatively create a sharing link to the board and guide members to click it in the web to activate their permissions to the board. The link can be easily created via Web Whiteboard.

Are there real use cases for this?

Yes, there are! Using this little trick you can insert an existing Whiteboard to a team. I see three good use cases for this one:

  • This can be useful in case you want to continue using the meeting Whiteboard but in a team. It might be safe to think that most of people will have access to the board and the rest can be managed via the sharing link or adding explicit permissions
  • Somebody removed the Whiteboard tab from team channel and you want it back. Currently this is an issue when you add a Whiteboard app to a team channel: it only creates a new Whiteboard
  • You have started to work on a Whiteboard without a connection to a team. This is similar to the first use case

What about custom provisioning a Whiteboard?

Of course there is a way to add a Whiteboard to a team when provisioning it! You can use Team templates or .. you can add it via Graph API. Keep reading and skip Team template part if you want Graph API instead of mouse clicks!

When adding a Whiteboard app via provisioning (or adding that to a team later with a script) it also takes care of any permissions out of the box as opposed when adding an existing Whiteboard to a team via Graph API.

Using Team Template

If you want a Whiteboard to a team channel when a new team is provisioned then you could consider using Team templates for that. You can add apps to channels in there – they are just placeholders but it can create a new Whiteboard when team is provisioned.

And when the Team is provisioned with this template team owner (usually that person is the first one to go through channels and tabs) can add the new Whiteboard to the team channel.

Using Graph API to add Whiteboard app during provisioning (or adding via script)

It is actually fairly simple to add Whiteboard (or any other application channel tab) during provisioning with a little Graph API. After all – we only need to know the Team App ID for the application.

  1. Add that application to the team using Add app to team. POST /teams/{team-id}/installedApps
  2. Add application app tab without content details

POST https://graph.microsoft.com/v1.0/teams/{id}/channels/{id}/tabs

{
             ”displayName”: ”Whiteboard”,
             ”teamsApp@odata.bind”: ”https://graph.microsoft.com/v1.0/appCatalogs/teamsApps/95de633a-083e-42f5-b444-a4295d8e9314”,
             ”configuration”: {
                          ”entityId”: null,
                          ”contentUrl”: null,
                          ”removeUrl”: null,
                          ”websiteUrl”: null
             }
}


The secret is in the TeamsApp@odata.bind section that defines “Whiteboard application goes here”.

If you have a custom provisioning of teams in place you might want to update it to include Whiteboard tabs as well.

One thought on “How to add an existing or new Whiteboard to a team channel using Graph API

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.