Guide du développeur Adobe Acrobat Sign pour Salesforce

Présentation

Le Guide du développeur Adobe Acrobat Sign pour Salesforce est conçu pour aider les développeurs Salesforce à en savoir plus sur les objets et les paramètres requis pour intégrer votre package Salesforce dans Adobe Acrobat Sign.

Consultez les rubriques de ce document pour en savoir plus :

• Instructions pour les développeurs
• Ordre des mises à jour
• Services Apex
• Services d’API
• Services Apex par lot
• Lot de modèles d’accord
• Service de modèle d’accord par lot
• Services REST
• Service d’arrière-plan
• Modifications de la rétrocompatibilité

Instructions pour les développeurs

• S’il vous faut savoir quand l’accord est intégralement signé, implémentez un déclencheur Apex sur l’objet echosign_dev1__SIGN_Agreement__c avant ou après la mise à niveau (en fonction des exigences et du cas d’utilisation). Lorsque le champ echosign_dev1__Status__c passe en statut Signé ou Approuvé ou en un autre statut, l’accord est terminé. 
• S’il vous faut savoir quand chaque PDF signé de façon individuelle est inséré, si par exemple, vous devez obtenir chaque PDF intermédiaire signé, implémentez un déclencheur Apex sur les objets Attachment (Pièce jointe) ou ContentVersion (Version du contenu), après insertion et recherchez un accord parent et un nom qui se termine par « - signed.pdf » ou « - approved.pdf » ou par un autre statut final
• S’il vous faut savoir quand un destinataire individuel a signé ou a approuvé un document, implémentez un déclencheur Apex sur l’objet echosign_dev1__SIGN_Recipients__c, avant ou après la mise à niveau (en fonction des exigences et du cas d’utilisation). Lorsque le champ echosign_dev1__Status__c passe en Signé ou Approuvé ou en un autre statut, le destinataire est terminé.  
• S’il vous faut savoir quand un événement particulier faisant partie du processus de signature se produit, tel qu’un accord envoyé pour signature ou un rappel envoyé, un déclencheur peut être créé sur l’objet des événements de l’accord.(echosign_dev1__SIGN_AgreementEvent__c) et peut vérifier le type de l’événement
• Les noms du statut de l’accord final pour un accord complet sont : « Signé », « Approuvé », « Accepté », « Formulaire-rempli » et « Livré »
  
• Les noms du statut de l’accord final pour un accord annulé sont : « Annulé/Refusé » et « Expiré »

Ordre des mises à jour

Dans la version 21, l’ordre des mises à jour a changé. Vous trouverez ci-dessous la séquence dans laquelle l’accord et ses objets associés sont mis à jour :

1. Pièces jointes 
2. Destinataires 
3. Accord (statut et autres attributs)
4. Événements de l’accord 
5. Flux Chatter 

Services Apex

Méthode Apex en vigueur

À partir d'Acrobat Sign for Salesforce V 21.0, tous les processus asynchrones (y compris les mises à jour automatiques et les mappages de données) utilisent la méthode Queueable au lieu de la méthode Future, comme recommandé par Salesforce.
Suite à cette modification, toutes les tâches de personnalisation ajoutées à la file d'attente Salesforce pour la mise à jour automatique ou le processus de mappage de données échoueront avec cette erreur : « System.LimitException: Too many queueable jobs added to queue:2. »

L’erreur se produit parce qu’un processus en attente ne peut ajouter qu’un enfant en attente, ce qui est déjà pris en charge par Acrobat Sign. Pour plus d’informations, voir Limitations d’Apex en attente. 

Lorsque le statut de l’accord ne change pas ou que le mappage de données ne s’exécute pas correctement, cette erreur peut s’afficher : « When chaining jobs, you can add only one job from an executing job with System.enqueueJob, which means that only one child job can exist for each parent queueable job. Starting multiple child jobs from the same queueable job isn’t supported. »

Pour résoudre cette erreur, recherchez le déclencheur concerné, le gestionnaire de processus ou le workflow, puis désactivez-le ou basculez-le pour utiliser un appel synchrone. Vous pouvez également le planifier pour plus tard.

Service de modèle d’accord

Le service de modèle d’accord est proposé comme service Apex global par le package géré. Cela permet au code Apex, en dehors du package géré, de charger des accords en fonction des modèles d’accord existants. La classe et l’ensemble des méthodes affichées sont déclarées comme global pour permettre l’accès à celles-ci.

Le service Apex est affiché via cette classe d’appel : echosign_dev1.AgreementTemplateService.

Méthodes

 Constructeurs

Propriétés de la classe globale

Variables d’exécution

La classe globale echosign_dev1.AgreementTemplateVariable possède les deux champs globaux suivants :

• name : nom de la variable, qui doit correspondre à une variable d’exécution configurée dans le modèle d’accord.
• value : valeur de la variable utilisée pendant le chargement du modèle. La valeur dépend de l’emplacement où la variable a été utilisée. Par exemple, pour un destinataire, ce peut être l’ID d’enregistrement ou l’adresse e-mail d’un contact, d’un prospect ou d’un utilisateur. Pour une variable de document, cela doit être l’ID d’enregistrement d’une pièce jointe.

Résultat

Chaque méthode retourne soit l’ID de l’enregistrement d’accord nouvellement créé, soit une exception avec un message d’erreur détaillé si un problème survient au cours du chargement.

Services API

Le service de modèle d’API de signature électronique Adobe est proposé comme service Apex global par le package géré. Cela permet au code Apex, y compris en dehors du package géré, d’invoquer un ensemble d’API de signature électronique Adobe par le biais de ces enveloppes. Les enveloppes simplifient considérablement l’appel des API. En effet, les consommateurs n’ont pas besoin de créer de modèle de données de requête et de réponse. Ceux-ci n’ont pas non plus à gérer la transformation des données Salesforce en modèles de données de signature électronique. Pour le consommateur, tout est simplifié. Par exemple, pour envoyer un accord, il suffit au consommateur de fournir l’ID d’enregistrement d’accord. Le service prend en charge la requête : il extrait les données pertinentes, les renseigne dans l’API et analyse le résultat.

La classe et l’ensemble des méthodes affichées sont déclarées comme global pour permettre l’accès à celles-ci.

• La version 17 et les versions antérieures invoquent les API SOAP.
• La version 18 et les versions supérieures invoquent les API REST.

Le service Apex est affiché via la classe d’appel : echosign_dev1.EchoSignApiService.

Amélioration de l’API Apex pour les autres destinataires

Depuis la version 24.14, l’API Apex mise à jour vous permet de remplacer ou d’ajouter d’autres destinataires. Elle est accessible dans la classe globale « EchoSignApiService ». Deux nouveaux éléments ont été introduits :

• Une fonction globale :
  

  /**

  * Input params:

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

• Une énumération globale : RECIPIENT_CHANGE_TYPE {REPLACE, ALTERNATE}

Exemple de code pour appeler cette API pour les destinataires (type de destinataire : adresse 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

}

Méthodes

Classes internes

• Classe globale : DocumentHistoryEvent

• Classe globale : DocumentInfo
  

• Classe globale : ParticipantInfo

• Classe globale : SendDocumentResult

• Classe globale : SigningUrl
  

Services Apex par lot

Expose les principales actions des accords de signature électronique à un niveau global, ce qui permet d’effectuer une même opération sur un ensemble d’accords. Cette classe implémente l’interface Salesforce Database.Batchable. Elle peut traiter tous les enregistrements, quel que soit le nombre. Ceux-ci sont rassemblés par lots de cinq et ces lots sont traités comme une transaction individuelle, ce qui permet de respecter les limitations du gouverneur.

Le service Apex par lot est affiché via la classe d’appel : echosign_dev1.EchoSignActionBatch.

Paramètres

Vous devez spécifier les paramètres suivants pour initialiser une opération par lot :

• Liste des ID d’enregistrement d’accord sur lesquels effectuer l’action indiquée : l’action peut être définie sur l’une des valeurs prises en charge suivantes : Rappeler, Envoyer, Annuler, Supprimer ou Mettre à jour.
• ID de session utilisateur actuel : obligatoire uniquement pour le type d’action de mise à jour.
• Enregistrement utilisateur de l’émetteur : utilisé pour avertir l’utilisateur par e-mail une fois le traitement global terminé.

Exemple d’utilisation

User submitterUser = UserInfo.getUserId();

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

Lot de modèles d’accord

Accepte une requête SOQL et un ID d’enregistrement de modèle d’accord. La requête est exécutée de façon à récupérer un ensemble d’enregistrements d’objet principal. Ceux-ci sont ensuite exécutés dans le modèle d’accord fourni, pour générer un enregistrement d’accord. Cette classe implémente l’interface Salesforce Database.Batchable. Elle peut traiter tous les enregistrements, quel que soit le nombre. Ceux-ci sont rassemblés par lots de cinq et ces lots sont traités comme une transaction individuelle, ce qui permet de respecter les limitations du gouverneur.

Les types d’enregistrements renvoyés par la requête SOQL doivent correspondre au type d’objet principal du modèle d’accord fourni. Le service de modèle d’accord est invoqué pour chaque enregistrement.

Le service Apex par lot est affiché via la classe d’appel :

echosign_dev1.AgreementTemplateBatch

Paramètres

Vous devez spécifier les paramètres suivants pour initialiser une opération par lot :

• Requête de SOQL à exécuter : doit inclure l’ID d’enregistrement comme champ sélectionné. Les autres champs sont facultatifs.
• ID d’enregistrement de modèle d’accord : utilisé avec l’ID d’enregistrement principal pour charger un accord.

Exemple d’utilisation

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 de modèle d’accord par lot

Accepte une liste d’ID d’enregistrement d’objet principal et le type d’objet principal. L’ensemble est ensuite interrogé et exécuté dans le modèle d’accord fourni, pour générer un enregistrement d’accord. Cette classe implémente l’interface Salesforce Database.Batchable. Elle peut traiter tous les enregistrements, quel que soit le nombre. Ceux-ci sont rassemblés par lots de cinq et ces lots sont traités comme une transaction individuelle, ce qui permet de respecter les limitations du gouverneur.

Le type d’objet principal donné doit correspondre au type d’objet principal du modèle d’accord fourni. Le service de modèle d’accord est invoqué pour chaque enregistrement.

Le service Apex par lot est affiché via la classe d’appel :

echosign_dev1.AgreementTemplateServiceBatch

Paramètres

Vous devez spécifier les paramètres suivants pour initialiser une opération par lot :

• La liste des ID d’enregistrements principaux
• L’ID d’enregistrement de modèle d’accord : utilisé avec les enregistrements principaux pour charger un accord
• Le nom de l’objet principal pour pouvoir formuler une requête pour les enregistrements principaux

Exemple d’utilisation

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

Services REST

Service de modèle d’accord

Le service de modèle d’accord est proposé comme service web REST de Salesforce par le package géré. Cela permet aux systèmes externes, en dehors de l’organisation Salesforce, de charger des accords en fonction des modèles d’accord existants. Consultez Création d’API REST avec Apex REST (en anglais) pour plus d’informations sur l’accès et l’invocation des services Apex REST personnalisés depuis Salesforce. Les appels doivent fournir un ID de session valide pour le processus d’authentification et d’autorisation.

Le service web est disponible à l’adresse suivante :

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

ID de modèle

La dernière partie de l’URL est l’ID de l’enregistrement de modèle d’accord de l’organisation Salesforce actuelle devant être utilisé pour charger l’accord. Cette partie de l’URL est facultative. Si cette partie est omise, c’est le modèle d’accord par défaut qui est chargé. Si l’ID de modèle est omis et qu’aucun modèle d’accord n’est désigné par défaut, un message d’erreur apparaît.

Un ID de modèle comprend 15 ou 18 caractères.

ID principal

Le paramètre masterId définit l’enregistrement principal devant être utilisé pour charger l’accord depuis un modèle d’accord spécifique. Ce paramètre est facultatif, mais il doit être défini pour tout modèle d’accord spécifiant un type d’objet principal dont il est fait référence dans le modèle.

Un ID principal comprend 15 ou 18 caractères.

Variables d’exécution

Tous les paramètres supplémentaires sont utilisés en tant que variables d’exécution, comme paires nom-valeur, pour alimenter les variables d’exécution spécifiées dans le modèle d’accord.

Résultat

Le service web REST renvoie un objet LoadResult qui contient les champs suivants :

• agreementId : lorsque le chargement de l’accord est réussi, contient l’ID de l’enregistrement de l’accord créé.
• error : en cas d’erreur lors du chargement de l’accord, contient un message d’erreur détaillé.

Service d’arrière-plan

Le service d’arrière-plan permet aux utilisateurs de package d’invoquer plusieurs actions pour un objet d’accord, en mettant à jour la valeur correspondante dans le champ Action d’arrière-plan (echosign_dev1 Background_Actions c). Une fois la valeur vide ou la valeur contenue dans le champ remplacée par l’une des valeurs suivantes, l’action est activée par un déclencheur inclus dans le package géré de signature électronique.

• Remind
• Send
• Cancel
• Delete
• Update

L’ensemble des actions s’exécute en mode futur asynchrone. Par conséquent, l’état est stocké dans le champ Erreur de l’accord.

Modifications de la rétrocompatibilité

Articles connexes

• Adobe Acrobat Sign pour Salesforce : Guide d’installation
• Adobe Acrobat Sign pour Salesforce : Guide de personnalisation avancée
• Adobe Acrobat Sign pour Salesforce : Mappage des champs et modèles
• Adobe Acrobat Sign pour Salesforce : Guide de mise à niveau
• Adobe Acrobat Sign pour Salesforce : Guide de l’utilisateur