---
title: "What Breaks a Workday Payroll File the Night Before Pay"
description: "PECI change detection, pay groups, and vendor labels decide whether tomorrow’s file is complete. ADP and UKG file layouts are not invented here."
url: https://kiweely.com/guides/what-breaks-a-workday-payroll-file-the-night-before-pay
---

# What Breaks a Workday Payroll File the Night Before Pay

The night before pay fails when the extract’s change-detection method, pay period, or population does not match the vendor’s file. Workday documents PECI and Payroll Interface in detail. It does not publish an ADP or UKG API on the pages checked for this guide.

-   **Checked** against Workday on November 16
-   Applies to **Workday Extend**
-   7 min read
-   Published November 16
-   By Kiweely

The file that leaves Workday the night before pay is an extract of worker changes for a pay group and a pay period. It is complete only when the change-detection method, the period, and the population match what the vendor will load. A finished integration event means Workday built that extract. It does not mean the vendor calculated the right net pay.

This guide uses Workday’s own third-party payroll pages. [Kiweely Roots](https://kiweely.com/roots) (coming next) names ADP, UKG, and in-country providers as payroll targets, with changes sent the night they happen. Workday’s course uses “ADP Payroll” once, as the example of a payroll company that pay groups roll up to. The pages checked here do not document an ADP or UKG endpoint, payload, or file layout. Those details are omitted on purpose. Where the Payroll Vendor you need is missing from Workday’s menu, [Creating PECI Integrations](https://doc.workday.com/workday-education/en-us/course-manuals/creating-integrations-using-global-payroll-connect/creating-peci-integrations.html) says to select Other.

## Two templates, and they are not interchangeable

[Overview of Third-Party Payroll](https://doc.workday.com/workday-education/en-us/course-manuals/creating-integrations-using-global-payroll-connect/overview-of-third-party-payroll.html) defines both connectors. They send a configurable subset of HCM data, with built-in change detection, as XML or CSV. You can transform the output further or hand the audit report to someone who keys the vendor.

| Template | How it reads history | What Workday says about it |
| --- | --- | --- |
| Payroll Effective Change Interface (PECI) | Effective stack. Every change, in the order it became effective and was entered. Built on the Data Initialization Service, not a web service. | Workday recommends PECI when you want the most detail. |
| Payroll Interface (PI) | Top of stack, from the Get Payees web service. Net change, without the sequence. | Some vendors require PI because they only accept top-of-stack data. Workday still maintains PI and is no longer enhancing it. |

Sending PECI’s full sequence to a vendor that only loads the net change, or sending PI’s net change to a vendor that replays every effective-dated correction, is a mapping failure even when both files are well-formed. Workday’s planning questions in the PECI chapter include “Is a Document Transform required?” That question is the vendor’s format. This guide does not answer it for ADP, UKG, or anyone else.

Payroll Vendor and Payroll Country are required on PECI, along with a document retention policy, or the launch fails. Workday says both vendor and country are reporting labels. They do not change the XML. Workday still recommends a separate integration system per payroll country and per payroll vendor. One nightly file for two countries is the configuration the course tells you to split. The change-detection chapter’s example is one payroll company for a UK vendor and another for a U.S. vendor.

## The two launch methods that decide “tonight”

[Change Detection](https://doc.workday.com/workday-education/en-us/course-manuals/creating-integrations-using-global-payroll-connect/change-detection.html) gives PECI two methods:

| Method | When Workday says to use it | What it includes | What it leaves behind |
| --- | --- | --- | --- |
| Include all changes effective in the pay period | The first launch of that pay period | Employee data effective in the current pay period, whatever the entry date | Transactions whose effective date is in a future pay period. They wait until the integration is processing that period. Entry-dated objects that were changed before the last successful run and are effective in the current period. The chapter says an all-effective run will not pick those up. |
| Include only changes entered since the last successful run | A later launch in the same pay period | Changes entered after the last successful run, and effective in the current period or a prior period | Anything entered before that last success, including a correction you made last week for this payday |

A night-before job that always uses the second method will miss a hire, a rate change, or a tax election that was entered earlier and is effective this period. A job that always uses the first method will miss those entry-dated corrections the note calls out, and it will also ignore next period’s future-dated transactions until their period arrives. Hire and termination can be sent as soon as they are created. That only helps if this run’s method is allowed to see them.

Four things shape the output: the entry and effective-date rules, changes to workers in the pay group, changes via tracked transactions, and changes to fields you included in the output. A field you never enabled cannot appear, no matter how correct the detection method is.

## Populations the extract will not contain

PECI’s own limits, from the creating-PECI chapter:

-   Contingent workers are absent. The Worker Effective Change Interface is the template Workday names for contingent worker data.
-   You cannot orchestrate it. PECI can be added to only one business process.
-   It does not support processing over 250,000 active employees.
-   One-time payments older than two years are not reported.
-   Benefit elections whose deduction begin date is earlier than the worker’s hire date are not reported.
-   Dynamic calculated compensation plans are not supported. Workday says to consider event-driven calculated compensation plans instead.

Pay groups decide who is in the file. A pay group belongs to one country. Workers belong to one pay group unless you use multiple jobs. Members share a period schedule and run categories, and only one run category on a pay group is Regular. Period schedules have start, end, and payment dates. A worker in the wrong pay group is in the wrong file or in no file. The overview lists the events vendors react to: promotion, address change, hire, transfer that changes pay group, leave, and benefit election.

The Transaction Log Service, when you enable it, stops the integration from comparing every worker change. It also stops detection of indirect changes, such as a worker moving to a different manager, unless a subscribed transaction makes that worker eligible for review. Subscribing to all business process types except a chosen set drops event types you excluded, and the course uses a worker’s time off as the example. The Effective Stack Sync Service is the final run Workday describes for a primary integration that runs often during the day: it catches indirect changes and is there so the file does not duplicate rows. Enable it with the transaction log, and use it for primary runs only. The event-driven service, which fires from a business process step, allows one primary integration per pay group.

A calculated field on a PECI override can throw away the night even when the population is right. Workday says some report fields, including Staffing History - All, pull enough background data to degrade the run, and an ill-configured calculated field can end the integration with an exception. Test the calculated field in a report first. The course says transactions that do not show in worker history can still be generated in the background.

## In-country payroll is a different product

[Setup Considerations: Payroll Global Deployment](https://doc.workday.com/admin-guide/en-us/payroll/payroll-considerations/dwn1595352231356.html) says you can manage payroll in Workday for Australia, Canada, France, Ireland, the United Kingdom, and the United States. Other countries use third-party payroll connectors, which the page describes as bidirectional templates for global reporting. A worker on international assignment can be paid in the host country for all pay, or only for selected expenses, while base pay stays on third-party payroll in the home country. The page also records gaps: Payroll for Canada does not produce a Record of Employment for international-assignment pay, and Payroll for Australia and Payroll for France do not support multiple jobs together with international assignment. Those are calculation limits inside Workday Payroll, not PECI vendor layouts.

If the night-before worry is benefit deductions rather than the payroll extract, read the split in [Create Benefits Connectors](https://doc.workday.com/workday-education/en-us/course-manuals/creating-benefits-connector-integrations/create-benefits-connectors.html). With Workday Payroll, a benefits connector can send actual contribution amounts. With a third-party payroll provider, it sends estimated amounts based on the benefit plan for plans without standard deductions. The Payroll Start Date and Payroll End Date on that connector are not a pay period. If the range does not cover a complete payroll cycle, the file omits the incomplete cycles. Current Benefit Elections is the report Workday names for checking the estimate.

## Where Roots fits

Roots (coming next) is outside the tenant. Payroll changes are in the set that is proven on Sandbox with the rows that failed and then held for approval. You choose that behavior per integration. The running integration is tested code, each integration has its own API client scoped to what it reads, and the run keeps times, counts, and outcomes. Register interest at [kiweely.com/roots](https://kiweely.com/roots) and name the pay groups. Roots does not add an ADP or UKG API that Workday’s pages do not publish, and it does not skip the Sandbox proof on a payroll file.

## Checks before you call the file ready

### Which method did this launch use?

If it is the first launch of the period, Workday’s method is “all changes effective in the pay period,” with the entry-dated exception above. If someone already launched a successful run this period, the later run is “entered since last success.” A schedule that cannot tell those apart will be short on payday.

### Are contractors, future periods, and old one-time payments supposed to be in this vendor file?

PECI will not put contingent workers, future-period effective dates, or one-time payments older than two years in the extract. If the vendor pays those people, they need a different template or a different process. This guide does not invent that process for a named vendor.

### Did the vendor label change the columns?

No. Payroll Vendor does not change the XML. A different column layout is a document transform or a field override, tested in a report before it is scheduled.

## Sources checked

-   [Overview of Third-Party Payroll](https://doc.workday.com/workday-education/en-us/course-manuals/creating-integrations-using-global-payroll-connect/overview-of-third-party-payroll.html)
-   [Creating PECI Integrations](https://doc.workday.com/workday-education/en-us/course-manuals/creating-integrations-using-global-payroll-connect/creating-peci-integrations.html)
-   [Change Detection (Global Payroll Connect)](https://doc.workday.com/workday-education/en-us/course-manuals/creating-integrations-using-global-payroll-connect/change-detection.html)
-   [Setup Considerations: Payroll Global Deployment](https://doc.workday.com/admin-guide/en-us/payroll/payroll-considerations/dwn1595352231356.html)
-   [Create Benefits Connectors](https://doc.workday.com/workday-education/en-us/course-manuals/creating-benefits-connector-integrations/create-benefits-connectors.html)

## Related guides

[All guides](https://kiweely.com/guides)

-   [### When a Successful Payroll File Still Has the Wrong Tax or Garnishment Workday Payroll withholds from the pay period that contains the order’s begin date, and it keeps federal and state tax levies running until you mark them inactive. A third-party extract can be delivered and still omit the order the vendor needed.](https://kiweely.com/guides/payroll-files-that-succeed-while-tax-and-garnishment-are-wrong)

### More guides on Tenants and developer accounts

[All 25 guides](https://kiweely.com/guides#tenants)

-   [Separating Production and Sandbox Workday Endpoints So Demos Miss Live Workers](https://kiweely.com/guides/separate-production-and-sandbox-workday-endpoints)
-   [Employee Screen Languages Without Changing the Tenant Default](https://kiweely.com/guides/localization-beyond-one-language-without-tenant-default)
-   [Accessing Employee Payslip Summaries and PDF Payslips Through Workday APIs](https://kiweely.com/guides/workday-payroll-payslip-summary-pdf-retrieval-apis)
-   [How Workday Stores Custom Plan Names, Reason Codes, and Translated Labels Across APIs](https://kiweely.com/guides/workday-custom-labels-translations-reading-tenant-terminology)
-   [Why Workday W-2 Box 1, 3, or 5 Wages Don’t Match Payroll Summary (and How to Fix Them)](https://kiweely.com/guides/workday-w2-box-mismatch-adjust-tax-balances)
-   [How to Customize the Workday Home Page, Daily Brief, and Global Navigation Sidebar](https://kiweely.com/guides/workday-configurable-home-page-daily-brief-setup)
-   [Workday Payroll Parallel Testing and Retro Calculation Audits in Sandbox](https://kiweely.com/guides/workday-payroll-parallel-testing-retro-audit)
-   [Workday Test Data: How to Build Realistic Data in a Sandbox or Implementation Tenant](https://kiweely.com/guides/workday-test-data-sandbox)

### From the blog on Tenants and developer accounts

[All posts](https://kiweely.com/blog)

-   [Check a Workday Community answer against your tenant](https://kiweely.com/blog/verify-workday-community-answers-with-tenant)
-   [Prototype in an Implementation tenant, then keep what you meant to keep](https://kiweely.com/blog/ai-workday-prototype-tenant-builds)
-   [What Workday has published about payroll parallel and close](https://kiweely.com/blog/ai-workday-payroll-parallel-financials-close)

## Let Workday check the work.

Kiweely writes WQL and builds orchestrations in your own tenant, and Workday, not Kiweely, says whether they passed.

[Start for free](https://kiweely.com/download) [See how it works](https://kiweely.com/vine/how-it-works)

## Get the next guide in your inbox.

One email a month with new guides and one Extend tip. Nothing else.
