# IRPCVaultAdmin.RestoreFromArchive

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md) > [Vault administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/index.md)

HTML version: https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/RestoreFromArchive/

Badges: `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](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/index.md) `MFiles.IRPCVaultAdmin`
- **gRPC method:** `/MFiles.IRPCVaultAdmin/RestoreFromArchive`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/restore-from-archive`
- **Request:** [`RestoreFromArchiveRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/RestoreFromArchive/index.md#request)
- **Response:** [`RestoreFromArchiveResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/RestoreFromArchive/index.md#response)
- **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)

<a id="remarks"></a>

## Remarks

- **Starts a background job and returns before it completes** unless `preview_only` is 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 right
  `manage_jobs`, a real (not preview) import must read from cloud storage
  (`cloud_storage_connection_string` and `cloud_storage_password`), and `source_file` must 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](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/DownloadScheduledJobOutputFile_ReadBlock/index.md)
  (`download_id` = `download_idsummary`), reading blocks until a block is shorter than requested.

<a id="request"></a>

## 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`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.RestoreFromArchiveJob/index.md) | 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`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Impersonation/index.md) | Impersonation information for accessing the archive target file on server. |
| `restorefromarchivejob.impersonation.type` | [`ImpersonationType`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ImpersonationType/index.md) | 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`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJRESTORINGFLAGS/index.md) | 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`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) | 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`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponent/index.md) | Accesses the custom component of this ACL. |
| `restorefromarchivejob.acl_override.restrictive_components[]` | repeated [`AccessControlListComponentMapEntry`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentMapEntry/index.md) | Accesses the restrictive automatic components of this ACL. |
| `restorefromarchivejob.acl_override.secondary_access_control_list` | [`AccessControlList`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlList/index.md) (recursive) | Secondary ACL used for latest version ACL. Not used for access check if null. |
| `restorefromarchivejob.acl_override.additive_components[]` | repeated [`AccessControlListComponentMapEntry`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AccessControlListComponentMapEntry/index.md) | Accesses the additive automatic components of this ACL. |
| `restorefromarchivejob.restore_structure_items[]` | repeated [`MetadataStructureSelector`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.MetadataStructureSelector/index.md) | 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`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.MetadataStructureItem/index.md) | 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`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.METADATASTRUCTURESELECTORFLAGS/index.md) | 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. |

<a id="response"></a>

## 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`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.RestoreFromArchiveJobOutputInfo/index.md) | 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. |

<a id="related"></a>

## Related methods

- [IRPCScheduledJobsAdmin.DownloadScheduledJobOutputFile_ReadBlock](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCScheduledJobsAdmin/DownloadScheduledJobOutputFile_ReadBlock/index.md): Reads a block of a job output file, such as the summary of a restore from archive preview.