Mapping SharePoint hub sites
This article helps you map out your hub site structure using PowerShell and draw.io.
There is a lot of excitement about the upcoming SharePoint Online hub sites and they are now available to tenants who have signed up for Targeted Release and will be generally available in May. Hub sites simplify the management of multiple sites by having a central hub from which sites can inherit common attributes such as navigation, search and content aggregation. In this blog article I am going to examine some of the technical underpinnings of how sites are associated with hubs and how as an administrator this information can be queried in order to gain some insight into how they are used in a tenant.
Currently, there is nothing much in the way of support to visualise how the sites are structured and to see what sites use which hub site. Wouldn’t it be great to have a simple way to see how they all link together?
New Updates in PowerShell
PowerShell has been gifted with several new commands that greatly help inspect and manipulate this new hub site feature. There are also some new properties added to sites; the most notable being:
- IsHubSite – Boolean
- This should be self-explanatory.
- HubSiteId – Guid
- HubSiteId contains the Id of the hub site that the site inherits from and if the site is not connected to a hubsite then the Id is 00000000-0000-0000-0000-000000000000.
- Where the site is a hub site, the HubSiteId will contain the Id of itself.
Get a hub site example
The following command will return these properties from a known hub site (“marketinghub1”)
Get-SPOSite -Identity https://m365...nt.com/sites/marketinghub1 | Select Title, Url, IsHubSite, HubSiteId
|Contoso Marketing Hub-1||https://m365…nt.com/sites/marketinghub1||True||db1589e3-f759-41e6-8e53-9f74c524b9c1|
Get an inheriting site example
This command shows the same properties for a site that is known to be associated with the previous hub site.
Get-SPOSite -Identity https://m365...nt.com/sites/inherit1 | Select Title, Url, IsHubSite, HubSiteId
So, I set about creating a script that would map out the structure of the hub sites in an entire farm.
Naturally the script starts by asking the user to sign into the farm’s admin site (note: this is important because you have to be a tenant admin to manage and query hub sites). The next step is to fetch all the hub sites. “Easy” I thought; just get all the sites where IsHubSite is true. Unfortunately, there is either a bug or a feature built into this current release that prevents these new properties being populated when queried!
To demonstrate this, I get the same site details as above but retrieve all sites in the tenant at the same time:
Get-SPOSite -Limit All | Select Title, Url, IsHubSite, HubSiteId
|Contoso Marketing Hub-2||https://m365…nt.com/sites/marketinghub2||False||00000000-0000-0000-0000-000000000000|
|Contoso Marketing Hub-1||https://m365…nt.com/sites/marketinghub1||False||00000000-0000-0000-0000-000000000000|
As you can see, both hub site related properties are un-populated in the results when we know them to have values.
So, the workaround is to use a loop to get each site in the tenancy and then get the individual site again by itself with all hub site properties present. I store the details in one of two arrays; one for hub sites and one for inheriting sites. I then do a second pass over the data in the arrays to create the mapping.
To add a bit of sparkle, I made the PowerShell script produce XML that could be imported into Google’s draw.io and here is an example of what it produced:
In practice, creating a diagram isn’t particularly useful given that, currently, the structure will always be one hub site with one level of associated sites. Perhaps a more useful purpose would be to build a global navigation component using a SharePoint Framework extension. If hub sites are used to identify related content as well as the look and feel, then it could be used to build navigation links at the top of every site. Given that the script runs with admin level permissions, one would need to consider permissions to avoid links appearing in menus where users do not have access to the underlying site.
Equally, it could be possible to flag certain hub sites using a custom attribute to identify sites that should be shown in the global navigation.
For the time being, I think this is a convenient way for tenant admins to run a quick script and generate this overview. I’ve posted the script on Github in case anyone would like to take a look for themselves. Feedback welcome!
Running the PowerShell on a small tenancy took about 10 seconds, therefore it would not be practical to have this run every time a page opens. Given that site structure changes do not happen often, it’s reasonable that the data could be cached and updated periodically. An Azure Timer Function would be perfect for the job, but consideration should be given to the fact it will need administrator access to the tenancy.
Based on feedback from other members of the team here, hub sites look like a promising and very popular addition to SharePoint Online. From an administrators point of view there is little current support for identifying hub sites and their subscribing sites. I have heard rumours that Microsoft are looking to add this capability to the new SharePoint Online Admin Center that is currently in Preview but nothing has been confirmed as yet. For now though, PowerShell is the only tool in the toolbox.