Как запустить БП по сделкам агентом

Задача

Сначала нужно отделить бизнес-сценарий от технического механизма.

Задача — как запустить БП по сделкам агентом. В этой теме важны: Агенты, CBPDocument::StartWorkflow, права пользователя.

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

Как это устроено

Большинство ошибок появляется из-за неверного формата данных или точки запуска.

ограничивайте выборку сделок;
проверяйте активные процессы, чтобы не создать дубли;
логируйте ошибки запуска;
учитывайте пользователя, от имени которого выполняются действия.

Рабочий подход

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

Для облака используйте REST и проверяйте права приложения. Для коробки, если код выполняется внутри портала, чаще удобнее PHP/D7 и штатные классы модуля.

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

Частые ошибки

Ошибки лучше ловить на минимальном примере, а не в большом процессе.

не проверили права пользователя или приложения;
перепутали ID, текстовое значение и XML_ID;
передали строку вместо массива для множественного поля;
запустили процесс повторно и получили дубли;
обошли штатную операцию CRM и не запустили роботов или события.

Минимальный пример

Пример показывает только базовую форму. На реальном портале замените ID, поля и права на свои.

use Bitrix\Main\Loader;

class DealWorkflowAgent
{
    public static function run(): string
    {
        Loader::includeModule('crm');
        Loader::includeModule('bizproc');

        $workflow_template_id = 123;
        $errors = [];

        foreach ([1001, 1002, 1003] as $deal_id) {
            $document_id = ['crm', 'CCrmDocumentDeal', 'DEAL_' . $deal_id];

            CBPDocument::StartWorkflow($workflow_template_id, $document_id, [], $errors);

            if ($errors) {
                AddMessage2Log($errors, 'deal_workflow_agent');
                $errors = [];
            }
        }

        return __METHOD__ . '();';
    }
}