In mijn vorige blog heb ik uitgelegd hoe je toegang kan krijgen tot de SharePoint 2013 Workflow platform. Met behulp van dit platform is het mogelijk om REST calls uit te voeren met behulp van een SharePoint Designer Workflow. In het tweede deel van deze blog serie ga ik uitleggen hoe je alles moet instellen om een REST call te kunnen uitvoeren.

REST Call uitvoeren met een Workflow

Voordat we een workflow met een REST call gaan maken is het belangrijk dat de structuur van een REST call duidelijk is. Aangezien een deel van de onderdelen van een REST call één op één gemapped worden naar een variabele. Mocht je nog geen ervaring hebben met REST calls, adviseer ik je daar eerst naar te kijken. Enkele voorbeelden zijn o.a. hier vinden.
Als je in jQuery een REST call maakt, zal deze er vergelijkbaar uitzien als onderstaande call.

Blog - Designer Workflows en de REST API (2)

In de bovenstaande call worden zes eigenschappen meegegeven namelijk:

  • URL
  • Type
  • Data
  • Headers
  • Success
  • Error

Van deze zes properties moet je de URL, Data en Headers als variabele meegeven binnen de REST Call in de Workflow. In de komende paragrafen ga ik laten zien hoe je deze properties moet invullen. Als voorbeeld gebruik ik een REST call die een nieuwe lijst aanmaakt.

URL

We beginnen als eerste met de URL. Maak hiervoor een variabele aan van het type String, met als naam RestUrl.

Om een lijst aan te maken gebruik je de volgende REST url: <siteUrl>/_api/web/lists. Maak deze aan met de actie “Set Workflow Variable”. Voor de siteUrl kan je de “Current Site Url” property gebruiken. De actie komt er dan als volgt uit te zien:

Blog - Designer Workflows en de REST API (2)

 

 

Headers

De 2e variabele die je mee moet geven zijn de Headers. In dit object geef je meer informatie over de REST call die je wilt uitvoeren, het headers object kan onder andere de volgende properties bevatten. Let op, je hebt niet bij elke REST calls elke property nodig.

  • Accept
    • Hiermee geef je aan wat voor response je verwacht
  • Content-Type
    • Hiermee geef je aan wat je aan data mee stuurt
  • X-HTTP-Method
    • Hiermee geef je aan of je een item update (MERGE) of verwijdert (DELETE)
  • If-Match
    • Bij een update kan je hiermee een controle doen of je de laatste versie bewerkt

Normaal gebruik je in een standaard REST call ook nog X-RequestDigest voor authenticatie. Maar deze is niet nodig indien je een REST call binnen een workflow aanroept en de workflow daarom zelf de authenticatie regelt. Voor sommige bewerkingen moet je hier zelf nog wat voor instellen, maar daar kom ik later in de blog op terug.

Voor de REST call die we hier maken zien de headers binnen een jQuery call er als volgt uit.

Blog Ronald - Designer Workflows en de REST API (2)

 

 

Hier zie je drie properties binnen het header object, namelijk accept, content-type en X-RequestDigest. Deze laatste kunnen we zoals gezegd weg laten, maar de andere twee dienen we toe te voegen aan een Dictionary. Maak hiervoor een nieuwe variabele aan genaamd Headers van het type Dictionary.

Zoals je ziet in bovenstaand voorbeeld, hebben zowel accept als content-type de waarde application/json;odata=verbose.

Stel deze waardes in met de actie “Build Dictionary”, dit zal er als volgt uit komen te zien.

Blog - Designer Workflows en de REST API (2)

Data

De laatste property die we moeten instellen is de data property. In deze property gaan we de gegevens van de lijst die we willen aanmaken meegeven. In een standaard REST call zou dit er als volgt uitzien.

Blog- Designer Workflows en de REST API (2)

 

 

 

Hier zie je dat het data object, weer een __metadata object bevat, dit betekent dat er twee variabele van het type Dictionary worden aangemaakt, namelijk “Data” en “Metadata”.

Als eerste gaan we het Metadata object aanmaken, deze bevat 1 property genaamd type met als waarde SP.List. Deze gaan we dan ook toevoegen aan de dictionary. Deze komt er dan als volgt uit te zien.

Blog - Designer Workflows en de REST API (2)

 

 

 

 

 

 

 

Vervolgens gaan we de rest van het data object maken, deze krijgt dan de volgende properties

  •  __metadata (let op, er staan twee underscores voor)
  • BaseTemplate (voor een lijst van templates klik op deze link).
  • Title
  • Description
  • ContentTypesEnabled

Maak eerst een nieuwe variabele van het type Dictionary aan genaamd Data. Stel vervolgens bovenstaande properties in. Aan de __metadata property geef je de Dictionary genaamd Metadata mee die je in de vorige stap had aangemaakt.

Blog - Designer Workflows en de REST API (2)

Nu de variabelen zijn aangemaakt, hebben we nog één variabele nodig om het resultaat van de REST call naar weg te schrijven. Maak hiervoor nog één variabele aan van het type Dictionary genaamd Result. Nu kunnen we REST Call gaan instellen, voeg hiervoor een Call HTTP Web Service actie toe aan je workflow, open de properties van de actie en vul deze als volgt in.

Blog - Designer Workflows en de REST API (2)

 

 

 

 

 

 

 

 

 

Als je nu de worklfow published, zal deze helaas niet direct werken aangezien de rechten structuur net wat anders geregeld wordt dan je gewend bent. De worfklow draait namelijk met zijn rechten en niet onder de rechten van de gebruiker. Daarom moet je dus eerst de rechten goed instellen. Ga hiervoor naar Site Settings -> Site Features en activeer de volgende feature:

Blog - Designer Workflows en de REST API (2)

 

 

  1. Ga vervolgens naar Site Settings -> Site app Permissions en kopieer de Guid van de Workflow App, deze staat tussen de 2e | en de @

Blog - Designer Workflows en de REST API (2)

 

Ga vervolgens naar de URL <siteUrl>/_layouts/15/appinv.aspx. Hier kan je de workflow rechten geven. Vul de Guid van de worklfow app in bij het App Id veld en klik op “Lookup”. De gegevens van de app worden dan voor je opgehaald.

Blog - Designer Workflows en de REST API (2)

Kopieer vervolgens onderstaande Xml naar het Permission Request XML veld en klik op Create.

<AppPermissionRequests>
<AppPermissionRequest Scope=”http://sharepoint/content/sitecollection”
Right=”FullControl” />
</AppPermissionRequests>

Met bovenstaande XML geef je de worklfow Full Control op de volledige site collection. Mocht je niet zo veel rechten willen geven dan is het mogelijk om de workflow alleen full control te geven op één bepaalde site, dit kan met behulp van onderstaande XML.

<AppPermissionRequests>
<AppPermissionRequest Scope=”http://sharepoint/content/sitecollection/web” Right=”FullControl” />
</AppPermissionRequests>

Run de workflow. Als je alles goed gedaan hebt wordt er een nieuwe Custom List aangemaakt met als naam MyList.

Uitlezen REST Resultaat

Als de REST call succesvol uitgevoerd is, krijg je een response terug met daarin informatie over de zojuist aangemaakte lijst. Deze informatie is onder te verdelen in twee categorieën, namelijk de basisgegevens van de lijst en de beschikbare endpoints om verdere gegevens van de lijst op te vragen, zoals de aanwezige Fields en Content Types. De endpoints laten we buiten beschouwing en we gaan kijken naar de basisgegevens die we terugkrijgen en hoe deze eruit te filteren zijn in de workflow.

Laten we eerst even kijken hoe de response eruit ziet, de endpoints zijn uit dit voorbeeld verwijderd voor een beter overzicht..

Blog - Designer Workflows en de REST API (2)

Zoals je hier ziet krijg je een json object terug met 1 property genaamd “d”. Deze property is ook weer een object met daarin de gegevens van de lijst. Indien je met jQuery zou werken, zou je zonder problemen de waardes kunnen ophalen. Het ophalen van de Title zou er bijvoorbeeld als volgt uit zien:

Blog - Designer Workflows en de REST API (2)

 

In een workflow gaat het vergelijkbaar. Voeg hiervoor de volgende actie toe aan je workflow: Get an item from a dictionary.

Aan deze actie geef je droe parameters mee namelijk:

  • de dictionary waaruit je de waarde wilt ophalen
  • de variabele waar je de op te halen waarde naar toe schrijft
  • het path van de waarde die je wilt ophalen

Dit path ziet er als volgt uit: “d\Title“. Zoals je ziet lijkt dit op de manier waarop je het ophaalt met jQuery. De actie om de Title op te halen ziet er dan uiteindelijk als volgt uit:

Blog - Designer Workflows en de REST API (2)

 

 

 

 

 

 

 

Deze structuur werkt ook voor als je een property wilt ophalen die dieper genest is in het Json object zoals de etag, die zoals je kan zien in de afbeelding weer onderdeel is van de __metadata property. Hiervoor geef je dan het volgende Path mee “d\__metadata\etag“.

Nu je ook weet hoe je het resultaat van een REST call in SharePoint Designer kan uitlezen ben je klaar om zelf aan de slag te gaan met je eigen REST calls. Tip hierbij is: zoek eerst op hoe je de call uitvoert met Jquery en converteer deze dan met behulp van de stappen die ik je getoond heb naar een SharePoint Workflow. Op deze manier kan je veel voorbeelden vinden (meer dan als je zoekt op SharePoint Designer en REST).

Succes en bedankt voor het lezen.