Using SharePoint Online Tenant Properties In SharePoint Framework Components

What are SharePoint Online Tenant Properties?

A SharePoint Online Tenant Property (StorageEntity) can be seen as a global property bag for the SharePoint tenant, where tenant administrators can manage the key-value pairs. This can be used for storing common information or settings which are common for all the site collections. The value of a SharePoint Online Property can be read by any SPFx component using a REST API. This could be helpful for showing the data which is not updated often. For example, the stock price of a company could be updated on a daily basis to the SharePoint Online tenant property, and an SPFx web part could read the stock value from the Storage Entity to show it in any SharePoint Online Site Collection or Microsoft Teams.

How to manage the Tenant Property?

Tenant properties are stored in the tenant app catalog or in the site's app catalog. A tenant administrator can use SharePoint Online Management Shell , Office CLI, or PnP PowerShell to Add/Update/Remove a tenant property.

Using SharePoint Online Management Shell

Adding/Updating a tenant property

Set-SPOStorageEntity -Site [URL OF THE APP CATALOG] -Key [KEY NAME FOR THE PROPERTY] -Description [TEXT] -Comments [TEXT]

Example

Set-SPOStorageEntity -Site "https://tenant-name.sharepoint.com/sites/app-catalog" -Key "StockPrice" -Value '{"ltp":542,"ltd":"25-Sep-2019"}' -Description "Companys stock quote JSON data" -Comments "Added on 25-Sep-2019:12:00:00 by Ram"

This command updates the SharePOint Online tenant property if it's already present, else a new property is created at the given scope.

Getting a tenant property's value

Get-SPOStorageEntity -Site [URL OF THE APP CATALOG] -Key [KEY NAME FOR THE PROPERTY]

Example

Get-SPOStorageEntity -Site "https://tenant-name.sharepoint.com/sites/app-catalog" -Key "StockPrice"
// OUTPUT OF THE CMDLET
Comment : Added on 25-Sep-2019:12:00:00 by PnP Job
Description : JSON data for storing the Stock Quote Info
Value : {"ltp":542,"ltd":"25-Sep-2019"}
Context : Microsoft.Online.SharePoint.PowerShell.CmdLetContext
Tag :
Path : Microsoft.SharePoint.Client.ObjectPathMethod
ObjectVersion :
ServerObjectIsNull : False
TypedObject : Microsoft.SharePoint.ClientSideComponent.StorageEntity

Remove a tenant property

Remove-SPOStorageEntity -Site [URL OF THE APP CATALOG] -Key [KEY NAME FOR THE PROPERTY]

Using PnP PowerShell

We can also use PnP PowerShell cmdlets if we connect using an administrator account with the Connect-PnPOnline cmdlet. The cmdlet syntax is simple and easy to use compared the SharePoint Online Management Shell. Also PnP Powershell can show all the tenant properties available, while in the SharePoint Online Management Shell we have to explicitly specify the key name of a property to get its value

Set a Teanant Property value

Set-PnPStorageEntity -Key "CompanySupportEmail" -Value "[email protected]"

Get all Tenant Property values

Get-PnPStorageEntity | fl
// OUTPUT OF THE CMDLET
Key : StockPrice
Value : {"ltp":542,"ltd":"25-Sep-2019"}
Comment : Added on 25-Sep-2019:12:00:00 by PnP Job
Description : JSON data for storing the Stock Quote Info
Key : CompanySupportEmail
Value : [email protected]
Comment :
Description :

Remove a Tenant Property

Remove-PnPStorageEntity -Key "CompanySupportEmail"

Using the Tenant Property's Value in SPFx Components

The tenant property values can be read from any custom component using the following REST call.

GET _api/web/GetStorageEntity('StockPrice')

Or we can also use PnP Js to read the property value. Below is the example code that can be used within an SPFx component (webpart or extension) to read the property value,

sp.web.getStorageEntity("StockPrice").then(res => {
var stockData = JSON.parse(res.Value)
// stockData.ltp : Has the last traded price of the stock
// stockData.ltd : Is the last traded/updated date for this stock quote
});

Conclusion

By using the tenant properties, common and global configurations/information can be stored easily by tenant administrators and developers can use the value in their SPFx solutions easily. This could help in effectively managing the configurations, like storing the analytics key in the tenant property, an administrator can easily change it later which gets effected in all SharePoint Site Collections (through an extension). Or stock price information can be stored in a property bag and an SPFx web part can show this price information in multiple site collections, allowing a company to reduce the external API calls to get the stock price.