Learning File upload

[#1]

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": []
}