bitrix-bizproc

name	bitrix-bizproc
description	Covers business processes (bizproc) — start/stop workflows from PHP, document types, custom activities in /local/activities/, boundary vs agents/Messenger; mentions bizprocdesigner. Applied for approvals, document workflows, automation activities. Key terms — CBPDocument, CBPRuntime, CBPWorkflow, CBPActivity, document type, Starter, workflow template, activities.

Business Processes (bizproc)

Baseline: main 23.0+. Verified against kernel module bizproc in this repo.

\Bitrix\Main\Loader::includeModule('bizproc');

Visual template designer UI lives in module bizprocdesigner (optional; feature flag BizProc). Runtime execution, documents, and activities are in bizproc.

Core Runtime Classes

Class	Role
\CBPDocument	Start / terminate / kill workflows; templates for start; permissions
\CBPRuntime	Runtime singleton; createWorkflow, getWorkflow, feature checks
\CBPWorkflow	Running instance
\CBPActivity	Base class for all activities (execute(), properties)
\CBPWorkflowTemplateLoader	Template search/load
\CBPDocumentService	Document provider bridge (module entity callbacks)
\CBPDocumentEventType	Create / Edit / Manual / Automation / …

Document identity is always a complex id array: [MODULE_ID, ENTITY, DOCUMENT_ID] (or type: [MODULE_ID, ENTITY, DOCUMENT_TYPE]).

Providers (CRM, lists, disk, …) register document services. Resolve helpers: \CBPHelper::ParseDocumentId(), normalizeComplexDocumentId(). Copy real [module, entity, id|type] triples from the owning module or an existing template — do not invent them.

Start / Stop from PHP

\Bitrix\Main\Loader::includeModule('bizproc');

$documentId = ['crm', 'CCrmDocumentDeal', $dealId]; // shape is provider-specific
$errors = [];

$workflowId = \CBPDocument::startWorkflow(
    $templateId,
    $documentId,
    [
        \CBPDocument::PARAM_TAGRET_USER => 'user_' . $userId, // spelling as in kernel
        \CBPDocument::PARAM_DOCUMENT_EVENT_TYPE => \CBPDocumentEventType::Manual,
    ],
    $errors,
);

\CBPDocument::autoStartWorkflows(
    $documentType, // [module, entity, type]
    \CBPDocumentEventType::Create, // or Edit
    $documentId,
    $parameters,
    $errors,
);

\CBPDocument::terminateWorkflow($workflowId, $documentId, $errors, $stateTitle = '');
\CBPDocument::killWorkflow($workflowId, terminate: true, documentId: $documentId);
\CBPDocument::sendExternalEvent($workflowId, $eventName, $parameters, $errors);

$can = \CBPDocument::canUserOperateDocument(
    \CBPCanUserOperateOperation::StartWorkflow,
    $userId,
    $documentId,
);

Also: getTemplatesForStart, getDocumentStates, getDocumentState.

Modern API: \Bitrix\Bizproc\Starter\Starter::getByScenario(Scenario::onManual) → setDocument / setTemplateIds / start() → StartResult. Facade: \Bitrix\Bizproc\Public\Service\Workflow\StarterService. AJAX: \Bitrix\Bizproc\Controller\Workflow\Starter.

Document Types Overview

A document type selects the provider that implements fields/rights via CBPDocumentService (GetDocumentFields, GetDocument, …). Starting a workflow needs: template id, matching complex document id, and parameters (CBPDocument::PARAM_* + template vars).

Custom Activities (/local/activities/)

Activity search order (\Bitrix\Bizproc\Runtime\ActivitySearcher\Searcher):

1. /local/activities
2. /local/activities/custom
3. /bitrix/activities/custom
4. /bitrix/activities/bitrix
5. /bitrix/modules/bizproc/activities

Minimal activity folder:

/local/activities/myvendorapprove/
├── .description.php      # ActivityDescription → $arActivityDescription
├── myvendorapprove.php   # class CBPMyVendorApprove extends CBPActivity
├── properties_dialog.php # optional designer form
└── lang/ru/*.php

Kernel sample pattern (DelayActivity):

// myvendorapprove.php
class CBPMyVendorApprove extends CBPActivity
{
    public function __construct($name)
    {
        parent::__construct($name);
        $this->arProperties = [
            'Title' => '',
            'Comment' => '',
        ];
    }

    public function execute()
    {
        // business work; use $this->GetDocumentId(), workflow services
        return CBPActivityExecutionStatus::Closed;
    }
}

.description.php should build \Bitrix\Bizproc\Activity\ActivityDescription (see install/activities/bitrix/delayactivity/.description.php) with setClass, type (ActivityType::ACTIVITY), category/groups.

Rules:

• Class name convention: CBP + activity directory name (PascalCase), matching setClass.
• No long blocking I/O inside execute() without scheduling — use delay/event activities or external jobs.
• Register nothing in .settings.php for filesystem activities — discovery is by folder scan.

Boundary vs Agents / Messenger

See skill bitrix-background-jobs.

Mechanism	Use when
Bizproc	Human tasks, approvals, document-state machine, branching by fields
CAgent	Periodic maintenance without document UI
addBackgroundJob	Short post-response work in same hit
Messenger	Reliable async jobs, retries, consumers (messenger:consume)

Bizproc can schedule delays (CBPDelayActivity, scheduler service) and may enqueue start via Messenger receivers (e.g. WorkflowStartReceiver) — that is internal runtime support, not a reason to replace BP with a queue for approvals.

Do not reimplement approval chains as agents. Do not run heavy CRM sync inside an activity execute() — start a Messenger message / agent and let the activity wait on an external event if needed (sendExternalEvent).

Designer Module

• bizprocdesigner: template designer UI; requires BP feature enabled (include.php checks CBXFeatures::IsFeatureEnabled('BizProc')).
• Template editing is admin/UI; runtime code should not depend on designer classes.

Checklist

• Loader::includeModule('bizproc') (and owning document module: crm, lists, …).
• Complex document id matches template document type.
• Handle $errors from startWorkflow / terminateWorkflow — do not ignore.
• Check canUserOperateDocument / type rights before manual start.
• Custom activities under /local/activities/… with .description.php + CBP* class.
• Approvals → bizproc; cron sync → agents/Messenger (bitrix-background-jobs).
• Prefer Result/StartResult patterns at module boundary when wrapping starters in services.