Using SharePoint Online Tenant Properties In SharePoint Framework Components

SharePoint Online Tenant Properties acts as a global property bag store for the tenant and all the SPFx components can read these property values through REST calls. This helps to store common tenant wide information which needs to be shown across all the SharePoint Online site collections.

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
  1. 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
  1. Get-SPOStorageEntity -Site "https://tenant-name.sharepoint.com/sites/app-catalog" -Key "StockPrice"  
  2.   
  3. // OUTPUT OF THE CMDLET 
  4. Comment            : Added on 25-Sep-2019:12:00:00 by PnP Job  
  5. Description        : JSON data for storing the Stock Quote Info  
  6. Value              : {"ltp":542,"ltd":"25-Sep-2019"}  
  7. Context            : Microsoft.Online.SharePoint.PowerShell.CmdLetContext  
  8. Tag                :  
  9. Path               : Microsoft.SharePoint.Client.ObjectPathMethod  
  10. ObjectVersion      :  
  11. ServerObjectIsNull : False  
  12. 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
  1. Set-PnPStorageEntity -Key "CompanySupportEmail" -Value "support@contoso.com" 
Get all Tenant Property values
  1. Get-PnPStorageEntity | fl  
  2.   
  3. // OUTPUT OF THE CMDLET  
  4. Key         : StockPrice  
  5. Value       : {"ltp":542,"ltd":"25-Sep-2019"}  
  6. Comment     : Added on 25-Sep-2019:12:00:00 by PnP Job  
  7. Description : JSON data for storing the Stock Quote Info  
  8.   
  9. Key         : CompanySupportEmail  
  10. Value       : support@contoso.com  
  11. Comment     :  
  12. Description : 
Remove a Tenant Property
  1. 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.
  1. 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,
  1. sp.web.getStorageEntity("StockPrice").then(res => {  
  2.     
  3.   var stockData = JSON.parse(res.Value)  
  4.   // stockData.ltp : Has the last traded price of the stock  
  5.   // stockData.ltd : Is the last traded/updated date for this stock quote  
  6.   
  7. }); 
 

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.