Задачи: обзор методов

Задачи в Битрикс24 — единое пространство, которое помогает организовать работу команды: поручать небольшие задания и управлять крупными проектами. В задачах можно отслеживать процесс работы сотрудников, контролировать сроки и распределять обязанности.

Быстрый переход: все методы и события

Пользовательская документация: задачи Битрикс24

Особенности методов задачОсобенности методов задач

В методах задач нужно соблюдать порядок следования параметров в запросе, указанный в таблицах параметров. Иначе запрос выполнится с ошибками.

Задачи в REST 3.0Задачи в REST 3.0

В REST 3.0 методы задач получили обновленную архитектуру, унифицированный формат ответов и поддержку связей между объектами. Сейчас REST 3.0 охватывает базовые операции над задачами, работу с чатом задачи, прикрепление файлов, результаты задачи и методы получения схемы полей (*.field.list / *.field.get).

Карточка задачиКарточка задачи

Карточку задачи можно разделить на блоки:

• описание
• системные и пользовательские поля
• чат задачи
• история и учет времени

Описание задачи содержит информацию о том, что нужно сделать. К тексту можно добавить чек-листы, файлы и связи с другими задачами.

Чек-листы помогут составить список шагов для выполнения задачи. Управлять чек-листами можно с помощью группы методов task.checklistitem.*.

Если нужно не заполнять одни и те же поля вручную для повторяющихся задач, используйте шаблоны задач. Шаблон позволяет заранее сохранить название, описание, участников, сроки, проект, чек-лист и другие параметры будущей задачи.

Связь с задачами создавайте методом task.dependence.add. Удаляйте — методом task.dependence.delete.

При создании задачи заполните системные поля: укажите исполнителя, наблюдателей, крайний срок выполнения, теги и так далее.

Если системных полей недостаточно, вы можете создать собственные пользовательские поля. Они позволяют хранить информацию в различных форматах данных: строка, число, дата со временем и да/нет. Создавать, изменять, получать или удалять пользовательские поля задач можно группой методов task.item.userfield.*.

В новой карточке задач обсуждение ведется в чате задачи. С версии модуля tasks 25.700.0 комментарии переведены в чат, поэтому для работы с сообщениями используйте методы чата задач и мессенджера. Подробности смотрите в статье Новая карточка задач: обзор изменений.

Итог работы над задачей можно записать в комментарий и зафиксировать как результат. Управляйте результатами задачи группой методов tasks.task.result.*.

Учет времени в задачах отслеживает время, затраченное сотрудником на задачу. Работать с записями о затраченном времени можно с помощью группы методов task.elapseditem.*.

Все действия с задачей фиксируются и сохраняются в истории задачи. Чтобы получить историю используйте метод tasks.task.history.list.

В REST 3.0 структура карточки остается прежней, но меняются модель данных и работа со связями. Полный состав полей новой версии описан в статье Поля задачи v 3.0.

Связь задач с другими объектамиСвязь задач с другими объектами

Родительская задача. У задачи могут быть подзадачи. В этом случае она считается родительской. Добавить привязку к родительской задаче можно в параметре PARENT_ID. Получить идентификатор задачи можно методом создания задачи или получения списка задач.

Группа или проект. Задача привязывается по идентификатору группы GROUP_ID. Получить идентификатор можно методом создания новой группы или методом получения списка групп.

Пользователь. Задача имеет привязку к пользователям по числовым идентификаторам в полях:

• CREATED_BY — постановщик
• RESPONSIBLE_ID — исполнитель
• ACCOMPLICES — соисполнители
• AUDITORS — наблюдатели
• CHANGED_BY — последний пользователь, который изменил задачу
• STATUS_CHANGED_BY — последний пользователь, который изменил статус задачи
• CLOSED_BY — пользователь, который завершил задачу

Получить идентификатор пользователя можно с помощью метода user.get.

CRM. К задаче можно привязать объекты CRM: контакты, компании, лиды, сделки, счета и смарт-процессы. Чтобы привязать объект, укажите в параметре UF_CRM_TASK его идентификатор с префиксом. Например, C_3 для контакта с id = 3. Получить идентификатор можно методом создания нового элемента CRM или методом получения списка элементов.

Почта. Задача может быть связана с письмом по идентификатору через параметр UF_MAIL_MESSAGE.

В REST 3.0 связи передаются в новой модели полей: parentId, groupId, crmItemIds, emailId, flowId, chatId. Также в новой модели отдельно доступны связи с пользователями через поля creatorId, responsibleId, accomplices, auditors, changedById, statusChangedById, closedById.

Метод tasks.task.get позволяет получать данные связанных объектов через select, например "select": ["parent.title", "responsible.name", "group.name", "chat.id"]. Данные учета времени также доступны в новой модели через elapsedTime.

Файлы ДискаФайлы Диска

К описанию задачи можно прикрепить файлы Диска. В параметре UF_TASK_WEBDAV_FILES передайте массив с идентификаторами файлов Диска. Перед каждым идентификатором укажите префикс n, например: "UF_TASK_WEBDAV_FILES": ["n428", "n345"]. Получить идентификаторы файлов можно двумя способами.

Использовать один из методов загрузки файла:

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

Использовать один из методов получения списка файлов:

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

Прикрепляйте файлы к задаче методом tasks.task.files.attach, если задача уже создана.

В REST 3.0 для уже созданной задачи используйте метод tasks.task.file.attach.

ПотокиПотоки

Потоки — это инструмент, который автоматизирует распределение и выполнение задач. Сотрудникам не нужно искать, кто будет делать задачу. Они ставят задачи в поток отдела, и он автоматически назначает исполнителя.

Управлять Потоками можно группой методов tasks.flow.Flow.*.

Задачи в СкрамеЗадачи в Скраме

Задачи в Скраме — это стандартные задачи Битрикс24 с расширенными возможностями для работы по методологии Скрам. В скраме команда может:

• оценивать сложность задач с помощью сторипоинтов
• прикреплять задачи к эпикам
• размещать задачи в бэклоге и спринтах
• передвигать задачи по стадиям спринта в процессе работы

Подробнее о Скраме и его методах — в статье Скрам: обзор методов.

Режимы работы с задачамиРежимы работы с задачами

Канбан — это инструмент, который помогает визуально представить работу с задачами в виде колонок и карточек. Колонки — это стадии работы, карточки — задачи. Канбан используется для работы с задачами в группах и проектах.

«Мой план» — это режим управления своими задачами в виде канбана. У каждого сотрудника будут свои стадии «Моего плана».

Управлять стадиями канбана и «Моего плана» можно группой методов task.stages.*.

Задачи в «Плане на день»Задачи в «Плане на день»

«План на день» — это список дел, задач и встреч, которые вы запланировали на рабочий день. Метод task.planner.getlist получает список задач из «Плана на день».

ВиджетыВиджеты

В карточку задачи можно встроить приложение. Благодаря встраиванию можно будет использовать приложение и не покидать карточку.

• Вкладка в карточке задачи TASK_VIEW_TAB
• Правая панель карточки задачи TASK_VIEW_SIDEBAR
• Ссылка в верхней части карточки задачи TASK_VIEW_TOP_PANEL

Приложение можно встроить в списке задач:

• Пункт контекстного меню списка TASK_LIST_CONTEXT_MENU

В режимах работы с задачами канбан или «Мой план» есть еще два специальных места для встройки:

• Пункт основного выпадающего меню TASK_USER_LIST_TOOLBAR, TASK_GROUP_LIST_TOOLBAR
• Пункт основного выпадающего меню около настроек роботов TASK_ROBOT_DESIGNER_TOOLBAR

В новой карточке задач с версии модуля tasks 25.700.0 места TASK_VIEW_TAB, TASK_VIEW_SIDEBAR и TASK_VIEW_TOP_PANEL объединены в блок «Приложения» в нижней части карточки.

Чат задачи в REST 3.0Чат задачи в REST 3.0

Обсуждение задачи в REST 3.0 ведется через чат. Метод tasks.task.chat.message.send отправляет сообщение в чат задачи.

Для работы с сообщениями также используйте методы мессенджера:

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

Обзор методов и событийОбзор методов и событий

Scope:

• task — для методов прежней версии API
• tasks — для методов REST 3.0

Кто может выполнять метод: в зависимости от метода

ОсновныеОсновные

Смена статуса задачиСмена статуса задачи

Метод	Описание
tasks.task.start	Переводит задачу в статус «выполняется»
tasks.task.pause	Останавливает выполнение задачи и переводит в статус «ждет выполнения»
tasks.task.defer	Переводит задачу в статус «отложена»
tasks.task.complete	Переводит задачу в статус «завершена»
tasks.task.renew	Возобновляет задачу после ее завершения

Действия пользователя по задачеДействия пользователя по задаче

Метод	Описание
tasks.task.startwatch	Включает наблюдение за задачей
tasks.task.stopwatch	Отключает наблюдение за задачей
tasks.task.favorite.add	Добавляет задачу в избранное
tasks.task.favorite.remove	Удаляет задачу из избранного
tasks.task.pin	Закрепляет задачу в списке
tasks.task.unpin	Открепляет задачу в списке
tasks.task.mute	Включает режим «Без звука»
tasks.task.unmute	Выключает режим «Без звука»

Результат задачиРезультат задачи

Метод	Описание
tasks.task.result.addFromComment	Добавляет комментарий в результат
tasks.task.result.list	Получает список результатов задачи
tasks.task.result.deleteFromComment	Удаляет комментарий из результата задачи
tasks.task.result.add	Добавляет результат к задаче
tasks.task.result.addfromchatmessage	Создает результат из сообщения чата задачи
tasks.task.result.update	Обновляет текст результата
tasks.task.result.list	Получает список результатов задачи v 3.0
tasks.task.result.delete	Удаляет результат задачи

Чек-листыЧек-листы

Метод	Описание
task.checklistitem.add	Добавляет новый элемент чек-листа к задаче
task.checklistitem.update	Обновляет данные элемента чек-листа
task.checklistitem.get	Получает элемент чек-листа по его id
task.checklistitem.getlist	Получает список элементов чек-листа в задаче
task.checklistitem.moveafteritem	Помещает элемент чек-листа в списке после указанного
task.checklistitem.complete	Отмечает элемент чек-листа как выполненный
task.checklistitem.renew	Отмечает выполненный элемент чек-листа как вновь активный
task.checklistitem.delete	Удаляет элемент чек-листа
task.checklistitem.isactionallowed	Проверяет, разрешено ли действие для элемента чек-листа
task.checklistitem.getmanifest	Получает список методов и их описание

КомментарииКомментарии

Метод	Описание
task.commentitem.add	Создает новый комментарий к задаче
task.commentitem.update	Обновляет данные комментария
task.commentitem.get	Получает комментарий к задаче
task.commentitem.getlist	Получает список комментариев к задаче
task.commentitem.delete	Удаляет комментарий

Затраченное времяЗатраченное время

Метод	Описание
task.elapseditem.add	Добавляет затраченное время к задаче
task.elapseditem.update	Обновляет параметры записи о затраченном времени
task.elapseditem.get	Получает запись о затраченном времени по ее идентификатору
task.elapseditem.getlist	Получает список записей о затраченном времени по задаче
task.elapseditem.delete	Удаляет запись о затраченном времени
task.elapseditem.isactionallowed	Проверяет разрешено ли действие
task.elapseditem.getmanifest	Получает список методов и их описание

Пользовательские поляПользовательские поля

Метод	Описание
task.item.userfield.add	Создает новое поле
task.item.userfield.update	Обновляет параметры поля
task.item.userfield.get	Получает поле по идентификатору
task.item.userfield.getlist	Получает список полей
task.item.userfield.delete	Удаляет поле
task.item.userfield.gettypes	Получает все доступные типы данных
task.item.userfield.getfields	Получает все доступные поля пользовательского поля

Стадии канбана и «Моего плана»Стадии канбана и «Моего плана»

Метод	Описание
task.stages.add	Добавляет стадии канбана или «Моего плана»
task.stages.update	Обновляет стадии канбана или «Моего плана»
task.stages.get	Получает стадии канбана или «Моего плана»
task.stages.canmovetask	Определяет, может ли текущий пользователь перемещать задачи в указанном объекте
task.stages.movetask	Перемещает задачи из одной стадии в другую
task.stages.delete	Удаляет стадии канбана или «Моего плана»

Задачи в «Плане на день»Задачи в «Плане на день»

Метод	Описание
task.planner.getList	Получает список задач из «Плана на день»

ПотокиПотоки

Метод	Описание
tasks.flow.Flow.create	Создать поток
tasks.flow.Flow.get	Получить поток
tasks.flow.Flow.update	Изменить поток
tasks.flow.Flow.delete	Удалить поток
tasks.flow.Flow.isExists	Проверить, существует ли поток с таким названием
tasks.flow.Flow.activate	Включить или выключить поток