This scenario should be familiar if you have used the Vault API. Your code relies on a specific configuration which you need to look up in your code. For example, you have a UDP and your code needs to look up the ProdDef object. How do you do it? What piece of information do you use?
Let’s start with the completely wrong answer. The ID value should not be used. It’s not consistent between Vaults, you don’t know the value ahead of time, and the value may change when you migrate to the next Vault release.
The Display Name is usable in certain cases, but is not bullet proof. The main problem is that the display name can be changed through the Vault settings. If your app is specific to a single Vault installation, then you can sometimes get away with this approach. If you are developing something for a mass market, then you can’t depend on the display name.
System Name is the most solid thing to use. Once this value is set, it can’t be changed. The Vault admins can change the display name all they want, the system name will not change.
In Vault 2012 and earlier, the server would create the system name for you using a randomly generated GUID. So there is no way you could know that value when you are writing your code.
In Vault 2013, we updated most of the Add functions so that you pass in the system name. This way, you can know ahead of time what the system name is. You can store that value in you code and be secure in the knowledge that it will locate the correct object.
When calling an Add function, you can’t set the system name to be whatever you want. It must be a GUID in the format (lower case) xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. If you have a .Net Guid object, you can just call ToString(“D”) to get that string. Even though your system name will not be human readable, but it will be reliable. And you are safe from naming collisions (as long as people don’t just cut and paste code from the sample apps on your blog).
Another caveat to this architecture is that you need to add the object through the API. If you do it through the UI, then the client will give it a random system name.