Logging in Workday Orchestrate: Log, Log to File, Add Integration Message and verbose logging

Four kinds of log, four different readers

Orchestrate has four ways to record what a run did, and each lands somewhere different. The Log step writes to the app's logs on the Workday Developer Site, for developers. Add Integration Message writes a message onto the integration event in the tenant, for the administrators who run the integration. Log to File builds a CSV log you can store and attach to that event, for record-by-record results. Verbose logging is a troubleshooting switch, turned on per orchestration through a REST API for a limited time, that records additional detail about how the code executed.

The Log step and where its output goes

The Log step takes one expression in its Message property and an optional Condition; when the condition is false, nothing is logged. Its output appears in the app's logs with wd_category = console, which is how Workday's log reference identifies custom messages from the Log component.

You can read it in two places:

• Run Logs in Orchestration Builder, generated when the orchestration runs on the tenant where it is deployed. The view has Run Logs and API Logs headings, an Edit Fields pane to choose columns, and an Auto-Refresh toggle that refreshes every 30 seconds.
• The Logs tab of the Analytics dashboard on the Developer Site, with search, session-only filters and presets for Access, App, Audit and Remote logs.

The fields that make orchestration logs usable are wd_orch_name, wd_orch_step_name, wd_level, wd_tenant, wd_env (IMPL, SANDBOX, PROD or WCPDEV) and wd_common_request_id, which links the entries of one request. Filter on the orchestration and step name rather than searching message text.

Retention: Workday permanently deletes log files older than 30 days. A user with an Admin role can download logs from the Analytics dashboard's Logs tab to keep them longer; the download does not apply the filters in your view. Anything you must be able to show in an audit three months later does not belong only in the Log step.

Logging the actual error inside an error handler

Workday's Handle Errors page notes that an error handler does not receive the outputs of the step it is attached to, only the inputs plus processingError. Workday's Update Service Dates Boomerang sample logs a loop failure with the current item and the processing error's message:

s"${"Error occurred in the loop."}${data.ReportLoop.item}${" Error Message - "}${data._group_ReportLoop.processingError.message()}"

When the message itself is cryptic, the Orchestrate errors guide lists the common ones and their causes. Put the record's business key (the employee ID, the invoice number) in that line rather than the whole item. A message with no key turns a five-minute fix into a search through every input row.

Add Integration Message: what the integration event shows

Add Integration Message writes to the integration event, which is what administrators see in the tenant when they check whether last night's run worked. It has a Severity (INFO by default, or CRITICAL, DEBUG, ERROR, WARNING), a Summary, an optional Detail and a Condition.

It is the Orchestrate counterpart of the integration messages a Studio integration writes with PutIntegrationMessage (see Studio integration message logging). Write these for the person reading the event, not for a developer:

• One INFO message at the start with the launch parameters that matter (the effective date, the pay group).
• One INFO message at the end with counts: records read, created, updated, skipped, failed.
• One ERROR message per failure that needs action, or one ERROR summary that points to the error log file when there are many.

Log to File: a per-record results file

Log to File appends a row to a named log each time it runs. Give it a Log Name and either the default columns (Timestamp, Severity, Message, Details) or a CSV format you created in Settings, with a value per column. The default separator is ,, the escape character / and the quote ". The Create CSV Formats page gives \ as its own default escape character, so set the escape character explicitly in your format if the receiving spreadsheet cares.

In the same Boomerang sample, the logs reach the integration event through a Store Document step:

1. In Create Values at the start, name the logs: SuccessLog.txt and ErrorLog.txt.
2. Inside the loop, a Log to File writes "Data updated successfully for" plus the employee ID to the success log, and the error branch and the loop's error handler write to the error log.
3. After the loop, a Store Document stores system.namedLogFile(data.Init.SuccessLogFile) with the log's name as its Document Title and Attach document to integration event set to true. That field defaults to false in Integration System orchestrations, so without it the file is stored but not visible on the event.
4. For the error log, the sample first reads system.namedLogFile(...) in a Create Values step with its own error handler, which adds an INFO message "No Error Log Created" when the read fails, and stores the file only when that step succeeded. A clean run writes nothing to the error log, and this guard keeps it from ending in a failure.

The sample sets Storage Expires In to P7D on both Store Document steps, so its logs are kept for 7 days. The field takes an ISO 8601 duration; set it to what your audit needs (P1M is one month).

Workday's Log to File reference adds one behaviour to know about: if a step fails and no error handler covers it, Orchestrate automatically stores all named logs and attaches them to the integration event. Logs that were already stored are stored again; the steps did not run twice.

Verbose logging: switch it on for a window, then off

Verbose logging adds execution detail for troubleshooting during development and is controlled per orchestration through a REST API on api.us.wcp.workday.com or api.eu.wcp.workday.com, depending on your region. You need the Developer, Collaborator or Developer Support role. Send a PUT to /orchestrate/v1/apps/{appID}/orchestrations/{orchName}/debug/logging with an Authorization: Bearer header carrying your Developer Site JWT (Workday's page explains how to copy it from the wday-access-token cookie; it is valid for 1 hour) and a body like:

{
  "tenantAlias": "your-tenant-alias",
  "oneTimeOnly": true,
  "duration": "2h",
  "stepFilter": "*"
}

duration defaults to 30m and can be at most 14d. oneTimeOnly: true applies it to a single run, after which the status shows disposed: true. stepFilter limits it to the steps you name; leave it out for all steps. A GET on the same path with ?tenantAlias= shows the current status and expiry, and a DELETE with the same query parameter turns it off.

Prefer oneTimeOnly with a step filter. It answers the question about one run and cannot be forgotten in a production tenant for two weeks.

What to keep in production

Workday does not prescribe a production logging level. This is a recommended setup, with the reason for each part:

1. Keep Add Integration Message at the start and end of every run, with counts, and an ERROR message for anything that needs a person.
2. Keep Log to File success and error logs for any run that changes records, stored on the integration event with a Storage Expires In that covers your audit period. These can outlive the 30-day app log retention; the Log step cannot.
3. Keep Log steps at decision points (which branch, how many pages, which batch), with business keys and without payloads.
4. Gate detailed Log steps behind a condition on an app attribute, for example attrstore.stringValue("logLevel") == "DEBUG", so you can raise the detail for a tenant through App Manager without redeploying. The environment attributes guide shows how to set values per environment.
5. Remove any Log step that writes a full request or response containing personal data, compensation or bank details. App logs are read on the Developer Site by the people who work on the app, a different audience from the tenant's security groups that protect that data.
6. Turn off verbose logging after the diagnosis, and check its status before a release.

Prove the logging works before you need it

Run the integration once with a deliberate failure, for example one record with a missing required field:

• The integration event should show your start and end messages, the counts adding up, and an ERROR message.
• The error log should be attached and name the failing record by its business key.
• Run Logs filtered on wd_orch_name and wd_orch_step_name should show your Log step output for that run, and the Run ID in Orchestration Activity should let you find the same run.

If any of those three is missing, fix it before go-live, while a failed run is still one you caused on purpose.