Wednesday, 14 September 2022

Partially update documents in Azure Cosmos DB

I have been working with Cosmos DB for a while now and until recently, there was one thing which always annoyed me: When updating a JSON document stored in a container, there was no way to only modify a few selected properties of the document. 

The entire JSON document had to be fetched by the client first, then locally replace the properties to be updated, and then send the entire document back to Cosmos DB and replace the previous version of the document. 

This was always a challenge because first, it added more work for developers and second, there could be concurrency issues if multiple clients could be downloading multiple copies of the document and updating the data and sending back their copy.

But fortunately, now it's possible to partially update a document in Cosmos DB and basically do a PATCH operation while only sending the properties to be changed over the wire. 

So in this post, let's have a look at the different ways in which we can partially update documents in Cosmos DB:

Setting up by creating a Cosmos DB document

First, we will create our sample document using code. I should mention I am using v3.30.1 of Azure Cosmos DB .NET core package from nuget: Microsoft.Azure.Cosmos

As you can see this is a simple document representing a User object with a few attached properties:

Now in order to only change a few properties in the object, we need to use the Partial document update feature in Azure Cosmos DB 

Update document properties

Now lets have a look at how we can modify and add properties to the User object:

In the code, we are updating an existing property of the document as well as adding a new property. Also, we are only sending the properties to be modified over the wire. 

We can also send both properties in a single operation by adding the operations to the patchOperations array.

Update elements in array

Just like document properties, we can also update single elements in an array in the document. Elements can be updated, added, added at a specific index and also removed from an array:

Update objects and their properties

The properties of a JSON document can themselves be objects as well. The Azure Cosmos DB patch operations can also be used to update properties of specific objects as well as modifying the objects themselves.

Hope this helps! For more details, do have a look at the Microsoft docs for Azure Cosmos DB partial updates:

Monday, 7 February 2022

Working with the Microsoft Graph communications API in a Microsoft Teams meeting app

Following up on my previous post about Microsoft Teams meeting apps, let's now have a look at how we can invoke the Microsoft Graph in our meeting app. 

Specifically, we will be using the Microsoft Graph communications API to get all meeting participants.

When I was first looking at this scenario, I thought it would be quite straightforward as this seems to be quite a common use case for meeting apps. However, I was in for a bit of a surprise as that did not turn out to be the case. 

My thinking was that I would get a meetingId as part of the Teams JS SDK context object and I would use this meetingId to get details from the Graph. But it turns out that the meetingId which the Teams JS SDK provides is completely different than the meetingId recognised by that Microsoft Graph

To fetch the meetingId which the Graph recognises, we have to introduce the Bot Framework SDK to the mix and exchange the Teams JS SDK meetingId for the Graph meeting Id. 

So let's see how to achieve this using code:

1) Using Teams JS SDK, get user id, meeting id, tenant id

This bit is straightforward, in your Teams tab you can get the meeting context using the Teams JS SDK:

2) Use Bot SDK to get Graph meeting ID from the Teams meeting id

Next, from your Teams Bot, call the /v1/meetings/{meeting-id} API. Couple of things you should know beforehand: 

This API is currently in developer preview. This means that it will only work for when the Microsoft Teams Clients have been switched to preview mode.

Secondly, we have to turn on Resource Specific Consent (RSC) for your app and request the required scopes. More details on both points here:

Once you have everything setup, you can call the API to get the meeting details:

The response would contain a details object with an msGraphResourceId property. This will be the meeting id which would work with the Graph API.

3) Use Graph API to get meeting participants from Graph meeting id

Finally, from the msGraphResourceId, we can make a regular call to the Graph to get the meeting details. Specifically, we will call the /onlineMeetings/{meetingId} endpoint:

In this case, we will get the meeting participants:

Make sure you have the correct Delegated or Application permissions granted to the Azure AD app registration you are using for authenticating to the Graph.

This is not an ideal situation as you might not have a requirement for a Bot in your Teams app and might be building a tab for example. In this case, Yannick Reekmans has written a post for you here:  

That's it for now. Hope you find this helpful when exploring meeting apps right now.

Thursday, 13 January 2022

Working with Apps for Microsoft Teams meetings

Microsoft Teams meetings extensions or "Apps for Teams meetings" are the newest entry in the Microsoft Teams extensibility story. They can be used to build custom experiences right into the meeting experience. Meeting participants are able to interact with the custom experiences either before, during or after the meeting. To know more about apps for Teams meetings, a great place to start is the Microsoft docs:

Pre-meeting and Post-meeting experiences

The pre and post meeting experiences are not too different than what we are used to when building Tabs for Teams. The basic structure remains the same with the only different thing being that the Teams SDK provides the meeting specific APIs when invoked from a meeting app. These APIs can be used to get meeting details like participants and meeting context in our app. More information on the APIs here:

In-meeting experiences

When it comes to the In-meeting experiences, there are two main areas: The side panel and the in meeting dialog box (also known as content bubble). The side panel is used to show custom experiences while the meeting is in progress

And the in-meeting dialog box (or content bubble) is used to show content, prompt or collect feedback from the users during the meeting:

I should mention here that the In-meeting experiences only work in the Teams desktop and mobile clients as of now. They don't work in the Teams web browser interface at the time of this writing. To me this is the biggest challenge for using them in production.

Now that's enough introduction of the concepts, let's take a look at how to actually build these experiences and what are the moving pieces when building them. The Microsoft docs do provide some great step by step tutorials for each of the use cases. 

In this post we will look at the In-meeting dialog box. We will take a look at the Microsoft's code sample and walk through it. You can find the code sample here:

1) Configure an Azure Bot and enable Teams Channel

Create a bot in Azure and configure the endpoint which should receive the Teams events:

Next, add the Teams channel so that the bot is able to talk to Microsoft Teams:

2) Update the Teams manifest

For the In-meeting dialog box, we don't have to make any special changes in the manifest. We just need to make sure that since the dialog box will be shown via the bot, our Teams app manifest should have the bot configured as part of it. 

3) Create an Azure AD app registration for the app

When we created the Azure Bot, a new Azure AD app registration was created behind the scenes as well. Grab the client id and client secret from this app as we would need it later to add to our bot config

4) Start the ngrok tunnel and update the code sample:

To debug locally, you will need to setup an ngrok tunnel to your local machine. More details here:

And in the code sample, update the bot client id and client secret along with the ngrok tunnel url:

5) In meeting dialog code:

The way to bring up an in-meeting dialog is to use the regular Bot Framework turnContext.SendActivityAsync(activity) code but with updated Teams channel data:

You will notice that in the In-meeting dialog url, there is a reference to {_config["BaseUrl"]}/ContentBubble 

This means that the contents of the in-meeting dialog have to be hosted in our app. This is good news as that means we have complete control over what is displayed in the dialog. In this code sample, the contents are hosted in an MVC view:

And once everything fits together, we can see the sample code running to show an In-meeting dialog launched in the context of a meeting:

Hope this helps, and thanks for reading!

Thursday, 16 December 2021

Building a Microsoft Teams bot: Sending custom data from an adaptive card button to the bot

This is the third article in my "Building a Microsoft Teams Bot" series. In this series, I have written down some interesting things I came across while creating a Microsoft Teams Bot app which is now available on AppSource:

Click here to see the previous articles in the series: 

Building a Microsoft Teams Bot: Posting an Adaptive Card carousel as a welcome message

Building a Microsoft Teams Bot: Deep linking to a Teams message from an Adaptive Card button

Todays article is around how to pass custom data from Adaptive Cards back to the Teams bot. This can be useful in scenarios when we want to show multiple options to the user in an Adaptive card and when the user selects an option, we want to send that option back to the bot and perform a relevant operation.

To achieve this, we will use the data property of the Adaptive Card Submit action: 
This property contains a key value pair of custom data which can be sent back to the bot. 

Here is a sample of how the card json will look when posting it to Teams:

To build this type of card in our bot code, we will iterate over the options and create Adaptive card Submit buttons with the relevant values in the data property:

And finally, when the user clicks on a button, Teams platform will send the corresponding data property back to the bot. This can then be used in the Submit action of the bot to perform a relevant operation.

Hope this was helpful!

Tuesday, 16 November 2021

Interactively authenticate Microsoft Graph .NET SDK with Azure Identity library

In this post, we will have a look at the new recommended way of using the Azure Identity library to authenticate to the Microsoft Graph .NET SDK. Since v4 of the Microsoft Graph SDK, using the Azure.Identity library is the preferred way to auth with the Graph over the previous Microsoft.Graph.Auth method. You can read more about it here:

Specifically, we will have a look at Interactive browser based authentication where the user would enter their credentials and the Azure Identity library will fetch the access token based on them.

Before going through the code, let us check out the Azure AD App registration which would be used to authenticate to the Graph API

Since we are going to authenticate from a .NET Desktop console application, we will select Desktop as a platform and add the default redirect URIs. In addition, we will also add http://localhost to the list.

The supported account types can be as per your requirements. I have selected the app to be multi tenant.

Select the Allow public client flows to "Yes":  

Select the needed scopes:

Once all of this in place, we can use the following code to open a browser window and authenticate to the Microsoft Graph once the user enters their credentials:

If this is the first time logging into this tenant, you will need to grant permissions to the app:

Once the authentication happens, you will see a similar message in the browser:

and our console window logs the current access token along with the expiry time and also uses the Graph SDK to get the display name of the current user:

Hope that helps!

Tuesday, 9 November 2021

Building a Microsoft Teams Bot: Deep linking to a Teams message from an Adaptive Card button

This is the second article in my "Building a Microsoft Teams Bot" series. In this series, I am planning to write down some interesting things I came across while creating a Microsoft Teams Bot app which is now available on AppSource:

Click here to see the previous article in the series: Building a Microsoft Teams Bot: Posting an Adaptive Card carousel as a welcome message

Todays article is around how to create deep links to teams messages from Adaptive cards. This can be useful in scenarios when you want to send users to a specific Teams chat message when they click on an Adaptive Card button:

If you are building the deep link manually, it can be grabbed from the "Copy link" button from the ellipsis menu in a Teams message:

Deep links to personal chats are in a different format compared to channel messages.
For Teams messages, the deep link format is:{ChannelId}/{messageId}

For personal chats, the deep link format is:{userAadObjectId}_{botId}@unq.gbl.spaces/{messageId}?context=%7B%22contextType%22:%22chat%22%7D

For bots and messaging extensions, this deep link can be built from parts of the payload sent to the Bot from the Teams platform when the bot is invoked:

Once you have the desired deep link, the next step is to assign it as the URI to an Adaptive Card button:

And that's it! Now you can easily add buttons to your adaptive cards which take the user to specific messages in Teams personal chats or channels. 

Hope this was helpful!

Monday, 1 November 2021

Working with MSAL and multiple Azure AD accounts in a React SPA

I came across an interesting scenario recently: I was working with a React SPA which used Azure AD for authenticating users, and it needed to work with multiple accounts logged in simultaneously. Specifically, we were building an Azure AD multi tenant application which needed to login to multiple M365 and Azure tenants and allow the user to manage all tenants at the same time.

The good thing was that MSAL v2 does support working with multiple accounts at the same time. So in this post, let's see how we are able to do that in a React SPA with MSAL js.

Before looking at the code, we would need to create a multi tenant Azure AD app which would be used to sign in to the different tenants. Step by step instructions can be found here:

Once this is in place, we can start looking at the code itself. I have take the MSAL React tutorial as the starting point for this code and modified it to work with multiple accounts. If you want to build it from scratch, this would be a good starting point:

The very first thing we would need is to setup the configuration for our app: 
You will notice the authority is set to the /organizations end point. This is because our app is a multi-tenant app which would be used to login to different tenants.

With the config, we will now initiate a PublicClientApplication in the index.tsx file:

Now lets get to the most important App.tsx file: 

There are multiple things happening here. Let's unpack them one by one. 

First, we are using the MSAL react useMsalAuthentication hook to setup the authentication and get the login method which we will use later.

What is also important is the prompt: 'select_account' property in the request which would help us login with a new account when we are already signed in with one account.

The AuthenticatedTemplate and UnauthenticatedTemplate MSAL react components help us display different views when at least one user is logged in or no user is logged in respectively.

Next, lets look at the ProfileContent.tsx component:

Based on the homeId of passed in to this component as a property, we are using the PublicClientApplication.acquireTokenSilent method to first get the access token of the relevant user. 

Once the accessToken is fetched, we are making a call to the Microsoft Graph to get the basic details of the user. We are using the callMsGraph function for this.

The ProfileData component takes in all properties fetched from the graph and displays it.

The handleLogout function uses the PublicClientApplication.logoutRedirect function to log out the specific user.

So after everything is in place, we would be able to work with multiple users logged in simultaneously at the same time.

Hope this helps! 

As always, the code for this post can be found on GitHub: