Описание

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

Примеры использования

Пример 1: Базовое получение элементов Смарт-процесса

Этот пример показывает, как безопасно получить все элементы определенного Смарт-процесса с обработкой ошибок.

  • Установлен лимит: не больше 500 элементов (лимит можно изменить в строке 30-33)
  use Bitrix\Crm\Service\Container;
use Bitrix\Main\Loader;

Loader::includeModule('crm');

// ВХОДНОЙ ПАРАМЕТР: Получение ID типа Смарт-процесса из переменной БП
$entityTypeId = "{{EntityTypeId}}";

// Валидация входных данных
if (empty($entityTypeId)) {
    $this->WriteToTrackingService("[ERROR] ID типа Смарт-процесса не передан");
    $rootActivity = $this->GetRootActivity();
    $rootActivity->SetVariable("Status", "INPUT_ERROR");
    $rootActivity->SetVariable("ErrorMessage", "Отсутствует обязательный параметр EntityTypeId");
    return;
}

$entityTypeId = (int)$entityTypeId;

try {
    $factory = Container::getInstance()->getFactory($entityTypeId);
    
    if (!$factory) {
        $this->WriteToTrackingService("[ERROR] Фабрика для типа Смарт-процесса " . $entityTypeId . " не найдена");
        $rootActivity = $this->GetRootActivity();
        $rootActivity->SetVariable("Status", "FACTORY_ERROR");
        return;
    }
    
    // ПОЛУЧЕНИЕ ДАННЫХ: Выборка элементов с лимитом
    $items = $factory->getItems([
        'limit' => 500 // Лимит записей за один запрос (критично для производительности)
    ]);
    
    if (empty($items)) {
        $rootActivity = $this->GetRootActivity();
        $rootActivity->SetVariable("ElementIDs", array());
        $rootActivity->SetVariable("FoundCount", 0);
        $rootActivity->SetVariable("Status", "NOT_FOUND");
        return;
    }
    
    $itemIDs = array();
    foreach ($items as $item) {
        $itemIDs[] = $item->getId();
    }
    
    // Проверка лимита
    if (count($items) >= 500) {
        $this->WriteToTrackingService("[WARNING] Достигнут лимит выборки 500 записей, возможны необработанные элементы");
    }
    
    // ВЫХОДНЫЕ ПАРАМЕТРЫ: Массив ID элементов и статус выполнения
    $rootActivity = $this->GetRootActivity();
    $rootActivity->SetVariable("ElementIDs", $itemIDs);
    $rootActivity->SetVariable("FoundCount", count($itemIDs));
    $rootActivity->SetVariable("Status", "SUCCESS");
    
} catch (\Exception $e) {
    $this->WriteToTrackingService("[CRITICAL] Ошибка получения элементов: " . $e->getMessage());
    $rootActivity = $this->GetRootActivity();
    $rootActivity->SetVariable("Status", "DB_ERROR");
    $rootActivity->SetVariable("ErrorMessage", $e->getMessage());
}

Входные параметры:

  • EntityTypeId (string/int) - ID типа Смарт-процесса (обязательный параметр). Как узнать?

Выходные переменные:

  • ElementIDs (array) - Массив ID всех найденных элементов
  • FoundCount (int) - Количество найденных элементов
  • Status (string) - Статус выполнения: SUCCESS, NOT_FOUND, INPUT_ERROR, FACTORY_ERROR, DB_ERROR
  • ErrorMessage (string) - Описание ошибки (заполняется при ошибках)

Возможные ошибки:

  • INPUT_ERROR - не передан EntityTypeId
  • FACTORY_ERROR - фабрика для указанного типа не найдена (неверный ID или тип удален)
  • DB_ERROR - ошибка при работе с базой данных
  • NOT_FOUND - элементы не найдены

Рекомендации:

  • Убедитесь, что модуль crm подключен с помощью Loader::includeModule('crm')
  • ID типа можно найти в настройках CRM или через crm.type.list в REST API
  • Всегда проверяйте переменную Status в следующих шагах БП
  • Для больших объемов данных (>500 записей) используйте пагинацию или агенты

Пример 2: Получение элементов с фильтрацией по пользовательскому полю

Этот пример демонстрирует, как получить элементы Смарт-процесса, применяя фильтр по пользовательскому полю через Factory API.

  • Установлен лимит: не больше 500 элементов (лимит можно изменить в строке 32-35)
  use Bitrix\Crm\Service\Container;
use Bitrix\Main\Loader;

Loader::includeModule('crm');

// ВХОДНЫЕ ПАРАМЕТРЫ: ID типа, код поля и значение для фильтрации
$entityTypeId = "{{EntityTypeId}}";
$userFieldCode = "{{UserFieldCode}}"; // Например: UF_CRM_MY_FIELD
$userFieldValue = "{{UserFieldValue}}";

// Валидация входных данных
if (empty($entityTypeId) || empty($userFieldCode) || empty($userFieldValue)) {
    $this->WriteToTrackingService("[ERROR] Не переданы обязательные параметры");
    $rootActivity = $this->GetRootActivity();
    $rootActivity->SetVariable("Status", "INPUT_ERROR");
    return;
}

$entityTypeId = (int)$entityTypeId;

try {
    $factory = Container::getInstance()->getFactory($entityTypeId);
    
    if (!$factory) {
        $this->WriteToTrackingService("[ERROR] Фабрика для типа Смарт-процесса " . $entityTypeId . " не найдена");
        $rootActivity = $this->GetRootActivity();
        $rootActivity->SetVariable("Status", "FACTORY_ERROR");
        return;
    }
    
    // ФИЛЬТРАЦИЯ: Выборка элементов по пользовательскому полю
    $items = $factory->getItems([
        'filter' => [$userFieldCode => $userFieldValue], // Фильтр по указанному полю
        'select' => ['ID', $userFieldCode], // Выбираем только нужные поля
        'limit' => 500 // Лимит записей за один запрос
    ]);
    
    if (empty($items)) {
        $rootActivity = $this->GetRootActivity();
        $rootActivity->SetVariable("FilteredElementIDs", array());
        $rootActivity->SetVariable("FoundCount", 0);
        $rootActivity->SetVariable("Status", "NOT_FOUND");
        return;
    }
    
    $filteredItemIDs = array();
    foreach ($items as $item) {
        $filteredItemIDs[] = $item->getId();
    }
    
    if (count($items) >= 500) {
        $this->WriteToTrackingService("[WARNING] Достигнут лимит выборки, возможны необработанные записи");
    }
    
    // ВЫХОДНЫЕ ПАРАМЕТРЫ: Массив ID отфильтрованных элементов и статус
    $rootActivity = $this->GetRootActivity();
    $rootActivity->SetVariable("FilteredElementIDs", $filteredItemIDs);
    $rootActivity->SetVariable("FoundCount", count($filteredItemIDs));
    $rootActivity->SetVariable("Status", "SUCCESS");
    
} catch (\Exception $e) {
    $this->WriteToTrackingService("[CRITICAL] Ошибка фильтрации элементов: " . $e->getMessage());
    $rootActivity = $this->GetRootActivity();
    $rootActivity->SetVariable("Status", "DB_ERROR");
    $rootActivity->SetVariable("ErrorMessage", $e->getMessage());
}

Входные параметры:

  • EntityTypeId (string/int) - ID типа Смарт-процесса (обязательный). Как узнать?
  • UserFieldCode (string) - Код пользовательского поля (например, UF_CRM_MY_FIELD) (обязательный). Как узнать?
  • UserFieldValue (mixed) - Значение для фильтрации (обязательный)

Выходные переменные:

  • FilteredElementIDs (array) - Массив ID отфильтрованных элементов
  • FoundCount (int) - Количество найденных элементов
  • Status (string) - Статус выполнения операции
  • ErrorMessage (string) - Описание ошибки

Возможные ошибки:

  • INPUT_ERROR - не переданы обязательные параметры (EntityTypeId, UserFieldCode или UserFieldValue)
  • FACTORY_ERROR - фабрика для типа не найдена
  • DB_ERROR - ошибка при выполнении запроса к БД
  • NOT_FOUND - элементы по заданному фильтру не найдены

Рекомендации:

  • Коды пользовательских полей имеют формат UF_CRM_* - уточняйте точные коды в настройках полей
  • Используйте параметр select для выборки только необходимых полей - это ускоряет выполнение запроса
  • Factory API - предпочтительный способ работы со Смарт-процессами, обеспечивающий единообразие

Пример 3: Получение дочерних элементов с исключением завершенных стадий

Продвинутый пример для получения IDs “ТОЛЬКО активных дочерних элементов” Смарт-процесса.

  • Установлен лимит: не больше 500 элементов (лимит можно изменить в строке 54-58)
  use Bitrix\Crm\Service\Container;
use Bitrix\Crm\PhaseSemantics;
use Bitrix\Main\Loader;

Loader::includeModule('crm');

// ВХОДНЫЕ ПАРАМЕТРЫ: ID родителя, тип смарт-процесса и поле связи
$parentId = "{{ParentID}}";
$smartProcessTypeId = "{{SmartProcessTypeId}}";
$parentFieldCode = "{{ParentFieldCode}}"; // Например: PARENT_ID_1360

// Валидация
if (empty($parentId) || empty($smartProcessTypeId) || empty($parentFieldCode)) {
    $this->WriteToTrackingService("[ERROR] Не переданы обязательные параметры: ParentID, SmartProcessTypeId или ParentFieldCode");
    $rootActivity = $this->GetRootActivity();
    $rootActivity->SetVariable("Status", "INPUT_ERROR");
    return;
}

$smartProcessTypeId = (int)$smartProcessTypeId;

try {
    // Получение фабрики
    $factory = Container::getInstance()->getFactory($smartProcessTypeId);
    
    if (!$factory) {
        $this->WriteToTrackingService("[ERROR] Фабрика для типа " . $smartProcessTypeId . " не найдена");
        $rootActivity = $this->GetRootActivity();
        $rootActivity->SetVariable("Status", "FACTORY_ERROR");
        return;
    }
    
    // СЛОЖНАЯ ЛОГИКА: Получение завершенных стадий (SUCCESS и FAILURE)
    // Это критично для фильтрации только активных элементов
    $finalStageIds = array();
    $stages = $factory->getStages();
    
    foreach ($stages as $stage) {
        if ($stage->getSemantics() === PhaseSemantics::SUCCESS || 
            $stage->getSemantics() === PhaseSemantics::FAILURE) {
            $finalStageIds[] = $stage->getStatusId();
        }
    }
    
    // ФИЛЬТР: Формируем условия выборки с исключением завершенных стадий
    $filter = array(
        $parentFieldCode => $parentId // Фильтр по родительскому элементу
    );
    
    if (!empty($finalStageIds)) {
        $filter['!STAGE_ID'] = $finalStageIds; // Исключаем завершенные стадии
    }
    
    // ПОЛУЧЕНИЕ ДАННЫХ: Выборка активных дочерних элементов
    $smartProcessElements = $factory->getItems([
        'filter' => $filter,
        'limit' => 500 // Лимит записей за один запрос
    ]);
    
    if (empty($smartProcessElements)) {
        $rootActivity = $this->GetRootActivity();
        $rootActivity->SetVariable("ElementIDs", array());
        $rootActivity->SetVariable("ElementCodes", array());
        $rootActivity->SetVariable("FoundCount", 0);
        $rootActivity->SetVariable("Status", "NOT_FOUND");
        return;
    }
    
    $elementIds = array();
    $elementCodes = array();
    
    // СЛОЖНАЯ ЛОГИКА: Конвертация ID типа в hex-префикс для REST API
    $hexPrefix = 'T' . strtolower(dechex($smartProcessTypeId));
    
    foreach ($smartProcessElements as $element) {
        $elementId = $element->getId();
        $elementIds[] = $elementId;
        $elementCodes[] = $hexPrefix . '_' . $elementId;
    }
    
    // Проверка лимита
    if (count($smartProcessElements) >= 500) {
        $this->WriteToTrackingService("[WARNING] Достигнут лимит выборки 500 записей, возможны необработанные элементы");
    }
    
    // ВЫХОДНЫЕ ПАРАМЕТРЫ: ID элементов, коды для REST API и статус
    $rootActivity = $this->GetRootActivity();
    $rootActivity->SetVariable("ElementIDs", $elementIds);
    $rootActivity->SetVariable("ElementCodes", $elementCodes);
    $rootActivity->SetVariable("FoundCount", count($elementIds));
    $rootActivity->SetVariable("Status", "SUCCESS");
    
} catch (\Exception $e) {
    $this->WriteToTrackingService("[CRITICAL] Ошибка получения элементов: " . $e->getMessage());
    $rootActivity = $this->GetRootActivity();
    $rootActivity->SetVariable("Status", "DB_ERROR");
    $rootActivity->SetVariable("ErrorMessage", $e->getMessage());
}

Входные параметры:

  • ParentID (string/int) - ID родительского элемента (обязательный)
  • SmartProcessTypeId (string/int) - ID типа дочернего Смарт-процесса (обязательный). Как узнать?
  • ParentFieldCode (string) - Код поля связи с родителем (например, PARENT_ID_1360) (обязательный). Как узнать?

Выходные переменные:

  • ElementIDs (array) - Массив ID активных дочерних элементов
  • ElementCodes (array) - Массив “кодов элементов” для REST API и поля привязки к CRM в Задачах (формат: T5a4_123)
  • FoundCount (int) - Количество найденных активных элементов
  • Status (string) - Статус выполнения операции
  • ErrorMessage (string) - Описание ошибки

Возможные ошибки:

  • INPUT_ERROR - не переданы обязательные параметры (ParentID, SmartProcessTypeId или ParentFieldCode)
  • FACTORY_ERROR - фабрика для указанного типа не найдена
  • DB_ERROR - ошибка при работе с базой данных
  • NOT_FOUND - активные дочерние элементы не найдены (все элементы могут быть в завершенных стадиях)

Работа со стадиями:

Смарт-процессы имеют стадии с различной семантикой:

  • PhaseSemantics::PROCESS - стадии в процессе работы
  • PhaseSemantics::SUCCESS - успешно завершенные стадии
  • PhaseSemantics::FAILURE - провальные стадии

Этот пример автоматически исключает элементы в стадиях SUCCESS и FAILURE, возвращая только активные элементы в работе.

Рекомендации:

  • Используйте ElementCodes при работе с REST API и привязке к задачам
  • Используйте ElementIDs для внутренней работы в PHP и действиях бизнес-процессов.
  • Поле связи с родителем имеет формат PARENT_ID_{TYPE_ID} - Как узнать?
  • При работе с иерархией всегда проверяйте, нужны ли вам завершенные элементы или только активные.

Фича примера кода №3:

Для работы с элементами через REST API Битрикс24 или для передачи в действие бизнес-процесса “Создать задачу”- возвращается в ElementCodes:

  T{hex_type_id}_{element_id}

Где:

  • T - префикс для типа
  • {hex_type_id} - ID типа в шестнадцатеричной системе (lowercase)
  • {element_id} - ID элемента

Пример: Для типа с ID 1364 (в hex = 554) и элемента с ID 123 код будет T554_123.

Эти коды используются например для привязки к задачам в поле “Элементы CRM”.

Общие рекомендации по использованию

  • Валидация: Всегда проверяйте входные параметры перед использованием, чтобы избежать выборки всех записей при пустых значениях.
  • Статусы: Всегда проверяйте переменную Status в следующих шагах БП для обработки различных сценариев выполнения.
  • Лимиты: Для больших объемов данных (>500 записей) используйте пагинацию или агенты для фоновой обработки.