Leave, absence and time
vPlan to YouForce integration: approved hours from vPlan as pay components in YouForce, employees from YouForce as resources
With an integration between vPlan and Visma Raet YouForce, approved hours from vPlan's time tracking go to YouForce as pay components, per employment, pay code and date. The other way, employees from YouForce appear in vPlan as resources, with start and end date, so work planning and payroll cover the same people.
What the integration does
Organisations that plan work in vPlan and have hours booked there often retype overtime and extra hours for payroll into YouForce, or deliver them in a spreadsheet. New colleagues only appear in vPlan once someone creates them there, and an employee who has left stays visible as a resource.
- An employee books hours on a card in vPlan and the planner or team lead approves them.
- KoppelHet fetches the approved entries, with the resource linked to the user.
- The activity determines the pay code. KoppelHet totals the hours per employment, pay code and date and sends them to YouForce.
- As soon as YouForce has processed the delivery, the entries in vPlan are locked. A rejected line gets the error message from YouForce in vPlan.
- A new employment in YouForce becomes a resource in vPlan; an end date becomes the end date of that resource.
Back: Employees and employments from YouForce as resources in vPlan
What to watch for with vPlan and Visma Raet YouForce
- In vPlan a time entry belongs to a user, not to a resource. Only when that user is linked to a resource can you tell which employee the hours belong to. KoppelHet fetches the entries including that resource and reports hours of users without one, so they do not drop out of payroll unnoticed.
- An entry in vPlan is draft, pending, approved or rejected. Only approved hours go to YouForce. KoppelHet then locks the entry and sets the sync date, so hours that are already in payroll are not changed quietly.
- YouForce processes pay components after delivery; the first response only contains a ticket number. KoppelHet follows that ticket and, on an error, puts the message from YouForce into the fields vPlan has for external integrations, so the planner sees on the entry itself what went wrong.
- YouForce accepts at most 100 lines per request, and a pay code may appear only once in a single request. Someone who books on three cards in vPlan on one day first produces three lines. KoppelHet totals them per pay code and date into one line per employment.
- Which pay codes an employment in YouForce may receive is fixed per employment. In vPlan the activity determines what kind of hours they are. KoppelHet links each activity to a pay code and checks in advance that the code belongs to the employment; otherwise an alert appears instead of a rejected delivery.
- The employee's YouForce number sits in vPlan as the external reference on the resource, and it must be unique, including against archived resources. When a former employee is rehired, KoppelHet reactivates the existing resource, because vPlan refuses a second resource with the same number.
How we build and run it
- The integration runs on the KoppelHet platform, hosted in a data centre in the EU.
- Every sync and every error is visible in the functional log; on an error your administrator is notified.
- A change that cannot go through is not half-applied but queued for another attempt.
- KoppelHet is ISO 27001 certified. Data travels encrypted and stays on the platform no longer than needed.
- After go-live we manage the integration and adjust it when your process changes.
- The integration fits next to your existing integration layer. Only the fields in the design are transferred; the platform keeps no register of its own.
Implementation and price
This is not an app you switch on. We build the integration for your organisation on our platform, with building blocks we reuse on every project. So it is custom work that does not start from scratch.
A consultant prepares the intake and analyses both systems. We then record the mapping and exceptions field by field, test in the test or acceptance environment and go live at a moment you choose. Costs are a one-off amount for the setup and a monthly amount for platform, monitoring and support.
Frequently asked questions
Do all booked hours go to YouForce?
No, only the activities you link to a pay code, such as overtime or allowance hours. Hours that only matter for job costing stay in vPlan.
What happens to hours corrected after processing?
Processed entries are locked in vPlan. A correction is entered as a new entry, so YouForce only receives the difference.
Can leave from YouForce also reach vPlan?
That can be added later as an extension, through the resource's schedule per date. This integration starts with hours and employees.
Technical details for IT
For those who want to know how it works under the hood: APIs, fields and sources used.
- vPlan through the vPlan API (https://api.vplan.com/v1) with OAuth 2. Time entries through GET /time_tracking with eager loading of user.resource; status draft, pending, approved or rejected. Feedback with PUT /time_tracking/{time_tracking_id} (locked, synchronized_at, external_failed, external_note). Resources through POST /resource with external_ref (a duplicate returns 422 Duplicate entry), start_date and end_date.
- To YouForce through the WFM API, POST /{domain}/v1.0/PayComponents/{employment} with elementCode, value and effectiveDate; at most 100 elements and no duplicate elementCode per request. Status through GET /{domain}/v1.0/PayComponents/{ticketId}/status (None, InProgress, Complete, Error with errorMessage). Scope Write_Basic; employees and employments are read with Get_Basic.
Which fields are transferred
The key fields. The full mapping is agreed per customer.
| Field in vPlan | Field in Visma Raet YouForce | Notes |
|---|---|---|
user.resource (vPlan) | Dienstverband (employment) in de URL van PayComponents | Through the YouForce number in the resource's external_ref |
activity_id | elementCode | Through a mapping table; only codes from the employment's bo4FieldCode |
duration, of start en end | value (uren) | |
start (datum) | effectiveDate (yyyy-MM-dd) | |
status approved | Voorwaarde om te versturen | |
Resultaat van het ticket | locked, synchronized_at, external_failed en external_note (vPlan) | |
personCode en employmentCode (YouForce, terug) | external_ref van de resource | |
hireDate en dischargeDate (YouForce, terug) | start_date en end_date |
Related
vPAFAS Profit → vPlan
AFAS to vPlan integration: employees as resources, schedule hours and leave in work planning
vPHiBob → vPlan
HiBob to vPlan integration: working pattern from Bob as workdays, time off as deviation in the plan
vPNmbrs → vPlan
Nmbrs to vPlan integration: employees, alternating work weeks and approved leave in production planning
vPPersonio → vPlan
Personio to vPlan integration: employees and approved absences from Personio in the plan