Version: 52.0.0

2.10.3. Обробка електронної пошти

Примітка:

Функціонал Обробка електронної пошти доступний лише при встановленні додаткового пакета messaging-mail.

Було впроваджено групу ярликів Обробка пошти для інтеграції платформи з сервісами електронної пошти, для керування листами. Ця група містить наступні ярлики:

Джерела електронної пошти — ярлик, за допомогою якого, ви можете додати вашу електронну скриньку у платформу, для подальшої роботи з її листами.
Правила обробки електронної пошти — ярлик, за допомогою якого, ви можете автоматизувати процес сортування та обробки вхідних листів на основі заданих критеріїв.
Отримані листи — ярлик для перегляду та керування всіма листами, які були отримані через налаштовані джерела електронної пошти.
Журнал поштових операцій — ярлик для відстеження всіх операцій з електронною поштою, включаючи помилки та статуси обробки.

2.10.3.1. Додати джерело електронної пошти

У панелі навігації, виберіть робочий стіл Студія 1.
Виберіть групу ярликів Інтеграція 2, а потім виберіть групу ярликів Обробка пошти 3.
Виберіть ярлик Джерела електронної пошти 4.
У панелі інструментів, виберіть + 5.
Заповніть поля, використовуючи підказки в таблиці нижче.

Поле	Опис
Протокол*	Виберіть протокол для отримання пошти: IMAPS — захищений протокол доступу до електронної пошти, що використовує SSL/TLS шифрування для безпечного з'єднання. IMAP — стандартний протокол доступу до електронної пошти без шифрування. Він має всі функціональні можливості IMAPS, але передача даних відбувається у відкритому вигляді через порт 143, що робить його вразливим для перехоплення. POP3S — захищена версія протоколу POP3 із SSL/TLS шифруванням. POP3 — базова версія протоколу POP3 без шифрування. Для більшості сучасних поштових серверів рекомендується використовувати IMAPS, оскільки він забезпечує найкращий баланс між функціональністю та безпекою.
Сервер*	Введіть URL-адресу сервера вхідної пошти. Ось URL-адреси популярних поштових серверів: Gmail: imap.gmail.com. ⚠️ Увага: gmail скриньку можна підключити лише якщо на ній встановлена двофакторна аутентифікація. Ukr.net: imap.ukr.net Outlook.com: outlook.office365.com
Порт*	Вкажіть порт підключення до сервера. Для протоколу IMAPS, наприклад, введіть номер порту 993.
Повний SSL	Активуйте цю опцію для захищеного з'єднання з поштовим сервером через SSL/TLS. Рекомендується для захисту облікових даних.
Логін*	Введіть електронну адресу або ім'я користувача для авторизації на поштовому сервері. ⚠️ Увага: gmail пошту можливо підключити лише якщо в ній налаштований доступ IMAP/POP3. Тоді в полі Логін мають бути введені дані саме від цього налаштованого доступу. Тобто, логін та пароль від самої скриньки не приймаються.
Пароль*	Введіть пароль доступу до поштової скриньки. ⚠️ Увага: gmail пошту можливо підключити лише якщо в ній налаштований доступ IMAP/POP3. Тоді в полі Пароль мають бути введені дані саме від цього налаштованого доступу. Тобто, логін та пароль від самої скриньки не приймаються.
Опис	Додайте короткий опис призначення цього поштового облікового запису для зручності адміністрування.

Примітка:

Поля позначені символом "*" є обов'язковими до заповнення.

Виберіть кнопку Перевірити, що перевірити чи ви ввели правильні дані вашої скриньки.
Виберіть кнопку Далі.
Заповніть поля, використовуючи підказки в таблиці нижче.

Поле	Опис
Папка для моніторингу*	Виберіть папку у вашої електронної скриньки, в якій ви бажаєте відстежувати нові листи: Custom — власна папка (потрібно вказати назву) Drafts — папка чернеток Inbox — папка вхідних листів (рекомендовано) Sent — папка відправлених листів Spam — папка спаму Trash — папка видалених листів
Дія при отриманні повідомлення*	Виберіть дію, яка виконуватиметься з листами після їх обробки: Видалити з папки — повне видалення листа з поштової скриньки Перемістити до папки — переміщення листа до вказаної папки вашої поштової скриньки Позначити ключовим словом — додавання мітки до листа без його переміщення
Зберігати отримані листи, днів	Введіть число, яке означатиме кількість днів протягом яких листи зберігатимуться в системі. За замовчуванням, листи зберігатимуться в системі та не будуть видалятись.

Примітка:

Поля позначені символом "*" є обов'язковими до заповнення.

Виберіть кнопку Далі.
Установіть прапорець Видаляти листи, що не відповідають жодному з правил 1, якщо бажаєте видаляти листи, які не відповідають жодному з правил фільтрування.
В полі Рівень журналювання 2 виберіть які саме типи даних ви бажаєте записувати в журнал поштових операцій:
- Відлагодження (рекомендований) — записувати в журнал всі типи сповіщень, включно з інформацією про встановлення з'єднання, вибір папки чи отримання листів. Додатково записуватимуться усі повідомлення, які ви додасте в серверному скрипті через logger.debug(), logger.info(), logger.warn() та logger.error().
- Інформація — записувати в журнал лише сповіщення про попередження, помилки та загальну інформацію про статуси обробки пошти. Додатково записуватимуться повідомлення які ви додасте в серверному скрипті через logger.info(), logger.warn() та logger.error().
- Попередження — записувати в журнал лише сповіщення про попередження та помилки обробки пошти. Додатково записуватимуться повідомлення які ви додасте в серверному скрипті через logger.warn() та logger.error().
- Помилка — записувати в журнал лише помилки отримання пошти. Додатково записуватимуться повідомлення які ви додасте в серверному скрипті через logger.error().
Примітка:
Додаткові повідомлення для журналювання можна налаштувати в серверному скрипті правил обробки електронної пошти.
Виберіть кнопку Додати.

Після успішного додавання джерела електронної пошти, система почне автоматично моніторити вказану папку та обробляти нові листи згідно з налаштованими правилами обробки електронної пошти.

2.10.3.2. Створити правило обробки електронної пошти

У панелі навігації, виберіть робочий стіл Студія 1.
Виберіть групу ярликів Інтеграція 2, а потім виберіть групу ярликів Обробка пошти 3.
Виберіть ярлик Правила електронної пошти 4.
У панелі інструментів, виберіть + 5.
Заповніть поля, використовуючи підказки в таблиці нижче.

Поле	Опис
Джерело електронної пошти*	Виберіть джерело електронної пошти (поштову скриньку) з листами якої бажаєте працювати.
Назва*	Введіть зрозумілу назву для правила.
Пріоритет*	Введіть будь-яке ціле число, щоб визначити послідовність виконання даного правила. Це поле є актуальним, якщо для одного джерела електронної пошти ви створили одразу декілька правил. Таким чином, за допомогою поля Пріоритет ви можете встановити послідовність, за якої ці правила застосовуватимуться. Правила з меншим числом виконуються раніше.
Опис	Додайте короткий опис правила.

Примітка:

Поля позначені символом "*" є обов'язковими до заповнення.

Перейдіть у вкладку Фільтри 1.
Заповніть поля 2, використовуючи підказки в таблиці нижче.

Поле	Опис
Інтерпретувати як регулярні вирази	Якщо перемикач не активований, платформа сприйматиме введені в поля дані буквально. Якщо активований, можете використовувати формат регулярних виразів — спеціальний синтаксис JavaScript для компактного запису складних правил пошуку. Приклади: `.*@example\.com` (всі адреси домену), `^support@` (адреси, що починаються з "support@"), `\d{4}` (чотиризначні числа).
Відправник містить	Увімкніть перемикач Відправник містить, якщо бажаєте фільтрувати листи по цьому критерію. А потім, в полі нижче, введіть частину адреси або домену відправника (наприклад, "@company.com" або "support").
Отримувач містить	Увімкніть перемикач Отримувач містить, якщо бажаєте фільтрувати листи по цьому критерію. А потім, в полі нижче, введіть частину адреси отримувача або ключові слова.
Копія містить	Увімкніть перемикач Копія містить, якщо бажаєте фільтрувати листи по цьому критерію. А потім, в полі нижче, введіть частину адреси з поля копії листа.
Тема містить	Увімкніть перемикач Тема містить, якщо бажаєте фільтрувати листи по цьому критерію. А потім, в полі нижче, введіть ключові слова або фрази, які повинні бути присутні в темі листа.
Тіло листа містить	Увімкніть перемикач Тіло листа містить, якщо бажаєте фільтрувати листи по цьому критерію. А потім, в полі нижче, введіть текстові фрагменти для пошуку в змісті повідомлення.
Використати скрипт для фільтрації	Увімкніть перемикач Використати скрипт для фільтрації, якщо бажаєте застосувати користувацький скрипт з більш складною логікою обробки. А потім, в полі нижче, введіть код скрипта. Скрипт має бути у форматі JavaScript, в скрипті доступні всі змінні (дані) листа: `@property \{string\} from` `@property \{string\} to` `@property \{string\|null\} cc` `@property \{string\|null\} subject` `@property \{string\} body` `@property \{string\} bodyText` `@property \{string\} rawContent` `@property \{string\} sentDate` `@property \{Array<\{name: string, contentType: string, data: ArrayBuffer\}>\} attachments`

Примітка:

Якщо жодна умова фільтрації не увімкнена та не налаштована, то дії які ви задасте у наступній вкладці, будуть застосовуватись до усіх листів, які приходитимуть на вказане джерело електронної пошти.
Якщо увімкнено декілька умов, то лист відфільтується лише якщо відповідатиме усім активованим фільтрам. Тобто якщо у вас увімкнено декілька умов, а лист відповідає лише одній.

Перейдіть у вкладку Дії 1, а потім виберіть Додати дію 2.
Заповніть поля 1, використовуючи підказки в таблиці нижче, а потім виберіть кнопку Додати 2.

Поле	Опис
Тип*	Виберіть один з наступних типів Серверний скрипт Виконати дію з електронного листа
Пріоритет*	Введіть будь-яке ціле число, щоб визначити послідовність виконання даної дії. Це поле є актуальним, якщо для одного правила ви створили одразу декілька дій. Таким чином, за допомогою поля Пріоритет ви можете встановити послідовність, за якої ці дії застосовуватимуться. Дії з меншим числом виконуються раніше.
Опис	Додайте короткий опис дії.

Примітка:

Поля позначені символом "*" є обов'язковими до заповнення.

Наступні кроки для типу Серверний скрипт

В полі Серверний скрипт, вставте потрібний серверний скрипт, відповідно до дії, яку ви бажаєте здійснити з відфільтрованими електронними листами. Див. Приклад серверного скрипта для додавання листів в таблицю.

Наступні кроки для типу Виконати дію з електронного листа

Щоб продовжити налаштовувати дії електронних листів див. розділ Налаштувати дії електронних листів.

У панелі інструментів виберіть піктограму Зберегти або Зберегти та закрити.

Приклад серверного скрипта для додавання листів в таблицю

const {App,Repository,DataStore} = require('@unitybase/ub')
module.exports = {
/**
* @param {object} params
* @param {EmailMessage} params.message
* @param {Logger} params.logger
*/
run({message, logger}) {
  const messageID = extractMessageId(message.rawContent)
  logger.debug('messageID: ' + messageID)
  const documentID = extractDocumentId(message.body)
  logger.debug('documentID: ' + documentID)
  if (!documentID) {
    return
  }
  const tableAttrID= UB.Repository('frm_Attribute')
    .attrs('ID')
    .where('code', '=', 'email_table') //set table attribute code
    .selectScalar()

  const collectionAttrID= UB.Repository('frm_Attribute')
    .attrs('ID')
    .where('code', '=', 'ms18') //set collection attribute code
    .selectScalar()
  const FileAttrID= UB.Repository('frm_Attribute')
    .attrs('ID')
    .where('code', '=', 'ms17') //set file attribute code
    .selectScalar()
  const now = new Date();
  const isoString = now.toISOString();
  const ds = DataStore('dfx_DocumentItem')
  const newItemID = ds.generateID()
  const fieldList = ['ID']
  const execParams = {
    ID: newItemID,
    documentID: documentID,
    attrID: tableAttrID,
    attrValues : JSON.stringify({
      "ms01": message.subject, //subject -text
      "LDOC_3784_1": message.from, //from - text
      "ms07": isoString //date and time
    })
  }
  const ubq = {
    entity: 'dfx_DocumentItem',
    fieldList,
    execParams,
    __skipRls: true,
  }
  ds.run('insert', ubq)
  DataStore('dfx_Document').runWithResult('setRichText', {
    execParams: {
      documentID: documentID,
      documentItemID: newItemID,
      attrCode: 'ms19', //rich text attribute code
      value: message.body
    },
    __skipRls: true,
    __skipOptimisticLock: true
  })
  const attachments= message.attachments

  if (attachments.length > 0) {
    for (const attach of attachments) {
      const ds1 = DataStore('dfx_DocumentAttachment')
      const attachmentID = ds1.generateID()
      ds1.insert({
        execParams: {
          ID: attachmentID,
          documentID: documentID,
          attrID: collectionAttrID,
          documentItemID: newItemID,
          original: JSON.stringify(
            App.blobStores.putContent({
              entity: 'dfx_DocumentAttachment',
              attribute: 'original',
              ID: attachmentID,
              fileName: attach.name
            }, attach.data)
          )
        }
      })
    } //end for
  } //end if
  const ds3 = DataStore('dfx_DocumentAttachment')
  const attachmentID = ds3.generateID()
  ds3.insert({
    execParams: {
      ID: attachmentID,
      documentID: documentID,
      attrID: FileAttrID,
      documentItemID: newItemID,
      attachment: JSON.stringify(
        App.blobStores.putContent({
          entity: 'dfx_DocumentAttachment',
          attribute: 'attachment',
          ID: attachmentID,
          fileName: `${messageID}.eml`
        }, message.rawContent)
      )
    }
  })

  /**
   * ВАЖЛИВО: Наступна функція витягує ID документа лише з HTML-тіла листа,
   * якщо воно містить <span style="color:#ffffff">12345</span>.
   * Це залежить від наявності саме такого елемента і стилю (#ffffff).
   * Якщо лист не містить такого <span> або поштовий клієнт змінив/прибрав стилі,
   * функція поверне null і обробка буде пропущена.
   */
  function extractDocumentId(htmlContent) {
    const match =
      htmlContent.match(/<span[^>]*color:\s*#ffffff;?[^>]*>(\d+)<\/span>/i);
    return match ? parseInt(match[1]) : null;
  }

  function extractMessageId(emailContent) {
    const match = emailContent.match(/Message-ID:\s*<([^>]+)>/i);
    return match ? match[1] : null;
  }
}
}

2.10.3.3. Переглянути отримані листи

В ярлику Отримані листи ви можете переглядати оригінальний вміст листа, його статус, а також повʼязані з ним поштові операції.

Щоб переглянути отримані листи:

У панелі навігації, виберіть робочий стіл Студія 1.
Виберіть групу ярликів Інтеграція 2, а потім виберіть групу ярликів Обробка пошти 3.
Виберіть ярлик Отримані листи 4.

В даному ярлику ви побачите список всіх листів, а також їх статуси:

Оброблений — лист який був успішно оброблений згідно з налаштованими правилами обробки
Відфільтрований — лист який був відфільтрований за допомогою встановлених фільтрів, але жодної дії до нього не було застосовано.
Помилка — лист, під час обробки якого виникла помилка. Це може бути пов'язано з неправильними налаштуваннями правил, проблемами з форматом листа або технічними збоями.
Очікує — лист знаходиться в черзі на обробку. Статус з'являється для листів, які були отримані, але ще не пройшли через всі етапи обробки.
Скасований — обробка листа була скасована вручну.

Виберіть потрібний лист, щоб переглянути його оригінальний вміст чи повʼязані з ним поштові операції.

2.10.3.4. Переглянути статус поштових операцій

У панелі навігації, виберіть робочий стіл Студія 1.
Виберіть групу ярликів Інтеграція 2, а потім виберіть групу ярликів Обробка пошти 3.
Виберіть ярлик Журнал поштових операцій 4.

У журналі поштових операцій відображається вся інформація про роботу системи обробки електронної пошти, включаючи успішні операції, попередження та помилки.

2.10.3.5. Дії електронних листів

За допомогою дій електронних листів ви можете налаштувати виконання завдання користувача за допомогою кнопок дій які ви зможете інтегрувати в електронний лист.

2.10.3.5.1. Налаштувати дії електронних листів

Щоб налаштувати дії електронних листів, виконайте наступні кроки:

Додайте джерело електронної пошти. Після створення, виконайте наступні дії:
1. У панелі інструментів виберіть кнопку Активувати 1.
2. Виберіть кнопку Зробити джерелом обробки дій 2.
Примітка:
Лише одне джерело електронної пошти може бути джерелом обробки дій. Щоб перевірити яке саме джерело є джерелом обробки у вашій системі: Робочий стіл Адміністрування 1 > Група ярликів Налаштування 2 > ярлик Налаштування системи 3 > ключ msg.execAction.replyToAdress 4
Перевірте поле Значення.
Створіть правило обробки електронної пошти. Під час створення правила, виконайте наступні умови:
1. В полі Джерело електронної пошти вкажіть те саме джерело, яке ви створили в кроці 1.
2. Перейдіть у вкладку Дії 1, а потім виберіть Додати дію 2.
3. В полі Тип 1 виберіть Виконати дію з електронного листа, а потім виберіть Додати 2.
4. У панелі інструментів виберіть піктограму Зберегти.
Створіть дії для виконання завдання — створіть дії, які бажаєте відображати на кнопках листа. Наприклад: "Погодити" та "Відхилити".
Створіть форму завдання. Під час створення шаблона, виконайте наступні умови:
1. У вкладці Дії 1 увімкніть ті самі дії, що ви створили у кроці 3 2.
2. У панелі інструментів виберіть піктограму Зберегти 3.
Створіть шаблон електронних листів. Під час створення шаблона, виконайте наступні умови:
1. В полі Тип виберіть Нотифікація завдання процесу.
2. Над полем Тіло листа виберіть + Дія.
3. Виберіть папку Дії для виконання завдання 1, щоб розгорнути її.
4. Зі списку виберіть ті дії, які ви увімкнули в кроці 4 2.
Увага:
- Дії на тілі листа мають збігатись з діями, що ви увімкнули у формі завдання. Якщо на тілі листа буде додана кнопка, дія якої не була увімкнена на формі завдання — така кнопка не працюватиме.
- Для кожної мовної версії шаблону потрібно додати кнопки дій окремо. Якщо ви створили новий переклад, але не додали до нього кнопки дій — ця мовна версія листа не міститиме кнопок жодною мовою.
Примітка:
Локалізація шаблону впливає на мову відображення кнопок дій в електронних листах. Якщо мовою за замовчуванням встановлено англійську, кнопки дій відображатимуться англійською мовою. Користувач отримає електронний лист тією мовою, яка встановлена в його профілі, або мовою за замовчуванням, якщо переклад для його мови недоступний.
Підключіть шаблон електронного листа до завдання користувача.
1. Відкрийте потрібну дефініцію бізнес-процесу.
2. Виберіть завдання користувача за допомогою якого бажаєте надіслати електронний лист 1.
3. В налаштуваннях завдання виберіть + на секцій Сповіщення 2.
4. В полі Призначити з 1 виберіть Шаблон електронного листа.
5. В полі Шаблон електронного листа 2 виберіть зі списку шаблон, який ви створили в кроці 5.
6. У панелі інструментів виберіть піктограму Зберегти.
Підключіть форму завдання до завдання користувача.
1. Виберіть те саме завдання користувача 1.
2. В налаштуваннях завдання розгорніть секцію Форма 2.
3. Виберіть опцію Форма завдання 1.
4. В полі Форма завдання 2 виберіть зі списку форму, яку ви створили в кроці 4.
5. У панелі інструментів виберіть піктограму Зберегти.

Примітки:

Дія задана у кнопці буде успішно виконана за наступних умов:

В системі є користувач з email-адресою як у відправника листа.
Термін дії виконання завдання не минув.
Користувач якому було відправлено лист з дією, має одну з наступних ролей в межах завдання: Потенційний виконавець, Виконавець, Супервізор. Дія виконана користувачем у ролі Спостерігач не буде обробленою.
Завдання користувача має статус Відкрите.

2.10.3.5.2. Змінити термін виконання

Змінити термін для конкретної дії

Щоб налаштувати термін виконання дії, виконайте наступні дії:

Відкрийте шаблон електронного листа в якому налаштовували дії.
В полі Тіло листа виберіть кнопку дії, термін якої бажаєте змінити 1.
В правому вехньому куті над кнопкою, виберіть Дія: Назва дії 2.
В полі Термін дії (годин) 1 введіть потрібну кількість годин.
У панелі інструментів виберіть піктограму Зберегти 2.

Змінити термін "за замовчуванням" для всієї платформи

Щоб змінити термін на рівні всієї платформи:

У панелі навігації, виберіть робочий стіл Адміністрування 1.
Виберіть групу ярликів Налаштування 2, а потім виберіть ярлик Налаштування системи 3.
Виберіть ключ msg.execAction.defaultOTPExpireHours 4.
В полі Значення 1 введіть бажану кількість годин, а потім виберіть піктограму 2.
В полях мов введіть те саме значення для кожного поля 1, а потім виберіть кнопку Застосувати 2.
У панелі інструментів виберіть піктограму Зберегти.

2.10.3.5.3. Змінити дизайн кнопки

Відкрийте шаблон електронного листа в якому налаштовували дії.
В полі Тіло листа виберіть кнопку дії, дизайн якої бажаєте змінити.
Виберіть вкладку Вигляд 1, а потім виберіть Вихідний код 2.
В полі Вихідний код внесіть потрібні зміни в css стилях 1, а потім виберіть кнопку Гаразд 2.

2.10.3.1. Додати джерело електронної пошти​

2.10.3.2. Створити правило обробки електронної пошти​

Приклад серверного скрипта для додавання листів в таблицю​

2.10.3.3. Переглянути отримані листи​

2.10.3.4. Переглянути статус поштових операцій​

2.10.3.5. Дії електронних листів​

2.10.3.5.1. Налаштувати дії електронних листів​

2.10.3.5.2. Змінити термін виконання​

2.10.3.5.3. Змінити дизайн кнопки​

2.10.3.1. Додати джерело електронної пошти

2.10.3.2. Створити правило обробки електронної пошти

Приклад серверного скрипта для додавання листів в таблицю

2.10.3.3. Переглянути отримані листи

2.10.3.4. Переглянути статус поштових операцій

2.10.3.5. Дії електронних листів

2.10.3.5.1. Налаштувати дії електронних листів

2.10.3.5.2. Змінити термін виконання

2.10.3.5.3. Змінити дизайн кнопки