Dotyczy wersji 2020.1.3.x autor: Tomasz Pytlak
Wstęp
Jedną z podstawowych funkcjonalności WEBCON BPS jest praca z załącznikami. Niektóre procesy, jak na przykład Repozytorium Dokumentów, mogą istnieć wyłącznie w celu skatalogowania i udostępnienia plików wybranym użytkownikom. W innych, załączniki mogą mieć drugorzędne znaczenie. Niezależnie od tego pozostają one jednym z centralnych elementów każdego systemu BPS.
Warto jednak zastanowić się nad przypadkiem, gdy chcemy wspólnie z klientem pracować nad plikiem, jednocześnie nie udostępniając systemu zewnętrznym użytkownikom. Przesyłanie pliku poprzez email może doprowadzić do sytuacji, w której mamy kilka wersji tego samego dokumentu i żadnej ze scalonymi zmianami. W takim przypadku warto rozważyć integrację BPS z usługami przechowywania plików jak OneDrive, czy opisany w niniejszym artykule Google Drive.
Przygotowanie Google API
Przygotowanie procesu należy rozpocząć od konfiguracji po stronie Google API zgodnie z dokumentacją dostępną pod adresem https://developers.google.com/drive/api/v3/about-sdk.
Poniżej opisano najprostszy schemat postępowania, pozwalający na integrację z Google Drive.
Pierwszym krokiem jest przejście na stronę https://console.developers.google.com/, zalogowanie się za pomocą konta Google i wybranie projektu z listy lub utworzenie nowego.
Rys. 1 Wybór projektu Google
Następnie w zakładce „Library” należy wyszukać i aktywować „Google Drive API”. Jest to rozszerzenie pozwalające na komunikację klienta z zasobami Google Drive.
Rysunek 2 Wybór API
W następnej kolejności w zakładce „OAuth consent screen” należy wybrać jaki typ użytkowników będzie miał dostęp do API.
Rys. 3 Wybór typu użytkowników
Potwierdzenie wyboru przyciskiem CREATE otwiera nowe okno, w którym należy nazwać aplikację.
Opcjonalnie można m.in. dodać logo, wskazać autoryzowane domeny lub ustawić maila kontaktowego dla użytkowników.
Rys. 4 Konfiguracja aplikacji
Na końcu należy przejść do trzeciej zakładki „Credentials” i za pomocą przycisku CREATE CREADENTIALS stworzyć nowego klienta OAuth, co umożliwi przeprowadzenie procesu autentykacji.
Rys. 5 Dodanie klienta OAuth
W konfiguracji wystarczy określić typ aplikacji oraz podać jej nazwę.
Rys. 6 Konfiguracja klienta OAuth
Po utworzeniu Klienta warto wejść do jego konfiguracji poprzez kliknięcie na nazwę i zwrócić uwagę na Client ID oraz Client secret, ponieważ będą to parametry potrzebne do uzyskania tokena.
Rys. 7 Parametry klienta OAuth
Utworzenie tokenów
W celu utworzenia refresh tokena należy wykonać dwa wywołania. W związku z tym, że jest to operacja jednorazowa, nie warto jej utrwalać w postaci procesu. Procedura jest opisana pod adresem https://developers.google.com/identity/protocols/oauth2/native-app#loopback-ip-address.
Pierwsze wywołanie służy uzyskaniu kodu autoryzacyjnego. Najwygodniej wykonać je w kontekście przeglądarki, ponieważ konieczne jest zalogowanie do konta Google. W poniższym wywołaniu należy podmienić {ClientID} na właściwe Client ID opisane w poprzednim rozdziale.
Ze względu na politykę bezpieczeństwa, wyświetlone zostanie ostrzeżenie o niezweryfikowanej aplikacji. Jej weryfikacja jest możliwa, ale wymaga kontaktu z Google i nie jest istotna dla treści artykułu. Wystarczy rozwinąć zakładkę „Advanced” i zaakceptować ryzyko, a następnie dwukrotnie zatwierdzić dostęp.
Rys. 8 Okno potwierdzenia dostępu
W odpowiedzi, w adresie URL wyświetlony zostanie parametr code, który należy zapisać i wkleić do kolejnego wywołania. Trzeba pamiętać, że posiada on określoną ważność.
Ewentualne pojawienie się błędu 404 związane jest z brakiem aplikacji hostowanej pod wskazanym jako redirect_url adresem. Parametry w adresie URL powinny być dostępne nawet w takim przypadku.
Drugie wywołanie ma na celu zamianę uzyskanego kodu na token. Ponieważ jest to wywołanie typu POST, najlepiej wykonać je przy pomocy dedykowanego oprogramowania jak np. Postman.
W tym celu należy wybrać typ POST, wskazać endpoint https://oauth2.googleapis.com/token oraz w zakładce Body uzupełnić pięć parametrów:
- Code – wartość uzyskana z poprzedniego wywołania
- Client_id – ID klienta analogicznie jak w poprzednim wywołaniu
- Client_secrets – wartość dostępna jest w parametrach klienta pod Client ID.
- Redirect_url – serwer, który otrzyma odpowiedź (w tym przypadku lokalny)
- Grant_type – wartość “authorization_code”
Rys. 9. Wymiana kodu na token w Postman – wywołanie
Podczas kopiowania wartości warto zwrócić uwagę, czy na końcu parametru nie wkleił się biały znak.
W odpowiedzi Google Drive API przesyła pięć wartości, z których najważniejszą dla opisanego poniżej obiegu jest refresh_token, który pozwoli na cykliczne odświeżanie tokena dostępu.
Rys. 10. Wymiana kodu na token w Postman – odpowiedź
Utrzymanie access tokena
Ponieważ token dostępu ważny jest jedynie przez godzinę, a dodatkowo trzeba udostępnić go na potrzeby systemu, najlepiej stworzyć obieg techniczny.
Jego zadaniem będzie przechowywanie access tokena oraz cykliczne odnawianie go z wykorzystaniem wywołania realizowanego za pomocą standardowej akcji „Wywołaj REST Web service”
Może składać się on z trzech kroków i w założeniu posiadać tylko jedną aktywną instancję.
Rys. 11 Schemat przykładowe obiegu technicznego utrzymującego token
Podczas rejestracji instancji, na formularzu należy uzupełnić parametry wywołania.
Dwa pierwsze parametry ponownie można znaleźć w konfiguracji klienta, trzeci przyjmuje stałą wartość „grant_type”, a czwarty to refresh_token uzyskany w poprzednim wywołaniu.
Rys. 12. Obieg techniczny podczas rejestracji
Na wejście do kroku Active dodano akcję „Refresh Token” typu „Wywołaj REST Web service”.
Autentykację ustawiono jako „Niestandardową” i wskazano endpoint żądania.
Rys. 13. Refresh token – zakładka Authentication
W drugiej zakładce zmieniono jedynie typ wywołania na POST.
Rys. 14. Refresh token – zakładka Request data
Parametry wywołania zostały wpisane w trzeciej zakładce.
Rys. 15. Refresh token – zakłądka Request body
Natomiast w czwartej określono mapowanie uzyskanego tokenu dostępu do pola na formularzu.
Rys. 16. Refresh token – zakładka Response
Dodatkowo na kroku dodano Timeout, który co 50 minut wykona automatyczne wywołanie w celu odnowienia tokenu.
Rys. 17. Timeout Refresh
Po przejściu ścieżką rejestracji na formularzu, pobrany zostanie pierwszy access token, a system automatycznie będzie go odnawiał w zadanym interwale czasu.
Rys. 17 Obieg techniczny po uzyskaniu access tokena
Należy zwrócić szczególną uwagę, na to, kto posiada dostęp do obiegu, ponieważ przechowuje on dane pozwalające na autentykację do Google Drive również spoza systemu BPS.
Publikacja pliku
Można wyobrazić sobie różne scenariusze, w których chcemy umieścić plik na Google Drive. W niniejszym przykładzie, rejestracja Umowy oznacza przesłanie ostatniego dodanego do formularza załącznika na dysk Google. W tym celu na ścieżce przejścia „Register” umieszczono akcję typu „Wywołaj REST Web service”, którą nazwano „Send file”.
W pierwszej zakładce konfiguracji po raz kolejny skorzystano z autentykacji anonimowej i wskazano odpowiedni endpoint – https://www.googleapis.com/upload/drive/v3/files.
Rys. 19. Send file – Zakładka Authentication
W drugiej zakładce zmieniono typ metody na POST oraz podano dwa parametry:
Authorization – token dostępu pobierany za pomocą reguły biznesowej z obiegu technicznego
uploadType – multipart, będący jednym z 3 dostępnych typów transferu obok „ media” oraz „resumable”. Metoda ta jest zalecana dla plików do 5MB wielkości. Więcej informacji na ich temat można znaleźć pod adresem https://developers.google.com/drive/api/v3/manage-uploads.
Rys.20. Send file – Zakładka Request data
Reguła biznesowa „Att: Authorization” zapisana jest w postaci SQL COMMAND i składa się ze stałej części ‘Bearer’ oraz tokena dostępu.
Rys. 21. Reguła Att: Authorization
Trzecia zakładka zawiera w tym przypadku w większości dane dotyczące samego pliku:
- Body type – dla tego przypadku ponownie Multipart, co umożliwia przesłanie zarówno metadanych jak i danych binarnych w obrębie jednego requesta
- JSON part headers – stały nagłówek “Content-Type:application/json”
- JSON part value – metadane zawierające w parametrze „name” nazwę pliku
- Binary part header – zawiera parametr „Content-Type” z informacją o rodzaju pliku
- Binary part value – zawiera dane binarne do wysłania. Pole wspiera trzy tryby:
- przekazanie ID załącznika znajdującego się w bazie WEBCON BPS
- przekazanie danych w formacie Data URL, który umożliwia przesłanie np. zawartości atrybutu typu obrazek
- dowolna zawartość tekstowa inna niż w powyższych punktach
W poniższym przypadku skorzystano z pierwszej metody.
Rys. 22 Request data – Zakładka Request body
Na powyższym zrzucie można zauważyć trzy reguły biznesowe. Reguła „Att: ID” stanowi podstawę dla pozostałych. Zawiera w sobie zapytanie SQL wyszukujące ID ostatniego załącznika dodanego do bieżącej instancji.
Rys. 23 Reguła Att: ID
Reguły „Att: Name” oraz „Att: Content type” bazują na “Att: ID” i nowych, predefiniowanych funkcjach zwracając odpowiednio nazwę załącznika i jego typ.
Rys. 24. Reguła Att: Name
Rys. 25. Reguła Att: Content type
W celu przetestowania tak skonfigurowanego obiegu wystarczy dodać załącznik i przejść ścieżką rejestracji.
Rys. 26. Załącznik na formularzu
Plik zostanie umieszczony na Google Drive.
Rys. 27 Załącznik dodany do Google Drive
Podsumowanie
Standardowa akcja dostępna w WEBCON BPS dostarcza możliwości integracji z wieloma zewnętrznymi dostawcami oprogramowania. W przypadku Google Drive można z niej skorzystać do przesyłania plików ale również wykonywania innych operacji jak utrzymywanie aktywnego tokena dostępu.
