IRPCVaultAdmin.RestoreFromArchive
Administration API / specialized admin session
Imports the contents of an archive (or one object of it) into the vault, or previews the import.
| Service | Vault administration MFiles.IRPCVaultAdmin |
|---|---|
| gRPC method | /MFiles.IRPCVaultAdmin/RestoreFromArchive |
| HTTP (mf-http-grpc) | POST /grpc/v1/restore-from-archive |
| Request | RestoreFromArchiveRequest |
| Response | RestoreFromArchiveResponse |
| Book and level | Administration API, specialized |
| Kind | admin |
| Session | Required: the session ID from LogIn in the mfiles-session-id-bin metadata. |
| Idempotent | no |
| Returns metadata structure version | no |
| Streaming | none (unary) |
Remarks
- Starts a background job and returns before it completes unless
preview_onlyis true; follow it with a session of this vault (see the service overview). A preview runs within the call and changes nothing. - Requires a vault session and the vault right
restore_from_archive. Without the server rightmanage_jobs, a real (not preview) import must read from cloud storage (cloud_storage_connection_stringandcloud_storage_password), andsource_filemust be empty even in a preview; otherwise it fails with "Access denied". - Fails on M-Files editions that do not include archiving.
- The preview writes a summary report (XML). Download it with
DownloadScheduledJobOutputFile_ReadBlock
(
download_id=download_idsummary), reading blocks until a block is shorter than requested.
Request: RestoreFromArchiveRequest
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 |
|---|---|---|
preview_only | bool | True to only preview the import and produce a summary report; nothing changes. False to start the import job. |
restorefromarchivejob | RestoreFromArchiveJob | The archive to import (a file on the server or cloud storage), what to import and the import options. |
restorefromarchivejob.source_file | string | Full path to the archive file on server. |
restorefromarchivejob.impersonation | Impersonation | Impersonation information for accessing the archive target file on server. |
restorefromarchivejob.impersonation.type | ImpersonationType | Impersonation type.Values: IMPERSONATION_TYPE_SYSTEM_ACCOUNT (0), IMPERSONATION_TYPE_LOCAL_WINDOWS_ACCOUNT (1), IMPERSONATION_TYPE_EXTERNAL_ACCOUNT (2). |
restorefromarchivejob.impersonation.account | string | Account name (e.g. DOMAIN\user). |
restorefromarchivejob.impersonation.encrypted_password | bytes | Encrypted password. |
restorefromarchivejob.restore_full_archive | bool | True to restore the entire contents of the archive. False to restore a specific document only. |
restorefromarchivejob.restore_object_id | int32 | If bEntireContents is false, specifies the document to restore. |
restorefromarchivejob.options | OBJRESTORINGFLAGS | Bit flags that control the execution of this restoring job. |
restorefromarchivejob.options.all | bool | Specifies all flags set; Including any future flags. |
restorefromarchivejob.options.target_path_is_directory | bool | If present, archive location represents a directory. |
restorefromarchivejob.options.overwrite_existing_versions | bool | If present, replace existing data with the incoming data. |
restorefromarchivejob.options.delete_restored_archive | bool | If present, delete the archive once restored. |
restorefromarchivejob.options.override_permissions | bool | If present, use the overriding permissions. |
restorefromarchivejob.options.restore_check_out_state | bool | DEPRECATED, DO NOT REUSE THE VALUE: const OBJRESTORINGFLAG OBJRESTORINGFLAG_RESETDELTATIMESTAMPS = ( 1 << 5 ); //!< If present, delta timestamps are reset on export jobs. |
restorefromarchivejob.options.do_not_destroy_objects | bool | If present, object destructions are not restored. |
restorefromarchivejob.options.use_names_as_alises | bool | If present, incoming names can be used as aliases. |
restorefromarchivejob.options.disable_external_object_types | bool | If present, all external connections of imported object types are disabled. |
restorefromarchivejob.options.disable_external_user_groups | bool | If present, all external connections of imported user groups are disabled. |
restorefromarchivejob.options.disable_event_handlers | bool | If present, all imported event handlers are deactivated. |
restorefromarchivejob.options.use_object_type_default_permissions | bool | If present, use the default permissions from object types. |
restorefromarchivejob.options.activate_automatic_permissions | bool | If present, new or changed definitions of automatic permissions are activated on objects. |
restorefromarchivejob.options.ignore_automatic_permissions | bool | If present, ignore the definitions of automatic permissions from the imported objects. |
restorefromarchivejob.options.do_not_update_structure_item_ids | bool | Forces the target vault to keep existing structure item guids. |
restorefromarchivejob.options.omit_done_file | bool | Prevents the 'done' file output. |
restorefromarchivejob.options.disable_code_in_property_definitions | bool | If present, all custom code in imported property definitions is deactivated. |
restorefromarchivejob.options.disable_code_in_workflows | bool | If present, all custom code in imported workflows is deactivated. |
restorefromarchivejob.options.allow_signed_code | bool | If present, unchanged or signed custom code is always allowed in import. |
restorefromarchivejob.options.import_older_views | bool | If present, the views with an older last modified date and time are imported. |
restorefromarchivejob.acl_override | AccessControlList | The overriding ACL. Can be unset. |
restorefromarchivejob.acl_override.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. |
restorefromarchivejob.acl_override.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. |
restorefromarchivejob.acl_override.custom_component | AccessControlListComponent | Accesses the custom component of this ACL. |
restorefromarchivejob.acl_override.restrictive_components[] | repeated AccessControlListComponentMapEntry | Accesses the restrictive automatic components of this ACL. |
restorefromarchivejob.acl_override.secondary_access_control_list | AccessControlList (recursive) | Secondary ACL used for latest version ACL. Not used for access check if null. |
restorefromarchivejob.acl_override.additive_components[] | repeated AccessControlListComponentMapEntry | Accesses the additive automatic components of this ACL. |
restorefromarchivejob.restore_structure_items[] | repeated MetadataStructureSelector | If not empty, specifies the metadata structure items to restore. |
restorefromarchivejob.restore_structure_items[].name | string | A friendly name for the selector. May be used to display the reasoning for the metadata structure item selection for a human (may be included in the preview xml). |
restorefromarchivejob.restore_structure_items[].id | string | Optional identificator for the selector. May be used to indicate the reasoning for the metadata structure item selection for a computer (may be included in the preview xml). |
restorefromarchivejob.restore_structure_items[].item_type | MetadataStructureItem | Metadata structure item type to select. |
restorefromarchivejob.restore_structure_items[].item_guid | string | The GUID of item to select. The primary selector. Not used it the value is GUID_NULL. |
restorefromarchivejob.restore_structure_items[].item_alias | string | A semantic alias of the item to select. Applied if the guid is not used. Not used if the value is empty string. |
restorefromarchivejob.restore_structure_items[].item_id | int32 | Id of the item to select. Will be used if no guid nor alias are specified. |
restorefromarchivejob.restore_structure_items[].options | METADATASTRUCTURESELECTORFLAGS | Bit flags that control the metadata structure selection. |
restorefromarchivejob.cloud_storage_connection_string | string | Transport connection string. |
restorefromarchivejob.cloud_storage_password | string | Package encryption password. |
restorefromarchivejob.configuration_id | string | Configuration id of this restoring job. |
Response: RestoreFromArchiveResponse
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 |
|---|---|---|
task_id | int32 | The ID of the vault's import job when preview_only is false. |
prestorefromarchivejoboinfo | RestoreFromArchiveJobOutputInfo | Not used: always empty. Download the summary report instead. |
prestorefromarchivejoboinfo.summary | bytes | The summary report in a serialized format. |
download_idsummary | int32 | The download ID of the preview's summary report when preview_only is true. 0 if there is no report. |
file_size_summary | int64 | The size of the summary report in bytes. |
Related methods
- IRPCScheduledJobsAdmin.DownloadScheduledJobOutputFile_ReadBlock -- Reads a block of a job output file, such as the summary of a restore from archive preview.