Adobe Acrobat Sign voor Salesforce: handleiding voor ontwikkelaars

Adobe Acrobat Sign for Salesforce: handleiding voor ontwikkelaars is ontworpen om Salesforce-ontwikkelaars te helpen meer te weten te komen over de objecten en parameters die nodig zijn om uw Salesforce-pakket te integreren met Adobe Acrobat Sign.

Zie de onderwerpen over dit document om meer te leren over het volgende:

• Ontwikkelaarsrichtlijnen
• Volgorde bijwerken
• Apex-services
• API-services
• Apex-batchservices
• Batch overeenkomstsjablonen
• Batch overeenkomstsjabloonservice
• REST-services
• Achtergrondservices
• Wijzigingen in achterwaartse compatibiliteit

• Als u wilt weten wanneer de overeenkomst volledig is ondertekend, implementeert u een Apex-trigger op het object echosign_dev1__SIGN_Agreement__c, na of vóór de update (afhankelijk van het gebruiksscenario en de vereisten). Wanneer het veld echosign_dev1__Status__c verandert naar Ondertekend of Goedgekeurd of een andere definitieve status, is de overeenkomst voltooid. 
• Als u wilt weten wanneer elke afzonderlijke ondertekende PDF wordt ingevoegd, bijvoorbeeld als u elke ondertekende PDF wilt ontvangen, voert u na het invoegen een Apex-trigger uit op de Bijlagen of ContentVersion-objecten en zoekt u naar een bovenliggende overeenkomst en een naam die eindigt op "- signed.pdf" of "-approved.pdf" of een andere definitieve status
• Als u wilt weten wanneer een individuele ontvanger heeft ondertekend of goedgekeurd, implementeert u een Apex-trigger op het object echosign_dev1__SIGN_Recipients__c, na of vóór de update (afhankelijk van het gebruiksscenario en de vereisten). Wanneer het veld echosign_dev1__Status__c de status Ondertekend, Goedgekeurde of een andere definitieve status wijzigt, is de ontvanger voltooid.
• Als u wilt weten wanneer een bepaalde gebeurtenis plaatsvindt die deel uitmaakt van het ondertekeningsproces, zoals een overeenkomst die ter ondertekening wordt verzonden of een herinnering die wordt verzonden, kunt u een trigger maken voor het contractgebeurtenissenobject (echosign_dev1__SIGN_AgreementEvent __c) en controleren op het type gebeurtenis
• De definitieve overeenkomststatusnamen voor een voltooide overeenkomst zijn: Ondertekend, Goedgekeurd, Geaccepteerd, Formulier ingevuld en Geleverd
  
• De definitieve overeenkomststatusnamen voor een beëindigde overeenkomst zijn: Geannuleerd/Geweigerd, Verlopen

Volgorde van updates

In v21 is de volgorde van updates veranderd. Hieronder ziet u de volgorde waarin de overeenkomst en de bijbehorende objecten worden bijgewerkt:

1. Bijlagen 
2. Ontvangers 
3. Overeenkomst (status en andere kenmerken)
4. Overeenkomstgebeurtenissen 
5. Chatter-feeds 

Apex-services

Gebruikte Apex-methode

Vanaf Acrobat Sign for Salesforce v 21.0 gebruiken alle asynchrone processen (inclusief automatische updates en gegevenstoewijzingen) de Queueable-methode in plaats van de Future-methode, zoals aanbevolen door Salesforce.
Met deze wijziging mislukken alle aanpassingstaken die voor het automatisch bijwerken of toewijzen van gegevens aan de Salesforce-wachtrij worden toegevoegd, met deze fout: "System.LimitException: Too many queueable jobs added to queue:2."

De fout treedt op omdat een queueable proces slechts één onderliggende queueable taak kan toevoegen, die al wordt opgepakt door Acrobat Sign. Raadpleeg Queuable Apex-limieten voor meer informatie.

Als de overeenkomststatus niet verandert of de gegevenstoewijzing niet correct wordt uitgevoerd, wordt mogelijk deze fout weergegeven: "Wanneer u taken koppelt, kunt u slechts één taak van een lopende taak toevoegen met System.enqueueJob. Dit betekent dat er slechts één onderliggende taak kan bestaan voor elke bovenliggende queueable taak. Er is geen ondersteuning voor het starten van meerdere onderliggende taken van dezelfde queueable taak."

Om deze fout op te lossen moet u nagaan welke trigger, process builder of workflow de fout veroorzaakt en deze deactiveren of omschakelen naar een synchrone aanroep of op een later moment plannen.

Overeenkomstsjabloonservice

De overeenkomstsjabloonservice wordt door het beheerde pakket weergegeven als een globale Apex-service. Hierdoor kan Apex-code buiten het beheerde pakket gebruikt worden om overeenkomsten te laden op basis van bestaande overeenkomstsjablonen. De klasse en alle weergegeven methoden zijn gemarkeerd als globaal om een dergelijke toegang toe te staan.

De Apex-service wordt weergegeven via de volgende aanroepklasse: echosign_dev1.AgreementTemplateService

Methoden

 Constructors

Algemene klasse-eigenschappen

Runtimevariabelen

De globale klasse echosign_dev1.AgreementTemplateVariable bevat de volgende twee globale velden:

• name: de naam van de variabele, die moet overeenkomen met de naam van een runtimevariabele die is geconfigureerd in de overeenkomstsjabloon.
• value: de waarde van de variabele die wordt gebruikt tijdens het laden van de sjabloon. De waarde is afhankelijk van waar de variabele is gebruikt. Voor een ontvanger moet het bijvoorbeeld een contact-, lead- of gebruikersrecord-ID of een e-mail zijn. Voor een documentvariabele moet het een bijlagerecord-ID zijn.

Resultaat

Elke methode retourneert de ID van de nieuw gemaakte overeenkomstrecord of geeft een uitzondering met een gedetailleerd foutbericht weer als er iets is misgegaan tijdens het laden.

API-services

De Adobe API-sjabloonservice voor elektronisch ondertekenen wordt door het beheerde pakket weergegeven als een globale Apex-service. Hierdoor kan Apex-code buiten het beheerde pakket een set Adobe API's voor elektronisch ondertekenen aanroepen via deze wrappers. De wrappers vereenvoudigen de API-aanroep aanzienlijk, omdat consumenten geen aanvraag- en antwoordgegevensmodel hoeven te maken. Ook hoeven consumenten de transformatie van Salesforce-gegevens naar gegevensmodellen van elektronisch ondertekenen niet te verwerken. Het grootste deel van de complexiteit wordt losgemaakt van de consument. Om bijvoorbeeld een overeenkomst te verzenden die de consument gewoon in de overeenkomstrecord-ID doorgeeft, zal de service een query uitvoeren, alle relevante gegevens extraheren, deze op de API doorgeven en het resultaat parseren.

De klasse en alle weergegeven methoden zijn gemarkeerd als globaal om een dergelijke toegang toe te staan.

• v17 en lager roept SOAP-API's aan
• v18 en hoger roept REST-API's aan

De Apex-service wordt weergegeven via de volgende aanroepklasse: echosign_dev1.EchoSignApiService

Verbetering van Apex-API voor alternatieve ontvangers

Vanaf versie 24.14 of hoger kunt u met de bijgewerkte Apex-API alternatieve ontvangers vervangen of toevoegen. Deze API is toegankelijk binnen de globale klasse EchoSignApiService. Er zijn twee nieuwe elementen geïntroduceerd:

• Een globale functie:
  

  /**

  * Invoerparameters:

  * toBeChangedRecipientId: SIGN_Recipient__c Id

  * newRecipientStr: JSON string of SIGN_Recipient__c of a new recipient for recipient replacement or alternate

  * changeType: REPLACE or ALTERNATE

  */

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

• Een globale opsomming: RECIPIENT_CHANGE_TYPE {REPLACE, ALTERNATE}

Voorbeeldcode om deze API voor ontvangers aan te roepen (type ontvanger als e-mail)

// first query all the recipients associated with the agreement

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;

// find the recipient that needs to be replaced or an alternate

// in this case, find the recipient by its email.

// More conditions can be added to find the recipient that is to be replaced or needs an alternate.

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;

    }

}

// update emal address for new recipient

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

// serialize it to json string

String newRecipientStr = JSON.serialize(newRecipient);

Try {

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

} catch (Exception ex) {

    // handle the exception and rethrow if needed

}

Methoden

Inner Classes

• Global Class: DocumentHistoryEvent

• Global Class: DocumentInfo
  

• Global Class: ParticipantInfo

• Global Glass: SendDocumentResult

• Global Class: SigningUrl
  

Apex-batchservices

Toont de belangrijkste acties voor elektronische ondertekening van de overeenkomst op bulkniveau, waardoor een bewerking kan worden uitgevoerd op basis van een reeks overeenkomsten. Deze klasse implementeert de Salesforce Database.Batchable-interface. Deze kan elk aantal records verwerken. Deze worden onderverdeeld in sets van 5 en elke set wordt als een individuele transactie verwerkt, waardoor de governorslimieten kunnen worden gerespecteerd.

De Apex batch-service wordt weergegeven via de volgende aanroepklasse: echosign_dev1.EchoSignActionBatch

Parameters

U moet de volgende parameters opgeven om een batchbewerking te initialiseren:

• Een lijst met de overeenkomstrecord-ID's waarop de opgegeven actie moet worden uitgevoerd: De actie kan een van de volgende ondersteunde waarden hebben: Herinneren, Verzenden, Annuleren, Verwijderen of Bijwerken.
• Huidige gebruikerssessie-ID: alleen vereist voor een type actie voor updates.
• Gebruikersrecord van indiener: wordt gebruikt om deze gebruiker via een e-mail op de hoogte te stellen zodra de bulkverwerking is voltooid.

Voorbeeld van gebruik

User submitterUser = UserInfo.getUserId();

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

Batch overeenkomstsjablonen

Neemt een SOQL-query en een record-ID voor een overeenkomstsjabloon op. De query wordt uitgevoerd om een set van hoofdobjectrecords te verkrijgen, die vervolgens door de meegeleverde overeenkomstsjabloon worden uitgevoerd om een overeenkomstrecord te genereren. Deze klasse implementeert de Salesforce Database.Batchable-interface. Deze kan elk aantal records verwerken. Deze worden onderverdeeld in sets van 5 en elke set wordt als een individuele transactie verwerkt, waardoor de governorslimieten kunnen worden gerespecteerd.

De recordtypen die worden verstuurd door de SOQL-query, moeten overeenkomen met het opgegeven hoofdobjecttype van de overeenkomstsjabloon. Voor elke record wordt de overeenkomstsjabloonservice aangeroepen.

De Apex-batchservice wordt weergegeven door middel van de volgende aanroepklasse:

echosign_dev1.AgreementTemplateBatch

Parameters

U moet de volgende parameters opgeven om een batchbewerking te initialiseren:

• SOQL-query om uit te voeren: moet de record-ID bevatten als een geselecteerd veld. Andere velden zijn optioneel.
• Record-ID overeenkomstsjabloon: Deze wordt gebruikt met de hoofdrecord-ID om een overeenkomst te laden.

Voorbeeld van gebruik

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

Batch overeenkomstsjabloonservice

Neemt een lijst op van hoofdobject-record-ID's en het hoofdobjecttype, waarop vervolgens een query wordt uitgevoerd. Elk van deze wordt vervolgens door de meegeleverde overeenkomstsjabloon gehaald om een overeenkomstrecord te genereren. Deze klasse implementeert de Salesforce Database.Batchable-interface. Deze kan elk aantal records verwerken. Deze worden onderverdeeld in sets van 5 en elke set wordt als een individuele transactie verwerkt, waardoor de governorslimieten kunnen worden gerespecteerd.

Het opgegeven hoofdobjecttype moet overeenkomen met het opgegeven hoofdobjecttype van de overeenkomstsjabloon. Voor elke record wordt de overeenkomstsjabloonservice aangeroepen.

De Apex-batchservice wordt weergegeven door middel van de volgende aanroepklasse:

echosign_dev1.AgreementTemplateServiceBatch

Parameters

U moet de volgende parameters opgeven om een batchbewerking te initialiseren:

• Lijst met hoofdrecord-ID's.
• Overeenkomstsjabloon record-ID: deze wordt gebruikt in combinatie met de hoofdrecords om een overeenkomst te laden.
• Naam van het hoofdobject om de hoofdrecords op te vragen.

Voorbeeld van gebruik

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

Overeenkomstsjabloonservice

De overeenkomstsjabloonservice wordt door het beheerde pakket weergegeven als een REST-webservice van Salesforce. Hierdoor kunnen externe systemen buiten de Salesforce-organisatie overeenkomsten laden op basis van bestaande overeenkomstsjablonen. Raadpleeg het artikel REST-API's maken met behulp van Apex REST voor meer informatie over het openen en aanroepen van aangepaste REST Apex-services vanuit Salesforce. Aanroepingen moeten een geldige sessie-ID bieden voor verificatie en autorisatie.

De webservice wordt weergegeven via de volgende URL:

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

Sjabloon-ID

Het laatste deel van de URL is de ID van de overeenkomstsjabloonrecord in de huidige Salesforce-organisatie die moet worden gebruikt om de overeenkomst te laden. Dit deel van de URL is optioneel. Indien dit wordt weggelaten, wordt de overeenkomstsjabloon geladen die als standaard is gemarkeerd. Als de sjabloon-ID wordt weggelaten en er geen standaard sjabloon-ID bestaat, wordt een fout geretourneerd.

De sjabloon-ID kan de indeling van 15 of 18 tekens hebben.

Hoofd-ID

De masterId-parameter specificeert welke hoofdrecord moet worden gebruikt om de overeenkomst uit de specifieke overeenkomstsjabloon te laden. Deze parameter is optioneel, maar moet worden opgegeven voor elke overeenkomstsjabloon die een hoofdobjecttype en verwijzingen naar dat hoofdobject in het sjabloon specificeert.

De hoofd-ID kan de indeling van 15 of 18 tekens hebben.

Runtimevariabelen

Eventuele aanvullende parameters worden gebruikt als runtimevariabelen, als naamwaardeparen, die worden gebruikt om alle runtimevariabelen in te vullen die zijn opgegeven in de overeenkomstsjabloon.

Resultaat

De REST-webservice retourneert een LoadResult-object met de volgende velden:

• agreementId: als de overeenkomst met succes is geladen, bevat deze de ID van de zojuist gemaakte overeenkomstrecord.
• fout: als er een fout is opgetreden tijdens het laden van de overeenkomst, bevat dit veld een gedetailleerde foutmelding.

Achtergrondservice

Met de mogelijkheid voor achtergrondservice kunnen pakketgebruikers verschillende acties op een overeenkomstobject aanroepen door het veld Achtergrondactie (echosign_dev1 Background_Actions c) bij te werken naar de bijbehorende waarde. Zodra de veldwaarde is gewijzigd van een lege waarde of een andere waarde naar één van de volgende waarden, wordt de actie gestart vanaf een trigger die deel uitmaakt van het door elektronisch ondertekenen beheerde pakket.

• Herinneren
• Verzenden
• Annuleren
• Verwijderen
• Bijwerken

Alle acties worden uitgevoerd in een asynchrone toekomstige modus, zodat de status wordt opgeslagen in het veld Fout in de overeenkomst.

Wijzigingen in achterwaartse compatibiliteit