Skip to content
KiweelyKiweelyKiweely

Filtering Empty Related Business Objects in WQL and Guarding Omitted RBO Keys in PMD

Checking whether a context-linked Related Business Object (RBO) is empty in a WQL WHERE clause can throw “Field: ... can only be used as a related business object field (RBO)”, and empty RBOs are omitted entirely from WQL JSON responses. Learn how to filter empty RBOs and guard PMD scripts.

  • Checked against Workday on
  • Applies to Workday Query Language
  • 3 min read
  • Published
  • By Kiweely
On this page

When replicating a Custom Report that has both a top-level filter and a subfilter on a Related Business Object (RBO)—or even when running Workday’s Convert Report to WQL task—you may end up with a WQL statement that checks WHERE <rbo> is not empty in the Primary Business Object (PBO) WHERE clause:

sql
SELECT employeeID, allowancePlans_{effectiveDate} AS allowancePlans_
FROM allActiveAndTerminatedWorkers (effectiveAsOfDate = '2026-09-30')
WHERE ON allowancePlans_
  cf_ZCFGlobalTFEligibleForNextMonthsProgram = true
  AND compensationPlan IN (8eba4afa96061001aa36f4c60f050000)
WHERE
  allowancePlans_ IS NOT EMPTY
  AND cf_GLobalTFEmployeeIsActiveInNextMonth = true
  AND activeStatus = true

Executing this query on allActiveAndTerminatedWorkers or workersForHCMReporting fails with the error:

text
Field: allowancePlans_ can only be used as a related business object field (RBO)

Yet if you simply delete allowancePlans_ IS NOT EMPTY from the WHERE clause, the query no longer excludes workers who have zero matching allowancePlans_ instances—returning the entire active worker population (for example, 130,000 workers instead of the 314 workers who actually hold that allowance plan).

Root Cause: Context-Linked Fields vs. Standard Instance Fields

Look closely at the trailing underscore in allowancePlans_ and inspect its field description in Workday:

“Provides the context link between the worker and compensation plan assignment business objects. This field specifically provides a link to the allowance plans assigned to an employee. Linked fields cannot be used in reports as fields, and should only be used as related business objects in reports.”

Standard multi-instance fields on a PBO can be evaluated in WHERE field IS NOT EMPTY. Context-linked RBO bridges (which often end in _, such as allowancePlans_ or meritPlans_PlanDetails) are not report fields on the PBO; they exist solely as RBO traversal links for SELECT rbo{...} and WHERE ON rbo .... Even though Convert Report to WQL mechanically translates the report filter into WHERE allowancePlans_ IS NOT EMPTY, the WQL validator rejects context-linked bridges inside the WHERE clause.

Fix: Extract Single Instance (ESI) or Extract Multi-Instance (EMI) Calculated Field on the PBO

To filter the PBO population so only workers with a matching RBO instance are returned:

  1. Create a True/False Condition calculated field on the Related Business Object (Compensation Plan Assignment) that evaluates your subfilter criteria (cf_ZCFGlobalTFEligibleForNextMonthsProgram = true and compensationPlan IN (...)).
  2. Create an Extract Single Instance (ESI) or Extract Multi-Instance (EMI) calculated field on the Primary Business Object (Worker) that extracts from the Compensation Plan Assignment relationship using the True/False Condition from Step 1.
  3. Because the ESI/EMI calculated field (cf_workerEligibleAllowancePlan) is a first-class report field on Worker, reference it directly in the PBO WHERE clause:
sql
SELECT employeeID, allowancePlans_{effectiveDate} AS allowancePlans_
FROM allActiveAndTerminatedWorkers (effectiveAsOfDate = '2026-09-30')
WHERE ON allowancePlans_
  cf_ZCFGlobalTFEligibleForNextMonthsProgram = true
  AND compensationPlan IN (8eba4afa96061001aa36f4c60f050000)
WHERE
  cf_workerEligibleAllowancePlan IS NOT EMPTY
  AND cf_GLobalTFEmployeeIsActiveInNextMonth = true
  AND activeStatus = true

Why Empty RBO Fields Disappear from WQL JSON Responses in PMD

When your WQL query intentionally returns PBO rows whose RBO collection may or may not have values—for example, querying work experience credentials alongside optional employmentDocumentation attachments—WQL exhibits a second behavior that catches PMD developers off guard:

sql
SELECT
  startEmploymentDate,
  endEmploymentDate,
  employer,
  jobTitle,
  academicAppointee,
  employmentDocumentation{workdayID AS id, fileName AS descriptor, documentType}
FROM instructorEligibilityCredentials_dnqbzb_workExperienceEligibilityCredentials
WHERE academicAppointee IN ('734428758077011554686b58e64dfd24')

When a row has no employmentDocumentation records, WQL’s JSON serializer completely omits the employmentDocumentation key from that row object rather than emitting "employmentDocumentation": [] or "employmentDocumentation": null:

json
{
  "total": 1,
  "data": [
    {
      "startEmploymentDate": "2015-01-01",
      "endEmploymentDate": "2019-12-31",
      "employer": "PSC",
      "jobTitle": "Faculty",
      "academicAppointee": {
        "descriptor": "Alex Rivera",
        "id": "734428758077011554686b58e64dfd24"
      }
    }
  ]
}

If a PMD script or grid cell template attempts to index row.employmentDocumentation[0].documentType or check row.employmentDocumentation.documentType without first checking whether the parent key exists on row, the page crashes at runtime because row.employmentDocumentation is undefined.

Fix: Guard Both the Parent RBO Array and Child Property with empty

In PMD scripting, the unary empty operator safely evaluates null, undefined (omitted JSON keys), empty strings "", and zero-length arrays [] in a single check. Always short-circuit on empty row.<rboName> before indexing [0] or traversing a nested property:

javascript
for (var row : getCredentials.data ?? []) {
  if (empty row.employmentDocumentation || empty row.employmentDocumentation[0].documentType) {
    // Key was omitted or array is empty — prompt user to attach documentation
    row.hasDocument = false;
  } else {
    // Safe to read row.employmentDocumentation[0].documentType
    row.hasDocument = true;
    row.docTypeDescriptor = row.employmentDocumentation[0].documentType.descriptor;
  }
}

Inside a PMD grid cellTemplate expression, you can also use optional chaining (?.) or a ternary with empty:

json
{
  "type": "text",
  "id": "docTypeCell",
  "value": "<% empty row.employmentDocumentation ? 'Missing Attachment' : row.employmentDocumentation[0].documentType?.descriptor %>"
}

How to Verify in the Tenant

  1. Run your query in View WQL Query Result. If WQL rejects WHERE <rbo> IS NOT EMPTY with can only be used as a related business object field (RBO), inspect the field definition in Workday to confirm whether it is a context-linked RBO bridge, then replace the PBO check with an ESI/EMI calculated field on the PBO.
  2. Compare the total row count in View WQL Query Result against your reference Custom Report to verify that PBO rows without matching RBO records are excluded when intended.
  3. For queries where the RBO is optional, inspect the raw JSON payload in REST API Explorer for a record with no RBO instances, confirm the RBO key is omitted from the JSON object, and verify that your PMD page loads those rows cleanly using empty row.<rboName>.

Sources checked

Related guides

All guides

Let Workday check the work.

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

Get the next guide in your inbox.

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

We’ll email you once to confirm. Unsubscribe in one click from any issue.