Настройка и использование библиотеки «Рассылки и уведомления»

Описание библиотеки

Предназначена для информационных рассылок и уведомлений о прикладных событиях внешних (относительно приложения) получателей.

В библиотеке поддерживаются следующие основные функции:

создание и редактирование шаблонов сообщений;
загрузка готовых html-шаблонов для дизайна макетов;
создание сообщений по событию;
создание сообщений по рассылке;
графический интерфейс для шаблонов сообщений.

Предварительные требования

«1С:Исполнитель» версии 5.x.

Загрузка библиотеки

По ссылке

Вы можете скачать актуальную версию проекта библиотеки по ссылке.

Из шаблона в панели управления

Для знакомства с основными возможностями библиотеки и концепциями технологии «1С:Исполнитель» вы можете использовать демо-приложение, которое представляет собой пример работы данной библиотеки и ее использования с другими библиотеками.

Данное приложение создано исключительно в демонстрационных целях. Оно не является законченным прикладным решением и не предназначено для автоматизации настоящих бизнес-процессов.

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

Откройте панель управления.
На вкладке Приложения нажмите + Новое приложение.
В открывшемся окне выберите Из проекта ⟶ Новый проект.
В выпадающем меню Шаблон проекта выберите пункт Проект с библиотеками. Заполните оставшиеся поля: укажите представление, имя и версию проекта, задайте имя приложения. Включите режим разработки для создаваемого приложения, выберите тип СУБД и нажмите Создать.

Когда приложение будет создано, оно появится в общем списке приложений. Для запуска приложения кликните по ссылке в колонке URL. Если вы хотите ознакомиться со структурой и содержимым проекта, нажмите Разработать, чтобы открыть проект в среде разработки.

Встраивание библиотеки в проект приложения

Перейдите к описанию проекта и в свойстве Библиотеки добавьте новый элемент РассылкиИУведомления.
В модуле проекта добавьте код инициализации библиотеки:
```
импорт e1c::РассылкиИУведомления::Основное

@ОбновлениеПроекта(Ид = "НаВерсиюА-А-А-А", Номер = 1)
метод НаВерсиюА-А-А-А()
    e1c::РассылкиИУведомления::Основное::РассылкиИУведомленияПИ.Инициализировать()
;
```
Метод инициализации библиотеки необходимо вызывать при переходе на каждую версию проекта, если в ней:
- добавляются или меняются описания поставляемых объектов:
  - МакетыОформления,
  - ШаблоныСообщений,
  - ПравилаЗаполненияПолучателей,
  - ГруппыПодписок,
  - СобытияСозданияСообщений.
- добавляются новые реализации контрактов:

Реализация контрактов

Добавьте реализацию указанных ниже контрактов.

ОснованияСообщений

Реализуйте контракт сущности e1c::РассылкиИУведомления::Основное::ОснованияСообщений.

СобытияСозданияСообщений

Реализуйте контракт типа e1c::РассылкиИУведомления::Основное::СобытияСозданияСообщений.

Реализацией контракта являются структуры с обязательным полем Основание:e1c::РассылкиИУведомления::Основное::ОснованияСообщений. С помощью этих структур описывается набор полей, которые можно использовать в шаблонах сообщений при генерации уведомлений. Если поле ссылочного типа, то в шаблонах сообщений можно использовать значения реквизитов этого типа. Каждое поле можно заполнить либо при генерации сообщения, либо перед его отправкой.

Инициализация

Реализуйте контракт сервиса e1c::РассылкиИУведомления::Основное::Инициализация.

Реализация каждого абстрактного метода сервиса должна возвращать массив описаний соответствующих поставляемых объектов:
- МакетыОформления,
- ШаблоныСообщений,
- ПравилаЗаполненияПолучателей,
- ГруппыПодписок,
- СобытияСозданияСообщений.
Описывать поставляемые объекты необязательно, кроме СобытияСозданияСообщений. Если поставляемых объектов такого типа нет, то реализация соответствующего метода будет возвращать пустой массив. Библиотека поставляет некоторые объекты — их можно использовать при описании других поставляемых объектов либо при настройке уведомлений в режиме пользователя:
- МакетыОформления — ИмяПоставляемого = ШаблоныСообщений.ЗаявкаНаРемонтИзменениеСтоимости.ВСтроку(),
- ГруппыПодписок — ИмяПоставляемого = ГруппыПодписок.РассылкиИУведомления_Рассылки.ВСтроку().

При описании поставляемых объектов можно ссылаться на другой поставляемый объект. Для этого каждому поставляемому объекту присваивается ИмяПоставляемого. Например, в описании шаблона сообщения можно сослаться на группу подписок, используя ИмяПоставляемого этой группы подписок:

Реализация метода ШаблоныСообщений() контракта сервиса «Инициализация»
@Реализация @Глобально
метод ШаблоныСообщений(): Массив<Инициализация.ОписаниеШаблонаСообщений>
    знч Результат = новый Массив<Инициализация.ОписаниеШаблонаСообщений>()
    
    знч ОСШ = РассылкиИУведомленияПИ.ОткрывающийСимволШаблона
    знч ЗСШ = РассылкиИУведомленияПИ.ЗакрывающийСимволШаблона
    
    область
        знч ШаблонСодержимого =
        "Уведомляем, что по заявке на ремонт %{ОСШ}Основание.Номер%{ЗСШ} от %{ОСШ}Основание.Дата%{ЗСШ} стоимость стала %{ОСШ}Основание.Стоимость%{ЗСШ}
            <br>Ранее стоимость была %{ОСШ}СтоимостьБыла%{ЗСШ}
            <br>Общая стоимость всех ваших невыполненных заявок на ремонт %{ОСШ}ОбщаяСтоимостьВсехЗаявок%{ЗСШ}"
        
        знч ШаблонТемы = "Изменилась стоимость по заявке на ремонт №%{ОСШ}Основание.Номер%{ЗСШ}"
        
        знч ТипОтправителя = РассылкиИУведомленияПИ.ОписаниеПоставляемогоКаналаТранспорта(
            РассылкиИУведомленияПИ.ИменаПоставляемыхКаналовТранспорта.ЭлектроннаяПочта).ТипОтправителяСообщений
        
        знч ОписаниеШаблона = новый Инициализация.ОписаниеШаблонаСообщений(
            Наименование     = "Заявка на ремонт: изменение стоимости",
            ИмяПоставляемого = ШаблоныСообщений.ЗаявкаНаРемонтИзменениеСтоимости.ВСтроку(),
            ТипСодержимого = ТипыСодержимогоСообщений.HTML,
            МакетОформления = РассылкиИУведомленияПИ.ИменаПоставляемыхМакетовОформления.РассылкиИУведомления_ПоУмолчанию.ВСтроку(),
            ТипСобытия = ТипыСобытийСозданияСообщений.Уведомление,
            Событие = Тип<СобытиеИзменениеСтоимостиРемонтаПоЗаявке>,
            КаналТранспорта = ТипОтправителя,
            ШаблонСодержимого = ШаблонСодержимого,
            ШаблонТемы = ШаблонТемы,
            ГруппаПодписок = ГруппыПодписок.СобытияЗаявокНаРемонт.ВСтроку(),
            ОтправлятьЧерез = 1м
        )
        
        
        Результат.Добавить(ОписаниеШаблона)
    ;
    
    возврат Результат
;

Необходимо описать все СобытияСозданияСообщений.

В случае отсутствия описания какой-либо реализации контракта типа e1c::РассылкиИУведомления::Основное::СобытияСозданияСообщений при инициализации библиотеки будет выброшено исключение.
Для всех полей структуры (кроме Основание) нужно указать, в какой момент это поле будет заполнено:
- ПриСоздании — заполненная структура будет передана в метод создания сообщений, значения полей будут сериализованы в JSON и сохранены. Типы таких полей должны поддерживать сериализацию в JSON.
- ПередОтправкой — в структуре, реализующей контракт типа e1c::РассылкиИУведомления::Основное::СобытияСозданияСообщений, необходимо реализовать метод ПередОтправкой(). В нем необходимо написать код заполнения полей, для которых в описании отмечено, что эти поля заполняются перед отправкой.

Реализация метода СобытияСозданияСообщений() контракта сервиса «Инициализация»
@Глобально @Реализация
метод СобытияСозданияСообщений(): Соответствие<Тип, Инициализация.ОписаниеСобытийСозданияСообщений>
    знч ОписанияСобытий = новый Соответствие<Тип, Инициализация.ОписаниеСобытийСозданияСообщений>()

    ОписанияСобытий.Вставить(Тип<СобытиеИзменениеСтоимостиРемонтаПоЗаявке>,
        новый Инициализация.ОписаниеСобытийСозданияСообщений("Заявка на ремонт: изменение стоимости", 
                                                            Тип<ЗаявкаНаРемонт.Ссылка>,
                                                            ТипыСобытийСозданияСообщений.Уведомление,
                                                            ГруппыПодписок.СобытияЗаявокНаРемонт.ВСтроку(),
                                                            {"СтоимостьБыла": МоментыЗаполненияПараметровСообщений.ПриСоздании,
                                                            "ОбщаяСтоимостьВсехЗаявок": МоментыЗаполненияПараметровСообщений.ПередОтправкой}))

    возврат ОписанияСобытий
;

Реализация метода ПередОтправкойСообщения() контракта типа «СобытияСозданияСообщений»
импорт e1c::РассылкиИУведомления::Основное

@Глобально @Реализация
метод ПередОтправкойСообщения(Получатель: ПолучателиСообщений.Ссылка): СобытияСозданияСообщений.ДействияССообщением
    знч Запрос = Запрос{
        ВЫБРАТЬ
            СУММА(Стоимость) КАК ОбщаяСтоимостьВсехЗаявок
        ИЗ
            ЗаявкаНаРемонт 
        ГДЕ
            Заявитель == %Получатель
            И Статус == СтатусыЗаявокНаРемонт.Принята
    }
    
    исп РезультатЗапроса = Запрос.Выполнить()
    
    для РезультатЗапросаСтрока из РезультатЗапроса
        если РезультатЗапросаСтрока.ОбщаяСтоимостьВсехЗаявок это Число
            ОбщаяСтоимостьВсехЗаявок = РезультатЗапросаСтрока.ОбщаяСтоимостьВсехЗаявок как Число
        ;
    ;   
    
    возврат СобытияСозданияСообщений.ДействияССообщением.Отправить
;

ПолучателиСообщений

Реализуйте контракт сущности e1c::РассылкиИУведомления::Основное::ПолучателиСообщений.

Информация о получателях сообщений может хранится в разных справочниках, например: Контрагенты, Пользователи, ФизическиеЛица, КонтактныеЛица и т. п. Эти справочники будут реализацией контракта сущности e1c::РассылкиИУведомления::Основное::ПолучателиСообщений.

ПолучателиСообщенийПИ

Реализуйте контракт сервиса e1c::РассылкиИУведомления::Основное::ПолучателиСообщенийПИ.

Для каждой реализации контракта сущности e1c::РассылкиИУведомления::Основное::ПолучателиСообщений необходимо реализовать контракт сервиса e1c::РассылкиИУведомления::Основное::ПолучателиСообщенийПИ, иначе при инициализации библиотеки будет выброшено исключение.

Каждый канал транспорта сообщений использует какой-либо тип контактной информации. В библиотеке реализован только один канал транспорта — электронная почта, поэтому для каждой реализации контракта сущности e1c::РассылкиИУведомления::Основное::ПолучателиСообщений необходимо описать получение адреса электронной почты.

Реализация контракта сервиса «ПолучателиСообщенийПИ»
@Реализация @Глобально
метод ОписанияПолучателейСообщений(Получатели: Массив<ПолучателиСообщений.Ссылка>, Канал: КаналыТранспортаСообщений.Ссылка, ТипКонтактнойИнформации: ТипыКонтактнойИнформации, ГруппаПодписок: ГруппыПодписок.Ссылка?): Соответствие<ПолучателиСообщений.Ссылка, ПолучателиСообщенийПИ.ОписаниеПолучателяСообщения>
    выбор ТипКонтактнойИнформации
        когда ТипыКонтактнойИнформации.АдресЭлектроннойПочты
        
        знч Запрос = Запрос{
            ВЫБРАТЬ
                Ссылка,
                АдресПочты,
                Наименование
            ИЗ
                Контрагенты
            ГДЕ
                Ссылка В (%Получатели)
        }
        
        возврат Запрос
                .Выполнить()
                .ВСоответствие<ПолучателиСообщений.Ссылка, ПолучателиСообщенийПИ.ОписаниеПолучателяСообщения>(
                        (Элемент) -> Элемент.Ссылка,
                        (Элемент) -> новый ПолучателиСообщенийПИ.ОписаниеПолучателяСообщения(
                            Элемент.Наименование, 
                            Элемент.АдресПочты))
        
    иначе
        выбросить новый e1c::РассылкиИУведомления::Общее::Общее.ОшибкаВстраиванияБиблиотеки("Не реализовано получение адреса для типа контактной информации %ТипКонтактнойИнформации для типа %{Тип<Контрагенты>}",
            РассылкиИУведомленияПИ.ИмяБиблиотеки(),
            {Тип<Контрагенты>})
    ;
    возврат {:}
;

@Реализация @Глобально
метод ТипПолучателяСообщений(): Тип<ПолучателиСообщений.Ссылка>
    возврат Тип<Контрагенты.Ссылка>
;

ПроверитьНаличиеКлючаДоступаКРассылкам

Реализуйте контракт сервиса e1c::РассылкиИУведомления::Основное::ПроверитьНаличиеКлючаДоступаКРассылкам.

Все настройки рассылок и уведомлений, которые выполняются в пользовательском режиме, совершаются пользователем с правами администратора, поэтому для доступа к ним настройка прав доступа не требуется.

Рассылки могут добавлять пользователи без прав администратора. Для настройки прав к рассылкам необходимо реализовать контракт сервиса e1c::РассылкиИУведомления::Основное::ПроверитьНаличиеКлючаДоступаКРассылкам.

Реализация контракта сервиса e1c::РассылкиИУведомления::Основное::ПроверитьНаличиеКлючаДоступаКРассылкам
@Глобально @Реализация
метод ПроверитьНаличиеКлючейДоступаКРассылкам(Ключи: ЧитаемыйМассив<КлючДоступаКРассылкам.Объект>, Пользователи: ЧитаемыйМассив<Пользователи.Объект>): ЧитаемоеСоответствие<КлючДоступаКРассылкам.Объект, ЧитаемаяКоллекция<Пользователи.Объект|Пользователи.Ссылка>>
   знч Результат = <КлючДоступаКРассылкам.Объект, Массив<Пользователи.Ссылка>>{:}

   знч ПользователиДляПроверки = Пользователи.Преобразовать(Пользователь -> Пользователь.Ссылка)

   знч Запрос = Запрос{
       ВЫБРАТЬ
           Ссылка
       ИЗ
           Пользователи
       ГДЕ
           Ссылка В (%ПользователиДляПроверки)
           и Администратор
       }

   знч Администраторы: Массив<Пользователи.Ссылка>
   для Строка из Запрос.Выполнить()
       Администраторы.Добавить(Строка.Ссылка)
   ;

   для Ключ из Ключи
       Результат.Вставить(Ключ, Администраторы)
   ;

   возврат Результат
;
`

Канал транспорта сообщений

Вы можете добавить свою реализацию канала транспорта сообщений. Библиотека предоставляет реализацию одного канала транспорта — электронная почта. Если этого достаточно, то ничего больше реализовывать не нужно.

Чтобы создать собственный канал транспорта, нужно реализовать контракт сущности e1c::РассылкиИУведомления::Основное::ОтправителиСообщений и для каждой реализации этого контракта добавить реализацию контракта сервиса e1c::РассылкиИУведомления::Основное::ОписаниеКаналаТранспорта.

Создание сообщений

Добавьте вызовы метода e1c::РассылкиИУведомления::Основное::РассылкиИУведомленияПИ.СоздатьСообщения().

Метод необходимо вызывать тогда, когда происходит событие, по которому предусмотрена отправка уведомлений об этом событии. Генерация сообщений по событиям происходит асинхронно, поэтому вызов метода СоздатьСообщения() не приводит к замедлению выполнения вызывающего кода. Сообщения будут сгенерированы, если по этому событию администратор приложения настроил генерацию уведомлений.

Есть две перегрузки метода:

СоздатьСообщения(Получатель: ПолучателиСообщений.Ссылка, Событие: СобытияСозданияСообщений) — сообщения будут созданы по указанному получателю.
СоздатьСообщения(Событие: СобытияСозданияСообщений) — сообщения будут созданы по всем получателям, которые подписаны на ГруппуПодписок, указанную в ШаблонеСообщений. Связь между ШаблономСообщений и Событием настраивает администратор приложения.

Вызов метода СоздатьСообщения() в обработчике события «ПослеЗаписи» документа «ЗаявкаНаРемонт»
импорт e1c::РассылкиИУведомления::Основное

@Обработчик
метод ПослеЗаписи(До: ЗаявкаНаРемонт.Данные, ПараметрыЗаписи: ЗаявкаНаРемонт.ПараметрыЗаписи)
    если ЭтоНовый()
        или До.Статус != Статус
        выбор Статус
            когда СтатусыЗаявокНаРемонт.Принята
                знч ОписаниеСобытия = новый СобытиеПриемЗаявкиНаРемонт(Основание = Ссылка)
                РассылкиИУведомленияПИ.СоздатьСообщения(Заявитель, ОписаниеСобытия)
            когда СтатусыЗаявокНаРемонт.Выполнена
                знч ОписаниеСобытия = новый СобытиеВыполнениеЗаявкиНаРемонт(Основание = Ссылка)
                РассылкиИУведомленияПИ.СоздатьСообщения(Заявитель, ОписаниеСобытия)
            когда СтатусыЗаявокНаРемонт.Отклонена
                знч ОписаниеСобытия = новый СобытиеОтклонениеЗаявкиНаРемонт(Основание = Ссылка)
                РассылкиИУведомленияПИ.СоздатьСообщения(Заявитель, ОписаниеСобытия)             
        ;
    ;
    
    если не ЭтоНовый()
        если До.Стоимость != Стоимость
            знч ОписаниеСобытия = новый СобытиеИзменениеСтоимостиРемонтаПоЗаявке(Основание = Ссылка,
                                                                                СтоимостьБыла = До.Стоимость)
            РассылкиИУведомленияПИ.СоздатьСообщения(Заявитель, ОписаниеСобытия)
        ;
    ;
;

Доработка пользовательского интерфейса

В формах объектов, реализующих контракт сущности e1c::РассылкиИУведомления::Основное::ОснованияСообщений можно добавить команды Подписаться и Подписчики.

В форме импортируйте пространство имен e1c::РассылкиИУведомления::Основное.
В раздел ДополнительныеКоманды формы объекта добавьте ФрагментКомандногоИнтерфейса.

В компонент ФрагментКомандногоИнтерфейса добавьте новый элемент вида Вычисляемое выражение и в поле Выражение впишите вызов метода.

РассылкиИУведомленияПИ.ФрагментКомандногоИнтерфейсаПодписки(Получатель: ПолучателиСообщений.Ссылка?,
                                                            Основание: ОснованияСообщений.Ссылка?,
                                                            ЭтоНовый: Булево,
                                                            Вид: ВидФрагментаКомандногоИнтерфейсаПодписки)

Пример вызова метода ФрагментКомандногоИнтерфейсаПодписки()
# ...
ДополнительныеКоманды:
    Тип: ФрагментКомандногоИнтерфейса<Команда>
    Элементы:
        - =РассылкиИУведомленияПИ.ФрагментКомандногоИнтерфейсаПодписки(
                Объект.Заявитель,
                Объект.Ссылка,
                ЭтоНовый(),
                РассылкиИУведомленияПИ.ВидФрагментаКомандногоИнтерфейсаПодписки.ВсеКоманды)
# ...

Добавьте команду доступа к списку рассылок.
- Добавьте компонент интерфейса ФрагментКомандногоИнтерфейса и импортируйте в нем пространство имен e1c::РассылкиИУведомления::Основное.
- Добавьте новый элемент вида Вычисляемое выражение и в поле Выражение впишите команду ОткрытьРассылки.
Доступ к настройкам библиотеки в пользовательском интерфейсе реализован через фрагмент командного интерфейса e1c::РассылкиИУведомления::Основное::НастройкиИАдминистрирование.
Добавьте компонент интерфейса e1c::РассылкиИУведомления::Основное::ОснованияУведомленийПанель в форму объекта каждой реализации контракта сущности e1c::РассылкиИУведомления::Основное::ПолучателиСообщений.
- Добавьте компонент типа e1c::РассылкиИУведомления::Основное::ОснованияУведомленийПанель.
- В обработчике события ПослеЧтения вызовите метод Заполнить().
```
@Обработчик
метод ПослеЧтения()
    Компоненты.ОснованияУведомленийПанель.Заполнить(Объект.Ссылка)
;
```

Программный интерфейс библиотеки

Библиотека в модуле e1c::РассылкиИУведомления::Основное::РассылкиИУведомленияПИ помимо описанных выше методов предоставляет следующие методы:

Метод	Описание
`ОтменитьОтправкуСообщений(Получатель: ПолучателиСообщений.Ссылка?, Событие: СобытияСозданияСообщений)`	Отменяет отправку сообщений для получателя по событию.
`ОтменитьОтправкуСообщений(Событие: СобытияСозданияСообщений)`	Отменяет отправку сообщений для получателя по всем событиям.
`Подписаться(Получатель: ПолучателиСообщений.Ссылка, Основание: ОснованияСообщений.Ссылка)`	Вычисляет по настройкам шаблонов сообщений, в каких группах подписок может участвовать основание, и подписывает получателя на все эти группы подписок по этому конкретному основанию.
`Подписаться(Получатель: ПолучателиСообщений.Ссылка, ГруппаПодписок: ГруппыПодписок.Ссылка)`	Подписывает получателя на группу подписок.
`Отписаться(Получатель: ПолучателиСообщений.Ссылка, Основание: ОснованияСообщений.Ссылка)`	Вычисляет по настройкам шаблонов сообщений, в каких группах подписок может участвовать основание, и отписывает получателя от всех уведомлений по этому основанию.
`Отписаться(Получатель: ПолучателиСообщений.Ссылка, ГруппаПодписок: ГруппыПодписок.Ссылка)`	Отписывает получателя от группы подписок.
`Подписчики(Основание: ОснованияСообщений.Ссылка): Массив<ПолучателиСообщений.Ссылка>?`	Возвращает всех получателей, которые подписаны на события по конкретному основанию.
`Подписан(Получатель: ПолучателиСообщений.Ссылка, Основание: ОснованияСообщений.Ссылка): Булево`	Возвращает признак, что получатель подписан на события по конкретному основанию.
`ИзменитьПодписку(Получатель: ПолучателиСообщений.Ссылка, Основание: ОснованияСообщений.Ссылка): Булево`	Если получатель подписан на события по конкретному основанию, то отписывает его, и наоборот. Возвращает состояние подписки после выполнения операции.
`ОснованияПодписок(ПолучательСообщений: ПолучателиСообщений.Ссылка): Массив<ОснованияСообщений.Ссылка>`	Возвращает массив оснований сообщений, на события которых подписаны указанные получатели.

Настройка и использование библиотеки «Рассылки и уведомления»

Описание библиотеки​

Предварительные требования​

Загрузка библиотеки​

По ссылке​

Из шаблона в панели управления​

Встраивание библиотеки в проект приложения​

Реализация контрактов​

ОснованияСообщений​

СобытияСозданияСообщений​

Инициализация​

ПолучателиСообщений​

ПолучателиСообщенийПИ​

ПроверитьНаличиеКлючаДоступаКРассылкам​

Канал транспорта сообщений​

Создание сообщений​

Доработка пользовательского интерфейса​

Программный интерфейс библиотеки​

См. также​