CRM / Пользовательские поля

Примеры внутреннего PHP API предназначены для коробки с подключённым ядром. Прямое чтение таблиц здесь — административная диагностика: оно само по себе не проверяет доступ пользователя к найденным объектам. Не публикуйте такой код как открытый HTTP-обработчик.

Общее понимание

Пользовательское поле состоит из двух частей: описание поля и значение поля в конкретной карточке.

Что такое UF-поля

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

Что нужно	Где смотреть
Описание поля	`Bitrix\Main\UserFieldTable` или `getUserFieldsInfo()`
Значение поля	В карточке CRM через фабрику, `get()` или `toArray()`
Создание/изменение поля	`CUserTypeEntity`

ENTITY_ID пользовательских полей

У пользовательского поля есть ENTITY_ID — код сущности, к которой поле относится.

CRM-сущность	ENTITY_ID
Лиды	`CRM_LEAD`
Сделки	`CRM_DEAL`
Контакты	`CRM_CONTACT`
Компании	`CRM_COMPANY`
Смарт-процессы	Лучше получать через фабрику: `$factory->getUserFieldEntityId()`

<?php

use Bitrix\Main\Loader;

if (!Loader::includeModule('crm')) {
    throw new \RuntimeException('Модуль crm не загружен');
}

function fetchUserFieldEntityId(int $entity_type_id): string {
    return \CCrmOwnerType::ResolveUserFieldEntityID($entity_type_id);
}

$deal_user_field_entity_id = fetchUserFieldEntityId(\CCrmOwnerType::Deal);

echo $deal_user_field_entity_id;

Получение полей

Для чтения описания полей удобнее использовать фабрику или D7-таблицу пользовательских полей.

Через фабрику CRM

Фабрика возвращает описание стандартных и пользовательских полей конкретного типа CRM.

<?php

use Bitrix\Main\Loader;
use Bitrix\Crm\Service;


if (!Loader::includeModule('crm')) {
    throw new \RuntimeException('Модуль crm не загружен');
}
const CRM_ENTITY_TYPE_ID = \CCrmOwnerType::Deal;

function fetchCrmFactoryFieldsInfo(int $entity_type_id): array {
    $factory = Service\Container::getInstance()->getFactory($entity_type_id);

    if ($factory === null) {
        return [];
    }

    return [
        'fields' => $factory->getFieldsInfo(),
        'user_fields' => $factory->getUserFieldsInfo(),
    ];
}

$fields_info = fetchCrmFactoryFieldsInfo(CRM_ENTITY_TYPE_ID);

print_r($fields_info);

Через UserFieldTable

UserFieldTable можно использовать для чтения списка полей и их системных настроек.

<?php

use Bitrix\Main\Loader;
use Bitrix\Main\UserFieldTable;

if (!Loader::includeModule('crm')) {
    throw new \RuntimeException('Модуль crm не загружен');
}

function fetchUserFieldsByEntityId(string $entity_id): array {
    $user_fields = [];

    $user_field_result = UserFieldTable::getList([
        'select' => [
            'ID',
            'ENTITY_ID',
            'FIELD_NAME',
            'USER_TYPE_ID',
            'XML_ID',
            'SORT',
            'MULTIPLE',
            'MANDATORY',
            'SHOW_IN_LIST',
            'EDIT_IN_LIST',
            'IS_SEARCHABLE',
            'SETTINGS',
        ],
        'filter' => [
            '=ENTITY_ID' => $entity_id,
        ],
        'order' => [
            'SORT' => 'ASC',
            'ID' => 'ASC',
        ],
    ]);

    while ($user_field = $user_field_result->fetch()) {
        $user_fields[] = $user_field;
    }

    return $user_fields;
}

$user_fields = fetchUserFieldsByEntityId('CRM_DEAL');

print_r($user_fields);

Получить значения из карточки

Значение пользовательского поля читается как обычное поле элемента CRM.

<?php

use Bitrix\Main\Loader;
use Bitrix\Crm\Service;

const DEAL_CUSTOM_FIELD_ID = 'UF_CRM_1234567890';

if (!Loader::includeModule('crm')) {
    throw new \RuntimeException('Модуль crm не загружен');
}
const CRM_DEAL_TYPE_ID = \CCrmOwnerType::Deal;

function fetchDealCustomFieldValue(int $deal_id, string $field_id) {
    $factory = Service\Container::getInstance()->getFactory(CRM_DEAL_TYPE_ID);

    if ($factory === null) {
        return null;
    }

    $deal_item = $factory->getItem($deal_id);

    if ($deal_item === null) {
        return null;
    }

    return $deal_item->get($field_id);
}

$field_value = fetchDealCustomFieldValue($deal_id, DEAL_CUSTOM_FIELD_ID);

print_r($field_value);

Создание и изменение

Для изменения описания пользовательских полей в коробке обычно используют CUserTypeEntity.

Добавить пользовательское поле

<?php

use Bitrix\Main\Loader;

if (!Loader::includeModule('crm')) {
    throw new \RuntimeException('Модуль crm не загружен');
}

function addStringUserField(string $entity_id, string $field_name, string $label): int {
    $user_type_entity = new \CUserTypeEntity();

    $field_id = $user_type_entity->Add([
        'ENTITY_ID' => $entity_id,
        'FIELD_NAME' => $field_name,
        'USER_TYPE_ID' => 'string',
        'XML_ID' => $field_name,
        'SORT' => 500,
        'MULTIPLE' => 'N',
        'MANDATORY' => 'N',
        'SHOW_FILTER' => 'I',
        'SHOW_IN_LIST' => 'Y',
        'EDIT_IN_LIST' => 'Y',
        'IS_SEARCHABLE' => 'Y',
        'EDIT_FORM_LABEL' => [
            'ru' => $label,
            'en' => $label,
        ],
        'LIST_COLUMN_LABEL' => [
            'ru' => $label,
            'en' => $label,
        ],
        'LIST_FILTER_LABEL' => [
            'ru' => $label,
            'en' => $label,
        ],
    ]);

    return (int) $field_id;
}

$field_id = addStringUserField(
    'CRM_DEAL',
    'UF_CRM_CUSTOM_COMMENT',
    'Комментарий интеграции'
);

echo $field_id;

Изменить настройки поля

<?php

function updateUserFieldLabel(int $user_field_id, string $label): bool {
    $user_type_entity = new \CUserTypeEntity();

    return (bool) $user_type_entity->Update(
        $user_field_id,
        [
            'EDIT_FORM_LABEL' => [
                'ru' => $label,
                'en' => $label,
            ],
            'LIST_COLUMN_LABEL' => [
                'ru' => $label,
                'en' => $label,
            ],
            'LIST_FILTER_LABEL' => [
                'ru' => $label,
                'en' => $label,
            ],
        ]
    );
}

$is_updated = updateUserFieldLabel($user_field_id, 'Новое название поля');

var_dump($is_updated);

Удалить поле

Удаление поля удалит и значения этого поля в карточках. Перед удалением лучше отдельно проверить, где поле используется: карточки, роботы, бизнес-процессы, отчёты, интеграции.

<?php

function deleteUserField(int $user_field_id): bool {
    $user_type_entity = new \CUserTypeEntity();

    return (bool) $user_type_entity->Delete($user_field_id);
}

$is_deleted = deleteUserField($user_field_id);

var_dump($is_deleted);