Status
De Bestandsuitwisseling module is nu “Algemeen Beschikbaar” voor Payroll Only gebruikers. Dit betekent dat je zelf de autorisatie kunt toekennen in Autorisatiebeheer. Bestandsuitwisseling is de vervanger van handmatig Zenden/Ontvangen met IBU.
Vanaf vandaag zal de applicatie Bestandsuitwisseling standaard beschikbaar zijn in Autorisatiebeheer. In Autorisatiebeheer kan de beheerder rechten geven voor de verschillende bestandstypes aan de desbetreffende gebruikers.
Heb je nog geen toegang tot Autorisatiebeheer? Dien een ticket in bij 4Me en vermeld daarin de gebruikers die toegang moeten krijgen tot Autorisatiebeheer. Wij zullen er dan voor zorgen dat deze gebruikers worden toegevoegd.
Wat je moet doen
Ken in Autorisatiebeheer de juiste (onderstaande) rechten toe aan je gebruikers aan de hand van de volgende stappen.
NOOT: Indien je nog niet bekend bent met Autorisatiebeheer kun je hier lezen hoe je Autorisatiebeheer kunt gebruiken.
Stap 1: Maak een nieuwe Autorisatie aan, door in het startscherm van Autorisatiebeheer op ‘Autorisatie toevoegen’ te klikken. Vul de naam in voor de nieuwe Autorisatie en ken vervolgens de nieuwe Autorisatie toe aan ‘Alle gebruikers’ of ‘Specifieke gebruikers’. Voeg de applicatie Bestandsuitwisseling toe aan de nieuwe Autorisatie met de volgende rechten:
Toegang tot Bestandsuitwisseling
Zend testbestanden naar Bestandsuitwisseling
Ontvang testbestanden van Bestandsuitwisseling
Met deze rechten hebben de gebruikers, aan wie de nieuwe Autorisatie is toegekend, toegang tot Bestandsuitwisseling, maar alleen voor de testbestanden en nog geen rechten voor applicatie specifieke bestanden.
Stap 2: Voeg alle gewenste applicaties en hun specifieke rechten toe aan de juiste autorisatiegroepen. Hierbij is het mogelijk om aan één Autorisatie meerdere applicaties inclusief bijbehorende rechten te koppelen:
Betaalmanager
Ontvang downloads van Betaalmanager Gemal
Ontvang opdrachten van Betaalmanager Gemal
Payroll Gemal Direct
Ontvang bestanden van Payroll Gemal Direct
Payroll Gemal Direct Zenden
Zend PSG Integratiebestanden naar Payroll Gemal Direct
Zend SPG Integratiebestanden naar Payroll Gemal Direct
Salarisdossier Gemal
Ontvang bestanden van Salarisdossier Gemal
Personeelsdossier
Ontvang bestanden van Personeelsdossier
Zend bestanden naar Personeelsdossier
Youforce Account Beheer
Zend XSSO bestanden naar Gebruikersbeheer
Zend Dienstverbanden CSV bestand naar Gebruikersbeheer
Zend Organisatie bestanden naar Gebruikersbeheer
Zend Roltoewijzing bestanden naar Gebruikersbeheer
Flex Benefit
Ontvang TE bestanden van Flex Benefits
Zend RBP Werknemers bestanden naar Flex Benefits
Stap 3. Controleer of alle gebruikers, die toegang moeten hebben tot Bestandsuitwisseling, toegevoegd zijn aan deze autorisatie. Dit kan per gebruiker of via het rapport.
Stap 4. Aanvullend dient in de applicaties ‘Betaalmanager’ en ‘Payroll Gemal Direct’ te worden ingesteld dat de bestanden verstuurd worden naar Bestandsuitwisseling in plaats van naar Zenden & Ontvangen. Een overzicht van de acties per applicatie staan op deze community pagina.
Stap 5. Bestandsuitwisseling is op dit moment beschikbaar in Mijn Youforce, maar kan ook worden bereikt via de "Bestandsuitwisseling" -tegel op de Youforce Desktop. In dat laatste geval moet de tegel wel worden geautoriseerd via Toegangsbeheer.
Extra informatie
Gebruikers moeten zich aanmelden via het nieuwe inloggen om gebruik te kunnen maken van Bestandsuitwisseling.
Bestanden kunnen gedurende 1 maand worden opgehaald/ontvangen.
Bestanden kunnen gedurende 1 maand zo nodig meerdere malen worden ontvangen.
Bij verzenden van bestanden wordt er een kopie van de te verzenden bestanden verstuurd. Het verzonden bestand blijft lokaal beschikbaar.
Ontvangen bestanden worden opgeslagen in de Download directory die in je browser is geconfigureerd.
De Nederlandse taal wordt ondersteund. De gebruikte taal volgt de keuze die je bij de persoonlijke instellingen in Mijn Youforce hebt gemaakt.
Het is mogelijk om tegelijkertijd meerdere bestanden te ontvangen. Zie Release-opmerkingen Bestandsuitwisseling update 16-10-2023.
Aan de volgende onderwerpen wordt op dit moment gewerkt. We zullen je hier op de community op de hoogte houden van de voortgang:
Op dit moment wordt nog niet geregistreerd wie een bestand heeft ingezonden of ontvangen. Deze informatie is dus nog niet terug te zien in de betreffende schermen
Kennisartikelen
Zenden en Ontvangen met de IBU stopt
Youforce-bestanden koppelen aan Bestandsuitwisseling.
Hoe Bestandsuitwisseling testen met dummy-bestanden
Releases voor bestandsuitwisseling
Status
De Bestandsuitwisseling module is nu “Algemeen Beschikbaar” voor HR Core Education gebruikers. Dit betekent dat je zelf de autorisatie kunt toekennen in Autorisatiebeheer. Bestandsuitwisseling is de vervanger van handmatig Zenden/Ontvangen met IBU.
Vanaf vandaag zal de applicatie Bestandsuitwisseling standaard beschikbaar zijn in Autorisatiebeheer. In Autorisatiebeheer kan de beheerder rechten geven voor de verschillende bestandstypes aan de desbetreffende gebruikers.
Heb je nog geen toegang tot Autorisatiebeheer? Dien een ticket in bij 4Me en vermeld daarin de gebruikers die toegang moeten krijgen tot Autorisatiebeheer. Wij zullen er dan voor zorgen dat deze gebruikers worden toegevoegd.
Wat je moet doen
Ken in Autorisatiebeheer de juiste (onderstaande) rechten toe aan je gebruikers aan de hand van de volgende stappen.
NOOT: Indien je nog niet bekend bent met Autorisatiebeheer kun je hier lezen hoe je Autorisatiebeheer kunt gebruiken.
Stap 1: Maak een nieuwe Autorisatie aan, door in het startscherm van Autorisatiebeheer op ‘Autorisatie toevoegen’ te klikken. Vul de naam in voor de nieuwe Autorisatie en ken vervolgens de nieuwe Autorisatie toe aan ‘Alle gebruikers’ of ‘Specifieke gebruikers’. Voeg de applicatie Bestandsuitwisseling toe aan de nieuwe Autorisatie met de volgende rechten:
Toegang tot Bestandsuitwisseling
Zend testbestanden naar Bestandsuitwisseling
Ontvang testbestanden van Bestandsuitwisseling
Met deze rechten hebben de gebruikers, aan wie de nieuwe Autorisatie is toegekend, toegang tot Bestandsuitwisseling, maar alleen voor de testbestanden en nog geen rechten voor applicatie specifieke bestanden.
Stap 2: Voeg alle gewenste applicaties en hun specifieke rechten toe aan de juiste autorisatiegroepen. Hierbij is het mogelijk om aan één Autorisatie meerdere applicaties inclusief bijbehorende rechten te koppelen:
HR Core Education
Zend aktes naar MI Education
Zend bulk bestanden naar HR Core Education
Ontvang declaratiebestanden van HR Core Education
Ontvang aktes van MI Education
Ontvang datafeed bestanden van MI Education
Betaalmanager
Ontvang downloads van Betaalmanager Gemal
Ontvang opdrachten van Betaalmanager Gemal
Payroll Gemal Direct
Ontvang bestanden van Payroll Gemal Direct
Payroll Gemal Direct Zenden
Zend WIG Integratiebestanden naar Payroll Gemal Direct
Personeelsdossier
Zend bestanden naar Personeelsdossier
Ontvang bestanden van Personeelsdossier
Salarisdossier Gemal
Ontvang bestanden van Salarisdossier Gemal
Youforce Account Beheer
Zend XSSO bestanden naar Gebruikersbeheer
Stap 3. Controleer of alle gebruikers, die toegang moeten hebben tot Bestandsuitwisseling, toegevoegd zijn aan deze autorisatie. Dit kan per gebruiker of via het rapport.
Stap 4. Aanvullend dient in de applicaties ‘Betaalmanager’ en ‘Payroll Gemal Direct’ te worden ingesteld dat de bestanden verstuurd worden naar Bestandsuitwisseling in plaats van naar Zenden en Ontvangen. Een overzicht van de acties per applicatie staan op deze community pagina .
Stap 5. Bestandsuitwisseling is op dit moment beschikbaar in Mijn Youforce, maar kan ook worden bereikt via de "Bestandsuitwisseling" -tegel op de Youforce Desktop. In dat laatste geval moet de tegel wel worden geautoriseerd via Toegangsbeheer.
Extra informatie
Gebruikers moeten zich aanmelden via het nieuwe inloggen om gebruik te kunnen maken van Bestandsuitwisseling.
Bestanden kunnen gedurende 1 maand worden opgehaald/ontvangen.
Bestanden kunnen gedurende 1 maand zo nodig meerdere malen worden ontvangen.
Bij verzenden van bestanden wordt er een kopie van de te verzenden bestanden verstuurd. Het verzonden bestand blijft lokaal beschikbaar.
Ontvangen bestanden worden opgeslagen in de Download directory die in je browser is geconfigureerd.
De Nederlandse taal wordt ondersteund. De gebruikte taal volgt de keuze die je bij de persoonlijke instellingen in Mijn Youforce hebt gemaakt.
Het is mogelijk om tegelijkertijd meerdere bestanden te ontvangen. Zie Release-opmerkingen Bestandsuitwisseling update 16-10-2023.
Aan de volgende onderwerpen wordt op dit moment gewerkt. We zullen je hier op de community op de hoogte houden van de voortgang:
Op dit moment wordt nog niet geregistreerd wie een bestand heeft ingezonden of ontvangen. Deze informatie is dus nog niet terug te zien in de betreffende schermen
Kennisartikelen
Zenden en Ontvangen met de IBU stopt
Youforce-bestanden koppelen aan Bestandsuitwisseling.
Hoe Bestandsuitwisseling testen met dummy-bestanden
Releases voor bestandsuitwisseling
Status
De Bestandsuitwisseling module is nu “Algemeen Beschikbaar” voor VIPS Disbursements gebruikers. Dit betekent dat je zelf de autorisatie kunt toekennen in Autorisatiebeheer. Bestandsuitwisseling is de vervanger van handmatig Zenden/Ontvangen met IBU.
Vanaf vandaag zal de applicatie Bestandsuitwisseling standaard beschikbaar zijn in Autorisatiebeheer. In Autorisatiebeheer kan de beheerder rechten geven voor de verschillende bestandstypes aan de desbetreffende gebruikers.
Heb je nog geen toegang tot Autorisatiebeheer? Dien een ticket in bij Jira Support en vermeld daarin de gebruikers die toegang moeten krijgen tot Autorisatiebeheer. Wij zullen er dan voor zorgen dat deze gebruikers worden toegevoegd.
Wat je moet doen
Ken in Autorisatiebeheer de juiste (onderstaande) rechten toe aan je gebruikers aan de hand van de volgende stappen.
NOOT: Indien je nog niet bekend bent met Autorisatiebeheer kun je hier lezen hoe je Autorisatiebeheer kunt gebruiken.
Stap 1: Maak een nieuwe Autorisatie aan, door in het startscherm van Autorisatiebeheer op ‘Autorisatie toevoegen’ te klikken. Vul de naam in voor de nieuwe Autorisatie en ken vervolgens de nieuwe Autorisatie toe aan ‘Alle gebruikers’ of ‘Specifieke gebruikers’. Voeg de applicatie Bestandsuitwisseling toe aan de nieuwe Autorisatie met de volgende rechten:
Toegang tot Bestandsuitwisseling
Zend testbestanden naar Bestandsuitwisseling
Ontvang testbestanden van Bestandsuitwisseling
Met deze rechten hebben de gebruikers, aan wie de nieuwe Autorisatie is toegekend, toegang tot Bestandsuitwisseling, maar alleen voor de testbestanden en nog geen rechten voor applicatie specifieke bestanden.
Stap 2: Voeg alle gewenste applicaties en hun specifieke rechten toe aan de juiste autorisatiegroepen. Hierbij is het mogelijk om aan één Autorisatie meerdere applicaties inclusief bijbehorende rechten te koppelen:
Betaalmanager
Betaalbestanden aangemaakt vanuit P&B Core:
Ontvang opdrachten van Betaalmanager VIPS Disbursements
Ontvang downloads van Betaalmanager VIPS Disbursements
Betaalbestanden aangemaakt vanuit Payroll Gemal:
Ontvang downloads van Betaalmanager Gemal
Ontvang opdrachten van Betaalmanager Gemal
VIPS Disbursements (P&B Core)
Zend bestanden naar VIPS Disbursements
Ontvang bestanden van VIPS Disbursements
Payroll Gemal Direct
Ontvang bestanden van Payroll Gemal Direct
Payroll Gemal Direct Zenden
Zend EHRM bestanden naar Payroll Gemal Direct
Zend WIG Integratiebestanden naar Payroll Gemal Direct
Salarisdossier Gemal
Ontvang bestanden van Salarisdossier Gemal
Stap 3. Autoriseer ook je gebruikers die reeds gebruik maken van Bestandsuitwisseling
Stap 4. Aanvullend dient in de applicaties ‘Betaalmanager’ en ‘Payroll Gemal’ te worden ingesteld dat de bestanden verstuurd worden naar BestandsuitwisselingI in plaats van naar Zenden & Ontvangen. Een overzicht van de acties per applicatie staan op deze community pagina.
Stap 5. De laatste stap is het toekennen van de ‘Bestandsuitwisseling’ -tegel aan de geautoriseerde gebruikers via Toegangsbeheer. Hiermee wordt de tegel ‘Bestandsuitwisseling’ op de Youforce Desktop zichtbaar.
Extra informatie
Gebruikers moeten zich aanmelden via het nieuwe inloggen om gebruik te kunnen maken van Bestandsuitwisseling.
Bestanden kunnen gedurende 1 maand worden opgehaald/ontvangen.
Bestanden kunnen gedurende 1 maand zo nodig meerdere malen worden ontvangen.
Bij verzenden van bestanden wordt er een kopie van de te verzenden bestanden verstuurd. Het verzonden bestand blijft lokaal beschikbaar.
Ontvangen bestanden worden opgeslagen in de Download directory die in je browser is geconfigureerd.
De Nederlandse taal wordt ondersteund. De gebruikte taal volgt de keuze die je bij de persoonlijke instellingen in Mijn Youforce hebt gemaakt.
Het is mogelijk om tegelijkertijd meerdere bestanden te ontvangen. Zie Release-opmerkingen Bestandsuitwisseling update 16-10-2023.
Aan de volgende onderwerpen wordt op dit moment gewerkt. We zullen je hier op de community op de hoogte houden van de voortgang:
Op dit moment wordt nog niet geregistreerd wie een bestand heeft ingezonden of ontvangen. Deze informatie is dus nog niet terug te zien in de betreffende schermen
De basic api heeft de status Controlled Available en is enkel nog beschikbaar in overleg met Visma Raet.
De Basic API beschikt over een autorisatie mechanisme waarmee bepaald kan worden tot welke medewerkers en datasets een extern systeem toegang heeft.
Het autorisatie mechanisme bestaat uit de volgende onderdelen:
Autorisatie op basis van API scopes Door het activeren van scopes kunnen externe systemen toegang krijgen tot één of meerdere endpoint en dataset. De scopes zijn vooraf door Visma Raet bepaald en omvatten één of meerdere endpoints, dataset en/of acties.
Autorisatie op medewerkers Met behulp van autorisaties filters kan worden bepaald welke medewerkers in de API beschikbaar komen.
Met dit document willen wij u informeren over de mogelijkheden van deze autorisatievormen in de API. Beide autorisatie mechanismes moeten door een consultant ingericht worden.
Autorisatie op basis van API scopes In de Visma developer portal zijn per API één of meerdere scopes gedefinieerd. Door het activeren van deze scope krijgt een extern systeem toegang tot één of meerdere endpoint en/of data set. Binnen de API worden de volgende scopes onderscheiden.
Scope
Omschrijving
Endpoints
Get_Basic
Get basic data zoals medewerker- & organisatiedata
GET persons GET employments GET organizationUnits GET roleAssignments GET jobProfiles
GetPrivateContactDetails
Voegt de privé contactgegevens aan de endpoint Person & Employee, zoals post- en woonadres, telefoonnummer vast & mobiel en het email adres.
GET persons
Dit betreft de volgende gegevens: ADRESGEVENS
Home:
P01014 straatnaam P01016 Huisnummer P01018 Huisnummer toev P01020 Postcode P01022 Plaatsnaam P01024 Land
Postal:
P00365 straatnaam P00367 huisnummer P00368 huisnummer toev P00313 postcode P00308 plaatsnaam P00847 land
TELEFOONNUMMERS
Home: P01027 - telefoonnr woonadres Mobile : P01036 - Telefoonnr mobiel
EMAILADRES
Prive: P01034 - E-mail adres privé
Uw consultant kan u helpen bij het activeren / deactiveren van deze scopes binnen de API.
Autorisatie op basis van autorisatie filters
De autorisatie filters hebben betrekking op welke medewerkers zichtbaar zijn in de API. Standaard worden altijd alle medewerkers getoond in de API. Bij het activeren van de API kan een consultant filters inrichten zodat maar een beperkte groep medewerkers via de API beschikbaar komen.
Filteren in de API is mogelijk op de volgende Beaufort velden:
P01102- Soort Arbeidsrelatie
P01103- Opdrachtgever
P01104- Instelling
P01110 - Code doelgroep
P05046 - Selectierubriek Basic API
Een veel voorkomen filter is bijvoorbeeld op Soort Arbeidsrelatie waarbij alleen eigen medewerkers in het extern systeem opgenomen worden. Maar ook een filter op de combinatie Opdrachtgever / Instelling geeft u de mogelijkheid om de medewerkers van één of meerdere specifieke instellingen in de API op te nemen.
Uw consultant kan u helpen bij het inrichten of wijzigen van de autorisatie filters.
De Basic api heeft de status Controlled Available en is enkel nog beschikbaar in overleg met Visma Raet.
Domein model
De Basic api bevat uitsluitend de basis medewerker- en organisatiegegevens. Middels deze API hebben externe systemen inzicht in de organisatiestructuur en de huidige medewerker.
Het model
Entiteiten en velden
Person (Persoon)
Id / personId
Technical and unique id. the Id is unique within the entity and tenant. The id is owned by the core system and can not changed by a user
P01001 - Persoonsnummer
PersonCode
The logical code or number of the employee.
P01001 - Persoonsnummer
Initials
The initials of the employee. Format depends
P00303 - Voorletters
firstNames
The official given names of the employee as stored in the HR Core system
P01002 - Voornamen
KnownAs
The name which is used by the employee as his first name
P01003 - Roepnaam
lastNameAtBirth
The last name at birth of the employee. Also known as the family name
P00301 - Geboortenaam
lastNameAtBirthPrefix
The prefix of the last name at birth
P00302 - Geboortenaam-voorvoegsels
lastName
The last which is currently used by the employee as his last name
P01008 - Samengestelde naam
lastNamePrefix
The prefix of the last name as used currently
P01009 - Samengestelde naam-voorvoegsels
nameAssembleOrder
Code of the assemble order that the core system uses for the last Name. The assemble order is depending on the core system and the logic behind it.
P00304 - Gebruik achternaam
partnerName
The partner last name
P00390 - Partner-naam
partnerNamePrefix
The prefix of the partner last name
P00391 - Partner-voorvoegsels
titlePrefix
The formal title which will be used as a prefix before the name like Doctor, Professor, et cetera
P00305 - Titulatuur voor de naam
titleSuffix
The formal title which will be used as postfix after the name like MSc or Master of Science
P03937 - Titulatuur achter de naam
gender
Gender of the person conform the ISO/IEC 5128 standard (0) Not known (1) Male (2) Female (9) Not applicable
P00330 - Geslacht M = Man / Male V = Vrouw / Female
dateOfBirth
Date of Birth
P00321 -Geboorte datum
deceased
Indicated if the employee deceased Note: most core systems have a date field. In the API this will be translated to boolean
P01005 - Datum overlijden
UserUID
Digital Identity of the user from the portal
PORTAL : Ping ID
emailAddresses
List of the email addresses of the employee. The fields are: type like Business, Private, etc. address
Business: P01035 - E-mail adres werk Private: P01034 - E-mail adres prive
phoneNumbers
list of phone numbers of the employee type like Business, Home, Mobile, et cetera number
Home: P01027 - telefoonnr woonadres Mobile : P01036 - Telefoonnr mobiel Business :P01037 - Telefoonnr werk FaxBusiness : P01039 Faxnr werk FaxHome : P01038 Faxnr prive
Addresses
list of addresses of the employee. The address fields are: addressType like Home, Post, etc. streetName Number streetNumberAdditional postalCode city country
Home: P01014 straatnaam P01016 Huisnummer P01018 Huisnummer toev P01020 Postcode P01022 Plaatsnaam P01024 Land Postal: P00365 straatnaam P00367 huisnummer P00368 huisnummer toev P00313 postcode P00308 plaatsnaam P00847 land
Employment (Dienstverband)
Id / employmentId
Technical and unique id. the Id is unique within the entity and tenant. The id is generated by the system and can not changed by a user.
Object Id = "PersonCode" + ContractCode
PersonCode / PersonId
Person code to which the employment is related
P01001 - Persoonsnummer
employmentCode / ContractCode / ContractId
Code of the contract
P01101 - volgnr dienstverband
PayrollClientCode
Logical code of the payroll client. Filter option for Row Authorisation (configuration API)
[P01103 Opdrachtgever]
PayrollInstitutionCode
Logical code of the payroll Institution. Filter option for Row Authorisation (configuration API)
[P01104 Instelling]
hireDate
The hire date of the employment
P00322 - Datum in dienst
dischargeDate
The end date or discharge date of the employment. This is always an "up to and including" date. In unknown the field will not be visible in the API
P00830 - Datum uit dienst
originalHireDate
The first hire date of original hire date of an employee within the organization. This date is important for the tenure or working anniversary of an employee
P00834 -Datum in dienst CAO
employmentType
Type of employment like Internal employee, contractor, "Wachtgelder" Filter option for Row Authorisation (configuration API)
P01102 - Soort arbeidsrelatie
contractType
Type of the contact like indefinite period ('Onbepaalde tijd') or given time ('bepaalde tijd')
P08259 - Code contract (on)bepaalde tijd
jobProfile
Official job title or job profile of the employment. The Job profile contains the following details: shortName: Code or short name of the job profile
P01107 - Primaire functie
classification
group or classification of the employment. Generic field Filter option for Row Authorisation (configuration API)
P01110 - Code doelgroep
organizationUnit
organization unit Id of employment. The Id is a reference to the entity org units
P01106 - Hierarchische org. eenheid
workingAmount
Work amount of employment. amountOfWork: the amount of work unitOfWork: Unit of work that specifies the amount of work like "hours", "days", et cetera periodOfWork: Period of work like "week" or "month" parttimePercentage
P01109 - Uren per week P00404 percentage deelbetrekking
Organisation unit (Organisatie-eenheid)
id
Technical and unique id of the organization Unit. the Id is unique within the entity and tenant. The id is generated by the system and can not changed by a user.
ID
shortName
Code or short name of the organizational unit
OE Code
fullName
Name of the organization unit
OE naam
parentOrgUnit
reference to the parent organizational unit. Empty means that it is organizational unit on the highest level in the company
ParentID
organisationUnitTpe
Type of the organization Unit
address
Address of the organisation Unit - Address - street - number - numberAdditional - postalCode - city
OE Adres
costCenter
default cost center of the organisation unit.
Kostenplaats
IsBlocked
Indicates if the Organization unit is block for adding new employees. note: it is possible there are still employee referring to this Org Unit.
blocked/inactive
Role assignment (roltoewijzing)
id
Technical and unique id of the role assigment. the Id is unique within the entity and tenant. The id is generated by the system and can not changed by a user.
object ID
PersonID / personCode
Technical ID of the Person
Persoonsnummer
shortName
Short name of the role the person will have for this organization, like Manager, HR Professional, Director.
P01062 - Rol
organisationUnit
Id of the organisation Unit
P01061 - Operationele org.eenheid
startDate
Start date from which the role assignment is valid for that employee
P01063 - ingangsdatum roltoewijzing
endDate
end date until when the role assignment is valid
P01064 - einddatum roltoewijzing
Job profile (functie)
id / shortName
Unique id of the Job profile. the Id is unique within the entity and tenant.
P02301 - Code functie
fullName
Name of the Job Profile
P02302 - Omschrijving functie
jobFamily
Job family to which the job profile belongs
P02305 - Code Functiegroep
User (Youforce user account)
Id / UserUID
Ping Id or User Id which be used for the SSO solution of Visma Raet
Ping ID
SourceId
Youforce user name
Gebruikersnaam
IdentityId
Identity of the user on the local network
Identity
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 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
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.
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.
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.
Testomgeving - Het is tevens mogelijk om gebruik te maken van onze sandbox. Met deze sandbox kun je testen. De applicatie voor de productieomgeving kan ook gekoppeld worden aan de sandbox. Maak hiervoor een 2e Invitation code aan (deze stap wordt later toegelicht).
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.
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 de gewenste Youforce API, 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 en zolang de goedkeuring niet is verleend kan je de stap van de Visma App Store niet uitvoeren.
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.
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. De goedkeuring door Visma Raet kan enkele dagen duren en zolang de goedkeuring niet is verleend kan je de stap van de Visma App Store niet uitvoeren.
Je kan door te klikken op stap ‘Visma App store’ naar de laatste stap (mits Visma Raet de API('s) heeft goedgekeurd).
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.
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.
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 ‘Invitatiecode aanmaken’.
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.
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
Testomgeving - Het is tevens mogelijk om gebruik te maken van onze sandbox. Met deze sandbox kun je testen. De applicatie voor de productieomgeving kan ook gekoppeld worden aan de sandbox. Maak hiervoor een Invitation code aan en deel die met Visma Raet.
De Recruitment api heeft de status Controlled Available en is enkel nog beschikbaar in overleg met Visma Raet.
De Recruitment API beschikt over een autorisatie mechanisme waarmee bepaald kan worden tot welke medewerkers en datasets een recruitment systeem toegang heeft.
Het autorisatie mechanisme bestaat uit de volgende onderdelen:
Autorisatie op basis van API scopes Door het activeren van scopes kunnen externe systemen toegang krijgen tot één of meerdere endpoint en dataset. De scopes zijn vooraf door Visma Raet bepaald en omvatten één of meerdere endpoints, dataset en/of acties.
Autorisatie op medewerkers Met behulp van autorisaties filters kan worden bepaald welke medewerkers in de API beschikbaar komen.
Met dit document willen wij u informeren over de mogelijkheden van deze autorisatievormen in de API. Beide autorisatie mechanismes moeten door een consultant ingericht worden.
Autorisatie op basis van API scopes In de Visma developer portal zijn per API één of meerdere scopes gedefinieerd. Door het activeren van deze scope krijgt een extern systeem toegang tot één of meerdere endpoint en/of data set. Binnen de API worden de volgende scopes onderscheiden.
Scope
Omschrijving
Endpoints
Invitation_only
Scope noodzakelijk om de API te kunnen activeren. Tijdens het activering proces wordt de contractafspraken gecontroleerd en vastgelegd. Deze scope geeft nog geen toegang tot enige vorm van data maar is noodzakelijk voor de onboarding van klanten op de API of applicatie
-
Get_Basic
Get basic data zoals medewerker- & organisatiedata
GET persons GET employments GET organizationUnits GET roleAssignments GET jobProfiles
GetPrivateContactDetails
Voegt de privé contactgegevens aan de endpoint Person & Employee, zoals post- en woonadres, telefoonnummer vast & mobiel en het email adres.
GET persons
Dit betreft de volgende gegevens: ADRESGEVENS
Home:
P01014 straatnaam P01016 Huisnummer P01018 Huisnummer toev P01020 Postcode P01022 Plaatsnaam P01024 Land
Postal:
P00365 straatnaam P00367 huisnummer P00368 huisnummer toev P00313 postcode P00308 plaatsnaam P00847 land
TELEFOONNUMMERS
Home: P01027 - telefoonnr woonadres Mobile : P01036 - Telefoonnr mobiel
EMAILADRES
Prive: P01034 - E-mail adres privé
HSS_startWorkflow
Scope voor het starten van workflows voor een nieuwe medewerker, nieuw contract of het wijzigen van een bestaat contract.
POST hires POST Contracts POST Contracts/Adjustments
Uw consultant kan u helpen bij het activeren / deactiveren van deze scopes binnen de API.
Autorisatie op basis van autorisatie filters
De autorisatie filters hebben betrekking op welke medewerkers zichtbaar zijn in de API. Standaard worden altijd alle medewerkers getoond in de API. Bij het activeren van de API kan een consultant filters inrichten zodat maar een beperkte groep medewerkers via de API beschikbaar komen.
Filteren in de API is mogelijk op de volgende Beaufort velden:
P01102- Soort Arbeidsrelatie
P01103- Opdrachtgever
P01104- Instelling
P01110 - Code doelgroep
P05045 - Selectierubriek Recruitment API
Een veel voorkomen filter is bijvoorbeeld op Soort Arbeidsrelatie waarbij alleen eigen medewerkers in het extern systeem opgenomen worden. Maar ook een filter op de combinatie Opdrachtgever / Instelling geeft u de mogelijkheid om de medewerkers van één of meerdere specifieke instellingen in de API op te nemen.
Uw consultant kan u helpen bij het inrichten of wijzigen van de autorisatie filters.
Note:
De Recruitment api heeft de status Controlled Available en is enkel nog beschikbaar in overleg met Visma Raet.
Artikel inhoud
Domein model
De Recruitment api bevat uitsluitend de basis medewerker- en organisatiegegevens. Middels deze API heeft de recruitment system inzicht in de organisatiestructuur en de huidige medewerker als mogelijk potentiële kandidaten binnen het recruitment proces.
Note:
De vacature en het onboarden van de nieuwe medewerker maken nog geen onderdeel uit van deze API.
Het model
Entiteiten en velden
Person (Persoon)
Id / personId
Technical and unique id. the Id is unique within the entity and tenant. The id is owned by the core system and can not changed by a user
P01001 - Persoonsnummer
PersonCode
The logical code or number of the employee.
P01001 - Persoonsnummer
Initials
The initials of the employee. Format depends
P00303 - Voorletters
firstNames
The official given names of the employee as stored in the HR Core system
P01002 - Voornamen
KnownAs
The name which is used by the employee as his first name
P01003 - Roepnaam
lastNameAtBirth
The last name at birth of the employee. Also known as the family name
P00301 - Geboortenaam
lastNameAtBirthPrefix
The prefix of the last name at birth
P00302 - Geboortenaam-voorvoegsels
lastName
The last which is currently used by the employee as his last name
P01008 - Samengestelde naam
lastNamePrefix
The prefix of the last name as used currently
P01009 - Samengestelde naam-voorvoegsels
nameAssembleOrder
Code of the assemble order that the core system uses for the last Name. The assemble order is depending on the core system and the logic behind it.
P00304 - Gebruik achternaam
partnerName
The partner last name
P00390 - Partner-naam
partnerNamePrefix
The prefix of the partner last name
P00391 - Partner-voorvoegsels
titlePrefix
The formal title which will be used as a prefix before the name like Doctor, Professor, et cetera
P00305 - Titulatuur voor de naam
titleSuffix
The formal title which will be used as postfix after the name like MSc or Master of Science
P03937 - Titulatuur achter de naam
gender
Gender of the person conform the ISO/IEC 5128 standard (0) Not known (1) Male (2) Female (9) Not applicable
P00330 - Geslacht M = Man / Male V = Vrouw / Female
dateOfBirth
Date of Birth
P00321 -Geboorte datum
deceased
Indicated if the employee deceased Note: most core systems have a date field. In the API this will be translated to boolean
P01005 - Datum overlijden
UserUID
Digital Identity of the user from the portal
PORTAL : Ping ID
emailAddresses
List of the email addresses of the employee. The fields are: type like Business, Private, etc. address
Business: P01035 - E-mail adres werk Private: P01034 - E-mail adres prive
phoneNumbers
list of phone numbers of the employee type like Business, Home, Mobile, et cetera number
Home: P01027 - telefoonnr woonadres Mobile : P01036 - Telefoonnr mobiel Business :P01037 - Telefoonnr werk FaxBusiness : P01039 Faxnr werk FaxHome : P01038 Faxnr prive
Addresses
list of addresses of the employee. The address fields are: addressType like Home, Post, etc. streetName Number streetNumberAdditional postalCode city country
Home: P01014 straatnaam P01016 Huisnummer P01018 Huisnummer toev P01020 Postcode P01022 Plaatsnaam P01024 Land Postal: P00365 straatnaam P00367 huisnummer P00368 huisnummer toev P00313 postcode P00308 plaatsnaam P00847 land
Employment (Dienstverband)
Id / employmentId
Technical and unique id. the Id is unique within the entity and tenant. The id is generated by the system and can not changed by a user.
Object Id = "PersonCode" + ContractCode
PersonCode / PersonId
Person code to which the employment is related
P01001 - Persoonsnummer
employmentCode / ContractCode / ContractId
Code of the contract
P01101 - volgnr dienstverband
PayrollClientCode
Logical code of the payroll client. Filter option for Row Authorisation (configuration API)
[P01103 Opdrachtgever]
PayrollInstitutionCode
Logical code of the payroll Institution. Filter option for Row Authorisation (configuration API)
[P01104 Instelling]
hireDate
The hire date of the employment
P00322 - Datum in dienst
dischargeDate
The end date or discharge date of the employment. This is always an "up to and including" date. In unknown the field will not be visible in the API
P00830 - Datum uit dienst
originalHireDate
The first hire date of original hire date of an employee within the organization. This date is important for the tenure or working anniversary of an employee
P00834 -Datum in dienst CAO
employmentType
Type of employment like Internal employee, contractor, "Wachtgelder" Filter option for Row Authorisation (configuration API)
P01102 - Soort arbeidsrelatie
contractType
Type of the contact like indefinite period ('Onbepaalde tijd') or given time ('bepaalde tijd')
P08259 - Code contract (on)bepaalde tijd
jobProfile
Official job title or job profile of the employment. The Job profile contains the following details: shortName: Code or short name of the job profile
P01107 - Primaire functie
classification
group or classification of the employment. Generic field Filter option for Row Authorisation (configuration API)
P01110 - Code doelgroep
organizationUnit
organization unit Id of employment. The Id is a reference to the entity org units
P01106 - Hierarchische org. eenheid
workingAmount
Work amount of employment. amountOfWork: the amount of work unitOfWork: Unit of work that specifies the amount of work like "hours", "days", et cetera periodOfWork: Period of work like "week" or "month" parttimePercentage
P01109 - Uren per week P00404 percentage deelbetrekking
Organisation unit (Organisatie-eenheid)
id
Technical and unique id of the organization Unit. the Id is unique within the entity and tenant. The id is generated by the system and can not changed by a user.
ID
shortName
Code or short name of the organizational unit
OE Code
fullName
Name of the organization unit
OE naam
parentOrgUnit
reference to the parent organizational unit. Empty means that it is organizational unit on the highest level in the company
ParentID
organisationUnitTpe
Type of the organization Unit
address
Address of the organisation Unit - Address - street - number - numberAdditional - postalCode - city
OE Adres
costCenter
default cost center of the organisation unit.
Kostenplaats
IsBlocked
Indicates if the Organization unit is block for adding new employees. note: it is possible there are still employee referring to this Org Unit.
blocked/inactive
Role assignment (roltoewijzing)
id
Technical and unique id of the role assigment. the Id is unique within the entity and tenant. The id is generated by the system and can not changed by a user.
object ID
PersonID / personCode
Technical ID of the Person
Persoonsnummer
shortName
Short name of the role the person will have for this organization, like Manager, HR Professional, Director.
P01062 - Rol
organisationUnit
Id of the organisation Unit
P01061 - Operationele org.eenheid
startDate
Start date from which the role assignment is valid for that employee
P01063 - ingangsdatum roltoewijzing
endDate
end date until when the role assignment is valid
P01064 - einddatum roltoewijzing
Job profile (functie)
id / shortName
Unique id of the Job profile. the Id is unique within the entity and tenant.
P02301 - Code functie
fullName
Name of the Job Profile
P02302 - Omschrijving functie
jobFamily
Job family to which the job profile belongs
P02305 - Code Functiegroep
User (Youforce user account)
Id / UserUID
Ping Id or User Id which be used for the SSO solution of Visma Raet
Ping ID
SourceId
Youforce user name
Gebruikersnaam
IdentityId
Identity of the user on the local network
Identity
Note:
De MLM api heeft de status Controlled Available en is enkel nog beschikbaar in overleg met Visma Raet.
De MLM api is een tijdelijke oplossing die op termijn vervangen wordt door de Sivi standaard en specifiek door het Sivi medewerker bericht. Zodra het Sivi medewerker bericht beschikbaar is, moet overgestapt worden op deze marktstandaard en komt de MLM api te vervallen.
De MLM API beschikt over een autorisatie mechanisme waarmee bepaald kan worden tot welke medewerkers en datasets een Medical Leave Management systeem toegang heeft.
Het autorisatie mechanisme bestaat uit de volgende onderdelen:
Autorisatie op basis van API scopes Door het activeren van scopes kunnen externe systemen toegang krijgen tot één of meerdere endpoint en dataset. De scopes zijn vooraf door Visma Raet bepaald en omvatten één of meerdere endpoints, dataset en/of acties.
Autorisatie op medewerkers Met behulp van autorisaties filters kan worden bepaald welke medewerkers in de API beschikbaar komen.
Met dit document willen wij u informeren over de mogelijkheden van deze autorisatievormen in de API. Beide autorisatie mechanismes moeten door een consultant ingericht worden.
Autorisatie op basis van API scopes In de Visma developer portal zijn per API één of meerdere scopes gedefinieerd. Door het activeren van deze scope krijgt een extern systeem toegang tot één of meerdere endpoint en/of data set. Binnen de API worden de volgende scopes onderscheiden.
Scope
Omschrijving
Endpoints
Invitation_only
Scope noodzakelijk om de API te kunnen activeren. Tijdens het activering proces wordt de contractafspraken gecontroleerd en vastgelegd. Deze scope geeft nog geen toegang tot enige vorm van data maar is noodzakelijk voor de onboarding van klanten op de API of applicatie
-
Get_Basic
Get basic data zoals medewerker- & organisatiedata
GET persons GET employments
GET employmentTimelines GET organizationUnits GET roleAssignments GET jobProfiles
GetPrivateContactDetails
Voegt de privé contactgegevens aan de endpoint Person & Employee, zoals post- en woonadres, telefoonnummer vast & mobiel en het email adres.
GET persons
Dit betreft de volgende gegevens: ADRESGEVENS
Home:
P01014 straatnaam P01016 Huisnummer P01018 Huisnummer toev P01020 Postcode P01022 Plaatsnaam P01024 Land
Postal:
P00365 straatnaam P00367 huisnummer P00368 huisnummer toev P00313 postcode P00308 plaatsnaam P00847 land
TELEFOONNUMMERS
Home: P01027 - telefoonnr woonadres Mobile : P01036 - Telefoonnr mobiel
EMAILADRES
Prive: P01034 - E-mail adres privé
Uw consultant kan u helpen bij het activeren / deactiveren van deze scopes binnen de API.
Autorisatie op basis van autorisatie filters
De autorisatie filters hebben betrekking op welke medewerkers zichtbaar zijn in de API. Standaard worden altijd alle medewerkers getoond in de API. Bij het activeren van de API kan een consultant filters inrichten zodat maar een beperkte groep medewerkers via de API beschikbaar komen.
Filteren in de API is mogelijk op de volgende Beaufort velden:
P01102 - Soort Arbeidsrelatie
P01103 - Opdrachtgever
P01104 - Instelling
P01110 - Code doelgroep
P05047 - Selectierubriek MLM api
Een veel voorkomen filter is bijvoorbeeld op Soort Arbeidsrelatie waarbij alleen eigen medewerkers in het extern systeem opgenomen worden. Maar ook een filter op de combinatie Opdrachtgever / Instelling geeft u de mogelijkheid om de medewerkers van één of meerdere specifieke instellingen in de API op te nemen.
Uw consultant kan u helpen bij het inrichten of wijzigen van de autorisatie filters.
Note:
De MLM api heeft de status Controlled Available en is enkel nog beschikbaar in overleg met Visma Raet.
De MLM api is een tijdelijke oplossing die op termijn vervangen wordt door de Sivi standaard en specifiek door het Sivi medewerker bericht. Zodra het Sivi medewerker bericht beschikbaar is, moet overgestapt worden op deze marktstandaard en komt de MLM api te vervallen.
Artikel inhoud
Domein model
De MLM api bevat uitsluitend de basis medewerker- en organisatiegegevens. Voor de verzuimgegevens wordt verwezen naar het SIVI bericht Verzuimmeldingen. De SIVI oplossing wordt separaat van deze MLM api aangeboden.
Het model
Entiteiten en velden
Person (Persoon)
Id / personId
Technical and unique id. the Id is unique within the entity and tenant. The id is owned by the core system and can not changed by a user
P01001 - Persoonsnummer
PersonCode
The logical code or number of the employee.
P01001 - Persoonsnummer
Initials
The initials of the employee. Format depends
P00303 - Voorletters
firstNames
The official given names of the employee as stored in the HR Core system
P01002 - Voornamen
KnownAs
The name which is used by the employee as his first name
P01003 - Roepnaam
lastNameAtBirth
The last name at birth of the employee. Also known as the family name
P00301 - Geboortenaam
lastNameAtBirthPrefix
The prefix of the last name at birth
P00302 - Geboortenaam-voorvoegsels
lastName
The last which is currently used by the employee as his last name
P01008 - Samengestelde naam
lastNamePrefix
The prefix of the last name as used currently
P01009 - Samengestelde naam-voorvoegsels
nameAssembleOrder
Code of the assemble order that the core system uses for the last Name. The assemble order is depending on the core system and the logic behind it.
P00304 - Gebruik achternaam
partnerName
The partner last name
P00390 - Partner-naam
partnerNamePrefix
The prefix of the partner last name
P00391 - Partner-voorvoegsels
titlePrefix
The formal title which will be used as a prefix before the name like Doctor, Professor, et cetera
P00305 - Titulatuur voor de naam
titleSuffix
The formal title which will be used as postfix after the name like MSc or Master of Science
P03937 - Titulatuur achter de naam
gender
Gender of the person conform the ISO/IEC 5128 standard (0) Not known (1) Male (2) Female (9) Not applicable
P00330 - Geslacht M = Man / Male V = Vrouw / Female
socialSecurityNumber
Dutch social security number of the employee
P00320 BSN nummer
dateOfBirth
Date of Birth
P00321 -Geboorte datum
deceased
Indicated if the employee deceased Note: most core systems have a date field. In the API this will be translated to boolean
P01005 - Datum overlijden
UserUID
Digital Identity of the user from the portal
PORTAL : Ping ID
emailAddresses
List of the email addresses of the employee. The fields are: type like Business, Private, etc. address
Business: P01035 - E-mail adres werk Private: P01034 - E-mail adres prive
phoneNumbers
list of phone numbers of the employee type like Business, Home, Mobile, et cetera number
Home: P01027 - telefoonnr woonadres Mobile : P01036 - Telefoonnr mobiel Business :P01037 - Telefoonnr werk FaxBusiness : P01039 Faxnr werk FaxHome : P01038 Faxnr prive
Addresses
list of addresses of the employee. The address fields are: addressType like Home, Post, etc. streetName Number streetNumberAdditional postalCode city country
Home: P01014 straatnaam P01016 Huisnummer P01018 Huisnummer toev P01020 Postcode P01022 Plaatsnaam P01024 Land P01012 Adres m.i.v. Postal: P00365 straatnaam P00367 huisnummer P00368 huisnummer toev P00313 postcode P00308 plaatsnaam P00847 land P01011 Adres m.i.v.
Employment (Dienstverband)
Id / employmentId
Technical and unique id. the Id is unique within the entity and tenant. The id is generated by the system and can not changed by a user.
Object Id = "PersonCode" + ContractCode
PersonCode / PersonId
Person code to which the employment is related
P01001 - Persoonsnummer
employmentCode / ContractCode / ContractId
Code of the contract
P01101 - volgnr dienstverband
PayrollClientCode
Logical code of the payroll client. Filter option for Row Authorisation (configuration API)
[P01103 Opdrachtgever]
PayrollInstitutionCode
Logical code of the payroll Institution. Filter option for Row Authorisation (configuration API)
[P01104 Instelling]
hireDate
The hire date of the employment
P00322 - Datum in dienst
dischargeDate
The end date or discharge date of the employment. This is always an "up to and including" date. In unknown the field will not be visible in the API
P00830 - Datum uit dienst
originalHireDate
The first hire date of original hire date of an employee within the organization. This date is important for the tenure or working anniversary of an employee
P00834 -Datum in dienst CAO
employmentType
Type of employment like Internal employee, contractor, "Wachtgelder" Filter option for Row Authorisation (configuration API)
P01102 - Soort arbeidsrelatie
contractType
Type of the contact like indefinite period ('Onbepaalde tijd') or given time ('bepaalde tijd')
P08259 - Code contract (on)bepaalde tijd
jobProfile
Official job title or job profile of the employment. The Job profile contains the following details: shortName: Code or short name of the job profile
P01107 - Primaire functie
classification
group or classification of the employment. Generic field Filter option for Row Authorisation (configuration API)
P01110 - Code doelgroep
organizationUnit
organization unit Id of employment. The Id is a reference to the entity org units
P01106 - Hierarchische org. eenheid
workingAmount
Work amount of employment. amountOfWork: the amount of work unitOfWork: Unit of work that specifies the amount of work like "hours", "days", et cetera periodOfWork: Period of work like "week" or "month" parttimePercentage
P01109 - Uren per week P00404 percentage deelbetrekking
Organisation unit (Organisatie-eenheid)
id
Technical and unique id of the organization Unit. the Id is unique within the entity and tenant. The id is generated by the system and can not changed by a user.
ID
shortName
Code or short name of the organizational unit
OE Code
fullName
Name of the organization unit
OE naam
parentOrgUnit
reference to the parent organizational unit. Empty means that it is organizational unit on the highest level in the company
ParentID
organisationUnitTpe
Type of the organization Unit
address
Address of the organisation Unit - Address - street - number - numberAdditional - postalCode - city
OE Adres
costCenter
default cost center of the organisation unit.
Kostenplaats
IsBlocked
Indicates if the Organization unit is block for adding new employees. note: it is possible there are still employee referring to this Org Unit.
blocked/inactive
Role assignment (roltoewijzing)
id
Technical and unique id of the role assigment. the Id is unique within the entity and tenant. The id is generated by the system and can not changed by a user.
object ID
PersonID / personCode
Technical ID of the Person
Persoonsnummer
shortName
Short name of the role the person will have for this organization, like Manager, HR Professional, Director.
P01062 - Rol
organisationUnit
Id of the organisation Unit
P01061 - Operationele org.eenheid
startDate
Start date from which the role assignment is valid for that employee
P01063 - ingangsdatum roltoewijzing
endDate
end date until when the role assignment is valid
P01064 - einddatum roltoewijzing
Job profile (functie)
id / shortName
Unique id of the Job profile. the Id is unique within the entity and tenant.
P02301 - Code functie
fullName
Name of the Job Profile
P02302 - Omschrijving functie
jobFamily
Job family to which the job profile belongs
P02305 - Code Functiegroep
User (youforce user account)
Id / UserUID
Ping Id or User Id which be used for the SSO solution of Visma Raet
Ping ID
SourceId
Youforce user name
Gebruikersnaam
IdentityId
Identity of the user on the local network
Identity
Youforce Developer Portal gaat offline
Onze producten en oplossingen worden beter wanneer ze verbinding maken met een ecosysteem van geweldige andere oplossingen. Mede daarom heeft Visma Raet besloten aan te sluiten bij het Visma Developer Portal.
Note: De WFM api is controlled available en is nog niet beschikbaar voor algemeen gebruik. De WFM API beschikt over een autorisatie mechanisme waarmee bepaald kan worden tot welke medewerkers en datasets een Workforce Management systeem toegang heeft.
Het autorisatie mechanisme bestaat uit de volgende onderdelen:
Autorisatie op basis van API scopes Door het activeren van scopes kunnen externe systemen toegang krijgen tot één of meerdere endpoint en dataset. De scopes zijn vooraf door Visma Raet bepaald en omvatten één of meerdere endpoints, dataset en/of acties.
Autorisatie op medewerkers Met behulp van autorisaties filters kan worden bepaald welke medewerkers in de API beschikbaar komen.
Met dit document willen wij u informeren over de mogelijkheden van deze autorisatievormen in de API. Beide autorisatie mechanismes moeten door een consultant ingericht worden.
Autorisatie op basis van API scopes In de Visma developer portal zijn per API één of meerdere scopes gedefinieerd. Door het activeren van deze scope krijgt een extern systeem toegang tot één of meerdere endpoint en/of data set. Binnen de API worden de volgende scopes onderscheiden.
Scope
Omschrijving
Endpoints
Invitation_only
Scope noodzakelijk om de API te kunnen activeren. Tijdens het activering proces wordt de contractafspraken gecontroleerd en vastgelegd. Deze scope geeft nog geen toegang tot enige vorm van data maar is noodzakelijk voor de onboarding van klanten op de API of applicatie
-
Get_Basic
Get basic data zoals medewerker- & organisatiedata
GET persons GET employments
GET employmentTimelines GET assignments GET organizationUnits GET roleAssignments GET jobProfiles
GetPrivateContactDetails
Voegt de privé contactgegevens aan de endpoint Person & Employee, zoals post- en woonadres, telefoonnummer vast & mobiel en het email adres.
GET persons GET Employees
Dit betreft de volgende gegevens: ADRESGEVENS
Home:
P01014 straatnaam P01016 Huisnummer P01018 Huisnummer toev P01020 Postcode P01022 Plaatsnaam P01024 Land
Postal:
P00365 straatnaam P00367 huisnummer P00368 huisnummer toev P00313 postcode P00308 plaatsnaam P00847 land
TELEFOONNUMMERS
Home: P01027 - telefoonnr woonadres Mobile : P01036 - Telefoonnr mobiel
EMAILADRES
Prive: P01034 - E-mail adres privé
Get salaryDetails
Lezen van de salarisgevens van medewerkers
GET SalaryDetails GET SalaryDetailTimelines
Get_maternitityLeave
Lezen van zwangerschapverlof van medewerkers
GET maternityLeave
Get_sicknessLeave
Lezen van ziekmeldingen van medewerkers
GET sickLeave
Get_leave
Lezen van verlofrechten en verlofopnames van medewerkers
GET leaveEntitlements GET leaveHours
Uw consultant kan u helpen bij het activeren / deactiveren van deze scopes binnen de API.
Autorisatie op basis van autorisatie filters
De autorisatie filters hebben betrekking op welke medewerkers zichtbaar zijn in de API. Standaard worden altijd alle medewerkers getoond in de API. Bij het activeren van de API kan een consultant filters inrichten zodat maar een beperkte groep medewerkers via de API beschikbaar komen.
Filteren in de API is mogelijk op de volgende Beaufort velden:
P01102- Soort Arbeidsrelatie
P01103- Opdrachtgever
P01104- Instelling
P01110 - Code doelgroep
P05042 - Selectie rubriek Domain API - WFM
Een veel voorkomen filter is bijvoorbeeld op Soort Arbeidsrelatie waarbij alleen eigen medewerkers in het extern systeem opgenomen worden. Maar ook een filter op de combinatie Opdrachtgever / Instelling geeft u de mogelijkheid om de medewerkers van één of meerdere specifieke instellingen in de API op te nemen.
Uw consultant kan u helpen bij het inrichten of wijzigen van de autorisatie filters.
De learning API beschikt over een autorisatie mechanisme waarmee bepaald kan worden tot welke medewerkers en datasets een learning systeem toegang heeft.
Het autorisatie mechanisme bestaat uit de volgende onderdelen:
Autorisatie op basis van API scopes Door het activeren van scopes kunnen externe systemen toegang krijgen tot één of meerdere endpoint en dataset. De scopes zijn vooraf door Visma Raet bepaald en omvatten één of meerdere endpoints, dataset en/of acties.
Autorisatie op medewerkers Met behulp van autorisaties filters kan worden bepaald welke medewerkers in de API beschikbaar komen.
Met dit document willen wij u informeren over de mogelijkheden van deze autorisatievormen in de API. Beide autorisatie mechanismes moeten door een consultant ingericht worden.
Autorisatie op basis van API scopes In de Visma developer portal zijn per API één of meerdere scopes gedefinieerd. Door het activeren van deze scope krijgt een extern systeem toegang tot één of meerdere endpoint en/of data set. Binnen de API worden de volgende scopes onderscheiden.
Scope
Omschrijving
Endpoints
Invitation_only
Scope noodzakelijk om de API te kunnen activeren. Tijdens het activering proces wordt de contractafspraken gecontroleerd en vastgelegd. Deze scope geeft nog geen toegang tot enige vorm van data maar is noodzakelijk voor de onboarding van klanten op de API of applicatie
-
Get_Basic
Get basic data zoals medewerker- & organisatiedata
GET persons GET employments GET employees GET assignments GET organizationUnits GET roleAssignments GET jobProfiles
Upload_documents
Upload van documenten zoals certificaten, diploma's, etc naar het Youforce personeelsdossier van de medewerker
POST documents/xxxxx zoals
POST documents/diploma POST documents/certifcate ect GET documents/{ticketId}/status
GetPrivateContactDetails
Voegt de privé contactgegevens aan de endpoint Person & Employee, zoals post- en woonadres, telefoonnummer vast & mobiel en het email adres.
GET persons GET Employees
Dit betreft de volgende gegevens: ADRESGEVENS
Home:
P01014 straatnaam P01016 Huisnummer P01018 Huisnummer toev P01020 Postcode P01022 Plaatsnaam P01024 Land
Postal:
P00365 straatnaam P00367 huisnummer P00368 huisnummer toev P00313 postcode P00308 plaatsnaam P00847 land
TELEFOONNUMMERS
Home: P01027 - telefoonnr woonadres Mobile : P01036 - Telefoonnr mobiel
EMAILADRES
Prive: P01034 - E-mail adres prive
Uw consultant kan u helpen bij het activeren / deactiveren van deze scopes binnen de API.
Autorisatie op basis van autorisatie filters
De autorisatie filters hebben betrekking op welke medewerkers zichtbaar zijn in de API. Standaard worden altijd alle medewerkers getoond in de API. Bij het activeren van de API kan een consultant filters inrichten zodat maar een beperkte groep medewerkers via de API beschikbaar komen.
Filteren in de API is mogelijk op de volgende Beaufort velden:
P01102- Soort Arbeidsrelatie
P01103- Opdrachtgever
P01104- Instelling
P01110 - Code doelgroep
P05041 - Selectie rubriek Domain API - Learning
Een veel voorkomen filter is bijvoorbeeld op Soort Arbeidsrelatie waarbij alleen eigen medewerkers in het extern systeem opgenomen worden. Maar ook een filter op de combinatie Opdrachtgever / Instelling geeft u de mogelijkheid om de medewerkers van één of meerdere specifieke instellingen in de API op te nemen.
Uw consultant kan u helpen bij het inrichten of wijzigen van de autorisatie filters.
Visma|Raet maakt nu gebruik van de Developer portal van Visma, een portal waar u API-applicaties kunt aanmaken en beheren. Met deze portal heeft u niet alleen toegang maar hebben uw collega's ook toegang tot de aangemaakte applicaties.
Wat moet u doen om gebruik te maken van de nieuwe portal?
Artikel inhoud
Domein model
Het model
Entiteiten en velden
Person (Persoon)
Id / personId
Technical and unique id. the Id is unique within the entity and tenant. The id is owned by the core system and can not changed by a user
P01001 - Persoonsnummer
PersonCode
The logical code or number of the employee.
P01001 - Persoonsnummer
Initials
The initials of the employee. Format depends
P00303 - Voorletters
firstNames
The official given names of the employee as stored in the HR Core system
P01002 - Voornamen
KnownAs
The name which is used by the employee as his first name
P01003 - Roepnaam
lastNameAtBirth
The last name at birth of the employee. Also known as the family name
P00301 - Geboortenaam
lastNameAtBirthPrefix
The prefix of the last name at birth
P00302 - Geboortenaam-voorvoegsels
lastName
The last which is currently used by the employee as his last name
P01008 - Samengestelde naam
lastNamePrefix
The prefix of the last name as used currently
P01009 - Samengestelde naam-voorvoegsels
nameAssembleOrder
Code of the assemble order that the core system uses for the last Name. The assemble order is depending on the core system and the logic behind it.
P00304 - Gebruik achternaam
partnerName
The partner last name
P00390 - Partner-naam
partnerNamePrefix
The prefix of the partner last name
P00391 - Partner-voorvoegsels
titlePrefix
The formal title which will be used as a prefix before the name like Doctor, Professor, et cetera
P00305 - Titulatuur voor de naam
titleSuffix
The formal title which will be used as postfix after the name like MSc or Master of Science
P03937 - Titulatuur achter de naam
gender
Gender of the person conform the ISO/IEC 5128 standard (0) Not known (1) Male (2) Female (9) Not applicable
P00330 - Geslacht M = Man / Male V = Vrouw / Female
dateOfBirth
Date of Birth
P00321 -Geboorte datum
deceased
Indicated if the employee deceased Note: most core systems have a date field. In the API this will be translated to boolean
P01005 - Datum overlijden
emailAddresses
List of the email addresses of the employee. The fields are: type like Business, Private, etc. address
Business: P01035 - E-mail adres werk Private: P01034 - E-mail adres prive
phoneNumbers
list of phone numbers of the employee type like Business, Home, Mobile, et cetera number
Home: P01027 - telefoonnr woonadres Mobile : P01036 - Telefoonnr mobiel Business :P01037 - Telefoonnr werk FaxBusiness : P01039 Faxnr werk FaxHome : P01038 Faxnr prive
Addresses
list of addresses of the employee. The address fields are: addressType like Home, Post, etc. streetName Number streetNumberAdditional postalCode city country
Home: P01014 straatnaam P01016 Huisnummer P01018 Huisnummer toev P01020 Postcode P01022 Plaatsnaam P01024 Land P01012 Adres m.i.v. Postal: P00365 straatnaam P00367 huisnummer P00368 huisnummer toev P00313 postcode P00308 plaatsnaam P00847 land P01011 Adres m.i.v.
Employment (Dienstverband)
Id / employmentId
Technical and unique id. the Id is unique within the entity and tenant. The id is generated by the system and can not changed by a user.
Object Id = "PersonCode" + ContractCode
PersonCode / PersonId
Person code to which the employment is related
P01001 - Persoonsnummer
employmentCode / ContractCode / ContractId
Code of the contract
P01101 - volgnr dienstverband
PayrollClientCode
Logical code of the payroll client. Filter option for Row Authorisation (configuration API)
P01103 Opdrachtgever
PayrollInstitutionCode
Logical code of the payroll Institution. Filter option for Row Authorisation (configuration API)
P01104 Instelling
hireDate
The hire date of the employment
P00322 - Datum in dienst
dischargeDate
The end date or discharge date of the employment. This is always an "up to and including" date. In unknown the field will not be visible in the API
P00830 - Datum uit dienst
originalHireDate
The first hire date of original hire date of an employee within the organization. This date is important for the tenure or working anniversary of an employee
P00834 -Datum in dienst CAO
employmentType
Type of employment like Internal employee, contractor, "Wachtgelder" Filter option for Row Authorisation (configuration API)
P01102 - Soort arbeidsrelatie
contractType
Type of the contact like indefinite period ('Onbepaalde tijd') or given time ('bepaalde tijd')
P08259 - Code contract (on)bepaalde tijd
jobProfile
Official job title or job profile of the employment. The Job profile contains the following details: shortName: Code or short name of the job profile
P01107 - Primaire functie
classification
group or classification of the employment. Generic field Filter option for Row Authorisation (configuration API)
P01110 - Code doelgroep
organizationUnit
organization unit Id of employment. The Id is a reference to the entity org units
P01106 - Hierarchische org. eenheid
workingAmount
Work amount of employment. amountOfWork: the amount of work unitOfWork: Unit of work that specifies the amount of work like "hours", "days", et cetera periodOfWork: Period of work like "week" or "month" parttimePercentage
P01109 - Uren per week P00404 percentage deelbetrekking
SalaryDetails (Dienstverband)
Id
Technical and unique id. the Id is unique within the entity and tenant. The id is generated by the system and can not changed by a user.
PersonCode
Person code to which the employment is related
P01001 - Persoonsnummer
employmentCode
Code of the employment
P01101 - volgnr dienstverband
GENERAL
typePaidWorkerCode
type of paid or unpaid worker
P00332 Code soort loner
SALARY DETAILS
payrollSchemeCode
payroll scheme related to the collective agreement
P00314 Code salarisregeling
payrollScale
Salary scale
P01151 Salaris
payrollSeniority
Salary step or seniority within the salary scale
P00326 Ancienniteit salaris
payrollAmountNo
salary amount number
P01152 Inpassingsnr salaris
GARANTEED SALARY DETAILS
GuaranteedPayrollScale
Garanteed salary scale.
P01157 Garantieschaal nummer
GuaranteedSeniority
Garanteed step or seniority within the garanteed scale
P01158 Ancienniteit garantieschaal
GuaranteedPayrollAmountNo
salary amount number
P00318 garantie salaris
CALCULATED SALARY DETAILS
CalculatedSalary
calculated gross salary by Beaufort
P01161 Berekend bruto salaris
CalculatedHourlySalary
calculated gross hourly salary by Beaufort
P01162 Berekend bruto uurloon
CalculatedGuaranteedSalary
calculated gross garanteed salary by Beaufort
P01159 Berekend garantiesalaris
CalculatedGuaranteedHourlySalary
calculated gross garanteed hourly salary by Beaufort
P01160 Berekend garantie uurloon
Assignments (Inzet)
assignmentID
Technical and unique id. the Id is unique within the entity and tenant. The id is generated by the system and can not changed by a user.
PersonCode / PersonId
Person code to which the employment is related
P01001 - Persoonsnummer
employmentCode / ContractCode / ContractId
Code of the contract
P01101 - volgnr dienstverband
startDate/validFrom
The date when the assignments start
P01125 - Ingang inzet
endDate/ValidUntil
The end date of the assignment. This is always an "up to and including" date. In unknown the field will not be visible in the API
P01126 - Einde inzet
jobProfile
Job title or job profile of the assignment. The Job profile contains the following details: shortName: Code or short name of the job profile
P01122 - Operationele functie
organizationUnit
Organization unit id of the assignment. The Organization Unit Id is a reference tot the organization unit entity
P01121 - Operationele org. eenheid
workingAmount
work amount of the assignment. amountOfWork: the amount of work unitOfWork : Unit of work that specifies the amount of work like "hours", "days", et cetera periodOfWork: Period of work like "week" or "month"
P01124 - Uren inzet per week
costCenter
the cost center of the Assignment
P01128 - Kostenplaats Inzet
costUnit
the cost unit of the Assignment
P01129 - Kostendrager Inzet
costType
the cost type of the Assignment
P01127 - Kostensoort Inzet
type
Type of assignment
P01123 - Soort Inzet
Cost allocation (Loonverdeling)
API Field
Description (English)
Beaufort field
Example
id
Technical and unique id. the Id is unique within the entity and tenant.
1000 1 0
PersonCode
Person code to which the employment is related
P01001 - Persoonsnummer
1000
employmentCode
Code of the contract
P01101 - volgnr dienstverband
1
sequenceNumber
Row number or sequence number or the cost allocation within the employee
P01131 - regelnr loonverdeling
0
costCenter
the cost center of the cost allocation row
P01134 - Kostenplaats loonverdeling
10000 - administratie
costUnit
the cost unit of the cost allocation row
P01135 - Kostendrager loonverdeling
10000 - Aministratie
costType
the cost type of the cost allocation row
P01133 - Kostensoort loonverdeling
41300 - Afdelingshoofd
percentage
Percentage of the cost allocation row
P01132 - Percentage loonverdeling
100
Leave Entitlements (Verlofrechten)
id
Technical and unique id. the Id is unique within the entity and tenant.
object id
PersonCode
Person code to which the employment is related
Persoonsnummer
employmentCode
Code of the contract
volgnr dienstverband
leaveType
leave type code, like WET for legal
P01430 code verlofsoort werknemer
leaveEntitlementYear
Year of the Leave entitlement
P01440 verlofjaar verlofrechten
leaveEntitlementLastYear
leave entitlement last year
P01442 verlofrecht vorig jaar in uren
leaveEntitlementThisYear
leave entitlement this year
P01443 verlofrecht huidig jaar in uren
leave hours (Opgenomen verlof in uren)
id
Technical and unique id. the Id is unique within the entity and tenant.
PersonCode
Person code to which the employment is related
Persoonsnummer
employmentCode
Code of the contract
volgnr dienstverband
leaveEntitlementYear
Year of the Leave entitlement
P01466 - verlofjaar verlofrecht
leaveType
leave type code, like WET for legal
P01465 - code verlofsoort
leaveSequence
leave request Id
P01460 - Volgnummer verloftijdvak
leaveDate
leave date
P01470 - Datum verlof
leaveHours
hours leave on specific leave
P01471 - uren verlof
Sickleave (Ziekte algemeen, uitgezonderd zwangerschapsverlof)
id
Technical and unique id of the sickness case. The Id is unique within the entity and tenant.
PersonCode
Person code to which the employment is related
Persoonsnummer
employmentCode
Code of the contract
volgnr dienstverband
startDate
first day of the sickness of the employee
P01600 Datum eerste ao-dag
recoveryDate
recovery date or first working day of the employee
P01606 Datum herstel
expectedRecoveryDate
Expected recovery date
P01605 Datum verwacht herstel toevoegen
Partial recovery
periodId
technical id of the partial recovery period
periodStartDate
The start date from which the new Illness percentages is valid
P01640 - Ziektetijdvak vanaf
percentage
The percentages the employee is still sick. the percentage is always related to the total amount of working hours of the employee itself
P01642 - Percentage ziek
Maternity leave (ziekte zwangerschapsverlof)
id
Technical and unique id of the Maternity leave. The Id is unique within the entity and tenant.
PersonCode
Person code to which the employment is related
Persoonsnummer
employmentCode
Code of the contract
volgnr dienstverband
startDate
first day of the maternity leave of the employee
P01600 Datum eerste ao-dag
recoveryDate
recovery date or first working day of the employee
P01606 Datum herstel
Q: How can I receive only changed records?
A: The From and To filter is available to receive changes in a given time range. The From and To filter option is available on most endpoints, except valueLists.
Example employees: Returns (active) employee records that have changed within the provided date-time range.
https://api.youforce.com/iam/v1.0/persons? from=2021-01-01T09:00:00.000Z &to=2022-01-10T14:00:00.000Z
Q: What does the 90 day retention policy signify?
A: At current, the retention policy on the data stored in for the IAM API is 90 days. Based on the following properties a record will be removed when the date defined for these properties is greater than 90 days in the past:
dischargeDate - employments, employees
endDate - role assignments, assignments
Q: Why do I see records with the with dischargeDates or endDates in the past?
A: We support the notion of retroactive changes i.e. when a dischargeDate for an employment or endDate for an assignment is defined today for a date is set in the past. This can be the result of an administrative mistake. In this scenario, the record will remain available for 90 more days based on the mutation date (date when the change was made).
Q: Why do I not see all the properties mentioned in the data mapping document in my response?
In the IAM API properties that do not have values defined in the core systems are hidden. For this reason there might be a different amount of properties available per record.
The File API allows you to download or upload files directly from Youforce, over HTTPS using the tool of your choice.
This API is controlled available and has consumption limitations. See API statuses
Concepts
Concept
Description
File API
Public endpoint to upload/list/download the files. In the request to File API, application id, business type and tenant are being identified. Once the files are uploaded to File API by a publisher application, the authorized subscriber application can list, download and delete the files.
Business Type
The files which are related to the same “business” are functionally grouped in File types called “Business types”. File types are represented by an integer called Business Type Id.
Client Application
Client Applications are the users of the system. They are identified by an application Id. Client Applications are also authorized to tenantId(s).Client application needs to obtain a authentication token by using credentials (client id and client secret).The token includes application id, tenant and permission of the application. Client Applications could be authorized either as publisher or subscriber of a business type.
Publisher
Publisher is a Client Application that can upload files of authorized business types and authorized tenants.
Subscriber
Subscriber is a Client Application that can download/list the files of authorized business types and authorized tenants.
Tenant
HR Core Client. Tenants are represented by tenant ids.
Authentication
We follow current industry standards and best practices. Authentication/authorization is not an exception. As part of the Identity and Access Management Strategy for system-to-system integrations, the File API is based on OAuth 2.0 and the authorization grant Client Credentials. Every API consumer system will be provisioned in our API Gateway as a Client Application (App). Client ID and Client Secret will be provided to be used by Apps as credentials. Thus, Apps will be able then to authenticate and get an access token (JWT) within the response payload. Subsequent requests authorization will be based on that access token previously retrieved.
Tenant Authorization
Client Applications (apps) need to be authorized to the corresponding Tenant (HR Core Client) in order to consume the API. By default, the applications are authorized to TenantId: sandbox.
File Type Authorization
Client applications (apps) need to be authorized as publisher or subscriber of business types
By default,sandbox apps are authorized to the Sandbox File Types.
Supported File Types
The File API has been designed to support a specific set of use cases. This may be extended over time, based on customer feedback. See list of Supported File Types.
Retention Period
The files will be physically deleted from Storage automatically after the retention period expires (1 month).
The metadata of the files (FileName, tenantId , BusinessTypeId, etc) is deleted after 6 months.
Samples
Here is an example of downloading a file using curl, available on most operating systems:
curl.exe https://api.raet.com/mft/v1.0/files/%fileid%?role=subscriber ^ --header "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." ^ --header "x-raet-tenant-id: 1234567" ^ --header "Accept: application/octet-stream" ^ --output @C:\Youforce\somefile.xml
See complete examples for curl (Batch), Powershell and .Net in Github.
Getting started
See the File API documentation to get started
User endpoint
The user endpoint supports the retrieval of users and to set an identity for a user, the following methods are supported as part of the users endpoint.
https://api.youforce.com/iam/v1.0/users
GET
Allows retrieving a single employee based on employeeId for the tenant specified in the request header.
https://api.youforce.com/iam/v1.0/users(employeeId=12345)
Supports the following parameter as part of the resource path:
employeeId - The unique id assigned to an employee
Returns a 200 OKwhen successful
PATCH
Allows to update or set an identity for a specific user based on employeeId for the tenant specified in the request header.
https://api.youforce.com/iam/v1.0/users(employeeId=12345)/identity
Supports the following parameters as part of its request body:
id- Ping Id of the employee which is to be used for SSO
{
"id": "user@customer.com"
}
Returns a 204 No content when successful Returns a 404 when the user account doesn't exists
Visibility of the change in Youforce portal
Please note that updating the identity through this endpoint
will update the identity in the Youforce authentication system
will NOT show the values in Youforce portal
Our authentication system is not running on the same service as the portal UI. The synchronization is just one way:
Changes done in the authentication system direct will not reflect in the Youforce portal UI
Changes done in this UI will reflect in the authentication system
This will be addressed in future, when we merge the two services.
Datamapping
Parameters
Description
Example
Data type
employeeId
The unique id assigned to the employee by the HR Core
12345
string
id
User id of the employee used in the Youforce authentication system
c7e230db-2a7f-4ef0-ad1d-9d30e7d94a2f
string
sourceId
Username of the user in the Youforce portal
XX123456
string
identityId
UPN/Identity in the customer authentication system that takes care of authentication Note: Only email format is supported
user@customer.com
string
General
Access to the Visma|Raet support desk
When Partner first starts using the Youforce API’s, Visma|Raet will create one end-user (hereinafter: Administrator) for Partner, who is given access to the Ticket system of Visma|Raet. An Administrator is an authorized person by Partner who uses the Youforce API’s and subsequently is able to create new Administrators. The Visma|Raet Ticket system is accessible through this link:
Log Support Ticket
Service Support
Questions about the functioning of Youforce API’s s are answered by Visma| Raet’s Service Center. We also process reports about malfunctions and deal with it adequately and ensure proper feedback. We offer these services to the registered, professional contact persons of Partner.
The designated contact persons of Partner, are able to report detected incidents to Visma Raet’s Service Center. This is possible via accessing the Visma|Raet Ticket system. In the case of escalation, you can contact us by telephone The ticket system of Visma|Raet grants access and information about the progress of submitted questions and the offered solutions. Contact persons are during the support process able to add information and react to the offered solutions by Visma|Raet.
Access by telephone of the Service Center
Access by telephone of the Service Center is meant for those situations where direct contact is needed to provide a solution or in case of escalation. The Service Center can be reached by telephone on workdays between 8:00 am and 6:00 pm.
We kindly ask you to enter your partner number and to choose between the Service on which the question is related to.
Our Stand-by Service can be reached by telephone outside work hours, for reports with respect to the availability of the Youforce APIs. The Stand-by Service is available on workdays between 6:00 am and 8:00 am and between 6:00 pm and 10:00 pm and during weekends between 6:00 am and 10:00 pm.
Note: The Stand-by Service is only for reports on malfunctions in the availability of the Youforce API’s applications and is not meant for substantive questions or for reporting other malfunctions.
FAQ
Who can get support?
Partners only. See How to become an Access Partner
How can I log a ticket on an API on login?
You will receive instructions for this as part of your access partner contract.
How long does it take before my ticket is picked up?
Visma | Raet applies four Support Level Codes to give the right priority to the malfunction and the corresponding response time. The distinction in Support Level Codes is based on the type, severity, the corresponding initial response time and the expected recovery time of the reported malfunction.
Code
Meaning
Description
1
High
The malfunction has a far-reached and immediate effect on the activities in the organization of the customer: activities cannot continue. There is no alternative solution that offers similar results.
2
Medium
The malfunction has a significant effect on the activities in the organization of the customer: An alternative solution is available, whether or not with some limitations.
3
Low
The malfunction has limited or no effect on the activities in the organization of the customer
The following resolution times relate to the Service Level Code, depending on the Service
Code
Meaning
Maximum duration
1
High
Solution by means of a workaround
90% within 24 hours
100% within 48 hours
Structural solution:
Within 30 calendar days
2
Medium
Structural solution:
Between 30-90 calendar days
3
Low Solution
The solution shall be included in the release calendar
How do get a login to the support tool?
You will receive instructions for this as part of your access partner contract.