Adobe Acrobat Sign for Salesforce: guida per gli sviluppatori

La Guida per sviluppatori di Adobe Acrobat Sign for Salesforce è progettata per consentire agli sviluppatori Salesforce di conoscere gli oggetti e i parametri necessari per integrare il pacchetto Salesforce con Adobe Acrobat Sign.

• Se hai bisogno di sapere quando l’accordo è stato completamente firmato, implementa un trigger Apex sull’oggetto echosign_dev1__SIGN_Agreement__c, prima o dopo l’aggiornamento (a seconda dei casi di utilizzo e dei requisiti). Quando il campo echosign_dev1__Status__c cambia in Firmato o Approvato o altri stati finali, l’accordo risulta completato.
• Per sapere quando viene inserito ogni singolo PDF firmato, ad esempio se hai bisogno di ottenere ogni PDF firmato intermedio, implementa un trigger Apex sugli oggetti Attachment o ContentVersion, dopo l’inserimento, e osserva se vi è un accordo principale e un nome che termina con “- firmato.pdf” o “- approvato.pdf” o un altro stato finale.
• Per sapere quando un singolo destinatario ha firmato o approvato un documento, implementa un trigger Apex sull’oggetto echosign_dev1__SIGN_Recipients__c, prima o dopo l’aggiornamento (a seconda dei casi di utilizzo e dei requisiti). Quando il campo echosign_dev1__Status__c diventa Firmato o Approvato o altri stati finali, il destinatario risulta completato.
• Per sapere quando si verifica un particolare evento del processo di firma, ad esempio quando un accordo viene inviato per la firma o quando viene inviato un promemoria, puoi creare un trigger nell’oggetto eventi accordo (echosign_dev1__SIGN_AgreementEvent__c) e verificare il tipo di evento
• I nomi per lo stato finale di un accordo completato sono: “Firmato”, “Approvato”, “Accettato”, “Compilato” e “Consegnato”
  
• I nomi per lo stato finale di un accordo terminato sono: “Annullato/Rifiutato”, “Annullato/Rifiutato”, “Scaduto”

Ordine degli aggiornamenti

Nella versione 21 l’ordine degli aggiornamenti è cambiato. Di seguito è riportata la sequenza di aggiornamento dell’accordo e dei suoi oggetti correlati:

1. Allegati 
2. Destinatari 
3. Accordo (stato e altri attributi)
4. Eventi accordo 
5. Feed di Chatter 

Servizi Apex

Metodo Apex in uso

A partire dalla versione 21.0 di Acrobat Sign for Salesforce, tutti i processi asincroni (che comprendono aggiornamenti automatici e mappature dei dati) non utilizzano più i metodi Future bensì l’approccio consigliato da Salesforce, Queueable.

A causa questa modifica, eventuali personalizzazioni dell’organizzazione abbonata che prevedono l’aggiunta di processi alla coda di Salesforce nel corso di un processo di aggiornamento automatico o di mappatura dei dati daranno luogo a un errore di tipo “System.LimitException: troppi processi Queueable aggiunti alla coda: 2”.

L’errore si verifica perché un processo queueable può aggiungere un solo processo secondario queueable che è già assunto da Acrobat Sign. Per ulteriori informazioni, consulta Limiti Queueable di Apex.

Errore: “Quando si concatenano più processi, è possibile aggiungere un solo processo da uno in esecuzione con System.enqueueJob. Ogni processo principale queueable può quindi avere un solo processo secondario. Non è possibile avviare più processi secondari dallo stesso processo queueable. ”

L’errore precedente si verifica quando lo stato dell’accordo non cambia o la mappatura dei dati non viene eseguita correttamente.Per risolverlo, individua il trigger, il generatore di processi o il flusso di lavoro e disattivalo oppure impostalo su una chiamata sincrona o pianificalo successivamente.

Servizio modelli di accordo

Il servizio modelli di accordo viene visualizzato come servizio Apex globale dal pacchetto gestito. Questo consente al codice Apex esterno al pacchetto gestito di caricare gli accordi in base ai modelli di accordo esistenti. La classe e tutti i metodi esposti sono contrassegnati come globale per consentire tale accesso.

Il servizio Apex viene esposto tramite la seguente classe di chiamata: echosign_dev1.AgreementTemplateService

  Metodi

 Costruttori (1)

global class AgreementTemplateService.AgreementTemplateListOptions

Proprietà (5)

global class AgreementTemplateService.AgreementTemplateBasicInfo

Proprietà (6)

global class AgreementTemplateService.AgreementTemplateDetails

Proprietà (6)

global class AgreementTemplateService.RecipientInfo

Proprietà (4)

  Variabili di runtime

La classe globale echosign_dev1.AgreementTemplateVariable dispone di due campi globali.

• name: il nome della variabile che deve corrispondere al nome della variabile di runtime configurata nel modello di accordo.
• value: il valore della variabile che verrà utilizzata durante il caricamento del modello. Il valore dipende dalla posizione in cui è stata utilizzata la variabile. Ad esempio, per un destinatario deve essere un contatto, un lead o un ID record utente o un’e-mail. Per una variabile documento, deve essere un ID record allegato.

Risultato

Ogni metodo restituisce l’ID del record dell’accordo appena creato o genera un’eccezione con un messaggio di errore dettagliato se si è verificato un errore durante l’operazione di caricamento.

Servizio API

Il servizio del modello API di firma elettronica di Adobe viene visualizzato come servizio Apex globale dal pacchetto gestito. Questo consente al codice Apex esterno al pacchetto gestito di richiamare un set di API di firma elettronica di Adobe tramite questi wrapper. I wrapper semplificano notevolmente la chiamata API perché i clienti non devono creare modelli di dati di richiesta e di risposta. Inoltre, i clienti non devono gestire la trasformazione dei dati Salesforce in modelli di dati con firma elettronica. La maggior parte della complessità è astratta dal cliente. Ad esempio, per inviare un accordo appena trasmesso dal cliente nell’ID del record dell’accordo, il servizio gestirà la relativa query estraendo tutti i dati pertinenti trasmettendoli all’API e analizzando il risultato.

Per consentire tale accesso, la classe e tutti i metodi esposti sono contrassegnati come globali.

• La v17 e le versioni precedenti richiamano le API SOAP
• La v18 e le versioni successive richiamano le API REST

Il servizio Apex viene esposto tramite la seguente classe di chiamata: echosign_dev1.EchoSignApiService

Metodi

Classi interne

global class DocumentHistoryEvent

Proprietà (2)

Costruttori (1)

global class DocumentInfo

Proprietà (5)

Costruttori (1)

global class ParticipantInfo

Proprietà (5)

Costruttori (1)

global class SendDocumentResult

Proprietà (3)

Costruttori (1)

global class SigningUrl

Proprietà (3)

Costruttori (1)

Servizi Batch Apex

Espone le principali azioni degli accordi con firma elettronica a livello collettivo, consentendo l’esecuzione di un’operazione su una set di accordi. Questa classe implementa l’interfaccia Database.Batchable di Salesforce. Può elaborare un numero qualsiasi di record suddivisi in insiemi di 5 ed elaborare ogni insieme come una singola transazione consentendo di rispettare i limiti di gestione.

Il servizio batch Apex è esposto tramite la seguente classe di chiamata: echosign_dev1.EchoSignActionBatch

Parametri

Per inizializzare un’operazione batch, è necessario specificare i seguenti parametri.

Un elenco degli ID record dell’accordo su cui eseguire l’azione fornita. L’azione da eseguire, uno dei seguenti valori supportati:

• Promemoria
• Invia
• Annulla
• Elimina
• Aggiorna

ID sessione utente corrente. Richiesto solo per un tipo di azione di aggiornamento.

Record utente del mittente, utilizzato per avvisare questo utente tramite e-mail una volta completata l’elaborazione in blocco.

Esempio di utilizzo

User submitterUser = UserInfo.getUserId();

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

Batch modelli di accordi

Inserisce una query SOQL e l’ID del record di un modello di accordo. La query viene eseguita per ottenere un set di record dell’oggetto principale, ognuno dei quali viene quindi eseguito tramite il modello di accordo fornito per generare un record dell’accordo. Questa classe implementa l’interfaccia Database.Batchable di Salesforce. Può elaborare un numero qualsiasi di record suddivisi in insiemi di 5 ed elaborare ogni insieme come una singola transazione consentendo di rispettare i limiti di gestione.

I tipi di record restituiti dalla query SOQL devono corrispondere al tipo di oggetto principale del modello di accordo fornito. Per ogni record, viene richiamato il servizio del modello di accordo.

Il servizio batch Apex è esposto tramite la seguente classe di chiamata:

echosign_dev1.AgreementTemplateBatch

Parametri

Per inizializzare un’operazione batch, è necessario specificare i seguenti parametri.

La query SOQL da eseguire deve contenere l’ID del record come campo selezionato. Qualsiasi altro campo è facoltativo.

ID del record del modello di accordo che verrà utilizzato insieme all’ID del record principale per caricare un accordo.

Esempio di utilizzo

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

Servizio batch modelli di accordo

Consente di visualizzare un elenco degli ID del record dell’oggetto principale e del tipo di oggetto principale che sono sottoposti a query, ognuno dei quali viene quindi eseguito tramite il modello di accordo fornito per generare un record dell’accordo. Questa classe implementa l’interfaccia Database.Batchable di Salesforce. Può elaborare un numero qualsiasi di record suddivisi in insiemi di 5 ed elaborare ogni insieme come una singola transazione consentendo di rispettare i limiti di gestione.

Il tipo di oggetto principale fornito deve corrispondere al tipo di oggetto principale del modello di accordo fornito. Per ogni record, viene richiamato il servizio del modello di accordo.

Il servizio batch Apex è esposto tramite la seguente classe di chiamata:

echosign_dev1.AgreementTemplateServiceBatch

Parametri

Per inizializzare un’operazione batch, è necessario specificare i seguenti parametri.

• Elenco degli ID dei record principali.
• ID record modello di accordo che verrà utilizzato insieme ai record principali per caricare un accordo.
• È necessario eseguire una query del nome oggetto principale per i record master.

Esempio di utilizzo

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

Servizi REST

Servizio modelli di accordo

Il servizio del modello di accordo viene visualizzato dal pacchetto gestito come servizio Web REST di Salesforce. Ciò consente ai sistemi esterni al di fuori dell’organizzazione di Salesforce di caricare gli accordi in base ai modelli di accordo esistenti. Per ulteriori dettagli su come accedere e richiamare i servizi personalizzati REST Apex da Salesforce, consulta l’articolo Creazione di API REST con Apex REST Le chiamate devono fornire un ID di sessione valido per l’autenticazione e l’autorizzazione.

Il servizio Web è accessibile dal seguente URL:

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

ID modello

L’ultima parte dell’URL è l’ID della registrazione del modello di accordo nell’organizzazione di Salesforce corrente che deve essere utilizzato per caricare l’accordo. Questa parte dell’URL è facoltativa. Se omessa, verrà caricato il modello di accordo contrassegnato come predefinito. Se l’ID modello è omesso e non esiste un ID modello per l’accordo predefinito, verrà restituito un errore.

L’ID modello può avere un formato di 15 o 18 caratteri.

ID principale

Il parametro masterId specifica quale record principale deve essere utilizzato per caricare l’accordo dal modello di accordo specifico. Questo parametro è facoltativo, ma deve essere indicato per qualsiasi modello di accordo che specifica un tipo di oggetto principale e fa riferimento a tale oggetto principale nel modello.

L’ID principale può avere un formato di 15 o 18 caratteri.

Variabili di runtime

Tutti i parametri aggiuntivi vengono utilizzati come variabili di runtime, come coppie di valori nome, per popolare le variabili di runtime specificate nel modello di accordo.

Risultato

Il servizio Web REST restituisce un oggetto LoadResult che contiene i seguenti campi:

• agreementId: se l’operazione di caricamento dell’accordo è riuscita, questo campo contiene l’ID del record dell’accordo appena creato.
• error: in caso di errore durante il caricamento dell’accordo, questo campo contiene un messaggio di errore dettagliato.

Servizio in background

La funzionalità di servizio in background consente ai clienti del pacchetto di richiamare varie azioni su un oggetto dell’accordo aggiornando il campo Azione in background (echosign_dev1 Background_Actions c) al valore corrispondente. Una volta modificato il valore del campo da un valore vuoto o da un altro valore a uno dei valori seguenti, l’azione viene avviata da un trigger incluso nel pacchetto di firma elettronica gestito.

• Promemoria
• Invia
• Annulla
• Elimina
• Aggiorna

Tutte le azioni vengono eseguite in modalità asincrona futura, quindi lo stato viene memorizzato nel campo Errore dell’accordo.

Modifiche per compatibilità con le versioni precedenti