Inhoudsopgave
- Inleiding
- Mappenstructuur
- Format importbestanden
- Advies: gebruik één indicator per importbestand
- Het verwerkingsproces
- Geautomatiseerd importbestanden uploaden naar SharePoint
- App registratie gegevens
- Stappenplan (op hoofdlijnen)
- Voorbeeld – PowerShell
- Voorbeeld – Python
- Contact
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, maar ook om bestanden automatisch te uploaden met behulp van de Microsoft Graph API.
Hoe je de SharePoint-omgeving kunt gebruiken en aan welke eisen de importbestanden moeten voldoen, wordt beschreven in deze handleiding.
Mappenstructuur
De SharePoint-omgeving is opgebouwd volgens een vaste mappenstructuur. Deze is weergegeven in onderstaande afbeelding.
| 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. |
Format importbestanden
Alleen importbestanden die voldoen aan het Swing-formaat kunnen worden geïmporteerd. Dit houdt in dat een importbestand moet voldoen aan de volgende eisen:
- Het importbestand moet een Excel-bestand (.xlsx) of een CSV-bestand zijn.
- 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
Gebruik bij voorkeur één indicator per importbestand. Hierdoor blijft beter inzichtelijk welke bestanden correct zijn verwerkt en welke niet.
Nadat een importbestand op hoofdlijnen is gevalideerd, wordt het in één keer geïmporteerd. Het verwerkingsproces wordt afgebroken zodra de eerste fout wordt gevonden. Als een bestand meerdere indicatoren bevat, kan een deel van de data al zijn geïmporteerd voordat de fout optreedt.
Het verwerkingsproces
Het verwerkingsproces van Files2Swing bestaat uit vier 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
De importbestanden worden gevalideerd, onder meer door te kijken of de importbestandsopbouw correct is en of de indicatoren aanwezig zijn in de Swing-beheeromgeving.
Importbestand verwerken – import
Nadat de importbestanden zijn gevalideerd, wordt de data in Swing geïmporteerd.
Als de data correct is geïmporteerd wordt het importbestand verplaatst naar de map “Verwerkt” op SharePoint.
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 map “Afgekeurd” op SharePoint.
Let op: Files2Swing controleert vooraf alleen of de opgegeven indicatoren bestaan. Er wordt niet gecontroleerd op de aanwezigheid van periodes, geolevels of dimensies. Zorg er daarom voor dat alles correct is ingesteld in Swing om fouten bij de import te voorkomen.
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.
Geautomatiseerd importbestanden uploaden naar SharePoint
Importbestanden kunnen handmatig in de map “Inkomend” op SharePoint geplaatst worden.
Het is ook mogelijk dit proces te automatiseren. Dit is met name handig wanneer er veel bestanden worden verwerkt of wanneer updates periodiek plaatsvinden.
Om dit te bewerkstelligen 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_Registatie.docx” dat door ABF is geplaatst in de map “Overig”. De inhoud van het document ziet er ongeveer zo uit.
De met groen gearceerde rijen zijn de gegevens die je nodig hebt.
Let op: de “Client ID” staat vermeld onder de naam “Toepassings-ID” en de “Client Secret” staat vermeld onder de naam “Secret Value”.
Stappenplan (op hoofdlijnen)
Er zijn meerdere mogelijkheden om de verbinding te maken met SharePoint, maar de stappen zijn globaal genomen hetzelfde.
De stappen die genomen dienen te worden zijn:
- Het opvragen van een access token
- Een lijst opvragen van alle submappen in SharePoint
- Het uploaden van bestanden naar een gespecificeerde folder
In de volgende twee paragrafen zijn voorbeelden te zien hoe deze stappen worden toegepast met behulp van PowerShell en Python.
Voorbeeld – PowerShell
In deze paragraaf geven we een voorbeeld van een PowerShell script waarmee geautomatiseerd importbestanden naar SharePoint geüpload worden. Zie ook de bijlage upload_to_sharepoint.ps1.
Voorbeeld – Python
In deze paragraaf geven we een voorbeeld van een Python script waarmee geautomatiseerd importbestanden naar SharePoint geüpload worden. Zie ook de bijlage upload_to_sharepoint.py.
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