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.
- Je třeba mít nainstalovaný aplikační server, aby mohla běžet plánovaná úloha.
- Pro funkci výběru Kategorií a složek v nastavení konkrétního emailového účtu je potřeba, aby byla v operačním systému na systému, kde běží K2, zaregistrována dodávaná DLL knihovna, která je součástí instalace K2, včetně lokální instalace. V případě, že tato knihovna zaregistrována není, pokusí se ji K2 sama zaregistrovat. Tato akce bude vyžadovat oprávnění lokálního správce Windows. V případě, že se knihovnu nepodaří zaregistrovat, zobrazí se chybová zpráva. I přesto je ale možné konfiguraci dokončit ručním vyplněním názvu kategorie/složky do příslušného pole.
- Microsoft 365 nebo Google Workspace s firemními e-mailovými účty. Osobní účty podporované nejsou.
- K2 API v2, přes které služba s K2 komunikuje
- Linuxový server, na kterém služba běží v Docker kontejneru
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ů
- Konfigurace účtů pro synchronizaci
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.

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.

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).

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.

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.
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.

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.

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.

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.

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ý.

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.

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.

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.

Obr.: Adresy přesměrování pro localhost a dvě webové K2
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é:
- Podle složky - všechny emaily z uvedené složky se budou importovat do K2.
- Podle kategorie – jen označené emaily danou kategorií (barvou) se budou importovat do K2.
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.

Obr.: Konfigurace emailových účtů pro synchronizaci emailů – nový účet
Základní údaje a přihlášení

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.
V záložce Základní údaje se provede nastavení emailů a přístupových údajů.

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:
- Emailová adresa i uživatelské jméno mají hodnotu emailu, pomocí kterého se uživatel přihlašuje do Office365
- Do hesla se vloží výše vygenerovaná hodnota případně heslo, kterým se uživatel normálně přihlašuje, nemá-li zapnuté vícefaktorové ověřování.
- URL pro připojení ke službě Exchange má hodnotu https://outlook.office.com/EWS/Exchange.asmx
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.

Obr.: Konfigurace účtu MS Graph API - pravidla synchronizace
Při synchronizaci podle složky se vybírá složka z emailu, kterou chceme celou naimportovat do K2.

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. |
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.

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.

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.

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.

Obr.: Pravidla synchronizace

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.

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.

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.

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.