Tasks: method overview

Tasks in Bitrix24 are a unified workspace that helps organize team workflows: assigning small assignments and managing large projects. With tasks, you can track employee progress, monitor deadlines, and distribute responsibilities.

Quick links: all methods and events

User documentation: Create a task

Task method featuresTask method features

When using task methods, you must follow the parameter order specified in the parameter tables. Otherwise, the request will execute with errors.

Tasks in REST 3.0Tasks in REST 3.0

In REST 3.0, task methods use an updated architecture, a unified response format, and support connections between objects. REST 3.0 currently covers basic task operations, task chat, file attachment, task results, and field schema methods (*.field.list / *.field.get).

Task cardTask card

A task card can be divided into blocks:

• description
• system and user fields
• task chat
• history and time tracking

The task description contains information about what needs to be done. You can add checklists, files, and links to other tasks to the text.

Checklists help create a list of steps to complete a task. You can manage checklists using the task.checklistitem.* method group.

If you need to avoid filling in the same fields manually for recurring tasks, use task templates. A template allows you to pre-save the title, description, participants, deadlines, project, checklist, and other parameters of a future task.

Create a link to tasks using the task.dependence.add method. Delete them using the task.dependence.delete method.

When creating a task, fill in the system fields: specify the responsible person, observers, deadline, tags, and so on.

If system fields are not enough, you can create your own user fields. They allow you to store information in various data formats: string, number, date with time, and yes/no. You can create, change, retrieve, or delete task user fields using the task.item.userfield.* method group.

In the new task card, discussions take place in the task chat. Since module version tasks 25.700.0, comments have been moved to the chat, so use task chat and messenger methods to work with messages. See details in the article New task card: overview of changes.

The result of working on a task can be written in a comment and recorded as a result. Manage task results using the tasks.task.result.* method group.

Time tracking in tasks monitors the time spent by an employee on a task. You can work with time tracking records using the task.elapseditem.* method group.

All actions with a task are recorded and retained in the task history. To retrieve the history, use the tasks.task.history.list method.

In REST 3.0, the task card structure remains the same, but the data model and work with relations are changed. The full field set of the new version is described in Task Fields v 3.0.

Connection with Other ObjectsConnection with Other Objects

Parent task. A task can have subtasks. In this case, it is considered a parent task. You can add a link to a parent task in the PARENT_ID parameter. You can retrieve a task identifier using the task creation method or the task list retrieval method.

Group or project. A task is linked by the group identifier GROUP_ID. You can retrieve the identifier using the new group creation method or the group list retrieval method.

User. A task is linked to users via numeric identifiers in the following fields:

• CREATED_BY — creator
• RESPONSIBLE_ID — assignee
• ACCOMPLICES — participants
• AUDITORS — observers
• CHANGED_BY — last user who changed the task
• STATUS_CHANGED_BY — last user who changed the task status
• CLOSED_BY — user who completed the task

You can retrieve a user identifier using the user.get method.

CRM. You can link CRM objects to a task: contacts, companies, leads, deals, invoices, and SPAs. To link an object, specify its identifier with a prefix in the UF_CRM_TASK parameter. For example, C_3 for contact with id = 3. You can retrieve the identifier using the create new CRM item method or the retrieve item list method.

Webmail. A task can be linked to an email by identifier via the UF_MAIL_MESSAGE parameter.

In REST 3.0, relations are passed in the new field model: parentId, groupId, crmItemIds, emailId, flowId, and chatId. In the new model, user relations are also available separately through the fields creatorId, responsibleId, accomplices, auditors, changedById, statusChangedById, and closedById.

The tasks.task.get method can get related object data through select, for example "select": ["parent.title", "responsible.name", "group.name", "chat.id"]. Time tracking data is also available in the new model through elapsedTime.

Drive filesDrive files

You can attach Drive files to a task description. In the UF_TASK_WEBDAV_FILES parameter, pass an array of Drive file IDs. Before each ID, specify the prefix n, for example: "UF_TASK_WEBDAV_FILES": ["n428", "n345"]. You can retrieve file identifiers in two ways.

Use one of the file upload methods:

• disk.storage.uploadfile
• disk.folder.uploadfile

Use one of the file list retrieval methods:

• disk.storage.getchildren
• disk.folder.getchildren

Attach files to a task using the tasks.task.files.attach method if the task has already been created.

In REST 3.0, use tasks.task.file.attach for an already created task.

FlowsFlows

Flows are a tool that automates task distribution and execution. Employees do not need to search for who will perform a task. They place tasks into a department flow, and it automatically assigns an executor.

Manage flows using the tasks.flow.Flow.* method group.

Scrum tasksScrum tasks

Scrum tasks are standard Bitrix24 tasks with extended capabilities for working with the Scrum methodology. In Scrum, a team can:

• estimate task complexity using story points
• attach tasks to epics
• place tasks in backlogs and sprints
• move tasks through sprint stages during the work process

For more details about Scrum and its methods, see the article Scrum: methods overview.

Task operating modesTask operating modes

Kanban is a tool that helps visually represent task work in the form of columns and cards. Columns are work stages, and cards are tasks. Kanban is used for working with tasks in groups and projects.

"My plan" is a mode for managing your own tasks in a Kanban view. Each employee will have their own "My plan" stages.

Kanban and "My plan" stages can be managed using the task.stages.* group of methods.

Tasks in "Daily plan"Tasks in "Daily plan"

"Daily plan" is a list of to-dos, tasks, and meetings that you have scheduled for the workday. The task.planner.getlist method retrieves the list of tasks from the "Daily plan".

WidgetsWidgets

An application can be embedded into a task card. Embedding allows you to use the application without leaving the card.

• Widget on the tab of the task card TASK_VIEW_TAB
• Widget in the right sidebar of the task card TASK_VIEW_SIDEBAR
• Widget in the top panel of the task card TASK_VIEW_TOP_PANEL

An application can also be embedded in the task list:

• Context menu item of a task in the list TASK_LIST_CONTEXT_MENU
• Dropdown menu item above the task list TASK_USER_LIST_TOOLBAR, TASK_GROUP_LIST_TOOLBAR
• Button in the task automation rules designer TASK_ROBOT_DESIGNER_TOOLBAR

In the new task card, starting from module version tasks 25.700.0, the TASK_VIEW_TAB, TASK_VIEW_SIDEBAR, and TASK_VIEW_TOP_PANEL embedding locations are combined into the "Applications" block at the bottom of the card.

How to choose a placement and what the handler receives is described in the overview of placements.

Task Chat in REST 3.0Task Chat in REST 3.0

Task discussion in REST 3.0 is performed through the chat. The tasks.task.chat.message.send method sends a message to the task chat.

To work with messages, also use messenger methods:

• im.message.update
• im.message.delete
• im.dialog.messages.get

Overview of Methods and EventsOverview of Methods and Events

Scope:

• task — for methods of the previous API version
• tasks — for REST 3.0 methods

Who can execute the method: depends on the method

BasicBasic

Task Status ChangesTask Status Changes

Method	Description
tasks.task.start	Moves a task to In Progress status
tasks.task.pause	Stops task execution and moves it to Waiting status
tasks.task.defer	Moves a task to Deferred status
tasks.task.complete	Moves a task to Completed status
tasks.task.renew	Renews a task after completion

User Actions on TaskUser Actions on Task

Method	Description
tasks.task.startwatch	Starts watching a task
tasks.task.stopwatch	Stops watching a task
tasks.task.favorite.add	Adds a task to favorites
tasks.task.favorite.remove	Removes a task from favorites
tasks.task.pin	Pins a task in the list
tasks.task.unpin	Unpins a task in the list
tasks.task.mute	Enables silent mode
tasks.task.unmute	Disables silent mode

Task ResultTask Result

Method	Description
tasks.task.result.addFromComment	Adds a comment to the result
tasks.task.result.list	Gets a list of task results
tasks.task.result.deleteFromComment	Removes a comment from the task result
tasks.task.result.add	Adds a result to the task
tasks.task.result.addfromchatmessage	Creates a result from a task chat message
tasks.task.result.update	Updates the result text
tasks.task.result.list	Gets a list of task results v 3.0
tasks.task.result.delete	Deletes a task result

ChecklistsChecklists

Method	Description
task.checklistitem.add	Adds a new checklist item to the task
task.checklistitem.update	Updates checklist item data
task.checklistitem.get	Gets a checklist item by its id
task.checklistitem.getlist	Gets a list of checklist items in the task
task.checklistitem.moveafteritem	Places a checklist item in the list after the specified one
task.checklistitem.complete	Marks a checklist item as completed
task.checklistitem.renew	Marks a completed checklist item as active again
task.checklistitem.delete	Deletes a checklist item
task.checklistitem.isactionallowed	Checks if an action is allowed for a checklist item
task.checklistitem.getmanifest	Gets a list of methods and their descriptions

CommentsComments

Method	Description
task.commentitem.add	Creates a new comment for a task
task.commentitem.update	Updates comment data
task.commentitem.get	Gets a comment for a task
task.commentitem.getlist	Gets a list of comments for a task
task.commentitem.delete	Deletes a comment

Time spentTime spent

Method	Description
task.elapseditem.add	Adds time spent to a task
task.elapseditem.update	Updates parameters of a time spent record
task.elapseditem.get	Gets a time spent record by its identifier
task.elapseditem.getlist	Gets a list of time spent records for a task
task.elapseditem.delete	Deletes a time spent record
task.elapseditem.isactionallowed	Checks if an action is allowed
task.elapseditem.getmanifest	Gets a list of methods and their descriptions

Custom fieldsCustom fields

Method	Description
task.item.userfield.add	Creates a new field
task.item.userfield.update	Updates field parameters
task.item.userfield.get	Gets a field by identifier
task.item.userfield.getlist	Gets a list of fields
task.item.userfield.delete	Deletes a field
task.item.userfield.gettypes	Gets all available data types
task.item.userfield.getfields	Gets all available custom field types

Kanban and "My Plan" stagesKanban and "My Plan" stages

Method	Description
task.stages.add	Adds Kanban or "My Plan" stages
task.stages.update	Updates Kanban or "My Plan" stages
task.stages.get	Gets Kanban or "My Plan" stages
task.stages.canmovetask	Determines if the current user can move tasks in the specified object
task.stages.movetask	Moves tasks from one stage to another
task.stages.delete	Deletes Kanban or "My Plan" stages

Tasks in "Plan for the day"Tasks in "Plan for the day"

Method	Description
task.planner.getList	Gets a list of tasks from "Plan for the Day"

FlowsFlows

Method	Description
tasks.flow.Flow.create	Creates a flow
tasks.flow.Flow.get	Retrieves a flow
tasks.flow.Flow.update	Updates a flow
tasks.flow.Flow.delete	Deletes a flow
tasks.flow.Flow.isExists	Checks whether a flow with this name exists
tasks.flow.Flow.activate	Enables or disables a flow