Working Time Directive Report (2024)

Note: This integration is an extension that is developed outside the normal release schedule to meet specific customer needs. To request one of these extensions, you must submit a Salesforce Service Request to UKG. After the extension is delivered to your tenant, you can edit it accordingly.

The Working Time Directive (WTD) is health and safety legislation that protects employees from working excessive hours. The directive requires employers to track and report on the average amount of time employees worked during a configurable reference period. Typically, the maximum is 48 hours of excess time over 17 weeks. This directive is a law in the United Kingdom.

The Working Time Directive Report integration exports the average worked or scheduled hours for employees based on the anchor date and the Working Time Directive rule that is assigned to the employee.

This integration exports the average amount of worked or scheduled time during the reference period. The reference period can include weeks that occur completely in the past, future or a combination of past and future. The current week is considered part of the future, in this context. For past weeks, the calculation relies on worked hours, and for future weeks (including the current week), the calculation relies on scheduled hours.

The following options are configurable:

Number of weeks and maximum threshold to use to compute the average hours
Which paycodes A category of time or money that employees earn, for example, Regular Hours, Bonus, or Sick. to consider for worked time and which paycodes to exclude
Whether to extend the averaging period with a number of excluded days
Anchor date around which to generate the audit either forward or backward in time

Use cases

Use case 1:

A manager works for a company and has to provide a report for the Working Time Directive audit for a group of employees in one store.

The audit spans the first period in 2020, so the Anchor Date = 1/1/2020.
The First Day of Week = Monday, so the report starts on the first Monday after the anchor date, which is 6/01/2020 (European date format = dd/mm/yyyy).

Example report for the group of employees

The report shows that one employee is in violation of the average worked time, which cannot be higher than 48:00 hours.

This employee worked on average 56:01 hours in the first 17 weeks of the year, which violates the Working Time Directive.
Also during this period, the employee had 5 days excluded from the average calculation. These days are added to the reference period so that the employee’s averaging period is extended by 5 working days which extends the 17-week audit period to 8/05/2020 instead of 3/05/2020.

To follow-up on this violation of the Working Time Directive, the auditor requests multiple iterations of the report to verify whether this violation was an exception or part of a pattern of consistently working more hours than are allowed.

The manager launches an audit for the one employee who is in violation, with up to 10 iterations to produce a rolling audit of the Working Time Directive average between January 6 and July 5, 2020, to get a comprehensive overview.

Example report for one employee

Use Case 2:

The Working Time Directive rule is configured to evaluate 17 weeks of data. Employees are non-compliant when the average weekly hours exceed 42.

An employee worked 50 hours each week for each of the previous 6 weeks. The employee is scheduled to work 40 hours each week for the next 11 weeks.

The Working Time Directive Report is executed for the 17-week period and the extension calculates:

Total hours worked: 6 *50 = 300

Total hours scheduled: 11 * 40 = 440

Average hours for each week: (300 + 440) / 17 = 43.5

Calculations show that the employee is likely to end up with a violation, indicating that a schedule adjustment is needed.

Before you start

Before you configure this integration, you must do the following:

Configure Access to Integrations.
Configure the following:

Custom field labels: In the people information record for each employee, create the following custom fields:

WTD Rule Name

WTD Opted In-Out

See the Custom Field Labels topic.

Get the URL, User, and Password for the APIGatewayServer.

Configure the Working Time Directive Report integration

For more information, see the Deploy Integrations topic.

Open the Integration Template Designer: Select Main Menu> Administration > Application Setup > Integrations Setup > Design Integration Templates.

Note: If prompted, enter your Username and Password. Click Tap Log in.
Make sure that the Account is correct. If not, select the right account.
Select the Deploy tab > Integration Packs.

From the list in the left column, search for and select the Pro WFM Working Time Directive Report Extension integration.

Note: If the integration does not display, select Browse Integration Packs to search for and select the iPack.

Click Tap Install.

From Unattached Environments, select the environment in which to deploy the integration process for the selected integration. Click Tap the double-left arrows button.

Configure the Working Time Directive Report integration settings

Select the environment

Select the Manage tab > Atom Management.
Select your environment.

Select environment extensions

In Administration, click tap Environment Extensions.
In Process Filter, click tap the magnifying glass.It can take several seconds before the button becomes active.

Scroll to and select the integration pack: Working Time Directive Report > WorkingTimeDirectiveReport_iPack_v3.

Configure connection settings

Caution: If you select Use Default for the connection settings and process properties, ensure that Value is blank. If Value is not blank, that value overrides the default value whether or not Use Default is selected or cleared. Example: If the default value is abc, but Value shows xyz, the integration uses xyz regardless of the setting of Use Default.

Select Connection Settings.

From the Connection list, select and configure the following:

Connection Settings
Setting	Required	Actions
WorkingTimeDirectiveReport_iPack_v3_APIGatewayServer	Required	To change the default API gateway server: Clear Use Default. Enter the URL to the server. Example: <tenantURL>/api
WorkingTimeDirectiveReport_iPack_v3_SFTPServer	Required	The SFTP server setting defines the connection to the file that contains the records. Integrations access only the internal SFTP account. To change the default SFTP server parameters: For each field, clear Use Default. Enter the following values: Enter the name of the internal Host. Enter the number of the Port for the internal SFTP account. In User, enter the username for the internal SFTP account. In Password, select <Encrypted>. Enter the new password for the internal SFTP account. Click Tap Apply.
WorkingTimeDirectiveReport_iPack_v3_Rules_CRT	Required	Enable Override.

Configure process properties

Select Process Properties.
Caution: Do not edit the default values of the AuthenticationProperties. By default, cookies are enabled and set the values for authentication properties.

Select WorkingTimeDirectiveReport-v2_ProcessProperties to set process properties that must be configured before the integration can run. This main process starts the integration process and handles errors.

Process Properties
Process property name	Column header value
_WorkingTimeDirectiveReport_iPack_v3_Rules_CRT	WTD Rule,Included Hours,Excluded Hours,Include Hours Threshold (hh:mm), Excluded Hours Threshold (hh:mm),Average Period (Weeks),MaximumAverage Period Days,Max Weekly Average (hh:mm:),First Day of Week

Configure cross-reference tables

Cross-reference tables (CRT) are the look-up tables that the integrations use to translate parameter values. One or more data values from the source system can be used to assign one or more parameters in the destination system.

If more than one row matches a reference value, the first match is the output value.
If no match is found, the output value can be null, or the integration can produce errors.

Select Cross Reference.
From the Cross Reference list, select the Working Time Directive table.
Select Override, which allows you to:

Download the tables when you run the integration.

Edit the table cells in Extensions.

When you finish, click tap OK.

WorkingTimeDirectiveReport_iPack_v3_Rules_CRT

Working Time Directive Report - Rules CRT structure
Column name	Description
WTD Rule	A unique Working Time Directive rule name.
Included Hours	The combined paycode that tracks the hours to include in the average calculation.
Excluded Hours	The combined paycode that tracks the hours to exclude from the average calculation.
Included Hours Threshold (hh:mm)	The minimum number of hours that are required in the combined paycode in order to be included in the average calculation. When the employee's worked hours in Excluded Hours fall below Excluded Hours Threshold (hh:mm) and their worked hours in Included Hours fall below Included Hours Threshold (hh:mm), the day is ignored. No patching is required. When the employee's worked hours in Excluded Hours exceed Excluded Hours Threshold (hh:mm) and their worked hours in Included Hours meet or exceed Included Hours Threshold (hh:mm), the day is ignored. Patching is required.
Excluded Hours Threshold (hh:mm)	The minimum number of hours that are required in the combined paycode in order to be excluded from the average calculation.
Average Period (Weeks)	The number of weeks to use for the averaging period.
Maximum Average Period (Days)	The maximum number of days to average, or the performance cap if excluded days are added to the overall average period.
Max Weekly Average (hh:mm)	The maximum average weekly hours as defined in the directive; any hours above this threshold put the employee in violation of the WTD rule.
First Day of Week	The first day of the work week.

Example Working Time Directive Report — Rules CRT content
WTD Rule	Included Hours	Excluded Hours	Included Hours Threshold (hh:mm)	Excluded Hours Threshold (hh:mm)	Average Period (Weeks)	Maximum Average Period (Days)	Max Weekly Average (hh:mm)	First Day of Week
WTD1	All Worked	All Absence	00:01	4:00	17	365	48:00	Monday
WTD2	All Worked	All Absence	00:01	5:00	17	356	40:00	Sunday

Install the Working Time Directive Report integration

After the integrations are deployed and the connection settings and process properties are configured, install the integrations to make them available for running or scheduling.

Note:

An integration template is the configured integration that you deploy to an Atom and then install to make available for running or scheduling.
An installed integration is a single instance of an integration that is based on an integration template. When you install an integration, you can define parameters or set parameters to be defined when the integration is run.

Select Main Menu>Administration>Application Setup>Integrations Setup>Install Integrations.
Click Tap Create .
In Integration Name, enter a unique name, such as WorkingTimeDirectiveReport_iPack_v3.
(Optional) Enter a Description.

Note: Do not select API Integration.

In File Access, select None to not select a connection.
(Optional) If the person who runs the integration doesn't have full access to integrations, select Execute Integration with System Account. This allows the integration access to all APIs in the FAP, and the relevant permissions and data, regardless of the FAP and GDAP of the person who runs the integration.
(Optional) Select Re-Run to allow repeated runs of the integration with the same parameter values as the previous run.
Email Notifications

(Optional)
1. Select Yes to send email and control center notifications for integration runs.
2. Enter the email addresses of the recipients for the following types of run status. For multiple recipients, separate the addresses by a comma, but no spaces:
  In Progress — The integration run started and has not finished.
  Completed — The integration ran successfully without errors.
  Failed — The integration ran successfully, but one or more records have errors. The integration run is treated as failed.If Abort on Failure is configured in an integration set A sequence of integrations that can be run on-demand or be scheduled., the integration set stops.
  Completed with Errors — The integration run has errors or could not run.
In Skip Configuration, select None (default) to allow multiple integrations to run at the same time or with the same data without restrictions.

Note: Do not select Allow Minute Interval.

Integration template and parameters
1. In Integration Template, select WorkingTimeDirectiveReport_iPack_v3.
2. Click Tap Assign.
3. In Integration Parameters, you can override default settings. Click Tap Create.
4. Complete the configuration for each parameter value.
5. Click Tap Save.
Click Tap Save.

Integration parameters
Parameter name	Description / User prompt / Mandatory	Template parameter	Parameter type
Hyperfind	Hyperfind or Location query for which the integration will run. Default = `All Home A query that returns a list of employees associated with a manager's employee group. All Home finds people who are active employees or active users as of today.` User prompt = Yes Mandatory = Yes Note: Ad-hoc Hyperfinds are not supported. All Home does not include terminated and inactive employees even if they have totals during the period. To include these totals, configure a Hyperfind that includes terminated and inactive employees and select that Hyperfind in this process property. The maximum number of employees in a Hyperfind is 3500. To process more employee records, divide the population into smaller Hyperfinds to run sequentially.	HyperfindAndLocation	Hyperfind
Individual Employee IDs	Comma-separated list of employee IDs for which the integration will run. When no value is entered, the integration defaults to the Hyperfind parameter. To process the integration for only a limited group of employees, enter the person numbers as defined in the source system, each separated by a comma (,) but not spaces. User prompt = Yes Mandatory = No	EmployeeIDs	Text
Opt In OptOut CustomFieldNumber	The number of the custom field that defines the Opt-In Opt-Out information in the employee’s people information. User prompt = No Mandatory = Yes	OptInOptOutCustomFieldNumber	Text
Output File Directory	The directory on the SFTPserver to archive the output files. Default = `/Outbound`. User prompt = No Mandatory = No	OutputDirectory	Text
WTD Rule Custom Field Number	The number of the custom field that defines the Working Time Directive rule in the employee’s people information. User prompt = No Mandatory = Yes	WTDRuleCustomFieldNumber	Text
Anchor Date	The start or base date of the reference period. User prompt = Yes Mandatory = Yes Note: The date must be entered in MM-DD-YYYY format.	AnchorDate	Date
Averaging Type	Specify whether to calculate average hours based on days in the past or in the future. If in the past (backward), includethe precedinganchor date. If in the future (forward), include the followinganchor date. User prompt = Yes Mandatory = Yes Parameter value = `Averaging Type` Supported values include: `Backward`: All worked days that precede the anchor date are considered when calculating the average hours. `Forward`: All worked days that follow the anchor date are considered when calculating the average hours.	AveragingType	Dropdown
Number of Iterations	The number of rolling time periods that the report generates. User prompt = Yes Mandatory = Yes Supported values: `1`—`10`.	NumberOfIterations	Dropdown

Ensure that the generic data access profiles (GDAP) allow access by the people who need to run the installed integrations. See Configure Access to Integrations.

Run and test the Working Time Directive Report integration

Run integrations to test that the configuration is set up correctly.

Run the integration

Select the integration:
1. Select Main Menu >Maintenance > Integrations.
2. Click Tap Run an Integration.
3. Select the WorkingTimeDirectiveReport_iPack_v3 integration from the list. Click Tap Select.
4. (Optional) Enter a unique Integration Run Name to make it easier to identify the run of the integration. Otherwise, the default name ends with a date and time stamp.
Set parameters as follows:
- Hyperfind: Select a hyperfind query of employees.
- (Optional) Individual Employee ID: To process data for only a limited group of employees, enter the person numbers, as defined in the source system, each separated by a comma (,) but no spaces.
  Example:
  - Generate a report for an individual or a few employees to show what they were paid and whether those amounts are correct.
  - For 3 employees: 13997,15556,20012
- Anchor Date: Select the start or base date of the reference period.
- Averaging Type: Specify whether to calculate average hours based on days in the past or in the future. If in the past (backward), includethe precedinganchor date. If in the future (forward), include the followinganchor date. Select one of the following:
  - Backward: All worked days that precede the anchor date are considered when calculating the average hours.
  - Forward: All worked days that follow the anchor date are considered when calculating the average hours.
- Iterations: Select the number of rolling time periods that the report generates.
Select the following:
- Run Integration: If this is the first time this integration is being run.
- Re-Run: If this integration has been run before, and the status is not In-Progress, you can run the integration again without entering the parameter values again. Click Tap Yes to continue, or No to not run the integration and to return to the parameter settings.
Wait for the confirmation that the integration completed or failed. Close the panel.
Click Tap Refresh.
To see details, select the integration run. Select Run Summary.

Check the results

Status indicators

In-Progress: The run of this integration has not yet completed.
Completed: The integration ran successfully without errors.
Scheduled: This integration is scheduled to run later or repeatedly.
(Grayed out)Scheduled but Deleted: This integration is scheduled to run, but the integration template has been deleted. When it runs, it will generate an error. To prevent this error, delete the scheduled integration run.
Completed with Errors: The integration ran successfully, but one or more records have errors. The integration run is treated as failed.If Abort on Failure is configured in an integration set, the integration set stops.
Failed: The integration run has errors or could not run.
To troubleshoot and resolve errors, do the following:
Check the Run Summary for details.
- To troubleshoot all types of errors, or if the Run Summary shows a large number of errors, click tap Go to Additional Details (if available), or click tap the Source File to open and examine the input source file.
- (Only for import integrations) To troubleshoot and resubmit integrations that have transactional or data errors, click tap Go to Transaction Assistant Corrects transaction errors in integrations without the need to resubmit entire projects..

To check the results in more detail, do the following:

To see detailed results, click tap the tile A container that provides navigation or action from its summary view. for the integration run.
Click Tap Run Summary to see the results of the integration run.
Example Run Summary details
Note: The available details vary by integration and configuration.
- Integration Run Name: Name of this run of the integration.
- Process Name: Name of any integration set that includes this integration.
- Integration Name: Name of the installed integration.
- Integration Reference ID: Unique identifier for this integration run (to help in troubleshooting errors).
- User: The person or user account that ran the integration.
- Integration Type: Import, Export, or None
- Start Date: Date and time when the integration run started.
- End Date: Date and time when the integration run finished.
- Status: In-Progress, Completed, Completed with Errors, or Failed.
- Records Processed: Number of records that were processed.
- Records Created: Number of records that were created.
- Errors: Number of records that failed.
- Source Files, Output File, and Error Files: For file-based import integrations, use Manage SFTP to access the source and output files on the inbound (source) and outbound (destination) SFTP folders. See the Manage SFTP topic.
Check the generated report to make sure that it shows the information correctly; for details, see Output file.

Note: You can schedule integrations and integration sets to run once later or at a recurring frequency. See the Schedule Integrations topic.

Output file

File Name: Working Time Directive Report _ MMddyyyy_HHmmss.csv
Format:Comma delimited
Frequency: On-demand or scheduled
Header Row:Yes, 1 row
Footer Row: No
Output Folder: /Outbound

Output file layout
Field	Comments or examples
Employee ID	The employee's identification number
Employee Name	The employee's first, middle, and last names
Home Account	The primary job that is assigned to the employee as of the anchor date
Period Start	The start date of the Average Period to calculate hours. This date corresponds to the First Day of Week. Note: When patching is applied (Backward Averaging), this date does not always reflect the start date of the time period of the report. Format = DD/MM/YYYY (European date format).
Period End	The end date of the Average Period to calculate hours. This date reflects the length of the work week and the number of weeks that are in the Average Period. Note: When patching is applied (Forward Averaging), this date does not always reflect the end date of the time period of the report. Format = DD/MM/YYYY (European date format).
Total Worked Hours	The total number of worked hours during the Average Period. Format: HH:mm Total Worked Hours = ((Sum of the Included Hours of the combined paycode during the actual period) — (Sum of the Included Hours of the combined paycode on the excluded days)) + ((Sum of the Included Hours of the combined paycode on extra days) — (Sum of the Included Hours of the combined paycode on ignored days [including hours less than the threshold]))
Average Worked Hours	The average number of worked hours each week during the Average Period. Format: HH:mm The Average Worked Hours calculation is based on the Average Period. When the Period Start and Period End dates: Exist entirely in the past: `Average Worked Hours = (Total Worked Hours)/Average Period (in Weeks)` Exist entirely in the future: `Average Worked Hours = (Total Scheduled Hours)/Average Period (in Weeks)` Span past and future: `Average Worked Hours = (Total Worked Hours in the past + Total Scheduled Hours in the future)/Average Period (in Weeks)`
Total Excluded Hours	Sum of the Excluded Hours of the combined paycode during the actual period that are more than the excluded hours threshold in the cross-reference table. Format: HH:mm
Total Days Added	The total number of days that have worked hours that are patched to the Average Period as a replacement for excluded days. These extra days that were added to the Average Period as Excluded Hours exceed the threshold.
Violation	Indicates whether the employee is in violation of the assigned Working Time Directive rule for the Average Period. The Max Weekly Average is used to check for violations. Values: yes or no.
Additional Info	Any of the following: New Hire: dd/MM/yyyy: The employee is hired during the averaging period. Terminated: dd/MM/yyyy: The employee is terminated during the averaging period. Insufficient Data: The averaging period falls in the future, or data is not available for patching. Insufficient Data, optin: dd/MM/yyyy optout: dd/MM/yyyy: The employee opted-in and opted-out during the averaging period. Insufficient Data, optin: dd/MM/yyyy: The employee opted-in during the averaging period. Insufficient Data, optout: dd/MM/yyyy: The employee opted-out during the averaging period.

Example Working Time Directive report

APIs

API details
API name	Type	Resource path	Description
Retrieve paycodes as manager	GET	/v1/timekeeping/setup/pay_codes	Returns a list of paycodes available to a manager.
Execute Hyperfind query	POST	/v1/commons/hyperfind/execute	Executes a Hyperfind by ID or qualifiers, and returns the results.
Retrieve Persons	POST	/v1/commons/persons/extensions/multi_read	Returns multiple person records based on search criteria.
Retrieve timecard data for multiple employees	POST	/v1/timekeeping/timecard_metrics Measures and tracks workforce performance by comparing planned with actual workload or coverage, or by showing variances at any organizational level./multi_read	Returns timecard data for a set of employees or locations.
Update integration execution details	POST	/v1/platform/integrations/update_status	Updates and returns the callback instance for the integration execution details.
Submit integration execution additional details	POST	/v1/platform/integration_executions/{id}/additional_details	Submits all additional details related to an API or batch integration execution.
Retrieve data element definitions by keys	POST	/v1/commons/data_dictionary/data_elements/multi_read	Returns a data element's definition by keys.