Storing Custom Data: Vault Options

You are writing a Vault application, and you have data that doesn't fit nicely into a Vault object.  Your data is not a File Property, or a Change Order, or a Folder, and so on.  Your data is something else, and you need to store it somewhere.

Welcome to Storing Custom Data, which will be an ongoing series on this blog.  Storing your custom data is a common problem.  There are many solutions, each with their own pros and cons.  In each article in the series, I will explore a different way to persist the custom data in your Vault application.

Vault Options
In this article, I will be talking about the "Vault Options" concept.  In a nutshell, a Vault Option is a name/value string pair that your program can read or write to.  I like to think of it as the Vault equivalent of the Windows registry. 

There is a companion concept called a "System Option".  The only difference is that a Vault Option is specific to a Vault and a System Option is valid across all Vaults in a given system.

The maximum length for an option name is 50 characters.  However the value is limited only by the HTTP max request length (50 MB is the default value for Vault).  So you can get pretty creative here, as I will illustrate in an example below.

Options can be set only by a user with administrative privileges.  However all users can read an option. So this technique is ideal for administrative settings, but doesn't work so well for user settings.

API functions
You can only get or set options data through the Web Service API.  It's one of the few API features that doesn't map to a client UI command.  There are 4 relevant functions and they are all in the Knowledge Vault Service:  GetVaultOption, SetVaultOption, GetSystemOption and SetSystemOption.

To create an option, you set it using a name that doesn't already exist.  The common naming convention is to use your company name as a prefix.  To delete an option, you just set the value to null. 

Any application can read any option value, however the application needs to know the exact option name.  There is currently no way to browse options.  So if your app stores data here, it's fairly safe from tampering.  When you create an option, you need to remember the name.  It's good form to delete an option when you are done using it, but it's usually hard to tell when this time is.  As a result, several unused options may get accumulated in the Vault as time goes on, just like with the Windows registry.

Example
Effective Folder Permissions 2.0 has an example of this technique.  In that application, there is a settings dialog, where the administrator can set up which folders to view in the Permissions Overview.  When the admin clicks OK, the settings are serialized as XML data and stored as a Vault option.  So all the settings are contained in a single option.  This approach works well for this application.  Not only is it easy to code, but it allows me to easily add or remove settings in the future. 

This example is illustrated in Settings.cs from Effective Folder Permissions 2.0.  The Settings class not only stores the settings data, but it can serialize/deserialize itself to XML and save/load itself from the Vault option.