Integration Agents
Integration agents, or adapters, are the specialists of a planning agent team that exchange data with the systems around the planning function: the WFM platform of record that consumes the short-term forecast and returns the roster, the ACD that supplies actuals, the human-resources system that supplies headcount and attrition, the finance system that supplies the budget envelope and consumes the cost view, and the enterprise planning platform that holds the plan of record. The page's claim is that an adapter's job is not to move data but to enforce two rules at the boundary, that every field maps to a definition and that nothing which changes a plan crosses without a signature, and that file exchange is the right first form because it makes both rules visible. This page gives the adapter pattern, the boundary rules, and the order in which integrations should be built.
What an adapter is
An adapter is a specialist with no analytical role. It reads a ledger version in the team's shape and writes a file in a system's shape, or the reverse, and it does three things on every crossing.
- Maps every field to a definition. A column arriving from the ACD called "handled" is mapped to the definitions ledger's record for handled contacts, or rejected. A column leaving for the platform of record is written under that platform's name for the same definition. The mapping is a file the adapter reads, owned by a person, versioned like any ledger.
- Checks the signature. An outbound forecast or plan version without a signature block is refused. The refusal is logged. No configuration flag overrides it.
- Logs the crossing. What crossed, in which direction, from which version, to which file, at what time. The change log holds it.
The pattern is the messaging literature's message translator and channel adapter, applied to planning objects.[1] What the pattern does not usually carry, and this page adds, is the signature rule, because in most integration work the question of who authorized the data to move is answered upstream. Here it is answered at the boundary, because the boundary is where a plan becomes real.
The boundaries
| System | Direction | What crosses | Definition enforced | Signature required |
|---|---|---|---|---|
| ACD or telephony platform | Inbound | Interval actuals: offered, handled, abandoned, handle time, speed of answer, agent states | Contact, handled, offered, handle time, state codes | No; actuals are measured, not decided |
| WFM platform of record | Outbound | The short-term forecast version by interval | Forecast interval grain, channel, skill mapping | Yes: the planner gate on the version |
| WFM platform of record | Inbound | Roster, schedules, shrinkage actuals, adherence | Scheduled, staffed and productive hours; shrinkage categories | No |
| Human-resources system | Inbound | Headcount, hires, leavers, moves, tenure | The headcount perimeter, per Headcount Reconciliation in Service Operations | No |
| Finance system | Inbound and outbound | Budget envelope in; cost view of the plan out | FTE-to-cost mapping; cost center perimeter | Outbound yes: the plan signature |
| Enterprise planning platform | Outbound | The signed plan of record, scenarios as named versions | Requirement hours, FTE, the planning unit hierarchy | Yes: the plan signature |
| Email or ticketing | Inbound | Asks and updates for the intake door | None at the boundary; the librarian classifies | No; the ask is [A] until graded |
The table's most consequential row is the second. The forecast the platform of record schedules against is the one thing the daily loop changes that reaches the floor, and the signature on it is the daily loop's control. An integration that lets an unsigned version through, because a batch job runs at 06:00 and the planner has not yet looked, has removed the gate without anyone deciding to.
File first, interface later
The series recommends that every adapter begin as a file exchange, a stamped file written to a shared location and picked up by the receiving system on its own schedule, and that programmatic interfaces come later, boundary by boundary, as each proves stable. Three reasons.
First, files are inspectable. A planner can open the forecast file that went to the platform of record and see what crossed; an API call leaves a log entry a planner will not read. During the period when trust in the team is being earned, that inspectability is the control. Second, files carry the signature naturally: the signed version is the file, and a receiving job that reads the signature block is a small script. Third, files decouple the team from the receiving system's release cycle, which is the ordinary argument for asynchronous integration.[2] API Integration Patterns for WFM describes the batch, webhook and streaming patterns an interface later adopts, and WFM Data Infrastructure and Integration Architecture the latency each planning function tolerates; this page's order is that the file form is built first for every boundary and replaced only where latency requires it, which for the daily forecast load it does not.
The one boundary that may need an interface early is the inbound ACD feed for Real-Time Agents, where interval latency matters. That is a different agent team's boundary and is treated on its page.
Definitions at the boundary
The mapping file is where the function's definitional work becomes enforceable. Standardize Before You Automate names shared definitions as a standardization and interfaces with named owners as another; the adapter's mapping is the object in which the two meet. A definition without a mapping is not yet in use; a mapping without a definition is a defect. The adapter's rejection log is therefore a measure of definitional maturity: a function whose adapters reject nothing has either finished its definitions or is not checking. The consistent finding that integration glue is where machine-learning systems accumulate hidden debt applies here with one twist: the mapping is that glue, and versioning it as a ledger is what keeps the debt visible.[3]
Worked example
In the series example, the forecast adapter is built in week one as a file exchange. Each morning after the planner gate it writes a file with one row per interval per channel per skill in the platform of record's column names, a header naming the forecast version it came from, and the signature block copied from the version. A scheduled job on the platform side reads the header, checks the signature, and loads. On Thursday 5 March 2026 the planner is delayed and the gate is not approved by 06:00. The adapter writes nothing. The platform's job finds no file and holds yesterday's forecast, which its own rules allow for one day. The daily note, published when the gate is finally approved at 09:40, says so in its "what changed" line. Nothing unsigned reached the floor, and nobody had to remember not to run the job.
The same month, the HR adapter rejects an inbound extract because a new leaver code has no mapping. The rejection opens a definitions question through the intake door; the librarian pins the code to the headcount perimeter definition; the mapping file gains a row; the extract loads the next day. The rejection log now holds the first entry of what will become the function's definitional backlog.
What would change this
The file-first rule is a sequencing choice on the ground of inspectability during a trust-building period; a function whose platform of record exposes a forecast interface with a native approval workflow could enforce the signature there and skip the file. The definition rule is not optional under the series' thesis, but its enforcement point could move upstream to the data engineer if the adapter proves to be the wrong place to reject.
How this connects
Adapters are the outermost specialists of The Agent Team Model and the last step of The Short-Term Forecasting Loop with an Agent Team and of Long-Term Planning Agents and the Plan of Record. The signature they check is set at the gates on Human Gates and Number Grades. The interfaces they implement are the interface register of Interconnected Workforce Management, whose nine rows the adapters make mechanical, and the technical patterns they grow into are on API Integration Patterns for WFM.
Maturity Model Position
File exchange with definitions enforced is Level 3 work on the WFM Labs Maturity Model™, and it is where most functions' integration actually sits. The signature rule at every plan-changing boundary and one mapping file per system on one set of definitions is the Level 4 form, the "one data core and one set of definitions" of Technology Journey from Level 2 to Level 5. Programmatic interfaces do not by themselves move a function up a level; a real-time interface carrying unmapped fields is a faster way to be wrong.
See Also
- AI Agent Teams for Workforce Management — the series hub
- The Agent Team Model — the adapter as a roster role
- Human Gates and Number Grades — the signatures the adapter checks
- Long-Term Planning Agents and the Plan of Record — the plan export
- Real-Time Agents — the one boundary that may need an interface first
- API Integration Patterns for WFM — batch, webhook and streaming patterns
- WFM Data Infrastructure and Integration Architecture — latency by planning function
- Interconnected Workforce Management — the interface register the adapters implement
References
- ↑ Hohpe, G., & Woolf, B. (2003). Enterprise Integration Patterns: Designing, Building, and Deploying Messaging Solutions. Addison-Wesley. ISBN 978-0-321-20068-6.
- ↑ Kleppmann, M. (2017). Designing Data-Intensive Applications. O'Reilly. ISBN 978-1-4493-7332-0.
- ↑ Sculley, D., Holt, G., Golovin, D., Davydov, E., Phillips, T., Ebner, D., Chaudhary, V., Young, M., Crespo, J.-F., & Dennison, D. (2015). "Hidden Technical Debt in Machine Learning Systems". Advances in Neural Information Processing Systems 28, 2503–2511.
