Microsoft SharePoint: Ein Einblick in Site Designs und Site Scripts

Mit Microsoft Office 365 und SharePoint-Online hat Microsoft eine neue Möglichkeit zur Anpassung von neuen und bestehenden Seiten eingeführt: Site-Designs und Site Scripts.

Zunächst stellt sich die Frage...

Was sind Site Designs und Site Scripts?

Site Designs und Site Scripts dienen zur Bereitstellung und Anpassung von neuen oder bestehenden modern Sites im SharePoint Online. Mit ihnen können Sie gewährleisten, dass Seiten, die Sie oder Ihre User erstellen, einem einheitlichen Schema entsprechen.

Site Scripts lassen sich als definierter Satz von Aktionen beschreiben, die bei Zuordnung zu einer Seite ausgeführt werden. Sie sind damit Microsofts Ansatz, die Templates aus den On-Premises-Zeiten abzulösen. Mit diesen Aktionen kann man beispielsweise Listen und Bibliotheken zu Seiten hinzufügen oder eine Theme sowie ein Seitenlogo setzen.

Die Aktionen, die im Site Script definiert sind, werden von oben nach unten ausgeführt und werden in JSON-Format angelegt. Dieses JSON folgt einem von Microsoft definierten Schema.

Die Site Scripts werden einem Site Design zugeordnet, welches eigentlich nichts anderes als ein Container für dieses ist. Einem Site Design können auch mehrere Site Scripts hinzugefügt werden.

Wenn Sie schon länger im Ökosystem SharePoint-Online unterwegs sind, sind Ihnen Site Designs und Site Scipts, wenn auch unbewusst, sicher schon über den Weg gelaufen. Denn Microsoft stellt selbst bereits „Out of the box“ verschiedene Site Designs zur Verfügung.

So kann man, wenn man beispielsweise eine neue „Communication Site“ erstellt bereits zwischen verschiedenen Site Designs wählen:

Limitierungen von Site Design und Site Scripts

Site Designs und Site Scripts haben gewisse Limitierungen, über die ich im Folgenden sprechen möchte:

Site Designs/Scripts sind nur im SharePoint-Online verfügbar. Des Weiteren kann es nur 100 Site Designs und Site Scripts in einem Tenant geben und ein Site Script darf nicht mehr als 30 Aktionen beinhalten.

Folgende Aktionen können mit ihnen realisiert werden:

1. Eine neue Liste oder Bibliothek erstellen
2. Erstellung von „Site Columns“ und Inhaltstypen
3. Seitenbranding setzen
4. Einer Seite ein Theme zuordenn
5. Das Seitenlogo setzen
6. Links zur Navigation hinzufügen/ entfernen
7. Einen Flow ausführen
8. Solution aus dem App-Katalog deployen
9. Ländereinstellungen für die Seite setzen
10. Hinzufügen von Benutzern und Gruppen zu SharePoint-Rollen
11. Die externe Freigabe-Funktion für die Seite festlegen

Site Script erstellen

Genug der Theorie. Lassen Sie uns nun in die Praxis springen und ein Site Script erstellen und einem Site Design hinzufügen.

Unser Site Script soll der Seite zunächst eine Liste hinzufügen, die ein Kommentarfeld beinhaltet.

Wie oben erwähnt starten wir mit einem Site Script, welches Microsofts JSON-Schema folgt und die Aktionen zur Erstellung der Liste beinhaltet.

Erstellen Sie eine JSON-Datei mit beliebigem Namen. Ich nenne meine SiteScript.json.

Der Grundaufbau dieser JSON sieht wie folgt aus (Bitte Zeilenumbruch beachten "..."):

{
    "$schema": "https://developer.microsoft.com/json-schemas/sp/...
...site-design-script-actions.schema.json",
    "actions": [],
    "version": 1
}

Das Attribut „$schema“ definiert das JSON-Schema von Microsoft. Das Attribut „actions“ ist ein Array, das unsere auszuführenden Aktionen beinhaltet.

Schema analysieren

Im nächsten Schritt wollen wir die Aktion im „actions“ Array definieren, die der Seite eine Liste hinzufügt.

Im Schema finden wir folgenden Abschnitt, der die Aktion zum Erstellen der Liste definiert (Bitte Zeilenumbruch beachten "..."):

{
   "$schema": "http://json-schema.org/draft-04/schema",
  "title": "JSON Schema for SiteScript Extensions",
  "definitions": {
         ...
  "createSPList": {
      "type": "object",
      "allOf": [
        { "$ref": "#/definitions/baseAction" },
        {
          "properties": {
            "verb": {
              "type": "string",
              "pattern": "^createSPList$"
            },
            "listName": {
              "type": "string",
              "description": "An identifying name for the list."
            },
            "templateType": {
              "type": "number",
              "description": "Specifies the type of a list definition...
... or a list template."
            },
            "subactions": {
              "description": "Sub-actions to run on the list.",
              "type": "array",
              "items": {
                "anyOf": [
                  { "$ref": "#/definitions/SPListSubactions/setTitle" },
                  { "$ref": "#/definitions/SPListSubactions/setDescription" },
                  { "$ref": "#/definitions/SPListSubactions/addSPField" },
                  { "$ref": "#/definitions/SPListSubactions/deleteSPField" },
                  { "$ref": "#/definitions/SPListSubactions/addSPFieldXml" },
                  { "$ref": "#/definitions/SPListSubactions/...
...addSPLookupFieldXml" },
                  { "$ref": "#/definitions/SPListSubactions/addSiteColumn" },
                  { "$ref": "#/definitions/SPListSubactions/addSPView" },
                  { "$ref": "#/definitions/SPListSubactions/removeSPView" },
                  { "$ref": "#/definitions/SPListSubactions/addFile" },
                  { "$ref": "#/definitions/SPListSubactions/addFolder" },
                  { "$ref": "#/definitions/SPListSubactions/addContentType" },
                  { "$ref": "#/definitions/SPListSubactions/...
...removeContentType" },
                  { "$ref": "#/definitions/SPListSubactions/...
...setSPFieldCustomFormatter" },
                  { "$ref": "#/definitions/SPListSubactions/...
...associateFieldCustomizer" },
                  { "$ref": "#/definitions/SPListSubactions/...
...associateListViewCommandSet" }
                ]
              },
              "additionalItems": false
            }
          },
          "required": [ "listName", "templateType", "verb" ]
        }
      ],
      "additionalProperties": false
    },
    ...
}

Unter dem Attribut „required“ finden wir die Attribute, die Pflicht sind, um die Aktion auszuführen.

Im Punkt „Subactions“ findet man Zusatzaktionen, die beim Anlegen der Liste mitausgeführt werden können. Hier finden wir auch eine Aktion zum Hinzufügen für Felder zu der Liste: „addSPField“.

Aktionen zum Site Script hinzufügen

Beginnen wir nun das Aktionsarray mit unserer Aktion zu befüllen (Bitte Zeilenumbruch beachten "..."):

{
    "$schema": "https://developer.microsoft.com/json-schemas/sp/...
...site-design-script-actions.schema.json",
    "actions": [{
        "verb": "createSPList",
        "listName": "SiteScriptListe",
        "templateType": 100, //templateType der Liste
    }],
    "version": 1
}

Wie erwähnt sind die Attribute „listname“, „templatetype“ und „verb“ Pflichtfelder. Dieses Site Script bildet somit die minimale Variante, um eine Liste einer Seite hinzuzufügen.

„listName“ ist der Name der Liste, die in SharePoint angelegt wird und „templateType“ ist der Listentyp. Der hier gewählte Listentyp, die 100, ist eine generische Liste. Alle Listentypen und deren Ids finden Sie hier.

Doch was bringt uns eine generische Liste ohne zusätzliche Felder? Da kommt die erwähnte sub-action aus dem Schema ins Spiel.

Die verwenden wir wie folgt (Bitte Zeilenumbruch beachten "..."):

{
    "$schema": "https://developer.microsoft.com/json-schemas/sp/...
...site-design-script-actions.schema.json",
    "actions": [{
        "verb": "createSPList",
        "listName": "SiteScriptListe",
        "templateType": 100, //templateType der Liste
        "subactions": [{
                "verb": "setDescription",
                "description": "diese Liste wurde durch ein Site...
... Script automatisch erstellt"
            },
            {
                "verb": "addSPField",
                "fieldType": "Text",
                "displayName": "Kommentar",
                "isRequired": true,
                "addToDefaultView": true
            }
        ]
    }],
    "version": 1
}

Die „Subactions“ werden wieder in einem Array definiert. Mit der Aktion „addSPField“ fügen wir der Liste eine Spalte hinzu, dessen Namen, Typen, das Anzeigen in der Standardansicht und das „required“-Attribut wir definieren.

Ich habe noch eine weitere „Subaction“ „setDescription“ erstellt, welche die Beschreibung der Liste setzt.

Das Site Script Ihrem Tenant hinzufügen

Um diesen Schritt zu vollziehen verwenden wir die SharePoint Online Management Shell.

Verbinden Sie sich zunächst mit Ihrem Tenant:

Connect-SPOService -URL "https://<Ihr Tenant>-admin.sharepoint.com"

Ersetze <Ihr Tenant> durch den Namen Ihres Tenants.

Geben Sie in das Popup-Fenster Ihre Credentials ein und führen Sie folgende Befehle aus (Bitte Zeilenumbruch beachten "..."):

$pathToSiteScript = "<Path>"
$siteScriptTitle = "<Titel>"
Get-Content $pathToSiteScript -Raw | Add-SPOSiteScript -Title ...
...$siteScriptTitle

Ersetzen Sie „Path“ durch Ihren Pfad zum Site Script und „Titel“ durch den Titel, den Ihr Site Script haben soll.

Insofern Ihr Site Script valide ist, sehen Sie folgende Ausgabe:

Damit haben wir ein Site Script erstellt und Ihrem Tenant hinzugefügt. Notieren Sie sich die ID, sie wird im nächsten Schritt benötigt.

Site Design erstellen und Site Script assoziieren

Wichtig: Ein Site Design wird einer Seitenart hinzugefügt. Ich werde mein Site Design an TeamSites hängen, diese besitzen die Webtemplate-ID 64. Falls Sie das Site Design mit einer anderen Art von Seite assoziieren möchten, müssen Sie sich die entsprechende ID raussuchen.

Auch für diesen Schritt verwenden wir wieder die SharePoint Online Management Shell. Führen Sie folgenden Befehl aus, um ein neues Site Design anzulegen (Bitte Zeilenumbruch beachten "..."):

Add-SPOSiteDesign -Title "mein erstes Site Design" -WebTemplate "64" ...
...-SiteScripts "<ID aus dem vorherigem Schritt>" -Description ...
..."mein erstes Site Design, fügt einer Seite eine Liste hinzu"

Das Attribut -SiteScripts befüllen wir mit der ID aus dem vorherigem Schritt. Das wars auch schon!

Wir haben damit ein Site Script und ein Site Design unserem Tenant hinzugefügt und können eine Site mit dem Site Design erstellen:

Gehen Sie auf die Landing Page Ihrer SharePoint-Umgebung und wählen Sie „Create Site“. Unter „Choose a design“ finden Sie Ihr neu angelegtes Site Design:

Nach Erstellung der Seite wird das Site Design ausgeführt und wenn es alle Aktionen durchgeführt hat, sehen Sie folgendes Banner im oberen Bereich.

Nach dem Neuladen, finden Sie die neu angelegte Liste mit Kommentarfeld in der Seite:

Ändern eines Site Scripts

Um ein Site Script zu ändern reicht es aus einfach eine neue JSON-Datei hochzuladen. Verwenden Sie dafür folgenden Befehl (Bitte Zeilenumbruch beachten "..."):

Set-SPOSiteScript -Identity <ihre Site Script ID> -Content ...
...(Get-Content <Ihr Path zur neunen JSON-Datei>

Mit Get-SPOSiteScript und Get-SPOSiteDesing kann mann sich seine Site Scripts und Site Designs anzeigen lassen und auch deren Id’s auslesen.

Ändern eines Site Designs

Bestehende Site Designs können mit dem Befehl „Set-SPOSiteDesign“ geändert werden. Das folgende Script fügt ein neues Site Script zu einem bestehenden hinzu (Bitte Zeilenumbruch beachten "..."):

$newSiteScript = (Get-Content <Path zum Site Script, ...
...das hinzugefügt werden soll> -Raw | Add-SPOSiteScript -Title ...
...<Titel des Scripts>) | Select -First 1 Id

Set-SPOSiteDesign -Identity <ID deines Site Designs> -SiteScripts ...
...<ID's der bereits bestehenden Scripte>, $newSiteScript.Id

Fazit / Ausblick

Grundlegend lässt sich sagen, dass Site Scripts und Site Designs eine gute Möglichkeit bilden, ein Gerüst für eine Seite zu bauen. Sobald es allerdings Anforderungen über die Standardfunktionen gibt, stößt man schnell an seine Grenzen.

Hier kommt die Möglichkeit, einen Flow aus dem Script heraus zu starten, sehr gelegen. Über diese kann man dann „Azure funtions“ und damit die PnP-Provisioning Engine starten, was einem weitere Möglichkeiten zur Bereitstellung von Seiten gibt.

Das ist allerdings ein Thema für einen weiteren Blogpost.

Bis dahin,

Ihr Team Software Engineering & Collaboration