Aplikace Factorify lze propojit s poštovními účty (IMAP) pro podporu automatického zpracování příchozí/odchozí pošty. Pro kompletní propojení je nutné nastavit odesílání emailů.
¶ Nastavení odesílání emailů
Nejvhodnější je použít jako odesílající server stejný, který se používá ve společnosti v nastavení mailových klientů.
V aplikaci Factorify se nastavuje centrálně jeden odesílací SMTP server, protože sama aplikace může odesílat emaily v zastoupení uživatele bez jeho interakce.
Aby toto mohlo správně fungovat, je třeba provést následující kroky:
- nastavit příslušné parametry v aplikaci Factorify
- nastavit (povolit) odesílání pro aplikaci na SMTP serveru (viz níže příklad postupu pro Google/Microsoft)
¶ Nastavení Factorify
Historickou možností je nastavit následující údaje přímo na serveru v properties souboru. Musí provádět IT správce aplikace.
Novější a univerzálnější možností je nastavit SMTP účty přímo v aplikaci Factorify (ui/settings/smtp-mail-account).
mail.protocol=smtp # smtp protokol
mail.host=smtp-relay.gmail.com # host jméno SMTP serveru
mail.port=587 # port SMTP serveru
mail.smtp.auth=false # je vyžadováno přihlašování ?
mail.smtp.starttls.enable=true # je použito šifrování ?
mail.from=info@factorify.cz # výchozí adresa odesílatele
mail.username= # přihlašovací jméno k serveru
mail.password= # přihlašovací heslo k serveru
Při použití vlastního SMTP který si zprovozníte na vlastním serveru, důrazně doporučujeme použít všechny možnosti pro zabránění zneužití / falešnému označování emailů jako spam. Jedná se převážně o zabezpečení SMTP před zneužitím, nastavení podepisování DKIM, o konfiguraci záznamů SPF/DKIM/DMARC v doméně, atd.
Je třeba povolit odesílání pro aplikace. Musí provádět administrátor Google Workspace.
https://admin.google.com/ac/apps/gmail/routing?hl=cs
V sekci Přenosová služba SMTP zvolte Přidat pravidlo a dialogovém okně vyplňte potřebné údaje. Kombinací parametrů zvolíte potřebnou úrověň bezpečnosti dle vašich potřeb.
Nedoporučujeme nastavit pravidla příliš volně, ale je vhodné minimálně přidat IP adresu serveru, kde běží aplikace Factorify.
Dle návodu
provést krok
Configure an IP Address-based connector to relay email through Microsoft 365 or Office 365
Step-by-step configuration instructions for SMTP relay
¶ Nastavení E-mailového účtu - příjem pošty
Nastavení -> Emailové účty (odkaz /ui/settings/imap-mail-account)
- Název - Zvolte dle libosti, například email
- Člověk - Pro automatické zpracování nevyplňovat. Určeno pro budoucí použití.
- Zakázat - Umožnuje dočasně poštovní chránku "vypnout"
- Zpracovávat zprávy - Pokud je zapnuto, účet (kontrolované složka) se bude periodicky kontrolovat a nové zprávy budou zpracovány. Jinak se jen do logu zapíše informace, pokud kontrolovaná složka obsahuje nové zprávy.
- Stahovat přílohy - například stahování PDF faktur a jejich zpracování pomocí integrace Rossum)
- Sekce Spojení - přístupové údaje k poštovní schránce
- Hostname - adresa serveru
- Port - číslo portu (pro IMAP typicky 143 pro nešifrované nebo STARTTLS spojení, 993 pro SSL spojení)
- Typ zabezpečeného spojení - vyberte typ zabezpečení
- Typ ověření
- Žádný - prevděpodobně využitelné jen ve speciálních případech
- Heslo - pro spojení se použije klasická kombinace jméno/heslo (viz. Přihlašovací údaje)
- Microsoft/Google OAUTH2 - viz níže
- Přihlašovací údaje - zvolit / vytvořit přihlašovací údaje typu E-mailový účet
- Tenant ID / ID klienta - určeno pro typ ověření Microsoft OAUTH2
- Kontrolovaná složka - Název IMAP složky která se má kontrolovat, typicky INBOX pro Doručenou poštu
- Účel - Pro rozlišení účtu při automatickém zpracování.
- např. INVOICES - následně můžete vytvořit BPM proces nad entitou ReceivedEmail, který na základě této hodnoty bude zakládat entity SubmittedDocument pro automatické zpracování příchozích faktur (příloh).
- ROBOT - speciální hodnota, určená pro automatické zpracování odpovědí na emaily odeslané z aplikace Factorify
- Smazat přečtené zprávy starší než ? dnů - Pokud je vyplněno, budou se při kontrole složky mazat přečtené zprávy starší než zadaný počet dnů.
¶ Automatické zpracování v BPM
- Vytvořte emailový účet s vyplněnou hodnotou Účel (viz výše).
- Vytvořte BPM proces na entitě ReceivedEmail
¶ Příklad pro automatické zpracování příloh faktur
var purpose = entity.mailAccount.purpose;
if (entity.attachments.size() < 1) {
return null;
}
if (purpose == 'INVOICES') {
var sd = createNew('SubmittedDocument');
sd.state = findState('SubmittedDocument', 'NEW');
var attNames = [...];
for (var item: entity.attachments) {
var att = createNew('SubmittedDocumentAttachment');
att.attachedFile = item.attachedFile;
sd.attachments.add(att);
attNames.add(item.attachedFile.name);
}
sd.attachmentNames = join(attNames, ', ');
sd.note = `email přijatý od ${entity.mailFrom} (id ${entity.id} )`;
persist(sd);
}
¶ Automatické zpracování odpovědí na emaily z aplikace
V Globálních parametrech do pole Email pro automatické zpracování uveďte email na který se mají zasílat odpovědi na emaily odesílané z aplikace. Pro tento email musí být založený poštovní účet s účelem ROBOT (viz výše).
¶ Agenda Přijatá pošta (Received email)
ui/received-email
Přijaté emaily z poštovních účtů IMAP.
¶ Přihlašovací údaje
ui/settings/person-credentials
- Typ: Emailový účet
- Člověk: nevyplňovat
- Jméno / heslo: Přístupové údaje k poštovní schránce
Někteří poskytovatelé mailových služeb zakazují přístup jen pomocí jména/hesla a vyžadují vícefaktorovou autorizaci / OAUTH2. U takových poskytovatelů jsou různé postupy jak přihlašovací údaje vytvořit. Pro povolení typu ověření jméno / heslo lze většinou u poskytovatele vytvořit pro mailový účet Heslo aplikace.
Je třeba se přihlásit ke Google účtu příslušného emailu a zapnout dvoufaktorovou autorizaci.
Následně se v části Dvoufázové ověření objeví možnost pro vytvoření hesla aplikace.
Zadejte název aplikace (jen pro přehlednost, např. Factorify) a nechte vytvořit heslo (postupujte podle instrukcí).
Vygenerovaný kód zadejte ve Factorify jako heslo v nastavení přihlašovacích údajů. Jako jméno zadejte email daného Google účtu.
Je třeba se přihlásit k Microsoft účtu.
V sekci Zabezpečení -> Rozšířené možnosti zabezpečení lze zapnout dvoustupňové ověřování.
V sekci Hesla aplikací lze vytvořit Nové heslo aplikace.
Vygenerovaný kód zadejte ve Factorify jako heslo v nastavení přihlašovacích údajů. Jako jméno zadejte email daného Microsoft účtu.
¶ Microsoft/Google OAUTH2
Typ ověřování OAUTH2 je určen primárně pro běžné přihlašování uživatelů (lidí). Pro automatizované přihlašování aplikací (služeb) je třeba provést další nastavení na straně poskytovatele.
Obecně se jedná tento postup:
- přihlášení do administrační konzole poskytovatele služeb
- vytvoření aplikace
- přiřazení potřebných oprávnění vytvořené aplikaci
- vytvoření přístupových údajů pro aplikaci
- zadaní přístupových údajů do aplikace Factorify
TODO
- portal.azure.com -> Podnikové aplikace
- vytvořit aplikaci (například "Factorify App")
- aplikaci přiřadit oprávnění API (v registraci aplikací) a Udělit souhlas správce
- Microsoft Graph -> offline_access
- Microsoft Graph -> IMAP.AccessAsUser.All
- Office 365 Exchange Online -> User.Read
- Office 365 Exchange Online -> IMAP.AccessAsApp
- Zpřístupnit rozhraní API
- user_impersonation
- Certifikáty a tajné kódy
- Nový tajný kód klienta (nejde nastavit nekonečná platnost, max 2 roky, je tedy třeba kód před vypršením vždy obnovit).
- Microsoft rozhraní neumožňuje nastavit detailní oprávnění a proto je potřeba provést další nastavení přes PoweShell
<tenantId>,<clientId>,<objectId>jsou údaje z vytvořené aplikace)
# instalace potřebných modulů (Administrátorská práva)
Install-Module -Name ExchangeOnlineManagement
# načtení modulu
Import-module ExchangeOnlineManagement
# připojení a nastavení oprávnění
Connect-ExchangeOnline -Organization <tenantId>
New-ServicePrincipal -AppId <clientId> -ObjectId <objectId> -DisplayName FactorifyApp
# nastavení oprávnění ke schránkce pro aplikaci
# je nutné provést pro každou schránku, ke které se bude přistupovat
Add-MailboxPermission -Identity "email@domena.xy" -User <objectId> -AccessRights FullAccess
V aplikaci Factorify se poté nastaví:
- Typ ověření: Microsoft OAUTH2
- Přístupové údaje: jméno emailový účet schránky, heslo: tajný kód aplikace
- Tenant ID, Client ID
TODO