Vault 2014 – AcquireFilesSettings & AcquisitionStatus Skipped

By Wayne Brill

I had a discussion about AcquireFilesSettings used with AcquireFile() recently with a colleague in engineering. I thought it could be useful so I am posing it here:

This post on Doug Redmond’s blog uses the AcquireFilesSettings.AddFileToAcquire() method instead of the AddEntityToAcquire() method and then specifies the acquisition option for each individual file to download. This will work fine, but an easier way is to use the AcquireFilesSettings.DefaultAcquisitionOption to control the acquisition option for all entities in the download.

Regarding skipped files, the documentation for the AcquisitionStatus.Skipped says, “The file was not acquired.  It was skipped based on a user choice that occurred during validation.” The “validation” step the documentation is referencing is essentially equivalent to the AcquireFileExtensibilityOptions.PreFileAcquire handler.  It is during this event that potential problems that might prevent a download from succeeding are passed to the handler and the handler decides what to do. The “user choice” part is really only relevant for GUI acquires. The default behavior during a GUI acquire is to display prompts to the user such as when a file needs to be replicated before it can be downloaded. If a user ops to not acquire a file when these prompts are displayed, the file is considered “skipped”. For non-GUI downloads, the default PreFileAcquire handler doesn’t display any prompts and just decides things programmatically.  The default implementation will “skip” downloading a file for the following reasons:

•    The file to be download needs to be synced with a remote site before downloading and the AcquireFilesSettings.OptionsResolution.SyncWithRemoteSite setting is set to SyncwithRemoteSite.Validate

•   The local file that is going to be overwritten contains edits that are not stored in Vault and will be lost if the file is downloaded and the AcquireFilesSettings.OptionsResolution.OverwriteOption is not set to OverwriteOptions.ForceOverwriteAll

•    The file to be acquired is checked out to the current user in the download location and the AcquireFilesSettings.OptionsResolution.OverwriteOption is not set to OverwriteOptions.ForceOverwriteAll

If they want to force that every file that is part of the acquire is at least attempted to be downloaded, they’ll have to set the SynceWithRemoteSite setting to Always and the OverwriteOption to ForceOverwriteAll. This doesn’t mean that all entities to be acquired will succeed but I believe it will mean they will all at least be attempted.