# Working with your run queue

## Introduction

When a process flow run is initialised automatically (via a [trigger shape](https://doc.wearepatchworks.com/product-documentation/process-flows/building-process-flows/process-flow-shapes/standard-shapes/trigger-shape) or a [Patchworks API](https://doc.wearepatchworks.com/product-documentation/developer-hub/patchworks-core-api) request), the run job is added to your `queue`.

[Manual runs](https://doc.wearepatchworks.com/product-documentation/developer-hub/patchworks-core-api/core-api-spotlights/initialising-a-process-flow-and-sending-data-via-the-patchworks-api/the-steps/initialising-a-process-flow-and-sending-data) (initialised from the canvas actions bar) and [manual retries](#retrying-a-failed-run) are NOT added to your queue:

<table><thead><tr><th width="388">Initialise method</th><th>Queued?<select><option value="MWtdIeeCOvAG" label="queued" color="blue"></option><option value="mlIMbNtPqr6P" label="not queued" color="blue"></option></select></th></tr></thead><tbody><tr><td><a href="../../building-process-flows/process-flow-shapes/standard-shapes/trigger-shape/trigger-shape-schedule">Trigger shape - schedule</a></td><td><span data-option="MWtdIeeCOvAG">queued</span></td></tr><tr><td><a href="../../building-process-flows/process-flow-shapes/standard-shapes/trigger-shape/trigger-shape-webhook">Trigger shape - webhook</a></td><td><span data-option="MWtdIeeCOvAG">queued</span></td></tr><tr><td><a href="../../building-process-flows/process-flow-shapes/standard-shapes/trigger-shape/trigger-shape-event-listener">Trigger shape - event connector</a></td><td><span data-option="MWtdIeeCOvAG">queued</span></td></tr><tr><td><a href="../../building-process-flows/process-flow-shapes/standard-shapes/run-process-flow-shape">Run process flow shape</a> </td><td><span data-option="MWtdIeeCOvAG">queued</span></td></tr><tr><td><a href="../../../developer-hub/patchworks-core-api/core-api-spotlights/initialising-a-process-flow-and-sending-data-via-the-patchworks-api">API request</a></td><td><span data-option="MWtdIeeCOvAG">queued</span></td></tr><tr><td><a href="../../managing-process-flows/initialising-a-process-flow-manually">Manual (via canvas actions bar)</a></td><td><span data-option="mlIMbNtPqr6P">not queued</span></td></tr><tr><td><a href="#retrying-a-failed-run">Retry (via run logs)</a></td><td><span data-option="mlIMbNtPqr6P">not queued</span></td></tr></tbody></table>

## How it works

The time that run jobs remain in the queue depends on various factors which are summarised below:

<table><thead><tr><th width="283">Factor</th><th>Summary</th></tr></thead><tbody><tr><td>Concurrent process flows allowance</td><td>Refers to the maximum number of process flows that can be run simultaneously - the greater your allowance, the faster your queued run jobs are processed. This allowance is determined by your <a href="../../../getting-started/core-subscription-tiers">Patchworks subscription</a>.</td></tr><tr><td>Scheduled process flows allowance</td><td><p>Refers to the maximum number of process flow run jobs that can be queued at any given time. </p><p><br>If this allowance is exceeded, any subsequent run jobs are held until a queue slot is released (i.e. until an existing item in your queue is picked to be run). This allowance is determined by your <a href="../../../getting-started/core-subscription-tiers">Patchworks subscription</a>. </p></td></tr><tr><td>The 'add to queue' frequency</td><td>The frequency that run jobs are added to your queue. This is a general system setting across the Patchworks platform - it's currently set to <code>30 seconds</code>.</td></tr><tr><td>The 'pick from queue' frequency</td><td>The frequency at which run jobs are picked from your queue and run. This is a general system setting across the Patchworks platform - it's currently set to <code>05 seconds</code> but will be reduced incrementally (aiming for every <code>1 second</code>) over the coming days.  </td></tr><tr><td>Queue priority</td><td>When configuring a process flow, you can set a <a href="../../building-process-flows/process-flow-settings">queue priority</a> (<code>highest</code>, <code>high</code>, <code>regular</code>, <code>low</code>, <code>lowest</code>). If set, this priority will affect the sequence in which run jobs are picked from your queue. </td></tr></tbody></table>

Points to note:

* Every `05` seconds, the system checks if any process flows are running:&#x20;
  * If **NO**, it checks the queue and picks more flows to run - the number of flows picked will be the maximum allowed to meet your `concurrent process flows` limit.&#x20;
  * If **YES**, it checks if our `concurrent process flows` limit has been reached. If it has, no more flows are picked from the queue. If it has not, the queue is checked and more flows are picked to run. The number of flows picked will be the maximum allowed to meet our `concurrent process flows` limit.
* If a process flow is [triggered manually](https://doc.wearepatchworks.com/product-documentation/process-flows/managing-process-flows/initialising-a-process-flow-manually), it bypasses the queue and is run as soon as possible. A manual run still consumes one flow from your `concurrent process flows` allowance - so while it's running, one less job can be picked from your queue.&#x20;
* By default, run jobs are picked from the queue in the sequence they were added. However, if a [queue priority](https://doc.wearepatchworks.com/product-documentation/process-flows/building-process-flows/process-flow-settings) has been set for a process flow, it takes precedence. For example, if your queue contains 6 run jobs with no `queue priority` and then a new job is added for a process flow with a `queue priority` set to `high`, this will be the next job to be picked (despite being the last to be added to the queue). Conversely, if a job is queued for a process flow with a `queue priority` set to `lowest`, this will be the last job to leave the queue. &#x20;

## Viewing your run queue

You can view all of your pending runs from the **queue** tab - entries are listed chronologically based on the time that the job was added to the queue:

<figure><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2FXTU1D1wyPRzdl1IBkAkG%2Frun%20queue%20main.png?alt=media&#x26;token=a08dc0d9-1e50-49f3-bc8b-f80d12110855" alt=""><figcaption></figcaption></figure>

At a glance, you can see:

* Process flow name (hyperlinked so you can quickly access the flow)
* Environment (only applicable if you use [virtual environments](https://doc.wearepatchworks.com/product-documentation/virtual-environments/about-virtual-environments))
* Trigger&#x20;
* Queued at time
* Priority

From here you can:

* [Filter the queue by environment](#filtering-your-queue-by-virtual-environment)
* [Remove a specific run job](#removing-a-specific-run-job) &#x20;
* [Remove all run jobs for a selected process flow](#removing-all-run-jobs-for-a-selected-process-flow)
* [Clear all run jobs](#clearing-all-run-jobs)&#x20;

{% hint style="info" %}
As soon as a pending job starts running, the entry is removed from this table and moves to the [active run logs](#working-with-run-logs) section.
{% endhint %}

{% hint style="info" %}
Whether or not a process flow is queued depends on how it is initialised - see [Are all run jobs queued?](#are-all-run-jobs-queued) for more information.
{% endhint %}

## Filtering your queue by virtual environment

If you use [virtual environments](https://doc.wearepatchworks.com/product-documentation/virtual-environments/about-virtual-environments), it can be useful to filter your run queue for a specific environment. You can do this using the environments dropdown selector at the top of the page. For example:

<figure><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2FYNUQyCKeXTYDoDSCvwM9%2Frun%20queue%20envs.png?alt=media&#x26;token=e7091cff-e786-45ef-8fee-34db8d3cac35" alt=""><figcaption></figcaption></figure>

## Removing a specific run job

To remove a specific run job from your queue (so it doesn't run), click the associated 'bin' icon:

<figure><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2FSD6NraT8Asyc91pB0I7j%2Fdelete%20individual%20run.png?alt=media&#x26;token=632273d6-c5b9-44a3-954d-ca2cb9da51f0" alt=""><figcaption></figcaption></figure>

When prompted, confirm this action.

{% hint style="info" %}
In the unlikely event that you delete a run job that has already left the queue (because the dashboard has not refreshed), you'll be advised of this when you attempt to confirm the delete action.&#x20;
{% endhint %}

## Removing all run jobs for a selected process flow

To remove all run jobs for a particular process flow (so none of them run):

{% stepper %}
{% step %}
**Select a process flow**

Select the required process flow from the dropdown list at the top of the page:

<figure><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2FjiW5cS50fE26succOv1s%2Fdelete%20for%20flow%201.png?alt=media&#x26;token=cfaec189-9019-48db-bee8-7cfb42b0c3ed" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}
**(Optional) Filter by virtual environment**

If you use [virtual environments](https://doc.wearepatchworks.com/product-documentation/virtual-environments), you can filter your queue by environment using the dropdown selector at the top of the page. For example:

<figure><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2F29CGLa1VFmjq0idDvjU6%2FRun%20queue.png?alt=media&#x26;token=f2eb0a1c-17f5-4888-a7c7-0426676163dc" alt=""><figcaption></figcaption></figure>

Any environments associated with jobs that are currently in the queue will be available for selection.
{% endstep %}

{% step %}
**Remove queued runs**&#x20;

Click the `remove all for flow` button:

<figure><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2FuK1AEZ2P0YdrPrVaRpN4%2Fdelete%20for%20flow%202.png?alt=media&#x26;token=5c178f7c-6297-4f16-8d1c-869845d22467" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}
**Confirm this action**

When prompted, confirm this action.
{% endstep %}
{% endstepper %}

## Clearing all run jobs

{% stepper %}
{% step %}
**(Optional) Filter by virtual environment**

If you use [virtual environments](https://doc.wearepatchworks.com/product-documentation/virtual-environments), you can remove all runs for a specific environment, using the dropdown selector at the top of the page. For example:

<figure><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2F29CGLa1VFmjq0idDvjU6%2FRun%20queue.png?alt=media&#x26;token=f2eb0a1c-17f5-4888-a7c7-0426676163dc" alt=""><figcaption></figcaption></figure>

Any environments associated with jobs that are currently in the queue will be available for selection.
{% endstep %}

{% step %}
**Clear the queue**&#x20;

Click the `clear queue` button. For example:

<figure><img src="https://2440044887-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLYNcUBVQwSkOMG6KjZfz%2Fuploads%2FsGYMpIHXOQn2hQ64AehN%2Fclear%20queue%201.png?alt=media&#x26;token=1fb021e3-106f-4a3f-9a0b-9a179bb41fa9" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}
**Confirm this action**

When prompted, confirm this action.
{% endstep %}
{% endstepper %}

## Related information

* [Viewing logs](https://doc.wearepatchworks.com/product-documentation/process-flows/error-reporting-and-exception-handling/run-logs-and-queue/working-with-run-logs/viewing-detailed-logs-for-a-flow-run)
* [Viewing logs (classic)](https://doc.wearepatchworks.com/product-documentation/process-flows/error-reporting-and-exception-handling/run-logs-and-queue/working-with-run-logs/viewing-logs-classic)
* [Downloading run logs](https://doc.wearepatchworks.com/product-documentation/process-flows/error-reporting-and-exception-handling/run-logs-and-queue/working-with-run-logs/downloading-run-logs)
* [Retrying a failed process flow run](https://doc.wearepatchworks.com/product-documentation/process-flows/error-reporting-and-exception-handling/run-logs-and-queue/working-with-run-logs/handling-failed-process-flow-runs/retrying-a-failed-process-flow-run)
* [Email notifications for failed process flow runs](https://doc.wearepatchworks.com/product-documentation/process-flows/error-reporting-and-exception-handling/email-notifications-for-failed-process-flow-runs)
* [Virtual environments](https://doc.wearepatchworks.com/product-documentation/virtual-environments/about-virtual-environments)