Swing API - Files2Swing

• Inleiding
• Werking van Files2Swing
• SharePoint-omgeving
  • SharePoint als centrale aanleverlocatie
  • Mappenstructuur
• Importbestanden
  • Standaard Swing-format
    • Onderwerpdata
    • Metadata
    • Automatische verwerkingsvolgorde
  • Aandachtspunten
    • Gebruik bij onderwerpdata één indicator per importbestand
  • Maatwerkverwerking
• Bestanden geautomatiseerd uploaden
  • Overzicht
  • Verbinding maken met SharePoint
• Verwerking van importbestanden
  • Importbestanden ophalen
  • Importbestanden verwerken
  • Proces afronden – logbestand en mailing
  • Samenvatting
• Contact

Inleiding

Files2Swing is een hulpmiddel waarmee datasets automatisch in een Swing-omgeving kunnen worden geïmporteerd. Hiervoor wordt gebruikgemaakt van een SharePoint-omgeving waarin importbestanden worden geplaatst. Files2Swing haalt deze bestanden op, controleert de opbouw en importeert de gegevens vervolgens automatisch in Swing.

Deze handleiding is bedoeld voor Swing-beheerders die Files2Swing willen inrichten. Het beschrijft zowel de achterliggende werking van Files2Swing als de praktische inrichting ervan. Er wordt uitgelegd hoe de SharePoint-omgeving is ingericht, hoe een koppeling met SharePoint kan worden gemaakt en hoe importbestanden moeten worden opgebouwd om succesvol verwerkt te kunnen worden. Let op: Voor het inrichten van de geautomatiseerde koppeling met SharePoint is technische kennis van Microsoft Graph API en/of scripting (bijvoorbeeld PowerShell of Python) vereist.

Werking van Files2Swing

Files2Swing automatiseert het importeren van datasets in Swing. Hierbij wordt gebruikgemaakt van een SharePoint-omgeving als centrale aanleverlocatie voor importbestanden. Externe systemen hoeven daardoor geen directe verbinding met de Swing-beheeromgeving te maken, maar leveren bestanden aan via SharePoint.

Files2Swing controleert periodiek of er nieuwe importbestanden aanwezig zijn. Nieuwe bestanden worden één voor één verwerkt. Tijdens de verwerking worden de importbestanden gevalideerd en geïmporteerd in Swing. Vervolgens worden de bestanden verplaatst naar de map Verwerkt of Afgekeurd en wordt een logbestand aangemaakt waarin de verwerking is vastgelegd.

Deze werkwijze biedt verschillende voordelen, zowel voor functionele als voor technische beheerders:

• een duidelijke scheiding tussen het aanleveren en verwerken van gegevens;
• eenvoudige automatisering via Microsoft Graph API;
• inzicht in de status van iedere verwerking;
• centrale logging en foutafhandeling.

Selecteer onderstaande afbeelding om deze op een nieuwe pagina te bekijken.

SharePoint-omgeving

SharePoint als centrale aanleverlocatie

Files2Swing maakt gebruik van een SharePoint-omgeving als centrale locatie voor het aanleveren en verwerken van importbestanden. Via eigen programmatuur worden importbestanden in deze omgeving geplaatst, waarna Files2Swing de verdere verwerking automatisch uitvoert.

Door SharePoint als tussenlaag te gebruiken, wordt de koppeling tussen eigen gegevens en Swing eenvoudiger, betrouwbaarder en beter beheersbaar. Daarnaast biedt de omgeving inzicht in de status van iedere verwerking en worden logbestanden centraal opgeslagen.

De data wordt opgeslagen op SharePoint binnen de Europese Microsoft-cloud. Microsoft beveiligt deze omgeving met uitgebreide beveiligingsmaatregelen, waaronder versleuteling van gegevens tijdens opslag en verzending. Daarnaast bepalen wij zelf welke medewerkers toegang hebben tot de data.

Mappenstructuur

De SharePoint-omgeving is opgebouwd volgens een vaste mappenstructuur. Iedere map heeft een eigen functie binnen het verwerkingsproces.

Hieronder wordt een voorbeeld getoond van een ingerichte Sharepoint-omgeving.

Importbestanden

Standaard Swing-format

Files2Swing werkt met standaard importbestanden in het Swing-format. Dit is dezelfde bestandsindeling wat ook rechtstreeks via Swing Studio kan worden geëxporteerd en geïmporteerd.

Er kunnen twee soorten bestanden worden verwerkt:

• Onderwerpdata (gegevens die worden geïmporteerd in een bestaand onderwerp)
• Metadata (zoals indicatoren, databronnen en dimensies)

Onderwerpdata

Onderwerpdata kan worden aangeleverd als .csv of .xlsx. Een CSV-bestand wordt altijd beschouwd als onderwerpdata. Ook een Excel-bestand zonder metadata-prefix wordt als onderwerpdata verwerkt. De werking van de prefixcode wordt in de paragraaf Metadata toegelicht.

Wanneer data als CSV wordt aangeleverd, geldt:

• scheidingsteken: puntkomma (;)
• decimaalteken: komma (,)

Een importbestand moet de volgende kolommen bevatten:

Hieronder volgen twee voorbeelden van een importbestand, één zonder cubemembers en één met cubemembers.

Voorbeeldbestand indicator zonder kenmerken (cubemembers)

Voorbeeldbestand indicator met kenmerken (cubemembers)

Metadata

Naast onderwerpdata kan Files2Swing ook metadata importeren. Deze metadata kan worden aangeleverd in het format van de exportbestanden uit Swing studio. Metadata moet worden aangeleverd als Excel-bestand met de extensie .xlsx. Het type metadata wordt bepaald aan de hand van de prefixcode in de bestandsnaam:

Bijvoorbeeld: bestand indicatoren_files2swing.xlsx bevat de metadata van de indicator met code testindicator_bevolking.

Automatische verwerkingsvolgorde

Wanneer meerdere bestanden tegelijkertijd worden aangeboden, bepaalt Files2Swing automatisch de juiste verwerkingsvolgorde.

Hierdoor wordt bijvoorbeeld eerst de metadata van een nieuwe indicator geïmporteerd en pas daarna de bijbehorende onderwerpdata. Zo wordt voorkomen dat data wordt geïmporteerd voor objecten die nog niet bestaan in Swing.

Gebruik bij onderwerpdata één indicator per importbestand

Door bij het importeren van onderwerpdata één indicator per bestand te gebruiken, blijft duidelijk welke gegevens correct zijn verwerkt. Wanneer er tijdens de verwerking van een bestand een fout wordt gevonden, wordt de verwerking op dat moment beëindigd. Als importbestanden meerdere onderwerpen bevatten, kan het onduidelijk zijn welk deel succesvol geïmporteerd is en welk deel mislukt. Door één indicator per bestand te hanteren blijven fouten overzichtelijk en eenvoudig te herstellen.

Maatwerkverwerking

Files2Swing ondersteunt standaard het Swing-format. In sommige situaties is het echter wenselijk om een afwijkend bestandsformaat te gebruiken of aanvullende controles uit te voeren voordat gegevens in Swing worden geïmporteerd.

ABF kan hiervoor maatwerk ontwikkelen, bijvoorbeeld om:

• gegevens uit een afwijkend bronformaat automatisch om te zetten naar het Swing-format.
• aanvullende kwaliteitscontroles uit te voeren vóór de import.
• nieuwe gegevens te vergelijken met eerder geïmporteerde data.
• alleen te importeren wanneer de gegevens aan vooraf gedefinieerde controles voldoen.

Neem contact op met jouw contactpersoon bij ABF om de mogelijkheden voor een maatwerkoplossing te bespreken.

Bestanden geautomatiseerd uploaden

Overzicht

Importbestanden kunnen zowel handmatig als geautomatiseerd worden geplaatst in de map Inkomend van de SharePoint-omgeving. ABF adviseert om bestanden eerst te testen door deze handmatig toe te voegen. Na een correcte verwerking kan dit proces worden geautomatiseerd. 

De automatische aanlevering verloopt via Microsoft Graph API. Hiervoor wordt een app-registratie gebruikt waarmee een externe applicatie bestanden kan uploaden naar de SharePoint-omgeving.

De implementatie bestaat uit drie stappen:

1. App-registratie overnemen
2. Verbinding maken met SharePoint
3. Importbestanden uploaden naar de map Inkomend

App-registratie

Om verbinding te maken met de SharePoint-omgeving zijn app-registratiegegevens nodig.

Deze gegevens zijn opgenomen in het document App_Registratie.docx, dat beschikbaar is in de map Overig.

De belangrijkste gegevens zijn:

Het volledige bestand bevat onderstaande gegevens:

Verbinding maken met SharePoint

Een verbinding met SharePoint via de Microsoft Graph API wordt, ongeacht de gebruikte programmeertaal, in dezelfde stappen geïmplementeerd:

1. Access token aanvragen
2. Verbinding maken met de SharePoint-site
3. De map Inkomend selecteren
4. Importbestanden uploaden

In de map Overig zijn voorbeeldscripts beschikbaar voor verschillende programmeertalen. De voorbeeldscripts kunnen als uitgangspunt worden gebruikt voor een eigen implementatie.

Verwerking van importbestanden

Nadat een importbestand is geplaatst in de map Inkomend, wordt de verdere verwerking volledig door Files2Swing uitgevoerd. Tijdens dit proces worden de importbestanden gecontroleerd, verwerkt en wordt het resultaat vastgelegd in een logbestand. De verwerking bestaat uit drie opeenvolgende stappen:

Importbestanden ophalen

Bij het starten van Files2Swing wordt gecontroleerd of er in de map Inkomend importbestanden staan. Wanneer er geen bestanden aanwezig zijn, wordt het proces beëindigd. Als er wel importbestanden in de map Inkomend staan, worden deze automatisch opgehaald en in een vaste volgorde verwerkt.

Aan het begin van de verwerking wordt een logbestand gemaakt waarin alle uitgevoerde stappen worden bijgehouden.

Importbestanden verwerken

Files2Swing verwerkt de importbestanden één voor één. Tijdens de verwerking wordt gecontroleerd of het importbestand correct kan worden verwerkt in de Swing-beheeromgeving. Wanneer de verwerking succesvol verloopt, worden de gegevens geïmporteerd en wordt het bestand verplaatst naar de map Verwerkt.

Als er tijdens de verwerking een fout optreedt, wordt het betreffende bestand niet verder verwerkt. Het bestand wordt verplaatst naar de map Afgekeurd en de oorzaak van de fout wordt vastgelegd in het logbestand.

Door bestanden afzonderlijk te verwerken heeft een fout in één importbestand geen invloed op de verwerking van andere bestanden.

Proces afronden – logbestand en mailing

Na afloop van de verwerking wordt een logbestand opgeslagen in de map Log.

Het logbestand bevat een overzicht van alle verwerkte bestanden, de uitgevoerde acties en eventuele foutmeldingen. Hiermee kan eenvoudig worden gecontroleerd of de verwerking succesvol is verlopen en kan zonodig worden achterhaald waarom een importbestand is afgekeurd.

Optioneel kan het logbestand automatisch worden verzonden naar één of meerdere opgegeven e-mailadressen. Hierdoor kunnen beheerders de resultaten van iedere verwerking volgen zonder de SharePoint-omgeving te openen.

Samenvatting

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