SharePoint-sivustojen tilaus- ja luontiprosessi (Osa 1)

Sivustojen tilaus- ja luontiprosessia nimitetään (SharePoint) kansankielellä provisioinniksi. Hienosta nimestään huolimatta kuvio on yksinkertainen:

• Käyttäjä täyttää sivuston tilauslomakkeen
• Tilaus lähtee hyväksyttäväksi
• Mikäli tilaus hyväksytään, sivusto luodaan automaattisesti

Käyttäjän tilauslomakkeella antamat tiedot vaikuttavat usein siihen, millainen luodusta sivustosta tulee.

SharePointin muokattavilla sivustopohjilla ei voi täysin korvata perinteisiä sivustojen provisiontiratkaisuja. Sivustopohjilla kun ei voi juuri vaikuttaa luotavan sivuston rakenteeseen (mitä web-osia käytetään, miten ne on asteltu sivulle jne).

Onkin syytä käydä läpi, miten provisionti voidaan toteuttaa modernissa SharePointissa siten että se istuu nätisti sivustojen olemassaolevaan luontikokemukseen.

Esimerkki – Projektisivustojen provisionti

Otetaan esimerkiksi projektisivustojen provisionti. Sivun luonti alkaa normaaliin tapaan SharePointin Create site -toiminnolla.

Lopputuloksena syntyy projektisivusto

• joka on liitetty hub-sivustoon (projektit)
• jonka asettelu ja käytetyt web-osat poikkeavat vakio tiimisivustosta

Ratkaisuun tarvitsemme seuraavat palikat

• Projektien yhteinen Hub sivusto (Hub site)
• Projektisivuston Sivustomalli (Site design)
• PnP-mallipohja  (PnP provisioning template), joka kuvaa mitä web-osia jne projektisivustoillemme tulee
• Azure Functions, jossa suoritetaan PowerShelliä, joka tekee sivustolle PnP-mallipohjassa kuvatut muutokset
• Flow työnkulku, joka käynnistää uuden sivuston luonnin yhteydessä yllämainitun Functionsin

Vaikuttaa työläältä… Onko se sitä myös käytännössä?

Vaihe 1 – Hub-sivuston määrittely

Luodan aluksi uusi viestintäsivusto (Projektit), johon yksittäiset projektisivustot tullaan liittämään.

Rekisteröidään sivusto PowerShellillä hub-sivustoksi:

Register-SPOHubSite https://distaging.sharepoint.com/sites/Projektit

Tehdään sivustolle muutama perusmuokkaus

• vaihdetaan teema ja logo
• lisätään projektit-kokonaisuuden yhteiseen navigaatioon projekteja kiinnostavat linkit (ohjeet, dokumenttipohjat ja linkki projektityötilalistaukseen)

Lopputulos näyttää seuraavalta.

Vaihe 2 – Provisionnin toteuttavan Flow:n luominen

Luodaan runko Flow:lle, jota uuden sivuston luonnin yhteydessä tullaan kutsumaan. Flow käynnistyy Http-kutsulla.

Http-kutsun body on:

{
    "type": "object",
    "properties": {
        "webUrl": {
            "type": "string"
        },
        "parameters": {
            "type": "object",
            "properties": {
                "event": {
                    "type": "string"
                },
                "product": {
                    "type": "string"
                },
                "PnpTemplate": {
                      "type": "string"
                }
            }
        }
    }

Tallennuksen jälkeen voimme poimia Flow:n HTTP POST URL:in talteen.

Vinkki: Et voi luoda Flow:ta, jossa ei ole yhtään toimintoa (Actions). Lisää käynnistimen perään vaikka toiminto, joka lähettää sinulle sähköpostin tai alustaa muuttujan. Poista tämä turha toiminto kun etenet rakentamisessa.

Vaihe 3 – Sivustomallin määrittely

Luodaan uusi sivustomalli (Projekti). Mallin avulla projekti-sivustot liitetään luomaamme Projektit hub-sivustoon, sekä käynnistetään haluttu Flow.

Sivustomallia varten tehdään sivuston luontiskripti (site script), joka ajetaan aina kun sivustomallilla luodaan uusi sivusto. Luontiscripti näyttää seuraavalta (Flown url on juuri luomamme Flow:n http post url).

Lisätään luontiscripti tenanttiimme.

Get-Content 'C:\Users\TimoPertilä\site-script_projekti.json' ` -Raw | `
Add-SPOSiteScript ` -Title "Script for project template'"

Luodaan sivustomalli, joka käyttää tekemäämme luontiscriptiä. Sivuston pohjana on tiimisivusto (WebTemplate = 64).

Add-SPOSiteDesign `
-Title "Project site" `
-WebTemplate "64" `
-SiteScripts "b8af9c5f-84f0-4f4b-a284-a4d6ffeeed34" `
-Description "Creates custom project site with DI theme"

Kokeillaan luoda projektisivusto tällä uudella sivustomallilla.

Sivuston luonnin jälkeen käynnistyy luontiscriptissä määritellyt lisätyöt.

Myös Flow on käynnistynyt! Vaikke se vielä mitään teekkään.

Hyvältä näyttää. Valmista ei silti vielä ole.

Vaihe 4 – Projektisivun PnP-mallipohjan luominen

Haluamme projektisivustomme sisällön poikkeavan normaalista tiimisivustosta. Tämä on helppo toteuttaa seuraavalla tavalla:

• Luodaan uusi tiimisivusto
• Tehdään siihen halutut muutokset
• Muodostetaan sen pohjalta PnP-mallipohja
• Tehdään uusille sivuille vastaavat muutokset PnP-mallipohjaa hyödyntäen

Suurin työ on miettiä millaisen projektisivuston haluamme.

Luodaan pohjaksi uusi tiimisivusto.

Tehdään sivustolle haluamamme muutokset.

Projektisivustopohjamme etusivu sisältää ainoastaan:

• Projektidokumentaation (dokumenttikirjasto)
• Projektiryhmän esittelyn (People web-osa)
• Tekstisisällön, johon sivuston omistaja ohjeistetaan kirjoittamaan projektin kuvaus
• Sivuston aktiviteetit

Sivuston PnP-mallipohja saadaan ulos komennolla

Connect-PnPOnline -Url https://distaging.sharepoint.com/sites/TimoProjektityotilapohja
Get-PnPProvisioningTemplate -ExcludeContentTypesFromSyndication -Out project_template.xml

Mallipohja sisältää kaiken lähtien sivuston omistajista. Haluamme mukaan ainoastaan määrittelemämme muutokset, joten poistetaan ProvisioningTemplate ja sen ClientSidePages-osiota lukuunottammatta kaikki muu. Siivottu pohja näyttää tältä.

Vaihe 5 – Käyttöoikeuksien luominen PnP:tä varten

Ratkaisussa käyttämämme PowerShell-komento tekee mallipohjan perusteella muutoksia luotuun sivustoon. Se ei onnistu ellei komentoa ajeta tunnuksilla, joilla on oikeus kyseiset muutokset tehdä.

Luodaan PnP:n ajamista varten SharePoint App osoitteessa  https://sinundomainisi.sharepoint.com/_layouts/15/appregnew.aspx

Otetaan Client Id ja Client Secret talteen.

Annetaan luodulle App:lle tarvittavat käyttöoikeudet https://sinundomainisi-admin.sharepoint.com/_layouts/15/appinv.aspx -sivulla.

Etsitään Client ID:llä oikea App ja kopioidaan App’s premission request -kenttään seuraava.

<AppPermissionRequests AllowAppOnlyPolicy="true" >
     <AppPermissionRequest Scope="http://sharepoint/content/tenant" Right="FullControl" />
 </AppPermissionRequests>

Luotu SharePoint Apps saa koko tenanttiin täydet oikeudet.

Eiköhän tällä pärjätä.

Vaihe 6 – PnP-mallipohjan liittäminen luotuun sivustoon

Vielä pitää hetki jaksaa ennen palkitsevaa loppua.

Luodaan Azure Functions, jossa voi ajaa PowerShelliä. Jotta PnP-komennot toimivat, tulee Functionsin käyttöön lisätä myös tarvittavat dll:t.

Avataan Functionsin Platform features -osion alta löytyvä Kudu.

Valitaan Debug Console -> CMD ja navigoidaan site -> wwroot -> funktiomme nimi.

Luodaan uusi kansio ”Modules”.

Haetaan tarvittavat dll:t omalle koneelle.

Save-Module -Name SharePointPnPPowerShellOnline -Path c:/demopnp

Ja kopiodaan ne Kudussa luomaamme kansioon.

Nyt Functions voi ajaa PnP-komentoja (oikeastaan SharePointPnPPowerShellOnline komentoja)!

Kopioidaan vielä PnP-mallipohja (project_template.xml) projektikansioon.

Lisätään Functionsin asetuksiin (Application settings) avaimet AppSecret ja AppID ja annetaan niiden arvoiksi aiemmin luodun SharePoint Appsin secret ja id.

Lopuksi lisätään Functioniin varsinainen koodi.

$requestBody = Get-Content $req -Raw | ConvertFrom-Json
$Url = $requestBody.Url
$PnpTemplateFile = $requestBody.PnpTemplateFile

$Path = 'D:\home\site\wwwroot\Apply-PnPProvisioningTemplate\'

Write-Output "Incoming request for '$Url'"
Connect-PnPOnline -AppId $env:AppId -AppSecret $env:AppSecret -Url $Url
Apply-PnPProvisioningTemplate -Path $Path$PnpTemplateFile

Lopputulos näyttää tältä.

Otetaan seuraavaa vaihetta varten talteen functionin url (oikea yläreuna: Get function URL).

Vaihe 7 – Functionsin kutsuminen Flow:sta

Lisätään Flow-työnkulkuumme http-toiminto, joka kutsuu luomaamme functionsia. Parametreina välitetään tilatun sivuston url (webUrl) sekä provisionnissa käytettävän PnP-mallipohjan nimi (PnpTemplate).

Lopputulos

Pienen väkertämisen jälkeen kaikki on valmista. Käyttäjä voi luoda projektisivuston normaaliin tapaan Create Site -ominaisudella.

Lopputuloksena on tiimisivuston pohjalta muokattu projektisivusto, joka on liitetty hub-sivustoon (Projektit).

Hieman yksinkertaistettuna homma etenee näin.

Yhteenveto

Ratkaisussa on useita säädettäviä palikoita. Onneksi ne ovat kaikki varsin yksinkertaisia.

Toteutettu ratkaisu poikkeaa kuitenkin merkittävästi perinteisestä provisiontiratkaisusta. Tilaajalta ei kysytä lisätietoja luotavaan sivustoon liittyeen. Projektisivustossa näitä voisi olla esimerkiksi

• projektin koko
• käytettävä projektimenetelmä
• projektin tyyppi
• asiakas

Tilauksia ei myöskään voi hyväksyä/hylätä.

Täydennetään ratkaisua tältäosin seuraavassa kirjoituksessa.