Программное создание напоминаний в задачах Битрикс24: полное руководство для разработчика

Автоматизация рутинных процессов — одна из ключевых задач при разработке под Битрикс24. Часто возникает необходимость программно создавать напоминания для задач: например, за час до крайнего срока, при смене статуса или по другому бизнес-событию.

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

Основа основ: класс CTaskReminders

Для всех операций с напоминаниями в задачах используется класс CTaskReminders. Несмотря на наличие более нового ORM API для задач, этот класс остается надежным и широко используемым инструментом, особенно для обратной совместимости и в тех случаях, когда требуется прямое и быстрое управление напоминаниями.

Ключевой метод, который нас интересует — Add(). Он добавляет новую запись о напоминании в базу данных.

Разбор метода CTaskReminders::Add()

Метод Add() принимает один аргумент — массив с полями будущего напоминания. Давайте детально разберем предоставленный вами рабочий пример:

<?php
// Подключаем модуль "Задачи", без этого ничего не сработает
if (\Bitrix\Main\Loader::includeModule('tasks')) 
{
    $taskId = 123; // ID задачи, к которой привязываем напоминание
    $userId = 456; // ID пользователя, который получит напоминание
    
    // Вычисляем время напоминания (например, сейчас + 1 час)
    $reminderTimestamp = time() + 3600; 
    
    $reminder = new CTaskReminders();
    $reminderId = $reminder->Add([
        'TASK_ID'     => $taskId,
        'USER_ID'     => $userId,
        'REMIND_DATE' => ConvertTimeStamp($reminderTimestamp, "FULL"), // Важнейший момент!
        'TYPE'        => CTaskReminders::REMINDER_TYPE_DEADLINE, // 'D'
        'TRANSPORT'   => CTaskReminders::REMINDER_TRANSPORT_EMAIL, // 'E'
    ]);

    if ($reminderId) {
        echo "Напоминание с ID {$reminderId} успешно создано.";
    } else {
        global $APPLICATION;
        if($e = $APPLICATION->GetException()) {
            echo "Ошибка: " . $e->GetString();  
        } else {
            echo "Неизвестная ошибка при создании напоминания.";
        }
    }
}
?>

Ключевые параметры массива:

• TASK_ID (обязательный): integer — ID задачи, к которой привязывается напоминание.
• USER_ID (обязательный): integer — ID пользователя, который получит уведомление. Чаще всего это ответственный по задаче.
• REMIND_DATE (обязательный): string — Дата и время, когда должно сработать напоминание. Это самый важный и частый источник ошибок. Дата должна быть передана в формате, который соответствует полному формату даты на сайте (DD.MM.YYYY HH:MI:SS). Надежный способ — подготовить timestamp и преобразовать его функцией ConvertTimeStamp($timestamp, «FULL»).
• TYPE (обязательный): char(1) — Тип напоминания. Используйте константы класса:
  • CTaskReminders::REMINDER_TYPE_DEADLINE (‘D’) — Напоминание привязано к крайнему сроку. Важно: при изменении дедлайна такое напоминание не сдвигается автоматически, его нужно удалять и создавать заново.
  • CTaskReminders::REMINDER_TYPE_COMMON (‘A’) — Обычное напоминание на указанную дату.
• TRANSPORT (обязательный): char(1) — Способ доставки уведомления.
  • CTaskReminders::REMINDER_TRANSPORT_EMAIL (‘E’) — Отправить на E-mail.
  • CTaskReminders::REMINDER_TRANSPORT_JABBER (‘J’) — Отправить в чат Битрикс24 (Jabber).
• RECEPIENT_TYPE (опционально, но рекомендуется): char(1) — Уточняет роль получателя. Для явного указания, что напоминание для конкретного USER_ID, используйте CTaskReminders::RECEPIENT_TYPE_SELF (‘S’).

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

Самый частый кейс — автоматическое создание напоминания при постановке задачи. Идеальное место для этого — обработчик события OnTaskAdd.

Шаг 1: Регистрируем обработчик

Добавьте в файл /local/php_interface/init.php 

следующий код:

<?php
// /local/php_interface/init.php

use Bitrix\Main\EventManager;

$eventManager = EventManager::getInstance();

$eventManager->addEventHandler(
    'tasks',
    'OnTaskAdd',
    'createDeadlineReminderOnTaskAdd'
);

function createDeadlineReminderOnTaskAdd($taskId, &$arFields)
{
    // Проверяем, что есть крайний срок и ответственный
    if (
        !empty($arFields['DEADLINE']) 
        && !empty($arFields['RESPONSIBLE_ID']) 
        && \Bitrix\Main\Loader::includeModule('tasks')
    ) {
        try {
            // Преобразуем крайний срок в timestamp
            $deadlineTimestamp = MakeTimeStamp($arFields['DEADLINE'], CSite::GetDateFormat("FULL"));
            if ($deadlineTimestamp === false) {
                return; // Не удалось распознать дату
            }
            
            // Вычисляем время напоминания: за 1 час до крайнего срока
            $reminderTimestamp = $deadlineTimestamp - 3600;
            
            // Не создаем напоминание, если оно уже в прошлом
            if ($reminderTimestamp < time()) {
                return;
            }
            
            $reminder = new CTaskReminders();
            $reminder->Add([
                'TASK_ID'     => $taskId,
                'USER_ID'     => $arFields['RESPONSIBLE_ID'],
                'REMIND_DATE' => ConvertTimeStamp($reminderTimestamp, "FULL"),
                'TYPE'        => CTaskReminders::REMINDER_TYPE_DEADLINE,
                'TRANSPORT'   => CTaskReminders::REMINDER_TRANSPORT_JABBER, // Отправляем в чат
                'RECEPIENT_TYPE' => CTaskReminders::RECEPIENT_TYPE_SELF,
            ]);

        } catch (\Exception $e) {
            // Опционально: логируем ошибку, если что-то пошло не так
            // AddMessage2Log($e->getMessage());
        }
    }
}

Что делает этот код:

1. «Цепляется» к событию OnTaskAdd, которое срабатывает после создания задачи.
2. Проверяет, есть ли у новой задачи крайний срок (DEADLINE).
3. Вычисляет время напоминания, отнимая 1 час (3600 секунд) от крайнего срока.
4. Проверяет, не оказалось ли время напоминания в прошлом (если задачу создали с уже горящим дедлайном).
5. Используя CTaskReminders::Add(), создает напоминание в чат для ответственного.

Важные моменты и частые ошибки

• Формат даты: Всегда используйте ConvertTimeStamp($timestamp, «FULL») для поля REMIND_DATE. Это самая частая причина «молчаливых» ошибок, когда метод Add() просто возвращает false без объяснения.
• Права доступа: Убедитесь, что код, вызывающий Add(), выполняется с достаточными правами. В контексте системных событий (OnTaskAdd и др.) это обычно не является проблемой.
• Проверка результата: Всегда проверяйте результат выполнения метода Add(). Если он вернул false или 0, значит напоминание не было создано. Используйте global $APPLICATION; $APPLICATION->GetException() для получения текста ошибки.

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