Site Designs: SharePoint Sites automatisch einrichten

Mit den Site Designs hat Microsoft vor rund einem Jahr eine neue Technologie für SharePoint Online eingeführt, mit der sich das Bereitstellen (Provisioning) von SharePoint-Sites und -Objekten automatisieren lässt. In den letzten Monaten wurden die Möglichkeiten sukzessive ausgebaut. Höchste Zeit also, sich die neue Vorlagentechnologie im Detail anzuschauen.

Grundlagen: Designs, Scripts und Actions

Im Grunde genommen handelt es sich bei den Site Designs um eine Abfolge von Kommandos, die auf eine bereits vorhandene SharePoint Site angewendet wird. Damit lassen sich zum einen Konfigurationseinstellungen an der Site vornehmen und zum anderen SharePoint-Objekte wie z.B. Dokumentenbibliotheken oder Navigationslinks einrichten. Doch wie funktionieren Site Designs genau und wie werden sie angewendet?

Site Actions

Site Designs bestehen aus einem oder mehreren Site Scripts, welche sich wiederum aus einer Abfolge von Site Actions zusammensetzen. Site Actions sind die eigentlichen Kommandos, die eine bestimmte Operation an einer Site durchführen. Derzeit (Stand Mai 2019) stellt Microsoft rund 30 Site Actions zur Verfügung, wobei das Angebot laufend ausgebaut wird.

Ein einfaches Beispiel für eine Site Action ist etwa applyTheme, die einer Site ein bestimmtes Theme (Farbschema) zuweisen kann:

{
   "verb": "applyTheme",
   "themeName": "Corporate Blue"
}

Wie im Code zu sehen, setzt sich eine Site Action aus dem jeweiligen Befehl (Verb) und einem oder mehreren Parametern zusammen. Daneben gibt es komplexere Site Actions, welche über Unteraktionen verfügen können. So etwa die Action createSPList zum Einrichten von SharePoint-Listen. Hier können in verschachtelter Form Sub-Kommandos wie addSPField oder addSPView verwendet werden, um einer Liste beim Einrichten gleich die nötigen Felder (Site Columns) oder Ansichten (Views) zuzuweisen.

Das folgende Codebeispiel verdeutlicht, wie mit der createSPList-Aktion eine Liste “Project Tasks” mit dem Feld “Assigned To” (addSPField) erstellt werden kann:

{
  "verb": "createSPList",
  "listName": "ProjectTaskList",
  "templateType": 100,
  "subactions": [
    {
      "verb": "setDescription",
      "description": "Project Tasks List"
    },
    {
      "verb": "setTitle",
      "title": "Project Tasks"
    },
    {
      "verb": "addSPField",
      "fieldType": "User",
      "displayName": "Assigned To",
      "internalName": "AssignedTo",
      "isRequired": false,
      "addToDefaultView": true
    }
  ]
}

Site Scripts

Der für die Anwendung auf SharePoint Sites notwendige Code wird in sogenannten Site Scripts im JSON-Format formuliert. Hier lassen sich mehrere Site Actions zu logischen Einheiten zusammenfassen. So kann beispielsweise ein Site Script zum Einrichten einer SharePoint-Dokumentenbibliothek inklusive aller notwendigen Felder, Ansichten und Navigations-Elemente definiert werden. Wer den notwendigen JSON-Code nicht mühselig mit einem Editor von Hand zusammenschustern möchte, kann auf das praktische Online Tool SiteDesigner.io zurückgreifen.

Site Designs

Site Designs sind die eigentlichen Vorlagen, welche den Benutzern über das SharePoint User Interface zur Verfügung gestellt werden. Sie setzen sich aus einem oder mehreren Site Scripts zusammen. Typischerweise werden in Site Designs Vorlagen für ganze Sites (Projekt-Site, Team-Site, Abteilungs-Site etc.) festgelegt, es ist aber auch möglich, Site Designs für oft benötigte SharePoint-Elemente wie beispielsweise für eine unternehmensweit einheitliche Dokumentenbibliothek zu Verfügung zu stellen.

Die etwas verwirrende Aufteilung zwischen Site Designs und Site Scripts hat einen praktischen Grund: Sie erlaubt es Site Scripts modular aufzubauen und flexibel in verschiedenen Site Designs wieder zu verwenden. So kann beispielsweise das Site Script für eine standardisierte Task-Liste sowohl in einer Projekt-Site- als auch in einer Team-Site-Vorlage genutzt werden.

Site Designs können auf unterschiedliche Weise auf SharePoint Sites angewendet werden:

• SharePoint Home: Benutzer können bei der Erstellung neuer Sites via SharePoint Home das gewünschte Site Design auswählen. Dieses wird unmittelbar nach der Erstellung der Site auf dieses angewendet.
• Site Settings Panel: Anwender können Site Designs über das Site Settings Panel (nur in Modern SharePoint Sites verfügbar) auch nachträglich auf eine Site anwenden.
• Hub-Site-Join: Beim Anschliessen einer Site an einen Hub, kann dieser automatisch ein Site Design zugewiesen werden. Das gewünschte Site Design muss dazu lediglich in den Einstellungen der entsprechenden Hub Site aktiviert werden.
• PowerShell / APIs: Administratoren können Site Designs auch via PowerShell (via Invoke-SPOSiteDesign) ausführen. Ausserdem gibt es APIs (CSOM oder REST), um Site Designs aus externen Anwendungen zu aktivieren.

• Der Parameter –WebTemplate gibt an, ob das Site Design in der «Site erstellen»-UI unter dem Bereich Team Site (64) oder Communication Site (68) angezeigt werden soll.
• Über den Parameter -SiteScripts können die IDs aller Site Scripts angegeben werden, welche dem Site Design zugewiesen werden sollen. Die IDs aller installierter Site Scripts lassen sich mit dem Kommando Get-SPOSiteScript | Format-Table auflisten.

Eine detaillierte Dokumentation zu den PowerShell-Kommandos rund um Site Designs erhält man unter folgendem Link: https://docs.microsoft.com/en-us/powershell/sharepoint/sharepoint-pnp/sharepoint-pnp-cmdlets.

Tipps zum Umgang mit Site Designs und Site Scripts

Nachfolgend ein paar wichtige Fakten und Tipps für den praktischen Einsatz von Site Designs und Site Scripts:

• 100 Site Designs pro Tenant: Pro Office 365 Tenant können derzeit bis zu 100 Site Scripts und 100 Site Designs eingerichtet werden.
• Large Site Designs: «Gewöhnliche» Site Designs können bis zu 30 Site Actions (inkl. Sub Actions) und maximal 20’000 Zeichen umfassen. Seit Anfang 2019 gibt es allerdings Unterstützung für «umfangreiche» Site Designs (inoffiziell auch als «Large Site Designs» bezeichnet, welche bis zu 300 Aktionen und 100’000 Zeichen umfassen dürfen. Für deren Anwendung steht ein eigenes PowerShell-Kommando (Add-SPOSiteDesignTask) bereit. Mit diesem Befehl wird das Site Design allerdings nicht sofort ausgeführt, sondern als Job für die spätere Abarbeitung zugefügt. Im Gegensatz zu den gewöhnlichen stehen die Large Site Designs nicht über die «Site Erstellen»-UI in SharePoint Home bereit.
• Classic SharePoint Sites: Site Designs können nicht nur für Modern SharePoint Sites, sondern auch für klassische SharePoint Team Sites (STS#0) oder Publishing Sites (BLANKINTRANET#0) genutzt werden. Deren Anwendung muss allerdings via PowerShell oder über die API ausgelöst werden.
• Einschränken der Nutzer: Wer die Nutzung eines spezifischen Site Designs auf einen bestimmten Nutzerkreis einschränken möchte, kann dies über das Kommando Grant-SPOSiteDesignRights tun. Das angegebene Site Design wird dann für alle anderen Benutzer ausgeblendet.
• Anpassen der Default-Templates: SharePoint Online verfügt bereits Out of the Box über vier Standard-Site-Designs: eines für Modern Team Sites (Team Site) und drei für Modern Communications Sites (Topic, Showcase und Blank). Es ist möglich, diesen Standard-Site-Designs zusätzliche Site Actions hinzuzufügen. Dies geschieht über den Switch -IsDefault des Add-SPOSiteDesign-Cmdlets. Wird der IsDefault-Switch auf “true” gesetzt, wird das entsprechende Site Design in der SharePoint UI nicht mehr angezeigt. Stattdessen werden die im Site Design definierten Aktionen ausgeführt, wenn eine der Standard-Vorlage verwendet wird.
• Bestehende Liste als Site Script exportieren: Seit Anfang 2019 besteht über das PowerShell-Cmdlet Get-SPOSiteScriptFromList die Möglichkeit, von einer bestehenden SharePoint-Liste das passende Site Script zu generieren.

Verfügbare Site Actions

Aktuell (Stand Anfang Mai 2019) stellt Microsoft rund 30 Site Actions zur Verfügung. Das Angebot wird laufend erweitert. Hier ein Überblick über einige interessante Site Actions:

Site Einstellungen

• applyTheme: Aktiviert ein bereits im Tenant vorhandenes Site Theme.
• addNavLink: Fügt einen Navigationslink hinzu.
• setRegionalSettings: Richtet lokale Einstellungen wie Zeitzone oder Locale Code ein.
• setSiteExternalSharingCapability: Aktiviert oder deaktiviert das externe Teilen (External Sharing).
• addPrincipalToSPGroup: Fügt Benutzer oder ganze Gruppen einer SharePoint-Gruppe (Besitzer, Mitglieder, Besucher etc.) hinzu.

SharePoint Objekte

• createSPList: Erstellt eine SharePoint-Liste oder Dokumentenbibliothek.
• createSiteColumn: Erstellt ein neues Feld (Site Column). Unterstützt derzeit die Datentypen Text, Number, Boolean, DateType und User.
• createSiteColumnXML: Erstellt ein neues Feld basierend auf einer CAML-Definition (Collaborative Application Markup Language). Damit lassen sich Felder für Datentypen erzeugen, welche von der createSiteColumn-Action nicht unterstützt werden. Dazu gehören z.B. Auswahl- oder Währungsfelder.
• addSPLookupFieldXml: Definiert ein Lookup-Feld mit Hilfe von CAML.
• createContentType: Erzeugt einen Content Types.

Andere

• joinHubSite: Schliesst eine Site an eine SharePoint Hub Site an.
• triggerFlow: Startet einen mit Microsoft Flow erstellten Workflow (siehe separater Abschnitt weiter unten).
• installSolution: Installiert ein Add-in oder eine SharePoint Framework Solution (SPFx) aus dem App Catalog des Tenants.

Einen kompletten Überblick über alle aktuellen Site-Script-Actions findet man unter https://docs.microsoft.com/en-us/sharepoint/dev/declarative-customization/site-design-json-schema.

Aktualisieren von bestehenden SharePoint Sites

Eine tolle Möglichkeit von Site Designs ist, dass sie nicht nur im Zuge der Site-Erstellung, sondern auch zu einem beliebigen späteren Zeitpunkt auf eine Site angewendet werden können. Damit lassen sich ganze Heerscharen von Sites mit neuen Einstellungen oder SharePoint-Objekten nachrüsten bzw. aktualisieren. Soll etwa einer Site eine standardisierte Dokumentenbibliothek hinzugefügt oder eine bereits bestehende aktualisiert werden, kann dies problemlos durch die Aktivierung des entsprechenden Site Designs geschehen.

Wie oben bereits erwähnt, kann die Anwendung des Designs auf eine Site via PowerShell (Invoke-SPOSiteDesign) oder über das Site Settings Panel (siehe Screenshot unten) durchgeführt werden. Praktisch: Über das Panel lässt sich auch abrufen, welche Site Designs bereits auf die Site angewendet wurden.

Für die Entfernung von SharePoint-Objekten stellen Site Designs allerdings nur eine beschränkte Zahl von Mitteln bereit. So gibt es derzeit nur eine Handvoll Site Actions, die das Entfernen von bestimmten Elementen ermöglichen. Aktuell stehen die Aktionen removeSPView (Listenansichten), removeContentType (Content Types), removeSiteColumn (Site Columns) und removeNavLink (Navigationselemente) zur Verfügung. Ausserdem gibt es die Aktion deleteSPField mit der ein Feld (Column) aus einer Liste gelöscht werden kann.

Integration mit Microsoft Flow

Sehr spannend ist die Option, einen auf Microsoft Flow basierten Workflow über ein Site Design zu starten. Denn damit lassen sich sehr einfach eigene Erweiterungen in den Site-Erstellungs-Prozess integrieren. So kann etwa externer Code über eine Azure Function ausgeführt werden, der via MS Graph API zusätzliche Konfigurationsschritte durchführt. Ein Beispiel wäre etwa die automatische Erweiterung einer SharePoint Team Site um einen Microsoft Teams Workspace.

Site Designs versus PNP Provisioning

Site Designs und Site Scripts sind eine elegante Lösung, um das Einrichten von SharePoint Sites und -Objekten zu automatisieren. Leider fehlen derzeit noch einige wichtige Funktionen. Dazu gehören etwa das Erstellen von Site Pages oder das Platzieren und Konfigurieren von Web Parts.

Seit einigen Jahren gibt es mit dem PNP Provisioning Framework ein bewährtes Konzept für die Bereitstellung von Sites und SharePoint-Objekten. PNP Provisioning ist in punkto Funktionsumfang wesentlich kompletter als die Site Designs in ihrer aktuellen Form. Insbesondere das Feature, Vorlagen für ganze Sites oder einzelne Objekte von bestehenden SharePoint-Sites generieren zu können, ist eine der grossen Stärken des PNP-Ansatzes.

Zwar ist es Microsofts erklärtes Ziel, den vollen Funktionsumfang von PNP Provisioning auch via Site Designs zur Verfügung zu stellen, ob dies jedoch jemals der Fall sein wird, bleibt abzuwarten. Im Moment hat man gar den Eindruck, dass sich der PNP-Provisioning-Ansatz schneller weiterentwickelt als die Site Designs. Wichtig zu wissen ist in diesem Zusammenhang auch, dass PNP Provisioning nicht direkt von Microsoft stammt, sondern im Rahmen eines Community-Projekts entwickelt wird, welches aber von Microsoft-Mitarbeitern betreut und koordiniert wird. Im Gegensatz zu den Site Designs bieten die Redmonder für PNP Provisioning demnach auch keinen offiziellen Support. Ausserdem hat das PNP-Provisioning-Framework den Nachteil, dass es keine native Integration in die SharePoint-Umgebung gibt. Zur Nutzung sind eine PowerShell-Umgebung, eigene Anwendungen oder Cloud-Dienste wie Azure Functions oder Azure Automation notwendig.

Glücklicherweise braucht man sich nicht zwingend für eines der beiden Konzepte zu entscheiden, denn die beiden Technologien können problemlos miteinander kombiniert werden. Damit erhält man quasi das Beste aus zwei Welten: Die native Integration der Site Designs in die SharePoint UI und das breite Funktionsspektrum von PNP Provisioning. Mit der oben beschriebenen Flow-Integration lassen sich PNP Templates mit relativ überschaubarem Aufwand in Site Designs integrieren.