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.

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:

Build one or more single-item requests
Collect the item requests into a bulk request
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.

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

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.

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.