Why the query works for you and fails for the ISU

An integration system user can run WQL from an orchestration only when its security group has the Workday Query Language domain and access to every data source, filter and field the query names. WQL always runs as an account and sees only what that account can see, so a query that works in your own session runs with the ISU's narrower security once the orchestration uses an ISU credential. The query is the same; the account is different.

Workday states the rule in two places. The WQL concept page says you need access to the Workday Query Language domain in the System functional area, and that you can only view and use data sources and fields you have security access to. The FROM clause reference adds that a query can only reach fields that Workday has authorized for Report Writer use and that "the current processing Workday account" has permission to access. In an orchestration, the current processing account is whoever the step's credential resolves to.

Workday's docs do not publish the error text a query returns when the account lacks access to a data source or field, so an "Illegal query" or similar message in the run log is not a diagnosis by itself. Diagnose by the account and its permissions, not by the wording. For syntax errors that have nothing to do with security, see WQL error messages and how to fix them.

Which account a WQL step actually runs as

WQL from an orchestration goes through a Send Workday API Request step to the WQL REST API. Workday's WQL sample orchestrations use the relative path /wql/v1/data. Workday notes that you do not need to register an API client to use WQL inside a Workday Extend or orchestration app. Registration is only for calling WQL from an external system.

The step's Auth tab picks a credential defined on the orchestration's Settings > Credentials tab. That choice decides the account:

  • The default Workday credential. Integration System orchestrations default to the Access Token From Initiating User endpoint scheme: the query runs as the person or ISU that launched the integration.
  • An ISU credential. The query runs as the integration system user named in the credential's Username expression.

Workday's guidance for integration apps is to use the initiating user's token and to add an ISU credential only when the integration must run as a different ISU from the one that launched it. For Extend apps, Workday gives a long-running asynchronous orchestration as a valid reason for an ISU, because a user's access token expires sooner. Two documented constraints apply: an ISU can be associated with only one app, and ISU credentials cannot be used in a Custom Agent Action orchestration, where they cause a build failure.

What the ISU needs before a WQL query can run

These steps follow Workday's Create Integration System Users for Apps and Assign Integration System Users to an App tasks, plus the WQL domain requirement.

  1. Create the user with the Create Integration System User task. Workday's instruction is to leave the session timeout at zero so the session does not expire.
  2. Create an integration system security group with Create Security Group, choosing Integration System Security Group (Unconstrained), and add the ISU to it.
  3. With Maintain Permissions for Security Group, grant the group View (a Report/Task permission, which is what Workday's integration app security page asks for on GET calls to Workday services) on:
    • the Workday Query Language domain in the System functional area;
    • the domains that secure each data source in the query's FROM clause;
    • the domains that secure each field in SELECT, WHERE and ORDER BY, including fields reached through related business objects.
  4. Run Activate Pending Security Policy Changes. Without this, nothing you granted takes effect.
  5. In App Manager, open the app with Configure, click Add Integration System User in the Integration System Users section, then click Create API Client on the new row. You need the WCP Integration System User Security domain to see the Add Integration System User button.
  6. On the orchestration's Credentials tab, add a credential of type ISU and put the ISU's name in Username. Select it on the WQL step's Auth tab.

Workday's WQL Milestone Celebrations sample shows the pattern on a real query against allActiveWorkers. It asks for an ISU with access to the Workday Query Language domain and Worker Data: Public Worker Reports, then points the orchestration's Workday credential at that ISU.

Step 3 is where most of the work is. List every alias in the query, including data source filters and their prompts, and confirm the group can reach each one. The metadata check below does this as the ISU.

Constrained groups and empty results

WQL honours object and data-level security for the issuing account, per Workday's WQL and RaaS comparison. Whether the ISU's group is constrained or unconstrained decides which instances it sees. A query that succeeds but returns fewer rows than you expect, or none, is usually this, not a broken query. See constrained vs unconstrained security groups for how the scoping works.

Because ISU access does not follow the end user's own security, Workday says you must add your own checks when the orchestration's results reach people who should not see everything the ISU can see.

Check the ISU's view with the WQL metadata endpoints

The WQL REST API offers endpoints that answer the security question directly when you call them with the same credential as the failing step:

GET /wql/v1/dataSources?alias=allActiveWorkers
GET /wql/v1/dataSources/{dataSourceWID}/fields
GET /wql/v1/dataSources/{dataSourceWID}/dataSourceFilters

Workday's comparison page says that to query any data source, filter or field in WQL, you must have access to it in Workday. If the data source is missing from the ISU's dataSources response, or a field you select is missing from its fields response, you have found the gap. Workday also recommends these calls for getting aliases right before you write the query. Add a temporary step to the orchestration that makes the call as the ISU and logs the response, then remove it once the query works.

Query length, cache and timeouts that look like security failures

Some WQL failures look like permission problems but are not:

  • Query length. GET /data with the query in the query parameter is for queries under 2,048 characters. Between 2,048 and 16,000 characters, use POST /data with the query in a JSON body: {"query": "SELECT … FROM …"}. Workday's WQLQuery sample in the Orchestrate for Integrations Sampler has both steps behind a branch, switched by a launch parameter.
  • Stale results. Workday caches WQL query results and clears them after 30 minutes. If you have just granted access and the next run still returns the old result, add offset=0 to the request to clear the cache.
  • Size and time. WQL returns at most 1 million rows. Without a LIMIT clause, a query that would return more fails. Workday also documents a 30-minute timeout from a tenanted host and 5 minutes through the api.workday.com gateway, and you view results 10,000 rows at a time. Paging is covered in WQL with more than 500 rows.

How to prove the fix

Run the orchestration again and open the WQL step in the run. Confirm a 2xx status and read the total value in the response body. Then run the same query as yourself and compare. If the totals differ, the remaining difference is security scope. If you expected them to differ (for example, the ISU is constrained on purpose), check a known record that should appear for the ISU and confirm it is in the data array.

kiweely can do the security half of this in the client's tenant, with consent: it reads the ISU's security group and the domains that secure each data source and field in the query, so the list of gaps comes from the tenant's real configuration rather than from memory.

Sources checked