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

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

Сейчас же рассмотрим прочие операции с элементом и списком элементов Смарт-процессов, а именно:

1. Получение списка элементов смарт-процесса

2. Получение данных конкретного элемента смарт-процесса

3. Добавление связанного контакта к элементу Смарт-процесса

4. Получение связей с другими сущностями CRM или смарт-процессами через relationManager

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

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

\Bitrix\Main\LoaderLoader::includeModule('crm');
$typeid = '147';//Идентификатор смарт-процесса
$factory = \Bitrix\Crm\ServiceService\Container::getInstance()->getFactory($typeid);

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

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

В первом примере разберем способ получения массива данных конкретного элемента смарт-процесса. Как уже указывал выше, считаем что фабрику мы инициализировали и можем выполнять с ней действия. Тогда в простейшем виде вытащить массив данных элемента Смарт-процесса с ID=1 можно следующим способом:

$sourceItemId = 1;//Идентификатор
$item = $factory->getItem($sourceItemId);
print_r($item->getData());

Данный способ предполагает получение объекта конкретного элемента, который как и фабрика содержит свой набор методов, в частности метод getData(), возвращающий массив значение полей элемента. Описание большинства методов, доступных из объекта элемента, можно посмотреть в официальной документации по D7.

А как же быть "счастливым" обладателям облачной версии, где нельзя добавлять свой PHP код в логику, а получить данные элемента Смарт-процесса все таки хочется? Для облака есть специальный Rest метод crm.item.get, который нам в этом поможет.

Пример запроса на получение данных элемента Смарт-процесса из JavaScript:

let item = return BX.ajax.runAction('crm.api.item.get',
            {
                data:
                    {
                        id: entityId,//Идентификатор элемента
                        entityTypeId: entityTypeId//Идентификатор Смарт-процесса
                    }
            });

2. Получение списка элементов Смарт-процесса

Для выполнения данной операции в простейшем виде на нужен будет метод фабрики getItems. Возвращает он такие-же объекты элемента, как в предыдущем разделе, для удобства упакованные в один массив. Пример реализации на PHP для коробочной версии Битрикс24, опять же считаем что фабрику мы уже инициализировали:

 $items = $faсtory->getItems([
'filter' => ['@ID' => $ids],//тут задаем фильтр для выборки, можно по полям элемента
'select' => ['ID', 'UF_CRM_2_FIELD', 'TITLE'],//Какие поля получить, можно указать * если нужны все
'order' => ['UF_CRM_2_FIELD' => 'ASC'],//Указываем поле по которому будет сортироваться выборка и направление сортировки
'limit'=>1000,//Сколько элементов выбрать за запрос
'offset' =>0//С какого элемента по счету начать выборку
        ]);

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

В RestAPI с получением списка элементов поможет метод crm.item.list.

Пример использования данного метода во front-end:

let items = BX.ajax.runAction('crm.api.item.list',
            {
                data:
                    {
                        entityTypeId: entityTypeId//Идентификатор Смарт-процесса
                    }
            });

Такой запрос получит массив всех элементов указанного смарт-процесса.

3. Добавление связанного контакта к Смарт-процессу

Помимо получение данных об элементе, из объекта элемента также можно получить данные о привязанных контактах. Пример реализации:

$sourceItemId = 1;//Идентификатор
$item = $factory->getItem($sourceItemId);
//Получить текущие связи элемента с контактами
$contactsBind = $item->getContactBindings();
//Результат вернется в том же формате, в котором его отдает метод \Bitrix\Crm\Binding\EntityBinding::prepareEntityBindings()
// добавить связь с контактом с ид = 1
$item->bindContacts(\Bitrix\Crm\Binding\EntityBinding::prepareEntityBindings(\CCrmOwnerType::Contact, [1]));
// удалить связь с контактом с ид = 1
$item->unBindContacts(\Bitrix\Crm\Binding\EntityBinding::prepareEntityBindings(\CCrmOwnerType::Contact, [1]));

Таким образом через встроенные методы объекта элемента мы можем оперировать привязанными контактами смарт-процесса.

4. Работа с прочими связями элемента через relationManager

Так как Смарт-процессы могут связываться не только с контактами, разберем пример получения данных о привязках через relationManager. Это такой специальный объект-сервис, позволяющий совершать действия с API связей между различными сущностями. Подробнее о нем можно почитать в официальной документации по ссылке выше. Пример кода для получения связей определенного элемента Смарт-процесса:

$relationManager = \Bitrix\Crm\Service\Container::getInstance()->getRelationManager();
//Получаем объект идентификатора элемента с помощью идентификатора Смарт-процесса и идентификатора элемента
$itemIdentifier = new \Bitrix\Crm\ItemIdentifier($entityTypeId, $entityId);
//Получаем связанные элементы
$bindedElements =  $relationManager->getElements($itemIdentifier);
//Получаем дочерние элементы
$childElements = $relationManager->getChildElements($itemIdentifier);
//Получаем родительские элементы
$parentElements = $relationManager->getParentElements($itemIdentifier);

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

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

1. Базовые операции

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

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

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

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

Всем спасибо за внимание!