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

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

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

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

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

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

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

Получить document id

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

$document_id = $this->getDocumentId();

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

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

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

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

$document_service = $this->workflow->GetService('DocumentService');
$document_fields = $document_service->getDocument($this->getDocumentId());
$document_fields = is_array($document_fields) ? $document_fields : [];

$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_service = $this->workflow->GetService('DocumentService');
$document_fields = $document_service->getDocument($this->getDocumentId());
$document_fields = is_array($document_fields) ? $document_fields : [];

$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($document_ids): int
{
    $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();

    $fields = [
        $field_id => $field_value,
    ];

    return (bool) $deal->Update($deal_id, $fields);
}

$deal_id = fetchEntityIdFromDocumentId($this->getDocumentId());

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

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

Источники