Using optional query parameters with Microsoft Graph API – Part 1

How to use optional OData query parameters while working with MS Graph API

In this article, I will explain how to execute the calls to Microsoft Graph API using some optional OData query parameters.

The objectives of this article are:

  • What are the optional OData query parameters?
  • List of supported OData query parameters, when to use which one
  • Execute some Graph API calls using query parameters

While Microsoft already has the documentation to cover all its technology, in this article, I will try to explain these OData query parameters with some different angles and usage scenarios. I’m sure you will enjoy reading this article and learn something new.

Background

This article shows how you can fire some calls to MS Graph API using optional query parameters with the MS Graph Explorer available here:

Office Development

In my previous articles, I explained the different components of Microsoft Graph Explorer and showed how to execute MS Graph API calls using the sample account. I suggest you read those articles too for better understanding MS Graph API Explorer.

You can read my previous articles on MS Graph API Explorer here:

What are the Optional Query Parameters?

The current version of Microsoft Graph API supports the OData version 4.0 standard. This OData standard defines how the data is exchanged between the originator and the consumer of the REST APIs.

Look at the format of an API endpoint in Microsoft Graph API:

Office Development

Here “query-parameters” is an optional set of parameters to modify the response/output of API calls. It always starts with $ sign. (Please note here that in the beta version of MS Graph API, using $ is now optional. We will see that later in the article). Query parameters start after “?” sign.

The Microsoft Graph API documentation here describes the optional query parameters as:

“You can use optional query parameters to customize the response in your Microsoft Graph app. Use query parameters to include more or fewer properties than the default response, filter the response for items that match a custom query, or provide additional parameters for a method.”

The OData standards specification on www.odata.org defines the optional query parameters as “System Query Options” which are explained in great detail here.

The ODATA standards specification explains these query parameters as:

“System Query Options are query string parameters a client may specify to control the amount and order of the data that an OData service returns for the resource identified by the URI. The names of all System Query Options are prefixed with a “$” character.

An OData service may support some or all of the System Query Options defined. If a data service does not support a System Query Option, it must reject any requests which contain the unsupported option…”

In short, using these optional query parameters in the API endpoint query string you can define the criteria applicable on the result. And these parameters are optional meaning if you don’t mention any of them in the query string, then also the API call works fine.

If you are not aware of OData standard, then I suggest you to spend some time on reading about the OData specification on the odata.org website here for better understanding of OData concepts.

List of supported query parameters in Microsoft Graph API

The following query parameters are supported in the current version of Microsoft Graph API:

  • $count
  • $expand
  • $filter
  • $orderby
  • $search
  • $select
  • $skip
  • $skipToken
  • $top

A complete list with details can be found on Microsoft Graph API documentation website here.

Let’s now see each of the above query parameters one by one in detail and fire queries in Microsoft Graph API Explorer.

I will explain them in increasing order of complexity of understanding.

(1) $top

Explanation

This parameter will fetch only certain number of data items as specified along with $top.

At times, you will not need to fetch all the items from the result set, but only first few of them. In this case, $top query parameter is used to specify how many items should be returned in the result.

Usually, $top query parameter is used with $orderby query parameter (Read more about $orderby in section 3 below).

Example

Open MS Graph Explorer here and fire following calls

Notice the amount of data being returned in results in the above calls. In real life API call execution, it will return the current user’s emails and all files on his/her OneDrive. This may not be required always, and returning these many items may not be best suited option performance-wise too.

When you want to see only some limited number of records, at that time you can use $top.

Go to MS Graph Explorer here and fire the following call:

https://graph.microsoft.com/v1.0/me/messages?$top=2 or click here, then press “Run Query”.

You will see only two result items, not the list of all messages,

Office Development
Note: I have collapsed the JSON result in above screenshot to show items fit in one screen.

Usage

In your programming, you can use $top query parameter to:

  • Show recent/latest/top items from a list of items
  • Implement paging (often used with $skip and $orderby)

(2) $count

Explanation

This parameter will fetch the total number/count of data items in the specified API endpoint along with the result.

Note that the API call will return the result “as it is” without this query parameter, but if this parameter is specified, then in addition to the result, a number indicating the result count is also returned.

You will see the result count in @odata.count property in response JSON.

Example

Open MS Graph Explorer here and fire following call to get list of emails

It will show the following result,

Office Development

Notice here as highlighted in above screenshot, MS Graph API will return to you the count of emails as the value of property @odata.count.

Fire more calls in MS Graph Explorer to understand the $count parameter as shown below

You will see MS Graph Explorer does not return any count or does not return any error, it simply returns a valid result. If the $count parameter is not applicable on the API endpoint it will ignore it.

I leave it to you now to try and explore the $count parameter with different Graph API calls.

Usage

In your programming, you can use $count query parameter to:

  • Get the no. of result items in the result, along with result item(s)

(3) $orderby

Explanation

This parameter will make the Graph API return the result in a specific sorting order. Sometimes, you will want your result from MS Graph API to be sorted in a certain order depending on the date or name or some other property of the resource being returned. Use $orderby parameter in those cases to get your result sorted in certain order.

Example

Open MS Graph Explorer here and fire following call to get all users.

You will see all the organization’s users are returned here. They are in the order of email address. You may want to have the result ordered by another property, let’s say display name.

Execute the following call

You will see the list of users is ordered by the display name of user,

Office Development
Note: In above screenshot only one result fits in the screen. Try scrolling the response view by yourself to see all the items.

The default order by is done in ascending order. If you want to order by descending order, then specify “desc” in the URL separated by a space.

Execute the following call,

You will see the list is now ordered descending by the display name:

Office Development

Usage

In your programming, you can use $orderby query parameter to:

  • Get an ordered list of result items, based on certain property
  • Get emails, events, other items in ascending or descending sort order

(4) $skip

Explanation

This query parameter tells the MS Graph API to omit the number of records as specified along with $skip from the result set. MS Graph API will follow the same sorting order it follows (if $orderby is not specified) and will omit that many number of records from the result as specified in the query string.

Example

Open MS Graph Explorer here and fire following call to get the list of contacts:

It will show the result with all contacts of sample account. Note the result’s “displayName” values for first 4 records (they start with “A”).

Now run the following query to skip first 4 records from result

You will see the result without those first 4 contacts,

Office Development

MS Graph API has omitted first 4 records from the result set.

What happens when we specify a skip count greater than no. of records in the result? Let’s find out.

Run the following query to skip 10000 records from result

We know there are no more than 10000 contacts in the sample account. This is the result you will get, it simply returns an empty set

Office Development

Usage

In your programming, you can use $skip query parameter to:

  • Omit the first few items from a list of items
  • Implement paging (often used with $top and $orderby)

We will see the rest of the parameters in next article. Until then you can go to MS Graph Explorer and try the above examples by yourself.

You can also read more of my MS Graph API articles here.

 

This article was first published by me on C# Corner Website here.

Header image courtesy: Microsoft

Office 365 Development with Visual Studio 2017 – Part 2

When Visual Studio 2017 was launched earlier this year, I wrote an article to provide a glimpse of how to get started with Office 365 development with VS 2017 and different project templates available in VS 2017. You can read it here.

Let’s continue our journey of Office 365 development with VS 2017 in this article.

Objectives

In this article, we will walk through creating and running Office 365 projects in VS 2017. Along with that, I will explain Office 365 Add-in concepts side by side.

We will learn the following in this article.

  • Creation of Excel add-in projects
  • Brief intro of Office 365 Add-in
  • When you should choose which type of project

Prerequisite

This article assumes that you already have installed Visual Studio 2017 with Office 365 development option on your PC. If not, then please read part-1 and follow the installation steps. You will not see the project templates mentioned in this article if you don’t have the correct version of Visual Studio with Office 365 development option.

To make sure which version of Visual Studio you are using, go to “Help” menu and select “About Microsoft Visual Studio” sub-menu in Visual Studio.

Make sure you are using Visual Studio 2017.

Office Development

I’m using Community edition of VS 2017 which is “Free, fully-featured IDE for students, open-source and individual developers”.

Office Development
Image credit: Microsoft

You can download VS 2017 Community edition here.

The Office 365 development options are same in all editions of VS 2017, namely Community, Professional, and Enterprise. So, it will not matter whichever edition of VS 2017 you have for following the steps of this article.

Getting Started

Let’s start with creating a new Office 365 project for the add-in.

Either click on the menu “File” -> “New” -> “Project” or on the “Start Page” under “New Project” section, click on “Create new project…”:

Office Development

In the “New Project” popup, expand “Office/SharePoint” category under Visual C# and click on “Add-ins”.

Office Development

You will see project templates for Word, Excel, PowerPoint, Outlook, and SharePoint add-in.

Let’s briefly understand about Office 365 add-ins.

What is Office 365 add-in?

With Office 365 add-in or Office add-in, you can build program/solution that extends Office applications and interacts with the content in Office documents. You can add new functionality to Microsoft Office clients or create new rich, interactive objects that can be embedded in Microsoft Office documents. Office add-in runs in Microsoft Office across multiple platforms, including Office for Windows, Office Online, Office for the Mac, and Office for the iPad.

For more information on Office 365 add-ins, read on Microsoft website here. I will cover more on Office 365 add-ins in a separate article later.

In the New Project popup, select “Excel Web Add-in”, then click OK.

You will see a “Create Office Add-in” dialog with following two options:

  • Add new functionalities to Excel.
  • Insert content into Excel spreadsheets.

    Office Development

Let’s quickly see what this means. We will understand by inserting some add-in in Excel.

Open Excel and create a new workbook. Go to “Insert” -> “My Add-ins” -> “See All…”:

Office Development

“Office Add-ins” dialog will open. Click on “STORE”, enter “Wikipedia” in search, once Wikipedia add-in appears, click on “Add” button next to it.

Office Development

The dialog box will close and you will see now that the “Wikipedia” add-in is added under “Add-ins” ribbon.

Office Development

Click on it and on the right side, you will see a new section.

Office Development

Anything you can do on Wikipedia website, now you can do from inside Excel only using this add-in.

This is an example of “Extend functionality” type of add-in. These types of add-ins let you do some work right from Office applications without opening any other application. If you want to create this type of add-in, you should select “Add new functionalities to Excel” option in “Create Office add-in” dialog.

Now, let’s see some other add-in examples. Once again in Excel, go to “Insert” -> “My Add-ins” -> “See All…”. In the “Office Add-ins” popup, click on “STORE” tab and search on “bubbles”,

Office Development

Click on the first row “Add” button. You will see in the top right under “Insert” ribbon, a new “Excel Bubbles” add-in is available now.

Office Development

Click on it and a section with bubbles is added into current worksheet.

Office Development

Click on the “Sample Table” bubble in this section. It will add some sample data in worksheet and populate bubbles as per data,

Office Development

This is an example of “Content” type of add-in which adds some content inside an Office application. If you want to create this type of add-in then you should select “Insert content into Excel spreadsheets” option in “Create Office add-in” dialog.

Let’s go back to Visual Studio now. We were on this popup,

Office Development

Let the selection be “Add new functionalities to Excel”. Click “Finish”.

VS will create a new Excel add-in solution with 2 projects,

Office Development

Before understanding “what” these projects are and “why” they are created, let’s first understand the composition of an Office 365 add-in.

An Office 365 add-in consists of two components,

Office Development
Image credit: Microsoft

  • XML manifest file
    specifies settings and capabilities of the add-in
  • Web application
    interacts with Office clients and documents

Now coming back to Visual Studio, in VS 2017 Solution Explorer, you will see these two projects:

  • ExcelWebAddIn1
    This is the manifest project containing the XML add-in configuration/settings
  • ExcelWebAddIn1Web
    This is the project which has all code defining the add-in & its interaction with Office document. It has JavaScript and HTML files which define the UI of the add-in.

    To provide same look and feel in the add-in as Office 365 clients, it uses Office UI Fabric JavaScript. I will cover more on Office UI Fabric JS in separate article later.

Let’s now run the project to see it working. Press F5, VS will build the solution and launch Excel to make your add-in available inside it.

In Excel, “Show Taskpane” button will be focused with a tool tip message,

Office Development

Click on the “Show Taskpane” button. The task pane area will be loaded on the right side of Excel worksheet.

Office Development

Please note that when you created a new Excel add-in project, VS 2017 has included some sample code in it. That’s why you see the text and button here. Also, if you note the worksheet has been loaded with some sample data,

Office Development

This sample add-in is for finding and highlighting highest value cell among the selected ones. To see it in action, select the sample data and click on “Highlight” button,

Office Development

The JS code will get executed and highest value cell among the selected cells will be highlighted.

Stop the running project from Visual Studio and let’s now see the code which made it work.

In the Solution Explorer, double click the “Home.html” file.

This is the file which contains all UI elements. The texts and button you saw in Excel add-in are defined here,

Office Development

In the Solution Explorer, double click on home.js file.

This is the file which contains all code to interact with Excel.

Office Development

It sets the button text to “Highlight” and also sets the JS function which should be executed when someone clicks on it, among other things.

The load sample data JS function which populates the worksheet with some random numbers,

Office Development

The code for finding the highest value cell and highlighting it,

Office Development

See how simple it is to get started with Office 365 add-in development? You must give it a try yourself using VS 2017.

The purpose of this article was to make developers aware of Office 365 add-in development using VS 2017 which I have done above. You have to come up with the idea of your add-in to create a real-life Office 365 add-in which adds some value to the Office clients.

That’s it for this article. I will cover more add-in options in next article.

Note: This article was originally published by me on C# corner website here.

Featured image courtesy: C# Corner

Get Office 365 data in Excel using MS Graph API

Learn how to use MS Graph API in Excel

Objective:

Recently I wrote an article about how you can consume MS Graph API in Power BI (read it here). MS Excel can also consume Microsoft Graph API in the same way.

In this article, I will show how you can quickly fetch Office 365 data of your organization in MS Excel using Microsoft Graph API. We will fetch an organization’s users list in MS Excel with MS Graph. Once you learn to use MS Graph API in MS Excel, you can explore more options by yourself.

To make this article easy to follow, let’s identify a real-world requirement and then see how we are going to solve it using MS Graph API and Excel.

Requirement:

Suppose you are working in the IT department of an organization who employs 500+ users. On weekly basis, new employees join your organization and some leave too. The receptionist needs up-to-date information about all employees and their contact details. You are asked to provide her a simple solution. You create an Excel workbook for her using MS Graph API data feed which will show list of employees which she can refresh anytime to get latest updates.

 Introduction:

What is MS Graph API?

Excerpt from https://developer.microsoft.com/en-us/graph/docs/concepts/overview

You can use the Microsoft Graph API to interact with the data of millions of users in the Microsoft cloud. Use Microsoft Graph to build apps for organizations and consumers that connect to a wealth of resources, relationships, and intelligence, all through a single endpoint: https://graph.microsoft.com

For more on MS Graph API, please go to https://developer.microsoft.com/en-us/graph

There is no coding involved to follow steps of this article. However, if you want to follow along the steps, then it’s better to have Office 365 developer account as mentioned in “Prerequisite” section below.

 Prerequisite:

  • Office 365 developer account

You may have access to Office 365 thru your employer/organization account. However, it is strongly advised that you don’t use your live/organization account to follow steps of this article. Instead, use Office 365 developer account. Use your live/organization account only when working in a production environment.

Read my blog on how to get Office 365 developer account for 1 year free here.

 Getting Started:

I assume you have Office 365 developer account and you also have MS Excel installed on your PC.

Open MS Excel and create new workbook.

Go to “Data” tab in ribbon and click “Get Data” on left side:

GetData1

When “Get Data” menu expands, click on “From Other Sources”, then click “From OData Feed” as shown below:

GetData 2

Once you click on “From OData Feed”, you will see a dialog to enter OData feed URL:

Odata URL

Why we choose this option?

MS Graph API is based on open web standards and it supports OData V4, and MS Graph API accepts and returns data in JSON format, making it easy to integrate with other applications and technologies.

We want to access all the users of an organization. The MS Graph API endpoint https://graph.microsoft.com/v1.0/users returns all users of an organization.

Enter https://graph.microsoft.com/v1.0/users in the textbox under URL and click OK:

Odata URL 2

Once you click on OK, you will see a dialog where you can specify your credentials to connect to MS Graph API:

Odata feed

Click on “Organizational account”, then click on “Sing in” button:

Odata feed 2

You will see “Office 365 Sign in” dialog:

O365 login

Don’t use your organization/live account to sign in. Use your Office 365 developer account to sign in.

After successful login, the “Office 365 Sign in” dialog will close, and your status on OData feed dialog will change to “singed in”:

Odata feed 3 Connect

Click on Connect button to continue.

It may take some time to fetch the result from MS Graph API call depending your internet connection, but it will not be more than a few seconds. Once MS Excel fetches the users using MS Graph API, it will show you result in a dialog.

For demo, I have created some users in Office 365 Admin Portal using my developer account. I suggest you also create some demo users with your Office 365 developer account using Office 365 Admin Portal.

You will see a result dialog like this, filled with your organization’s users:

result dialog

Notice the “Load” button has a down arrow, click on it and you will see “Load” and “Load To…” options:

Load

Click on “Load To…” link, you will see an “Import Data” dialog:

import data

This dialog has options for how you want to view the data and where you want to place the data. You can import the data to new worksheet too. We will not do anything special in this dialog, I just wanted to show you the options available in Excel.

Click on OK button and the dialog will close. As “New worksheet” was selected in “Import Data” dialog, you will see a new sheet has been added to Excel and data is populated:

excel result

What has happened here?

MS Excel has received the JSON data result from MS Graph API in response to the call to https://graph.microsoft.com/v1.0/users endpoint, and converted it to a data table for you. What you see here is the list of all properties it got from MS Graph API.

By default, Excel will load all the columns it received from MS Graph API, some columns will not have data and you will not want to display all the columns. We will see in some time how you can choose only some columns to be displayed.

Also, if you note on right side new section “Queries & Connections” has been added:

queries

Right click on “Query1” and click “Edit”:

Query Edit

You will see “Query Editor” is opened in a popup, click on “Choose Columns”:

Choose Columns

You will see “Choose Columns” dialog:

Choose Columns 2

Uncheck the very first “(Select All Columns)” checkbox, then select only below columns, then click OK:

  • displayName
  • jobTitle
  • mail
  • mobilePhone
  • officeLocation

You will see now Query Editor will only show the columns we selected in above step:

Close and load

Click on “Close & Load” button on top left to continue.

The Query Editor will close and you will Excel now shows you only those columns you selected:

excel chosen columns

Good job! You got your organization’s data in Excel using MS Graph API. How simple it was!

Now, let’s come back to the receptionist’s requirement I mentioned at the start of the article. A new employee has just joined office. She needs his details in this Excel too. What should she do?

For the demo to work, I have opened Office 365 Admin Portal and added a new user named “Graph Explorer” to my organization using Office 365 developer account. I suggest you also add a new demo user to your developer account using “Office 365 Admin Portal” -> “Add a user” link.

After adding a new user in Admin Portal, right click on “Query1” in Excel and click “Refresh”:

refresh

Excel will once again connect to MS Graph API and will fetch result and refresh the contents in worksheet:

new user

Do you see the user “Graph Explorer” now in the first row?

So, the reception’s requirement is fulfilled. Every time she wants latest data, she has to just hit “refresh” and MS Graph API will do the rest.

What’s next?

The purpose of this article was only to show you how MS Graph API data can be consumed in MS Excel, which I have shown above. Similarly, you can try by yourself calling some other MS Graph API endpoints.

Meanwhile, if you want to read more of my articles on MS Graph API, please visit https://nilesh.live/blogs/msgraph/.

Display Office 365 data using MS Graph API in Power BI

Learn how you can consume MS Graph API data in Power BI

Objective:

In this article, I will show how you can display Office 365 data of your organization in Power BI report using MS Graph API.

I will show how you can fetch your organization’s users with MS Graph API, and quickly create a report using Power BI Desktop. Once you learn to use MS Graph API in Power BI, you can explore more options to create some interesting reports on your own.

Background:

This article assumes you know something about MS Graph API and Power BI.

What is MS Graph API?

Excerpt from https://developer.microsoft.com/en-us/graph/docs/concepts/overview

You can use the Microsoft Graph API to interact with the data of millions of users in the Microsoft cloud. Use Microsoft Graph to build apps for organizations and consumers that connect to a wealth of resources, relationships, and intelligence, all through a single endpoint: https://graph.microsoft.com

For more on MS Graph API, please go to https://developer.microsoft.com/en-us/graph

What is Power BI?

Excerpt from https://powerbi.microsoft.com/en-us/

Power BI is a suite of business analytics tools that deliver insights throughout your organization. Connect to hundreds of data sources, simplify data prep, and drive ad hoc analysis.”

For more on Power BI, please go to https://powerbi.microsoft.com/en-us/

There is no coding involved to follow steps of this article. However, if you want to follow along the steps, then you will need things mentioned in “Prerequisites” section. If you don’t want to follow along and just want to read, you can jump to “Getting Started” section.

Prerequisites:

  • Office 365 developer account

You may have access to Office 365 thru your employer/organization account. However, it is strongly advised that you don’t use your live/organization account to follow steps of this article. Instead, use Office 365 developer account.

Read my blog on how to get Office 365 developer account for 1 year free here.

  • Power BI Desktop

You will need Power BI Desktop to create the report which will consume MS Graph API data.

Power BI Desktop can be downloaded free from this link:

https://www.microsoft.com/en-us/download/details.aspx?id=45331

Power BI Desktop getting started guide is here:

https://powerbi.microsoft.com/en-us/documentation/powerbi-desktop-getting-started/

 

Getting Started:

I assume you have Office 365 developer account and you have installed Power BI Desktop on your PC.

Let’s get started.

Open Power BI Desktop.

PowerBI1

Once open, you will see it’s welcome screen:

PowerBI2

Click on “Get Data” just below Power BI Desktop header on top left.

Alternatively, if you close this welcome screen, then you will also see “Get Data” icon at top left:

PowerBI3

Once click on “Get Data”, you will be presented with a “Get Data” dialog. Click on “Other” in left-middle section:

Get data

Once you click on “Other” link, on the right side of dialog you will see some options. Select “OData Feed”, then click on “Connect” button:

Odata Feed

You will see a dialog to enter OData feed URL:

Odata Feed blank

Why we choose this option?

MS Graph API is based on open web standards and it supports OData V4, and MS Graph API accepts and returns data in JSON format, making it easy to integrate with other applications and technologies.

We want to access all the users of an organization. The MS Graph API endpoint https://graph.microsoft.com/v1.0/users returns all users of an organization.

Enter https://graph.microsoft.com/v1.0/users in the textbox under URL and click OK:

Odata Feed2

Once you click on OK, you will see a dialog where you can specify your credentials to connect to MS Graph API.

Odata Feed3

Click on “Organizational account”, then click on “Sing in” button:

Odata Feed4

You will see Office 365 log in dialog:

O365 login

Don’t use your organization/live account to sign in. Use your Office 365 developer account to sign in.

Once you login successfully that dialog will close, and your status on OData feed dialog will change to singed in:

O365 login2

Click on Connect button to continue.

Once Power BI fetches the users using MS Graph API, it will show you in a dialog. For testing purpose, I have created some users using my developer account. I suggest you also create some test users in your Office 365 developer account using Office 365 Portal.

I have masked some sensitive data from my popup:

user data

You should also see your organization’s users here. Click on “Load” to continue.

You will see some messages in a popup while Power BI loads your data using MS Graph API:

loading

Once this dialog closes, on the right side you will see the data table under “Fields” section:

fields

What has happened here?

Power BI Desktop has received the JSON data from MS Graph API in response to the call to https://graph.microsoft.com/v1.0/users endpoint, and converted it to a data table for you. What you see under the Fields -> Query1 section is the list of all properties it got from MS Graph API.

Now we have the data we want from MS Graph API loaded into Power BI. Let’s create a report using it.

Click on “Table” icon under Visualizations on right side of screen:

table

You will see your screen will be loaded with an empty table:

empty table

Now we should select which fields we want to show in table. Under Fields section on right, select displayName, jobTitle and officeLocation fields in that order:

fields selection

As and when you select the fields, you will see the table being loaded with data:

table with data

Hurray, you have created your first Power BI report using MS Graph API!

What’s next?

The purpose of this article was only to show you how MS Graph API data can be consumed in Power BI, which I have shown above. Similarly, you can try by yourself creating some other reports/visualizations and calling some more MS Graph API endpoints.

If you want to share the report, you can do it using the Publish feature of Power BI:

publish

But this requires a Power BI account and it’s out of scope for this article. I suggest trying it on your own.

Meanwhile if you want to read more of my articles on MS Graph API, please go to https://nilesh.live/blogs/msgraph

Register your application to work with Office 365 – Part 2

Learn how to register your application to work with Office 365

In this article, I will continue from where we left in part-1 to register an application to work with Office 365 using the Microsoft App Registration Portal.

This is part-2 of the two-part series, I suggest to read the part-1 here first before continuing.

The objectives of this article are:

  • Alternate way to register your application
  • How to run sample code
  • Access your registered application from MS Azure Portal
  • Application flow

Alternate Way to register:

You can also register application from the “Quick Start” page which is shown immediately after your login to App Registration Portal https://apps.dev.microsoft.com/portal/quickstart:

Quick Start.png

Click on the “Web” link, you will be shown following:

“Web” link.png

Enter the application name and your contact email, then click on “Create”. I entered “CSCorner” in the application name:

Create.png

You will be shown a success message and asked for redirect URL:

redirect URL3.png

For a quick demo, enter the same URL we entered above http://localhost:57329/AfterLoginPage and click “Save”.

How to run sample code:

After clicking “Save” button in above section, you will be shown a sample code section:

sample code section.png

You can see that your application’s ID and redirect URL are already there. This is a simple HTML and JavaScript code which you can quickly integrate into your application to redirect users to Microsoft for login.

Copy the script to any HTML page header section or create a new page in sample ASP.Net web application we created above.

Scroll down on the portal registration page, you will see code for HTML button:

HTML button.png

Copy this code to body section of new HTML page you created. Save and run the page in browser.

If you create a new ASP.Net web form, then mark to page as startup page and run your web application.

In both the cases, it is necessary that the http://localhost:57329 site is running so that Microsoft can redirect your application to that page.

Both the before login page and after login page of sample web application are attached with this article. You need to add them to your sample application to test demo. Don’t forget to change “clientId” and “redirectUri” values in your page:

sample application.png

Run the application or browse the HTML page you created:

Run the application.png

Click on the Sign in button. You will be shown a login page from Microsoft:

login page from Microsoft.png

Enter your Microsoft login and password, click on “Sign in”.

You may be shown a page like shown below asking for your permission to give grant to application if you are logging in for the first time. Please note this is not the actual screen shot of my application, I have taken it as reference from Microsoft site:

permission.png

Image source: Microsoft

You will be redirected to the page mentioned in “Redirect URL” setting:

redirect.png

Congratulations! You have implemented the authentication with MS Identity stack. Remember you must write code for fetching data from MS Graph API or any other Office 365 APIs. This article covers only registering your application with MS App Registration Portal and demo of logging in using Microsoft credentials.

Access your registered apps from MS Azure Portal:

The applications you registered here are also accessible from MS Azure Portal.

To do so, login to MS Azure portal https://portal.azure.com with the same login you used to register your app on MS App Registration Portal.

Once you are logged in, find and click on the link “Azure Active Directory” Azure Active Directory in left pane:

Azure Active Directory2.png

One more menu will open, find and click on the link “App registrations”App registrations:

App registrations2.png

Alternatively, without clicking on that link, Azure portal will show you the registered apps on the dashboard:

dashboard.png

Either click on the “App Registrations” menu on left or click on the “App Registrations” web part in dashboard.

You will be shown following screen:

App Registrations3.png

You will not see your registered app directly here, Click on the “Microsoft Application Console” link.

Azure portal will redirect you to a login page, once your login is successful, you will be redirected to “My Applications” page of MS Application Registration Portal:

Microsoft Application Console.png

Application flow:

If you really want to develop an application and fetch some data from Office 365, you will need to do much more than just register an application in the portal.

Here is the complete application flow for your reference, you can follow it step by step to develop an application which will access data from MS Graph API or Office 365 APIs:

  • Register the application on Microsoft App Registration Portal: https://apps.dev.microsoft.com
  • Configure the project with ID & key or copy and paste the sample code from portal quick start
  • Authenticate the user and get an access token
  • Call Microsoft Graph API / Office 365 API(s) / Other MS Cloud API
  • Parse the result, show the result to application user

I will cover these steps in detail in a future article, until then – Happy learning!

 

Header Image Credit: C# Corner

Register your application to work with Office 365 – Part 1

Register your application to work with Office 365 using the Microsoft Application Registration Portal.

In this article, I will explain how you can register your application to work with Office 365 using the Microsoft App Registration Portal.

This is part-1 of the two-part series, you can continue to read another part here.

These are the objectives of the article:

  • What is Microsoft Application Registration portal?
  • Why you should know about it?
  • Overview of components in Microsoft Application Registration portal

 Background:

If you are developing an application which is going to work with Microsoft Office 365, like fetching data using MS Graph API or any other Office 365 API, then you will need to register your application with Microsoft first.

Your application users need to be authenticated in Microsoft identity stack first before your application can fetch data using the MS Graph API or any other Office 365 API on their behalf.

 What is Microsoft Application Registration portal?

MS Application Registration Portal is the website where you can go and register your application so that it can work with MS Identity stack and you can get access token to get data from Microsoft APIs.

Here you can:

  • Register new applications
  • Modify existing application for – access permissions, redirection URL, etc.
  • Generate keys
  • Set up application profile

 Why you should know about Microsoft Application Registration portal?

Apart from the purpose stated above, if you want to eliminate managing user name and passwords in your application on your own and let users log in with Microsoft work or school or personal account, then you can delegate the work of authentication to Microsoft. Users can login to your application using Microsoft Identity stack.

By supporting sign in with Microsoft identity stack, your application can have single sign on with Windows and Microsoft cloud applications, can protect your users with the same technology and investments used to protect Microsoft’s users, and can programmatically access information and insights about users via the Microsoft Graph API or other Office 365 APIs.

Any application which wants to use the capabilities of MS Identity stack must first be registered in MS App Registration portal. Here you will be able to get an App ID and redirect URL along with secret code which is necessary to make your app work with Office 365.

Important:

At the Application Registration portal, you will generate an App Secret which will be shown to you only once. Please retain that App Secret, as you will need it to run your app. If you forget it, you will need to restart the registration flow again. There is no way to get the App Secret again.

Cross-platform support:

It supports registering application for iOS, Android, web, and more:

cross

Access data from Microsoft APIs

Access user data inside the enterprise — get an Office 365 user’s calendar, mail, and contacts. The registration in MS App Registration Portal satisfies the basic authentication requirement, you must write code specific to the Office 365 or any other Microsoft API.

Wide use

The Microsoft identity stack has been battle tested by some of the biggest companies in the world.

Using MS Identity stack, you can offer one-click sign in to:

  • Around 85% of the Fortune 500 companies’ users
  • Around 85M monthly active users on Office 365 commercial
  • Around 400M Outlook.com monthly active users

What you will need to register?

You can register using your Microsoft work or school or personal account. You can use your MS Office 365 developer account or windows live account to register your app.

If you are developing for Office 365 and you want to create a developer trial account, read my article here in which I have explained in detail how you can get a free Office 365 account for 1 year.

Where you can register your application?

You can visit the MS App Registration portal here, and then click “Register your app >

reg.png

If you are not already logged in and you click on “Register your app >” link, then portal will first redirect you to login page:

log.png

If you enter your Office 365 developer account, then you will be shown a screen like below to enter password:

pw.png

Let’s see different components in MS App Registration Component

Once you have entered your correct password and successfully logged in, you will be shown the following screen:

f1.png

You can see here the options to register an application for iOS, Android or Web.

If you click on the “My Applications” link on top right, then it will show you any existing application registration in current login id:

my apps.png

Application name and its GUID app id are masked in above screen shot by me for security purpose. You can also see “Add an app” button on top right in this screen. Click on that button and you will see a popup to register new application:

register new application.png

Enter the name of your application and click “Create application”. I entered “CSharpCorner” and clicked on the button:

Create application.png

Portal will create an application named “CSharpCorner” for you. I have highlighted the application name. I have also hidden my email id and application id which is unique id for your application. Have a look at different options available in this page. One by one I will cover those below.

Also, note the message displayed below application name header “CsharpCorner Registration”:

CsharpCorner Registration.png

It says that the application “CSharpCorner” will be registered in the MS Azure active directory instance which manages the login account with which you have logged in. What it means is covered later in this article.

For the scope of this article, “Azure Active Directory” is not covered in any more detail but I suggest you read about it on Microsoft Docs here.

On the same page, note that a section for assigning Microsoft Graph permissions:

Microsoft Graph permissions.png

Further down the page, you will see some other profile settings:

profile settings.png

You can add logo for your application, and URLs for your application’s home page, ToS, Privacy, etc.

Still further down the page, there are some other advanced options, along with save and cancel buttons:

advanced options.png

“Application Secrets” section:

Scroll to the “Application Secrets” section.

Application Secrets.png

Click on the “Generate New Password” button to create a password for our application. Portal will generate new password for your application and show in a popup:

Generate New Password.png

Note that the password will be shown to you only once now and there is no way to see this password again. So, it is necessary to store this password somewhere safe so that you can use it in your code later.

You will use this password along with the “application id” of this application to make your users authenticated by Microsoft.

Click “Ok” button and you will see that Portal shows you masked password:

masked password.png

Mostly in programming you will use the application id and password combination to redirect your users to authenticate on Microsoft site. But if you want to create a private key/certificate it can be done here too.

Click on the “Generate New Key Pair” link:

Generate New Key Pair.png

Enter the password and click “Ok”. Remember the password used to create the key, store it somewhere safely. Also, within seconds when the private key is ready, Portal will show you message to save it:

download the file.png

Click on “Save File” and then click “Ok” to download the file.

Once the file is downloaded, you can go to the download location and see the file:

download location.png

Double click on it to import; a certificate import wizard will be shown to you:

certificate import wizard.png

For the scope of this article, the certificate import wizard is not covered. You can explore it on your own.

“Platforms” section:

Now go back to the App Registration Portal, scroll to the “Platforms” section and click on “Add Platform” button:

Platforms

You will see the “Add Platform” popup:

Add Platform.png

 

Web application, Native application and Web API platforms can be added here. Click on “Web”. The following section will be added to the page:

Web application.png

The most important setting here is the “Redirect URL”:

Redirect URL.png

It’s the URL to which the user’s browser will be redirected after Microsoft authenticates the user. It should be a URL of a page in your web application which you want to show once user completes authentication with Microsoft, like a landing page.

For showing you a demo, I have created a sample ASP.Net application on my PC and taken its local URL which I will enter in the “Redirect URL” textbox:

http://localhost:57329/AfterLoginPage

Redirect URL 2.png

Similarly, you can also click on “Add Platform” again and select “Native Application” this time:

Native Application.png

You will see the “Native Application” section will be added to the page:

Native Application2.png

Once again click on “Add Platform” and select “Web API”:

Web API.png

The “Web API” section will be added to page:

Web API2.png

I will not go into details of “Native Application” and “Web API” sections.

You can delete these two platforms if you added for testing, because for demo I will show you only “Web” platform.

“Microsoft Graph Permissions” section:

In this section, the permission to your application when it communicates with MS Graph API is decided.

To understand better, read the following extract from Microsoft Docs:

By defining these types of permissions, the resource has fine-grained control over its data and how the data is exposed. A third-party app can request these permissions from an app user. The app user must approve the permissions before the app can act on the user’s behalf. By chunking the resource’s functionality into smaller permission sets, third-party apps can be built to request only the specific permissions that they need to perform their function. App users can know exactly how an app will use their data, and they can be more confident that the app is not behaving with malicious intent.

By default, there is only one “User.Read” permission which is the simple most read-only permission:

User.Read.png

Click on the “Add” button besides “Delegated Permissions”. You will be shown the “Select Permission” popup:

Select Permission.png

It’s up to you which permission you want to give to your application based on the type of work you are doing in it. Never give unnecessary or all permissions to application as it may result in some user data loss inadvertently. Select only those permissions which you actually need in your application. Let’s say your application will send and receive emails, then select the Mail.Read and Mail.Send permissions.

Click “Ok” and see the permissions are there on the page:

permissions.png

Scroll down to the bottom of the page and click on “Save” to save the changes.

There is also another way to register your application which I will cover in part-2 of the series.

To read how to register application in alternate way, how to see registered applications in MS Azure Portal and for a quick demo, check my part-2 article here.

 

Header Image Credit: C# Corner

Introduction to Microsoft Office 365 Developer Program

In this article, I will introduce you to MS Office 365 Developer program.

Background

The user base of MS Office 365 is increasing day by day by leaps and bounds. Microsoft needs to prepare more and more developers who work with Office 365. For this reason, Microsoft has designed the MS Office 365 Developer Program for the developers who build Office 365 solutions across desktop, web, and mobile platforms.

The MS Office 365 Developer Program can be accessed via the link https://dev.office.com/devprogram

MS Office 365

You can start registering for the developer program by clicking on “Join Now” button.

What are the benefits of MS Office 365 developer program?

The program offers many benefits. The most interesting one is one year free Office 365 developer subscription.

MS Office 365

You can also access some free online training on Office 365 too.

If you register now and till next few days, you will also get a chance to participate in a draw to win MS Ignite 2017 event.

MS Office 365

Why you should register

If you want to start with Office 365 development which is very much in demand now, then you will need a demo or test account for your programming. You may have access to Office 365 via your employer organization but that is the live organization data. You may not want to play with live data while you are in  the testing and training phase of some new programming.

Once you get the developer account, you can use it for various Office 365 related programming works, like:

  • MS Graph API
  • Office 365 API
  • Office 365 Add-ins

Microsoft is giving you a free one year subscription which you should not miss.

What you will get

Among other things described in one of the screenshots above, you will get “Office 365 Enterprise E3 Developer Trial” subscription with 5 users and US $10.40 user/month credit.

MS Office 365

Note: Shown above is a screenshot of my developer trial subscription from Office 365 Admin portal.

How to register

You can either click on “Join Now” button as shown in first screen or scroll down on the dev program home page and click on the “Join Developer Program >” button.

MS Office 365

Once you click on the “Join” button, you will be shown a registration page.

MS Office 365

Fill in your details and continue. Once you have completed the registration, you will get an email from Office Developer account.

MS Office 365

This email has a link to redeem your free Office 365 developer account. Click on the “Redeem today” link in the email to continue.

You will be shown the following screen.

MS Office 365

Fill in your details and continue.

You will see the following confirmation page.

MS Office 365

Please keep note of your user id which ends with “.onmicrosoft.com” which you will use to login to Office 365.

Office 365 Portal & Admin Portal

Once you have everything setup, you can visit the Office365 portal to access your account here.

MS Office 365

Note: The above shown image is my office 365 portal landing page. You can start using the Office 365 products right away.

You can visit the Office 365 admin portal here.

MS Office 365

You can manage users, groups, etc. from the Office 365 admin portal.

Finally, go to the billing section and check your subscription. It will show you how many number of days are left.

MS Office 365

Go now and create an Office 365 developer account, create some test data, and start programming with Office 365.

What’s stopping you?

 

Note: This article was published by me on C# Corner website here.

Header Image Credit: C# Corner