About the Tasks API
With Tasks, site admins can efficiently create and manage tasks on a site. This enables site admins to organize and prioritize their daily activities, enhancing their customer relationship management. Tasks include activities such as follow up calls or emails, scheduling meetings with clients, tracking steps for customer onboarding, and more.
The Tasks API allows you to:
- Create and update tasks with the option to set a due date or to link the task to a contact.
- Count the total amount of tasks you have, or count the amount of tasks based on provided filters. For example, you can count the number of tasks that are linked to a specific contact.
- Retrieve tasks.
- Prioritize your tasks by adjusting the display order.
- Delete tasks you no longer need.
Terminology
- Task: A specific activity, action, or assignment that needs to be completed by a site admin.
- Reminder notification: A notification that is sent if the task has a due date. The reminder is sent the day before the due date and on the due date.
Setup
To use the Tasks API, install the @wix/crm
package using npm or Yarn:
1npm install @wix/crm
or
1yarn add @wix/crm
Then import { tasks }
from @wix/crm
:
1import { tasks } from '@wix/crm'
Counts the number of tasks.
This endpoint returns the count of all tasks regardless of the task status
.
Optionally, you can pass a filter to count only tasks based on specified criteria.
Permission Scopes
For app development, you must have one of the following permission scopes:function countTasks(options: CountTasksOptions): Promise<CountTasksResponse>
Creates a new task.
All fields in the task
object are optional. If you don't pass any fields in the task
object, the function returns a task with the following core properties:
_id
_createdDate
_updatedDate
status
source
revision
Permission Scopes
For app development, you must have one of the following permission scopes:function createTask(task: Task): Promise<Task>
Deletes a task by ID.
Permission Scopes
For app development, you must have one of the following permission scopes:function deleteTask(taskId: string): Promise<void>
Retrieves a task by ID.
Permission Scopes
For app development, you must have one of the following permission scopes:function getTask(taskId: string): Promise<Task>
Moves a task specified by ID to be placed after another task in the display.
You can reposition a task to be first in the display by ommitting beforeTaskId
.
Permission Scopes
For app development, you must have one of the following permission scopes:function moveTaskAfter(taskId: string, options: MoveTaskAfterOptions): Promise<void>
Creates a query to retrieve a list of tasks.
The queryTasks()
function builds a query to retrieve a list of tasks and returns a TasksQueryBuilder
object.
The returned object contains the query definition which is typically used to run the query using the find()
function. You can refine the query by chaining TasksQueryBuilder
functions onto the query. TasksQueryBuilder
functions enable you to sort, filter, and control the results that queryTasks()
returns.
queryTasks()
runs with these TasksQueryBuilder
defaults, which you can override:
limit(50)
descending('_createdDate')
The functions that are chained to queryTasks()
are applied in the order they are called. For example, if you apply ascending('_createdDate')
and then descending('_updatedDate')
, the results are sorted first by the created date and then, if there are multiple results with the same date, the items are sorted by the updated date.
The following TasksQueryBuilder
functions are supported for queryTasks()
. For a full description of the task
object, see the object returned for the items
property in TasksQueryResult
.
PROPERTY | SUPPORTED FILTERS & SORTING |
---|---|
_id | eq() ,ne() ,in() ,ascending() ,descending() |
_createdDate | eq() ,ne() ,gt() ,lt() ,ge() ,le() ,ascending() ,descending() |
_updatedDate | eq() ,ne() ,gt() ,lt() ,ge() ,le() ,ascending() ,descending() |
dueDate | eq() ,ne() ,gt() ,lt() ,ge() ,le() ,ascending() ,descending() |
status | eq() ,ne() ,in() |
contact.id | eq() ,ne() ,in() ,exists() |
Permission Scopes
For app development, you must have one of the following permission scopes:function queryTasks(): TasksQueryBuilder
Updates a task.
Each time the task is updated, revision
increments by 1.
The existing revision
must be included when updating the task.
This ensures you're working with the latest task
and prevents unintended overwrites.
Permission Scopes
For app development, you must have one of the following permission scopes:function updateTask(_id: string, task: UpdateTask): Promise<Task>