Mijn Communities
Help

Van IBU naar File API - HR Core Online - Aan de Slag

12-10-2022 13:33 (Bijgewerkt op 03-11-2023)
  • 1 Antwoorden
  • 4 kudos
  • 8753 Weergaven

 

Introductie

Voor de overgang van de IBU (Automatisch) naar File API kun je de volgende opties in overweging nemen:  

  1. Je kunt dit volledig zelf doen
  2. Consultancy afspraak van een uur waarin wij de file API en benodigde stappen uitleggen.
  3. 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:

  1. Inventariseer om welke bestanden het gaat.
  2. Maak een Account aan op Visma Developer Portal
  3. Maak een applicatie aan op Visma Developer Portal
  4. Maak een Invitatiecode aan op Visma Developer Portal
  5. Dien een ticket in via ‘Mijn support
  6. Pas systemen aan om gebruik te maken van File API
  7. 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

 

WeslyvanHorssen_0-1665574102670.png

 

WeslyvanHorssen_1-1665574102698.png

 

 

De portal zal via do.not.reply@mail.connect.visma.com  je een e-mail sturen met een Activatie account link.

 

Gebruik bij het registreren het Kvk-nummer als Organization number

WeslyvanHorssen_2-1665574102609.png

 

 

Startscherm na inloggen

WeslyvanHorssen_3-1665574102737.png

 

 

Desgewenst kun je een collega toevoegen via My team en New member. Jullie hebben dan beiden inzicht in de gegevens van de applicatie.



WeslyvanHorssen_4-1665574102732.png

 

 

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 gebruik van de File API vragen we je om een aparte applicatie aan te maken per business type (bijvoorbeeld BINT, Datafeed, DPIA100).

 

Kies via het tabblad My Applications voor Add Application

WeslyvanHorssen_5-1665574102789.png

 

Als application type selecteer Service, dit is het enige type wat door Visma|Raet wordt ondersteund.

WeslyvanHorssen_6-1665574102606.png

 

 

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, om je bij vragen sneller van dienst te kunnen zijn, vragen wij je om bij het gebruik van de File API de waarde alsvolgt te kiezen:
VRA_fileapi_6412345_BINT
oftewel VRA_fileapi_ met daarachter je Visma|Raet-klantnummer en business type. 

 

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 gebruik van de File API de waarde als volgt te kiezen:

VRA_fileapi_6412345_BINT

oftewel VRA_fileapi_ met daarachter je Visma|Raet-klantnummer van de testomgeving en business type. 

 

Het is tevens mogelijk om gebruik te maken van onze sandbox. Met deze sandbox kun je 3 dummy testfiles testen. De applicatie voor de productieomgeving kan ook gekoppeld worden aan de sandbox. Maak hiervoor een 2e invitation code aan. 

 

Via deze applicatie met bijbehorende Client Id en Secret krijg je toegang de data en of bestanden uit de Youforce/HRCoreOnline-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.

 

WeslyvanHorssen_7-1665574102801.png

 

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.

CristoAmezcua_0-1690786954619.png

 

 

Via het tabblad Integrations selecteer je Youforce File (voor de bestanden), oftewel je ‘basis’ API, je gebruikt hiervoor New integration.

 

WeslyvanHorssen_9-1665574102614.png

 

 

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.

 

WeslyvanHorssen_0-1665578548032.png

 

 

Per API dien je de Scope te selecteren welke gebruikt gaat worden in de applicatie. Op deze manier kun je bepaalde functionaliteiten (endpoints) binnen de Youforce API uitsluiten van je applicatie. Je kunt vanzelfsprekend ook alle Scopes selecteren, een API kan ook bestaan uit 1 Scope.

 

WeslyvanHorssen_1-1665578597760.png

 

Scopes

Betekenis

businesstypes list 

In de toekomst zal deze scope publishers en subscribers toestaan om informatie te krijgen over businesstypes.

Op dit moment is het alleen mogelijk voor een publisher om op te vragen of er een subscriber is voor een specifieke tenant/businesstype combinatie.

files delete

Deze scope staat subscribers toe om bestanden te verwijderen

files download

Deze scope staat subscribers toe om bestanden te downloaden, alsook publishers om bestanden die zij zelf geüpload hebben te downloaden.

files upload

Deze scope staat publishers toe om bestanden te uploaden.

files list

Deze scope staat subscribers toe om bestanden weer te geven, alsook publishers voor de bestanden die zij zelf geüpload hebben.


  • Gebruik onderstaande tabel voor het selecteren van de scopes:

Tabel filetypes

 

HR Core Online gebruik makend van de IBU Unattended (Automatisch)

IBU: Module Id - Naam

File API: Business Type Id - Name

Scopes

403 - Ontvangen van Hosted BO4 - Download

101028 - BO4 Bint Export

  • businesstypes list
  • files delete
  • files download
  • files list

407 - Ontvangen van Hosted BO4 RPSA - Download

101028 - BO4 Bint Export

  • businesstypes list
  • files delete
  • files download
  • files list

402 - Zenden naar Hosted BO4 - Upload

101020 - BO4 DPIA100 Import

  • businesstypes list
  • files upload
  • files download
  • files list

406 - Zenden naar Hosted BO4 RPSA - Upload

101020 - BO4 DPIA100 Import

  • businesstypes list
  • files upload
  • files download
  • files list

81 - Management Informatie - Download

118000 - MI BO4 Datafeed

  • businesstypes list
  • files delete
  • 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 kan door te klikken op stap ‘Visma App store’ naar de laatste stap.

 

WeslyvanHorssen_2-1665578653465.png

 


 

 

Tabblad Visma App Store, op dit moment stellen wij de Visma App Store niet ter beschikking aan onze klanten. 

 

Voor toegang tot de klantdata genereer je een Invitation Code. Hoe je dit doet staat hieronder verder uitgelegd. Visma | Raet zal de toegang tot de klant-data goedkeuren en dan direct de koppeling van klantdata aan je applicatie gereedmaken.

 

WeslyvanHorssen_13-1665574102799.png

 

Na Start setup for Visma App Store ziet u onderstaand scherm en dan kies je bij Access level - Audience voor Invite only

 

Vul ook de url in waar uw product is uitgelegd.

WeslyvanHorssen_14-1665574102597.png

 

 

Je bent nu klaar met het aanmaken van de applicatie, de optie Save wordt zichtbaar op het moment dat Visma | Raet de applicatie heeft goedgekeurd, je kunt het aanmaken sluiten door bijvoorbeeld op Back to my Applications te klikken. 

Wanneer Visma | Raet de goedkeuring heeft verleend, ontvang je hier een e-mail van en kun je de volgende stap uitvoeren door de applicatie te koppelen aan klant-data. Dit staat uitgelegd in het volgende hoofdstuk 4 ‘Invitatiecode aanmaken’.

 

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). 

WeslyvanHorssen_15-1665574102668.png

 

Kies voor het tabblad Visma App Store. En vervolgens New Invitation Code.

WeslyvanHorssen_16-1665574102699.png

 

 

Bij Invitation description vul je de naam van de betreffende klant in. En klik vervolgens op Generate.

WeslyvanHorssen_17-1665574102589.png

 

 

WeslyvanHorssen_18-1665574102713.png

 

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.

WeslyvanHorssen_19-1665574102734.png

 

Voorbeeld van een Tenant ID

WeslyvanHorssen_20-1665574102695.png

 

5 - Dien een ticket in via Mijn Support

Dien ticket in via Mijn Support met de invitation code en het verzoek om autorisatie.

Selecteer template van IBU naar File API.

CristoAmezcua_1-1690788099304.png

 


6 - Pas systemen aan om gebruik te maken van File API

 

De versturende systemen dienen aangepast te worden voor verzenden via de file API. Zie link voor meer informatie per systeem.

 

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.


 

 

Opmerkingen
FBB Zorgboog
ACTIVE CONTRIBUTOR *
door FBB Zorgboog

@Wesly van Horssen

Wij lopen vast bij: Na Start setup for Visma App Store ziet u onderstaand scherm en dan kies je bij Access level - Audience voor Invite only

De optie Access level verschijnt niet. Wel geeft die aan dat het logo ontbreekt.

Ook blijft op tabblad Integrations de aangemaakte applicatie (IAM API) al dagen op Pending staan. 

Inmiddels heb ik al een aanvraag voor een consultant ingediend, maar de tijd dringt en wellicht is de oplossing simpel maar voor ons onvindbaar 😔