# Background operations (IRPCBackgroundOperationsAdmin)

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)

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

Monitors the vault's background work: refreshes of external object types and external
locations, and the queue of asynchronous tasks.

Use this interface to start, stop and query background operations.

- **gRPC service:** `MFiles.IRPCBackgroundOperationsAdmin`
- **Book and level:** [Administration API](https://developer.m-files.com/APIs/gRPC-API/admin/index.md), specialized
- **Methods:** 9
- **Proto file:** [`mfiles/IRPCBackgroundOperationsAdmin.proto`](https://developer.m-files.com/APIs/gRPC-API/downloads/proto/mfiles/IRPCBackgroundOperationsAdmin.proto)

<a id="overview"></a>

## Overview

M-Files Admin uses this service to show and start background refreshes and to list the vault's
asynchronous tasks. Every method needs a vault session and the vault right
`change_metadata_structure` (part of full control); a normal user gets "Access denied.". The exception is
[CheckAndRegisterMultiServerResponsibility](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/CheckAndRegisterMultiServerResponsibility/index.md),
which is for an M-Files component.

**Background operations** are identified by a
[BackgroundOperationID](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.BackgroundOperationID/index.md): `type` and `id`. M-Files Admin uses
`BACKGROUND_OPERATION_TYPE_REFRESH_EXTERNAL_OBJECT_TYPE` with the object type ID and
`BACKGROUND_OPERATION_TYPE_REFRESH_EXTERNAL_LOCATION` with the external location ID. Start one with
[StartBackgroundOperation](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/StartBackgroundOperation/index.md),
then follow it with
[GetBackgroundOperationStatus](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/GetBackgroundOperationStatus/index.md)
or block with
[WaitForBackgroundOperationCompletion](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/WaitForBackgroundOperationCompletion/index.md).

**Asynchronous tasks** ([AsyncTask](https://developer.m-files.com/APIs/gRPC-API/Reference/Messages/MFiles.AsyncTask/index.md)) are work items that the vault queues
and runs later, for example permission updates after a change (`ACLPseudoUserPropagation`,
`RefreshObjectsACL`) or preview file generation (`GenerateViewerFiles`). Task IDs grow over
time. Read them with
[GetAsyncTasksRange](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/GetAsyncTasksRange/index.md) or
[GetAsyncTask](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/GetAsyncTask/index.md), and wait for them with
[WaitForAsyncTaskCompletion](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/WaitForAsyncTaskCompletion/index.md).

To wait until the vault has finished all background work queued so far (for example in a test,
after a change that triggers permission updates):

1. [QueueAndGetLatestAsyncTask](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/QueueAndGetLatestAsyncTask/index.md);
   stop if `is_available` is false.
2. [WaitForAsyncTaskCompletion](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/WaitForAsyncTaskCompletion/index.md)
   with `async_tasks` = [that task's ID] and `tasks_request` = { `async_task_start`: the same ID,
   `max_count`: 50, `latest`: true, `filters`: 3 (queued or running) }.
3. Repeat step 2 with the IDs in `tasks_response.async_tasks` until it is empty.

<a id="methods"></a>

## Methods

| Method | Summary | Facts |
|---|---|---|
| [CheckAndRegisterMultiServerResponsibility](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/CheckAndRegisterMultiServerResponsibility/index.md) | Tells whether this server is the one in a multi-server vault that runs the reporting data exports, and claims that role if no server has it. | `internal: not for applications` `admin` `session` `idempotent` |
| [GetAsyncTask](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/GetAsyncTask/index.md) | Gets one asynchronous task by ID. | `admin` `session` `idempotent` |
| [GetAsyncTasks](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/GetAsyncTasks/index.md) | Gets the vault's asynchronous tasks, newest first. | `admin` `session` `idempotent` |
| [GetAsyncTasksRange](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/GetAsyncTasksRange/index.md) | Gets a page of asynchronous tasks, oldest or newest first, optionally only tasks in given states. | `admin` `session` `idempotent` |
| [GetBackgroundOperationStatus](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/GetBackgroundOperationStatus/index.md) | Gets the run state of a background operation, such as an external object type refresh. | `admin` `session` `idempotent` |
| [QueueAndGetLatestAsyncTask](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/QueueAndGetLatestAsyncTask/index.md) | Gets the newest asynchronous task of the vault and asks the server to queue pending tasks for running now. | `admin` `session` `idempotent` |
| [StartBackgroundOperation](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/StartBackgroundOperation/index.md) | Starts a background operation now, such as a full refresh of an external object type from its external database. | `admin` `session` `idempotent` |
| [WaitForAsyncTaskCompletion](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/WaitForAsyncTaskCompletion/index.md) | Waits until the given asynchronous tasks have finished, then optionally returns a list of tasks. | `admin` `session` `idempotent` |
| [WaitForBackgroundOperationCompletion](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCBackgroundOperationsAdmin/WaitForBackgroundOperationCompletion/index.md) | Waits until a background operation has finished, or stops it. | `admin` `session` `idempotent` |