Каждый PHP-разработчик, работающий с экосистемой Bitrix Framework, должен глубоко понимать работу её ключевых компонентов. В этой статье мы проведем подробный аудит темы «Пользовательские типы полей в CRM», проанализируем лучшие практики и покажем, как правильно использовать пользовательские типы в реальных задачах.

Пользовательские типы полей в CRM

В CRM можно создавать поля двух типов:

• стандартные: число, строка, дата, адрес, ссылка, файл и так далее,
• пользовательские: встройки приложений внутри карточки CRM.

С помощью полей пользовательского типа можно:

• выводить в карточке CRM данные, которым не подходят стандартные типы полей. Фактически данные будут храниться в базе приложения в нужном формате, а встройка будет показывать их внутри поля.
• создавать элементы интерфейса в карточках CRM. Например, выводить внутри поля кнопки для управления приложением.
• интегрировать внешние сервисы в карточку CRM. Например, выводить в поле динамическую информацию. При каждом открытии карточки поле будет совершать запрос к обработчику приложения и автоматически подгружать свежие данные.

> Быстрый переход: все методы
>
> Пользовательская документация: Работа с пользовательскими полями

Связь с объектами CRM

Пользовательские типы полей можно добавлять в карточки:

• сделок — используйте методы crm.deal.userfield.add или userfieldconfig.add,
• лидов — crm.lead.userfield.add или userfieldconfig.add,
• контактов — crm.contact.userfield.add или userfieldconfig.add,
• компаний — crm.company.userfield.add или userfieldconfig.add,
• новых счетов — userfieldconfig.add,
• коммерческих предложений — crm.quote.userfield.add или userfieldconfig.add,
• смарт-процессов — userfieldconfig.add.

В поле USER_TYPE_ID передавайте значение по форме rest_#ID_приложения#_#USER_TYPE_ID#. Например, для приложения с ID: 123 и USER_TYPE_ID: userfield1 значение будет rest_123_test_userfield1.

Чтобы получить ID приложения, используйте метод app.info.

Ошибки при работе с пользовательскими типами полей

Ошибка 400 при создании поля

При создании поля с пользовательским типом можно получить ошибку Error! 400: ERROR_CORE: Указан неверный пользовательский тип. (400).

1. Выполните метод userfieldtype.list.

• Если метод вернул тип поля USER_TYPE_ID, переходите к пункту 2.

• Если нужный тип поля не найден, зарегистрируйте новый тип методом userfieldtype.add.

2. Выполните метод app.info. Метод проверит корректность установки приложения.

• Если метод вернул INSTALLED = true, приложение установлено корректно.

• Если метод вернул INSTALLED = false, выполните на странице приложения метод BX24.installFinish. Метод завершит установку приложения с интерфейсом.

    BX24.init(function(){
        BX24.installFinish();
    });

Ошибка 50x при загрузке поля

Если поле создалось без ошибок, но контент в нем не загружается:

1. Проверьте URL обработчика HANDLER, указанный при регистрации поля, методом userfieldtype.list. Чтобы изменить HANDLER, используйте метод userfieldtype.update.

2. Убедитесь, что обработчик доступен из интернета:

• не используйте локальные адреса: localhost, 192.168.* и другие адреса, доступные только из локальной сети,

• проверьте доступность обработчика с помощью публичных сервисов «доступности сайта».

3. Проверьте:

• корректность SSL-сертификата, если используется HTTPS,

• отсутствие блокировок в .htaccess или firewall на сервере обработчика,

• возвращаемые HTTP-коды, должен быть 200 OK.

Общие рекомендации

• Используйте HTTPS-протокол для обработчиков, иначе браузеры могут блокировать загрузку контента приложения.

• Давайте понятные названия для типов полей: учитывайте назначение поля и связь с приложением. Тип поля нельзя переименовать после создания — только удалить и зарегистрировать заново.

• Встроить виджет в лид в виде пользовательского свойства

• Механизм встройки виджетов

Обзор методов {#all-methods}

> Scope: placement, crm
>
> Кто может выполнять метод: администратор