CBPDocument::StartWorkflow: программный запуск бизнес-процессов в коробочной версии Битрикс24

Область применения и ключевые сущности

Метод CBPDocument::StartWorkflow используется для программного запуска бизнес-процессов над следующими типами документов (и не только):

• Лиды CRM (CCrmDocumentLead) — запуск БП для лида.
• Сделки CRM (CCrmDocumentDeal) — запуск БП для сделки.
• Смарт-процессы (Bitrix\Crm\Integration\BizProc\Document\Dynamic) — БП для динамических сущностей CRM.
• Элементы инфоблоков (CIBlockDocument) — запуск БП для элемента инфоблока.
• Элементы универсальных списков (BizprocDocument) — БП для списков.
• Задачи (Bitrix\Tasks\Integration\Bizproc\Document\Task) — БП для задач.
• Документы диска (Bitrix\Disk\BizProcDocument) — БП для файлов в Диске.
• Документы ленты новостей (CBPVirtualDocument) — БП для элементов ленты.

Параметры метода

Метод имеет следующую сигнатуру:

php

public static function StartWorkflow(
    integer $workflowTemplateId,
    array $documentId,
    array $arParameters,
    array &$arErrors
)

Параметр workflowTemplateId (ID шаблона БП)

Числовой идентификатор шаблона бизнес-процесса, который необходимо запустить. ID можно получить:

• Из URL при редактировании шаблона в административной части (/bitrix/admin/bizproc_workflow_edit.php?ID=190 — здесь ID=190).
• Из таблицы b_bp_workflow_template.
• Программно через CBPWorkflowTemplateLoader::GetList().

Параметр documentId (идентификатор документа)

Массив из трёх элементов, однозначно идентифицирующих документ, над которым запускается БП:

Компонент	Описание
module_id	Идентификатор модуля (например, 'crm', 'bizproc', 'disk', 'tasks')
document_class	Класс документа (например, 'CCrmDocumentLead', 'CIBlockDocument')
document_id	Непосредственно ID документа с учётом префикса (например, 'LEAD_123', 'DEAL_456')

Примеры documentId для разных сущностей:

php

// Лид CRM
['crm', 'CCrmDocumentLead', 'LEAD_' . $leadId]

// Сделка CRM
['crm', 'CCrmDocumentDeal', 'DEAL_' . $dealId]

// Смарт-процесс (Dynamic)
['crm', 'Bitrix\Crm\Integration\BizProc\Document\Dynamic', 'DYNAMIC_' . $entityTypeId . '_' . $elementId]

// Элемент инфоблока
['bizproc', 'CIBlockDocument', $elementId]

// Элемент универсального списка
['lists', 'BizprocDocument', $id_element]

// Шаблон списка (для запуска БП, привязанного к типу документа)
['lists', 'Bitrix\Lists\BizprocDocumentLists', $id_element]

// Задача
['tasks', 'Bitrix\Tasks\Integration\Bizproc\Document\Task', $taskId]

// Документ диска
['disk', 'Bitrix\Disk\BizProcDocument', $fileId]

Параметр arParameters (параметры запуска)

Ассоциативный массив, передающий входящие параметры бизнес-процесса. Ключи массива должны соответствовать именам параметров, определённых в шаблоне БП. Если процесс запускается из другого процесса и требуется передать множественное значение, оно должно быть оформлено как массив.

Обязательные параметры:

• 'TargetUser' — указывает, от чьего имени выполняется запуск. Формат: 'user_X', где X — ID пользователя. Рекомендуется передавать текущего пользователя: "user_" . intval($GLOBALS["USER"]->GetID()).

Параметр &$arErrors (массив ошибок)

Передаётся по ссылке. В случае ошибки заполняется массивом вида:

php

array(
    array(
        "code" => "код_ошибки",
        "message" => "сообщение об ошибке",
        "file" => "путь_к_файлу"
    ),
    ...
)

Возвращаемое значение

Метод возвращает строку — идентификатор запущенного экземпляра бизнес-процесса (workflowId). В случае ошибки возвращается null и заполняется $arErrors.

Практические примеры

Пример 1. Запуск БП для сделки CRM

php

if (\Bitrix\Main\Loader::includeModule('bizproc') && \Bitrix\Main\Loader::includeModule('crm')) {
    $arErrors = [];
    
    $wfId = CBPDocument::StartWorkflow(
        190,                                   // ID шаблона БП
        ['crm', 'CCrmDocumentDeal', 'DEAL_' . $dealId],  // идентификатор документа
        ['TargetUser' => 'user_' . $GLOBALS['USER']->GetID()], // параметры
        $arErrors
    );
    
    if (!empty($arErrors)) {
        foreach ($arErrors as $error) {
            echo "Ошибка: " . $error['message'] . "\n";
        }
    } else {
        echo "Бизнес-процесс запущен, ID: " . $wfId;
    }
}

Пример 2. Запуск БП для лида

php

CModule::IncludeModule('bizproc');
CModule::IncludeModule('crm');

$arErrorsTmp = [];

$wfId = CBPDocument::StartWorkflow(
    190,                                 // ID робота
    ['crm', 'CCrmDocumentLead', 'LEAD_' . $leadId],
    ['TargetUser' => 'user_1'],          // запуск от имени администратора
    $arErrorsTmp
);

if (count($arErrorsTmp) > 0) {
    foreach ($arErrorsTmp as $e) {
        echo "[".$e["code"]."] ".$e["message"]."\n";
    }
}

Пример 3. Запуск БП с передачей пользовательских параметров

php

// Предположим, в шаблоне БП есть параметры: "Comment" и "Priority"
$arWorkflowParameters = [
    'Comment' => 'Автоматически созданная заявка',
    'Priority' => 'High'
];

$arErrors = [];
$wfId = CBPDocument::StartWorkflow(
    95,
    ['bizproc', 'CBPVirtualDocument', $documentId],
    array_merge($arWorkflowParameters, ['TargetUser' => 'user_' . $USER->GetID()]),
    $arErrors
);

Пример 4. Запуск БП для элемента инфоблока

php

if (CModule::IncludeModule('bizproc') && CModule::IncludeModule('iblock')) {
    $arErrors = [];
    
    $wfId = CBPDocument::StartWorkflow(
        42,                                  // ID шаблона БП
        ['bizproc', 'CIBlockDocument', $elementId],
        ['TargetUser' => 'user_' . $GLOBALS['USER']->GetID()],
        $arErrors
    );
}

Пример 5. Запуск БП для элемента универсального списка

php

if (CModule::IncludeModule('bizproc') && CModule::IncludeModule('lists')) {
    $arErrors = [];
    
    $wfId = CBPDocument::StartWorkflow(
        56,                                         // ID шаблона
        ['lists', 'BizprocDocument', $elementId],   // идентификатор элемента списка
        ['TargetUser' => 'user_' . $GLOBALS['USER']->GetID()],
        $arErrors
    );
}

Пример 6. Запуск БП для смарт-процесса

php

$entityTypeId = 10;  // ID типа смарт-процесса
$elementId = 123;    // ID элемента смарт-процесса

$wfId = \CBPDocument::StartWorkflow(
    529,   // ID шаблона БП
    ['crm', 'Bitrix\Crm\Integration\BizProc\Document\Dynamic', 'DYNAMIC_' . $entityTypeId . '_' . $elementId],
    array_merge($arWorkflowParameters, ['TargetUser' => 'user_15']),
    $arErrorsTmp
);

Пример 7. Запуск БП для элемента ленты новостей

php

// Сначала создаём элемент ленты
$documentId = CBPVirtualDocument::CreateDocument(0, [
    'IBLOCK_ID' => 70,
    'NAME' => 'Уведомление',
    'CREATED_BY' => 'user_' . $GLOBALS['USER']->GetID(),
]);

// Запускаем БП для созданного элемента
$wfId = CBPDocument::StartWorkflow(
    246,                                    // шаблон БП
    ['bizproc', 'CBPVirtualDocument', $documentId],
    ['TargetUser' => 'user_' . $GLOBALS['USER']->GetID()],
    $arErrors
);

Особый случай: запуск БП при изменении стадии сделки/лида через API

Если вы изменяете стадию сделки или лида программно через CCrmDeal::Update() или CCrmLead::Update(), бизнес-процессы, настроенные на автоматический запуск при смене стадии, не сработают автоматически. Их нужно запускать явно.

Рекомендуемый подход — двухэтапное обновление:

php

$deal = new CCrmDeal(false);
$arOptions = ['CURRENT_USER' => $userId];

// Шаг 1: обновляем все поля, кроме стадии
$arUpdateData = [
    'UF_CRM_...' => $someValue,
    // другие поля...
];
$deal->Update($dealId, $arUpdateData, true, true, $arOptions);

// Шаг 2: меняем стадию
$arUpdateData = ['STAGE_ID' => $newStageId];
$deal->Update($dealId, $arUpdateData, true, true, $arOptions);

// Шаг 3: запускаем бизнес-процессы для сделки
CModule::IncludeModule('bizproc');
$arErrors = [];
CBPDocument::StartWorkflow(
    $bpId,   // ID шаблона БП, который должен сработать при переходе на эту стадию
    ['crm', 'CCrmDocumentDeal', 'DEAL_' . $dealId],
    ['TargetUser' => 'user_' . $userId],
    $arErrors
);

Альтернативные методы

Метод	Описание
CBPRuntime::CreateWorkflow()	Низкоуровневый метод, создающий экземпляр БП. Требует ручного вызова $wi->Start(). Рекомендуется использовать StartWorkflow как более удобную обёртку.
CBPDocument::AutoStartWorkflows()	Запускает все бизнес-процессы, настроенные на автозапуск для данного документа. Полезно при массовом импорте элементов.
CBPDocument::GetDocumentStates()	Позволяет получить список запущенных БП для документа. Может использоваться для проверки перед запуском.

Особенности и рекомендации

1. Обязательное подключение модулей: Перед вызовом метода необходимо подключить модуль bizproc через CModule::IncludeModule('bizproc') или \Bitrix\Main\Loader::includeModule('bizproc'). Для CRM-сущностей также потребуется crm.

2. ID шаблона бизнес-процесса: Самый простой способ получить ID — открыть шаблон в режиме редактирования (/bitrix/admin/bizproc_workflow_edit.php?ID=...) и посмотреть значение параметра ID в URL. Для программного получения можно использовать таблицу b_bp_workflow_template.

3. TargetUser: Всегда указывайте параметр TargetUser. Без него бизнес-процесс может выполниться, но действия, требующие прав пользователя (например, отправка уведомлений), могут отработать некорректно.

4. Обработка ошибок: Всегда проверяйте массив $arErrors после вызова метода. В официальной документации указано, что метод обрабатывает исключения и собирает их в этот массив.

5. Автозапуск при создании через API: При создании элемента через API (CCrmLead::Add, CIBlockElement::Add и т.д.) бизнес-процессы, настроенные на автозапуск, не запускаются. Используйте CBPDocument::StartWorkflow или CBPDocument::AutoStartWorkflows для их запуска.

6. Производительность: При массовом запуске БП (например, для нескольких сотен элементов) рекомендуется использовать агентов или отложенные вызовы, чтобы не превысить время выполнения скрипта.

7. Передача множественных параметров: Если параметр бизнес-процесса является множественным (например, список пользователей), передавайте его в виде массива.

Заключение

CBPDocument::StartWorkflow — это основной и рекомендуемый метод для программного запуска бизнес-процессов в коробочной версии Битрикс24. Он поддерживает все типы документов: от классических лидов и сделок до смарт-процессов, элементов инфоблоков и задач. Понимание этого метода необходимо каждому разработчику, который автоматизирует бизнес-логику через API Битрикс. Правильное использование метода с корректной обработкой ошибок позволяет гибко управлять бизнес-процессами и интегрировать их с внешними системами.