Начало работы с Email

В этом разделе представлен минимальный пример использования дополнения Email Sending. Цель - создать ленту новостей для пользователей приложения. Такая лента может использоваться для отправки объявлений, обновлений, уведомлений, статистики использования и другой связанной информации по электронной почте.

Чтобы следовать инструкциям, создайте новый проект Jmix и установите дополнение.

Создание сущности и экранов

Сначала создайте сущность для хранения новостных записей, а также простые экраны CRUD для управления ими. Следуйте инструкциям ниже:

  1. Создайте сущность NewsItem со следующими атрибутами:

    • date типа LocalDate.

    • subject типа String.

    • content типа String с неограниченной длиной.

  2. Создайте экраны списка и деталей для этой сущности.

  3. Откройте экран списка и добавьте новую кнопку, привязав ее к действию отправки письма:

    news-item-list-view.xml
    <hbox id="buttonsPanel" classNames="buttons-panel">
    <button id="createButton" action="newsItemsDataGrid.createAction"/>
    <button id="editButton" action="newsItemsDataGrid.editAction"/>
    <button id="removeButton" action="newsItemsDataGrid.removeAction"/>
    <button id="sendEmailButton" action="newsItemsDataGrid.sendEmailAction"/> (1)
    <simplePagination id="pagination" dataLoader="newsItemsDl"/>
</hbox>
<dataGrid id="newsItemsDataGrid"
          width="100%"
          minHeight="20em"
          dataContainer="newsItemsDc"
          columnReorderingAllowed="true">
    <actions>
        <action id="createAction" type="list_create"/>
        <action id="editAction" type="list_edit"/>
        <action id="removeAction" type="list_remove"/>
        <action id="sendEmailAction" type="list_itemTracking" icon="vaadin:envelope" text="Send Email"/> (2)
    </actions>
    <columns resizable="true">
        <column property="date"/>
        <column property="subject"/>
        <column property="content"/>
    </columns>
</dataGrid>
    1 Добавьте новую кнопку.
    2 Добавьте новое действие.

Логика отправки письма

С готовым пользовательским интерфейсом добавьте логику, чтобы сделать его функциональным. Эта логика будет использовать API дополнения.

  1. Настройте обработчик для действия sendEmailAction. В обработчике покажите диалог с вопросом, можно ли поставить новость в очередь на отправку:

    @Autowired
private Dialogs dialogs; (1)

@Subscribe("newsItemsDataGrid.sendEmailAction")
public void onNewsItemsDataGridSendEmailAction(final ActionPerformedEvent event) {
    NewsItem newsItem = newsItemsDataGrid.getSingleSelectedItem();

    dialogs.createOptionDialog()
            .withHeader("Sending email")
            .withText("Emails will be queued for sending. Continue?")
            .withActions(
                    new DialogAction(DialogAction.Type.YES) {
                        @Override
                        public void actionPerform(Component component) {
                            try {
                                sendNewsByEmail(newsItem);
                            } catch (IOException e) {
                                log.error("Error sending email");
                                notifications.create("Error sending email").show();
                            }
                        }
                    },
                    new DialogAction(DialogAction.Type.NO)
            )
            .open();
}
    1 Инжектируйте объект io.jmix.flowui.Dialogs в класс контроллера.

  2. Реализуйте метод sendNewsByEmail().

    @Autowired
private Emailer emailer; (1)

@Autowired
private Resources resources; (2)

private void sendNewsByEmail(NewsItem newsItem) throws IOException {
    InputStream resourceAsStream = resources.getResourceAsStream("/META-INF/resources/icons/icon.png"); (3)
    byte[] bytes = IOUtils.toByteArray(resourceAsStream);
    EmailAttachment emailAttachment = new EmailAttachment(bytes, "logo.png", "logoId"); (4)

    final EmailInfo emailInfo = EmailInfoBuilder.create() (5)
            .setAddresses("john.doe@company.com,jane.doe@company.com")
            .setSubject(newsItem.getSubject())
            .setFrom(null) (6)
            .setBodyContentType("text/plain; charset=UTF-8")
            .setBody(newsItem.getContent())
            .setAttachments(emailAttachment)
            .setImportant(false)
            .build();
    emailer.sendEmailAsync(emailInfo); (7)
}
    1 Инжектируйте интерфейс io.jmix.email.Emailer.
    2 Инжектируйте интерфейс io.jmix.core.Resources.
    3 Для демонстрации добавления вложения мы будем использовать файл значка приложения.
    4 Создайте объект io.jmix.email.EmailAttachment.
    5 Создайте объект io.jmix.email.EmailInfo с помощью io.jmix.email.EmailInfoBuilder.
    6 Адрес from будет взят из свойства jmix.email.from-address.
    7 Отправьте письмо асинхронно (в фоновом режиме).

Настройка параметров SMTP-сервера

Используйте свойства Spring Boot для почты, чтобы определить параметры отправки писем, такие как протокол, хост, порт и другие, в файле application.properties. Актуальные значения уточните у вашего системного администратора или поставщика почтовых услуг.

Если ваш SMTP-сервер принимает подключения без аутентификации на стандартном порту 25 (например, внутренний почтовый релей), достаточно указать хост сервера и адрес отправителя:

spring.mail.host=smtp.company.com
jmix.email.from-address=info@company.com

Если ваш почтовый сервер использует базовую аутентификацию по имени пользователя и паролю, укажите также учетные данные и параметры подключения. Например:

spring.mail.host=smtp.company.com
spring.mail.port=587
spring.mail.protocol=smtp
spring.mail.username=username
spring.mail.password=password
spring.mail.properties.mail.smtp.auth=true
spring.mail.properties.mail.smtp.starttls.enable=true
Многие почтовые провайдеры поддерживают только авторизацию на основе токена OAuth 2.0 или отказываются от базовой аутентификации. Если ваш провайдер — Google или Microsoft, следуйте инструкциям в разделе Настройка OAuth для Google и Microsoft.

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

Запустите приложение, откройте экран News items. Нажмите Create, чтобы создать новостную запись. После сохранения и возврата к предыдущему экрану выберите вашу запись и нажмите Send Email. Появится диалог подтверждения - нажмите Yes, чтобы продолжить.

confirmation

Перейдите в экран Email → Email History. Запись со статусом Queue указывает на то, что письмо ожидает отправки. Детали письма будут отображены справа при его выборе.

email history

Чтобы отправить письмо из пользовательского интерфейса, выберите его из списка и нажмите Resend email. Вы можете изменить или добавить получателей перед отправкой. Как только письмо будет отправлено, статус изменится на Sent.

Для регулярной отправки писем из очереди или отправки по конкретному расписанию настройте Планировщик Quartz.
resend