Le variabili nelle Query di Zoho CRM ti permettono di inserire valori dinamici in fase di esecuzione, rendendo una singola query salvata riutilizzabile in molti contesti diversi senza doverla riscrivere ogni volta.
Perché è importante
Quando crei una query in Zoho CRM, i valori di filtro fissi ne limitano il riutilizzo. Le variabili risolvono questo problema fungendo da segnaposto che vengono compilati nel momento in cui la query viene eseguita — ad esempio, passando un ID Contatto specifico o un valore Stage da un componente Canvas o da una chiamata API. Capire come dichiararle e utilizzarle correttamente fa risparmiare molto tempo di sviluppo e mantiene la libreria di query snella. [5]
---
Procedura passo dopo passo
Passaggio 1. Accedi alla sezione Query andando su Impostazioni → Developer Hub → Query. Si aprirà la finestra Query, che elenca tutte le query già create. [2]
Passaggio 2. Fai clic su Aggiungi Query per iniziare a creare una nuova query. Nel pop-up Crea Query, inserisci un Nome Query e un Nome API, quindi fai clic su Avanti. [2]
Passaggio 3. In Configurazione, il tipo di sorgente predefinito è Modulo Zoho CRM. Se hai bisogno di un tipo di sorgente diverso (come COQL o REST API), fai clic su Cambia per passare a un altro. Seleziona il modulo CRM che vuoi interrogare. Se il modulo contiene campi di lookup, puoi includere moduli correlati tramite il menu a discesa Modulo Correlato — tieni presente che è consentito un massimo di due campi di modulo correlato. [2]
Passaggio 4. Dal menu a discesa Campi, seleziona i campi che vuoi che la query restituisca. Puoi selezionare fino a 50 campi in una singola query. [2]
Passaggio 5. In Criteri, scegli come filtrare i record. Le opzioni sono Nessuno (nessun filtro), filtra per ID Record, oppure applica Criteri personalizzati usando comparatori combinati con operatori AND/OR. È qui che le variabili diventano essenziali: invece di digitare un valore fisso per un criterio, scegli l'opzione di valore dinamico. Un valore dinamico indica che i dati effettivi verranno forniti quando la query viene eseguita altrove nella tua configurazione CRM. [2]
Passaggio 6. Dichiara la tua variabile utilizzando la sintassi richiesta. Ovunque tu voglia un valore dinamico — all'interno di un campo criteri, un'istruzione COQL, un endpoint REST API o un valore parametro — digita il nome della variabile racchiuso tra doppie parentesi graffe: {{VARIABLE_NAME}}. Questo è l'unico formato accettato; qualsiasi variazione impedirà il riconoscimento della variabile in fase di esecuzione. [1][5]
Passaggio 7. Le variabili sono supportate in più posizioni della query: valori dei criteri, istruzioni COQL, URL degli endpoint e altri campi parametro. Quando in seguito associ la query a un componente come una vista Canvas, ti verrà chiesto di mappare ogni variabile dichiarata al campo o alla sorgente dati appropriata, in modo che il valore in fase di esecuzione possa essere passato correttamente. [5]
Passaggio 8. Una volta configurati la query e i relativi variabili, procedi con il salvataggio. Puoi rivisitare la query in qualsiasi momento dalla scheda Query. Per modificare la struttura della risposta, passa il cursore sulla query, fai clic sull'icona a tre punti e seleziona Gestisci Schema — questo ti consente di modificare i tipi di campo e le etichette nell'output della query senza riscriverla. [1]
---
Errori comuni
- Sintassi della variabile errata. Le variabili devono essere scritte come
{{VARIABLE_NAME}}— parentesi singole, parentesi quadre o qualsiasi altro formato non funzioneranno. Controlla attentamente ogni segnaposto prima di salvare. [1][5] - Variabili non mappate al momento dell'associazione. Se colleghi una query contenente variabili a un componente Canvas o a un'altra funzionalità CRM ma dimentichi di mappare ogni variabile a un campo sorgente, la query fallirà in fase di esecuzione perché non viene fornito alcun valore. Verifica sempre il passaggio di mappatura dopo aver associato una query. [5]
- Superamento dei limiti di campi o lookup. Selezionare più di 50 campi o più di due lookup di moduli correlati causerà il rifiuto della configurazione della query. Pianifica la selezione dei campi prima di creare i criteri. [2]
- Prerequisiti per la sorgente REST API. Se utilizzi un tipo di sorgente REST API anziché un Modulo CRM, devi prima aggiungere l'host esterno ai Domini Attendibili e inserire nella whitelist gli IP di Zoho CRM sul tuo server relay prima che la sorgente possa essere validata e salvata. [5]
---
Cosa verificare
- La sintassi delle variabili è corretta — conferma che ogni segnaposto dinamico nella tua query segua il formato a doppie parentesi graffe
{{VARIABLE_NAME}}prima di salvare. [1] - Le variabili sono mappate — dopo aver associato la query a un Canvas o a un altro componente, apri la configurazione di mappatura e verifica che ogni variabile si risolva in un campo dati attivo. [5]
- Lo schema riflette le tue esigenze — usa Gestisci Schema per confermare che i tipi di campo e le etichette nella risposta della query corrispondano a ciò che il componente che la utilizza si aspetta, specialmente se hai modificato lo schema dopo la creazione iniziale. [1]
---
*Beam Help è una risorsa di supporto esperto indipendente per i prodotti Zoho e non è il supporto ufficiale Zoho. Per problemi a livello di piattaforma, apri sempre un ticket direttamente con Zoho.*