Obsługa dokumentów jest jedną z podstawowych funkcji wykorzystywanych przez użytkowników, którzy każdego dnia przeglądają i tworzą setki, jeśli nie tysiące plików. Część z nich jest w formie zeskanowanych dokumentów, przesyłanych za pomocą faksu, a część jest przesyłana i cyfrowo podpisywana wykorzystując połączenie z rozwiązaniem Adobe Sign.
W niniejszym artykule skupimy się na tym, w jaki sposób wykorzystać aplikację Heroku do wypełniania wcześniej przygotowanych dokumentów w formacie .pdf danymi, wprowadzonymi przez użytkownika w Community Salesforce’, na podstawie jednego z projektów realizowanych w Sii.
Nie przedstawię tutaj całościowego rozwiązania, nie będę także umieszczał fragmentów kodu, ale znajdą się tutaj najważniejsze kroki, wskazujące jak nawiązać połączenie z aplikacją Heroku z poziomu platformy Salesforce oraz ogólne założenia wykorzystywanej funkcjonalności.
Co to jest Heroku?
W projekcie używamy aplikacji umieszczonej na Heroku w celu obróbki dokumentów na różne sposoby:
- uzupełniania dokumentów danymi,
- obracania stron do góry nogami,
- dzielenia stron na kilka mniejszych dokumentów.
Na potrzeby tego artykułu skupimy się na wypełnianiu dokumentów przekazanymi danymi, natomiast Heroku samo w sobie nie posiada takiej funkcjonalności – trzeba więc ją stworzyć.
Na początek jednak pytanie: czym w ogóle jest Heroku?
Platforma Salesforce łączy w sobie wiele usług i narzędzi w jedną spójną całość. Platforma Heroku jest rozwiązaniem działającym w chmurze, które funkcjonuje jako Platform as a Service i jest częścią tego zestawu narzędzi udostępnionego użytkownikom. Jej celem jest umożliwienie użytkownikowi hostowania aplikacji webowej w usłudze serverless. Platforma pozwala na łatwe zarządzanie i budowanie aplikacji, bez konieczności martwienia się o server i jego ustawienia.
Stworzoną aplikację (w jednym z przykładowych dostępnych języków: Java, Ruby, Python, PHP, JavaScript, oraz Go) można wdrożyć za pomocą powszechnie dostępnych narzędzi typu Git Hub. Heroku ma przejrzysty panel do monitorowania wydajności aplikacji oraz podstawowe instrukcje na temat korzystania z dostępnych funkcjonalności.
Heroku – jak zacząć?
Aby zacząć naszą pracę, potrzebujemy konta na platformie Heroku. Możemy stworzyć aplikację na własny użytek lub użyć konta do przechowywania wielu aplikacji w ramach całego projektu.
Na potrzeby tego artykułu stworzymy nową aplikację o nazwie pdftools:
Do nowo stworzonej aplikacji będziemy potrzebować odpowiednich wtyczek, które pomogą nam w realizacji projektu – bez nich nie będziemy w stanie zaimplementować niektórych wymaganych rozwiązań. Najważniejszą z nich będzie Heroku Postgres, dzięki której możemy stworzyć bazę danych po stronie Heroku, w której będziemy przechowywać nasze dokumenty.
Dokumenty będą tam przechowywane w „surowej” postaci. Można je nazwać szablonem, na który będziemy nanosić nasze zmiany. Będą to podstawowe, puste, odpowiednio spreparowane pliki z merge field-ami (więcej o tym w następnym rozdziale), a wersje wypełnione przesłanymi danymi będą tam tylko tymczasowo – po uzupełnieniu i odesłaniu będą kasowane, żeby nie przechowywać danych wrażliwych.
Wiadomo jednak, że samo dodanie wtyczki nie wystarczy i trzeba się połączyć z nowo powstałą bazą, za pomocą odpowiedniego narzędzia, np. aplikacji pgAdmin. Dzięki podłączeniu się do bazy danych, stworzonej przez naszą wtyczkę, będziemy mogli dodać całą strukturę naszej bazy z odpowiednimi tabelami.
Oprócz tego mamy dostęp do wielu innych wtyczek, jak np. CloudAMQP i New Relic APM, które mogą nam pomóc w monitorowaniu przepływu danych, błędów lub wizualizacji innych potrzebnych informacji. Oczywiście sama aplikacja będzie zawierać wykresy prezentujące jej działanie, ale dodatkowe wtyczki mogą znacznie rozbudować tę funkcjonalność:
Najważniejszym krokiem jest jednak napisanie samej aplikacji, w naszym przypadku przy użyciu języka Java, która będzie obsługiwać zapytania przesyłane przez Salesforce. Nie jestem w stanie zamieścić tutaj kodu używanego w naszej aplikacji, ale żeby umieścić kod w aplikacji, możemy postępować zgodnie z krokami przedstawionymi w zakładce Deploy.
Ogólna zasada działania naszej aplikacji polega na pobraniu mapy, zawierającej wszystkie wartości, które chcemy przypisać pod konkretne klucze pól na wybranym dokumencie, a następnie zwrócenie nam uzupełnionego pliku .pdf. W tym celu potrzebujemy jednak specjalnie przygotowanego dokumentu.
Dokument
Na początek będziemy potrzebować odpowiednio przygotowaną strukturę pliku .pdf. Będzie się on składać z opisów oraz pól, do których wstawiamy konkretne wartości (nic nas nie powstrzymuje od przygotowania skomplikowanych tabel lub formularzy).
Na przykład, załóżmy, że nasz dokument będzie zawierać dane użytkownika z naszego systemu. Musimy więc przygotować odpowiednie pola, żeby te informacje przechować:
Powyższy przykład pokazuje, że każde z naszych pól (merge field) jest przypisane do konkretnej wartości, a nazwa każdego pola będzie wykorzystana przez nas później do przekazania pożądanych informacji. Tak jak wspomniałem wcześniej, do uzupełnienia tych pól będziemy musieli przesłać w zapytaniu odpowiednie wartości.
W tym celu musimy przekazać co najmniej dwie podstawowe informacje:
- nazwę pliku, który chcemy wypełnić,
- mapę danych, w postaci nazwy pola, oraz wartości, którą chcemy do danego pola przypisać.
Tak przygotowane zapytanie musi obsłużyć Heroku, wybierając wskazany przez nas dokument z bazy danych oraz na podstawie mapy danych przypisać odpowiednie wartości do pól o odpowiednich nazwach
Przykład zapytania w formacie JSON:
{
"documentName": "UserDataDocument",
"userData": [
{"FirstName": "TestFN"},
{"LastName": "TestLN"},
{ "Birthday": "01/01/1999"},
{"Birthday": "01/01/1999"},
{"GenderMale": "true"},
...
]
}
Podpięcie aplikacji Heroku pod Salesforce
Pierwszym krokiem będzie oczywiście stworzenie klas i metod w systemie, dzięki którym będziemy mogli wysyłać zapytania do naszej aplikacji po stronie Heroku. W tym przypadku potrzebujemy osobnych metod do wysłania nowego pliku .pdf obsługiwanego dokumentu do bazy danych w Heroku Postgres oraz osobnych metod do przesłania danych do wypełnienia przygotowanego dokumentu.
Wszystkie adresy URL, pod które będziemy wysyłać zapytania przechowujemy w rekordzie typu Metadata, gdzie posiadamy osobną konfigurację pod różne środowiska (np. DEV, SQA, UAT):
Można też, jak na przykładzie powyżej, skonfigurować dodatkową aplikację zapasową, na którą nastąpi przekierowanie w przypadku wystąpienia konkretnej ilości błędów w danym czasie.
Drugim krokiem będzie wybranie odpowiedniego użytkownika na naszym środowisku, który posłuży do uwierzytelnienia naszego połączenia. W tym celu stworzymy nowego, któremu przydzielimy specjalny profil i uprawnienia, żeby posiadał dostęp tylko i wyłącznie do danych wymaganych dla naszej funkcjonalności.
Następnym krokiem jest stworzenie nowej Connected App, która posłuży do połączenia się z naszą nowo stworzoną aplikacją po stronie Heroku.
Po stworzeniu PDF Tools App będziemy mieć dostęp do danych, które wykorzystamy w konfiguracji połączenia z Heroku. W tym celu będziemy potrzebować Consumer Key and Secret.
Użyjemy informacji przechwyconych tutaj i wcześniej utworzonego użytkownika, aby utworzyć plik po stronie aplikacji Heroku, który posłuży do uwierzytelnienia naszego połączenia. Poniżej umieszczam przykład wpisu z takiego pliku, zawierający wszystkie potrzebne informacje dla jednego ze środowisk:
[ENV_NAME][email protected].[ENV_NAME] [ENV_NAME].sfPassword=[ENCRYPTED_PASSWORD_TOKEN] [ENV_NAME].sfServerurl=https://test.salesforce.com [ENV_NAME].authEndpoint=https://test.salesforce.com/services/Soap/u/35.0 [ENV_NAME][email protected].[ENV_NAME] [ENV_NAME].oauthPassword=[ENCRYPTED_PASSWORD_TOKEN] [ENV_NAME].oauthEndpoint=https://test.salesforce.com/services/oauth2/token [ENV_NAME].oauth_client_id=[CONSUMER_KEY] [ENV_NAME].oauth_client_secret=[ENCRYPTED_CONSUMER_SECRET] [ENV_NAME].sessionTtl=5 [ENV_NAME].domainPart=[ENV_NAME]
Tak spreparowany plik konfiguracyjny, zawierający informacje o wszystkich użytkownikach z różnych środowisk korzystających z danej aplikacji, umieszczamy w kodzie aplikacji Heroku, gdzie będzie używany do sprawdzania połączenia.
Podsumowanie
Realizując wskazane powyżej kroki, można stworzyć podpiętą pod środowisko Salesforce aplikację Heroku, która ma na celu uzupełnienie wybranego przez nas dokumentu dostarczonymi wartościami.
Podstawowe kroki i opisy tworzenia takich aplikacji można też znaleźć na platformie Trailhead, zawierającej wiele materiałów treningowych, wprowadzających w działanie narzędzia Salesforce.
Mam nadzieję, że powyższy artykuł przysłuży się chociaż w najmniejszym stopniu do stworzenia podobnego rozwiązania.
***
A jeśli interesują Cię rozwiązania Salesforce, zerknij koniecznie również do innych artykułów naszych autorów.
Zostaw komentarz