IRPCValueLists.GetLookupItems
Vault API / core read session or assertion idempotent returns metadata structure version
Gets the selectable items of one or more value lists or object types in one call, for example to fill lookup controls.
| Service | Value lists MFiles.IRPCValueLists |
|---|---|
| gRPC method | /MFiles.IRPCValueLists/GetLookupItems |
| HTTP (mf-http-grpc) | POST /grpc/v1/get-lookup-items |
| Request | GetLookupItemsRequest |
| Response | GetLookupItemsResponse |
| Book and level | Vault API, core |
| Kind | read |
| Session | Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata). |
| Idempotent | yes |
| Returns metadata structure version | yes (in the mfiles-metadata-version-bin trailer) |
| Streaming | none (unary) |
Remarks
- Requires a vault session. No special vault rights are needed; items the user is not allowed to see are left out.
- One LookupItemRequest per list. The response has one LookupItemResponse per request, in request order; identical requests are run once and their result copied.
- Deleted items are left out unless a request has the condition Deleted (5) equal to true, in which case only deleted items are returned. This differs from SearchValueListItemsWithPermissions.
- Set
LookupItemRequest.property_defto the lookup property being edited to apply that property's value filter (PropertyDef.value_list_item_filter); use -1 for no filter. results_limitunset or 0 returns all matching items. When a list has more items than the limit,has_more_resultsis true; narrow the search with a name condition instead of paging (there is no offset).- In hierarchical lists, the parents of matching items are returned too, so a response can
contain more items than
results_limit. - The order of the items is not specified; sort on the client.
- If any request names an unknown list, the whole call fails with "Not found.".
- For external lists,
external_data_source_refreshcan refresh the list from its external database before the read. Not cacheable: item lists change without a metadata structure version change. - Related: GetValueListItemProposals for the user's recently used values.
Request: GetLookupItemsRequest
Request for getting lookup items of multiple object types or value lists (lookup types).
Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
requests[] | repeated LookupItemRequest | One request per value list or object type. See LookupItemRequest. |
requests[].external_data_source_refresh | ExtDBRefreshType | For a list connected to an external database: whether to refresh it from the database before the read. EXT_DBREFRESH_TYPE_NONE reads the items the vault already has.Values: EXT_DBREFRESH_TYPE_NONE (0), EXT_DBREFRESH_TYPE_QUICK (1), EXT_DBREFRESH_TYPE_FULL (2). |
requests[].value_list_id | int32 | The ID of the value list or object type whose items are wanted. |
requests[].property_def | int32 | The ID of the lookup property being edited, to apply its value filter (PropertyDef.value_list_item_filter), or -1 for no filter. Set -1 explicitly: the default 0 is a real property definition ID (Name or title). |
requests[].search_conditions[] | repeated SearchCondition | Item conditions, combined with AND, on the item pseudo properties 1-8 (for example 2 = name); see the IRPCValueLists overview. Deleted items are left out unless the condition Deleted (5) equal to true is given. |
requests[].search_conditions[].expression | Expression | The left side of the condition: what is evaluated for each object, such as a property value, a status value or any field (full-text search). |
requests[].search_conditions[].type | ConditionType | The comparison operator. |
requests[].search_conditions[].value | TypedValue | The right side of the condition: the value to compare with. Its data type must suit the expression, for example a lookup for a lookup property, Boolean for STATUS_TYPE_IS_DELETED. |
requests[].results_limit | optional uint32 | The maximum number of items to return. Unset or 0 returns all. |
resolve_current_user_placeholders | bool | True to replace the "current user" entry in each item's automatic permissions with the caller's own user ID. |
include_permissions | bool | True to fill acl and current_user_permissions of each returned item. Leave false if you need only IDs and names. |
timeout_in_seconds | uint32 | 0 for no timeout. Otherwise the server checks the elapsed time between the steps of the call and fails it with a timeout error once the limit has passed. |
Response: GetLookupItemsResponse
Search multiple object type items response.
Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.
| Field | Type | Description |
|---|---|---|
lookup_item_results[] | repeated LookupItemResponse | One result per request, in the order of requests. |
lookup_item_results[].value_list_id | int32 | The value_list_id of the request. |
lookup_item_results[].items[] | repeated ValueListItemData | The matching items, with permissions if the request had include_permissions. In hierarchical lists the parents of matching items are included. |
lookup_item_results[].items[].item | ValueListItem | The item. See ValueListItem. |
lookup_item_results[].items[].acl | AccessControlList | The access control list of the item. Set only when the request had include_permissions. |
lookup_item_results[].items[].current_user_permissions | ObjectPermissionsForClient | What the caller may do with the item. Set only when the request had include_permissions. |
lookup_item_results[].has_more_results | bool | True if more items matched than results_limit allowed. |
Related methods
- SearchValueListItemsWithPermissions -- Searches the items of one value list or object type by item ID, name, owner, parent or deleted state.
- GetValueListItemProposals -- Gets the values that the calling user has most recently used for a lookup property.