What is Microsoft Office 365 (Best Tutorial 2019)

What is Microsoft Office 365

Microsoft Office 365: A quick tour

Microsoft Office 365 is one of the most innovative sets of services Microsoft has offered in the last decade, together with Microsoft Azure. In this tutorial, you will learn what Office 365 is and the fundamental services on which the Office 365 offering is built.

 

What is Microsoft Office 365?

Microsoft Office 365 is the most important Software as a Service offering Microsoft currently provides. Software as a Service (SaaS) provides a software solution with a licensing model based on a subscription and delivered through a centrally hosted infrastructure that typically is on the cloud. 

 

There are four main offerings available:

On-premises Everything is based on hardware and software that is installed within the building (the premises) of the company or person using the software. All the key aspects of a software solution, like availability, scalability, and security, are the responsibility of the company or person who runs that software.

 

Infrastructure as a Service (IaaS) The software is installed on one or more virtual machines that are hosted by a third party, abstracting the subject that uses that software from taking care of all the physical infrastructural topics like networking, storage, physical servers, and virtualization.

 

Platform as a Service (PaaS) The software is hosted and executed in a platform that allows developers to focus on data and custom application development. The resources used to host the software solution can be shared across multiple subjects. In that case, PaaS guarantees isolation and data partitioning.

 

Software as a Service (SaaS) The software solution is provided on a subscription basis and is delivered through a centrally hosted infrastructure. Typically, the software solution can be improved by creating customizations and/or embracing an extensibility model that keeps the SaaS offering safe and isolated from any third-party customization.

 

Office 365 fits into the SaaS category. Following the guidance in this blog, you—as a developer—will be able to build customizations and extensions according to the extensibility model of a SaaS offering.

 

One fundamental concept that you need to understand about the various hosting models is that developing solutions for SaaS allows you to focus on your business requirements without having to take care of any infrastructural or platform-related tasks, as you would if you were hosting a solution running in any of the other hosting models.

 

Often, developers waste their time architecting and configuring virtual machines, services, and servers just for the sake of hosting their custom-developed solutions. With the SaaS model, you will completely focus on customizing the software provided as a service by realizing the business requirements that you need to satisfy.

 

Microsoft Office 365 services

Let’s now dig into the main services Microsoft Office 365 offers. First, it is important to note that Office 365 is a continuously growing and changing offering.

 

Thus, the list of services available at the time of this writing could be different from the list of services available at the time of reading. From a developer’s perspective, this is awesome and challenging because you will be continuously learning as the platform grows.

 

The basis of Office 365 is Microsoft Azure Active Directory (Azure AD.  The Azure AD is the directory system on the cloud that sits under the cover of every Office 365 tenant.

 

The Azure AD is used to store users’ identities, to authenticate them, and to federate tenants with third-party identity providers on-premises. All the licensed users of an Office 365 tenant are first users in the Azure AD tenant related to the Office 365 tenant.

 

Once you assign a license to a user stored in Azure AD, that user will be able to consume the assigned services. The Azure AD is almost unknown to the end users, but you cannot have an Office 365 tenant without Azure AD.

 

Every time an end user authenticates to access a tenant, she interacts with the authentication process of Azure AD. However, this is often fluent and transparent to the user.

 

From an administrative perspective, the Azure AD service that supports an Office 365 tenant is available and can be reached through the Office 365 admin portal within the list of services that can be administered.

 

Aside from Azure AD, all the other services available for an end user are accessible through the Office 365 app launcher. The app launcher is accessible by clicking the command button in the upper-left corner of the screen when using Office 365 from a desktop PC within a browser.

 

As you can see, the number of apps that you can utilize is quite large, and it is growing continually. Every user will see the apps for which he has been granted access in the Office 365 app launcher.

 

The first fundamental set of provided capabilities are those related to Microsoft Exchange Online (also known as EXO), which is the cloud-based SaaS version of Microsoft Exchange. Through Exchange Online, you can leverage and provide to your user's services like Mail, Calendar, People, and Tasks. 

 

From a technical perspective, Exchange Online is just an Exchange Server hosted on the cloud, and the above services are provided either through the web browser or by using any compliant client like Microsoft Outlook or any mobile software available to consume the Exchange Online services.

 

For example, if you have an Android or iOS mobile phone or tablet, you will be able to consume Exchange Online even without installing or having Office or Outlook. Often, Exchange Online is the first service that enterprises move to the cloud to reduce their total cost of mailbox ownership and to improve their mobile users’ experience.

 

In many cases, the second service that makes companies move to Office 365 is Skype for Business (also known as S4B). By using Skype for Business, you can enable powerful real-time collaboration and teamwork.

 

To give a few examples: you can make a one-to-one or one-to-many conference calls; you can share a presenter’s screen, even providing remote control of a PC; you can share a whiteboard or a notes file; you can present a slide deck, and you can make a poll.

 

You can also register a conference call for your own reference or for sharing a .mp4 file with people who were not present on the call. Furthermore, by using S4B you can make a call between an Office 365 user who uses S4B and an external user who uses Skype personal.

 

Moreover, you can leverage the service called PSTN Conferencing, which enables you to make conference calls with people who do not have a PC or any other kind of modern device—just a legacy telephone.

 

By leveraging S4B, you can even use the Cloud PBX service, which allows your PC or device running S4B to become a replacement for a classic telephone.

 

Your S4B account will be associated with a legacy telephone number, and anyone using a telephone will be able to make a phone call to you. You will answer the call by using S4B instead of the classic telephone.

 

Depending on your business requirements and geographical location, these last two capabilities (PSTN Conferencing and Cloud PBX) can require some on-premises infrastructural servers and services to make it possible to connect your on-premises telephone infrastructure to S4B.

 

Moreover, in 2015 Microsoft introduced a service called Skype Meeting Broadcast, which enables you to produce, host, and broadcast live online meetings to large online audiences, which can reach up to 10,000 concurrent users/viewers. The attendees of the meeting will just need to have a web browser, while the presenter/producer will have to use S4B.

 

This powerful service enables you to make broad presentations to a set of defined and authorized users, to all the users who have a company-related account in a specific Office 365 tenant, or even publicly to any anonymous users.

 

You can also configure the meeting to be integrated with a Yammer network for social discussion about the presented content. Furthermore, you can measure the mood of the people attending the meeting by using Bing Pulse, which can be integrated into the UI of the meeting broadcast.

 

OneDrive for Business (also known as OD4B) is another outstanding feature of Office 365 that allows users—typically employees—to store, sync, and share their personal and work documents in a cloud-based repository that they can access securely from everywhere and from any device just by providing the proper set of user credentials.

 

At the time of this writing, every user who owns a OneDrive for a Business license can store up to 1 terabyte (TB) of data in her personal repository.

 

There is also the capability to keep an offline copy of the personal document on your desktop PC, which can be synchronized with the cloud whenever there is network connectivity. Due to high demand, the synchronization client of OneDrive for Business is subject to improvements and the introduction of new capabilities.

 

Often, the OneDrive for Business service name is also used to embrace the capability to keep an offline copy of the SharePoint Online libraries that you have in Office 365 or even in SharePoint on-premises.

 

In the past, the same synchronization client was used to synchronize both the personal storage in OneDrive for Business and the business-related document libraries stored in the intranet.

 

However, at the time of this writing, there are two different clients: the old one, which can still be used to synchronize document libraries, and the new one (called NextGen Synchronization Client) just for OneDrive for Business and OneDrive Personal.

 

We just talked about document libraries stored in SharePoint Online because SharePoint Online (also known as SPO) is another fundamental service Office 365 offers and is filed under the SharePoint icon in the app launcher. Like Exchange Online, SharePoint Online is a cloud-hosted version of the well-known Microsoft SharePoint Server product.

 

Although SharePoint Online shares the main architectural pillars with the on-premises version of SharePoint 2016, on the cloud there are some services, capabilities, and architectural choices that make the SPO offering unique and not 100 percent comparable with SharePoint on-premises.

 

For example, there are services or capabilities of SharePoint 2016 that are available on-premises only (for example, some Business Intelligence capabilities), and there are other services that are available on the cloud only (for example, the external sharing capability of SPO that allows users to share sites and documents with people outside the company if company policies allow it).

 

Many other capabilities and functionalities can be mentioned when comparing SharePoint 2016 on-premises and SharePoint Online, but they are outside the scope of this blog.

 

When you click the SharePoint app in the app launcher, you get access to the new SharePoint home page, which was introduced by Jeff Teper (Corporate Vice President for SharePoint and OneDrive in Microsoft Corporation) together with other new user interface enhancements on May 4, 2016, during an online conference called “The Future of SharePoint.”

 

In the new SharePoint home page, users will find a list of companywide promoted sites, a list of followed sites, some useful companywide links, and a direct link to the most frequently accessed sites. This page is the entry point, from a SharePoint Online perspective to the entire set of sites (site collections in SharePoint) of interest to the current user.

 

When you work with documents stored in SharePoint Online or in OneDrive for Business, if those files are Office documents you can leverage the Office Online services, which allow you to read and write/modify those documents just by using a web browser.

 

This is a powerful capability that makes it possible to realize mobile working and to have a digital workplace that requires nothing more than a web browser.

 

Every Office 365 user with a web browser such as Microsoft Edge, Internet Explorer, Google Chrome, or Firefox can be productive, read documents, or write/modify/create documents using Word Online, Excel Online, PowerPoint Online, or OneNote Online. This service makes it possible to work everywhere with almost any device.

 

Another powerful capability Office 365 provides that integrates some of the services we have just seen is Office 365 Groups. 

Office 365 Groups are a service mainly built on top of Azure AD, Exchange Online, SharePoint Online, and OneDrive for Business. Office 365 Groups enable people using Office 365 to create work groups;

 

which can be considered modern digital workplaces, where they can share conversations, a mailbox that behaves like a distribution list, files, a OneNote notebook, a calendar, a directory of people contributing to the group, and direct Skype for Business integration.

 

Office 365 Groups provide a self-service experience for users, who can create both public and private groups and can invite people to contribute to the groups. At the time of this writing, Office 365 Groups are available for tenant internal users only. However, the public roadmap for the service includes upcoming support for external users.

 

Another key feature of Office 365 Groups is the capability for tenant admins to manage groups from the Office 365 admin portal, to enforce naming policies for self-service created groups, and to orchestrate groups’ creation by allowing or denying group creation permissions to users.

 

Later in this blog, you will learn about what is available for tenant admins to accomplish administrative, management, and governance tasks.

 

From an end user perspective, Office 365 Groups can be consumed by using the web browser on any device, by using Microsoft Outlook 2016, and soon even by using Microsoft Outlook for Mac.

 

From a developer perspective, Office 365 Groups can be managed through a set of REST-based APIs, which are part of the Microsoft Graph API. In Section II, “Office 365 programming model,” and in Section III, “Consuming Office 365,” you will learn how to use the Microsoft Graph API to consume and manage Office 365 Groups.

 

Moreover, as a developer, you can connect custom applications with Office 365 Groups, providing support for getting useful information and content from external services or applications into groups.

 

For example, there are already connectors for BingNews, GitHub, BitBucket, JIRA, and many other services. You can even create your own custom connectors, “Creating Office 365 applications,” you will learn how to do that.

 

The Planner app is a new service that Microsoft released in early June 2016 that offers a visual tool to organize teamwork. By using Planner, you can create and organize plans, assign and monitor tasks that are part of a plan, organize tasks in buckets, and attach files or links to any specific task.

 

In general, the Planner is a tool to manage time, resources, and tasks with a vision board and a set of graphical charts to better understand the overall progress of a plan.

 

One key feature of plans in Planner is that—internally and from an architectural perspective—they are based on and leverage Office 365 Groups. Thus, whenever you create a new plan in Planner, you will also have a related Office 365 Group, which implies having conversations, a calendar, files, a OneNote notebook, and the Skype for Business integration.

 

From a developer perspective, Planner can be consumed by using a specific set of REST APIs, which are in beta/preview version at the time of this writing but are scheduled for release in 2016.

 

Thus, you can think about creating custom software solutions that integrate emails (EXO), files (OD4B and SPO), and groups and plans, orchestrating real business-level solutions.

 

Microsoft Power BI is an important service to visualize data that is integrated to Office 365. By using Power BI, you can import or consume datasets, presenting data through reports that can visualize charts and graphs and can be organized into dashboards that present data and information through tiles coming from different reports.

 

Power BI is an extensible platform that can be consumed and embedded without an Office 365 subscription. It provides additional features such as an automatic refresh of data models based on data stored on OneDrive for Business.

 

This platform also provides features that help users navigate data, such as Power BI Q&A, which allows users to ask for data using natural language questions, and Quick Insights, which automatically finds valuable relationships in a data model. 

 

Yammer is another service that can be consumed as part of the Office 365 offering. Yammer is a cloud-based SaaS solution that provides the capability to create a private enterprise social network for a company.

 

By using Yammer, employees can collaborate; exchange messages; chat; and share content across departments, locations, and business apps.

 

Yammer’s overall goal is to provide a social network to improve productivity, connect people, and freely share ideas and content without the common and reasonable constraints of a classic intranet or collaboration portal.

 

Through Yammer, you can also involve partners, customers, and vendors in external networks that can go beyond the limits of your company network.

 

Within a network, whether it is private and company-related or external and open to third parties, users can freely create public or private groups, discuss and share documents and videos, make polls, give prizes to other members, and in general enjoy being part of an enterprise social network, working from anywhere and using any client device.

 

Another interesting service is Office Delve, which is one of the most innovative emerging technologies available in Office 365.

 

It is one of the new services Microsoft introduced in 2015 in the category of NextGen Portals. NextGen Portals are services typically based on SharePoint Online, from a user interface perspective, that leverage the Office 365 ecosystem and the Office Graph to provide high-level services and tools to improve quality of work— and quality of life—for Office 365 users.

 

Office Delve is a service based on Microsoft SharePoint Online that provides users with the most relevant content based on what they are working on and whom they are working with.

 

The basic idea of Office Delve is to leverage the Office Graph, going beyond the common information silos that exist across the applications available in the Office 365 ecosystem.

 

Instead of thinking in terms of emails in Exchange Online, attachments to emails, documents stored in SharePoint Online, documents stored in OneDrive for Business, video files, and so on, you need to consider the most useful and/or recently updated content with which you should work, regardless of where it is. Delve will take care of highlighting for you exactly what really matters for your daily job.

 

The Office Graph is an intelligent mapping among people, content, and interactions that happen in Office 365. Office Delve uses the insights and the relationships stored within the Office Graph to proactively and actively suggest content to the users, providing each user with a dashboard of cards that refers to what should be most relevant to that user. 

 

By using Office Delve, users can organize cards in boards, grouping items that share the same goal, project, or group of people working on it. Boards can be used to tag content and to retrieve personalized/grouped views of popular documents and contents that share a tag.

 

The key benefit of Office Delve is that users don’t have to search for what they seek. They just need to access Office Delve and—regardless of the source of the content—they will be able to find and consume the content if it is relevant for them. Users can also organize content and boards into a list of favorites to keep track of what matters most to them.

 

Moreover, through Office Delve all users have a personal profile page called “Me” that they can use to keep track of their personal activity and content, filtered by file type.

 

Through the personal page, a user can consume and customize his personal profile data, which includes all the information that is stored in the Azure AD and that defines the user profile in Office 365, including the company organizational chart if applicable.

 

Every user has a personal page in Office Delve, and every user can browse the personal pages of the other users, consuming only public, nonsensitive data, browsing and searching the Office Graph based on users’ profile properties, information, and expertise.

 

Additionally, through the Office Delve interface, a user can create and maintain an enterprise blog that can be indexed by the search index of SharePoint Online and becomes discoverable by the other people working within the same company.

 

Another notable feature of Office Delve is Office Delve Analytics, through which users can measure how they spend their time at work. By using Office Delve Analytics, users can identify the people and activities that represent their priorities and their most time-consuming targets.

 

This can help them determine how to spend a workday in an effective and productive way. They can also set goals and track their progress toward accomplishment of the goals. 

 

Office Delve can even be consumed using a mobile device by leveraging the Android and iOS clients that are available, respectively, on Google Play and on the Apple App Store.

 

Another interesting and useful NextGen Portal is Office 365 Video, which enables enterprises—and companies in general—to post, share, and discover video content that is organized in channels.

 

The goal of Office 365 Video is to provide a beautiful, usable, socially aware user interface for consuming multimedia video content, either from a desktop PC or from a mobile device.

 

Through the Office 365 Video portal, enterprises can create training channels, repositories of marketing videos, and companywide libraries of videos. Office 365 Video also makes it possible to discuss a specific video on Yammer, to share a direct link to a video by email, and to embed the video into a SharePoint Online site or within the companywide infrastructure.

 

Furthermore, Office 365 Video has a set of management and administrative tools for administrators and is available only to the users of the target tenant, without the capability to share video content outside of the current company boundaries.

 

Maybe in the near future, based on a publicly declared roadmap, Office 365 Video will become available for sharing videos with people outside the current tenant.

 

Office 365 Video leverages the well-known and solid Azure Media Services for encoding and streaming the video content. Azure Media Services leverages a smooth streaming technology to adapt the video quality to the consuming device and the available bandwidth.

 

Moreover, Office 365 Video uses a set of SharePoint Online site collections for storing all the original video files.

 

As a result of this architectural choice, the same technical boundaries that apply to SharePoint Online apply to Office 365 Video. For example, you cannot upload files larger than 10 gigabytes (GB), and you cannot have a channel bigger than 1 terabyte (TB), which is the upper size limit for a single site collection in SharePoint Online.

 

One relatively new product that is part of the Office 365 ecosystem is Office Sway, which is a new tool to visualize and share ideas, news, projects, or whatever else is on your mind that you want to express to others. A Sway is a canvas that renders its content as a sequence, adapting the rendering to the target device.

 

For example, by using Sway you can render a presentation of a new project, mixing text, technical drawings, pictures, and whatever else you want to express within a sequence of views. You can organize content coming from multiple sources like OneDrive for Business, Twitter, YouTube, and Flickr.

 

You can also use your mobile smartphone or tablet to take pictures and present them in Sway. In general, Sway is a fresh new tool to create dynamic presentations that you can build on the go and share with other people in your company. 

 

The final application that can be part of the Office 365 offering is Microsoft PowerApps, which is in preview at the time of this writing. By using PowerApps, you can create mobile-aware software apps that consume data from multiple data sources, providing customizable and responsive UI forms and integrating data in logic flows that can behave like enterprise-level workflows.

 

The power of applications built with PowerApps is their capability to consume data securely through an open connector model and to connect with external REST-based services to execute actions.

 

By using this approach, you can design an app that can be used to integrate different software and technologies, and you can consume that app from any place and using any device. Microsoft PowerApps is available as a web-based application for building and consuming apps, but there are also client apps for Windows and iOS.

 

Microsoft PowerApps natively provide connectors for Office 365 (including Exchange Online, SharePoint Online, and OneDrive for Business), Dropbox, Twitter, Salesforce, Microsoft CRM, Google Drive, SQL Database on Microsoft Azure, and any HTTP/HTTPS service in general.

 

Based on the data consumed from the above data connections, you can define logic flows and wait for approvals, send email notifications, invoke commands, and so on. For example, the logic flows can be built by using Microsoft Flow, which is another new service provided by Microsoft as part of the Office 365 offering.

 

Overall, the idea of PowerApps is to make it possible for power users to easily design multidevice and multistep forms and logic flows that can be shared with others without needing to be developers. 

 

If there is anything you are looking for that is not yet available out of the box in the Office 365 offering, you can search for it in the Office Store, where you can find thousands of business-level SharePoint Add-ins and Office 365 applications provided for free or sold by third parties that you can download, install, and use in your tenant.

 

You should also keep an eye on the Office 365 Public Roadmap, which is available at the following URL: Microsoft 365 Roadmap | Microsoft 365. There, you will find a list of all the launched new features, the features that are currently rolling out, those that are under development, and those that have been canceled.

 

By periodically checking the Office 365 Public Roadmap, you can have a quick look at the status of the ecosystem, and you can plan the adoption of upcoming technologies and services.

 

One last component that is available in the app launcher if you are an administrator of your Office 365 tenant is the Admin command, which brings you to the Office 365 admin portal. From there, you can administer the entire tenant and every service for which you have been designated as an administrator.

 

For example, if you are a tenant global admin user, you will have access to all the settings and services.

 

 However, if you have been assigned only the SharePoint Online administrative rights, you will still have access to the Office 365 admin portal, but from there you will only have access to the SharePoint Online Admin Center and a subset of tenant settings that are available to SharePoint administrators.

 

In the upcoming section, “Administration in Office 365,” you will dig into more details about the administrative UI and common tasks in Office 365.

 

Microsoft Office on PC/Mac and Click-to-Run

Aside from the online services, the Office 365 offering can also include licenses to use the well-known desktop edition of Microsoft Office for PC or Mac. Depending on the subscription plan you have, you could have the right to run Microsoft Office on up to five PCs or Macs per user.

 

The Microsoft Office edition you can use is Office 2016 at the time of this writing, and it is called Microsoft Office 365 Business or Microsoft Office 365 ProPlus, depending on the subscription plan you have. Further details about the available subscription plans are provided in the upcoming section, “Licensing and subscription plans.”

 

One of the most interesting features of the Office client provided within Office 365 is the Click-to-Run installation. You can install Microsoft Office through a completely new installation model, which is based on a Microsoft streaming and virtualization technology.

 

This new technology reduces the time required to install and run the Office client applications, which are usually available to run in a matter of seconds or minutes, depending on your network bandwidth.

 

The streaming part of the Click-to-Run technology allows you to run the Office client software before the entire product is downloaded. In the meantime, an asynchronous download process will download all the components in the background.

 

The virtualization part of the Click-to-Run technology allows you to run multiple versions of Office on the same computer by providing an isolated and virtualized environment for Office. This is just to allow a smooth transition between different versions of Office; it is not a long-term solution.

 

Under the cover, the virtualization technology is based on the Microsoft Application Virtualization (App-V) technology and runs Office in a self-contained, virtual environment on the local computer.

 

The isolated environment provides a separate location for each version of the Office product files and settings so that they don’t change other applications that are already installed on the computer.

 

Additionally, this prevents any conflict between different versions of Office, which can be installed and executed on the same machine. The only constraint is that all the concurrently installed Office versions have to be the same edition.

 

For example, they can be all 32-bit editions or 64-bit editions, but you cannot mix 32-bit and 64-bit editions on the same machine.

 

Click-to-Run is a setup process completely different from the Windows Installer (MSI) technique that was used in the past. When using the old approach based on MSI setup processes, you had to wait for the entire product to be installed before being able to use it.

 

In contrast, the streaming technology first downloads all the fundamental components to run the Office client, followed by all the other components, which will be downloaded in the background.

 

If you try to use a feature that is not yet downloaded and installed, Click-to-Run immediately downloads and installs that feature. The streaming process ends when all the products and features are completely downloaded and installed.

 

Another interesting difference between the MSI installation and the new Click-to-Run setup process is that in the former you were able to select the components to install, while with the latter you always install the whole product.

 

You cannot install a subset of the components unless you manually customize a configuration file that defines the installation rules. By default, you will always end up having the full Office client components included in your license subscription.

 

This new installation technique always provides you the most recent version of Office, so you don’t have to install the product and all the related patches and service packs before being able to use it, as you did with the MSI installation. By default, the product version installed with Click-to-Run will be the latest one.

 

Furthermore, whenever a new Office patch or update comes out, updating an already installed Office client that has been installed using Click-to-Run is an automatic process that can be handled in a matter of seconds or minutes, based on the download time of the update.

 

Once you have installed the Office client and the product is completely downloaded and installed, you don’t need to be connected to the network or the Internet to use Office.

 

From a licensing perspective, the Office client will need to check that your Office 365 subscription is active and valid at least once a month (specifically, at least once every 30 days). Thus, you need to be sure that your users can connect to the Office Licensing Service via the Internet at least once every 30 days.

 

The licensing service will double-check that the users still have valid Office 365 subscription licenses and that they don’t use a number of Office client installations over the licensed number.

 

For example, as you will see in the following section, “Licensing and subscription plans,” in the Office 365 E3 plan every user can run Office client on up to five devices.

 

The monthly license check will verify not only the subscription license but also that the total number of installed copies of Office client does not exceed the licensed limit.

 

If the computer goes offline for more than 30 days, Office client commutes to the reduced functionality mode until the next time a connection can be made and the license can be verified.

 

In reduced functionality mode, Office client remains installed on the computer, but users can only view and print their documents. All features for editing or creating new documents are disabled.

 

In the previous paragraphs, you saw that you need to be connected to the network or the Internet to install or update your Office client. This means that the Click-to-Run technology can be used even without a permanent Internet connection.

 

Another key feature of Click-to-Run is that you are not required to be connected to the Internet to set up Office client. For example, you can distribute Office client via Click-to-Run using a software distribution network share.

 

This approach reduces the Internet bandwidth needed to download and install Office client on multiple devices and improves the download speed, making it possible to download the Click-to-Run packages once and make them available to all the users through an internal network share.

 

Moreover, the capability to download the Click-to-Run packages locally enables you to leverage any software distribution tool and technique you like and to test patches and updates on some pre-defined devices, distributing the updates across the company based on your own schedule.

 

Otherwise, and by default, if your client computers installed Office client via Click-to-Run using the public Internet distribution point, they will get updates automatically as soon as Microsoft releases them.

 

In big, enterprise-level companies, the capability to leverage the new Click-to-Run installation technology without losing control over devices, users, and updates is important. Fortunately, the Click-to-Run technology is totally compliant with common enterprise-level software distribution techniques and rules.

 

Licensing and subscription plans

In the previous section, you learned about the services available in Office 365. However, not all services are available to all users or customers. The set of available services depends on the purchased subscriptions and licenses. 

 

As you can see, there are a wide variety of offerings—and this list is not complete and could be even longer. For the sake of simplicity, we focused on the main options.

 

 Nevertheless, it is important to keep in mind that you can mix some of the plans based on your needs, which makes it possible to tailor the best solution for every business.

 

For example, imagine that you have an enterprise company with 8,000 employees, 1,500 external consultants, 500 resellers, 20,000 customers, and 2,000 suppliers.

 

In this situation, you can buy 8,000 subscriptions of Office 365 Enterprise E5 for the employees so that they will have Office 365 ProPlus on their client devices and the Cloud PBX and the PSTN Conferencing capability.

 

This way, your employees will be able to do their work from wherever they want (office, home, or traveling) and will always be available and reachable, even by phone.

 

Furthermore, you can buy 1,500 subscriptions of Office 365 Enterprise E1 for the external consultants so that they will have almost the same services as the employees, except the Office 365 ProPlus license and the telephony capabilities.

 

Then, you can buy 500 subscriptions of Office 365 E3 for the resellers so that they will be almost like employees, without the Cloud PBX capabilities but including Office 365 ProPlus on their mobile devices.

 

Last, to share documents and sites with customers and suppliers, you will just need to leverage the external sharing capabilities of Office 365, which are available for free and for an unlimited number of external users.

 

Administration in Office 365

Having such a big landscape of services and tools, like those offered by Office 365, requires having some effective and productive tools for administration and governance of the entire platform. In this section, you will see some of the available out-of-box administrative tools that are useful to keep control of your tenant and services.

 

To administer one or more of the services offered by the Office 365 ecosystem, a user should belong to one of the following roles:

 

Global administrator This is the highest administrative role. It implies access to all the administrative features of all the services and administrative rights on the Azure AD under the cover of the Office 365 tenant.

 

Users in the global administrator role are the only ones who can assign other administrative roles. There could be multiple global administrator users, and for safety and recovery reasons you should have at least two users with this role. The person who signs up the tenant subscription is assigned to this role automatically.

 

Billing administrator This is the role for users who can purchase new licenses, manage subscriptions, manage support tickets, and monitor the health of services. Moreover, users in this role can download the invoices for billed services.

  • Exchange administrator This is the role for users administering Exchange Online.
  • Users who belong to this role have access to the Exchange Admin Center (EAC).
  • Password administrator Users in this role can reset other users’ passwords, manage service requests, and monitor the health of services.

 

Skype for Business administrator This is the role for users administering Skype for Business. Users who belong to this role have access to the Skype for Business Admin Center.

 

Service administrator Users in this role manage service requests and monitor the health of services. This role requires users to have administrative permission for any specific service that has to be managed.

  • SharePoint administrator This is the role for users administering SharePoint Online.
  • Users who belong to this role have access to the SharePoint Online Admin Center.

 

User management administrator Users in this role can reset users’ passwords; monitor the health of services; and manage users’ accounts, groups, and service requests. Users in this role can’t delete a global admin, create other admin roles, or reset passwords for billing, global, and service administrators.

 

The global administrator role is an all-or-nothing role, while all the other roles can be assigned selectively based on the effective permissions that you want to provide. In the following sections, you will see the main tools available for administrators in Office 365.

 

Notice that whenever you define an administrative role for a target user, you will have to provide an alternative email address for any further account recovery action. You should also consider enabling multifactor authentication for administrative users to have a better level of security and privacy.

 

Moreover, it is common to have administrative users who just accomplish their administrative roles and are not associated with any specific license.

 

It is up to you to define whether you want to assign a subscription license to an administrative account, but it is not mandatory to have a subscription license to administer a specific service. Thus, you don’t need to pay any license fee to have any of the administrative accounts.

 

The new Office 365 Admin Center

Every user belonging to an administrative role can access the Office 365 Admin Center, which is a site dedicated to administrators of one or more of the available services and of the whole tenant.

 

The Admin Center has been renewed in early 2016 and provides a nice web UI, which can be consumed from almost any device and in any place. There is also a mobile app available for the main mobile platforms (iOS, Android, and Windows Phone) if you prefer to use a native app. 

 

The screenshot has been taken using a global administrative account. Thus, all the services are available. As you can see, the home page provides a dashboard with a first look at the health status of the farm and of the services.

 

In case of any issue, including services with reduced functionalities even if they are still running, you will be informed and will have access to detailed information about the issue and a roadmap for the resolution of the issue.

 

Moreover, through the welcome dashboard, you can access the most common and frequently used actions, like those related to managing users, the activity reports, the billing information, and the message center.

 

On the left side of the screen, you can access all the tenant-wide settings as long as you have proper permissions to access them. The following list explains the main sections of the new administrative user interface.

 

Home This is the home page of the Office 365 Admin Center.

Users Within this section, you can manage active users, restore deleted users, and manage email migration. The latest capability allows you to import mailbox content from external services or repositories like Gmail, Microsoft free personal email, Hotmail, Yahoo, a PST file, and any other mail service that is accessible through the IMAP protocol.

 

Groups

This section can be used to administer distribution lists, security groups, or Office 365 Groups.

Groups > Shared Mailboxes This section provides the user interface for administering any shared mailbox in Exchange Online. Keep in mind that shared mailboxes do not require any additional license for Exchange Online.

 

Resources > Rooms & Equipment This section allows you to manage company assets like meeting rooms or cars, which can be allocated and blogged for meetings or for any shared usage. This list of resources will be available to all users in the tenant.

 

Resources > Sites This section allows you to see the list of SharePoint Online site collections, including some information about the external sharing settings.

 

From this page, you can also enable/disable and configure the external sharing settings for any specific site collection, and you can see the external users, if any, including the capability to remove any external user. You can also create a new site collection from scratch.

 

Billing Through this section, you can manage subscriptions, licenses, and bills. From this section, you can also buy new subscriptions and licenses, if needed.

 

Support This section is used to create and manage support requests and to monitor the health status of services.

 

Settings > Apps This is a wide section that allows you to define settings related to the whole set of apps or services offered within the tenant.

 

From here, you can configure antispam and antimalware settings in Exchange Online, configure site collections and external sharing in SharePoint Online, software updates, user software settings, and so on.

 

Settings > Security & Privacy From this section, you can define general security rules like password expiration policies.

Settings > Domains This section provides the user interface to manage DNS domains associated with the current tenant.

 

From here, you can register new DNS domains, configure DNS settings of already registered domains, and review the suggested DNS settings for configured domains. You can also make a live check of your DNS settings if needed.

 

Settings > Organization Profile This section allows you to define general information about your organization and the physical location of your business in Bing Places for Business.

 

Within this section, you can also enable the First Release capability, which allows you to test upcoming new features for a subset of test users before they are released. Moreover, here you can define a custom theme for your tenant and you can define any custom tile for the Office 365 app launcher.

 

Settings > Partner Relationship This section allows you to manage delegated partners, which are external Microsoft partners that can perform delegated administration for you on your tenant. For example, a delegated partner could be the partner who sold you the Office 365 subscription.

 

To access and manage your tenant, a delegated partner has to be authorized by a global administrator of your tenant. The delegation process starts with the partner sending an email to ask if you want to give him permission to act as a partner on your tenant.

 

Reports > Usage From this section, you can see reports about the services used. Here, you can find reports like users’ email activity, Office license activations, and so on.

 

Reports > Security & Compliance From this section, you can configure any rule about auditing, protection, security, and data loss prevention (DLP).

 

Health > Service Health Through this section, you can check the history of issues, double-check any future maintenance plan, and check the current status of the services running your Office 365 tenant.

 

Health > Message Center This section gives you access to the latest messages about the health status of your tenant and its related services.

 

Health > Recently Added This section gives you a quick overview, with links to detailed information, of the newly released capabilities and features and the upcoming news based on the current Office 365 public roadmap.

 

Health > Directory Sync Status This section provides a useful user interface to review, monitor, and manage the DNS domains configured for directory synchronization and federation. It will show up just in case the current tenant has directory synchronization in place.

 

  • Admin Centers > Exchange From this section, you can access the Exchange Online Admin Center.
  • Admin Centers > Skype for Business From this section, you can access the Skype for Business Admin Center.
  • Admin Centers > SharePoint From this section, you can access the SharePoint Online Admin Center.

 

Admin Centers > Yammer From this section, you can access the administrative settings of the Yammer network related to the current Office 365 tenant, if any. Admin Centers > Security & Compliance From this section, you can access the Office 365 Compliance Center.

 

Admin Centers > Azure AD By following this link, you can access the Azure management portal to manage the Azure AD tenant that is under the cover of the current Office 365 tenant. At the time of this writing, the new Office 365 Admin Center is still under public preview, even if fully functional and code completely.

 

The classic Office 365 Admin Center

If you prefer to use the previous edition of the Office 365 Admin Center, which is still available for backward compatibility, you can select the Go to the old Admin Center button in the upper-right corner of the home page of the new Admin Center, and you will be brought to the old, or “classic,” UI. From there, you will find almost the same actions and commands available through a different UI.

 

For your own reference, here you can find the settings and menu items as they are organized in the previous edition of the Office 365 Admin Center.

 

Dashboard The home page of the old Office 365 Admin Center.

Setup From here, you can follow a multi-step setup wizard that will enable you to set up your tenant, including any related DNS domain; define the users; copy data into mailboxes, and start delivering email messages. It usually takes between 20 and 30 minutes to be ready with a properly set up tenant.

 

Users Within this section, you can manage active users, restore deleted users, and manage delegated partners (external Microsoft Partners that can perform delegated administration for you on your tenant). You already read information about delegated partners in the previous section about the new Office 365 Admin Center.

 

Company Profile Through this section, you can define companywide information like the company profile, any custom theme for the whole tenant, custom tiles in the app launcher, and customs help desk services.

 

Import This section provides the capability to import large amounts of data, like PST mailboxes or large files and folders, into Exchange Online or SharePoint Online. You can upload those files using the Internet network, or you can ship hard drives to Microsoft.

 

You can find further details about importing PST files in the article “Import PST files to Office 365,” which is available on Microsoft TechNet at the following URL: Overview of importing your organization PST files to Office 365.

 

You can also find more details about importing large numbers of files to SharePoint Online in the article “Import data to Office 365,” which is available on Microsoft TechNet at the following URL: https://technet.microsoft.com/library/mt210445.aspx.

 

Contacts This section allows you to manage an All Contacts address list for the tenant.

Contacts recorded in this list will be available to all users in the tenant.

Shared Mailboxes This section provides the user interface for administering any shared mailbox in Exchange Online. Keep in mind that shared mailboxes do not require any additional license for Exchange Online.

 

Meeting Rooms This section allows you to manage company assets like meeting rooms, which can be allocated and blogged for meetings. This list of resources will be available to all users in the tenant.

 

Groups These can be used to administer distribution lists or Office 365 Groups.

Domains This section provides the user interface to manage DNS domains associated with the current tenant. From here, you can register new DNS domains and configure DNS settings of already registered domains.

 

Public Website This is an informative page that explains how to create a public website for your company by leveraging any of the third-party services available.

 

For some old tenants, it is still possible to create or manage a public website hosted in SharePoint Online, but it is an old and retired capability that you should no longer use and on which you should no longer rely.

 

Billing Through this section, you can manage subscriptions, licenses, and bills. You can also buy new subscriptions and licenses. Moreover, you can define the users who will receive billing notifications.

 

External Sharing This section allows you to define at the tenant level if you want to enable external sharing for SharePoint Online sites, calendars, Skype for Business, or Integrated Apps. You can also see some reporting that allows you to understand what is shared with whom, keeping your data under control.

 

Mobile Management This section provides the capability to manage mobile devices, like smartphones and tablets, remotely by applying settings and restrictions, controlling mobile access, and being able to do a remote wipe of corporate data.

 

Service Settings This is a wide section that allows you to define settings related to the entire set of services offered within the tenant. From here, you can configure antispam and antimalware settings in Exchange Online; create site collections in SharePoint Online; define general rules like password expiration rules, software updates, and user software settings; and so on.

 

Within this section, you can also enable the First Release capability, which allows you to test upcoming new features for a subset of test users before they are released.

 

Reports From this section, you can see reports about the services used. Here, you can find reports like users’ resources and licenses usage, Skype for Business activities, SharePoint Online storage metrics, and statistics, OneDrive for Business storage metrics, auditing of security critical events, data loss prevention (DLP) reports, and so on.

 

  • Service Health Through this section, you can check the history of issues and double-check any future maintenance plan.
  • Support This section is used to create and manage support requests and to monitor the health status of services.
  • Purchase Services This section provides access to the store, from which you can buy additional services and licenses.
  • Message Center This section gives you access to the latest messages about the health status of your tenant and its related services.

 

Tools This is the main entry point for a set of useful tools for checking the overall tenant configuration, the Exchange Server on-premises configuration with the Office 365 Best Practices Analyzer, the network connectivity and bandwidth with the Microsoft Connectivity Analyzer, and the Office 365 Client Performance Analyzer.

 

Admin This section provides access to the administrative interface of all the services available at the tenant level, like Exchange Online, Skype for Business, SharePoint Online, Yammer, the Compliance Center, Azure AD, Bing Places for Business, and so on. 

 

However, because this blog targets developers, in this blog you will not see many more details about the available administrative sections, except for a couple of areas that are of interest to a developer. Two sections in particular really matter from a developer perspective, and the following sections will dig into them.

 

Organization Profile

The section related to the Organization Profile allows admins to manage a custom theme for the whole tenant and custom tiles for the app launcher or a custom help desk.

 

The Organization Profile page provides access to some descriptive information about your company. This information includes the organization name, the address, the telephone number, and the main technical reference email addresses.

 

The most interesting sections of the Organization Profile, from a developer perspective, are the Custom Theming and the Custom Tiles.

 

A custom theme for the tenant applies to the Office 365 suite bar and in particular to the top navigation bar. 

 

A custom theme is made of the following elements:

Custom logo This is an image with a fixed size of 200 × 30 pixels, not larger than 10 KB, which can be a JPG, PNG, or GIF. It will be shown in the middle of the top navigation bar.

 

URL for a clickable logo If you want to make the custom logo clickable, here you can provide the target URL that will be loaded by clicking the logo. Provide full URL, including http:// or https://.

 

Background image Defines a background image with a fixed size of 1366 × 50 pixels or fewer, not larger than 15 KB, which can be a JPG, PNG, or GIF. It will be shown as the background for the top navigation bar.

 

  • Accent color The color that is used for the app launcher button, for mouseover, and for other accents.
  • Navbar background color Defines the background color for the top navigation bar.
  • Text and icons Define the color used for text and icons in the top navigation bar.
  • App launcher icon Allows you to select the color for the app launcher icon.

 

Through the Custom Theming page, you have the option to remove any applied custom theming or custom colors, and you can prevent users from overriding the custom theming with their own theme.

 

Custom Tiles is another useful section that allows you to define custom items that will be available to the end users for pinning in the app launcher.

 

Every tile is made of a Title, a URL that can target a link inside or outside the tenant, a Description, and an Image URL for the image that will be shown inside the tile.

 

At the time of this writing, any custom tile will be available to the end users, but they will have to pin the tile in their app launcher manually.

 

Otherwise, that tile will be visible only by clicking the My Apps link in the lower area of the app launcher. Soon it likely will be possible to force the pinning of a tile in the app launcher for all the users in the tenant, improving the governance experience for tenant administrators. You can also extend the app launcher with custom tiles by creating and registering applications in Azure AD. 

 

SharePoint Admin Center

Another useful administrative tool, not only from an IT professional perspective but also from a developer perspective, is the SharePoint Admin Center. In fact, most of the development done around Office 365 includes or at least leverages the SharePoint Online service.

 

You could do any custom development solution that does not relate to SharePoint Online, but most of the developers who were working in SharePoint on-premises are moving to SharePoint Online and to the cloud development model, so they will need to manage SharePoint Online through the SharePoint Admin Center.

 

Through the SharePoint Admin Center, you can manage the following sections:

Site Collections This section allows you to create and manage all the site collections defined in the current tenant. From this section, you can also enable and configure or disable the external sharing capabilities on any site collection and manage the storage quota and the resource quota.

 

InfoPath This section is available for managing the settings of the InfoPath Forms Services. However, InfoPath is a discontinued technology, only available for backward compatibility, and you should avoid using it. 

 

BCS The Business Connectivity Services (BCS) section allows you to configure and manage BCS connections, which can target any REST-based service. This capability becomes interesting when you have hybrid topologies and you want to consume within SharePoint Online some business data that are available on-premises.

 

Term Store This is a fundamental section for defining and managing term groups, term sets, and terms. Whenever you are working on real-world enterprise-level projects, you usually need to define taxonomies, and this section is the best place to go.

 

Records Management This section allows you to define “send to” connections for submitting content to sites with configured Content Organizer. 

 

Search This section provides the main entry point for configuring the Search service at the tenant level. It includes the capability to configure the search schema, the query rules, the result sources, and many other search-related settings.

 

Secure Store This section can be used to define Secure Store applications for accessing external services by providing a specific set of credentials. Apps This section can be used to set up the tenant-level app catalog if any.

 

It also allows you to configure the settings related to the SharePoint Add-ins in general, like add-in settings, licenses, store settings, and so on.

 

Settings This section allows you to make some tenant-level configuration settings like showing or hiding OneDrive for Business to the users, allowing or denying access to the Microsoft Graph, choosing between having Yammer or the old newsfeeds enabled by default, configuring services like Information Rights Management (IRM), enabling or disabling the new SharePoint UI experience, and so on.

 

Configure Hybrid This section provides an easy-to-use wizard to set up a hybrid topology between Office 365 and SharePoint on-premises.

 

If you like, you can also administer SharePoint Online by using Microsoft PowerShell scripting. You can leverage both the SharePoint Online Management Shell, which is available at the following URL (Manage SharePoint Online with Office 365 PowerShell), and the OfficeDev PnP PowerShell extensions, which are available for free as an open source project at the following URL: PnP PowerShell overview. 

 

Summary

In this blog, you studied the overall architecture of Office 365, and you learned that it is one of Microsoft’s main SaaS offerings. You examined the main services the Office 365 ecosystem offers, and you learned about the new Office client offering, which is installed through the Click-to-Run setup model.

 

You saw the main subscriptions available on the market and the services included in each subscription.

 

Moreover, you explored the main administrative roles of an Office 365 tenant and the administrative tools available to manage, monitor, and maintain the services included. In particular, you saw the administrative tools for customizing the UI and branding of an Office 365 tenant and for administering the Microsoft SharePoint Online service.

 

Overview of Office 365 development

Moreover, you will see some of the most useful tools available on the market, most of them made by the community of Office 365 developers, to realize the potential of the platform.

 

Setting up your development environment

First of all, to develop solutions for Office 365, you need to set up your development environment. One piece of great news in the Office 365 development world is that you don’t need to install any server-side components. You just need to have a client machine that is connected to the Internet to consume the online services of Office 365.

 

Setting up an Office 365 developer tenant

To develop solutions for Office 365 and practice with the samples that are illustrated in this blog, you need to have an Office 365 subscription, which can be used for development and testing purposes only.

 

Office 365 is a service Microsoft provides through a subscription model, but if you are new to Office 365 development you can register to have a free one-year subscription and a dedicated developer tenant. Open your browser and navigate to the URL: dev.office.com/. Follow the instructions to join the Office 365 Developer Program and sign up.

 

By joining the Developer Program, you will get a free subscription to Office 365 valid for one year and some other content and free licenses of third-party tools that can help you develop your solutions.

 

You should think about having a dedicated development and testing environment for the full cycle of development, not only for the first year. Most likely, you will also need a Microsoft Azure subscription for publishing some of the developments you will make.

 

If you have a valid MSDN subscription, you should be able to activate a corresponding Microsoft Azure subscription with some prepaid credits. If you do not, you should register for a new Azure subscription, providing a credit card as a guarantee.

 

Configuring your development machine

Once you have defined the Office 365 and Azure subscriptions, you are ready to set up your development machine. Nowadays, a common development environment is made of Microsoft Visual Studio Code or Microsoft Visual Studio 2015 and some other useful development tools.

 

Note that for most of the development tasks that we will cover in this blog, the free license of Visual Studio Code will suffice.

 

However, if you are a professional developer, you probably will find it beneficial to have a professional tool like Microsoft Visual Studio 2015, updated with Update 2 and enriched with the latest version of Office development tools for Visual Studio, which you can download from the following URL: http://aka.ms/getlatestofficedevtools.

 

For example, if you are using Microsoft Visual Studio 2015, you can find some ready-to-go project templates that are helpful when developing SharePoint Add-ins or Office Add-ins.

 

 In Visual Studio 2015, you can find many more project templates targeting Office VSTO and SharePoint solutions, but they all target the old development model for on-premises only (SharePoint 2010 and SharePoint 2013) or the old extensibility model of Office client. Thus, when working in Visual Studio 2015 and targeting Office 365.

 

However, as you will learn by reading this blog, programming for Office 365 doesn’t mean developing solutions for SharePoint Online and Office client only. In general, you will learn how to write web applications, or native applications, that leverage the entire Office 365 ecosystem.

 

In contrast, if you are using Visual Studio Code, you will have to write almost everything from scratch, even though there are some useful open source tools about which you will learn in the upcoming pages.

 

In addition to the main development tools, you probably will need some additional tools and SDKs to develop a whole set of Office 365 solutions.

 

Office 365 Developer Patterns & Practices tools

First, there is a community project called Office 365 Developer Patterns & Practices (PnP), which is an initiative originally made by some Microsoft internal people and today held by a core team of a few Microsoft internals and external community members like MCSMs (Microsoft Certified Solution Masters for SharePoint) and MVPs (Microsoft Most Valuable Professionals).

 

You can find more information about PnP at the following URL: SharePoint Developer Community (SharePoint PnP) resources. The focus of PnP is to provide training, guidance articles, samples, solutions, and more to support the community of Office 365 developers.

 

One of the key elements of the PnP offering is a library of helper types, extension methods, and frameworks to make it easy to develop Office 365 solutions.

 

The library is called SharePoint PnP Core library, and it is an open source library that is available for free on GitHub (SharePoint/PnP-Sites-Core). It can be installed in any Visual Studio project by searching for “SharePointPnP”.

 

Note

NuGet is a package manager for Microsoft development platforms like Microsoft Visual Studio and Microsoft .NET in general. By using the NuGet Package Manager, you can easily install and keep up to date any package provided by Microsoft or by any third parties, with a UI that is fully integrated with Visual Studio.

SharePointPnPCore2013 Targets SharePoint 2013 on-premises and uses the CSOM (client-side object model) library for SharePoint 2013 on-premises

 

  • SharePointPnPCore2016 Targets SharePoint 2016 on-premises
  • SharePointPnPCoreOnline Targets SharePoint Online and leverages the latest CSOM library for SharePoint Online
  • Depending on your target platform, you will have to download the proper package. All the packages provide almost the same set of capabilities except for the functionalities that are available only on the cloud or only on SharePoint 2016.
  • Because the PnP Core library is so powerful, you probably will find it useful to reference it in every Office 365 solution.

 

Another amazing feature included in the PnP Core library is the PnP Remote Provisioning Engine, which targets provisioning on SharePoint 2013, SharePoint 2016, or SharePoint Online.

 

If you are a SharePoint developer for on-premises, and you are used to developing solutions using the old FTC (Full Trust Code) development model, you probably know that in SharePoint on-premises—since SharePoint 2007—it is possible to provision artifacts (lists, libraries, content types, site columns, and so on) by using the feature framework.

 

The feature framework uses CAML (Collaborative Application Markup Language) and XML-based files to define the artifacts to provision. However, the FTC development model and the feature framework are not available in the new world of SharePoint Online and Office 365.

 

Nevertheless, you can do remote provisioning. This means using SharePoint CSOM to provision artifacts instead of using the CAML/XML-based feature framework.

 

While transforming FTC solutions, WSP (Windows SharePoint Services) packages, and Sandboxed solutions into the new add-in model, you should also approach provisioning artifacts and settings in a more maintainable manner.

 

Using pure CSOM enables you to control by code the provisioning and the versioning of artifacts. This is the options Microsoft engineering officially recommends because CAML/XML-based provisioning will cause maintenance challenges with the evolving templates or definitions.

 

Nevertheless, doing all the provisioning manually and by writing CSOM-based code could be a long and painful task.

 

Luckily, the PnP Core team and the entire OfficeDev PnP community have built an engine that is part of the PnP Core library. It leverages the PnP Core library extensions, enabling you to provision artifacts easily.

 

Moreover, the PnP Remote Provisioning Engine enables you to model your artifacts within the web browser by using a prototype or a model site and to extract the designed artifacts into a template file, which can then be applied to any target site.

 

The overall goal of the PnP Remote Provisioning Engine is to make it simple to accomplish useful and common tasks while provisioning sites and artifacts.

 

The provisioning template can be created in memory by using a domain model that is defined within the PnP Core library, or, as already stated, it can be persisted as a file.

 

In the latter scenario, out of the box, the file can be an XML file based on a community-defined XML Schema (SharePoint/PnP-Provisioning-Schema), or it can be a JSON file.

 

Since June 2016, there is also support for an OpenXML file format, which includes all of the information for provisioning artifacts within a unique ZIP file that adheres to the OPC (Open Packaging Conventions) specification.

 

By default, a template can be read from or written to a file system folder, a document library in SharePoint, or a container in Azure Blob storage, which is a cloud-based repository for binary blobs (that is, files) available on Microsoft

 

Azure. However, from an architectural perspective, you can implement your own template formatter and your custom persistence provider to save or load a template with whatever format and persistence storage you like.

 

Built on top of the PnP Core library and the PnP Remote Provisioning Engine is the PnP Partner Pack, which can be considered a starter kit for customers and partners.

 

The PnP Partner Pack provides most of the patterns described by PnP within a unique and articulated solution that can be installed on any Office 365 tenant.

 

The solution enables you to provide a high-level user interface for managing self-service site collections and site creation based on stored PnP provisioning templates and gives you the capability to save and manage a companywide catalog of provisioning templates.

 

Moreover, the PnP Partner Pack includes other interesting samples and tools in the fields of governance and maintenance of SharePoint Online site collections.

 

Another powerful component of the PnP offering is the PnP PowerShell cmdlets. On GitHub (https://github.com/OfficeDev/PnP-PowerShell)—thanks to the efforts of Erwin van Hunen (https://twitter.com/erwinvanhunen)—you can find about a hundred open source custom cmdlets that make it possible to consume SharePoint on-premises (2013/2016) and SharePoint Online from PowerShell.

 

You can accomplish tasks like creating site collections and sites, lists, content types, site columns, and so on.

 

As an Office 365 developer, you will need to have this set of cmdlets on your environment.

 

To install the PnP PowerShell cmdlets, you can download a.MSI setup package from GitHub by browsing to the following URL: github.com/OfficeDev/PnP-PowerShell/tree/master/Binaries

 

There, you will find three flavors, which pair the same options as the PnP Core library:

  • SharePointPnPPowerShell2013.msi Targets SharePoint 2013 on-premises
  • SharePointPnPPowerShell2016.msi Targets SharePoint 2016 on-premises
  • SharePointPnPPowerShellOnline.msi Targets SharePoint Online

 

Another option you have, if your main operating system is Windows 10 or if you have at least PowerShell 3.0 and PowerShell Package Management, is to install the PnP PowerShell package directly within PowerShell by using the Install-Module cmdlet, using any of the following statements, based on the version of cmdlets that you want to install:

  • Install-Module SharePointPnPPowerShellOnline
  • Install-Module SharePointPnPPowerShell2016
  • Install-Module SharePointPnPPowerShell2013

 

Once you have installed the PnP PowerShell cmdlets on your machine and the PnP Core library in your development projects, you will have a rich set of tools for developing Office 365 solutions.

 

Preparing for the SharePoint Framework

Another interesting option available for developing SharePoint Online and general Office 365 solutions is to leverage development languages like JavaScript, TypeScript, and Node.js.

 

“Microsoft Graph API reference,” provide the capability to create powerful solutions written with JavaScript or any other script language that can consume REST endpoints. Moreover, the evolution announced on May 4, 2016, about the SharePoint Framework will involve developing client-side web parts and applications using JavaScript.

 

Thus, it’s worth spending some time setting up your development environment to support these modern development techniques, which will be the future for developing the UI of SharePoint.

 

First of all, it is fundamental to say that to develop with the SharePoint Framework, you can use either a Windows or a Mac development machine. Thus, you are no longer forced to have a specific Microsoft operating system to develop.

 

The tools needed to develop modern solutions are, as for SharePoint Add-ins and Office Add-ins, any of the Visual Studio flavors like Visual Studio Code or Visual Studio 2015. Nevertheless, you can use any text or code editor you like, as long as you can use it to write JavaScript or TypeScript code.

 

Note

TypeScript is a typed superset of JavaScript that compiles to plain JavaScript. It is useful whenever you need to create large JavaScript development projects because it allows you to write fully typed code, with syntax check and compile-time check, but produce plain JavaScript files as a result.

 

Microsoft has introduced TypeScript, but most enterprise companies worldwide use it. You can find samples, documentation, and further details about TypeScript on the language’s official website: TypeScript - JavaScript that scales.

 

You will also need to install the latest version of a Node.js runtime, which can be downloaded from the official Node.js site: Node.js. With Node.js you will also use NPM, which is a package manager similar to NuGet for .NET.

 

It is suggested that you update the NPM package manager to the latest version, which can be accomplished by using NPM by itself with a command like the following:

npm install -g npm

 

The solutions that you create with Node.js can be easily hosted on the cloud—for example, using Microsoft Azure. This realizes the potential of any Node.js solution for Office 365 or SharePoint Framework.

 

Moreover, it is useful to have a console emulator to play with Node.js and some other tools that you will install later. Thus, it is suggested that you install Curl for Windows (www.confusedbycode.com/curl/) and Cmder for Windows ( cmder.net/), which is a console emulator for Windows.

 

There are two more useful tools for automating scaffolding of solutions and compilation tasks. The first tool is Yeoman (yeoman.io/), which can be installed through NPM while in the Cmder console, for example.

 

The second tool is Gulp (gulp.js), which automates the compilation and release of code through a set of customizable workflows. Gulp can also be installed using NPM from the console emulator.

 

Office 365 applications development

Now that you have your development environment set up and ready to go, let’s start thinking about the various kinds of solutions that you can develop in Office 365.

 

First of all, you should know that every kind of project that interacts with Office 365 by consuming its services can be considered an Office 365 application. Later in this blog, in blog 10, “Creating Office 365 applications,” you will learn about development techniques and see a real business solution in practice.

 

In this section, you will get an overview of the main architectural patterns and the most common scenarios that developing a custom Office 365 application can satisfy. The following list is far from complete, but it provides a good set of common types of applications and solutions that you probably will need to create or at least consider in your real-life projects.

 

Web applications

The first flavor of applications for Office 365 is applications with a web-based user interface. You can develop such applications with whatever development environment you like. However, if you usually develop with Microsoft technologies, you probably will use Microsoft asp.net/.

 

Nowadays, one of the most common techniques for developing asp.net/ applications is to leverage the Model-View-Controller (MVC) pattern and to create an  asp.net/ MVC application. However, from a technological perspective, you are free to create an asp.net/

 

WebForm application. That said, in the field of Office 365 development, you should consider that there are many more samples on the network for MVC than for WebForm. 

 

Moreover, if you are not a .NET developer and, for example, prefer to develop web applications using PHP or Java, you can still realize almost the same potentials that you could by using Microsoft .NET.

 

Full-page web applications

When you create a web application that extends Office 365, you have to face multiple architectural patterns and hosting options. One option is to create an application that will be hosted externally from Office 365—for example, using an Azure website within an Azure App Service.

 

An Azure App Service is a cloud Platform as a Service (PaaS) offering provided by Microsoft Azure that enables you to build and host websites and REST services for mobile applications, connecting to data services and consuming data available on the cloud or on-premises.

 

Generally, these kinds of solutions are called provider-hosted applications (PHAs). This option is interesting when your application has an autonomous and independent UX (user experience) that can be integrated with the UX of the Office 365 ecosystem.

 

In such a scenario, you typically can leverage toolkits like Office UI Fabric (Home - Office UI Fabric) to brand the UI of your application with controls and building blocks that will make your application behaves like the standard Office 365 UX but will keep a lot of control over the entire UI/UX of the solution.

 

The end users will have a dedicated experience in which the custom Office 365 application will be provided as a full-screen, full-browser solution.

In this kind of solution, you should try to preserve the common UI of Office 365, including the Office 365 suite bar. 

 

This solution can be applied to any kind of application, whatever Office 365 services it consumes or extends. In fact, the application will provide the entire UI, and the Office 365 services will be consumed through the Microsoft Graph.

 

You will have to register the application in Microsoft Azure Active Directory (AD), “Azure Active Directory and security,” you will learn how to accomplish this task.

 

The end users will be brought to the custom application by clicking a tile in the Office 365 app launcher, by following a direct link in a SharePoint site page, or by activating an add-in in the UI of Office client, among other methods.

 

The application will communicate with Office 365 by using REST over HTTPS and the Microsoft Graph or the SharePoint REST API. If the application has to execute some background and/or long-running processes, you can apply some decoupling and asynchronous patterns.

 

A typical use case for this kind of application is a scenario in which you have to coordinate multiple services, like Exchange Online, SharePoint Online, the Office 365 Groups, and so on, and you need to provide a unique and common UI/UX to the end users, working in the background with the back-end services.

 

From an implementation cost perspective, these solutions guarantee a very convenient cost of development because they are basically simple web applications that consume Office 365 through a set of documented APIs.

 

These kinds of solutions are also cost-effective from a knowledge and learning perspective. They have a very low total cost of development and maintenance because the developers can be generalasp.net/ developers—you don’t need to have dedicated developers with deep vertical expertise on every involved service of the Office 365 ecosystem. Of course, knowing a little bit about Office 365 development could be useful.

 

Web API applications

Another option that you have is to create a web application that just hosts a set of custom REST APIs. These REST APIs can consume the Office 365 ecosystem in the back end, providing a richer set of services as custom endpoints. From security (authentication and authorization) perspective, you can fully leverage Azure AD for users’ authentication and authorization.

 

In fact, in Azure AD you can register not only applications that will consume third-party services like those offered by the Microsoft Graph, but also your own services, providing authorization rules that Azure AD will enforce during the consumption of those services.

 

A typical use case for hosting a web API application for Office 365 is when you want to enrich the native services, integrating custom data repositories or third-party applications. This kind of solution becomes particularly interesting when the consumer of the REST API is another web application or a native application.

 

You can mix the two solutions to create a web-based application that provides a set of UI elements and pages together with some custom REST API endpoints.

 

Single-page applications

A third option for developing an Office 365 application is to create a single-page application (SPA). An SPA is basically a web application that provides the UX through a unique page with some client-side JavaScript code.

 

These kinds of solutions typically are based on one of the JavaScript toolkits available on the market and in the community like KnockoutJS, AngularJS, and many others.

 

The key point of an SPA is to provide the end users with an immersive UX based on a single page that mimics the experience of a classic desktop solution, avoiding the need to reload the whole page or change the current page.

 

An SPA typically leverages AJAX and WebSockets to communicate with the server, dynamically updating the UI by leveraging HTML5, CSS3, JavaScript/jQuery, and/or any other toolkit for creating dynamic pages in JavaScript.

 

A common scenario in these use cases is to have a set of custom Web APIs in the back end hosted, for example, on Azure and invoked by the client-side code in the SPA.

 

Such applications are usually hosted within SharePoint Online in dedicated pages, even if theoretically you can host them wherever you like. Hosting them within the domain that provides SharePoint Online content makes it simple to solve any cross-domain or cross-origin resource sharing (CORS) issue—in particular if those applications just need to consume resources hosted in SharePoint Online, which is often the case.

 

Typical examples of native SPAs are Office 365 Video and most of the NextGen Portals that Microsoft is releasing. The upcoming SharePoint Framework can also leverage the same development model.

 

Native applications

Another common use case is related to native applications, which are custom applications targeting specific devices and/or client operating systems. Typically, they are mobile applications or desktop applications. They could be apps for smartphones, for tablets, or for any other devices.

 

The key point is that the UI/UX is built using device-specific frameworks and programming languages, while the back-end information and services could be directly provided by the Microsoft Graph and Office 365 or could be a set of custom REST API hosted in a web API application.

 

Regardless of the kind of REST API, the native application consumes, from an architectural perspective the application will leverage Azure AD and OpenID Connect for users’ authentication and the Open Authorization protocol (OAuth) for users’ authorization.

 

In the Microsoft technology landscape, you can use toolkits like Visual Studio 2015 and Xamarin to create multi-device applications for iOS, Android, and Windows Phone and for creating Universal Windows Platform (UWP) apps.

 

From an architectural perspective, having a common set of APIs in the back end and a common UI/UX framework that targets all the potential platforms makes the overall solution promising.

 

These kinds of applications are completely integrated with the out-of-box Office 365 and Microsoft Azure offerings, and through them, you can realize great potential.

 

Office 365 Connectors

One last flavor of Office 365 custom development solutions that deserve a section in this blog is the capability to create Office 365 Connectors, which are custom extensions that can be plugged into Office 365 Groups.

 

Office 365 Groups are a new and emerging capability of Office 365 that allows people using Office 365 to self-create modern digital workplaces that are completely integrated with Outlook 2016 client and with the web-based UI of Outlook Web Access.

 

Office 365 Groups provide a unique and modern place where people can keep track of documents, notes, emails, calendars, Skype calls, and so on. However, nowadays most people also use third-party tools and cloud-based applications like Twitter, Trello, Asana, Slack, GitHub, Zendesk, Salesforce, and many others.

 

The Office 365 Connectors are a new technology that enables you to deliver relevant content and events from external applications into the shared inbox of an Office 365 Group.

 

The content and events are delivered as cards into the shared inbox so that everybody belonging to the target Office 365 Group can see them by using Outlook 2016 Client, Outlook Web Access, or even the native mobile applications for Office 365 Groups available for iOS, Android, and Windows Phone.

 

At the time of this writing, there are already more than 50 connectors available, and many more will come in the near future.

 

For example, you can set up a connection between an Office 365 Group focused on marketing a specific product and Twitter to get a notification card whenever there is a new tweet referring to any specific hashtag or account in Twitter. Or you can connect that Office 365 Group to Asana to manage tasks, and so on.

 

From a developer perspective, you can create custom connectors, which have to be registered in Office 365 to be able to communicate with Office 365 Groups.

 

The communication protocol between your custom connectors and the Office 365 Groups leverages a webhook that the connector has to invoke by providing a JSON message via an HTTP POST request over SSL. In Figure, you can see a sample card for a custom event provided by a custom connector.

 

If you like, you can also publish your connectors on the Office 365 Connectors catalog to make them available to others via the Office Store. A connector published on the public catalog will have to pass an approval process held by Microsoft.

 

An even easier way of providing custom events and messages is to register a webhook for a specific Office 365 Group manually.

 

This option is only for one-shot scenarios in which you don’t need to reuse the same connector on multiple groups, and it requires an IT buddy to register the webhook manually in the group and to fire JSON messages to deliver cards to the target group.

 

SharePoint online development

When developing solutions for Office 365, SharePoint Online often plays a big role. In fact, most of the solutions leverage SharePoint Online for storing documents, providing the basic UI elements, handling lists of tasks and calendars, and so on.

 

Thus, in this section, you will learn about the most common development scenarios that you can satisfy with SharePoint Online and some of the tools that you installed on your development machine.

 

SharePoint Add-ins

The first and main scope of custom development in SharePoint Online is the development of SharePoint Add-ins. To be fair, all topics related to developing SharePoint Add-ins for SharePoint Online also target SharePoint on-premises.

 

The environments share the same development and extensibility model, so despite the need to learn a new development model— especially if you come from the FTC (Full Trust Code) development model—the return on investment is worth it.

 

This is an excellent feature of the SharePoint Add-in model because you write once and use twice (online and on-premises).

 

Note

If you are migrating from existing solutions for SharePoint on-premises, you can also have a look at the PnP guidance articles about the transformation from the FTC model to the cloud model.

 

Nowadays, you can develop a custom SharePoint Add-in whenever you need to create a custom solution that mainly targets SharePoint Online.

 

As you saw in the previous section, “Office 365 applications development,” the capability to develop an Office 365 application that can target SharePoint Online and all the other services of the Office 365 ecosystem makes this last option more interesting.

 

The main difference between a SharePoint Add-in and an Office 365 application is that the SharePoint Add-in is registered in Microsoft Azure ACS (Access Control Service) through the add-in registration UI provided by SharePoint Online and can consume SharePoint Online only.

 

In contrast, an Office 365 application is registered in the Azure AD and can consume any service provided by Office 365 as long as it has proper permissions.

 

However, there are use cases in which you will need to create a SharePoint Add-in to achieve your results. Here is a short list of the most common scenarios in which you probably will create a SharePoint Add-in instead of an Office 365 application:

 

Custom overriding of SharePoint UI through JavaScript embedding Customize the out-of-box UI and behavior of SharePoint by embedding custom JavaScript files—for example, through a user’s custom actions—and by changing the HTML DOM (Document Object Model) of the pages or the behavior of some of the out-of-box commands.

 

You can achieve the same result by creating an Office 365 application, but the investment of having a superset of capabilities just to provision a user’s custom action is not worth the time required.

 

Custom SharePoint workflow solutions developed in Visual Studio 2015 Create SharePoint hosted workflow applications that can be executed in the integrated mode to provide custom workflows through the standard UI of SharePoint and by extending lists and libraries within a host site.

 

This cannot be achieved by creating an Office 365 application because the workflow manager component is available only within a SharePoint Add-in. Moreover, a workflow-integrated application can only be created through a SharePoint Add-in.

 

Custom list and library forms Override the out-of-box add/display/edit forms of lists or libraries by replacing them with custom pages hosted in a provider-hosted SharePoint Add-in (PHA).

 

Like UI overriding via JavaScript, this can be done by using an Office 365 application, but it is easier to create a SharePoint Add-in.

 

Remote event receivers Create and register remote event receivers based on a WCF (Windows Communication Foundation) channel to handle events related to sites, lists, libraries, and so on.

 

This is another typical SharePoint-oriented development scenario in which an Office 365 application does not fit. You will see more details about this topic in the upcoming section “Remote event receivers” of this blog.

 

Any SharePoint on-premises custom development solution You cannot customize a SharePoint on-premises farm with an Office 365 application, and unless you are in a hybrid topology, generally you cannot consume SharePoint on-premises from Office

 

A custom solution that has to target both SharePoint Online and SharePoint on-premises falls into this category. Because this blog is about programming Office 365 and not about SharePoint on-premises, this last bullet can be considered an edge case.

In this blog, you will not dig into the development of SharePoint Add-ins because the focus is the entire Office 365 development. Nevertheless, it is important to know real use cases that require you to create a customization solution tied to SharePoint Online.

 

Remote timer jobs for SharePoint

Another common use case in which you can create a solution for SharePoint Online is the creation of a remote timer job.

Aside from the word remote in the name, a timer job is a piece of code, typically executed based on a schedule, that interacts with SharePoint and executes some kind of maintenance task like synchronizing list items with external line of business systems, updating or uploading documents from external file repositories, checking governance rules, and so on.

 

In SharePoint on-premises, there were the FTC timer jobs. On the cloud—in SharePoint Online—you can replace them with remote timer jobs.

 

Remote means that the job interacts with SharePoint Online using the client-side object model (CSOM) instead of running on the server and using the server object model of SharePoint, as it did for on-premises and FTC timer jobs.

 

You can and should create jobs as remote timer jobs, even if your target is SharePoint on-premises, to be ready to migrate to SharePoint Online if and when you need to.

 

Moreover, if you are targeting SharePoint Online, a common architectural pattern is to use an Azure WebJob within an Azure App Service for running the batch software.

 

An Azure WebJob is a portion of code that can be executed on demand or based on a schedule and that consumes computer resources of the Azure App Service in which it is deployed. From a developer’s perspective, an Azure WebJob can be a console application written in C#, a PowerShell script, a Node.js program, and so on.

 

A key point to keep in mind while developing a remote timer job is that usually, it interacts with SharePoint Online using an App-Only OAuth token.

 

You will dig into details of OAuth, but basically, it means that one option is to register the job application as a SharePoint Add-in and to provide App-Only permissions to it.

 

Thus, from a technical perspective, the remote timer job will be similar to any other SharePoint Add-in, giving you the same development experience.

 

A remote timer job can also be created as an Office 365 application, registering it in the Azure AD instead of using Azure ACS.

 

The benefit of creating a remote timer job for SharePoint Online as an Office 365 application is that you can target the entire Office 365 ecosystem and easily consume the Microsoft Graph instead of targeting SharePoint Online only.

 

Remote timer jobs are useful in most real enterprise-level solutions because you can decouple the execution of business tasks, which will happen in the background within the job, from the user interface that the end users will use to provide input for and to schedule those tasks.

 

Indeed, whenever you provide a web-based UI to end users, like when you create a SharePoint Add-in or an Office 365 application, you shouldn’t execute long-running and/or business-critical tasks within the process that is servicing web requests.

 

Any issue, any request timeout, or any application pool recycle in the front end could compromise the running processes.

 

Decoupling the UI from the real business processes allows you to run, monitor, and recover/repeat the business processes without any dependency from the UI layer. Furthermore, having an asynchronous pattern based on a queue allows you to scale more and be resilient in case of any sudden increase in user requests.

 

In the Office 365 Dev PnP Core library, you can find the remote timer job framework, which is useful for creating a remote timer job for SharePoint.

 

In the remote timer job framework, you have all the base types and plumbing available for creating your jobs. You can find further details about this framework and about the Office 365 Dev PnP Core library in general in the PnP Core Training videos.

 

Remote event receivers

One more use case that deserves custom development for SharePoint Online is remote event receivers (RERs). As in the previous section, the word remote just means that the event receiver will not be an FTC event receiver running on a SharePoint server and leveraging the server object model.

 

It will be a bunch of code, typically C# and wrapped into a WCF service, which will be invoked by SharePoint Online (or on-premises) upon one or more events to which the RER subscribed. SharePoint Online will fire a SOAP request against the WCF service whenever any of the subscribed events happen.

 

The architectural model of the RERs makes them suitable for SharePoint only. Nowadays, the solutions based on REST webhooks are much more interesting and open because having a WCF service wrapper to make the RER endpoint available is a tight requirement. 

 

Nevertheless, you might have to create an RER for SharePoint Online or for SharePoint on-premises, and in that case, you will leverage almost the same syntax, tools, and knowledge that you need to create a SharePoint Add-in.

 

Remote provisioning

One last scenario in which you probably will create a solution specific for SharePoint Online is the remote provisioning of artifacts and settings onto a target SharePoint Online site, site collection, or tenant.

 

Earlier in this blog, you saw the concept of remote provisioning in SharePoint Online as the capability to set up configuration settings and to create artifacts like lists, libraries, content types, site columns, and so on by using CSOM.

 

To do that, you will need a custom SharePoint Add-in or a remote timer job that will execute the CSOM requests against the target SharePoint Online.

 

If you just need to provision a site based on a template and you want to leverage the PnP Remote Provisioning Engine, it will suffice to use the PnP PowerShell cmdlets to get a template from a model site and save it as an OpenXML, XML, or JSON file.

 

For example, by using the PnP PowerShell extensions you can export a site as a template into an OpenXML .pnp file, including all the taxonomy terms and persisting any branding file, by using the following syntax:

 

Connect-SPOnline "https://[tenant-name] sharepoint.com/sites/[template-site]"

Get-SPOProvisioningTemplate -Out template.pnp -IncludeAllTermGroups - PersistBrandingFiles

where [tenant-name] and [template-site] have to be replaced with real values coming from your environment.

Later, you can apply that template to a target site by using the following syntax, still in PowerShell:


Connect-SPOnline "https://[tenant-name].sharepoint.com/sites/[target-site]"

Apply-SPOProvisioningTemplate -Path .\template.pnp

 

However, if you want to do more, like dynamically creating lists, libraries, or sites based on the current user inputs or any specific event that could happen in SharePoint Online, you will need to do remote provisioning programmatically.

 

You can still leverage the PnP Core library and the Provisioning Engine to accomplish this task, but you will have to write some custom code. 

 

Once again, if the provisioning of artifacts is part of a bigger solution that includes provisioning and something else not directly related to SharePoint Online, you can consider creating an Office 365 application registered in Azure AD instead.

 

Office client development

So far, you have seen some common use cases and custom development scenarios for solutions that target the online services the Office 365 ecosystem offers. Another fundamental set of customization projects are those for extending the Office client offering.

 

Since Office 2013, the extensibility model of Office client, whether it is the desktop version or the web-based version offered through Office Online services, is possible through a new development model called Office Add-ins.

 

The Office Add-ins model enables you to extend Office applications like Word, Excel, Outlook, and PowerPoint by using a set of well-known web technologies like HTML, CSS, and JavaScript together with the capability to consume a set of REST services.

 

Furthermore, you can create custom add-ins for Microsoft Access Web Apps, which are the web version of Access that is hosted in SharePoint Online. This blog will not cover the add-ins for Access Web Apps.

 

At the time of this writing, Microsoft has greatly improved the capabilities and the potential of Office Add-ins, making it possible to create add-ins that can be executed on a PC (Office 2013 or Office 2016), on a Mac (Office 2016 for Mac), in Office Online, or even on an iPad (Office for iPad).

 

Moreover, Microsoft is currently working on making it possible to leverage the same development model to extend Office for iPhone, Office for Android, and Office Mobile for Windows 10.

 

Office Add-ins can be used to add new functionalities to applications and documents or to embed complex and interactive objects into documents. For example, you could have an Office Add-in for Word that binds external data into a document. Or, you could have an Office Add-in for Excel that embeds a dynamic map or a graph into a spreadsheet.

 

An Office Add-in is basically made of an XML manifest file and a web application made of a bunch of HTML, CSS, and JavaScript files, which represent the real add-in implementation. In Figure, you can see an architectural overview of the Office Add-ins.

 

The manifest file defines some general information about the add-in and the integration points of the add-in with the Office client applications, like the buttons or commands that extend the native UI and the URL of the pages that will be embedded in the target client application. Within the manifest, you can define permissions and data access requirements for the add-in.

 

The very basic web application could be a single, simple HTML page, hosted somewhere like a private web server or any other hosting infrastructure.

 

However, usually the web application under the cover of an Office Add-in is built using both client-side and server-side technologies like JavaScript, Node.js, The Official Microsoft ASP.NET Site, PHP, and so on, and it can be hosted within an Azure App Service.

 

Usually, an Office Add-in interacts with the Office client environment by leveraging a JavaScript API for Office clients, provided by Microsoft. Moreover, Word and Excel have a dedicated set of host-specific object models for JavaScript to provide more contextual objects for interacting with the Office client hosting environment.

 

Often, you will also need to consume third-party services or REST APIs within the Office Add-in. For example, you can consume the Microsoft Graph or even a custom set of REST APIs.

 

In case you want to consume third-party services from the HTML code of the Office Add-in and avoid any CORS or same-origin policy issues, you can just leverage some server-side code published by the web host that publishes the add-in, or you can leverage the JSON-P protocol.

 

Further details about the entire development model of the Office Add-ins, including an explanation of the available APIs and the techniques to work around CORS and same-origin policies, “Creating Office Add-ins.” This section gives only a general overview of the Office Add-ins development model.

 

When you think about the Office Add-ins, you should consider some different flavors of add-ins, which are described in the following list:

 

Task Pane The user interface is based on panels that are usually docked on the UI of the Office client application. The add-in will enhance the overall user experience, and it will not be tight to a specific document, but generally available in the UI of the Office clients.

 

Users can drag the task pane around the UI of the Office client, having a user experience similar to the out-of-box task panes provided by Office. A Task Pane add-in targets almost any Office client application like Word, Excel, Outlook, PowerPoint, and even Project.

 

Content This kind of add-in is useful to extend the content of a document. The overall user experience from an end user’s perspective is to embed an external object into the content of a document. A Content add-in targets only Excel, PowerPoint, or browser-based Access.

 

Outlook These add-ins target the mail or calendar appointment reading/composing experience and are usually activated based on a trigger like a specific word in the subject or body of a message, a particular sender of a received email message, and so on. An Outlook add-in targets Outlook client, Outlook Web App, and Outlook Web Access (OWA) for devices.

 

Command This kind of add-in can add buttons on the Office ribbon or on selected contextual menus. The overall goal is to provide the end users with the same user experience they have for consuming out-of-box capabilities when they consume Office Add-ins.

 

A Command add-in can be used to open a Task Pane add-in, to execute a command, or to insert custom content into a document. At the time of this writing, the App Command add-ins are supported in Outlook and are in the preview for Excel, Word, and PowerPoint.

 

To develop Office Add-ins, you can use almost any text editor because you just need to write the XML manifest file and the HTML/CSS/JS files.

 

However, by using Visual Studio Code or Visual Studio 2015 you can improve your quality of life because you will have some tooling for generating the XML manifest file for you and some autogenerated HTML and JavaScript code to speed up the overall add-in development process.

 

If you are using Visual Studio Code, you can consider leveraging a Yeoman Office Add-in generator, which will create all the scaffolding for you, and you will be able to implement them core functionalities of your Office Add-in without taking care of all the plumbing and details.

 

If you are using Visual Studio 2015 and the latest Office development tools for Visual Studio, you will be able to develop add-ins using all the professional tools available in Visual Studio 2015.

 

Nevertheless, it is fundamental to understand that to create Office Add-ins, you can use whatever development tool you like and whatever development platform you like, including The Official Microsoft ASP.NET Site, PHP, Node.js, and so on.

 

Once you have created an Office Add-in, you probably will want to install it on a testing environment. You can do this by leveraging the sideloading capabilities of Office Online.

 

You can find further details about sideloading add-ins for Word, Excel, and PowerPoint at the following URL: Sideload Office Add-ins for testing. You can find further information about sideloading Outlook add-ins at the following URL: msdn.microsoft.com/en-us/library/office/mt657707.aspx.

 

After proper testing, you will be able to release the add-in at the corporate level by using the add-in corporate catalog or even worldwide on the public marketplace by leveraging the Office Store, “Publishing your application and add-ins,” you will learn more about how to publish an Office Add-in, a SharePoint Add-in, or an Office 365 application either on the corporate catalog or in the Office Store.

 

Summary

In this blog, you had an overview of the most common and useful development techniques for extending and customizing Office 365.

 

First, you learned about how to set up your development environment properly, not only installing the most common tools like Visual Studio Code or Visual Studio 2015, but also installing and leveraging third-parties’ SDKs, libraries, and community projects to improve your code and your quality of life.

 

Then, you discovered Office 365 applications and the various flavors of projects like web applications, including full-page web applications, web API applications, single-page applications, and native applications. You also learned about the new Office 365 Connectors.

 

From a SharePoint perspective, you were introduced to SharePoint Add-ins, remote timer jobs, and remote event receivers, and you saw that you can use them to extend the SharePoint Online and SharePoint on-premises experiences.

 

You also had an overview of the remote provisioning techniques, which enable you to provision artifacts and configurations settings on both SharePoint Online and SharePoint on-premises.

 

Last, you had a sneak preview of the Office client development model. You saw the Office Add-in flavors available at the time of this writing and the support matrix related to the various versions of Office Online, Office 2013 or 2016 for Windows, and Office 2016 for Mac or iPad.

 

All the concepts you learned in this blog will be covered in detail in the upcoming sections, so by reading the remaining blogs of this blog, you will learn how to create real solutions leveraging all the potentials of the Office 365 ecosystem as a complete platform for developing custom solutions.

 

What is the Microsoft Graph API?

The Microsoft Graph API is a set of services, published through a unique and consolidated REST endpoint, that allow users to consume the main functionalities and the most useful capabilities of the services offered by Microsoft Office 365. 

  • Microsoft Exchange Online
  • Microsoft SharePoint Online
  • Microsoft Skype for Business
  • Microsoft OneDrive for Business
  • Microsoft Video Portal
  • Microsoft Power BI

 

Microsoft Azure Active Directory

Many other services will become available in the near future, leveraging a common model of consumption and a shared set of development patterns that make it easier for developers to consume the entire Office 365 platform and provide business-level solutions fully integrated with Office 365.

 

From a low-level perspective, those services can be consumed from any development platform such as Microsoft .NET Framework, Java, PHP, JavaScript/jQuery, Node.js, and so on. The only requirement is the capability to make HTTP requests and to handle the JSON serialization to encode requests and decode responses.

 

From a high-level perspective, the Microsoft Graph API is a way to consume all the services that were already available as a separate set of REST endpoints, through a unique set of rules and using a consolidated endpoint address.  For now, just consider that consolidation improves the code quality, performance, and usability of Microsoft Graph.

 

As you can see, the Microsoft Graph endpoint is a kind of wrapper on top of the APIs that were already available in Office 365 through the disparate Office 365 REST API, with the addition of some new API and the Office Graph insights and relationships. So far, the main services offered by the Microsoft Graph API are:

  • Users and Groups, which are services related to users’ information, groups’ definitions, and groups’ membership. 
  • Files, which target the OneDrive for Business service 
  • Mail, calendar, and contacts, which are services related to the Exchange Online service 

 

The authentication and authorization layer is provided by Microsoft Azure Active Directory (Azure AD), and from a development perspective, you will be able to implement a client wrapper within whatever development platform you choose, including Microsoft .NET, iOS, and Android.

 

From a URL perspective, the unified approach the Microsoft Graph API supports and sponsors allow you to consume all the services from a basic unique URL, which is https://graph.microsoft.com. To consume a specific API or service, you will have to append to the base URL the version number of the API that you want to consume and the name of the target API.

 

For example, if you want to consume version 1.0 of the Microsoft Graph, the URL will be like the following: http://graph.microsoft.com/v1.0/<service-specific-endpoint>

 

If you want to consume the beta version of the Microsoft Graph, you can substitute the v1.0 version number with the meta keyword, using a URL like the following: http://graph.microsoft.com/beta/<service-specific-endpoint>. 

 

In general, for any existing or future version of the API, the URL to consume it will be like the following:  http://graph.microsoft.com/<version>/<service-specific-endpoint>

 

Microsoft is also working on some open source SDK projects hosted on GitHub that allow you to consume the Microsoft Graph easily from custom developed solutions. These open source SDK projects can be accessed through the following URL:

http://graph.microsoft.io/code-samples-and-sdks

 

In particular, if you want to consume the Microsoft Graph API from a Microsoft .NET software solution, you can leverage the Microsoft Graph SDK library for .NET, which is available as a NuGet package in Microsoft Visual Studio. The name of the NuGet package is Microsoft.Graph.

 

On GitHub, under the Microsoft graph main organization that is available at the URL https://github.com/MicrosoftGraph/, there are samples of how to use the Microsoft Graph API within iOS (https://github.com/microsoftgraph/msgraph-sdk-ios) and Android (https://github.com/microsoftgraph/msgraph-sdk-android).

 

In general, if you want to leverage the Microsoft Graph API from any platform, you can always use the REST API directly via HTTP. You can also consider using the VIPR tool (https://github.com/microsoft/vipr), which is a toolkit for generating client libraries for an OData service. The VIPR tool supports C#, Objective-C, and Java. Internally, the Microsoft

 

Graph SDKs use the VIPR tool.

You can even use the Office 365 REST API; however, is not unified under a unique and common endpoint URL. The old development model already has client libraries targeting the main and most-adopted development platforms like Microsoft .NET, JavaScript, and some Open Source SDKs for Android and iOS.

 

In particular, there is a .NET client library that is still available on NuGet to consume the Office 365 REST API easily with Microsoft Visual Studio and the Microsoft Office development tools for Visual Studio.

 

This client library allows you to leverage the Office 365 REST API within a wide range of Microsoft .NET custom software solutions. The supported flavors of .NET software solutions that can leverage the .NET client library for the Office 365 REST API are:

  • .NET Windows Store apps
  • Windows Forms applications
  • WPF applications
  • http://ASP.NET MVC web applications
  • http://ASP.NET Web Forms applications
  • Xamarin Android and iOS applications

 

Multidevice hybrid apps

In this blog, you will focus on the Microsoft Graph API, and in the following blogs, you will see how to leverage it within Microsoft .NET Framework. From a technology choice perspective, you should use the new Microsoft Graph API as much as you can and avoid using the per-service REST API.

 

In the following sections, you will find many more details about the main and most relevant Microsoft Graph services. To properly consume them, you will have to leverage an HTTP and REST client tool.

 

Microsoft, for testing and development purposes, provides a tool with a web-based UI that is called Graph Explorer. It is available at the following URL: https://graph.microsoft.io/en-us/graph-explorer 

 

REST API.

Another useful tool for testing any REST API is Fiddler, which is a free tool made available by Telerik. It can be downloaded from the following URL: http://www.telerik.com/fiddler

 

Microsoft Graph API metadata

Before diving into some of the available flavors of the provided API, it is useful to note that the Microsoft Graph API adheres to the OData 4.0 protocol specification.

 

Thus, the first thing you can do to discover the entire set of available entities, actions, and services is to query the metadata of the OData service. You just need to make an HTTP GET request for the following URL:

 

https://graph.microsoft.com/v1.0/$metadata

 

This URL is freely available and does not require any kind of authentication. Thus, you can plan to periodically query for that URL in an unattended process to refresh the metadata of the provided services and rebuild any autogenerated client library—for example, one built using the VIPR tool that you saw in the previous section.

 

If you use any of the SDK provided by Microsoft, you can just keep the SDK package updated.

 

The result of such an HTTP request will be an XML-based representation of the Microsoft Graph API metadata, leveraging the EDMX namespace (http://docs.oasis-open.org/odata/ns/edmx).

 

It is out of the scope of this blog to comment in detail on the resulting metadata XML. However, it is useful to examine the structure of the EntityContainer element, which is unique for each metadata document and defines the entity sets, singletons, function, and action imports exposed by the OData service. 

https://graph.microsoft.com/<version>/<targetEntitySet|singleton|function|action>

 

Each of the previous entity sets or singletons returns a definition based on a single EntityType XML element, which is detailed in the metadata schema. For example, for the user's collection, each user element is of type Microsoft.Graph.user, which is defined in a specific EntityType element.

 

The Microsoft.Graph.User definition declares the properties available for every user object, like displayName, givenName, and so on. Moreover, every user object provides a set of navigation properties, like messages, calendars, events, and drive, and each navigation property leads to another collection of objects.

 

This makes it possible to navigate the directory as an object hierarchy with a fluent approach.

 

Note that the behavior described for the Microsoft.Graph.User type can be applied to any other EntityType defined in the metadata schema. 

 

In the following sections, you will see some of these entities in more detail, working with direct HTTP requests, to better understand how to consume the Microsoft Graph API from any device or platform capable of using the HTTP protocol.

 

Consuming users and security groups

Let’s start consuming some services related to the current user, other users, and groups. As you saw in Figure, the main endpoint of the Microsoft Graph API is based on the URL Microsoft Graph, and you have to append the protocol version and the target service to this base URL. Notice that the Microsoft Graph API URLs are not case-sensitive.

 

All the sample HTTP requests and responses illustrated from here to the end of this blog can be simulated by using the Microsoft Graph Explorer or Fiddler.

 

For the sake of completeness, included in the code samples of this blog you will find a file (Microsoft-Graph-Samples.saz) that represents a trace saved from Fiddler that reproduces all of the requests illustrated.

 

Yourself and other users

Accessing the current user’s profile, the user’s properties, and the assigned Office 365 licenses is a well-known use case. In fact, whenever you create an app or an external tool that leverages the Office 365 services, you probably will have to define the current user’s context.

 

To access the current user, the entry point is https://graph.microsoft.com/v1.0/me/. You can consume that URL with an HTTP GET request, providing the proper authentication information.

 

In response, you will get a JSON object that will define a bunch of useful information. Depending on the Accept HTTP header for controlling OData, you can request an object with three different behaviors:

 

Accept: application/json;odata.metadata=none; => The service should omit any metadata information. The only OData metadata attribute provided, if any, will be the @odata.nextLink to provide the link to the next page of objects when browsing for an entity set.

 

Accept: application/json;odata.metadata=minimal; => The service should remove computable control information from the response payload.

Only the attributes @odata.context, @odata.nextLink (if any), @http://odata.id, and a few others will be provided in the response payload.

Accept: application/json;odata.metadata=full; =>

The service must include all the control information explicitly in the response payload.


Based on the data.metadata attribute that you provide, the payload size can be very different.

 By default, if you omit the odata.metadata attribute, the Microsoft Graph API applies a minimal behavior for OData metadata. 

In Listing, you can see an excerpt of such a JSON response, based on minimal metadata.

 

LISTING An excerpt of a JSON response for the https://graph.microsoft.com/v1.0/me/ API request

{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users/$entity",
"@odata.type": "#microsoft.graph.user",
"@http://odata.id": "users/bea7a848-0459-4bee-9034-5513ee7f66e0",
"businessPhones": [
"030-22446688"
],
"displayName": "Thesis Scientist",
"givenName": "Paolo",
"jobTitle": null,
"mail": "Thesis@SysDev.onmicrosoft.com",
"mobilePhone": "+391234567890",
"officeLocation": null,
"preferredLanguage": "en-US",
"surname": "Pialorsi",
"userPrincipalName": "Thesis@PiaSysDev.onmicrosoft.com",
"id": "bea7a848-0459-4bee-9034-5513ee7f66e0"
}

 

As you can see, there is information about the JSON object itself, which is an instance of a Microsoft.Graph.User type. There is information about the current user such as address, display name, telephone, email, and so on.

 

Another set of information that deserves attention is the list of properties related to on-premises directory synchronization if it is configured.

 

For example, you can see the on-premises user’s SID (onPremisesImmutableId), when the last synchronization happened (onPremisesLastSyncDateTime), and so on. Last, you will find the proxy address and the fundamental UPN (User Principal Name), which will be a unique identifier for the current user.

 

You can use the UPN to access any specific user profile as long as you have the permissions to consume the user’s directory in Azure AD. Let’s say that you want to access the entire list of users for a specific tenant.

 

You can make an HTTP GET request for the following URL: https://graph.microsoft.com/v1.0/users. In this case, the result will be a JSON representation of an array of Microsoft.Graph.User objects.

 

If you want to access the profile properties of a specific user, you can make an HTTP GET request for the following URL: https://graph.microsoft.com/v1.0/users/UPN.

 

For example, when the current user has a UPN value like name@domain.com, the following URL defines a direct entry point to the user’s profile: https://graph.microsoft.com/v1.0/users/name@domain.com.

 

It is also possible to read the values of single properties instead of getting the entire JSON object. Moreover, there are complex properties like the user’s photo that can be accessed only through a direct request. To access a single property, you can append the property name to the URL path of the user’s profile URL. 

 

LISTING The HTTP GET request for the userPrincipalName property of the current user

GET /v1.0/me/userPrincipalName HTTP/1.1
Authorization: Bearer eyJ0...
Host: http://graph.microsoft.com
Content-Length: 0
In Listing 3-3, you can see the response that you should get back.
LISTING 3-3 The HTTP response for the current user’s userPrincipalName property
HTTP/1.1 200 OK
Cache-Control: private
Content-Type:
application/json;odata.metadata=minimal;odata.streaming=true;IEEE754Compatib
le=false;charset=utf-8
Server: Microsoft-IIS/8.5
request-id: 0c2f199c-782e-4918-8bd0-91b0c246a9c8
client-request-id: 0c2f199c-782e-4918-8bd0-91b0c246a9c8
OData-Version: 4.0
OutBoundDuration: 71.2145
Duration: 113.3553
X-Powered-By: http://ASP.NET
Date: Sat, 05 Sep 2015 08:54:52 GMT
Content-Length: 192
{"@odata.context":"https://graph.microsoft.com/v1.0/$metadata#users('<UserID>')/us palName","value":"paolo@<tenant>.http://onmicrosoft.com"}

 

Notice that the response contains a bunch of useful information like the ID of the request, the target server version and engine, and the overall duration of the request processing. The response is in JSON format, and you should deserialize it.

 

However, you can also directly access the bare property value as text by appending the $value path to the property URL. The final URL will look like the following:

https://graph.microsoft.com/v1.0/me/userPrincipalName/$value

 

This technique becomes increasingly useful when you want to retrieve binary properties like the user’s photo.

 

By providing the $value path at the end of the user’s photo property, you will get back the binary image file directly, which is useful for creating great user experiences in your applications. In Listing, you can see the user’s photo request.

 

LISTING The HTTP GET request for the photo binary property value of the current user

GET /v1.0/me/photo/$value HTTP/1.1

Authorization: Bearer eyJ0...

Host: http://graph.microsoft.com

Content-Length: 0

 

In Listing you can see the response from an HTTP perspective.

LISTING The HTTP response for the binary value of the current user’s photo property
HTTP/1.1 200 OK
Cache-Control: private
Content-Type: image/jpeg
Server: Microsoft-IIS/8.5
request-id: 528841c7-eda8-4eb7-99f7-b241be2b66f9
client-request-id: 528841c7-eda8-4eb7-99f7-b241be2b66f9
OutBoundDuration: 1080.2745
Duration: 1268.9802
X-Powered-By: http://ASP.NET
Date: Sat, 05 Sep 2015 08:26:09 GMT
Content-Length: 31194

 

You can read information about yourself or other users, and you can update that information if you have proper permissions. To change data or execute operations, you will have to switch from HTTP GET requests to other HTTP verbs like POST, PATCH, and so on.

 

For example, to update your current mobile phone number, you can make an HTTP PATCH request against your profile URL (https://graph.microsoft.com/v1.0/me).

 

You will have to provide a JSON object that defines the profile properties that you want to patch. It is fundamental in this case to set the Content-Type header of the request according to the JSON. 

 

LISTING The HTTP PATCH request to update the mobile phone number of the current user

PATCH /v1.0/me HTTP/1.1
Authorization: Bearer eyJ0...
Host: http://graph.microsoft.com
Content-Type: application/json;
Content-Length: 31
{ "mobilePhone":"+39-123456789" }

 

LISTING The HTTP response for the current user’s profile update request

HTTP/1.1 204 No Content
Cache-Control: private
Transfer-Encoding: chunked
Content-Type: text/plain
Server: Microsoft-IIS/8.5
request-id: fbb823c4-0de9-40e1-bba1-eb5b9101baac
client-request-id: fbb823c4-0de9-40e1-bba1-eb5b9101baac
OutBoundDuration: 491.0361
Duration: 494.4198
X-Powered-By: http://ASP.NET
Date: Sat, 05 Sep 2015 07:07:27 GMT
From a content perspective, the response just confirms that the operation was successful (HTTP Status 204).

 

Security groups

Through the Microsoft Graph API, you can also access groups, including both security groups, synchronized across premises using directory synchronization tools, and the new Office 365 Groups, which are also called Unified Groups from an Office 365 perspective. The new Office 365 Groups are covered later in this blog in the section “Working with Office 365 Groups.”

 

The security groups are accessible as objects of type Microsoft.Graph.Group through the following URL: https://graph.microsoft.com/v1.0/groups

 

The URL returns the entire list of groups, regardless of whether they are security groups or Office 365 Groups. However, you can play with the group types of property, which has a null value for security groups and a value of Unified for any Office 365 Group. 

 

You can also access any specific group by providing the group’s ID in the URL. For example: https://graph.microsoft.com/v1.0/groups/<Group_ObjectId>

 

To access the members of a specific group, you can add the member's keyword at the end of the single group endpoint URL.

 

Consuming mail, contacts, and calendars

Now that you have learned how to consume users, security groups, and licenses, you are ready to leverage the other APIs—for example, those for Microsoft Exchange Online, which is another common and useful scenario.

 

Thanks to the unified API model, the base URL remains the same; you just have to change the relative URL of the service endpoint. The personal emails of the current user are available through the following base URL: https://graph.microsoft.com/v1.0/me/Messages

 

Mail messages

As already stated, to access the current user’s mailbox, you can query the https://graph.microsoft.com/v1.0/me/Messages URL.

 

The result will be an array of JSON objects of type Microsoft.Graph.Message or of type Microsoft.Graph.EventMessage, which are the email messages and the event-related messages in the current user’s mailbox, regardless of the folder in which they are stored. 

 

It is interesting to notice that by default, the mail service will do output paging and, unless you specify something different in the OData query sent to the service, the default page size will be 10 items per page.

 

At the beginning of the JSON answer, you will find a property with name @odata.nexLink that contains the URL to access the next page of results, and this kind of “next page” link will be available in any requested page.

 

As a result, developers are obliged to do paging, which is a good habit but unfortunately is not always common practice.

 

Moreover, you can see that each message provides well-known information like subject, sender, recipients, content, parent folder Id, and so on. One fundamental piece of information for each message is the Id property.

 

By appending a specific message Id at the end of the path of the message, you can access that specific message item directly.

 

The HTTP GET request will look like the following, where the message Id has been truncated for typographic needs:https://graph.microsoft.com/v1.0/me/messages/AAMk...AA=

 

The response will be a JSON object of type Microsoft.Graph.Message with the same properties that were available for each message within the list of messages.

 

Because we are using the OData protocol to query the Microsoft Graph API, we can also use the standard protocol’s syntax to project a subset of properties or to partition the results.

 

For example, imagine that you want to retrieve just the Id, Subject, From, and To Recipients properties of the current message. In Listing, you can see the HTTP GET request to achieve this result, which will target the following URL:

https://graph.microsoft.com/v1.0/me/messages/AAMk...AA=?
$select=Id,Subject,From,ToRecipients
LISTING The HTTP GET request for a subset of properties for a specific email message
GET /v1.0/me/messages/AAMk...AA=?$select=Id,Subject,From,ToRecipients HTTP/1.1
Authorization: Bearer eyJ0...
Host: http://graph.microsoft.com
Content-Type: application/json
Content-Length: 31

In Listing, you can see the response that you should get back.

 

LISTING The JSON response for a projection of properties of a specific email message

{
"@odata.context":
"https://graph.microsoft.com/v1.0/<tenant>/$metadata#users('paolo.
pialorsi%40sharepoint
-http://camp.com')/Messages/$entity", "@odata.type": "#Microsoft.Graph.Message", "@http://odata.id": "users/paolo.pialorsi%40sharepoint-
http://camp.com/MeNzAwL WFkZGExY2M5NDRlZQBGAAAAAAAENAAB VRa8oaXCdnl9HAAIQ3Vk_AAA%3D",
"@odata.etag": "W/\"CQAAABYAAABrFd4C2tvVRa8oaXCdnl9HAAJVc9Lf\"", "Id":
"AAMkADU4Zjk3ZTQzLWFjMDctNDM5Mi04NzAwLWFkZGExY2M5NDRlZQBGAAAAAACIOUtE7VENSpDAypZBE Q3Vk_AAA=",
"Subject": "This is a sample message!",
"From": {
"EmailAddress": {
"Address": "someone@contoso.com",
"Name": "someone@contoso.com"
}
},
"ToRecipients": [
{
"EmailAddress": {
"Address": "paolo.pialorsi@sharepoint-camp.com",
"Name": "Thesis Scientist"
}
}
]
}

 

If you want to filter all the messages in the current user’s inbox based on a specific subject value, here is the corresponding OData query URL:

 https://graph.microsoft.com/v1.0/me/messages? $filter=Subject%20eq%20’Office%20365%20blog’

 

Sending an email message by using the Microsoft Graph API is also a simple task. You just need to make an HTTP POST request with the JSON object representing the message to send and targeting the URL of the list of messages to store the message as a draft. In Listing, you can see the HTTP POST request to achieve this result.

 

LISTING The HTTP POST request to save a draft of a new email message

POST /v1.0/me/messages HTTP/1.1
Authorization: Bearer eyJ0...
Host: http://graph.microsoft.com
Content-Length: 383
Content-Type: application/json
{
"Subject": "Sample email from Microsoft Graph API",
"Body": {
"ContentType": "HTML",
"Content": "Hey! This email comes to you from the <b>Microsoft Graph API</b>!"
},
"Importance": "High",
"ToRecipients": [
{
"EmailAddress": {
"Address": "Thesis@gmail.com.com"
}
}
]
}

 

The HTTP response that you will get back will be the JSON representation of the just-saved draft message. In the message object, you will see the IsDraft property with a value of true.

 

To send that message, you will need to invoke the send action, which can be addressed by appending the send keyword at the end of the URL of the message and using an HTTP POST method. 

 

LISTING The HTTP POST request to send a draft email message

POST /v1.0/me/messages/AAMk...AA=/send HTTP/1.1

Authorization: Bearer eyJ0...

Host: http://graph.microsoft.com

Content-Length: 0

 

Content-Type: application/json

The HTTP response will confirm that the message has been sent by providing an HTTP Status Code with a value of 202 (Accepted). Note that if you have sent a message draft and you try to send it again, the REST API call will fail because the engine will not find that draft (HTTP Status 404 Not Found).

 

If you try to retrieve the just-sent message, it will no longer be available. The message draft has been sent and moved to the Sent Items folder, where you will find the message with the IsDraft property with a value of false, which means that the message has been sent.

 

To access a specific mail folder, you can use the mail folders navigation property of any Microsoft.Graph.User object for which the current user has the rights to access the mailbox. For example, the following URL retrieves the list of available mail folders: https://graph.microsoft.com/v1.0/me/mailFolders

 

As with the mail messages, you can access any specific folder by Id, and you can browse the messages of that specific folder by appending the messages keyword to the URL of the folder.

 

 Another option for sending an email message quickly is to directly leverage the Sendmail action, which is available for any object of type Microsoft.Graph.User. In Listing, you can see the HTTP POST request to invoke the action, which is available as microsoft.graph.sendMail or just Sendmail.

 

LISTING  The HTTP POST request to send an email message

POST /v1.0/me/sendMail HTTP/1.1
Authorization: Bearer eyJ0...
Host: http://graph.microsoft.com
Content-Length: 383
Content-Type: application/json
{
"Message": {
"Subject": "Sample email from Microsoft Graph API",
"Body": {
"ContentType": "HTML",
"Content": "Hey! This email comes to you from the <b>Microsoft Graph
API"
},
"ToRecipients": [
{
"EmailAddress": {
"Address": "thesis@gmail.com"
}
}
]
},
"SaveToSentItems": "true"
}

 

Again, the HTTP response will confirm that the message has been sent by providing an HTTP Status Code with a value of 202 (Accepted). 

 

If you want to reply to a received message, you can leverage the reply action provided by each message instance. You just need to make an HTTP POST request targeting the message to which you want to reply and appending the reply path to the URL of the message.

 

Within the HTTP POST request body message, you provide a JSON response made of a comment property, which will be the response to the received message. In Listing, you can see a sample reply to a message.

 

LISTING The HTTP POST request to reply to a specific email message

POST /v1.0/me/messages/AAMk...AA=/reply HTTP/1.1
Authorization: Bearer eyJ0...
Host: http://graph.microsoft.com
Content-Type: application/json
Content-Length: 59
{
"Comment": "Wow! This message is really amazing!"
}

 

The response will be empty with an HTTP Status Code with a value of 202 (Accepted).

To reply to all the recipients of a message, there is the reply action that has to be invoked like the reply action. To forward the message to someone, you can use the forward action, which accepts in the HTTP POST request a list of recipients who will receive the forwarded message and an optional comment that will be included in the forwarded message. In Listing, you can see a message forwarding example.

 

LISTING The HTTP request to forward a message to someone, including a comment

POST /v1.0/me/messages/AAMk...AA=/forward HTTP/1.1
Authorization: Bearer eyJ0...
Host: http://graph.microsoft.com
Content-Type: application/json
Content-Length: 237
{
"Comment": "Please read and give me a feedback...",
"ToRecipients": [
{
"EmailAddress": {
"Address": "someone@contoso.com"
}
},
{
"EmailAddress": {
"Address": "paolo.pialorsi@sharepoint-camp.com"
}
}
]
}

 

Some other interesting actions are move, which moves an email from one folder to another, and copy, which copies a message from one folder to another. Both the move and copy actions accept a JSON object that declares where to move or copy the message.

 

 One more common use case is the deletion of a message, which can be accomplished by making an HTTP DELETE request targeting the URL of the email message.

 

LISTING The HTTP request to delete an email message

DELETE /v1.0/me/messages/AAMk...AA= HTTP/1.1
Authorization: Bearer eyJ0...
Host: http://graph.microsoft.com
Content-Type: application/json
Content-Length: 0

 

The response will be empty with an HTTP Status Code with a value of 204 (No Content). The last use case related to messages and emails is the handling of attachments.

 

To enumerate the attachments of an email, if any, you need to make an HTTP GET request targeting the email’s direct URL and appending the attachments keyword at the end of the URL. This will give you access to the collection of attachments.

 

LISTING  The HTTP request to access the collection of attachments of an email message

GET /v1.0/me/messages/AAMk...AA=/attachments HTTP/1.1
Authorization: Bearer eyJ0...
Host: http://graph.microsoft.com
Content-Type: application/json
Content-Length: 0

In Listing, you can see an excerpt of the JSON response that enumerates the attachments of an email message.

 

LISTING An excerpt of the HTTP response that enumerates the attachments of an email message

HTTP/1.1 200 OK
Cache-Control: private
Content-Type: application/json;odata.metadata=minimal;odata.streaming=true
;IEEE754Compatible
=false;charset=utf-8
Server: Microsoft-IIS/8.5
request-id: a3c1cd57-f2a0-4c0b-8a76-409c7f848fea
client-request-id: a3c1cd57-f2a0-4c0b-8a76-409c7f848fea
OData-Version: 4.0
OutBoundDuration: 165.8664
Duration: 175.4871
X-Powered-By: http://ASP.NET
Date: Sat, 05 Sep 2015 14:15:39 GMT
Content-Length: 720
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('paolo.
pialorsi%http://40sharepoint-camp.com')
/Messages('AAMkADU4Zjk3ZTQzLWFjMDctNDM5Mi04NzAwLWFkZGExY2M5NDRlZQBGAAAAAACIOUtE7VE
BE6ONBwBrFd4C2tvVRa8oaXCdnl9HAAAAAAENAABrFd4C2tvVRa8oaXCdnl9HAAIQ3Vk3AAA%3D')/Atta
,
"value": [
{
"@odata.type": "#Microsoft.Graph.fileAttachment",
"@http://odata.id": "users/paolo.pialorsi%http://40sharepoint-camp.com/Messages/
AAMkADU4Zjk3ZTQzLWFjMDctNDM5Mi04NzAwLUhYBJDQ%3D",
"Id":
"AAMkADU4Zjk3ZKkGk=",
"Name": "CEM41wGUUAEjpHH.jpg",
"ContentType": "image/jpeg",
"Size": 110796,
"IsInline": false,
"DateTimeLastModified": "2015-05-06T03:45:26Z", "ContentId":
"A4216D1F77482F49B2765EBDD1788161@eurprd01.prod.exchangelabs.com", "ContentLocation": null,
"IsContactPhoto": false,
"ContentBytes": "LzlqLzRBQVFTa1pKUmdBQkFRQUFBUUFCQUFELzJ..."
}
]
}

 

As you can see, the result is a JSON array of objects of type Microsoft.Graph.FileAttachment, in which each item is identified by a unique Id property.

 

Moreover, you can see there are fundamental properties like the ContentType and the ContentBytes that allow you to access the real file attachment properly typed from a content-type perspective.

 

If you want to access a specific attachment file, you can append the value of the related Id to the URL of the collection of attachments.

 

Contacts

The current user’s contacts are another useful capability that is available through the new Microsoft Graph API. To consume the contacts, you have to make an HTTP GET request against the following URL:

 

 https://graph.microsoft.com/v1.0/<user>/contacts In Listing, you can see an excerpt of the resulting JSON response, which represents an array of objects of type Microsoft.Graph.Contact.

 

LISTING An excerpt of the HTTP response that enumerates the organizational or personal contacts in a tenant

{
"@odata.context":
"https://graph.microsoft.com/v1.0/$metadata#users('paolo.pialorsi%40sharepoint-
http://camp.com')
/contacts",
"value": [
{
"@odata.etag": "W/\"EQAAABYAAABrFd4C2tvVRa8oaXCdnl9HAAIQ4ll9\"", "id":
"AAMkADU4Zjk3ZTQzLWFjMDctNDM53XCjAAA=",
"createdDateTime": "2015-09-06T08:41:30Z",
"lastModifiedDateTime": "2015-09-06T08:41:30Z",
"changeKey": "EQAAABYAAABrFd4C2tvVRa8oaXCdnl9HAAIQ4ll9",
"categories": [],
"parentFolderId":
"AAMkADU4Zjk3ZTQzLWFjMDctNAypZBEd4C2tvVRa8oaXCdnl9HAAAAAAEPAAA=",
"birthday": null,
"fileAs": "Green, Mike",
"displayName": "Mike Green",
"givenName": "Mike",
"initials": null,
"middleName": null,
"nickName": null,
"surname": "Green",
"title": null,
"yomiGivenName": null,
"yomiSurname": null,
"yomiCompanyName": null,
"generation": null,
"emailAddresses": [
{
"name": "Mike Green",
"address": "mike.green@contoso.com"
}
],
"imAddresses": [],
"jobTitle": null,
"companyName": null,
"department": null,
"officeLocation": null,
"profession": null,
"businessHomePage": null,
"assistantName": null,
"manager": null,
"homePhones": [],
"businessPhones": [],
"homeAddress": {},
"businessAddress": {},
"otherAddress": {},
"spouseName": null,
"personalNotes": null,
"children": []
},
...
]
}

The structure of contact is defined in the metadata XML document for the Microsoft Graph API. You can see there is an Id property, which can be used to retrieve a specific contact instance directly.

 

Moreover, there are all the common properties for contact, like displayName, email addresses, companyName, and so on.

 

You can also browse users’ various contact folders by querying the contact folders navigation property of an object of type Microsoft.Graph.User. Every contact folder can be accessed by Id, and you can browse its contacts through the contacts navigation property.

 

You can even add contacts or contact folders by making an HTTP POST request against the target collection and providing the JSON representation of the object to create.

 

Calendars and events

Another common use case is the consumption of calendars and events, which are available through a user-oriented set of URLs.  For example, in Listing, you can see the JSON representation of the default calendar for the current user.

 

LISTING An excerpt of the HTTP response that represents the default calendar of the current user

{
"@odata.context":
"https://graph.microsoft.com/v1.0/<tenant>/$metadata#users('paolo.
pialorsi%40sharepoint
"@odata.type": "#Microsoft.Graph.Calendar",
"@http://odata.id": "users/paolo.pialorsi%http://40sharepoint-camp.com/Calendar",
"Id":
"AAMkADU4Zjk3ZTQzLWFjMDctNDM5Mi04NzAwLWFkZGSpDAypZ
d4C2tvVRa8oaXCAAA=", "Name": "Calendar",
"ChangeKey": "axXeAtrb1UWvKGlwnZ5fRwACEOJhrw==",
"Color": "LightGreen"
}

 

The object is a JSON serialization of type Microsoft.Graph.Calendar, which is made of a few properties like Name, Color, and Id. If you invoke the calendars entry point, you will get back an array of objects of type Microsoft.Graph.Calendar.

 

Once you have a calendar, regardless of whether it is the default calendar or a secondary calendar, you can access the events of a specific time and date interval by invoking the calendarView navigation property through an HTTP GET request and providing a couple of query string arguments to declare the startDateTime and the endDateTime in UTC time format.  

 

As you can see, the response includes all the typical information for an event, like Subject, Body, Start and End dates (including their time zone), ShowAs, Attendees, Responses,

 

Organizer, and so on.

You can also access the entire list of events for the current user by invoking the events navigation property of the current calendar or of the current user through an HTTP GET request. The events navigation property will give you back a JSON array of Microsoft.Graph.Event objects. 

 

As with email messages, discussed in the previous section, you can add, update, or delete calendar events by leveraging the various HTTP verbs. 

 

LISTING  The HTTP request to add a new event to the current user’s default calendar

POST /v1.0/me/calendar/events HTTP/1.1
Authorization: Bearer eyJ0...
Host: http://graph.microsoft.com
Content-Length: 599
Content-Type: application/json
{
"Subject": "Sample meeting create via Microsoft Graph API",
"Body": {
"ContentType": "HTML",
"Content": "The <b>Microsoft Graph API</b> really rock!"
},
"start": {
"@odata.type": "#microsoft.graph.dateTimeTimeZone",
"dateTime": "2015-12-22T16:30:00.0000000",
"timeZone": "UTC"
},
"end": {
"@odata.type": "#microsoft.graph.dateTimeTimeZone",
"dateTime": "2015-12-22T17:00:00.0000000",
"timeZone": "UTC"
},
"Attendees": [
{
"EmailAddress": {
"Address": "someone@contoso.com",
"Name": "Thesis Scientist"
},
"Type": "Required"
}
],
"Location": {
"DisplayName": "Headquarters"
},
"ShowAs": "Busy",
}

 

The HTTP response will confirm that the event has been created by providing an HTTP Status Code with a value of 201 (Created). If you want to update an existing event, you can make an HTTP PATCH request, targeting that event by Id and sending the updated properties as a JSON object.

 

For example, in Listing, you can see how to update the Subject property of the just-created event.

 

LISTING The HTTP request to update an existing event in the current user’s default calendar

PATCH /v1.0/me/calendar/events/AAMkADU... HTTP/1.1
Authorization: Bearer eyJ0...
Host: http://graph.microsoft.com
Content-Length: 79
Content-Type: application/json
{
"Subject": "Sample meeting create via Microsoft Graph AP – Updated!"
}

 

The HTTP response will confirm the successful update by providing an HTTP Status Code with a value of 200 (OK) and providing the JSON serialization of the updated event in the response body. Last, if you want to delete an event from a calendar, you can use the HTTP DELETE method, targeting the event URL.

 

The response will be an HTTP Status Code 204 (No Content), meaning that the event has been deleted. Under the cover, Microsoft Exchange Online will handle all the email notifications like sending invitations, updates, and event cancellations.

 

It is interesting to note that the same REST-based techniques used for managing single events can be used to manage calendars. For example, you can create, update, or delete a secondary calendar by targeting the collection:

https://graph.microsoft.com/v1.0/me/calendars

 

This is a powerful capability that enables you to create custom software solutions that can completely handle messages, contacts, calendars, and events via REST.

 

Event invitations

Another common scenario is to manage invitations for events sent to the current user by third parties. In Microsoft Exchange Online, any meeting invitation will automatically be placed in the target user’s default calendar, as happens on-premises.

 

Thus, to access an invitation, you just need to target the specific calendar event object that you want to manage by providing the Id of the object. 

 

LISTING An excerpt of the JSON object representing a meeting request the current user has received

{
"@odata.context":
"https://graph.microsoft.com/v1.0/$metadata#users('thesis%40sharepoint-
http://camp.com')
/Calendar/Events/$entity",
"@odata.type": "#Microsoft.Graph.Event",
"@http://odata.id":
"users/paolo%http://40PiaSysDev.onmicrosoft.com/Calendar/Events/AAMkADU4Zjk3ZTQzLWFjMDctN
zAwLWFkZGExY2M5NDRlZQBGAAAAAACIOUtE7VENSpDAypZBE6ONBwBrFd4C2tvVRa8oaXCdnl9HAAAAAAE
C2tvVRa8oaXCdnl9HAAIQ3Xh2AAA%3D",
"Id":
"AAMkADU4Zjk3ZTQzLWFjMDctNDM5Mi04NzAwLWFkZGExY2M5NDRlZQBGAAAAAACIOUtE7VENSpDAypZ
d4C2tvVRa8oaXCdnl9HAAAAAAEOAABrFd4C2tvVRa8oaXCdnl9HAAIQ3Xh2AAA=",
...
"Importance": "Normal",
"HasAttachments": false,
"start": { "@odata.type": "#microsoft.graph.dateTimeTimeZone",
"dateTime": "2015-12-22T16:30:00.0000000",
"timeZone": "UTC"
}, "end": {
"@odata.type": "#microsoft.graph.dateTimeTimeZone",
"dateTime": "2015-12-22T17:00:00.0000000",
"timeZone": "UTC"
},
...
"ResponseStatus": {
"Response": "not responded",
"Time": "0001-01-01T00:00:00Z"
},
...
}

 

As you can see highlighted in bold text, there are Id and ResponseStatus properties, together with the rich set of properties defining the event. If the ResponseStatus property has a value of not responded for the property with name Response, it means that the meeting request is pending response.

 

To accept the meeting request, you can make an HTTP POST request targeting the event URL and appending the accept operation to the URL. The ResponseStatus property of the target event will assume a value of Accepted for the property with name Response, and the Time property will assume the value of the date and time when you accepted the meeting request.

 

To decline a meeting request, the operation to append to the URL of the event is decline. To give a tentative answer, you can append the tentatively accept operation to the URL of the event.

 

Regardless of whether you accept, decline, or tentatively accept the meeting request, you will have the option to provide to the meeting organizer a response message that will be provided to the REST API as a JSON object in the body of the request. 

 

LISTING The HTTP request to accept a meeting request, providing a comment to the meeting organizer

POST /v1.0/me/calendar/events/AAMkADU.../accept HTTP/1.1
Authorization: Bearer eyJ0...
Host: http://graph.microsoft.com
Content-Length: 59
Content-Type: application/json;charset=utf-8;odata=minimalmetadata
{
"Comment": "Sure, I'm looking forward to meet you!"
}

The HTTP response will confirm the successful response by providing an HTTP Status Code with a value of 202 (Accepted).

 

Consuming OneDrive for Business

Another useful set of operations and services is related to OneDrive for Business. To access the files for the current user, you need to target the HTTP endpoint available at the URL https://graph.microsoft.com/v1.0/me/drive. 

 

Through the OneDrive URL, you can read information about the owner of the drive and about the storage quota and available storage space. By browsing the navigation properties of the drive, you can access all of its contents.

 

Querying files and folders

The first step to access the files of a OneDrive for Business drive instance is to query the root navigation property of the drive by using a URL like the following: https://graph.microsoft.com/v1.0/me/drive/root

 

By making an HTTP GET request for the items URL, you will get back a JSON array of objects of type Microsoft.Graph.driveItem, which can be a folder item or a single file item.

 

By default, the query for the children of the root URL will return only those files and folders defined in the root folder of the current user’s OneDrive for Business. If you want to browse the available folders, you have to do it manually, accessing every folder by Id. 

 

There is also a useful set of item properties like name, createdBy, lastModifiedBy, createdDateTime, lastModifiedDateTime, web URL, and so on. The web URL property for a file allows direct access to the file content through a direct URL, which is a useful capability.

 

Moreover, when the resulting item is a folder, you will also find the childCount property that indicates whether there are child items (subfolders or files) within that folder.

 

Let’s say that you want to access the Sample Share folder defined in the result presented in Listing. You will just need to make an HTTP GET request for the following URL:

 

https://graph.microsoft.com/v1.0/me/drive/items where the value at the end of the URL is the unique Id of the folder. If you prefer to access the folder by name instead of by using the unique Id, you can use a URL like the following:

 

https://graph.microsoft.com/v1.0/me/drive/root/children/Sample%20Share

 

However, by doing this you will not access the files—just the folder object and its properties. To access any child files or folders, you can query the children navigation property of the Microsoft.Graph.drive them type. In Listing, you can see a sample of this kind of request.

 

LISTING  The HTTP GET request for the children of a folder in OneDrive for Business for the current user

GET /v1.0/me/drive/items/01MDKYG3G3MLQJYQ7CUZG3GQRA7MBBY57D/children HTTP/1.1

Authorization: Bearer eyJ0...

Host: http://graph.microsoft.com

Content-Length: 0

 

Content-Type: application/json

The result will be an array of objects of type Microsoft.Graph.driveItem and will look like. Using this approach, you can navigate through the hierarchy of folders in OneDrive for Business.

 

Other interesting capabilities that are available for folders and files are the navigation properties to access the createdByUser and the lastModifiedByUser objects. Through these navigation properties, you can access the object of type Microsoft.Graph.

 

The user that represents the user who created the item and the user who last modified the item. This is another way to traverse the graph and to access the objects described in the previous section, “Consuming users and security groups.”

 

You can also empower the OData querying capabilities, as you did with the email messages, to retrieve just a subset of files or folders, to select a subset of properties, or to customize the order of results. 

 

One last use case to consider is downloading a file. To retrieve the raw content of a file, you can make a direct HTTP GET request for the URL of the Microsoft.Graph.drive them object instance, appending the content function name just after the file URL.

 

The URL will look like the following: https://graph.microsoft.com/v1.0/me/drive/items/01MDKYG3EIHAILISRHVBDJQVXKTI3

 

The result will be an HTTP Status Code with a value of 302 (Redirect), which will redirect the HTTP request to the real URL of the file in OneDrive for Business, providing a temporary guest access token that will be valid for a small amount of time (approximately two hours).

 

It is interesting to notice that you can also leverage the web URL property, which will open the file in the web browser instead of providing the content for download.

 

This capability is useful to access Microsoft Office files within the browser to leverage the document rendering and editing capabilities of Office web applications.

 

Managing files and folders

In the previous section, you learned how to query folders and files, traverse the folder hierarchy, and download files directly. In this section, you will see how to create new folders and files, update the properties and content of files, and move or delete a file.

 

Let’s start by creating a folder. You just need to make an HTTP POST request against the children collection of items of the parent folder in which you would like to create the new folder.

 

For example, imagine that you want to create a new folder called “Child Folder” in the existing folder named “Sample Folder” that you saw in previous examples. 

 

LISTING The HTTP POST request to create a new folder in OneDrive for Business

POST /v1.0/me/drive/items/01MDKYG3G3MLQJYQ7CUZG3GQRA7MBBY57D/children HTTP/1.1
Authorization: Bearer eyJ0...
Host: http://graph.microsoft.com
Content-Length: 51
Content-Type: application/json
{
"folder": {},
"name": "Child Folder - 2"
}

 

As you can see, the request is straightforward, and the response will be an HTTP Status Code with a value of 201 (Created). In the body of the response, you will find a JSON object that represents the just-created folder.

 

If you plan to use the newly created folder—for example, to upload some files into it—you can grab the Id property for subsequent requests. Once you have created a new folder and grabbed its Id property, to create a file in that folder you can make an HTTP POST request against the collection of children of the new folder. 

 

LISTING The HTTP POST request to upload a new file into a target folder in OneDrive for Business

POST /v1.0/me/drive/items/01MDKYG3G3MLQJYQ7CUZG3GQRA7MBBY57D/children HTTP/1.1
Authorization: Bearer eyJ0...
Host: http://graph.microsoft.com
Content-Length: 219
Content-Type: application/json
{
"file": {},
"name": "SampleImage.png"
}

 

After you have created the Microsoft.Graph.the driveItem object, you will have to provide the real content of the file. For example, if the file is an image in JPEG format, you will have to upload the binary content of the image. 

 

To upload or update the content of a file, you have to make an HTTP PUT request for the URL of the file, appending the content operation name, setting the proper content type for the request, and putting the file content in the body of the request. 

 

LISTING he HTTP POST request to upload content into a file created in OneDrive for Business

PUT /v1.0/me/drive/items/01MDKYG3GK3HVL5QVCGFELA4Z7NECG2PON/content HTTP/1.1

Authorization: Bearer eyJ0...

Host: http://graph.microsoft.com

Content-Length: 51

Content-Type: image/png

<Here goes the binary content of the image file>

 

Copying a file around the OneDrive for Business repository is another common the requirement that can be accomplished by invoking the microsoft.graph.copy (or copy) method exposed by every instance of type Microsoft.Graph.driveItem, whether it is a file or a folder. 

 

LISTING The HTTP POST request to copy a file from the current folder to another folder in OneDrive for Business

POST /v1.0/me/drive/items/01MDKYG3G3MLQJYQ7CUZG3GQRA7MBBY57D/copy HTTP/1.1
Authorization: Bearer eyJ0...
Host: http://graph.microsoft.com
Content-Length: 60
Content-Type: application/json
{
"parentReference": {
"id": "01MDKYG3G3MLQJYQ7CUZG3GQRA7MBBY57D",
},
"name": "SampleImageCopied.png"
}

Again, the result will be an HTTP Status Code with a value of 202 (Accepted). If you want to update the properties of the just-created or copied file, you can use the HTTP PATCH method, targeting the URL of the file for which you want to update the properties. In Listing, you can see a sample update request that renames a file by patching the name property.

 

LISTING The HTTP PATCH request to update the properties of a file in OneDrive for Business

PATCH /v1.0/me/drive/items/01MDKYG3G3MLQJYQ7CUZG3GQRA7MBBY57D HTTP/1.1
Authorization: Bearer eyJ0...
Host: http://graph.microsoft.com
Content-Length: 45
Content-Type: application/json
IF-MATCH: "{BD6935D3-C45B-40E6-9251-2BCB3EDA7881},2"
{
"name": "SampleImage-Renamed.png"
}

 

Notice the IF-MATCH header in the HTTP request, which is required to update an object of type Microsoft.Graph.Item. You can get the value of the eTag property from the JSON serialization of any item (file or folder).

 

If the eTag value you provide in the header is not equal to the eTag value existing on the service side, it means that someone else already updated the target item. You will get back a concurrency exception with a message like the following excerpt:

{"error": {"code": "notAllowed","message": "ETag does not match current item's value",

"innerError": {"request-id": "4367386f-d3a3-4d93-ac4b-cf4662a028ac","date": "2016-06-

15T14:51:24"}}

}

If you want to force your update, regardless any other concurrent update, you can provide a value of “*” (without quotes) for the IF-MATCH header, or—at your own risk—you can even skip the IF-MATCH header.

 

Aside from any concurrency issue, the result of a successful update will be the JSON serialization of the updated Microsoft.Graph.drive them object. Last, to delete a file or a folder, you can leverage the HTTP DELETE method, targeting the unique Id of the item to delete. The listing shows how to make such a request.

 

LISTING The HTTP DELETE request to delete a file in OneDrive for Business

DELETE /v1.0/me/drive/items/01MDKYG3G3MLQJYQ7CUZG3GQRA7MBBY57D HTTP/1.1
Authorization: Bearer eyJ0...
Host: http://graph.microsoft.com
Content-Length: 0
Content-Type: application/json

 

The response will be an HTTP Status Code with a value of 204 (No Content), which implies a successful deletion of the target file or folder.

 

Searching within a drive

In real-life scenarios, users have a lot of files in their OneDrive for Business, especially considering the huge amount of data that every user is allowed to store there.

 

Thus, browsing the folders and files is not always the best way to find content. Luckily, OneDrive for Business is based on Microsoft SharePoint Online, which provides a powerful search engine that can be used to search OneDrive for Business.

 

Searching for content, whether files or folders, is straightforward. You just need to target an object of type Microsoft.Graph.driveItem, which can be the root folder or any subfolder, and invoke the microsoft.graph.search (or search) function providing a search query text.

 

In Listing, you can see a sample search request that looks for any file or folder containing the word “sample.”

 

LISTING The HTTP GET request to search for files or folders containing the word “sample”

GET /v1.0/me/drive/root/microsoft.graph.search(q='sample') HTTP/1.1
Authorization: Bearer eyJ0...
Host: http://graph.microsoft.com
Content-Length: 0
Content-Type: application/json
The response will look like the excerpt in Listing and will include both files and folders matching the search criteria.
LISTING An excerpt of the JSON array returned by invoking the search operation for the root folder of the OneDrive for Business of the current user
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#driveItem",
"value": [
{
"@odata.type": "#microsoft.graph.driveItem",
"createdBy": {
"user": {
"displayName": "Thesis Scientist"
}
},
"createdDateTime": "2015-07-10T17:13:04Z",
"folder": {
"childCount": 0
},
"id": "01MDKYG3G3MLQJYQ7CUZG3GQRA7MBBY57D",
"lastModifiedBy": {
"user": {
"displayName": "Thesis Scientist"
}
},
"lastModifiedDateTime": "2015-07-10T17:13:04Z",
"name": "Sample Share",
"searchResult": {},
"size": 0,
"webUrl": "https://sharepoint-camp_com/Documents /Sample%20Share"
},
{
"@odata.type": "#microsoft.graph.driveItem",
"createdBy": {
"user": {
"displayName": "Thesis Scientist"
}
},
"createdDateTime": "2015-09-09T04:25:26Z",
"file": {},
"id": "01MDKYG3EIHAILISRHVBDJQVXKTI3LGHVA",
"lastModifiedBy": {
"user": {
"displayName": "Thesis Scientist"
}
},
"lastModifiedDateTime": "2013-07-11T00:23:31Z",
"name": "Office 365 Sample File.pdf",
"searchResult": {},
"size": 426620,
"webUrl": "https://sharepoint-camp_com/Documents /Sample%20Share/Office%20365%20Sample%20File.pdf"
},
...
]
}

Note that the search engine will not only search for files and folders with matching names but also will search the content inside files, as happens with the classic Microsoft SharePoint search engine.

 

Sharing files and folders

Sharing a file or a folder is another useful capability that is available through the Microsoft Graph API. Whenever you want to share an object of type Microsoft.Graph.drive them, you can invoke the microsoft.graph.createLink (or createLink) action using an HTTP POST method.

 

The create Link action accepts two input parameters: type A string parameter that defines whether the item will be shared for view, which means read-only; for edit, which means read and write;

 

or for embed, which creates an embeddable link scope Defines the scope of the action link and can have a value of organization, which means that the target users will have to access the resource with an organizational account; or anonymous, which means that the link will be accessible anonymously. 

 

These parameters have to be provided through a JSON serialized object. In Listing, you can see a sample file sharing request.

 

LISTING The HTTP POST request to share a file for anonymous viewing

>POST
/v1.0/me/drive/items/01MDKYG3AUTHKROIRYDVHIHLBSZQU7ZNUE/microsoft.graph.createLink
HTTP/1.1
Authorization: Bearer eyJ0...
Host: http://graph.microsoft.com
Content-Length: 0
Content-Type: application/json
{
"type": "view",
"scope": "anonymous"
}

The response is illustrated in Listing and represents an instance of an object of type Microsoft.Graph.Permission.

 

LISTING An excerpt of the JSON returned by invoking the microsoft.graph.the createLink operation for a driveItem

{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#permission",
"@odata.type": "#microsoft.graph.permission",
"id": "N0JCQTQ2MzItRTAxQi00RDlBLUFEMkEtNEZCMTZDRkFDODM3",
"roles": [
"read"
],
"link": {
"type": "view",
"webUrl":
"https://piasysdev-my.sharepoint.com/_layouts/15/guestaccess.aspx?
guestaccesstoken=OQ7bQd8
WRvu0OTxu2%2fuKi6KoHB%2bidQgE6tZVGnoC35c%3d&docid=2_0e34e1f4b0e5640388180ae9a6e49f
}
}

The sharing link will be available in the web URL property of the link object.

 

Working with Office 365 Groups

Office 365 Groups are a new feature of Office 365. The Microsoft Graph API provides a way to interact with the Office 365 Groups and to browse all the capabilities of each group.

 

As stated in the section “Consuming users and security groups” earlier in this blog, to access the Office 365 Groups you can browse the group's entity set of the current tenant to get a list of objects of type Microsoft.Graph.Group, where the group types property contains the value Unified. Here, you can see the corresponding URL, which leverages OData filtering capabilities:

 

https://graph.microsoft.com/v1.0/groups?

$filter=groupTypes/any(g:%20g%20eq%20’Unified’)

Notice any operator applied on the collection property named group types and the OData syntax to represent a kind of predicate. In Listing, you can see an excerpt of the result for the query defined above.

 

LISTING An excerpt of the JSON array providing the groups of type Office 365 Group

{
"value": [
{
"id": "c748625f-ece2-4951-bab7-6e89ad8b6f10",
"description": "Sample Group",
"displayName": "Sample Group",
"groupTypes": [
"Unified"
],
"mail": "samplegroup@PiaSysDev.onmicrosoft.com",
"mailEnabled": true,
"mailNickname": "samplegroup",
"onPremisesLastSyncDateTime": null,
"onPremisesSecurityIdentifier": null,
"onPremisesSyncEnabled": null,
"proxyAddresses": [
"SMTP:samplegroup@PiaSysDev.onmicrosoft.com"
],
"securityEnabled": false,
"visibility": "Public"
}]
}

The result of such a URL query will be a JSON object that represents a collection of Office 365 Groups. You can see the main properties of the Office 365 Group instance, including the id, displayName, mail address, visibility, and so on.

 

As with any group, you can access a specific group by appending the id value after the group's collection URL.

 

For example, to retrieve a direct reference to the Sample Group that is illustrated in Listing, you can make an HTTP GET request for the following URL:

https://graph.microsoft.com/v1.0/groups/c748625f-ece2-4951-bab7-6e89ad8b6f10

 

Moreover, every Office 365 Group provides a set of navigation properties to browse the photo for the group, the calendar, the conversations, the files, and the group’s members. For example, if you want to access the photo of the group, here is the sample URL to use:

https://graph.microsoft.com/v1.0/groups/<group-id>/photo/$value

 

To access the calendar of a group, you just need to make an HTTP GET request for a URL like the following:

https://graph.microsoft.com/v1.0/groups/<group-id>/calendar

 

You will get back an object of type Microsoft.Graph.Calendar, which can be used exactly like any other calendar in the Microsoft Graph. You can refer to the section “Consuming mail, contacts, and calendars” earlier in this blog for further details about how to manage calendars, events, and meetings.

 

To access a group’s conversations, there is a straightforward navigation property called conversations, which can be used to get a list of all the conversations or to access a specific conversation by id. 

 

LISTING  An excerpt of the JSON representation of a conversation within an Office 365 Group

{
"id":
"AAQkADdkNjZjMDUwLTA1ZmItNGRiNS04ZWI5LTdjOTQwZTk1MDZiNAAQABzdWzBNd3VKtWsenlfeLc
"topic": "The new group Sample Group is ready",
"hasAttachments": true,
"lastDeliveredDateTime": "2015-12-03T12:01:30Z",
"uniqueSenders": [
"Sample Group"
],
"preview": "Welcome to the group Sample Group."
}

The group’s members can be queried by invoking the member's navigation property, like in the following URL:

https://graph.microsoft.com/v1.0/groups/<group-id>/members

 

You can subscribe to or unsubscribe from email notifications by using the subscribeByMail and the unsubscribeByMail actions, and you can manage the group as a favorite by using the addFavorite and remove favorite methods.

 

Last, you can access the OneDrive for Business storage dedicated to a specific Office 365

Group just by requesting, via HTTP GET, the drive entry point with a URL like the following:

https://graph.microsoft.com/v1.0/groups/<group-id>/drive

The result will be an object of type Microsoft.Graph.drive, which behaves exactly as the users’ OneDrive for Business file storage. Refer to the section “Consuming OneDrive for Business” earlier in this blog for further details.

 

Summary

In this blog, you learned about the Microsoft Graph API: its architecture and the overall goal of having a unified set of API. Moreover, you learned how to consume services related to users and groups in the Office Graph. You explored how to consume Exchange Online– related services to browse email messages, send a new message, and reply to a received message.

 

You also saw how to query and manage calendars and contacts. You learned how to query, update, and manage files and folders in OneDrive for Business. Last, you explored how to browse the new Office 365 Groups and their content.

 

The information provided in this and the following blog enables you to consume the Microsoft Graph API from any device and using any development platform as long as it supports the capability to fire HTTP requests and to serialize/deserialize JSON objects.

Recommend