# Application task queue (IRPCApplicationTaskQueue)

Location: [gRPC API](https://developer.m-files.com/APIs/gRPC-API/index.md) > [Server integration API](https://developer.m-files.com/APIs/gRPC-API/integration/index.md)

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

Persistent task queues and broadcast messages that vault applications use to share background
work between the server instances of a vault.

This interface provides access to vault specific task queue for adding and managing the tasks.

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

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

## Overview

This is the server side of the task queue API that vault applications use through the M-Files
API (`Vault.ApplicationTaskOperations`). A vault application opens named queues, adds tasks
with an opaque payload, and its instances on every server of the vault reserve, process and
update them. Queues also carry broadcast messages that every consumer reads.

**Who should call it.** Vault applications, through the M-Files API. An external application
normally should not: the queues belong to the vault applications that open them, and reserving
or updating their tasks takes work away from those applications. Use it only for queues that
your own code owns, or read-only for diagnostics
([GetTaskQueues](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCApplicationTaskQueue/GetTaskQueues/index.md),
[GetTaskIdentifiersFromQueue](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCApplicationTaskQueue/GetTaskIdentifiersFromQueue/index.md),
[GetApplicationTasks](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCApplicationTaskQueue/GetApplicationTasks/index.md)).

**Rights.** Every method needs a vault session of a user with an account in the vault and the
vault right `change_full_control_role`, which only users with full control of the vault have; a
normal user gets "Access denied.". The vault's internal queues, such as
`m-files.server.core.broadcast`, are refused with "Access denied." by the methods that open,
add to, reserve from, broadcast to or destroy a queue, but they are listed by
[GetTaskQueues](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCApplicationTaskQueue/GetTaskQueues/index.md).

**Task life cycle** ([ApplicationTaskState](https://developer.m-files.com/APIs/gRPC-API/Reference/Enums/MFiles.ApplicationTaskState/index.md)):

1. [OpenTaskQueue](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCApplicationTaskQueue/OpenTaskQueue/index.md) creates the queue if
   it does not exist. Call it before adding or reserving.
2. [AddTask](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCApplicationTaskQueue/AddTask/index.md) or
   [AddScheduledTask](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCApplicationTaskQueue/AddScheduledTask/index.md) adds a task in
   state `APPLICATION_TASK_STATE_WAITING`.
3. [ReserveTasksForProcessing](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCApplicationTaskQueue/ReserveTasksForProcessing/index.md)
   moves a waiting task to `APPLICATION_TASK_STATE_IN_PROGRESS` and returns it to one caller.
4. [UpdateTask](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCApplicationTaskQueue/UpdateTask/index.md) reports progress and finally
   sets `COMPLETED`, `FAILED` or `CANCELED`. An in-progress task that is not updated within its
   restore timeout goes back to waiting and can be reserved again.

The server cleans up by itself: completed tasks are deleted; failed and cancelled tasks and
broadcast messages after a day; and queues that have not been used for seven days, together with
their tasks.

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

## Methods

| Method | Summary | Facts |
|---|---|---|
| [AddScheduledTask](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCApplicationTaskQueue/AddScheduledTask/index.md) | Adds a task to a task queue that becomes available for processing at a given time. | `write` `session` |
| [AddTask](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCApplicationTaskQueue/AddTask/index.md) | Adds a task to a task queue, ready to be reserved at once. | `write` `session` |
| [ClearAndDestroyTaskQueue](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCApplicationTaskQueue/ClearAndDestroyTaskQueue/index.md) | Deletes a task queue and all of its tasks. | `write` `session` |
| [GetApplicationTasks](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCApplicationTaskQueue/GetApplicationTasks/index.md) | Gets tasks by ID without reserving them. | `write` `session` |
| [GetLatestBroadcastMessageIdentifiers](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCApplicationTaskQueue/GetLatestBroadcastMessageIdentifiers/index.md) | Gets the ID of the newest broadcast message of each given queue. | `write` `session` |
| [GetNewBroadcastMessages](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCApplicationTaskQueue/GetNewBroadcastMessages/index.md) | Gets the broadcast messages of a queue that are newer than the given message ID. | `write` `session` |
| [GetTaskIdentifiersFromQueue](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCApplicationTaskQueue/GetTaskIdentifiersFromQueue/index.md) | Gets the IDs of the tasks of a queue that are in the given states. | `write` `session` |
| [GetTaskQueues](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCApplicationTaskQueue/GetTaskQueues/index.md) | Gets the IDs of all task queues of the vault. | `write` `session` |
| [OpenTaskQueue](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCApplicationTaskQueue/OpenTaskQueue/index.md) | Creates a task queue if it does not exist, or confirms an existing one. | `write` `session` |
| [ReserveTasksForProcessing](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCApplicationTaskQueue/ReserveTasksForProcessing/index.md) | Reserves the next waiting task from each of the given queues for the caller to process. | `write` `session` |
| [SendBroadcastMessage](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCApplicationTaskQueue/SendBroadcastMessage/index.md) | Sends a broadcast message through a task queue to every consumer of that queue. | `write` `session` |
| [UpdateTask](https://developer.m-files.com/APIs/gRPC-API/Reference/MFiles.IRPCApplicationTaskQueue/UpdateTask/index.md) | Reports the progress or the final state of a task. | `write` `session` |