Adobe Acrobat Sign für Salesforce: Handbuch für Entwicklung

Überblick

Adobe Acrobat Sign für Salesforce: Entwicklungshandbuch soll Salesforce-Entwicklerinnen und -Entwicklern dabei helfen, mehr über die Objekte und Parameter zu erfahren, die für die Integration von Adobe Acrobat Sign im Salesforce-Paket erforderlich sind.

Unter den Themen in diesem Dokument findest du Informationen zu:

• Richtlinien für Entwicklerinnen und Entwickler
• Aktualisierungsreihenfolge
• Apex-Dienste
• API-Dienste
• Apex-Batch-Dienste
• Vereinbarungsvorlagen-Batch
• Service-Batch für Vereinbarungsvorlagen
• REST-Dienste
• Hintergrunddienste
• Änderungen bei der Abwärtskompatibilität

Richtlinien für Entwicklerinnen und Entwickler

• Wenn Sie die Information benötigen, dass eine Vereinbarung vollständig unterzeichnet wurde, implementieren Sie einen Apex-Auslöser im Objekt echosign_dev1__SIGN_Agreement__c nach oder vor dem Update (je nach Anwendungsfall und Anforderungen). Wenn das Feld echosign_dev1__Status__c zu Signed oder Approved oder einem anderen finalen Status geändert wird, ist die Vereinbarung abgeschlossen. 
• Wenn Sie die Information benötigen, dass die unterzeichneten PDFs der einzelnen Beteiligten eingefügt wurden – weil Sie beispielsweise die jeweiligen Zwischenversionen der PDF abrufen müssen –, können Sie nach dem Einfügen einen Apex-Auslöser in den Objekten „Attachment“ oder „ContentVersion“ implementieren und auf eine übergeordnete Vereinbarung mit einem Namen hin prüfen, der auf „-signed.pdf“, „-approved.pdf“ oder einen anderen finalen Status endet.
• Wenn Sie die Information benötigen, dass ein einzelner Empfänger die Vereinbarung unterzeichnet oder genehmigt hat, implementieren Sie einen Apex-Auslöser im Objekt echosign_dev1__SIGN_Recipients__c nach oder vor dem Update (je nach Anwendungsfall und Anforderungen). Wenn das Feld echosign_dev1__Status__c zu Signed oder Approved oder einem anderen finalen Status geändert wird, ist der Empfänger abgeschlossen.  
• Wenn Sie die Information benötigen, dass ein bestimmtes Ereignis aufgetreten ist, das Teil des Unterzeichnungsprozesses ist, wie z. B. eine Vereinbarung, die zum Unterschreiben gesendet wurde, oder eine Erinnerung, können Sie einen Auslöser im Ereignisobjekt der Vereinbarung (echosign_dev1__SIGN_AgreementEvent__c) erstellen und auf den entsprechenden Ereignistyp hin prüfen.
• Die finalen Vereinbarungsstatus lauten: Signed, Approved, Accepted, Form-Filled und Delivered
  
• Die finalen Vereinbarungsstatus für beendete Vereinbarungen lauten: Cancelled/Declined, Canceled/Declined, Expired

Aktualisierungsreihenfolge

In Version 21 wurde die Reihenfolge der Updates geändert. Im Folgenden finden Sie die Reihenfolge, in der die Vereinbarung und die zugehörigen Objekte aktualisiert werden:

1. Anlagen 
2. Empfänger 
3. Vereinbarung (Status und andere Attribute)
4. Vereinbarungsereignisse 
5. Chatter-Feeds 

Apex-Dienste

Apex-Methode wird verwendet

Ab Acrobat Sign für Salesforce V 21.0 verwenden alle asynchronen Prozesse (einschließlich automatischer Updates und Datenmappings) die Queueable-Methode anstelle der Future-Methode, wie von Salesforce empfohlen.
Mit dieser Änderung werden alle Anpassungsaufträge, die zur Salesforce-Warteschlange für automatische Updates oder Daten-Mapping-Prozesse hinzugefügt werden, mit diesem Fehler fehlschlagen: „System.LimitException: Too many queueable jobs added to queue:2."

Der Fehler tritt auf, weil ein warteschlangenfähiger Prozess nur einen untergeordneten warteschlangenfähigen Job hinzufügen kann, der bereits von Acrobat Sign beegt ist. Weitere Informationen finden sich unter Beschränkungen für Queueable Apex. 

Wenn sich der Vereinbarungsstatus nicht ändert oder die Datenzuordnung nicht ordnungsgemäß ausgeführt wird, wird möglicherweise der folgende Fehler angezeigt: Wenn Sie Jobs verketten, können Sie nur einen Job aus einem ausgeführten Job mit „System.enqueueJob“ hinzufügen. Das bedeutet, dass für jeden übergeordneten, warteschlangenfähigen Job nur ein untergeordneter Job vorhanden sein kann. Das Starten mehrerer untergeordneter Jobs aus demselben warteschlangenfähigen Job wird nicht unterstützt.

Um diesen Fehler zu beheben, suche nach dem auslösenden Auslöser, Prozessgenerator oder Workflow und deaktiviere ihn oder schalte ihn um, sodass ein synchroner Aufruf verwendet wird, oder plane ihn für später ein.

Vereinbarungsvorlagendienst

Der Vereinbarungsvorlagendienst wird als globaler Apex-Dienst vom verwalteten Paket bereitgestellt. Dadurch können mithilfe des Apex-Codes außerhalb des verwalteten Pakets Vereinbarungen basierend auf vorhandenen Vereinbarungsvorlagen geladen werden. Die Klasse und alle bereitgestellten Methoden werden als global markiert, um einen derartigen Zugriff zu gewähren.

Der Apex-Dienst wird durch die folgende Aufrufklasse bereitgestellt: echosign_dev1.AgreementTemplateService.

Methoden

 Konstruktoren

Eigenschaften der globalen Klasse

Laufzeitvariablen

Die globale Klasse echosign_dev1.AgreementTemplateVariable hat zwei globale Felder:

• name: der Variablenname, der mit einem in der Vereinbarungsvorlage konfigurierten Laufzeitvariablennamen übereinstimmen muss.
• Wert: der beim Laden der Vorlage verwendete Variablenwert. Der Wert ist davon abhängig, wo die Variable verwendet wurde. Für eine empfangende Partei muss dies beispielsweise ein Kontakt, Lead oder eine Datensatz-ID der nutzenden Person oder eine E-Mail sein. Bei einer Dokumentenvariable muss dies die ID eines Anhangsdatensatzes sein.

Ergebnis

Die einzelnen Methoden geben entweder die ID des neu erstellten Vereinbarungsdatensatzes zurück oder lösen eine Ausnahme mit einer ausführlichen Fehlermeldung aus, wenn während des Ladevorgangs ein Fehler auftritt.

API-Dienste

Der e-Signieren-API-Vorlagendienst von Adobe wird als globaler Apex-Dienst vom verwalteten Paket bereitgestellt. Dadurch kann ein Apex-Code außerhalb des verwalteten Pakets einen Satz mit e-Signieren-APIs von Adobe über diese Wrapper aufrufen. Die Wrapper vereinfachen den API-Aufruf deutlich, da Endbenutzer*innen kein Anforderungs- und Antwortdatenmodell erstellen müssen. Zudem müssen sich die Endbenutzer*innen nicht um die Konvertierung von Salesforce-Daten in e-Signieren-Datenmodelle kümmern. Ein Großteil der Komplexität wird dem Endbenutzer abgenommen. Zum Senden einer Vereinbarung übergibt der Endverbraucher beispielsweise einfach die ID des Vereinbarungsdatensatzes. Der Dienst kümmert sich um die Abfrage, die Extrahierung aller relevanten Daten, die Weiterleitung an die API und um die Ergebnisanalyse.

Die Klasse und alle bereitgestellten Methoden werden als global markiert, um einen derartigen Zugriff zu gewähren.

• v17 und früher ruft SOAP-APIs auf
• v18 und höher ruft REST-APIs auf

Der Apex-Dienst wird durch die folgende Aufrufklasse bereitgestellt: echosign_dev1.EchoSignApiService

Apex-API-Erweiterung für alternative Empfangende

Ab Version 24.14 kannst du mit der aktualisierten Apex-API alternative Empfangende ersetzen oder hinzufügen und der Zugriff erfolgt innerhalb der globalen Klasse „EchoSignApiService“. Es wurden zwei neue Elemente eingeführt:

• Eine globale Funktion:
  

  /**

  * Eingabeparameter:

  * toBeChangedRecipientId: SIGN_Recipient__c Id

  * newRecipientStr: JSON-Zeichenfolge von SIGN_Recipient__c einer neuen empfangenden Partei zum Ersetzen der empfangenden Partei oder als Alternative

  * changeType: REPLACE oder ALTERNATE

  */

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

• Eine globale Enumeration: RECIPIENT_CHANGE_TYPE {REPLACE, ALTERNATE}

Beispielcode zum Aufrufen dieser API für Empfangende (Typ der empfangenden Partei als E-Mail)

// zunächst alle mit der Vereinbarung verbundenen Empfangenden abfragen

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;

// die zu ersetzende empfangende Partei oder eine alternative Partei suchen

// in diesem Fall die empfangende Partei anhand deren E-Mail-Adresse suchen.

// Es können weitere Bedingungen hinzugefügt werden, um die empfangende Partei zu finden, die ersetzt werden soll oder die eine Alternative benötigt.

for(SIGN_Recipients__c recipient: recipients) {

    if (rep.echosign_dev1__Email_Address__c == 'einePerson@beispiel.com') {

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

         replacedRecipient = recipient;

    }

}

// E-Mail-Adresse für neue empfangende Partei aktualisieren

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

// in eine JSON-Zeichenfolge serialisieren

String newRecipientStr = JSON.serialize(newRecipient);

Try {

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

} catch (Exception ex) {

    // Ausnahme behandeln und bei Bedarf neu auslösen

}

Methoden

Innere Klassen

• Globale Klasse: DocumentHistoryEvent

• Globale Klasse: DocumentInfo
  

• Globale Klasse: ParticipantInfo

• Globale Klasse: SendDocumentResult

• Globale Klasse: SigningUrl
  

Apex-Batch-Dienste

Stellt die e-Signieren-Hauptaktionen für Vereinbarungen auf Massenebene bereit und ermöglicht somit die Ausführung eines Vorgangs für eine Reihe von Vereinbarungen. Diese Klasse implementiert die Salesforce-Schnittstelle Database.Batchable. Dabei kann eine beliebige Anzahl Datensätze verarbeitet werden, die in 5er-Gruppen aufgeteilt werden. Jede Gruppe wird als individuelle Transaktion verarbeitet, wodurch Kontrollgrenzen respektiert werden können.

Der Apex-Batchdienst wird durch die folgende Aufrufklasse bereitgestellt: echosign_dev1.EchoSignActionBatch

Parameter

Du musst die folgenden Parameter angeben, um einen Batchvorgang zu initialisieren:

• Eine Liste der Vereinbarungsdatensatz-IDs, für die die angegebene Aktion ausgeführt werden soll: Die Aktion kann einen der folgenden unterstützten Werte aufweisen: Erinnern, Senden, Abbrechen, Löschen oder Aktualisieren.
• Aktuelle Benutzendensitzungs-ID: nur für den Aktionstyp „Aktualisierung“ erforderlich.
• Benutzendendatensatz der absendenden Partei: wird für die Benachrichtigung der Benutzerin oder des Benutzers per E-Mail verwendet, wenn die Massenverarbeitung abgeschlossen ist.

Anwendungsbeispiel

User submitterUser = UserInfo.getUserId();

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

Vereinbarungsvorlagen-Batch

Verwendet eine SOQL-Abfrage und eine Vereinbarungsvorlagendatensatz-ID. Die Abfrage wird ausgeführt, um einen Satz mit Masterobjektdatensätzen zu erhalten, von denen dann jeder durch die bereitgestellte Vereinbarungsvorlage ausgeführt wird, um einen Vereinbarungsdatensatz zu generieren. Diese Klasse implementiert die Salesforce-Schnittstelle Database.Batchable. Dabei kann eine beliebige Anzahl Datensätze verarbeitet werden, die in 5er-Gruppen aufgeteilt werden. Jede Gruppe wird als individuelle Transaktion verarbeitet, wodurch Kontrollgrenzen respektiert werden können.

Die von der SOQL-Abfrage zurückgegebenen Datensatztypen müssen mit dem bereitgestellten Masterobjekttyp der Vereinbarungsvorlage übereinstimmen. Der Vereinbarungsvorlagendienst wird für alle Datensätze aufgerufen.

Der Apex-Batchdienst wird durch die folgende Aufrufklasse bereitgestellt:

echosign_dev1.AgreementTemplateBatch

Parameter

Du musst die folgenden Parameter angeben, um einen Batchvorgang zu initialisieren:

• Auszuführende SOQL-Abfrage: muss die Datensatz-ID als ausgewähltes Feld enthalten. Andere Felder sind optional.
• Vereinbarungsvorlagendatensatz-ID: wird in Verbindung mit der ID des primären Datensatzes verwendet, um eine Vereinbarung zu laden.

Anwendungsbeispiel

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

Service-Batch für Vereinbarungsvorlagen

Verwendet eine Liste mit Masterobjektdatensatz-IDs und den Masterobjekttyp, die dann abgefragt werden, und von denen jede bzw. jeder die bereitgestellte Vereinbarungsvorlage durchläuft, um einen Vereinbarungsdatensatz zu generieren. Diese Klasse implementiert die Salesforce-Schnittstelle Database.Batchable. Dabei kann eine beliebige Anzahl Datensätze verarbeitet werden, die in 5er-Gruppen aufgeteilt werden. Jede Gruppe wird als individuelle Transaktion verarbeitet, wodurch Kontrollgrenzen respektiert werden können.

Der bereitgestellte Masterobjekttyp muss mit dem bereitgestellten Masterobjekttyp für die Vereinbarungsvorlage übereinstimmen. Der Vereinbarungsvorlagendienst wird für alle Datensätze aufgerufen.

Der Apex-Batchdienst wird durch die folgende Aufrufklasse bereitgestellt:

echosign_dev1.AgreementTemplateServiceBatch

Parameter

Du musst die folgenden Parameter angeben, um einen Batchvorgang zu initialisieren:

• Liste der Masterdatensatz-IDs.
• Vereinbarungsvorlagendatensatz-ID: wird in Verbindung mit den Masterdatensätzen verwendet, um eine Vereinbarung zu laden.
• Masterobjektname für die Abfrage der Masterdatensätze.

Anwendungsbeispiel

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

REST-Dienste

Vereinbarungsvorlagendienst

Der Vereinbarungsvorlagendienst wird als globaler Salesforce REST-Webdienst vom verwalteten Paket bereitgestellt. Dadurch können mithilfe von externen Systemen außerhalb der Salesforce-Organisation Vereinbarungen basierend auf vorhandenen Vereinbarungsvorlagen geladen werden. Weitere Einzelheiten zum Zugreifen auf und Aufrufen von benutzerdefinierten REST-Apex-Diensten aus Salesforce finden Sie im Artikel Erstellen von REST-APIs mit Apex REST. Bei den Aufrufen muss eine gültige Sitzungs-ID für die Authentifizierung und Autorisierung bereitgestellt werden.

Der Webdienst wird unter der folgenden URL bereitgestellt:

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

Vorlagen-ID

Der letzte Teil der URL ist die ID des Vereinbarungsvorlagendatensatzes in der aktuellen Salesforce-Organisation, die zum Laden der Vereinbarung verwendet werden soll. Dieser Teil der URL ist optional. Wird sie ausgelassen, wird die als Standard markierte Vereinbarungsvorlage geladen. Wenn die Vorlagen-ID ausgelassen wird und keine Standard-Vereinbarungsvorlagen-ID vorhanden ist, wird ein Fehler zurückgegeben.

Die Vorlagen-ID kann im Format mit 15 oder 18 Zeichen vorliegen.

Master-ID

Der Parameter masterId gibt an, welcher Masterdatensatz zum Laden der Vereinbarung aus der angegebenen Vereinbarungsvorlage verwendet werden soll. Dieser Parameter ist zwar optional, er muss jedoch für die Vereinbarungsvorlage angegeben werden, die einen Masterobjekttyp spezifiziert und dieses Masterobjekt in der Vorlage referenziert.

Die Master-ID kann im Format mit 15 oder 18 Zeichen vorliegen.

Laufzeitvariablen

Zusätzliche Parameter werden als Laufzeitvariablen in Form von Name-Wert-Paaren verwendet, um die in der Vereinbarungsvorlage angegebenen Laufzeitvariablen zu füllen.

Ergebnis

Der REST-Webdienst gibt ein LoadResult-Objekt zurück, das die folgenden Felder enthält:

• agreementId: Wenn die Vereinbarung erfolgreich geladen wurde, enthält diese die ID des neu erstellten Vereinbarungsdatensatzes.
• error: Wenn während des Ladens der Vereinbarung ein Fehler aufgetreten ist, enthält dieses Feld eine detaillierte Fehlermeldung.

Hintergrunddienst

Die Funktion für den Hintergrunddienst ermöglicht Paketbenutzern das Aufrufen verschiedener Aktionen für ein Vereinbarungsobjekt, indem das Feld „Hintergrundaktion“ (echosign_dev1 Background_Actions c) auf den entsprechenden Wert aktualisiert wird. Sobald der Feldwert aus einem leeren Wert oder einem anderen Wert in einen der folgenden Werte geändert wird, wird die Aktion von einem Auslöser gestartet, der Teil des verwalteten e-Signieren-Pakets ist.

• Remind
• Send
• Cancel
• Delete
• Update

Alle Aktionen werden in einem asynchronen künftigen Modus ausgeführt, sodass der Status im Fehlerfeld der Vereinbarung gespeichert wird.

Änderungen bei der Abwärtskompatibilität

Ähnliche Themen

• Adobe Acrobat Sign für Salesforce – Installationshandbuch
• Adobe Acrobat Sign für Salesforce – Erweitertes Anpassungshandbuch
• Adobe Acrobat Sign für Salesforce – Feldzuordnung und Vorlagen
• Adobe Acrobat Sign für Salesforce – Upgrade-Handbuch
• Adobe Acrobat Sign für Salesforce – Benutzerhandbuch