Mijn Communities
Help

Learning File upload

21-12-2021 16:25 (Bijgewerkt op 28-03-2023)
  • 0 Antwoorden
  • 0 kudos
  • 1022 Weergaven

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.

 

file upload.png

 

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-Typemultipart/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

RenSanders_1-1648820874404.png

 

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

RenSanders_2-1648821127478.png

 

 

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