Integrazione con Salesforce (SFDC)

Questa pagina descrive i passaggi di integrazione per il carico di lavoro operativo di Salesforce (SFDC) in Data Foundation di Cortex Framework. Cortex Framework integra i dati di Salesforce con le pipeline Dataflow tramite BigQuery, mentre Cloud Composer pianifica e monitora queste pipeline Dataflow per ottenere approfondimenti dai tuoi dati.

File di configurazione

Il file config.json nel repository di Cortex Framework Data Foundation configura le impostazioni necessarie per trasferire i dati da qualsiasi origine dati, inclusa Salesforce. Questo file contiene i seguenti parametri per i carichi di lavoro Salesforce operativi:

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

La tabella seguente descrive il valore di ciascun parametro operativo SFDC:

Parametro Significato Valore predefinito Descrizione
SFDC.deployCDC Esegui il deployment di CDC true Genera script di elaborazione CDC da eseguire come DAG in Cloud Composer. Consulta la documentazione per le diverse opzioni di importazione per Salesforce Sales Cloud.
SFDC.createMappingViews Crea viste di mappatura true I DAG forniti per recuperare i nuovi record dalle API Salesforce aggiornano i record al momento dell'atterraggio. Se questo valore è impostato su true, vengono generate visualizzazioni nel set di dati elaborato da CDC per esporre le tabelle con la "versione più recente dei dati di fatto" del set di dati non elaborato. Se è false e SFDC.deployCDC è true, i DAG vengono generati con l'elaborazione Change Data Capture (CDC) in base a SystemModstamp. Consulta i dettagli sull'elaborazione CDC per Salesforce.
SFDC.createPlaceholders Creare segnaposto true Crea tabelle segnaposto vuote nel caso in cui non vengano generate dal processo di importazione per consentire l'esecuzione senza errori del deployment dei report a valle.
SFDC.datasets.raw Set di dati di destinazione non elaborati - Utilizzato dal processo CDC, è qui che lo strumento di replica inserisce i dati di Salesforce. Se utilizzi dati di test, crea un set di dati vuoto.
SFDC.datasets.cdc Set di dati elaborato con CDC - Set di dati che funge da origine per le visualizzazioni dei report e da destinazione per i DAG elaborati dei record. Se utilizzi dati di test, crea un set di dati vuoto.
SFDC.datasets.reporting Set di dati di report SFDC "REPORTING_SFDC" Nome del set di dati accessibile agli utenti finali per i report, dove vengono implementate le viste e le tabelle rivolte agli utenti.
SFDC.currencies Filtrare le valute [ "USD" ] Se non utilizzi dati di test, inserisci una singola valuta (ad es. [ "USD" ]) o più valute (ad es. [ "USD", "CAD" ]) pertinenti per la tua attività. Questi valori vengono utilizzati per sostituire i segnaposto in SQL nei modelli di analisi, se disponibili.

Modello dati

Questa sezione descrive il modello di dati di Salesforce (SFDC) utilizzando il diagramma di relazione tra entità (ERD).

Diagramma delle relazioni tra entità per SFDC

Figura 2. Salesforce (SFDC): diagramma delle relazioni tra entità.

Visualizzazioni di base

Questi sono gli oggetti blu nell'ERD e sono viste sulle tabelle CDC senza trasformazioni diverse da alcuni alias dei nomi delle colonne. Visualizza gli script in src/SFDC/src/reporting/ddls.

Viste report

Si tratta degli oggetti verdi nell'ERD e contengono gli attributi dimensionali pertinenti utilizzati dalle tabelle dei report. Visualizza gli script in src/SFDC/src/reporting/ddls.

Requisiti dei dati di Salesforce

Questa sezione illustra le specifiche relative alla struttura dei dati di Salesforce per l'utilizzo con Cortex Framework.

  • Struttura della tabella:
    • Nomi: i nomi delle tabelle utilizzano snake_case (parole minuscole separate da trattini bassi) e sono al plurale. Ad esempio: some_objects.
    • Tipi di dati:le colonne mantengono gli stessi tipi di dati rappresentati in Salesforce.
    • Legibilità:alcuni nomi di campo potrebbero essere leggermente modificati per una maggiore chiarezza nel livello di generazione di report.
  • Ttabelle vuote e deployment: le tabelle richieste mancanti nel set di dati non elaborato vengono create automaticamente come tabelle vuote durante il processo di deployment. In questo modo viene garantita un'esecuzione senza problemi del passaggio di deployment del CDC.
  • Requisiti CDC: i campi Id e SystemModstamp sono fondamentali per consentire agli script CDC di monitorare le modifiche ai dati. Possono avere questi nomi esatti o altri. Gli script di elaborazione dei dati non elaborati forniti recuperano automaticamente questi campi dalle API e aggiornano la tabella di replica di destinazione.
    • Id: funge da identificatore univoco per ogni record.
    • SystemModstamp: questo campo memorizza un timestamp che indica l'ultima volta che un record è stato modificato.
  • Script di elaborazione dei dati non elaborati:gli script di elaborazione dei dati non elaborati forniti non richiedono un'ulteriore elaborazione (CDC). Questo comportamento viene impostato per impostazione predefinita durante il deployment.

Tabelle di origine per la conversione di valute

Salesforce ti consente di gestire le valute in due modi:

  • Base:è l'impostazione predefinita, in cui tutti i dati utilizzano una singola valuta.
  • Avanzata: consente la conversione tra più valute in base ai tassi di cambio (è necessario attivare la Gestione avanzata delle valute).

Se utilizzi la gestione avanzata delle valute, Salesforce utilizza due tabelle speciali:

  • CurrencyTypes: questa tabella memorizza le informazioni sulle diverse valute che utilizzi (ad esempio USD, EUR e così via).
  • TassoDiConversioneDatato: questa tabella contiene i tassi di cambio tra le valute nel tempo.

Cortex Framework si aspetta che queste tabelle siano presenti se utilizzi la gestione avanzata delle valute. Se non utilizzi la gestione avanzata delle valute, puoi rimuovere le voci relative a queste tabelle da un file di configurazione (src/SFDC/config/ingestion_settings.yaml). Questo passaggio impedisce tentativi non necessari di estrarre dati da tabelle inesistenti.

Caricamento dei dati di SFDC in BigQuery

Cortex Framework fornisce una soluzione di replica basata su script Python pianificati in Apache Airflow e API Salesforce Bulk 2.0. Questi script Python possono essere adattati e pianificati nello strumento che preferisci. Per ulteriori informazioni, consulta il modulo di estrazione SFDC.

Cortex Framework offre anche tre diversi metodi per integrare i dati, a seconda della loro provenienza e della modalità di gestione:

  1. Chiamate API: questa opzione è per i dati a cui è possibile accedere direttamente tramite un'API. Cortex Framework può chiamare l'API, acquisire i dati e memorizzarli in un set di dati "Raw" in BigQuery. Se nel set di dati sono presenti record esistenti, Cortex Framework può aggiornarli con i nuovi dati.
  2. Visualizzazioni di mappatura della struttura:questo metodo è utile se hai già caricato i dati in BigQuery tramite un altro strumento, ma la struttura dei dati non corrisponde alle esigenze di Cortex Framework. Cortex Framework utilizza le "visualizzazioni" (come le tabelle virtuali) per tradurre la struttura di dati esistente nel formato previsto dalle funzionalità di generazione di report di Cortex Framework.

  3. Script di elaborazione CDC (Change Data Capture):questa opzione è progettata appositamente per i dati in continua evoluzione. Gli script CDC monitorano queste modifiche e aggiornano di conseguenza i dati in BigQuery. Questi script si basano su due campi speciali nei dati:

    • Id: identificatore univoco di ogni record.
    • SystemModstamp: un timestamp che indica quando è stato modificato un record.

    Se i tuoi dati non hanno questi nomi esatti, gli script possono essere modificati per riconoscerli con nomi diversi. Durante questa procedura puoi anche aggiungere campi personalizzati allo schema di dati. Ad esempio, la tabella di origine con i dati dell'oggetto Account deve avere i campi Id e SystemModstamp originali. Se questi campi hanno nomi diversi, il file src/SFDC/src/table_schema/accounts.csv deve essere aggiornato con il nome del campo Id mappato a AccountId e a qualsiasi campo del timestamp della modifica del sistema mappato a SystemModstamp. Per ulteriori informazioni, consulta la documentazione di SystemModStamp.

Se hai già caricato i dati tramite un altro strumento (e vengono aggiornati costantemente), Cortex può comunque utilizzarli. Gli script CDC sono dotati di file di mappatura che possono tradurre la struttura di dati esistente nel formato necessario per Cortex Framework. Durante questa procedura puoi anche aggiungere campi personalizzati ai dati.

Configura l'integrazione dell'API e il CDC

Per importare i dati di Salesforce in BigQuery, puoi utilizzare i seguenti metodi:

  1. Script di Cortex per le chiamate API: fornisce script di replica per Salesforce o uno strumento di replica dei dati di tua scelta.L'aspetto fondamentale è che i dati importati devono essere uguali a quelli provenienti dalle API Salesforce.
  2. Strumento di replica e accodamento sempre : se utilizzi uno strumento per la replica, questo metodo è adatto a uno strumento che può aggiungere nuovi record di dati (_appendalways_pattern) o aggiornare i record esistenti.
  3. Strumento di replica e aggiunta di nuovi record: se lo strumento non aggiorna i record e riproduce le modifiche come nuovi record in una tabella di destinazione (non elaborata), Cortex Data Foundation offre la possibilità di creare script di elaborazione CDC. Per ulteriori informazioni, consulta la procedura CDC.

Workload Salesforce: opzioni di integrazione dei dati

Figura 1. Workload Salesforce: opzioni di integrazione dei dati.

Per assicurarti che i dati corrispondano a quanto previsto da Cortex Framework, puoi modificare la configurazione della mappatura per mappare lo strumento di replica o gli schemi esistenti. In questo modo vengono generate visualizzazioni di mappatura compatibili con la struttura prevista da Cortex Framework Data Foundation.

Utilizza il file ingestion_settings.yaml per configurare la generazione di script per chiamare le API Salesforce e replicare i dati nel set di dati non elaborato (sezione salesforce_to_raw_tables) e la generazione di script per elaborare le modifiche in arrivo nel set di dati non elaborato e nel set di dati elaborato tramite CDC (sezione raw_to_cdc_tables).

Per impostazione predefinita, gli script forniti per la lettura dalle API aggiornano le modifiche nel set di dati non elaborato, pertanto gli script di elaborazione CDC non sono richiesti e vengono create viste di mappatura per allineare lo schema di origine a quello previsto.

La generazione degli script di elaborazione della CDC non viene eseguita se SFDC.createMappingViews=true è presente in config.json (comportamento predefinito). Se sono necessari script CDC, imposta SFDC.createMappingViews=false. Questo secondo passaggio consente inoltre di eseguire la mappatura tra gli schemi di origine e gli schemi richiesti come richiesto da Cortex Framework Data Foundation.

Il seguente esempio di file di configurazione setting.yaml illustra la generazione di visualizzazioni di mappatura quando uno strumento di replica aggiorna i dati direttamente nel set di dati replicato, come illustrato in option 3 (ovvero non è richiesta alcuna CDC, solo la rimappatura di tabelle e nomi di campi). Poiché non è richiesto alcun CDC, questa opzione viene eseguita a condizione che il parametro SFDC.createMappingViews nel file config.json rimanga 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"

In questo esempio, la rimozione della configurazione di una tabella di base o di tutte le tabelle di base dalle sezioni salta la generazione dei DAG di quella tabella di base o dell'intera sezione, come illustrato per salesforce_to_raw_tables. Per questo scenario, l'impostazione del parametro deployCDC : False ha lo stesso effetto, poiché non è necessario generare script di elaborazione CDC.

Mappatura dei dati

Devi mappare i campi di dati in entrata al formato previsto da Cortex Data Foundation. Ad esempio, un campo denominato unicornId del sistema di dati di origine deve essere rinominato e riconosciuto come AccountId (con un tipo di dati stringa) in Cortex Data Foundation:

  • Campo origine: unicornId (nome utilizzato nel sistema di origine)
  • Campo Cortex: AccountId (nome previsto da Cortex)
  • Tipo di dati: String (tipo di dati previsto da Cortex)

Mappatura dei campi polimorfici

Cortex Framework Data Foundation supporta la mappatura dei campi polimorfi, ovvero campi il cui nome può variare, ma la cui struttura rimane coerente. I nomi di tipo di campo polimorfico (ad es. Who.Type) possono essere replicati aggiungendo un elemento [Field Name]_Type nei rispettivi file CSV di mappatura: src/SFDC/src/table_schema/tasks.csv. Ad esempio, se devi replicare il campo Who.Type dell'oggetto Task, aggiungi la riga Who_Type,Who_Type,STRING. Viene definito un nuovo campo denominato Who.Type che si mappa a se stesso (mantiene lo stesso nome) e ha un tipo di dati stringa.

Modificare i modelli DAG

Potresti dover modificare i modelli DAG per la copia dei dati dal continuo o per l'elaborazione dei dati non elaborati in base alle esigenze della tua istanza di Airflow o Cloud Composer. Per ulteriori informazioni, consulta Raccogliere le impostazioni di Cloud Composer.

Se non hai bisogno di CDC o di generazione di dati non elaborati dalle chiamate API, imposta deployCDC=false. In alternativa, puoi rimuovere i contenuti delle sezioni in ingestion_settings.yaml. Se è noto che le strutture di dati sono coerenti con quelle previste da Cortex Framework Data Foundation, puoi saltare la generazione delle visualizzazioni di mappatura impostando SFDC.createMappingViews=false.

Configurazione del modulo di estrazione

Questa sezione illustra i passaggi per utilizzare il modulo di estrazione da Salesforce a BigQuery fornito da Data Foundation. I requisiti e il flusso possono variare a seconda del sistema e della configurazione esistenti. In alternativa, puoi utilizzare altri strumenti disponibili.

Configura le credenziali e l'app collegata

Accedi come amministratore all'istanza Salesforce per completare quanto segue:

  1. Crea o identifica un profilo in Salesforce che soddisfi i seguenti requisiti:
    1. Permission for Apex REST Services and API Enabled sia concessa in Autorizzazioni di sistema.
    2. L'autorizzazione View All viene concessa per tutti gli oggetti che vuoi replicare. Ad esempio, Account e Cases. Controlla se ci sono limitazioni o problemi con l'amministratore della sicurezza.
    3. Nessuna autorizzazione concessa per le operazioni relative all'accesso all'interfaccia utente, come Salesforce Anywhere in Lightning Experience, Salesforce Anywhere su dispositivo mobile, Utente Lightning Experience e Utente accesso Lightning. Controlla se ci sono limitazioni o problemi con l'amministratore di sicurezza.
  2. Crea o utilizza un utente esistente identificato in Salesforce. Devi conoscere il nome utente, la password e il token di sicurezza dell'utente. Considera quanto segue:
    • Idealmente, dovrebbe essere un utente dedicato all'esecuzione di questa replica.
    • L'utente deve essere assegnato al profilo che hai creato o identificato nel passaggio 1.
    • Qui puoi vedere Nome utente e reimpostare la Password.
    • Puoi reimpostare il token di sicurezza se non lo hai e non è utilizzato da un'altra procedura.
  3. Crea un'app connessa. È l'unico canale di comunicazione per stabilire la connessione a Salesforce dall'esterno con l'aiuto del profilo, dell'API Salesforce, delle credenziali utente standard e del relativo token di sicurezza.
    1. Segui le istruzioni per abilitare le impostazioni OAuth per l'integrazione dell'API.
    2. Assicurati che Require Secret for Web Server Flow e Require Secretfor Refresh Token Flow siano abilitati nella sezione API (Impostazioni OAuth abilitate).
    3. Consulta la documentazione su come ottenere la chiave consumer (che verrà utilizzata in seguito come ID client). Rivolgiti al tuo amministratore della sicurezza per eventuali problemi o limitazioni.
  4. Assegna l'app connessa al profilo creato.
    1. Seleziona Configurazione in alto a destra nella schermata Home di Salesforce.
    2. Nella casella Ricerca rapida, inserisci profile e poi seleziona Profilo. Cerca il profilo creato nel passaggio 1.
    3. Apri il profilo.
    4. Fai clic sul link App collegate assegnate.
    5. Fai clic su Modifica.
    6. Aggiungi l'app collegata appena creata.
    7. Fai clic sul pulsante Salva.

Configura Secret Manager

Configura Secret Manager per archiviare i dettagli di connessione. Il modulo Salesforce-to-BigQuery si basa su Secret Manager per memorizzare in modo sicuro le credenziali necessarie per connettersi a Salesforce e BigQuery. Questo approccio evita di esporre informazioni sensibili come le password direttamente nel codice o nei file di configurazione, migliorando la sicurezza.

Crea un secret con le seguenti specifiche. Per istruzioni più dettagliate, consulta Creare un segreto.

  • Nome segreto: airflow-connections-salesforce-conn

  • Valore secret:

    http://USERNAME:PASSWORD@https%3A%2F%2FINSTANCE_NAME.lightning.force.com?client_id=CLIENT_ID&security_token=SECRET_TOKEN`

    Sostituisci quanto segue:

    • USERNAME con il tuo nome utente.
    • PASSWORD con la tua password.
    • INSTANCE_NAME con il nome dell'istanza.
    • CLIENT_ID con il tuo ID client.
    • SECRET_TOKEN con il tuo token segreto.

Per ulteriori informazioni, vedi come trovare il nome dell'istanza.

Librerie Cloud Composer per la replica

Per eseguire gli script Python nei DAG forniti da Cortex Framework Data Foundation, devi installare alcune dipendenze. Per la versione 1.10 di Airflow, segui la documentazione relativa all'installazione delle dipendenze Python per Cloud Composer 1 per installare i seguenti pacchetti in ordine:

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

Per la versione 2.x di Airflow, consulta la documentazione Installare le dipendenze Python per la documentazione di Cloud Composer 2 per installare apache-airflow-providers-salesforce~=5.2.0.

Utilizza il seguente comando per installare ogni pacchetto richiesto:

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

Sostituisci quanto segue:

  • ENVIRONMENT_NAME con il nome dell'ambiente assegnato.
  • LOCATION con la località.
  • PACKAGE_NAME con il nome del pacchetto scelto.
  • EXTRAS_AND_VERSION con le specifiche degli extra e della versione.

Il seguente comando è un esempio di installazione di un pacchetto obbligatorio:

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

Attiva Secret Manager come backend

Attiva Google Secret Manager come backend di sicurezza. Questo passaggio ti chiede di attivare Secret Manager come posizione di archiviazione principale per informazioni sensibili come password e chiavi API utilizzate dal tuo ambiente Cloud Composer. In questo modo, la sicurezza viene migliorata centralizzando e gestendo le credenziali in un servizio dedicato. Per maggiori informazioni, consulta Secret Manager.

Consenti all'account di servizio Composer di accedere ai secret

Questo passaggio garantisce che l'account di servizio associato a Cloud Composer abbia le autorizzazioni necessarie per accedere ai secret archiviati in Secret Manager. Per impostazione predefinita, Cloud Composer utilizza l'account di servizio Compute Engine. L'autorizzazione richiesta è Secret Manager Secret Accessor. Questa autorizzazione consente all'account di servizio di recuperare e utilizzare i secret archiviati in Secret Manager.Per una guida completa sulla configurazione dei controlli di accesso in Secret Manager, consulta la documentazione sul controllo dell'accesso.

Connessione BigQuery in Airflow

Assicurati di creare la connessione sfdc_cdc_bq in base alle indicazioni riportate in Raccogliere le impostazioni di Cloud Composer. È probabile che questa connessione venga utilizzata dal modulo Salesforce-to-BigQuery per stabilire la comunicazione con BigQuery.

Passaggi successivi