В этом небольшом рецепте рассмотрим, как правильно добавлять контактную информацию в конфигурациях на базе БСП, на примере справочника Пользователи. Пример рассмотрен на базе БСП 3.1.9.
Почему нельзя просто добавить строку в табличную часть КонтактнаяИнформация?
Механизмы библиотеки требуют корректного формирования скрытого служебного реквизита Значение в формате JSON, а также реквизита ЗначенияПолей в формате XML. Для правильной работы с КИ следует использовать программный интерфейс — общий модуль УправлениеКонтактнойИнформацией.
Главный метод для записи контактов
В БСП 3.1.11 разработчики добавили еще один параметр "РаспознатьАдрес", но далеко не все конфигурации используют последние релизы БСП, поэтому рассмотрим более общий пример.
В версии БСП 3.1.9 процедура добавления контактной информации имеет 5 параметров.
УправлениеКонтактнойИнформацией.ДобавитьКонтактнуюИнформацию(СсылкаИлиОбъект, ЗначениеИлиПредставление, ВидКонтактнойИнформации, Дата, Замещать)
Пояснения к параметрам:
СсылкаИлиОбъект — элемент, которому мы добавляем контакт. Сюда можно передать либо Ссылку, либо сам Объект справочника/документа.
Важный нюанс: если передать Ссылку, БСП «под капотом» сама получит из нее объект, добавит контакты и сразу же запишет его в базу. Если же передать Объект (например, полученный через ПолучитьОбъект()), контакт просто добавится в табличную часть в оперативной памяти, и для сохранения изменений вам нужно будет вызвать Объект.Записать() самостоятельно.- ЗначениеИлиПредставление — непосредственно сами контактные данные в виде строки. Сюда можно передать как обычный текст (например, простой номер телефона "8 (999) 123-45-67" или адрес в свободной форме), так и уже сформированную, структурированную строку в формате JSON (или XML для старых форматов XDTO).
- ВидКонтактнойИнформации — ссылка на элемент справочника ВидыКонтактнойИнформации. Указывает системе, что именно мы сейчас загружаем (например, «Юридический адрес», «Телефон пользователя», «Личный Email» и т.д.).
- Дата — дата, с которой этот контакт начинает действовать. Параметр нужен только для тех видов контактной информации, у которых в настройках включено ведение истории изменений (часто используется в зарплатных конфигурациях для адресов физлиц). Если историю вести не нужно или дата неизвестна, можно ничего не передавать — система автоматически подставит текущую дату сеанса.
Замещать — флаг (тип Булево), который отвечает за поведение при совпадении видов КИ.
Если передать Истина (по умолчанию), БСП найдет старый контакт этого вида и перезапишет его вашими новыми данными.
Если передать Ложь, метод попытается добавить данные новой строкой (чтобы у объекта стало, например, два рабочих телефона). Но будьте внимательны: если в настройках самого вида КИ запрещено добавление нескольких значений, а старый контакт уже есть, метод просто проигнорирует вашу новую запись.
Практический пример: добавляем Email, Телефон и Адрес пользователю
Напишем процедуру, которая принимает ссылку на пользователя, строку с почтой и строку с телефоном, и корректно записывает их через API БСП.
&НаСервере Процедура ЗаполнитьКонтактыПользователя(СсылкаНаПользователя, ПолеТелефон, ПолеЕмейл) Экспорт ОбъектПользователь = СсылкаНаПользователя.ПолучитьОбъект(); // Имена предопределенных данных могут отличаться в зависимости от конфигурации ВидКИ_Email = Справочники.ВидыКонтактнойИнформации.EmailПользователя; ВидКИ_Телефон = Справочники.ВидыКонтактнойИнформации.ТелефонПользователя; // Предполагается, что такой вид КИ в базе уже создан ВидКИ_Адрес = Справочники.ВидыКонтактнойИнформации.НайтиПоНаименованию("Адрес пользователя"); Если ЗначениеЗаполнено(ПолеЕмейл) Тогда УправлениеКонтактнойИнформацией.ДобавитьКонтактнуюИнформацию( ОбъектПользователь, ПолеЕмейл, ВидКИ_Email, Неопределено, // Дата (история не ведется) Истина // Перезаписываем старый email, если он был ); КонецЕсли; Если ЗначениеЗаполнено(ПолеТелефон) Тогда УправлениеКонтактнойИнформацией.ДобавитьКонтактнуюИнформацию(ОбъектПользователь, ПолеТелефон, ВидКИ_Телефон, Неопределено, Истина); КонецЕсли; Если ЗначениеЗаполнено(ПолеАдрес) Тогда УправлениеКонтактнойИнформацией.ДобавитьКонтактнуюИнформацию(ОбъектПользователь, ПолеАдрес, ВидКИ_Адрес, Неопределено, Истина); КонецЕсли; ОбъектПользователь.Записать(); КонецПроцедуры
Современные версии БСП могут корректно распознавать поля по представлению, если оно записано в верном формате. Например, если мы передадим представление адреса строкой с индексом, городом, улицей и домом, которые есть в классификаторе, БСП корректно выделит эти поля.
Но может случиться и так, что поля будут распознаны неверно, например в случае составных названий улиц, муниципальных районов и т.п.
Для этого в сложных случаях следует явно формировать JSON представление с нужными полями, и уже его записывать. В примере ниже рассмотрено заполнение только нескольких полей адреса, на самом деле их значительно больше - см. описание метода ПоляАдреса().
// 1. Создаем структуру полей адреса ПоляАдреса = РаботаСАдресамиКлиентСервер.ПоляАдреса(); ПоляАдреса.Индекс = "119049"; ПоляАдреса.Регион = "Город Москва"; ПоляАдреса.Улица = "ул Крымский Вал"; ПоляАдреса.ТипАдреса = РаботаСАдресамиКлиентСервер.МуниципальныйАдрес(); ПоляАдреса.Здание.Номер = "91"; // 2. Преобразуем структуру в JSON-формат БСП JSONАдреса = РаботаСАдресами.ПоляАдресаВJSON(ПоляАдреса); // 3. Передаем JSON вместо строки УправлениеКонтактнойИнформацией.ДобавитьКонтактнуюИнформацию(ОбъектПользователь, JSONАдреса, ВидКИ_Адрес, Неопределено, Истина);
Плохие советы
На просторах интернета можно встретить множество статей, где кочует одна и та же информация - запись КИ через метод ЗаписатьКонтактнуюИнформацию, а также получение XML представления через методы
УправлениеКонтактнойИнформациейСлужебный.КонтактнаяИнформацияXDTOПоПредставлению и УправлениеКонтактнойИнформациейСлужебный.КонтактнаяИнформацияXDTOВXML.
Это устаревший подход, который содержит сразу три ловушки.
Первая - мы нарушаем стандарты разработки на БСП, используя служебные модули. На то они и служебные, что не предназначены для прямого использования.
Вторая - нам придется вручную контролировать, есть ли строка с нужным видом КИ в табличной части, удалять ее, и заменять новой.
И третья ловушка - нам придется написать достаточно много вспомогательного кода, получить xml представление, и обязательно записать объект.
А стандартный подход предполагает, что мы можем передать хоть объект, хоть ссылку, и БСП сама запишет объект по ссылке, сама разберет представление, сама обеспечит обновление существующих строк - в общем, сильно облегчит нам жизнь.
Чувствуете, что застряли в основах 1С?
Информация в интернете кажется обрывочной, а на решение простых задач уходят часы? Вы не одиноки. Я запустил Клуб для 1С разработчиков Alexcode.PRO. Внутри - продвинутые статьи, видео, материалы для скачивания, закрытый чат для резидентов и возможность влиять на контент.