← Назад к справке

Бизнес-процессы

Поля документа

Как читать поля документа бизнес-процесса через DocumentService и как менять сам документ через API нужной сущности.

Документ бизнес-процесса — это сущность, по которой запущен процесс: сделка, лид, элемент списка, элемент смарт-процесса и так далее. В PHP-блоке поля документа лучше читать через DocumentService, а не через подстановки.

Чтение документа

Основной рабочий путь: получить ID документа, получить сервис документа и прочитать поля.

Получить document id

getDocumentId() возвращает идентификатор документа бизнес-процесса. Его формат зависит от типа документа. 

/**
 * Записывает document id в отчёт.
 */
function writeDocumentIdToReport($context): void
{
    $document_id = $context->getDocumentId();

    $context->WriteToTrackingService(
        print_r($document_id, true),
        0,
        \CBPTrackingType::Report
    );
}

writeDocumentIdToReport($this);

Перед универсальным кодом лучше один раз вывести getDocumentId() в отчёт и посмотреть фактический формат на своём типе документа.

Получить поля документа

Сервис документа можно получить из workflow через GetService('DocumentService'). Дальше вызывается getDocument(). 

/**
 * Получает поля документа бизнес-процесса.
 */
function fetchDocumentFields($context): array
{
    $document_service = $context->workflow->GetService('DocumentService');
    $document_fields = $document_service->getDocument($context->getDocumentId());

    return is_array($document_fields) ? $document_fields : [];
}

$document_fields = fetchDocumentFields($this);

$this->WriteToTrackingService(
    print_r($document_fields, true),
    0,
    \CBPTrackingType::Report
);

Получить конкретное поле

После получения документа можно брать нужное поле из массива. Код поля зависит от документа: для сделки это одни поля, для элемента списка — другие. 

/**
 * Получает значение поля документа.
 */
function fetchDocumentFieldValue(array $document_fields, string $field_id)
{
    return $document_fields[$field_id] ?? null;
}

$document_fields = fetchDocumentFields($this);

$title = (string) fetchDocumentFieldValue($document_fields, 'TITLE');

$this->SetVariable('document_title', $title);

Не нужно вставлять в PHP-код {=Document:TITLE}. Если поле пустое или содержит кавычки, можно получить синтаксическую ошибку ещё до выполнения кода.

Изменение документа

Читать документ можно через DocumentService, а изменять лучше через API той сущности, по которой запущен процесс.

Почему не через $this

$this — это контекст действия бизнес-процесса. Через него удобно работать с переменными, константами и отчётом, но саму CRM-карточку лучше менять через CCrmDeal, фабрику CRM, ORM смарт-процесса или стандартное действие изменения документа.

Изменить сделку CRM

Пример ниже подходит как заготовка для CRM-документа сделки. Для другого документа сначала выведите getDocumentId() и проверьте формат. 

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

/**
 * Получает ID сущности из document id.
 */
function fetchEntityIdFromDocumentId($context): int
{
    $document_ids = $context->getDocumentId();
    $document_code = is_array($document_ids) ? (string) end($document_ids) : (string) $document_ids;

    preg_match('/(\d+)$/', $document_code, $matches);

    return isset($matches[1]) ? (int) $matches[1] : 0;
}

/**
 * Изменяет поле сделки.
 */
function updateDealField(int $deal_id, string $field_id, $field_value): bool
{
    if ($deal_id <= 0) {
        return false;
    }

    $deal = new \CCrmDeal();

    return (bool) $deal->Update(
        $deal_id,
        [
            $field_id => $field_value,
        ]
    );
}

$deal_id = fetchEntityIdFromDocumentId($this);

$is_updated = updateDealField($deal_id, 'TITLE', 'Новое название сделки');

$this->WriteToTrackingService(
    $is_updated ? 'Сделка обновлена' : 'Сделка не обновлена',
    0,
    \CBPTrackingType::Report
);

Источники