Inleiding
ABF biedt een SharePoint-omgeving waarmee importbestanden automatisch naar Swing kunnen worden geüpload. De omgeving kan worden gebruikt om importbestanden handmatig toe te voegen of om bestanden automatisch te uploaden met behulp van de Microsoft Graph API.
In deze handleiding wordt beschreven hoe je de SharePoint-omgeving kunt gebruiken en aan welke eisen de importbestanden moeten voldoen.
Mappenstructuur SharePoint-omgeving
De SharePoint-omgeving is opgebouwd volgens een vaste structuur. De structuur is weergegeven in onderstaande tabel.
| Inkomend | Hier plaats je de importbestanden die je wilt laten importeren. |
| Verwerkt | Hier worden de importbestanden geplaatst die succesvol zijn geïmporteerd. |
| Afgekeurd | Hier worden de importbestanden geplaatst die niet geïmporteerd konden worden vanwege een fout. |
| Log | In deze map worden logbestanden opgeslagen. Hierin staat wat er met een importbestand is gebeurd. |
| Overig | In deze map staan de API-gegevens en kunnen overige bestanden worden geplaatst. |
Swingformat
Er kunnen alleen importbestanden in csv- of xlsx-formaat worden geïmporteerd die voldoen aan het ‘Swing format’. Het importbestand moet de volgende kolomtitels bevatten:
| indicatorcode | De code van de indicator |
| periodcode | De periode waarvoor de data geldt (bijvoorbeeld 2025) |
| geolevelcode | Het geografische schaalniveau (bijvoorbeeld gemeente of provincie) |
| geoitemcode | De specifieke geografische locatie (bijvoorbeeld een gemeentecode) |
| cubemembers (optioneel) | De kenmerken van de data (alleen van toepassing bij kubusonderwerpen) |
| value | De waarde van het datarecord |
Voorbeeld importbestand – voorbeeld van platte dataset
Voorbeeld importbestand – voorbeeld van kubusdataset
Advies: gebruik één indicator per importbestand
Door één indicator per importbestand te gebruiken, is er een beter overzicht over wat wel en wat niet correct verwerkt is. Nadat het importbestand op hoofdlijnen gevalideerd is, wordt het bestand in één keer geïmporteerd. Het verwerkingsproces wordt per importbestand afgebroken bij de eerste foutmelding die in het importbestand wordt gevonden. Let op: voorafgaand aan de foutmelding kan al een deel van de data zijn geïmporteerd wanneer meerdere indicatoren in het bestand zijn opgenomen.
Bestanden geautomatiseerd uploaden
Importbestanden kunnen handmatig in de map “Inkomend” op SharePoint geplaatst worden.
Het is ook mogelijk dit proces te automatiseren. Dit wordt met name aanbevolen wanneer er veel bestanden worden verwerkt of updates periodiek plaatsvinden.
Om dit proces te automatiseren moet er een koppeling worden gemaakt met SharePoint via een app-registratie. Vervolgens kan met deze koppeling het verdere uploadproces worden ingericht, bijvoorbeeld met behulp van een script.
App-registratiegegevens
De app-registratiegegevens zijn nodig om een connectie te kunnen maken met de SharePoint-omgeving.
Je kunt deze gegevens vinden in het Word-document “App_Registratie.docx” dat door ABF is geplaatst in de map “Overig” in de SharePoint-omgeving. De inhoud van het document ziet er ongeveer zo uit.
| App registratie | ||
| 1 | Naam | Demo_DataHub |
| 2 | Client-ID | <Hier staat de Client ID> |
| 3 | Object-ID | voorbeeld123objectID |
| 4 | Tenant-ID | <Hier staat de Tenant ID> |
| 5 | Site-ID | abfresearch.nl.sharepoint.com/voorbeeld123siteID |
| 6 | Drive-ID | <Hier staat de Drive ID> |
| 7 | Secret-ID | voorbeeld123secretID |
| 8 | Expiration date | Datum waarop de toegang tot de SharePointomgeving verloopt |
| 9 | Client Secret | <Hier staat de Client Secret> |
| 10 | WebURL | https://abfresearch.nl.sharepoint.com/sites/Demo_DataHub |
De dikgedrukte rijen zijn de relevante gegevens die ingevuld moeten worden.
Verbinding maken met SharePoint via PowerShell of Python
Er zijn meerdere mogelijkheden om de verbinding te maken met SharePoint, maar de stappen zijn globaal genomen hetzelfde:
- Het opvragen van een access token
- Een lijst opvragen van alle submappen in SharePoint
- Het uploaden van bestanden naar een gespecificeerde folder
Bekijk een voorbeeld in PowerShell of in Python.
Verwerkingsproces
Het verwerkingsproces van Files2Swing bestaat uit drie stappen:
Proces starten – importbestanden ophalen
Files2Swing controleert of er importbestanden in de map “Inkomend” op SharePoint staan.
Als er geen importbestanden in de map “Inkomend” staan wordt het proces beëindigd.
Zijn er wel importbestanden, dan wordt in een lineair proces per importbestand de rest van het verwerkingsproces doorlopen. Er wordt dan ook een logbestand aangemaakt waarin de verwerking wordt bijgehouden.
Importbestand verwerken - validatie en import
De importbestanden worden gevalideerd, onder meer door te kijken of de importbestandsopbouw correct is en of de indicatoren aanwezig zijn in de Swing beheeromgeving. Daarna wordt de data in Swing geïmporteerd.
Als de data correct is geïmporteerd wordt het importbestand verplaatst naar de Verwerkt-map op SharePoint, voorzien van een timestamp. Als een importbestand niet door de validatie komt, of er treedt een fout op bij het importeren, dan wordt het proces voor dit importbestand beëindigd. Het importbestand wordt dan verplaatst naar de Afgekeurd-map op SharePoint.
Let op: Files2Swing valideert uitsluitend of indicatoren bestaan. Er wordt niet gecontroleerd op:
- periodes
- gebiedsniveaus
- dimensies
Zorg ervoor dat de metadata al aanwezig zijn in de Swing beheeromgeving.
Proces afronden – logbestand
Wanneer alle importbestanden zijn verwerkt, wordt het logbestand afgerond en neergezet in de map “Log” op SharePoint.
Een voorbeeld van een logbestand is hieronder weergegeven.
Voorbeeld logbestand waarbij één importbestand is afgekeurd omdat een indicator niet aanwezig was in Swing en één importbestand correct is verwerkt.
Contact
Voor vragen en opmerkingen kun je contact opnemen met de Swing Helpdesk via de helpdeskwebsite of per e-mail.
Website: helpdesk.swing.eu
E-mail: helpdesk@swing.eu