Workday integrations transfer files over SFTP and apply PGP encryption either through tenanted Integration Process Event business process services (Service - Document Delivery and Service - Document Retrieval) or inside a Workday Studio assembly using the sftp-out transport and pgp-encrypt / pgp-decrypt steps. Workday recommends using business process Delivery and Retrieval services whenever possible so administrators can rotate SSH keys, X.509 certificates, PGP keys, and SFTP directories in the tenant without editing or redeploying Studio CLAR files. When SFTP or PGP steps fail, the root cause is almost always an environment restriction mismatch (Restricted To), an expired key pair or unverified SSH host key fingerprint, a missing Put* domain permission for deploying delivery services, or an invalid embedded PGP plaintext filename.

Choose between Business Process Delivery/Retrieval and Studio sftp-out

Even when an integration is built in Workday Studio, you do not have to hard-code SFTP transports or PGP steps inside the assembly diagram. Compare the two approaches:

Capability Business Process Delivery / Retrieval Service (Recommended) Studio sftp-out Transport & pgp-encrypt / pgp-decrypt Steps
CapabilityWhere configuredBusiness Process Delivery / Retrieval Service (Recommended)In the tenant on the Integration Process Event business process (Business Process > Create, Copy, or Link Definition)Studio sftp-out Transport & pgp-encrypt / pgp-decrypt StepsInside the Studio assembly (sftp-out, pgp-encrypt, pgp-decrypt) deployed via a CLAR file
CapabilityCredential & key storageBusiness Process Delivery / Retrieval Service (Recommended)Directly accesses tenanted SSH key pairs (Create x509 Private Key Pair) and PGP keys (Create PGP Public Key / Create PGP Private Key Pair)Studio sftp-out Transport & pgp-encrypt / pgp-decrypt StepsCannot directly browse tenant key stores unless passed via attachment:certificate/ WID references or packaged in ws/WSAR-INF
CapabilityKey rotation & endpoint changesBusiness Process Delivery / Retrieval Service (Recommended)Admin updates the transport or key in the tenant UI with zero Studio redeploymentStudio sftp-out Transport & pgp-encrypt / pgp-decrypt StepsRequires updating Studio properties or WSAR-INF key files and redeploying the collection if keys are packaged in the archive
CapabilityWhen to useBusiness Process Delivery / Retrieval Service (Recommended)Standard pre-execution file retrieval and post-execution file delivery for EIB, Connectors, and StudioStudio sftp-out Transport & pgp-encrypt / pgp-decrypt StepsMid-assembly transfers where an integration must dynamically list, fetch, or delete remote files during step execution

In Workday Studio, never use the legacy Ftp common component (vm://wcc/Ftp) for new integrations; it has been removed from the Studio Palette and hides public-key authentication options. Always use a business process Delivery/Retrieval service or the native sftp-out component.

Configure SFTP Delivery, Retrieval, and Sequence Generators

To attach a tenant-managed SFTP transport to a Connector or Studio integration:

  1. From the integration system's Related Actions, select Business Process > Create, Copy, or Link Definition to create an integration-specific Integration Process Event business process definition.
  2. Add a Service - Document Delivery step (after Service - Fire Integration for outbound) or a Service - Document Retrieval step (before Service - Fire Integration for inbound).
  3. Click Configure Document Delivery (or Configure Document Retrieval) on the business process step and populate:
    • Document(s): Select the output of the associated integration process (remember that Studio store steps must be tagged with is.document.deliverable = true via PutIntegrationMessage to be picked up).
    • Transport Type: Select SFTP.
    • SFTP Address: Enter the SFTP URI with the server hostname or IP address (append the port number if non-standard; Workday defaults to port 22).
    • Directory: Enter the case-sensitive target directory on the remote server. Include a leading slash (/) only for an absolute path, not a relative path. The directory must already exist on the SFTP server.
    • Use Temp File / Temp File Name: Uploads the payload under a temporary name and renames it upon completion so downstream vendor jobs do not pick up partially written files.
    • Restricted To: Restrict each transport configuration to its matching environment (Production, Sandbox, Implementation). If you migrate an integration from Implementation to Production and leave Restricted To set to Implementation, the transport will fail or skip files in Production until updated.
  4. To prevent overwriting files on the remote SFTP directory, enable the Integration Sequence Generator service and run Related Actions > Integration System > Configure Integration Sequence Generators to define a dynamic filename pattern with date-time tokens and incrementing sequence numbers.
  5. Before launching the full integration, run Related Actions > Integration > Test Transport on the integration system to test connecting to the SFTP server, listing remote directory files, or sending a test file.

Configure SSH key authentication, X.509 certificates, and Dual Authentication

SFTP endpoints authenticate using a username/password, an SSH key pair, or both (dual authentication). Workday manages keys and certificates through dedicated security tasks:

Key / Certificate Task in Workday Purpose in Integrations
Key / Certificate Task in WorkdayCreate x509 Private Key PairPurpose in IntegrationsGenerates an SSH / X.509 public-private key pair in Workday. You export the public key to share with the external SFTP server administrator and select this key pair under SSH Authentication on the SFTP transport.
Key / Certificate Task in WorkdayCreate x509 Public KeyPurpose in IntegrationsStores an external X.509 public certificate in the tenant (for example, -----BEGIN CERTIFICATE----- ... -----END CERTIFICATE-----) for JWT bearer grants, WS-Security SOAP authentication, or partner signature verification.
Key / Certificate Task in WorkdayCreate PGP Public KeyPurpose in IntegrationsImports an external vendor's PGP public key into Workday so outbound Delivery services (or Studio pgp-encrypt steps) can encrypt files sent to that vendor.
Key / Certificate Task in WorkdayCreate PGP Private Key PairPurpose in IntegrationsGenerates a PGP key pair inside Workday so you can share the public key with a vendor and use the private key under Decrypt Using on inbound Retrieval services (or digital signing on outbound files).

Studio sftp-out authentication and dual-authentication behavior

When you configure an sftp-out transport inside a Workday Studio assembly, pay close attention to the Dual Authentication (dual-authentication) property on the Common tab and its private-key child element (Private Key path in ws/WSAR-INF and Passphrase):

  • Dual Authentication = false (default) with no private key configured: Authenticates using Username and Password.
  • Dual Authentication = false (default) with a private-key child element configured: Automatically authenticates using only the Username and Private Key, ignoring the Password field completely.
  • Dual Authentication = true: Enforces two-factor SFTP authentication requiring both the Username/Password combination and the Private Key value.
  • Host Key Fingerprint (host-key-fingerprint): Stores the SFTP server's SSH host key fingerprint. If the external vendor rebuilds their SFTP server or rotates their server host key without notice, SFTP connections fail immediately during the SSH handshake until you update the Host Key Fingerprint value.
  • File deletion after get: Unlike a business process Retrieval service (which has a Delete After Retrieval checkbox that fails the retrieval if delete permissions are denied), the sftp-out transport's get method does not automatically delete the remote file. You must invoke a separate sftp-out component with Method set to delete to remove the file after retrieval.

Configure PGP encryption, decryption, and digital signatures

For outbound integrations, configure PGP encryption on the business process Service - Document Delivery step by selecting the vendor's PGP public key (and optionally signing the file with a Workday PGP private key pair). For inbound integrations, select your Workday PGP Private Key Pair in the Decrypt Using field on the Service - Document Retrieval step.

Referencing tenant PGP keys in a Studio pgp-encrypt step

While Workday recommends performing PGP encryption in the business process Delivery service, if you must encrypt mid-assembly using the Studio pgp-encrypt encoding step, you do not have to hard-code the .asc key file inside ws/WSAR-INF. You can dynamically reference a PGP public key stored in the Workday tenant via an Integration Attribute:

  1. Define a Reference-type Integration Attribute on your workday-in transport (for example, PGP Encryption Key) that references a public key object in the tenant.
  2. On the pgp-encrypt step's Common tab, set the Certificate (certificate) property to an attachment:certificate/ MVEL expression:
attachment:certificate/WID_VALUE

where WID_VALUE is replaced by an MVEL expression calling intsys.getAttributeReferenceData('PGP Encryption Key', 'WID').

Alternatively, Certificate accepts a mediation context variable URL (mctx:vars/MyPublicKey) or a relative file path inside ws/WSAR-INF (such as /keys/VendorPublicKey.asc).

Key pgp-encrypt properties that cause runtime errors if misconfigured:

  • Ascii Armored (ascii-armored): Set to true to output Base64-like ASCII-armored PGP text with header/footer blocks, or false for raw binary PGP output.
  • Containing Integrity Check (containing-integrity-check): Generates a message modification detection code (MDC) / integrity check required by modern OpenPGP implementations.
  • Textmode (textmode): Only set Textmode = true if the input payload strictly uses <CR><LF> (\r\n) Windows line endings. If you set Textmode = true on data that uses Unix <LF> line endings, Workday throws an encryption error.

Fix common SFTP, PGP, and key rotation errors

Use this diagnostic table to resolve the most frequent transport and encryption failures:

Observed Error or Symptom Root Cause Resolution
Observed Error or SymptomInbound PGP file named VendorData.pgp appears on the Integration Event as _CONSOLE (or *.plaintext)Root CausePGP embeds an internal plaintext filename inside the encrypted packet. Workday's Retrieval Service uses that embedded filename when naming the decrypted attachment. When a vendor encrypts data via standard input (stdin / pipe) without passing a filename flag, their PGP tool embeds _CONSOLE as the filename.ResolutionAsk the sending vendor to specify a proper filename when encrypting (or strip the embedded _CONSOLE flag). If no plaintext filename is embedded at all, Workday strips .pgp (myFile.csv.pgp becomes myFile.csv), keeps .xlsx, or appends .plaintext. In Studio pgp-decrypt, set the Decrypted Filename (decrypted-filename) property to override a missing embedded name.
Observed Error or SymptomPermission to deploy denied (integration contains a delivery or retrieval service) when deploying from StudioRoot CauseDeploying a Studio integration that defines a delivery or retrieval service requires permissions beyond Integration Build.ResolutionGrant the developer's security group Put permission in at least one of these domains: Business Process Administration, Manage: Business Process Definitions, or iLoad Web Services, then activate pending security changes.
Observed Error or SymptomSFTP Retrieval or Connection fails after migrating from Sandbox/Implementation to ProductionRoot CauseThe transport's Restricted To field is still set to Implementation or Sandbox. When the current tenant environment does not match Restricted To, Workday refuses to execute the transport and retrieves zero files.ResolutionEdit the SFTP connection or business process Delivery/Retrieval transport in Production and update Restricted To to Production (or configure separate environment-specific transports prior to migration).
Observed Error or SymptomSFTP retrieval imports the file data, then fails at the end of the transport stepRoot CauseDelete After Retrieval is enabled on the SFTP configuration, but the SFTP user account on the external server only has read (r) permissions and lacks write/delete (w) permissions on the remote directory.ResolutionEither ask the external SFTP administrator to grant delete permissions to the SFTP user for that directory, or clear the Delete After Retrieval checkbox.
Observed Error or SymptomSudden SFTP or SOAP authentication failure on a previously working scheduled integrationRoot CauseAn X.509 certificate, SSH key pair, or PGP key reached its expiration date, or the vendor rotated their SFTP server's SSH host key fingerprint.ResolutionCheck certificate and key expiration dates in Workday security configuration. Rotate the key via Create x509 Private Key Pair, Create x509 Public Key, or Create PGP Public Key, update the transport's Host Key Fingerprint if the server changed, and run Integration > Test Transport to confirm connectivity.

How kiweely fits

kiweely diagnoses failing SFTP transports, PGP encryption steps, and certificate expirations across EIBs, Cloud Connect packages, and Workday Studio assemblies. It inspects your integration events, business process delivery steps, and Studio transport properties in your sandbox tenant to identify misconfigured key references or environment restrictions and verify the transport end to end. Kiweely Personal is free in your Workday personal developer account and its tenant.

Frequently asked questions

Why did my decrypted inbound PGP file get renamed to _CONSOLE on the integration event?

When PGP encrypts a file, it embeds an internal plaintext filename inside the encrypted payload, and Workday's Retrieval Service uses that embedded string to name the decrypted event document. If the external sender encrypted the data stream from standard input (stdin) without specifying an output filename metadata flag, their PGP utility embeds _CONSOLE as the original filename. Have the sender pass a valid filename parameter in their PGP encryption command.

Why does Studio sftp-out ignore my password when I also configure a private key?

By default, the sftp-out component sets Dual Authentication (dual-authentication) to false. When dual-authentication is false and a private-key child element is present, Workday Studio authenticates using only the username and private key and ignores the password property. Set Dual Authentication to true if the external SFTP server requires both a password and an SSH private key.

What are the file count and duration limits for SFTP data transfers in Workday?

Workday integration delivery and retrieval services (as well as SFTP connections) can transfer a maximum of 5,000 files per run, and the transfer must complete within the runtime window (2 hours guaranteed for Studio integrations; 5 hours maximum for Prism SFTP connections). If an inbound SFTP folder accumulates more than 5,000 small files, archive them into a .zip or .tar file before transfer and extract them using the unzip-splitter or unzip step.

Sources checked