About the Background Tasks API

The Background Tasks API allows you to create and manage tasks that process data items. Tasks run in the background, so they don't block the user's ability to work on their site while items are processed.

Each task has a different type, which determines the kind of processing the task performs on the items of the specified collection. You can create tasks to:

  • Copy data from one field to another for all items in a collection.
  • Update field data for items that match a specified filter.
  • Delete all items in a collection that match a specified filter.
  • Update the publish status for items that match a specified filter.

Before you begin

It's important to note the following points before starting to code:

  • To enable Wix Data APIs to interact with a site, its code editor must be enabled.
  • To run a task of the type UPDATE_PUBLISH_STATUS, the collection must have the Publish plugin to control item visibility.

Use cases

Terminology

  • Field: Where item content is stored in a collection. Collections can have multiple fields. Learn more about collection fields.
  • Field type: The kind of content each field can contain. Learn more about field types.
  • Collection environment: Each collection can have two separate versions, one for testing and one for the live site. Learn more about working with sandbox and live collections.
  • Publish plugin: Allows items in a data collection to be marked as draft or published. Published items are visible to site visitors, while draft items are not. Learn more about controlling live site item visibility.
Did this help?

Sample Flows

This article presents possible sample flows that you can support. This can be a helpful jumping-off point as you plan your implementation.

Note: Learn more about querying data collections using API Query Language.

Set items' Publish status

On a data collection that has the Publish plugin, create a task to publish all special-edition holiday items at the specified time:

  1. Call Create Task and specify the following parameters:

    Copy
    { "task": { "type": "UPDATE_PUBLISH_STATUS", "updatePublishStatusOptions": { "dataCollectionId": "products", "filter": { "holidays": { "$in": ["Halloween"] } }, "operation": "SCHEDULE_PUBLISHED_STATUS", "schedulePublishedStatusOptions": { "date": "2024-10-24T10:00:00Z" } } } }

    The method returns the following response:

    Copy
    { "task": { "id": "b8815393-3bca-4de7-b592-53eeb1465a61", "type": "UPDATE_PUBLISH_STATUS", "status": "NEW", "startedAt": "2024-09-05T10:34:59.507Z", "estimatedItemCount": 5, "itemsSucceeded": 0, "itemsFailed": 0, "failures": [], "updatePublishStatusOptions": { "dataCollectionId": "Products", "filter": { "holidays": { "$in": ["Halloween"] } }, "operation": "SCHEDULE_PUBLISHED_STATUS", "schedulePublishedStatusOptions": { "date": "2024-10-24T10:00:00Z" } } } }
  2. At any point, you can check the task status by calling the Get Task method with the task ID.

    The method returns a response such as:

    Copy
    { "task": { "id": "b8815393-3bca-4de7-b592-53eeb1465a61", "type": "SCHEDULE_PUBLISHED_STATUS", "status": "FAILED", "startedAt": "2024-09-05T10:34:59.507Z", "finishedAt": "2024-09-05T10:35:03.654Z", "estimatedItemCount": 4, "itemsSucceeded": 0, "itemsFailed": 4, "failures": [ { "code": 404, "description": "Collection not found.", "data": { "dataCollectionId": "Products" } } ], "updatePublishStatusOptions": { "dataCollectionId": "Products", "filter": { "holidays": { "$in": ["Halloween"] } }, "operation": "SCHEDULE_PUBLISHED_STATUS", "schedulePublishedStatusOptions": { "date": "2024-10-24T10:00:00Z" } } } }

Delete items by query

Create a task to retrieve and delete all products from a specified manufacturer:

  1. Call Create Task and specify the following parameters:

    Copy
    { "task": { "type": "DELETE_BY_QUERY", "deleteByQueryOptions": { "dataCollectionId": "Products", "filter": { "manufacturer": "BadAcme" } } } }

    The method might return the following response:

    Copy
    { "task": { "id": "097a5564-0fec-4425-8d1e-3e753b48a422", "type": "DELETE_BY_QUERY", "status": "NEW", "startedAt": "2024-09-05T10:34:59.507Z", "estimatedItemCount": 3, "itemsSucceeded": 0, "itemsFailed": 0, "failures": [], "deleteByQueryOptions": { "dataCollectionId": "Products", "filter": { "manufacturer": "BadAcme" } } } }
  2. At any point, you can check the task status by calling the Get Task method with the task ID.

The method returns a response such as:

Copy
{ "task": { "id": "097a5564-0fec-4425-8d1e-3e753b48a422", "type": "DELETE_BY_QUERY", "status": "COMPLETED", "startedAt": "2024-09-05T10:34:59.507Z", "finishedAt": "2024-09-05T10:35:03.654Z", "estimatedItemCount": 3, "itemsSucceeded": 3, "itemsFailed": 0, "failures": [], "deleteByQueryOptions": { "dataCollectionId": "Products", "filter": { "manufacturer": "BadAcme" } } } }
Did this help?

Background Task Object


Background task job that processes data items in bulk.

Properties
idstringRead-onlyformat GUID

Task ID.


typestring

Task type.


statusstringRead-only

Task status.


startedAtstringRead-onlyformat date-time

Task start time. Empty if the task status is NEW.


finishedAtstringRead-onlyformat date-time

Task finish time. Empty until the task status updates to COMPLETED or FAILED.


itemsFailedintegerRead-only

Number of items whose processing failed.


failuresArray <ApplicationError>Read-onlymaxItems 100

List of errors generated during the task.

Learn more about Wix Data error codes.


estimatedItemCountintegerRead-only

Estimated number of items affected by the task.


itemsSucceededintegerRead-only

Number of items successfully processed so far.


ONE OF:

deleteByQueryOptionsDeleteByQueryOptionsbeta

Options for tasks of the type DELETE_BY_QUERY.


copyFieldDataOptionsCopyFieldDataOptionsbeta

Options for tasks of the type COPY_FIELD_DATA.


editFieldDataOptionsEditFieldDataOptionsbeta

Options for tasks of the type EDIT_FIELD_DATA.


updatePublishStatusOptionsUpdatePublishStatusOptionsbeta

Options for tasks of the type UPDATE_PUBLISH_STATUS.

Task
JSON
{ "id": "097a5564-0fec-4425-8d1e-3e753b48a422", "type": "DELETE_BY_QUERY", "status": "COMPLETED", "startedAt": "2024-09-05T10:34:59.507Z", "finishedAt": "2024-09-05T10:35:03.654Z", "itemCount": 3, "itemsSucceeded": 3, "itemsFailed": 0, "failures": [], "deleteByQueryOptions": { "dataCollectionId": "Items", "environment": "LIVE", "filter": { "altText": { "$contains": "Placeholder" } } } }
Did this help?

GET

List Tasks


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Lists all existing tasks.

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage All Data Resources
Manage Data Items
Write Data Items
Learn more about app permissions.
Endpoint
GET
https://www.wixapis.com/cms/v1/tasks

Query Params
paging.limitintegerminimum 0format int32

Number of items to load.


paging.offsetintegerminimum 0format int32

Number of items to skip in the current sort order.

Response Object
tasksArray <Task>

Retrieved tasks.


metadataMetadata

Paging metadata.

List tasks
Request
cURL
curl GET https://wixapis.com/autocms/v1/tasks?paging.offset=5 \ -H 'Authorization: <AUTH>'
Response
JSON
{ "tasks": [ { "id": "097a5564-0fec-4425-8d1e-3e753b48a422", "type": "DELETE_BY_QUERY", "status": "NEW", "startedAt": "2024-09-05T10:34:59.507Z", "estimatedItemCount": 3, "itemsSucceeded": 0, "itemsFailed": 0, "failures": [], "deleteByQueryOptions": { "dataCollectionId": "Items", "environment": "LIVE", "filter": { "holidays": { "$in": ["Halloween"] } } } }, { "id": "097a5564-0fec-4425-8d1e-3e753b48a422", "type": "EDIT_FIELD_DATA", "status": "NEW", "startedAt": "2024-09-05T10:34:59.507Z", "estimatedItemCount": 3, "itemsSucceeded": 0, "itemsFailed": 0, "failures": [], "editFieldDataOptions": { "dataCollectionId": "Items", "environment": "LIVE", "filter": { "holidays": { "$in": ["Halloween"] } }, "fieldKey": "tags", "operations": { "addItems": ["sale"], "removeItems": ["outdated"], "replaceItems": [ { "from": "Goob", "to": "Good" } ], "removeDuplicates": true } } } ], "metadata": { "count": 0, "offset": 5, "total": 0 } }
Did this help?

POST

Create Task


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Creates and runs a new background task.

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage All Data Resources
Manage Data Items
Write Data Items
Learn more about app permissions.
Endpoint
POST
https://www.wixapis.com/cms/v1/tasks

Body Params
taskTaskRequired

Task to create and run.

Response Object
taskTask

Created task.

Request
cURL
curl POST https://wixapis.com/autocms/v1/tasks \ -H 'Authorization: <AUTH>' \ -H 'Content-Type: application/json' \ -d '{ "task": { "type": "DELETE_BY_QUERY", "deleteByQueryOptions": { "dataCollectionId": "Items", "environment": "LIVE", "filter": { "holidays": { "$in": ["Halloween"] } }, } } }'
Response
JSON
{ "task": { "id": "097a5564-0fec-4425-8d1e-3e753b48a422", "type": "DELETE_BY_QUERY", "status": "NEW", "startedAt": "2024-09-05T10:34:59.507Z", "estimatedItemCount": 3, "itemsSucceeded": 0, "itemsFailed": 0, "failures": [], "deleteByQueryOptions": { "dataCollectionId": "Items", "environment": "LIVE", "filter": { "altText": { "$in": "Halloween" } } } } }
Did this help?

GET

Get Task


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Retrieves the specified task.

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage All Data Resources
Manage Data Items
Write Data Items
Learn more about app permissions.
Endpoint
GET
https://www.wixapis.com/cms/v1/tasks/{taskId}

Path Params
taskIdstringRequired

Task ID.

Response Object
taskTask

Retrieved task.

Get a Task
Request
cURL
curl GET https://wixapis.com/autocms/v1/tasks/097a5564-0fec-4425-8d1e-3e753b48a422 \ -H 'Authorization: <AUTH>'
Response
JSON
{ "task": { "id": "097a5564-0fec-4425-8d1e-3e753b48a422", "type": "DELETE_BY_QUERY", "status": "COMPLETED", "startedAt": "2024-09-05T10:34:59.507Z", "finishedAt": "2024-09-05T10:35:03.654Z", "estimatedItemCount": 3, "itemsSucceeded": 3, "itemsFailed": 0, "failures": [], "deleteByQueryOptions": { "dataCollectionId": "Items", "environment": "LIVE", "filter": { "holidays": { "$in": ["Halloween"] } } } } }
Did this help?

DELETE

Cancel Task


Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Cancels an existing task.

Authentication

You can only call this method when authenticated as a Wix app or Wix user identity.

Permissions
Manage All Data Resources
Manage Data Items
Write Data Items
Learn more about app permissions.
Endpoint
DELETE
https://www.wixapis.com/cms/v1/tasks/{taskId}

Path Params
taskIdstringRequired

Task ID.

Response Object
taskTask

Cancelled task.

Cancel a Task
Request
cURL
curl DELETE https://wixapis.com/autocms/v1/tasks/097a5564-0fec-4425-8d1e-3e753b48a422 \ -H 'Authorization: <AUTH>'
Response
JSON
{ "task": { "id": "097a5564-0fec-4425-8d1e-3e753b48a422", "type": "DELETE_BY_QUERY", "status": "FAILED", "startedAt": "2024-09-05T10:34:59.507Z", "finishedAt": "2024-09-05T10:35:03.654Z", "estimatedItemCount": 3, "itemsProcessed": 3, "itemsFailed": 0, "failures": [ { "code": "CANCELLED", "description": "Cancelled" } ], "deleteByQuery": { "collectionName": "Items", "filter": { "holidays": { "$in": ["Halloween"] } } } } }
Did this help?