1. Overview
Domain Purpose:
The WorkForce Management domain enables integration between HR Core and external Workforce management systems who are responsible for the planning of employees within an organization. As an organization, I want to know the capacity of my employees, so that planners in our system are able to do the resource planning.
We talk about capacity in terms of “which employees and for how many hours they are available” or “Which absences do we take in account (planned and unplanned)”.
Typical Use Cases:
- As a planning system I want to know the joiners and leavers so that I can manage the user-accounts of the user within the planning system
- As a planning system I want to know which employees are on a sick leave or maternity leave to plan accordingly within the planning system
- As a planning system I want to know the leave balance of the employee, especially when there is a contract change
- As a planning system I want to export the worked hours or other variables of the employees, so that they get paid by the payroll system of Visma
Base URL:
https://api.youforce.com/wfm
2. Domain model
3. Included entities
This is the list of available endpoints for this domain.
Take into account that the endpoints will show the information that has been already processed by BO4. This means that changes in the recent future might be shown in the response of the APIs and not the current value.
| Entity | Description | Access capabilities |
|---|---|---|
| Assignments | Allocation of specific tasks or duties to an employee within an employment. For example, an employee is assigned to a different department as a temporary replacement or to help another department without changing his own employment. HR Core: Inzet | READ |
| Cost Allocations | Regarding the distribution of financial resources or expenses across different departments or projects, it is the cost center of an employee. An employee can have multiple cost allocations. HR Core: Loonverdeling | READ |
| Employments | The formal relationship between an employer and an employee regarding their job position. A person can have multiple employments at the same time. HR Core: Dienstverband | READ |
| Employment Timelines | The chronological sequence of events in the past pertaining to an individual’s employment within an organization, including start and end dates. It is based on the history table of Beaufort. The endpoint contains the same fields as the endpoint employments. HR Core: Dienstverband Historie | READ |
| Employment Work Schedules | The planned working hours and days for an employee within their employment. HR Core: Werkrooster | READ |
| Entitlements | Different users that have a certain entitlement. | READ |
| Job Profiles | Different profiles or functions existing for each role within the company. HR Core: Functie | READ |
| Leave Entitlements | Extra adjustments made to an employee’s leave entitlement due the decision of the employee to buy or sell a specific amount of leave hours. HR Core: Verlofrechten | READ |
| Leave Entitlements Changes | Extra adjustments made to an employee’s leave entitlement due to certain employment circumstances. HR Core: Verlofrecht Mutaties | READ |
| Leave Hours | Specific number of hours of leave taken or scheduled by an employee. HR Core: Verlof tijdvakken | READ |
| Maternity Leave | Leave granted to an employee around the time of childbirth or adoption. HR Core: Ziekte zwangerschapverlof | READ |
| Organization Units | Distinct business units, departments, divisions, etc within a larger organization that represent functional or geographical areas and how these are related to each other. HR Core: Organisatie eenheden | READ |
| Pay Components | The WFM system can share the number of hours of overtime, extra shifts etc. that are relevant for the payroll. | WRITE |
| Persons | An individual employee or worker within the organization, including some personal details. This could also contain people without (active) employment. Additionally, if the person has an employment which is out of the historicaldays, then the person won’t be retrieved neither. HR Core: Persoon | READ |
| Planned Changes | Changes in employment type, organization unit, job profile and amount of hours that will come in the future detailing the start and end dates of the change. HR Core: Indirecte Mutaties | READ |
| Role Assignments | Role Assignments: Allocation of specific roles or responsibilities to a person within the organization. The role assignment describes “who” is responsible for “what“ and “when“ within the organization unit. HR Core: Rol toewijzing | READ |
| Salary Details | Information regarding an employee’s salary, including base pay, payroll scale, seniority, … HR Core: Dienstverband | READ |
| Sick Leave | Leave granted to an employee due to illness, including the sickness periods, allowing them to recover without job or pay loss. HR Core: Ziekte algemeen | READ |
| Work Patterns | The agreed schedule of working hours along the days and rest periods for an employee. HR Core: Werkpatroon | READ |
4. Security and Scopes
All available endpoints are secured using OAuth 2.0 and protected by scopes.
| Scope | Description | Affected endpoints |
|---|---|---|
| Youforce-WFM:Get_Basic | Grants access to basic employee & organisation data | GET /v1.0/assignments GET /v1.0/costAllocations GET /v1.0/employments GET /v1.0/employments/timelines GET /v1.0/employments/plannedChanges GET /v1.0/employmentWorkSchedules GET /v1.0/entitlements/{Entitlement}/users GET /v1.0/jobProfiles GET /v1.0/organizationUnits GET /v1.0/persons GET /v1.0/roleAssignments GET /v1.0/workPatterns |
| Youforce-WFM:GetPrivateContactDetails | Grants access to private contact details like address, phone number and email address of the employees | GET /v1.0/persons Extra fields shown: emailAddresses, phoneNumbers, addresses |
| Youforce-WFM:Get_leave | Grants access to leave entitlements and leave request | GET /v1.0/leaveEntitlements GET /v1.0/leaveEntitlementChanges GET /v1.0/leaveHours |
| Youforce-WFM:Get_maternityLeave | Grants access to Maternity leave data | GET /v1.0/maternityleaves |
| Youforce-WFM:Get_salaryDetails | Grants access to Salary details | GET /v1.0/salaryDetails |
| Youforce-WFM:Get_sickleave | Grants access to Sickness data | GET /v1.0/sickleaves |
| Youforce-WFM:Write_Basic | Enables to write back changes for payroll calculation (hours & other paycomponents) | POST /v1.0/payComponents/{ComponentId} GET /v1.0/payComponents/{TicketId}/status |
5. Pagination & Filtering parameters
Learn how to efficiently manage large amounts of information by using pagination and filtering parameters to improve performance and user experience.
Pagination Parameters:
These parameters control the pagination of API results:
- take: Use this parameter to retrieve a certein amount of registers per call, being the minimun value 1 and the maximum value 1000.
- skip: Use this parameter to skip a certein amount of records. Use it for offset-based pagination.
- nextLink: For large paginated responses, if there are more registers than shown in the output, we will provide a continuation token that you can use in the next call to get the next page.
Date Filtering Parameters:
These parameters filter records based on creation or modification dates:
- from: Use this parameter to filter records based on creation or last modification dates and retrieve records which modification date is greater or equal to the value in the filter.
- to: Use this parameter to filter records based on creation or last modification dates and retrieve records which modification date is less or equal to the value in the filter
Filters on validity of a record
- validOn: Use this parameter to filter temporal entities that are valid on a specific date (e.g., contract validity based on its start and end dates).
This filter is meant to be used in combination with From and To parameters. For example, with From and To you will get the Employments that are modified in a specific range, and with validOn you will limit the response to the records that are active on a specific date.
Available endpoints: timelines, assignment and role assignment endpoints.
Other Parameters:
- isActive: Use this parameter to distinguish between active or deleted records. It doesn’t correspond to the block field in BO4.
Available for all endpoints. - personId, personCode: Use one of these parameters to filter indistinctly by the code of an specific individual.
Available endpoints: Assignment, CostAllocation, Person, RoleAssignment and PlannedChanged. - company: Use this parameter to filter by company field.
Available endpoints: Employment. - organizationUnit: Use this parameter to filter by department or team structure.
Available endpoints: Employment. - shortName: Use this parameter to filter by the short name of an organization unit or job profile depending on the endpoint.
Available endpoints: JobProfile, RoleAssignment and OrganizationUnit. - statusFrom: Use this parameter to filter records based on the status date field and retrieve records which status date is greater or equal to the value in the filter.
Available endpoints: PlannedChanges. - statusTo: Use this parameter to filter records based on the status date field and retrieve records which status date is less or equal to the value in the filter.
Available endpoints: PlannedChanges. - status: Use this parameter to filter records based on the status field. The possible values are: pending, processed, blocked and rejected.
Available endpoints: PlannedChanges endpoint.
6. Deprecated Endpoints
List of Deprecated Routes:
- GET /v1.0/EmploymentTimelines:
This behavior has been incorporated as part of the Employments endpoint –> GET /v1.0/Employments/Timelines - GET /v1.0/EmploymentTimelines/{id}:
This behavior has been incorporated as part of the Employments endpoint –> GET /v1.0/Employments/Timelines/{id}
7. Swagger page
For more detailed information about the endpoints available in this API, please visit the Youforce wfm API Swagger page