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

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

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

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

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

<?php

use Bitrix\Main\Loader;

Loader::includeModule('crm');

/**
 * Получает ENTITY_ID пользовательских полей 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;

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

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

<?php

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

const CRM_ENTITY_TYPE_ID = \CCrmOwnerType::Deal;

Loader::includeModule('crm');

/**
 * Получает описание полей через фабрику.
 */
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;

Loader::includeModule('crm');

/**
 * Получает пользовательские поля по ENTITY_ID.
 */
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 CRM_DEAL_TYPE_ID = \CCrmOwnerType::Deal;
const DEAL_CUSTOM_FIELD_ID = 'UF_CRM_1234567890';

Loader::includeModule('crm');

/**
 * Получает значение пользовательского поля сделки.
 */
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);

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

<?php

use Bitrix\Main\Loader;

Loader::includeModule('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);

• Официальный курс: пользовательские поля
• Официальная документация: UserFieldTable
• Официальная документация: CUserTypeEntity
• Официальная документация: CRM Service Factory
• Официальная документация: CCrmOwnerType / идентификаторы
• REST: crm.userfield.fields