Value lists (IRPCValueLists)
Reads value lists and their items, and lets users add and edit value list items and traditional folders.
| gRPC service | MFiles.IRPCValueLists |
|---|---|
| Book and level | Vault API, core |
| Methods | 17 |
| Proto file | mfiles/IRPCValueLists.proto |
Overview
Use it to fill lookup controls and to read or maintain the items of value lists. The service is not read-only: the remarks of its write methods list the vault rights they need. For how value lists relate to object types, classes and properties, see Vault and metadata structure; for keeping a cached list current, see Metadata structure version and caching.
- List the value lists (and object types) of the vault: GetValueLists, GetValueList.
- Candidate values for lookup properties (lookup control, autocomplete), several lists per call: GetLookupItems.
- Find items of one list by name, ID, owner, parent or deleted state: SearchValueListItemsWithPermissions.
- Keep a local copy of a list up to date with deltas: GetValueListItemsWithPermissions.
- The user's recently used values of a lookup property: GetValueListItemProposals.
- Add, update or undelete an item: AddValueListItemFromClient, UpdateValueListItemFromClient, UndeleteValueListItem.
- Traditional folders: CreateOrFindTraditionalFolder, RenameValueListItemFromClient, RemoveValueListItemFromClient, RemoveOrDestroyTraditionalFolder, ChangeValueListItemPermissionsFromClient.
- Permissions of an item: GetValueListItemPermissions, CheckAccessToValueListItem.
IDs. Value lists and object types share one ID space: an object type is a value list whose
items are objects (ValueList.is_real_object_type). The item calls accept both, so
GetLookupItems returns customers for object type
136 just as it returns countries for value list 154. An item is identified by an
ObjID: type is the value list ID and item_id.internal_id the item
ID. Item IDs are unique only within one list. Lookup property values
(PropertyDef with is_based_on_value_list) point to items of
PropertyDef.value_list. Built-in lists keep their IDs in every vault, for example 1 Classes,
2 Class groups, 4 Traditional folders, 6 Users, 7 Workflows, 8 Workflow states, 16 User groups.
Item search conditions. The search_conditions of the item searches are
SearchConditions whose expression is a property value
(EXPRESSION_TYPE_PROPERTY_VALUE) on one of these pseudo property definition IDs. They exist
only in item searches; ordinary property definitions are rejected with "Invalid search
condition.". Conditions are combined with AND.
| ID | Item field | Value (TypedValue) |
Example condition type |
|---|---|---|---|
| 1 | Item ID | DATATYPE_INTEGER |
CONDITION_TYPE_EQUAL |
| 2 | Name | DATATYPE_TEXT |
CONDITION_TYPE_CONTAINS, CONDITION_TYPE_STARTS_WITH (case-insensitive) |
| 3 | Owner item | DATATYPE_LOOKUP (lookup.value_list_item_info.obj_id = owner item) |
CONDITION_TYPE_EQUAL |
| 4 | Parent item | DATATYPE_INTEGER, or unset for top-level items |
CONDITION_TYPE_EQUAL |
| 5 | Deleted | DATATYPE_BOOLEAN |
CONDITION_TYPE_EQUAL |
| 6 | Object type | DATATYPE_INTEGER |
CONDITION_TYPE_EQUAL |
| 7 | External (display) ID | DATATYPE_TEXT |
CONDITION_TYPE_EQUAL |
| 8 | GUID | DATATYPE_TEXT (with braces) |
CONDITION_TYPE_EQUAL |
To search objects by their properties, use SearchObjects
instead. Item lists are not covered by the metadata structure version: adding or changing items does not
change the mfiles-metadata-version-bin trailer, so do not cache items by it.
Highlighted methods
| Method | Summary | Facts |
|---|---|---|
| GetValueLists | Gets all value lists of the vault, including the object types, without icons. | read session or assertion idempotent returns metadata structure version |
| GetValueList | Gets one value list or object type by ID, without its icon. | write session or assertion returns metadata structure version |
| GetLookupItems | Gets the selectable items of one or more value lists or object types in one call, for example to fill lookup controls. | read session or assertion idempotent returns metadata structure version |
| SearchValueListItemsWithPermissions | Searches the items of one value list or object type by item ID, name, owner, parent or deleted state. | read session or assertion idempotent returns metadata structure version |
| AddValueListItemFromClient | Adds a new item to a value list, as a user. | write session or assertion returns metadata structure version |
Other methods
| Method | Summary | Facts |
|---|---|---|
| ChangeValueListItemPermissionsFromClient | Changes the permissions of a traditional folder. | write session or assertion idempotent returns metadata structure version |
| CheckAccessToValueListItem | Checks whether the calling user has the given access under an access control list that the caller supplies. | read session or assertion idempotent returns metadata structure version |
| CreateFolderTree | Creates a tree of traditional folders under one anchor in one transaction: either every folder is created or the call fails and nothing is saved. | write session or assertion returns metadata structure version |
| CreateOrFindTraditionalFolder | Creates a traditional folder, or returns an existing folder with the same name. | write session or assertion returns metadata structure version |
| GetValueListItemPermissions | Gets the permissions of one item of a plain value list. | read session or assertion idempotent returns metadata structure version |
| GetValueListItemProposals | Gets the values that the calling user has most recently used for a lookup property. | read session or assertion idempotent returns metadata structure version |
| GetValueListItemsWithPermissions | Gets the items of one value list or object type, or only the changes since a known version. | read session or assertion idempotent returns metadata structure version |
| RemoveOrDestroyTraditionalFolder | Deletes or destroys a traditional folder and everything in it. | write session or assertion returns metadata structure version |
| RemoveValueListItemFromClient | Deletes a traditional folder (marks it deleted). | write session or assertion returns metadata structure version |
| RenameValueListItemFromClient | Renames a traditional folder. | write session or assertion idempotent returns metadata structure version |
| UndeleteValueListItem | Restores a deleted item of a plain value list, together with its deleted parent items. | write session or assertion |
| UpdateValueListItemFromClient | Updates an item of a plain value list or a traditional folder, as a user. | write session or assertion returns metadata structure version |