Déclencheur Salesforce

Le déclencheur Salesforce vous permet d'écouter des événements Capture des données modifiées (CDC) ou Plate-forme de messagerie d'entreprise. Avec ce déclencheur, vous pouvez commencer l'intégration en fonction de l'un des événements CDC (créer, mettre à jour, supprimer ou annuler la suppression) ou des événements Plate-forme dans votre instance Salesforce.

Avant de commencer

Cette section décrit les étapes requises pour connecter et configurer une instance Salesforce afin d'utiliser les événements Capture de données modifiées (CDC) ou Plate-forme pour diffuser les modifications dans votre intégration Apigee Integration via un sujet Pub/Sub. Les étapes suivantes doivent être effectuées avant de configurer une tâche ou un déclencheur associé à Salesforce dans Apigee :

Configurer un utilisateur d'intégration

Pour configurer un utilisateur d'intégration, procédez comme suit :

  1. Connectez-vous à votre instance Salesforce à l'aide de vos identifiants sysadmin.
  2. Cliquez sur l'icône en forme de roue dentée, puis sélectionnez Configuration, comme illustré par l'image ci-dessous : image illustrant la page de configurationimage illustrant la page de configuration
  3. Cliquez sur Utilisateurs > Utilisateurs dans le menu Administration.
  4. Dans le volet Utilisateurs, sélectionnez le bouton Nouvel utilisateur.
  5. Dans la boîte de dialogue Modifier le compte utilisateur, saisissez les informations suivantes :
    1. Prénom : prénom de l'utilisateur d'intégration.
    2. Nom : nom de l'utilisateur d'intégration.
    3. Adresse e-mail : adresse e-mail de l'utilisateur d'intégration. Dans l'idéal, il doit s'agir de l'adresse e-mail d'un groupe.
    4. Nom d'utilisateur : nom d'utilisateur conforme à toutes les conventions de dénomination au niveau de l'organisation.

      Si vous créez un utilisateur d'intégration, utilisez le format suivant : EMAIL.SALESFORCE_ORG_NAME.SANDBOX_NAME

      Si vous disposez déjà d'un utilisateur d'intégration, vérifiez que le nom d'utilisateur est saisi ici.

    5. Rôle : faites votre choix dans le menu déroulant des options.
    6. Licence utilisateur : saisissez Salesforce ou, si vous utilisez une organisation d'essai, saisissez Salesforce Platform.
    7. Profil : sélectionnez le profil d'autorisations des utilisateurs d'intégration dans la liste déroulante.

      Nous vous recommandons d'attribuer un profil sans autorisations, afin de protéger l'accès à Salesforce de votre utilisateur d'intégration contre toute utilisation non autorisée.

    8. Cliquez sur Enregistrer.
  6. Pour mettre à jour le mot de passe du nouvel utilisateur d'intégration, procédez comme suit :
    1. Cliquez sur le bouton Réinitialiser les mots de passe dans le volet Utilisateurs. Un e-mail de réinitialisation du mot de passe est envoyé à l'adresse e-mail associée à l'utilisateur.
    2. Suivez le flux de réinitialisation du mot de passe depuis le compte de messagerie. Notez bien le nouveau mot de passe, car vous en aurez besoin pour une étape ultérieure.

Configurer un ensemble d'autorisations

Si vous avez déjà accès à un ensemble d'autorisations approprié pour un utilisateur d'intégration, vous pouvez ignorer cette étape et passer à la section Configurer un jeton de sécurité. Sinon, procédez comme suit pour configurer un ensemble d'autorisations pour l'utilisateur d'intégration et l'objet Salesforce.

Pour configurer un ensemble d'autorisations pour l'utilisateur d'intégration, procédez comme suit :

  1. Dans le menu Configuration, cliquez sur Utilisateurs > Ensembles d'autorisations.
  2. Dans le volet Ensembles d'autorisations, cliquez sur le bouton Nouveau.
  3. Dans la boîte de dialogue Ensembles d'autorisations, saisissez les informations suivantes :
    • Libellé : saisissez un nom pour l'ensemble d'autorisations.
    • Licence : sélectionnez Salesforce dans la liste déroulante Licence.
    • Cliquez sur Save (Enregistrer).
  4. Dans la liste des options Paramètres système, faites défiler la page vers le bas, puis sélectionnez Autorisations système.
  5. Sur la page Autorisations système, cliquez sur le bouton Modifier.
  6. Faites défiler la liste des autorisations disponibles, puis cochez la case API activée.

    L'autorisation Utilisateur d'API uniquement est également requise, mais ne peut pas être activée tant que le jeton de sécurité requis n'a pas été réinitialisé. Cette autorisation est ajoutée ultérieurement.

  7. (Facultatif) Faites défiler la page, puis sélectionnez Modifier toutes les données et Afficher toutes les données, le cas échéant. Ces autorisations ne sont pas obligatoires, mais peuvent être utiles si vous souhaitez autoriser automatiquement l'utilisateur d'intégration à accéder aux nouveaux objets. Nous vous recommandons de n'activer ces autorisations que pour les tests en bac à sable.
  8. Faites défiler jusqu'en haut de la liste des autorisations, puis cliquez sur Enregistrer.
  9. Confirmez vos paramètres, puis cliquez sur Enregistrer.

Pour configurer l'ensemble d'autorisations de l'objet Salesforce, procédez comme suit :

  1. Cliquez sur Aperçu des ensembles d'autorisations pour revenir à la page principale de configuration Ensemble d'autorisations.
  2. Sélectionnez Paramètres d'objet dans la section Applications du volet Ensemble d'autorisations.
  3. Faites défiler la page vers le bas, puis sélectionnez les objets Salesforce nécessitant un ensemble d'autorisations. Cet exemple utilise l'objet Opportunity.
  4. Cliquez sur le bouton Modifier de la page d'informations détaillées sur l'objet.
  5. Cochez les cases correspondant aux types d'enregistrements. Si vous savez quels types d'enregistrements sont requis, sélectionnez-les. Si vous ne savez pas quels types d'enregistrements sont requis, sélectionnez-les tous.
  6. Cochez les cases correspondant aux autorisations d'objets à activer. Nous vous recommandons de sélectionner Lecture et Tout afficher.
  7. Accordez un accès en lecture ou un accès en modification à chaque champ d'objet en cochant la case correspondante.
  8. Faites défiler jusqu'en haut de la page, puis cliquez sur Enregistrer.

Configurer un jeton de sécurité

Si vous avez déjà créé un jeton de sécurité pour l'utilisateur d'intégration et que vous avez réinitialisé le mot de passe, un e-mail contenant un nouveau jeton de sécurité est envoyé automatiquement. Vous pouvez utiliser le nouveau jeton et passer à la section Créer une application connectée.

Sinon, procédez comme suit pour réinitialiser le jeton de sécurité de l'utilisateur d'intégration :

  1. Connectez-vous à Salesforce en tant qu'utilisateur d'intégration, à l'aide du nom d'utilisateur et du mot de passe définis précédemment.
  2. Dans le menu principal, cliquez sur la photo de profil, puis sur Paramètres.
  3. Dans le menu Paramètres, sélectionnez Réinitialiser mon jeton de sécurité pour ouvrir le volet Réinitialiser le jeton de sécurité.
  4. Cliquez sur le bouton Réinitialiser le jeton de sécurité.
  5. Vérifiez dans le compte de messagerie associé à l'utilisateur d'intégration si vous avez reçu un e-mail contenant le nouveau jeton de sécurité. Notez bien le nouveau jeton de sécurité, car vous en aurez besoin pour une prochaine étape.
  6. (Facultatif) Activez l'autorisation Utilisateur d'API uniquement dans la section Autorisations système de votre ensemble d'autorisations, comme expliqué dans la section Configurer une autorisation ci-dessus.

Créer une application connectée

Vous devez disposer d'une autorisation d'administration système pour configurer une application connectée. Si vous êtes actuellement connecté en tant qu'utilisateur d'intégration, déconnectez puis reconnectez-vous en tant que sysadmin.

Pour configurer une application connectée, procédez comme suit :

  1. Cliquez sur l'icône représentant une roue dentée, puis sélectionnez Configuration.
  2. Dans le menu Configuration, recherchez et sélectionnez Gestionnaire d'applications comme illustré sur l'image ci-dessous : image illustrant la page de configurationimage illustrant la page de configuration
  3. Cliquez sur New Connected App (Nouvelle application connectée).
  4. Dans le volet de configuration, saisissez les informations suivantes :
    • Nom de l'application connectée : saisissez un nom pour votre application connectée.
    • Nom de l'API : saisissez le nom de l'API.
    • Adresse e-mail de contact : saisissez une adresse e-mail pour votre application connectée, idéalement un alias d'adresse e-mail de groupe.
    • API (Activer les paramètres OAuth) : sélectionnez Activer les paramètres OAuth. Ensuite, définissez les éléments suivants :
      1. (Facultatif) URL de rappel : cette étape est nécessaire uniquement si vous souhaitez qu'un service externe effectue la validation. Si vous choisissez de fournir un rappel, assurez-vous d'inclure le préfixe http(s)://.
      2. Champs d'application OAuth sélectionnés : Sélectionnez :
        • Accéder à vos données et les gérer (API)
        • Effectuer des requêtes en votre nom à tout moment (refresh_token, offline_access)
  5. Cliquez sur Enregistrer.
  6. Cliquez sur Continuer.
  7. Un secret client et une clé client s'affichent sur la page suivante. Notez ces valeurs, car elles seront utilisées lors de la configuration du module d'authentification pour Apigee.
  8. Cliquez sur le bouton Gérer.
  9. Une fois sur la page Détails de l'application connectée, cliquez sur le bouton Modifier les règles.
  10. Dans la section Règles OAuth, remplacez la valeur du menu déroulant Utilisateurs autorisés par Les utilisateurs approuvés par l'administrateur sont pré-autorisés.
  11. Cliquez sur Enregistrer.
  12. Faites défiler la page jusqu'à la section Profils et Ensembles d'autorisations pour sélectionner le profil ou l'ensemble d'autorisations que vous souhaitez appliquer à l'application connectée.
  13. Sélectionnez le profil ou l'ensemble d'autorisations de votre choix.
  14. Cliquez sur Enregistrer.

Étapes préalables à l'utilisation d'événements CDC

Avant de configurer votre déclencheur Apigee Integration pour utiliser des événements CDC, assurez-vous, dans Salesforce, d'ajouter un objet configuré aux événements CDC :

  1. Connectez-vous à Salesforce en tant que sysadmin.
  2. Cliquez sur l'icône en forme de roue dentée, puis sur Configuration.
  3. Dans le menu de navigation de gauche, recherchez et sélectionnez Capture de données modifiées.
  4. Sur la page de configuration Capture de données modifiées, localisez l'objet Salesforce que vous souhaitez utiliser dans la colonne Entités disponibles et faites-le glisser vers la colonne Entités sélectionnées.
  5. Cliquez sur Enregistrer.

Étapes préalables à l'utilisation d'événements Plate-forme

Avant de configurer votre déclencheur Apigee Integration pour utiliser des événements Plate-forme, réalisez les étapes suivantes dans Salesforce :

  • Créer un événement Plate-forme
  • Mettre à jour les autorisations pour l'événement Plate-forme

Créer un événement Plate-forme

Procédez comme suit pour créer un événement Plate-forme :

  1. Connectez-vous à votre instance Salesforce à l'aide de vos identifiants sysadmin.
  2. Cliquez sur l'icône représentant une roue dentée, puis sélectionnez Configuration.
  3. Dans le volet de navigation, recherchez Plate-forme, puis cliquez sur Événements de plate-forme.
  4. image montrant un nouvel événement de plate-formeimage montrant un nouvel événement de plate-forme
  5. Sur la page Événements de plate-forme, cliquez sur Nouvel événement de plate-forme et définissez les propriétés suivantes :
  • Label
  • Libellé pluriel
  • Nom de l'objet (ce champ est renseigné automatiquement)
  • Comportement de publication Sélectionnez l'une des valeurs suivantes :
    • Publier après le commit : annule la diffusion des événements si une condition n'est pas remplie.
    • Publier immédiatement : déclenche instantanément l'événement, sans attendre de validation.
    Pour en savoir plus sur le comportement de publication, consultez la page Événements Plate-forme et transactions.
  • État du déploiement (facultatif) : sélectionnez Déployé si l'événement est prêt à être déployé.
  • Cliquez sur Enregistrer.
  • image montrant le paramétrage des libellés et du comportement de publication pour un événement de plate-formeimage montrant le paramétrage des libellés et du comportement de publication pour un événement de plate-forme
  • Créez des champs personnalisés. Pour créer des champs personnalisés, cliquez sur Nouveau dans la section Champs et relations personnalisés, puis sélectionnez le type de champ personnalisé. Vous pouvez créer autant de champs personnalisés que nécessaire.
  • Après avoir créé les champs personnalisés, notez la valeur du champ Nom d'API sur la page Événements de plate-forme. Le nom de l'objet se termine par _e, ce qui signifie qu'il s'agit d'un objet d'événement de plate-forme. Pour un objet CDC, le nom de l'objet se termine par _c.

    image montrant les détails d'un événement de plate-forme enregistréimage montrant les détails d'un événement de plate-forme enregistré

    Mettre à jour les autorisations pour l'événement Plate-forme

    L'ensemble d'autorisations doit être mis à jour pour permettre à l'utilisateur d'intégration d'accéder à l'événement de plate-forme nouvellement créé.

    Pour mettre à jour les autorisations, procédez comme suit :

    1. Dans le menu Configuration, cliquez sur Utilisateurs > Ensembles d'autorisations.
    2. Sur la page Ensembles d'autorisations, cliquez sur l'autorisation créée précédemment.
    3. Cliquez sur Paramètres d'objet > Plural Label of the Platform Event.
    4. Dans la section Autorisations concernant les objets, activez les autorisations de lecture et de création.
    5. Cliquez sur Enregistrer.
    6. image montrant les autorisations d'un événement de plate-formeimage montrant les autorisations d'un événement de plate-forme

    Ajouter un déclencheur Salesforce

    Procédez comme suit pour ajouter un déclencheur Salesforce à une intégration nouvelle ou existante :
    1. Dans l'interface utilisateur Apigee, sélectionnez votre organisation Apigee.
    2. Cliquez sur Développer > Intégrations.
    3. Sélectionnez une intégration existante ou créez-en une en cliquant sur Créer une intégration.

      Si vous créez une intégration :

      1. Saisissez un nom et une description dans la boîte de dialogue Créer une intégration.
      2. Dans la liste des régions compatibles, sélectionnez une région pour l'intégration.
      3. Cliquez sur Créer.

      La page de conception d'intégration s'affiche.

    4. Dans la barre de navigation de la page de conception d'intégration, cliquez sur +Ajouter une tâche ou un déclencheur > Tâches pour afficher la liste des tâches disponibles.
    5. Sélectionnez une intégration existante ou cliquez sur Créer une intégration.
    6. Dans l'éditeur d'intégrations, cliquez sur + Ajouter une tâche/un déclencheur > Déclencheurs pour afficher les déclencheurs disponibles.
    7. Cliquez sur l'élément Déclencheur Salesforce et placez-le dans le concepteur.

    Configurer le déclencheur Salesforce

    Procédez comme suit pour configurer le déclencheur Salesforce :

    1. Cliquez sur Déclencheur Salesforce dans l'éditeur d'intégrations pour afficher le volet de configuration du déclencheur.
    2. Sélectionnez une instance Salesforce dans le menu déroulant Configuration de l'instance Salesforce.

      Si vous ne disposez pas d'une instance Salesforce, créez-en une. Pour en savoir plus, consultez la section Créer une instance Salesforce.

    3. Sélectionnez un canal de distribution Salesforce dans la liste déroulante Configuration du canal de distributin Salesforce.

      Si vous ne disposez pas d'un canal de distribution Salesforce, créez-en un. Pour plus d'informations, consultez Créer un canal de distribution Salesforce.

    4. Si vous avez choisi le type d'événement CDC, sélectionnez l'une des opérations suivantes :
      • Create
      • Update
      • Delete
      • Undelete

      Le déclencheur ne s'exécute que si l'opération spécifique ou l'opération d'écart se produit.

      Le déclencheur Salesforce ne peut être configuré que pour une seule opération. Si vous souhaitez exécuter le déclencheur pour plusieurs opérations, créez un déclencheur Salesforce pour chaque opération.

    Créer une instance Salesforce

    Pour configurer une nouvelle instance Salesforce, procédez comme suit :

    1. Dans les propriétés modifiables du déclencheur, cliquez sur Sélectionner une configuration d'instance Salesforce > + Ajouter une configuration d'instance Salesforce.
    2. Dans la boîte de dialogue Ajouter une configuration d'instance Salesforce, définissez les propriétés suivantes :
      • Nom de connexion de l'instance Salesforce : saisissez un nom pour l'instance.

        Après la configuration, vous utiliserez ce nom pour faire référence à l'instance Salesforce.

      • Domaine Salesforce : saisissez une autorité de service pour l'instance. Vous trouverez ce domaine dans votre compte Salesforce. Par exemple, instance.my.salesforce.com. L'image suivante illustre le domaine Salesforce :

        Obtention du domaine Salesforce dans une instance Salesforce Obtention du domaine Salesforce dans une instance Salesforce

      • Profil d'authentification : sélectionnez un profil d'authentification.

        Si vous ne possédez pas de profil d'authentification, créez-en un. Pour en savoir plus, consultez Créer un profil d'authentification.

      • ID d'organisation Salesforce : saisissez ID d'organisation de l'instance Salesforce. Vous pouvez obtenir cet ID auprès de votre administrateur Salesforce.
    3. Cliquez sur Ajouter.

    Créer un canal de distribution Salesforce

    Pour configurer un nouveau canal Salesforce, procédez comme suit :

    1. Dans les propriétés modifiables du déclencheur, cliquez sur Sélectionner un canal de distribution Salesforce > + Ajouter une configuration de canal de distribution Salesforce.
    2. Dans la boîte de dialogue Ajouter une configuration de canal de distribution Salesforce, saisissez le nom d'objet de la propriété Nom de l'objet Salesforce.

      Si vous n'êtes pas sûr du nom de l'objet, contactez votre administrateur Salesforce.

    3. Cliquez sur Ajouter.

    Variables de sortie

    La réponse du déclencheur Salesforce est disponible dans les variables de sortie.

    Les variables de sortie d'un événement CDC sont décrites dans le tableau suivant :

    Variable Type de données Description
    SalesforceTriggerCdcPayload JSON Détails de l'événement de modification.
    SalesforceTriggerEvent JSON Contient le replayId de l'événement.
    SalesforceTriggerSchema Chaîne Schéma du déclencheur.
    SalesforceTriggerCdcSnapshot JSON Instantané de l'objet après l'événement de modification. Ce champ n'est disponible que pour les opérations Update et Create.
    SalesforceTriggerCdcRecordId Chaîne Contient l'enregistrement recordId mis à jour ou ajouté. recordId est l'identifiant de l'objet Salesforce modifié.

    Les variables de sortie d'un événement Plate-forme sont décrites dans le tableau suivant :

    Variable Type de données Description
    SalesforceTriggerPEPayload JSON Détails de l'événement de modification.
    SalesforceTriggerEvent JSON Contient le replayId de l'événement.
    SalesforceTriggerSchema Chaîne Schéma du déclencheur.
    Le paramètre de sortie pour ce déclencheur est la variable JSON CdcTriggerPayload. La variable JSON contient des objets d'enregistrement mis à jour.

    Bonnes pratiques

    L'utilisation du déclencheur Salesforce est recommandée dans les cas où vous souhaitez utiliser des notifications Salesforce pour déclencher des intégrations sans écrire de code personnalisé pour publier des événements Salesforce. Toute modification de champ dans votre demande Salesforce, même mineure, déclenche un événement de CDC Salesforce, qui déclenche une intégration, ce qui peut générer un bruit d'intégration conséquent. Pensez à utiliser les filtres d'événements de modification pour ne filtrer que les événements CDC requis qui déclenchent l'intégration. L'utilisation de filtres d'événements de modification peut contribuer à réduire le bruit d'intégration et à garantir le bon respect des limites de votre licence.

    De même, nous vous recommandons d'annuler la publication d'une intégration à l'aide de ce déclencheur lorsque celle-ci n'est plus nécessaire. Tant que sa publication n'a pas été annulée ou qu'elle n'a pas été supprimée, l'intégration continue d'écouter les événements Salesforce CDC et Plate-forme.

    Points à prendre en compte

    Avant d'utiliser le déclencheur Salesforce pour exécuter votre intégration, tenez compte des points suivants :

    • Salesforce envoie généralement un maximum de 100 000 événements de CDC et de plate-forme par jour. Contactez votre administrateur Salesforce pour connaître les restrictions de licence avant de choisir des événements CDC pour votre déclencheur d'intégration.
    • Si vous envisagez d'effectuer des importations groupées dans Salesforce, pensez à suspendre le CDC pour réduire le bruit d'intégration et assurer la conformité avec les limites de votre licence.
    • La taille maximale de message d'événement que Salesforce peut publier est de 1 Mo. Pour en savoir plus, consultez la page Allocations de capture des données modifiées.
    • Apigee Integration n'accepte pas les événements Salesforce CDC pour les régions de mini-clusters suivantes :
      • asia-northeast1
      • asia-south1
      • australia-southeast1
      • europe-west2
      • europe-west3
      • europe-west6
      • northamerica-northeast1
      • southamerica-east1
      • us-east4
      • us-west2