Introductie
Voor de overgang van de IBU (Automatisch) naar File API kun je de volgende opties in overweging nemen:
Je kunt dit volledig zelf doen
Consultancy afspraak van een uur waarin wij de file API en benodigde stappen uitleggen.
Consultancy afspraak van 4 uur (Intake 1 uur + 3 uur verdere inrichting) waarin we onderstaande stappen gezamenlijk doorlopen.
Voor optie 2 en 3 (het inplannen van een consultancy afspraak) kan je in Mijn Support een nieuwe aanvraag indienen, kiezen voor soort consultancy (API), optie Aanvraag consultancy en vervolgens de benodigde informatie velden invullen.
Indien je ervoor kiest om de inrichting zelf te doen, volg dan onderstaande stappen zoals beschreven in dit artikel:
Inventariseer om welke bestanden het gaat.
Maak een account aan op het Visma Developer Portal
Maak een applicatie aan op het Visma Developer Portal
Maak een invitatiecode aan op Visma Developer Portal
Dien een ticket in via ‘Mijn support’
Pas zonodig de modules aan om gebruik te maken van File API
Implementeer de nieuwe File API oplossing in uw eigen omgeving.
1 - Inventariseer om welke bestanden het gaat
Jullie Customer Success Manager heeft inzicht in het gebruik van IBU en kan daar op verzoek een lijst van aanleveren.
2 - Account aanmaken op Visma Developer Portal
De Visma Developer portal is te bereiken via
https://oauth.developers.visma.com/service-registry/home
en maak via Create account een account aan
De portal zal via
[email protected] je een e-mail sturen met een Activatie account link.
Gebruik bij het registreren het Kvk-nummer als Organization number
Startscherm na inloggen
Desgewenst kun je een collega toevoegen via My team en New member. Jullie hebben dan beiden inzicht in de gegevens van de applicatie.
De volgende stap is het aanmaken van een applicatie (zie stap 3).
3 - Een applicatie aanmaken
Door een applicatie aan te maken ontstaat er een API Key en een Secret Key die je gebruikt om de authenticatietoken op te halen.
Bij het inrichten van de File API vragen we je om een aparte applicatie aan te maken per file type (bijv. Datafeed, Aktes Export). Volg de stappen 3 tot en met 5 uit dit document voor elke applicatie die je aanmaakt.
Kies via het tabblad My Applications voor Add Application
Als application type selecteer Service, dit is het enige type wat door Visma|Raet wordt ondersteund.
Het aanmaken van de applicatie gaat via vier tabbladen, vul de gegevens in op het eerste tabblad Details. Weet dat de opgegeven Client Id wordt gebruikt als API key bij de API-aanroepen.
Je moet zelf de Client Id opgeven en om je bij vragen sneller van dienst te kunnen zijn, vragen wij je om bij het inrichten van de File API de waarde alsvolgt te kiezen: VRA_fileapi_6412345_Datafeed oftewel VRA_fileapi_ met daarachter je Visma|Raet-klantnummer en file type.
De 'isv'-prefix wordt standaard altijd toegevoegd
Let op: De Applicatienaam en Client Id heb je nodig in stap 5 om de autorisatie aan te vragen.
Let op:
Testomgeving - Indien je de API wilt koppelen aan jullie eigen testomgeving vragen wij je om bij het inrichten van de File API de waarde als volgt te kiezen:
VRA_fileapi_6412346_BINT
oftewel VRA_fileapi_ met daarachter je Visma|Raet-klantnummer van de testomgeving en file type.
Om je File API inrichting te testen kun je tevens gebruik maken van onze sandbox. Met deze sandbox kun je 3 dummy files ontvangen en ook testbestanden insturen. De applicatie voor de productieomgeving kan ook gekoppeld worden aan deze sandbox. Maak hiervoor een 2e invitatie code aan in stap 4.
Via deze applicatie met bijbehorende Client Id en Secret krijg je toegang de data en of bestanden uit de Youforce/HRCoreEducation-omgeving(en). Eén API key-set kan toegang geven tot meerdere klantomgevingen.
Via de Tenant Id die je als Header meestuurt bij het aanvragen van een authenticatie token bepaal je de benodigde klantomgeving.
Access Token Lifetime mag op de default waarde blijven staan. Een aanpassing van deze waarde heeft geen effect op werking van de API, alsmede de opties Include JSON Web Token ID en TestApplication.
Gebruik eerst Save as a draft om vervolgens de applicatie aan te maken via Create, via Next ga je naar het volgende tabblad.
Het tabblad Credentials stelt je in staat om de API Secret aan te maken. Let op, de Secret waarde wordt alleen getoond via de pop up bij het aanmaken, dus neem dit direct over. De pop up toont ook je eerder gekozen ID (API key).
Let op: Wordt de bestaande secret vergeten dan dien je een nieuwe aan te maken, deze wordt dan toegevoegd.
Via het tabblad Integrations selecteer je Youforce File (voor de bestanden), oftewel je ‘basis’ API, je gebruikt hiervoor New integration.
Visma | Raet zal de opgegeven API’s goedkeuren. Dit gaat via een workflow in de portal, je hoeft daar niks voor te doen. De goedkeuring door Visma | Raet kan enkele dagen duren.
Per API dien je de Scope(s) te selecteren welke gebruikt gaat worden in deze applicatie. Op deze manier kun je bepaalde functionaliteiten binnen de Youforce API uitsluiten van je applicatie. Je kunt vanzelfsprekend ook alle Scopes selecteren, maar een API kan ook slechts 1 Scope gebruiken.
Onder het volgende screenshot vind je een tabel met de beschikbare scopes voor de verschillende file types.
Scopes
Betekenis
businesstypes list
In de toekomst zal deze scope inzenders en ontvangers toestaan om informatie te krijgen over file types (businesstypes).
Op dit moment is het alleen mogelijk voor een inzender om op te vragen of er een ontvanger is voor een specifieke tenant/file type combinatie.
files delete
Deze scope staat ontvangers toe om bestanden te verwijderen die je niet wilt downloaden.
files download
Deze scope staat ontvangers toe om bestanden te downloaden, alsook inzenders om bestanden die zij zelf geüpload hebben te downloaden.
files upload
Deze scope staat inzenders toe om bestanden te uploaden.
files list
Deze scope staat ontvangers toe om bestanden weer te geven die klaar staan voor ontvangen, alsook inzenders voor de bestanden die zij zelf geüpload hebben.
Onderstaande tabel bevat alle beschikbare file types en de scopes die beschikbaar zijn voor dat file type. Kies het file type waar je de applicatie voor aan het aanmaken bent en maak een keuze uit de scopes die daarvoor beschikbaar zijn.
(Meerdere opties zijn dus mogelijk)
Tabel file types
HR Core Education gebruik makend van de IBU
IBU: Module Id - Naam
File API: File Type Id - Name
Scopes
3 - Payroll Gemal Engine - Download
128001 - Payroll Gemal Exports
businesstypes list
files delete
files download
files list
17 - PayrollZend - Upload
129001 - Gemal Direct import Integratiebestanden (WIG*.im)
businesstypes list
files upload
files download
files list
34-Betaalmanager Downloads - Download
135000 - RBM Gemal Downloads (csv)
businesstypes list
files delete
files download
files list
36-Betaalmanager Opdrachten - Download
135001 - RBM Gemal Payment Files (xml, zip)
businesstypes list
files delete
files download
files list
33 - Salarisdossier - Download
106000 - Salarisdossier Gemal Export
businesstypes list
files delete
files download
files list
35 - Personeelsdossier - Upload
107003 - Personeelsdossier Imports
businesstypes list
files upload
files download
files list
38 - Personeelsdossier - Download
107001 - Personeelsdossier Exports
businesstypes list
files delete
files download
files list
41 - Gebruikersbeheer - Upload
121003 - IAM XSSO
businesstypes list
files upload
files download
files list
80 - HR Core Edu Bulk Import - Upload
120000 - HRCE Bulk import
businesstypes list
files upload
files download
files list
81 - Management Informatie - Download
117000 - MI Education Datafeed Exports
businesstypes list
files delete
files download
files list
81 - Management Informatie - Download
117001 - MI Education Aktes Exports
businesstypes list
files delete
files download
files list
81 - Management Informatie - Download
120001 - HR Core Declaration Exports
businesstypes list
files delete
files download
files list
82 - Management Informatie - Upload
117004 - MI Education Akte Imports
businesstypes list
files upload
files download
files list
Het tabblad Integrations kan je niet direct bevestigen via Save, dat kan pas op het moment dat Visma|Raet de gekozen API’s bij de applicatie heeft goedgekeurd, dit gaat via een flow je hoeft hier niks voor te doen.
Je moet wachten op de bevestigings email van de goedkeuring door Visma|Raet voordat je met de volgende stappen verder kunt gaan.
Je kan door te klikken op de knop ‘Visma App store’ naar de laatste stap.
Tabblad Visma App Store
Voor toegang tot de klantdata genereer je straks in stap 4 een Invitatie Code. Hiervoor moet in de Visma App Store eerst het Access level - Audience configureren.
Na Start setup for Visma App Store ziet u onderstaand scherm en dan kies je bij Access level - Audience voor Invite only
Je bent nu klaar met het aanmaken van de applicatie, de optie Save is zichtbaar op het moment dat Visma | Raet de applicatie heeft goedgekeurd. Zo niet dan kun je dit scherm sluiten door bijvoorbeeld op Back to my Applications te klikken.
4 - Invitatiecode aanmaken
Met een invitatiecode maak je het mogelijk de klantgegevens op te halen via je applicatie.
Ga naar de Developer Portal https://oauth.developers.visma.com/service-registry/home
Kies voor My Applications. En klik op het potloodje achter de applicatie (Edit).
Kies voor het tabblad Visma App Store. En vervolgens New Invitation Code.
Bij Invitation description vul je de naam van de betreffende klant in. En klik vervolgens op Generate.
Let op: De Invitation Code heb je nodig in stap 5 om toegang te vragen tot de klant-data.
Visma | Raet zal de toegang tot de klant-data goedkeuren en dan direct de koppeling van klantdata aan je applicatie gereedmaken.
Binnen het beheer van je applicatie en het scherm Integrations is via de tabblad Tenants (default wordt het tabblad Scopes getoond) terug te zien welke klanten (tenants) gekoppeld zijn aan je applicatie. Dit scherm laat ook de bijbehorende TenantID zien. De TenantID is benodigd bij het opvragen van de authenticatie token.
Voorbeeld van een Tenant ID
5 - Dien een ticket in via Mijn Support
Dien ticket in via Mijn Support met de invitation code en het verzoek om autorisatie voor de File API.
Vermeld in het ticket de volgende gegevens:
Klantnummer:
Je Visma|Raet relatienummer
Naam IT medewerker
Degene die de File API bij jullie installeert
Telefoonnummer IT medewerker
Email IT medewerker
Invitatiecode
Deze code heb je aangemaakt in stap 4
Client Id
De Client Id heb je aangemaakt in stap 3
Applicatienaam
De Applicatienaam heb je aangemaakt in stap 3
File type
Het file type wat je met deze applicatie gaat zenden of ontvangen. Bijv 117000 - MI Education Datafeed Exports
6 - Pas systemen aan om gebruik te maken van File API
Als je Payroll Gemal Direct en/of Betaalmanager gebruikt dan moet je deze applicaties configureren voor de File API.
Zie deze link voor meer informatie per module.
Voor andere modules hoef je niets te doen.
7 - Implementeer de nieuwe File API oplossing in uw eigen omgeving.
Vraag een IT collega met verstand van schedulen en het opstellen van powershell scripts om het stappenplan te volgen.
Je vind de voorbeeld powershell scripts op deze pagina.