Entities

Update:  This article has been re-written for Vault 2012. In my opinion, the new article does a better job of explaining the major concepts.

In the Vault 2011 API, many of the features are driven by an Entity concept.  In fact, entire services use Entities as their common currency.  Specifically the Behavior, Category, Property, Replication, Revision and Security services.  So what are Entities?  How do you use them?

The closest analogy I can come up with is the Object base class in .NET.  It's kind of like a top-level base class which can be used to manipulated objects in an abstract way. 

For Vault, this means that there can be a single function that operates on multiple object types.  In earlier versions of Vault, separate functions had to be created for each item type.

For example, in Vault 2010, there are 5 functions for looking up property values:
   PropInst [] DocumentService.GetProperties (Long [] fileIds, Long [] propertyDefinitionIds)
   PropInst [] ItemService.GetItemProperties (Long [] itemIds, Long [] propertyDefIDs)
   PropInst [] ItemService.GetReferenceDesignatorProperties (Long [] itemRefDesIds, Long [] propertyDefIDs)
   PropInst [] ChangeOrderService.GetChangeOrderProperties (Long [] changeOrderIds, Long [] propertyListIds)
   PropInst [] ForumService.GetMessageProperties (Long [] messageIds, Long [] propertyListIds)

In Vault 2011, the same functionality is contained in a single function:
   PropInst [] PropertyService.GetProperties (String entityClassId, Long [] entityIds, Long [] propertyDefIds)

Not everything is an Entity
Most of the major objects are Entities, such as Files and Folders.  But some things are not, like Users and Groups.  I don't want to go into why some things are Entities and some things are not.  That explanation would require me to go deep into the database architecture.  The general rule is to assume that everything is not an Entity unless explicitly stated.

Some objects contain multiple Entities
A File object actually has 2 Entities contained inside it.  The "File Version" Entity and the "File Master" Entity.  These are uniquely identified by the Id and MasterId properties respectively.  The function parameter will usually tell you which ID to pass in.
For Item objects, there are 3 Entities:  Item Version, Item Revision and Item Master.

The list of Entities
Here is the list of Entities that are in use for the Vault 2011 API:

• File Version
• File Master
• Folder
• Item Version
• Item Revision
• Item Master
• Reference Designator
• Change Order
• Forum Message

Internal to the database, there are more Entity types, but they can't be used as Entities at the API level.

Functions do not support all Entity types
Just because a function takes an EntityId doesn't mean the function will work with all Entity types.  For example, if you pass in a Folder.Id to GetProperites, it will fail because Vault does not support properties on Folders. 
So there is some burden on the programmer to know which functions work on which Entity types.  Knowledge of the Vault product itself should be sufficient to deduce this information.

Entity IDs are unique across a given Vault
All Entity ID values are taken from the same numbering system.  For example, if you have a Folder with an ID of 5, there will be no Files with an ID of 5 for the Vault.

API terms
EntityId – This is the ID value of the Entity.  Usually this is the 'Id' property on the object.  If there are multiple Entities in the object, then pass in the one that relates to a specific version (ex.  File.Id or Folder.Id)
EntityMasterId – This is the ID value that matches to the master concept, which refers to all versions of the object (ex.  File.MasterId).  If the object isn't a type that is versioned, just pass in the regular 'Id' property (ex. Folder.Id).
EntityClassId – This is a string value that tells what type of object to work with.  Some functions require this information and some do not.  Call AdminService.GetServerConfiguration() to see the list of legal values. 
NOTE:  Folder is noticeably absent from the list.  The reason is that there are are no functions that require an EntityClassId of "FOLDER".