Dieses Dokument ist für Salesforce-Entwickler vorgesehen und enthält die Objekte und Parameter, die zum Integrieren des Salesforce-Pakets mit Adobe Sign benötigt werden.

Vorsicht:

Achten Sie darauf, dass Adobe Sign für Salesforce Objekte sich ggf. in einer zukünftigen Version ändern können. 

Wenn Sie benutzerdefinierte Lösungen nutzen, die von diesen Objekten abhängig sind, müssen Sie diese Lösungen bei Änderungen der Objekte möglicherweise anpassen.

Best Practices zur Integration

  • 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

Updatereihenfolge

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 Version 21.x wurden alle asynchronen Prozesse (einschließlich automatischer Aktualisierungen und Datenzuordnungen) von der Future-Methode auf Queueable umgestellt. Dieser neue Ansatz wird von Salesforce empfohlen.

Aufgrund dieser Änderung schlagen alle Anpassungen in der Abonnentenorganisation, die im Rahmen der automatischen Aktualisierung und/oder Datenzuordnung Jobs zur Salesforce-Warteschlange hinzufügen, mit der Fehlermeldung „System.LimitException: Zu viele warteschlangenfähige Jobs zur Warteschlange hinzugefügt: 2“ fehl.

Dies geschieht, weil ein Warteschlangenprozess nur einen  untergeordneten, warteschlangenfähigen Job hinzufügen kann, der bereits von Adobe Sign belegt ist (siehe Abschnitt „Beschränkungen für Queueable Apex“).

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.“

Das Symptom dieses Fehlers ist, dass sich der Vereinbarungsstatus nicht ändert und/oder die Datenzuordnung nicht korrekt ausgeführt wird. 

Um diesen Fehler zu beheben, suchen Sie nach dem auslösenden Auslöser, Prozessgenerator oder Workflow und deaktivieren Sie ihn oder schalten Sie ihn um, sodass ein synchroner Anruf verwendet wird, oder planen Sie ihn in der Zukunft, z. B. 1 Stunde später.

In Version 21.x wurde die Apex-Methode von der Future-Methode in Queueable Apex geändert.

Kunden, die ihre Integrationen genutzt haben, um die Future-Methode zu verwenden, sollten ihren Code aktualisieren, um Queueable Apex zu verwenden, und diesen in ihrer Sandbox-Umgebung gründlich testen, bevor sie Version 21.x oder höher in der Live-Umgebung bereitstellen.


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

Hinweis:

 Das Laden einer Vereinbarungsvorlage mit eSign-Bibliotheksvorlagen wird derzeit nicht unterstützt. Verschieben Sie die Dokumentvorlagen in eine Salesforce-Dokumentenbibliothek.

 

Methoden

global

static Id load()

Lädt standardmäßig eine Vereinbarung, für die eine Vereinbarungsvorlage verwendet wird und für die kein Masterobjekttyp vorhanden ist.

global

static Id load(String templateId)

Lädt eine Vereinbarung, für die die angegebene Vereinbarungsvorlagen-ID verwendet wird und für die kein Masterobjekttyp vorhanden ist.

 

global

static Id load(String templateId, String masterId)

Lädt eine Vereinbarung, für die die angegebene Vorlagen-ID und die angegebene Masterdatensatz-ID verwendet wird und deren Typ mit dem Masterobjekttyp übereinstimmen muss, der in der angegebenen Vereinbarungsvorlage konfiguriert ist.

global

static Id load(String templateId, String masterId, Map<String,AgreementTemplateVariable> agreementTemplateVariables)

Lädt eine Vereinbarung, für die die angegebene Vorlagen-ID und die angegebene Masterdatensatz-ID verwendet wird und deren Typ mit dem Masterobjekttyp übereinstimmen muss, der in der angegebenen Vereinbarungsvorlage konfiguriert ist. Auch Durchgänge in den angegebenen Laufzeitvariablen als Name-Wert-Paare.

 

 

Laufzeitvariablen

Die globale Klasse „echosign_dev1.AgreementTemplateVariable“ hat zwei globale Felder.

  • name: Der Variablenname, der mit einem in der Vereinbarungsvorlage konfigurierten Laufzeitvariablennamen übereinstimmen muss.
  • value: Der Wert dieser Variable, der während des Ladens der Vorlage verwendet wird. Der Wert ist davon abhängig, wo die Variable verwendet wurde. Für einen Empfänger muss dies beispielsweise Kontakt, Lead oder eine Benutzerdatensatz-ID 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 aufgetreten ist.

API-Dienst

Der Adobe eSign-API-Vorlagendienst wird als globaler Apex-Dienst vom verwalteten Paket bereitgestellt. Dadurch kann ein Apex-Code außerhalb des verwalteten Pakets einen Satz mit Adobe eSign-APIs über diese Wrapper aufrufen. Die Wrapper vereinfachen den API-Aufruf deutlich, da Endbenutzer kein Anforderungs- und Antwortdatenmodell erstellen müssen. Zudem müssen sich die Endbenutzer nicht um die Konvertierung von Salesforce-Daten in eSign-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

Methoden

global

static void cancelDocument(Id agreementId)

Storniert die Vereinbarung mit der angegebenen Vereinbarungs-ID.

global

static void delegateSigner(Id agreementId, String delegatedEmail)

Delegieren Sie das Unterschreiben an die bereitgestellte E-Mail-Adresse.

global

static void delegateSigner(Id agreementId, String delegatedEmail, String message)

Delegieren Sie das Unterschreiben an die bereitgestellte E-Mail-Adresse mit der angegebenen Nachricht.

global

static echosign_dev1.EchoSignApiService.DocumentInfo getDocumentInfo(Id agreementId)

Ruft ausführliche Informationen für die angegebene Vereinbarungs-ID ab.

global

static List<EchoSignApiService.SigningUrl>

getSigningUrls(Id agreementId) 

Ruft alle signierenden URLs für die angegebene Vereinbarungs-ID ab.

global

static void removeDocument(Id agreementId)

Storniert die Vereinbarung mit der angegebenen Vereinbarungs-ID und löscht den Vereinbarungsdatensatz in Salesforce (die Vereinbarung wird nicht aus dem Adobe eSign-Konto entfernt).

global

static void replaceSigner(Id replacementRecipientId)

Ersetzt den angegebenen Unterzeichner.

global

static void replaceSigner(Id replacementRecipientId, String message)

Ersetzt den angegebenen Unterzeichner mit der angegebenen Meldung.

global

static echosign_dev1.EchoSignApiService.

SendDocumentResult sendDocument(Id agreementId)

Sendet die Vereinbarung mit der angegebenen Vereinbarungs-ID, gibt das Ergebnis mit dem Dokumentschlüssel und den URLs zurück.

global

static void sendReminder(Id agreementId)

Sendet eine Erinnerung an den aktuellen Unterzeichner für die angegebene Vereinbarungs-ID.

global static void updateAgreement(Id agreementId)  Aktualisiert die Vereinbarung mit der angegebenen Vereinbarungs-ID.

 

Innere Klassen

global class DocumentHistoryEvent

Eigenschaften (2)

Zugriff

Name

global

String eventType

global

String participantEmail

 

Konstruktoren (1)

Zugriff

Signatur

global

DocumentHistoryEvent()


global class DocumentInfo

Eigenschaften (5)

Zugriff

Name

global

Map<string,list> historyByEmail

global

Map participantsByEmail

global

Map participantsByName

global

String senderEmail

global

String status

 

Konstruktoren (1)

Zugriff

Signatur

global

DocumentInfo()

 

global class ParticipantInfo

Eigenschaften (5)

Zugriff

Name

global

String company

global

String email

global

String name

global

String status

global

String title

 

Konstruktoren (1)

Zugriff

Signatur

global

ParticipantInfo()

 

global class SendDocumentResult

Eigenschaften (3)

Zugriff

Name

global

String documentKey

global

Exception error

global

String url

 

Konstruktoren (1)

Zugriff

Signatur

global

SendDocumentResult()

 

global class SigningUrl

Eigenschaften (3)

Zugriff

Name

global

String email

global

String esignUrl

global

String simpleEsignUrl

 

Konstruktoren (1)

Zugriff

Signatur

Global

 

Apex-Batch-Dienste

Stellt die eSign-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

Die folgenden Parameter müssen angegeben werden, um einen Batchvorgang zu initialisieren.

Eine Liste der Vereinbarungsdatensatz-IDs, für die die angegebene Aktion ausgeführt werden soll. Die auszuführende Aktion, einer der folgenden unterstützten Werte:

  • Remind
  • Send
  • Cancel
  • Delete
  • Update

Aktuelle Benutzersitzungs-ID. Nur für einen Aktualisierungsaktionstyp erforderlich.

Benutzerdatensatz des Absenders, der für die Benachrichtigung dieses Benutzers per E-Mail verwendet wird, wenn die Massenverarbeitung abgeschlossen ist.

Anwendungsbeispiel

User submitterUser = UserInfo.getUserId();

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

 

Vereinbarungsvorlage 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

Die folgenden Parameter müssen angegeben werden, um einen Batchvorgang zu initialisieren.

Auszuführende SOQL-Frage, muss die Datensatz-ID als ausgewähltes Feld enthalten. Alle anderen Felder sind optional.

Vereinbarungsvorlagendatensatz-ID, die in Verbindung mit der Masterdatensatz-ID verwendet wird, 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); syncProcessId = Database.executeBatch(batch, 5);

 

Vereinbarungsvorlage Dienst-Batch

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

Die folgenden Parameter müssen angegeben werden, um einen Batchvorgang zu initialisieren.

  • Liste der Masterdatensatz-IDs.
  • Vereinbarungsvorlagendatensatz-ID, die in Verbindung mit den Masterdatensätzen verwendet wird, 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');
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

Hinweis:

  • Der Instanzname variiert je nach Organisationsinstanz.
  • https://_<instance_name>_.salesforce.com/services/apexrest/echosign_dev1/template/load/<template_id> ist eine POST-HTTP-Methode für Paketversionen 20.0 und höher.
    • Versionen vor v20 verwenden eine GET-Methode.

 

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 von eSign verwalteten 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

  • Der Vereinbarungsstatus wird jetzt aktualisiert, nachdem die Dokumente und Empfänger aktualisiert wurden.
    • Vor Version 21 wurde der Status vorher festgelegt.
  • Das Objekt „Signed Agreement“ (in dem die Bild-URLs gespeichert werden) wird jetzt gar nicht mehr eingefügt.
    • Vor Version 21 wurde es eingefügt, nachdem alle anderen Updates abgeschlossen waren.
  • Die maximale Größe einer Callout-Anfrage oder -Antwort beträgt 12 MB für asynchrones Apex nach Salesforce-Beschränkungen: https://developer.salesforce.com/docs/atlas.en-us.210.0.apexcode.meta/apexcode/apex_gov_limits.htm
    • Dokumente mit mehr als 12 MB werden aufgrund des Limits nicht von Sign abgerufen.
  • Die Ereignisbeschreibungen für Vereinbarungen haben sich geändert. Sie entsprechen jetzt den Beschreibungen, die von der Sign-API zurückgegeben bzw. in den Audit-Berichten aufgeführt werden.
  • Der Updateprozess wird jetzt als nativer Apex-Batch-Prozess (ein asynchroner Prozess) in Salesforce ausgeführt.
    • Zuvor erfolgten Updates über API-Aufrufe außerhalb von Salesforce.
    • Die Auslöser dieser Statusupdates, die die asynchronen Prozesse in Gang bringen, funktionieren nicht mehr, da Salesforce Aufrufe eines anderen asynchronen Prozesses als der bereits laufende nicht erlaubt.
  • Vor Version 21 wurden Updates der Vereinbarungsattribute auf separate Updateaufrufe aufgeteilt. Jetzt wird das Vereinbarungsobjekt in nur einer Transaktion aktualisiert.
  • Vor Version 21 konnten fehlgeschlagene Vereinbarungen nur durch manuelle Updates aus Salesforce heraus abgerufen werden.
    • Updates sind jetzt zuverlässiger, da das Sign-Backend fehlgeschlagene Ereignisse so oft erneut versucht, wie festgelegt.
  • Manuelle Updates umfassen jetzt alle Aspekte der Vereinbarungen, einschließlich zugehöriger Objekte.
  • Push-Vereinbarungen werden jetzt im asynchronen Modus ausgeführt und es werden zusätzliche Attribute aktualisiert – ganz wie bei regulären Updates.
  • Es sind neue Einstellungen verfügbar, um Updates der verschiedenen Vereinbarungsattribute zu (de-)aktivieren.
  • Wenn ein signiertes PDF-Dokument in Salesforce gespeichert wird, kann kein Deskriptor (signiert oder genehmigt) mehr am Ende des PDF-Dateinamens angehängt werden.