PublishQueue
PublishQueue
The PublishQueue class reads the publish queue of a stack and cancels scheduled actions. The queue records publish, unpublish, and delete activities on entries and assets, and release deployments.
When to Use This Class: Use this class to check the status of a publish, or to cancel a scheduled publish or release deployment.
Conceptual Role: Acts as the Content Management API (CMA) client for the /publish-queue endpoint. Call stack.PublishQueue() to get an instance.
Returns: PublishQueue. An object for publish queue operations.
Instance State
The UID you pass to stack.PublishQueue() decides which methods you can call on the instance:
- Call stack.PublishQueue() without a UID to list the queue with FindAll or FindAllAsync.
- Call stack.PublishQueue("<PUBLISH_QUEUE_UID>") to work with one activity, for example Fetch or Cancel.
If you call a method from the other group, it throws InvalidOperationException before any request leaves the SDK. Both wrong cases throw the same exception type. The Method Index below lists every method in each group.
Warning The SDK treats an empty string as no UID. stack.PublishQueue("") allows FindAll, which then sends its request to /publish-queue/ with a trailing slash. Call stack.PublishQueue() with no argument when you mean the whole queue.
Class-Level Notes
Authentication.
- stack.PublishQueue() throws InvalidOperationException when the client has no authtoken and the stack has no management token.
- The CMA reference accepts a management token or an Open Authorization (OAuth) token for publish queue requests.
No api_version header.
- The SDK sends no api_version header on publish queue requests, and ParameterCollection adds query parameters only.
- The CMA reference uses the api_version header with the value 3.2 to include Nested Reference Publishing activities. These methods cannot request them.
Responses.
- Every method returns the raw API response as a ContentstackResponse. Read it with OpenJsonObjectResponse().
Capability Matrix
| Capability | Supported | Notes / Alternative |
|---|---|---|
| Include Nested Reference Publishing activities | No | The SDK sends no api_version header on these requests. |
| Schedule a publish | Not on this class | Set ScheduledAt on PublishUnpublishDetails when you publish an entry or asset. |
Method Index
List the queue. Available on stack.PublishQueue() when you pass no UID.
| Method Name | Returns | Description |
|---|---|---|
| FindAll | The API response with the publish queue activities. | Lists the activities in the publish queue. |
| FindAllAsync | The API response with the publish queue activities. | Lists the activities in the publish queue asynchronously. |
Work with one activity. Available on stack.PublishQueue("<PUBLISH_QUEUE_UID>").
| Method Name | Returns | Description |
|---|---|---|
| Fetch | The API response with the requested publish queue activity. | Retrieves one activity. |
| FetchAsync | The API response with the requested publish queue activity. | Retrieves one activity asynchronously. |
| Cancel | The API response with the cancellation notice. | Cancels a scheduled action. |
| CancelAsync | The API response with the cancellation notice. | Cancels a scheduled action asynchronously. |
Class-Level Snippet
This snippet lists the publish queue, fetches one activity, and cancels it while it still waits in the queue.
using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Models;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
Stack stack = client.Stack("<API_KEY>");
try
{
ContentstackResponse queue = await stack.PublishQueue().FindAllAsync();
Console.WriteLine(queue.OpenJsonObjectResponse().ToJsonString());
ContentstackResponse activity = await stack.PublishQueue("<PUBLISH_QUEUE_UID>").FetchAsync();
Console.WriteLine(activity.OpenJsonObjectResponse().ToJsonString());
// Cancel the activity while it still waits in the queue
await stack.PublishQueue("<PUBLISH_QUEUE_UID>").CancelAsync();
}
catch (ContentstackErrorException e)
{
Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}Methods
Each method of the PublishQueue class has its own section below, with its parameters, validation rules, behavior, and examples.
Cancel
Cancel cancels a scheduled publish or unpublish of entries or assets, or a scheduled release deployment.
| Name | Type | Description |
|---|---|---|
| collection | ParameterCollection? | Adds query parameters to the request. |
Returns: ContentstackResponse. The API response with the cancellation notice.
Validation
- Throws InvalidOperationException if the client has no authtoken and the stack has no management token, because the request needs credentials.
- Throws InvalidOperationException if the instance has no UID, because Cancel acts on one scheduled activity. Call stack.PublishQueue("<PUBLISH_QUEUE_UID>").
- The SDK does not check whether the activity still has a schedule. The API decides whether it can cancel the activity.
- Throws ContentstackErrorException when the API rejects the request.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Sends one GET request to /publish-queue/<PUBLISH_QUEUE_UID>/unschedule. See Cancel scheduled action in the Content Management API (CMA) reference.
- Adds the entries of collection to the query string. null or an empty collection adds none.
- Returns the raw API response.
Warning Canceling a scheduled action removes it from the publish queue. The SDK offers no way to restore the schedule. Schedule the publish or deployment again if you need it.
Example
Basic usage: cancel a scheduled publish
using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
try
{
ContentstackResponse response = client.Stack("<API_KEY>").PublishQueue("<PUBLISH_QUEUE_UID>").Cancel();
Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
// Thrown when the API rejects the request
Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}All parameters: cancel a scheduled action with a query parameter collection
using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Queryable;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
// The CMA reference lists no query parameters for this request. Add any parameter the API accepts.
ParameterCollection collection = new ParameterCollection();
collection.Add("<PARAMETER_NAME>", "<PARAMETER_VALUE>");
try
{
ContentstackResponse response = client.Stack("<API_KEY>").PublishQueue("<PUBLISH_QUEUE_UID>").Cancel(collection);
Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}CancelAsync
CancelAsync cancels a scheduled publish or unpublish of entries or assets, or a scheduled release deployment, without blocking the calling thread.
| Name | Type | Description |
|---|---|---|
| collection | ParameterCollection? | Adds query parameters to the request. |
Returns: Task<ContentstackResponse>. The API response with the cancellation notice.
Validation
- Throws InvalidOperationException if the client has no authtoken and the stack has no management token, because the request needs credentials.
- Throws InvalidOperationException if the instance has no UID, because CancelAsync acts on one scheduled activity. Call stack.PublishQueue("<PUBLISH_QUEUE_UID>").
- The SDK does not check whether the activity still has a schedule. The API decides whether it can cancel the activity.
- The SDK throws the client-side exceptions above when you call CancelAsync, before it returns a task. An API rejection surfaces when you await the task.
- Throws ContentstackErrorException when the API rejects the request.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Completes the task when the API responds.
- Otherwise behaves like Cancel.
Warning Canceling a scheduled action removes it from the publish queue. The SDK offers no way to restore the schedule. Schedule the publish or deployment again if you need it.
Example
Basic usage: cancel a scheduled publish
using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
try
{
ContentstackResponse response = await client.Stack("<API_KEY>").PublishQueue("<PUBLISH_QUEUE_UID>").CancelAsync();
Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
// Thrown when the API rejects the request
Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}All parameters: cancel a scheduled action with a query parameter collection
using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Queryable;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
// The CMA reference lists no query parameters for this request. Add any parameter the API accepts.
ParameterCollection collection = new ParameterCollection();
collection.Add("<PARAMETER_NAME>", "<PARAMETER_VALUE>");
try
{
ContentstackResponse response = await client.Stack("<API_KEY>").PublishQueue("<PUBLISH_QUEUE_UID>").CancelAsync(collection);
Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}Fetch
Fetch retrieves one publish, unpublish, or delete activity, or one release deployment, from the publish queue.
| Name | Type | Description |
|---|---|---|
| collection | ParameterCollection? | Adds query parameters to the request. |
Returns: ContentstackResponse. The API response with the requested publish queue activity.
Validation
- Throws InvalidOperationException if the client has no authtoken and the stack has no management token, because the request needs credentials.
- Throws InvalidOperationException if the instance has no UID, because Fetch reads one activity. Call stack.PublishQueue("<PUBLISH_QUEUE_UID>").
- Throws ContentstackErrorException when the API rejects the request.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Sends one GET request to /publish-queue/<PUBLISH_QUEUE_UID>. See Get publish queue activity in the Content Management API (CMA) reference.
- The CMA reference states that this request covers activities from the last 30 days.
- Adds the entries of collection to the query string. null or an empty collection adds none.
- Returns the raw API response.
Example
Basic usage: fetch one publish queue activity
using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
try
{
ContentstackResponse response = client.Stack("<API_KEY>").PublishQueue("<PUBLISH_QUEUE_UID>").Fetch();
Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
// Thrown when the API rejects the request
Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}All parameters: fetch an activity with the branch key
using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Queryable;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
ParameterCollection collection = new ParameterCollection();
collection.Add("include_branch", true);
try
{
ContentstackResponse response = client.Stack("<API_KEY>").PublishQueue("<PUBLISH_QUEUE_UID>").Fetch(collection);
Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}Authentication: use a management token instead of an authtoken
using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
ContentstackClient client = new ContentstackClient();
try
{
ContentstackResponse response = client.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>").PublishQueue("<PUBLISH_QUEUE_UID>").Fetch();
Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}FetchAsync
FetchAsync retrieves one publish, unpublish, or delete activity, or one release deployment, from the publish queue, without blocking the calling thread.
| Name | Type | Description |
|---|---|---|
| collection | ParameterCollection? | Adds query parameters to the request. |
Returns: Task<ContentstackResponse>. The API response with the requested publish queue activity.
Validation
- Throws InvalidOperationException if the client has no authtoken and the stack has no management token, because the request needs credentials.
- Throws InvalidOperationException if the instance has no UID, because FetchAsync reads one activity. Call stack.PublishQueue("<PUBLISH_QUEUE_UID>").
- The SDK throws the client-side exceptions above when you call FetchAsync, before it returns a task. An API rejection surfaces when you await the task.
- Throws ContentstackErrorException when the API rejects the request.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Completes the task when the API responds.
- Otherwise behaves like Fetch.
Example
Basic usage: fetch one publish queue activity
using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
try
{
ContentstackResponse response = await client.Stack("<API_KEY>").PublishQueue("<PUBLISH_QUEUE_UID>").FetchAsync();
Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
// Thrown when the API rejects the request
Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}All parameters: fetch an activity with the branch key
using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Queryable;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
ParameterCollection collection = new ParameterCollection();
collection.Add("include_branch", true);
try
{
ContentstackResponse response = await client.Stack("<API_KEY>").PublishQueue("<PUBLISH_QUEUE_UID>").FetchAsync(collection);
Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}FindAll
FindAll retrieves the publish, unpublish, and delete activities of the stack, including release deployments.
| Name | Type | Description |
|---|---|---|
| collection | ParameterCollection? | Adds query parameters, for example include_branch. |
Returns: ContentstackResponse. The API response with the publish queue activities.
Validation
- Throws InvalidOperationException if the client has no authtoken and the stack has no management token, because the request needs credentials.
- Throws InvalidOperationException if the instance has a UID, because FindAll lists the whole publish queue. Call stack.PublishQueue() with no UID.
- Throws ContentstackErrorException when the API rejects the request.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Sends one GET request to /publish-queue. See Get publish queue in the Content Management API (CMA) reference.
- The CMA reference states that the publish queue covers activities from the last 90 days.
- Adds the entries of collection to the query string. null or an empty collection adds none.
- Returns the raw API response.
Example
Basic usage: list the publish queue
using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
try
{
ContentstackResponse response = client.Stack("<API_KEY>").PublishQueue().FindAll();
Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
// Thrown when the API rejects the request
Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}All parameters: list the publish queue with the branch key
using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Queryable;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
ParameterCollection collection = new ParameterCollection();
collection.Add("include_branch", true);
try
{
ContentstackResponse response = client.Stack("<API_KEY>").PublishQueue().FindAll(collection);
Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}Authentication: use a management token instead of an authtoken
using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
ContentstackClient client = new ContentstackClient();
try
{
ContentstackResponse response = client.Stack("<API_KEY>", "<MANAGEMENT_TOKEN>").PublishQueue().FindAll();
Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}FindAllAsync
FindAllAsync retrieves the publish, unpublish, and delete activities of the stack, including release deployments, without blocking the calling thread.
| Name | Type | Description |
|---|---|---|
| collection | ParameterCollection? | Adds query parameters, for example include_branch. |
Returns: Task<ContentstackResponse>. The API response with the publish queue activities.
Validation
- Throws InvalidOperationException if the client has no authtoken and the stack has no management token, because the request needs credentials.
- Throws InvalidOperationException if the instance has a UID, because FindAllAsync lists the whole publish queue. Call stack.PublishQueue() with no UID.
- The SDK throws the client-side exceptions above when you call FindAllAsync, before it returns a task. An API rejection surfaces when you await the task.
- Throws ContentstackErrorException when the API rejects the request.
Additional Resource Refer to Content Management API Errors for the full error code list.
Behavior
- Completes the task when the API responds.
- Otherwise behaves like FindAll.
Example
Basic usage: list the publish queue
using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
try
{
ContentstackResponse response = await client.Stack("<API_KEY>").PublishQueue().FindAllAsync();
Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
// Thrown when the API rejects the request
Console.WriteLine($"Request failed: {(int)e.StatusCode} {e.ErrorCode} {e.ErrorMessage}");
}All parameters: list the publish queue with the branch key
using System;
using Contentstack.Management.Core;
using Contentstack.Management.Core.Exceptions;
using Contentstack.Management.Core.Queryable;
ContentstackClient client = new ContentstackClient("<AUTHTOKEN>");
ParameterCollection collection = new ParameterCollection();
collection.Add("include_branch", true);
try
{
ContentstackResponse response = await client.Stack("<API_KEY>").PublishQueue().FindAllAsync(collection);
Console.WriteLine(response.OpenJsonObjectResponse().ToJsonString());
}
catch (ContentstackErrorException e)
{
Console.WriteLine(e.ErrorMessage);
}