Swing API - FilesToSwing

Gewijzigd op Vr, 12 Apr om 11:42 AM

Inleiding

In deze beknopte handleiding staat beschreven hoe er door middel van een API geautomatiseerd bestanden naar uw Swing versie kan worden verstuurd. Het versturen van bestanden gaat via de webpagina https://upload.swing.eu. Binnen deze webpagina is een API beschikbaar waarmee bestanden vanuit uw backend systeem kunnen worden verzonden naar Swing, de inrichting van dit proces kunt u zelf bepalen zodat de bestanden geautomatiseerd in de Swing versie worden geïmporteerd. Het gaat hierbij om data en metadata bestanden. De structuur van deze bestanden moet volgens de specificaties van Swing Studio zijn, deze zijn te vinden in de Swing Studio handleiding. Een voorbeeld van het format van deze bestanden kunt u hier vinden. Een eenvoudige manier om te testen of de bestanden voldoen, is deze te importeren in uw Swing beheer omgeving (Studio). In de log kunt u zien of eventuele fouten zijn opgetreden.

Deze handleiding is geschreven voor IT medewerkers / applicatiebeheerders en bevat technische informatie. Ook worden een aantal voorbeelden gegeven voor het aanroepen van de API. Deze zijn middels een .zip file aan u verzonden of kunt u zelf downloaden.

Instructie

Om de API te gebruiken heeft u een API sleutel nodig. Deze ontvangt u van de Swing Helpdesk zodra de API voorziening voor uw versie is ingericht. De API sleutel moet u bij het aanroepen van de API en versturen van bestanden meesturen. Onderstaand is aangegeven hoe dat werkt.

/Api/ProjectUpload

Deze call is om bestanden naar een Swing database te sturen. Voor deze aanroep is het mogelijk om direct bestanden te sturen via multipart/form-data, maar het is ook mogelijk om direct CSV/JSON te uploaden.

Alle onderstaande voorbeelden zijn te vinden in de .zip file met voorbeelden.

Hieronder een voorbeeld voor multipart/form-data:

HTML (ExampleProjectRequest.html)

C# (ExampleProjectRequest.cs)

R (ExampleProjectRequest.r)

Postman (ExampleProjectRequest.json)

Het postman voorbeeld bestand kan worden geïmporteerd in Postman https://www.postman.com/. Postman is een gratis programma voor het testen van API’s .

Parameters voor Files2Swing

De ProjectUpload call kan gebruik maken van de import functionaliteit van Files2Swing. Voor deze kunnen een aantal optionele parameters worden opgegeven, die ook door de import functionaliteit in Swing Studio beschikbaar zijn:

adjustStartAndEndperiod: Automatisch start- en eindperioden van geïmporteerde onderwerpen aanpassen.

appendData: Records met dezelfde kenmerken automatisch totaliseren (alleen mogelijk bij absolute waarden, niet mogelijk bij gegevenstype: Data - Waarde per record).

deleteEmptyAndNvtDataRecords: Data records met alleen NVT(-99998) of EMPTY (-99996) waarden verwijderen.

skipRecordsWithUnknownDimItems: Records met onbekende kenmerken overslaan, zoals onbekende geoitems.

clearData: Eerst alle data verwijderen (van de onderwerpen in het importbestand).

clearDataFromImport: Alleen data voor combinaties van onderwerp, periode en geolevel die in het import bestand bestaan, worden eerst verwijderd.

Met true/false kan een parameter geactiveerd worden. Onderstaand een voorbeeld waarbij de parameters worden toegepast. In dit geval wordt eerst de data van de geimporteerde onderwerpen uit de database verwijderd en de start- en eindperioden van de betreffende onderwerpen worden niet aangepast:

https://upload.swing.eu/api/projectupload?adjustStartAndEndperiod=false&clearData=true

phases: Bij het opzetten van de files2swing functionaliteit wordt bepaald of de test (admin), live of beide omgevingen moeten worden geüpdatet. Met de phases parameter (live/admin) kan dit overruled worden. De admin versie zal bij gebruik van deze parameter altijd geüpdatet worden.

Alleen bijwerken van admin:

https://upload.swing.eu/api/projectupload?phases=admin

email: Bij het opzetten van de files2swing functionaliteit wordt opgegeven wie een email notificatie moeten krijgen. Met deze parameter kunnen email adressen toegevoegd worden. Dit kunnen meerdere mail adressen zijn, gescheiden door ;.

https://upload.swing.eu/api/projectupload?email=user1@upload.com;user2@upload.nl

Werking van OTAP versie met phases parameter

Indien de Studioversie een OTAP versie betreft, dus met een test/accept/live omgeving, dan kan middels parameters opgegeven worden naar welke omgeving ("phase") geüpdatet moet worden. De admin versie wordt altijd bijgewerkt en men kan kiezen om alleen de accept of live versie, of allebei bij te werken. Dit kan door het toevoegen van een parameter "phases" achter de URL. Deze kan gescheiden door een komma opgegeven worden.

Alleen bijwerken van admin:

https://upload.swing.eu/api/projectupload?phases=admin

Bijwerken admin en accept versie:

https://upload.swing.eu/api/projectupload?phases=accept

Bijwerken admin,accept en live versie:

https://upload.swing.eu/api/projectupload?phases=accept,live

Resultaat

Indien alles goed is verlopen is het resultaat een HTTP 200. Er kan natuurlijk ook iets mis gaan, de volgende foutmeldingen zijn mogelijk:

HTTP 400: Gegevens zijn incompleet of bestand ontbreekt.

HTTP 403: Het request bevat een ongeldige API sleutel.

HTTP 415: Het request is niet in het juiste format.

Indien u naar aanleiding van deze instructie nog aanvullende vragen heeft neem dan gerust contact op de Swing helpdesk.

Contactgegevens Swing-helpdesk

E-mailadres: helpdesk@swing.eu

Telefoonnummer Nederland: +31 15 2799399

Telefoonnummer België: +32 78 480935