Why the action works in Orchestration Builder and fails from the agent

A Custom Agent Action can call Workday REST, SOAP and WQL with ordinary Send Workday API Request steps, but through an agent every step runs as the signed-in user and may only call Workday resources registered on the agent. Each REST operation, SOAP operation, report and WQL method the orchestration touches, including inside suborchestrations, needs its Workday ID (WID) in the agent's skill.

That is why the same orchestration can pass in Orchestration Builder and fail from the agent. Orchestration Builder runs it as you, with your full security. From the agent, Workday's documented symptoms of a missing registration are a 403 error on a REST call, a 401 error on a SOAP call, or the message The task submitted is not authorized.

Two other rules follow from the same design. You can't use ISU credentials in a Custom Agent Action orchestration; Workday says doing so causes a build failure. And registering a resource on the agent doesn't grant anyone access to it: the user still needs the domain or business process permissions behind every call.

Build the action so the agent calls it correctly

Create the orchestration from the Custom Agent Action template. The name can be at most 30 characters. Then, on the Start step, click Configure Request and fill the Custom Agent Actions tab:

  • Action Display Name and Action Description. The description is what the model reads when deciding whether to call the tool, so say when to use it, not only what it does: "Returns a worker's open Equipment Requests. Use when someone asks what equipment they have requested or what is still pending."
  • Action Annotations. Pick Read-Only for any action that only reads. Workday agents ask the user to approve every call to an action that isn't Read-Only, so a lookup marked Destructive produces an approval prompt every time.
  • Request Properties. Every property needs a description, with its format and a sample value. A property without a default must be supplied by the agent. If the agent sends a missing, unknown or wrongly typed input, the call fails with The input arguments do not match the expected input schema for tool followed by the orchestration name and the input at fault.
  • Query Parameters. Delete unused rows before saving. Workday warns that empty rows can produce an invalid tool schema, and the client then can't load the tools.

On the End step, click Configure Response and describe each output parameter on the Custom Agent Actions tab so the agent can interpret the result.

Find the Workday ID of every call

List every Workday REST API, SOAP operation, report and WQL data source the orchestration calls, suborchestrations included. Then collect their WIDs:

  1. On the Developer Site, connect to the tenant and copy the access token.
  2. Call the Agent Resource Search API on your region's Agent Gateway host with Authorization: Bearer <access token>. Narrow with searchString, toolType (REST or SOAP) and operationType (VIEW for GET, CREATE for POST, PATCH for PATCH). The Finder API guide covers the request in detail.
  3. Copy the wid of each result. When several results share a name, Workday's troubleshooting steps say to copy every one.
  4. For WQL, use Workday's fixed method IDs: 9749ba9ac47e1000073fdc1bc8a5001a for GET and 3e15b2a1676d10000c9572ea9cc264b3 for POST.
  5. If the search doesn't return an operation, such as a SOAP operation that writes data, build a custom report. Use the Create Custom Report task, report type Advanced, Optimized for Performance cleared, and data source Public Web Services for SOAP (columns: Web Service, Web Service Operation Name, Workday ID) or All Public Service Operations for REST (columns: Service, Name, Workday ID).

Send the search to the Agent Gateway host, not the tenant's own REST host. Workday notes that the tenant's REST host rejects the Developer Site token.

Register the IDs on the agent

How you register depends on where the agent lives.

For a custom agent built in App Builder, the WIDs go in the .agentskill file's tool-wids, and the tool names in allowed-tools. Workday's build steps say plainly that when you use APIs in Custom Agent Actions, you must include the API WID in the skills file. An Equipment Request skill whose action reads with WQL would carry:

allowed-tools:
  - wqlGet
tool-wids:
  - name: wqlGet
    wid: 9749ba9ac47e1000073fdc1bc8a5001a

That wqlGet entry, with that WID, appears in Workday's own sample skill files. The action itself is registered under its Action ID, the identifier shown on the Custom Agent Actions tab of Configure Request; Workday's troubleshooting steps say the identifier in the skill must be that Action ID. Formatting is exact: a space anywhere in a WID stops the tool from registering, so check pasted values for leading, trailing and embedded spaces. Then click Save and Deploy.

For an external agent registered through the ASOR API, add each WID as a workdayResources entry on the skill in the agent definition and post the definition again to /asor/v1/agentDefinition. Keep the same name, provider and version so Workday updates the existing agent instead of creating a second one.

In both cases, sign in again from the agent's client afterwards. An access token issued before the registration changed doesn't include the new resources, so the old session keeps failing even though the fix is in place.

When it fails for some users only

Open the agent in Agent Management Hub, go to the Skills tab and click View Security. The View Security for Agent Skill report lists each tool and the policies that secure it. Rows with Functional Status Review Required or Config Required are policies that don't include the security groups in the skill's Available To. Add a group those users belong to, for a domain through Domain > Edit Domain Security Policy Permissions, then run Activate Pending Security Policy Changes.

Read the result, then the run

Call the action and read what comes back before opening any logs. A successful result carries the run ID in _meta as X-Orchestrate-Id. A failed run adds lines with AppRefId, Orchestration and OrchId, where OrchId is the run ID. An error with no run ID at all means the call failed before the orchestration started, usually an unregistered tool name (Unknown tool:) or an input schema mismatch.

With a run ID, open the app on the Developer Site, select Orchestration Activity, choose the orchestration, click Filter and enter the ID in Other IDs. Read the status carefully:

  • Completed means the orchestration finished, not that the action succeeded. An orchestration that catches its own error and returns it in the response also completes.
  • Completed With Errors means a step error went unhandled.
  • Timed Out means the run passed 5 minutes, the limit for synchronous orchestrations.

From the run, View Logs (or View Error Logs) opens Run Logs filtered to it; search for LogStep to see only your Log steps. Run Logs opened from Orchestration Builder show the last 15 minutes by default, so widen the range for older runs.

Keep responses small

A Custom Agent Action response is capped: Response size too large appears above 2 MB, or above 1 MB once you enter Response Properties descriptions on the end step. A WQL query or REST collection returned whole is the easy way to hit it, so select only the fields the agent needs, add a WQL LIMIT clause, and shape the output in the orchestration before the End step.

The proof that the fix worked is the same call, from the same user, returning a result with an X-Orchestrate-Id and a run that shows Completed with the data you expected in its output.

Sources checked