Adobe Acrobat Sign pro Salesforce – Příručka pro vývojáře

Přehled

Adobe Acrobat Sign pro Salesforce – Příručka pro vývojáře je navržena tak, aby vývojářům Salesforce pomohla seznámit se s objekty a parametry, které jsou potřebné pro integraci balíčku Salesforce se službou Adobe Acrobat Sign.

Témata tohoto dokumentu pokrývají:

• Pokyny pro vývojáře
• Pořadí aktualizací
• Služby Apex
• Služby rozhraní API
• Služby dávky Apex
• Dávku šablon dohod
• Dávku služeb šablon dohod
• Služby rozhraní REST
• Služby na pozadí
• Změny ve zpětné kompatibilitě

Pokyny pro vývojáře

• Pokud potřebujete vědět, kdy je dohoda plně podepsána, implementujte na objektu echosign_dev1__SIGN_Agreement__c spouštěč Apex, a to po aktualizaci nebo před ní (v závislosti na případu použití a požadavcích). Jakmile se pole echosign_dev1__Status__c změní na hodnotu Podepsáno, Schváleno nebo jiný konečný stav, je dohoda dokončena. 
• Pokud potřebujete vědět, kdy dojde ke vložení každého jednotlivého podepsaného PDF, například pokud potřebujete získat každé průběžně podepisované PDF, pak po vložení implementujte spouštěč Apex na objektech Attachment nebo ContentVersion a hledejte nadřazenou dohodu a název, který končí „- signed.pdf“, „- approved.pdf“ nebo jiným konečným stavem
• Pokud potřebujete vědět, kdy každý jednotlivý příjemce podepsal nebo schválil, implementujte spouštěč Apex na objektu echosign_dev1__SIGN_Recipients__c, a to po aktualizaci nebo před ní (v závislosti na případu použití a požadavcích). Jakmile se pole echosign_dev1__Status__c změní na hodnotu Podepsáno, Schváleno nebo jiný konečný stav, je příjemce dokončen.  
• Pokud potřebujete vědět, kdy nastane určitá událost, která je součástí procesu podepisování, například odeslání dohody k podpisu nebo odeslání připomenutí, lze na objektu událostí dohody (echosign_dev1__SIGN_AgreementEvent__c) vytvořit spouštěč a zkontrolovat typ události
• Názvy konečných stavů dohody pro dokončenou dohodu jsou: „Podepsáno“, „Schváleno“, „Přijato“, „Formulář vyplněn“ a „Doručeno“
  
• Názvy konečných stavů dohody pro ukončenou dohodu jsou: „Zrušeno/Odmítnuto“, „Platnost vypršela“

Pořadí aktualizací

Ve verzi v21 se pořadí aktualizací změnilo. Níže uvádíme pořadí, ve kterém se aktualizují dohody a jejich související objekty:

1. Přílohy 
2. Příjemci 
3. Dohoda (stav a její další atributy)
4. Události dohody 
5. Kanály služby Chatter 

Služby Apex

Použitá metoda Apex

Počínaje verzí Acrobat Sign pro Salesforce V 21.0 všechny asynchronní procesy (včetně automatických aktualizací a mapování dat) používají metodu Queueable namísto metody Future, jak doporučuje Salesforce.
S touto změnou všechny úlohy přizpůsobení, které jsou přidány do fronty Salesforce pro automatickou aktualizaci nebo proces mapování dat, selžou s touto chybou: „System.LimitException: Too many queueable jobs added to queue:2."

K chybě dochází proto, že proces zařaditelný do fronty může přidat pouze jednu podřízenou úlohu zařaditelnou do fronty, a toto místo je již obsazeno aplikací Acrobat Sign. Podrobnosti naleznete v části Limity metod Apex zařaditelných do fronty. 

Pokud se stav dohody nezmění nebo pokud mapování dat neproběhne správně, může se zobrazit tato chyba: „Při řetězení úloh lze pomocí System.enqueueJob přidat pouze jednu úlohu z prováděné úlohy, což znamená, že pro každou nadřazenou úlohu, kterou lze zařadit do fronty, může existovat pouze jedna podřízená úloha. Spuštění více podřízených úloh ze stejné úlohy zařaditelné do fronty není podporováno.“

Postup řešení této chyby: vyhledejte problematický spouštěč, tvůrce procesu nebo pracovní postup, a deaktivujte ho nebo přepněte na používání synchronního volání nebo jej naplánujte na později.

Služba šablony dohod

Služba šablony dohod je zpřístupněna jako globální služba Apex prostřednictvím spravovaného balíčku. To umožňuje kódu Apex mimo spravovaný balíček načítat dohody na základě existujících šablon dohod. Aby byl takový přístup možný, jsou třída a všechny zobrazené metody označeny jako globální.

Služba Apex je zpřístupněna prostřednictvím této třídy volání: echosign_dev1.AgreementTemplateService

Metody

 Konstruktory

Vlastnosti globální třídy

Proměnné běhového prostředí

Globální třída echosign_dev1.AgreementTemplateVariable má následující dvě globální pole:

• name: Název proměnné, který musí odpovídat názvu proměnné běhového prostředí nakonfigurované v šabloně dohody.
• value: Hodnota proměnné použitá při načítání šablony. Hodnota závisí na tom, kde byla proměnná použita. Například v případě příjemce se musí jednat o kontakt, lead nebo e-mail či ID záznamu uživatele. V případě proměnné dokumentu se musí jednat o ID záznamu přílohy.

Výsledek

Každá metoda buď vrátí ID nově vytvořeného záznamu dohody, nebo, pokud se při načítání něco pokazí, vypíše výjimku s podrobnou chybovou zprávou.

Služby rozhraní API

Služba šablony Adobe e-Sign API je zpřístupněna jako globální služba Apex prostřednictvím spravovaného balíčku. To umožňuje kódu Apex mimo spravovaný balíček vyvolat prostřednictvím těchto obálek sadu rozhraní API Adobe e-Sign. Obálky výrazně zjednodušují volání rozhraní API, protože uživatelé nemusí vytvářet datový model požadavku a odpovědi. Uživatelé rovněž nemusí zpracovávat transformaci dat Salesforce do datových modelů e-Sign. Od většiny složitostí je uživatel oproštěn. Například pro odeslání dohody uživatel pouze předá ID záznamu dohody a služba se postará o dotazování, extrakci všech relevantních dat, předání na API a analýzu výsledku.

Aby byl takový přístup možný, jsou třída a všechny zobrazené metody označeny jako globální.

• verze 17 a nižší vyvolává rozhraní SOAP API
• verze 18 a vyšší vyvolává rozhraní REST API

Služba Apex je zpřístupněna prostřednictvím následující třídy volání: echosign_dev1.EchoSignApiService

Vylepšení Apex API pro alternativní příjemce

U verze 24.14 nebo novější umožňuje aktualizované rozhraní Apex API nahradit nebo přidat alternativní příjemce a je přístupné v rámci globální třídy „EchoSignApiService“. Byly představeny dva nové prvky:

• Globální funkce:
  

  /**

  * Vstupní parametry:

  * toBeChangedRecipientId: SIGN_Recipient__c Id

  * newRecipientStr: JSON řetězec SIGN_Recipient__c nového příjemce pro náhradního nebo alternativního příjemce

  * changeType: REPLACE nebo ALTERNATE

  */

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

• Globální výčet: RECIPIENT_CHANGE_TYPE {REPLACE, ALTERNATE}

Ukázka kódu pro volání tohoto rozhraní API pro příjemce (typ příjemce jako E-mail)

// nejprve podejte dotaz na všechny příjemce přidružené k dohodě

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;

// vyhledejte příjemce, kterého je třeba nahradit, nebo jeho náhradníka

// v tomto případě vyhledejte příjemce podle jeho e-mailu.

// Pro vyhledání příjemce, který má být nahrazen nebo potřebuje náhradníka, lze přidat další podmínky.

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;

    }

}

// aktualizace e-mailové adresy nového příjemce

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

// serializace do řetězce json

String newRecipientStr = JSON.serialize(newRecipient);

Try {

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

} catch (Exception ex) {

    // zpracuje výjimku a v případě potřeby ji zopakuje

}

Metody

Vnitřní třídy

• Globální třída: DocumentHistoryEvent

• Globální třída: DocumentInfo
  

• Globální třída: ParticipantInfo

• Globální třída: SendDocumentResult

• Globální třída: SigningUrl
  

Služby dávky Apex

Zobrazuje hlavní akce dohody služby e-Sign na hromadné úrovni, což umožňuje provést operaci na sadě dohod. Tato třída implementuje rozhraní Salesforce Database.Batchable. Může zpracovat libovolný počet záznamů, které budou rozděleny do sad po 5 a každá sada bude zpracována jako samostatná transakce, což umožňuje dodržet limity správce služby.

Služba dávky Apex je zpřístupněna prostřednictvím následující třídy volání: echosign_dev1.EchoSignActionBatch

Parametry

Pro inicializaci dávkové operace je nutné zadat následující parametry:

• Seznam ID záznamů o dohodách, na kterých má být provedena zadaná akce: Akce může mít některou z následujících podporovaných hodnot: Remind, Send, Cancel, Delete nebo Update.
• ID aktuální uživatelské relace: Vyžadováno pouze pro akci typu update.
• Záznam uživatele odesílatele: Slouží k upozornění uživatele prostřednictvím e-mailu po dokončení hromadného zpracování.

Příklad použití

User submitterUser = UserInfo.getUserId();

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

Dávka šablon dohod

Přijímá dotaz SOQL a ID záznamu šablony dohody. Provedením dotazu se získá sada záznamů primárních objektů, z nichž každý je následně zpracován pomocí zadané šablony dohody, čímž se vytvoří záznam dohody. Tato třída implementuje rozhraní Salesforce Database.Batchable. Může zpracovat libovolný počet záznamů, které budou rozděleny do sad po 5 a každá sada bude zpracována jako samostatná transakce, což umožňuje dodržet limity správce služby.

Typy záznamů vrácené dotazem SOQL musí odpovídat zadanému typu primárního objektu šablony dohody. Pro každý záznam je vyvolána služba šablony dohody.

Služba dávky Apex je zpřístupněna prostřednictvím následující třídy volání:

echosign_dev1.AgreementTemplateBatch

Parametry

Pro inicializaci dávkové operace je nutné zadat následující parametry:

• SOQL dotaz, který se má provést: Musí obsahovat ID záznamu jako vybrané pole. Ostatní pole jsou volitelná.
• ID záznamu šablony dohody: Používá se spolu s ID primárního záznamu k načtení dohody.

Příklad použití

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);

Dávka služeb šablon dohod

Přijímá seznam ID záznamů primárních objektů a typ primárního objektu, které jsou následně dotazovány, a každý z nich je poté zpracován prostřednictvím poskytnuté šablony dohody, aby byl vygenerován záznam dohody. Tato třída implementuje rozhraní Salesforce Database.Batchable. Může zpracovat libovolný počet záznamů, které budou rozděleny do sad po 5 a každá sada bude zpracována jako samostatná transakce, což umožňuje dodržet limity správce služby.

Zadaný typ primárního objektu musí odpovídat zadanému typu primárního objektu šablony dohody. Pro každý záznam je vyvolána služba šablony dohody.

Služba dávky Apex je zpřístupněna prostřednictvím následující třídy volání:

echosign_dev1.AgreementTemplateServiceBatch

Parametry

Pro inicializaci dávkové operace je nutné zadat následující parametry:

• Seznam ID primárních záznamů.
• ID záznamu šablony dohody: Používá se spolu s primárními záznamy k načtení dohody.
• Název primárního objektu na dotaz pro primární záznamy.

Příklad použití

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);

Služby rozhraní REST

Služba šablony dohod

Služba šablony dohod je zpřístupněna jako webová služba Salesforce REST prostřednictvím spravovaného balíčku. To umožňuje externím systémům mimo organizaci Salesforce načítat dohody na základě existujících šablon dohod. Další podrobnosti o tom, jak přistupovat k vlastním službám Apex REST a vyvolávat je z prostředí Salesforce, najdete v článku Vytváření rozhraní REST API pomocí ApexREST. Vyvolání musí obsahovat platné ID relace pro účely ověření a autorizace.

Webová služba je zpřístupněna z následující adresy URL:

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

ID šablony

Poslední částí adresy URL je ID záznamu šablony dohody v aktuální organizaci Salesforce, který by měl být použit k načtení dohody. Tato část adresy URL je nepovinná. Pokud ji vynecháte, bude načtena šablona dohody označená jako výchozí. Pokud je ID šablony vynecháno a ID výchozí šablony dohody neexistuje, bude vrácena chyba.

ID šablony může být v 15 nebo 18znakovém formátu.

Primární ID

Parametr masterId určuje, který primární záznam má být použit pro načtení dohody z konkrétní šablony dohody. Tento parametr je nepovinný, ale musí být specifikován pro každou šablonu dohody, která určuje typ primárního objektu a v šabloně na tento primární objekt odkazuje.

Primární ID může být v 15 nebo 18znakovém formátu.

Proměnné běhového prostředí

Veškeré dodatečné parametry se používají jako proměnné běhového prostředí ve formě dvojic název-hodnota, které slouží k vyplnění všech proměnných běhového prostředí zadaných v šabloně dohody.

Výsledek

Webová služba REST vrací objekt LoadResult, který obsahuje následující pole:

• agreementId: Pokud byla operace načtení dohody úspěšná, obsahuje ID nově vytvořeného záznamu dohody.
• error: Pokud při načítání dohody došlo k nějaké chybě, bude toto pole obsahovat podrobnou chybovou zprávu.

Služba na pozadí

Pomocí služby na pozadí mohou uživatelé balíčku vyvolat různé akce na objektu dohody tak, že pole Background Action (echosign_dev1 Background_Actions c) aktualizují na odpovídající hodnotu. Jakmile je hodnota pole změněna z prázdné hodnoty nebo jiné hodnoty na jednu z následujících hodnot, je akce zahájena spouštěčem, který je součástí spravovaného balíčku e-Sign.

• Připomenout
• Odeslat
• Zrušit
• Odstranit
• Aktualizovat

Všechny akce se provedou v asynchronním režimu future, takže stav se v dohodě uloží do pole Error.

Změny ve zpětné kompatibilitě

Podobné

• Adobe Acrobat Sign pro Salesforce – Instalační příručka
• Adobe Acrobat Sign pro Salesforce – Příručka pro pokročilé přizpůsobení
• Adobe Acrobat Sign pro Salesforce – Mapování polí a šablony
• Adobe Acrobat Sign pro Salesforce – Příručka pro upgrade
• Adobe Acrobat Sign pro Salesforce – Příručka uživatele