Introduction to PnP

The Office 365 Developer Patterns & Practices (PnP) initiative was originally formed in 2013 by a group of Microsoft consultants who were working on helping on-premises customers to move their SharePoint deployments to cloud. As part of this customer facing work we came up with initial transformation patterns and collected input on what works and what does not work from enterprise development perspective using add-in model.

Since there was clearly a growing interest for customers to move to cloud, all of these learnings and patterns were initially shared cross Microsoft with a project name as ‘Gapps’. At the time this was not really that official and ‘Gapps’ was great name since we provided guidance on how to address gaps in the add-in mode. It did not refer to “Google-Apps”, which was my manager’s initial question when he heard about this first time.

Since these patterns and code had significant demand also from other customers and partners, we decided to move to CodePlex and program was renamed as Office App Model Samples or Office AMS.  We released this project in the SPC 2014. There was clearly a massive demand in the community for this material and project was the most visited project at CodePlex immediately on the week it was released.

Based on the success and demand, Microsoft Product Marketing wanted to ensure more visibility for the program and on end of July 2014, program was relaunched using the brand “Office 365 Developer Patterns and Practices” or simply as PnP. At the same time, we made also a decision to move to GitHub were also many other Microsoft driven programs and solutions were gradually moving.

As part of the initial efforts we also started creating new PnP Core component, which was then released as it’s own Nuget package as part of our monthly releases. PnP Core component is managed code, which encapsulates common CSOM operations to more simplified interface and is targeted to simplify development and therefore also to increase productivity of developers. New versions of the Core component is released on monthly basis as part of the PnP monthly releases and it has different versions for on-premises and SPO due the different capabilities supported on both sides.

Lot of the PnP samples and guidance concentrates on the SharePoint add-in model and more specifically on showing how to implement typical SharePoint customizations using add-in model techniques. One of the key reason for this is that many of the PnP Core team members are working full time on this area with enterprise customers and we feed PnP guidance from this customer facing work. This is also the reason why many of the PnP samples and solutions demand full permissions to host web, site collection or to tenant, which makes them not suitable to be distributed using SharePoint store. We are however absolutely open for contributions for other areas as well and start now growing program outside of the SharePoint samples.

We have come a long way from the start together with the community members. From day one objective was to provide first internal and then public channel where community can easily share their learnings and patterns, which are also approved and reviewed by Microsoft engineering. By sharing our learnings between others in the community, we can start building on common knowledge cross the community.

Some of initial thinking behind the model working with community to solve the problems together on SharePoint and Office 365 development is coming from years back. Obviously this is not unique model cross the industry. Here’s a slide from my SharePoint MCM delivery decks around site provisioning from SP2010 time frame (this is from 2010 or 2011). It’s great to see that with community we have been able to create something as unique as PnP Provisioning engine for this specific area, not obviously forgetting all the other guidance and code what the PnP is providing.

Note. this slide is referencing more towards cloud transition, but you can also use remote provisioning models on-premises. There’s growing interest on driving consistency cross development models for cloud and on-premises.

Usage and growth during past year

Growth of the PnP guidance usage and interest has been really great during the past year. Obviously the fact that we have released new community contributed content constantly on monthly basis has kept the interest on-going. We are also delightful to see how community members are helping each other in the GitHub and in Yammer. We have tracked different numbers during past year (starting from November 2014) and here’s two charts showing the growth in practice. These are pretty impressive and big thank belongs for the people who have contributed and shared their learnings.

During June 2015 we did quick PnP usage survey for the community to collect feedback on making decisions around following steps in PnP program. We wanted to understand value what the program provides and also collection input on following concentration areas. Here’s quick notes based on the collected information. We get 150 responses on the survey.

• 60% of responses stated that PnP guidance has saved at least 10 days of development time in their project. 10% stated that overall save with PnP is more than 50 days.
• 80% of responses had used PnP in their on-premises or Office 365 deployments
• 80% of responses had custom site provisioning solution built, from which 82% were using PnP provisioning engine
• 40% of the responses indicated that next concentration area should be Office 365 APIs. ALM, additional SP add-in guidance and on-premises guidance were equally important and only 10% indicated that Office Add-Ins would be important

We are also highly grateful on the free comments which were part of the survey. Here’s few quotes on them.

• “One of the greatest things done to devs. Thank you and keep up the good work.”
• “You guys seem to have the experience of what is needed out in the field. A lot of the stuff you guys built should make it in to the product right away.”
• “Amazing effort by the team from both MS and community members (love the Core and PowerShell) !”
• “Office PnP is by far the most collaborative and open forum I have ever seen in my 15 years working with Microsoft. It’s helping us drive O365 projects and advise our customers on technical direction. Please keep up the good work!”
• “This is the most valuable resource for developers Microsoft has ever produced.”

Community involvement and contributions

PnP Core team is the group of people who have sufficient permissions to approve pull requests in the GitHub repository and who are active in the Yammer group on helping others around the questions. Core team also is the main group of people making joint decision around the direction and technical approaches in the Core component or in PnP in general.

We started with small number of Microsoft employees, but then grew the team with active community members. Right now Core team consists from roughly 10 Microsoft employees and 3 community members who are all MCMs and MVPs. We are further looking into extending the community members in future from active people who show the interest on assisting with the PnP program. All core team members are actively working with customers’ day to day basis, which is good and bad for PnP program. It means that each of them have real life experiences on the shared material, but it also means that lot of the PnP work is done outside of normal business hours. You can see full list of Core team members from our landing page at http://aka.ms/OfficeDevPnP.

Big part of the PnP guidance and code is coming also directly from the community and we have been extremely grateful on the interest on sharing learnings between other community members. PnP has have already 78 individual contributors. Your contributions and feedback is vital for the program and want to really say big thanks on this.

If you are interested on contributing some of your work for the benefit of others and to gain visibility for your content at dev.office.com, including our monthly communications, please check more information for PnP GitHub repository wiki pages.

New repository structure at GitHub

Starting with September 2015 release, we have now split the PnP repository to smaller pieces. This decision was done for ensuring easier consumption on relevant samples around the specific topic and to differentiate some of the more isolated functionalities to own repository for easier maintenance. Here’s full list of new PnP repositories and their purpose.

• PnP – Main repository in future as well, but will be smaller
• PnP-Guidance – Guidance, presentations and articles which are partly sync’d to MSDN
• PnP-Sites-Core – Office Dev PnP Core component released also as Nuget package
• PnP-PowerShell – Office Dev PnP PowerShell Cmdlets
• PnP-Office-Addins – Office Add-in samples and models
• PnP-Office365-API – Office 365 and Azure AD related add-ins
• PnP-Provisioning-Schema – Repository for the PnP provisioning engine schema development. Schema has its own lifecycle and slightly different team which works on that
• PnP-Transformation – Material specifically for the transformation process. Currently draft version of the InfoPath transformation
• PnP-ALM – Upcoming repository for application life cycle guidance for add-in approaches including scripts and other assets for cloud and on-premises
• PnP-Partner-Pack – Packaged guidance with detailed instructions on setting things up in Office 365 and in Azure. This initiative was started during August and target date for final delivery is on mid-Oct.

We will still continue doing monthly releases with master merge which means that all submissions should be targeted to Dev branch where suitable. Some of the repositories work slightly differently, like the Guidance repository, where we only have one branch with always the latest information and material.

Looking forward

Now that the structure has been split and re-structuring is completed, we will continue working on multiple areas in the guidance, including new samples and articles. We will start spending more time on Office 365 APIs and also in the Office Add-Ins to ensure that we have coverage on these sides as well. We would absolutely welcome contributions on these topics as well and have already received some great community contributions for them.
Other areas where we will spend time in near term are following:

• ALM guidance for the add-in model and Office 365 API side
• On-premises add-in model considerations
• More packaged and easily deployable provisioning and governance solution with detailed setup guidance – see PnP Partner Pack repository for details.

Obviously there’s multiple other things in the radar and we’ll start working on these gradually. This is long lasting journey and we are only in the start.

In short term our next monthly release will be on 4th of September and next monthly community call on Tuesday 8th of September. Typical monthly community call will consist from program update and demos on new samples part of the release. You can download calendar invite (ics) to monthly community call from dev.office.com.

PnP Resources

Here’s a quick list of most important PnP resources and locations.

• PnP under dev.office.com – http://aka.ms/OfficeDevPnP – One location for all the resources and news around PnP
• PnP GitHub – http://aka.ms/OfficeDevPnPGitHub – main repository
• PnP MSDN pages – http://aka.ms/OfficeDevPnPMSDN
• PnP Yammer group – http://aka.ms/OfficeDevPnPYammer
• PnP Videos at Channel 9 – http://aka.ms/OfficeDevPnPVideos
• PnP training package (videos in Channel 9) – http://aka.ms/OfficeDevPnPTraining 
• PnP Guidance Repository – http://aka.ms/OfficeDevPnPGuidance

FAQ

PnP repository is so large, why not individual repositories for each sample?
We are trying to mitigate the growth now with the split of the repository to numerous ones, like explained earlier in this post. We are not considering on splitting each sample to own repository, since we wanted to rather have slightly bigger repository targeted for specific area which developers can easily pull down using Git tooling. This way you do not need to fork and manage multiple repositories for finding all the relevant samples for example for SharePoint hosted add-ins.

Many of the samples require full permissions and cannot be released as store apps
This is true and it’s something what we are looking into. PnP started initially from perspective where we concentrate on enterprise development scenarios with the add-in model and in these cases full permissions are acceptable. Also in many cases, you will need to have full permissions to gain access on more advance scenarios, like when you provision site collections or you want to use app/add-in only permissions.

Why are majority of the samples provider hosted apps?
There are many samples which are showing different techniques on applying configurations or provisioning different assets for SharePoint sites. We didn’t want to make these samples too difficult and we rather consider some of them as stepping stones for more complex scenarios. This is why some of the samples are using pretty simple UI to apply needed configurations to the sites.

You can absolutely do some of these capabilities also using SharePoint hosted add-ins, but there are also significant limitations for SP hosted add-ins. You cannot for example perform any tenant level operations or use add-in/app only permissions.
With provider hosted model you can achieve much more interesting scenarios when you combine your add-in with Azure tooling. This will give you really great capabilities in the Office 365.

Is this official guidance from Microsoft engineering?
Yes. All code what is shared from the PnP is supported and approved by Office 365 and SP engineering. We will perform updates in the samples as needed based on possible changes on supportability side. Some of the samples do however show slightly controversial approaches (like JavaScript embedding) where it’s important to realize the possible impact on the future if similar approach is taken in your deployments. These things are never black and white, which means that some shown patterns could be critical for some customers, but cause challenges for others.

I have pretty similar sample as already in the PnP, can I still submit my code
If there’s already similar sample in the PnP, we would rather appreciate updates on the exist one. This way we are evolving the shared sample rather than introducing yet again additional sample which is doing pretty similar stuff as existing samples. As an example, we are pretty nicely covered on the Provisioning topic, so would rather see updates on existing samples than yet again another demo on self-service site collection creation.

Is PnP code and samples supported by Microsoft or is there a SLA for this content?
PnP is community driven open source project and even though all shared materials is blessed by engineering, it does not mean that Microsoft will directly provide support on the samples. Microsoft is closely involved in the program, but in the end this is typical open source program where there’s no direct support or SLAs on getting responses. PnP Yammer group is the most active developer Yammer group at Office 365 Network and does work great as a support channel, but in the end there’s no SLAs on this support.  

Can I use PnP code and samples commercially in my own projects?
Yes. These are samples and patterns provided for you without any restrictions. If you want ot use any of the samples or create training package based on the provided materials, feel free to do that.

I’d like to join the effort and contribute as well
You can find guidance on getting started with contributions from the PnP GitHub wiki. We are looking into extending the program with new community members and will obviously target those people who have been first active in contributions and in PnP Yammer group. You can also follow up easily what’s happening in the program by joining to our monthly community call on 2nd Tuesday on each month.

I do not have time to contribute, but would like to consume PnP as much as possible
This is absolutely fine and we do understand that you might not have time to contribute back. Obviously we would hope that you’d still give us input and feedback. Also reporting any bugs as issues to our repositories would be highly appreciated.

How do I follow all the latest changes in the PnP side?
Use our landing page at the http://aka.ms/OfficeDevPnP for getting access on latest updates in the PnP program. You should also join to our monthly community call on 2nd Tuesday on each month for getting information on latest updates.

How can I find relevant samples and guidance in PnP for me?
Use our sample and guidance search tool at http://dev.office.com/patterns-and-practices-resources. This page provides filter categories which can be used to easily find what’s relevant for you.

I have few technical questions or questions around PnP – how to get answers to these.
Please use the PnP Yammer group at http://aka.ms/OfficeDevPnPYammer for starting discussion with the PnP Core team. This absolutely more preferred option than sending direct emails.

OMG this was long post in Finglish
I know and do apology that. So much to cover and didn’t want to miss anything important.

“Sharing is caring”

Vesa Juvonen, Senior Program Manager, Office 365, Microsoft