Déclencheur Salesforce

Annonce : Application Integration est désormais disponible pour votre projet Google Cloud. Vous pouvez désormais utiliser Apigee Integration et Application Integration dans le même projet Google Cloud. En savoir plus

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
• Configurer un ensemble d'autorisations
• Configurer un jeton de sécurité
• Créer une application connectée

Remarque : Pour effectuer ces étapes, vous devez disposer d'un accès d'administrateur système à votre instance Salesforce. Si vous ne disposez pas d'un accès administrateur, partagez ces instructions avec votre administrateur Salesforce.

Ce tutoriel fournit des instructions détaillées, mais il est recommandé d'avoir une bonne connaissance des options de configuration de Salesforce. Salesforce fournit une documentation détaillée destinée aux développeurs, qui vous aidera à faire vos premiers pas.

Configurer un utilisateur d'intégration

Remarque : Si vous disposez déjà d'un utilisateur d'intégration et connaissez le mot de passe, vous pouvez passer à l'étape suivante. Si vous devez réinitialiser le mot de passe, consultez l'étape 6 ci-dessous.

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 :
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.
      Remarque : Confirmez que vous avez accès au compte de messagerie associé à l'utilisateur d'intégration avant de déclencher le flux de réinitialisation du mot de passe. De plus, si vous avez activé l'authentification SSO pour cet utilisateur, vous ne pourrez pas réinitialiser le mot de passe. Pour activer l'option de réinitialisation, accédez à Profil > Autorisations système, puis décochez l'option Connexion SSO activée.
   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 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.
   REMARQUE : La CDC n'accepte qu'un sous-ensemble d'objets Salesforce standards. Pour en savoir plus, consultez la page Modifier la compatibilité des objets d'événement.
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.
   Remarque : L'accès en écriture n'est pas nécessaire pour l'utilisation de la CDC.
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 :
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.
   Remarque : L'application associée que vous venez de créer ne fonctionnera pas pendant les 2 à 10 minutes suivant sa création.
6. Cliquez sur Continuer. Vous devez procéder à nouveau à l'autorisation à l'aide d'un code de validation envoyé à votre adresse e-mail.
7. Une fois le code validé, 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.
    Vous pouvez sélectionner un profil, un ensemble d'autorisations ou une combinaison des deux, afin que les utilisateurs disposant du profil ou de l'ensemble d'autorisations appropriés puissent accéder à 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.
   Remarque : Vous pouvez sélectionner jusqu'à cinq objets par licence Salesforce pour la CDC. Pour plus d'informations et d'options de licence, contactez votre représentant Salesforce.
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. 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.

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.

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.

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 :

  

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

  Si vous ne possédez pas de profil d'authentification, créez un profil dont le type d'authentification soit défini sur Identifiants de mots de passe des propriétaires de ressources OAuth 2.0. L'image suivante montre les champs requis pour créer un profil d'authentification :

  

  Pour en savoir plus sur les champs, consultez la section Identifiants de mots de passe des propriétaires de ressources OAuth 2.0. Pour l'instance Salesforce, saisissez les valeurs suivantes :
  • ID client : saisissez la clé client que vous avez notée lors de la configuration d'une application connectée.
  • Secret : saisissez le code secret du client que vous avez noté lors de la configuration d'une application connectée.
  • Mot de passe : saisissez le mot de passe de l'utilisateur au format USER_PASSWORDSECURITY_TOKEN. Remplacez les éléments suivants :
    • USER_PASSWORD : mot de passe de l'utilisateur Salesforce.
    • SECURITY_TOKEN : jeton de sécurité que vous avez défini pour votre intégration.
    Par exemple, si votre USER_PASSWORD est test-password et que votre SECURITY_TOKEN est 737K27NCa3O6, votre mot de passe sera test-password737K27NCa3O6.
• 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.

Remarques

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.
  Remarque : Plusieurs intégrations utilisant le même canal Salesforce ne double pas votre consommation de quota Salesforce.
• 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 n'accepte pas les événements Salesforce CDC pour les régions suivantes :
  • asia-northeast1
  • asia-south1
  • australia-southeast1
  • europe-west2
  • europe-west3
  • europe-west6
  • northamerica-northeast1
  • southamerica-east1
  • us-east4
  • us-west2