Last year, I tried to explain the Entity concept in the Vault API, and I never felt that I did a good job. Read the article at your own peril. In true software developer form, here is the hotfix to my bug-filled earlier article.
There are 2 concepts in the Vault API: Entities and Behaviors. The two concepts are intertwined; you can't describe one without describing the other.
An Entity is an object that can have behaviors on it.
A Behavior is a feature that can be applied to entities.
The driver behind these concepts is something every programmer should already be familiar with: re-use. By having features that can work with multiple object types, Vault has less code, a cleaner API, greater stability, and so on.
Files and Folders are examples of entities. Properties and Categories are examples of behaviors. Not every object in Vault is an entity, and not every feature is a behavior. It's also important to know that a given entity type may not support every behavior.
For example, here is a table explaining which entities have which behaviors in Vault Professional 2012.
| Property | Revision | Category | Security (ACL) |
Lifecycle | Ownership (replication) |
|
| Files | * | * | * | * | * | * |
| Folders | * | * | * | * | ||
| Items | * | * | * | * | * | |
| Change Orders | * | * | ||||
| Forum Message | * | |||||
| Reference Designator |
* |
Note: Even though Items and Change Orders have lifecycles, the feature cannot be applied to other entity types. The File lifecycle engine is the only one that is entity-based.
The web services in the API is structured according to the entity/behavior model as shown in the table below.
| Entity Services | Behavior Services | Other |
|
|
|
The behavior services are easiest to spot because the functions have parameters like "entityId" and "entityClassId". In the entity-based services, the functions usually take more specific IDs, such as "fileId". Let's focus more on the terminology used in the behavior services.
EntityId - Each entity has an ID that uniquely identifies it. Usually this is the "Id" property on the object. For example: File.Id
EntityMasterId - If the entity can be versioned, then there is a master ID, which is used to refer to the entire collection of versions. Usually this is the "MasterId" property on the object. For example: File.MasterId
If a function is asking for an EntityMasterId, but the object doesn't have one, just pass in the ID value. For example: Folder.Id
EntityClassId - This is a string value containing the type name. Call AdminService.GetServerConfiguration() to see the list of legal values. For your convenience, I will list them out here.
| Entity type | EntityClassId value |
| File | FILE |
| Folder | FLDR |
| Item | ITEM |
| Change Order | CO |
| Reference Designator | ITEMRDES |
| Forum Message | FRMMSG |
Subscribe