Обработка входящей почты

Обработка электронных писем происходит с помощью Действий для входящей почты (sys_email_inbound_action). Например, если в теме входящего письма электронной почты содержится слово "Инцидент", система создает запись об инциденте.

Действия для входящей почты аналогичны бизнес-правилам в использовании скриптов и условий, которые выполняют действия над целевой таблицей. Электронные письма проверяются действиями для входящей почты на соответствие определенным условиям и на наличие некоторых признаков, которые связывают электронное письмо с задачей. Если условия соблюдены, обработка входящей электронной почты выполняет предварительно настроенные действия. Существует два типа действий:

• Выполнить действие: запускает указанный скрипт.
• Ответное письмо: отправляет ответное электронное письмо.

В отличие от правил уведомлений, действия для входящей почты позволяют пользователю взаимодействовать с записями в системе.

Например, при обработке инцидента в статусе Требуются уточнения, система должна вставлять текст электронного письма с ответом заявителя в поле Беседа в ленте активности. Для этого создается действие для входящей почты, условием для срабатывания которого является наличие определенного текста в теме и совпадение номера задачи с номером в записи об инциденте.

внимание

Для обработки входящей электронной почты настройте учетную запись электронной почты по умолчанию. Подробнее читайте в статье Почтовый аккаунт.

Цепочка обработки писем

Порядок обработки входящего письма определяется следующими параметрами:

• Условия, которым должно соответствовать электронное письмо для выполнения действия.
• Тип действия, выполняемого при получении электронного письма.
• Параметры, управляющие потоком обработки.

Третья группа параметров необходима для организации нескольких действий таким образом, чтобы они проверяли входящее электронное письмо на соответствие условию, определенному в каждом из них, в определенном порядке. Одно входящее электронное письмо может инициировать выполнение одного или нескольких действий подряд или ни одного, в зависимости от значений полей Активно, Порядок и Остановить обработку по завершению в каждом действии, определенном в системе.

Действия для входящих писем обрабатываются начиная с действия с наименьшим Порядком, в соответствии со следующей логикой:

1. Если действие активно (на форме его записи установлен флажок Активно), система начинает проверять полученное письмо по условиям действия.
   • Если действие не активно – система переходит к следующему по Порядку.
2. Электронное письмо проверяется на соответствие условиям для выполнения действия.
   • Если оно не соответствует, система пропускает действие и переходит к проверке следующего действия с шага 1.
3. В зависимости от значения поля Тип действия, выполняется Скрипт или отправляется Ответное письмо.
4. Проверяется флажок Остановить обработку по завершению:
   • Если флажок установлен – обработка письма завершается и все последующие действия в цепочке обработки игнорируются.
   • Если флажок снят – система переходит к следующему действию и повторяет шаги 1–4.
5. Обработка письма завершается, когда система выполняет все активные действия или при выполнении действия с установленным флажком Остановить обработку по завершению.

Процесс обработки писем представлен на схеме ниже:

Настройка обработки входящей почты

1. Перейдите в Системные уведомления → Действия для входящей почты.
2. Нажмите Создать и заполните поля.
3. Нажмите Сохранить или Сохранить и выйти, чтобы применить изменения.

подсказка

Требуемая роль: admin.

Поля формы Действие для входящей почты

Поле	Обязательно	Описание
Наименование	Нет	Укажите название действия.
Тип действия	Нет	Выберите тип действия. Доступные варианты: Выполнить действие – при срабатывании запускается Скрипт. Ответное письмо – при срабатывании на адрес, инициировавший действие, отправляется письмо. Его содержание определяется полем Ответное письмо. Действие с типом Ответное письмо использует почтовый аккаунт по умолчанию для отправки писем, даже если доступно несколько аккаунтов.
Тип сообщения	Нет	Укажите тип сообщения, необходимый для выполнения действия. Доступные опции: Новое – электронное письмо, которое не соответствует критериями типов Ответ и Переадресация. Ответ – электронное письмо, тема которого начинается с одного из специальных префиксов или слов, определяемых системным свойством simple.email.reply_subject_prefix. Переадресация – пересланное электронное письмо, тема которого начинается с одного из специальных префиксов или слов, определяемых системным свойством simple.email.forward_subject_prefix. Все – письма всех типов (новые, ответные или переадресованные письма).
Содержит статус доставки	Нет	Установите флажок, чтобы вызвать действие в ответ на письма со статусом доставки.
Содержит приглашение	Нет	Установите флажок, чтобы вызвать действие в ответ на письма с приглашением.
Описание	Нет	Введите подробное описание действия.
Ответное письмо	Нет	Введите текст ответного письма. Оно отправится на исходный электронный адрес, письмо с которого инициировало действие.
От кого	Да	Укажите пользователя, от лица которого будет выполнен скрипт или отправлено ответное письмо.
Скрипт	Нет	Введите скрипт, который запускает действие. Вы можете использовать все методы классов серверного API.
Активно	Нет	Установите флажок, чтобы активировать запись.
Порядок	Нет	Введите число, чтобы определить порядок обработки действий. Действия обрабатываются в порядке возрастания.
Остановить обработку по завершению	Нет	Установите флажок, чтобы завершить обработку письма после выполнения текущего действия. Все последующие действия (с большим Порядком) игнорируются.

примечание

Доступны следующие объекты:

• email – экземпляр класса SimpleRecord, который обращается к записи из таблицы Электронная почта (sys_email) для обработки. Чтобы получить значения полей записи, используйте точечную нотацию для объекта email.
• event – экземпляр записи таблицы Действия для входящей почты (sys_email_inbound_action).

Пример скрипта Действия для входящей почты

(function runAction(/*SimpleRecord*/ event, /*SimpleRecord*/ email) {
const newTask = new SimpleRecord('task');
newTask.subject = email.subject;
newTask.description = email.body_text;
if (email.blind_carbon_copy) {
    newTask.attention_required = true;
    }
cosnt insertedTaskID = newTask.insert();
}

Пример использования

---

Вам нужно настроить действие, реализующее следующую логику:

• Когда система получает письмо с темой, содержащей ключевое слово "доступ", создается новый инцидент. Он назначается на группу, которая ответственна за безопасность и выдачу доступов к системе и данным.

Создайте действие:

Поле	Значение
Наименование	Создание инцидента (проблемы с доступом)
Тип действия	Выполнить действие
Тип сообщения	Новое
Активно	true
Скрипт	Пример скрипта ниже.

Пример скрипта

(function runAction( /*SimpleRecord*/ event, /*SimpleRecord*/ email) {
 
    ss.importIncludeScript('EmailHelper');
    const helper = new EmailHelper();
 
    const letter = email.subject.match('aсcess'); // Проверка ключевых слов
    if (letter) {
        const incident = new SimpleRecord('itsm_incident');
        incident.subject = email.subject;
        /* Если адрес отправителя зарегистрирован в системе, то в поле Заявитель будет указана ссылка на
        существующую запись пользователя.
        В остальных случаях в поле будет указано Гость*/
        incident.caller = helper.userIDbyEmail(helper.parseSender(email.from));
 
        incident.description = email.body_text;
        incident.state = '-2'; // Зарегистрировано
        incident.contact_type = '20'; // Email
        incident.assignment_group = '162920380313692887'; // Группа безопасности
        incident.impact = '2'; // Средний
        incident.urgency = '2'; // Средний
        const insertedIncidentId = incident.insert();
 
        if (insertedIncidentId != 0) {
            ss.debug(`Email ${email.sys_id} processing result: Incident with ID ${insertedIncidentId}`);
 
            const attach = new SimpleAttachment();
            attach.copy('sys_email', email.sys_id, 'itsm_incident', insertedIncidentId);
            return;
        }
        ss.error(`Inbound Action Failed!\nErrors:` + JSON.stringify(incident.getErrors(), null, 2));
    }
})(event, email);

Регистрация обработки писем

Каждое срабатывание действия регистрируется в Журнале работы скриптов. Чтобы увидеть эти записи, отфильтруйте журнал по следующим критериям:

• Источник равно Inbound Action
• Основной документ содержит 0229fa8a-bcbe-1f11

внимание

Поле Основной документ отвечает за письма, обработанные действием. Введите полный адрес или его часть и используйте операторы условий для точного или неточного условия.

Рекомендации

Парсинг входящей почты возвращает значение адреса для поля От кого записи из таблицы Электронная почта (sys_email) в нижнем регистре.

При поиске пользователя по электронной почте в поле Скрипт не следует использовать оператор равно, так как значение электронной почты можно вводить заглавными буквами. Например, J.Doe@mail.com.

Не рекомендуется

user.get('email', 'j.doe@mail.com');

Также не рекомендуется использовать оператор содержит при поиске пользователя по электронной почте, поскольку поиск найдет пользователя с похожим адресом электронной почты, например, raj.doe@mail.com.

Не рекомендуется

user.get('email', 'like', 'j.doe@mail.com')

В следующем примере показан скрипт с методом userIDbyEmail(), который ищет пользователя по значению электронной почты:

ss.importIncludeScript('EmailHelper');
class MyEmailHelper extends EmailHelper {
    userIDbyEmail(email) {
        const user = new SimpleRecord('user');
        user.addQuery('email', 'startswith', email);
        user.addQuery('email', 'endswith', email);
        user.selectAttributes('sys_id');
        user.setLimit(1);
        user.query();
        if (user.next()) {
            return user.sys_id;
        }
        return this.searchGuest();
    }
}