Быстрый старт работы со Смарт-процессами в коробке Битрикс24 для разработчика. Часть 1. Базовые операции

Представляю вашему вниманию цикл статей по работе с пока еще мало знакомым многим битрикс-разработчикам инструментом оперирования данными с CRM Битрикс24 через абстрактные фабрики. В первой статье рассмотрим базовые операции с элементами сущностей CRM — создание, изменение, удаление.


Вышедший год назад, но уже «перевернувший» структурное восприятие многих Битрикс24 интеграторов на «до и после», модуль «Смарт-процессы», все активнее и активнее используется при автоматизации различных задач. Гибкость модуля, по сути позволяющая создавать новые сущности CRM в неограниченном количестве, по достоинству оценена пользователями. Но вот для разработчиков, особенно привыкших для оперирования элементами использовать уже привычные методы BitrixAPI, например такие классы как CCrmDeal, CCrmLead и пр. оказалось в части смарт процессов все не так просто и однозначно. Обращение к элементам и изменение их происходило через привычные всем Битрикс разработчикам методы, например GetList, Add, Update.

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

Начнем со структурного понимания работы с новыми сущностями. Как я уже писал выше, теперь Смарт-Процессов может быть неограниченное количество, с любыми наименованиями. Поэтому для реализации методов оперирования данными процесса в ядре был реализован специальный метод по шаблону проектирования «Абстрактная фабрика».

Если упростить механизм для понимания, теперь для любой сущности CRM Битрикс24 (не только Смарт-процессов) можно инициализировать такую фабрику, и дальше через ее методы оперировать параметрами и элементами сущности.

Да, для стандартных сущностей оставили старые классы в качестве обратной совместимости. А также в старые классы «прокинули» поля связки со Смарт-процессами. Но с самим Смарт-процесса без нового «фабричного» API сделать ничего не получится.

1. Инициализация фабрики

Пример инициализации фабрики выглядит следующим образом:use Bitrix\Main\Loader;

use Bitrix\Crm\Service;

Loader::includeModule('crm');

$typeid = '124';//Идентификатор смарт-процесса

$factory = Service\Container::getInstance()->getFactory($typeid);  

Также в качестве typeid можно передать идентификатор сущности CRM из класса \CCrmOwnerType, например \CCrmOwnerType::Deal. То есть по факту фабрику можно инициализировать для любой сущности CRM. Подробнее о том как именованы идентификаторы других сущностей и примеры их передачи в фабрику указаны здесь, в фабрику для создания передаем в виде entityTypeID, указанного по ссылке.

После инициализации фабрики становятся доступными все методы, доступные абстрактной фабрике CRM. Они подробно расписаны в официальной документации тут.

Далее разберем наиболее часто встречающиеся в задачах для разработчиков.

2.Получение стадий сущности из фабрики

Так как Смарт-Процесс помимо возможности содержать указанные пользователем поля с данными также может содержать и нетиповую статусную модель, разработчику нужно знать, какие статусы использует процесс перед операциями с данным процессом.

use Bitrix\Crm\Service\Container;

$factory = Container::getInstance()->getFactory($entityTypeID)

if ($factory && $factory->isStagesSupported())

{

$stages = $factory->getStages()->getAll();

foreach( $stages as $stage){

$arStages = $stage->getStatusId();

}

}

будет возвращен массив типа

DT124_6:NEW,DT124_6:PREPARATION,DT124_6:CLIENT,DT124_6:SUCCESS,DT124_6:FAIL,

где 124 -  идентификатор типа смарт-процесса, а 6 — ид смарт-процесса.

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

Для создания нового элемента через фабрику теперь недостаточно просто запустить метод создания. Операция создания теперь тоже формирует свой подобъект, в котором после всех необходимых действий нужно выполнить метод запуска операции. Только после этого нужный объект будет создан. Рассмотрим пример создания элемента в простейшем виде:

use Bitrix\Crm\Service\Container;

$faсtory = Container::getInstance()->getFactory($entityTypeId);

$data = [

               'TITLE' => ‘Название элемента’,

               ‘ASSIGNED_BY_ID’=>$userId,

               'UF_CRM_1_DATE' => new Bitrix\Main\Type\DateTime(),

               'PARENT_ID_2' => $dealId,

               "STAGE_ID"  =>  "DT124_6:NEW",

 ];

$item = $factory ->createItem($data); 

$item->save();

Также процесс создания можно дополнительно кастомизировать, к примеру добавив через объект Context пользователя, под которым данное действие будет выполнено. К примеру, код будет выполняться в агенте и нам нужно установить пользователя руками. В этом случае наш пример приобретает вид:

use Bitrix\Crm\Service\Container;

$factory = Container::getInstance()->getFactory($entityTypeId);

$context = new \Bitrix\Crm\Service\Context();

$context -> setUserId($userId);

data = [

               'TITLE' => ‘Название элемента’,

               ‘ASSIGNED_BY_ID’=>$userId,

               'UF_CRM_1_DATE' => new Bitrix\Main\Type\DateTime(),

               'PARENT_ID_2' => $dealId,

               "STAGE_ID"  =>  "DT124_6:NEW",

 ];

$item = $factory ->createItem($data); 

$saveOperation = $fabrika ->getAddOperation($item, $context);

$operationResult = $saveOperation->launch();

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

4. Изменение элемента Смарт-процесса

Для изменения элементов в фабрике есть 2 подхода — изменение одного поля конкретного элемента и изменение нескольких полей через массив. Также есть возможность по аналогии с операцией создания через Context кастомизировать операцию изменения.

Рассмотрим простую операцию изменения одного поля элемента:

use Bitrix\Crm\Service\Container;

$factory = Container::getInstance()->getFactory($entityTypeId);

$item = $factory->getItem($entityId);

$item->set('UF_CRM_1_FIELD', $value);

$item->save();

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

use Bitrix\Crm\Service\Container;

$factory = Container::getInstance()->getFactory($entityTypeId);

$class = $factory -> getDataClass();

 $saveResult = $class::update($id, $arUpdate);

В массив arUpdate кладем уже привычные с традиционных методов апи новые значения полей, в ключи массива — идентификаторы полей в которые эти значения нужно вписать.

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

use Bitrix\Crm\Service\Container;

$factory = Container::getInstance()->getFactory($entityTypeId);

$context = new \Bitrix\Crm\Service\Context();

$context -> setUserId($userId);

$item = $factory->getItem($entityId);

$saveOperation = $factory ->getUpdateOperation($item, $context); 

$operationResult = $saveOperation->launch();

5. Удаление элемента Смарт-процесса

Для удаление элемента смарт-процесса нам понадобится использовать уже знакомый нам по этой статье Context. Удаление возможно на момент написания статьи только с его использованием. Рассмотрим пример удаления элемента:

use Bitrix\Crm\Service\Container;

$faсtory = Container::getInstance()->getFactory($entityTypeId);

$context = new \Bitrix\Crm\Service\Context();

$context -> setUserId($userId);

$item = $factory->getItem($entityId);

$saveOperation = $factory ->getUpdateOperation($item, $context); 

$operationResult = $saveOperation->launch();

Планы на следующие части

В рамках цикла статей по работе со Смарт-процессами через API Битрикс24 коробочной версии планируются еще статьи:

2. Работа со списком элемента Смарт-процесса и связями между ними
3. Как реализовать обработчики события для Смарт-процессов

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

Вместо заключения

В комментариях к данной записи был бы рад услышать мнение других разработчиков Битрикс24 по поводу нового API CRM. Насколько оно удобно для понимания? Всем спасибо за внимание.

Также хочу порекомендовать к посещению бесплатный вебинар от моих коллег из OTUS на котором мы рассмотрим как создавать свои таблицы в БД Битрикс24. Создадим комплексный компонент списка, включая такие элементы как фильтр, пагинация, кнопки действий.
Вы научитесь: создавать свои компоненты для Битрикс24, добавлять выгрузку данных списка в Excel, добавлять свои данные и действия в шаблон.

Подробнее о бесплатном вебинаре