Введение в модуль Задачи

Модуль Задачи tasks хранит поручения сотрудников и ход их выполнения. В задаче фиксируют, что нужно сделать, кто отвечает за результат, кто помогает и следит за работой, к какому сроку нужен результат. Обсуждение задачи идет в ее чате, а итог работы сохраняют как результат задачи.

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

Модуль Задачи входит в Битрикс24 и отсутствует в стандартной поставке «1С-Битрикс: Управление сайтом».

Когда использовать API модуля

Модуль подходит для следующих сценариев.

  • Создать задачу по событию в другой системе или модуле, например по новой заявке или обращению.

  • Изменить задачу, например перенести срок, сменить ответственного или завершить работу.

  • Выбрать задачи сотрудника или проекта для отчета, виджета или выгрузки.

  • Написать сообщение в чат задачи, прикрепить файлы, учесть затраченное время.

  • Проверить, может ли сотрудник прочитать или изменить задачу.

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

PHP API используют в серверном коде коробочного Битрикс24. Для облачного Битрикс24 и внешних приложений используйте REST API задач.

Основные объекты

Задача — центральный объект модуля. Остальные объекты описывают ее участников, место и ход работы.

Задача — поручение с названием, описанием, сроками и статусом. У каждой задачи есть ID. По нему задачу читают, меняют и связывают с другими объектами.

Участники — сотрудники, которые работают с задачей. Роль участника определяет, что он видит и может менять в задаче.

  • Постановщик — создает задачу. Если у задачи включен контроль, постановщик проверяет и принимает работу.

  • Ответственный — выполняет задачу. У задачи один ответственный.

  • Соисполнители — помогают ответственному. Их может быть несколько.

  • Наблюдатели — следят за ходом работы без права ее выполнять.

Статус — этап выполнения задачи. Задача ждет выполнения, выполняется, завершена, отложена или находится в другом статусе. Статусы и их константы перечислены в статье Поля, участники и статусы задач.

Крайний срок — дата и время, к которым нужен результат. Кроме крайнего срока, у задачи есть плановые даты начала и завершения. В объекте задачи это свойства deadlineTs, startPlanTs и endPlanTs, в классическом API — поля DEADLINE, START_DATE_PLAN и END_DATE_PLAN. Все поля описаны в разделе Основные поля задачи.

Проект — рабочая группа модуля Социальная сеть socialnetwork. Задача может принадлежать проекту. Тогда права на создание и просмотр задачи зависят и от настроек группы.

Поток — общий канал, через который сотрудники ставят однотипные задачи. Настройки потока могут сами назначить ответственного и крайний срок новой задачи. Поток задачи хранит поле FLOW_ID, в объекте задачи — свойство flow.

Чат задачи — чат модуля Веб-мессенджер im, привязанный к задаче. В нем участники обсуждают работу и получают уведомления об изменениях. Как отправить сообщение в чат, описано в статье Чат, результаты, файлы и учет времени.

Результат — сообщение, которое фиксирует итог работы. Постановщик может требовать результат. Тогда ответственный не сможет завершить задачу, пока не добавит его. Требование не действует для постановщика и администратора. Команда завершения требование не проверяет, поэтому перед ее запуском проверьте право Bitrix\Tasks\Access\ActionDictionary::ACTION_TASK_COMPLETE_RESULT, как показано в разделе Завершить задачу с результатом.

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

API модуля

В модуле одновременно работают несколько поколений API. Для нового кода используйте команды и провайдер TaskProvider из пространства имен Bitrix\Tasks\V2\Public.

  • Команды Bitrix\Tasks\V2\Public\Command\... создают, меняют и удаляют задачи и связанные данные. Например, команда Bitrix\Tasks\V2\Public\Command\Task\AddTaskCommand создает задачу, а Bitrix\Tasks\V2\Public\Command\Task\UpdateTaskCommand меняет ее.

  • Провайдер Bitrix\Tasks\V2\Public\Provider\TaskProvider читает задачу и список задач с учетом прав сотрудника методами get() и getList(). Для подсчета задач и пользовательских полей в списках остается класс Bitrix\Tasks\Provider\TaskList с запросом Bitrix\Tasks\Provider\Query\TaskQuery. Подробнее — в статье Чтение и выборка задач.

  • Контроллер доступа Bitrix\Tasks\Access\TaskAccessController проверяет, может ли сотрудник выполнить действие с задачей.

  • События OnTaskAdd, OnTaskUpdate, OnTaskDelete и другие запускают код обработчиков при изменении задачи. Параметры событий описаны в статье События модуля Задачи.

Команды создания, изменения и удаления задачи не проверяют права сотрудника. Перед запуском команды по запросу пользователя выполните два шага.

  • Проверьте доступ методом Bitrix\Tasks\Access\TaskAccessController::can(). Для действия ActionDictionary::ACTION_TASK_SAVE передайте четвертым аргументом модель новых данных Bitrix\Tasks\Access\Model\TaskModel, без нее проверка возвращает false. Порядок проверки описан в разделе Проверить права сотрудника.

  • Запустите команду и проверьте ее результат, как показано в разделе Проверить права и запустить команду.

Класс ORM Bitrix\Tasks\Internals\TaskTable подходит только для чтения. Он не учитывает права сотрудника, а запись через него не создает участников, чат, уведомления и не вызывает события модуля. Подробнее — в разделе Выбрать API для записи.

Метод CTaskCommentItem::add() не создает сообщение, потому что комментарии задачи перенесены в чат. Для сообщений в чат задачи используйте команду Bitrix\Tasks\V2\Public\Command\Task\Chat\SendMessageCommand, подробнее — в разделе Классический API.

Классы CTasks и CTaskItem устарели, но продолжают работать. Для нового кода используйте команды и провайдер.

Чем различаются слои API и какой класс выбрать для конкретного действия, читайте в статье Как выбрать API задач.

Что подготовить для PHP-сценария

Для чтения или изменения задачи нужны два значения.

  • ID задачи — идентификатор существующей задачи.

  • ID пользователя — сотрудник, от имени которого код читает или меняет задачу. Его права определяют, какие задачи доступны коду.

Если код выполняется по запросу сотрудника, передайте ID текущего пользователя. Агент или фоновое задание работают без авторизованного пользователя, поэтому ID сотрудника задайте в коде или в настройках своего модуля.

Первый запрос к задаче

Подготовьте ID существующей задачи и подставьте его вместо 123. Код подключит модуль, прочитает задачу от имени текущего пользователя и выведет ее название и статус.

Перед запуском подключите пролог Bitrix Framework. Модуль tasks пример подключает сам методом Loader::includeModule('tasks').

use Bitrix\Main\Engine\CurrentUser;
use Bitrix\Main\Loader;
use Bitrix\Tasks\V2\Public\Provider\Params\TaskParams;
use Bitrix\Tasks\V2\Public\Provider\TaskProvider;

if (!Loader::includeModule('tasks'))
{
    throw new \RuntimeException('Не удалось подключить модуль Задачи');
}

$taskId = 123;
// В агенте текущего пользователя нет, задайте ID сотрудника явно, например $userId = 45;
$userId = (int)CurrentUser::get()->getId();

if ($userId <= 0)
{
    throw new \RuntimeException('Нет авторизованного пользователя');
}

$task = (new TaskProvider())->get(TaskParams::mapFromIds($taskId, $userId));

if ($task === null)
{
    throw new \RuntimeException('Задача не найдена или нет прав на чтение');
}

echo $task->title . ' — ' . $task->status?->value;

Метод TaskParams::mapFromIds() готовит параметры чтения из ID задачи и ID пользователя. Провайдер проверяет право сотрудника на чтение. Метод get() возвращает объект задачи Bitrix\Tasks\V2\Internal\Entity\Task или null, если задача не найдена или сотрудник не может ее прочитать.

Объект задачи доступен только для чтения. Основные свойства объекта перечислены ниже.

  • title — название задачи.

  • status — статус как enum Bitrix\Tasks\V2\Internal\Entity\Task\Status. Для задач старых версий модуля свойство может содержать null.

  • status->value — строковое значение статуса, например pending или in_progress.

  • deadlineTs — крайний срок как метка времени Unix.

Чтобы изменить задачу, используйте команду UpdateTaskCommand, как описано в статье Создание, изменение и удаление задач.

Границы модуля

Модуль Задачи хранит поручения и ход их выполнения. Часть данных задачи хранят другие модули.

  • Проекты и их участников хранит модуль Социальная сеть socialnetwork.

  • Чат задачи и его сообщения хранит модуль Веб-мессенджер im.

  • Файлы задачи хранит модуль Диск disk. Задача хранит только ссылки на файлы.

  • Сделки, контакты и другие элементы, к которым привязывают задачу, хранит модуль CRM.

Права сотрудника на задачу проверяет модуль Задачи. Общие принципы прав в Bitrix Framework собраны в статье Права доступа.

Выберите следующую статью по задаче.

  1. Как выбрать API задач — разберитесь в слоях API и заменах классических методов.

  2. Создание, изменение и удаление задач — создайте задачу, подзадачу или задачу в проекте без дублей, смените статус, срок или участников.

  3. Чтение и выборка задач — прочитайте задачу, выберите задачи сотрудника или проекта, разбейте список на страницы и посчитайте задачи.

  4. Поля, участники и статусы задач — найдите поля, константы статусов и приоритетов, теги и пользовательские поля.

  5. Чат, результаты, файлы и учет времени — отправьте сообщение, добавьте результат, файл или запись времени.

  6. Права доступа к задачам — проверьте действие от имени сотрудника.

  7. События модуля Задачи — подпишитесь на события, проверьте или отмените изменение задачи и выполните свой код после него.