Accessing Your Vault's File Staging Server

Each Vault in your domain has its own file staging server, which supports various features including Vault Loader and Unclassified Document Creation. The file staging server is a temporary storage area for files you’re uploading to or extracting from Vault. For example, when using Vault Loader to create a new document, you upload the source file to the file staging server before loading the CSV. The CSV then references the source file location on the file staging server.

The file staging server deletes files according to the following rules:

  • Refreshing your Vault removes all files from the file staging server.
  • The server automatically deletes uploaded files and empty directories after 1 year.
  • The server automatically deletes extracted files and folders every 72 hours by default. This auto-deletion timeframe does not apply to files that users upload to the file staging server.
  • Deleted files are not recoverable.

Server URL

The URL for each staging server is the same as the corresponding Vault, for example, veepharm.veevavault.com.

How to Access File Staging Servers

You can access your staging server using your favorite FTP client, the Vault REST API, through the command line, or using Vault File Manager.

Vault Loader Details

You can view and manage files and folders on your Vault’s file staging server using the Vault Loader command line tool. Learn more in the Vault Loader File Staging Command Line Tool Reference.

Users do not need access to the staging server to access files on it with Vault Loader. For example, one user with file staging server access could upload files, and another user without access could create documents via Vault Loader that reference files on the staging server.

Vault File Manager Details

You can view, upload, move, rename, and delete files and folders on your Vault’s file staging server using Vault File Manager. Users with the Vault Owner or System Admin security profile can view and access the root folders of all Vault users in the File Staging tab. Users with the File Staging: Access via Vault File Manager permission can view their root folder on the File Staging tab.

Client Settings

Use the following settings with an FTP client:

  • Protocol: Explicit FTPS or FTPES
  • Encryption: Require explicit FTP over TLS (FTPS). This is a security requirement. Your network infrastructure must support FTPS traffic.
  • Port: This does not typically need to be added and will default to Port 21.
  • Host: vlt-{PODID}-ftp.veevavault.com. For example, 42 is the PODID if your Vault is on POD VV1-42. This value will change if your Vault is migrated to a different POD.
    • For convenience, some Vaults may be able to use the host: {domain}.veevavault.com. For example: veepharm is the domain in veepharm.veevavault.com. This does not work in all configurations.
  • Timeout: 180 seconds if uploading large files.
  • User: {DNS}.veevavault.com+{USERNAME}. This uses the same user name that you log in with. For example: veepharm.veevavault.com+tchung@veepharm.com.
  • Password: Your login password for this Vault. This is the same password used for your standard login. You can also use a valid session ID.
  • Login Type: Normal
  • Transfer File Type: Transfer files as binary
  • Transfer Mode: Passive
    • Active mode is unsupported
  • TLS Session Reuse: If your client has this setting, disable it.

Network & Firewall Settings

In addition to your FTP client settings, your network environment may require some modification. Before trying to connect to the File Staging Server via FTPES, ensure your network and firewall are configured as follows:

  • Outbound firewall filters must permit TCP traffic on these ports to the Host:
    • 21
    • 56000-56100
    • If you are using the Vault Domain in the Host setting:
      • port 21 needs to be open to the Host IP address
      • 56000-56100 need to be open to the vlt-{PODID}-ftp.veevavault.com IP address.
      • If you have multiple Vaults on multiple PODs, please contact support for an address range that encompasses all of them.
  • Firewall filters should be configured by IP address, not DNS name
    • Your network team can retrieve the address from DNS
    • Some firewalls will use the DNS name for reverse lookups, which will fail. Others will scan the TLS handshake to get the connection domain name value and fail the data connections as they do not look like normal web traffic.
  • If the client is behind a Network Address Translation (NAT) device, the NAT device must ensure that all connections generated by the FTPES session are translated to the same source IP address.
    • NAT devices with IP address pools without “stickiness” are incompatible with the FTPES service.
    • This limitation also impacts Active-Active firewalls with separate NAT addresses but without “stickiness” for the TCP connections.

File Staging Server Limits

The following limits affect file uploads to the File Staging Server:

  • File names cannot exceed 218 bytes, including the file extension. Note that one (1) character does not always equal one (1) byte. For example, the character “菌” is three (3) bytes.
  • Complete folder paths cannot exceed 955 bytes.
  • Folders cannot be renamed or moved.
  • Folder modification times reported in file listings are incorrect.
  • Listing large folders is slow.
    • Structure large datasets into trees and remove old files when they are no longer required to achieve better performance.
  • Folder listings are truncated at 65,000 rows.
    • Integrations dependent upon full folder listings should ensure that folders are kept below this value.

Your File Staging Server is a temporary storage solution and you should not retain files on the server for an entire year.

The automated deletion of all content after 1 year has the following effects on directories:

  • Directory objects in the underlying storage are deleted one year after creation.
  • Directories with contents will continue to appear until they are empty, at which point they will vanish.

Any integrations that anticipate the existence of a directory should catch the error when the directory does not exist and recreate the directory. Actively accessing content around the time of the automatic deletion can result in corrupted directory listings. This will normally clear after a refresh. If it persists, contact Veeva Support.

Inbox Details

You can create Staged documents by uploading files to the Inbox directory on your Vault’s file staging server. Staged is the name of the document type, lifecycle, and lifecycle state. Staged documents are unclassified. You and other users with access can classify these documents like any other unclassified document. However, Staged documents do not use the Unclassified lifecycle and may have different roles and access control settings.

The file staging server’s Inbox is automatically available in all Vaults. Before using this feature, Admins should:

Message Templates

  • Cannot Upload LSA to Binder or Placeholder (ftp_inbox_attach_to_unsupported_document__v): Vault uses this error message when the target document for a rendition is a binder or placeholder.
  • Large Size Asset Attached (ftp_inbox_lsa_uploaded_to_exsting_doc__v): This notification goes to the user who uploaded a Large Size Asset rendition to an existing document.
  • Cannot Attach Viewable Rendition to Video (ftp_inbox_attach_viewable_rendition_to_video__v): Vault uses this error message when the target document for an uploaded Viewable Rendition file is a video.
  • Max File Size Exceeded (ftp_upload_too_large__v): Vault uses this error message when a file exceeds the size limits. It is not specific to file staging server Inbox.
  • Missing Rendition Type (ftp_inbox_missing_rendition_type__v): Vault uses this error message when the uploading user does not specfy a remdition type or specifies an invalid rendition type.
  • No Appropriate Permission (ftp_inbox_no_appropriate_rendition_permission__v): Vault uses this error message when the uploading user attempts to update a document on which they don’t have the required permissions.
  • Target Document Not Found (ftp_inbox_target_document_notFound__v): This error message occurs when the filename targets a Document ID that does not exist. In some cases, the ID is valid, but the user uploading does not have View Document access to the targeted document.

Clinical File Staging Server Loader (Clinical Operations Only)

In Clinical Operations Vaults, you can use your Vault’s File Staging Server to load object record data into Vault. See Creating & Updating Records With Vault Staging Server for details.

Staging Server Permissions

To download files from the staging server, you must have the standard Vault Owner or System Admin security profile or have a custom security profile that includes the File Staging: Access and API: Access API permissions.

The staging server does not support SAML SSO authentication.

To upload files to the root folder on the staging server, you must have the standard Vault Owner or System Admin security profile. Users with the File Staging: Access permission can upload files to a personal folder.

When referencing a file in a user’s personal folder on the staging server, you must include the user directory in the file path. For example, Clara is not a Vault Owner or System Admin. She can only upload files directly to Vault1234/u5678, where 1234 is her Vault ID and 5678 is her user ID. Note that Clara can still make new directories inside of her user directory, such as /u5678/uploads.

File Staging Linking

Admins can link a Vault’s File Staging server to a different Vault, without needing to rely on Product Support. You can use File Staging Linking during migrations where it’s common for users to link file staging rather than manually moving documents between different File Staging servers.

The File Staging Settings page allows Admins to view and modify File Staging Linking. To use File Staging Linking, you must have the standard Vault Owner or System Admin security profile. To manage the permissions for the File Staging Linking page, navigate to Admin > User & Groups > Permission Sets > [Permission Set] > Admin.

From the Admin page, navigate to Settings > File Staging Settings to edit the File Staging Settings for a Vault.

This page includes the following sections:

  • Vault Details provides information about the Vault that the Admin is currently in.
  • Vault shows the Vault’s name and ID.
  • File Staging used by indicates whether the Vault’s File Staging server is linked to another Vault. Each Vault can only have one file staging link, but multiple Vaults can point to a single file staging area.
  • Update File Staging allows Admins to link the current Vault to a different File Staging server.

Configuring File Staging Linking

To link a Vault’s File Staging server to a different Vault:

  1. From the File Staging Settings menu, next to the Use File Staging from dropdown, click Edit.
  2. The Use File Staging from dropdown shows the list of File Staging servers that are available to be linked to the Vault that the Admin is currently in. Select an available dropdown option, and click Save.
  3. A dialog will appear warning the Admin that files in the File Staging server of the current Vault will no longer be accessible. Click Continue to confirm.

Upon confirmation, the Link Status changes from Active to Pending. A notification is available once the linking is complete, and the Link Status will change to Active. The amount of time that the link update takes is dependent on the number of files in the selected File Staging Server.

Troubleshooting Error Messages

Error Message Troubleshooting Step
File Staging linking for this Vault could not be completed successfully due to:
A stale browser tab allowed an invalid selection. Please refresh Vault Settings tabs and try again.		 This error occurred because a stale tab allowed an invalid selection.
Refresh the Vault Settings tab and update the linking again.
File Staging linking for this Vault could not be completed successfully due to:
Files are currently being transferred to long term storage. Users should wait several minutes and try again.		 This error occurred because files in the Vault’s existing File Staging are currently being transferred over to the Vault.
All files need to be transferred over before the File Staging link can be updated.
File Staging linking for this Vault could not be completed successfully due to:
A server error.		 Contact Veeva Support.

You can complete all steps in this article with the standard System Administrator or Vault Owner security profile. If your Vault uses custom security profiles, your profile must grant the following permissions:

Type Permission Label Controls
Security Profile API: Access API Ability to access your Vault’s file staging server and download files via the API.
Security Profile Application: File Staging: Access Ability to access your Vault’s file staging server and upload documents to a personal folder via the API.
Security Profile Application: File Staging: Access via Vault File Manager Ability to access your Vault’s file staging server in Vault File Manager.