Gmail dla poczty przychodzącej w AMODIT

Artykuł zweryfikowany dla wersji 260331.

Wprowadzenie

Ten artykuł jest dla administratora, który chce skonfigurować Gmail jako źródło wiadomości dla poczty przychodzącej w AMODIT.

Materiał obejmuje scenariusz, w którym:

AMODIT odbiera wiadomości z konta Gmail albo Google Workspace,
wiadomości trafiają do procesu,
system może na ich podstawie zakładać nowe sprawy albo przetwarzać je zgodnie z ustawieniami procesu.

W tym wariancie autoryzacja odbywa się przez OAuth, a sam odbiór wiadomości przez IMAP.

Kiedy ten artykuł ma sens

Ten materiał jest właściwy wtedy, gdy:

organizacja korzysta ze skrzynki Gmail albo Google Workspace,
AMODIT ma pobierać wiadomości z tej skrzynki,
skrzynka ma być powiązana z konkretnym procesem,
administrator chce uruchomić odbiór wiadomości bez używania zwykłego hasła użytkownika jako głównego mechanizmu logowania.

Jeżeli szukasz ogólnego opisu poczty przychodzącej albo samych ustawień procesu tworzenia spraw z maila, zacznij od artykułów obszarowych. Ten wpis pokazuje, jak zastosować te mechanizmy konkretnie dla Gmail.

Wymagania wstępne

Zanim zaczniesz, przygotuj:

konto Gmail albo Google Workspace, którego AMODIT ma używać,
uprawnienia administratora do Ustawień systemowych,
dostęp do konfiguracji procesu,
możliwość zalogowania się do Google w oknie OAuth,
jeżeli organizacja używa własnej aplikacji Google:
- client_id,
- client_secret,
- poprawny adres przekierowania https://<adres_AMODIT>/api/oauth/redirect.

Co trzeba ustawić

Konfiguracja Gmail dla poczty przychodzącej obejmuje dwa poziomy:

wspólną konfigurację Google OAuth po stronie systemu,
konfigurację skrzynki Gmail na poziomie procesu.

Oba poziomy muszą być ze sobą zgodne. Ustawienia systemowe decydują o tym, jak AMODIT łączy się z Gmail, a ustawienia procesu określają, z którego konta i folderu system ma czytać wiadomości.

Krok 1. Ustal, czy organizacja używa domyślnej aplikacji Google czy własnej

AMODIT może korzystać z domyślnej konfiguracji Google OAuth albo z własnej aplikacji Google przygotowanej przez organizację.

Własna aplikacja ma sens wtedy, gdy:

polityka bezpieczeństwa wymaga własnej rejestracji aplikacji,
organizacja chce samodzielnie zarządzać zgodami OAuth,
środowisko nie powinno korzystać ze współdzielonej konfiguracji AMODIT.

Jeżeli organizacja używa własnej aplikacji, w AMODIT trzeba uzupełnić parametr GoogleApplicationConfig.

Przykładowy format:

{
  "web": {
    "client_id": ".....",
    "auth_uri": "https://accounts.google.com/o/oauth2/auth",
    "token_uri": "https://accounts.google.com/o/oauth2/token",
    "client_secret": ".....",
    "redirect_uris": [
      "https://twoj-adres-amodit/api/oauth/redirect"
    ]
  }
}

Adres przekierowania wpisany w Google musi być zgodny z rzeczywistym adresem AMODIT używanym przy logowaniu OAuth.

Krok 2. Ustaw wspólny transport przychodzący

W Ustawieniach systemowych, w sekcji Poczta przychodząca, ustaw:

Protocol = IMAP,
Server name or IP = imap.gmail.com,
port zgodny z konfiguracją Gmail,
Use SSL zgodnie z wymaganiami usługi.

Ta kombinacja jest potrzebna po to, aby AMODIT rozpoznał Gmail jako dostawcę OAuth dla poczty przychodzącej.

Krok 3. Powiąż skrzynkę Gmail z procesem

W konfiguracji procesu, w sekcji powiązanej skrzynki mailowej, uzupełnij:

E-mail login adresem Gmail używanym przez proces,
Folder wartością INBOX, jeżeli ten folder ma być czytany przez system.

To ustawienie decyduje o tym, z jakiej skrzynki i z jakiego miejsca AMODIT ma pobierać wiadomości dla tego procesu.

Krok 4. Wygeneruj token OAuth dla procesu

Po ustawieniu IMAP i serwera imap.gmail.com w konfiguracji procesu pojawia się akcja generowania tokenu OAuth.

W tym miejscu:

wpisz login skrzynki Gmail,
użyj akcji generowania tokenu,
zaloguj się w Google na właściwe konto,
zaakceptuj wymagane zgody,
zapisz konfigurację procesu.

Po poprawnym zakończeniu tego kroku token zostaje zapisany w polu hasła skrzynki procesu. W tym scenariuszu pole hasła nie przechowuje zwykłego hasła użytkownika, tylko dane autoryzacji OAuth potrzebne do odbioru wiadomości.

Krok 5. Sprawdź, czy w środowisku jest dostępny parametr GoogleApplicationConfig

W części środowisk wymagany parametr jest już dostępny w UI. W innych trzeba go najpierw dodać technicznie.

Jeżeli środowisko nie ma jeszcze GoogleApplicationConfig, administrator techniczny może dodać go w tabeli parameters.

INSERT INTO parameters (parName, parValue, parGroup, parIndex, parDefaultValue, parType)
VALUES ('GoogleApplicationConfig', '', 'IncomingMail', '15', '', 't');

Ten krok nie jest potrzebny w każdym wdrożeniu, ale warto go sprawdzić, jeśli środowisko nie pokazuje konfiguracji Google OAuth.

Weryfikacja

Po poprawnej konfiguracji:

proces zapisuje dane skrzynki Gmail,
w konfiguracji procesu jest dostępna akcja generowania tokenu OAuth dla imap.gmail.com,
system może pobierać wiadomości z tej skrzynki do procesu.

Typowe problemy

Nie widać akcji generowania tokenu OAuth dla procesu

Najpierw sprawdź:

czy protokół przychodzący jest ustawiony na IMAP,
czy serwer jest ustawiony dokładnie na imap.gmail.com,
czy konfigurujesz skrzynkę na poziomie procesu, a nie tylko na poziomie systemowym.

Po logowaniu Google pojawia się komunikat Refresh token not retrieved!

Najczęściej oznacza to, że konto Gmail ma już zapisane połączenie z inną aplikacją i Google nie zwraca nowego refresh token.

W takiej sytuacji:

zaloguj się na dane konto Google,
przejdź do listy aplikacji z dostępem do konta,
usuń wcześniejsze połączenie dla tej aplikacji,
ponów generowanie tokenu w AMODIT.

Zwykłe hasło użytkownika nie działa

W konfiguracji opisanej w tym artykule autoryzacja odbywa się przez OAuth. Jeżeli organizacja chce korzystać z Gmail w tym wariancie, samo hasło użytkownika nie zastępuje tokenu OAuth.

Organizacja używa własnej aplikacji Google i logowanie nie kończy się poprawnie

Wtedy trzeba sprawdzić zgodność trzech elementów:

danych client_id i client_secret,
adresu przekierowania wpisanego w Google,
rzeczywistego adresu AMODIT używanego przy generowaniu tokenu.

Wynik końcowy

Po wykonaniu tej konfiguracji AMODIT potrafi odbierać wiadomości z Gmail przez IMAP i OAuth, a następnie przekazywać je do procesu zgodnie z konfiguracją poczty przychodzącej i tworzenia spraw z maila.