Setting the new page header in a modern SharePoint page using C# or PowerShell

This week a question came up about how to set the Header in a modern page using code. Normally in these cases you could go to the PnP Provisioning library. Using the PnP Schema you can provision a page and specify some properties of the header that shows up when deployed. You can specify:

  • Title
  • ServerRelativeImageUrl
  • Translate X
  • Translate Y

Unfortunately, there has been some updates to the modern pages which allows for a new layout for headers and the current PnP library doesn’t have support for them yet. Notice the image below, we have a few new layouts and a new field called “Topic Header”.

So what I am going to do, is explain how we can achieve the new layout with the Topic Header field. I looked into the existing PnP codebase to see how the current header implementation was done, and it gave me a lot of insight into how to solve this problem.

How to achieve this

In order to create a new page and specify a new page header we actually have to create a new page in the Site Pages list and then update some of the hidden properties of the site page. Specifically we need to update the following fields:

  • LayoutWebpartsContent
  • PageLayoutType
  • CanvasContent1
  • _TopicHeader
  • ClientSideApplicationId

Where do the properties for a header live?

The thing about modern web parts is that a lot of them store the properties that are being rendered within the web part itself. Because of this, I actually have to set the HTML and JSON object of the web part on the site page’s LayoutsWebpartsContent field. It’s quite complex, so in order to be as safe as possible and get the correct HTML, I decided the best approach  would be to create a template page (pictured above) and use that as a way to get the proper data for my newly provisioned pages.

C# Implementation

This C# example is actually going to use the PnP Core library (not required). We’ll get a reference to my template page and grab the LayoutWebpartsContent property. This will return all of the HTML required for the header. Then, we’ll create a new article page, update a few required properties and then update the LayoutWebpartsContent property from the template values.

Link to gist

  using (var ctx = new OfficeDevPnP.Core.AuthenticationManager().GetAppOnlyAuthenticatedContext(newSiteUrl, clientId, clientSecret))
            {
                var pages = ctx.Web.Lists.GetByTitle("Site Pages");
                ctx.Load(pages);
                
                //get template page
                var templatePage = pages.RootFolder.GetFile("Project-Home.aspx").ListItemAllFields;
                ctx.Load(templatePage);
                ctx.ExecuteQuery();
                
                //this is our template page content
                var _customPageHeader = templatePage[ClientSidePage.PageLayoutContentField]; //LayoutWebpartsContent
                var _canvasContent = templatePage["CanvasContent1"];

                //create new page in site page library
                var item = pages.RootFolder.Files.AddTemplateFile("/sites/test/sitepages/BeauTest.aspx", TemplateFileType.ClientSidePage).ListItemAllFields;
              
               //update page header from template information
                item[ClientSidePage.PageLayoutContentField] = _customPageHeader;        
                item[ClientSidePage.ClientSideApplicationId] = ClientSidePage.SitePagesFeatureId; //ClientSideApplicationId - b6917cb1-93a0-4b97-a84d-7cf49975d4ec
                item["CanvasContent1"] = _canvasContent; //"
"; item["_TopicHeader"] = "Service Line"; item.Update(); ctx.Load(item); ctx.ExecuteQuery(); }

 

PowerShell Implementation

The following example is the equivalent of the C# code using CSOM, and instead of using a template file, I’ve hard coded the HTML into the code itself. This way, if you wanted to add some tokens in your HTML to dynamically replace the “Topic Header”, or change the layout you could do so directly in that HTML string.

Link to Gist

[System.Reflection.Assembly]::LoadWithPartialName("Microsoft.SharePoint.Client")
[System.Reflection.Assembly]::LoadWithPartialName("Microsoft.SharePoint.Client.Runtime")
 

$admin = 'youraccount@tenant.OnMicrosoft.Com'
$password = Read-Host 'Enter Password' -AsSecureString

$context = New-Object Microsoft.SharePoint.Client.ClientContext("https://tenant.sharepoint.com/sites/testpnp");
$credentials = New-Object Microsoft.SharePoint.Client.SharePointOnlineCredentials($admin , $password)
$context.Credentials = $credentials


$pagesLibrary = $context.Web.Lists.GetByTitle('Site Pages');
$context.Load($pagesLibrary);

$newPageitem = $pagesLibrary.RootFolder.Files.AddTemplateFile("/sites/testpnp/sitepages/TestPage.aspx", "ClientSidePage").ListItemAllFields;

$newPageitem["Title"] = "Project Home";
$newPageitem["ClientSideApplicationId"] = "b6917cb1-93a0-4b97-a84d-7cf49975d4ec";
$newPageitem["PageLayoutType"] = "Article";
$newPageitem["LayoutWebpartsContent"] = '
'; $newPageitem["CanvasContent1"] = "
"; $newPageitem["_TopicHeader"] = "Service Line"; $newPageitem.Update(); $context.Load($newPageitem); $context.ExecuteQuery();

 

A special thanks

I’d like to thank Garry Trinder for mentioning the current limitation and providing me with the idea on figuring out how to solve this issue and subsequently creating this post!

Thanks to the PnP Team for setting up a lot of the framework and for making this post possible. Sharing is caring.

How to find which site designs have been applied on a SharePoint site.

In SharePoint Online, a new provisioning process is being used which allows an administrator to define a set of designs that can be applied to a newly created site. These site designs consist of the ability add column, lists, specify themes, apply SPFx solutions and more.

It’s important to note that multiple site designs can be applied to a site in SharePoint online.

How site designs can be applied to a site collection

  • During creation of a new site using the SharePoint UI
  • During the association to a hub site
  • Invoking on an existing site using Invoke-SPOSiteDesign and Add-SPOSiteDesignTask

Because site designs can be applied in multiple ways and more than one site design can be applied to a site, an admin may want to have a way to see which site designs have been invoked onto a site.

Introducing Get-SPOSiteDesignRun

Get-SPoSiteDesignRun is a new command available to the SharePoint Online Management Shell that will show which site designs have been applied to a specific site collection.

$siteDesignsRan = Get-SPOSiteDesignRun -WebUrl "https://yoursite.sharepoint.com/sites/testsite"

Id                : e4ff3264-c7b1-4121-b179-445382216703
SiteDesignId      : d082fc0e-9a49-4675-88ac-d49e0931670e
WebId             : 42a2b14c-ce2a-485e-8854-92d3b334704f
SiteId            : f848c5a3-9c6b-40f6-becd-8c5661f0e558
SiteDesignVersion : 1
SiteDesignTitle   : Long Site Design

Id                : 8efb3528-3ff1-4dcf-98a3-7f020492a79f
SiteDesignId      : d082fc0e-9a49-4675-88ac-d49e0931670e
WebId             : 42a2b14c-ce2a-485e-8854-92d3b334704f
SiteId            : f848c5a3-9c6b-40f6-becd-8c5661f0e558
SiteDesignVersion : 1
SiteDesignTitle   : Long Site Design

Id                : 00000000-0000-0000-0000-000000000000
SiteDesignId      : 7da58b45-b11d-4e3c-940b-a96c925d02be
WebId             : 42a2b14c-ce2a-485e-8854-92d3b334704f
SiteId            : f848c5a3-9c6b-40f6-becd-8c5661f0e558
SiteDesignVersion : 1
SiteDesignTitle   : MMD Test

Notice the first two site designs that were run, are actually the same. This is because not only does this command show all site designs applied, it also shows the history of invocations against this site collection. Using Invoke-SPOSiteDesign or Add-SPOSiteDesignTask. More information on Add-SPOSiteDesignTask can be found in my previous post.

Needing more information

Get-SPOSiteDesignRun is a valuable command, but as an administrator you may not know what each site design has implemented and the history of actions taken in the site collection. To do this, you can use the new Get-SPOSiteDesignRunStatus command and it will return the result of each action from every site script in your site design.

In the command above, I got a list of site designs that have been invoked onto a site collection and stored them in an object called $siteDesignsRan. I can use the Get-SPOSiteDesignRunStatus command to find more information about each site design invocation.

Get-SPOSiteDesignRunStatus -Run $siteDesignsRan[1]

OrdinalIndex    : 0
SiteScriptID    : 0aa8ce3a-0a7f-4963-bd0f-07ce28a6a5dd
SiteScriptTitle : LongSiteScript
SiteScriptIndex : 0
ActionIndex     : 0
ActionTitle     : Create site column MyTestMMD2TaxHTField through XML
ActionKey       : 00000000-0000-0000-0000-000000000000
OutcomeCode     : Success
OutcomeText     : 

OrdinalIndex    : 1
SiteScriptID    : 0aa8ce3a-0a7f-4963-bd0f-07ce28a6a5dd
SiteScriptTitle : LongSiteScript
SiteScriptIndex : 0
ActionIndex     : 1
ActionTitle     : Create site column MyTestMMD2 through XML
ActionKey       : 00000000-0000-0000-0000-000000000000
OutcomeCode     : Success
OutcomeText     : 

OrdinalIndex    : 2
SiteScriptID    : 0aa8ce3a-0a7f-4963-bd0f-07ce28a6a5dd
SiteScriptTitle : LongSiteScript
SiteScriptIndex : 0
ActionIndex     : 2
ActionTitle     : Create content type Test CT
ActionKey       : 00000000-0000-0000-0000-000000000000
OutcomeCode     : NoOp
OutcomeText     : 

OrdinalIndex    : 3
SiteScriptID    : 0aa8ce3a-0a7f-4963-bd0f-07ce28a6a5dd
SiteScriptTitle : LongSiteScript
SiteScriptIndex : 0
ActionIndex     : 2
ActionTitle     : Add site column MyTestMMD2 to content type
ActionKey       : 00000000-0000-0000-0000-000000000000
OutcomeCode     : NoOp
OutcomeText     : 

OrdinalIndex    : 4
SiteScriptID    : 0aa8ce3a-0a7f-4963-bd0f-07ce28a6a5dd
SiteScriptTitle : LongSiteScript
SiteScriptIndex : 0
ActionIndex     : 2
ActionTitle     : Add site column MyTestMMD2TaxHTField to content type
ActionKey       : 00000000-0000-0000-0000-000000000000
OutcomeCode     : NoOp
OutcomeText     : 

OrdinalIndex    : 5
SiteScriptID    : 0aa8ce3a-0a7f-4963-bd0f-07ce28a6a5dd
SiteScriptTitle : LongSiteScript
SiteScriptIndex : 0
ActionIndex     : 3
ActionTitle     : Create or update list Custom List
ActionKey       : 00000000-0000-0000-0000-000000000000
OutcomeCode     : NoOp
OutcomeText     : List with name Custom List already exists.

OrdinalIndex    : 6
SiteScriptID    : 0aa8ce3a-0a7f-4963-bd0f-07ce28a6a5dd
SiteScriptTitle : LongSiteScript
SiteScriptIndex : 0
ActionIndex     : 3
ActionTitle     : Add content type Test CT
ActionKey       : 00000000-0000-0000-0000-000000000000
OutcomeCode     : NoOp
OutcomeText     :

This is a great command that should be in every admin’s toolbox to help manage and govern SharePoint sites. It gives us a very clear history of what actions have been taken on a given site collection and the results of those actions.

If you ever have a question as to which site designs have been applied to your site, look no further than Get-SPOSiteDesignRun and Get-SPOSiteDesignRunStatus.

Overcome the 30 action site script limitation in SharePoint Online

This blog post pertains to invoking site designs using PowerShell and not through the SharePoint UI. Increasing the 30 action limit through the UI/UX will be supported soon!

During Ignite in Orlando this year, I had the pleasure to see Sean Squires present on the the latest and greatest features for site provisioning in SharePoint Online. He spoke about some of the future updates coming that will help get over some of the limitations of site designs and site scripts.

What 30 action limit?

When site designs and site scripts were first released, there was a limit of 30 actions that could be used in a site script. These actions include:

  • Creating a content type
  • Creating a list
  • Adding a content type to a list
  • creating list columns
  • setting regional settings
  • deploying SPFx solutions
  • and more…

That means if you started using site scripts when they were first released and you needed to deploy a large amount of customization, you’d have to do this with PowerShell and Azure Functions using the “triggerFlow” action.

Introducing Add-SPOSiteDesignTask

During Ignite, Sean announced that new PowerShell commandlets would be available to increase this limitation from 30 to an extremely high number (100k characters apparently). The release of this has seemingly gone under the radar, but is now available for use!

Add-SPOSiteDesignTask is meant to replace the existing Invoke-SPOSiteDesign. The command is used to apply an already publishing site design to any target site collection. This means there is still a limit of 30 actions when creating sites from the SharePoint UI.

However, unlike Invoke-SPOSiteDesign, the command doesn’t run the site design immediately, instead the site design invocation is put into a schedule to run.

Testing it out

I’ve created a basic site design and site script that run 30+ actions onto a SharePoint site collection. The site script will create 33 site columns, a custom list and apply the columns to the list.

$script = @'
  {
                  "$schema": "schema.json",
                   "actions": [
                            {
                                "verb": "createSiteColumn",
                                "fieldType": "Text",
                                "internalName": "testColumn1",
                                "displayName": "Test Column1",
                                "isRequired": false
                               },
                                {
                                "verb": "createSiteColumn",
                                "fieldType": "Text",
                                "internalName": "testColumn2",
                                "displayName": "Test Column2",
                                "isRequired": false
                               },
                                {
                                "verb": "createSiteColumn",
                                "fieldType": "Text",
                                "internalName": "testColumn3",
                                "displayName": "Test Column3",
                                "isRequired": false
                               },
                                {
                                "verb": "createSiteColumn",
                                "fieldType": "Text",
                                "internalName": "testColumn4",
                                "displayName": "Test Column4",
                                "isRequired": false
                               },
                                {
                                "verb": "createSiteColumn",
                                "fieldType": "Text",
                                "internalName": "testColumn5",
                                "displayName": "Test Column5",
                                "isRequired": false
                               },
                                {
                                "verb": "createSiteColumn",
                                "fieldType": "Text",
                                "internalName": "testColumn6",
                                "displayName": "Test Column6",
                                "isRequired": false
                               },
                                {
                                "verb": "createSiteColumn",
                                "fieldType": "Text",
                                "internalName": "testColumn7",
                                "displayName": "Test Column7",
                                "isRequired": false
                               },
                                {
                                "verb": "createSiteColumn",
                                "fieldType": "Text",
                                "internalName": "testColumn8",
                                "displayName": "Test Column8",
                                "isRequired": false
                               },
                                {
                                "verb": "createSiteColumn",
                                "fieldType": "Text",
                                "internalName": "testColumn9",
                                "displayName": "Test Column9",
                                "isRequired": false
                               },
                                {
                                "verb": "createSiteColumn",
                                "fieldType": "Text",
                                "internalName": "testColumn10",
                                "displayName": "Test Column10",
                                "isRequired": false
                               },
                                {
                                "verb": "createSiteColumn",
                                "fieldType": "Text",
                                "internalName": "testColumn11",
                                "displayName": "Test Column11",
                                "isRequired": false
                               },
                                {
                                "verb": "createSiteColumn",
                                "fieldType": "Text",
                                "internalName": "testColumn12",
                                "displayName": "Test Column12",
                                "isRequired": false
                               },
                                {
                                "verb": "createSiteColumn",
                                "fieldType": "Text",
                                "internalName": "testColumn13",
                                "displayName": "Test Column13",
                                "isRequired": false
                               },
                                {
                                "verb": "createSiteColumn",
                                "fieldType": "Text",
                                "internalName": "testColumn14",
                                "displayName": "Test Column14",
                                "isRequired": false
                               },
                                {
                                "verb": "createSiteColumn",
                                "fieldType": "Text",
                                "internalName": "testColumn15",
                                "displayName": "Test Column15",
                                "isRequired": false
                               },
                                {
                                "verb": "createSiteColumn",
                                "fieldType": "Text",
                                "internalName": "testColumn16",
                                "displayName": "Test Column16",
                                "isRequired": false
                               },
                                {
                                "verb": "createSiteColumn",
                                "fieldType": "Text",
                                "internalName": "testColumn17",
                                "displayName": "Test Column17",
                                "isRequired": false
                               },
                                {
                                "verb": "createSiteColumn",
                                "fieldType": "Text",
                                "internalName": "testColumn18",
                                "displayName": "Test Column18",
                                "isRequired": false
                               },
                                {
                                "verb": "createSiteColumn",
                                "fieldType": "Text",
                                "internalName": "testColumn19",
                                "displayName": "Test Column19",
                                "isRequired": false
                               },
                                {
                                "verb": "createSiteColumn",
                                "fieldType": "Text",
                                "internalName": "testColumn20",
                                "displayName": "Test Column20",
                                "isRequired": false
                               },
                                {
                                "verb": "createSiteColumn",
                                "fieldType": "Text",
                                "internalName": "testColumn21",
                                "displayName": "Test Column21",
                                "isRequired": false
                               },
                                {
                                "verb": "createSiteColumn",
                                "fieldType": "Text",
                                "internalName": "testColumn22",
                                "displayName": "Test Column22",
                                "isRequired": false
                               },
                                {
                                "verb": "createSiteColumn",
                                "fieldType": "Text",
                                "internalName": "testColumn23",
                                "displayName": "Test Column23",
                                "isRequired": false
                               },
                                {
                                "verb": "createSiteColumn",
                                "fieldType": "Text",
                                "internalName": "testColumn24",
                                "displayName": "Test Column24",
                                "isRequired": false
                               }, {
                                "verb": "createSiteColumn",
                                "fieldType": "Text",
                                "internalName": "testColumn25",
                                "displayName": "Test Column25",
                                "isRequired": false
                               },
                                {
                                "verb": "createSiteColumn",
                                "fieldType": "Text",
                                "internalName": "testColumn26",
                                "displayName": "Test Column26",
                                "isRequired": false
                               },
                                {
                                "verb": "createSiteColumn",
                                "fieldType": "Text",
                                "internalName": "testColumn27",
                                "displayName": "Test Column27",
                                "isRequired": false
                               },
                                {
                                "verb": "createSiteColumn",
                                "fieldType": "Text",
                                "internalName": "testColumn28",
                                "displayName": "Test Column28",
                                "isRequired": false
                               }, {
                                "verb": "createSiteColumn",
                                "fieldType": "Text",
                                "internalName": "testColumn29",
                                "displayName": "Test Column29",
                                "isRequired": false
                               },
                                {
                                "verb": "createSiteColumn",
                                "fieldType": "Text",
                                "internalName": "testColumn30",
                                "displayName": "Test Column30",
                                "isRequired": false
                               },
                                {
                                "verb": "createSiteColumn",
                                "fieldType": "Text",
                                "internalName": "testColumn31",
                                "displayName": "Test Column31",
                                "isRequired": false
                               },
                                {
                                "verb": "createSiteColumn",
                                "fieldType": "Text",
                                "internalName": "testColumn32",
                                "displayName": "Test Column32",
                                "isRequired": false
                               },
                                {
                                "verb": "createSiteColumn",
                                "fieldType": "Text",
                                "internalName": "testColumn33",
                                "displayName": "Test Column33",
                                "isRequired": false
                               },
                        {
                           "verb": "createContentType",
                           "name": "Test CT",
                           "description": "custom content type",
                           "parentName": "Item",
                           "hidden": false,
                           "subactions": [                         
                               {
                               "verb": "addSiteColumn",
                               "internalName":"testColumn1"
                               },
                               {
                               "verb": "addSiteColumn",
                               "internalName":"testColumn2"
                               },
                               {
                               "verb": "addSiteColumn",
                               "internalName":"testColumn3"
                               },
                               {
                               "verb": "addSiteColumn",
                               "internalName":"testColumn4"
                               },
                               {
                               "verb": "addSiteColumn",
                               "internalName":"testColumn5"
                               },
                               {
                               "verb": "addSiteColumn",
                               "internalName":"testColumn6"
                               },
                               {
                               "verb": "addSiteColumn",
                               "internalName":"testColumn7"
                               },{
                               "verb": "addSiteColumn",
                               "internalName":"testColumn8"
                               },
                               {
                               "verb": "addSiteColumn",
                               "internalName":"testColumn9"
                               },{
                               "verb": "addSiteColumn",
                               "internalName":"testColumn10"
                               },
                               {
                               "verb": "addSiteColumn",
                               "internalName":"testColumn11"
                               },{
                               "verb": "addSiteColumn",
                               "internalName":"testColumn12"
                               },
                               {
                               "verb": "addSiteColumn",
                               "internalName":"testColumn13"
                               },{
                               "verb": "addSiteColumn",
                               "internalName":"testColumn14"
                               },{
                               "verb": "addSiteColumn",
                               "internalName":"testColumn15"
                               },
                               {
                               "verb": "addSiteColumn",
                               "internalName":"testColumn16"
                               },{
                               "verb": "addSiteColumn",
                               "internalName":"testColumn17"
                               },
                               {
                               "verb": "addSiteColumn",
                               "internalName":"testColumn18"
                               },
                               {
                               "verb": "addSiteColumn",
                               "internalName":"testColumn19"
                               },
                               {
                               "verb": "addSiteColumn",
                               "internalName":"testColumn20"
                               },
                               {
                               "verb": "addSiteColumn",
                               "internalName":"testColumn21"
                               },
                               {
                               "verb": "addSiteColumn",
                               "internalName":"testColumn22"
                               },
                               {
                               "verb": "addSiteColumn",
                               "internalName":"testColumn23"
                               },
                               {
                               "verb": "addSiteColumn",
                               "internalName":"testColumn24"
                               },
                               {
                               "verb": "addSiteColumn",
                               "internalName":"testColum25"
                               },
                               {
                               "verb": "addSiteColumn",
                               "internalName":"testColumn26"
                               },{
                               "verb": "addSiteColumn",
                               "internalName":"testColumn27"
                               },
                              {
                               "verb": "addSiteColumn",
                               "internalName":"testColumn28"
                               },
                               {
                               "verb": "addSiteColumn",
                               "internalName":"testColumn29"
                               },
                               {
                               "verb": "addSiteColumn",
                               "internalName":"testColumn30"
                               },
                               {
                               "verb": "addSiteColumn",
                               "internalName":"testColumn31"
                               },
                               {
                               "verb": "addSiteColumn",
                               "internalName":"testColumn32"
                               },
                               {
                               "verb": "addSiteColumn",
                               "internalName":"testColumn33"
                               },
                               
                            ]
                       },
                       {
                        "verb": "createSPList",
                        "listName": "Custom List",
                        "templateType": 100,
                        "subactions": [
                           {
                            "verb": "addContentType",
                            "name": "Test CT"
                           }                      
                         ]
                        }
            
              
                   ],
                   "bindata": { },
               "version": 1
              }
              
              }

}
'@

I have added this site script to SharePoint using the Add-SPOSiteScript command and subsequently added the site script to a new site design using Add-SPOSiteDesign.

Add-SPOSiteScript -Title "LongSiteScript" -Description "Long Site Script" -Content $script
-returned id = 0aa8ce3a-0a7f-4963-bd0f-07ce28a6a5dd

Add-SPOSiteDesign -Title "Long Action Site Design" -WebTemplate "0" -SiteScripts "0aa8ce3a-0a7f-4963-bd0f-07ce28a6a5dd" -Description "Long Action Test"
-return id = d082fc0e-9a49-4675-88ac-d49e0931670e

Using Add-SPOSiteDesignTask

Now that I have created a long site script and the associated site design, it’s time to run the site design on an existing site. I will invoke the site design using Add-SPOSiteDesignTask and passing in the WebUrl and the SiteDesignId from my new site design.

Add-SPOSiteDesignTask -SiteDesignId d082fc0e-9a49-4675-88ac-d49e0931670e -WebUrl https://yourtenantsite.sharepoint.com/sites/testlongscript

After invoking the command, PowerShell is going to output some information for you. It will provide the ID of the new task as well as the associated site design that was provisioned.

Add-SPOSiteDesignTask -SiteDesignId d082fc0e-9a49-4675-88ac-d49e0931670e -WebUrl https://yourtenantsite.sharepoint.com/sites/testlongscript

Id : e4ff3264-c7b1-4121-b179-445382216703
SiteDesignId : d082fc0e-9a49-4675-88ac-d49e0931670e
WebId : 42a2b14c-ce2a-485e-8854-92d3b334704f
SiteId : f848c5a3-9c6b-40f6-becd-8c5661f0e558
LogonName : i:0#.f|membership|beau@cameronsoft.onmicrosoft.com

Checking the results

After waiting a minute or so, I was able to see the reflected changes in my environment.

ContentType

To learn more about Add-SPOSiteDesignTask, the documentation can be found here.

Deploy Managed Metadata fields using site designs and site scripts

(Notice: This post may show unsupported methods for provisioning fields)

You may be in a scenario where you want to create Managed Metadata columns using modern provisioning. This post is going to outline a method that can be used to provision Managed Metadata columns using site designs. Site designs are a new model for provisioning assets (fields,content types, lists, etc…) in modern SharePoint. Information on site designs and site scripts can be found here.

Multiple ways to create columns

Using a site script,  you can create both list and site columns using two different actions — “addSPField” and “addSiteColumn”. The first will deploy a list column and the second action will deploy a site column. However, these two actions only support basic field types in SharePoint. These field types include:

  • Text
  • Note
  • Number
  • Boolean
  • User
  • DateTime

Complex columns such as people fields and managed metadata fields need to be created using the Field Element definition. Using site designs and site scripts, we can provision complex fields using the Field definition with the addSPFieldXml and createSiteColumnXML actions.

There are many ways you can get the Field definition after they have been created in the SharePoint UI. Here are a couple options you could use to export out the schema XML for a list and get the field definitions.

https://yoursite/_vti_bin/owssvr.dll?Cmd=ExportList&List={YOUR_LIST_GUID}

You could also use PnP PowerShell to export out the schema

 $list = Get-PnPList -Identity "your list" -Includes SchemaXml
 $schema = $list.SchemaXml

Which complex fields are supported?

If look through the site script documentation you may notice, it doesn’t actually define which field types are supposed through XML. In regards to a complex field such as a Managed Metadata field, we took to twitter to see if Microsoft had any input. Sean Squires mentioned that currently they do not support Managed Metadata Fields, at least in an elegant way (which to me means, if it works great! if it doesn’t…it’s not officially supported).

How it can be achieved

Managed Metadata Fields are complex fields that actually require two fields to be deployed in order to function properly. One field is a TaxonomyFieldType and another is a Note field. This means we actually have to deploy two fields during the provisioning process.

When you export out a list schema and find your Managed Metadata field, you’ll notice it references the Note field using the ID of the Note field in the TextField node. You may also notice there are tokens for properties such as WebId, SiteId, ListId in your Field definition. In order for the deployment of the field to work we need to remove these token properties.

Secondly, we’ll need to update the <Property> nodes inside the <Customziation> node for the following properties.

  • SspId
  • TermSetId
  • AnchorId

By default, these properties may be using braces to identify the GUID for the Term store, Term set and Anchor. We need to remove the braces and leave the rest of the GUID string.

Here is an example of a cleaned up XML for a Managed Metadata field. Notice how I have removed the {braces} from around the GUIDs for SspdId, TermSetId and AnchorId (in bold).

<Field Type="TaxonomyFieldType" Name="MyTestMMD" SourceID="http://schemas.microsoft.com/sharepoint/v3" StaticName="MyTestMMD" DisplayName="My Test Tax" Group="Test group" ShowField="Term1033" Required="FALSE" EnforceUniqueValues="FALSE" Mult="FALSE"> <Default /> <Customization> <ArrayOfProperty> <Property> <Name>SspId</Name> <Value xmlns:p4="http://www.w3.org/2001/XMLSchema-instance" xmlns:q1="http://www.w3.org/2001/XMLSchema" p4:type="q1:string">1ba8a7c0-a373-4bb7-8ee0-2d130933743a</Value> </Property> <Property> <Name>GroupId</Name> <Value xmlns:p4="http://www.w3.org/2001/XMLSchema-instance" xmlns:q2="http://www.w3.org/2001/XMLSchema" p4:type="q2:string">0e8f395e-ff58-4d45-9ff7-e331ab728beb</Value> </Property> <Property> <Name>TermSetId</Name> <Value xmlns:p4="http://www.w3.org/2001/XMLSchema-instance" xmlns:q2="http://www.w3.org/2001/XMLSchema" p4:type="q2:string">487ba508-4fba-49f1-be4f-ceee2624da0a</Value> </Property> <Property> <Name>TextField</Name> <Value xmlns:p4="http://www.w3.org/2001/XMLSchema-instance" xmlns:q6="http://www.w3.org/2001/XMLSchema" p4:type="q6:string">{44a5d269-ce40-4a8f-b0d6-6b7bcb95ff71}</Value> </Property> <Property> <Name>AnchorId</Name> <Value xmlns:p4="http://www.w3.org/2001/XMLSchema-instance" xmlns:q3="http://www.w3.org/2001/XMLSchema" p4:type="q3:string">00000000-0000-0000-0000-000000000000</Value> </Property> <Property> <Name>IsPathRendered</Name> <Value xmlns:p4="http://www.w3.org/2001/XMLSchema-instance" xmlns:q7="http://www.w3.org/2001/XMLSchema" p4:type="q7:boolean">false</Value> </Property> <Property> <Name>IsKeyword</Name> <Value xmlns:p4="http://www.w3.org/2001/XMLSchema-instance" xmlns:q8="http://www.w3.org/2001/XMLSchema" p4:type="q8:boolean">false</Value> </Property> <Property> <Name>Open</Name> <Value xmlns:p4="http://www.w3.org/2001/XMLSchema-instance" xmlns:q5="http://www.w3.org/2001/XMLSchema" p4:type="q5:boolean">false</Value> </Property> </ArrayOfProperty> </Customization> </Field>

A couple notes

If you fail to do this successfully, it may look like your column is working. However, SharePoint will not create managed or crawled properties correctly, thus making your column not searchable.

Final site script actions

The next thing we want to do is escape the XML so can we can use it inside a JSON site script. Then finally, we can add the Field definitions to our site script using the “createSiteColumnXml” action.

Here is an example of the two site script actions required to deploy a Managed Metadata field using site designs.

 {
   "verb": "createSiteColumnXml",  
    "schemaXml": "<Field ID=\"{44a5d269-ce40-4a8f-b0d6-6b7bcb95ff71}\" SourceID=\"http:\/\/schemas.microsoft.com\/sharepoint\/v3\" Type=\"Note\" Name=\"MyTestMMDTaxHTField\" StaticName=\"MyTestMMDTaxHTField\" DisplayName=\"MyTestMMDTaxHTField\" Group=\"Test group\" ShowInViewForms=\"FALSE\" Required=\"FALSE\" Hidden=\"TRUE\" CanToggleHidden=\"TRUE\" />"  
 },   
 {  
  "verb": "createSiteColumnXml",  
  "schemaXml": "<Field Type=\"TaxonomyFieldType\" Name=\"MyTestMMD\" SourceID=\"http:\/\/schemas.microsoft.com\/sharepoint\/v3\" StaticName=\"MyTestMMD\" DisplayName=\"My Test Tax\" Group=\"Test group\" ShowField=\"Term1033\" Required=\"FALSE\" EnforceUniqueValues=\"FALSE\" Mult=\"FALSE\"> <Default></Default> <Customization> <ArrayOfProperty> <Property> <Name>SspId</Name> <Value xmlns:q1=\"http://www.w3.org/2001/XMLSchema\" p4:type=\"q1:string\" xmlns:p4=\"http://www.w3.org/2001/XMLSchema-instance\">1ba8a7c0-a373-4bb7-8ee0-2d130933743a</Value> </Property> <Property> <Name>GroupId</Name> <Value xmlns:q2=\"http://www.w3.org/2001/XMLSchema\" p4:type=\"q2:string\" xmlns:p4=\"http://www.w3.org/2001/XMLSchema-instance\">0e8f395e-ff58-4d45-9ff7-e331ab728beb</Value> </Property> <Property> <Name>TermSetId</Name> <Value xmlns:q2=\"http://www.w3.org/2001/XMLSchema\" p4:type=\"q2:string\" xmlns:p4=\"http://www.w3.org/2001/XMLSchema-instance\">487ba508-4fba-49f1-be4f-ceee2624da0a</Value> </Property> <Property> <Name>TextField</Name> <Value xmlns:q6=\"http://www.w3.org/2001/XMLSchema\" p4:type=\"q6:string\" xmlns:p4=\"http://www.w3.org/2001/XMLSchema-instance\">{44a5d269-ce40-4a8f-b0d6-6b7bcb95ff71}</Value> </Property> <Property> <Name>AnchorId</Name> <Value xmlns:q3=\"http://www.w3.org/2001/XMLSchema\" p4:type=\"q3:string\" xmlns:p4=\"http://www.w3.org/2001/XMLSchema-instance\">00000000-0000-0000-0000-000000000000</Value> </Property> <Property> <Name>IsPathRendered</Name> <Value xmlns:q7=\"http://www.w3.org/2001/XMLSchema\" p4:type=\"q7:boolean\" xmlns:p4=\"http://www.w3.org/2001/XMLSchema-instance\">false</Value> </Property> <Property> <Name>IsKeyword</Name> <Value xmlns:q8=\"http://www.w3.org/2001/XMLSchema\" p4:type=\"q8:boolean\" xmlns:p4=\"http://www.w3.org/2001/XMLSchema-instance\">false</Value> </Property> <Property> <Name>Open</Name> <Value xmlns:q5=\"http://www.w3.org/2001/XMLSchema\" p4:type=\"q5:boolean\" xmlns:p4=\"http://www.w3.org/2001/XMLSchema-instance\">false</Value> </Property> </ArrayOfProperty> </Customization> </Field>"  
  },

You can see a full site script in this Gist.

Caveats & “uh ohs”

Using the site script actions above, you should be able to successfully create Managed Metadata fields using site designs. Just be aware that if you see some negative impacts when provisioning these…they are not fully supported by Microsoft.

Augment SharePoint site provisioning with messaging in real-time with Socket.io

Modern provisioning in SharePoint has taken on a new framework called Site designs. Site designs are like templates in that they can be used each time a new site is created in your Office 365 tenancy. A site design is essentially a list of actions (site scripts) that you want SharePoint to execute when creating new sites. These actions may include:

  • Creating a new list or library (or modifying the default one created with the site)
  • Creating site columns, content types, and configuring other list settings
  • Applying a theme
  • Setting a site logo
  • Adding navigation
  • Triggering a Microsoft Flow
  • Installing a deployed solution from the app catalog
  • Setting regional settings for the site
  • Setting external sharing capability for the site

Extending site designs

While site designs are continually being improved and expanded on by Microsoft, there are some gaps. From the beginning, Microsoft was aware they wouldn’t be able to fill all  gaps from the start so they allowed us to extend the out of the box provisioning using Microsoft Flow and Azure Functions using the “triggerFlow” action. To learn more about this functionality follow this PnP documentation.

Picture1.png

This model is extremely extensible and allows you to move some of the workload over to an Azure Function or Azure Automation Services to run PowerShell & C# to apply more custom provisioning artifacts such as pre-configured pages and web parts.

No Messaging?

Currently there is a limitation using this model. Given that the provisioning process has moved off into Azure, we are unable to notify the user what the current stage the Azure Function is currently running at.

Here is what the current messaging system looks like

Picture2.png

I’ve been told that that ability to provide our own messaging into this dialog is “coming”, but currently I wanted to overcome this limitation.

Clippy is back!

Months ago when SPFx application customizers were released I jokingly built a Clippy extension to run on modern SharePoint pages. The goal was to show how to call Microsoft Graph from an application customizer.

Clippy.png

I thought I would supercharge the functionality of Clippy by connecting him to the site design provisioning process.

Socket.io + Express

In order to do this, I had to come up with a mechanism for providing Clippy real-time updates during the provisioning process. I had recently started playing around with Socket.io and I believed this would be the best route forward.

I implemented Socket.io inside an Express api which is currently living up in the Azure. The plan is use this Socket.io as a messaging relay between the Azure Functions and my Clippy extension.

This is what the new flow looks like

NewFlow

We start with a site design that sends the new site URL to Microsoft Flow. Microsoft Flow will pick up that trigger and send an HTTP request to a Durable Azure Function orchestrator in Azure.

The Durable Azure Function orchestrator allows me to split out provisioning tasks (create lists, create pages, provision navigation, apply branding) while at the same time, maintaining state across my Azure Function tasks. As the provisioning is happening, I will send updates to Socket.io.

The Socket.io will receive the message from the Azure Function and update Clippy in real-time in SharePoint.

Socket.IO Configuration

Connection

In order to configure Socket.io to be the messaging system, I had to make sure I was working with individual clients and not broadcasting messages across all Clippy extensions in my tenancy. To do this, I am emitting from Clippy a “room” name. This room is the siteURL of the current site Clippy is running.

ioconnect

By doing this, whenever  I send a message from Socket.io to Clippy, I know exactly where to send it to.

Messaging

Messaging to Clippy is done through a POST request to Socket.Io The POST request contains a message, the provisioning status (complete/running) and the URL (unique identifier for the room). I take these parameters and emit the message to the Clippy extensions where room name is equal to the Site URL.

POstMessage

Clippy Configuration

Configuring Clippy is quite simple, it’s as easy as connecting to Socket.io in Azure and subscribing to the “emit” events.

Inside the _renderPlaceHolders() function of my application customizer, I am going to create a new Clippy and register to Socket.io

ClippyRegister

Inside the _registerSocketIO, I instantiate a new socket request to Socket.io. Once connected, I am going to send a message with my “room” name. This room name is going to be uniquely identified by the siteUrl of the current site being provisioned.

regiserIO

I have two basic actions I am subscribing to — “provisioningUpdate” and “provisioningComplete”. When Socket.io receives a message and broadcasts that, Clippy will pick it up and “speak” to the user the current update from provisioning.

The Azure Function

As previously mentioned, I am using a Durable Function to do the provisioning process. To learn about Durable Functions follow this link.  Here is what the Orchestrator tasks looks like.

Asure Function Design.png

Notice that I am passing in the siteUrl coming from my Microsoft Flow HTTP trigger. Inside, I have a couple tasks that are running.

  • Establish site as a hub site
  • Provisioning Lists
  • Provision Pages
  • Provision Terms

Also notice that I have an _emitUpdate() function which is running before and after my asynchronous tasks. During the provisioning process, this _emitUpdate is going to POST a message to Socket.io.

What a task looks like

Let’s take a look at what an individual task looks like.

ProvisionLists

My Azure Function task is going to create a new AppOnly context to SharePoint, load a provisioning template that contains a set of lists to be created and uses ApplyProvisioningTemplate(template) to apply the template to my site.

Inside _emitUpdate

My _emitUpdate is fairly simple. It’s going to take a message from the Orchestrator, create a new HttpClient and execute a POST message to my Socket.io with the current status of the provisioning process.

emitUpdate

Putting it together

Without going to deep into this (because it really is more high level education than anything)… let’s see what these messages look like in real time.

If Gif is missing… wait for it to load. Full size view can be found here.

ClippyProvision-min (1)

Want to learn more?

If you are looking to learn more about how I put this together, join me at SharePoint Saturday Denver on October 6th and I’ll be also be demoing this solution at SharePoint Saturday New England! Sign up!

An Open Invitation: #MSIgnite2018

With Microsoft Ignite only days away,  there is a lot of excitement around new releases and features as it pertains to Office 365 & SharePoint! Microsoft Ignite is a great experience to learn new things, connect with Microsoft Product Teams on new features and also network with like minded people!

Sometimes, it feels like too much. There are so many great sessions happening through the day, that you’ve likely jammed packed your schedule, rushing between sessions and heading to the expo hall. Like many, you may be using Microsoft Ignite as a way to get some one on one time to address issues you have been experiencing or any questions you are looking to have  answered.

In reality, the only downtime you have may be breakfast and lunch.  This is where I’d like to extend an open invitation to anyone interested.

Let’s chat over breakfast/lunch!

Unfortunately, I am unable to speak at Microsoft Ignite, but I would still love to connect with people who are attending or might be seeking some more in depth discussions about questions or concerns they may have with a lot of the new features in Office 365.

So let’s take the opportunity to sit down in a laid back environment, bounce some ideas and questions off each other.  I understand I may not be able to answer all of your questions, but maybe I’ll be able to point you in the right direction, or introduce you to someone who does know the answer 🙂

Topics we can chat about

  • SharePoint Administration
  • SharePoint Development (classic & modern SPFx)
  • General SharePoint Online/Office 365 (Provisioning, architecture, IA, Search)
  • Office 365 Apps (Microsoft Flow, Microsoft Planner, PowerBI)

How to find me

The best way to find me is to reach out to me on Twitter . You can tweet at me and we’ll find a table during breakfast and lunch and chat! Hope to see you there.

Customizing the SharePoint Starter-Kit for Office 365 Part 3 – Collab Footer

The SharePoint Starter Kit is an open source initiative that provides an end to end solution for provisioning pre-built sites, web parts, extensions, site designs and more in an Office 365 environment. If you’ve explored it’s functionality and are looking to see how you can configure and customize it yourself, today we’ll be talking about the Collab footer.

The Collab footer is the menu bar (highlighted in red) at the bottom this image.

CollabFooter

The Collab footer is a SharePoint Framework customizer that allows for showing a set of standardized links and supports personalized links for the current logged in user.  You may be thinking this is very similar to the Portal footer. In fact, it is very similar in that it shares the same personal links. That means when a user configures a personal link on the Collab footer, it will automatically show up on the Portal footer in the hub site as well!

The personal links are stored in a property on the User Profile that needs to be created by an admin. Instructions to do so can be found on the GitHub repository at this page.

Here is what the Collab footer looks like when hovering over nested links.

CollabFooterExpanded

Where are the links stored?

Unlike the Portal footer, where the links are stored in a SharePoint list… the links in the Collab Footer are stored in the Term store which gets automatically provisioned during the deployment of the Starter Kit.

CollabFooterTerms

How to modify the links in the Collab Footer

In order to modify the links in the footer, you’ll need to edit the properties on each term within the PnP-CollabFooter-SharedLinks term set. Let’s make a modification to the Legal Policies link. By default, it links to https://intranet.contoso.com/LegalPolicies and looks like this.

CollabFooter-LegalPolicies

If you’d like to change the label for the link, just rename the term in the term set. Select the term and change the default label.

CollabFooterDefaultLabel.png

The link value is stored on the navigation property of the term in the term set. Click on the term and select Navigation from the tabbed menu.

CollabFooterNavigation.png

Let’s modify the default value to now link to a new library in our HR site that holds policy documents and click save.

CollabFooterChangeLink

 

Modify the link icon

If you are adding your own links or wish to change the icon of an existing link, it’s very simple. The icon’s used for the links are stored on custom properties on the term and references UI Fabric Icons.

Navigate to the UI Fabric Icons site and select an icon that suits your needs. Let’s modify the lock icon to be the “Documentation” icon instead of a padlock. Hover over the icon with your mouse, and copy the value underneath it.

CollabFooterDocumentation

To change the icon, navigate to the Term Store and select the term you wish to change. Select Custom Properties from the tabbed menu and you’ll find a custom property called PnP-CollabFooter-Icon. The default value for Legal Policies is “Lock”. This value is the icon class from UI Fabric.

Replace this value in the custom property of the term with the Fabric Icon we copied.

CollabFooterDocumentationSaved

If we reload the Collab footer we will see the new icon!

CollabFooterNewIcon

My new icon isn’t working!

You may find when you update the Icon with a different one, that it doesn’t render and instead you see a square box instead.

NoIcon

The reason for this is the SharePoint Framework isn’t using the latest version of Office UI Fabric. Because of this, you’ll have to choose a new icon.

Customize a menu for each Team site

After deploying the Starter Kit, you will notice the Collab footer is identical on both the HR and the Marketing site (this is by design). In the real world, it might make sense for department sites to have their own footer. In my environment, I had deployed an IT site along side the HR and Marketing team sites.

Let’s create a new footer for the Information Technology team site. In order to do so, here are the list of things we’ll need to do.

  1. Create a new term set for the IT site
  2. Remove the current Collab footer
  3. Add Collab footer back with new clientsidecomponentproperties

Create new Term Set

ItLinks

Start by creating a new Term Set under the PnPTermSets group. We’ll call it “PnP-CollabFooter-ITLinks”Create a couple terms, update their links in the Navigation menu and add the custom property for the icon from the Custom Properties menu.

Remove the current Collab footer.

In order to remove the existing Collab footer that was deployed from the Starter Kit, we’ll need to use PowerShell.

Connect-PnPOnline https://yoursite.sharepoint.com/sites/itsite
Remove-PnPCustomAction -Identity "CollabFooter"

Add updated Collab Footer

Now that we have removed the existing footer, we need up add the footer back and update the clientsidecomponentproperties before we do.

Clientsidecomponentproperties is a JSON object that defines a set of properties to be used by a SharePoint Framework component. Notice the property “sourceTermSet”.

Connect-PnPOnline https://yoursite.sharepoint.com/sites/itsite
Add-PnPCustomAction -Name "CollabFooter" -Title "CollabFooter" -ClientSideComponentId c0ab3b94-8609-40cf-861e-2a1759170b43 -Location "ClientSideExtension.ApplicationCustomizer" -ClientSideComponentProperties "{""sourceTermSet"":""PnP-CollabFooter-ITLinks"",""personalItemsStorageProperty"":""PnP-CollabFooter-MyLinks""}"

In the sourceTermSet value, I have set the value to the name of the new PnP-CollabFooter-ITLinks term set set we created earlier. Run this command and then navigate to your Information Technology site and see the new footer!

ITNewFooter.png

Final Thoughts

I hope you find this post helpful. The SharePoint Starter Kit is a great example of how to provision solutions into Office 365. It includes 17 different web parts and 7 application customizers which are free for you use to use and modify! If you have any questions or would like more information on this post, please comment and let me know!

Sharing is caring.

How To: Create Modern SharePoint site templates using Office 365 Site Designs

One of the biggest questions I see is, “How do we create site templates using Office 365 groups?”. It is no surprise that site templates were one of the most widely used features in previous versions of SharePoint. Site templates give site owners and SharePoint admins a way to incorporate some governance into the creation of team sites and expedite the creation process. However, this out-of-the-box functionality, until recently wasn’t available for new modern sites.  In this blog we’ll step through creating our own using an Office 365 group.


Before we begin you should be aware that we no longer call them “site templates”. In the modern SharePoint world, Microsoft has chosen to designate the names “site designs” for modern templating. So if you find yourself needing to search google, keep this in mind.

Secondly, site designs aren’t the only way to create templated sites within SharePoint. A very common and community driven framework known as PnP Provisioning it also a very common way to create templates and provision new sites into your Office 365 & SharePoint environments. If you would like to know the difference’s between site designs and PnP Provisioning please check out Chris O’Brien’s recent post.


A walk through

The Site Script

The first step to creating a modern site template is to create a site script using a JSON file. A site script is a file that defines that actions that SharePoint will run when a user selects your site design. Site scripts are provisioned using SharePoint Online Management Shell. For this example, we are going to create a new department team site template to be used within an Office365 Group. However, we will be adding in some PnP scripts to add a global navigation using the SharePoint Framework to the newly created site. To learn more about what actions are available, click here


   {
 "$schema": "schema.json",
     "actions": [
                    {
           "verb": "applyTheme",
           "themeName": "Custom Black"
         },
         {
             "verb": "createSPList",
             "listName": "Team Projects",
             "templateType": 100,
             "subactions": [
                 {
                     "verb": "SetDescription",
                     "description": "List to hold Team Project Statuses"
                 },
                 {
                     "verb": "addSPField",
                     "fieldType": "Text",
                     "displayName": "Project Status",
                     "addToDefaultView": true,
                     "isRequired": true
                 },
                 {
                     "verb": "addSPField",
                     "fieldType": "User",
                     "displayName": "Project Manager",
                     "addToDefaultView": true,
                     "isRequired": true
                 },
                 {
                     "verb": "addSPField",
                     "fieldType": "Note",
                     "displayName": "Project Notes",
                     "isRequired": false
                 }
             ]
         },
         {
            "verb":"triggerFlow",
            "url":"THIS-IS-THE-URL-TO-YOUR-FLOW",
            "name":"Provision Assets for Group",
            "parameters":{
                "event":"",
                "product":""
            }
         },
         {
            "verb":"setSPFieldCustomFormatter",
            "fieldDisplayName":"Project Status",
            "formatterJSON":{
    "elmType": "div",
    "txtContent": "@currentField",
    "style": {
        "color": "#fff",
        "padding-left": "14px",
        "background-color": {
            "operator": "?",
            "operands": [
                {
                    "operator": "==",
                    "operands": [
                        "@currentField",
                        "Red"
                    ]
                },
                "#e81123",
                {
                    "operator": "?",
                    "operands": [
                        {
                            "operator": "==",
                            "operands": [
                                "@currentField",
                                "Green"
                            ]
                        },
                        "#00B294",
                        {
                            "operator": "?",
                            "operands": [
                                {
                                    "operator": "==",
                                    "operands": [
                                        "@currentField",
                                        "Amber"
                                    ]
                                },
                                "#ff8c00",
                                {
                                    "operator": "?",
                                    "operands": [
                                        {
                                            "operator": "==",
                                            "operands": [
                                                "@currentField",
                                                "Yellow"
                                            ]
                                        },
                                        "#fff100",
                                        ""
                                    ]
                                }
                            ]
                        }
                    ]
                }
            ]
        }
    }
}
         }
     ],
         "bindata": { },
 "version": 1
}

 

In this scenario, we will be using the following actions:

createSPList

This action will create a new list named “Team Projects”. It will also create associated columns pertaining to a typical project.

addSPField

This action will create those new fields on the Team Projects list.

applyTheme

This action will apply a created theme (either out of the box, or a custom one using the new fabric theme generator) and apply it to the newly created site.

triggerFlow

This action is going to fire off a Microsoft Flow, passing the URL of the newly created site. The flow will trigger an Azure Function which is going to provision some SPFx components using PnP PowerShell.

setSPFieldCustomFormatter

This action is going to apply a JSON object for the Column Formatter to apply on the Team Projects list.


Create a Theme

Creating a theme for a modern site is a little bit different than we’ve done in the past using composed looks in classic SharePoint. We are going to want to use the new Theme Generator when creating themes for modern sites. This generator, though limited at the time, allows us to modify a primary color, body color and a background color.

ThemeBuilder.png

Start by playing around with the color selectors. You’ll notice that at the bottom, the Fabric Palette will change colors and you can see how some fonts and controls will be themed when loaded into your SharePoint site. I am going to build a black and yellow theme. You’ll also notice it gives you a specified output in JSON,SASS and PowerShell. These will be used depending on how we upload the new theme to SharePoint — in our scenario, we’ll be using PowerShell.

Copy the contents of the PowerShell output and open up PowerShell. We’ll provision the new theme to our environment using the SharePoint Online Management Shell. For more detailed information on this process, please follow this post. To provision the theme, we’ll connect to our tenant and then using the Add-SPOTheme command we’ll provision the JSONObject


    $themepallette = @{
  "themePrimary" = "#00ffff";
  "themeLighterAlt" = "#f3fcfc";
  "themeLighter" = "#daffff";
  "themeLight" = "#affefe";
  "themeTertiary" = "#76ffff";
  "themeSecondary" = "#39ffff";
  "themeDarkAlt" = "#00c4c4";
  "themeDark" = "#009090";
  "themeDarker" = "#005252";
  "neutralLighterAlt" = "#f8f8f8";
  "neutralLighter" = "#f4f4f4";
  "neutralLight" = "#eaeaea";
  "neutralQuaternaryAlt" = "#dadada";
  "neutralQuaternary" = "#d0d0d0";
  "neutralTertiaryAlt" = "#c8c8c8";
  "neutralTertiary" = "#a6a6a6";
  "neutralSecondaryAlt" = "#767676";
  "neutralSecondary" = "#666666";
  "neutralPrimary" = "#333";
  "neutralPrimaryAlt" = "#3c3c3c";
  "neutralDark" = "#212121";
  "black" = "#000000";
  "white" = "#fff";
  "primaryBackground" = "#fff";
  "primaryText" = "#333"
 }
 
Connect-SPOService -Url https://yoursharepoint-admin.sharepoint.com
Add-SPOTheme -Name "Custom Black" -Palette $themepallette -IsInverted $false

If you have a good eye, you’ll notice the -Name parameter is also the same name that is in the applyTheme action of my site script. This will be the new theme we provision when our new Site Design runs.

If you are wondering where this theme shows up, navigate to your SharePoint site, hit the gear in the top right and select Change the look. You’ll see your new theme!

ThemeChangeTheLook.png

 

Package and Upload SharePoint Framework Navigation

The reason I am deploying a custom global navigation solution is because Hub Sites currently do not exist in Office 365 tenants. So in the meantime, I’d still like to apply a global navigation across all of my sites that I create so that they feel “connected” in the new flat structure.

The first thing you will want to do is head over to the SharePoint extensions GitHub and pull down Paolo’s global navigation application customizer. This SPFx solution, is a global navigation menu that is injected into the header (and/or footer) of your SharePoint sites. It is a tenant-wide deployment, which means it will automatically be available to all site collections without having to add the app through site contents. The documentation provided should give you all the information required to set this up. If you need information on how to build customizations using SPFX, start here.

I have downloaded and built the SharePoint Framework solution and uploaded it to my app catalog within my tenancy. The next thing I need to do, is configure a global navigation that I want all of my modern sites to use and then we’ll proceed to creating some PowerShell scripts.

TermStore

 

Create Azure Function & Call PnP to provision Global Navigation

As mentioned previously, we’ll be calling an Azure Function via the Microsoft Flow trigger. There are a couple ways to do this, either by setting up a Queue Function using App Authentication, or you configure your Azure Function to grab your credentials from environment variables. The preferred method is to set up your credentials using App-Only authentication as outlined in that blog post. You’ll want to use this post to figure out how to add PnP Modules to your Azure Function. In my scenario, I am actually going to set up an HTTPTrigger Azure Function because why not show a different example… and also because I may have a need to call this function directly in other scenarios.

Below is my Azure Function PowerShell. The PowerShell code is also available on Paolo’s github for the menu.


    #incoming webUrl from the Microsoft Flow call
    # POST method: $req
    $requestBody = Get-Content $req -Raw | ConvertFrom-Json
    $name = $requestBody.name
    
    # GET method: each querystring parameter is its own variable
    if ($req_query_name) 
    {
        $webUrl = $req_query_name 
    }

    Connect-PnPOnline -AppId $env:SPO_AppId -AppSecret $env:SPO_AppSecret -Url $webUrl
    
    $context = Get-PnPContext
    $web = Get-PnPWeb
    $context.Load($web)
    Execute-PnPQuery
    
    $ca = $web.UserCustomActions.Add()
    $ca.ClientSideComponentId = "b1efedb9-b371-4f5c-a90f-3742d1842cf3"
    $ca.ClientSideComponentProperties = "{""TopMenuTermSet"":""TenantGlobalNav"",""BottomMenuTermSet"":""TenantGlobalFooter""}"
    $ca.Location = "ClientSideExtension.ApplicationCustomizer"
    $ca.Name = "TenantGlobalNavBarCustomAction"
    $ca.Title = "TenantGlobalNavBarCustomAction"
    $ca.Description = "Custom action for Tenant Global NavBar Application Custom"
    
    $ca.Update()
    
    $context.Load($web.UserCustomActions)
    Execute-PnPQuery

The code is going to recieve a parameter called webUrl and it will be the url of the new site created from my site design. This url is used in the Connect-PnPOnline command.

Create Microsoft Flow

Creating the Microsoft Flow is required because it will be the mechanism for which we pass a webUrl parameter to our azure function (we can’t call an Azure Function directly from a site script).The flow will consist of two actions: When a HTTP request is received and a HTTP requestAs previously mentioned, most tutorials will likely show you using flow to add a message to an Azure queue. I will be calling the Azure Function directly.

Use this JSON to place into your body JSON for your Http Request received 


    {
    "type": "object",
    "properties": {
        "webUrl": {
            "type": "string"
        },
        "parameters": {
            "type": "object",
            "properties": {
                "event": {
                    "type": "string"
                },
                "product": {
                    "type": "string"
                }
            }
        }
    }

}

 

Here is the full Flow. You need to grab the Uri to your Azure Function. You can get this URL by opening up your Azure Function and selecting </> Get function url in the top right of your code window.

Flow.png

You’ll notice that inside the body of the HTTP request, I am passing a parameter called webUrl, which is equal to the web url of the new site I am creating. This property comes through within the Flow request.

 

Update triggerFlow action in site script

Now that we have configured our Flow and our Azure Function, we need to connect the Flow to the site script (JSON file above). To do this, copy the Flow URL, When a HTTP request is received in your Flow (it’s outlined in grey in the image).

Copy and paste this into our site script in the triggerAction verb like so:

OLD

    
         {
            "verb":"triggerFlow",
            "url":"THIS-IS-THE-URL-TO-YOUR-FLOW",
            "name":"Provision Assets for Group",
            "parameters":{
                "event":"",
                "product":""
            }
         }
         

NEW



         
          {
            "verb":"triggerFlow",
            "url":"https://prod-06.westus.logic.azure.com:443/workflows....",
            "name":"Provision Assets for Group",
            "parameters":{
                "event":"",
                "product":""
            }
         }

Upload site script and site design

That’s it! The only thing left to do is add the site script and site design using PowerShell. I have created the site script and saved it into a JSON file called SiteScriptProvisionGlobalNav.json.

Add-SPOSIteScript


    Connect-SPOService -Url 'https://yourtenant-admin.sharepoint.com'
    #get JSON content and add site script
    Get-Content 'C:\Users\Me\SiteScriptProvisionGlobalNav.json'-Raw | Add-SPOSiteScript  -Title "Aerie Team Site"
    

Running this in PowerShell will return the ID of the new site script. We’ll use this ID to add the site design to the tenant. Notice -SiteScripts parameter is equal to the ID of the newly uploaded site script and -WebTemplate is “64”. The value 64 represents an Office 365 Group and the value 68 would represent a communication site.

Add-SPOSiteDesign


    
Add-SPOSiteDesign -Title "Aerie Team Site" -WebTemplate "64" -SiteScripts "7a5c6fd8-0953-4381-a04d-6a4400448d0c" -Description "Creates a new Aerie Team Template Site with Global Nav"-PreviewImageUrl "https://mytenant.sharepoint.com/SiteAssets/logo.jpeg" -PreviewImageAltText "site preview"

    

 

Add your team site!

Finally, the last thing to do is create your new team site from your site design and watch the magic happen!

Navigate to the /_layouts/15/SharePoint.aspx page and select + Create Site

Site Slection

Remember that we’ll be selecting a team site. On the next window, we should see our new site design.

TeamSiteCreation

After clicking next and finish, we should start seeing our site script do it’s work. It will start by applying our Custom Black theme, creating a new Team Projects list and subsequently triggering a flow to add global navigation to our newly created site

SideWindow

 

Now check out the final product! We have a newly created group site, with a SPFx global navigation menu in the header of the site!

Black


 

How To: PnP Starter-Kit for Office 365 Part 2 – Tiles

Welcome back to another post in my blog series on the PnP Starter-kit. If you’ve found this post, it’s likely you already know what the PnP Starter Kit is. However, if you do not, I’ve written a quick starter post about it here. The PnP Starter Kit is an open source initiative that provides an end to end solution for provisioning pre-built sites, web parts, extensions, site designs and more in an Office 365 environment.

Today we’ll be talking about the Tiles web part (highlighted in red)!

Tiles.png

The Tiles web part is a grid of links that can be customized using the out of the box page editing experience. This web part allows you to customize which icon to load, the size of the tiles and where the tiles link to. To start customizing, set the page in edit mode and edit the web part.

TilesProperties

Icons

If you open up the properties, you will notice in the header a description that specifies how to change/add the icons to your tile. There is a link that brings you to the Office UI Fabric Icon page. This is important, but current limitation (feature?) of the Tiles web part is that you can only source icons from the Office Fabric Icon library.

One caveat you should be aware of as you navigate and start choosing icons, is that the Office UI Fabric site may be more up to date than the icons available in the SPFx solution.  This is because the version of Office UI Fabric used in the SharePoint Framework is a little behind the current release of Office UI Fabric. If you select an icon and it doesn’t load, this would be why.

Configure the Tiles

Unlike other implementations of tile links (promoted links for example), the Tiles web part isn’t list driven. What I mean by that, is in order to change the tiles and their links, you’ll have to actually open up and edit the web part every time. While it is a different editing experience, it actually has some real sweet under the covers. When you click “Configure the Tiles”, you’ll notice a new editing modal pop up.

TilesPrropertyExpanded

This editing pane is a table that you can modify properties such as the Title, Description, URL, UI Fabric Icon and specify whether the link should load in the same window or a new tab.

What gets me excited most about this property pane, is that it is not built specifically for this web part. In fact, if you are building SPFx solutions and have a need for inserting complex data types of lists/collections, you can use this! The best part is that this control is included in the re-usable property pane controls repository here.

Create a new Link

Let’s say we are going to build a new Tile link which links to the Microsoft Forms web site. Let’s start by clicking “Configure the tiles” and adding a new record for our new link. We’ll put the title as “Forms” and specify the URL to https://forms.office.com

NewLink

 

Next, we need to find an Icon to load into our tile. Let’s navigate to the UI Fabric website and find the icon for Microsoft Forms.

FormsIcon.png

You’ll notice when you hover of the icon, it shows the name of the icon “OfficeFormsLogo”. This is actually the class name that UI Fabric uses to render icon. Let’s copy that value and we’ll paste it into our property pane for a new tile in the “UI Fabric icon name” field.

FabricIconAdded

Now if you click “Add and Save”, you should see your new tile link!

FormsLoaded.png

 

 

Customizing the PnP Starter-Kit for Office 365 Part 1 – Portal Footer

If you’ve found this post, it’s likely you already know what the PnP Starter Kit is. However, if you do not, I’ve written a quick starter post about it here. The PnP Starter Kit is an open source initiative that provides an end to end solution for provisioning pre-built sites, web parts, extensions, site designs and more in an Office 365 environment.

While it really is an exhaustive example of how this can be done, many people are hoping to augment the solution to suit their own business needs. Because of this, I am going to start a series about how to configure and change certain aspects of the starter kit. In this post, we’ll talk about how to modify the footer in the hub site, aka “Portal Footer”.

The Portal Footer is the orange bar (highlighted in red) at the bottom this image.

PnpFooter

The portal footer is an expanding footer that allows for showing standard company links and supports personalized links for the current logged in user. The personal links are stored in a property on the User Profile that needs to be created by an admin. Instructions to do so can be found on the GitHub repository at this page.

Here what the footer looks like expanded.

PnpFooterExpanded.png

You’ll notice there are columns with a list of links inside. They are grouped by “Applications”, “Internal Modules”, “News” and “My Links” (the links that are held on the user profile).  The “Applications”, “Internal Modules” and “News” group of links are stored within a SharePoint list on the portal site in a list called “PnP-PortalFooter-Links”, which are deployed automatically with the Starter Kit. If you navigate to the list https://yoursite.sharepoint.com/sites/YourSitePrefix/Lists/PnPPortalFooterLinks/AllItems.aspx you will be able to see and modify the existing links and link groups that show in the footer.

Modify a company wide link in the footer

To modify an existing link in the footer, all you need to do is edit one of the links in the PnPPortalFooterLinks list. Let’s do that now. I am going to open up the CRM link item under “Applications” and change the title from “CRM” to “NEW CRM TITLE”.
PnpFooterLinkChange

Once I save the item, and reload the page and expand my footer, I’ll see my new title.

NewTitleForCRM

Permission the portal link items

While I rarely recommend item level permissions, there are times where this may make sense. Generally speaking, item level permissions can make it hard for IT staff members to manage what content users have access to in SharePoint. Also, in a list with many items, item level permissions become a performance concern. However, in the case of this links list, it’s unlikely we’ll have that many items so it should be fairly easy to manage.

The footer link can only access items in a list that the current logged in user has access to, thus allowing us to show or hide links to specific users. Let’s say that the ERP application in the “Applications” group should only be visible to a specific ERP team. Using out of the box permission, we can remove access and grant permissions to the item for that team only.

Add my own personal links

As previously mentioned, the portal footer allows for users to create and link to their favorite locations that they access the most. To do this, expand the footer using the arrows on the right. You’ll see the ability to add and edit the links on your profile.

AddNewLInk.png

If you are a SharePoint admin, you can navigate to the User Profiles in the SharePoint Admin center and see the values for links that users are storing on their profiles.

UserProfile

 

Update company name

If you look at the footer, you’ll notice it has a copyright for Contoso 2018 and also has a help desk link to support@contoso.com. Changing these values is the most common request I have seen from users who have tested out the starter kit and want to use these extensions. In order to do this, we actually need to modify the PnP Provisioning template provided with the solution because these values aren’t stored anywhere in SharePoint.

If you have downloaded/cloned the repository, navigate to the provisioning folder and open up the hubsite.xml file. This is the template that defines the structure of the portal site. It includes all of the pages, the navigation, the web parts and identifies which application customizers will load for this site. Towards the bottom of the file you will see an XML node called <pnp:CustomActions>, inside it defines the Portal Footer properties.
PortalFooterXML

Let’s say I want to change the values highlighted in red that correspond to the Copyright and Help link in the footer. My fictional company is Cameronsoft and we manufacture fake widgets, so I definitely want to have my company’s name in the footer at all times. I will change these values in the template.xml before deploying the PnP starter kit.

portalxmlcameronsoft.png

Now, if i deploy the starter kit, my company’s information will be listed at the bottom instead of Contoso!

Cameronsfotfooter.png

Updating an already deployed footer

Let’s say you’ve deployed the footer but you didn’t realize that it would be labeled with Contoso. I wouldn’t try to re-deploy the starter-kit, because you may find complications with that. So here is a set of PowerShell scripts to help you do so. Using PnP, you’ll need to connect to the hub site and remove the existing portal footer, and re-add a new one with new properties.

Connect-PnPOnline https://yoursite.sharepoint.com/sites/demositeportal
Remove-PnPCustomAction -Identity "PortalFooter"

Add-PnPCustomAction -Name "PortalFooter" -Title "PortalFooter" -ClientSideComponentId b8eb4ec9-934a-4248-a15f-863d27f94f60 -Location "ClientSideExtension.ApplicationCustomizer" -ClientSideComponentProperties "{""linksListTitle"":""PnP-PortalFooter-Links"",""copyright"":""@Copyright CameronSoft, 2018"",""support"":""support@cameronsoft.com"",""personalItemsStorageProperty"":""PnP-CollabFooter-MyLinks""}"

We start by connecting to the hub site using Connect-PnPOnline.

Then we remove the application customizer with the name “PortalFooter”. Followed up by Add-PnPCustomAction. Notice, the clientsidecomponentproperties is a JSON object that defines the values on the footer. Just update these to include your company instead of Constoso!

Modify Footer code

You may find the footer isn’t displayed exactly how you like, or you want to add your own custom functionality. Well, no problem there! This is an open source project and you are free to change anything you like. To find the footer code, open your sp-starter-kit folder in VS Code and navigate to /solution/src/extensions/portalfooter This is where you can modify the code to suite your needs. Once complete, just rebuild and package the solution then upload it to your app catalog! Instructions on SPFx and how to build and deploy apps can be found here.

Final Comments

I hope you find this post helpful. As I mentioned, I am going to be doing a short series on this for those of you who wish to customize or change the PnP Starter kit. If you have any questions, I suggest going to the GitHub repository first. Eric Overfield has done a fantastic job producing documentation for this solution. If you can’t find what you are looking for, you can ask a question in the issues list or you can just comment on this post and I’d be happy to help!