**Source URL:** https://limited.veevavault.dev/medical/vault-sdk/services/file-staging-service

# File Staging Service

Each Vault in your domain has its own file staging, which you can access using Vault Java SDK or Vault API. You can use this as a temporary storage area for files you're loading. Vault also uses it to store extracted files.

Access to file staging is controlled by the *File Staging: Access* permission. Learn more about permissions, file staging paths, and limits in the [File Staging guide](/medical/vault-api/guides/file-staging/).

`FileStagingService` provides methods to create, retrieve, list, delete, and move or rename files and folders in file staging. All operations are performed in bulk and support up to 500 items per request.

Use `FileStagingService` to work with staged files directly from Vault Java SDK code. For example, from a trigger, action, or other custom integration.

Every file staging operation follows the same pattern:

1.  Build one or more single-item requests
2.  Collect the item requests into a bulk request
3.  Pass that to the matching service method

Each method returns a batch operation on which you specify a success handler with `onSuccesses()` and an error-handling strategy with `onErrors()`, then call `execute()`. Specifying an error-handling strategy is required.

## Creating Files and Folders

Use `createItems()` to create files and folders in file staging. For each item, specify a `FileStagingKind` (`FILE` or `FOLDER`) and the target path. For file creation, also provide a `FileReference` pointing to the source file. File names cannot exceed 218 bytes, and complete folder paths cannot exceed 955 bytes.

By default, creating an item at a path that already exists results in an error. Set `withOverwrite(true)` to replace the existing item.

By default, Vault also validates that the parent path exists before creating an item. To skip this validation, set `withFlat(true)`, which can improve performance when the parent structure is already known.

<Aside type="caution">
Skipping validation with `withFlat(true)` can be risky. When using, ensure no item of the same name already exists anywhere along the path.
</Aside>

The following code example creates files and folders in file staging:

```java
FileStagingService fileStagingService = ServiceLocator.locate(FileStagingService.class);

FileStagingCreateItemRequest folderRequest = fileStagingService.newCreateItemRequestBuilder()
    .withKind(FileStagingKind.FOLDER)
    .withPath("u1234/reports")
    .build();

// csvFileRef is a FileReference to the source file, for example one obtained from a document or another SDK service
FileStagingCreateItemRequest fileRequest = fileStagingService.newCreateItemRequestBuilder()
    .withKind(FileStagingKind.FILE)
    .withPath("u1234/reports/summary.csv")
    .withFileReference(csvFileRef)
    .build();

FileStagingCreateItemsCollectionRequest createRequest = fileStagingService.newCreateItemsCollectionRequestBuilder()
    .withItems(VaultCollections.asList(folderRequest, fileRequest))
    .build();

fileStagingService.createItems(createRequest)
    .onSuccesses(results -> {
        for (FileStagingCreateItemResult result : results) {
            FileStagingItem createdItem = result.getFileStagingItem();
            logService.info("Created: " + createdItem.getPath());
        }
    })
    .onErrors(errors -> {
        for (FileStagingCreateItemError error : errors) {
            logService.error(error.getError().getMessage());
        }
    })
    .execute();
```

## Retrieving Files

Use `getFiles()` to retrieve metadata and a file reference for one or more staged files. Build a request for each file path with `newGetFileRequestBuilder()`. This operation supports file paths only, not folders. Collect them with `newGetFilesCollectionRequestBuilder()`. Each successful result provides a `FileStagingItem` containing the file's path, name, and a `FileStagingFileReference` you can pass to other SDK services.

## Retrieving Folders

Use `listFolders()` to retrieve the contents of one or more folders. Build a request for each folder path with `newListFolderRequestBuilder()` and collect them with `newListFoldersCollectionRequestBuilder()`. Each successful result exposes its items as a stream of `FileStagingItem` objects.

By default, `listFolders()` returns only the immediate contents of each folder. Set `withFlat(true)` to recursively return all files nested beneath the folder, including those in its subfolders. Folder listings are truncated at 65,000 rows, so structure large datasets into subfolders to stay within this limit.

## Deleting Files and Folders

Use `deleteItems()` to delete files and folders. Build a request for each item with `newDeleteItemRequestBuilder()`. To delete a folder and all of its contents, include `withRecursive()`, which is valid only for folder paths. Delete operations run asynchronously, meaning each successful result returns a job ID. Treat this job ID as the handle for tracking completion rather than assuming the change has taken effect when `execute()` returns.

## Moving and Renaming Files and Folders

Use `updateItems()` to move or rename files and folders. For each request built with `newUpdateItemRequestBuilder()`, specify the existing path, then a new parent path to move the item, a new name to rename it, or both. Like delete, these operations run asynchronously and return a job ID to track completion.

Learn more about each operation's methods and interfaces in the [Javadocs](https://repo.veevavault.com/javadoc/vault-sdk-api/26.2.3/docs/api/com/veeva/vault/sdk/api/filestaging/package-summary.html).

## Using FileStagingFileReference

`FileStagingFileReference` is a `FileReference` that points to a file in file staging. You obtain one from a `FileStagingItem` returned by `getFiles()` or `listFolders()`, or you can pass one directly into a `createItems()` call to write an existing Vault file to file staging.

Because `FileStagingFileReference` implements `FileReference`, you can pass it to any SDK service method that accepts a file reference, including:

*   `DocumentVersion.setSourceFile()`: Set a staged file as a document's source file.
*   `DocumentService.newDocumentAttachment()`: Create a document attachment from a staged file.
*   `DocumentService.newDocumentRendition()`: Add a rendition from a staged file.
*   `FileTranslationInput.Builder.withSourceFile()`: Supply a staged file as translation input.

In addition to the standard file reference behavior, `FileStagingFileReference` exposes `getPath()`, `getSize()`, and `getLastModified()`. Learn more in the [Javadocs](https://repo.veevavault.com/javadoc/vault-sdk-api/26.2.3/docs/api/com/veeva/vault/sdk/api/filestaging/package-summary.html).

---

**Previous:** [File Translation Service](/medical/vault-sdk/services/translation-service)  
**Next:** [Additional Services](/medical/vault-sdk/services/misc-services)