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. ... View more

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. ... View more

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  ... View more

Gebruikersautorisaties door CEA-nummers voor Payroll Gemal Exports   Huidige situatie: Op dit moment hebben de gebruikers die geautoriseerd zijn voor het bestandstype "Payroll Gemal Exports" de mogelijkheid om de bestanden van alle CEA-nummers van de organisatie te ontvangen. Het is niet mogelijk om gebruikers te autoriseren om alleen bestanden van specifieke CEA-nummers te ontvangen. Vanaf 7 oktober 2024 komt in Bestandsuitwisseling nieuwe functionaliteit beschikbaar waarmee het toekennen van het ontvangen van specifieke CEA-nummers voor het bestandstype "Payroll Gemal Exports" mogelijk wordt gemaakt voor gebruikers.   Jouw actie: Werkt jouw organisatie niet met meerdere CEA-nummers, of mogen jullie gebruikers de informatie van alle CEA-nummers downloaden, dan hoef je niets te doen. Werkt jouw organisatie wel met meerdere ceanummers en wil je specifieke gebruikers autoriseren om alleen bestanden van bepaalde CEA-nummers te mogen downloaden, volg dan de onderstaande instructies om de autorisaties toe te kennen.   Gebruikers autoriseren voor specifieke CEA-nummers voor Payroll Gemal Exports: In Autorisatiebeheer komt per 7 oktober een nieuw recht beschikbaar: "Toegang tot Bestandsuitwisseling-instellingen" onder de applicatie "Bestandsuitwisseling".     Beheerders die voor dit nieuwe recht worden geautoriseerd, krijgen een nieuw tabblad genaamd "Instellingen" te zien in Bestandsuitwisseling.     In dit tabblad hebben beheerders de mogelijkheid om via het schuifje "Activeer autorisatie voor Payroll Gemal Export" de nieuwe functionaliteit te activeren. Deze optie is standaard uitgeschakeld omdat alle gebruikers op dit moment toegang hebben tot alle CEA-nummers van de organisatie.   Wanneer je het schuifje naar ‘Actief’ zet, voeg dan één voor één de gebruikers toe via de knop ‘Gebruiker Toevoegen’ en geef per gebruiker aan tot welk(e) CEA-nummer(s) zij toegang krijgen voor het bestandstype "Payroll Gemal Exports".   De gebruikers die op deze manier geautoriseerd worden, zullen in de “Ontvang bestanden" tab dan alleen de bestanden van dit bestandstype zien die gerelateerd zijn aan de opgegeven CEA-nummers.   Let op: de gebruikers die niet in de lijst staan, zullen geen enkel bestand van dit bestandstype in de “Ontvang bestanden" tab zien.           ... View more

Bestandsuitwisseling Test file type is gedefinieerd in Bestandsuitwisseling voor test doeleinden. Het bestandstype kan worden gebruikt om de upload en download van dummy-bestanden te testen. Dit file type kan al geautoriseerd worden via Autorisatiebeheer.   Doorloop de volgende stappen om dit file type te gebruiken:   1 - Voeg het rechten “Zend testbestanden naar Bestandsuitwisseling” en “Ontvang testbestanden van Bestandsuitwisseling” toe in Autorisatiebeheer, onder de Applicatie “Bestandsuitwisseling”.   2 - Ga naar de Bestandsuitwisseling applicatie en klik op “Send Files”. 3 - Selecteer het nieuwe bestandstype uit de keuzelijst, selecteer een dummybestand door op "Select Files" te klikken en activeer vervolgens het verzenden door op de "Upload" knop te klikken. 4 - Als het bestand succesvol is ingestuurd verschijnt het in de “Sent Files” lijst.   5 - Een paar seconden later zal het bestand ook verschijnen in de "Receive Files" sectie.  6 - klik op het download-icoon om het te downloaden.     ... View more

UPDATE 01.11.2023: Video over Bestandsuitwisseling toegevoegd waarin het gebruik en autorisatie  van Bestandsuitwisseling wordt uitgelegd. UPDATE 20.10.2023: we hebben dit artikel geupdate met de laatste informatie omdat Bestandsuitwisseling (het handmatig zenden / ontvangen van bestanden) nu ook algemeen beschikbaar is voor HR Core Education, VIPS DIsbursements en Payroll Only klanten. UPDATE 29.08.2023: we hebben dit artikel geupdate met de laatste informatie omdat Bestandsuitwisseling (het handmatig zenden / ontvangen van bestanden) nu algemeen beschikbaar is voor HR Core Online klanten.   Momenteel verzend en ontvang je bestanden van en naar Youforce via de ‘Zenden en Ontvangen’ functionaliteit middels de zogenoemde ‘IBU’ (Intracom Bestands Uitwisseling). De nieuwe manier van verzenden en ontvangen via File API en Bestandsuitwisseling is reeds beschikbaar voor HR Core Online en P&B Core klanten. Wij lichten deze toe in dit artikel.   Aan klanten die gebruik maken van andere HR Cores zullen wij op korte termijn ook informatie verstrekken. Wat is Zenden en Ontvangen en wat doet de IBU? Via ‘Zenden en Ontvangen’ ontvang (download) je bestanden vanuit Youforce, bijvoorbeeld als er een salarisrun is gemaakt. Via ‘Zenden en Ontvangen’ staat het bestand voor de loonjournaalpost klaar zodat je het kan downloaden. Je gebruikt dan de functionaliteit ‘handmatig’, jij bepaalt immers het moment. Handmatig verzenden (uploaden) naar Youforce doe je bijvoorbeeld met een mutatie-bestand (DPIA100).   De IBU is een Visma | Raet-applicatie die de daadwerkelijke down- en/of upload van bestanden naar en van Youforce bewerkstelligt. De IBU wordt door Youforce opgestart op het moment dat je het bestand ontvangt en/of verstuurt. IBU zorgt voor het verkeer tussen jouw computer en Youforce, zie de afbeelding hieronder waarin de download met de IBU plaatsvindt.   Naast de handmatige versie wordt ‘Zenden & Ontvangen’ met behulp van IBU ook geautomatiseerd ingezet. Bijvoorbeeld bij de bestanden van de BINT-koppeling of de Datafeed. Jij hoeft dan geen handeling te verrichten om een bestand te down- of uploaden naar Youforce.       Je hebt in het verleden hiervoor een Youforce-gebruiker aangemaakt en deze via ‘Zenden en Ontvangen’ gekoppeld om dit mogelijk te maken. Jouw IT-afdeling, eventueel met de hulp van een Visma | Raet-consultant, heeft dit verder geautomatiseerd.   Het onderscheid tussen ‘handmatig’ en ‘automatisch’ is belangrijk omdat het huidige ‘Zenden en Ontvangen’ met de IBU wordt vervangen door twee verschillende oplossingen. Iedere oplossing is geoptimaliseerd voor het specifieke doel.   Het handmatig verzenden en ontvangen van bestanden op basis van de IBU wordt vervangen door de nieuwe Bestandsuitwisseling-functionaliteit. Voor down- en of uploaden van bestanden via Bestandsuitwisseling heb je geen IBU meer nodig. Het geautomatiseerd ontvangen en/of verzenden van bestanden zal in de nieuwe situatie op basis van een File API gebeuren.   Waarom over en wat te doen? Waarom stoppen we met ‘Zenden en Ontvangen’ met behulp van IBU? Hiervoor hebben wij een aantal redenen:  Zero footprint. Voor de nieuwe Bestandsuitwisseling hoef je geen applicatie meer lokaal op je computer te installeren, wat in geval van de IBU wel nodig was. Het lokaal installeren van software past niet meer bij onze, maar vaak ook niet bij jullie IT-strategie. Voor de automatische up- en download: een API is een moderne en duurzame techniek die nog beter voldoet aan de huidige eisen met betrekking tot AVG en Security.  Omdat voor de File API geen Youforce-certificaat meer nodig is, is het beheer eenvoudiger en minder foutgevoelig. En tenslotte is de File API volledig gebouwd voor de cloud en wordt daardoor automatisch geschaald zodra er meer of minder capaciteit nodig is. Dit komt de prestaties ten goede.   Wanneer uitfaseren? We gaan de IBU eind 2023 geleidelijk uitfaseren. Vanzelfsprekend nemen wij jullie stap voor stap mee in deze uitfasering.        Wie doet wat? De activering voor de handmatige Bestandsuitwisseling kan gedaan worden door jullie applicatie/functioneel beheerder. Voor de automatische download (File API) is kennis van scripting nodig. Deze expertise is waarschijnlijk bij jullie IT-afdeling belegd.   Wat concreet te doen? Informeer intern de mensen die actie moeten ondernemen (denk aan diegene die de applicatie- of functioneel beheerdersrol op zich neemt en iemand van ICT die verstand heeft van scripten en schedulen) Zet de omzetting van IBU naar File API en/of Bestandstuitwisseling op je interne roadmap/agenda Vraag consultancy aan (zie volgende hoofdstuk) als je zelf niet in staat bent de migratie uit te voeren. Wij kunnen dit snel en efficiënt regelen zonder dat jij er geen omkijken naar hebt.   Hulp nodig? Wanneer je liever ontzorgd wilt worden, is het mogelijk om consultancy in te zetten. We bieden de volgende opties: een intake-gesprek met één van onze consultants. Tijdens deze intake (maximaal 1 uur, kosten € 157,50, excl btw) spreekt de consultant alle gepubliceerde informatie met je door. Tevens wordt samen met de consultant bepaald wat de impact is voor jouw organisatie, welke acties moeten worden ondernomen en wat de verwachte doorlooptijd daarvan is. Een consultancyafname van 4 uur waarin alle stappen die nodig zijn voor de geautomatiseerde download via de File API worden uitgevoerd.  Deze service kan ook afgenomen worden middels de creditbundel. Een intake aanvragen doe je eenvoudig hier.      De stappen die benodigd zijn voor de overgang naar de vervanging van handmatig zenden/ontvangen en de geautomatiseerde variant vind je hieronder. Bestandsuitwisseling voor de handmatige download en upload ‘Bestandsuitwisseling’ is ontwikkeld om handmatig bestanden uit te wisselen met Youforce.   Zie hier enkele screenshots van de nieuwe Bestandsuitwisseling.     Bekijk ook onze video waarin de nieuwe Bestandsuitwisseling wordt getoond en wordt uitgelegd hoe je deze voor je gebruikers kunt autoriseren.     De verschillende stappen voor het autoriseren van Bestandsuitwisseling zoals getoond in de video, vind je terug in het volgende hoofdstuk. Stappenplan voor de Youforce HR-professional  Volg de stappen zoals beschreven in dit artikel indien je gebruik maakt van HR Core Online. Volg de stappen zoals beschreven in dit artikel indien je gebruik maakt van HR Core Education. Volg de stappen zoals beschreven in dit artikel indien je gebruik maakt van VIPS Disbursements. Volg de stappen zoals beschreven in dit artikel indien je gebruik maakt van Payroll Only. Volg de stappen zoals beschreven in dit artikel indien je gebruik maakt van P&B Core.   Wij zullen op korte termijn ook de gebruikers van andere HR Cores informeren over de te nemen stappen. File API voor de automatische download De nieuwe wijze voor de automatische bestandsuitwisseling gaat via de File API.  De File API downloadt een bestand vanuit Youforce, vergelijkbaar zoals nu ‘Zenden en Ontvangen’ in combinatie met de IBU nu werkt.     Het opstarten van de File API doe je net als bij de IBU met een ‘script’ dat je ‘scheduled’ (automatiseert op vaste tijden).    Stappenplan voor de Youforce HR-professional en IT Voor de activering van de File API is het raadzaam een collega van de IT-afdeling te betrekken die scripts kan schrijven en kan schedulen.   We hebben een stappenplan gemaakt waarin wordt uitgelegd hoe je kan achterhalen welke bestandstypen je nu automatisch download en upload, waar en hoe je de File API aanmaakt en wat je moet doen in HR Core Online om de bestanden via de File API beschikbaar te stellen.   Het automatiseren van de File API is werk voor je IT-afdeling. Meer details hierover vind je in het stappenplan, zie ‘checklist File API’. ... View more

Nieuwe functionaliteit en verbeteringen Toegang via Autorisatiebeheer HR Core Online gebruikers en overige gebruikers maken nu gebruik van Autorisatiebeheer om toegang te krijgen tot de Bestandsuitwisseling module. Het toe te kennen recht is “Toegang tot Bestandsuitwisseling”.   File Type Autorisatie via Autorisatiebeheer Op dit moment vindt de gebruikers autorisatie voor de ondersteunde file types nog plaats via een 4me request en wordt afgehandeld door Product Development   In de nabije toekomst zal deze gebruikers autorisatie voor ondersteunde file types ook via Autorisatiebeheer verlopen, en zal het 4me request niet meer nodig zijn.   Nieuw Test File Type: Bestandsuitwisseling Test Een nieuw file type is gedefinieerd in Bestandsuitwisseling voor test doeleinden. Dit file type kan al geautoriseerd worden via Autorisatiebeheer.   Op dit moment kan het file type worden gebruikt om te testen of bestanden correct worden ingezonden door Bestandsuitwisseling. Doorloop de volgende stappen om dit file type te gebruiken:   1 - Voeg het nieuwe recht “Bestandsuitwisseling Test - Zenden” toe in Toegangsbeheer, onder de Applicatie “Bestandsuitwisseling”.    2 - Ga naar de Bestandsuitwisseling applicatie en click op “Send Files”. 3 - Selecteer het nieuwe file type in de dropdown en Zend een willekeurig test bestand.    4 - Als het bestand succesvol is ingestuurd verschijnt het in de “Sent Files” lijst ... View more

Visma Connect en File API zal onderhevig zijn aan gepland onderhoud tijdens 21 Juni 2023 01:00-03:00 CEST.    De File API en Youforce API's zullen worden beïnvloed.   We verontschuldigen ons voor mogelijk ongemak. ... View more

In dit voorgaande artikel hebben we het uitfaseren van het Youforce Developer Portal gecommuniceerd en de benodigde stappen aangegeven om uw Applicaties te migreren naar het nieuwe Visma Developer Portal.    Het Youforce Developer Portal zal met ingang van 1 Juni offline gaan en niet meer gebruikt kunnen worden. We raden u aan om voor deze datum uw Applicaties te migreren naar het Visma Developer Portal om te voorkomen dat er onderbrekingen optreden in uw geautomatiseerde bestandsuitwisseling.   Tegelijkertijd zullen de basis URL’s voor de File API offline gaan. De nieuwe File API basis URL is https://fileapi.youforce.com/v1.0   Uw actie:  Controleer samen met uw IT afdeling: Of uw Applicaties zijn aangemaakt in het Visma Developer Portal Dat uw Applicaties de nieuwe File API basis URL gebruiken.   In onderstaande tabel staan de oude File API URL’s, de vervangende nieuwe URL en de uiterste datum waarop de wijziging moet hebben plaatsgevonden.   Oude URLs Nieuwe URL Deadline https://api.raet.com/mft/v1.0 https://fileapi.youforce.com/v1.0 1 Juni https://api.youforce.com/mft/v1.0 https://fileapi.youforce.com/v1.0 1 Juni ... View more

De Youforce File API zal op 17 Mei 2023 tussen 01:00-03:00 CEST gepland onderhoud ondergaan. De service zal gedurende ongeveer 30 minuten niet beschikbaar zijn.   De File Exchange module zal gedurende het onderhoud ook niet beschikbaar zijn omdat er geen bestanden kunnen worden uitgewisseld.   Zie ook onze status pagina https://status.visma.com/ voor meer informatie. ... View more