This document describes the ‘De leerrekening (EduBookers) - Visma Raet Learning API’ - connector. This connector has been built on top of the Visma Raet Learning API.
With the documents endpoint files like certificates and other kind of documents can be uploaded for an employee to the Visma Personal File System (Personeelsdossier).
The API supports the following types of documents
certificate (Certificaat)
diploma (Diploma)
career agreement (Loopbaan afspraak)
career mail (Correspondentie loopbaan)
career other (Overige loonbaan documenten)
appraisal Review (Beoordelingsgesprek)
performance Review (Functioneringsgesprek)
As-synchronized file upload
Learning systems can upload files, like certificates, diplomas for individual employees to the Personal File System of Visma Raet. The file upload is an a-synchronized process. After the file is uploaded the consumer will receive a ticket Id, which can be used to monitor the process of the file upload.
Endpoints
The API supports the following type of documents:
API endpoint
Personal file system
endpoint
Document type
Description
learning/v1.0/employees/ {personCode}/documents/certificate
certificaat
Certificaat
learning/v1.1/employees/ {personCode}/documents/certificate
certificaat
Certificaat
learning/v1.1/employees/ {personCode}/documents/diploma
diploma
Diploma
learning/v1.1/employees/ {personCode}/documents/appraisalReview
beoordelingsGesprek
Beoordelingsgesprek
learning/v1.1/employees/ {personCode}/documents/performanceReview
functioneringsGesprek
Functioneringsgesprek
learning/v1.1/employees/ {personCode}/documents/careerAgreement
loopbaanafspraken
Loonbaan afspraken
learning/v1.1/employees/ {personCode}/documents/careerMail
corrLoopbaan
Correnspondentie loopbaan
learning/v1.1/employees/ {personCode}/documents/careerOther
ovLoopbaan
Overige loonbaan documenten
Note:
v1.1 is using Content-Type: multipart/form-data and supports the other document types as well.
v1.0 is using Content-Type: multipart/related and supports only certificates. We are advice you the use the latest version of an endpoint
To upload a document you need to use the POST method. For example POST https://api.youforce.com//learning/v1.1/employees/{personCode}/documents/diploma
for uploading a diploma to the Personal File System of Visma Raet. The endpoint returns a ticketId . The file will be stored in a standard folder for diplomas (see table for the other endpoints)
The API will automatically upload the file to the Personal File System. This is an a-synchronized process with an automatic retry mechanism in case the file systems is not available. The retry mechanism will try to upload the file in a maximum of 6 hours. After this period the file will be rejected with a message. Also if the file is too big (maximum 4 Mb) or isn’t a PDF file, the upload will be rejected.
GET documents/{TicketId}/status Endpoint for getting the status of the file upload. The endpoint will return the status of the file. After the file is processed successfully the status Complete is returned.
Examples
version 1.1 (all document types)
Use POST request with multipart/form-data content type.
Replace the PersonCode in the URL with the Id of the employee
Use the authentication token received from the authentication endpoint
Replace the tenant code with the tenant code of the client
Give the document a proper description
The field validFrom is optional. If it's empty the system date will be used as default
The content-type for the file is application/pdf Other type of files will be rejected by the API. The file size is also limited to a maximum of 4 Mb
Response
Example of the response.
HTTP/1.1 200 Content-Type: application/json { "ticketId": "7ca486f6-c730-4d50-a2ec-31a3a1373366", "description": "Example description", "size": 77491, "tenantId": "4028868", "creationDateTime": "2022-04-01T13:53:30.3985949", "status": "InProgress", "errorMessages": [] }
version 1.0 (certificates only)
Use POST request with multipart/related content type with the first part having metadata in json format and the second one having a file.
Replace the PersonCode in the URL with the Id of the employee
Use the authentication token received from the authentication endpoint
Replace the tenant code with the tenant code of the client
Give the document a proper description
The content-type of the metadata is application/json The content-type for the file is application/pdf Other type of files will be rejected by the API. The file size is also limited to a maximum of 4 Mb
POST https://api.youforce.com/learning/V1.0/api/employees//documents/certificate Authorization: Bearer [YOUR_AUTH_TOKEN] Content-Type: multipart/related; boundary=boundary_not_used_within_file_content --boundary_not_used_within_file_content Content-Type: application/json; charset=UTF-8 { "Description":"YOUR_OWN_DESCRIPTION", "ValidFrom" : "2021-01-01" } --boundary_not_used_within_file_content Content-Type: application/pdf [PDF Content] --boundary_not_used_within_file_content--
Upload status
After the file is posted to the API, the file upload can be followed with the status endpoint. Replace the TicketId in the URL with the ticketId from the previous API call.
GET https://api.youforce.com/learning/v1.0/employees/documents/{{TicketId}}/status
The API will return the status of the file upload. If the API could not upload the file, an error is shown as well.
Response
{ "status": "Complete", "errorMessages": [] }
API Statuses
Controlled Available (CA)
APIs (or API versions) with this status are not ready yet to be rolled out to the complete customer base:
It is available to a few partners
Connections of a partner to the customer environment (tenant) are put on a waiting list, and it will take time before the connection is accepted
There can be functional limitations of these APIs
Controlled Available APIs have the usual security and support level.
General Available (GA)
APIs (or API versions) with this status are available to all partners. The API can be used by all customers who use any of the HR Core systems that are supported by this API.
Deprecated
The API (or API version) is being phased out. We do not accept any new connections on this API (version). We will ask our access partners to move to another interface API. See also your Service Level Agreement.
Life cycle policy
We aim to provide you with a policy for releases and support for older versions for a consistent and predictable experience.
You can also find this information in the Service Level Agreement.
Different types of changes
The life cycle of any API products has dependencies on underlying products. Changes in those products may require changes to the API to support it. We distinguish between breaking changes and non-breaking changes. A breaking change is one that breaks the contract an API consumer depends on, either by a change in structure, behavior or semantics. The release and support strategy makes a clear distinction in how these are managed.
Major releases
At times Raet may need to make larger changes to the API. Reasons may be changes to legal requirements, adding a large new feature to the API or an change in other products the API depends on. In these cases Raet may create a new major release of the API. We strive to also keep major releases backward compatible as much as possible but this may not always be possible. In case of breaking changes In general Raet aims to have a maximum of one major release per year.
Each major release will be supported for at least 24 months after releasing the next major version.
As a client to our API you will have to adjust your software to follow the major releases of our API as they will impact your integration. You must update your software to support the new API version as older API versions will be decommissioned following the policy as outlined above.
Minor releases
A minor release will never contain breaking changes, the are used to deliver incremental changes. Minor versions will not be visible in the path of the API. Raet can install minor updates in the standard release windows or as part of a hotfix and will communicate the changes as part of the release notes. Since this does not impact any existing functionality, we do not provide side-by-side support for multiple minor versions of the same major version: a minor upgrade just replaces the previous version.
As a consumer of the API it is up to you to decide if you start using the newly available features.
Announcing major releases
Each release of a major API version will be accompanied by communication about the support lifecycle of the current version in the release notes.
When approaching the sunset-date for an API product, we will actively reach out to inform any customers still using it:
Communication
When
Where
Recipient
Announcement
At the release of the new major version. Includes the date of decommissioning the previous version.
General release notes
All recipients of general release notes.
At the release of the new major version. Includes the date of decommissioning the previous version.
Developer portal
Designated API contact persons
1st notification
6 months prior to decommissioning
Designated API contact persons
2nd notification
3 months prior to decommissioning
Designated API contact persons
3rd notification
1 months prior to decommissioning
Designated API contact persons
Spike arrest details
Spike arrest is the way we protect against traffic spikes. Our APIs and backend can handle a certain amount of traffic, and the Spike Arrest policy smooths the traffic to the general amounts.
Spike Arrest’s behavior differs from what you might expect to see from the literal per minute values.
Our default spike arrest is set to 100pm (100 requests per minute). That does not mean you can do 100 requests inside a 1-second. Spike Arrest smooths the number of full requests in a minute by dividing it into smaller intervals:
Per-minute rates get smoothed into full requests allowed in intervals of seconds.
For example, 100pm gets smoothed like this: 60 seconds (1 minute) / 100pm = 0.6-second intervals, or 1 request allowed every 0.6 seconds. A second request inside of 0.6 seconds will fail. Also, the 101st request within a minute will fail.
When you exceed the policy, the API will return response code '429 - Too many requests' and you have to wait for the next time window.
Choose an API product
Youforce has several API products available, you find more information here:
https://developer.visma.com/api/youforce
Every API covers a different use cases, for example
The IAM API is intended for identity & access management systems and enables the provisioning of users in other systems like Active Directory or IDP.
The Learning API provides employee data that is relevant for applications in the learning, development, appraisal domain, etc.
The File API allows you to download or upload files directly from Youforce.
In this way we help to achieve ‘purpose binding’ required to safeguard the privacy of employees and to comply with GDPR legislation. It furthermore allows us to tailor and grow the API supporting specific needs in that domain
Create an account and application To use an Youforce API product, you must register and create an account. An account is quick to set up and is free of charge. A step by step manual is availible here.
Get the access token
In order to grant access to a target API, Apps must first authenticate against our Authorization Server.
This token will provide access to a particular tenant in a specific application. Hence, this step will require knowing the client-id, client-secret and tenant-id.
curl -X POST
'https://connect.visma.com/connect/token'
-H 'Cache-Control: no-cache'
-H 'Content-Type: application/x-www-form-urlencoded'
-d 'client_secret=xxxxxxx
&client_id=xxxxxxxx
&tenant_id=xxxxxxxx
&grant_type=client_credentials'
Below, a response example containing the access token, the authorized scopes and the expiration time which is 1 hour max. After that time Apps need to re-authenticate to get a new access token.
{
'access_token':'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
'expires_in': '3600',
'token_type': 'Bearer',
"scope": "youforce-fileapi:files:list youforce-fileapi:files:upload"
}
HTTPs support
Our API's domain is secured by using digicert (SHA2) certificates, a world wide industry-recognized provider.
Protocol
TLS 1.2 (only)
Key exchange
ECDHE RSA with X25519
Cipher
AES_256_GCM
All HTTP Requests will be refused with a Not Found 404 error response.
Request headers
Our APIs have headers in common
Header Name
Description
Cache-Control
The Cache-Control general-header field is used to specify directives that MUST be obeyed by all caching mechanisms along the request/response chain.
In our authentication request the header is mandatory with the value
Cach-Control: no-cache
Content-Type
The content type of the resource in case the request content in the body. Example:
Content-Type: application/x-www-form-urlencoded
Authorization
The information required for request authentication
Accept
The Accept request-header field can be used to specify certain media types which are acceptable for the response. Example:
Accept: text/plain
Response Codes
Our APIs have response codes in common.
Type
Responses
Situation
Succes Codes
200 OK
Synchronous read, update, and delete operations
201 Created
Synchronous create requests
202 Accepted
A-synchronous operations
204 No Content
Referring to non-existing entity (e.g. after delete)
Redirection Codes
304 Not Modified
Resource has not been modified.
308 Permanent redirect
Resource has permanently moved.
Invalid Request Errors
400 Bad request
Bad Request (e.g. validation errors)
401 Unauthorized
Not Authorized: Missing or invalid access token
403 Forbidden
Not Authorized: Authenticated, but user has no access to the API
404 Not Found
Invalid URL: Item does not exist (anymore). The canonical identifier (collection/{canonical id}) cannot be found. Not Authorized: Authenticated, access to api, but user has no access to to the resource (data authorization). From a security standpoint we don't expose the reason why the object could not be found because an attacker can use this to figure out the internals of our system.
409 Conflict
Concurrency problem: Record changed by another user
Server Errors
500 Internal server error
Server Error (e.g. database failure, event could not be send)
503 Service unavailable
Server Error (resource temporary not available)