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

Статья объясняет, как приложение регистрирует свой тип поля, как создать поле этого типа в карточке CRM и как разобрать типовые ошибки. Работа обработчика внутри поля описана в статье Пользовательские типы полей: обзор методов.

Быстрый переход: все методы

Пользовательская документация: Пользовательские поля в CRM

Стандартные и пользовательские типыСтандартные и пользовательские типы

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

• стандартные типы — строка, число, дата, список, адрес, ссылка, файл и другие. Их полный список возвращает метод crm.userfield.types
• пользовательские типы — типы, которые приложение регистрирует методом userfieldtype.add. Поле такого типа показывает в карточке CRM интерфейс приложения — это встройка

Если значение — обычный текст, число, дата или выбор из списка, подойдет стандартный тип. Пользовательский тип нужен, если поле должно:

• выводить данные, для которых не подходят стандартные типы. Значение хранится в Битрикс24, а приложение показывает его и при необходимости дополняет данными своего сервиса
• выводить элементы управления, например кнопки приложения
• подгружать данные внешнего сервиса: при каждом открытии карточки поле запрашивает обработчик приложения

Как работает пользовательский тип поляКак работает пользовательский тип поля

1. Приложение регистрирует тип методом userfieldtype.add: передает код типа USER_TYPE_ID и адрес обработчика HANDLER. Код типа сохраняется строчными буквами: MyField превратится в myfield.
2. Поле этого типа создают с полным кодом rest_<APP_ID>_<USER_TYPE_ID>, где APP_ID — значение ID из ответа метода app.info.
3. Когда пользователь открывает карточку, Битрикс24 загружает HANDLER во фрейме поля и передает данные поля и элемента в PLACEMENT_OPTIONS.
4. Обработчик передает значение в форму карточки командой setValue через BX24.placement.call. Значение запишется в Битрикс24, когда пользователь сохранит карточку.

Методы userfieldtype.* работают только в контексте приложения: при вызове через вебхук они возвращают ошибку WRONG_AUTH_TYPE. Вызывать их может только администратор. Для создания поля эти условия не действуют. Поле по полному коду типа можно создать через вебхук или из другого приложения — нужны только права и scope из раздела Как создать поле пользовательского типа.

Как создать поле пользовательского типаКак создать поле пользовательского типа

Поле создают универсальным методом userfieldconfig.add или методом crm.*.userfield.add нужного объекта.

Методы crm.*.userfield.add устарели, но поля с типами приложений создают. Методы REST 3.0 crm.<тип>.field.custom.add, которые их заменяют, такие поля не создают.

В методах crm.*.userfield.add полный код передают в fields.USER_TYPE_ID, в userfieldconfig.add — в field.userTypeId. Например, для приложения с ID: 123 и типа userfield1 код будет rest_123_userfield1.

Методам crm.*.userfield.add нужен scope crm, методу userfieldconfig.add — scope userfieldconfig и crm. Всем этим методам нужно право «Разрешить изменять настройки» в CRM.

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

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

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

1. Выполните метод userfieldtype.list из того приложения, которое регистрировало тип: метод возвращает только типы вызывающего приложения.

   • Если в списке есть нужный тип, сверьте код в запросе на создание поля. Нужен полный код rest_<APP_ID>_<USER_TYPE_ID>, где USER_TYPE_ID — значение из ответа userfieldtype.list. Если код верный, переходите к пункту 2.

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

2. Выполните метод app.info. Метод возвращает флаг INSTALLED — признак завершенной установки.

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

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

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

Обработчик не открывается в полеОбработчик не открывается в поле

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

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

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

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

   • проверьте, что адрес HANDLER открывается с устройства вне вашей сети

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

   • что SSL-сертификат обработчика корректный

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

Требования и рекомендацииТребования и рекомендации

• Обработчик должен открываться по HTTPS: страница Битрикс24 открыта по HTTPS, и браузер блокирует загрузку фрейма по HTTP.

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

• Код типа USER_TYPE_ID после регистрации не меняется: userfieldtype.update изменяет только название, описание и обработчик. Для нового кода удалите тип и зарегистрируйте заново.

Обзор методовОбзор методов

Scope: placement

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

Продолжите изучениеПродолжите изучение

• Пользовательские типы полей: обзор методов
• Как встроить виджет в лид в виде пользовательского поля
• Механизм встраивания виджетов