Releases Youforce API & bestandsuitwisseling

  Dit zijn de fixes sinds versie 1.24: Probleem opgelost bij het downloaden in Chunks (delen) Het automatisch opnieuw downloaden bij fouten tijdens de download herkent nu naast status 500 Server Fout, ook status 499 (client disconnect) De ChunkSize limiet is verhoogt naar 1000 MB. Dit betekent dat bestanden tot 1000 MB grootte nu met 1 request kunnen worden gedownload. Afhankelijk van jouw infrastructuur kan het aan te bevelen zijn om een kleinere ChunkSize in te stellen. Dit doe je in het config.xml bestand.   Volg de instructies in ons kennisbank artikel om de nieuwste scripts (1.25) te installeren.

Deze releasenotes zijn technisch van aard en bedoeld voor File API-ontwikkelaars die direct met de File API integreren of bekend zijn met de technische werking ervan. Deel deze release notes graag met de IT-afdeling van jullie organisatie.   Inleiding   De file API maakt op dit moment gebruik van het veilige OAUTH 2.0 protocol om gebruikers te authenticeren en bestanden uit te wisselen. Dit OAUTH 2.0 protocol is een wereldwijde standaard voor gegevensuitwisseling via API’s en wordt beschouwd als zeer veilig. Een 100% veiligheid is in onze huidige IT wereld echter moeilijk te garanderen. We proberen dan ook steeds de kansen op gegevensverlies nog verder  te minimaliseren. Zo is er ook voor het OAUTH 2.0 protocol een uitbreiding bedacht die deze kansen nog verder minimaliseert, de DPOP-token implementatie. Het implementeren van het DPoP token vereist een programmatische aanpassing aan de klantzijde. Daarom is deze optie vooral bedoeld voor klanten die zelf software ontwikkelen/hebben ontwikkeld voor gebruik met de File API. Neem zo nodig contact op met je IT afdeling of dit voor jullie een optie is. Gebruiken jullie op dit moment de powershell scripts om met de File API te communiceren, houd dan dit kanaal in de gaten. In de nabije toekomst zullen we het DPoP-token ook in de powershell scripts implementeren.   Huidige situatie Momenteel ondersteunt de File API geen DPoP-tokens als OAuth-bewijstype.   Nieuwe situatie Vanaf vandaag, 26 februari 2025, worden DPoP-tokens ook ondersteund.   Jouw actie: Indien je er zorg voor wilt dragen dat uitsluitend de rechtmatige ‘client’ een specifiek toegangstoken kan gebruiken, kun je de DPoP-stroom implementeren in je File API applicatie. Zodra de wijzigingen aan jullie kant zijn geïmplementeerd, kan je de onderstaande toggle activeren in het Visma Developer Portal → My Applications → Details. Deze wijziging zorgt voor een nog betere beveiliging van jouw File AP integratie.   Officiële specificatie: RFC 9449 - OAuth 2.0 Demonstrating Proof-of-Possession (DPoP) Ondersteunde cryptografische algoritmen: Onze implementatie hanteert strikte beveiligingsmaatregelen en ondersteunt uitsluitend de volgende cryptografische algoritmen: RSA: RS256, RS384, RS512, PS256, PS384, PS512 ECDSA: ES256, ES384, ES512 Het gebruik van het algoritme 'none' wordt expliciet geweigerd. Unieke identificator voor de DPoP-proof JWT: Deze implementatie bevat een validatie om reply-aanvallen te voorkomen. Hiervoor worden de waarden die in de jti-claim worden verzonden gedurende het geldigheidsvenster opgeslagen, zodat wordt gewaarborgd dat deze waarde uniek is en slechts één keer wordt gebruikt. Zorg ervoor dat je bij elke aanvraag een unieke GUID opgeeft in de jti-claim.

Deze release notes zijn van technische aard en bedoeld voor File API ontwikkelaars die rechtstreeks met de File API integreren of de technische werking van de File API kennen. Deel deze release notes met jouw IT afdeling.   IP Whitelisting voor File API Applicaties Huidige Situatie  Momenteel ondersteunt de File API geen IP-whitelisting, dus jouw File API-verzoeken kunnen overal worden gedaan.   Nieuwe Situatie Vanaf heden, 22 oktober 2024, is de ondersteuning van IP whitelisting beschikbaar, dus als je dat wenst, kun je deze configuratie nu al aanvragen voor jouw File API applicatie en jouw publieke IP(s) om de veiligheid van File API verzoeken te vergroten.   Jouw Actie:  Maak een 4me-verzoek aan met de onderstaande informatie:   Jouw openbare IP-adressen in CIDR-indeling (bijvoorbeeld: 192.0.2.0/24) vanwaar met de File API wordt gecommuniceerd. Jouw ClientId dat wordt gebruikt om bij de File API te authenticeren.

Deze release notes zijn van technische aard en bedoeld voor File API ontwikkelaars die rechtstreeks met de File API integreren of de technische werking van de File API kennen. Deel deze release notes met jouw IT afdeling.   File API Healthcheck Endpoint Huidige Situatie   Een goede gewoonte bij het gebruik van API's is het controleren van hun status voordat ze daadwerkelijk worden aangeroepen. Momenteel is de enige manier om erachter te komen of de File API operationeel is, het aanroepen van een van de beschikbare eindpunten (bijvoorbeeld het List-eindpunt) en het controleren van het resultaat. Als het resultaat een fout is, moet uw uitwisselingsproces de fout afhandelen..   Een betere manier is om de status van de File API te controleren voordat u uw uitwisselingsproces start. Om dit te vergemakkelijken en verbeteren hebben we een nieuw “Health Check”-eindpunt geïntroduceerd dat kan worden aangeroepen voordat uw uitwisselingsproces begint. Nieuwe situatie   Vanaf heden, 22 oktober 2024, is het ‘Health Check’ eindpunt beschikbaar om de status van de File API te controleren.   Dit nieuwe eindpunt vertelt je of de File API volledig operationeel is of dat er sprake is van een storing. In geval van een storing kunt u uw uitwisselingsproces uitstellen tot een later tijdstip.   Het eindpunt kan op 3 verschillende manieren worden gebruikt:   Handmatig (bijv met Postman) om de beschikbaarheid op een willekeurig moment te kunnen controleren. Automatisch (als onderdeel van uw monitoringsysteem) om regelmatig de status van de File API te controleren. Automatisch (als onderdeel van uw uitwisselingsproces) vlak voordat uw geautomatiseerde uitwisselingsproces begint. In de toekomst zullen de resultaten van de health check ook in Youforce worden weergegeven, waardoor de handmatige verificatie veel sneller en intuïtief zal verlopen.   Response van het ‘Health Check’ eindpunt   Het eindpunt retourneert de algemene status van de File API en de status van elk individueel eindpunt.  De mogelijke waarden voor de algemene status van de File API zijn:   Operational: Wanneer de status van alle eindpunten “healthy” is. Major Outage: Wanneer de status van een van de meest gebruikte eindpunten ‘unhealthy’ is. De meest gebruikte eindpunten zijn:  Publisher UploadMultipart Subscriber Delivery Subscriber List Subscriber Download Partial Outage: Wanneer de status van de meest gebruikte eindpunten ‘healthy’ is, maar de status van een van de minder gebruikte eindpunten ’unhealthy’ is. De minder gebruikte eindpunten zijn: Publisher UploadResumable Publisher List Publisher Download Subscriber DownloadByChunks Subscriber Delete Jouw Actie  Als u het Health Check-eindpunt wilt gaan gebruiken om de status van de File API te controleren, volgt u de stappen zoals die worden uitgelegd in onze technische File API-documentatie.  Zie onderstaande technische links: File API documentation  File API Swagger  File API Postman Collection 

Na vele aankondigingen is het dan uiteindelijk zover! Sinds dinsdag 2 april 2024 om 18:00 uur is het niet meer mogelijk om van de IBU gebruik te maken. Dit geldt zowel voor de interactieve IBU die je via Zend/Ontvang gebruikte, als ook voor de StandAlone IBU die automatisch je bestanden inzond en/of ophaalde. Vanaf nu zijn Bestandsuitwisseling en File API de nieuwe tools waarmee je bestanden met Youforce uitwisselt.   Lees voor de laatste informatie ons recent gepubliceerde nieuws artikel.  

Dit zijn de fixes sinds versie 1.22: Het upload script logde nog niet in de Monitor file. Dit is verholpen. Verbeterde afhandeling bij het verwijderen van tijdelijke bestanden Bug opgelost waarbij het genoemde aantal bestanden voor uploaden verkeerd werd getoond als er maar 1 bestand klaar stond om te uploaden. Upload script maakte log bestand aan met de verkeerde naam. Dit is verholpen. Volg de instructies in ons kennisbank artikel om de nieuwste scripts (1.24) te installeren.    

Op 19-02-2024 hebben wij een nieuwe versie (1.22) van de PowerShell scripts gepubliceerd met de volgende verbeteringen: Vermelding van de minimale vereiste .NET versie 4.8 in de readme bestanden. Verbetering van het download proces. Verplicht gebruik van TLS 1.2 toegevoegd in het Upload script. Vermelding van versies van: de PowerShell scripts, Windows en .NET versie tbv een betere ondersteuning. Je vind de PowerShell scripts hier.  

Nieuwe functionaliteit en verbeteringen in Powershell Voorbeeld Scripts  Support voor logbestanden Upload in blokken verhoogt bestandsgrootte limiet voor zenden van 100MB naar 10GB Download in blokken verhoogt bestandsgrootte limiet voor ontvangen van 2GB naar 10GB Verbeterde betrouwbaarheid Toegevoegd: Standaard Proxy Settings detectie Commentaar toegevoegd  Configureer logbestanden in upload en download voorbeelden   Er is een nieuwe sectie toegevoegd aan het configuratiebestand van de voorbeelden om logbestanden te kunnen configureren.     Volg deze stappen om de logbestanden te configureren:   1 - Download de laatste versie van de Powershell voorbeelden hier  2 - Pas in de config.xml de setting : “Logs” - “Enabled” aan met waarde “true” 3 - Pas in de config.xml de setting : “Logs” - “Path” aan met de directory waar de logbestanden worden opgeslagen. 4 - Pas in de config.xml de setting: “Logs” - “MonitorFile” aan met de naam van de Monitor file. De Monitor file wordt opslagen in dezelfde directory waar de logbestanden worden opgeslagen.   Voor de gedetailleerde logbestanden wordt elke dag een nieuw bestand aangemaakt. Het Monitor bestand behoudt altijd dezelfde naam en bevat, i.t.t. de andere logbestanden, alleen die regels die nodig zijn om te beoordelen of de scripts correct functioneren of dat er fouten zijn opgetreden. Het Monitor bestand is met name geschikt voor geautomatiseerde controle op het correct functioneren van de scripts en voor fout detectie. Bij fouten kan het gedetailleerde logbestand meer informatie geven over de mogelijke oorzaak van de opgetreden fout. Voor verdere bijzonderheden lees de Readme bij de powershell voorbeelden. Readme Upload voorbeeld  Readme Download voorbeeld    Upload voorbeeld uitgebreid met uploaden in blokken (chunks)   Een verbetering in het upload voorbeeld zorgt er voor dat bestanden nu in blokken worden verzonden. Met deze nieuwe functionaliteit wordt de bestandsgrootte limiet voor in te zenden bestanden verhoogt van 100MB naar 10 GB.   Een nieuw veld (<ChunkSize>) is toegevoegd aan de configuratie waarmee de blokgrootte kan worden geconfigureerd.  De aanbevolen blokgrootte (beste performance) voor inzenden is 4MB.   Volg deze stappen om inzenden met blokken te configureren:   1 - Download de laatste versie van de Powershell voorbeelden hier  2 - Pas in de config.xml de setting : “Upload” - “ChunkSize” aan met waarde “4”   Voor verdere bijzonderheden lees de Readme bij het powershell voorbeeld. Readme Upload voorbeeld  Download voorbeeld uitgebreid met downloaden in blokken (chunks)   Een verbetering in het download voorbeeld zorgt er voor dat bestanden nu in blokken worden ontvangen. Met deze nieuwe functionaliteit wordt de bestandsgrootte limiet voor te ontvangen bestanden verhoogt van 2GB naar 10 GB.   Een nieuw veld (<ChunkSize>) is toegevoegd aan de configuratie waarmee de blokgrootte kan worden geconfigureerd.  De aanbevolen blokgrootte (performance) voor ontvangen is 100MB.   Volg deze stappen om ontvangen met blokken te configureren:   1 - Download de laatste versie van de Powershell voorbeelden hier  2 - Pas in de config.xml de setting : “Download” - “ChunkSize” aan met waarde “100”   Voor verdere bijzonderheden lees de Readme bij het powershell voorbeeld. Readme Download voorbeeld  Verbeteringen in Betrouwbaarheid   De betrouwbaarheid van de scripts is verbeterd door voor elk request een retry mechanisme te implementeren zodat bij een mogelijke internet en/of server fout de bestandsoverdracht niet direct stopt, maar dat het request nog een keer wordt geprobeerd.   Proxy Server settings Er is code aan de scripts toegevoegd zodat uw standaard Proxy Server settings automatisch worden gedetecteerd.   Commentaar toegevoegd De scripts zijn voorzien van meer commentaar om de code/functionaliteit van de verschillende onderdelen van de scripts duidelijker te maken.