Trigger di Salesforce

Il trigger di Salesforce ti consente di ascoltare gli eventi Change Data Capture (CDC) o della piattaforma di messaggistica aziendale. Con questo trigger, puoi avviare l'integrazione in base a qualsiasi evento CDC (creazione, aggiornamento, eliminazione o annullamento eliminazione) o agli eventi della piattaforma nell'istanza Salesforce.

Prima di iniziare

Questa sezione descrive i passaggi necessari per connettere e configurare un'istanza Salesforce per utilizzare gli eventi Change Data Capture (CDC) o la piattaforma per trasmettere le modifiche all'Apigee Integration in modo Pub/Sub. I passaggi seguenti devono essere completati prima di configurare qualsiasi attività o trigger relativi a Salesforce in Apigee:

Configura un utente di integrazione

Configura un utente di integrazione seguendo questi passaggi:

  1. Accedi all'istanza Salesforce con le tue credenziali sysadmin.
  2. Fai clic sull'icona a forma di ingranaggio e seleziona Configurazione, come mostrato nell'immagine di seguito: immagine che mostra la pagina di configurazioneimmagine che mostra la pagina di configurazione
  3. Fai clic su Utenti > Utenti nel menu Amministrazione.
  4. Nel riquadro Utenti, seleziona il pulsante Nuovo utente.
  5. Nella finestra di dialogo User Edit (Modifica utente), inserisci i seguenti dettagli:
    1. Nome: nome dell'utente dell'integrazione.
    2. Cognome: cognome dell'utente dell'integrazione.
    3. Indirizzo email: indirizzo email dell'utente di integrazione. Idealmente, dovrebbe essere un'email di gruppo.
    4. Nome utente: nome utente conforme a qualsiasi convenzione di denominazione a livello di organizzazione.

      Se stai creando un nuovo utente di integrazione, utilizza il formato seguente: EMAIL.SALESFORCE_ORG_NAME.SANDBOX_NAME

      Se esiste già un utente di integrazione, verifica che il nome utente sia stato inserito qui.

    5. Ruolo: seleziona un'opzione dal menu a discesa.
    6. User License (Licenza utente): inserisci Salesforce oppure, se utilizzi un'organizzazione di prova, inserisci Salesforce Platform.
    7. Profilo: seleziona dal menu a discesa il profilo delle autorizzazioni per gli utenti con integrazione.

      Ti consigliamo di assegnare un profilo senza autorizzazioni per proteggere l'accesso a Salesforce dell'utente di integrazione da utilizzi non autorizzati.

    8. Fai clic su Salva.
  6. Per aggiornare la password per il nuovo utente di integrazione, segui questi passaggi:
    1. Fai clic sul pulsante Reimposta password nel riquadro Utenti. Un'email di reimpostazione della password viene inviata all'indirizzo email associato all'utente.
    2. Segui il flusso di reimpostazione della password dall'account email. Prendi nota della nuova password, che ti servirà in un passaggio successivo.

Configura un set di autorizzazioni

Se hai già accesso a un set di autorizzazioni appropriato per un utente di integrazione, puoi saltare questo passaggio e passare a Configurare un token di sicurezza. In caso contrario, segui questi passaggi per configurare un set di autorizzazioni per l'utente di integrazione e l'oggetto Salesforce.

Per configurare un set di autorizzazioni per l'utente di integrazione:

  1. Nel menu Configurazione, fai clic su Utenti > Set di autorizzazioni.
  2. Nel riquadro Set di autorizzazioni, fai clic sul pulsante Nuovo.
  3. Nella finestra di dialogo Set di autorizzazioni, inserisci i seguenti dettagli:
    • Etichetta: inserisci un nome per l'insieme di autorizzazioni.
    • Licenza: seleziona Salesforce dal menu a discesa Licenza.
    • Fai clic su Salva.
  4. Nell'elenco delle opzioni di Sistema, scorri verso il basso e seleziona Autorizzazioni di sistema.
  5. Nella pagina Autorizzazioni di sistema, fai clic sul pulsante Modifica.
  6. Scorri verso il basso l'elenco delle autorizzazioni disponibili e seleziona la casella di controllo Abilitata API.

    È richiesta anche l'autorizzazione Utente solo API, ma non può essere abilitata fino a quando il token di sicurezza richiesto non viene reimpostato. Questa autorizzazione verrà aggiunta in un passaggio successivo.

  7. (Facoltativo) Scorri e seleziona Modifica tutti i dati e Visualizza tutti i dati, se applicabile. Queste autorizzazioni non sono necessarie, ma possono essere utili se vuoi concedere automaticamente all'utente dell'integrazione l'accesso ai nuovi oggetti. Ti consigliamo di abilitare queste autorizzazioni solo per i test in una sandbox.
  8. Scorri fino all'inizio dell'elenco delle autorizzazioni e fai clic su Salva.
  9. Conferma le impostazioni e fai clic su Salva.

Per configurare l'insieme di autorizzazioni per l'oggetto Salesforce:

  1. Fai clic su Panoramica del set di autorizzazioni per tornare alla pagina di configurazione principale di Set di autorizzazioni.
  2. Seleziona Impostazioni degli oggetti dalla sezione App del riquadro Set di autorizzazioni.
  3. Scorri verso il basso e seleziona gli oggetti Salesforce che richiedono un set di autorizzazioni. In questo esempio viene utilizzato l'oggetto Opportunity.
  4. Fai clic sul pulsante Modifica nella pagina dei dettagli dell'oggetto.
  5. Seleziona le caselle di controllo relative ai tipi di record. Se sai quali tipi di record sono richiesti, selezionali. Se non sai quali tipi di record sono richiesti, selezionali tutti.
  6. Seleziona le caselle di controllo relative alle Autorizzazioni degli oggetti da attivare. È consigliabile utilizzare le opzioni Leggi e Visualizza tutto.
  7. Concedi l'accesso in lettura o l'accesso in modifica per ciascun campo dell'oggetto selezionando la casella di controllo corrispondente.
  8. Scorri fino alla parte superiore della pagina e fai clic su Salva.

Configura un token di sicurezza

Se hai creato in precedenza un token di sicurezza per l'utente di integrazione e reimposti la password, viene inviata automaticamente un'email con un nuovo token di sicurezza. Puoi utilizzare il nuovo token e andare alla sezione Creare un'app connessa.

In caso contrario, segui questi passaggi per reimpostare il token di sicurezza per l'utente di integrazione:

  1. Accedi a Salesforce come utente di integrazione, utilizzando il nome utente e la password impostati nel passaggio precedente.
  2. Nel menu principale, fai clic sull'immagine del profilo, quindi su Impostazioni.
  3. Dal menu Impostazioni, seleziona Reimposta il mio token di sicurezza per aprire il riquadro Reimposta token di sicurezza.
  4. Fai clic sul pulsante Reimposta token di sicurezza.
  5. Verifica se nell'account email associato all'utente di integrazione è presente un'email contenente il nuovo token di sicurezza. Prendi nota del nuovo token di sicurezza, che ti servirà in un passaggio successivo.
  6. (Facoltativo) Abilita l'autorizzazione Solo utente API in Autorizzazioni di sistema per il tuo set di autorizzazioni, come descritto nella sezione Configurare un set di autorizzazioni qui sopra.

Crea un'app collegata

Per configurare un'app connessa è necessaria l'autorizzazione dell'amministratore di sistema. Se hai eseguito l'accesso come utenti dell'integrazione, assicurati di uscire e di accedere di nuovo come sysadmin.

Per configurare un'app collegata:

  1. Fai clic sull'icona a forma di ingranaggio e seleziona Configurazione.
  2. Nel menu Setup, cerca e seleziona App Manager (Gestione app), come mostrato nell'immagine seguente: immagine che mostra la pagina di configurazioneimmagine che mostra la pagina di configurazione
  3. Fai clic su Nuova app collegata.
  4. Nel riquadro di configurazione, fornisci i seguenti dettagli:
    • Nome app collegata: inserisci un nome per l'app collegata.
    • Nome API: inserisci il nome dell'API.
    • Email di contatto: inserisci un indirizzo email per la tua app collegata, idealmente un alias email di gruppo.
    • API (Abilita impostazioni OAuth): seleziona Abilita impostazioni OAuth. Quindi, imposta quanto segue:
      1. (Facoltativo) URL di callback: questo campo è obbligatorio solo se vuoi che un servizio esterno esegua la convalida. Se scegli di fornire un callback, assicurati di includere il prefisso http(s)://.
      2. Ambiti OAuth selezionati: seleziona:
        • Accedere e gestire i dati (API)
        • Eseguire richieste per tuo conto in qualsiasi momento (refresh_token, offline_access)
  5. Fai clic su Salva.
  6. Fai clic su Continua. Devi eseguire nuovamente l'autorizzazione con un codice di verifica inviato al tuo indirizzo email.
  7. Dopo aver verificato il codice, nella pagina successiva vengono visualizzati un segreto utente e una chiave utente. Prendi nota di questi valori, che verranno utilizzati durante la configurazione del modulo di autenticazione per Apigee.
  8. Fai clic sul pulsante Gestisci.
  9. Nella pagina Dettagli dell'app collegata, fai clic sul pulsante Modifica criteri.
  10. Nella sezione Criteri OAuth, modifica il valore del menu a discesa Utenti consentiti in Gli utenti approvati dall'amministratore sono pre-autorizzati.
  11. Fai clic su Salva.
  12. Scorri fino alla sezione Profili e Set di autorizzazioni della pagina per selezionare il profilo o il set di autorizzazioni da applicare all'app collegata.
  13. Seleziona il profilo o il set di autorizzazioni desiderato.
  14. Fai clic su Salva.

Passaggi preliminari per l'utilizzo degli eventi CDC

Prima di configurare il trigger di Apigee per utilizzare gli eventi CDC, assicurati di aggiungere un oggetto configurato a CDC in Salesforce:

  1. Accedi a Salesforce come sysadmin.
  2. Fai clic sull'icona a forma di ingranaggio, quindi su Configurazione.
  3. Nel menu di navigazione a sinistra, cerca e seleziona Modifica acquisizione dati.
  4. Nella pagina di configurazione Modifica acquisizione dati, individua l'oggetto Salesforce che vuoi utilizzare nella colonna Entità disponibili e trascinalo nella colonna Entità selezionate.
  5. Fai clic su Salva.

Passaggi preliminari per l'utilizzo degli eventi della piattaforma

Prima di configurare il trigger di Apigee per utilizzare gli eventi della piattaforma, completa i seguenti passaggi in Salesforce:

  • Crea un evento piattaforma
  • Aggiorna le autorizzazioni per l'evento della piattaforma

Crea un evento Platform

Per creare un evento della piattaforma, segui questi passaggi:

  1. Accedi all'istanza Salesforce con le tue credenziali sysadmin.
  2. Fai clic sull'icona a forma di ingranaggio e seleziona Configurazione.
  3. Nel riquadro di navigazione, cerca Piattaforma e fai clic su Eventi piattaforma.
    4. immagine che mostra un nuovo evento sulla piattaformaimmagine che mostra un nuovo evento sulla piattaforma
  4. Nella pagina Eventi piattaforma, fai clic su Nuovo evento piattaforma e imposta le seguenti proprietà:
  • Etichetta
  • Etichetta plurale
  • Nome oggetto(questo campo viene compilato automaticamente)
  • Comportamento di pubblicazione Seleziona uno dei seguenti valori:
    • Pubblica dopo il commit: ripristina il flusso di eventi se una condizione non è soddisfatta.
    • Pubblica immediatamente: attiva immediatamente l'evento, senza attendere la convalida.
    Per saperne di più sul comportamento di pubblicazione, consulta Eventi e transazioni della piattaforma.
  • (Facoltativo) Stato deployment: seleziona Deployment eseguito se l'evento è pronto per il deployment.
  • Fai clic su Salva.
    • immagine che mostra l'impostazione delle etichette e il comportamento di pubblicazione per un evento della piattaformaimmagine che mostra l'impostazione delle etichette e il comportamento di pubblicazione per un evento della piattaforma
  • Creare campi personalizzati. Per creare campi personalizzati, fai clic su Nuovo nella sezione Campi e relazioni personalizzati e seleziona il tipo di campo personalizzato. Puoi creare un numero illimitato di campi personalizzati.

    • Dopo aver creato i campi personalizzati, nella pagina Eventi piattaforma, nota il valore del campo Nome API. Il nome dell'oggetto termina con _e, a indicare che l'oggetto è un oggetto evento di piattaforma. Per un oggetto CDC, il nome dell'oggetto termina con _c.

    immagine che mostra i dettagli di un evento della piattaforma salvatoimmagine che mostra i dettagli di un evento della piattaforma salvato

    Aggiorna le autorizzazioni per l'evento della piattaforma

    È necessario aggiornare le autorizzazioni impostate per consentire all'utente di integrazione di accedere all'evento della piattaforma appena creato.

    Per aggiornare le autorizzazioni, segui questi passaggi:

    1. Nel menu Configurazione, fai clic su Utenti > Set di autorizzazioni.
    2. Nella pagina Set di autorizzazioni, fai clic sull'autorizzazione creata in precedenza.
    3. Fai clic su Impostazioni oggetto > Plural Label of the Platform Event.
    4. Nella sezione Autorizzazioni degli oggetti, attiva le autorizzazioni di lettura e creazione.
    5. Fai clic su Salva.
      6. immagine che mostra le autorizzazioni di un evento della piattaformaimmagine che mostra le autorizzazioni di un evento della piattaforma

    Aggiungi un trigger Salesforce

    Per aggiungere un attivatore Salesforce a un'integrazione nuova o esistente:
    1. Nell'interfaccia utente di Apigee, seleziona la tua organizzazione Apigee.
    2. Fai clic su Sviluppa > Integrazioni.
    3. Seleziona un'integrazione esistente o creane una nuova facendo clic su Crea integrazione.

      Se stai creando una nuova integrazione:

      1. Inserisci un nome e una descrizione nella finestra di dialogo Crea integrazione.
      2. Seleziona una regione per l'integrazione dall'elenco delle regioni supportate.
      3. Fai clic su Crea.

      In questo modo viene aperta l'integrazione nel designer dell'integrazione.

    4. Nella barra di navigazione del designer dell'integrazione, fai clic su +Aggiungi un'attività/un trigger > Tasks per visualizzare l'elenco delle attività disponibili.
    5. Seleziona un'integrazione esistente o fai clic su Crea integrazione.
    6. Nell'editor di integrazione, fai clic su + Aggiungi un'attività/un attivatore > Trigger per visualizzare gli attivatori disponibili
    7. Fai clic sull'elemento attivatore Salesforce e posizionalo nel designer.

    Configurare il trigger di Salesforce

    Per configurare il trigger di Salesforce, segui questi passaggi:

    1. Fai clic su Trigger Salesforce nell'editor di integrazione per visualizzare il riquadro di configurazione del trigger.
    2. Seleziona un'istanza Salesforce dal menu a discesa Configurazione dell'istanza Salesforce.

      Se non hai un'istanza Salesforce, creane una nuova. Per saperne di più, consulta Creare una nuova istanza Salesforce.

    3. Seleziona un canale Salesforce dal menu a discesa Configurazione canale Salesforce.

      Se non disponi di un canale Salesforce, creane uno nuovo. Per saperne di più, consulta Creare un nuovo canale Salesforce.

    4. Se hai scelto CDC come tipo di evento, seleziona una qualsiasi delle seguenti operazioni:
      • Create
      • Update
      • Delete
      • Undelete

      Il trigger viene eseguito solo se si verifica l'operazione specifica o l'operazione gap.

      Il trigger di Salesforce può essere configurato per una sola operazione. Se vuoi eseguire il trigger per più operazioni, crea un trigger Salesforce per ogni operazione.

    Crea una nuova istanza Salesforce

    Per configurare una nuova istanza Salesforce:

    1. Nelle proprietà modificabili del trigger, fai clic su Seleziona una configurazione di istanza Salesforce > + Aggiungi nuova configurazione istanza Salesforce.
    2. Nella finestra di dialogo Aggiungi configurazione istanza Salesforce, imposta le seguenti proprietà:
      • Nome connessione istanza Salesforce: inserisci un nome per l'istanza.

        Dopo la configurazione, utilizzerai questo nome per fare riferimento all'istanza Salesforce.

      • Dominio Salesforce: inserisci un'autorità di servizio per l'istanza. Puoi trovare il dominio nel tuo account Salesforce. Ad esempio, instance.my.salesforce.com. L'immagine seguente mostra il dominio Salesforce:

        Ottieni il dominio Salesforce in un'istanza Salesforce Ottieni il dominio Salesforce in un'istanza Salesforce

      • Profilo di autenticazione: seleziona un profilo di autenticazione.

        Se non hai un profilo di autenticazione, creane uno nuovo per il tipo di autenticazione Credenziali della password del proprietario della risorsa OAuth 2.0. La seguente immagine mostra i campi obbligatori per creare un profilo di autenticazione:

        Credenziali della password del proprietario delle risorse OAuth 2.0 Credenziali della password del proprietario delle risorse OAuth 2.0

        Per informazioni sui campi, vedi Credenziali della password del proprietario delle risorse OAuth 2.0. Per l'istanza Salesforce, inserisci i seguenti valori:
        • ID client:inserisci la chiave utente che hai annotato durante la configurazione di un'app collegata.
        • Secret:inserisci il segreto utente che hai annotato durante la configurazione di un'app collegata.
        • Password: inserisci la password utente nel formato USER_PASSWORDSECURITY_TOKEN. Sostituisci quanto segue: Ad esempio, se il tuo USER_PASSWORD è test-password e SECURITY_TOKEN è 737K27NCa3O6, la tua password sarà test-password737K27NCa3O6.
  • ID organizzazione Salesforce: inserisci l'ID organizzazione dell'istanza Salesforce. Puoi ottenere l'ID dall'amministratore Salesforce.
  • Fai clic su Aggiungi.

    • Creare un nuovo canale Salesforce

    Per configurare un nuovo canale Salesforce:

    1. Nelle proprietà modificabili dell'attivatore, fai clic su Seleziona una configurazione del canale Salesforce > + Aggiungi nuova configurazione del canale Salesforce.
    2. Nella finestra di dialogo Aggiungi configurazione canale Salesforce, inserisci il nome dell'oggetto per la proprietà Nome oggetto Salesforce.

      Se hai dubbi sul nome dell'oggetto, contatta l'amministratore Salesforce.

    3. Fai clic su Aggiungi.

    Variabili di output

    La risposta del trigger di Salesforce è disponibile nelle variabili di output.

    Le variabili di output per un evento CDC sono descritte nella seguente tabella:

    Variabile Tipo di dati Description
    SalesforceTriggerCdcPayload JSON Dettagli dell'evento di modifica.
    SalesforceTriggerEvent JSON Contiene replayId dell'evento.
    SalesforceTriggerSchema Stringa Schema del trigger.
    SalesforceTriggerCdcSnapshot JSON Snapshot dell'oggetto dopo l'evento di modifica. Questo campo è disponibile solo per le operazioni Update e Create.
    SalesforceTriggerCdcRecordId Stringa Contiene il valore recordId del record aggiornato o aggiunto. recordId è un identificatore dell'oggetto Salesforce modificato.

    Le variabili di output per un evento Platform sono descritte nella seguente tabella:

    Variabile Tipo di dati Description
    SalesforceTriggerPEPayload JSON Dettagli dell'evento di modifica.
    SalesforceTriggerEvent JSON Contiene replayId dell'evento.
    SalesforceTriggerSchema Stringa Schema del trigger.
    Il parametro di output per questo attivatore è la variabile JSON CdcTriggerPayload. La variabile JSON contiene oggetti record aggiornati.

    best practice

    L'attivatore Salesforce è consigliato nei casi in cui vuoi utilizzare le notifiche Salesforce per attivare le integrazioni senza scrivere codice personalizzato per pubblicare eventi Salesforce. Qualsiasi modifica di piccola entità nel campo della richiesta di assistenza di Salesforce attiva un evento CDC di Salesforce e, di conseguenza, attiva un'integrazione, che può generare un rumore di integrazione significativo. Valuta la possibilità di utilizzare Modifica filtri eventi per filtrare solo gli eventi CDC richiesti che attivano l'integrazione. L'utilizzo di Modifica i filtri di eventi può aiutare a ridurre il rumore di integrazione e a garantire la conformità con le limitazioni delle licenze.

    Allo stesso modo, ti consigliamo di annullare la pubblicazione di qualsiasi integrazione utilizzando questo attivatore quando l'integrazione non è più necessaria. Finché non viene annullata la pubblicazione o viene eliminata, l'integrazione continuerà a rimanere in ascolto per gli eventi CDC e della piattaforma di Salesforce.

    Considerazioni

    Prima di utilizzare il trigger di Salesforce per eseguire l'integrazione, considera quanto segue:

    • In genere, Salesforce invia un massimo di 100.000 eventi della piattaforma CDC e della piattaforma al giorno. Rivolgiti all'amministratore Salesforce per comprendere le limitazioni delle tue licenze prima di scegliere gli eventi CDC per l'attivatore di integrazione.
    • Se stai pianificando caricamenti collettivi su Salesforce, ti consigliamo di mettere in pausa CDC per ridurre il rumore di integrazione e garantire la conformità alle limitazioni delle tue licenze.
    • Le dimensioni massime dei messaggi evento che Salesforce possono pubblicare sono pari a 1 MB. Per maggiori informazioni, consulta Modificare le allocazioni di acquisizione dati.
    • Apigee non supporta gli eventi CDC di Salesforce per le seguenti regioni del minicluster:
      • asia-northeast1
      • asia-south1
      • australia-southeast1
      • europe-west2
      • europe-west3
      • europe-west6
      • northamerica-northeast1
      • southamerica-east1
      • us-east4
      • us-west2