Adobe Acrobat Sign dla Salesforce: poradnik dla programistów

Omówienie

Adobe Acrobat Sign dla Salesforce: poradnik dla programistów ma na celu pomóc programistom Salesforce w zapoznaniu się z obiektami i parametrami wymaganymi do integracji pakietu Salesforce z Adobe Acrobat Sign.

Zapoznaj się z tematami w tym dokumencie, aby dowiedzieć się więcej:

• Wytyczne dla programistów
• Kolejność aktualizacji
• Usługi Apex
• Usługi API
• Usługi wsadowe Apex
• Partia szablonów umów
• Usługa partii szablonów umów
• Usługi REST
• Usługi w tle
• Zmiany w zakresie kompatybilności wstecznej

Wytyczne dla programistów

• Jeśli chcesz wiedzieć, kiedy umowa została w pełni podpisana, zaimplementuj wyzwalacz Apex na obiekcie echosign_dev1__SIGN_Agreement__c po lub przed aktualizacją (w zależności od przypadku użycia i wymagań). Gdy pole echosign_dev1__Status__c zmieni się na Podpisano lub Zatwierdzono lub inny status końcowy, umowa zostanie zakończona. 
• Jeśli chcesz wiedzieć, kiedy każdy pojedynczy podpisany plik PDF jest wstawiany, jeśli na przykład musisz uzyskać każdy pośredni podpisany plik PDF, zaimplementuj wyzwalacz Apex na obiektach Attachment lub ContentVersion po wstawieniu i obserwuj umowę nadrzędną i nazwę, która kończy się na „- signed.pdf” lub „- approved.pdf” albo inny status końcowy
• Jeśli chcesz wiedzieć, kiedy indywidualny odbiorca podpisał lub zatwierdził, zaimplementuj wyzwalacz Apex na obiekcie echosign_dev1__SIGN_Recipients__c po lub przed aktualizacją (w zależności od przypadku użycia i wymagań). Gdy pole echosign_dev1__Status__c zmieni się na Podpisano lub Zatwierdzono lub inny status końcowy, odbiorca zostanie zakończony.  
• Jeśli chcesz wiedzieć, kiedy wystąpi określone zdarzenie, które jest częścią procesu podpisywania, takie jak wysłanie umowy do podpisu lub wysłanie przypomnienia, możesz utworzyć wyzwalacz na obiekcie zdarzeń umowy (echosign_dev1__SIGN_AgreementEvent__c) i sprawdzić typ zdarzenia
• Nazwy statusu umowy końcowej dla zakończonej umowy to: „Podpisana”, „Zatwierdzona”, „Zaakceptowana”, „Wypełniona” i „Dostarczona”
  
• Nazwy statusu umowy końcowej dla rozwiązanej umowy to: „Anulowana / Odrzucona”, „Anulowana / Odrzucona”, „Wygasła”

Kolejność aktualizacji

W wersji v21 kolejność aktualizacji uległa zmianie. Poniżej przedstawiono kolejność uaktualniania umowy i powiązanych z nią obiektów:

1. Załączniki 
2. Odbiorcy 
3. Umowa (status i inne atrybuty)
4. Zdarzenia umowy 
5. Wiadomości z aplikacji Chatter 

Usługi Apex

Metoda Apex w użyciu

Począwszy od wersji Acrobat Sign for Salesforce V 21.0, wszystkie procesy asynchroniczne (w tym aktualizacje automatyczne i mapowania danych) używają metody Queueable zamiast metody Future, zgodnie z zaleceniem Salesforce.
W związku z tą zmianą wszystkie zadania dostosowywania, które są dodawane do kolejki Salesforce w celu automatycznej aktualizacji lub procesu mapowania danych, zakończą się niepowodzeniem z tym błędem: „System.LimitException: Too many queueable jobs added to queue:2."

Błąd występuje, ponieważ proces kolejkowy może dodać tylko jedno podrzędne zadanie kolejkowe, które jest już zajęte przez Acrobat Sign. Szczegółowe informacje można znaleźć na stronie Ograniczenia kolejkowania Apex. 

Gdy stan umowy nie zmienia się lub mapowanie danych nie działa poprawnie, może zostać wyświetlony ten błąd: „When chaining jobs, you can add only one job from an executing job with System.enqueueJob, which means that only one child job can exist for each parent queueable job. Starting multiple child jobs from the same queueable job isn’t supported” („Podczas łączenia zadań można dodać tylko jedno zadanie z zadania wykonywanego za pomocą polecenia System.enqueueJob, co oznacza, że dla każdego z zadań w kolejce nadrzędnej może istnieć tylko jedno zadanie podrzędne. Uruchomienie wielu zadań podrzędnych z tego samego zadania nie jest obsługiwane”).

Aby rozwiązać ten błąd, poszukaj czynnika wyzwalającego, narzędzia tworzenia procesu lub obiegu pracy. Następnie dezaktywuj to działanie, ustaw je jako proces synchroniczny lub zaplanuj na później.

Usługa szablonów umów

Usługa szablonów umów jest udostępniana jako globalna usługa Apex przez pakiet zarządzany. Pozwala to kodowi Apex spoza pakietu zarządzanego na ładowanie umów w oparciu o istniejące szablony umów. Klasa i wszystkie ujawnione metody są oznaczone jako globalne, aby umożliwić taki dostęp.

Usługa Apex jest dostępna za pośrednictwem tej klasy wywołania: echosign_dev1.AgreementTemplateService

Metody

 Konstruktory

Globalne właściwości klasy

Zmienne środowiska wykonawczego

Klasa globalna echosign_dev1.AgreementTemplateVariable ma następujące dwa pola globalne:

• name: nazwa zmiennej, która musi być zgodna z nazwą zmiennej środowiska wykonawczego skonfigurowaną w szablonie umowy.
• value: wartość zmiennej używana podczas ładowania szablonu. Wartość zależy od tego, gdzie zmienna została użyta. Na przykład w przypadku odbiorcy musi to być kontakt, potencjalny klient, identyfikator rekordu użytkownika lub adres e-mail. W przypadku zmiennej dokumentu musi to być identyfikator rekordu załącznika.

Wynik

Każda metoda zwraca identyfikator nowo utworzonego rekordu umowy lub zgłasza wyjątek ze szczegółowym komunikatem o błędzie, jeśli coś pójdzie nie tak podczas operacji ładowania.

Usługi API

Usługa szablonu Adobe e-Sign API jest udostępniana jako globalna usługa Apex przez pakiet zarządzany. Umożliwia to kodowi Apex spoza pakietu zarządzanego wywoływanie zestawu interfejsów API Adobe e-Sign za pośrednictwem tych opakowań. Opakowania znacznie upraszczają wywoływanie API, ponieważ konsumenci nie muszą tworzyć modelu danych żądania i odpowiedzi. Konsumenci nie muszą również zajmować się transformacją danych Salesforce do modeli danych e-Sign. Większość złożoności jest niewidoczna dla konsumenta. Na przykład aby wysłać umowę, konsument po prostu przekazuje identyfikator rekordu umowy, usługa zajmie się zapytaniem, wyodrębnieniem wszystkich odpowiednich danych, przekazaniem ich do interfejsu API i przeanalizowaniem wyniku.

Klasa i wszystkie ujawnione metody są oznaczone jako globalne, aby umożliwić taki dostęp.

• v17 i starsze wywołują API SOAP
• v18 i nowsze wywołują API REST

Usługa Apex jest dostępna za pośrednictwem następującej klasy wywołania: echosign_dev1.EchoSignApiService

Ulepszenie interfejsu API Apex dla alternatywnych odbiorców

Począwszy od wersji 24.14 lub nowszej, zaktualizowany interfejs API Apex umożliwia zastępowanie lub dodawanie alternatywnych odbiorców i jest dostępny w ramach globalnej klasy „EchoSignApiService”, wprowadzono dwa nowe elementy:

• Funkcja globalna:
  

  /**

  * Parametry wejściowe:

  * toBeChangedRecipientId: SIGN_Recipient__c Id

  * newRecipientStr: Ciąg JSON SIGN_Recipient__c nowego odbiorcy w celu zastąpienia odbiorcy lub alternatywy

  * changeType: REPLACE lub ALTERNATE

  */

  global static void changeRecipient(Id toBeChangedRecipientId, String newRecipientStr, RECIPIENT_CHANGE_TYPE changeType )

• Globalne wyliczenie: RECIPIENT_CHANGE_TYPE {REPLACE, ALTERNATE}

Przykładowy kod wywołujący ten interfejs API dla odbiorców (typ odbiorcy jako Email)

// najpierw zapytaj wszystkich odbiorców powiązanych z umową

List<SIGN_Recipients__c> recipients = [SELECT Id, echosign_dev1__Agreement__c, echosign_dev1__Email_Address__c, echosign_dev1__ParticipantSet__c, echosign_dev1__Recipient_Type__c, echosign_dev1__Order_Number__c FROM echosign_dev1__SIGN_Recipients__c where echosign_dev1__Agreement__c = 'a0P7X000008Cc1GUAS'];

SIGN_Recipients__c newRecipient = null;

SIGN_Recipients__c replacedRecipient = null;

// znaleźć odbiorcę, który ma zostać zastąpiony lub alternatywę

// w tym przypadku znajdź odbiorcę po jego adresie e-mail.

// Można dodać więcej warunków, aby znaleźć odbiorcę, który ma zostać zastąpiony lub potrzebuje alternatywy.

for(SIGN_Recipients__c recipient: recipients) {

    if (rep.echosign_dev1__Email_Address__c == 'someUser@example.com') {

         newRecipient = recipient.clone(false, true, false, false);

         replacedRecipient = recipient;

    }

}

// zaktualizuj adres e-mail dla nowego odbiorcy

newRecipient.echosign_dev1__Email_Address__c = ''someNewUser@abc.com';

// szereguje go do łańcucha json

String newRecipientStr = JSON.serialize(newRecipient);

Try {

    echosign_dev1.EchoSignApiService.changeRecipient(replacedRecipient.Id, newRecipientStr, EchoSignApiService.RECIPIENT_CHANGE_TYPE.REPLACE);

} catch (Exception ex) {

    // obsłużyć wyjątek i w razie potrzeby rzucić ponownie

}

Metody

Klasy wewnętrzne

• Klasa globalna: DocumentHistoryEvent

• Klasa globalna: DocumentInfo
  

• Klasa globalna: ParticipantInfo

• Klasa globalna: SendDocumentResult

• Klasa globalna: SigningUrl
  

Usługi wsadowe Apex

Udostępnia główne akcje umowy e-Sign na poziomie zbiorczym, umożliwiając wykonanie operacji na zestawie umów. Klasa ta implementuje interfejs Salesforce Database.Batchable. Może przetwarzać dowolną liczbę rekordów, które zostaną podzielone na zestawy po 5, i przetwarzać każdy zestaw jako indywidualną transakcję, co pozwala na przestrzeganie limitów zarządcy.

Usługa wsadowa Apex jest dostępna za pośrednictwem następującej klasy wywołania: echosign_dev1.EchoSignActionBatch

Parametry

Aby zainicjować operację wsadową, należy określić następujące parametry:

• Lista identyfikatorów rekordów umowy, na których należy wykonać podane działanie: akcja może mieć dowolną z następujących obsługiwanych wartości: Przypomnij, Wyślij, Anuluj, Usuń lub Aktualizuj.
• Identyfikator bieżącej sesji użytkownika: Wymagane tylko dla typu akcji aktualizacji.
• Rekord użytkownika przesyłającego: służy do powiadamiania użytkownika za pośrednictwem wiadomości e-mail po zakończeniu przetwarzania zbiorczego.

Przykład użycia

User submitterUser = UserInfo.getUserId();

EchoSignActionBatch batch = new EchoSignActionBatch( agreementIds, 'Remind', UserInfo.getSessionId(), submitterUser); Id syncProcessId = Database.executeBatch(batch, 5);

Partia szablonów umów

Pobiera zapytanie SOQL i identyfikator rekordu szablonu umowy. Zapytanie jest wykonywane w celu uzyskania zestawu rekordów obiektów głównych, z których każdy jest następnie uruchamiany przez dostarczony szablon umowy w celu wygenerowania rekordu umowy. Klasa ta implementuje interfejs Salesforce Database.Batchable. Może przetwarzać dowolną liczbę rekordów, które zostaną podzielone na zestawy po 5, i przetwarzać każdy zestaw jako indywidualną transakcję, co pozwala na przestrzeganie limitów zarządcy.

Typy rekordów zwracane przez zapytanie SOQL muszą być zgodne z podanym typem obiektu głównego szablonu umowy. Dla każdego rekordu wywoływana jest usługa szablonu umowy.

Usługa wsadowa Apex jest dostępna za pośrednictwem następującej klasy wywołania:

echosign_dev1.AgreementTemplateBatch

Parametry

Aby zainicjować operację wsadową, należy określić następujące parametry:

• Zapytanie SOQL do wykonania: musi zawierać identyfikator rekordu jako wybrane pole. Pozostałe pola są opcjonalne.
• Identyfikator rekordu szablonu umowy: jest używany wraz z identyfikatorem rekordu głównego w celu załadowania umowy.

Przykład użycia

String agreementTemplateId = [SELECT Id from echosign_dev1__Agreement_Template__c where Name = 'Default Template']; String soqlQuery = 'SELECT Id from Contact where Account.IsActive = true';

AgreementTemplateBatch batch = new AgreementTemplateBatch(soqlQuery, agreementTemplateId); Id syncProcessId = Database.executeBatch(batch, 5);

Usługa partii szablonów umów

Pobiera listę identyfikatorów rekordów obiektu głównego i typ obiektu głównego, które są następnie odpytywane, a każdy z nich jest następnie uruchamiany przez dostarczony szablon umowy w celu wygenerowania rekordu umowy. Klasa ta implementuje interfejs Salesforce Database.Batchable. Może przetwarzać dowolną liczbę rekordów, które zostaną podzielone na zestawy po 5, i przetwarzać każdy zestaw jako indywidualną transakcję, co pozwala na przestrzeganie limitów zarządcy.

Podany typ obiektu głównego musi być zgodny z podanym typem obiektu głównego szablonu umowy. Dla każdego rekordu wywoływana jest usługa szablonu umowy.

Usługa wsadowa Apex jest dostępna za pośrednictwem następującej klasy wywołania:

echosign_dev1.AgreementTemplateServiceBatch

Parametry

Aby zainicjować operację wsadową, należy określić następujące parametry:

• Lista identyfikatorów rekordów głównych.
• Identyfikator rekordu szablonu umowy: jest on używany wraz z rekordami głównymi w celu załadowania umowy.
• Nazwa obiektu głównego do zapytania o rekordy główne.

Przykład użycia

String agreementTemplateId = [SELECT Id from echosign_dev1__Agreement_Template__c where Name = 'Default Template'];

AgreementTemplateBatch batch = new AgreementTemplateServiceBatch(new List<Id>{'01p50000000HoMB'}, agreementTemplateId, 'Contact');
Id syncProcessId = Database.executeBatch(batch, 5);

Usługi REST

Usługa szablonów umów

Usługa szablonów umów jest udostępniana jako usługa sieciowa Salesforce REST przez pakiet zarządzany. Umożliwia to zewnętrznym systemom spoza organizacji Salesforce ładowanie umów w oparciu o istniejące szablony umów. Więcej informacji na temat uzyskiwania dostępu i wywoływania niestandardowych usług REST Apex z poziomu Salesforce można znaleźć w artykule Tworzenie REST API przy użyciu Apex REST. Wywołania muszą zawierać prawidłowy identyfikator sesji w celu uwierzytelnienia i autoryzacji.

Usługa sieciowa jest dostępna pod następującym adresem URL:

https://<instance_name>.salesforce.com/services/apexrest/echosign_dev1/template/load/<template_id>?masterId=<master_id>&varName1=var Value1&varName2=varValue2

Adres ID szablonu

Ostatnia część adresu URL to identyfikator rekordu szablonu umowy w bieżącej organizacji Salesforce, który powinien zostać użyty do załadowania umowy. Ta część adresu URL jest opcjonalna. W przypadku pominięcia załadowany zostanie szablon umowy oznaczony jako domyślny. Jeśli identyfikator szablonu zostanie pominięty i nie istnieje domyślny identyfikator szablonu umowy, zwrócony zostanie błąd.

Identyfikator szablonu może mieć format 15 lub 18 znaków.

Identyfikator główny

Parametr masterId określa, który rekord główny powinien zostać użyty do załadowania umowy z określonego szablonu umowy. Ten parametr jest opcjonalny, ale musi być określony dla każdego szablonu umowy, który określa typ obiektu głównego i odwołuje się do tego obiektu głównego w szablonie.

Identyfikator główny może mieć format 15 lub 18 znaków.

Zmienne środowiska wykonawczego

Wszelkie dodatkowe parametry są używane jako zmienne środowiska wykonawczego, jako pary nazwa-wartość, używane do wypełnienia dowolnych zmiennych środowiska wykonawczego określonych w szablonie umowy.

Wynik

Usługa sieciowa REST zwraca obiekt LoadResult, który zawiera następujące pola:

• agreementId : jeśli operacja wczytania umowy zakończyła się powodzeniem, zawiera identyfikator nowo utworzonego rekordu umowy.
• error: jeśli podczas ładowania umowy wystąpił jakikolwiek błąd, pole to będzie zawierać szczegółowy komunikat o błędzie.

Usługi w tle

Funkcja usługi w tle umożliwia konsumentom pakietów wywoływanie różnych akcji na obiekcie umowy poprzez aktualizację pola Operacje w tle (echosign_dev1 Background_Actions c) do odpowiedniej wartości. Gdy wartość pola zostanie zmieniona z wartości pustej lub innej wartości na jedną z poniższych wartości, akcja zostanie uruchomiona z wyzwalacza, który jest częścią pakietu zarządzanego e-Sign.

• Przypomnij
• Wyślij
• Anuluj
• Usuń
• Zaktualizuj

Wszystkie operacje wykonywane są w asynchronicznym trybie przyszłości, więc status zostanie zapisany w polu Error w umowie.

Zmiany w zakresie kompatybilności wstecznej

Więcej materiałów tego typu

• Adobe Acrobat Sign dla Salesforce — instrukcja instalacji
• Adobe Acrobat Sign dla Salesforce — instrukcja wprowadzania ustawień zaawansowanych
• Adobe Acrobat Sign dla Salesforce — mapowanie pól i szablony
• Adobe Acrobat Sign dla Salesforce — instrukcja aktualizacji
• Adobe Acrobat Sign dla Salesforce — instrukcja użytkownika