It's All Just Ones and Zeros

Vault 2014 API Language Pack

One of the neat things about the UI components in the SDK is that they are also used by the Vault clients.  This means that when the product gets localized, the SDK components get localized automatically.

All you need to do is grab the satellite assemblies and distribute them with your app.  Oh wait, you don’t need to do that.  Dan Dulzo has already done this for you.  Thanks Dan.

Click here to download the Vault 2014 API Language Pack

This should include all the langauges that Vault supports.  If we missed one, let us know.

---

When to use
You should only use this for EXEs you write or when plugging in to a non-Autodesk application.  If you are plugging in to an Autodesk product, the localization pack(s) should already be in place.

How to use
In the zip file are a bunch of folders with language codes for names.  Grab the folders you want and place them under your EXE folder.  For example, if your app is installed at c:\myApp\Program.exe, then your German language back would be at c:\myApp\de.

Don’t feel you need to have one language folder.  Feel free to dump them all in your EXE folder.  At runtime, Windows will load the appropriate language pack based on the OS settings.  If your language isn’t in the language pack, the UI defaults to English, but you knew that already.

This language pack only supplies localizations of UI in the Vault SDK.  Any UI you create yourself will have to be handled by you. 

---

Screenshots

Here is the login dialog, which is invoked by the following code:

connection = VDF.Vault.Forms.Library.Login(null);

English:

German:

 

Here is an error dialog, which is being invoked from the following code:
catch (Exception ex)
{

    VDF.Forms.Library.ShowError(ex, ex.Message);

}

English:

German:

Vault Filestore Server

Welcome to my 256th blog posting.  If you are one of my loyal readers, you probably already know why that is significant.  Regardless, I’ll be “celebrating” by going over the filestore server...

One of the major architecture changes in Vault 2014 is the filestore server.  In order to explain this architecture, I need to first explain how things worked in 2013. 

If you had a multi-site environment in Vault 2013, it looked like this.

There is a problem with this architecture, every time you need data from the database, you need to go through two hops.  Just about everything you do in Vault requires the database, so the extra hop is significant.

---

For Vault 2014 the architecture, was updated to look like this.

DB calls go directly to the database, so it’s only one hop.  That efficiency comes at a cost however.  The new architecture is more complex.

---

Things that may be confusing:

• This architecture is always in place, even for Vault Basic and single-site installs.  It’s just easier to have 1 architecture.
• For multi-site, a client will actually be talking to two different servers.
• You log-in to the filestore server.
• Internally the WebServiceManager or Connection object asks the filestore server where the database server is located.
• File upload/download operations require communicating with both servers.  Again, the Connection object handles the details internally.
• For backward compatibility purposes, the filestore server handles all 2012 and 2013 web service calls. You need to use the 2014 API if you want the one-hop behavior.
• There are now two sets of server log files.  vlog is for database server issues and AVFS-log is for filestore issues.  Even on a single server you see these two logs.

---

The functionality is broken down by web service.  So some services are on the database server and some are on the filestore server.  There are no services that show up on both, with the exception of the Information Service.

Filestore services:

• AuthService
• FilestoreService
• FilestoreVaultService
• IdentificationService
• InformationService

Database services:

• AdminService
• BehaviorService
• CategoryService
• ChangeOrderService
• ContentService
• CustomEntityService
• DocumentService
• DocumentServiceExtensions
• ForumService
• InformationService
• ItemService
• JobService
• KnowledgeVaultService
• LifeCycleService
• PackageService
• PropertyService
• ReplicationService
• RevisionService
• SecurityService

The URLs are different too depending on which server you are talking too.  Database services are http://[server]/autodeskDM/services/v18/[service].svc while filestore services are http://[server]/autodeskDM/services/filestore/v18/[service].svc. But you shouldn’t have to care about that if you are using WebServiceManager or Connection.

Job Processor Updates in 2014

In an effort to address some long standing Job Processor issues, some major changes were made in 2014.  At the time of this writing, there are still some issues being worked on, so be sure to read the workarounds at the bottom of the post.  But let’s start with the good news.

---

All settings are in .vcet.config

In previous releases, you would have to update the XML in JobProcessor.exe.config so that it knew about your custom job types.  This was an annoying extra step in deploying you plug-in.  For Vault 2014, the .vcet.config format was overhauled (along with the loading mechanism for plug-ins) so it was a good time to slip in a feature that allowed Job Processor to read the job types directly from .vcet.config.

The new .vcet.config allows for meta-data in the form of key/value pairs.  Job processor looks for keys that start with “JobType” and associates those types with your plug-in.  You can have as many types as you want, just make sure to keep the key names unique.  Name your keys like “JobType1”, “JobType2”, “JobType3” and so on.

Example (the parts in red are what you edit in your project):

<configuration>   <connectivity.ExtensionSettings3>      <extension       interface="Autodesk.Connectivity.JobProcessor.Extensibility.IJobHandler, Autodesk.Connectivity.JobProcessor.Extensibility, Version=18.0.0.0, Culture=neutral, PublicKeyToken=aa20f34aedd220e1"       type="MyNamespace.MyClassName, MyAssemblyName">       <setting key="JobType1" value="MyJobType"/>       <setting key="JobType2" value="AnotherJobType"/>     </extension>   </connectivity.ExtensionSettings3> </configuration>

---

More command line options

You can never be rich or have too many command line options.  In 2014, you can now set username, password and server from the command line using -u, -p and -s respectively. If you are using Windows authentication, use -w.

Example:  JobProcessor.exe -u Administrator -p pwd123 -s MyVaultServer
Example:  JobProcessor.exe -w -s MyVaultServer

---

Connectivity.JobProcessor.Delegate.Host.exe

To make JobProcessor.exe more stable, all the unstable operations were moved to a different process.  All plug-ins now run in Connectivity.JobProcessor.Delegate.Host.exe, that way if a job crashes or leaks memory, the problem can be handled.  And by “handled”, I mean that JobProcessor just kills the delegate process and starts another one.  In fact, JobProcessor will periodically kill and restart the delegate just to be on the safe side.

So what does this mean for your plug-in...

• To debug, you need to attach to the running  Connectivity.JobProcessor.Delegate.Host.exe.  You can’t launch this process on your own.  If you run against JobProcessor.exe, your breakpoints won’t activate.
• If you are saving data in memory, keep in mind that the entire process may be killed and restarted.
• Only one delegate exe will be running at any given time.  And, jobs are still run single-threaded.  So you don’t have to worry about your code running in parallel with other jobs.
• The OnJobProcessorStartup and OnJobProcessorShutdown events trigger on the startup and graceful shutdown of the delegate process.  If there is a crash, there may not be a shutdown event.

---

Open issues and workarounds

Problem: AcquireFiles hangs when running inside of a job.  You may see errors like “Cannot evaluate expression because the current thread is in a sleep, wait, or join”.
Cause:  The VDF was initialized as a UI app, which is the default setting.  We are working on a fix.
Workaround:  While the fix is being worked on, you can set the VDF to non-UI mode with the below line of code.  It won’t hurt anything if multiple plug-ins call this code.  And the code won’t harm anything after the fix is released.

Autodesk.DataManagement.Client.Framework.Library.Initialize(false);

Additional Information:  Deadlock using AcquireFiles() Vault 2014

The Package Service

The Package Service is harder to describe than the rest of the Vault web services.  It was designed with one thing in mind, but ended up doing something else.  As a result, there are some artifacts left around that make it confusing to work with.  The main use nowadays is to import and export BOM data between the Item service and a file.  But there is still some active legacy behavior that you might find useful.

---

File Import/Export:

The Package Service implements the Import and Export commands for Item BOM data.  You can find sample code in the ItemEditor example in the SDK.

The biggest confusion with import/export API is that the Package Service has its own BOM objects, which act as an intermediate between the Item Service BOM and the imported/exported file.  Another point of confusion is the fact that the words "import" and "export" don't show up in any of the API functions.  

For example, to export, you call PackageService.GetItemsAndBOMsFromItemIds() to convert the Item BOM to the Package BOM.  Next you call PackageService.DownloadPackage() to convert the Package BOM into a file.

Import works pretty much the same way but in reverse.  The major difference is that the Package BOM has can detect conflicts in the import.  For example, if you try to import revision A of an item but Vault has the same item at revision B, that's a conflict.  The Package BOM allows you to see, and sometimes fix, conflicts like these before the Item BOM gets updated.

---

Legacy Behavior:

The original intent of the Package service was to be an integration point between Vault and ERP Systems.  The original name for the service was the ERPService and you can still see ERP used in a few class names.  Out of the box, Vault supported compatibility to Microsoft Great Plains.  There was an Axapta integration too, but I think it required Autodesk Consulting.  Both integrations consisted of Vault importing/exporting data to a Microsoft Message Queue (MSMQ).

The intent was to support more integrations and maybe even have a pluggable interface.  But once the Job Server feature was developed, it became the main focus for integrations.  I wouldn’t go as far to say that the Package Service is gathering dust, but I don’t expect any other systems to be added to the Package Service.  You can basically import/export to an MSMQ or a file (which is labeled as “other” in the UI).  As far as I know, the MSMQ features still work, so you can use it as an alternative to Vault job queue.

Vault Integration Pattern - Asynchronous Queue

The final entry in my Vault Integration Pattern series will focus on using Vault’s job queue for transferring data.  Like I said before, there are more integrations patterns out there, I’m just focusing on the ones that I have used first-hand.

I used this technique for the short-lived integration between Vault and PLM.  Let me just get this out of the way upfront: The integration pattern I used had nothing to do with the app being discontinued.  The long term vision changed, and the integration was caught in the middle.  From a technical standpoint, the integration pattern is sound.

---

Since PLM is in the cloud and Vault is behind a firewall, there was no easy way for PLM to have a direct view into Vault.  Data would have to be copied to PLM.  I also wanted a very reliable mechanism for data transfer, so doing it real-time in the Vault clients was not a good fit.

I went with the Vault job queue because it provides a guaranteed mechanism for the data transfer.  If it’s on the queue, I can rely on it staying on the queue until it gets properly dealt with.  If there is an error, it’s logged in the form of an error job on the queue.  If something critical goes wrong, like a power outage, the job is still on the queue in the processing state.

The downside is that the queue is asynchronous.  Even if you grab jobs directly off the queue you are still relying on polling.  There is no way to instantly know when the job is queued.  The other major disadvantage is that it runs without any user interaction.  So you can’t prompt the user for information and you can’t rely on problems getting addressed immediately.

If you are replicating data this way, I highly suggest having some kind of re-sync button.  It’s great when developing and debugging.  It’s also doubles as a bulk-load command, which is usually a requirement for integrations like this.  Lastly, it’s a magic fix-all button for a bunch of difficult error cases, such as a user deleting data manually.  These re-sync buttons tend to be slow, but that’s OK because things are asynchronous.  Also, with the job queue priority feature, you can insure that the re-sync doesn’t interfere with everyday operations.

---

To summarize...

Advantages:

• Guaranteed delivery - Jobs on the queue are guaranteed to stay there until something process them or the Vault admin removes them.
• Failure recovery - Failed jobs can be re-submitted.
• Background process - Doesn’t interfere or slow down normal operations.

Disadvantages:

• Conflicts - The same data may get updated at the same time in two different systems.
• Asynchronous - You have to wait before you can see results.
• Duplicate data - The same data is now in two different systems.

Vault Integration Pattern - Real-time Events

Welcome to part 2 of my 3-part series on Vault integration patterns.  There are many more than 3 patterns, but I’m going to stick to ones that I’ve actually used on an app or product. 

Today’s pattern is the idea that Vault communicates with the other system, in real time, whenever things change.  I used this pattern for Vault ♥ Bluestreak.  In that app, I hooked to events from Vault Explorer and Events.  This allowed the app to “listen” to what the user is doing and send out notifications to Bluestreak.  Bluestreak would then post on the notification on it’s Activity Stream, which is similar to a Facebook wall.

Maybe it will be clearer if you see the demo video (no audio):

The general idea here is that the integration app listens to events and interacts with the other system as soon as the event comes in.  Vault doesn’t have server side events, so the app has to be client-side.  In this case, the communication is one way.  I’m sending alerts to Bluestreak, but I don’t need to get any sort of response.  So the code makes heavy use of Post events.  The communication with Bluestreak is done in another thread for performance reasons.

If you have a case where you need to read data from the other system, this pattern still works.  The only difference is that you would be using the GetRestrictions or Pre events.  Multi-threading probably won’t work here since you need to halt the Vault operation while waiting for the other system to respond.

---

Advantages:

• Operations occur in real time - No need to keep hitting the refresh button, like when working with the Job Processor.
• User Interaction - If you need input from the user, you can do it.  You can also pop up errors immediately if something goes wrong.

Disadvantages:

• Events are not guaranteed - Because the operations are client-side, they occur outside the database transaction.  This means that there is a chance that the event happens, but the Post event never fires.  For example, a file changes lifecycle state, and the power goes out right before the Post event fires.  In this case, the Post even is lost forever.  Along the same lines, a Pre event may fire, but the actual operation my never get a chance to run.  So if you need 100% guarantee on your data, this is not the pattern to use.
• Client side install - If you have 100 Vault users that need to integrate with the other system, you need to install the app on 100 machines.  If an app starts failing for a user, it may not be immediately obvious.

Features across different object types

Let’s start off with a quick quiz.  Look at the image and answer the following questions:
Are the file and the folder in the same category?
Are the file and the folder in the same lifecycle state?

Answers:  No, they are in different categories, and yes, they are in the same lifecycle state.

It can be a bit confusing when you have concepts that span multiple objects types.  Sometimes you can share behavior across different types and sometimes you can’t.  In this article, I’ll attempt to explain what the scope of each feature.

Custom entities make things more tricky.  In case you don’t know already, all custom entities are part of the same entity class (CUSTENT).  When you create your own custom entity definition, it’s actually a sub-type of CUSTENT.  So that adds another level of complexity when defining scope.

---

Let me go down feature-by-feature and explain the scope...

Categories - A category is specific to an entity class.  It cannot be shared across different entity classes.  So a File and a Folder can never have the same category.  You can give set the display names the same on a File and Folder categories, like in my quiz, but they are still different underlying objects.

Categories are applied at the entity class level.  So, CUSTENT categories can be used by any of the custom entity sub-types.  So it is possible for a Foo object and a Bar object to have the same category.

Property Definitions - A property definition can span multiple entity classes.  If you go to the admin settings, you will see that it’s common for Files and Folders to share a property definition.  Categories can provide additional behavior, but it’s not required.  If a Property Definition is associated to the FILE entity class, then any file object can have that property, regardless of category.

If a property definition is associated to the CUSTENT entity class, then it’s available to all sub-types.  There is no way to have a property definition specifically for Foo objects.

Searching - A search is specific to an entity class.  This is pretty obvious at the API level since the functions are named FindXBySearchConditions, where the X is the entity class.

For custom entities, a search will span all CUSTENT objects, regardless of sub-types.  So it’s possible for a single search to return both Foo and Bar objects.  Most of the time, you don’t want this, so you need to add a search condition that narrows the search to a specific sub-type.

Lifecycle Definitions - Files, folders and custom entities all share the same lifecycle engine.  Any lifecycle definition can be used across these 3 entity types and any custom object sub-types.  The only restriction is that the entity must be in a category that is associated with the lifecycle definition.

Revision Schemes - They work similar to lifecycle definitions.  You can share them across different entity classes, but the entity must be in a category that is associated with the lifecycle definition.

Roles and Permissions - The role usually mentions the entity class directly, such as Item Editor (Level 1).  So it’s pretty clear that roles are specific to an entity class. 

For custom entities, a role applies to all custom entity sub types.  So somebody with Custom Object Editor (Level 1), can edit both “foo” and “bar” objects.  If you want the user to be able to edit “foo” but not “bar”, you need to give that user the edit role, then use ACL security to restrict edit on “bar” objects.

Custom Commands - These can be bound to a specific entity type.  In the case of custom entities, they can be bound to specific to a sub-type.  A command can work with to different types/sub-types by binding the command to multiple command sites.  Another option is to specify null for the NavigationTypes property, which has the effect of making the command always available.

Custom Tab Views - These are always bound to a specific entity type or custom entity sub-type.  You can’t share a file tab with an item tab or a “foo” tab with a “bar” tab.

---

Speaking of bar tabs, it’s payday and my shift is over.  I’ll leave you with this this handy chart, summarizing everything.

	Entity class scope	Custom entity sub-type scope
Categories	Specific to a single entity class	Always shared across all sub-types
Property Definitions	May be shared with multiple entity classes	Always shared across all sub-types
Searching	Specific to a single entity class	Always shared across all sub-types
Lifecycle Definitions	May be shared with multiple entity classes (dependent on category)	May be shared with multiple sub-types (dependent on category)
Revision Schemes	May be shared with multiple entity classes (dependent on category)	N/A
Roles and Permissions	Specific to a single entity class	Always shared across all sub-types
Custom Commands	May be shared with multiple entity classes	May be shared with multiple sub-types
Custom Tab Views	Specific to a single entity class	Specific to a single sub-type

Vault Integration Pattern - Provide a View

By far, the most common use of the Vault API is to provide some sort of integrations with something else.  Sure there are some good utilities up on the App Store, but they don’t represent the majority of the cases.  Consulting is where it’s at, and there are a surprising number of systems out there to connect Vault to.

Each integration is different, so there is no way for me to tell you everything you ever need to know.  However, there are certain patterns that emerge, and it’s the patterns that I will be focusing on.

The first pattern is the one I used when designing the SharePoint 2010 integration.  One system provides a view of data in another system.  In this case, SharePoint 2010 provides a view Vault data.

If you do it right, the end user should not know (and not care) that the data is coming from an outside system.  The SP integration does this very well.  Here is a game you can play.  Look at the following video and try to figure out what is the SharePoint data and what is the Vault data.

One cool thing about BCS, the SP feature I used for the integration, is that it doesn’t just provide a view of external data.  BCS allows you to link SharePoint data with external data.  This is a pretty useful feature for integrations like this.  If you can’t link the data between the two systems, then the integration loses a lot of value.  The end user may as well just use two separate applications.

---

I’ll end the article with some quick bullets on the advantages and disadvantages of this pattern.  If I left anything out, please let me know in the comments section.

Advantages:

• No duplication of data - Everything is just cleaner when data lives in one and only one place.  You don’t have to worry about stale data, and you don’t have to worry about conflicts

Disadvantages:

• Performance - Constantly pulling data from another source is time consuming.  No matter how much you optimize things, it will never be as fast as having the data in the same system.  For SharePoint, we found that the distance between the SP server and the Vault server was the biggest factor in how quick the Vault pages came up in SP.
• Network Dependency - If the network ever goes down between the two systems, the integration is effectively broken.  People who rely on the data will no longer be able to access it.

The BOM Pipeline

I want to explain a bit how bill of material data works in Vault.  It’s not very intuitive looking at the API.  I’ll also attempt to answer the question, “Why did they do it that way?”

The Primary Workflow

Let me know over the “primary workflow,” which I’m defining as the workflow most responsible for the architecture.  There are plenty of other valid workflows, but I’m not going to focus on them much here.

It’s best if I list out the sequence of events in the primary workflow:

1. The CAD user adds a file to Vault.
2. The CAD plug-in uploads a BOM object along with the file.  I’ll refer to this object as the “file BOM”.
3. The “file BOM” object gets stored in the database and mostly stays dormant.
4. A Vault user selects the file and runs the “Assign Item” command.
5. Internally, the “file BOM” gets read and becomes the template for creating or updating Vault Items.  In other words, the “file BOM” fills out most the information in the Assign Item wizard.
6. When the Assign Item wizard is complete, the Item objects are created and hooked together to form an “Item BOM”.  The Item BOM is what user sees and interacts with in the Item Master.
7. The “file BOM” is still around in the database, but it goes back to being dormant.  It would only be used again if there is an update to the Item BOM or a need to re-create the Item BOM.

Impact

There are some interesting consequences as a result of this workflow.

• The item structure has nothing to do with the file assembly structure.  The file BOM is the only factor.
• The file BOM is uploaded, even if the product is Vault Basic.  The idea is that the product may get upgraded to Vault Professional in the future.  If the upgrade never happens, the BOM data stays dormant forever.
• The file BOM is not static data.  It may get altered by the server.  For example, data gets “filled in” during an Assign Item operation.  This way things are optimized if the Items ever need to be updated.
• Results from GetBOMByFileId are not guaranteed to be the same, even when called on the same file version. See previous bullet.
• GetBOMByFileId is not actually used anywhere in the process.  It’s an API-only feature intended for testing and troubleshooting purposes.  And yes, I’m well aware that many people are using this function beyond it’s intended scope.

File BOM vs. Item BOM

Here is a quick rundown of the two different BOM representations.

	File BOM	Item BOM
Purpose	A template for the Item BOM	Represent an accurate Bill of Materials
Visible to end user	No	Yes
File scope	Attached to 1 and only 1 file.	Can be associated with 0 to many files.
Can be directly edited	No	Yes

Finding by Search Conditions

It recently came to my attention that there are no articles on using the Find X By Search Conditions.  So let my fix that now.  These Find functions are the API equivalent of the Advanced Find command in the UI.  Hopefully you are familiar with the following dialog.

The basic idea is that you construct your search criteria by chaining together a bunch of search conditions.  The result set consists of all the entities that match the search conditions.

The results are returned in pages for performance reasons.  By default 100 is the page size, but that value can be changed in ADMS Console.  You can also define sort criteria, so that the results come back in a specific order.  That way you can hopefully get what you want on the first page.

Each major entity type has it’s own set of Find by Search Conditions functions, but they all work basically the same.  I will be focusing mainly on FindFilesBySearchConditions for this article.

---

Sample code
I’ll start by showing the code, then explaining what is going on.

// C# PropDef [] filePropDefs = m_svcMgr.PropertyService.GetPropertyDefinitionsByEntityClassId("FILE"); PropDef checkedOutPropDef = filePropDefs.Single(n => n.SysName == "CheckoutUserName"); PropDef projectPropDef = filePropDefs.Single(n => n.SysName == "Project");   SrchCond isCheckedOut = new SrchCond() {     PropDefId = checkedOutPropDef.Id,     PropTyp = PropertySearchType.SingleProperty,     SrchOper = 5, // is not empty     SrchRule = SearchRuleType.Must, };   SrchCond padlockProject = new SrchCond() {     PropDefId = projectPropDef.Id,     PropTyp = PropertySearchType.SingleProperty,     SrchOper = 3, // is equal     SrchRule = SearchRuleType.Must,     SrchTxt = "Padlock" };   string bookmark = string.Empty; SrchStatus status = null; List<File> totalResults = new List<File>(); while (status == null || totalResults.Count < status.TotalHits) {     File [] results = m_svcMgr.DocumentService.FindFilesBySearchConditions(         new SrchCond[] { isCheckedOut, padlockProject },         null, null, false, true, ref bookmark, out status);       if (results != null)         totalResults.AddRange(results);     else         break; } // total results now has the results

' VB.NET Dim filePropDefs As PropDef() = _     m_svcMgr.PropertyService.GetPropertyDefinitionsByEntityClassId("FILE") Dim checkedOutPropDef As PropDef = _     filePropDefs.[Single](Function(n) n.SysName = "CheckoutUserName") Dim projectPropDef As PropDef = _     filePropDefs.[Single](Function(n) n.SysName = "Project")   ' SrchOper 5 => is not empty Dim isCheckedOut As New SrchCond() With { _        .PropDefId = checkedOutPropDef.Id, _        .PropTyp = PropertySearchType.SingleProperty, _        .SrchOper = 5, _         .SrchRule = SearchRuleType.Must _ }   ' SrchOper 3 => equals Dim padlockProject As New SrchCond() With { _        .PropDefId = projectPropDef.Id, _        .PropTyp = PropertySearchType.SingleProperty, _        .SrchOper = 3, _        .SrchRule = SearchRuleType.Must, _        .SrchTxt = "Padlock" _ }   Dim bookmark As String = String.Empty Dim status As SrchStatus = Nothing Dim totalResults As New List(Of File)() While status Is Nothing OrElse totalResults.Count < status.TotalHits        Dim results As File() = _           m_svcMgr.DocumentService.FindFilesBySearchConditions( _            New SrchCond() {isCheckedOut, padlockProject}, _            Nothing, Nothing, False, True, bookmark, _               status)          If results IsNot Nothing Then               totalResults.AddRange(results)        Else               Exit While        End If End While ' total results now has the results

The code is running the same search from the screenshot at the top of the article.  In this case, I want to gather all results, even if it’s bigger than the page size.  I put the Find call in a while loop so that I can keep going, page by page, until I get all the results.

---

Search Conditions 
The SrchCond objects are the main building blocks of your search.  Each object defines a single condition in the search.  A condition consists of a property, a condition and a value.  For example, “Author is Doug” or “CreateDate is less than 6/31/2011”.  Value may not be used in some cases depending on the condition.  For example, “Checked Out By is not empty”. 

The PropTyp property basically determines if this is an advanced search or a basic search.  “SingleProperty” means advanced search because the value only relates to a single property.  “AllProperties” and “AllPropertiesAndContent” both refer to the basic search feature where a single value is compared against all properties.

SrchOper defines the comparison operator, such as “equals” or “less than”.  It’s a number, and the SDK documentation has a table of all the legal values.

Search Rule is something I covered in another article, so I won’t go over it here.  The advanced find command in the Vault client always uses Must, which means there is an AND relationship between the conditions.

---

FindFilesBySearchConditions
Here is the function itself.  I won’t be going over every parameter, but I will make sure to cover the tricky ones.

File[] FindFilesBySearchConditions(
   SrchCond[] conditions,
   SrchSort[] sortConditions,
   long[] folderIds,
   bool recurseFolders,
   bool latestOnly,
   ref System.string bookmark,
   out SrchStatus searchstatus
)

The first parameter is the array of search conditions.  You can pass in an empty array, which results in all Files being returned.  It’s actually the most efficient way to scan through all the files in the Vault.

Next is the array of sort objects.  You can pass in null if you don’t care about the order.  If you do want a sort, the SrchSort class is pretty straightforward.  It’s a Vault property you want to sort on, and you can have it be ascending or descending.  The input is an array so that you can sort across multiple properties.  The first object in the array is a primary sort, the second object is the secondary sort, and so on.

FolderIds is for cases where you want to search in a specific set of folders.  If you want to search the whole Vault, pass in null.  Passing in the root folder may slow performance.

Bookmark is for when you need multiple pages returned.  The first time you call Find, you pass in an empty string for the bookmark.  If you don’t get all the results in the first call, bookmark will get updated.  You can then use the bookmark for the next call and it will continue the search from where the last search left off.

Search Status lets you know how many total results there are.  It also lets you know if a re-index is going on.  In the event of a re-index, your results may not be 100% accurate.  There is not much you can do in this case aside from warning the user.