Поля, участники и статусы задач
Данные задачи доступны в двух формах. Класс ORM Bitrix\Tasks\Internals\TaskTable и классический API хранят их в полях с именами в верхнем регистре и числовыми константами. Объект задачи Bitrix\Tasks\V2\Internal\Entity\Task, который возвращает провайдер и принимают команды, хранит их в свойствах в стиле camelCase, а статус и приоритет — значениями enum.
Верхний регистр встречается в TaskTable, фильтрах запроса Bitrix\Tasks\Provider\Query\TaskQuery, обработчиках событий и классическом API. Стиль camelCase используют провайдер TaskProvider и команды. Используйте статью как справочник, когда переносите данные между TaskTable, фильтрами и объектом задачи.
Перед запуском примеров подключите пролог Bitrix Framework и модуль tasks. Полный код подключения приведен в первом примере раздела Участники и роли, в остальных примерах его нет. Выполняйте их после этого кода подключения.
Переменная $userId в примерах содержит ID сотрудника, от имени которого выполняется действие, $taskId — ID задачи, $taskIds — массив ID задач.
Как читать и менять задачи, описано в статьях Чтение и выборка задач и Создание, изменение и удаление задач.
Основные поля задачи
Таблица сопоставляет поля TaskTable со свойствами объекта задачи Bitrix\Tasks\V2\Internal\Entity\Task и ключами массива для метода Task::mapFromArray(). Ключи массива строятся так:
-
для простых значений ключ совпадает с именем свойства,
-
для постановщика, ответственного, проекта и потока передают ключ с суффиксом
Idи числовым ID, напримерcreatorId, -
для соисполнителей и наблюдателей — ключ с суффиксом
Idsи массивом ID, напримерauditorsIds.
Прочерк в колонке ключа означает, что значение заполняет модуль. Типы значений для записи приведены в разделе Подготовить данные задачи.
Поле TaskTable |
Свойство объекта | Ключ для mapFromArray() |
Тип в объекте | Описание | Запись |
|---|---|---|---|---|---|
ID |
id |
id |
int |
ID задачи | Только при изменении, ключ id указывает задачу |
TITLE |
title |
title |
string |
Название | Да |
DESCRIPTION |
description |
description |
string |
Описание | Да |
CREATED_BY |
creator |
creatorId с ID пользователя |
Объект пользователя | Постановщик | Да |
RESPONSIBLE_ID |
responsible |
responsibleId с ID пользователя |
Объект пользователя | Ответственный | Да |
STATUS |
status |
— | enum Bitrix\Tasks\V2\Internal\Entity\Task\Status |
Статус. Значения приведены в разделе Статусы | Нет, только командами статуса |
PRIORITY |
priority |
priority со строковым значением enum |
enum Bitrix\Tasks\V2\Internal\Entity\Priority |
Приоритет. Значения приведены в разделе Приоритет | Да |
DEADLINE |
deadlineTs |
deadlineTs |
int, метка времени Unix |
Крайний срок | Да |
START_DATE_PLAN |
startPlanTs |
startPlanTs |
int, метка времени Unix |
Плановая дата начала | Да |
END_DATE_PLAN |
endPlanTs |
endPlanTs |
int, метка времени Unix |
Плановая дата завершения | Да |
DATE_START |
startedTs |
— | int, метка времени Unix |
Дата, когда задачу начали выполнять | Нет, заполняет модуль при переходе в статус «Выполняется» |
CREATED_DATE |
createdTs |
— | int, метка времени Unix |
Дата создания | Нет, заполняет модуль |
CHANGED_DATE |
changedTs |
— | int, метка времени Unix |
Дата последнего изменения | Нет, заполняет модуль |
ACTIVITY_DATE |
activityTs |
— | int, метка времени Unix |
Дата последней активности в задаче | Нет, заполняет модуль |
CLOSED_DATE |
closedTs |
— | int, метка времени Unix |
Дата завершения | Нет, заполняет модуль |
GROUP_ID |
group |
groupId с ID проекта |
Объект проекта | Проект | Да |
Нет поля. В фильтре TaskQuery — FLOW_ID |
flow |
flowId с ID потока |
Объект потока | Поток | Да |
PARENT_ID |
parentId |
parentId |
int |
ID родительской задачи | Да |
TASK_CONTROL |
needsControl |
needsControl |
bool. В TaskTable — значения Y и N |
Контроль постановщика после завершения | Да |
ALLOW_CHANGE_DEADLINE |
allowsChangeDeadline |
allowsChangeDeadline |
bool. В TaskTable — значения Y и N |
Ответственный может менять крайний срок | Да |
ALLOW_TIME_TRACKING |
allowsTimeTracking |
allowsTimeTracking |
bool. В TaskTable — значения Y и N |
Учет времени в задаче включен | Да |
XML_ID |
xmlId |
xmlId |
string |
Внешний код для связи с другой системой | Да |
| Нет поля. Хранится в параметрах задачи | requireResult |
requireResult |
bool |
Сотрудник не завершит задачу без результата | Да |
Если значение не задано или связанные данные не загружены, свойство объекта равно null. Обращайтесь к свойствам-объектам через оператор ?->. ID постановщика, ответственного и проекта возвращают выражения $task->creator?->id, $task->responsible?->id и $task->group?->id.
Свойства status, startedTs, createdTs, changedTs, activityTs и closedTs заполняет модуль, в таблице они отмечены в колонке «Запись». При создании и изменении задачи через Task::mapFromArray() их не передают. Статус меняют командами из раздела Статусы.
Поток задачи хранится отдельно от строки задачи, поэтому поля потока в TaskTable нет. Требование результата тоже хранится отдельно, в параметрах задачи.
Даты в TaskTable — объекты Bitrix\Main\Type\DateTime. В объекте задачи даты хранятся как метки времени Unix, поэтому имена свойств заканчиваются на Ts. Метка превращается в объект даты вызовом Bitrix\Main\Type\DateTime::createFromTimestamp().
При выборке через TaskTable добавляйте условие '=ZOMBIE' => 'N', как описано в разделе Прочитать строки через TaskTable. Иначе в выборку попадут служебные строки задач, удаленных старыми версиями модуля.
Участники и роли
У задачи четыре роли участников. Каждая роль определяет, что сотрудник видит и может делать в задаче. Какие действия доступны ролям, описано в статье Права доступа к задачам.
| Роль | Код в MemberTable |
Константа MemberTable |
Свойство объекта | Ключ для mapFromArray() |
Сколько участников |
|---|---|---|---|---|---|
| Постановщик | O |
MEMBER_TYPE_ORIGINATOR |
creator |
creatorId |
Один |
| Ответственный | R |
MEMBER_TYPE_RESPONSIBLE |
responsible |
responsibleId |
Один |
| Соисполнитель | A |
MEMBER_TYPE_ACCOMPLICE |
accomplices |
accomplicesIds |
Несколько |
| Наблюдатель | U |
MEMBER_TYPE_AUDITOR |
auditors |
auditorsIds |
Несколько |
Класс ORM Bitrix\Tasks\Internals\Task\MemberTable хранит всех участников задачи в таблице b_tasks_member. Каждая строка связывает задачу и сотрудника в одной роли. Поля строки перечислены ниже.
-
TASK_ID— ID задачи. -
USER_ID— ID сотрудника. -
TYPE— код роли из таблицы выше.
Постановщик и ответственный дополнительно записаны в поля CREATED_BY и RESPONSIBLE_ID таблицы задач. Первичный ключ таблицы участников состоит из трех полей TASK_ID, USER_ID и TYPE, поэтому один сотрудник может занимать в задаче несколько ролей.
Чтобы выбрать задачи сотрудника в любой роли, используйте поле фильтра MEMBER, а в роли ответственного или соисполнителя — DOER. Поля фильтра описаны в статье Чтение и выборка задач.
При создании задачи участников передают ключами из таблицы. У существующей задачи участников меняют командами из раздела Сменить статус или участников. Аргументы этих команд называются accompliceIds и auditorIds и отличаются от ключей accomplicesIds и auditorsIds.
Прочитать участников задачи
Участников одной задачи возвращает провайдер TaskProvider, если в параметрах TaskParams::mapFromIds() включен ключ members. Без этого ключа свойства creator, responsible, accomplices и auditors равны null. Провайдер проверяет право сотрудника на чтение задачи и возвращает null, если задачи нет или прав не хватает.
Свойства creator и responsible — объекты пользователей, ID возвращает свойство id. Свойства accomplices и auditors — коллекции пользователей. Массив ID возвращает метод getIdList() коллекции.
Пример. Код читает задачу с участниками и получает ID постановщика, ответственного, соисполнителей и наблюдателей.
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('Не удалось подключить модуль Задачи');
}
$task = (new TaskProvider())->get(
TaskParams::mapFromIds($taskId, $userId, ['members' => true])
);
if ($task === null)
{
throw new \RuntimeException('Задача не найдена или нет прав на чтение');
}
$creatorId = $task->creator?->id;
$responsibleId = $task->responsible?->id;
$accompliceIds = $task->accomplices?->getIdList() ?? [];
$auditorIds = $task->auditors?->getIdList() ?? [];
Другие параметры чтения описаны в разделе Прочитать одну задачу.
Прочитать участников списка задач
Метод TaskProvider::getList() загружает соисполнителей и наблюдателей для каждой задачи списка, а ответственного и постановщика — если в выборке есть ключи responsibleId и createdBy. Подробнее — в разделе Выбрать список задач.
Если ID задач уже известны, например из выборки TaskList, выберите строки MemberTable с фильтром по массиву ID задач. Так код выполнит один запрос вместо запроса на каждую задачу.
Класс MemberTable не проверяет права сотрудника. Передавайте в фильтр ID задач, которые сотрудник уже может читать.
Пример. Код собирает соисполнителей и наблюдателей для списка задач. Результат — массив, где ключ — ID задачи, а значение — массивы ID по кодам ролей.
use Bitrix\Tasks\Internals\Task\MemberTable;
$members = [];
if (!empty($taskIds))
{
$rows = MemberTable::getList([
'select' => ['TASK_ID', 'USER_ID', 'TYPE'],
'filter' => [
'@TASK_ID' => $taskIds,
'@TYPE' => [
MemberTable::MEMBER_TYPE_ACCOMPLICE,
MemberTable::MEMBER_TYPE_AUDITOR,
],
],
]);
while ($row = $rows->fetch())
{
$members[(int)$row['TASK_ID']][$row['TYPE']][] = (int)$row['USER_ID'];
}
}
// ID наблюдателей первой задачи из списка
$auditorIds = $members[$taskIds[0]][MemberTable::MEMBER_TYPE_AUDITOR] ?? [];
Код проверяет $taskIds перед запросом и не обращается к базе данных для пустого списка. Задачи без участников выбранных ролей в массив $members не попадут, поэтому читайте значения с оператором ??.
Статусы
Статус показывает этап выполнения задачи. В TaskTable статус — число из констант класса Bitrix\Tasks\Internals\Task\Status. В запросе TaskQuery то же число передают и получают полем REAL_STATUS. В объекте задачи статус — enum Bitrix\Tasks\V2\Internal\Entity\Task\Status со строковыми значениями.
Значения констант совпадают с классическими константами CTasks::STATE_*. Замены других классических констант приведены в статье Как выбрать API задач.
Константа Status |
Число | Значение enum | Case enum | Что означает |
|---|---|---|---|---|
NEW |
1 | — | — | Новая задача. Статус старых версий модуля, у новых задач не встречается. При чтении через провайдер свойство status объекта такой задачи равно null |
PENDING |
2 | pending |
Pending |
Ждет выполнения |
IN_PROGRESS |
3 | in_progress |
InProgress |
Выполняется |
SUPPOSEDLY_COMPLETED |
4 | supposedly_completed |
SupposedlyCompleted |
Ждет контроля постановщика |
COMPLETED |
5 | completed |
Completed |
Завершена |
DEFERRED |
6 | deferred |
Deferred |
Отложена |
DECLINED |
7 | declined |
Declined |
Отклонена. Статус старых версий модуля, командами не устанавливается |
У двух классов статусов одинаковое короткое имя Status. Если в одном файле нужны оба, задайте псевдоним в use, например use Bitrix\Tasks\V2\Internal\Entity\Task\Status as TaskStatus;.
Статус меняют командами из пространства имен Bitrix\Tasks\V2\Public\Command\Task\Status, а не записью поля.
-
Команда сохраняет статус и выполняет связанные действия, например отправляет уведомления участникам.
-
Каждая команда принимает аргументы
taskIdиconfigс объектомBitrix\Tasks\V2\Internal\Service\Task\Action\Update\Config\UpdateConfig. -
Аргумент
userIdобъектаUpdateConfigзадает сотрудника, от имени которого выполняется действие. -
Все команды из таблицы создаются одинаково, например
new StartTaskCommand(taskId: $taskId, config: new UpdateConfig(userId: $userId)). -
Команду запускает метод
run().
| Команда | Какой статус устанавливает |
|---|---|
Bitrix\Tasks\V2\Public\Command\Task\Status\StartTaskCommand |
InProgress |
Bitrix\Tasks\V2\Public\Command\Task\Status\TakeTaskCommand |
InProgress и назначает ответственным сотрудника, ID которого передан в аргументе userId объекта UpdateConfig |
Bitrix\Tasks\V2\Public\Command\Task\Status\PauseTaskCommand |
Pending |
Bitrix\Tasks\V2\Public\Command\Task\Status\CompleteTaskCommand |
Completed. Если у задачи включен контроль, ответственный и постановщик разные и завершает не постановщик, — SupposedlyCompleted. Задачу в статусе SupposedlyCompleted администратор или руководитель постановщика завершает сразу в Completed |
Bitrix\Tasks\V2\Public\Command\Task\Status\ApproveTaskCommand |
Completed |
Bitrix\Tasks\V2\Public\Command\Task\Status\DisapproveTaskCommand |
Pending |
Bitrix\Tasks\V2\Public\Command\Task\Status\DeferTaskCommand |
Deferred |
Bitrix\Tasks\V2\Public\Command\Task\Status\RenewTaskCommand |
Pending |
Права для каждой команды и пример запуска приведены в разделе Сменить статус или участников.
Сравнить статус в объекте задачи
Статус объекта задачи сравнивают с case enum, а не со строкой. Свойство status содержит объект enum, поэтому сравнение со строкой 'in_progress' всегда вернет false. Строковое значение возвращает свойство value, например $task->status?->value.
Пример. Код проверяет, выполняется ли задача, и получает строковое значение статуса.
use Bitrix\Tasks\V2\Internal\Entity\Task\Status as TaskStatus;
use Bitrix\Tasks\V2\Public\Provider\Params\TaskParams;
use Bitrix\Tasks\V2\Public\Provider\TaskProvider;
$task = (new TaskProvider())->get(TaskParams::mapFromIds($taskId, $userId));
$isInProgress = $task?->status === TaskStatus::InProgress;
// Строка для журнала или внешней системы, например in_progress
$statusCode = $task?->status?->value;
Вычисляемые состояния
Кроме статуса, у задачи есть вычисляемые состояния из класса Bitrix\Tasks\Internals\Task\MetaStatus. Они не хранятся в задаче, а вычисляются при выборке.
-
MetaStatus::EXPIREDравно-1— крайний срок прошел, а задача не завершена. -
MetaStatus::UNSEENравно-2— сотрудник еще не открывал новую задачу, которую ему поставил другой сотрудник. -
MetaStatus::EXPIRED_SOONравно-3— крайний срок скоро наступит, а задача не завершена.
Эти значения возвращает поле STATUS в выборке TaskQuery, а для остальных задач оно содержит настоящий статус. Чтобы всегда получать настоящий статус, выбирайте поле REAL_STATUS. Если сравнить STATUS с константой Status::IN_PROGRESS, просроченная задача в работе не пройдет проверку.
В обработчиках событий поле STATUS содержит настоящий статус числом. Формат полей в событиях описан в статье События модуля Задачи.
Приоритет
Приоритет задачи задают константы класса Bitrix\Tasks\Internals\Task\Priority. В объекте задачи приоритет — enum Bitrix\Tasks\V2\Internal\Entity\Priority со строковыми значениями. Значения констант совпадают с классическими константами CTasks::PRIORITY_*.
Константа Priority |
Число | Значение enum | Case enum | Что означает |
|---|---|---|---|---|
LOW |
0 | low |
Low |
Низкий. Записывается значением low, но провайдер TaskProvider возвращает его как average |
AVERAGE |
1 | average |
Average |
Средний |
HIGH |
2 | high |
High |
Высокий |
В метод Task::mapFromArray() приоритет передают строковым значением enum, например 'priority' => 'high'. Неизвестное значение метод превращает в null без ошибки, и приоритет задачи не изменится.
При записи значение low сохраняется как Priority::LOW со значением 0. При чтении через провайдер низкий и средний приоритет возвращаются одним значением average. Чтобы отличить низкий приоритет, читайте поле PRIORITY через TaskTable или TaskQuery.
Теги
Тег — метка, по которой задачи группируют и находят. В объекте задачи теги хранятся в свойстве tags — коллекции тегов. У каждого тега есть свойство name с названием.
Для выборки задач по тегу используйте поле фильтра TAG с названием тега, как описано в разделе Отфильтровать по тегу или пользовательскому полю.
Прочитать теги задачи
Теги возвращает провайдер TaskProvider, если в параметрах TaskParams::mapFromIds() включен ключ tags. Без этого ключа свойство tags равно null. Массив названий возвращает метод getNameList() коллекции.
Пример. Код читает задачу с тегами и получает массив названий тегов.
use Bitrix\Tasks\V2\Public\Provider\Params\TaskParams;
use Bitrix\Tasks\V2\Public\Provider\TaskProvider;
$task = (new TaskProvider())->get(
TaskParams::mapFromIds($taskId, $userId, ['tags' => true])
);
$tagNames = $task?->tags?->getNameList() ?? [];
Заменить теги задачи
Теги передают ключом tags в метод Task::mapFromArray(). Значение — массив, где каждый тег задан массивом с ключом name. Объект задачи передают в команду Bitrix\Tasks\V2\Public\Command\Task\UpdateTaskCommand.
Переданный список заменяет теги задачи. Тег, которого нет в списке, команда удалит. Пустой массив 'tags' => [] удалит все теги, кроме тегов из названия и описания.
Слова с символом # в названии и описании задачи модуль тоже сохраняет как теги. Например, текст Проверить #отчет добавит тег отчет. При каждом изменении задачи модуль ищет такие слова в текущих названии и описании и добавляет их к списку тегов. Поэтому тег из текста задачи нельзя удалить через ключ tags, пока слово с # остается в тексте.
Если изменить название или описание без ключа tags, модуль сохранит текущие теги и добавит к ним слова с # из нового текста.
Пример. Код заменяет теги задачи списком из двух тегов.
use Bitrix\Tasks\V2\Internal\Entity\Task;
use Bitrix\Tasks\V2\Internal\Service\Task\Action\Update\Config\UpdateConfig;
use Bitrix\Tasks\V2\Public\Command\Task\UpdateTaskCommand;
$result = (new UpdateTaskCommand(
task: Task::mapFromArray([
'id' => $taskId,
'tags' => [
['name' => 'отчет'],
['name' => 'квартал'],
],
]),
config: new UpdateConfig(userId: $userId),
))->run();
if (!$result->isSuccess())
{
throw new \RuntimeException(implode(', ', $result->getErrorMessages()));
}
Пример не проверяет права сотрудника. Перед запуском по запросу сотрудника проверьте право на изменение, как описано в разделе Изменить задачу.
Добавить тег к текущим
Ключ tags заменяет весь список. Чтобы добавить один тег, прочитайте текущие теги через провайдер, добавьте новый и передайте полный список. Иначе команда удалит остальные теги задачи.
Пример. Код добавляет к задаче тег срочно и сохраняет прежние теги.
use Bitrix\Tasks\V2\Internal\Entity\Task;
use Bitrix\Tasks\V2\Internal\Service\Task\Action\Update\Config\UpdateConfig;
use Bitrix\Tasks\V2\Public\Command\Task\UpdateTaskCommand;
use Bitrix\Tasks\V2\Public\Provider\Params\TaskParams;
use Bitrix\Tasks\V2\Public\Provider\TaskProvider;
$task = (new TaskProvider())->get(
TaskParams::mapFromIds($taskId, $userId, ['tags' => true])
);
if ($task === null)
{
throw new \RuntimeException('Задача не найдена или нет прав на чтение');
}
$tagNames = $task->tags?->getNameList() ?? [];
if (!in_array('срочно', $tagNames, true))
{
$tagNames[] = 'срочно';
$result = (new UpdateTaskCommand(
task: Task::mapFromArray([
'id' => $taskId,
'tags' => array_map(static fn (string $name): array => ['name' => $name], $tagNames),
]),
config: new UpdateConfig(userId: $userId),
))->run();
if (!$result->isSuccess())
{
throw new \RuntimeException(implode(', ', $result->getErrorMessages()));
}
}
Пользовательские поля
Задачи поддерживают пользовательские поля. Идентификатор объекта для пользовательских полей задач — TASKS_TASK, он же константа Bitrix\Tasks\V2\Internal\Entity\UF\UserField::TASK. Код поля начинается с префикса UF_.
Модуль использует несколько системных пользовательских полей. Они не попадают в свойство userFields объекта задачи. Для них в объекте есть отдельные свойства.
-
UF_TASK_WEBDAV_FILES— файлы задачи с Диска, свойствоfileIds. Провайдер заполняет свойство, только если в параметрах чтения включен ключuserFields. Файлы прикрепляют и открепляют командамиBitrix\Tasks\V2\Public\Command\Task\Attachment\AttachFilesCommandиBitrix\Tasks\V2\Public\Command\Task\Attachment\DetachFilesCommand, как описано в статье Чат, результаты, файлы и учет времени. -
UF_CRM_TASK— привязки к элементам CRM, свойствоcrmItemIds. При чтении через провайдер включите ключcrm, он возвращает только элементы, доступные сотруднику. -
UF_MAIL_MESSAGE— письмо, из которого создана задача, свойствоemail.
Создать пользовательское поле
Поле создают через API пользовательских полей, как поля других объектов. Метод CUserTypeEntity::Add() принимает массив параметров поля, где в ключе ENTITY_ID передают TASKS_TASK. Метод возвращает ID поля или false. Текст ошибки возвращает $GLOBALS['APPLICATION']->GetException(). Полный набор параметров и типов описан в статье Пользовательские поля.
Метод не проверяет права пользователя. Запускайте создание поля в доверенном коде, например при установке модуля. Перед созданием проверьте, нет ли поля с таким кодом, иначе повторный запуск вернет ошибку. Существующее поле ищут методом Bitrix\Main\UserFieldTable::getList() с фильтром по ENTITY_ID со значением TASKS_TASK и по FIELD_NAME с кодом поля.
Пример. Код создает у задач строковое поле UF_PROJECT_CODE для кода проекта во внешней системе.
use Bitrix\Main\UserFieldTable;
$fieldName = 'UF_PROJECT_CODE';
$exists = UserFieldTable::getList([
'select' => ['ID'],
'filter' => [
'=ENTITY_ID' => 'TASKS_TASK',
'=FIELD_NAME' => $fieldName,
],
])->fetch();
if (!$exists)
{
$fieldId = (new \CUserTypeEntity())->Add([
'ENTITY_ID' => 'TASKS_TASK',
'FIELD_NAME' => $fieldName,
'USER_TYPE_ID' => 'string',
'MULTIPLE' => 'N',
'MANDATORY' => 'N',
'EDIT_FORM_LABEL' => ['ru' => 'Код проекта'],
'LIST_COLUMN_LABEL' => ['ru' => 'Код проекта'],
]);
if (!$fieldId)
{
$exception = $GLOBALS['APPLICATION']->GetException();
throw new \RuntimeException($exception ? $exception->GetString() : 'Не удалось создать поле');
}
}
Обязательное поле модуль проверяет не всегда, и это легко пропустить.
-
При создании задачи модуль проверяет обязательные поля, только если в задаче передано хотя бы одно пользовательское поле. Тогда пустое обязательное поле остановит создание. Задача без пользовательских полей в данных, в том числе без файлов и привязок к CRM, создастся и с пустым обязательным полем.
-
При изменении задачи модуль проверяет обязательность только у переданных полей.
Поэтому не рассчитывайте, что флаг обязательности гарантирует значение у всех задач. Проверяйте значение в своем коде, если сценарий без него не работает.
Записать значения полей
Значения пользовательских полей передают ключом userFields в метод Task::mapFromArray(). Каждое поле задают массивом с ключами key — код поля и value — значение. Для множественного поля value — массив значений. Объект задачи передают в команду AddTaskCommand при создании или в команду UpdateTaskCommand при изменении.
Команда передает value в менеджер пользовательских полей CUserTypeManager::Update() без преобразований, поэтому формат значения такой же, как в классическом API. Форматы для частых типов полей приведены в таблице. Остальные типы описаны в статье Пользовательские поля.
Тип поля USER_TYPE_ID |
Формат value |
|---|---|
string |
Строка |
boolean |
Любое значение. Модуль сохраняет 1, если значение истинно, иначе 0 |
date |
Объект Bitrix\Main\Type\Date или строка в формате даты сайта |
datetime |
Объект Bitrix\Main\Type\DateTime или строка во времени пользователя в формате сайта, например 17.11.2026 14:30:00 для формата DD.MM.YYYY HH:MI:SS. Строку без времени модуль сохранит с временем 00:00 |
enumeration |
ID элемента списка, а не его текст. Для немножественного поля из массива сохраняется первый элемент |
file |
ID файла из таблицы b_file или массив загружаемого файла в формате CFile::MakeFileArray() |
Команда изменения записывает только переданные поля. Значения остальных пользовательских полей остаются прежними.
Перед сохранением команда проверяет значения через менеджер пользовательских полей. Если значение не прошло проверку, задача не изменится, а результат команды будет содержать ошибку. Проверяйте isSuccess() после каждого запуска.
Пример. Код записывает значение поля UF_PROJECT_CODE в существующую задачу.
use Bitrix\Tasks\V2\Internal\Entity\Task;
use Bitrix\Tasks\V2\Internal\Service\Task\Action\Update\Config\UpdateConfig;
use Bitrix\Tasks\V2\Public\Command\Task\UpdateTaskCommand;
$result = (new UpdateTaskCommand(
task: Task::mapFromArray([
'id' => $taskId,
'userFields' => [
['key' => 'UF_PROJECT_CODE', 'value' => 'Q4'],
],
]),
config: new UpdateConfig(userId: $userId),
))->run();
if (!$result->isSuccess())
{
throw new \RuntimeException(implode(', ', $result->getErrorMessages()));
}
Пример не проверяет права сотрудника. Перед запуском по запросу сотрудника проверьте право на изменение, как описано в разделе Изменить задачу.
Системные поля из списка выше через userFields не передавайте. Для них используйте отдельные ключи объекта задачи и команды.
Прочитать значения полей
Значения пользовательских полей одной задачи возвращает провайдер TaskProvider, если в параметрах TaskParams::mapFromIds() включен ключ userFields. Свойство userFields — коллекция объектов со свойствами key и value. Объект поля по коду возвращает метод findOne() коллекции. Метод принимает массив условий, например ['key' => 'UF_PROJECT_CODE'], и возвращает null, если поля нет. Без ключа userFields провайдер не загружает значения полей, и свойство userFields содержит пустую коллекцию.
Пример. Код читает значение поля UF_PROJECT_CODE одной задачи.
use Bitrix\Tasks\V2\Public\Provider\Params\TaskParams;
use Bitrix\Tasks\V2\Public\Provider\TaskProvider;
$task = (new TaskProvider())->get(
TaskParams::mapFromIds($taskId, $userId, ['userFields' => true])
);
$projectCode = $task?->userFields?->findOne(['key' => 'UF_PROJECT_CODE'])?->value;
Метод TaskProvider::getList() своих пользовательских полей не поддерживает, поэтому для списка задач используйте класс TaskList.
-
Перечислите коды полей в
setSelect()запросаTaskQuery. -
Чтобы отфильтровать задачи по полю, передайте в метод
setWhere()запроса ключ с оператором перед кодом поля, например'=UF_PROJECT_CODE'. -
Выполните запрос методом
Bitrix\Tasks\Provider\TaskList::getList(). Он возвращает массив строк, ключи каждой строки — коды полей изsetSelect(). Значения пользовательских полей вернутся под их кодами.
Пример. Код выбирает задачи сотрудника со значением поля UF_PROJECT_CODE.
use Bitrix\Tasks\Provider\Query\TaskQuery;
use Bitrix\Tasks\Provider\TaskList;
$query =
(new TaskQuery($userId))
->setSelect(['ID', 'TITLE', 'UF_PROJECT_CODE'])
->setWhere(['=UF_PROJECT_CODE' => 'Q4'])
;
foreach ((new TaskList())->getList($query) as $row)
{
$projectCode = $row['UF_PROJECT_CODE'];
}
Если поля с таким кодом у задач нет, запрос пропустит его без ошибки и значение в строках не вернет. Проверьте код поля, если значение не пришло.
Проверить результат
Перед публикацией кода выполните в тестовом Битрикс24 несколько проверок.
-
Прочитайте задачу через провайдер без ключей
members,tagsиuserFieldsи убедитесь, что код не падает на свойствах, равныхnull, и на пустой коллекции пользовательских полей. -
Сравните участников из
MemberTableс карточкой задачи. Для выборки по списку задач передавайте только ID задач, которые сотрудник может читать. -
Замените теги задачи, в названии которой есть слово с
#, и проверьте, что тег из названия остался. -
Добавьте тег к задаче с тремя тегами и убедитесь, что прежние теги сохранились.
-
Запишите значение пользовательского поля и прочитайте его через провайдер с ключом
userFields. Убедитесь, что значения других пользовательских полей не изменились. -
Передайте значение неверного типа в пользовательское поле и проверьте, что код обрабатывает ошибку из результата команды.
-
Если код сравнивает статус из выборки
TaskQuery, проверьте его на просроченной задаче и выбирайте полеREAL_STATUS.