Associate a SharePoint Online site to a HubSite

The association can be done by an Owner of the site to associate, by a SharePoint Online administrator, or automatically using site design. We will first cover how to associate a SharePoint Online site to a HubSite from a site owner perspective.

From a site owner perspective

To associate a SharePoint Online site to a HubSite, the site Owner needs to have access to the HubSite and to be allowed to associate sites to the HubSite. if you need more information on this, you can refer to Register a SharePoint Online site as a HubSite where we cover the site association filtering.

Fist the site owner will go to the site information of the site to associate :

Then will be able to see the HubSites the organization is allowing him to associate site to in the HubSite association section :

The process is pretty easy, the site Owner can still remove the HubSite association in the same menu by choosing “None”. In this scenario we can argue on the flexibility for the site Owners to relate sites to each other while the IT department can maintain those environments by managing the HubSite.

From a SharePoint Online administrator perspective

As a SharePoint Online administrator, you can associate a site to a HubSite in the SharePoint Online admin center under active sites :

You will be prompted for a HubSite to associate this site with :

Here are the related cmdLet for PowerShell using the Microsoft.Online.SharePoint.PowerShell Module

#Connecting to SharePoint
Connect-SPOService -Url "https://btcstech-admin.sharepoint.com"
#Associating a site to a HubSite
Add-SPOHubSiteAssociation "https://btcstech.sharepoint.com/sites/GRP-TeamSite" -HubSite "https://btcstech.sharepoint.com/sites/NewHubsite"

Note that you can associate a sub-site using this cmdLet, then the whole site Collection will be associated to the HubSite (Top-level site and every sub-site)

Automate the HubSite association with Site Design

Site Design is a very powerful feature for the organization to automate actions when SharePoint Online sites are created. Long story short, it allow organizations to define Site Design under Team and Communication sites and automate actions when the site is created. So the user will chose a Site Design when creating a site, and the Site Scripts associated to the selected Site Design will automate action like adding content to the site, triggering a flow or, in our case, join the site to a HubSite.
Let’s take an example where we define a Site design for Team sites associating the new site to a HubSite.

We will use PowerShell with the Microsoft.Online.SharePoint.PowerShell module to perform the configuration. First we need to retrieve the GUID of the HubSite :

#Connecting to SharePoint
Connect-SPOService -Url "https://btcstech-admin.sharepoint.com"
#Retrieve the HubSite, then the GUID
$hubSite = Get-SPOHubsite https://btcstech.sharepoint.com/sites/NewHubsite
$hubSite.Id

We will then define the Site Script to perform the HubSite association, you will change the GUID with yours. And save this Json code to a file, in my case in “C:\scripts\joinHubSiteScript.json”

{
 "$schema": "schema.json",
 "actions": [
 {
 "verb": "joinHubSite",
 "hubSiteId": "339f4869-d7a5-4e3b-99ac-93f912a75798"
 }
 ],
 "bindata": { },
 "version": 1
}

We will then push the Site Script to SharePoint Online and define a Site Design that use this Site Script for the Team site creation :

#Retrieve the Site Script content
$siteScriptContent = Get-Content 'C:\scripts\joinHubSiteScript.json'-Raw
#Create the Site Script in SharePoint Online
$siteScript = Add-SPOSiteScript -Title "JoinHubSite" -Content $siteScriptContent

#Define a preview image Url for the site design
$previewUrl = "https://btcstech.sharepoint.com/sites/NewHubsite/Shared%20Documents/hubSite preview.png"
#Define the Site Design 
Add-SPOSiteDesign -Title "HubSite association Site Design" -WebTemplate "64" -SiteScripts $siteScript.Id -Description "Creates a site joined to the HubSite"-PreviewImageUrl $previewUrl -PreviewImageAltText "site preview"

Here we choose the -WebTemplate parameter with the “64” value for the Site Design to be applied to the Team site creation. You can use the value “68” for your Site Design to be applied to the Communication site creation.

After deploying our Site Design, it is now available in the Team site creation UI :

We the site is created, we are redirected to the site. A little banner appear on the top telling us a Site Design is being applied, we can click on the link to see the actions performed by the Site Design :

Once done, we can refresh and voila : The Site Script executed the operation. Our site is automatically associated to a HubSite when created 🙂

If you need further information on Site Script and Site Design I recomend you to read the related Microsoft documentation.
You can also read the HubSite overview and how to register a HubSite article in this blog.