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

Adobe Acrobat Sign für Salesforce: Handbuch für Entwicklung soll Salesforce-Entwickler*innen dabei helfen, mehr über die Objekte und Parameter zu erfahren, die für die Integration von Adobe Acrobat Sign in ihr Salesforce-Paket erforderlich sind.

• 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 Acrobat Sign für Salesforce V 21.0 wurden alle asynchronen Prozesse (einschließlich automatischer Aktualisierungen und Datenzuordnungen) von  Future-Methoden auf Queueable-Methoden umgestellt. Dieses Vorgehen wird von Salesforce empfohlen.

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

Der Fehler tritt auf, weil ein Queuable-Prozess nur einen untergeordneten Queueable-Job hinzufügen kann. Diesen Slot nimmt bereits Acrobat Sign ein. Weitere Informationen finden Sie unter Queueable Apex-Beschränkungen.

Fehler: „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 Queueable-Job nur ein untergeordneter Job vorhanden sein kann. Das Starten mehrerer untergeordneter Jobs aus demselben Queueable-Job wird nicht unterstützt.“

Der oben genannte Fehler tritt auf, wenn sich der Vereinbarungsstatus nicht ändert oder die Datenzuordnung nicht ordnungsgemäß 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 Aufruf verwendet wird, oder planen Sie 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 (1)

global class AgreementTemplateService.AgreementTemplateListOptions

Eingenschaften (5)

global class AgreementTemplateService.AgreementTemplateBasicInfo

Eigenschaften (6)

global class AgreementTemplateService.AgreementTemplateDetails

Eigenschaften (6)

global class AgreementTemplateService.RecipientInfo

Eigenschaften (4)

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

Methoden

Innere Klassen

global class DocumentHistoryEvent

Eigenschaften (2)

Konstruktoren (1)

global class DocumentInfo

Eigenschaften (5)

  Konstruktoren (1)

global class ParticipantInfo

Eigenschaften (5)

  Konstruktoren (1)

global class SendDocumentResult

Eigenschaften (3)

Konstruktoren (1)

global class SigningUrl

Eigenschaften (3)

Konstruktoren (1)

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

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

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

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

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