# IRPCVaultAdmin.ArchiveDocuments

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/ArchiveDocuments/

Badges: `Administration API / specialized` `admin` `session`

Exports (archives) the objects that match a filter into an archive package, or previews how many
would be archived.

- **Service:** [Vault administration](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/index.md) `MFiles.IRPCVaultAdmin`
- **gRPC method:** `/MFiles.IRPCVaultAdmin/ArchiveDocuments`
- **HTTP (mf-http-grpc):** `POST /grpc/v1/archive-documents`
- **Request:** [`ArchiveDocumentsRequest`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/ArchiveDocuments/index.md#request)
- **Response:** [`ArchiveDocumentsResponse`](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCVaultAdmin/ArchiveDocuments/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 `archive`. Without the server right `manage_jobs`,
  a real (not preview) archive must go to cloud storage (`cloud_storage_connection_string` and
  `cloud_storage_password`), and `target_path` must be empty even in a preview; otherwise it
  fails with "Access denied". With `manage_jobs`, set either `target_path` or the cloud storage
  settings.
- Depending on `archive_job.options`, the objects can be destroyed after they are archived.
- Fails on M-Files editions that do not include archiving.

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

## Request: ArchiveDocumentsRequest

> 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 |
|---|---|---|
| `preview_only` | `bool` | True to only count what would be archived; the destination in the job is then ignored and nothing changes. False to start the archiving job. |
| `archive_job` | [`ArchiveDocsJob`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ArchiveDocsJob/index.md) | The objects to archive (`object_filter`), the destination and the options. |
| `archive_job.target_path` | `string` | Full path to the target file on server. |
| `archive_job.impersonation` | [`Impersonation`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.Impersonation/index.md) | Impersonation information for accessing the archive target files on server. |
| `archive_job.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). |
| `archive_job.impersonation.account` | `string` | Account name (e.g. DOMAIN\user). |
| `archive_job.impersonation.encrypted_password` | `bytes` | Encrypted password. |
| `archive_job.options` | [`OBJARCHIVINGFLAGS`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.OBJARCHIVINGFLAGS/index.md) | Bit flags that control the execution of this archiving job. |
| `archive_job.options.all` | `bool` | Specifies all flags set; Including any future flags. |
| `archive_job.options.overwrite_existing_files` | `bool` | If present, existing target files are overwritten. If not present, job fails if a target file already exists. |
| `archive_job.options.archive_latest_version_only` | `bool` | If present, only the latest version is archived. |
| `archive_job.options.destroy_archived_objects` | `bool` | If present and archiving full objects, the archived objects are destroyed. |
| `archive_job.options.reset_marked_for_archiving` | `bool` | If present, the 'Marked for archiving' property is reset upon archiving. |
| `archive_job.options.archive_data_files` | `bool` | If present, data files are archived instead of document files. |
| `archive_job.options.create_archive_pdfs` | `bool` | If present, files are also saved as PDF/A. |
| `archive_job.options.archive_destroyed_objects` | `bool` | If present, destroyed objects are archived. |
| `archive_job.options.target_path_is_directory` | `bool` | If present, archive location represents a directory. |
| `archive_job.options.ignore_last_run_timestamp` | `bool` | If present, delta timestamp is not applied (even if provided as non-FILETIME_ZERO). |
| `archive_job.options.ignore_search_conditions` | `bool` | If present, search filter is not applied (even if provided). |
| `archive_job.options.export_drop_out_information` | `bool` | If present, dropout information is exported if a previously exported object is not anymore part of the export set. |
| `archive_job.options.export_content` | `bool` | If present, vault content will be exported. |
| `archive_job.options.export_structure` | `bool` | If present, vault metadata structure will be exported. |
| `archive_job.options.export_value_list_values` | `bool` | If present, values of the selected values lists will be exported. |
| `archive_job.options.export_private_view_settings` | `bool` | If present, private settings of the selected views will be exported. |
| `archive_job.options.export_migrated_as_internal` | `bool` | If present, migrated objects will be exported as internal objects without <externalrepository> element. |
| `archive_job.options.export_workspace_tabs` | `bool` | If present, workspace tabs will be exported. |
| `archive_job.object_filter` | [`SearchConditionArray`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchConditionArray/index.md) | The conditions that limit the object set of this archiving job. |
| `archive_job.object_filter.value[]` | repeated [`SearchCondition`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.SearchCondition/index.md) | The conditions. All of them must match. |
| `archive_job.last_run_timestamp_utc` | [`google.protobuf.Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | If indicated by OBJARCHIVINGFLAG_DELTA, only changes newer than this timestamp are archived. In UTC. |
| `archive_job.structure_items[]` | repeated [`ExportStructureItem`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ExportStructureItem/index.md) | The metadata structure items which will be exported. |
| `archive_job.structure_items[].type` | [`MetadataStructureItem`](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.MetadataStructureItem/index.md) | Metadata structure item type. |
| `archive_job.structure_items[].group_selection` | [`StructureItemGroup`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.StructureItemGroup/index.md) | The group selection inside of an item type |
| `archive_job.structure_items[].id` | `int32` | Metadata structure item ID. This is used if the group selection is not used. Otherwise it is MFBuiltInMetadataStructureItemIDAll. Should be used if guid is GUID_NULL. |
| `archive_job.structure_items[].guid` | `string` | Metadata structure item GUID. If not GUID_NULL, should be used instead of lID. This is used e.g. with event handler items. |
| `archive_job.cloud_storage_connection_string` | `string` | Full path to the target file on server. |
| `archive_job.cloud_storage_password` | `string` | Full path to the target file on server. |
| `archive_job.configuration_id` | `string` | Configuration id of this archiving job. |

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

## Response: ArchiveDocumentsResponse

> 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 archiving job when `preview_only` is false. |
| `archive_jobs_info` | [`ArchiveDocsJobOutputInfo`](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.ArchiveDocsJobOutputInfo/index.md) | The preview result when `preview_only` is true: the number of objects and bytes. |
| `archive_jobs_info.objects` | `uint32` | The number of archived documents. |
| `archive_jobs_info.bytes` | `int64` | The amount of archived bytes. |