IRPCSearch.GetFolderContents
Vault API / core read session or assertion idempotent returns metadata structure version
Lists the contents of a view or a view level: subviews, grouping folders and objects.
| Service | Search MFiles.IRPCSearch |
|---|---|
| gRPC method | /MFiles.IRPCSearch/GetFolderContents |
| HTTP (mf-http-grpc) | POST /grpc/v1/get-folder-contents |
| Request | GetFolderContentsRequest |
| Response | GetFolderContentsResponse |
| 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
This is how the M-Files clients browse views. path is the folder location from the vault root:
- An empty
pathlists the root:view_foldersholds the views the caller can see. - Append a
FOLDER_TYPE_VIEW_FOLDERfolder with a view ID to list that view. A view can contain subviews (view_folders), grouping levels (property_folders), objects, or a mix. A view nested in another view can also be listed without its parent view inpath. - To open a grouping folder, append a
FOLDER_TYPE_PROPERTY_FOLDERfolder whosetyped_valueis the TypedValue returned inproperty_folders, unchanged.
Results are filtered by the caller's permissions. To find objects by conditions, use SearchObjects instead.
Request: GetFolderContentsRequest
A request structure for GetFolderContents RPC call. It contains all request data.
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 |
|---|---|---|
call_importance | CallImportance | The importance level of this call. Typically CALL_IMPORTANCE_NORMAL.Values: CALL_IMPORTANCE_DEFAULT (0), CALL_IMPORTANCE_NORMAL (1), CALL_IMPORTANCE_CAN_BE_REJECTED (2). |
target | SearchTarget | Search options. |
target.index | string | The name of the search index to use. Empty uses the vault's default index. An unknown name fails with "Target index is not available." |
target.mode | SearchMode | Whether to prefer, require or avoid the full-text search engine. See SearchMode.Values: SEARCH_MODE_DEFAULT (0), SEARCH_MODE_FAVOR_FULL_TEXT_SEARCH (1), SEARCH_MODE_REQUIRE_FULL_TEXT_SEARCH (2), SEARCH_MODE_REQUIRE_DATABASE_SEARCH (3). |
target.search_master_storage | bool | True to also search objects kept in Master Storage, where the vault supports it. |
target.continuation_token | string | Continuation token for paging results from Master Storage. SearchObjects does not support it and fails with "Continuation token is not supported." when it is set together with search_master_storage. |
path[] | repeated Folder | The folder location from the vault root, one Folder per level. Empty lists the vault root. |
path[].type | FolderType | The type of the folder, for example FOLDER_TYPE_VIEW_FOLDER or FOLDER_TYPE_PROPERTY_FOLDER.Values: FOLDER_TYPE_UNKNOWN (0), FOLDER_TYPE_ANY_FOLDER (1), FOLDER_TYPE_VIEW_FOLDER (2), FOLDER_TYPE_PROPERTY_FOLDER (3), FOLDER_TYPE_TRADITIONAL_FOLDER (4), FOLDER_TYPE_SEARCH_FOLDER (5), FOLDER_TYPE_EXTERNAL_VIEW_FOLDER (6). |
path[].data | FolderInfoUnion | Additional folder type -specific information as a union. |
path[].data.any_folder | FolderInfoUnion.AnyFolderData (oneof data) | Any folder type. |
path[].data.view_folder | FolderInfoUnion.ViewFolderData (oneof data) | View folder type. |
path[].data.property_folder | FolderInfoUnion.PropertyFolderData (oneof data) | Property (virtual) folder type. |
path[].data.traditional_folder | FolderInfoUnion.TraditionalFolderData (oneof data) | Traditional folder type. |
path[].data.search_folder | FolderInfoUnion.SearchFolderData (oneof data) | Search folder (extended view folder) type. |
path[].data.external_view_folder | FolderInfoUnion.ExternalViewFolderData (oneof data) | External view folder type. |
page_requests[] | repeated SearchResultsPageRequest | If not empty, specifies search results page requests. |
page_requests[].object_type | int32 | The identifier of a search results group. |
page_requests[].page | int32 | The zero-based index of a page. |
page_requests[].options | SRPREQUESTFLAGS | Search results page request flags. |
page_requests[].options.all | bool | Specifies all flags set; Including any future flags. |
page_requests[].options.unseen_page | bool | If available, the page request is for an unseen page. |
page_requests[].options.ignore_original_conditions | bool | If available, the original conditions are ignored. This can be used when including ObjIDs. Do not use with SRPREQUEST_UNSEENPAGE. |
page_requests[].options.seen_page | bool | If available, the page request is for an already seen page. |
page_requests[].options.initial_page | bool | If available, the page request is initial and for an unseen page. Do not use with SRPREQUEST_SEENPAGE. |
page_requests[].seen_objects[] | repeated ObjID | An array of ObjIDs. If the SRPREQUEST_UNSEENPAGE flag is available, these are ObjIDs to exclude. If the SRPREQUEST_SEENPAGE flag is available, these are ObjIDs to include. |
page_requests[].seen_objects[].type | int32 | The object type ID, for example 0 for documents. In a lookup value, the value list ID (for a lookup to objects, the object type ID). |
page_requests[].seen_objects[].item_id | ItemID | The ID of the object within its type, in item_id.internal_id. |
limit | uint32 | The maximum number of objects to return; 0 leaves the limit to the server. has_more_objects tells whether more objects exist. |
facet_filter | StringValue | If set, specifies the additional facet search filter. |
facet_filter.value | string | String. |
sorting | SearchResultsSorting | If not empty, specifies how search results are being sorted. |
sorting.rules | SortRuleValueArray | The sort rule. Exactly one rule is supported; more than one cannot be sorted. |
sorting.rules.values[] | repeated SortRule | Sort rules. The first rule has the highest presedence meaning that it is the primary sort rule. |
sorting.options | SortFlags | Sort flags. Set allow_resorting_to_default_sort to get relevance order instead of an error when the rule cannot be applied. |
sorting.options.all | bool | Specifies all flags set; Including any future flags. |
sorting.options.allow_resorting_to_default_sort | bool | Allows resorting to default sorting if the specified sorting is not supported. If this flag is not present, an unsupported sort request causes an error. |
include_selected_folders | bool | True to also return the user's selected folders of the level in selectedPropertyFolders. Ignored when the folder selection is not available. If the selected folders cannot be listed, for example because the search times out, the whole call fails; retry without includeSelectedFolders. |
selected_folders_only | bool | With includeSelectedFolders, true to skip the normal property folder listing. Ignored without includeSelectedFolders. |
Response: GetFolderContentsResponse
A response structure for GetFolderContents RPC call. It contains all response data.
Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page. Fields marked (recursive) refer to a type already on their path.
| Field | Type | Description |
|---|---|---|
view_folders[] | repeated View | Resulting views array. |
view_folders[].id | int32 | The ID of the view. |
view_folders[].type | ViewType | The type of the view.Values: VIEW_TYPE_SHOW_OBJECTS (0), VIEW_TYPE_FILTER_ONLY (1). |
view_folders[].name | string | The name of the view. |
view_folders[].is_common | bool | Tells if the view is admin-defined (common) or user-defined. |
view_folders[].is_visible | bool | Tells if the view is visible. |
view_folders[].location | ViewLocation | The location of the view. Valid only if bHasParent is true. |
view_folders[].location.parent_folder[] | repeated Folder | Array of folders describing the parent folder of the view. The first element of the array must be a view folder. Other elements, if any, are property folders. |
view_folders[].location.customizes_property_folder | bool | True if the view is overlapping with a property folder. |
view_folders[].location.customized_property_folder | TypedValue | The overlapped property folder. Ignored if bOverlapping is false. |
view_folders[].content_definition | SearchDef | The search definition that contains the view levels and search conditions of the view. |
view_folders[].content_definition.filter_conditions[] | repeated SearchCondition | The conditions that limit the object set of this search. |
view_folders[].content_definition.grouping_levels[] | repeated GroupingLevel | View levels (the display hierarchy of this search). |
view_folders[].content_definition.options | SearchFlags | Search flags. This affects the resulting object version set and also distinct view level values displayed inside this search. |
view_folders[].acl | AccessControlList | Permissions. |
view_folders[].acl.checked_out_to_user | int32 | Specifies the ID of the user who has extended rights because of the checkout operation performed by her. 0 if such user does not exist. |
view_folders[].acl.is_fully_authoritative | bool | Specifies whether this access control list is set to ignore the secondary permissions that come from the latest checked in version. |
view_folders[].acl.custom_component | AccessControlListComponent | Accesses the custom component of this ACL. |
view_folders[].acl.restrictive_components[] | repeated AccessControlListComponentMapEntry | Accesses the restrictive automatic components of this ACL. |
view_folders[].acl.secondary_access_control_list | AccessControlList (recursive) | Secondary ACL used for latest version ACL. Not used for access check if null. |
view_folders[].acl.additive_components[] | repeated AccessControlListComponentMapEntry | Accesses the additive automatic components of this ACL. |
view_folders[].flags_obsolete | uint32 | Bit flags that provide additional information on the view. |
view_folders[].options | VIEWFLAGS | Bit flags that provide additional information on the view. |
view_folders[].options.all | bool | Specifies all flags set; Including any future flags. |
view_folders[].options.indexed | bool | Materialized/indexed view. |
view_folders[].options.incompatible_with_full_text_search | bool | The search conditions of the view definition (excluding the grouping levels) are not compatible with full-text search. |
view_folders[].options.sort_across_all_pages_disabled | bool | Sorting search results is disabled. |
view_folders[].guid | string | GUID for the view. |
view_folders[].view_visualization | ViewVisualization | View visualization information. |
view_folders[].view_visualization.subview_groups[] | repeated SubviewGroup | The subviews of the view as groups. |
property_folders[] | repeated TypedValue | Resulting property folders array. |
property_folders[].is_null_value | bool | True if the value is empty. data is then unset. |
property_folders[].type | Datatype | The data type of the value. |
property_folders[].data | TypedValueUnion | The value, in the member that matches type. Unset for an empty value. |
property_folders[].data.text | string (oneof data) | The value of DATATYPE_TEXT. |
property_folders[].data.integer | int32 (oneof data) | The value of DATATYPE_INTEGER. |
property_folders[].data.real_number | double (oneof data) | The value of DATATYPE_REAL_NUMBER. |
property_folders[].data.decimal_number | string (oneof data) | Fixed precision number. |
property_folders[].data.date | google.protobuf.Timestamp (oneof data) | The value of DATATYPE_DATE: midnight UTC of the date. |
property_folders[].data.time | google.protobuf.Timestamp (oneof data) | Time. |
property_folders[].data.timestamp | google.protobuf.Timestamp (oneof data) | The value of DATATYPE_TIMESTAMP, in UTC. |
property_folders[].data.boolean | bool (oneof data) | The value of DATATYPE_BOOLEAN. |
property_folders[].data.lookup | Lookup (oneof data) | The value of DATATYPE_LOOKUP: one value list item or object. |
property_folders[].data.multi_select_lookup | MultiSelectLookup (oneof data) | The value of DATATYPE_MULTI_SELECT_LOOKUP: any number of value list items or objects. |
property_folders[].data.integer64 | int64 (oneof data) | Integer (8 bytes). |
property_folders[].data.filetime | google.protobuf.Timestamp (oneof data) | FILETIME (64-bit integer). |
property_folders[].data.multi_line_text | string (oneof data) | The value of DATATYPE_MULTI_LINE_TEXT. |
property_folders[].data.acl | AccessControlList (oneof data) | Access Control List. |
traditional_folders[] | repeated Lookup | Resulting traditional folders array. |
traditional_folders[].value_list_item_info | ItemInfo | The selected item. Only obj_id is needed when setting a value. |
traditional_folders[].value_list_item_info.obj_id | ObjID | The object id or value list item id. Includes the object type or value list id. |
traditional_folders[].value_list_item_info.name | string | The name of the item. |
traditional_folders[].value_list_item_info.external_id_status | ExtIDStatus | The status of this item's external ID.Values: EXT_IDSTATUS_UNKNOWN (0), EXT_IDSTATUS_EXTERNAL (1), EXT_IDSTATUS_INTERNAL (2), EXT_IDSTATUS_DISCARDED (3), EXT_IDSTATUS_NOT_AVAILABLE (4), EXT_IDSTATUS_EXTERNAL_REDUCED (5). |
traditional_folders[].value_list_item_info.external_id | string | The external ID (display ID) of this item. unset means that the external ID is the same as the internal ID. |
traditional_folders[].value_list_item_info.guid | string | GUID for the item. |
traditional_folders[].value_list_item_info.options | ITEMFLAGS | Bit flags that provide additional information on the item (e.g. is the object deleted). |
traditional_folders[].value_list_item_info.external_repository_icon_id | string | The ID of the item's icon. |
traditional_folders[].version | ObjVerVersion | The version of the selected object. The server returns OBJ_VER_VERSION_TYPE_LATEST (-1), meaning the latest version. |
traditional_folders[].version.type | ObjVerVersionType | What internal_version means. OBJ_VER_VERSION_TYPE_SPECIFIC for a version number.Values: OBJ_VER_VERSION_TYPE_UNINITIALIZED (0), OBJ_VER_VERSION_TYPE_LATEST (1), OBJ_VER_VERSION_TYPE_ANY (2), OBJ_VER_VERSION_TYPE_ALL (3), OBJ_VER_VERSION_TYPE_SPECIFIC (4), OBJ_VER_VERSION_TYPE_VALUE_LIST_ITEM (6), OBJ_VER_VERSION_TYPE_OBJECT_LEVEL_REFERENCE (7). |
traditional_folders[].version.internal_version | int32 | The version number, starting from 1, when type is OBJ_VER_VERSION_TYPE_SPECIFIC. The server returns -1 with OBJ_VER_VERSION_TYPE_LATEST. |
traditional_folders[].version.external_repository_version | string | Used only for objects in external repositories. Leave empty. |
traditional_folders[].version.external_repository_sort_key | int64 | Used only for objects in external repositories. Leave 0. |
objects[] | repeated SearchResultsItem | Resulting objects array. |
objects[].object | ObjectVersionEx | The object and the found version: object ID, version, title, class, files and status. Property values are not included. |
objects[].object.version_info | ObjectVersion | Object Version information. |
objects[].object.object_info | ObjectLevelInfo | Object-level information. |
objects[].score | int32 | The relevance score of the result. Higher is more relevant. |
objects[].chunk | string | For an Aino search, the passage of text that matched. Empty for other searches. |
external_repository_folders[] | repeated ExternalView | Reulsting external views array. |
external_repository_folders[].id | ExternalRepositoryID | The view ID in external repository. |
external_repository_folders[].id.connection | string | The external repository connection identifier. |
external_repository_folders[].id.item | string | External ID within the scope of the connection to external system. |
external_repository_folders[].display_name | string | The name of the view. |
external_repository_folders[].external_repository_icon_id | string | The icon ID. |
external_repository_folders[].parent_id | ExternalRepositoryID | The view's parent ID in external repository. May be uninitialized if the external view does not have a parent. |
external_repository_folders[].parent_id.connection | string | The external repository connection identifier. |
external_repository_folders[].parent_id.item | string | External ID within the scope of the connection to external system. |
external_repository_folders[].object_data | ObjectVersionExWP | If not null, the object representation of the folder. |
external_repository_folders[].object_data.object_version | ObjectVersionEx | Object info. |
external_repository_folders[].object_data.properties[] | repeated PropertyValue | Property values, or an empty array. |
external_repository_folders[].object_data.acl | AccessControlList | If set, ACL. |
external_repository_folders[].object_data.current_user_permissions | ObjectPermissionsForClient | If set, permissions of the object version. |
external_repository_folders[].folder_capabilities | FOLDERCAPABILITYFLAGS | Bit flags that provide information on the folder capabilities. |
external_repository_folders[].folder_capabilities.all | bool | Specifies all flags set; Including any future flags. |
external_repository_folders[].folder_capabilities.can_search_within_this_folder | bool | |
external_repository_folders[].acl | AccessControlList | If set, ACL. |
external_repository_folders[].acl.checked_out_to_user | int32 | Specifies the ID of the user who has extended rights because of the checkout operation performed by her. 0 if such user does not exist. |
external_repository_folders[].acl.is_fully_authoritative | bool | Specifies whether this access control list is set to ignore the secondary permissions that come from the latest checked in version. |
external_repository_folders[].acl.custom_component | AccessControlListComponent | Accesses the custom component of this ACL. |
external_repository_folders[].acl.restrictive_components[] | repeated AccessControlListComponentMapEntry | Accesses the restrictive automatic components of this ACL. |
external_repository_folders[].acl.secondary_access_control_list | AccessControlList (recursive) | Secondary ACL used for latest version ACL. Not used for access check if null. |
external_repository_folders[].acl.additive_components[] | repeated AccessControlListComponentMapEntry | Accesses the additive automatic components of this ACL. |
has_more_property_folders | bool | Are there more property folders? |
has_more_objects | bool | Are there more objects? |
has_more_external_repository_folders | bool | Are there more external view folders? |
pages_with_more_results[] | repeated int32 | The list of item group identifications IDs the results of which were limited. The group identification ID depends on how the search results were grouped. E.g. object type ID. |
search_execution_info | SearchOutputInfo | Additional information about the completed search operation. |
search_execution_info.processing_time_at_engine_in_milliseconds | int32 | The processing time at the search engine, in milliseconds. -1 if not known. |
search_execution_info.processing_time_at_engine_from_mfserver_in_milliseconds | int32 | The processing time at the search engine, including network roundtrip from MFServer, in milliseconds. -1 if not known. |
search_execution_info.processing_time_at_mfserver_in_milliseconds | int32 | The total processing time at MFServer, in milliseconds. -1 if not known. |
search_execution_info.processing_time_at_mfserver_from_client_in_milliseconds | int32 | The total processing time at MFServer, including network roundtrip from the client, in milliseconds. -1 if not known. |
options | SEARCHSTATUSFLAGS | Search status flags. |
options.all | bool | Specifies all flags set; Including any future flags. |
options.multiphase_object_type_search_needed | bool | Multi-phase OT search is needed. |
options.wildcard_expansion_limit_exceeded | bool | Wildcard expansion limit has been exceeded (but some results has been returned anyway). |
options.may_contain_stale_data | bool | Data returned by search may be out of date. |
options.resorted_to_default_sort | bool | Requested sorting is not supported and result set was established using the default sorting (relevance). |
options.resorted_to_default_sort_too_many_results | bool | Requested sorting is not supported and result set was established using the default sorting (relevance) because there are too many matching results for sorting. |
options.sorted_by_engine | bool | Data returned by search was sorted by the engine (Global Sorting). |
objects_continuation_token | string | Continuation token for paginating search results for objects from Master Storage. |
has_additional_results | bool | True if there are additional results that can't be counted in advance. |
selected_property_folders[] | repeated TypedValue | The user's still valid selected property folders of the level, in no particular order. Filled only when includeSelectedFolders was requested. |
selected_property_folders[].is_null_value | bool | True if the value is empty. data is then unset. |
selected_property_folders[].type | Datatype | The data type of the value. |
selected_property_folders[].data | TypedValueUnion | The value, in the member that matches type. Unset for an empty value. |
selected_property_folders[].data.text | string (oneof data) | The value of DATATYPE_TEXT. |
selected_property_folders[].data.integer | int32 (oneof data) | The value of DATATYPE_INTEGER. |
selected_property_folders[].data.real_number | double (oneof data) | The value of DATATYPE_REAL_NUMBER. |
selected_property_folders[].data.decimal_number | string (oneof data) | Fixed precision number. |
selected_property_folders[].data.date | google.protobuf.Timestamp (oneof data) | The value of DATATYPE_DATE: midnight UTC of the date. |
selected_property_folders[].data.time | google.protobuf.Timestamp (oneof data) | Time. |
selected_property_folders[].data.timestamp | google.protobuf.Timestamp (oneof data) | The value of DATATYPE_TIMESTAMP, in UTC. |
selected_property_folders[].data.boolean | bool (oneof data) | The value of DATATYPE_BOOLEAN. |
selected_property_folders[].data.lookup | Lookup (oneof data) | The value of DATATYPE_LOOKUP: one value list item or object. |
selected_property_folders[].data.multi_select_lookup | MultiSelectLookup (oneof data) | The value of DATATYPE_MULTI_SELECT_LOOKUP: any number of value list items or objects. |
selected_property_folders[].data.integer64 | int64 (oneof data) | Integer (8 bytes). |
selected_property_folders[].data.filetime | google.protobuf.Timestamp (oneof data) | FILETIME (64-bit integer). |
selected_property_folders[].data.multi_line_text | string (oneof data) | The value of DATATYPE_MULTI_LINE_TEXT. |
selected_property_folders[].data.acl | AccessControlList (oneof data) | Access Control List. |
max_property_folders_limit | uint32 | The effective limit of the property folders of the level, which is also the folder selection limit. Zero means no limit, or that the folder selection is not available or the folder does not list a view level. Use canHaveSelectedFolders to tell if the level can hold a selection. |
can_have_selected_folders | bool | True when the folders of the level can be selected. |
Related methods
- SearchObjects -- Searches the vault for objects that match the given conditions.
- GetFolderContentsOfPinboard -- Gets the contents of the Pinboard items.
- GetFolderContentsOrDelta -- Gets the contents of the specified folder, or a delta that indicates changes to document vault data since the logical timestamp known by the caller.