Работа с элементами Смарт Процессов на низком уровне в модуле CRM Битрикс24

Рассуждая об элементах смарт-процессов в CRM можно запросто запутаться в понятиях и их взаимосвязях. Поначалу неопытные разработчики принимают запись в базу данных значений за совершение действий, однако это вовсе не так. Если удалось записать в таблицу значения, это совершенно не значит что те же действия будут выполнены в связанных компонентах. Запись в базу данных там тоже появится, но это будет лишь вершиной айсберга.

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

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

Порядок работы на низком уровне

Взаимодействие с элементами смарт-процессов осуществляется через фабрики Bitrix\Crm\Service\Factory, получать которые необходимо из контейнера \Bitrix\Crm\Service\Container. Это означает что перед выполнением любой операции необходимо:

Получить контейнер \Bitrix\Crm\Service\Container в некоторых случаях можно обойтись без контейнеров, но использование их строго рекомендовано, чтобы обеспечивать возможность наследования и переопределения действий
Получить фабрику Bitrix\Crm\Service\Factory
Выполнить нужное действие

Перед дальнейшей работой необходимо получить фабрику элементов смарт-процессов:

\Bitrix\Main\Loader::IncludeModule('crm');

// получаем контейнер
$container = \Bitrix\Crm\Service\Container::getInstance();

// получаем объект фабрики с ID 3
$factory = $container->getFactory( 3 );

Получение списка полей элемента смарт процесса

Для получения списка полей смарт-процесса используется метод getFieldsCollection, он возвращает экземпляр Bitrix\Crm\Field\Collection с описанием всех полей элемента смарт-процесса:

\Bitrix\Main\Loader::IncludeModule('crm');

// получаем контейнер
$container = \Bitrix\Crm\Service\Container::getInstance();

// получаем объект фабрики с ID 3
$factory = $container->getFactory(3);

// получаем коллекцию полей
$fieldsCollection = $factory->getFieldsCollection();

// перебираем коллекцию
foreach ($fieldsCollection as $field) {
    // получаем заголовок
    var_dump($field->getTitle());
    // получаем название
    var_dump($field->getName());
}

Поиск элементов смарт процесса

Для поиска элементов в каждой фабрике существуют два метода:

getItems доступ к элементам без проверки прав пользователя
getItemsFilteredByPermissions доступ к элементам с проверкой прав пользователя

Доступ к элементам без проверки прав пользователя методом getItems ()

Метод getItems, по параметрам аналогичен ORM методу getList, однако вместо массива массивов, возвращает массив объектов Bitrix\Crm\Item\Dynamic.

Найдем все элементы исходного смарт-процесса, которые содержат цифру 2:

\Bitrix\Main\Loader::IncludeModule('crm');

// получаем контейнер
$container = \Bitrix\Crm\Service\Container::getInstance();

// получаем объект фабрики смарт процесса с идентификатором 1036
$factory = $container->getFactory(1036);

// выборка элементов по фильтру
$elementsWithA = $factory->getItems([
    'filter' => [
        '%TITLE' => '2'
    ]
]);

// перебираем полученные данные
foreach ($elementsWithA as $element) {
    print_r($element->getTitle());
}

Доступ к элементам с проверкой прав пользователя методом getItemsFilteredByPermissions ()

Для поиска элементов смарт-процесса с учетом прав необходимо использовать метод getItemsFilteredByPermissions, который принимает следующие параметры:

$parameters массив, аналогичный getList
$userId идентификатор текущего пользователя, если не передан, будет учитываться текущий
$operation уровень прав, который проверяется по-умолчанию чтение

Найдем все элементы исходного смарт-процесса, которые содержат цифру 2 доступных пользователю с ID равным 1:

\Bitrix\Main\Loader::IncludeModule('crm');

// получаем контейнер
$container = \Bitrix\Crm\Service\Container::getInstance();

// получаем объект фабрики смарт процесса с идентификатором 1036
$factory = $container->getFactory(1036);

// выборка элементов по фильтру, доступных пользователю с ID 1
$elementsWithA = $factory->getItemsFilteredByPermissions(
    [
        'filter' => [
            '%TITLE' => '2'
        ]
    ],
    1
);

// перебираем полученные данные
foreach ($elementsWithA as $element) {
    print_r($element->getTitle());
}

Создание элемента смарт процесса

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

Код расположенный ниже, представлен в ознакомительных целях и не удовлетворяет критериям:

Прозрачности (вы не сможете отследить все места и доп.действия с элементом)
Расширяемости (вы не сможете быстро переопределить или дополнить доп.действиями)
Консистентности (код ниже не гарантирует корректную работу системы в некоторых частях (поиск, права, таймлайн и т.п.))

Вариант с низкоуровневым созданием элемента смарт-процесса:

\Bitrix\Main\Loader::IncludeModule('crm');

// получаем контейнер
$container = \Bitrix\Crm\Service\Container::getInstance();

// получаем объект фабрики смарт процесса с идентификатором 1036
$factory = $container->getFactory(1036);

// формируем массив с данными которые запишутся в смарт процесс
$initialFields = [
    'TITLE' => 'Новый смарт процесс22',
    'ASSIGNED_BY_ID' => 1
];

// создаем новый смарт процесс
$item = $factory->createItem($initialFields);

// сохраняем новый смарт процесс
$saveResult = $item->save();

if ($saveResult->isSuccess()) {
    /**
     * Success result
     * $item->getId();
     */
} else {
    /**
     * Some errors
     * Get error with:
     * $saveResult->getErrors();
     *
     * Get error messages:
     * $saveResult->getErrorMessages();
     */
}

Это самое низкоуровневое сохранение элемента, в котором не происходит следующих действий:

Установка значений по-умолчанию
Проверки прав
Установки связей
Отправки push уведомлений
Запуска бизнес-процессов и автоматизаций
Перерасчета прав
Обновление поискового индекса
Учета статистики
Формирования timeline

Рекомендуемый вариант с использованием операций.

Обновление элемента смарт процесса

Код расположенный ниже, представлен в ознакомительных целях и не удовлетворяет критериям:

Прозрачности (вы не сможете отследить все места и доп.действия с элементом)
Расширяемости (вы не сможете быстро переопределить или дополнить доп.действиями)
Консистентности (код ниже не гарантирует корректную работу системы в некоторых частях (поиск, права, таймлайн и т.п.))

Вариант с низкоуровневым обновлением элемента смарт-процесса:

\Bitrix\Main\Loader::IncludeModule('crm');

// получаем контейнер
$container = \Bitrix\Crm\Service\Container::getInstance();

// получаем объект фабрики смарт процесса с идентификатором 1036
$factory = $container->getFactory(1036);

// получаем элемент смарт процесса с ID 25
$item = $factory->getItem(25);

// меняим заголовок одним из методв
//$item->setTitle('Новый заголовок');
$item->set('TITLE', 'Новый заголовок');

// сохраняем элемент смарт процесса
$updateResult = $item->save();

if ($updateResult->isSuccess()) {
    /**
     * Success result
     * $item->getId();
     */
} else {
    /**
     * Some errors
     * Get error with:
     * $updateResult->getErrors();
     *
     * Get error messages:
     * $updateResult->getErrorMessages();
     */
}

Это самое низкоуровневое обновление элемента, в котором не происходит следующих действий:

Не затрагиваются связанные сущности

Удаление элемента смарт процесса

Код расположенный ниже, представлен в ознакомительных целях и не удовлетворяет критериям:

Прозрачности (вы не сможете отследить все места и доп.действия с элементом)
Расширяемости (вы не сможете быстро переопределить или дополнить доп.действиями)
Консистентности (код ниже не гарантирует корректную работу системы в некоторых частях (поиск, права, таймлайн и т.п.))

Вариант с низкоуровневым удалением элемента смарт-процесса:

\Bitrix\Main\Loader::IncludeModule('crm');

// получаем контейнер
$container = \Bitrix\Crm\Service\Container::getInstance();

// получаем объект фабрики смарт процесса с идентификатором 1036
$factory = $container->getFactory(1036);

// получаем элемент смарт процесса с ID 24
$item = $factory->getItem(24);

// удаляем смарт процесс
$deleteResult = $item->delete();

if ($deleteResult->isSuccess()) {
    /**
     * Success result
     * $item->getId();
     */
} else {
    /**
     * Some errors
     * Get error with:
     * $saveResult->getErrors();
     *
     * Get error messages:
     * $saveResult->getErrorMessages();
     */
}

Это самое низкоуровневое удаление элемента, в котором не происходит следующих действий:

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

Рекомендуемый вариант с использованием операций.