Leave, absence and time
Deputy to YouForce integration: timesheets approved for pay as pay components per employment
With an integration between Deputy and Visma Raet YouForce, timesheets approved for pay in Deputy go to YouForce automatically as pay components, per employment and per date. Only once YouForce has processed the delivery does KoppelHet mark the timesheets as paid in Deputy, and new employees from YouForce are in the roster on time.
What the integration does
Organisations that schedule in Deputy and run Dutch payroll in Visma Raet YouForce export the timesheets per period and enter the hours per pay component in YouForce. Someone with two employments then easily gets the hours on the wrong number, and a shift changed in Deputy after the export falls outside the payroll run.
- HR records a new employee or change in YouForce, also when it takes effect later.
- KoppelHet places the employee in Deputy at the location that belongs to the organisation unit, with the employment number as payroll ID.
- Managers in Deputy approve first the time and then the pay.
- KoppelHet delivers the hours per pay rule as a pay component to YouForce and follows processing per ticket.
- Processed timesheets are marked as paid in Deputy; rejected lines appear as an alert in the platform.
Back: Hours per pay rule as pay component · Premium hours Deputy calculates with pay rules
What to watch for with Deputy and Visma Raet YouForce
- YouForce books pay components on an employment, not on a person. Deputy stores the payroll ID per agreement at a location. KoppelHet puts the YouForce employment number there, so someone with a permanent and an on-call contract gets the hours on the right contract.
- An elementCode in the delivery must exist in YouForce as a field code of the employment. Deputy gives each pay rule its own export code. Before the first period payroll records the elementCode per export code; a pay rule without a translation is not sent and is reported.
- YouForce rejects a delivery in which the same elementCode appears twice, and accepts at most a hundred elements at a time. Deputy returns separate pay lines per timesheet, also for the same kind of hours on one day. KoppelHet totals them per elementCode and date and spreads them over deliveries, so each code appears only once per delivery.
- YouForce processes a delivery later and first returns only a ticket number. A paid timesheet is locked in Deputy. KoppelHet therefore waits for the ticket status Complete before marking the timesheets as paid; on Error the timesheet stays correctable in Deputy.
- Deputy marks timesheets as paid per pay period, and a single timesheet from another period makes the whole call fail. YouForce does not know those periods, as it works with the date per element. KoppelHet remembers per ticket which Deputy period belongs to it and returns the status per period.
- YouForce records planned changes ahead, such as a transfer to another department from next month. KoppelHet only changes the location in Deputy on the effective date, so the current location can keep scheduling until that day.
- A leave balance in Deputy is overwritten, not added to. YouForce supplies leave entitlements per employment and leave type, but only for the last two years and with a separate read scope. KoppelHet therefore sends the full balance per type, and only if you want it.
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
Who calculates the premiums, Deputy or YouForce?
We agree that beforehand. If Deputy calculates the premium with a pay rule, it goes as its own pay component. If YouForce calculates it, we only send the worked hours.
What if YouForce rejects a line?
Then the timesheet stays unpaid in Deputy and YouForce's error message appears in the platform. After correction it goes in the next round.
Technical details for IT
For those who want to know how it works under the hood: APIs, fields and sources used.
- Deputy is read through the resources Timesheet (TimeApproved, PayRuleApproved, PaycycleId) and TimesheetPayReturn (Value per PayRule), and through webhooks with a SHA-256 HMAC in X-Deputy-Secret. Marking as paid through POST /api/v1/payroll/mark/{periodid}/paid with TimesheetIdArray; the PeriodId comes from EmployeePaycycle. Employees through management/v2/employees with workplaces[].agreement.payrollId, leave balance through LeaveAccrual.
- To YouForce through the WFM API, POST /{domain}/v1.0/PayComponents/{employment} with elementCode, value and effectiveDate per element; at most 100 elements and no duplicate elementCode per request. Processing is asynchronous; GET /{domain}/v1.0/PayComponents/{ticketId}/status returns None, InProgress, Complete or Error. Scope Youforce-WFM:Write_Basic.
- YouForce is read with Get_Basic (Persons, Employments, Employment Planned Changes, Organization Units) on latestSync with from and to; leave entitlements with the Get_leave scope.
Which fields are transferred
The key fields. The full mapping is agreed per customer.
| Field in Deputy | Field in Visma Raet YouForce | Notes |
|---|---|---|
workplaces[].agreement.payrollId | Dienstverband (employment) in de URL van PayComponents | The employment number, not the person number |
PayRule.PayrollCategory (exportcode) | elementCode | Must exist as bo4FieldCode in YouForce |
TimesheetPayReturn.Value | value | |
Datum van de timesheet | effectiveDate (yyyy-MM-dd) | |
YouForce organizationUnit (terug) | primaryLocation | Through a table to Deputy locations |
YouForce persoon en startdatum dienstverband (terug) | firstName, lastName, startDate | |
YouForce Leave Entitlements (terug) | LeaveAccrual | The full balance, Deputy overwrites |
Related
Deputy → AFAS Profit
Deputy to AFAS integration: approved timesheets to the payroll run, employees and leave balance back
Deputy → Nmbrs
Deputy to Nmbrs integration: approved hours as variable hours in the right period
HiBob → Deputy
HiBob to Deputy integration: employees, approved time off and leave balances from Bob in the schedule
Personio → Deputy
Personio to Deputy integration: employees and approved absences from Personio in Deputy, worked time back as attendance