Tijdens een recent project ontdekte ik hoe cruciaal de juiste volgorde is bij het opbouwen van een SharePoint site script. Het doel leek eenvoudig: bij het provisioneren van nieuwe projectomgevingen moest er een managed metadata kolom beschikbaar zijn binnen een content type, en dat content type moest vervolgens worden toegepast in de bibliotheken van de site. Klinkt logisch, toch? In de praktijk bleek het lastiger dan gedacht.
Waar liep ik tegenaan?
Bij de eerste versie van het site script werkte de kolom niet zoals verwacht. De bibliotheken werden wel aangemaakt, maar de content types waren incompleet: de managed metadata kolom verscheen niet of functioneerde niet correct. Het probleem zat in de volgorde waarin de onderdelen in de JSON waren gedefinieerd.
De sleutel: volgorde in je JSON
Na veel testen ontdekte ik dat SharePoint streng is in de volgorde waarin je onderdelen definieert. Dit bleek het werkende recept te zijn:
- Eerst definieer je de managed metadata kolom (Type:
TaxonomyFieldType) - Daarna maak je het content type aan en voeg je deze kolom toe
- Tot slot creëer je de bibliotheken waarin het content type wordt gebruikt
Pas toen ik deze volgorde hanteerde, werkte alles zoals bedoeld.
Waarom zou je dit gebruiken?
Het gebruik van site scripts (die je verwerkt in een site template) voor het provisioneren van je sites zorgt voor consistentie en automatisering. Nieuwe projectomgevingen zijn direct klaar voor gebruik, zonder handmatige aanpassingen.
Wat als je dit niet doet?
Zonder deze aanpak is het risico groot dat je bibliotheken of content types onvolledig zijn. Het kost dan extra tijd om achteraf te corrigeren, en je verliest het voordeel van een gestroomlijnde provisioning.
Praktijkvoorbeeld: van mappen naar metadata
De bouwonderneming waarvoor ik dit heb toegepast, werkte op de fileserver met een uitgebreide mappenstructuur. Voor de migratie naar SharePoint hebben we gekozen voor een andere aanpak:
- De hoofdmappen van elk project zijn omgezet naar afzonderlijke documentbibliotheken
- De onderliggende mappen hebben we laten vervallen. In plaats daarvan is er een managed metadata kolom toegevoegd waarin we de documentcategorie vastleggen
| Bibliotheek | Documentcategorie |
|---|---|
| Contracten | Verkoopovereenkomst |
| Aannemingsovereenkomst | |
| Vergunning | |
| Projectgegevens | Voortraject |
| Werkdocumenten | |
| Oplevering | |
| Verslagen | Overdracht |
| Ontwerp | |
| Bouwvergadering | |
| Werkvergadering | |
| Projectteamoverleg | |
| Overheid | |
| Nuts | |
| Brandweer |
Deze kolom correspondeert met de oude submappen en zorgt voor een consistente labeling van documenten. Dit komt de werkbaarheid en structuur ten goede. Door slim gebruik te maken van views kunnen we de oude mappenstructuur visueel terugbrengen, maar hebben we ook de flexibiliteit om documenten op andere manieren te filteren en sorteren.
Oplossing: Site Template
Om nieuwe projectsites uit te rollen maken we een site template aan (voorheen: Site Design). Dit template kunnen we toepassen op alle nieuwe projectsites. Dat kunnen we handmatig doen, via een Power Automate flow, of we laten het site template automatisch toepassen wanneer we de nieuwe projectsite koppelen aan de Projecten Hub site.
Site Template Aanmaken
Om een site template te maken moet je eerst een site script creëren. Met het site script maak je vervolgens een site template aan.
$sitescript = Get-Content "ProjectSjabloonSiteScript.json" -Raw
Add-PnPSiteScript -Title "Project Site Script" -Description "Site script voor project sites" -Content $sitescriptDit geeft als resultaat een GUID (SiteScriptId) van het nieuwe site script die je gebruikt in het volgende commando:
Add-PnPSiteDesign -Title "Project Site Template" -SiteScriptIds "e84dcb46-3ab9-4456-a136-66fc6ae3d3c5" -Description "Template voor nieuwe projectsites" -WebTemplate "64" -ThumbnailUrl "https://contoso.sharepoint.com/sites/templates/siteassets/logo.png"Tip: WebTemplate “64” is een team site zonder Microsoft 365 groep en “STS#3” is een team site mét Microsoft 365 groep.
Het nieuwe site template is nu toegevoegd aan SharePoint en kun je selecteren via het SharePoint instellingen menu.
Site Script: Anatomie is belangrijk
Zoals ik al zei heb ik gemerkt dat de opbouw (anatomie) van het site script cruciaal is. Als de volgorde verkeerd is, zullen bepaalde verbs niet kunnen worden uitgevoerd. Let op: Bij het aanmaken of updaten van het site template krijg je daar geen melding van!
Site Script Voorbeeld
{
"$schema": "schema.json",
"actions": [
{
"verb": "createSiteColumnXml",
"schemaXml": "<Field Type='TaxonomyFieldType' DisplayName='Documentcategorie' ShowField='Term1033' ID='979464ad-5fc4-4c37-8525-5a65d6aaf7fe' StaticName='Documentcategorie' Name='Documentcategorie' Group='Custom Columns' EnforceUniqueValues='FALSE' Required='FALSE'><Customization><ArrayOfProperty><Property><Name>SspId</Name><Value>01708df8-aba7-4910-84c4-f9cbde2dc9c6</Value></Property><Property><Name>TermSetId</Name><Value>7035798c-752a-4d56-9afe-8f7c06efaa91</Value></Property></ArrayOfProperty></Customization></Field>",
"pushChanges": true
},
{
"verb": "createContentType",
"name": "Projectdocument",
"id": "0x010100CED07B7596A51C40B1B6F8DBDB8874DD",
"parentId": "0x0101",
"group": "Custom Content Types",
"subactions": [
{ "verb": "addSiteColumn", "internalName": "Documentcategorie" },
{ "verb": "addSiteColumn", "internalName": "Projectnummer" }
]
},
{
"verb": "setRegionalSettings",
"locale": 1043,
"sortOrder": 25,
"hourFormat": "24"
},
{ "verb": "joinHubSite", "hubSiteId": "d0117e91-1048-4d18-8235-83998a4eab64" },
{ "verb": "setSiteExternalSharingCapability", "capability": "Disabled" },
// Bibliotheken aanmaken
{
"verb": "createSPList",
"listName": "01 Contracten",
"templateType": 101,
"allowContentTypes": true,
"subactions": [
{ "verb": "addContentType", "name": "Projectdocument" },
{ "verb": "removeContentType", "name": "Document" },
{ "verb": "addSPField", "fieldType": "Text", "displayName": "Projectnummer", "isRequired": false },
{
"verb": "addSPView",
"name": "Per Documentcategorie",
"query": "<GroupBy Collapse='TRUE'><FieldRef Name='Documentcategorie' /></GroupBy>",
"rowLimit": 30,
"isPaged": true,
"viewFields": ["Documentcategorie", "DocIcon", "LinkFilename", "_UIVersionString", "Modified", "Editor"]
}
]
},
{
"verb": "createSPList",
"listName": "02 Projectgegevens",
"templateType": 101,
"allowContentTypes": true,
"subactions": [
{ "verb": "addContentType", "name": "Projectdocument" },
{ "verb": "removeContentType", "name": "Document" },
{ "verb": "addSPField", "fieldType": "Text", "displayName": "Projectnummer", "isRequired": false }
]
},
// Navigatie opschonen
{
"verb": "removeNavLink", "displayName": "Pagina's", "isWebRelative": true
},
{
"verb": "removeNavLink", "displayName": "Site contents", "isWebRelative": true
}
],
"version": 1
}Belangrijke Parameters
createSiteColumnXml
Vervang de volgende velden met je eigen waarden:
| Eigenschap | Uitleg |
|---|---|
| DisplayName | Naam van de kolom |
| ID | Een unieke GUID. Genereer deze in PowerShell met [guid]::NewGuid() |
| StaticName | Internal name |
| Name | Naam van de kolom |
| Group | In welke groep wordt de kolom opgeslagen (bv. Custom Columns) |
| EnforceUniqueValues | TRUE of FALSE |
| Required | TRUE of FALSE |
| SspId | Term group ID (te vinden in de SharePoint admin portal onder Content services / Term Store) |
| TermSetId | TermSet ID (te vinden in de SharePoint admin portal onder Content services / Term Store) |
createContentType
| Eigenschap | Uitleg |
|---|---|
| Id | ID van het content type (te vinden in de SharePoint admin portal onder Content services / Content type gallery) |
| ParentId | ID van het bovenliggende content type. Dit is meestal het Document content type. ID: 0x0101 |
| Group | In welke groep slaan we het nieuwe content type op |
Belangrijk: Vergeet niet om in de subactions de nieuwe site kolom toe te voegen.
Resultaat
Na het toepassen van het site template zie je het volgende resultaat:
Adoptie: De sleutel tot succes
Deze manier van categoriseren van documenten is anders dan de meesten gewend zijn (werken in de Verkenner). Het is daarom belangrijk om te laten zien en ervaren dat het werken met managed metadata en views een aantal voordelen heeft:
- Beter sorteren, groeperen en filteren van documenten
- Sneller en betere zoekresultaten in SharePoint door goede metadata
- Flexibiliteit om documenten op verschillende manieren te bekijken
Adoptie is hier de sleutel! Investeer tijd in training en ondersteuning van gebruikers.
Site Template Updaten
Tijdens het ontwikkelen van site scripts en site templates zul je regelmatig iets willen aanpassen. Ik gebruik daarvoor dit eenvoudige PowerShell script:
Clear-Host
$sitescript = Get-Content "ProjectSjabloonSiteScript.json" -Raw
Set-PnPSiteScript -Identity "5bf00bc8-8049-4a9c-9efc-0beb39b9db23" -Title "Project Site Script" -Version 2 -Content $sitescript
Set-PnPSiteDesign -Identity "26ee5c13-9387-4ddf-a15b-155155c4d741" -SiteScriptIds "5bf00bc8-8049-4a9c-9efc-0beb39b9db23" -Title "Project Site" -Description "Site Design for Projects" -WebTemplate "64" -Version 2 -ThumbnailUrl "https://<tenant>.sharepoint.com/sites/Projectenportaal/SiteAssets/NieuwProject.png"Tip: Vergeet niet om de ID’s en omschrijvingen aan te passen naar jouw situatie.
Wees de eerste om te reageren