Основные команды

К основным командам относятся действия создания, редактирования и удаления задачи.

Примечание: все команды располагаются в пространсве имен Bitrix\Tasks\V2\Public\Command

Объект задачи

Прежде чем приступать к рассмотрению команд, сначала необходимо понять доменную модель. Большинство команд работает не массивом данных, а с нормализованной моделью или специальными объектами, так например задача определяется классом Bitrix\Tasks\V2\Internal\Entity\Task, а пользователь Bitrix\Tasks\V2\Internal\Entity\User. Прежде чем рассматривать команды, необходимо посмотреть из чего состоят эти сущности и как их получать.

Рассматрим Entity\Task - класс описывающий задачу до или после изменений в системе. Основные поля объекта задачи:

Поле	Тип	Описание
`id`	int?	ID задачи (не указывается при создании)
`title`	string?	Название задачи (обязательно)
`description`	string?	Описание задачи (HTML/текст)
`creator`	User?	Создатель задачи (обязательно)
`responsible`	User?	Ответственный пользователь
`deadlineTs`	int?	Срок выполнения (timestamp)
`startPlanTs`	int?	Планируемая дата начала
`endPlanTs`	int?	Планируемая дата окончания
`parentId`	int?	ID родительской задачи
`group`	Group?	Группа проекта
`stage`	Stage?	Статус/стадия задачи
`flow`	Flow?	Бизнес-процесс задачи
`priority`	Priority?	Приоритет (`low`, `medium`, `high`)
`status`	Status?	Статус задачи (`new`, `inprogress`, `completed` и т.д.)
`accomplices`	UserCollection?	Соисполнители
`auditors`	UserCollection?	Аудиторы
`fileIds`	array?	ID файлов вложения
`checklist`	array?	Чек-лист задачи
`epicId`	int?	ID эпака
`storyPoints`	string?	Story points
`tags`	TagCollection?	Теги задачи
`reminders`	ReminderCollection?	Напоминания
`chatId`	int?	ID чата для задачи
`source`	Source?	Источник создания задачи

Пример создания объекта:

use Bitrix\Tasks\V2\Internal\Entity\Task;

$taskDTO = new Task(
	title: "Название задачи",
	creator: new User(id:123)
);

Создание задачи

AddTaskCommand создаёт новую задачу в системе. Это основная команда для добавления задач с возможностью указания всех параметров задачи и опций выполнения.

Входные аргументы:

Параметр	Тип	Обязательный	Описание
`$task`	`Entity\Task`	Да	Объект задачи с параметрами новой задачи
`$config`	`AddConfig`	Да	Конфигурация добавления задачи

AddConfig - объект конфигурации для настройки процесса создания задачи, может содержать следующие поля:

Параметр	Тип	Значение по умолчанию	Описание
`userId`	int	-	ID пользователя, от которого создается задача
`fromAgent`	bool	`false`	Флаг создания через агента
`fromWorkFlow`	bool	`false`	Флаг создания через workflow
`checkFileRights`	bool	`false`	Проверять права на файлы
`cloneAttachments`	bool	`false`	Клонировать вложения
`byPassParameters`	array	`[]`	Параметры обхода (для интеграции)
`skipBP`	bool	`false`	Пропустить запуск бизнес-процессов
`skipTimeZoneFields`	array	`[]`	Поля для пропуска конвертации часовых поясов
`needCorrectDatePlan`	bool	`true`	Корректировать плановые даты
`useConsistency`	bool	`false`	Использовать консистентность данных
`checkUserFields`	bool	`true`	Проверять пользовательские поля
`eventGuid`	string?	`null`	GUID события для синхронизации
`runtime`	`RuntimeData`	`new RuntimeData()`	Дополнительные параметры выполнения

Пример использования команды:

use Bitrix\Tasks\V2\Internal\Entity\Task;
use Bitrix\Tasks\V2\Internal\Entity\User;
use Bitrix\Tasks\V2\Internal\Entity\Task\Group;
use Bitrix\Tasks\V2\Internal\Service\Task\Action\Add\Config\AddConfig;
use Bitrix\Tasks\V2\Public\Command\Task\AddTaskCommand;
use Bitrix\Tasks\V2\Internal\Entity\Task\Priority;

$creator = new User(
    id: 123,
    name: 'Иван Иванов',
    email: 'ivan@example.com'
);

$responsible = new User(
    id: 456,
    name: 'Петр Петров',
    email: 'petr@example.com'
);

$task = new Task(
    title: 'Подготовить отчет за квартал',
    description: 'Необходимо собрать данные и подготовить отчет',
    creator: $creator,
    responsible: $responsible,
    deadlineTs: strtotime('+7 days'),
    startPlanTs: time(),
    group: new Group(id: 10),
    priority: Priority::High
);

$config = new AddConfig(
    userId: 123,
    fromAgent: false,
    skipBP: false,
    needCorrectDatePlan: true
);

$command = new AddTaskCommand($task, $config);

/**
 * @var Bitrix\Tasks\V2\Internal\Result\Result
 */
$result = $command->run();
    
if ($result->isSuccess()) {
    $newTask = $result->getObject();
    echo "Задача создана. ID: {$newTask->getId()}";
} else {
    foreach ($result->getErrors() as $error) {
        echo "Ошибка: {$error->getMessage()}";
    }
}

Редактирование задачи

UpdateTaskCommand обновляет существующую задачу в системе. Позволяет изменять параметры задачи и управлять поведением обработки изменений через конфигурацию.

Входные аргументы:

Параметр	Тип	Обязательный	Описание
`$task`	`Entity\Task`	Да	Объект задачи с новыми значениями (только изменяемые поля)
`$config`	`UpdateConfig`	Да	Конфигурация обновления задачи
`$taskBeforeUpdate`	`null	Entity\Task`?	Нет
`$taskChangesContext`	`null	Entity\Task`?	Нет

UpdateConfig — объект конфигурации для настройки процесса редактирования задачи, может содержать следующие поля:

Параметр	Тип	Значение по умолчанию	Описание
`userId`	int	-	ID пользователя, выполняющего обновление
`needCorrectDatePlan`	bool	`true`	Корректировать даты плана при изменении зависимостей
`checkFileRights`	bool	`false`	Проверять права доступа к файлам
`correctDatePlanDependent`	bool	`true`	Корректировать планы зависимых задач
`skipTimeZoneFields`	array	`[]`	Поля для пропуска конвертации часовых поясов
`needAutoclose`	bool	`true`	Автоматически закрывать задачу при завершении
`skipNotifications`	bool	`false`	Пропустить отправку уведомлений
`skipRecount`	bool	`false`	Пропустить пересчет агрегированных данных
`byPassParameters`	array	`[]`	Параметры обхода
`skipComments`	bool	`false`	Пропустить создание комментариев об изменениях
`skipPush`	bool	`false`	Пропустить push-уведомления
`skipBP`	bool	`false`	Пропустить бизнес-процессы
`useConsistency`	bool	`false`	Использовать консистентность данных
`eventGuid`	string?	`null`	GUID события
`runtime`	`RuntimeData`	`new RuntimeData()`	Дополнительные параметры выполнения

Пример редактирования задачи:

use Bitrix\Tasks\V2\Internal\Entity\Task;
use Bitrix\Tasks\V2\Internal\Entity\User;
use Bitrix\Tasks\V2\Internal\Service\Task\Action\Update\Config\UpdateConfig;
use Bitrix\Tasks\V2\Public\Command\Task\UpdateTaskCommand;

/**
 * Task ID to update
 * @var        int
 */
$taskId = 999;

$updatedTask = new Task(
    id: $taskId,
    title: 'New title',
    description: 'New description',
    responsible: new User(id: 456),
    deadlineTs: strtotime('+5 days')
);

$config = UpdateConfig::createFromArray(
    userId: 123,
    parameters: [
        'CORRECT_DATE_PLAN' => true,
        'AUTO_CLOSE' => true,
        'SEND_UPDATE_PULL_EVENT' => true
    ]
);

$command = new UpdateTaskCommand($updatedTask, $config);

$result = $command->run();

if ($result->isSuccess()) {
    $task = $result->getObject();
    echo "Задача {$task->getId()} обновлена\n";
    echo "Название: {$task->getTitle()}\n";
    echo "Статус: {$task->getStatus()?->value}\n";
} else {
    foreach ($result->getErrors() as $error) {
        echo "Ошибка: {$error->getMessage()}\n";
    }
}

Конфигурация `UpdateConfig`

Существует несколько способов создать объект конфигурации для настройки:

Через конструктор:

$config = new UpdateConfig(
    userId: 123,
    needCorrectDatePlan: true,
    skipNotifications: false
);

Через фабричный-метод createFromArray

$config = UpdateConfig::createFromArray(
    userId: 123,
    parameters: [
        'CORRECT_DATE_PLAN' => true,           // Корректировать даты
        'CORRECT_DATE_PLAN_DEPENDENT_TASKS' => true,  // Корректировать зависимые
        'AUTO_CLOSE' => true,                  // Автозакрытие
        'SKIP_NOTIFICATION' => true,           // Без уведомлений
        'SEND_UPDATE_PULL_EVENT' => true,      // Отправлять pull-event
        'META::EVENT_GUID' => 'xxx-yyy-zzz',   // GUID события
        'THROTTLE_MESSAGES' => true,           // Троттлинг сообщений
        'FIELDS_FOR_COMMENTS' => true          // Создавать комментарий к изменениям
    ]
);

Копирование задачи

CopyTaskCommand создаёт копию существующей задачи со всеми её параметрами. Позволяет быстро создать похожую задачу на основе шаблона.

Входные аргументы:

Параметр	Тип	Обязательный	Описание
`$task`	`Entity\Task`	Да	Объект копируемой задачи
`$config`	`CopyConfig`	Да	Конфигурация копирования задачи

CopyConfig — объект конфигурации для настройки процесса копирования задачи, может содержать следующие поля:

Параметр	Тип	Значение по умолчанию	Описание
`userId`	int	-	ID пользователя, выполняющего копирование
`withSubTasks`	bool	`false`	Копировать подзадачи
`withCheckLists`	bool	`false`	Копировать чек-листы
`withAttachments`	bool	`false`	Копировать вложения
`withRelatedTasks`	bool	`false`	Копировать связанные задачи
`withReminders`	bool	`false`	Копировать напомнинания
`withGanttLinks`	bool	`false`	Копировать связи из Ганта
`useConsistency`	bool	`false`	Использовать консистентность данных
`targetTaskId`	?int	`null`	Идентификатор задачи, куда нужно копировать изменения (если указан, то данные будут копированы в нее)

Пример выполнения:

use Bitrix\Tasks\V2\Public\Command\Task\Copy\CopyTaskCommand;
use Bitrix\Tasks\V2\Internal\Service\Task\Action\Copy\Config\CopyConfig;

/**
 * Original task from database
 * @var        Task
 */
$originalTask = new Task(
    id: 123,
    title: 'New title',
    description: 'New description',
    responsible: new User(id: 456),
    deadlineTs: strtotime('+5 days')
);

$copyConfig = new CopyConfig(
	userId: 1, // Who copy
	withCheckLists: true,
	withAttachments: true,
	useConsistency: true
);

$command = new CopyTaskCommand(
	$originalTask,
	$copyConfig
);

$result = $command->run();
    
if ($result->isSuccess()) {
    $newTask = $result->getObject();
    echo "Копия задачи создана с ID: {$newTask->getId()}";
    echo "\nНазвание: {$newTask->getTitle()}";
} else {
    foreach ($result->getErrors() as $error) {
        echo "Ошибка: {$error->getMessage()}";
    }
}

Изменение крайнего срока

UpdateDeadlineCommand обновляет срок выполнения задачи (дедлайн). Позволяет устанавливать новую дату и время завершения задачи.

Входные аргументы:

Параметр	Тип	Обязательный	Описание
`$taskId`	int	Да	ID задачи
`$deadlineTs`	int	Да	Новая дата дедлайна в виде timestamp ( UNIX timestamp)
`$updateConfig`	UpdateConfig	Да	Конфигурация к обновлению задачи
`$reason`	?string	Нет	Комментарий к изменению дедлайна

Пример выполнения:

use Bitrix\Tasks\V2\Public\Command\Task\Deadline\UpdateDeadlineCommand;
use Bitrix\Tasks\V2\Internal\Service\Task\Action\Update\Config\UpdateConfig;

$command = new UpdateDeadlineCommand(
    taskId: 1,
    deadlineTs: strtotime('+7 days'),
    updateConfig: new UpdateConfig(userId: 123),
    reason: 'Срок сдвинут по запросу клиента'
);

$result = $command->run();
    
if (!$result->isSuccess()) {
    foreach ($result->getErrors() as $error) {
        echo "Ошибка: {$error->getMessage()}";
    }
}

Удаление задачи

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

Входные аргументы:

Параметр	Тип	Обязательный	Описание
`$taskId`	int	Да	ID задачи для удаления (должен быть положительным числом)
`$config`	`DeleteConfig`	Да	Конфигурация удаления задачи
`$taskBefore`	`Entity\Task`?	Нет	Объект задачи до удаления (для логирования/аудита)

DeleteConfig — объект конфигурации для настройки процесса удаления задачи, может содержать следующие поля:

Параметр	Тип	Значение по умолчанию	Описание
`userId`	int	-	ID пользователя, выполняющего удаление
`byPassParameters`	array	`[]`	Дополнительные параметры, для своих обработчиков и обхода для интеграций
`skipExchangeSync`	bool	`false`	Пропустить синхронизацию с Exchange
`eventGuid`	string?	`null`	GUID события для синхронизации
`skipBP`	bool	`false`	Пропустить бизнес-процессы при удалении
`useConsistency`	bool	`false`	Использовать консистентность данных
`runtime`	`RuntimeData`	`new RuntimeData()`	Дополнительные параметры удаления

Пример выполнения:

use Bitrix\Tasks\V2\Internal\Service\Task\Action\Delete\Config\DeleteConfig;
use Bitrix\Tasks\V2\Public\Command\Task\DeleteTaskCommand;

/**
 * Task id to delete
 *
 * @var        int
 */
$taskId = 12345;

$config = new DeleteConfig(
    userId: 123,
    skipExchangeSync: false,
    skipBP: false,
    useConsistency: true
);

$command = new DeleteTaskCommand(
    taskId: $taskId,
    config: $config
);

$result = $command->run();

if ($result->isSuccess()) {
    echo "Задача {$taskId} успешно удалена";
} else {
    foreach ($result->getErrors() as $error) {
        echo "Ошибка удаления: {$error->getMessage()}";
    }
}

Обработка результата

Результат каждой команды - это Bitrix\Tasks\V2\Internal\Result\Result, наследник Bitrix\Main\Result, обогощенный специализированными методами для упрощения работы с результатом.

Если вы еще не работали с результатами, рекоменду ознакомиться со статьей в документации описыющую работу с результатом и ошибками.

Мы рассмотрим лишь отличающиеся методы, которые полезны в нашей повседневной работе:

getId(): null|int|string - возвращает идентификатор созданной/измененной сущности.
getCollection(): ?EntityCollectionInterface - возвращает объект коллекции элементов.
getObject(): ?EntityInterface - возвращает объект элемента.
getDataByKey(string $key): mixed - возвращает значение из data-массива по ключу.

Пример успешного выполнения

При выполнении AddTaskCommand возвращается объект Result:

isSuccess() → true
getObject() → возвращает созданный объект \Bitrix\Tasks\V2\Internal\Entity\Task
getId() → ID созданной задачи

Пример ответа:

Result {
    isSuccess(): true,
    getId(): 999,
    getObject(): Task {
        id: 999,
        title: 'Подготовить отчет за квартал',
        ...
    }
}

Пример ошибки

Пример ответа при ошибке создания задачи (нет соединения с БД):

Result {
    isSuccess(): false,
    errors: [
        Error {
            code: 'TASK_NOT_CREATED',
            message: 'Не удалось создать задачу: Connection refused',
            details: [...]
        }
    ]
}

Пример ошибки обновления несуществующей задачи:

Result {
    isSuccess(): false,
    errors: [
        Error {
            code: 'TASK_NOT_FOUND',
            message: 'Задача с ID 99999 не найдена'
        }
    ]
}

Пример ошибки связанной с правами доступа:

Result {
    isSuccess(): false,
    errors: [
        Error {
            code: 'ACCESS_DENIED',
            message: 'Нет прав на обновление этой задачи'
        }
    ]
}

Модуль Задачи > Основные команды

#Основные команды

#Объект задачи

#Создание задачи

#Редактирование задачи

#Конфигурация UpdateConfig

#Копирование задачи

#Изменение крайнего срока

#Удаление задачи

#Обработка результата

#Пример успешного выполнения

#Пример ошибки

Основные команды

Объект задачи

Создание задачи

Редактирование задачи

Конфигурация `UpdateConfig`

Копирование задачи

Изменение крайнего срока

Удаление задачи

Обработка результата

Пример успешного выполнения

Пример ошибки