Cette page a été traduite par l'API Cloud Translation.

Intégration à Salesforce (SFDC)

Cette page décrit les étapes d'intégration de la charge de travail opérationnelle Salesforce (SFDC) dans la fondation de données du framework Cortex. Cortex Framework intègre les données de Salesforce aux pipelines Dataflow via BigQuery, tandis que Cloud Composer planifie et surveille ces pipelines Dataflow pour obtenir des insights à partir de vos données.

Fichier de configuration

Le fichier config.json du répertoire Cortex Framework Data Foundation configure les paramètres requis pour transférer des données à partir de n'importe quelle source de données, y compris Salesforce. Ce fichier contient les paramètres suivants pour les charges de travail Salesforce opérationnelles:

    "SFDC": {
        "deployCDC": true,
        "createMappingViews": true,
        "createPlaceholders": true,
        "datasets": {
            "cdc": "",
            "raw": "",
            "reporting": "REPORTING_SFDC"
        }
    }

Le tableau suivant décrit la valeur de chaque paramètre opérationnel SFDC:

Paramètre	Signification	Valeur par défaut	Description
`SFDC.deployCDC`	Déployer la CDC	`true`	Générez des scripts de traitement CDC à exécuter en tant que DAG dans Cloud Composer. Consultez la documentation pour découvrir les différentes options d'ingestion pour Salesforce Sales Cloud.
`SFDC.createMappingViews`	Créer des vues de mappage	`true`	Les DAG fournis pour extraire de nouveaux enregistrements à partir des API Salesforce mettent à jour les enregistrements à l'atterrissage. Lorsque cette valeur est définie sur "true", des vues sont générées dans l'ensemble de données traité par le CDC afin d'afficher des tableaux avec la "dernière version de la vérité" de l'ensemble de données brut. Si la valeur est false et que `SFDC.deployCDC` est `true`, les DAG sont générés avec le traitement CDC (Change Data Capture) basé sur SystemModstamp. Pour en savoir plus sur le traitement CDC pour Salesforce, consultez les détails.
`SFDC.createPlaceholders`	Créer des espaces réservés	`true`	Créez des tables d'espace réservé vides au cas où elles ne seraient pas générées par le processus d'ingestion afin de permettre l'exécution du déploiement des rapports en aval sans erreur.
`SFDC.datasets.raw`	Ensemble de données de destination brut	-	Utilisé par le processus CDC, c'est là que l'outil de réplication place les données de Salesforce. Si vous utilisez des données de test, créez un ensemble de données vide.
`SFDC.datasets.cdc`	Ensemble de données traité par la CDC	-	Ensemble de données qui sert de source pour les vues de création de rapports et de cible pour les DAG des enregistrements traités. Si vous utilisez des données de test, créez un ensemble de données vide.
`SFDC.datasets.reporting`	Ensemble de données de rapport SFDC	`"REPORTING_SFDC"`	Nom de l'ensemble de données accessible aux utilisateurs finaux pour la création de rapports, où les vues et les tables destinées aux utilisateurs sont déployées.
`SFDC.currencies`	Filtrer les devises	`[ "USD" ]`	Si vous n'utilisez pas de données de test, saisissez une seule devise (par exemple, `[ "USD" ]`) ou plusieurs devises (par exemple,`[ "USD", "CAD" ]`) en fonction de votre activité. Ces valeurs sont utilisées pour remplacer les espaces réservés dans SQL dans les modèles d'analyse, le cas échéant.

Modèle de données

Cette section décrit le modèle de données Salesforce (SFDC) à l'aide du diagramme des relations entre entités (ERD).

Figure 2 Salesforce (SFDC): diagramme des relations entre entités.

Vues de base

Il s'agit des objets bleus de l'ERD. Il s'agit de vues sur les tables CDC sans autre transformation que certains alias de nom de colonne. Consultez les scripts dans src/SFDC/src/reporting/ddls.

Vues de rapports

Il s'agit des objets verts de l'ERD et ils contiennent les attributs dimensionnels pertinents utilisés par les tableaux de rapports. Consultez les scripts dans src/SFDC/src/reporting/ddls.

Exigences concernant les données Salesforce

Cette section décrit précisément comment vos données Salesforce doivent être structurées pour être utilisées avec Cortex Framework.

Structure de la table:
- Noms:les noms de table utilisent snake_case (mots en minuscules séparés par des traits de soulignement) et sont au pluriel. Par exemple, some_objects.
- Types de données:les colonnes conservent les mêmes types de données que ceux représentés dans Salesforce.
- Lisibilité:certains noms de champs peuvent être légèrement ajustés pour plus de clarté dans la couche de création de rapports.
Tables vides et déploiement:toutes les tables requises manquantes dans l'ensemble de données brut sont automatiquement créées en tant que tables vides lors du processus de déploiement. Cela garantit une exécution fluide de l'étape de déploiement du CDC.
Exigences concernant la capture de données modifiées:les champs Id et SystemModstamp sont essentiels pour que les scripts de capture de données modifiées puissent suivre les modifications apportées à vos données. Ils peuvent porter ces noms exacts ou d'autres. Les scripts de traitement brut fournis extraient automatiquement ces champs à partir des API et mettent à jour la table de réplication cible.
- Id: sert d'identifiant unique pour chaque enregistrement.
- SystemModstamp: ce champ stocke un code temporel indiquant la dernière fois qu'un enregistrement a été modifié.
Scripts de traitement brut:les scripts de traitement brut fournis ne nécessitent pas de traitement supplémentaire (CDC). Ce comportement est défini par défaut lors du déploiement.

Tables sources pour la conversion des devises

Salesforce vous permet de gérer les devises de deux manières:

Standard:option par défaut, dans laquelle toutes les données utilisent une seule devise.
Avancé: permet de convertir plusieurs devises en fonction des taux de change (requiert l'activation de la gestion avancée des devises).

Si vous utilisez la gestion avancée des devises, Salesforce utilise deux tables spéciales:

CurrencyTypes: ce tableau stocke des informations sur les différentes devises que vous utilisez (par exemple, USD, EUR, etc.).
DatedConversionRates: ce tableau contient les taux de change entre les devises au fil du temps.

Cortex Framework s'attend à ce que ces tables soient présentes si vous utilisez la gestion avancée des devises. Si vous n'utilisez pas la gestion avancée des devises, vous pouvez supprimer les entrées associées à ces tables d'un fichier de configuration (src/SFDC/config/ingestion_settings.yaml). Cette étape évite les tentatives inutiles d'extraction de données à partir de tables inexistantes.

Charger des données SFDC dans BigQuery

Cortex Framework fournit une solution de réplication basée sur des scripts Python planifiés dans Apache Airflow et Salesforce Bulk API 2.0. Ces scripts Python peuvent être adaptés et planifiés dans l'outil de votre choix. Pour en savoir plus, consultez la section Module d'extraction SFDC.

Cortex Framework propose également trois méthodes différentes pour intégrer vos données, en fonction de leur origine et de leur gestion:

Appels d'API:cette option s'applique aux données auxquelles vous pouvez accéder directement via une API. Cortex Framework peut appeler l'API, récupérer les données et les stocker dans un ensemble de données "brut" dans BigQuery. Si des enregistrements existent dans l'ensemble de données, Cortex Framework peut les mettre à jour avec les nouvelles données.
Vues de mappage de structure:cette méthode est utile si vous avez déjà chargé vos données dans BigQuery à l'aide d'un autre outil, mais que la structure des données ne correspond pas à ce dont Cortex Framework a besoin. Cortex Framework utilise des "vues" (comme des tables virtuelles) pour traduire la structure de données existante au format attendu par les fonctionnalités de reporting de Cortex Framework.
Scripts de traitement de la capture de données modifiées (CDC):cette option est conçue spécifiquement pour les données qui changent constamment. Les scripts CDC suivent ces modifications et mettent à jour les données dans BigQuery en conséquence. Ces scripts s'appuient sur deux champs spéciaux de vos données:
- Id: identifiant unique de chaque enregistrement.
- SystemModstamp: code temporel indiquant la date et l'heure de modification d'un enregistrement.
Si vos données ne portent pas ces noms exacts, les scripts peuvent être ajustés pour les reconnaître avec des noms différents. Vous pouvez également ajouter des champs personnalisés à votre schéma de données au cours de ce processus. Par exemple, la table source contenant les données de l'objet Compte doit comporter les champs Id et SystemModstamp d'origine. Si ces champs portent des noms différents, le fichier src/SFDC/src/table_schema/accounts.csv doit être mis à jour avec le nom du champ Id mappé sur AccountId et le champ de code temporel de modification du système mappé sur SystemModstamp. Pour en savoir plus, consultez la documentation sur SystemModStamp.

Si vous avez déjà chargé des données via un autre outil (et qu'elles sont constamment mises à jour), Cortex peut toujours les utiliser. Les scripts CDC sont fournis avec des fichiers de mappage pouvant traduire votre structure de données existante dans le format dont Cortex Framework a besoin. Vous pouvez même ajouter des champs personnalisés à vos données au cours de ce processus.

Configurer l'intégration de l'API et le CDC

Pour importer vos données Salesforce dans BigQuery, vous pouvez utiliser les méthodes suivantes:

Scripts Cortex pour les appels d'API: fournit des scripts de réplication pour Salesforce ou un outil de réplication de données de votre choix.L'essentiel est que les données que vous importez doivent se présenter de la même manière que si elles provenaient des API Salesforce.
Outil de réplication et ajout toujours : si vous utilisez un outil de réplication, cette option est destinée à un outil pouvant ajouter de nouveaux enregistrements de données (_appendalways_pattern) ou mettre à jour des enregistrements existants.
Outil de réplication et ajout d'enregistrements: si l'outil ne met pas à jour les enregistrements et réplique les modifications en tant que nouveaux enregistrements dans une table cible (brute), Cortex Data Foundation vous permet de créer des scripts de traitement CDC. Pour en savoir plus, consultez le processus CDC.

Charge de travail Salesforce: options d'intégration des données

Figure 1 Charge de travail Salesforce: options d'intégration des données

Pour vous assurer que vos données correspondent à ce que Cortex Framework attend, vous pouvez ajuster la configuration de mappage pour mapper votre outil de réplication ou vos schémas existants. Cela génère des vues de mappage compatibles avec la structure attendue par l'infrastructure de données Cortex Framework.

Utilisez le fichier ingestion_settings.yaml pour configurer la génération de scripts permettant d'appeler les API Salesforce et de répliquer les données dans l'ensemble de données brut (section salesforce_to_raw_tables), ainsi que la génération de scripts permettant de traiter les modifications entrantes dans l'ensemble de données brut et dans l'ensemble de données traité par CDC (section raw_to_cdc_tables).

Par défaut, les scripts fournis pour lire à partir des API mettent à jour les modifications dans le jeu de données brut. Par conséquent, les scripts de traitement CDC ne sont pas nécessaires, et des vues de mappage sont créées pour aligner le schéma source sur le schéma attendu.

La génération de scripts de traitement CDC n'est pas exécutée si SFDC.createMappingViews=true est défini dans config.json (comportement par défaut). Si des scripts CDC sont requis, définissez SFDC.createMappingViews=false. Cette deuxième étape permet également de mapper les schémas sources dans les schémas requis, comme l'exige l'infrastructure de données Cortex Framework.

L'exemple de fichier de configuration setting.yaml suivant illustre la génération de vues de mappage lorsqu'un outil de réplication met à jour les données directement dans l'ensemble de données répliqué, comme illustré dans option 3 (c'est-à-dire qu'aucun CDC n'est requis, uniquement un remappage des tables et des noms de champs). Étant donné qu'aucun CDC n'est requis, cette option s'exécute tant que le paramètre SFDC.createMappingViews du fichier config.json reste true.

  salesforce_to_raw_tables:
  - base_table: accounts
    raw_table: Accounts
    api_name: Account
      load_frequency: "@daily"
  - base_table: cases
    raw_table: cases2
    api_name: Case
    load_frequency: "@daily"

Dans cet exemple, la suppression de la configuration d'une table de base ou de toutes les tables de base des sections ignore la génération des DAG de cette table de base ou de l'ensemble de la section, comme illustré pour salesforce_to_raw_tables. Dans ce scénario, définir le paramètre deployCDC : False a le même effet, car aucun script de traitement CDC ne doit être généré.

Mappage de données

Vous devez mapper les champs de données entrantes au format attendu par Cortex Data Foundation. Par exemple, un champ nommé unicornId de votre système de données source doit être renommé et reconnu comme AccountId (avec un type de données de chaîne) dans Cortex Data Foundation:

Champ source: unicornId (nom utilisé dans le système source)
Champ Cortex: AccountId (nom attendu par Cortex)
Type de données: String (type de données attendu par Cortex)

Mappage des champs polymorphes

Cortex Framework Data Foundation prend en charge la mise en correspondance de champs polymorphes, dont le nom peut varier, mais dont la structure reste cohérente. Les noms de types de champ polymorphes (par exemple, Who.Type) peuvent être répliqués en ajoutant un élément [Field Name]_Type dans les fichiers CSV de mappage respectifs : src/SFDC/src/table_schema/tasks.csv. Par exemple, si vous devez répliquer le champ Who.Type de l'objet Task, ajoutez la ligne Who_Type,Who_Type,STRING. Cela définit un nouveau champ nommé Who.Type qui se mappe lui-même (conserve le même nom) et qui a un type de données de chaîne.

Modifier des modèles de DAG

Vous devrez peut-être ajuster les modèles DAG pour CDC ou pour le traitement des données brutes, selon les besoins de votre instance d'Airflow ou de Cloud Composer. Pour en savoir plus, consultez la section Recueillir les paramètres Cloud Composer.

Si vous n'avez pas besoin de CDC ni de génération de données brutes à partir d'appels d'API, définissez deployCDC=false. Vous pouvez également supprimer le contenu des sections dans ingestion_settings.yaml. Si les structures de données sont connues pour être cohérentes avec celles attendues par Cortex Framework Data Foundation, vous pouvez ignorer la génération des vues de mappage en définissant SFDC.createMappingViews=false.

Configurer le module d'extraction

Cette section présente les étapes à suivre pour utiliser le module d'extraction Salesforce vers BigQuery fourni par Data Foundation. Vos exigences et votre flux peuvent varier en fonction de votre système et de votre configuration existante. Vous pouvez également utiliser d'autres outils disponibles.

Configurer les identifiants et l'application associée

Connectez-vous en tant qu'administrateur à votre instance Salesforce pour effectuer les opérations suivantes:

Créez ou identifiez un profil dans Salesforce qui répond aux exigences suivantes :
1. Permission for Apex REST Services and API Enabled est accordée sous Autorisations système.
2. L'autorisation View All est accordée pour tous les objets que vous souhaitez répliquer. (par exemple, "Compte" et "Demandes"). Vérifiez auprès de votre administrateur de sécurité s'il existe des restrictions ou des problèmes.
3. Aucune autorisation accordée pour les connexions à l'interface utilisateur, comme Salesforce Anywhere dans Lightning Experience, Salesforce Anywhere sur mobile, l'utilisateur Lightning Experience et l'utilisateur de la connexion Lightning. Vérifiez si votre administrateur de sécurité a mis en place des restrictions ou des problèmes.
Créez ou utilisez un identifiant utilisateur existant dans Salesforce. Vous devez connaître le nom d'utilisateur, le mot de passe et le jeton de sécurité de l'utilisateur. Réfléchissez aux points suivants :
- Idéalement, il doit s'agir d'un utilisateur dédié à l'exécution de cette réplication.
- L'utilisateur doit être attribué au profil que vous avez créé ou identifié à l'étape 1.
- Vous pouvez voir le nom d'utilisateur et réinitialiser le mot de passe ici.
- Vous pouvez réinitialiser le jeton de sécurité si vous ne l'avez pas et qu'il n'est pas utilisé par un autre processus.
Créez une application connectée. Il s'agit du seul canal de communication permettant d'établir une connexion à Salesforce depuis le monde extérieur à l'aide du profil, de l'API Salesforce, des identifiants utilisateur standards et de son jeton de sécurité.
1. Suivez les instructions pour activer les paramètres OAuth pour l'intégration d'API.
2. Assurez-vous que Require Secret for Web Server Flow et Require Secretfor Refresh Token Flow sont activés dans la section API (Enabled OAuth Settings) (API (Paramètres OAuth activés)).
3. Consultez la documentation pour savoir comment obtenir votre clé client (qui sera ensuite utilisée comme ID client). Contactez votre administrateur de sécurité pour connaître les problèmes ou les restrictions.
Attribuez votre application connectée au profil créé.
1. Sélectionnez Configuration en haut à droite de l'écran d'accueil de Salesforce.
2. Dans la zone Quick Find (Recherche rapide), saisissez profile, puis sélectionnez Profile (Fiches). Recherchez le profil créé à l'étape 1.
3. Ouvrez le profil.
4. Cliquez sur le lien Applications connectées attribuées.
5. Cliquez sur Modifier.
6. Ajoutez l'application connectée nouvellement créée.
7. Cliquez sur le bouton Enregistrer.

Configurer Secret Manager

Configurez Secret Manager pour stocker les informations de connexion. Le module Salesforce-to-BigQuery s'appuie sur Secret Manager pour stocker de manière sécurisée les identifiants dont il a besoin pour se connecter à Salesforce et à BigQuery. Cette approche évite d'exposer des informations sensibles telles que des mots de passe directement dans votre code ou vos fichiers de configuration, ce qui renforce la sécurité.

Créez un secret avec les spécifications suivantes. Pour en savoir plus, consultez la section Créer un secret.

Nom du secret: airflow-connections-salesforce-conn
Valeur du secret:
```
http://USERNAME:PASSWORD@https%3A%2F%2FINSTANCE_NAME.lightning.force.com?client_id=CLIENT_ID&security_token=SECRET_TOKEN`
```
Remplacez les éléments suivants :
- USERNAME par votre nom d'utilisateur.
- PASSWORD par votre mot de passe.
- INSTANCE_NAME par le nom de l'instance.
- CLIENT_ID par votre ID client.
- SECRET_TOKEN par votre jeton secret.

Pour en savoir plus, consultez Comment trouver le nom de votre instance.

Bibliothèques Cloud Composer pour la réplication

Pour exécuter les scripts Python dans les DAG fournis par l'infrastructure de données Cortex Framework, vous devez installer certaines dépendances. Pour Airflow version 1.10, suivez la documentation Install Python dependencies for Cloud Composer 1 (Installer les dépendances Python pour Cloud Composer 1) pour installer les packages suivants, dans l'ordre:

tableauserverclient==0.17
apache-airflow-backport-providers-salesforce==2021.3.3

Pour Airflow version 2.x, consultez la documentation Install Python dependencies for Cloud Composer 2 documentation (Installer des dépendances Python pour Cloud Composer 2) pour installer apache-airflow-providers-salesforce~=5.2.0.

Utilisez la commande suivante pour installer chaque package requis:

  gcloud composer environments update ENVIRONMENT_NAME \
  --location LOCATION \
   --update-pypi-package PACKAGE_NAME EXTRAS_AND_VERSION

Remplacez les éléments suivants :

ENVIRONMENT_NAME par le nom de l'environnement attribué.
LOCATION par l'emplacement.
PACKAGE_NAME par le nom du package choisi.
EXTRAS_AND_VERSION avec les spécifications des extras et de la version.

La commande suivante est un exemple d'installation de package requise:

gcloud composer environments update my-composer-instance \
  --location us-central1 \
  --update-pypi-package apache-airflow-backport-providers-salesforce>=2021.3.3

Activer Secret Manager en tant que backend

Activez Google Secret Manager comme backend de sécurité. Cette étape vous invite à activer Secret Manager comme emplacement de stockage principal pour les informations sensibles telles que les mots de passe et les clés API utilisées par votre environnement Cloud Composer. Cela améliore la sécurité en centralisant et en gérant les identifiants dans un service dédié. Pour en savoir plus, consultez Secret Manager.

Autoriser le compte de service Composer à accéder aux secrets

Cette étape garantit que le compte de service associé à Cloud Composer dispose des autorisations nécessaires pour accéder aux secrets stockés dans Secret Manager. Par défaut, Cloud Composer utilise le compte de service Compute Engine. L'autorisation requise est Secret Manager Secret Accessor. Cette autorisation permet au compte de service de récupérer et d'utiliser les secrets stockés dans Secret Manager.Pour obtenir un guide complet sur la configuration des contrôles des accès dans Secret Manager, consultez la documentation sur le contrôle des accès.

Connexion BigQuery dans Airflow

Veillez à créer la connexion sfdc_cdc_bq conformément à la section Collecter les paramètres Cloud Composer. Cette connexion est probablement utilisée par le module Salesforce-to-BigQuery pour établir la communication avec BigQuery.

Étape suivante

Pour en savoir plus sur les autres sources de données et charges de travail, consultez la page Sources de données et charges de travail.
Pour en savoir plus sur les étapes de déploiement dans les environnements de production, consultez la section Conditions préalables au déploiement de Cortex Framework Data Foundation.