Using the Vault API can feel overwhelming, especially when you’re just getting started. In this post, we’ll break down one of the most useful parts of the API: searching for files based on their properties. By the end, you’ll understand how to build search conditions, control the search location, and retrieve a clean list of matching files from Vault.
Let’s dive in.
Why Search Conditions Matter
If you're building an Inventor add-in, automating processes, or simply querying Vault programmatically, knowing how to construct search conditions is essential. Well-built search conditions allow Vault to efficiently filter files based on metadata, making your tools faster, cleaner, and easier to maintain.
Defining the Path
Before performing a property-based search, you need to define the folder path where Vault should look.
To search the entire Vault, use:
$/
In Vault:
- $ represents the working folder
- / indicates to search inside that working folder
To narrow your search (highly recommend for performance), specify a more precise path:
"$/Designs"
"$/Designs/CustomerA/"
"$/Designs/CustomerB/"
The more specific the folder, the faster the search will run.
Secure a Vault Connection
Vault supports several secure connection methods.
For this example, we rely on the active Vault connection provided through the Inventor Vault Add-in.
This means the user must be logged in through the Vault Add-in before the API calls are made.
References:
Imports System.Runtime.Versioning
Imports VDF = Autodesk.DataManagement.Client.Framework
Imports Connectivity.InventorAddin.EdmAddin
Connection Example:
Public Function GetActiveConnection() As VDF.Vault.Currency.Connections.Connection
Dim EDMS As EdmSecurity = EdmSecurity.Instance
Dim connection As VDF.Vault.Currency.Connections.Connection = EDMS.VaultConnection
If connection IsNot Nothing AndAlso connection.IsConnected Then
Return connection
End If
Return Nothing
End Function
DocumentService
DocumentService is the primary API for interacting with files and folders inside Vault.
It performs all file-centric operations, including:
-
Searching for files
-
Navigating folders
-
Retrieving file versions
-
Checking files in/out
-
Managing file relationships
Any time your add-in needs to access or manipulate a Vault file, DocumentService is the Web Service doing the work.
Dim docService As ACW.DocumentService = VaultConn.GetActiveConnection.WebServiceManager.DocumentService
PropertyService
PropertyService is the API used to work with Vault metadata.
This includes retrieving property definitions, reading property values, and updating metadata on Vault entities such as files, folders, and items.
Dim propService As ACW.PropertyService = VaultConn.GetActiveConnection.WebServiceManager.PropertyService
Property Definitions
Before you can search by property, you must retrieve Vault’s property definitions. Each property (e.g., Part Number, Description, Material) has an internal ID, so you need to map the display name to its corresponding PropDef.Id.
Because we’re searching files, we use the "FILE" entity class ID:
Dim propDefs As ACW.PropDef() = propService.GetPropertyDefinitionsByEntityClassId("FILE")
Vault supports several other entity class IDs as well, and you can find the most common ones in the table below.
Creating Search Conditions
This part of the process converts each property name/value pair into a Vault-ready search condition.
The code:
-
Loops through each property filter in the dictionary
-
Skips empty entries
-
Locates the matching PropDef
-
Builds a SrchCond (the actual Vault search instruction)
-
Adds each valid condition to a list
Dim searches As New List(Of ACW.SrchCond)
For Each kvp As KeyValuePair(Of String, String) In propFilters
Dim propName As String = kvp.Key
Dim propValue As String = kvp.Value
' Skip blank entries
If String.IsNullOrWhiteSpace(propName) OrElse String.IsNullOrWhiteSpace(propValue) Then
Continue For
End If
' Find the matching property definition
Dim def As ACW.PropDef = propDefs.SingleOrDefault(Function(pd As ACW.PropDef) pd.DispName = propName)
If def Is Nothing Then
Debug.WriteLine($"Property '{propName}' not found in Vault definitions.")
Continue For
End If
' Create the search condition for this property/value pair
Dim cond As New ACW.SrchCond With {
.PropDefId = def.Id,
.PropTyp = PropertySearchType.SingleProperty,
.SrchOper = 3, ' Equals
.SrchRule = ACW.SearchRuleType.Must,
.SrchTxt = propValue
}
searches.Add(cond)
Next
Resolving Vault Folders
Next, we determine which folder Vault should search in. The code calls FindFoldersByPath and extracts only valid folder IDs (ignoring any unresolved paths):
Dim folders As ACW.Folder() = docService.FindFoldersByPaths(New String() {incSearchInFolder})
Dim folderIDs As Long() = folders?.
Where(Function(f As ACW.Folder) f.Id <> -1).
Select(Function(f As ACW.Folder) f.Id).
ToArray()
If folderIDs Is Nothing OrElse folderIDs.Length = 0 Then
Throw New InvalidOperationException($"No valid folders found at: {incSearchInFolder}")
End If
Executing the Vault Search
With search conditions and folder IDs ready, the final step is to call Vault's FindFilesBySearchConditions. The bookmark and status variables support cases where Vault returns large result sets in multiple parts.
Dim bookmark As String = String.Empty
Dim status As ACW.SrchStatus = Nothing
Dim files As ACW.File() = docService.FindFilesBySearchConditions(
searches.ToArray(),
Nothing,
folderIDs,
True, ' Include subfolders
True, ' Latest versions only
bookmark,
status
)
' Return all matching files (if any)
Return If(files IsNot Nothing AndAlso files.Length > 0, files, Nothing)
Vault returns an array of matching file objects, or Nothing if no results are found.
Full Code Example:
Public Function FindFilesFromProps(propFilters As Dictionary(Of String, String), Optional incSearchInFolder As String = "$/") As ACW.File()
Try
'Validate the Vault connection
If VaultConn.GetActiveConnection Is Nothing Then
Throw New InvalidOperationException("Vault connection is not active.")
End If
'Get Vault services and property definitions
Dim docService As ACW.DocumentService = VaultConn.GetActiveConnection.WebServiceManager.DocumentService
Dim propService As ACW.PropertyService = VaultConn.GetActiveConnection.WebServiceManager.PropertyService
Dim propDefs As ACW.PropDef() = propService.GetPropertyDefinitionsByEntityClassId("FILE")
Dim searches As New List(Of ACW.SrchCond)
For Each kvp As KeyValuePair(Of String, String) In propFilters
Dim propName As String = kvp.Key
Dim propValue As String = kvp.Value
' Skip blank entries
If String.IsNullOrWhiteSpace(propName) OrElse String.IsNullOrWhiteSpace(propValue) Then
Continue For
End If
' Find the matching property definition
Dim def As ACW.PropDef = propDefs.SingleOrDefault(Function(pd As ACW.PropDef) pd.DispName = propName)
If def Is Nothing Then
Debug.WriteLine($"Property '{propName}' not found in Vault definitions.")
Continue For
End If
' Create the search condition for this property/value pair
Dim cond As New ACW.SrchCond With {
.PropDefId = def.Id,
.PropTyp = ACW.PropertySearchType.SingleProperty,
.SrchOper = 3, ' Equals
.SrchRule = ACW.SearchRuleType.Must,
.SrchTxt = propValue
}
searches.Add(cond)
Next
' Get the folder(s) to search in
Dim folders As ACW.Folder() = docService.FindFoldersByPaths(New String() {incSearchInFolder})
Dim folderIDs As Long() = folders?.
Where(Function(f As ACW.Folder) f.Id <> -1).
Select(Function(f As ACW.Folder) f.Id).
ToArray()
If folderIDs Is Nothing OrElse folderIDs.Length = 0 Then
Throw New InvalidOperationException($"No valid folders found at: {incSearchInFolder}")
End If
' Execute the Vault search
Dim bookmark As String = String.Empty
Dim status As ACW.SrchStatus = Nothing
Dim files As ACW.File() = docService.FindFilesBySearchConditions(
searches.ToArray(),
Nothing,
folderIDs,
True, ' Include subfolders
True, ' Latest versions only
bookmark,
status
)
' Return all matching files (if any)
Return If(files IsNot Nothing AndAlso files.Length > 0, files, Nothing)
Catch ex As Exception
Debug.WriteLine($"Vault search failed: {ex.Message}")
Return Nothing
End Try
End Function
Additional Visual Studio Tips
To successfully work with the Vault API, your project must reference several Autodesk assemblies (DLLs). These DLLs provide access to Vault’s Web Services as well as the connection exposed through the Inventor Vault Add-In. Without these references, calls related to authentication, file searches, or property access will fail or appear missing in IntelliSense.
Below are the two essential references required for the example in this post:
Autodesk.Connectivity.WebServices
This assembly contains the core Vault Web Services such as DocumentService and PropertyService.
Inventor/Vault 2025 DLL Location:
C:\ProgramData\Autodesk\ApplicationPlugins\VaultInventor2025.bundle\Contents\Autodesk.Connectivity.WebServices.dll
Connectivity.InventorAddin.EdmAddin
This assembly gives you access to the EdmSecurity and the active Vault Connection used when Inventor is logged in.
Inventor/Vault 2025 DLL Location:
C:\ProgramData\Autodesk\ApplicationPlugins\VaultInventor2025.bundle\Contents\Connectivity.InventorAddin.EdmAddin.dll
Required Imports
Make sure you include the following import at the top of the class containing your search function:
Imports ACW = Autodesk.Connectivity.WebServices
This simplifies your code and ensures that all Vault Web Service classes (such as ACW.DocumentService, ACW.PropDef, and ACW.SrchCond) resolve correctly.
Wrap-Up
Property-based searches are one of the most powerful tools in the Vault API.
Once you understand how to retrieve property definitions, build search conditions, and specify a search location, you can automate workflows, build smarter add-ins, and query Vault data with precision.
2 Comments
