·
Workday Integration
·
Josh Santinon
Sub documents: getting parent and child data out of Workday properly
A practical guide to using Workday Document Builders and sub documents in field overrides to output parent and child data as a nested XML structure, rather than flattening it into single value calculated fields. It covers the two main use cases (keeping multi-instance entries separate, and bringing in objects a connector does not output natively, such as payment elections), the Grid enablement prerequisite, how the pieces fit together, and what to watch for.
If you build connector-based integrations in Workday, you already know the standard field override pattern: one field, one value. You define a field in the override service, point it at a report field or calculated field, and it lands as a single element in the output.
It breaks down when the source data is multi-instance. Dependants, payment elections, cost allocations and assignments all have a 1:M relationship with the worker, and each instance carries its own set of fields. The usual workaround is an Extract Multi-Instance or Lookup Related Value chain that concatenates everything into one delimited string, which the XSLT or the receiving system then has to split back apart.
Document Builders give you a cleaner option. A Document Builder navigates from the primary business object to a related business object and outputs it as a sub document: each instance becomes its own child element under the worker, with its fields nested inside it. The output keeps the parent and child relationship that exists in Workday instead of flattening it into a single value.
Before you start: Grid enablement
Check that Grid enablement is active in your tenant before you design around this. Document Builders and sub documents do not work well without it, and finding that out after you have built and tested the rest of the integration is an expensive way to learn it.
A single value versus a structure
The difference is easiest to see in the output.
Here is the typical calculated field approach to multi-instance data. Everything is concatenated into one field, and the receiving system (or your XSLT) has to split it back apart:
Here is the same data through a Document Builder exposed as a sub document:
Same data, different contract. The first relies on delimiters never appearing in the data, on every field being populated in the right order, and on someone remembering how it was built. The second describes itself.
(Element names here are illustrative. Yours will follow the names you give the fields in your override configuration.)
Where this earns its place
There are two situations where I reach for a Document Builder over a calculated field.
Multi-instance fields that need to stay separate. Dependants, cost allocations, work contact details, assignments, licences and certifications. Any time the receiving system needs one entry per record rather than one blob per worker, a sub document gives you that natively. Each instance becomes its own child element, with its own fields, and downstream mapping becomes a simple loop.
Objects the connector does not bring through. Delivered connectors only expose what Workday chose to include in them. Payment elections are a good example: they are not part of what Core Connector: Worker outputs natively, yet plenty of downstream payroll and finance systems need them. A Document Builder can navigate from the worker to their payment elections and bring each one through with its payment type, account details and distribution, as its own element under the worker, as shown in the example above.
Without this, the usual workaround is a separate report or integration for the missing object, which then has to be matched back to the worker file on the other side. One extract is easier to support than two that have to agree.
How the pieces fit together
Create the Document Builder with the Create Document Builder task.
Set the Context Business Object to the object your fields actually live on (the dependant, the payment election), not the worker.
Add the fields you want in each child element, ensuring to set the data type and any formatting types (e.g. ISO country codes)
Attach it as a Sub Document in your field override configuration, so it is output under the parent record.
Set the loop on and order by values in the “Loop on instances” column. Loop on being the unique multi-instance field you want multiples of, and order by being the value you want it sorted by.
Run it and read the XML before anyone builds a mapping against it.
Things to watch
Filter the instances. Navigate to a multi-instance object without a condition and you get all of it, including ended and inactive records. Decide what “current” means for the receiving system and build that into the condition.
Pick the right context object. If a field will not appear in the builder, you are usually on the wrong Context Business Object.
Agree the structure downstream first. A nested structure is a change to the file contract. Whoever owns the receiving mapping needs to know before it lands.
Mind the security. Bringing in objects like payment elections means your integration system user needs access to the domains that secure them. Bank details are sensitive data, so check who can see the output as well as who can generate it.
Treat builders as shared objects. A Document Builder lives in the tenant as its own definition. Name it for what it outputs and keep a note of which integrations use it, so a change for one does not surprise another.
Calculated fields are still the right tool for logic: formatting, deriving a value, returning a flag. Sub documents are the right tool for shape. Most messy integration output I see comes from asking a single value to carry a relationship it was never built to hold.
Need help with integrations that have become harder to support?
Santinon Consulting brings practical experience to the design, remediation, and handover of Workday integrations.