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

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

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

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

1. У панелі навігації, виберіть робочий стіл Студія 1.

2. Виберіть групу ярликів Інтеграція 2, а потім виберіть групу ярликів Обробка пошти 3.

3. Виберіть ярлик Джерела електронної пошти 4.

4. У панелі інструментів, виберіть + 5.

   

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. Тоді в полі Пароль мають бути введені дані саме від цього налаштованого доступу. Тобто, логін та пароль від самої скриньки не приймаються.
Опис	Додайте короткий опис призначення цього поштового облікового запису для зручності адміністрування.

Примітка:

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

6. Виберіть кнопку Перевірити, що перевірити чи ви ввели правильні дані вашої скриньки.

   

7. Виберіть кнопку Далі.

   

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

   

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

Примітка:

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

9. Виберіть кнопку Далі.

   

10. Установіть прапорець Видаляти листи, що не відповідають жодному з правил 1, якщо бажаєте видаляти листи, які не відповідають жодному з правил фільтрування.

11. В полі Рівень журналювання 2 виберіть які саме типи даних ви бажаєте записувати в журнал поштових операцій:

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

    Додаткові повідомлення для журналювання можна налаштувати в серверному скрипті правил обробки електронної пошти.

    

12. Виберіть кнопку Додати.

    

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

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

1. У панелі навігації, виберіть робочий стіл Студія 1.

2. Виберіть групу ярликів Інтеграція 2, а потім виберіть групу ярликів Обробка пошти 3.

3. Виберіть ярлик Правила електронної пошти 4.

4. У панелі інструментів, виберіть + 5.

   

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

   

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

Примітка:

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

6. Перейдіть у вкладку Фільтри 1.

7. Заповніть поля 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

Примітка:

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

8. Перейдіть у вкладку Дії 1, а потім виберіть Додати дію 2.

   

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

   

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

Примітка:

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

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

    

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

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

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)
      )
    }
  })
  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. У панелі навігації, виберіть робочий стіл Студія 1.

2. Виберіть групу ярликів Інтеграція 2, а потім виберіть групу ярликів Обробка пошти 3.

3. Виберіть ярлик Отримані листи 4.

   

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

• Оброблений — лист який був успішно оброблений згідно з налаштованими правилами обробки

• Відфільтрований — лист який був відфільтрований за допомогою встановлених фільтрів, але жодної дії до нього не було застосовано.

• Помилка — лист, під час обробки якого виникла помилка. Це може бути пов'язано з неправильними налаштуваннями правил, проблемами з форматом листа або технічними збоями.

• Очікує — лист знаходиться в черзі на обробку. Статус з'являється для листів, які були отримані, але ще не пройшли через всі етапи обробки.

• Скасований — обробка листа була скасована вручну.

  

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

1. У панелі навігації, виберіть робочий стіл Студія 1.

2. Виберіть групу ярликів Інтеграція 2, а потім виберіть групу ярликів Обробка пошти 3.

3. Виберіть ярлик Журнал поштових операцій 4.

   

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