Trigger di Salesforce

Annuncio: Application Integration è ora disponibile per il tuo progetto Google Cloud. Ora puoi utilizzare sia Apigee Integration che Application Integration all'interno dello stesso progetto Google Cloud. Scopri di più

Il trigger di Salesforce consente di ascoltare gli eventi Change Data Capture (CDC) o Enterprise Messaging Platform. Con questo trigger, puoi avviare l'integrazione in base a uno qualsiasi degli eventi CDC (Crea, Aggiorna, Elimina o Annulla eliminazione) o agli eventi della piattaforma nella tua istanza Salesforce.

Prima di iniziare

Questa sezione illustra i passaggi necessari per connettere e configurare un'istanza Salesforce per utilizzare gli eventi Change Data Capture (CDC) o Platform per trasmettere le modifiche all'Apigee Integration in un modo Pub/Sub. Devi completare i seguenti passaggi prima di configurare qualsiasi attività o trigger relativo a Salesforce in Apigee:

• Configurare un utente di integrazione
• Configurare un set di autorizzazioni
• Configurare un token di sicurezza
• Creare un'app collegata

Nota: per completare questi passaggi, è necessario l'accesso amministrativo alla tua istanza Salesforce. Se non disponi dell'accesso amministrativo, condividi queste istruzioni con l'amministratore Salesforce.

Questo tutorial fornisce istruzioni approfondite, ma ti consigliamo di acquisire familiarità con le opzioni di configurazione di Salesforce. Salesforce fornisce la documentazione per gli sviluppatori dettagliata per aiutarti a iniziare.

Configura un utente di integrazione

Nota: se hai già un utente di integrazione e conosci la password, puoi andare al passaggio successivo. Se devi reimpostare la password, vedi il passaggio 6 di seguito.

Per configurare un utente di integrazione:

1. Accedi all'istanza Salesforce con le tue credenziali di sysadmin.
2. Fai clic sull'icona a forma di ingranaggio e seleziona Configurazione, come mostrato nell'immagine di seguito:
3. Fai clic su Utenti > Utenti dal menu Amministrazione.
4. Dal riquadro Utenti, seleziona il pulsante Nuovo utente.
5. Nella finestra di dialogo Modifica utente, inserisci i seguenti dettagli:
   1. Nome: nome dell'utente di integrazione.
   2. Cognome: cognome dell'utente di integrazione.
   3. Indirizzo email: l'indirizzo email dell'utente di integrazione. Idealmente, dovrebbe essere un indirizzo email di gruppo.
   4. Nome utente: il nome utente conforme alle convenzioni di denominazione a livello di organizzazione.

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

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

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

      Consigliamo di assegnare un profilo senza autorizzazioni per proteggere l'accesso a Salesforce dell'utente di integrazione da un utilizzo non autorizzato.

   8. Fai clic su Salva.
6. Per aggiornare la password per il nuovo utente di integrazione:
   1. Fai clic sul pulsante Reimposta password nel riquadro Utenti. Viene inviata un'email di reimpostazione della password all'indirizzo email associato all'utente.
      Nota: prima di attivare il flusso di reimpostazione della password, verifica di avere accesso all'account email associato all'utente di integrazione. Inoltre, se l'accesso SSO è attivo per questo utente, non potrai reimpostare la password. Per abilitare l'opzione di reimpostazione, vai a Profilo > Autorizzazioni di sistema e deseleziona l'opzione SSO Login Enabled (Accesso SSO abilitato).
   2. Segui la procedura 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 procedere con la configurazione di 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. Dal 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 il set di autorizzazioni.
   • Licenza: seleziona Salesforce dal menu a discesa Licenza.
   • Fai clic su Salva.
4. Nell'elenco delle opzioni delle impostazioni 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 API abilitata.

   È richiesta anche l'autorizzazione Utente solo API, ma non può essere attivata finché non viene reimpostato il token di sicurezza. 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 di integrazione l'accesso ai nuovi oggetti. Ti consigliamo di abilitare queste autorizzazioni solo per i test in una sandbox.
8. Scorri fino in cima all'elenco delle autorizzazioni e fai clic su Salva.
9. Conferma le impostazioni e fai clic su Salva.

Per configurare il set di autorizzazioni per l'oggetto Salesforce:

1. Fai clic su Panoramica del set di autorizzazioni per tornare alla pagina di configurazione principale del Set di autorizzazioni.
2. Seleziona Impostazioni oggetto 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.
   NOTA: CDC supporta solo un sottoinsieme di oggetti Salesforce standard. Per saperne di più, consulta: Supporto degli oggetti di modifica.
4. Fai clic sul pulsante Modifica nella pagina dei dettagli dell'oggetto.
5. Seleziona le caselle di controllo per i tipi di record. Se sai quali tipi di record sono obbligatori, selezionali. Se non sai quali tipi di record sono richiesti, selezionali tutti.
6. Seleziona le caselle di controllo per le Autorizzazioni degli oggetti da abilitare. Ti consigliamo le opzioni Leggi e Visualizza tutto.
7. Concedi l'accesso in lettura o l'accesso in modifica a ciascun campo dell'oggetto selezionando la casella di controllo corrispondente.
   Nota: l'accesso in scrittura non è necessario per l'utilizzo con la CDC.
8. Scorri fino in cima alla pagina e fai clic su Salva.

Configura un token di sicurezza

Se hai già creato un token di sicurezza per l'utente di integrazione e hai reimpostato la password, viene inviata automaticamente un'email con un nuovo token di sicurezza. Puoi utilizzare il nuovo token e passare direttamente a Creare un'app collegata.

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 in un passaggio precedente.
2. Nel menu principale, fai clic sull'immagine del profilo e poi su Impostazioni.
3. Dal menu Settings (Impostazioni), seleziona Reset My Security Token (Reimposta il token di sicurezza) per aprire il riquadro Reset Security Token (Reimposta token di sicurezza).
4. Fai clic sul pulsante Reimposta token di sicurezza.
5. Cerca nell'account email associato all'utente di integrazione un'email contenente il nuovo token di sicurezza. Prendi nota del nuovo token di sicurezza, perché ti servirà in un passaggio successivo.
6. (Facoltativo) Attiva l'autorizzazione Solo utenti API in Autorizzazioni di sistema per il tuo set di autorizzazioni, come descritto in Configurare un set di autorizzazioni in alto.

Crea un'app connessa

Per configurare un'app connessa è necessaria l'autorizzazione di amministrazione del sistema. Se al momento hai eseguito l'accesso come utenti dell'integrazione, assicurati di uscire e di accedere nuovamente come sysadmin.

Per configurare un'app connessa:

1. Fai clic sull'icona a forma di ingranaggio, quindi seleziona Configurazione.
2. Nel menu Configurazione, cerca e seleziona Gestione app, come mostrato nell'immagine di seguito:
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 l'app collegata, possibilmente 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 effettuare un callback, assicurati di includere il prefisso http(s)://.
     2. Ambiti OAuth selezionati: seleziona:
        • Accedere ai dati e gestirli (API)
        • Eseguire richieste per tuo conto in qualsiasi momento (refresh_token, offline_access)
5. Fai clic su Salva.
   Nota: l'app connessa appena creata non funzionerà per i primi 2-10 minuti dopo la creazione.
6. Fai clic su Continua. Devi eseguire nuovamente l'autorizzazione con un codice di verifica inviato al tuo indirizzo email.
7. Dopo la verifica del codice, nella pagina successiva verranno visualizzati un consumer secret e una consumer key. Prendi nota di questi valori, poiché verranno utilizzati durante la configurazione del modulo di autenticazione per Apigee.
8. Fai clic sul pulsante Gestisci.
9. Quando ti trovi nella pagina Dettagli app collegata, fai clic sul pulsante Modifica norme.
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 l'insieme di autorizzazioni da applicare all'app collegata.
    Puoi selezionare un profilo, un set di autorizzazioni o una combinazione di entrambi, che consentirà agli utenti con il profilo o il set di autorizzazioni corretti di accedere all'app collegata.
13. Seleziona il profilo o l'insieme di autorizzazioni desiderato.
14. Fai clic su Salva.

Passaggi prerequisiti per utilizzare gli eventi CDC

Prima di configurare il trigger Apigee per l'utilizzo degli eventi CDC, assicurati di aggiungere un oggetto configurato per CDC in Salesforce:

1. Accedi a Salesforce come sysadmin.
2. Fai clic sull'icona a forma di ingranaggio, quindi su Configurazione.
3. Utilizzando il menu di navigazione a sinistra, cerca e seleziona Modifica acquisizione dati.
4. Nella pagina di configurazione Modifica acquisizione dati, individua l'oggetto Salesforce da utilizzare nella colonna Entità disponibili e trascinalo nella colonna Entità selezionate.
   Nota: per CDC è possibile selezionare un massimo di 5 oggetti per licenza Salesforce. Contatta il tuo rappresentante Salesforce per ulteriori informazioni e opzioni di licenza.
5. Fai clic su Salva.

Passaggi prerequisiti per utilizzare gli eventi della piattaforma

Prima di configurare il trigger Apigee per l'utilizzo degli eventi della piattaforma, completa i seguenti passaggi in Salesforce:

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

Crea un evento piattaforma

Per creare un evento della piattaforma, segui questi passaggi:

1. Accedi all'istanza Salesforce con le tue credenziali di sysadmin.
2. Fai clic sull'icona a forma di ingranaggio e seleziona Configurazione.
3. Nel riquadro di navigazione, cerca Piattaforma e poi fai clic su Eventi piattaforma.

4. Nella pagina Eventi piattaforma, fai clic su Nuovo evento della 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 all'istante l'evento, senza attendere la convalida.
  Per saperne di più sul comportamento di pubblicazione, consulta Eventi e transazioni sulla piattaforma.
• (Facoltativo) Stato deployment: seleziona Deployment eseguito se l'evento è pronto per il deployment.

Fai clic su Salva.

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 tutti i campi personalizzati necessario.

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

Aggiorna le autorizzazioni per l'evento della piattaforma

Le autorizzazioni impostate devono essere aggiornate per consentire all'utente di integrazione di accedere all'evento della piattaforma appena creato.

Per aggiornare le autorizzazioni, segui questi passaggi:

1. Dal 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 oggetti, abilita le autorizzazioni Lettura e Creazione.
5. Fai clic su Salva.

Aggiungi un trigger Salesforce

Per aggiungere un attivatore Salesforce a un'integrazione nuova o esistente:

1. Nell'UI 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.

   Viene aperta l'integrazione nel designer dell'integrazione.

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

Configura il trigger di Salesforce

Per configurare il trigger di Salesforce, segui questi passaggi:

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

   Se non disponi di un'istanza Salesforce, creane una nuova. Per maggiori informazioni, consulta Creare una nuova istanza Salesforce.

3. Seleziona un canale Salesforce dall'elenco a discesa Configurazione canale Salesforce.

   Se non disponi di un canale Salesforce, creane uno nuovo. Per maggiori informazioni, consulta Creare un nuovo canale Salesforce.

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

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

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

Crea una nuova istanza Salesforce

Per configurare una nuova istanza Salesforce, segui questi passaggi:

1. Nelle proprietà modificabili dell'attivatore, fai clic su Seleziona una configurazione dell'istanza Salesforce > + Aggiungi nuova configurazione istanza Salesforce.
2. Nella finestra di dialogo Aggiungi la configurazione dell'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 di 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. La seguente immagine mostra il dominio Salesforce:

  

• Profilo di autenticazione: seleziona un profilo di autenticazione.

  Se non hai un profilo di autenticazione, creane uno nuovo di tipo Credenziali della password del proprietario della risorsa OAuth 2.0. Nell'immagine seguente sono mostrati i campi necessari per creare un profilo di autenticazione:

  

  Per informazioni sui campi, vedi Credenziali della password del proprietario della risorsa 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.
  • Segreto: 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:
    • USER_PASSWORD: la password utente Salesforce.
    • SECURITY_TOKEN: il token di sicurezza che hai impostato per l'integrazione.
    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.
3. Fai clic su Aggiungi.

Crea 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 la configurazione del 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 dell'attivatore Salesforce è disponibile nelle variabili di output.

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

Variabile	Tipo di dati	Descrizione
SalesforceTriggerCdcPayload	JSON	Dettagli dell'evento di modifica.
SalesforceTriggerEvent	JSON	Contiene replayId dell'evento.
SalesforceTriggerSchema	String	Schema del trigger.
SalesforceTriggerCdcSnapshot	JSON	Snapshot dell'oggetto dopo l'evento di modifica. Questo campo è disponibile solo per le operazioni Update e Create.
SalesforceTriggerCdcRecordId	String	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	Descrizione
SalesforceTriggerPEPayload	JSON	Dettagli dell'evento di modifica.
SalesforceTriggerEvent	JSON	Contiene replayId dell'evento.
SalesforceTriggerSchema	String	Schema del trigger.

Il parametro di output per questo trigger è la variabile JSON CdcTriggerPayload. La variabile JSON contiene oggetti record aggiornati.

Best practice

L'utilizzo dell'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à ai campi nella richiesta Salesforce attiverà un evento CDC di Salesforce e, di conseguenza, attiverà un'integrazione, che può generare un rumore significativo per l'integrazione. Valuta la possibilità di utilizzare Modifica filtri eventi per filtrare solo gli eventi CDC richiesti che attivano l'integrazione. L'utilizzo di Modifica filtri eventi può contribuire a ridurre il rumore di integrazione e garantire la conformità con le limitazioni della tua licenza.

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

Considerazioni

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

• Salesforce invia generalmente un massimo di 100.000 eventi CDC e Platform al giorno. Rivolgiti all'amministratore Salesforce per comprendere le limitazioni delle tue licenze prima di scegliere gli eventi CDC per l'attivatore di integrazione.
  Nota: più integrazioni che utilizzano lo stesso canale Salesforce non raddoppiano l'utilizzo delle quote di Salesforce.
• Se stai pianificando caricamenti collettivi su Salesforce, valuta la possibilità di mettere in pausa la CDC per ridurre il rumore di integrazione e garantire la conformità con le limitazioni della tua licenza.
• La dimensione massima dei messaggi di evento che Salesforce può pubblicare è 1 MB. Per maggiori informazioni, consulta la sezione Modificare le allocazioni delle acquisizioni dati.
• Apigee non supporta gli eventi CDC di Salesforce per le seguenti regioni:
  • asia-northeast1
  • asia-south1
  • australia-southeast1
  • europe-west2
  • europe-west3
  • europe-west6
  • northamerica-northeast1
  • southamerica-east1
  • us-east4
  • us-west2