Integracja z Salesforce

Integracja z Salesforce umożliwia powiązanie dokumentów biurowych z danymi tej platformy zarządzania relacjami z klientami.

Na czym polega integracja z Salesforce

Integracja z Salesforce to połączenie systemu zarządzania relacjami z klientami z aplikacją obsługującą dokumenty biurowe albo z repozytorium plików. Jej zadaniem jest wymiana danych między tymi środowiskami, na przykład powiązanie dokumentu oferty, protokołu, umowy lub raportu z konkretnym kontaktem, kontem, szansą sprzedaży albo sprawą zapisaną w Salesforce. Sam dokument może pozostać przechowywany w systemie plików, usłudze chmurowej lub w mechanizmie Salesforce Files, natomiast w rekordzie Salesforce umieszcza się odwołanie, metadane albo kopię pliku.

Zakres integracji zależy od użytych aplikacji i przyjętego modelu danych. Możliwa jest synchronizacja jednostronna, w której dokumenty są pobierane z jednego systemu i rejestrowane w drugim, albo synchronizacja dwustronna obejmująca także aktualizacje, zmianę statusu i usuwanie powiązań. W praktyce trzeba jednoznacznie ustalić, który system jest źródłem prawdy dla nazwy pliku, właściciela, daty utworzenia, wersji dokumentu oraz identyfikatora klienta.

Powiązanie plików z rekordami CRM

W Salesforce pliki są obsługiwane między innymi przez obiekty ContentVersion, ContentDocument i ContentDocumentLink. ContentVersion opisuje konkretną wersję pliku, ContentDocument reprezentuje dokument jako całość, a ContentDocumentLink określa powiązanie dokumentu z rekordem lub użytkownikiem. Dzięki takiemu modelowi jeden dokument może być skojarzony z więcej niż jednym rekordem, a kolejne wersje mogą być przechowywane bez traktowania ich jako całkowicie niezależnych plików.

Integracja z dokumentami biurowymi wymaga mapowania pól. Nazwa pliku może zostać zestawiona z tytułem dokumentu, identyfikator klienta z identyfikatorem konta lub kontaktu, a status obiegu dokumentu z polem wyboru albo wartością tekstową w Salesforce. Należy także rozstrzygnąć sposób obsługi duplikatów. Bez reguł identyfikacji ten sam plik może zostać zapisany wielokrotnie, na przykład po zmianie nazwy, ponownym przesłaniu lub ponowieniu przerwanego żądania.

Warstwa komunikacji i autoryzacja

Do komunikacji z Salesforce stosuje się interfejsy API, w tym REST API i SOAP API. REST API wykorzystuje żądania HTTP oraz format JSON lub XML i jest często używane do obsługi pojedynczych rekordów oraz prostych operacji na plikach. SOAP API udostępnia kontrakt opisany przez WSDL i może być przydatne w rozwiązaniach opartych na formalnych usługach sieciowych. Przy większych zbiorach danych stosuje się Bulk API 2.0, przeznaczone do asynchronicznego przetwarzania dużej liczby rekordów.

Dostęp wymaga uwierzytelnienia i odpowiednich uprawnień. Salesforce korzysta z mechanizmów OAuth 2.0, a konfiguracja po stronie platformy może obejmować Connected App, zakresy dostępu, użytkownika integracyjnego i politykę tokenów. Sam token nie zastępuje kontroli uprawnień do obiektów, pól i plików. Dlatego integracja może poprawnie połączyć się z API, a mimo to otrzymywać błąd braku dostępu do określonego rekordu lub dokumentu. Diagnostyka powinna rozróżniać błąd uwierzytelnienia, brak autoryzacji, nieprawidłowy identyfikator, przekroczenie limitu oraz niezgodność formatu danych.

Diagnostyka niespójności w obiegu dokumentów

Przy problemach z integracją należy prześledzić cały przebieg operacji: utworzenie dokumentu, odczyt jego metadanych, znalezienie właściwego rekordu Salesforce, przesłanie treści, utworzenie powiązania i potwierdzenie wyniku. W logach powinny być rejestrowane identyfikatory korelacyjne, typ wykonywanej operacji, kod odpowiedzi HTTP, informacja o ponowieniu żądania oraz rezultat walidacji danych. Nie należy zapisywać w logach tokenów dostępowych ani pełnej zawartości dokumentów.

Typowym źródłem niespójności jest przerwanie operacji po przesłaniu pliku, lecz przed utworzeniem powiązania z rekordem. Innym przypadkiem jest aktualizacja dokumentu w jednym systemie bez przekazania informacji do drugiego. Pomocne są wtedy identyfikatory wersji, znacznik czasu modyfikacji i jawnie określona strategia konfliktów. Ponawianie żądań powinno uwzględniać idempotencję, aby chwilowa awaria sieci nie powodowała tworzenia kolejnych kopii tego samego dokumentu. Warto również sprawdzić kodowanie znaków, typ MIME, maksymalny rozmiar pliku oraz ograniczenia API obowiązujące w konkretnej organizacji Salesforce.