Работа с задачами в Битрикс24 (Коробка): Подробное руководство для разработчиков

Введение:

Битрикс24 – мощная платформа для управления бизнесом, и модуль «Задачи» является одним из ключевых элементов для организации работы. В «коробочной» версии Битрикс24 разработчики получают прямой доступ к API, что позволяет гибко интегрировать задачи в собственные решения, автоматизировать процессы и создавать кастомные инструменты.

Эта статья – ваш исчерпывающий гид по работе с задачами в Битрикс24 «коробка». Мы рассмотрим все ключевые аспекты: от подключения модуля и использования обработчиков событий до создания сложных фильтров и управления задачами через API. Статья оптимизирована для SEO, чтобы помочь вам быстро найти ответы на свои вопросы и углубить знания в этой области.

1. Подключение модуля задач

Первый шаг к работе с задачами – подключение модуля tasks в вашем PHP-коде. Это необходимо для доступа ко всем классам и функциям API задач.

<?php
// Подключаем модуль "Задачи"
CModule::IncludeModule("tasks");
?>

2. Обработчики событий: Автоматизация рабочих процессов

Обработчики событий (Event Handlers) – мощный инструмент для автоматизации действий в Битрикс24. Они позволяют вашему коду реагировать на определенные события, происходящие в системе. Для задач доступны следующие события:

• OnBeforeTaskAdd: Вызывается непосредственно перед добавлением новой задачи. Это идеальное место для модификации данных задачи до ее сохранения в базе данных.

<?php
// Регистрируем обработчик события OnBeforeTaskAdd
AddEventHandler("tasks", "OnBeforeTaskAdd", "MyOnBeforeTaskAdd");

function MyOnBeforeTaskAdd(&$arTask)
{
    // Пример: Добавляем префикс "[NEW]" к заголовку каждой новой задачи
    $arTask["TITLE"] = "[NEW] " . $arTask["TITLE"];
}
?>

• OnTaskAdd: Срабатывает после успешного добавления задачи. Предоставляет вам ID новой задачи ($idTask) и полный массив данных задачи ($arTask).

<?php
// Регистрируем обработчик события OnTaskAdd
AddEventHandler("tasks", "OnTaskAdd", "MyOnTaskAdd");

function MyOnTaskAdd($idTask, $arTask)
{
    // Пример: Логируем факт создания новой задачи
    CEventLog::Add(array(
        "SEVERITY" => "INFO",
        "AUDIT_TYPE_ID" => "TASKS_TASK_CREATED",
        "MODULE_ID" => "tasks",
        "ITEM_ID" => $idTask,
        "DESCRIPTION" => "Создана задача с ID: " . $idTask
    ));
}
?>

• OnBeforeTaskUpdate: Вызывается перед обновлением существующей задачи. Позволяет изменять данные задачи ($data) и поля задачи ($arFields) непосредственно перед сохранением изменений.

<?php
// Регистрируем обработчик события OnBeforeTaskUpdate
AddEventHandler("tasks", "OnBeforeTaskUpdate", "MyOnBeforeTaskUpdate");

function MyOnBeforeTaskUpdate($id, &$data, &$arTaskCopy)
{
    // Пример: Запрещаем изменение поля "Название" после создания задачи
    unset($data["TITLE"]);
}
?>

• OnTaskUpdate: Срабатывает после обновления задачи. Передает ID обновленной задачи ($ID), массив измененных полей ($arFields) и «копию» задачи до изменений ($arTaskCopy).

<?php
// Регистрируем обработчик события OnTaskUpdate
AddEventHandler("tasks", "OnTaskUpdate", "MyOnTaskUpdate");

function MyOnTaskUpdate($ID, &$arFields, &$arTaskCopy)
{
    // Пример: Логируем изменения статуса задачи
    if (isset($arFields["STATUS"])) {
        CEventLog::Add(array(
            "SEVERITY" => "INFO",
            "AUDIT_TYPE_ID" => "TASKS_TASK_STATUS_CHANGED",
            "MODULE_ID" => "tasks",
            "ITEM_ID" => $ID,
            "DESCRIPTION" => "Статус задачи с ID: " . $ID . " изменен на " . $arFields["STATUS"]
        ));
    }
}
?>

Практический пример обработчика: Автоматическое удаление лишних напоминаний (пингов)

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

<?php
// Регистрируем обработчик OnBeforeTaskAdd
AddEventHandler("tasks", "OnBeforeTaskAdd", "removeRedundantReminders");

function removeRedundantReminders(&$arTask)
{
    // Проверяем, есть ли напоминания и является ли это массивом
    if (isset($arTask['REMINDERS']) && is_array($arTask['REMINDERS']))
    {
        // Проходим по всем напоминаниям
        foreach ($arTask['REMINDERS'] as $key => $reminder)
        {
            // Если тип транспорта - Jabber, удаляем напоминание
            if ($reminder['TRANSPORT'] == CTaskReminders::REMINDER_TRANSPORT_JABBER)
            {
                unset($arTask['REMINDERS'][$key]);
            }
        }
    }
}
?>

Добавление напоминания к задаче программно

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

<?php
// Массив полей для создания напоминания
$arFields = Array(
    "TASK_ID" => $idTask, // ID задачи, к которой добавляем напоминание (переменная $idTask должна быть определена ранее)
    "USER_ID" => $arTask["CREATED_BY"], // ID пользователя-получателя (постановщик задачи)
    "REMIND_DATE" => date("d.m.Y H:i:s", strtotime("+5 hours")), // Дата и время напоминания (за 5 часов до текущего времени)
    "TYPE" => CTaskReminders::REMINDER_TYPE_DEADLINE, // Тип напоминания: к крайнему сроку
    "TRANSPORT" => CTaskReminders::REMINDER_TRANSPORT_JABBER // Тип транспорта: Jabber (можно изменить на CTaskReminders::REMINDER_TRANSPORT_EMAIL для email-уведомлений)
);

// Создаем экземпляр класса CTaskReminders
$obTaskReminders = new CTaskReminders;

// Добавляем напоминание
$ID = $obTaskReminders->Add($arFields);
?>

3. Работа с задачами, связанными с CRM сущностями

В Битрикс24 задачи часто используются в связке с CRM, например, для управления задачами по сделкам или лидам. API позволяет эффективно получать и обновлять такие задачи.

Получение задач, привязанных к CRM сущности (сделка):

<?php
// Фильтруем задачи по тегу и привязке к CRM сделке
$arFilter = array(
    'TAG' => $tag, // Переменная $tag должна содержать тег для поиска задач
    "UF_CRM_TASK" => "D_" . $dealID, // "D_" - префикс для сделок, $dealID - ID сделки
    // "L_" - префикс для лидов, "C_" - для контактов, "CO_" - для компаний
);

// Получаем список задач, отсортированный по крайнему сроку
$res = CTasks::GetList(
    Array("DEADLINE" => "ASC"), // Сортировка по полю DEADLINE в порядке возрастания
    $arFilter, // Применяем фильтр для отбора задач
    Array("ID", "TITLE", "DEADLINE"), // Выбираем поля ID, TITLE и DEADLINE
    Array("USER_ID" => 1) // Выполняем запрос от имени пользователя с ID=1 (администратор)
);

// Обрабатываем полученные задачи
while($arTask1 = $res->GetNext())
{
    echo "ID задачи:".$arTask1["ID"]."<br>"; // Выводим ID задачи
    echo "Название:".$arTask1["TITLE"]."<br>"; // Выводим название задачи
    echo "Крайний срок:".$arTask1["DEADLINE"]."<br><br>"; // Выводим крайний срок задачи
}
?>

Обновление задач, связанных с CRM (пример обновления статуса):

<?php
// Фильтруем задачи по тегу и CRM сделке
$arFilter = array(
    'TAG' => $tag, // Переменная $tag должна быть определена ранее
    "UF_CRM_TASK" => "D_".$dealID, // "D_" - префикс для сделок, $dealID - ID сделки
);

// Получаем список задач
$res = CTasks::GetList(
    Array("DEADLINE" => "ASC"), // Сортировка по полю DEADLINE в порядке возрастания
    $arFilter, // Применяем фильтр для отбора задач
    array("ID"), // Выбираем только поле ID
    array("USER_ID"=>1) // Выполняем запрос от имени пользователя с ID=1 (администратор)
);

// Создаем объект CTasks для обновления задач
$obTask = new CTasks;

// Цикл по найденным задачам
while($arTask1 = $res->GetNext())
{
    // Обновляем статус задачи на "Завершена"
    $obTask->Update(
        $arTask1["ID"], // ID задачи для обновления
        Array(
            "STATUS" => CTasks::STATE_COMPLETED // Устанавливаем статус "Завершена" (константа CTasks::STATE_COMPLETED)
        ),
        Array('USER_ID' => 1) // Выполняем обновление от имени пользователя с ID=1 (администратор)
    );
}
?>

4. Создание новой задачи через API

Метод \CTaskItem::add() позволяет программно создавать новые задачи в Битрикс24.

<?php
// Массив данных для новой задачи
$newTask = array(
    "TITLE" => "Заголовок задачи", // Заголовок задачи
    "DESCRIPTION" => "Описание задачи", // Описание задачи
    "TAGS" => array("CRM", "tag1"), // Теги задачи (массив строк)
    "DEADLINE" => date("d.m.Y H:i:s", strtotime(("+".($time+4)." hours"))), // Крайний срок (вычисляется динамически)
    "CREATED_BY" => $arTaskCopy["RESPONSIBLE_ID"], // ID пользователя, создавшего задачу
    "RESPONSIBLE_ID" => $arTaskCopy["RESPONSIBLE_ID"], // ID ответственного пользователя
    "AUDITORS" => $arTaskCopy["AUDITORS"], // Наблюдатели (массив ID пользователей)
    //"TASK_CONTROL" => "Y", // Контроль задачи постановщиком (необязательное поле)
    "ADD_IN_REPORT" => "Y", // Добавление в отчет (необязательное поле)
    "DEPENDS_ON" => $arFields["ID"], // Зависимость от другой задачи (необязательное поле)
    "UF_CRM_TASK" => $arTaskCopy["UF_CRM_TASK"] // Связь с CRM сущностями (необязательное поле)
);

// Создаем задачу с помощью CTaskItem::add()
$taskItem = \CTaskItem::add($newTask, 1); // 1 - ID пользователя, выполняющего действие (например, администратора)
?>

Дополнительные параметры при создании задачи:

• TASK_CONTROL: ‘Y’ или ‘N’. Включает или отключает контроль выполнения задачи постановщиком. По умолчанию ‘N’.
• ADD_IN_REPORT: ‘Y’ или ‘N’. Включает или отключает добавление задачи в отчеты. По умолчанию ‘N’.
• TASK_CONTROL: ‘Y’ или ‘N’. Включает или отключает контроль задачи постановщиком. По умолчанию ‘N’.
• MATCH_WORK_TIME: ‘Y’ или ‘N’. Учитывать рабочее время при планировании сроков. По умолчанию ‘N’.
• ALLOW_CHANGE_DEADLINE: ‘Y’ или ‘N’. Разрешить или запретить изменение крайнего срока ответственным. По умолчанию ‘Y’.
• AUDITORS: array(user_id1, user_id2, …) Массив ID пользователей-наблюдателей.
• ACCOMPLICES: array(user_id1, user_id2, …) Массив ID пользователей-соисполнителей.
• DEPENDS_ON: array(task_id1, task_id2, …) Массив ID задач, от которых зависит текущая задача.
• TAGS: array(«tag1», «tag2», …) Массив тегов задачи.
• FILES: array(file_id1, file_id2, …) Массив ID файлов, прикрепленных к задаче. (Устаревший метод, рекомендуется использовать UF_TASK_WEBDAV_FILES).
• UF_TASK_WEBDAV_FILES: array(file_id1, file_id2, …) Массив ID файлов Диска, прикрепленных к задаче. (Рекомендуемый метод для прикрепления файлов).
• REPLICATE: ‘Y’ или ‘N’. Задача является регулярной. По умолчанию ‘N’.
• REPLICATE_PARAMS: Сериализованный массив параметров регулярности задачи (для создания регулярных задач).
• GROUP_ID: ID рабочей группы, к которой относится задача.
• PARENT_ID: ID родительской задачи (для создания подзадач).
• Пользовательские поля (UF_*): Вы можете добавлять и использовать любые пользовательские поля, определенные для задач.

5. Добавление наблюдателя в задачу с тегом «SMART» (автоматически)

Следующие обработчики событий демонстрируют, как автоматически добавлять определенного наблюдателя (например, пользователя с ID=25) в задачи, помеченные тегом «SMART».

<?php
// Обработчик OnBeforeTaskAdd для добавления наблюдателя при создании задачи
AddEventHandler("tasks", "OnBeforeTaskAdd", "AddSmartViewerByAdd");

function AddSmartViewerByAdd(&$arFields)
{
    $arSmartViewers = [25]; // Массив ID наблюдателей для добавления

    // Проверяем наличие тега "SMART"
    if(!empty($arFields["TAGS"]) && is_array($arFields["TAGS"]) && in_array("SMART", $arFields["TAGS"]))
    {
        $arFields["AUDITORS"] = $arFields["AUDITORS"] ?? []; // Инициализируем массив AUDITORS, если он пуст
        $arFields["AUDITORS"] = array_unique(array_merge($arFields["AUDITORS"],$arSmartViewers)); // Добавляем новых наблюдателей, исключая дубликаты
    }

    // Пример: Автоматическое отключение контроля задачи (необязательно)
    $possibleCompliteTaskFieldID = 'UF_AUTO_696681441528'; // ID пользовательского поля для контроля
    if(isset($arFields[$possibleCompliteTaskFieldID]) && ($arFields[$possibleCompliteTaskFieldID] == '1'))
    {
        $arFields["TASK_CONTROL"] = "N"; // Отключаем контроль задачи
    }
}

// Обработчик OnBeforeTaskUpdate для добавления наблюдателя при обновлении задачи
AddEventHandler("tasks", "OnBeforeTaskUpdate", "AddSmartViewerByUpdate");

function AddSmartViewerByUpdate ($id, &$arFields, &$arTaskCopy) {
    $arSmartViewers = [25]; // Массив ID наблюдателей для добавления

    // Проверяем наличие тега "SMART"
    if(!empty($arFields["TAGS"]) && is_array($arFields["TAGS"]) && in_array("SMART", $arFields["TAGS"]))
    {
        $arFields["AUDITORS"] = $arFields["AUDITORS"] ?? $arTaskCopy["AUDITORS"]; // Инициализируем массив AUDITORS
        $arFields["AUDITORS"] = array_unique(array_merge($arFields["AUDITORS"],$arSmartViewers)); // Добавляем новых наблюдателей
    }
}
?>

6. Примеры рабочих фильтров для CTasks::GetList()

Метод CTasks::GetList() позволяет получать списки задач с гибкой фильтрацией. Рассмотрим несколько примеров:

Простой фильтр: Задачи с тегом «SMART»

<?php
// Фильтр для задач с тегом "SMART"
$arFilter = array(
    'TAG' => array("SMART"), // Фильтруем по тегу "SMART"
);

// Получаем список задач
$res = CTasks::GetList(
    Array("DEADLINE" => "ASC"), // Сортировка по крайнему сроку
    $arFilter, // Применяем фильтр
    Array("ID", "TITLE", "DEADLINE"), // Выбираем поля ID, TITLE, DEADLINE
    Array("USER_ID"=>1) // Запрос от имени пользователя ID=1
);

// Обрабатываем результаты (вывод, логирование и т.д.)
while($arTask1 = $res->GetNext()){
    // ... (код обработки результатов)
}
?>

Дополнительные примеры сложных фильтров:

• Фильтр по дате создания за определенный период:

<?php
$arFilter = array(
    '>=CREATED_DATE' => date("d.m.Y H:i:s", strtotime("-1 month")), // Задачи, созданные не ранее месяца назад
    '<=CREATED_DATE' => date("d.m.Y H:i:s"), // Задачи, созданные не позднее текущего момента
);
?>

• Фильтр по ответственному и приоритету:

<?php
$arFilter = array(
    "RESPONSIBLE_ID" => 5, // Задачи, ответственным за которые является пользователь с ID=5
    "PRIORITY" => CTasks::PRIORITY_HIGH, // И приоритет - высокий
);
?>

• Фильтр по статусу и наличию наблюдателей:

<?php
$arFilter = array(
    "STATUS" => CTasks::STATE_IN_PROGRESS, // Задачи в статусе "В процессе"
    "!AUDITORS" => false, // И у которых есть наблюдатели (поле AUDITORS не пустое)
);
?>

• Фильтр с использованием логического «ИЛИ» и пользовательского поля:

<?php
$arFilter = array(
    '::LOGIC' => 'OR', // Логическое "ИЛИ"
    "STATUS" => CTasks::STATE_NEW, // Задачи в статусе "Новая"
    "UF_TASK_IMPORTANT" => 1, // ИЛИ задачи, у которых пользовательское поле UF_TASK_IMPORTANT равно 1 (например, "Важная задача")
);
?>

Сложный фильтр: Задачи, где текущий пользователь соисполнитель или ответственный, и задачи не завершены

<?php
// Сложный фильтр для отбора задач
$arFilter = array(
    '::LOGIC' => 'AND', // Логическое "И" для всего фильтра
    '!REAL_STATUS' => CTasks::STATE_COMPLETED, // Исключаем завершенные задачи
    '::SUBFILTER-1' => array( // Подфильтр 1 (логическое "ИЛИ")
        '::LOGIC' => 'OR', // Логическое "ИЛИ" внутри подфильтра
        '::SUBFILTER-1' => array( // Вложенный подфильтр 1.1
            'ACCOMPLICE' => array($USER->GetID()), // Задачи, где текущий пользователь - соисполнитель
            'REAL_STATUS' => array( // И статусы:
                CTasks::STATE_NEW,
                CTasks::STATE_PENDING,
                CTasks::STATE_IN_PROGRESS
            ),
        ),
        '::SUBFILTER-2' => array( // Вложенный подфильтр 1.2
            'RESPONSIBLE_ID' => $USER->GetID(), // ИЛИ задачи, где текущий пользователь - ответственный
            'REAL_STATUS' => array( // И статусы:
                CTasks::STATE_NEW,
                CTasks::STATE_PENDING,
                CTasks::STATE_IN_PROGRESS
            ),
        ),
    ),
);

// Получаем список задач с применением сложного фильтра
$res = CTasks::GetList(
    Array(), // Сортировка не важна в данном примере
    $arFilter, // Применяем сложный фильтр
    Array("ID", "TITLE", "STATUS", "RESPONSIBLE_ID", "CREATED_BY", "DEADLINE"), // Выбираем нужные поля
    Array() // Дополнительные параметры не требуются
);

// Обрабатываем результаты
while($Tasks = $res->GetNext())
{
    // ... (код обработки результатов)
}
?>

7. Ключевые константы и методы для работы с задачами

Для эффективной работы с API задач важно знать основные константы и методы.

Константы статусов задач (CTasks::STATE_*):

• CTasks::METASTATE_VIRGIN_NEW (-2): Новая задача (не просмотрена).
• CTasks::METASTATE_EXPIRED (-1): Задача просрочена.
• CTasks::METASTATE_EXPIRED_SOON (-3): Задача почти просрочена.
• CTasks::STATE_NEW (1): Новая задача.
• CTasks::STATE_PENDING (2): Задача принята исполнителем.
• CTasks::STATE_IN_PROGRESS (3): Задача выполняется.
• CTasks::STATE_SUPPOSEDLY_COMPLETED (4): Условно завершена (ожидает подтверждения).
• CTasks::STATE_COMPLETED (5): Задача завершена.
• CTasks::STATE_DEFERRED (6): Задача отложена.
• CTasks::STATE_DECLINED (7): Задача отклонена.

Константы приоритетов задач (CTasks::PRIORITY_*):

• CTasks::PRIORITY_LOW (0): Низкий приоритет.
• CTasks::PRIORITY_AVERAGE (1): Средний приоритет.
• CTasks::PRIORITY_HIGH (2): Высокий приоритет.

Константы действий над задачей (CTaskItem::ACTION_*):

• CTaskItem::ACTION_ACCEPT (1): Принять задачу.
• CTaskItem::ACTION_DECLINE (2): Отклонить задачу.
• CTaskItem::ACTION_COMPLETE (3): Завершить задачу.
• CTaskItem::ACTION_APPROVE (4): Подтвердить выполнение задачи.
• CTaskItem::ACTION_DISAPPROVE (5): Отклонить выполнение задачи.
• CTaskItem::ACTION_START (6): Начать выполнение задачи.
• CTaskItem::ACTION_DELEGATE (7): Делегировать задачу.
• CTaskItem::ACTION_REMOVE (8): Удалить задачу.
• CTaskItem::ACTION_EDIT (9): Редактировать задачу.
• CTaskItem::ACTION_DEFER (10): Отложить задачу.
• CTaskItem::ACTION_RENEW (11): Возобновить задачу.
• CTaskItem::ACTION_CREATE (12): Создать задачу.
• CTaskItem::ACTION_CHANGE_DEADLINE (13): Изменить крайний срок.
• CTaskItem::ACTION_PAUSE (17): Поставить задачу на паузу.
• CTaskItem::ACTION_START_TIME_TRACKING (18): Запустить учет времени.
• CTaskItem::ACTION_CHECKLIST_ADD_ITEMS (14): Добавить пункт в чек-лист.
• CTaskItem::ACTION_CHECKLIST_REORDER_ITEMS (22): Изменить порядок пунктов чек-листа.
• CTaskItem::ACTION_ELAPSED_TIME_ADD (15): Добавить затраченное время.
• CTaskItem::ACTION_ADD_FAVORITE (19): Добавить в избранное.
• CTaskItem::ACTION_DELETE_FAVORITE (20): Удалить из избранного.
• CTaskItem::ACTION_TOGGLE_FAVORITE (21): Переключить «избранность».
• CTaskItem::ACTION_READ (23): Прочитать задачу.
• CTaskItem::ACTION_RATE (1702): Оценить задачу.

Константы ролей пользователей в задаче (CTaskItem::ROLE_*):

• CTaskItem::ROLE_NOT_A_MEMBER (1): Не участник задачи.
• CTaskItem::ROLE_DIRECTOR (2): Постановщик.
• CTaskItem::ROLE_RESPONSIBLE (4): Ответственный.
• CTaskItem::ROLE_ACCOMPLICE (8): Соисполнитель.
• CTaskItem::ROLE_AUDITOR (16): Наблюдатель.

Константы форматов описания задачи (CTaskItem::DESCR_FORMAT_*):

• CTaskItem::DESCR_FORMAT_RAW (1): Оригинальный формат (HTML или BBCode).
• CTaskItem::DESCR_FORMAT_HTML (2): HTML формат.
• CTaskItem::DESCR_FORMAT_PLAIN_TEXT (3): Текстовый формат.

Константы идентификаторов предустановленных фильтров (CTaskFilterCtrl::STD_PRESET_*):

• CTaskFilterCtrl::ROOT_PRESET (0): Корневой пресет (не используется напрямую).
• CTaskFilterCtrl::STD_PRESET_ACTIVE_MY_TASKS (-1): «Мои задачи».
• CTaskFilterCtrl::STD_PRESET_ACTIVE_I_AM_DOER (-2): «Порученые мне».
• CTaskFilterCtrl::STD_PRESET_ACTIVE_I_AM_ORIGINATOR (-3): «Поставленные мной».
• CTaskFilterCtrl::STD_PRESET_ACTIVE_I_AM_AUDITOR (-4): «Наблюдаю».
• CTaskFilterCtrl::STD_PRESET_DEFERRED_MY_TASKS (-5): «Отложенные».
• CTaskFilterCtrl::STD_PRESET_COMPLETED_MY_TASKS (-6): «Завершенные».
• CTaskFilterCtrl::STD_PRESET_ACTIVE_I_AM_RESPONSIBLE (-7): «Я ответственный».
• CTaskFilterCtrl::STD_PRESET_ACTIVE_I_AM_ACCOMPLICE (-8): «Я соисполнитель».
• CTaskFilterCtrl::STD_PRESET_ALL_MY_TASKS (-9): «Все задачи».
• CTaskFilterCtrl::STD_PRESET_EXPIRED (-11): «Просроченные».
• CTaskFilterCtrl::STD_PRESET_EXPIRED_SOON (-12): «Скоро истекает срок».
• CTaskFilterCtrl::STD_PRESET_ALIAS_TO_DEFAULT (-9): Псевдоним для «Все задачи».

Основные методы класса CTasks:

Примеры для основных методов класса CTasks

Важно: Перед использованием этих примеров убедитесь, что у вас подключен модуль tasks:

<?php
CModule::IncludeModule("tasks");
?>

1. Add()

Описание: Метод Add() добавляет новую задачу и возвращает ее ID.

Пример:

<?php
CModule::IncludeModule("tasks");

// Параметры новой задачи
$taskData = [
    'TITLE' => 'Новая задача, созданная через CTasks::Add()',
    'RESPONSIBLE_ID' => 1, // ID ответственного пользователя
    'DESCRIPTION' => 'Описание новой задачи.',
    // ... другие поля задачи ...
];

$task = new CTasks();
$taskId = $task->Add($taskData);

if ($taskId) {
    echo "Задача успешно создана. ID задачи: " . $taskId;
} else {
    echo "Не удалось создать задачу. Ошибки:\n";
    echo "<pre>";
    var_dump($task->GetErrors());
    echo "</pre>";
}
?>

Пояснение:

• Создается массив $taskData с параметрами новой задачи, включая обязательные TITLE и RESPONSIBLE_ID.
• Создается экземпляр класса CTasks.
• $task->Add($taskData) вызывает метод Add() для создания задачи.
• Проверяется, успешно ли создана задача, и выводится ID задачи или список ошибок, если таковые возникли, используя $task->GetErrors().

2. AddAccomplices()

Описание: Метод AddAccomplices() добавляет соисполнителей к задаче. Устаревший метод. Рекомендуется использовать CTaskItem->update().

Пример:

<?php
CModule::IncludeModule("tasks");

// ID задачи, к которой добавляем соисполнителей
$taskId = 123;
// Массив ID пользователей-соисполнителей
$accomplicesIds = [2, 3];

$task = new CTasks();
$task->AddAccomplices($taskId, $accomplicesIds);

echo "Соисполнители успешно добавлены к задаче с ID " . $taskId;
?>

Пояснение:

• Указывается ID задачи $taskId и массив ID соисполнителей $accomplicesIds.
• Создается экземпляр класса CTasks.
• $task->AddAccomplices($taskId, $accomplicesIds) вызывает метод AddAccomplices() для добавления соисполнителей.
• Выводится сообщение об успехе.

3. AddAuditors()

Описание: Метод AddAuditors() добавляет наблюдателей к задаче. Устаревший метод. Рекомендуется использовать CTaskItem->update().

Пример:

<?php
CModule::IncludeModule("tasks");

// ID задачи, к которой добавляем наблюдателей
$taskId = 123;
// Массив ID пользователей-наблюдателей
$auditorsIds = [4, 5];

$task = new CTasks();
$task->AddAuditors($taskId, $auditorsIds);

echo "Наблюдатели успешно добавлены к задаче с ID " . $taskId;
?>

Пояснение:

• Аналогично AddAccomplices(), но добавляет наблюдателей.

4. AddFiles()

Описание: Метод AddFiles() добавляет файлы к задаче. Устаревший метод. Рекомендуется использовать CTaskItem->update().

Пример:

<?php
CModule::IncludeModule("tasks");

// ID задачи, к которой добавляем файлы
$taskId = 123;
// Массив ID файлов (из модуля Файлы или Диск)
$fileIds = [10, 11];

$task = new CTasks();
$task->AddFiles($taskId, $fileIds);

echo "Файлы успешно добавлены к задаче с ID " . $taskId;
?>

Пояснение:

• Указывается ID задачи $taskId и массив ID файлов $fileIds.
• Создается экземпляр класса CTasks.
• $task->AddFiles($taskId, $fileIds) вызывает метод AddFiles() для добавления файлов.
• Выводится сообщение об успехе.

5. AddPrevious()

Описание: Метод AddPrevious() добавляет предыдущие задачи (зависимости) к задаче. Устаревший метод. Рекомендуется использовать CTaskItem->update().

Пример:

<?php
CModule::IncludeModule("tasks");

// ID задачи, к которой добавляем зависимости
$taskId = 123;
// Массив ID предыдущих задач
$previousTaskIds = [120, 121];

$task = new CTasks();
$task->AddPrevious($taskId, $previousTaskIds);

echo "Зависимости успешно добавлены к задаче с ID " . $taskId;
?>

Пояснение:

• Аналогично AddFiles(), но добавляет зависимости от предыдущих задач.

6. AddTags()

Описание: Метод AddTags() добавляет теги к задаче. Устаревший метод. Рекомендуется использовать Tag.

Пример:

<?php
CModule::IncludeModule("tasks");

// ID задачи, к которой добавляем теги
$taskId = 123;
// Массив тегов
$tags = ["Важный", "Срочно"];

$task = new CTasks();
$task->AddTags($taskId, 1, $tags); // 1 - ID пользователя, выполняющего действие

echo "Теги успешно добавлены к задаче с ID " . $taskId;
?>

Пояснение:

• Указывается ID задачи $taskId, ID пользователя, выполняющего действие (в примере 1), и массив тегов $tags.
• Создается экземпляр класса CTasks.
• $task->AddTags($taskId, 1, $tags) вызывает метод AddTags() для добавления тегов.
• Выводится сообщение об успехе.

7. Delete()

Описание: Метод Delete() удаляет задачу по ее ID.

Пример:

<?php
CModule::IncludeModule("tasks");

// ID задачи для удаления
$taskId = 123;

$task = new CTasks();
$result = $task->Delete($taskId);

if ($result) {
    echo "Задача с ID " . $taskId . " успешно удалена.";
} else {
    echo "Не удалось удалить задачу с ID " . $taskId . ". Ошибки:\n";
    echo "<pre>";
    var_dump($task->GetErrors());
    echo "</pre>";
}
?>

Пояснение:

• Указывается ID задачи $taskId для удаления.
• Создается экземпляр класса CTasks.
• $task->Delete($taskId) вызывает метод Delete() для удаления задачи.
• Проверяется результат удаления и выводится сообщение об успехе или список ошибок, если удаление не удалось.

8. GetByID()

Описание: Метод GetByID() возвращает массив с полями задачи по ее ID.

Пример:

<?php
CModule::IncludeModule("tasks");

// ID задачи для получения данных
$taskId = 123;

$task = new CTasks();
$taskDataResult = $task->GetByID($taskId);

if ($taskData = $taskDataResult->Fetch()) {
    echo "Данные задачи с ID " . $taskId . ":\n";
    echo "<pre>";
    var_dump($taskData);
    echo "</pre>";
} else {
    echo "Не удалось получить данные задачи с ID " . $taskId . ".";
}
?>

Пояснение:

• Указывается ID задачи $taskId для получения данных.
• Создается экземпляр класса CTasks.
• $task->GetByID($taskId) вызывает метод GetByID() и возвращает объект CDBResult.
• $taskDataResult->Fetch() извлекает массив с полями задачи из результата запроса.
• Проверяется, удалось ли получить данные, и выводится массив $taskData или сообщение об ошибке.

9. GetChildrenCount()

Описание: Метод GetChildrenCount() возвращает количество подзадач для указанной задачи.

Пример:

<?php
CModule::IncludeModule("tasks");

// ID родительской задачи, для которой нужно получить количество подзадач
$taskId = 123;

$task = new CTasks();
$childrenCountResult = $task->GetChildrenCount([], $taskId);

if ($childrenCountResult) {
    if ($childrenCount = $childrenCountResult->Fetch()) {
        echo "Количество подзадач для задачи с ID " . $taskId . ": " . $childrenCount["CNT"];
    } else {
        echo "У задачи с ID " . $taskId . " нет подзадач.";
    }
} else {
    echo "Не удалось получить количество подзадач для задачи с ID " . $taskId . ".";
}
?>

Пояснение:

• Указывается ID родительской задачи $taskId.
• Создается экземпляр класса CTasks.
• $task->GetChildrenCount([], $taskId) вызывает метод GetChildrenCount() и возвращает объект CDBResult.
• $childrenCountResult->Fetch() извлекает массив с количеством подзадач.
• Выводится количество подзадач или сообщение об их отсутствии/ошибке.

10. GetList()

Описание: Метод GetList() возвращает список задач, отфильтрованных и отсортированных по заданным параметрам.

Пример:

<?php
CModule::IncludeModule("tasks");

// Параметры фильтрации
$arFilter = [
    'RESPONSIBLE_ID' => 1, // Фильтр по ответственному пользователю
    'STATUS' => CTasks::STATE_IN_PROGRESS, // Фильтр по статусу "В процессе"
];

// Параметры сортировки
$arOrder = [
    'PRIORITY' => 'DESC', // Сортировать по приоритету в убывающем порядке
    'DEADLINE' => 'ASC', // Затем по сроку в возрастающем порядке
];

// Параметры выборки полей
$arSelect = [
    'ID',
    'TITLE',
    'PRIORITY',
    'STATUS',
    'DEADLINE',
    'RESPONSIBLE_ID',
];

$task = new CTasks();
$taskListResult = $task->GetList($arOrder, $arFilter, $arSelect);

if ($taskListResult) {
    echo "Список задач, отфильтрованных и отсортированных:\n";
    echo "<pre>";
    while ($taskItem = $taskListResult->Fetch()) {
        var_dump($taskItem);
        echo "<br><br>";
    }
    echo "</pre>";
} else {
    echo "Не удалось получить список задач.";
}
?>

Пояснение:

• Создаются массивы $arOrder, $arFilter, и $arSelect для определения параметров запроса.
• $task->GetList($arOrder, $arFilter, $arSelect) вызывает метод GetList() и возвращает объект CDBResult.
• В цикле while ($taskItem = $taskListResult->Fetch()) перебираются задачи из результата запроса, и данные каждой задачи выводятся на экран с помощью var_dump($taskItem).

11. GetUpdatesCount()

Описание: Метод GetUpdatesCount() возвращает количество изменений в задачах. Устаревший метод.

Пример:

<?php
CModule::IncludeModule("tasks");

// Массив просмотренных задач, где ключ - ID задачи, значение - дата просмотра в формате базы данных
$arViewedTasks = [
    123 => '2023-10-26 10:00:00',
    124 => '2023-10-25 15:30:00',
];

$task = new CTasks();
$updatesCount = $task->GetUpdatesCount($arViewedTasks);

if ($updatesCount) {
    echo "Количество обновлений в задачах:\n";
    echo "<pre>";
    var_dump($updatesCount);
    echo "</pre>";
} else {
    echo "Не удалось получить количество обновлений.";
}
?>

Пояснение:

• Создается массив $arViewedTasks с данными о просмотренных задачах.
• $task->GetUpdatesCount($arViewedTasks) вызывает метод GetUpdatesCount() и возвращает массив с количеством обновлений для каждой задачи.
• Выводится массив $updatesCount или сообщение об ошибке.

12. Update()

Описание: Метод Update() обновляет параметры существующей задачи.

Пример:

<?php
CModule::IncludeModule("tasks");

// ID задачи для обновления
$taskId = 123;

// Массив полей для обновления
$updateTaskData = [
    'TITLE' => 'Обновленное название задачи',
    'DESCRIPTION' => 'Обновленное описание задачи.',
    'PRIORITY' => CTasks::PRIORITY_HIGH, // Изменить приоритет на высокий
    // ... другие поля для обновления ...
];

$task = new CTasks();
$result = $task->Update($taskId, $updateTaskData);

if ($result) {
    echo "Задача с ID " . $taskId . " успешно обновлена.";
} else {
    echo "Не удалось обновить задачу с ID " . $taskId . ". Ошибки:\n";
    echo "<pre>";
    var_dump($task->GetErrors());
    echo "</pre>";
}
?>

Пояснение:

• Указывается ID задачи $taskId для обновления и массив $updateTaskData с новыми значениями полей.
• Создается экземпляр класса CTasks.
• $task->Update($taskId, $updateTaskData) вызывает метод Update() для обновления задачи.
• Проверяется результат обновления и выводится сообщение об успехе или список ошибок.

13. getAvailableOrderFields()

Описание: Метод getAvailableOrderFields() возвращает массив доступных полей для сортировки в методе GetList().

Пример:

<?php
CModule::IncludeModule("tasks");

$task = new CTasks();
$orderFields = $task->getAvailableOrderFields();

echo "Доступные поля для сортировки:\n";
echo "<pre>";
var_dump($orderFields);
echo "</pre>";
?>

Пояснение:

• Создается экземпляр класса CTasks.
• $task->getAvailableOrderFields() вызывает метод getAvailableOrderFields() и возвращает массив $orderFields.
• Выводится массив доступных полей для сортировки.

Эти примеры демонстрируют, как использовать основные методы класса CTasks для работы с задачами в Битрикс24. Пожалуйста, обратите внимание, что некоторые методы (AddAccomplices, AddAuditors, AddFiles, AddPrevious, AddTags, GetUpdatesCount) являются устаревшими, и рекомендуется использовать новые методы класса CTaskItem для работы с задачами.

Методы нового класса CTaskItem:

Примеры для методов класса CTaskItem

Важно: Перед использованием этих примеров убедитесь, что у вас подключен модуль tasks:

<?php
CModule::IncludeModule("tasks");
?>

1. add()

Описание: Метод add() создает новую задачу и возвращает экземпляр класса CTaskItem, представляющий эту задачу.

Пример:

<?php
CModule::IncludeModule("tasks");

// ID пользователя, от имени которого создается задача
$userId = 1;

// Параметры новой задачи
$taskData = [
    'TITLE' => 'Моя новая задача',
    'RESPONSIBLE_ID' => $userId, // Назначить ответственным того же пользователя
    'DESCRIPTION' => 'Описание моей новой задачи.',
    // ... другие поля задачи ...
];

try {
    $taskItem = CTaskItem::add($taskData, $userId);

    if ($taskItem) {
        echo "Задача успешно создана. ID задачи: " . $taskItem->getId();
    } else {
        echo "Не удалось создать задачу.";
    }
} catch (TasksException $e) {
    echo "Ошибка при создании задачи: " . $e->getMessage();
}
?>

2. getData()

Описание: Метод getData() возвращает массив, содержащий данные о задаче. По умолчанию возвращает экранированные данные для безопасного вывода в HTML.

Пример:

<?php
CModule::IncludeModule("tasks");

// ID существующей задачи
$taskId = 123;
// ID пользователя, имеющего доступ к задаче
$userId = 1;

try {
    $taskItem = CTaskItem::getInstance($taskId, $userId);
    $taskData = $taskItem->getData();

    echo "<pre>";
    var_dump($taskData);
    echo "</pre>";

} catch (TasksException $e) {
    echo "Ошибка при получении данных задачи: " . $e->getMessage();
}
?>

3. getDescription()

Описание: Метод getDescription() возвращает описание задачи в различных форматах (RAW, HTML, Plain Text). По умолчанию возвращает HTML-форматированное описание.

Примеры:

a) Получение HTML-описания (по умолчанию):

<?php
CModule::IncludeModule("tasks");

// ID существующей задачи
$taskId = 123;
// ID пользователя, имеющего доступ к задаче
$userId = 1;

try {
    $taskItem = CTaskItem::getInstance($taskId, $userId);
    $descriptionHTML = $taskItem->getDescription();
    echo "HTML описание: " . $descriptionHTML;

} catch (TasksException $e) {
    echo "Ошибка при получении описания задачи: " . $e->getMessage();
}
?>

b) Получение RAW-описания (как есть, BB-код или HTML):

<?php
CModule::IncludeModule("tasks");

// ID существующей задачи
$taskId = 123;
// ID пользователя, имеющего доступ к задаче
$userId = 1;

try {
    $taskItem = CTaskItem::getInstance($taskId, $userId);
    $descriptionRAW = $taskItem->getDescription(CTaskItem::DESCR_FORMAT_RAW);
    echo "RAW описание: " . $descriptionRAW;

} catch (TasksException $e) {
    echo "Ошибка при получении описания задачи: " . $e->getMessage();
}
?>

c) Получение Plain Text описания (без HTML/BB-кодов):

<?php
CModule::IncludeModule("tasks");

// ID существующей задачи
$taskId = 123;
// ID пользователя, имеющего доступ к задаче
$userId = 1;

try {
    $taskItem = CTaskItem::getInstance($taskId, $userId);
    $descriptionPlainText = $taskItem->getDescription(CTaskItem::DESCR_FORMAT_PLAIN_TEXT);
    echo "Plain Text описание: " . $descriptionPlainText;

} catch (TasksException $e) {
    echo "Ошибка при получении описания задачи: " . $e->getMessage();
}
?>

4. getFiles()

Описание: Метод getFiles() возвращает массив, содержащий идентификаторы файлов, прикрепленных к задаче. Важно: Этот метод возвращает идентификаторы файлов, хранящихся в устаревшем модуле WebDAV. Для новых задач, использующих Диск, следует использовать другие методы для работы с файлами.

Пример:

<?php
CModule::IncludeModule("tasks");

// ID существующей задачи
$taskId = 123;
// ID пользователя, имеющего доступ к задаче
$userId = 1;

try {
    $taskItem = CTaskItem::getInstance($taskId, $userId);
    $files = $taskItem->getFiles();

    echo "Идентификаторы файлов, прикрепленных к задаче:\n";
    echo "<pre>";
    var_dump($files);
    echo "</pre>";

} catch (TasksException $e) {
    echo "Ошибка при получении файлов задачи: " . $e->getMessage();
}
?>

5. getTags()

Описание: Метод getTags() возвращает массив, содержащий теги задачи.

Пример:

<?php
CModule::IncludeModule("tasks");

// ID существующей задачи
$taskId = 123;
// ID пользователя, имеющего доступ к задаче
$userId = 1;

try {
    $taskItem = CTaskItem::getInstance($taskId, $userId);
    $tags = $taskItem->getTags();

    echo "Теги задачи:\n";
    echo "<pre>";
    var_dump($tags);
    echo "</pre>";

} catch (TasksException $e) {
    echo "Ошибка при получении тегов задачи: " . $e->getMessage();
}
?>

6. getDependsOn()

Описание: Метод getDependsOn() возвращает массив, содержащий идентификаторы задач, от которых зависит текущая задача.

Пример:

<?php
CModule::IncludeModule("tasks");

// ID существующей задачи
$taskId = 123;
// ID пользователя, имеющего доступ к задаче
$userId = 1;

try {
    $taskItem = CTaskItem::getInstance($taskId, $userId);
    $dependsOnTasks = $taskItem->getDependsOn();

    echo "Задачи, от которых зависит текущая задача:\n";
    echo "<pre>";
    var_dump($dependsOnTasks);
    echo "</pre>";

} catch (TasksException $e) {
    echo "Ошибка при получении зависимостей задачи: " . $e->getMessage();
}
?>

7. getAllowedActions()

Описание: Метод getAllowedActions() возвращает массив, описывающий допустимые действия над задачей для текущего пользователя.

Пример:

<?php
CModule::IncludeModule("tasks");

// ID существующей задачи
$taskId = 123;
// ID пользователя, имеющего доступ к задаче
$userId = 1;

try {
    $taskItem = CTaskItem::getInstance($taskId, $userId);
    $allowedActions = $taskItem->getAllowedActions();

    echo "Допустимые действия над задачей:\n";
    echo "<pre>";
    var_dump($allowedActions);
    echo "</pre>";

} catch (TasksException $e) {
    echo "Ошибка при получении допустимых действий: " . $e->getMessage();
}
?>

8. isActionAllowed()

Описание: Метод isActionAllowed() проверяет, разрешено ли определенное действие над задачей для текущего пользователя. Возвращает true, если действие разрешено, и false в противном случае.

Примеры:

a) Проверка разрешения на редактирование задачи:

<?php
CModule::IncludeModule("tasks");

// ID существующей задачи
$taskId = 123;
// ID пользователя, имеющего доступ к задаче
$userId = 1;

try {
    $taskItem = CTaskItem::getInstance($taskId, $userId);
    $canEdit = $taskItem->isActionAllowed(CTaskItem::ACTION_EDIT);

    if ($canEdit) {
        echo "Редактирование задачи разрешено.";
    } else {
        echo "Редактирование задачи запрещено.";
    }

} catch (TasksException $e) {
    echo "Ошибка при проверке разрешения: " . $e->getMessage();
}
?>

b) Проверка разрешения на удаление задачи:

<?php
CModule::IncludeModule("tasks");

// ID существующей задачи
$taskId = 123;
// ID пользователя, имеющего доступ к задаче
$userId = 1;

try {
    $taskItem = CTaskItem::getInstance($taskId, $userId);
    $canDelete = $taskItem->isActionAllowed(CTaskItem::ACTION_REMOVE);

    if ($canDelete) {
        echo "Удаление задачи разрешено.";
    } else {
        echo "Удаление задачи запрещено.";
    }

} catch (TasksException $e) {
    echo "Ошибка при проверке разрешения: " . $e->getMessage();
}
?>

9. delete()

Описание: Метод delete() удаляет задачу.

Пример:

<?php
CModule::IncludeModule("tasks");

// ID существующей задачи
$taskId = 123;
// ID пользователя, имеющего доступ к задаче
$userId = 1;

try {
    $taskItem = CTaskItem::getInstance($taskId, $userId);
    $taskItem->delete();
    echo "Задача успешно удалена.";

} catch (TasksException $e) {
    echo "Ошибка при удалении задачи: " . $e->getMessage();
}
?>

10. delegate()

Описание: Метод delegate() делегирует задачу другому ответственному пользователю.

Пример:

<?php
CModule::IncludeModule("tasks");

// ID существующей задачи
$taskId = 123;
// ID пользователя, имеющего доступ к задаче
$userId = 1;
// ID пользователя, которому делегируется задача
$newResponsibleId = 2;

try {
    $taskItem = CTaskItem::getInstance($taskId, $userId);
    $taskItem->delegate($newResponsibleId);
    echo "Задача успешно делегирована пользователю с ID " . $newResponsibleId;

} catch (TasksException $e) {
    echo "Ошибка при делегировании задачи: " . $e->getMessage();
}
?>

11. startExecution()

Описание: Метод startExecution() переводит задачу в статус «выполняется» (CTasks::STATE_IN_PROGRESS).

Пример:

<?php
CModule::IncludeModule("tasks");

// ID существующей задачи
$taskId = 123;
// ID пользователя, имеющего доступ к задаче
$userId = 1;

try {
    $taskItem = CTaskItem::getInstance($taskId, $userId);
    $taskItem->startExecution();
    echo "Задача переведена в статус 'выполняется'.";

} catch (TasksException $e) {
    echo "Ошибка при переводе задачи в статус 'выполняется': " . $e->getMessage();
}
?>

12. pauseExecution()

Описание: Метод pauseExecution() переводит задачу в статус «ожидает выполнения» (CTasks::STATE_PENDING).

Пример:

<?php
CModule::IncludeModule("tasks");

// ID существующей задачи
$taskId = 123;
// ID пользователя, имеющего доступ к задаче
$userId = 1;

try {
    $taskItem = CTaskItem::getInstance($taskId, $userId);
    $taskItem->pauseExecution();
    echo "Задача переведена в статус 'ожидает выполнения'.";

} catch (TasksException $e) {
    echo "Ошибка при переводе задачи в статус 'ожидает выполнения': " . $e->getMessage();
}
?>

13. defer()

Описание: Метод defer() переводит задачу в статус «отложена» (CTasks::STATE_DEFERRED).

Пример:

<?php
CModule::IncludeModule("tasks");

// ID существующей задачи
$taskId = 123;
// ID пользователя, имеющего доступ к задаче
$userId = 1;

try {
    $taskItem = CTaskItem::getInstance($taskId, $userId);
    $taskItem->defer();
    echo "Задача переведена в статус 'отложена'.";

} catch (TasksException $e) {
    echo "Ошибка при переводе задачи в статус 'отложена': " . $e->getMessage();
}
?>

14. renew()

Описание: Метод renew() переводит задачу в статус «новая» или «принята», в зависимости от настроек. В контексте модуля tasks, обычно переводит в «новая» (CTasks::STATE_NEW).

Пример:

<?php
CModule::IncludeModule("tasks");

// ID существующей задачи
$taskId = 123;
// ID пользователя, имеющего доступ к задаче
$userId = 1;

try {
    $taskItem = CTaskItem::getInstance($taskId, $userId);
    $taskItem->renew();
    echo "Задача переведена в статус 'новая'.";

} catch (TasksException $e) {
    echo "Ошибка при переводе задачи в статус 'новая': " . $e->getMessage();
}
?>

15. complete()

Описание: Метод complete() переводит задачу в статус «завершена» (CTasks::STATE_COMPLETED) или «условно завершена» (CTasks::STATE_SUPPOSEDLY_COMPLETED), в зависимости от настроек контроля постановщиком.

Пример:

<?php
CModule::IncludeModule("tasks");

// ID существующей задачи
$taskId = 123;
// ID пользователя, имеющего доступ к задаче
$userId = 1;

try {
    $taskItem = CTaskItem::getInstance($taskId, $userId);
    $taskItem->complete();
    echo "Задача переведена в статус 'завершена' или 'условно завершена'.";

} catch (TasksException $e) {
    echo "Ошибка при переводе задачи в статус 'завершена' или 'условно завершена': " . $e->getMessage();
}
?>

16. approve()

Описание: Метод approve() одобряет условно завершенную задачу и переводит ее в статус «завершена» (CTasks::STATE_COMPLETED).

Пример:

<?php
CModule::IncludeModule("tasks");

// ID существующей задачи
$taskId = 123;
// ID пользователя, имеющего доступ к задаче
$userId = 1;

try {
    $taskItem = CTaskItem::getInstance($taskId, $userId);
    $taskItem->approve();
    echo "Задача одобрена и переведена в статус 'завершена'.";

} catch (TasksException $e) {
    echo "Ошибка при одобрении задачи: " . $e->getMessage();
}
?>

17. disapprove()

Описание: Метод disapprove() отклоняет условно завершенную задачу и переводит ее обратно в статус «новая» или «принята» (обычно «новая», CTasks::STATE_NEW).

Пример:

<?php
CModule::IncludeModule("tasks");

// ID существующей задачи
$taskId = 123;
// ID пользователя, имеющего доступ к задаче
$userId = 1;

try {
    $taskItem = CTaskItem::getInstance($taskId, $userId);
    $taskItem->disapprove();
    echo "Задача отклонена и переведена в статус 'новая'.";

} catch (TasksException $e) {
    echo "Ошибка при отклонении задачи: " . $e->getMessage();
}
?>

18. update()

Описание: Метод update() позволяет изменять параметры задачи. Принимает массив с новыми значениями полей задачи.

Пример:

<?php
CModule::IncludeModule("tasks");

// ID существующей задачи
$taskId = 123;
// ID пользователя, имеющего доступ к задаче
$userId = 1;

$newTaskData = [
    'TITLE' => 'Обновленное название задачи',
    'DESCRIPTION' => 'Обновленное описание задачи.',
    'PRIORITY' => CTasks::PRIORITY_HIGH, // Изменить приоритет на высокий
    // ... другие поля для обновления ...
];

try {
    $taskItem = CTaskItem::getInstance($taskId, $userId);
    $taskItem->update($newTaskData);
    echo "Задача успешно обновлена.";

} catch (TasksException $e) {
    echo "Ошибка при обновлении задачи: " . $e->getMessage();
}
?>

19. addByTemplate()

Описание: Метод addByTemplate() создает новую задачу на основе шаблона задачи и возвращает экземпляр класса CTaskItem для созданной задачи.

Пример:

<?php
CModule::IncludeModule("tasks");

// ID шаблона задачи
$templateId = 456;
// ID пользователя, от имени которого создается задача
$userId = 1;

try {
    $newTaskItem = CTaskItem::addByTemplate($templateId, $userId);

    if ($newTaskItem) {
        echo "Задача успешно создана из шаблона. ID задачи: " . $newTaskItem->getId();
    } else {
        echo "Не удалось создать задачу из шаблона.";
    }
} catch (TasksException $e) {
    echo "Ошибка при создании задачи из шаблона: " . $e->getMessage();
}
?>

20. addChildTaskByTemplate()

Описание: Метод addChildTaskByTemplate() добавляет подзадачи к текущей задаче на основе шаблона подзадач. Возвращает массив экземпляров CTaskItem для созданных подзадач.

Пример:

<?php
CModule::IncludeModule("tasks");

// ID существующей задачи (родительской)
$taskId = 123;
// ID шаблона подзадач
$templateId = 789;
// ID пользователя, имеющего доступ к задаче
$userId = 1;

try {
    $taskItem = CTaskItem::getInstance($taskId, $userId);
    $childTaskItems = $taskItem->addChildTaskByTemplate($templateId);

    if (!empty($childTaskItems)) {
        echo "Подзадачи успешно созданы из шаблона. IDs подзадач: ";
        foreach ($childTaskItems as $childTaskItem) {
            echo $childTaskItem->getId() . ", ";
        }
    } else {
        echo "Не удалось создать подзадачи из шаблона.";
    }
} catch (TasksException $e) {
    echo "Ошибка при создании подзадач из шаблона: " . $e->getMessage();
}
?>

21. duplicate()

Описание: Метод duplicate() копирует текущую задачу и возвращает экземпляр класса CTaskItem для созданной копии.

Пример:

<?php
CModule::IncludeModule("tasks");

// ID существующей задачи
$taskId = 123;
// ID пользователя, имеющего доступ к задаче
$userId = 1;

try {
    $taskItem = CTaskItem::getInstance($taskId, $userId);
    $duplicatedTaskItem = $taskItem->duplicate();

    if ($duplicatedTaskItem) {
        echo "Задача успешно скопирована. ID копии: " . $duplicatedTaskItem->getId();
    } else {
        echo "Не удалось скопировать задачу.";
    }
} catch (TasksException $e) {
    echo "Ошибка при копировании задачи: " . $e->getMessage();
}
?>

22. duplicateChildTasks()

Описание: Метод duplicateChildTasks() копирует подзадачи текущей задачи и привязывает их к другой задаче (клону). Возвращает массив экземпляров CTaskItem для скопированных подзадач.

Пример:

<?php
CModule::IncludeModule("tasks");

// ID существующей задачи (родительской)
$taskId = 123;
// ID пользователя, имеющего доступ к задаче
$userId = 1;
// ID задачи-клона
$duplicatedTaskId = 456;

try {
    $taskItem = CTaskItem::getInstance($taskId, $userId);
    $duplicatedTaskItem = CTaskItem::getInstance($duplicatedTaskId, $userId);
    $duplicatedChildTaskItems = $taskItem->duplicateChildTasks($duplicatedTaskItem);

    if (!empty($duplicatedChildTaskItems)) {
        echo "Подзадачи успешно скопированы в задачу-клон. IDs скопированных подзадач: ";
        foreach ($duplicatedChildTaskItems as $duplicatedChildTaskItem) {
            echo $duplicatedChildTaskItem->getId() . ", ";
        }
    } else {
        echo "Не удалось скопировать подзадачи.";
    }
} catch (TasksException $e) {
    echo "Ошибка при копировании подзадач: " . $e->getMessage();
}
?>

23. addToFavorite()

Описание: Метод addToFavorite() добавляет текущую задачу в список «Избранное» для текущего пользователя.

Пример:

<?php
CModule::IncludeModule("tasks");

// ID существующей задачи
$taskId = 123;
// ID пользователя, имеющего доступ к задаче
$userId = 1;

try {
    $taskItem = CTaskItem::getInstance($taskId, $userId);
    $taskItem->addToFavorite();
    echo "Задача добавлена в 'Избранное'.";

} catch (TasksException $e) {
    echo "Ошибка при добавлении задачи в 'Избранное': " . $e->getMessage();
}
?>

24. deleteFromFavorite()

Описание: Метод deleteFromFavorite() удаляет текущую задачу из списка «Избранное» для текущего пользователя.

Пример:

<?php
CModule::IncludeModule("tasks");

// ID существующей задачи
$taskId = 123;
// ID пользователя, имеющего доступ к задаче
$userId = 1;

try {
    $taskItem = CTaskItem::getInstance($taskId, $userId);
    $taskItem->deleteFromFavorite();
    echo "Задача удалена из 'Избранное'.";

} catch (TasksException $e) {
    echo "Ошибка при удалении задачи из 'Избранное': " . $e->getMessage();
}
?>

25. toggleFavorite()

Описание: Метод toggleFavorite() переключает состояние «Избранное» для текущей задачи. Если задача была в «Избранном», она удаляется, если не была — добавляется. Возвращает true, если задача была добавлена в «Избранное», и false, если удалена.

Пример:

<?php
CModule::IncludeModule("tasks");

// ID существующей задачи
$taskId = 123;
// ID пользователя, имеющего доступ к задаче
$userId = 1;

try {
    $taskItem = CTaskItem::getInstance($taskId, $userId);
    $isFavorite = $taskItem->toggleFavorite();

    if ($isFavorite) {
        echo "Задача добавлена в 'Избранное'.";
    } else {
        echo "Задача удалена из 'Избранное'.";
    }

} catch (TasksException $e) {
    echo "Ошибка при переключении состояния 'Избранное': " . $e->getMessage();
}
?>

26. addProjectDependence()

Описание: Метод addProjectDependence() добавляет зависимость от другой задачи в рамках Ганта.

Пример:

<?php
CModule::IncludeModule("tasks");

// ID существующей задачи (родительской)
$taskId = 123;
// ID задачи, от которой нужно сделать зависимость
$parentTaskId = 987;
// ID пользователя, имеющего доступ к задаче
$userId = 1;

try {
    $taskItem = CTaskItem::getInstance($taskId, $userId);
    $taskItem->addProjectDependence($parentTaskId);
    echo "Зависимость от задачи с ID " . $parentTaskId . " успешно добавлена.";

} catch (TasksException $e) {
    echo "Ошибка при добавлении зависимости: " . $e->getMessage();
} catch (ActionNotAllowedException $e) {
    echo "Действие не разрешено: " . $e->getMessage();
} catch (ActionFailedException $e) {
    echo "Не удалось добавить зависимость: " . $e->getMessage();
}
?>

27. updateProjectDependence()

Описание: Метод updateProjectDependence() обновляет тип зависимости от другой задачи в рамках Ганта.

Пример:

<?php
CModule::IncludeModule("tasks");

// ID существующей задачи (родительской)
$taskId = 123;
// ID задачи, от которой зависимость уже существует
$parentTaskId = 987;
// ID пользователя, имеющего доступ к задаче
$userId = 1;
// Новый тип зависимости (пример)
$linkType = CTaskDependenceTable::LINK_TYPE_START_START;

try {
    $taskItem = CTaskItem::getInstance($taskId, $userId);
    $taskItem->updateProjectDependence($parentTaskId, $linkType);
    echo "Тип зависимости от задачи с ID " . $parentTaskId . " успешно обновлен.";

} catch (TasksException $e) {
    echo "Ошибка при обновлении типа зависимости: " . $e->getMessage();
} catch (ActionNotAllowedException $e) {
    echo "Действие не разрешено: " . $e->getMessage();
} catch (ActionFailedException $e) {
    echo "Не удалось обновить тип зависимости: " . $e->getMessage();
}
?>

28. deleteProjectDependence()

Описание: Метод deleteProjectDependence() удаляет зависимость одной задачи от другой в рамках Ганта.

Пример:

<?php
CModule::IncludeModule("tasks");

// ID существующей задачи (родительской)
$taskId = 123;
// ID задачи, от которой нужно удалить зависимость
$parentTaskId = 987;
// ID пользователя, имеющего доступ к задаче
$userId = 1;

try {
    $taskItem = CTaskItem::getInstance($taskId, $userId);
    $taskItem->deleteProjectDependence($parentTaskId);
    echo "Зависимость от задачи с ID " . $parentTaskId . " успешно удалена.";

} catch (TasksException $e) {
    echo "Ошибка при удалении зависимости: " . $e->getMessage();
} catch (ActionNotAllowedException $e) {
    echo "Действие не разрешено: " . $e->getMessage();
} catch (ActionFailedException $e) {
    echo "Не удалось удалить зависимость: " . $e->getMessage();
}
?>

Важно:

• Замените 123 (и другие примеры IDs) на реальные ID существующих задач в вашей системе.
• Убедитесь, что пользователь с ID 1 (или другим $userId в примерах) имеет доступ к задачам, с которыми вы работаете.
• Не забудьте про обработку исключений TasksException и других возможных исключений, как показано в примерах.

8. REST API для задач (tasks.task.*)

Для более гибкой интеграции задач в веб-приложения и внешние системы, Битрикс24 предоставляет REST API. Методы REST API для задач доступны через пространство имен tasks.task.*.

Получение доступных полей задачи (tasks.task.getFields)

Метод tasks.task.getFields позволяет получить список всех доступных полей задачи, их типы и описания. Это полезно для динамического построения форм и фильтров.

<?php
require_once (__DIR__."/crest.php"); // Подключение библиотеки REST API

// Вызов метода rest api tasks.task.getFields
$arTaskFields = CRest::call(
    'tasks.task.getFields',
    [] // Пустой массив параметров
);

// Вывод результата (для отладки)
echo "<pre>";
var_dump($arTaskFields);
echo "</pre>";
?>

Создание задачи через REST API (tasks.task.add)

Метод tasks.task.add используется для создания новых задач через REST API.

<?php
require_once (__DIR__."/crest.php"); // Подключение библиотеки REST API

$result = CRest::call(
    'tasks.task.add',
    [
        "fields" => [
            "TITLE" => "test task name", // Название задачи
            "RESPONSIBLE_ID" => 1, // ID ответственного пользователя
            "DESCRIPTION" => "Здесь должно быть описание задачи", // Описание задачи
            "UF_CRM_TASK" => ["D_2", "L_2", "C_2"], // Привязка к CRM (сделка, лид, контакт)
            "UF_AUTO_397120965343" => "значение строкового поля", // Пример пользовательского строкового поля
            "UF_AUTO_623440760361" => 777, // Пример пользовательского числового поля
            "UF_AUTO_481217671836" => "15.02.2024 01:01:00", // Пример пользовательского поля даты
            "UF_AUTO_405537248694" => true, // Пример пользовательского логического поля
        ]
    ]
);

// Вывод результата (для отладки)
echo "<pre>";
var_dump($result);
echo "</pre>";
?>

Изменение (обновление) задачи через REST API (tasks.task.update)

Метод tasks.task.update позволяет обновлять существующие задачи.

<?php
require_once(__DIR__."/crest.php"); // Подключение библиотеки REST API

$result = CRest::call(
    'tasks.task.update',
    [
        "taskId" => 30, // ID задачи, которую нужно обновить
        "fields" => [
            "TITLE" => "new test task name", // Новое название задачи
        ]
    ]
);

// Вывод результата (для отладки)
echo "<pre>";
var_dump($result);
echo "</pre>";
?>

Получение данных о задаче через REST API (tasks.task.get)

Метод tasks.task.get используется для получения данных конкретной задачи по ее ID.

<?php
require_once(__DIR__."/crest.php"); // Подключение библиотеки REST API

$result = CRest::call(
    'tasks.task.get',
    [
        "taskId" => 30, // ID задачи, данные которой нужно получить
        "select" => ["ID", "TITLE"] // Выбор полей для получения (ID, TITLE)
    ]
);

// Вывод результата (для отладки)
echo "<pre>";
var_dump($result);
echo "</pre>";
?>

Получение списка задач через REST API (tasks.task.list)

Метод tasks.task.list позволяет получить массив задач с фильтрацией и постраничной навигацией.

<?php
require_once (__DIR__."/crest.php"); // Подключение библиотеки REST API

$result = CRest::call(
    'tasks.task.list',
    [
        "select" => ["ID", "TITLE"], // Выбор полей для получения (ID, TITLE)
        "order" => ["ID" => "DESC"], // Сортировка по ID в обратном порядке
        "filter" => ["!STATUS" => 5], // Фильтр: исключить задачи со статусом 5 (завершенные)
    ]
);

// Вывод результата (для отладки)
echo "<pre>";
var_dump($result);
echo "</pre>";
?>

Удаление задачи через REST API (tasks.task.delete)

Метод tasks.task.delete используется для удаления задачи по ее ID.

<?php
require_once (__DIR__."/crest.php"); // Подключение библиотеки REST API

$result = CRest::call(
    'tasks.task.delete',
    [
        "taskId" => 28, // ID задачи, которую нужно удалить
    ]
);

// Вывод результата (для отладки)
echo "<pre>";
var_dump($result);
echo "</pre>";
?>

Завершение задачи через REST API (tasks.task.complete)

Метод tasks.task.complete используется для завершения задачи.

<?php
require_once (__DIR__."/crest.php"); // Подключение библиотеки REST API

$result = CRest::call(
    'tasks.task.complete',
    [
        "taskId" => 30 // ID задачи, которую нужно завершить
    ]
);

// Вывод результата (для отладки)
echo "<pre>";
var_dump($result);
echo "</pre>";
?>

Дополнительные методы REST API (tasks.task.*):

• tasks.task.getcounters: Возвращает счетчики задач для текущего пользователя. Полезно для отображения количества новых, просроченных и других типов задач в интерфейсе.
• tasks.task.timer.start(taskId): Запускает таймер учета времени для задачи.
• tasks.task.timer.pause(taskId): Приостанавливает таймер учета времени для задачи.
• tasks.task.timer.complete(taskId): Завершает таймер учета времени для задачи.
• tasks.task.checklistitem.add(taskId, fields): Добавляет пункт в чек-лист задачи.
• tasks.task.checklistitem.getlist(taskId): Возвращает список пунктов чек-листа задачи.
• tasks.task.checklistitem.update(taskId, itemId, fields): Обновляет пункт чек-листа.
• tasks.task.checklistitem.delete(taskId, itemId): Удаляет пункт чек-листа.
• tasks.task.commentitem.add(taskId, fields): Добавляет комментарий к задаче.
• tasks.task.commentitem.getlist(taskId): Возвращает список комментариев к задаче.
• tasks.task.commentitem.get(taskId, itemId): Возвращает данные конкретного комментария.
• tasks.task.commentitem.update(taskId, itemId, fields): Обновляет комментарий.
• tasks.task.commentitem.delete(taskId, itemId): Удаляет комментарий.

8.1. Обработка ошибок и отладка

При работе с API задач важно правильно обрабатывать ошибки и уметь отлаживать код.

• Проверка результатов выполнения методов: Все методы API возвращают объекты, содержащие информацию об успехе выполнения и, в случае ошибки, массив ошибок. Всегда проверяйте isSuccess() и getErrors() для обработки возможных проблем.

<?php
$result = CTaskItem::add($newTask, 1);

if (!$result->isSuccess()) {
    $errors = $result->getErrors()->getMessages();
    foreach ($errors as $error) {
        echo "Ошибка: " . $error->getMessage() . " (Код: " . $error->getCode() . ")<br>";
    }
} else {
    $taskId = $result->getId();
    echo "Задача успешно создана, ID: " . $taskId;
}
?>

• Использование CAdminException для обработки ошибок в административном интерфейсе: При разработке административных страниц Битрикс24 используйте CAdminException для корректного отображения ошибок пользователю.
• Логирование ошибок: В продакшн-среде рекомендуется вести логирование ошибок для последующего анализа и исправления. Используйте CEventLog::Add() или собственные механизмы логирования.
• Отладка с помощью var_dump() и <pre>: Для отладки в процессе разработки используйте var_dump() и тег <pre> для просмотра содержимого переменных и массивов, возвращаемых API.

9. Оптимизация производительности при работе с задачами

При работе с большим количеством задач важно учитывать производительность вашего кода.

• Пакетные запросы (REST API): Используйте пакетные запросы REST API (batch метод) для выполнения нескольких операций за один запрос. Это снижает нагрузку на сервер и ускоряет выполнение операций.
• Эффективная фильтрация: Тщательно продумывайте фильтры для CTasks::GetList() и tasks.task.list, чтобы сократить количество получаемых задач и уменьшить нагрузку на базу данных.
• Кеширование данных: Используйте механизмы кеширования Битрикс24 для хранения часто используемых данных (например, списков задач, данных пользователей) и снижения нагрузки на базу данных.
• Использование CTaskItem::getInstance(): Для повторного доступа к задаче в рамках одного запроса используйте статический метод CTaskItem::getInstance(), который использует пул объектов и кеширование, что повышает производительность.
• Отложенные операции (агенты и очереди): Для длительных операций, таких как массовая обработка задач или отправка уведомлений, используйте агенты Битрикс24 или собственные очереди задач, чтобы не блокировать основной поток выполнения и обеспечить отзывчивость системы.

10. Безопасность при работе с API задач

• Проверка прав доступа: Всегда проверяйте права доступа пользователя перед выполнением операций с задачами, используя методы checkAccess() класса CTaskItem или TaskAccessController.
• Фильтрация входных данных: Очищайте и валидируйте все входные данные, получаемые от пользователей или внешних систем, перед использованием их в запросах к API задач, чтобы предотвратить SQL-инъекции и другие угрозы безопасности.
• Ограничение доступа к API: Ограничьте доступ к API задач только доверенным пользователям или приложениям. Используйте права доступа Битрикс24 для контроля доступа к модулю «Задачи» и его API.
• Использование HTTPS: Всегда используйте HTTPS для обмена данными с API Битрикс24, чтобы защитить данные от перехвата и несанкционированного доступа.

Заключение:

В этой статье мы подробно рассмотрели различные методы работы с задачами в Битрикс24 «коробка», от базового подключения модуля до использования REST API.

Используйте полученные знания для создания эффективных решений на базе Битрикс24!