Book Contents

Book Index

Synchronizace emailů do aktivit v K2

Automatické stahování emailů do aktivit v K2 je nástroj, pomocí kterého dojde k odeslání celého emailu do K2. Tato funkce je dostupná pouze pro použití s Office 365 a s poštovním serverem MS Exchange. Ten lze spárovat s libovolným e-mailovým klientem (nejčastěji MS Outlook). Na jeho základě dojde k vytvoření aktivity s obsahem emailu a propojení aktivity na kontaktní osoby nebo partnery dle odesilatele nebo příjemců emailu. Aktivita je vytvořená bez zásahu uživatele na základě nastavené plánované úlohy pro Synchronizaci emailů. Nástroj se dá využít zejména v zákaznické podpoře, kde dochází k evidenci veškeré komunikace se zákazníkem nebo jako podpora pro obchodníky a marketing, při sledování a vyhodnocování příležitostí apod.

Předpoklady pro zajištění funkčnosti Synchronizace emailů do K2

Služba běží mimo K2, na samostatném linuxovém serveru, a s K2 komunikuje přes K2 API.

Kdo službu instaluje

Linuxový server, Docker kontejner i samotnou službu nastavuje systémový specialista K2. Zvolí nebo vygeneruje také šifrovací klíč pro OAuth tokeny, který je předán zákazníkovi. Klíč pak zákazník zadá v globální konfiguraci na záložce MS Graph API (viz dále).

služba RabbitMQ pro K2 verze 27 a vyšší

RabbitMQ je služba třetí strany. Synchronizace bez ní funguje, ale pokud je synchromizace provozována na verzi 2027 a vyšší, je vhodné ji mít naistalovanou. Služba pak dostává změny konfigurace z K2 okamžitě a nemusí se K2 pravidelně dotazovat.

Jak služba zapadá do architektury K2, popisuje Architektura K2, scénář 6.

Pozn.: Synchronizace z on-premise serveru MS Exchange dál běží přes původní nastavení na záložce MS Exchange API (viz kapitola Záložka MS Exchange API) a není třeba instalovat novou službu.

Nastavení v K2

V zásadě je možné provést dva druhy nastavení dle potřeb zákazníka. Uživatel si může vybrat, které emaily chce do k2 uložit nebo je možné uložit do K2 celou složku z emailu. Podle potřeby se pak provede nastavení v K2.

Ve stromovém menu Marketing/Synchronizace emailů existují dvě funkce, které je třeba nastavit pro automatický import emailů:

Globální nastavení synchronizace emailů

Globální konfiguraci nastavuje administrátor K2 jednou pro celou firmu. Konfigurace je k dispozici ve stromovém menu Marketing / Synchronizace emailů funkcí Globální nastavení synchronizace emailů. Formulář má čtyři záložky: Společné, MS Exchange API, MS Graph API a Google.

pic_8305

Obr.: Globální konfigurace synchromizace mailů - záložka Společné

Záložka Společné

Popis polí:

Typ aktivity přijaté emailové zprávy - Typ aktivity, který vznikne při importu přijaté e-mailové zprávy.

Typ aktivity odeslané emailové zprávy - Typ aktivity, který vznikne při importu odeslané e-mailové zprávy.

Složka pro aktivity - Složka, pod kterou vznikají aktivity z importovaných e-mailů.

Typ dokumentu importovaných příloh - Typ dokumentu, který vznikne při importu příloh z e-mailů. Typ dokumentu musí mít nastavenou archivační složku a vybraný Unikátní přesun, kam se budou přílohy ukládat.

Intervaly (pouze nová emailová služba)

Pozn.: níže zadané hodnoty doporučujeme něměnit

Interval načítání konfigurace službou email-service [s] - Jak často se služba ptá K2 na změny v konfiguracích. S RabbitMQ se nepoužívá, změny přicházejí hned. Výchozí hodnota je 300 s (5 min)

Interval synchronizace e-mailů službou email-service [s] - Jak často služba projde všechny konfigurace a pravidla a spustí synchronizaci. Výchozí hodnota je 300 s (5 min)

Předstih obnovení přístupového tokenu před vypršením [s] - Kolik sekund před vypršením platnosti přístupového tokenu ho služba obnoví. Výchozí hodota je 120 s (2 min)

Záložka MS Exchange API

Tato záložka platí jen pro původní synchronizaci přes Exchange Web Services (EWS), kterou dál používají on-premise servery MS Exchange. Nová e-mailová služba synchronizaci celých konverzací nepodporuje, proto zůstala pole pro konverzace jen tady.

pic_8306

Obr.: Globální konfigurace synchronizace emailů - záložka MS Exchange API

Pokud chce zákazník synchronizovat emaily, musí nejdříve zjistit hodnoty Client Id, Client Secret a Tenant Id. Ty zjistí v Azure Active Directory (https://aad.portal.azure.com/), kam se musí přihlásit administrátor. Ten zde musí zaregistrovat novou aplikaci, která bude mít oprávnění pro používání EWS API a používat "app-only authentizaci". Celý postup je popsán na stránkách: https://learn.microsoft.com/en-us/exchange/client-developer/exchange-web-services/how-to-authenticate-an-ews-application-by-using-oauth.

Pokud by chtěl administrátor limitovat povolení aplikace, která takto má přístup ke všem mailovým schránkám, může tak učinit a povolit přístup k části schránek. Více k tomuto na adrese: https://learn.microsoft.com/en-us/graph/auth-limit-mailbox-access.

Poté, co zadá hodnoty Client Id, Client Secret a Tenant Id mohou jednotliví uživatelé nastavit své účty pro přístup k jejich emailovým schránkám. V Konfiguraci účtů pro synchronizaci emailů nastaví svou emailovou adresu a URL pro připojení k MS Exchange (pro Office 365 je to https://outlook.office365.com/EWS/Exchange.asmx).

Zatržítkem Používat přihlašování pomocí OAUTH nastavíme přihlašování pomocí OAUTH.

Hodnoty do polí OAuth Tenant Id, OAuth Client Id a OAuth Client Secret zajistí administrátor přihlášením do Azure Active Directory.

Do pole Typ aktivity konverzace se nastaví Typ aktivity, který bude vznikat při importu emailové komunikace, tedy více zpráv se stejným předmětem emailu. Pokud synchronizuji jednu emailovou zprávu, všechny předchozí i následné emaily se budou také synchronizovat. K aktivitám, které reprezentují emaily, se udělá jedna nadřízená aktivita, která bude zastřešovat konverzaci a bude mít zadaný uvedený typ.

Záložka MS Graph API

Na této záložce se nastavuje připojení nové služby k Microsoft 365 přes Microsoft Graph. Hodnoty pro skupinu Microsoft získáte v Microsoft Entra viz kapitola Registrace aplikace v Microsoft Entra.

Microsoft 365: jen pracovní účty vaší organizace

Přihlásit se mohou jen pracovní účty vaší organizace v Microsoft 365. Osobní účty Microsoft, například @outlook.com, @hotmail.com nebo @live.com, nefungují. Proto se aplikace v Microsoft Entra registruje jen pro vaši organizaci (kapitola Registrace aplikace v Microsoft Entra, krok 3).

pic_8307

Obr.: Globální konfigurace synchronizace emailů - záložka MS Graph API

Společné pro OAuth2

Používat přihlašování pomocí OAUTH - Nová služba se přihlašuje vždy přes OAuth.

Klíč pro šifrování OAuth tokenů - Musí být shodný s klíčem nastaveným v e-mailové službě. Předá vám ho systémový specialista K2, který službu instaloval.

Port pro přesměrování při přihlášení z desktopu - Pokud port není blokovaný na počítačích, ze kterých se uživatelé přihlašují, pak není důvod hodnotu měnit. Stejný port se zadává do adresy přesměrování v Microsoft Entra (kapitola Registrace aplikace v Microsoft Entra, krok 3) a v Google Cloud (kapitola XY, krok 7). Výchozí hodnota je 51576.

Microsoft

TenantId vlastní firmy v Microsoft Entra - ID vaší organizace v Microsoft Entra. Zjištění hodnoty je popsán v další kapitole Registrace aplikace v Microsoft Entra.

ClientId vlastní aplikační registrace v Microsoft Entra - ID aplikace, kterou pro K2 zaregistrujete v postupu popsaném v další kapitole Registrace aplikace v Microsoft Entra.

ClientSecret přiřazené aplikační registraci v Microsoft Entra - Tajný klíč. Viz kapitola Registrace aplikace v Microsoft Entra.

Záložka Google

Přihlásit se mohou jen pracovní účty vaší organizace v Google Workspace. Osobní účty Google (@gmail.com) nefungují. Proto musí být OAuth consent screen nastavený jako Internal (viz další kapitola).

Tady se nastavuje připojení nové služby k Google Workspace. Skupina Společné pro OAuth2 je stejná jako na záložce MS Graph API. Hodnoty pro skupinu Google získáte v Google Cloud popsané v další kapitole Registrace klienta v Google Cloud.

pic_8308

Obr.: Globální konfigurace synchronizace emailů, záložka Google

ClientId klienta z Google Cloud - ID klienta OAuth, kterého pro K2 vytvoříte v Google Cloud. Zkopírujete ho z části Client ID a Client secret v kapitole Registrace klienta v Google Cloud.

ClientSecret klienta z Google Cloud - Tajný klíč tohoto klienta. Zkopírujete ho z části Client ID a Client secret v kapitole Registrace klienta v Google Cloud.

Book Contents

Book Index

Registrace aplikace v Microsoft Entra

Hodnoty pro skupinu Microsoft získá administrátor Microsoft 365 v Microsoft Entra admin center. Postup stačí udělat jednou pro celou firmu.

Na úvodní stránce Home najdete Tenant ID. Zkopírujte ho do pole TenantId vlastní firmy v Microsoft Entra.

pic_8309

Obr.: Tenant ID na úvodní stránce Microsoft Entra

Založte novou registraci aplikace. V menu Entra ID otevřete App registrations a klikněte na New registration.

pic_8310

Obr.: App registration, tlačítko New registration

Vyplňte registraci

Name - název podle kterého aplikaci poznáte, např. K2 Synchronizace emailů.

Supported account types: Single tenant only - tedy jen účty vaší organizace.

Redirect URI - jako platformu zvolte Web, i když jde o localhost, a zadejte http://localhost:51576/. Tato adresa slouží k přihlášení z desktopového K2. Port musí odpovídat poli Port pro přesměrování při přihlášení z desktopu. Potvrďte tlačítkem Register.

pic_8311

Obr.: Registrace aplikace s adresou přesměrování pro localhost

Zkopírujte ClientId

Na stránce Overview nové aplikace zkopírujte Application (client) ID do pole ClientId vlastní aplikační registrace v Microsoft Entra.

pic_8312

Obr.: Application (client) ID na stránce Overview

Přidejte oprávnění pro Microsoft Graph

Otevřete API permissions a klikněte na Add a permission. Zvolte Microsoft Graph, pak Delegated permissions, zaškrtněte tato oprávnění a potvrďte tlačítkem Add permissions:

Mail.ReadWrite: čtení a úprava pošty uživatele,

offline_access: služba může obnovovat přístup bez nového přihlášení uživatele.

Oprávnění User.Read má registrace od začátku, ponechte ho.

Nakonec klikněte na Grant admin consent for <vaše organizace>. Uživatelé pak nemusí aplikaci schvalovat sami při prvním přihlášení. Pokud vaše organizace uživatelům schvalování aplikací nedovoluje, je tento krok nutný.

pic_8317

Obr.: API permissions s udělenými oprávněními a tlačítkem Grant admin consent

Vytvořte tajný klíč

Otevřete Certificates & secrets a na záložce Client secrets klikněte na New client secret. Zadejte popis, zvolte platnost a potvrďte tlačítkem Add.

pic_8313

Obr.: Certificates & secrets, tlačítko New client secret

Zkopírujte hodnotu tajného klíče

Zkopírujte hodnotu ze sloupce Value, ne Secret ID, do pole ClientSecret přiřazené aplikační registraci v Microsoft Entra. Entra hodnotu ukáže jen hned po vytvoření, později už ji neuvidíte.

Platnost klíče

Tajný klíč má omezenou platnost (sloupec Expires). Před jejím koncem vytvořte nový klíč a zadejte ho do K2. Po vypršení se služba k Microsoft 365 nepřipojí a e-maily se přestanou synchronizovat. K2 na to administrátory upozorní. Jakmile nový klíč do K2 zadáte, synchronizace se obnoví sama. Službu není nutné restartovat.

pic_8314

Obr.: Kopírujte hodnotu Value, ne Secret ID (hodnota klíče je na obrázku skrytá)

Přidejte adresy přesměrování pro webová K2

Otevřete Authentication a přes Add Redirect URI přidejte adresu pro každé webové K2. Typ platformy je Web, adresa má tvar https://<adresa-webového-K2>/Redirect.

Důležité:

Adresy přesměrování musíte přidat pro všechny webové K2, které provozujete, pokud se z nich mají uživatelé přihlašovat.

pic_8315

Obr.: Adresy přesměrování pro localhost a dvě webové K2

Book Contents

Book Index

Registrace klienta v Google Cloud

Hodnoty pro skupinu Google získá administrátor v Google Cloud Console. Postup stačí udělat jednou pro celou firmu. Pracujte v projektu, který pro K2 používáte nebo založíte (na obrázcích Muj projekt). Projekt musí patřit pod organizaci vaší firmy v Google Workspace, jinak ho v kroku 4 nepůjde nastavit jako Internal.

Oprávnění

Na rozdíl od Microsoft Entra se v Google Cloud oprávnění k poště nenastavují. Každý uživatel je udělí sám, když se v K2 poprvé přihlásí ke svému účtu Google.

Otevřete seznam zapmutých API

V menu otevřete APIs and services a zvolte Enabled APIs and services.

Konfigurace emailových účtů pro synchronizaci emailů

V Konfiguraci emailových účtů nastavíme emailový účet, který bude funkce obsluhovat. Nastavit je možné více emailů. Uživatel zadá přístupové údaje na svůj email (jméno a heslo) a stanoví pravidla, podle kterých bude docházet k synchronizaci. Synchronizovat je možné:

Nový účet

Nový účet přidáte tlačítkem Nová položka a volbou typu účtu:

Konfigurace účtu MS Graph API (novější) pro Microsoft 365,

Konfigurace účtu Gmail pro Google Workspace,

Konfigurace účtu MS Exchange API (starší) jen pro on-premise servery MS Exchange.

pic_8335

Obr.: Konfigurace emailových účtů pro synchronizaci emailů – nový účet

Základní údaje a přihlášení

pic_8336

Obr.: Konfigurace účtu MS Graph API - základní údaje

E-mailová adresa - Pracovní e-mailová adresa, kterou bude nástroj obsluhovat.

Kontaktní osoba - Kontaktní osoba slouží pro propojení s K2, kde se bude vyplňovat jako Zodpovědná osoba při vytvoření aktivity.

Volitelná nastavení

Importovat pouze emaily od uložených partnerů/osob - Importovat se budou jen e-maily, jejichž adresát (odesílatel) je uložen v kontaktních osobách.

Ukládat přílohy - Volba pro uložení příloh e-mailu.

Ukládat zprávy ve formátu EML - Celý e-mail se uloží jako příloha EML.

Kategorie pro zprávy, které byly Synchronizované do K2 - Kategorie z e-mailu, kterou se označí e-mailové zprávy, které již byly synchronizovány do K2.

Výběr ze seznamu jen s RabbitMQ (zeleně ohraničené tlačítko z obrázku)

Tlačítko nabídne kategorie přímo z e-mailové schránky. Funguje jen při provozu s RabbitMQ (viz minulá kapitola). Bez RabbitMQ se vepíše název ručně, přesně tak, jak je ve schránce. Totéž platí pro složky a kategorie v pravidlech synchronizace a pro štítky v Gmailu.

Tlačítkem Přihlásit se v prohlížeči se otevře přihlašovací stránka Microsoftu, u účtu Gmail přihlašovací stránka Googlu. Uživatel se přihlásí bezpečně přímo tam, svým pracovním účtem. Heslo zadává jen Microsoftu nebo Googlu, K2 ho nevidí ani neukládá.

U Google Workspace uživatel při prvním přihlášení udělí K2 oprávnění k poště. Pole Platné přihlášení ukazuje, jestli je přihlášení platné.

Účet Gmail

Konfigurace účtu Gmail je stejná jako u Microsoft 365. Jen se místo kategorií používají štítky: štítek pro synchronizované zprávy a pravidlo synchronizace podle štítku.

Základní údaje

V záložce Základní údaje se provede nastavení emailů a přístupových údajů.

pic_5509

Obr.: Konfigurace emailových účtů pro synchronizaci emailů – Základní údaje

Popis polí:

E-mailová adresa

Emailová adresa, kterou bude nástroj obsluhovat.

Kontaktní osoba

Kontaktní osoba slouží pro propojení s K2, kde se bude vyplňovat jako Zodpovědná osoba při vytvoření aktivity.

Uživatelské jméno

Uživatelské jméno pro přístup na Exchange.

Heslo

Heslo pro přístup na Exchange.

URL pro připojení ke službě Exchange

URL adresa emailového serveru, ze kterého má být pošta synchronizována, končící příponou "/ews/exchange.asmx". Pokud je URL adresa zadaná špatně, tak by nemělo být možné se k serveru připojit a plánovaná úloha bude hlásit chybu.

Kategorie pro zprávy, které byly synchronizované do K2

Kategorie z emailu, kterou se označí emailové zprávy, které již byly synchronizovány do K2.

Importovat pouze emaily od uložených partnerů/osob

Importovat se budou jen emaily, jejichž adresát (odesílatel) je uložen v kontaktních osobách.

Ukládat přílohy

Volba pro uložení příloh emailu.

Ukládat zprávy ve formátu EML

Celý email se uloží jako příloha EML.

Nastavení pro Office 365:

Pokud má uživatel zapnuté vícefaktorové ověřování, je nutné, aby v nastavení ( https://account.activedirectory.windowsazure.com/AppPasswords.aspx) přidal novou metodu "Heslo aplikace", kde se mu vygeneruje pro aplikaci heslo, které vícefaktorové ověřování obchází. (Postup je popsaný na https://allthingscloud.info/2019/03/21/iphone-calendar-synchronization-with-office-365/). Nemá-li uživatel vícefaktorové ověřování zapnuté, tak tento krok odpadá.

Pak už je nutné jen správně vyplnit konfiguraci účtů pro synchronizaci:

Pravidla synchronizace

V záložce Pravidla synchronizace uživatel nastavuje, zda se bude synchronizovat celá složka nebo uživatel bude vybírat jen některé emaily. Nové pravidlo se přidá tlačítkem Nová položka a volbou Synchronizace složky nebo Synchronizace podle kategorie.

pic_8337

Obr.: Konfigurace účtu MS Graph API - pravidla synchronizace

Synchronizace podle složky

Při synchronizaci podle složky se vybírá složka z emailu, kterou chceme celou naimportovat do K2.

pic_8338

Obr.: Synchronizace složky

Synchronizovaná složka

Složka z e-mailu, ze které se budou vybírat e-maily k synchronizaci. Bez RabbitMQ je nutné zadat název ručně, u podsložky celou cestu, například Inbox/Zákazníci.

Synchronizovat podložky

Volba pro synchronizaci včetně podsložek v emailu.

Synchronizovat celé konverzace

Volba pro synchronizaci celé konverzace.

Datum poslední synchronizace

Datum a čas, do kterého jsou e-maily ze složky synchronizované. Při další synchronizaci se importují e-maily od tohoto data výše. Při založení pravidla můžete datum zadat a synchronizace pak začne od něj. Když pole necháte prázdné, při první synchronizaci se naimportují všechny e-maily ve složce, od nejstarších. Služba je zpracovává postupně, nejvýš 50 e-mailů z jednoho pravidla v každém kole synchronizace. Po uložení pravidla už datum změnit nejde, dál ho posouvá služba.

Synchronizace podle kategorie

Po výběru synchronizace podle kategorie se zobrazí formulář, kde se zadá Synchronizovaná složka. Po kliku na tečky se zobrazí nabídka složek z emailu. Synchronizují se jen e-maily označené zvolenou kategorií, a to ze všech složek schránky.

pic_8339

Obr.: Synchronizace podle kategorie

Synchronizovaná složka

Uživatel vybere složku z emailu, ze které se budou vybírat emaily k synchronizaci. Po nastavení uživatelského jména a hesla se již budou nabízet nastavené složky přímo ze zadaného emailu.

Jméno synchronizované kategorie

Uživatel zadá kategorii z emailu, kterou chce importovat do K2. Bez RabbitMQ je třeba zadat název ručně.

Pravidlo nemá datum poslední synchronizace, protože kategorii lze přiřadit i starému e-mailu. Po úspěšné synchronizaci služba kategorii z e-mailu odebere, takže se stejný e-mail neimportuje dvakrát. Pokud se import nepovede, kategorie zůstane a e-mail se zkusí znovu v dalším kole. V Gmailu platí totéž pro štítky.

Výběr emailů pro synchronizaci do K2 se provádí přiřazením Kategorie (rozlišení dle barev) danému emailu. Uživatel si může v emailu vytvořit své kategorie. Pravým tlačítkem myši vybere volbu Zařadit do kategorií a potom pravým tlačítkem myši na Všechny kategorie.

pic_5504

Obr.: Zařadit do kategorií v emailu

Stiskem tlačítka „Nová“ se vytvoří nová kategorie v emailu, která se pojmenuje a přiřadí se jí barva. Uživatel může také využít stávající kategorie a jen si ji např. přejmenovat.

pic_5507

Obr.: Barevné kategorie v emailu

Pro ukázku jsem vytvořila Kategorii Do K2 a Synchronizované s K2. Kategorií Do K2 jsem přiřadila emailům, které jsem vybrala k synchronizaci.

pic_5512

Obr.: Pravidla synchronizace

pic_5513

Obr.: Nabídka menu Jméno synchronizované kategorie - Kategorie emailových zpráv

V Gmailu se místo kategorií používají štítky. Nový štítek vytvoříte tlačítkem + vedle nadpisu Labels (Štítky) v levém panelu. E-mailu ho pak přiřadíte ikonou štítku nad otevřenou zprávou.

pic_8340

Obr.: Vytvoření nového štítku v Gmailu

Nastavení plánované úlohy

Aby funkce mohla začít pracovat, je třeba nastavit plánovanou úlohu Synchronizace emailů do K2, která je zařazená mezi Ostatní. V plánované úloze se pak nastaví, v jakém časovém intervalu budou synchronizace probíhat, jestli třeba co 10 minut, nebo jen v noci.

pic_8060

Obr.: Plánovaná úloha pro Synchronizaci emailů do K2

Vytvořená aktivita

Po importu emailů prostřednictvím plánované úlohy vznikne v K2 nová aktivita.

pic_8341

Obr.: Naimportovaná aktivita

Pole aktivity:

Typ aktivity

Dosadí se typ nastavený ve funkci Globální nastavení.

Název

Zapíše se předmět emailu.

Nadř. složka

Zadaná složka z funkce Globálního nastavení.

Datum Od

Datum přijatého/odeslaného emailu.

Datum Do

Datum přijatého/odeslaného emailu (stejné jako datum Od).

Zápis

Obsah emailu.

Kontaktní osoba

Odesílatel/příjemce emailu, pokud má zadaný email v K2 v kontaktních osobách. Pokud se daný email v kontaktních osobách nenajde, pole zůstane prázdné.

Partner

Partner z kontaktní osoby.

Zodpovědná osoba

Majitel emailového účtu.

Pokud má email přílohu a v Konfiguraci účtů máme nastaveno Ukládat přílohy, příloha z emailu se naimportuje do záložky Dokumenty dané aktivity.