Premiers pas avec les déclencheurs Apex

• Écrire un déclencheur pour un objet Salesforce
• Utiliser des variables de contexte de déclencheur
• Appeler une méthode de classe depuis un déclencheur
• Utiliser la méthode de sObject addError() dans un déclencheur pour empêcher les opérations de sauvegarde

Remarque

Vous souhaitez apprendre en français ? Dans ce badge, les validations de défi pratique Trailhead se font en anglais. Les traductions sont fournies entre parenthèses à titre de référence. Dans votre Trailhead Playground, veillez (1) à définir les États-Unis comme région, (2) à sélectionner l’anglais comme langue, et (3) à copier et coller uniquement les valeurs en anglais. Suivez les instructions ici.

Consultez le badge Trailhead dans votre langue pour découvrir comment profiter de l’expérience Trailhead traduite.

Avant de commencer

Les déclencheurs Apex sont utiles, amusants et vraiment super. Ce module vous aide à les découvrir, mais il fait également référence à d’autres fonctionnalités Salesforce pour vous montrer la puissance des déclencheurs Apex. Afin de tirer le meilleur parti de ce module, nous vous recommandons vivement de consulter d’abord ces modules :

• Quick Start: Apex
• Concepts Apex de base et base de données
• SOQL pour les administrateurs
• Bases de la Developer Console

Exemple de déclencheur

Types de déclencheur

Il existe deux types de déclencheurs.

• Les Before triggers (déclencheurs before) sont utilisés pour mettre à jour ou valider des valeurs d’enregistrement avant de les enregistrer dans la base de données.
• Les After triggers (déclencheurs after) sont utilisés pour accéder aux valeurs de champ définies par le système (par exemple le champ Id ou LastModifiedDate d’un enregistrement), et pour appliquer les modifications dans d’autres enregistrements. Les enregistrements qui activent le déclencheur after sont en lecture seule.

Utilisation de variables de contexte

Pour accéder aux enregistrements qui activent le déclencheur, utilisez des variables de contexte. Par exemple, Trigger.new contient tous les enregistrements insérés dans des déclencheurs insert ou update. Trigger.old fournit l’ancienne version des sObjects avant leur mise à jour dans des déclencheurs update, ou la liste de sObjects supprimés dans des déclencheurs delete. Les déclencheurs peuvent être activés lors de l'insertion d'un enregistrement ou de l'insertion en masse de nombreux enregistrements via l'API ou Apex. Par conséquent, des variables de contexte (telles que Trigger.new) peuvent contenir un seul ou plusieurs enregistrements. Vous pouvez itérer sur Trigger.new pour obtenir chaque sObject individuel.

Cet exemple est une version modifiée de l'exemple de déclencheur HelloWorldTrigger. Il itère sur chaque compte d’une boucle for et met à jour le champ Description de chaque compte.

trigger HelloWorldTrigger on Account (before insert) {
    for(Account a : Trigger.new) {
        a.Description = 'New description';
    }   
}

Le système sauvegarde les enregistrements qui ont activé le déclencheur before après l'exécution du déclencheur. Vous pouvez modifier les enregistrements du déclencheur sans appeler explicitement une opération DML insérer ou mettre à jour. Si vous exécutez des instructions DML sur ces enregistrements, vous obtenez une erreur.

D'autres variables de contexte renvoient une valeur booléenne pour indiquer si le déclencheur a été activé suite à une mise à jour ou à un autre événement. Ces variables sont utiles lorsqu'un déclencheur combine plusieurs événements. Par exemple :

trigger ContextExampleTrigger on Account (before insert, after insert, after delete) {
    if (Trigger.isInsert) {
        if (Trigger.isBefore) {
            // Process before insert
        } else if (Trigger.isAfter) {
            // Process after insert
        }        
    }
    else if (Trigger.isDelete) {
        // Process after delete
    }
}

Le tableau ci-dessous présente la liste complète des variables de contexte disponibles pour les déclencheurs.

Appel d'une méthode de classe à partir d'un déclencheur

Vous pouvez appeler des méthodes utilitaires à partir d'un déclencheur. L'appel de méthodes d'autres classes permet de réutiliser le code, de diminuer la taille de vos déclencheurs et d'améliorer la maintenance de votre code Apex. Il permet également d'utiliser une programmation orientée objet.

L'exemple de déclencheur ci-dessous montre comment appeler une méthode statique à partir d'un déclencheur. Si le déclencheur a été activé suite à un événement d'insertion, l'exemple appelle la méthode statique sendMail() dans la classe EmailManager. Cette méthode utilitaire envoie un e-mail au destinataire spécifié et contient le nombre d'enregistrements de contact insérés.

1. Dans la Developer Console, cliquez sur File (Fichier) | New (Nouveau) | Apex Class (Classe Apex).
2. Saisissez EmailManager, puis cliquez sur OK.
3. Remplacez le corps de classe par défaut par l’exemple de classe EmailManager ci-dessous.

   public class EmailManager {
       // Public method
       public static void sendMail(String address, String subject, String body) {
           // Create an email message object
           Messaging.SingleEmailMessage mail = new Messaging.SingleEmailMessage();
           String[] toAddresses = new String[] {address};
           mail.setToAddresses(toAddresses);
           mail.setSubject(subject);
           mail.setPlainTextBody(body);
           // Pass this email message to the built-in sendEmail method 
           // of the Messaging class
           Messaging.SendEmailResult[] results = Messaging.sendEmail(
                                     new Messaging.SingleEmailMessage[] { mail });
           // Call a helper method to inspect the returned results
           inspectResults(results);
       }
       // Helper method
       private static Boolean inspectResults(Messaging.SendEmailResult[] results) {
           Boolean sendResult = true;
           // sendEmail returns an array of result objects.
           // Iterate through the list to inspect results. 
           // In this class, the methods send only one email, 
           // so we should have only one result.
           for (Messaging.SendEmailResult res : results) {
               if (res.isSuccess()) {
                   System.debug('Email sent successfully');
               }
               else {
                   sendResult = false;
                   System.debug('The following errors occurred: ' + res.getErrors());                 
               }
           }
           return sendResult;
       }
   }

4. Dans la Developer Console, cliquez sur Fichier (File) | New (Nouveau) | Apex Trigger (Déclencheur Apex).
5. Saisissez le nom de déclencheur ExampleTrigger, puis sélectionnez Contact pour sObject. Cliquez sur Submit (Soumettre).
6. Remplacez le code par défaut par le code ci-dessous, puis remplacez le texte de l’espace réservé dans sendMail() par votre adresse e-mail.

   trigger ExampleTrigger on Contact (after insert, after delete) {
       if (Trigger.isInsert) {
           Integer recordCount = Trigger.new.size();
           // Call a utility method from another class
           EmailManager.sendMail('Your email address', 'Trailhead Trigger Tutorial', 
                       recordCount + ' contact(s) were inserted.');
       }
       else if (Trigger.isDelete) {
           // Process after delete
       }
   }

7. Pour enregistrer, appuyez sur Ctrl+S.
8. Pour tester le déclencheur, créez un contact.
   1. Cliquez sur Debug (Débogage) | Open Execute Anonymous Window (Ouvrir une fenêtre d’exécution anonyme).
   2. Dans la nouvelle fenêtre, ajoutez l'élément suivant, puis cliquez sur Execute (Exécuter).

      Contact c = new Contact(LastName='Test Contact');
      insert c;

9. Dans le journal de débogage, assurez-vous que le déclencheur a été activé. Le message écrit par la méthode utilitaire est également indiqué à la fin du journal : DEBUG|Email sent successfully
10. Vérifiez maintenant si vous avez reçu un e-mail avec le corps de texte 1 contact(s) were inserted.
    
    Une fois votre nouveau déclencheur en place, vous recevez un e-mail chaque fois que vous ajoutez un ou plusieurs contacts !

Ajout d'enregistrements associés

Les déclencheurs sont souvent utilisés pour accéder à et gérer des enregistrements associés aux enregistrements dans le contexte du déclencheur (enregistrements qui ont entraîné l'activation du déclencheur).

Ce déclencheur ajoute une opportunité associée à chaque compte nouveau ou mis à jour si aucune opportunité ne lui est déjà associée. Le déclencheur exécute d'abord une requête SOQL pour récupérer les opportunités enfants des comptes dans lesquels il a été activé. Le déclencheur itère ensuite sur la liste de sObjects dans Trigger.new pour obtenir chaque sObject de compte. Si en compte n'a aucun sObject d'opportunité associé, la boucle for en crée un. Si le déclencheur a créé des opportunités, l'instruction finale les insère.

1. Ajoutez le déclencheur suivant à l’aide de la Developer Console (suivez les étapes de l’exemple HelloWorldTrigger, mais utilisez le nom de déclencheur AddRelatedRecord).

   trigger AddRelatedRecord on Account(after insert, after update) {
       List<Opportunity> oppList = new List<Opportunity>();
       // Get the related opportunities for the accounts in this trigger
       Map<Id,Account> acctsWithOpps = new Map<Id,Account>(
           [SELECT Id,(SELECT Id FROM Opportunities) FROM Account WHERE Id IN :Trigger.new]);
       // Add an opportunity for each account if it doesn't already have one.
       // Iterate through each account.
       for(Account a : Trigger.new) {
           System.debug('acctsWithOpps.get(a.Id).Opportunities.size()=' + acctsWithOpps.get(a.Id).Opportunities.size());
           // Check if the account already has a related opportunity.
           if (acctsWithOpps.get(a.Id).Opportunities.size() == 0) {
               // If it doesn't, add a default opportunity
               oppList.add(new Opportunity(Name=a.Name + ' Opportunity',
                                          StageName='Prospecting',
                                          CloseDate=System.today().addMonths(1),
                                          AccountId=a.Id));
           }           
       }
       if (oppList.size() > 0) {
           insert oppList;
       }
   }

2. Pour tester le déclencheur, créez un compte dans l'interface utilisateur de Salesforce, puis nommez-le Apples & Oranges.
3. Dans la liste associée Opportunities (Opportunités) de la page du compte, recherchez la nouvelle opportunité. Le déclencheur a automatiquement ajouté cette opportunité !

Le déclencheur que vous avez ajouté itère sur tous les enregistrements du contexte du déclencheur. La boucle for itère sur Trigger.new. La boucle de ce déclencheur pourrait toutefois être beaucoup plus efficace. Nous n'avons pas réellement besoin d'accéder à chaque compte dans le contexte de ce déclencheur, mais uniquement à certains comptes, ceux sans opportunité. L'unité suivante montre comment rendre ce déclencheur plus efficace. L'unité Modèles de conception de déclencheurs en masse montre comment modifier la requête SOQL pour récupérer uniquement les comptes sans opportunité. Elle indique ensuite comment itérer uniquement sur ces enregistrements.

Utilisation d'exceptions de déclencheur

Il est parfois utile de définir des restrictions sur certaines opérations de base de données, par exemple pour empêcher la sauvegarde d'enregistrements lorsque certaines conditions sont remplies. Pour empêcher la sauvegarde d'enregistrements dans un déclencheur, appelez la méthode addError() sur le sObject en question. La méthode addError() renvoie une erreur fatale dans un déclencheur. Le message d'erreur est affiché dans l'interface utilisateur et est consigné.

Le déclencheur ci-dessous empêche la suppression d'un compte s'il a des opportunités associées. Par défaut, la suppression d'un compte entraîne la suppression en cascade de tous ses enregistrements associés. Ce déclencheur empêche la suppression en cascade des opportunités. Essayez ce déclencheur ! Si vous avez exécuté l’exemple précédent, votre organisation a un compte appelé Apples & Oranges avec une opportunité associée. Cet exemple utilise ce compte.

1. Dans la Developer Console, ajoutez le déclencheur suivant :

   trigger AccountDeletion on Account (before delete) {
       // Prevent the deletion of accounts if they have related opportunities.
       for (Account a : [SELECT Id FROM Account
                        WHERE Id IN (SELECT AccountId FROM Opportunity) AND
                        Id IN :Trigger.old]) {
           Trigger.oldMap.get(a.Id).addError(
               'Cannot delete account with related opportunities.');
       }
   }

2. Dans l'interface utilisateur de Salesforce, accédez à la page du compte Apples & Oranges, puis cliquez sur Delete (Supprimer).
3. Dans l’écran contextuel de confirmation, cliquez sur OK.
   
   Recherchez l’erreur de validation avec le message personnalisé Cannot delete account with related opportunities (Impossible de supprimer un compte avec des opportunités liées).
   
   
4. Désactivez le déclencheur AccountDeletion. Si vous laissez ce déclencheur actif, vous ne pouvez pas utiliser vos questions de vérification.
   1. Dans Setup (Configuration), recherchez Apex Triggers (Déclencheurs Apex).
   2. Dans la page Apex Triggers (Déclencheurs Apex), cliquez sur Edit (Modifier) en regard du déclencheur AccountDeletion.
   3. Désélectionnez Is Active (Actif).
   4. Cliquez sur Save (Enregistrer).

L’appel de addError() dans un déclencheur entraîne la restauration de l’ensemble des opérations, sauf lorsqu’un DML en masse est appelé avec un succès partiel.

• Si un appel DML en masse effectué dans l’API de la plate-forme Lightning a généré le déclencheur, le moteur d’exécution met de côté les enregistrements erronés. Il tente ensuite une sauvegarde partielle des enregistrements qui n'ont pas renvoyé d'erreur.
• Si une instruction DML dans Apex a généré le déclencheur, toute erreur annule l'opération complète. Cependant, le moteur d'exécution continue de traiter chaque enregistrement de l'opération afin de générer une liste complète d'erreurs.

Déclencheurs et appels externes

Apex permet de transmettre des appels et d'intégrer votre code Apex à des services Web externes. Les appels Apex à des services Web externes sont appelés des appels externes. Par exemple, vous pouvez émettre un appel externe à un service de cotation boursière pour obtenir les derniers cours. Lors de la transmission d’un appel externe à partir d’un déclencheur, l’appel doit être effectué de façon asynchrone pour que le processus de déclenchement ne vous empêche pas de travailler en attendant la réponse du service externe. L’appel asynchrone est émis dans un processus en arrière-plan et la réponse est reçue lorsque le service externe la renvoie.

Pour émettre un appel externe à partir d'un déclencheur, appelez une méthode de classe exécutée de façon asynchrone. Ce type de méthode est appelé méthode future et est annoté avec @future(callout=true). Cet exemple de classe contient d'une méthode future qui génère l'appel externe.

L'exemple utilise une URL de point de terminaison fictive. Vous ne pouvez pas exécuter cet exemple, sauf si vous définissez le point de terminaison sur une URL valide et ajoutez un site distant dans Salesforce pour votre point de terminaison.

public class CalloutClass {
    @future(callout=true)
    public static void makeCallout() {
        HttpRequest request = new HttpRequest();
        // Set the endpoint URL.
        String endpoint = 'http://yourHost/yourService';
        request.setEndPoint(endpoint);
        // Set the HTTP verb to GET.
        request.setMethod('GET');
        // Send the HTTP request and get the response.
        HttpResponse response = new HTTP().send(request);
    }
}

Cet exemple montre le déclencheur qui appelle la méthode dans la classe pour émettre un appel externe asynchrone.

trigger CalloutTrigger on Account (before insert, before update) {
    CalloutClass.makeCallout();
}

Cette section présente une vue d'ensemble des appels externes, sans préciser de détail. Pour plus d’informations, reportez-vous à Invocation d’appels en utilisant Apex dans le Guide du développeur Apex.