IRPCValueLists.CreateOrFindTraditionalFolder

Vault API / core write session or assertion returns metadata structure version

Creates a traditional folder, or returns an existing folder with the same name.

Service	Value lists `MFiles.IRPCValueLists`
gRPC method	`/MFiles.IRPCValueLists/CreateOrFindTraditionalFolder`
HTTP (mf-http-grpc)	`POST /grpc/v1/create-or-find-traditional-folder`
Request	`CreateOrFindTraditionalFolderRequest`
Response	`CreateOrFindTraditionalFolderResponse`
Book and level	Vault API, core
Kind	write
Session	Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
Idempotent	no
Returns metadata structure version	yes (in the mfiles-metadata-version-bin trailer)
Streaming	none (unary)

Remarks

Requires the vault rights license_allows_modifications and manage_traditional_folders.
The item must be in Traditional folders (item_info.obj_id.type 4) and have a name; it cannot have an owner. Set has_parent and parent_id for a subfolder.
Names are compared case-insensitively. A deleted folder with the same name is always undeleted and returned, whatever can_return_existing_folder says.
The response lists the folder and its parent folders.

Request: CreateOrFindTraditionalFolderRequest

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
`vl_item`	`ValueListItem`	The folder to create: `item_info.obj_id.type` 4, `item_info.name`, and for a subfolder `has_parent` and `parent_id`. The item ID is ignored.
`vl_item.item_info`	`ItemInfo`	The item's identity and name: `obj_id.type` is the value list ID, `obj_id.item_id.internal_id` the item ID (unique within the list only), plus `name`, `guid`, `external_id` and flags. `options.is_deleted` marks a deleted item.
`vl_item.item_info.obj_id`	`ObjID`	The object id or value list item id. Includes the object type or value list id.
`vl_item.item_info.name`	`string`	The name of the item.
`vl_item.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).
`vl_item.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.
`vl_item.item_info.guid`	`string`	GUID for the item.
`vl_item.item_info.options`	`ITEMFLAGS`	Bit flags that provide additional information on the item (e.g. is the object deleted).
`vl_item.item_info.external_repository_icon_id`	`string`	The ID of the item's icon.
`vl_item.has_parent`	`bool`	True if the item has a parent item in the same (hierarchical) list.
`vl_item.has_owner`	`bool`	True if the item belongs to an item of the owner list (`ValueList.owner_object_type`).
`vl_item.parent_id`	`int32`	With `has_parent`, the item ID of the parent item; otherwise ignored.
`vl_item.owner_id`	`int32`	With `has_owner`, the item ID of the owner item in the owner list.
`vl_item.owner_name`	`string`	The name of the owner item.
`vl_item.automatic_permissions`	`AutomaticPermissions`	If set, specifies the automatic permissions for an object for which the user selects this item.
`vl_item.automatic_permissions.permissions`	`NamedACL`	The automatic permissions for an object for which the user selects this item.
`vl_item.automatic_permissions.is_default`	`bool`	True if these automatic permissions are not private i.e. they are not directly specified for (owned by) this item but they come from somewhere else, e.g. from the default/common automatic permissions of the object type.
`vl_item.automatic_permissions.use_object_permissions`	`bool`	If true the object/item's own permissions are used as its automatic permissions.
`vl_item.icon`	`Bytes`	If set, contains the icon of this item in .ICO format.
`vl_item.icon.value`	`bytes`	Array of bytes.
`can_return_existing_folder`	`bool`	True to return an existing folder with the same name (compared case-insensitively) instead of failing.

Response: CreateOrFindTraditionalFolderResponse

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
`putf8szvlitems[]`	repeated `ValueListItem`	The created or found folder and its parent folders.
`putf8szvlitems[].item_info`	`ItemInfo`	The item's identity and name: `obj_id.type` is the value list ID, `obj_id.item_id.internal_id` the item ID (unique within the list only), plus `name`, `guid`, `external_id` and flags. `options.is_deleted` marks a deleted item.
`putf8szvlitems[].item_info.obj_id`	`ObjID`	The object id or value list item id. Includes the object type or value list id.
`putf8szvlitems[].item_info.name`	`string`	The name of the item.
`putf8szvlitems[].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).
`putf8szvlitems[].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.
`putf8szvlitems[].item_info.guid`	`string`	GUID for the item.
`putf8szvlitems[].item_info.options`	`ITEMFLAGS`	Bit flags that provide additional information on the item (e.g. is the object deleted).
`putf8szvlitems[].item_info.external_repository_icon_id`	`string`	The ID of the item's icon.
`putf8szvlitems[].has_parent`	`bool`	True if the item has a parent item in the same (hierarchical) list.
`putf8szvlitems[].has_owner`	`bool`	True if the item belongs to an item of the owner list (`ValueList.owner_object_type`).
`putf8szvlitems[].parent_id`	`int32`	With `has_parent`, the item ID of the parent item; otherwise ignored.
`putf8szvlitems[].owner_id`	`int32`	With `has_owner`, the item ID of the owner item in the owner list.
`putf8szvlitems[].owner_name`	`string`	The name of the owner item.
`putf8szvlitems[].automatic_permissions`	`AutomaticPermissions`	If set, specifies the automatic permissions for an object for which the user selects this item.
`putf8szvlitems[].automatic_permissions.permissions`	`NamedACL`	The automatic permissions for an object for which the user selects this item.
`putf8szvlitems[].automatic_permissions.is_default`	`bool`	True if these automatic permissions are not private i.e. they are not directly specified for (owned by) this item but they come from somewhere else, e.g. from the default/common automatic permissions of the object type.
`putf8szvlitems[].automatic_permissions.use_object_permissions`	`bool`	If true the object/item's own permissions are used as its automatic permissions.
`putf8szvlitems[].icon`	`Bytes`	If set, contains the icon of this item in .ICO format.
`putf8szvlitems[].icon.value`	`bytes`	Array of bytes.
`current_version_on_server`	`int64`	The current version of the Traditional folders list's items (see `GetValueListItemsWithPermissions.known_version`).