Salesforce-Integration (SFDC)

Auf dieser Seite werden die Schritte zur Einbindung der Salesforce-Arbeitslast (SFDC) in die Cortex Framework Data Foundation beschrieben. Cortex Framework integriert Daten aus Salesforce über Dataflow-Pipelines in BigQuery. Cloud Composer plant und überwacht diese Dataflow-Pipelines, um Erkenntnisse aus Ihren Daten zu gewinnen.

Konfigurationsdatei

In der Datei config.json im Cortex Framework Data Foundation-Repository werden die Einstellungen konfiguriert, die für die Übertragung von Daten aus einer beliebigen Datenquelle erforderlich sind, einschließlich Salesforce. Diese Datei enthält die folgenden Parameter für laufende Salesforce-Arbeitslasten:

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

In der folgenden Tabelle wird der Wert für jeden SFDC-Betriebsparameter beschrieben:

Parameter Bedeutung Standardwert Beschreibung
SFDC.deployCDC CDC bereitstellen true Generieren Sie CDC-Verarbeitungsscripts, die als DAGs in Cloud Composer ausgeführt werden. In der Dokumentation finden Sie Informationen zu den verschiedenen Datenaufnahmeoptionen für Salesforce Sales Cloud.
SFDC.createMappingViews Zuordnungsansichten erstellen true Die bereitgestellten DAGs zum Abrufen neuer Einträge aus den Salesforce APIs aktualisieren Einträge beim Landen. Wenn dieser Wert auf „wahr“ gesetzt ist, werden im CDC-ge verarbeiteten Datenpool Ansichten generiert, um Tabellen mit der „aktuellen Version der Wahrheit“ aus dem Rohdatenpool zu präsentieren. Wenn „false“ und SFDC.deployCDC = true ist, werden DAGs mit CDC-Verarbeitung (Change Data Capture) basierend auf dem SystemModstamp generiert. Weitere Informationen zur CDC-Verarbeitung für Salesforce
SFDC.createPlaceholders Platzhalter erstellen true Erstellen Sie leere Platzhaltertabellen für den Fall, dass sie nicht durch den Datenaufnahmeprozess generiert werden, damit die Bereitstellung der nachgelagerten Berichte ohne Fehler ausgeführt werden kann.
SFDC.datasets.raw Rohdaten-Dataset für Landingpage - Wird vom CDC-Prozess verwendet. Hier landen die Daten aus Salesforce im Replikationstool. Wenn Sie Testdaten verwenden, erstellen Sie ein leeres Dataset.
SFDC.datasets.cdc Mit CDC verarbeiteter Datensatz - Dataset, das als Quelle für die Berichtsansichten und als Ziel für die DAGs für die verarbeiteten Einträge dient. Wenn Sie Testdaten verwenden, erstellen Sie ein leeres Dataset.
SFDC.datasets.reporting Berichtsdatensatz in Salesforce "REPORTING_SFDC" Name des Datensatzes, auf den Endnutzer für die Berichterstellung zugreifen können, in dem Ansichten und für Nutzer sichtbare Tabellen bereitgestellt werden.
SFDC.currencies Währungen filtern [ "USD" ] Wenn Sie keine Testdaten verwenden, geben Sie eine einzelne Währung (z. B. [ "USD" ]) oder mehrere Währungen (z. B. [ "USD", "CAD" ]) ein, die für Ihr Unternehmen relevant sind. Diese Werte werden verwendet, um Platzhalter in SQL in Analysemodellen zu ersetzen, sofern verfügbar.

Datenmodell

In diesem Abschnitt wird das Salesforce-Datenmodell (SFDC) anhand eines Entitätsbeziehungsdiagramms (ERD) beschrieben.

Entitäts-Beziehungs-Diagramm für SFDC

Abbildung 2 Salesforce (SFDC): Entitäts-Beziehungs-Diagramm.

Basisansichten

Dies sind die blauen Objekte in der ERD. Sie sind Ansichten auf CDC-Tabellen ohne andere Transformationen als einige Aliasse für Spaltennamen. Scripts in src/SFDC/src/reporting/ddls ansehen

Berichtsdatenansichten

Das sind die grünen Objekte in der ERD. Sie enthalten die relevanten Dimensionsattribute, die in den Berichtstabellen verwendet werden. Scripts in src/SFDC/src/reporting/ddls ansehen

Anforderungen an Salesforce-Daten

In diesem Abschnitt wird beschrieben, wie Ihre Salesforce-Daten für die Verwendung mit dem Cortex-Framework strukturiert sein müssen.

  • Tabellenstruktur:
    • Benennung:Tabellennamen werden mit snake_case (Wörter in Kleinbuchstaben, getrennt durch Unterstriche) erstellt und stehen im Plural. Beispiel: some_objects
    • Datentypen:Spalten haben dieselben Datentypen wie in Salesforce.
    • Lesbarkeit:Einige Feldnamen werden möglicherweise leicht angepasst, um die Übersichtlichkeit in der Berichtsebene zu verbessern.
  • Leere Tabellen und Bereitstellung: Alle erforderlichen Tabellen, die im Rohdatensatz fehlen, werden während der Bereitstellung automatisch als leere Tabellen erstellt. So wird eine reibungslose Ausführung des CDC-Bereitstellungsschritts gewährleistet.
  • CDC-Anforderungen:Die Felder Id und SystemModstamp sind für CDC-Scripts entscheidend, um Änderungen an Ihren Daten zu verfolgen. Sie können genau diese Namen oder andere haben. Die bereitgestellten Scripts für die Rohdatenverarbeitung rufen diese Felder automatisch aus den APIs ab und aktualisieren die Zielreplikationstabelle.
    • Id: Diese dient als eindeutige Kennung für jeden Datensatz.
    • SystemModstamp: In diesem Feld wird ein Zeitstempel gespeichert, der angibt, wann ein Eintrag zuletzt geändert wurde.
  • Scripts für die Rohdatenverarbeitung:Für die bereitgestellten Scripts für die Rohdatenverarbeitung ist keine zusätzliche Verarbeitung (CDC) erforderlich. Dieses Verhalten wird standardmäßig bei der Bereitstellung festgelegt.

Quelltabellen für die Währungsumrechnung

In Salesforce haben Sie zwei Möglichkeiten, Währungen zu verwalten:

  • Einfach:Dies ist die Standardeinstellung, bei der für alle Daten eine einzige Währung verwendet wird.
  • Erweitert: Hier werden mehrere Währungen basierend auf Wechselkursen umgerechnet. Dazu muss die erweiterte Währungsverwaltung aktiviert sein.

Wenn Sie die erweiterte Währungsverwaltung verwenden, werden in Salesforce zwei spezielle Tabellen verwendet:

  • CurrencyTypes: In dieser Tabelle werden Informationen zu den verschiedenen Währungen gespeichert, die Sie verwenden (z. B. USD, EUR usw.).
  • DatedConversionRates: In dieser Tabelle finden Sie die Wechselkurse zwischen Währungen im Zeitverlauf.

Cortex Framework erwartet, dass diese Tabellen vorhanden sind, wenn Sie die erweiterte Währungsverwaltung verwenden. Wenn Sie die erweiterte Währungsverwaltung nicht verwenden, können Sie Einträge, die sich auf diese Tabellen beziehen, aus einer Konfigurationsdatei (src/SFDC/config/ingestion_settings.yaml) entfernen. Dadurch werden unnötige Versuche verhindert, Daten aus nicht vorhandenen Tabellen zu extrahieren.

SFDC-Daten in BigQuery laden

Das Cortex-Framework bietet eine Replikationslösung, die auf Python-Scripts basiert, die in Apache Airflow und der Salesforce Bulk API 2.0 geplant werden. Diese Python-Scripts können in Ihrem bevorzugten Tool angepasst und geplant werden. Weitere Informationen finden Sie im Hilfeartikel SFDC-Extraktionsmodul.

Cortex Framework bietet außerdem drei verschiedene Methoden zur Datenintegration, je nachdem, woher Ihre Daten stammen und wie sie verwaltet werden:

  1. API-Aufrufe:Diese Option gilt für Daten, auf die direkt über eine API zugegriffen werden kann. Cortex Framework kann die API aufrufen, die Daten abrufen und in einem „Raw“-Dataset in BigQuery speichern. Wenn im Datensatz bereits Einträge vorhanden sind, kann Cortex Framework sie mit den neuen Daten aktualisieren.
  2. Strukturzuordnungsansichten:Diese Methode ist nützlich, wenn Sie Ihre Daten bereits über ein anderes Tool in BigQuery geladen haben, die Datenstruktur aber nicht den Anforderungen des Cortex-Frameworks entspricht. Das Cortex Framework verwendet „Ansichten“ (z. B. virtuelle Tabellen), um die vorhandene Datenstruktur in das Format umzuwandeln, das von den Berichtsfunktionen des Cortex Frameworks erwartet wird.
  3. CDC-Verarbeitungsscripts (Change Data Capture):Diese Option ist speziell für Daten konzipiert, die sich ständig ändern. CDC-Scripts erfassen diese Änderungen und aktualisieren die Daten in BigQuery entsprechend. Diese Scripts basieren auf zwei speziellen Feldern in Ihren Daten:

    • Id: eindeutige Kennung für jeden Datensatz.
    • SystemModstamp: Ein Zeitstempel, der angibt, wann ein Datensatz geändert wurde.

    Wenn Ihre Daten nicht genau diese Namen haben, können die Scripts so angepasst werden, dass sie mit anderen Namen erkannt werden. Außerdem können Sie Ihrem Datenschema während dieses Vorgangs benutzerdefinierte Felder hinzufügen. Die Quelltabelle mit den Daten des Kontoobjekts sollte beispielsweise die ursprünglichen Felder Id und SystemModstamp enthalten. Wenn diese Felder unterschiedliche Namen haben, muss die Datei src/SFDC/src/table_schema/accounts.csv so aktualisiert werden, dass der Name des Felds Id mit AccountId und das Feld für den Zeitstempel der Systemänderung mit SystemModstamp übereinstimmt. Weitere Informationen finden Sie in der Dokumentation zu SystemModStamp.

Wenn Sie Daten bereits über ein anderes Tool geladen haben und diese ständig aktualisiert werden, können sie in Cortex verwendet werden. Die CDC-Scripts enthalten Zuordnungsdateien, mit denen Ihre vorhandene Datenstruktur in das Format umgewandelt werden kann, das für das Cortex-Framework erforderlich ist. Sie können Ihren Daten dabei sogar benutzerdefinierte Felder hinzufügen.

API-Integration und CDC konfigurieren

Sie haben folgende Möglichkeiten, Ihre Salesforce-Daten in BigQuery zu importieren:

  1. Cortex-Scripts für API-Aufrufe: Hier finden Sie Replikationsscripts für Salesforce oder ein Tool zur Datenreplizierung Ihrer Wahl.Wichtig ist, dass die importierten Daten so aussehen, als würden sie von den Salesforce APIs stammen.
  2. Replikationstool und „append always“ : Wenn Sie ein Tool für die Replikation verwenden, ist diese Methode für ein Tool geeignet, mit dem entweder neue Datensätze hinzugefügt (_appendalways_pattern) oder vorhandene Datensätze aktualisiert werden können.
  3. Replikationstool und neue Einträge hinzufügen: Wenn das Tool die Einträge nicht aktualisiert und alle Änderungen als neue Einträge in eine Zieltabelle (Raw) repliziert, bietet Cortex Data Foundation die Möglichkeit, CDC-Verarbeitungsscripts zu erstellen. Weitere Informationen finden Sie unter CDC-Prozess.

Salesforce-Arbeitslast: Optionen für die Datenintegration

Abbildung 1. Salesforce-Arbeitslast: Optionen für die Datenintegration

Damit Ihre Daten den Anforderungen des Cortex-Frameworks entsprechen, können Sie die Zuordnungskonfiguration so anpassen, dass Ihr Replikationstool oder vorhandene Schemata zugeordnet werden. Dadurch werden Zuordnungsansichten generiert, die mit der von Cortex Framework Data Foundation erwarteten Struktur kompatibel sind.

Mit der Datei ingestion_settings.yaml können Sie die Generierung von Scripts konfigurieren, um die Salesforce APIs aufzurufen und die Daten in den Rohdatensatz zu replizieren (Abschnitt salesforce_to_raw_tables) sowie die Generierung von Scripts, um Änderungen zu verarbeiten, die in den Rohdatensatz und in den mit CDC verarbeiteten Datensatz eingehen (Abschnitt raw_to_cdc_tables).

Standardmäßig aktualisieren die Scripts, die zum Lesen aus APIs bereitgestellt werden, Änderungen im Rohdatensatz. Daher sind keine Verarbeitungsscripts für die kontinuierliche Datenübertragung erforderlich. Stattdessen werden Zuordnungsansichten erstellt, um das Quellschema an das erwartete Schema anzupassen.

Die Generierung von CDC-Verarbeitungsscripts wird nicht ausgeführt, wenn SFDC.createMappingViews=true in der config.json festgelegt ist (Standardverhalten). Wenn CDC-Scripts erforderlich sind, legen Sie SFDC.createMappingViews=false fest. Dieser zweite Schritt ermöglicht auch die Zuordnung der Quellschemata zu den erforderlichen Schemata, wie von der Cortex Framework Data Foundation gefordert.

Das folgende Beispiel einer setting.yaml-Konfigurationsdatei veranschaulicht die Generierung von Zuordnungsansichten, wenn ein Replikationstool die Daten wie in option 3 dargestellt direkt in den replizierten Datensatz aktualisiert. Es ist also keine CDC erforderlich, sondern nur eine Neuzuordnung von Tabellen- und Feldnamen. Da keine CDC erforderlich ist, wird diese Option ausgeführt, solange der Parameter SFDC.createMappingViews in der Datei „config.json“ true bleibt.

  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 diesem Beispiel wird die Generierung von DAGs für eine Basistabelle oder alle Basistabellen in den Abschnitten übersprungen, wenn die Konfiguration für eine oder alle Basistabellen aus den Abschnitten entfernt wird, wie für salesforce_to_raw_tables dargestellt. In diesem Szenario hat die Einstellung des Parameters deployCDC : False denselben Effekt, da keine CDC-Verarbeitungsscripts generiert werden müssen.

Datenabgleich

Sie müssen eingehende Datenfelder dem von Cortex Data Foundation erwarteten Format zuordnen. Beispiel: Ein Feld mit dem Namen unicornId aus Ihrem Quelldatensystem sollte in Cortex Data Foundation in AccountId (mit dem Datentyp „String“) umbenannt und als solches erkannt werden:

  • Quellfeld: unicornId (Name, der im Quellsystem verwendet wird)
  • Cortex-Feld: AccountId (von Cortex erwarteter Name)
  • Datentyp: String (von Cortex erwarteter Datentyp)

Polymorphe Felder zuordnen

Die Cortex Framework Data Foundation unterstützt die Zuordnung polymorpher Felder, deren Name variieren kann, deren Struktur jedoch gleich bleibt. Polymorphe Feldtypnamen (z. B. Who.Type) können repliziert werden, indem Sie in den entsprechenden CSV-Dateien für die Zuordnung ein [Field Name]_Type-Element hinzufügen: src/SFDC/src/table_schema/tasks.csv. Wenn Sie beispielsweise das Feld Who.Type des Task-Objekts replizieren möchten, fügen Sie die Zeile Who_Type,Who_Type,STRING hinzu. Dadurch wird ein neues Feld namens Who.Type definiert, das sich selbst zuordnet (behält denselben Namen bei) und den Datentyp „String“ hat.

DAG-Vorlagen ändern

Möglicherweise müssen Sie die DAG-Vorlagen für die kontinuierliche Datenübernahme oder für die Verarbeitung von Rohdaten entsprechend Ihrer Airflow- oder Cloud Composer-Instanz anpassen. Weitere Informationen finden Sie unter Cloud Composer-Einstellungen abrufen.

Wenn Sie keine CDC-Daten oder Rohdaten aus API-Aufrufen benötigen, legen Sie deployCDC=false fest. Alternativ können Sie den Inhalt der Abschnitte in ingestion_settings.yaml entfernen. Wenn die Datenstrukturen mit denen der Cortex Framework Data Foundation übereinstimmen, können Sie die Generierung von Zuordnungsansichten über die Einstellung SFDC.createMappingViews=false überspringen.

Extraktionsmodul konfigurieren

In diesem Abschnitt wird beschrieben, wie Sie das von Data Foundation bereitgestellte Salesforce-zu-BigQuery-Extraktionsmodul verwenden. Ihre Anforderungen und Abläufe können je nach System und vorhandener Konfiguration variieren. Alternativ können Sie auch andere Tools verwenden.

Anmeldedaten und verbundene App einrichten

Melden Sie sich als Administrator in Ihrer Salesforce-Instanz an, um Folgendes zu tun:

  1. Erstellen oder identifizieren Sie ein Profil in Salesforce, das den folgenden Anforderungen entspricht:
    1. Permission for Apex REST Services and API Enabled wird unter Systemberechtigungen gewährt.
    2. Die Berechtigung View All wird für alle Objekte gewährt, die Sie replizieren möchten. Beispiel: „Konto“ und „Fälle“. Erkundige dich bei deinem Sicherheitsadministrator, ob es Einschränkungen oder Probleme gibt.
    3. Es wurden keine Berechtigungen für die Anmeldung in der Benutzeroberfläche erteilt, z. B. für Salesforce Anywhere in Lightning Experience, Salesforce Anywhere auf Mobilgeräten, Lightning Experience-Nutzer und Lightning-Anmeldenutzer. Erkundige dich bei deinem Sicherheitsadministrator, ob es Einschränkungen oder Probleme gibt.
  2. Erstellen Sie einen neuen Nutzer oder verwenden Sie einen vorhandenen Nutzer in Salesforce. Sie benötigen den Nutzernamen, das Passwort und das Sicherheitstoken des Nutzers. Beachten Sie dabei Folgendes:
    • Idealerweise sollte es sich dabei um einen Nutzer handeln, der ausschließlich für die Ausführung dieser Replikation zuständig ist.
    • Der Nutzer sollte dem Profil zugewiesen sein, das Sie in Schritt 1 erstellt oder angegeben haben.
    • Hier sehen Sie den Nutzernamen und können das Passwort zurücksetzen.
    • Sie können das Sicherheitstoken zurücksetzen, wenn Sie es nicht haben und es von keinem anderen Prozess verwendet wird.
  3. Erstellen Sie eine verbundene App. Dies ist der einzige Kommunikationskanal, über den eine Verbindung von extern zu Salesforce hergestellt werden kann. Dazu werden das Profil, die Salesforce API, die Standardnutzeranmeldedaten und das Sicherheitstoken verwendet.
    1. Folgen Sie der Anleitung, um die OAuth-Einstellungen für die API-Integration zu aktivieren.
    2. Prüfen Sie, ob Require Secret for Web Server Flow und Require Secretfor Refresh Token Flow im Abschnitt API (Aktivierte OAuth-Einstellungen) aktiviert sind.
    3. In dieser Dokumentation erfährst du, wie du deinen Nutzerschlüssel abrufen kannst, der später als Client-ID verwendet wird. Wenden Sie sich an Ihren Sicherheitsadministrator, um Probleme oder Einschränkungen zu prüfen.
  4. Weisen Sie dem erstellten Profil Ihre verbundene App zu.
    1. Wählen Sie rechts oben auf dem Salesforce-Startbildschirm Einrichtung aus.
    2. Geben Sie im Feld Schnellsuche profile ein und wählen Sie dann Profil aus. Suchen Sie nach dem Profil, das Sie in Schritt 1 erstellt haben.
    3. Rufen Sie das Profil auf.
    4. Klicken Sie auf den Link Zugewiesene verbundene Apps.
    5. Klicken Sie auf Bearbeiten.
    6. Fügen Sie die neu erstellte verbundene App hinzu.
    7. Klicken Sie auf Speichern.

Secret Manager einrichten

Konfigurieren Sie Secret Manager zum Speichern von Verbindungsdetails. Das Salesforce-zu-BigQuery-Modul verwendet Secret Manager, um die Anmeldedaten für die Verbindung zu Salesforce und BigQuery sicher zu speichern. So werden vertrauliche Informationen wie Passwörter nicht direkt in Ihrem Code oder Ihren Konfigurationsdateien preisgegeben, was die Sicherheit erhöht.

Erstellen Sie ein Secret mit den folgenden Spezifikationen. Eine ausführliche Anleitung finden Sie unter Secret erstellen.

  • Geheimname: airflow-connections-salesforce-conn
  • Secret-Wert:

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

    Ersetzen Sie Folgendes:

    • USERNAME durch Ihren Nutzernamen.
    • PASSWORD mit Ihrem Passwort.
    • INSTANCE_NAME durch den Namen der Instanz.
    • CLIENT_ID durch Ihre Kundennummer.
    • SECRET_TOKEN durch dein geheimes Token.

Weitere Informationen finden Sie unter Instanznamen ermitteln.

Cloud Composer-Bibliotheken für die Replikation

Um die Python-Scripts in den DAGs auszuführen, die von der Cortex Framework Data Foundation bereitgestellt werden, müssen Sie einige Abhängigkeiten installieren. Für Airflow-Version 1.10 folgen Sie der Anleitung zum Installieren von Python-Abhängigkeiten für Cloud Composer 1, um die folgenden Pakete in der richtigen Reihenfolge zu installieren:

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

Informationen zur Installation von apache-airflow-providers-salesforce~=5.2.0 für Airflow-Version 2.x finden Sie in der Dokumentation Python-Abhängigkeiten für Cloud Composer 2 installieren.

Mit dem folgenden Befehl können Sie alle erforderlichen Pakete installieren:

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

Ersetzen Sie Folgendes:

  • ENVIRONMENT_NAME durch den zugewiesenen Umgebungsnamen.
  • LOCATION durch den Standort.
  • PACKAGE_NAME durch den ausgewählten Paketnamen.
  • EXTRAS_AND_VERSION mit den Spezifikationen der Extras und der Version.

Der folgende Befehl ist ein Beispiel für die Installation eines erforderlichen Pakets:

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

Secret Manager als Back-End aktivieren

Aktivieren Sie Google Secret Manager als Sicherheits-Back-End. In diesem Schritt aktivieren Sie Secret Manager als primären Speicherort für vertrauliche Informationen wie Passwörter und API-Schlüssel, die in Ihrer Cloud Composer-Umgebung verwendet werden. Dies verbessert die Sicherheit, da Anmeldedaten in einem speziellen Dienst zentralisiert und verwaltet werden. Weitere Informationen finden Sie unter Secret Manager.

Composer-Dienstkonto Zugriff auf Secrets gewähren

Dadurch erhält das mit Cloud Composer verknüpfte Dienstkonto die erforderlichen Berechtigungen für den Zugriff auf in Secret Manager gespeicherte Secrets. Standardmäßig verwendet Cloud Composer das Compute Engine-Dienstkonto. Die erforderliche Berechtigung ist Secret Manager Secret Accessor. Mit dieser Berechtigung kann das Dienstkonto in Secret Manager gespeicherte Secrets abrufen und verwenden.Eine umfassende Anleitung zum Konfigurieren der Zugriffssteuerung in Secret Manager finden Sie in der Dokumentation zur Zugriffssteuerung.

BigQuery-Verbindung in Airflow

Erstellen Sie die Verbindung sfdc_cdc_bq gemäß der Anleitung unter Cloud Composer-Einstellungen abrufen. Diese Verbindung wird wahrscheinlich vom Salesforce-zu-BigQuery-Modul verwendet, um die Kommunikation mit BigQuery herzustellen.

Nächste Schritte