Salesforce-Trigger

Mit dem Salesforce-Trigger können Sie Ereignisse der Typen Change Data Capture (CDC) oder Enterprise Messaging Platform überwachen. Mit diesem Trigger können Sie Ihre Integration basierend auf einem beliebigen CDC-Ereignis (Erstellen, Aktualisieren, Löschen, Wiederherstellen) oder den Plattformereignissen in Ihrer Salesforce-Instanz starten.

Hinweis

In diesem Abschnitt werden die Schritte beschrieben, die zum Verbinden und Konfigurieren einer Salesforce-Instanz erforderlich sind, um Ereignisse des Typs Change Data Capture (CDC) oder Plattform zu verwenden, um Änderungen in Form von Pub/Sub an Apigee Integration zu streamen. Die folgenden Schritte müssen ausgeführt werden, bevor Salesforce-Aufgaben oder -Trigger in Apigee konfiguriert werden:

Integrationsnutzer einrichten

So richten Sie einen Integrationsnutzer ein:

  1. Melden Sie sich mit Ihren sysadmin-Anmeldedaten bei der Salesforce-Instanz an.
  2. Klicken Sie auf das Zahnradsymbol und wählen Sie dann Einrichtung aus, wie in der folgenden Abbildung dargestellt: EinrichtungsseiteEinrichtungsseite
  3. Klicken Sie im Administrationsmenü auf Nutzer > Nutzer.
  4. Klicken Sie im Bereich Nutzer auf die Schaltfläche Neuer Nutzer.
  5. Geben Sie im Dialogfeld Nutzerbearbeitung die folgenden Informationen ein:
    1. Vorname: Vorname des Integrationsnutzers.
    2. Nachname: Nachname des Integrationsnutzers.
    3. E-Mail-Adresse: E-Mail-Adresse für den Integrationsnutzer. Idealerweise sollte es sich um eine Gruppen-E-Mail-Adresse handeln.
    4. Nutzername: Nutzername, der den Namenskonventionen auf Organisationsebene entspricht.

      Wenn Sie einen neuen Integrationsnutzer erstellen, verwenden Sie das folgende Format: EMAIL.SALESFORCE_ORG_NAME.SANDBOX_NAME

      Wenn Sie bereits einen Integrationsnutzer haben, prüfen Sie, ob dessen Nutzername hier eingegeben ist.

    5. Rolle: Wählen Sie im Drop-down-Menü die gewünschte Option aus.
    6. Nutzerlizenz: Geben Sie Salesforce oder bei Verwendung einer Testorganisation Salesforce Platform ein.
    7. Profil: Wählen Sie im Drop-down-Menü das Berechtigungsprofil für Integrationsnutzer aus.

      Wir empfehlen, ein Profil ohne Berechtigungen zuzuweisen, um den Salesforce-Zugriff von Integrations-Nutzern vor unbefugter Nutzung zu schützen.

    8. Klicken Sie auf Speichern.
  6. So aktualisieren Sie das Passwort des neuen Integrationsnutzers:
    1. Klicken Sie im Bereich Nutzer auf Passwörter zurücksetzen. Anschließend wird eine E-Mail zum Zurücksetzen des Passworts an die dem Nutzer zugeordnete E-Mail-Adresse gesendet.
    2. Folgen Sie den Schritten zum Zurücksetzen des Passworts des E-Mail-Kontos. Notieren Sie sich das neue Passwort, da Sie es später noch benötigen.

Berechtigungssatz konfigurieren

Wenn Sie bereits Zugriff auf einen Satz von Berechtigungen haben, die für einen Integrationsnutzer geeignet sind, können Sie diesen Schritt überspringen und mit dem Abschnitt Sicherheitstoken einrichten fortfahren. Andernfalls gehen Sie vor, wie im Folgenden gezeigt, um einen Berechtigungssatz für den Integrationsnutzer und das Salesforce-Objekt zu konfigurieren.

So konfigurieren Sie einen Berechtigungssatz für den Integrationsnutzer:

  1. Klicken Sie im Menü Einrichtung auf Nutzer > Berechtigungssätze.
  2. Klicken Sie im Bereich Berechtigungssätze auf die Schaltfläche Neu.
  3. Geben Sie im Dialogfeld Berechtigungssätze die folgenden Informationen ein:
    • Label: Geben Sie einen Namen für den Berechtigungssatz ein.
    • Lizenz: Wählen Sie aus dem Drop-down-Menü Lizenz die Option Salesforce aus.
    • Klicken Sie auf Speichern.
  4. Scrollen Sie in der Liste der Einstellungsoptionen für System nach unten und wählen Sie Systemberechtigungen aus.
  5. Klicken Sie auf der Seite Systemberechtigungen auf die Schaltfläche Bearbeiten.
  6. Scrollen Sie in der Liste der verfügbaren Berechtigungen nach unten und klicken Sie auf das Kästchen API aktiviert.

    Die Berechtigung Nur API-Nutzer ist ebenfalls erforderlich, kann aber erst aktiviert werden, wenn das erforderliche Sicherheitstoken zurückgesetzt wurde. Diese Berechtigung wird in einem späteren Schritt hinzugefügt.

  7. (Optional): Scrollen Sie und wählen Sie gegebenenfalls Alle Daten ändern und Alle Daten anzeigen aus. Diese Berechtigungen sind nicht erforderlich, können aber hilfreich sein, wenn Sie dem Integrationsnutzer automatisch Zugriff auf neue Objekte gewähren möchten. Wir empfehlen, diese Berechtigungen nur zum Testen in einer Sandbox zu aktivieren.
  8. Scrollen Sie zum Anfang der Berechtigungsliste und klicken Sie auf Speichern.
  9. Prüfen Sie Ihre Einstellungen und klicken Sie auf Speichern.

So konfigurieren Sie den Berechtigungssatz für das Salesforce-Objekt:

  1. Klicken Sie auf Übersicht über Berechtigungen, um zur Hauptkonfigurationsseite für Berechtigungssatz zurückzukehren.
  2. Wählen Sie im Bereich Berechtigungssatz im Abschnitt Anwendungen die Option Objekteinstellungen aus.
  3. Scrollen Sie nach unten und wählen Sie die Salesforce-Objekte aus, für die ein Berechtigungssatz benötigt wird. In diesem Beispiel wird das Opportunity-Objekt verwendet.
  4. Klicken Sie auf der Detailseite des Objekts auf Bearbeiten.
  5. Klicken Sie auf die Kästchen der jeweiligen Eintragstypen, die für Sie erforderlich sind. Wenn Sie nicht wissen, welche Eintragstypen benötigt werden, wählen Sie alle aus.
  6. Klicken Sie auf die Kästchen für die gewünschten Objektberechtigungen, um sie zu aktivieren. Die Optionen Lesen und Alle ansehen werden empfohlen.
  7. Gewähren Sie jedem Objektfeld Lesezugriff oder Bearbeitungszugriff durch Klicken auf das entsprechende Kästchen.
  8. Scrollen Sie auf der Seite nach oben und klicken Sie auf Save.

Sicherheitstoken einrichten

Wenn Sie bereits zuvor ein Sicherheitstoken für den Integrationsnutzer erstellt und das Passwort zurückgesetzt haben, wird automatisch eine E-Mail mit einem neuen Sicherheitstoken gesendet. Sie können dieses neue Token verwenden und mit dem Schritt Verbundene App erstellen fortfahren.

Andernfalls führen Sie die folgenden Schritte aus, um das Sicherheitstoken für den Integrationsnutzer zurückzusetzen:

  1. Melden Sie sich bei Salesforce als Integrationsnutzer mit dem Nutzernamen und dem Passwort an, den bzw. das Sie in einem vorherigen Schritt eingerichtet haben.
  2. Klicken Sie im Hauptmenü auf das Profilbild und dann auf Einstellungen.
  3. Wählen Sie im Menü Einstellungen die Option Mein Sicherheitstoken zurücksetzen aus, um den Bereich Sicherheitstoken zurücksetzen zu öffnen.
  4. Klicken Sie auf Sicherheitstoken zurücksetzen.
  5. Suchen Sie im E-Mail-Konto des Integrationsnutzers nach einer E-Mail, die das neue Sicherheitstoken enthält. Notieren Sie sich das neue Sicherheitstoken. Sie benötigen es für einen späteren Schritt.
  6. (Optional) Aktivieren Sie unter Systemberechtigungen die Berechtigung Nur API-Nutzer für Ihren Berechtigungssatz aus, wie oben im Abschnitt Berechtigungssatz konfigurieren erläutert.

Verbundene App erstellen

Zur Einrichtung einer verbundenen App ist die Berechtigung für die Systemadministration erforderlich. Wenn Sie derzeit als Integrationsnutzer angemeldet sind, melden Sie sich ab und dann wieder als sysadmin an.

So richten Sie eine verbundene App ein:

  1. Klicken Sie auf das Zahnradsymbol und wählen Sie dann Einrichtung aus.
  2. Suchen Sie im Menü Einrichtung nach App Manager und wählen Sie die Option aus, wie in der folgenden Abbildung dargestellt: EinrichtungsseiteEinrichtungsseite
  3. Klicken Sie auf Neue verbundene App.
  4. Geben Sie im Konfigurationsbereich die folgenden Informationen ein:
    • Name der verbundenen App: Geben Sie einen Namen für Ihre verbundene App ein.
    • API-Name: Geben Sie den Namen der API ein.
    • Kontakt-E-Mail-Adresse: Geben Sie eine E-Mail-Adresse für Ihre verbundene App ein, idealerweise einen Gruppen-E-Mail-Alias.
    • API (OAuth-Einstellungen aktivieren): Wählen Sie OAuth-Einstellungen aktivieren aus. Legen Sie anschließend Folgendes fest:
      1. (Optional) Callback-URL: Diese ist nur erforderlich, wenn ein externer Dienst die Validierung vornehmen soll. Wenn Sie einen Callback bereitstellen möchten, müssen Sie das Präfix http(s):// hinzufügen.
      2. Ausgewählte OAuth-Bereiche: Wählen Sie Folgendes aus:
        • Daten aufrufen und verwalten (api)
        • Anfragen jederzeit in Ihrem Namen ausführen (refresh_token, offline_access)
  5. Klicken Sie auf Speichern.
  6. Klicken Sie auf Weiter. Sie müssen sich mit einem Bestätigungscode, der an Ihre E-Mail-Adresse gesendet wurde, noch einmal autorisieren.
  7. Nach erfolgreicher Überprüfung des Codes werden auf der nächsten Seite ein Consumer-Secret und ein Consumer-Key angezeigt. Notieren Sie sich diese Werte. Sie werden bei der Einrichtung des Auth-Moduls für Apigee verwendet.
  8. Klicken Sie auf die Schaltfläche Verwalten.
  9. Klicken Sie auf der Seite Verbundene App-Detail auf die Schaltfläche Richtlinien bearbeiten.
  10. Ändern Sie im Abschnitt OAuth-Richtlinien den Wert im Drop-down-Menü Berechtigte Nutzer in Vom Administrator genehmigte Nutzer sind vorautorisiert.
  11. Klicken Sie auf Speichern.
  12. Scrollen Sie zu den Abschnitten Profile und Berechtigungssätze auf der Seite, um das Profil oder den Berechtigungssatz auszuwählen, das bzw. den Sie auf die verbundene App anwenden möchten.
  13. Wählen Sie das gewünschte Profil oder den gewünschten Berechtigungssatz aus.
  14. Klicken Sie auf Speichern.

Voraussetzungen für die Verwendung von CDC-Ereignissen

Bevor Sie Ihren Apigee-Trigger für die Verwendung von CDC-Ereignissen konfigurieren, müssen Sie CDC in Salesforce ein konfiguriertes Objekt hinzufügen:

  1. Melden Sie sich bei Salesforce als sysadmin an.
  2. Klicken Sie auf das Zahnradsymbol und dann auf Einrichtung.
  3. Suchen Sie im linken Navigationsbereich nach der Option Change Data Capture und wählen Sie diese aus.
  4. Ermitteln Sie auf der Einrichtungsseite für Change Data Capture in der Spalte Verfügbare Entitäten das Salesforce-Objekt, das Sie verwenden möchten, und ziehen Sie es in die Spalte Ausgewählte Entitäten.
  5. Klicken Sie auf Speichern.

Voraussetzungen für die Verwendung von Platformereignissen

Führen Sie die folgenden Schritte in Salesforce aus, bevor Sie den Apigee-Trigger für die Verwendung von Plattformereignissen konfigurieren:

  • Plattformereignis erstellen
  • Berechtigungen für Plattformereignis aktualisieren

Plattformereignis erstellen

So erstellen Sie ein Plattformereignis:

  1. Melden Sie sich mit Ihren sysadmin-Anmeldedaten bei der Salesforce-Instanz an.
  2. Klicken Sie auf das Zahnradsymbol und wählen Sie dann Einrichtung aus.
  3. Suchen Sie im Navigationsbereich nach Plattform und klicken Sie dann auf Plattformereignisse.
  4. Abbildung mit einem neuen PlattformereignisAbbildung mit einem neuen Plattformereignis
  5. Klicken Sie auf der Seite Plattformereignisse auf Neues Plattformereignis und legen Sie die folgenden Attribute fest:
  • Label
  • Plural Label
  • Objektname (Dieses Feld wird automatisch ausgefüllt)
  • Veröffentlichungsverhalten Wählen Sie einen der folgenden Werte aus:
    • Veröffentlichen nach dem Commit: Beendet das Streaming von Ereignissen, wenn eine Bedingung nicht erfüllt ist.
    • Sofort veröffentlichen: Das Ereignis wird sofort ausgelöst, ohne auf Validierung zu warten.
    Weitere Informationen zum Veröffentlichungsverhalten finden Sie unter Plattformereignisse und Transaktionen.
  • Bereitstellungsstatus (optional): Wählen Sie Bereitgestellt aus, wenn das Ereignis für die Bereitstellung bereit ist.
  • Klicken Sie auf Speichern.
  • Abbildung mit Einstellungen für Labels und Veröffentlichungsverhalten für ein PlattformereignisAbbildung mit Einstellungen für Labels und Veröffentlichungsverhalten für ein Plattformereignis
  • Benutzerdefinierte Felder erstellen. Klicken Sie auf Neu erstellen im Abschnitt Benutzerdefinierte Felder und Beziehungen und wählen Sie den Typ des benutzerdefinierten Felds aus. Sie können beliebig viele benutzerdefinierte Felder erstellen.
  • Nachdem Sie die benutzerdefinierten Felder erstellt haben, beachten Sie auf der Seite Plattformereignisse den Wert des Feldes API-Name. Der Objektname endet auf _e, d. h. das Objekt ist ein Plattformereignisobjekt. Bei einem CDC-Objekt endet der Objektname auf _c.

    Abbildung mit Details zu einem gespeicherten PlattformereignisAbbildung mit Details zu einem gespeicherten Plattformereignis

    Berechtigungen für Plattformereignis aktualisieren

    Die Berechtigungen müssen aktualisiert werden, damit der Integrationsnutzer auf das neu erstellte Plattformereignis zugreifen kann.

    Zum Aktualisieren der Berechtigungen führen Sie die folgenden Schritte aus:

    1. Klicken Sie im Menü Einrichtung auf Nutzer > Berechtigungssätze.
    2. Klicken Sie auf der Seite Berechtigungssätze auf die zuvor erstellte Berechtigung.
    3. Klicken Sie auf Objekteinstellungen > Plural Label of the Platform Event.
    4. Aktivieren Sie im Abschnitt Objektberechtigungen die Berechtigungen Lesen und Erstellen.
    5. Klicken Sie auf Speichern.
    6. Abbildung mit Berechtigungen eines PlattformereignissesAbbildung mit Berechtigungen eines Plattformereignisses

    Salesforce-Trigger hinzufügen

    So fügen Sie einer neuen oder vorhandenen Integration einen Salesforce-Trigger hinzu:
    1. Wählen Sie in der Apigee-Benutzeroberfläche Ihre Apigee-Organisation aus.
    2. Klicken Sie auf Entwickeln > Integrationen.
    3. Wählen Sie eine vorhandene Integration aus oder erstellen Sie eine neue Integration, indem Sie auf Integration erstellen klicken.

      Wenn Sie eine neue Integration erstellen, gehen Sie so vor:

      1. Geben Sie im Dialogfeld Integration erstellen einen Namen und eine Beschreibung ein.
      2. Wählen Sie eine Region für die Integration aus der Liste der unterstützten Regionen aus.
      3. Klicken Sie auf Erstellen.

      Dadurch wird die Integration auf der Seite Integrationsdesigner geöffnet.

    4. Klicken Sie in der Navigationsleiste Integrationsdesigner auf + Aufgabe/Trigger hinzufügen > Aufgaben, um die Liste der verfügbaren Aufgaben aufzurufen.
    5. Wählen Sie eine vorhandene Integration aus oder klicken Sie auf Integration erstellen.
    6. Klicken Sie im Integrationseditor auf + Aufgabe/Trigger hinzufügen > Trigger, um die verfügbaren Trigger aufzurufen.
    7. Klicken Sie auf das Element Salesforce-Trigger und platzieren Sie es im Designer.

    Salesforce-Trigger konfigurieren

    Führen Sie folgende Schritte aus, um den Salesforce-Trigger zu konfigurieren:

    1. Klicken Sie im Integrationseditor auf Salesforce-Trigger, um den Bereich für die Trigger-Konfiguration aufzurufen.
    2. Wählen Sie im Drop-down-Menü Salesforce-Instanzkonfiguration eine Salesforce-Instanz aus.

      Wenn Sie keine Salesforce-Instanz haben, erstellen Sie eine neue Instanz. Weitere Informationen finden Sie unter Neue Salesforce-Instanz erstellen.

    3. Wählen Sie im Drop-down Salesforce-Kanalkonfiguration einen Salesforce-Kanal aus.

      Wenn Sie noch keinen Salesforce-Kanal haben, erstellen Sie einen neuen Kanal. Weitere Informationen finden Sie unter Neuen Salesforce-Kanal erstellen.

    4. Wenn Sie als Ereignistyp CDC ausgewählt haben, wählen Sie nun einen der folgenden Vorgänge aus:
      • Create
      • Update
      • Delete
      • Undelete

      Der Trigger wird nur ausgeführt, wenn der spezifische Vorgang oder die Lücke auftritt.

      Der Salesforce-Trigger kann nur für einen Vorgang konfiguriert werden. Wenn Sie den Trigger für mehrere Vorgänge ausführen möchten, erstellen Sie für jeden Vorgang einen Salesforce-Trigger.

    Neue Salesforce-Instanz erstellen

    Führen Sie die folgenden Schritte aus, um eine neue Salesforce-Instanz zu konfigurieren:

    1. Klicken Sie in den bearbeitbaren Attributen des Triggers auf Salesforce-Instanzkonfiguration auswählen > + Neue Salesforce-Instanzkonfiguration hinzufügen.
    2. Legen Sie im Dialogfeld Salesforce-Instanz hinzufügen die folgenden Attribute fest:
      • Verbindungsname der Salesforce-Instanz: Geben Sie einen Namen für die Instanz ein.

        Nach dem Konfigurieren verwenden Sie diesen Namen, um auf die Salesforce-Instanz zu verweisen.

      • Salesforce-Domain: Geben Sie einen Dienstanbieter für die Instanz ein. Sie finden die Domain in Ihrem Salesforce-Konto. Beispiel: instance.my.salesforce.com. Die folgende Abbildung zeigt die Salesforce-Domain:

        Salesforce-Domain in einer Salesforce-Instanz abrufen Salesforce-Domain in einer Salesforce-Instanz abrufen

      • Authentifizierungsprofil: Wählen Sie ein Authentifizierungsprofil aus.

        Wenn Sie kein Authentifizierungsprofil haben, erstellen Sie ein neues Profil für den Authentifizierungstyp Anmeldedaten des OAuth 2.0-Ressourceninhabers. Die folgende Abbildung zeigt die Felder, die zum Erstellen eines Authentifizierungsprofils erforderlich sind:

        Passwort des OAuth 2.0-Ressourceninhabers Passwort des OAuth 2.0-Ressourceninhabers

        Informationen zu den Feldern finden Sie unter Anmeldedaten des OAuth 2.0-Ressourceninhabers. Geben Sie für die Salesforce-Instanz die folgenden Werte ein:
  • Salesforce-Organisations-ID: Geben Sie die Organisations-ID der Salesforce-Instanz ein. Sie erhalten die ID von Ihrem Salesforce-Administrator.
  • Klicken Sie auf Add.
  • Neuen Salesforce-Kanal erstellen

    Führen Sie die folgenden Schritte aus, um einen neuen Salesforce-Kanal zu konfigurieren:

    1. Klicken Sie in den bearbeitbaren Attributen des Triggers auf Salesforce-Kanalkonfiguration auswählen > + Neue Salesforce-Kanalkonfiguration hinzufügen.
    2. Geben Sie im Dialogfeld Salesforce-Kanalkonfiguration hinzufügen den Objektnamen für das Attribut Salesforce-Objektname ein.

      Wenn Sie den Objektnamen nicht kennen, wenden Sie sich an Ihren Salesforce-Administrator.

    3. Klicken Sie auf Add.

    Ausgabevariablen

    Die Antwort vom Salesforce Trigger steht in den Ausgabevariablen zur Verfügung.

    Die Ausgabevariablen für ein CDC-Ereignis werden in folgender Tabelle beschrieben:

    Variable Datentyp Beschreibung
    SalesforceTriggerCdcPayload JSON Informationen zum Änderungsereignis.
    SalesforceTriggerEvent JSON Enthält den replayId des Ereignisses.
    SalesforceTriggerSchema String Triggerschema.
    SalesforceTriggerCdcSnapshot JSON Snapshot des Objekts nach dem Änderungsereignis. Dieses Feld ist nur für die Vorgänge Update und Create verfügbar.
    SalesforceTriggerCdcRecordId String Enthält den recordId des aktualisierten oder hinzugefügten Eintrags. Der recordId ist eine Kennung des geänderten Salesforce-Objekts.

    Die Ausgabevariablen für Platform-Ereignisse werden in folgender Tabelle beschrieben:

    Variable Datentyp Beschreibung
    SalesforceTriggerPEPayload JSON Informationen zum Änderungsereignis.
    SalesforceTriggerEvent JSON Enthält den replayId des Ereignisses.
    SalesforceTriggerSchema String Triggerschema.
    Der Ausgabeparameter für diesen Trigger ist die JSON-Variable CdcTriggerPayload. Die JSON-Variable enthält aktualisierte Datensatzobjekte.

    Best Practices

    Die Verwendung des Salesforce-Triggers wird empfohlen, wenn Sie Salesforce-Benachrichtigungen verwenden möchten, um Integrationen auszulösen, ohne benutzerdefinierten Code zum Veröffentlichen von Salesforce-Ereignissen zu schreiben. Jede kleine Feldänderung in Ihrem Salesforce-Fall löst ein Salesforce CDC-Ereignis und somit eine Integration aus, was zu einer erheblichen Beeinträchtigung der Integration führen kann. Sie können Änderungsereignis-Filter verwenden, um nur die erforderlichen CDC-Ereignisse zu filtern, die die Integration auslösen. Die Verwendung von Änderungsereignis-Filtern kann die Beeinträchtigung von Integrationen reduzieren und die Einhaltung von Lizenzeinschränkungen gewährleisten.

    Genauso empfehlen wir, die Veröffentlichung aller Integrationen aufzuheben, die diesen Trigger verwenden, wenn die jeweilige Integration nicht mehr benötigt wird. Die Integration überwacht weiterhin auf Salesforce CDC- und Plattformereignisse, bis ihre Veröffentlichung aufgehoben oder gelöscht wird.

    Hinweise

    Bevor Sie den Salesforce-Trigger zum Ausführen Ihrer Integration verwenden, sollten Sie Folgendes berücksichtigen:

    • Salesforce sendet in der Regel maximal 100.000 CDC- und Plattformereignisse pro Tag. Wenden Sie sich an Ihren Salesforce-Administrator, um Ihre Lizenzeinschränkungen zu verstehen, bevor Sie CDC-Ereignisse für den Integrationstrigger auswählen.
    • Wenn Sie Bulk-Uploads nach Salesforce planen, sollten Sie CDC pausieren und, um eine Beeinträchtigung der Integration zu reduzieren und die Lizenzbeschränkungen einzuhalten.
    • Die maximale Ereignisnachrichtengröße, die von Salesforce veröffentlicht werden kann, beträgt 1 MB. Weitere Informationen finden Sie unter Change Data Capture-Zuweisungen.
    • Apigee unterstützt keine Salesforce CDC-Ereignisse für die folgenden Minicluster-Regionen:
      • asia-northeast1
      • asia-south1
      • australia-southeast1
      • europe-west2
      • europe-west3
      • europe-west6
      • northamerica-northeast1
      • southamerica-east1
      • us-east4
      • us-west2