API для смарт процессов в CRM Битрикс24

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

Задача: обеспечить точку входа.

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

Каждая фабрика является наследником абстрактного класса \Bitrix\Crm\Service\Factory который содержит универсальные методы, работающие на любом наследнике.

Паттерн: реализация паттерна Фабричный Метод (Factory Method).

Задача: фабрика создает объекты Operation (операции) для работы с элементами CRM.

Как работает: DinamicFactory наследуется от базового \Bitrix\Crm\Service\Factory.

Нас интересует три главных метода фабрики, которые возвращают объекты операций:

1. getAddOperation() → Operation\Add (создание)
2. getUpdateOperation() → Operation\Update (обновление)
3. getDeleteOperation() → Operation\Delete (удаление)

Термин Operation (Операция) наиболее емко описывает необходимый набор действий для достижений конкретной цели.

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

Задача: инкапсулирует всю логику выполнения действия над элементом (добавление, изменение, удаление).

Как работает: каждая операция содержит массив Action, отдельные шаги с бизнес-логикой, операция последовательно выполняет эти шаги.

Аналогом обработчиков событий в старом подходе Битрикс, являются Action (Действие), специальный класс реализующий Bitrix\Crm\Service\Operation\Action, который добавляется к операции.

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

Как работает: вас должен интересовать один главный метод process(). Он принимает объект Bitrix\Crm\Item (элемент, над которым проводится операция) и возвращает Bitrix\Main\Result (успех или ошибку).

Создаем класс-фабрику, которая будет возвращать операцию с вашим обработчиком:

/local/modules/hmarketing.rest/lib/Crm/OrderFactory.php<?php

namespace Hmarketing\Rest\Crm;

use Bitrix\Crm\Service\Factory\Dynamic;
use Bitrix\Crm\Service\Context;
use Bitrix\Crm\Service\Operation;
use Bitrix\Crm\Model\Dynamic\TypeTable;
use Bitrix\Crm\Item;

class OrderFactory extends Dynamic
{
    // идентификатор типа смарт-процесса
    protected int $entityTypeId = 1036;

    public function __construct()
    {
        $type = TypeTable::getByEntityTypeId($this->entityTypeId)->fetchObject();

        if (!is_null($type))
        {
            parent::__construct($type);
        }
        else
        {
            // важно, обработайте случай, если тип не найден
            throw new \Exception("Smart Process с идентификатором ID={$this->entityTypeId} не найден.");
        }
    }

    // переопределяем метод получения операции обновления
    public function getUpdateOperation(Item $item, Context $context = null): Operation\Update
    {
        // 1. получаем стандартную операцию обновления
        $operation = parent::getUpdateOperation($item, $context);

        // 2. добавляем свой Action на этап "ПЕРЕД сохранением"
        $operation->addAction(
            Operation::ACTION_BEFORE_SAVE,
            new \Hmarketing\Rest\Action\OrderAction()
        );

        return $operation;
    }
}

Регистрируем нашу фабрику вместо стандартной. Это нужно сделать в точке входа, например в init.php. Ключ сервиса формируется по шаблону crm.service.factory.dynamic.{ID_СУЩНОСТИ}:

/local/php_interface/init.php<?php

// подключаем модуль crm
\Bitrix\Main\Loader::includeModule('crm');

// подключаем кастомный модуль где лежат все файлы hmarketing.rest
\Bitrix\Main\Loader::includeModule('hmarketing.rest');


// подменяем фабрику для конкретного смарт-процесса (ID=1036)
\Bitrix\Main\DI\ServiceLocator::getInstance()->addInstance(
    // ключ для динамического типа
    'crm.service.factory.dynamic.1036',
    // подкидываем экземпляр класса созданного на первом шаге
    new Hmarketing\Rest\Crm\OrderFactory()
);

Создаем класс, в котором будет реализована ваша логика обработки:

/local/modules/hmarketing.rest/lib/Action/OrderAction.php<?php

namespace Hmarketing\Rest\Action;

use Bitrix\Main\Result;
use Bitrix\Main\Error;
use Bitrix\Crm\Item;
use Bitrix\Crm\Service\Operation\Action;

class OrderAction extends Action
{
    public function process(Item $item): Result
    {
        $result = new Result();

        // для примера, проверим созданное свойство сумма
        if ($item->get('UF_CRM_3_1766692211591') < 0)
        {
            $result->addError(new Error("Сумма заказа не может быть отрицательной!"));
        }

        // возвращаем результат операции
        return $result;
    }
}

С полученными смарт процессами можно работать на свое усмотрение.

// переменная содержащия массив для выборки
$itemIDs = [];
// смарт процесс с идентификатором 1036
$entityTypeId = 10361;
// получаем фабрику через класс-обертку
$factory = Bitrix\Crm\Service\Container::getInstance()->getFactory($entityTypeId);
// проверка на наличие смарт процесса
if (!$factory) {
    throw new \Exception("Smart Process с идентификатором ID={$entityTypeId} не найден.");
}
// выборка элементов с лимитом
$items = $factory->getItems([
    // лимит записей за один запрос, критично для производительности
    'limit' => 500
]);
// перебираем полученные данные
foreach ($items as $item) {
    $itemIDs[] = [
        'ID' => $item['ID'],
        'TITLE' => $item['TITLE'],
        'UF_SUMMA' => $item['UF_CRM_3_1766692211591']
    ];
}

Операторы сравнения позволяют задавать условия фильтрации:

• = равно (работает и с массивами)
• % подстрока
• > больше
• < меньше
• @ IN (EXPR) в качестве значения передается массив или объект
• !@ NOT IN (EXPR)в качестве значения передается массив или объект
• != не равно
• !% не подстрока
• >< между, в качестве значения передается массив array (MIN, MAX)
• >= больше или равно
• <= меньше или равно
• =% ищет строки, которые начинаются с указанного значения. Аналог оператора LIKE в SQL
• %= ищет строки, которые заканчиваются указанным значением. Аналог оператора LIKE в SQL

Префиксы %= и =% эквивалентны и используются для поиска подстрок:

• '%=NAME' => 'тест' аналог LIKE, не подстрока
• '%=NAME' => 'тест%' содержит «тест» в начале
• '%=NAME' => '%тест' содержит «тест» в конце
• '%=NAME' => '%тест%' содержит подстроку «тест»

Булево выражение для ExpressionField, например для EXISTS() или NOT EXISTS()

• == булевое выражение для ExpressionField (например, для EXISTS () или NOT EXISTS ())
• !>< не между, в качестве значения передается массив array (MIN, MAX)
• !=% NOT LIKE
• !%= NOT LIKE
• '==ID' => null условие, что поле ID равно NULL (в sql-запросе будет преобразовано в ID IS NULL)
• '!==NAME' => null условие, что поле NAME не равно NULL (в sql-запросе будет преобразовано в NAME IS NOT NULL)

// переменная содержащия массив для выборки
$itemIDs = [];
// смарт процесс с идентификатором 1036
$entityTypeId = 1036;
// получаем фабрику через класс-обертку
$factory = Bitrix\Crm\Service\Container::getInstance()->getFactory($entityTypeId);
// проверка на наличие смарт процесса
if (!$factory) {
    throw new \Exception("Smart Process с идентификатором ID={$entityTypeId} не найден.");
}
// выборка элементов с лимитом по пользовательскому полю
$items = $factory->getItems([
    // фильтр по указанному полю
    'filter' => ['=UF_CRM_3_1766692211591' => 10.0],
    // выбираем только нужные поля
    'select' => ['ID', 'TITLE', 'UF_CRM_3_1766692211591'],
    // лимит записей за один запрос, критично для производительности
    'limit' => 500
]);
// перебираем полученные данные
foreach ($items as $item) {
    $itemIDs[] = [
        'ID' => $item['ID'],
        'TITLE' => $item['TITLE'],
        'UF_SUMMA' => $item['UF_CRM_3_1766692211591']
    ];
}

Валидация заложенная разработчиками Битрикс24:

// смарт процесс с идентификатором 1036
$entityTypeId = 1036;
// получаем фабрику через класс-обертку
$factory = Bitrix\Crm\Service\Container::getInstance()->getFactory($entityTypeId);
// проверка на наличие смарт процесса
if (!$factory) {
    throw new \Exception("Smart Process с идентификатором ID={$entityTypeId} не найден.");
}
// описываем массив полей смарт процесса, включая кастомные
$item = $factory->createItem([
    'TITLE' => 'Новый смарт процесс2',
    'UF_CRM_3_1766692211591' => 10.0
]);
// метод добавления смарт процесса
$operation = $factory->getAddOperation($item);
// отключаем все проверки
$operation->disableAllChecks();
// сохраняем новый смарт процесс
$addResult = $operation->launch();
// проверяем на ощибки
$errorMessages = $addResult->getErrorMessages();
// если ощибок нет, получаем ID новой записи СП
if ($addResult->isSuccess()) {
    $newId = $item->getId();
} else {
    throw new \Exception("Элемент Smart Processa не создан.");
}

Переменная $addResult будет содержать данные об удаленных смарт процессах:

// смарт процесс с идентификатором 1036
$entityTypeId = 1036;
// получаем фабрику через класс-обертку
$factory = Bitrix\Crm\Service\Container::getInstance()->getFactory($entityTypeId);
// проверка на наличие смарт процесса
if (!$factory) {
    throw new \Exception("Smart Process с идентификатором ID={$entityTypeId} не найден.");
}
// получаем смарт процессы по фильтру
$items = $factory->getItems([
    'filter' => [
        'TITLE' => 'Новый смарт процесс1',
    ]
]);
// перебираем полученные данные
foreach($items as $item) {
    // метод удаления смарт процесса
    $operation = $factory->getDeleteOperation($item);
    // отключаем проверки
    $operation
        ->disableCheckFields()
        ->disableBizProc()
        ->disableCheckAccess()
    ;
    // сохраняем удаленные смарт процессы
    $addResult = $operation->launch();
}