Persistent IDs

If you are integrating Vault and another system, you will probably want to use Persistent IDs.   Like the name implies, these identifiers are persisted and will not change in the future. 

Persistent IDs came out in Vault 2013 as an undocumented feature.  For Vault 2014, it’s now being officially supported.  Before Vault 2013, there was no guaranteed way to store a reference to an entity.

Non Persistent IDs

Let me give you some examples of non-persistent IDs to illustrate why a new feature was needed.

File Name – Files can be renamed.
Property Values – The values can be changed in new releases.  Old releases can be purged.
File ID and MasterID – These are the database keys, which may need to change if the database gets re-designed.  This did actually occur during the Vault 3 -> 4 migration.  That was 8 releases ago, but it could happen again.

API Usage

The Persistent ID feature is handled by 2 functions in the KnowledgeVaultService: GetPersistentIds and ResolvePersistentIds.

GetPersistentIds gives you the PersistentIds for a set of entities.  There are two types of IDs you can get: History and Latest.  History gives you an ID to a specific version of an entity.  Latest gives you a version independent ID, which is basically a persistent Master ID.  If an entity is not versioned, then either type gives you the same result.

Be careful when using History.  If you have an ID to a version that gets purged, then that ID will not be able to get resolved. 

ResolvePersistentIds takes a set of Persistent IDs and gives you back the entity IDs and types.  If the Persistent ID is a Latest type, then you get back the latest version of the entity.  A History type results in a specific version of an entity being returned.

Other Details

• Persistent IDs only work for entities, which are Files, Folders, Items, Change Orders and Custom Objects.
• Persistent IDs are unique for a given Vault, but not across multiple Vaults.
• Some non-entity classes, such as Property Definitions and Categories, use a System Name as a non-changing identifier.
  • System Names are persistent in the sense that they cannot be changed by a user and will not change in future releases.  So you can safely store these outside of Vault.
  • System Names are not compatible with the GetPersistentIds and ResolvePersistentIds functions.