SharePoint Framework

Add comments to SharePoint list items using the REST API

Beau Cameron6 Comments

One of the newest features to come to SharePoint Online is the ability to add comments within the activity panel on SharePoint list items. In a previous post, I talked about how we can retrieve these new comments using the SharePoint REST API.

List comments are a great new way for users to collaborate together on list items as users can have threaded conversations with one another.

In the past we would have used a multi-line text column with “append changes” to create threaded conversations on list items. The problem with this is this method creates new versions and those comments are difficult to retrieve programmatically. Please see my post on retrieving values in multi-line text fields more efficiently.

Add a comment using the REST API

Recently, I’ve been seeing more posts on support forums and in social asking how these comments can be accessed and created programmatically. Well, like most things in the modern interface, they are implemented using client-side code, which must mean there is a REST API backing the functionality.

You will need to execute a POST request to the following endpoint

Endpoint – https://yourtenant.sharepoint.com/sites/ContosoGroup/_api/web/lists/GetByTitle(“<YourListName>&#8221;)/items(<ItemId>)/Comments()

Parameters – The parameter you will pass through the body is called “text”. Construct your JSON object as {“text”:”your sample comment”}

fetch("https://yourtenant.sharepoint.com/sites/ContosoGroup/_api/web/lists/GetByTitle('Test')/items(<ItemId>)/Comments()", {
"headers": {
"accept": "application/json;odata=verbose",
"content-type": "application/json;charset=UTF-8",
"x-requestdigest": "<yourRequestDigest""
},
"body": "{\"text\":\"Add a new comment\"}",
"method": "POST",
"mode": "cors",
"credentials": "include"
});

Using the above POST call, you can submit a new comment to the list item as the current user (there is no way to add list item comments on-behalf of another user). When you execute the request and update your x-requestdigest, and the appropriate values for the URI, your comment will be successfully added to the list item (see below).

I hope you find this post helpful and if you have any questions, please feel free to reach out!

SharePoint Online – Retrieve values of a multi-line text field with append changes in a single REST call

Beau Cameron5 Comments

One of the most common questions I see in SharePoint support forums is how to retrieve the history of a multi-line text field with “append changes” in SharePoint. In most cases, the answer is to retrieve each previous version of a SharePoint item and iterate through them to construct all values in the multi-line text field.

The reasoning behind this is fairly obvious — each instance of a change in the multi-line text field is stored in a separate version of the SharePoint item.

Take for example the following Test list. This list contains a title field and a multi-line text field with “append changes”

If you open up the information panel for this item, you will see the multiline text field with the previous values. Notice how I have updated this item twice and added a value to the Multi field multiple times.

In order to see how SharePoint stores this data, check out the version history. The version history shows the two times I have edited the item, with the latest version being the most recent value in the multi-line text field.

Now you can see why you need to loop through versions. If you did a standard REST call using something like _api/web/lists/getbytitle(‘Test’)/items(1), the Multi column would only have the value of “My second comment in the multiline text field”.

Well, fear no more! There is in fact a way to retrieve the values in your list item without having to iterate over each previous version of the item.

Introducing RenderExtendedListFormData()

An unknown and undocumented REST endpoint exists in SharePoint Online called RenderExtendedListFormData() is the solution we need. You may be saying, “oh, we shouldn’t use undocumented REST endpoints”. Valid point, however, you should be aware that this endpoint is exactly what is used when rendering the information pane in Modern SharePoint via first-party.

Below you will see how to make this request into SharePoint. The RenderExtendedListFormData method is a POST call and takes 5 parameters:

itemId – The ID of your list item

formId – The form name (this is how MSFT determines what fields are returned in the request based on the form)

mode – I haven’t figured out what this means yet

options – I haven’t figured out what this means yet

cutoffVersion – Which is the latest version you want to pull. e.g, if you pass in 0, it will retrieve every version up until the first. If you pass in “2” it will put every version up until 2.0.

fetch("https://yourtenant.sharepoint.com/sites/contosoportal/_api/web/GetList(@v1)/RenderExtendedListFormData(itemId=1,formId='editform',mode='2',options=47,cutoffVersion=0)?@v1=%27%2Fsites%2Fcontosoportal%2FLists%2FTest%27", {
   "headers": {
     "accept": "application/json;odata=verbose",
     "accept-language": "en-US,en;q=0.9",
     "content-type": "application/json;odata=verbose",
     "sec-fetch-dest": "empty",
     "sec-fetch-mode": "cors",
     "sec-fetch-site": "same-origin",
     "x-requestdigest": "<yourRequestDigest>",
   },
   "referrer": "https://yourtenant.sharepoint.com/sites/contosoportal/Lists/Test/AllItems.aspx",
   "referrerPolicy": "strict-origin-when-cross-origin",
   "body": "",
   "method": "POST",
   "mode": "cors",
   "credentials": "include"
 });

The Response

The response from this call includes a lot of data as it’s used for the rendering of the edit form, but if you look closely you’ll notice the values for the multiline text field are stored in d.RenderExtendedListFormData.<ColumName>

The Multi (your column name) object contains all of the values in the multi-line text field based on the parameters of my REST call above. The response includes the text value, who wrote the value (email, title, id) as well as when the item was created.

HOW AWESOME IS THAT?! I retrieved all appended changes of my multi-line text field, using a single REST call.

Caveats + FYI

As mentioned previously, this is an undocumented REST endpoint. Even though this is used first-party by Microsoft, you should be aware this endpoint is subject to change and your solutions will have a dependency on that. Use at your own risk!

If you know what the other parameters (mode / option) mean in the REST call, I’d love to find out! Please message me if you know!

Retrieve Modern SharePoint list item comments using REST

Beau Cameron1 Comment

Recently someone had posted on a SharePoint support forum asking whether or not it was possible to retrieve the new modern list item comments programmatically. In case you haven’t seen this yet, Microsoft has introduced the ability for users to add comments to the activity feed on list items in SharePoint.

To add a comment, navigate to your list item, open up the information pane and scroll to bottom. You will see the activity feed where you can add, remove and view comments from yourself and others on a list item.

While the endpoint is not yet documented, it is indeed possible to interact with these comments. However, be aware, the comments are not apart of the list item object in REST, you must call a different endpoint to retrieve the values.

Get list item comments using REST

To retrieve all of the comments on a list item using REST, you can make a GET call the following API endpoint.

/_api/web/lists/getbytitle('<ListName>')/items(<ItemID>)/GetComments()

Here is the response

{
    "d": {
        "results": [{
            "__metadata": {
                "id": "https://yourcompanyname.sharepoint.com/sites/SiteName/_api/web/lists('43f52951-64fa-4362-b03e-4fefde369da9')/GetItemById(1)/Comments(1)",
                "uri": "https://yourcompanyname.sharepoint.com/sites/SiteName/_api/web/lists('43f52951-64fa-4362-b03e-4fefde369da9')/GetItemById(1)/Comments(1)",
                "type": "Microsoft.SharePoint.Comments.comment"
            },
            "likedBy": {
                "__deferred": {
                    "uri": "https://yourcompanyname.sharepoint.com/sites/SiteName/_api/web/lists('43f52951-64fa-4362-b03e-4fefde369da9')/GetItemById(1)/Comments(1)/likedBy"
                }
            },
            "replies": {
                "results": []
            },
            "author": {
                "__metadata": {
                    "type": "SP.Shring.Principal"
                },
                "email": "beau@yourcompanyname.com",
                "expiration": null,
                "id": 6,
                "isActive": true,
                "isExternal": false,
                "jobTitle": null,
                "loginName": "i:0#.f|membership|beau@yourcompanyname.com",
                "name": "Beau Cameron",
                "principalType": 1,
                "userId": null,
                "userPrincipalName": null
            },
            "createdDate": "2020-12-15T21:32:05.52Z",
            "id": "1",
            "isLikedByUser": false,
            "isReply": false,
            "itemId": 1,
            "likeCount": 0,
            "listId": "43f52951-64fa-4362-b03e-4fefde369da9",
            "mentions": {
                "__metadata": {
                    "type": "Collection(Microsoft.SharePoint.Comments.Client.Identity)"
                },
                "results": []
            },
            "parentId": "0",
            "replyCount": 0,
            "text": "Add a new comment"
        }]
    }
}

Experiment – Find out where SPFx Web Parts are being used in Modern SharePoint sites

Beau Cameron1 Comment

Recently, I saw a post on Tech Community that asked if there were APIs available to find out where a specific web part may be used in an environment. The reason was to provide a list of sites so an email could be sent to those specific site owners to let them know that a deployment was going to happen for some SPFx web parts.

My first thought was to loop through all of the sites and find out if the the SharePoint Framework app had been installed. This would work except in the case of a tenant wide deployment of the SharePoint Framework web parts. So instead of finding out where a web part has been installed, we need to find out where a web part was actually being used.

The Experiment

To me, this sounded like a great idea, unfortunately, I wasn’t aware of any APIs that were able to do this. Then I got to thinking, maybe we could use the search API to do this. In those post, I am going to try and see if we can use the Search API to find web part usage in SharePoint. Be aware this solution would only work for modern pages using your SPFx web part.

CanvasContent1

When adding web parts to a modern site page in Office 365, the HTML content is saved into a column called “CanvasContent1”. I quickly looked at the search schema to see if I would be able to search on this column.

canvascontent

Unfortunately, by default, the CanvasContent1 managed property called CanvasContent1OWSHTML didn’t have a crawled property mapped to it.  So I decided to map ows_CanvasContent1 to a new RefinableString.

untitled

Now, in order for the column to be searchable we have to wait for the column to re-crawl in our environment… this could take some time in SharePoint Online.

What to search for

The CanvasContent1 field contains a bunch of html data about the contents of the page. This includes web parts and their configuration including properties. Stored inside the CanvasContent1 field will also include the ID of the web parts configured on the page.With this in mind, I figured it would be fairly easy to find where a web part is being used in an environment by searching against this field.

Let’s say that I have a web part with the component id of 62799350-83b2-40a1-b35d-5417cc54daea as shown in this SPFx manifest file.

untitled

If I execute a search query against the RefinableString field where it contains this GUID, I should be fairly certain the page contains my web part.

Using the SharePoint Search  REST API, I can execute the following call to return the Title, Path and Site of the page that is rendering my web part.

Request

https://testsite.sharepoint.com/sites/test/_api/search/query?QueryText='RefinableString134:62799350-83b2-40a1-b35d-5417cc54daea*'&selectProperties='Title,Path,SPWebUrl'

Response

In the response, I have found 2 pages where my web part is being loaded.

<d:query xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" xmlns:georss="http://www.georss.org/georss" xmlns:gml="http://www.opengis.net/gml"m:type="Microsoft.Office.Server.Search.REST.SearchResult">
<d:ElapsedTime m:type="Edm.Int32">104</d:ElapsedTime>
<d:PrimaryQueryResult m:type="Microsoft.Office.Server.Search.REST.QueryResult">
<d:CustomResults m:type="Collection(Microsoft.Office.Server.Search.REST.CustomResult)"/>
<d:QueryId>37de1142-2baf-4ea6-ab0b-b646a0a57d31</d:QueryId>
<d:QueryRuleId m:type="Edm.Guid">00000000-0000-0000-0000-000000000000</d:QueryRuleId>
<d:RefinementResults m:null="true"/>
<d:RelevantResults m:type="Microsoft.Office.Server.Search.REST.RelevantResults">
<d:GroupTemplateId m:null="true"/>
<d:ItemTemplateId m:null="true"/>
<d:Properties m:type="Collection(SP.KeyValue)">
<d:element>
<d:Key>GenerationId</d:Key>
<d:Value>9223372036854775806</d:Value>
<d:ValueType>Edm.Int64</d:ValueType>
</d:element>
<d:element>
<d:Key>indexSystem</d:Key>
<d:Value/>
<d:ValueType>Edm.String</d:ValueType>
</d:element>
<d:element>
<d:Key>ExecutionTimeMs</d:Key>
<d:Value>47</d:Value>
<d:ValueType>Edm.Int32</d:ValueType>
</d:element>
<d:element>
<d:Key>QueryModification</d:Key>
<d:Value>
RefinableString134:62799350-83b2-40a1-b35d-5417cc54daea* -ContentClass=urn:content-class:SPSPeople
</d:Value>
<d:ValueType>Edm.String</d:ValueType>
</d:element>
<d:element>
<d:Key>RenderTemplateId</d:Key>
<d:Value>
~sitecollection/_catalogs/masterpage/Display Templates/Search/Group_Default.js
</d:Value>
<d:ValueType>Edm.String</d:ValueType>
</d:element>
<d:element>
<d:Key>StartRecord</d:Key>
<d:Value>0</d:Value>
<d:ValueType>Edm.Int32</d:ValueType>
</d:element>
<d:element>
<d:Key>IsLastBlockInSubstrate</d:Key>
<d:Value>true</d:Value>
<d:ValueType>Edm.Boolean</d:ValueType>
</d:element>
<d:element>
<d:Key>IsFirstBlockInSubstrate</d:Key>
<d:Value>false</d:Value>
<d:ValueType>Edm.Boolean</d:ValueType>
</d:element>
<d:element>
<d:Key>IsFirstPinnedResultBlock</d:Key>
<d:Value>false</d:Value>
<d:ValueType>Edm.Boolean</d:ValueType>
</d:element>
<d:element>
<d:Key>IsLastPinnedResultBlock</d:Key>
<d:Value>false</d:Value>
<d:ValueType>Edm.Boolean</d:ValueType>
</d:element>
<d:element>
<d:Key>IsFirstRankedResultBlock</d:Key>
<d:Value>true</d:Value>
<d:ValueType>Edm.Boolean</d:ValueType>
</d:element>
<d:element>
<d:Key>IsLastRankedResultBlock</d:Key>
<d:Value>true</d:Value>
<d:ValueType>Edm.Boolean</d:ValueType>
</d:element>
<d:element>
<d:Key>MixedTableOrder</d:Key>
<d:Value>0</d:Value>
<d:ValueType>Edm.Int32</d:ValueType>
</d:element>
</d:Properties>
<d:ResultTitle m:null="true"/>
<d:ResultTitleUrl m:null="true"/>
<d:RowCount m:type="Edm.Int32">2</d:RowCount>
<d:Table m:type="SP.SimpleDataTable">
<d:Rows>
<d:element m:type="SP.SimpleDataRow">
<d:Cells>
<d:element m:type="SP.KeyValue">
<d:Key>Rank</d:Key>
<d:Value>16.8176937103271</d:Value>
<d:ValueType>Edm.Double</d:ValueType>
</d:element>
<d:element m:type="SP.KeyValue">
<d:Key>DocId</d:Key>
<d:Value>17601926184608</d:Value>
<d:ValueType>Edm.Int64</d:ValueType>
</d:element>
<d:element m:type="SP.KeyValue">
<d:Key>Title</d:Key>
<d:Value>Home</d:Value>
<d:ValueType>Edm.String</d:ValueType>
</d:element>
<d:element m:type="SP.KeyValue">
<d:Key>Path</d:Key>
<d:Value>
https://testsite.sharepoint.com/sites/test/SitePages/AlertnativeHome.aspx
</d:Value>
<d:ValueType>Edm.String</d:ValueType>
</d:element>
<d:element m:type="SP.KeyValue">
<d:Key>SPWebUrl</d:Key>
<d:Value>
https://testsite.sharepoint.com/sites/test
</d:Value>
<d:ValueType>Edm.String</d:ValueType>
</d:element>
<d:element m:type="SP.KeyValue">
<d:Key>OriginalPath</d:Key>
<d:Value>
https://testsite.sharepoint.com/sites/test/SitePages/AlertnativeHome.aspx
</d:Value>
<d:ValueType>Edm.String</d:ValueType>
</d:element>
<d:element m:type="SP.KeyValue">
<d:Key>PartitionId</d:Key>
<d:Value>ca45b536-df01-44b6-afa0-d3f8e7ebb312</d:Value>
<d:ValueType>Edm.Guid</d:ValueType>
</d:element>
<d:element m:type="SP.KeyValue">
<d:Key>UrlZone</d:Key>
<d:Value>0</d:Value>
<d:ValueType>Edm.Int32</d:ValueType>
</d:element>
<d:element m:type="SP.KeyValue">
<d:Key>Culture</d:Key>
<d:Value>en-US</d:Value>
<d:ValueType>Edm.String</d:ValueType>
</d:element>
<d:element m:type="SP.KeyValue">
<d:Key>ResultTypeId</d:Key>
<d:Value>0</d:Value>
<d:ValueType>Edm.Int32</d:ValueType>
</d:element>
<d:element m:type="SP.KeyValue">
<d:Key>RenderTemplateId</d:Key>
<d:Value>
~sitecollection/_catalogs/masterpage/Display Templates/Search/Item_Default.js
</d:Value>
<d:ValueType>Edm.String</d:ValueType>
</d:element>
</d:Cells>
</d:element>
<d:element m:type="SP.SimpleDataRow">
<d:Cells>
<d:element m:type="SP.KeyValue">
<d:Key>Rank</d:Key>
<d:Value>16.8176937103271</d:Value>
<d:ValueType>Edm.Double</d:ValueType>
</d:element>
<d:element m:type="SP.KeyValue">
<d:Key>DocId</d:Key>
<d:Value>17601957874490</d:Value>
<d:ValueType>Edm.Int64</d:ValueType>
</d:element>
<d:element m:type="SP.KeyValue">
<d:Key>Title</d:Key>
<d:Value>Home</d:Value>
<d:ValueType>Edm.String</d:ValueType>
</d:element>
<d:element m:type="SP.KeyValue">
<d:Key>Path</d:Key>
<d:Value>
https://testsite.sharepoint.com/sites/test/SitePages/AlternativeHome2.aspx
</d:Value>
<d:ValueType>Edm.String</d:ValueType>
</d:element>
<d:element m:type="SP.KeyValue">
<d:Key>SPWebUrl</d:Key>
<d:Value>
https://testsite.sharepoint.com/sites/test
</d:Value>
<d:ValueType>Edm.String</d:ValueType>
</d:element>
<d:element m:type="SP.KeyValue">
<d:Key>OriginalPath</d:Key>
<d:Value>
https://testsite.sharepoint.com/sites/test/SitePages/AlternativeHome2.aspx
</d:Value>
<d:ValueType>Edm.String</d:ValueType>
</d:element>
<d:element m:type="SP.KeyValue">
<d:Key>PartitionId</d:Key>
<d:Value>ca45b536-df01-44b6-afa0-d3f8e7ebb312</d:Value>
<d:ValueType>Edm.Guid</d:ValueType>
</d:element>
<d:element m:type="SP.KeyValue">
<d:Key>UrlZone</d:Key>
<d:Value>0</d:Value>
<d:ValueType>Edm.Int32</d:ValueType>
</d:element>
<d:element m:type="SP.KeyValue">
<d:Key>Culture</d:Key>
<d:Value>en-US</d:Value>
<d:ValueType>Edm.String</d:ValueType>
</d:element>
<d:element m:type="SP.KeyValue">
<d:Key>ResultTypeId</d:Key>
<d:Value>0</d:Value>
<d:ValueType>Edm.Int32</d:ValueType>
</d:element>
<d:element m:type="SP.KeyValue">
<d:Key>RenderTemplateId</d:Key>
<d:Value>
~sitecollection/_catalogs/masterpage/Display Templates/Search/Item_Default.js
</d:Value>
<d:ValueType>Edm.String</d:ValueType>
</d:element>
</d:Cells>
</d:element>
</d:Rows>
</d:Table>
<d:TotalRows m:type="Edm.Int32">2</d:TotalRows>
<d:TotalRowsIncludingDuplicates m:type="Edm.Int32">2</d:TotalRowsIncludingDuplicates>
</d:RelevantResults>
<d:SpecialTermResults m:null="true"/>
</d:PrimaryQueryResult>
<d:Properties m:type="Collection(SP.KeyValue)">
<d:element>
<d:Key>RowLimit</d:Key>
<d:Value>500</d:Value>
<d:ValueType>Edm.Int32</d:ValueType>
</d:element>
<d:element>
<d:Key>SourceId</d:Key>
<d:Value>8413cd39-2156-4e00-b54d-11efd9abdb89</d:Value>
<d:ValueType>Edm.Guid</d:ValueType>
</d:element>
<d:element>
<d:Key>CorrelationId</d:Key>
<d:Value>02b6b69e-10c1-7000-727b-bc8a6f5546b9</d:Value>
<d:ValueType>Edm.Guid</d:ValueType>
</d:element>
<d:element>
<d:Key>WasGroupRestricted</d:Key>
<d:Value>false</d:Value>
<d:ValueType>Edm.Boolean</d:ValueType>
</d:element>
<d:element>
<d:Key>IsPartial</d:Key>
<d:Value>false</d:Value>
<d:ValueType>Edm.Boolean</d:ValueType>
</d:element>
<d:element>
<d:Key>HasParseException</d:Key>
<d:Value>false</d:Value>
<d:ValueType>Edm.Boolean</d:ValueType>
</d:element>
<d:element>
<d:Key>WordBreakerLanguage</d:Key>
<d:Value>en</d:Value>
<d:ValueType>Edm.String</d:ValueType>
</d:element>
<d:element>
<d:Key>IsPartialUpnDocIdMapping</d:Key>
<d:Value>false</d:Value>
<d:ValueType>Edm.Boolean</d:ValueType>
</d:element>
<d:element>
<d:Key>EnableInterleaving</d:Key>
<d:Value>true</d:Value>
<d:ValueType>Edm.Boolean</d:ValueType>
</d:element>
<d:element>
<d:Key>IsMissingUnifiedGroups</d:Key>
<d:Value>false</d:Value>
<d:ValueType>Edm.Boolean</d:ValueType>
</d:element>
<d:element>
<d:Key>Constellation</d:Key>
<d:Value>iC6B8D</d:Value>
<d:ValueType>Edm.String</d:ValueType>
</d:element>
<d:element>
<d:Key>SerializedQuery</d:Key>
<d:Value>
<Query Culture="en-US" EnableStemming="True" EnablePhonetic="False" EnableNicknames="False" IgnoreAllNoiseQuery="True" SummaryLength="180" MaxSnippetLength="180" DesiredSnippetLength="90" KeywordInclusion="0" QueryText="RefinableString134:62799350-83b2-40a1-b35d-5417cc54daea*" QueryTemplate="" TrimDuplicates="True" Site="532bd9a4-869f-45e2-b5f0-323f6604a429" Web="c67564a0-242f-40bf-b4ac-a0ea8dbc935e" KeywordType="True" HiddenConstraints="" />
</d:Value>
<d:ValueType>Edm.String</d:ValueType>
</d:element>
</d:Properties>
<d:SecondaryQueryResults m:type="Collection(Microsoft.Office.Server.Search.REST.QueryResult)"/>
<d:SpellingSuggestion/>
<d:TriggeredRules m:type="Collection(Edm.Guid)"/>
</d:query>

In my result set, I have found two pages in the same site that was using this specific web part. With a larger result set that comes back, I could loop through the records and figure out which sites are running my web part, and send an email accordingly to each site owner about the upcoming web part deployment!

Final Thoughts

This was a fun experiment to test out and I am going to continue to do some more exploration to see if there are other methods possible for finding out this information. I haven’t been able to do thorough testing, but I would love to hear if this works for you and/or if you have another approach!

Caveats/Feedback

  1. This would only work for web parts placed on modern pages
  2. If site owners have disabled content from being searchable, it will not show up. (Thanks Paul Bullock!)
  3. There are much better approaches to monitoring this type of information. As Sam Crewdson noted on twitter  the use of Application Insights is a robust way to track and monitor solutions in your environment. Here is a blog post by Chris O’Brien showing how to use application insights with SPFx.

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

Beau Cameron2 Comments

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!

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

Beau Cameron4 Comments

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: PnP Starter-Kit for Office 365 Part 2 – Tiles

Beau Cameron2 Comments

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

Beau Cameron25 Comments

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!

Edit HTML files in SharePoint Library

Beau CameronLeave a comment

In Modern Office 365, one of the neat new features is the ability to edit HTML files by opening up a file from a Modern library. The HTML contents would load in the browser and were able to edit the HTML without having to download the file or edit the file using SharePoint Designer — this was a very powerful capability for many people.

Well, recently Microsoft has removed this capability (not sure why) as noted by Mark Rackley. Please vote in the UserVoice!

 What to do?

This wasn’t the first occurrence of this issue. I have found others posted about this topic on other social forums such as Reddit and Facebook. Because of this, I have decided to just build a simple little CommandSet button that will run on SharePoint libraries, which bypasses the new Microsoft changes and allows you to edit an HTML file in the browser. In order to do this, all we need to do is append &p=5 into the browser URL.

The Solution

The solution was quite simple. Build a SPFx CommandSet button, which allows the user to select an HTML file and then navigate to the view page with &p=5 appended to it.

 

COmmandSet

The code is quite simple. When a user selects a file with a file type of “html”, show the command button. When the button is clicked, grab the FileName, file path and folder path. Construct a new URL, and append &p=5.

What it looks like

Select an HTML file, the CommandSet button shows up

Library

 

Click “Edit HTML”, the page will redirect to the modern list view display form, with &p=5 to load the default edit view of the file.

TestFile

Try it out

If you’d like to try it out, please do. I have uploaded the source and the sppkg file to my GitHub Repository.  The sppkg file will be in the sppkg folder. Upload this to your app catalog. Subsequently, you can deploy the app via Site Contents or using PowerShell.  Below is a sample PowerShell command for you. (This is old code, there are other ways to provision this)

 Connect-PnPOnline -Url https://test.sharepoint.com/sites/MySite
 
 $context = Get-PnPContext
 $web = Get-PnPWeb
 $context.Load($web)
 Execute-PnPQuery
 
 $ca = $web.UserCustomActions.Add()
 $ca.RegistrationType = "List"
 $ca.RegistrationId = "101"
 $ca.ClientSideComponentId = "6599b3cc-7631-4a55-962e-43d1757977ec"
 $ca.ClientSideComponentProperties = "{""sampleTextOne"":""Edit HTML""}" 
 $ca.Location = "ClientSideExtension.ListViewCommandSet.CommandBar"
 
 $ca.Name = "EditHTML CommandButton"
 $ca.Title = "EditHTML CommandButton"
 $ca.Description = "EditHTML CommandButton"
 
 $ca.Update()
 
 $context.Load($web.UserCustomActions)
 Execute-PnPQuery

 

PnP-Starter-Kit for Standard Release Tenants

Beau Cameron1 Comment

I am going to preface this blog post with — if you have an issue with the solution setup I have below, please do not add issues to the PnP-Starter-Kit issues list. This solution below, is a replication of the pnp-starter-kit and not managed by the PnP Team.

I’d also like to say, that you don’t need this post. The PnP-Starter-Kit should be deployed into First-Release tenants. I’ve had reservations on whether or not to post this.

What is it?

The PnP-Starter-Kit is an open sourced initiative that was released by the PnP-Team to show all of the capabilities that currently exist around provisioning in Office 365 using the SharePoint Framework and PnP Provisioning. For more information on the project, the GitHub repository can be found here.

One of the requirements of the PnP-Starter-Kit, is that it requires your tenant to be configured for “First Release for everyone”. This is because some of the web parts utilize the new AadHttpClient and MsGraphClient. These are currently in preview, but require permissions to be requested and approved under “API Management” in the admin center.

What’s in this my solution?

This solution is essentially an exact replica of the PnP repository, except that I have removed all of the web parts that require First Release and I have modified the deploy scripts and PnP Provisioning XML files to also support standard release tenants. What this means is that you will not have the LOB application or any of the web parts that generally show up on the personal page (except the people directory).

Why do this?

You may be wondering why I would do this. Since all of this is brand new and uses experimental features, it should only be deployed into a test/demo tenant, where turning on First Release shouldn’t be a problem. However, through some of the issues lists and comments I’ve seen on social media, it appears many people want to deploy the web parts into standard release tenants to test out the web parts, so I figured “why not?”.

You can get a demo tenant for free and set that tenant to first-release. However, if you really feel you want to deploy this into Standard Release… here you go.

How to deploy

The deployment of this is exactly the same as the full PnP Starter Kit, except you don’t have to configure any of the API management stuff.

GitHub Repository Here

  1. Make sure you’ve updated your PowerShell module to the latest version.
  2. Make sure your development environment is configured correctly here.
  3. Make sure your tenant is configured following this page for the User Profile property for the Portal Footer.
  4. Make sure your tenant has an app catalog
    1. Wait 24 hours after creating one
  5. Make sure your account is a Term Store Administrator

To deploy the starter kit, you’ll need to upload the sharepoint-portal-showcase.sppkg from the /package folder to your app catalog.  This will provision the web parts to all of your site collections for use. If you’d like to also include the 3 demo sites, and pre-built pages included in the full starter kit, then open up Powershell and navigate to the provisioning folder. Once inside the folder, execute the following command to start the provisioning process.

.\deploy.ps1 -TenantUrl https://YourTenant.sharepoint.com -SitePrefix Demo

 

Questions?

If you have any questions, just ask me. Please note, that I will not really be maintaining this repository, so it will not be receiving any of the new bug fixes and updates from the PnP Team.

Please do not add issues about this package to the PnP-Starter-Kit GitHub repository issues list.