Быстрый старт работы со Смарт-процессами в коробке Битрикс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. Как реализовать обработчики события для Смарт-процессов

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

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

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