Vous trouverez dans ce document conçu pour les développeurs de Salesforce les objets et les paramètres nécessaires à l’intégration votre package Salesforce dans Adobe Sign.

Attention :

Rappelez-vous que les objets Adobe Sign pour Salesforce peuvent changer dans une version ultérieure. 

Si vous créez une solution personnalisée qui dépend de ces objets et que ces derniers sont modifiés, vous devrez peut-être mettre à jour votre solution.

Directives relatives à l’intégration

  • 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

Depuis les versions 21.x, tous les processus asynchrones (notamment les mises à jour automatiques et les mappages de données) sont passés de Future Method Apex à Queueable Apex, la nouvelle approche recommandée par Salesforce.

En raison de cette modification, toutes les personnalisations au sein de l’organisation de l’abonné qui ont ajouté des tâches à la file d’attente de Salesforce dans le cadre de la mise à jour automatique et/ou du processus de mappage des données déclencheront une erreur : « System.LimitException : trop de tâches pouvant être mises en attente ajoutées à la file d’attente : 2 ».

Cela est dû au fait qu’un processus pouvant être mis en attente peut uniquement ajouter une tâche enfant pouvant être mise en attente, ce qui est déjà pris en charge par Adobe Sign (consultez la section « Limites de la Queueable Apex »).

« Lors de l’enchaînement de tâches, vous pouvez ajouter une seule tâche à partir d’une tâche en cours d’exécution avec System.enqueueJob, ce qui signifie qu’une seule tâche enfant peut exister pour chaque tâche pouvant être mise en attente parent. Le démarrage de plusieurs tâches enfant de la même tâche pouvant être mise en attente n’est pas pris en charge. ».

Cette erreur se remarque car l’état de l’accord ne change pas et/ou le mappage de données ne fonctionne pas correctement. 

Pour résoudre cette erreur, recherchez le déclencheur concerné, le gestionnaire de processus ou le flux de travaux et désactivez-le ou basculez-le pour utiliser un appel synchrone, ou bien encore planifiez-le pour plus tard, par exemple dans 1 heure.

Dans les versions 21.x, la méthode Apex a été modifiée : de Future Method Apex elle est passée à Queueable Apex.

Les clients qui se sont appuyés sur leurs intégrations pour utiliser la méthode Future Method Apex doivent mettre à jour leur code afin d’utiliser la méthode Queuable Apex et tester de manière exhaustive leur environnement Sandbox avant de déployer la version 21.x ou ultérieure en production.


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 la classe d’appel : echosign_dev1.AgreementTemplateService.

Remarque :

 Le chargement d’un modèle d’accord des modèles de bibliothèque eSign n’est actuellement pas pris en charge. Déplacez les modèles de document vers une bibliothèque de documents Salesforce.

 

Méthodes

global

static Id load()

Charge un accord en utilisant un modèle d’accord par défaut qui ne contient pas de type d’objet principal.

global

static Id load(String templateId)

Charge un accord avec l’ID de modèle d’accord spécifié qui ne contient pas de type d’objet principal.

 

global

static Id load(String templateId, String masterId)

Charge un accord avec l’ID de modèle d’accord et l’ID d’enregistrement principal spécifiés, dont le type doit correspondre au type d’objet principal configuré dans le modèle d’accord spécifié.

global

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

Charge un accord avec l’ID de modèle d’accord et l’ID d’enregistrement principal spécifiés, dont le type doit correspondre au type d’objet principal configuré dans le modèle d’accord spécifié. Fournit également les variables d‘exécution spécifiées comme paires nom/valeur.

 

 

Variables d’exécution

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

  • name : nom de la variable, qui doit correspondre à une variable d’exécution configurée dans le modèle d’accord.
  • value : valeur de cette variable, qui sera utilisée lors du chargement du modèle. La valeur dépend de l’emplacement où la variable a été utilisée. Par exemple, pour un destinataire, cela peut être l’ID d’enregistrement ou l’adresse électronique 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 créé, soit une exception avec un message d’erreur détaillé si un problème survient au cours du chargement.

Service API

Le service de modèle d’API Adobe eSign 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’appeler un ensemble d’API Adobe eSign 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 modèles de données Salesforce en modèles de données eSign. 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 appellent les API SOAP.
  • La version 18 et les versions supérieures appellent les API REST.

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

Méthodes

global

static void cancelDocument(Id agreementId)

Annule l’accord correspondant à l’ID d’accord spécifié.

global

static void delegateSigner(Id agreementId, String delegatedEmail)

Délègue la signature à l’adresse électronique fournie.

global

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

Délègue la signature à l’adresse électronique fournie, avec le message spécifié.

global

static echsign_dev1.EchoSignApiService.DocumentInfo getDocumentInfo(Id agreementId)

Récupère des informations détaillées pour l’ID d’accord spécifié.

global

static List getSigningUrls(Id agreementId)

Récupère l’ensemble des URL de signature pour l’ID d’accord spécifié.

global

static void removeDocument(Id agreementId)

Annule l’accord correspondant à l’ID d’accord spécifié et supprime l’enregistrement de l’accord dans Salesforce (l’accord n’est pas supprimé du compte Adobe eSign).

global

static void replaceSigner(Id replacementRecipientId)

Remplace le signataire spécifié.

global

static void replaceSigner(Id replacementRecipientId, String message)

Remplace le signataire spécifié, avec le message spécifié.

global

static echsign_dev1.EchoSignApiService.SendD ocumentResult sendDocument(Id agreementId)

Envoie l’accord avec l’ID d’accord spécifié et renvoie le résultat avec la clé et l’URL du document.

global

static void sendReminder(Id agreementId)

Envoie un rappel au signataire actuel pour l’ID d’accord spécifié.

global static void updateAgreement(Id agreementId)  Met à jour l’accord correspondant à l’ID d’accord spécifié.

 

Classes internes

global class DocumentHistoryEvent

Propriétés (2)

Accès

Nom

global

String eventType

global

String participantEmail

 

Constructeurs (1)

Accès

Signature

global

DocumentHistoryEvent()

 

global class DocumentInfo

Propriétés (5)

Accès

Nom

global

Map<string,list> historyByEmail

global

Map participantsByEmail

global

Map participantsByName

global

String senderEmail

global

String status

 

Constructeurs (1)

Accès

Signature

global

DocumentInfo()

 

global class ParticipantInfo

Propriétés (5)

Accès

Nom

global

String company

global

String email

global

String name

global

String status

global

String title

 

Constructeurs (1)

Accès

Signature

global

ParticipantInfo()

 

global class SendDocumentResult

Propriétés (3)

Accès

Nom

global

String documentKey

global

Exception error

global

String url

 

Constructeurs (1)

Accès

Signature

global

SendDocumentResult()

 

global class SigningUrl

Propriétés (3)

Accès

Nom

global

String email

global

String esignUrl

global

String simpleEsignUrl

 

Constructeurs (1)

Accès

Signature

Global

 

Services Apex par lot

Expose les principales actions des accords eSign à 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

Les paramètres suivants doivent être spécifiés pour initialiser une opération par lots :

La liste des ID d’enregistrement des accords sur lesquels effectuer l’action. L’action à exécuter, parmi les valeurs prises en charge ci-dessous :

  • Remind
  • Send
  • Cancel
  • Delete
  • Update

L’ID de session de l’utilisateur actuel. (Requis uniquement pour une mise à jour du type d’action.)

Enregistrement utilisateur de l’émetteur : utilisé pour avertir l’utilisateur par courrier électronique une fois le traitement global terminé.

Exemple d’utilisation

User submitterUser = UserInfo.getUserId();

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

 

Modèle d’accord par lot

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 appelé pour chaque enregistrement.

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

echosign_dev1.AgreementTemplateBatch

Paramètres

Les paramètres suivants doivent être spécifiés pour initialiser une opération par lots :

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é conjointement à 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); syncProcessId = Database.executeBatch(batch, 5);

 

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 appelé pour chaque enregistrement.

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

echosign_dev1.AgreementTemplateServiceBatch

Paramètres

Les paramètres suivants doivent être spécifiés pour initialiser une opération par lots :

  • La liste des ID d’enregistrements principaux
  • L’ID d’enregistrement de modèle d’accord, utilisé conjointement aux 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');
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’appel aux 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

Remarque :

Le nom d’instance change en fonction de l’instance de votre organisation.

 

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 de modèle 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’appeler 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 l’action 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é eSign.

  • 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é pour la version 21

  • Le statut de l’accord est désormais mis à jour une fois les documents et les destinataires mis à jour
    • Avant la version 21, le statut était défini avant.
  • L’objet Accord signé (contenant les URLs des images) n’est maintenant plus du tout inséré
    • Avant la version 21, il était inséré une fois toutes les autres mises à jour terminées.
  • La taille maximale d’une requête ou d’une réponse d’appel est limitée à 12 Mo pour l’Apex asynchrone selon les limitations du gouverneur Salesforce : https://developer.salesforce.com/docs/atlas.en-us.210.0.apexcode.meta/apexcode/apex_gov_limits.htm
    • Les documents dont la taille excède 12 Mo ne peuvent pas être récupérés d’Adobe Sign en raison de la limite ci-dessus.
  • Les descriptions des événements de l’accord ont changé. Elles correspondent désormais à la description renvoyée par l’API Sign avec les rapports d’audit.
  • Le processus de mise à jour s’exécute désormais comme un processus par lots Apex natif (qui est un processus asynchrone) dans Salesforce
    • Avant, il s’agissait d’une mise à jour effectuée à l’aide d’appels API provenant de l’extérieur de Salesforce
    • Il n’est désormais plus possible de déclencher ces mises à jour de statut qui lançaient les processus asynchrones, car Salesforce limite l’appel à un autre processus asynchrone à partir d’un processus asynchrone en cours d’exécution.
  • Avant la version 21, les mises à jour des attributs de l’accord étaient divisées entre des appels distincts de mises à jour. Désormais, l’objet de l’accord est entièrement mis à jour lors d’une seule transaction.
  • Avant la version 21, les accords qui avaient échoués ne pouvaient être récupérés qu’en effectuant une mise à jour manuelle de Salesforce
    • Désormais, les mises à jour sont plus fiables puisque le back-end Sign récupère automatiquement les événements ayant échoué selon un nombre de fois spécifié.
  • Les mises à jour manuelles mettent désormais à jour tous les aspects des accords, y compris les objets associés.
  • Les accords Push s’exécutent désormais en mode asynchrone, comme les mises à jour régulières et les attributs supplémentaires sont mis à jour également de la même façon que les mises à jour régulières.
  • De nouveaux paramètres ont été introduits pour activer ou désactiver les mises à jour de différents aspects de l’accord.

Ce produit est distribué sous licence Creative Commons Attribution - Pas d’utilisation commerciale - Partage à l’identique 3.0 non transposé  Les publications Twitter™ et Facebook ne sont pas couvertes par les dispositions Creative Commons.

Mentions légales   |   Politique de confidentialité en ligne