Modello di articolo

Informazioni sull’evento JSON

Avete mai voluto che una richiesta fatta sul vostro sito web facesse scattare un ticket in Qualtrics? Avete mai desiderato creare un’integrazione perfetta tra Qualtrics e il vostro sistema interno? Vi è mai capitato di voler triggerare un’attività nella scheda Flussi di lavoro, ma con un evento che si verifica al di fuori di Qualtrics?

Gli eventi JSON consentono a software esterni di avviare flussi di lavoro tramite richiesta HTTP. Invece di aspettare che un evento in Qualtrics attivi ulteriori azioni nella piattaforma, è possibile configurare semplicemente un evento JSON per ricevere richieste da terze parti.

Limitazioni

L’evento JSON non è compatibile con le seguenti impostazioni e configurazioni:

• Tutto ciò che non è HTTP (ad esempio, coda di messaggi, SMS).
• Chiamate HTTP in uscita.
• Elaborare XML (il corpo della richiesta XML sarà ignorato).
• Elaborare qualsiasi cosa che non sia JSON.
• Autenticarsi in qualsiasi altro modo che non sia un’intestazione X-API-TOKEN o il nostro HTTP basic auth modificato.
  Consiglio Q: OAuth e altre forme di autenticatori sono incompatibili con gli eventi JSON.
• Qualsiasi parsing JSON che non può essere soddisfatto utilizzando le query JSONPath sul corpo JSON.
• Chiamate che superano il limite della tariffa API di 3.000 al minuto.
• Carichi utili superiori a 100 KB.

Tipi di autorizzazione supportati

Autenticazione basata su token / Autenticazione tramite intestazione

È possibile autenticarsi passando il proprio token API nell’intestazione della richiesta come X-API-TOKEN.

.curl -X POST -H 'X-API-TOKEN: yourapitokenhere' -H 'Content-Type: application/json' -d '{

 

surveyId": "SV_012345678912345",

  "format": "csv"

}' 'https://yourdatacenterid.qualtrics.com/API/v3/responseexports'

Autenticazione di base HTTP

Basic Auth è solitamente una versione codificata Base64 di nome utente:password. Tuttavia, per una maggiore sicurezza, Qualtrics utilizza una stringa codificata Base64 di username:x-api-token.

Per utilizzare Basic Auth, è necessario impostare le intestazioni sulla richiesta HTTP. L’intestazione specifica è AUTORITÀ.

 demo@qualtrics.com:f8gIK7G6GFH985Y4

 Base ZGVtb0BxdWFsdHJpY3MuY29tOmY4Z0lLN0c2R0ZIOTg1WTQ=

Impostazione di un evento JSON

1. Per prima cosa, è necessario creare un flusso di lavoro. Andate alla pagina Flussi di lavoro autonomi.
   
   Consiglio Q: è possibile utilizzare eventi JSON anche nel metodo Scheda Flussi di lavoro in un progetto. Consigliamo di aggiungere un flusso di lavoro a un progetto specifico solo se sono esplicitamente collegati. (Ad esempio, si distribuisce il progetto con l’evento JSON)
2. Assicuratevi di essere nella scheda Flussi di lavoro .
3. Fare clic su Crea un flusso di lavoro.
4. Selezionare Avviato alla ricezione di un evento.
5. Selezionare l’evento JSON .
   
6. Se lo si desidera, specificare un sommario del Trigger, che dovrebbe descrivere lo scopo dell’evento JSON.
7. Verrà fornito un URL. Utilizzate questa opzione per richiamare il vostro nuovo flusso di lavoro dall’esterno di Qualtrics, utilizzando Postman, il vostro sistema interno o altre applicazioni simili. Per copiarlo, fare clic su Copia URL.
8. Per impostazione predefinita, gli eventi JSON richiedono l’autenticatore. Se si desidera consentire richieste non autenticate, è possibile disabilitare la richiesta di autenticazione da parte di QUALTRICS.
9. Ora è possibile definire i dati dell’evento. In questo modo si acquisiscono i dati della richiesta in entrata. Per iniziare, fare clic su Impostazioni avanzate.
   
   Consiglio Q: per informazioni sulla sezione Test, vedere Acquisizione di eventi di seguito.
10. Nella casella a sinistra, indicare il nome del campo JSON. Nella casella a destra, indicare la posizione all’interno dei dati dell’evento (corpo della richiesta HTTP).
    Consiglio Q: le posizioni devono essere in formato JSONPath! Vedere la tabella seguente per una guida rapida alla sintassi di JSONPath.
11. Per aggiungere un altro campo, fare clic su Aggiungi un campo JSON.
12. Se si desidera aggiungere un parametro QUERY, aggiungerlo nella sezione Parametri QUERY . Per ulteriori informazioni su cosa sono questi parametri e come funzionano nelle API, consultare la nostra Documentazione API sui parametri.
    Attenzione: Non è consigliabile passare dati di identificazione personale attraverso parametri QUERY. Tutte le informazioni personali o i dati sensibili devono essere passati attraverso il corpo POST quando possibile, in quanto il POST è più sicuro. Per domande o dubbi, contattare il Supporto Qualtrics.
13. Per rimuovere un campo, fare clic sul segno meno ( – ).
14. Per salvare le modifiche, fare clic su Salva.
15. Ora è possibile aggiungere condizioni e un’attività al flusso di lavoro facendo clic sul segno più ( + ). Le condizioni determinano l’esecuzione di un flusso di lavoro, mentre le attività sono il risultato del flusso di lavoro. Vedere il Panoramica dei flussi di lavoro per ulteriori informazioni.
    

Cattura degli eventi

Quando si crea un evento API esterno, potrebbe essere necessario analizzare i dati dal corpo del post. Tuttavia, a volte può essere difficile analizzare questi dati. Se si vuole capire cosa sta inviando l’API esterna, seguire questi passaggi.

1. Fare clic sull’evento JSON.
   
2. Per impostazione predefinita, l’opzione Cattura campi JSON dai risultati del test in modo che possano essere utilizzati come testo trasferito in altre attività di questo flusso di lavoro sarà attivata. Questa opzione fa sì che i campi analizzati nel corpo del payload siano automaticamente disponibili come testo trasferito quando si aggiungono le attività del flusso di lavoro.
   
3. Fare clic su Esegui un nuovo test.
4. Verrà visualizzato un messaggio che indica che Qualtrics è in attesa di ricevere l’evento dal sistema esterno. Attivare l’API esterna.
   Consiglio Q: per annullare il test, fare clic su Annulla test.
5. Se il test è riuscito, verrà visualizzato il messaggio Connessione riuscita al server. Il carico utile verrà analizzato e aggiunto alla finestra.
6. Se si desidera, fare clic su Esegui un nuovo test per eseguire un altro test. Dopo aver cliccato su questa opzione, è necessario eseguire la chiamata API avanti.
7. Fare clic su Salva.

Sintassi di JSONPath

La tabella seguente fornisce alcune delle basi della sintassi di JSONPath. Si noti che questi non sono stabiliti da Qualtrics, ma sono standard utilizzati con JSON.

Esempio di sintassi JSONPath

In questo esempio mostreremo come, dato un oggetto JSON, si possa utilizzare la tabella JSONPath.

Questo è il nostro oggetto JSON:

{
"eventDescription": "Entrate mensili",
"negozi": [
{
"nome": "Acme Store",
"total": 1000000,
"topItem":

{ "price": "50", "descrizione": "Incudine" }
},
{
"nome": "Il chiosco delle banane",
"totale": 250000,
"topItem":

{ "prezzo": "4", "descrizione": "Il Gob" }
},
{
"name": "Pizza Planet",
"totale": 80000,
"topItem":

{ "prezzo": "15", "descrizione": "Pepperoni" }
}
]
}

Ora dovremmo aggiungere i valori di ritorno che vediamo nella tabella JSONPath per rendere il tutto più chiaro.

$ -> Acme Store
@ -> [
{
"nome": "Acme Store",
"total": 1000000,
"topItem":

{ "price": "50", "descrizione": "Incudine" }
}
]
. -> Entrate mensili
... -50

-> ["Acme Store", "The Banana Stand", "Pizza Planet"]
[] -> Acme Store
[,] -> [
Macro sconosciuta: {"nome"}
,

Macro sconosciuta: {"nome"}
]

**Cambia l'Esempio di [inizio:fine:passo] con "$.negozi[1:3:1]"
[start:end:step] -> [
{
"nome": "Il chiosco delle banane",
"total": 250000,
"topItem":

{ "price": "4", "descrizione": "Il Gob" }
},
{
"name": "Pizza Planet",
"totale": 80000,
"topItem":

{ "prezzo": "15", "descrizione": "Pepperoni" }
}
]

?() -> [{
"nome": "Acme Store",
"total": 1000000,
"topItem":

{ "price": "50", "descrizione": "Incudine" }
}]

() -> [
{
"nome": "Pizza Planet",
"totale": 80000,
"topItem":

{ "prezzo": "15", "descrizione": "Pepperoni" }
}
]

Esempio di API in Node Javascript

L’esempio che segue è un modello di base da seguire per la formattazione dei dati degli eventi.

var request = require('request-promise');
var surveyId = "SV_XXXXXXXXXX";
var triggerId = "OC_XXXXXXXXX";
var brandId = "YOUR_BRAND_ID";
var userId = "UR_XXXXXXXXXXXXX";
var datacenter = "xx1";
var apiToken = "YOUR_QUALTRICS_API_TOKEN";

var url = "https://" + datacenter + ".qualtrics.com/inbound-event/v1/event/JSON/trigger" +
     "?contextId=" + surveyId + "&userId=" + userId + "&brandId=" + brandId + "&triggerId=" + triggerId;
var payload = {
    "text": "Questo è un testo",
    "object": {
        "number": 4
    },
    "array": ["a", "b", "c", "d"]
};

var options = {
    url: url,
    json: true,
    body: payload,
    headers: {
        "Content-Type": "application/json", // OBBLIGATORIO!!!
        "X-API-TOKEN": token API
    }
};

request.post(options).then(function (ret) {
    console.log("success:", url, payload);
}).catch(function (err) {
    console.log("error: ", url);
    console.log(err);
});

Esempio: Integrazione con Freshdesk

L’evento JSON può essere utilizzato per l’integrazione con Freshdesk come regola Webhook in Dispatch’r. Ciò significa che gli eventi in Freshdesk possono attivare attività in Qualtrics, come la creazione di un ticket o la distribuzione di un sondaggio.

1. In QUALTRICS, impostare l’evento su Evento JSON.
   
2. Copiare l’URL.
   
3. In una nuova scheda, accedere a Freshdesk.
4. Nella sezione Amministrazione, selezionare l’opzione più adatta al tipo di regola che si desidera impostare.
   
   Consiglio Q: Scopri la differenza tra Dispatch’r, Supervisor e Observernella documentazione di supporto di Freshdesk.
5. Creare una nuova regola.
   
6. Impostare le condizioni per determinare quale evento di Freshdesk debba innescare un’attività in QUALTRICS.
   
   Esempio: Forse quando un agente Freshdesk fa in modo che lo stato del ticket passi da qualsiasi stato a Risolto, si desidera inviare un sondaggio CSAT utilizzando QUALTRrics.
7. Aggiungere una nuova azione e selezionare Trigger Web Hook.
   
8. Impostare il tipo di richiesta su POST.
   
9. In URL di callback, incollare l’URL dell’evento JSON dal passaggio 2.
10. Per utilizzare l’autenticazione con token, aggiungere intestazioni personalizzate, inserire X-API-TOKEN: e impostarlo uguale al token API.
    
11. Per utilizzare l’autenticazione HTTP Basic, fare clic su Requires Authentication, aggiungere il nome utente di Qualtrics e, al posto della password, inserire il token API.
    
12. Assicurarsi che la codifica sia JSON.
    
13. Selezionare manualmente il contenuto da trasmettere o scegliere Avanzate per inserire un corpo JSON.
14. Salvate la vostra regola.
15. In Qualtrics, terminate il flusso di lavoro. In questo esempio, probabilmente aggiungeremo un elemento Attività della DIRECTORY XM .
    
16. Non dimenticate di pubblicare le modifiche al sondaggio quando siete pronti a lanciarlo.

Esempio: Integrazione con ServiceNow

L’evento JSON può essere utilizzato per integrarsi con ServiceNow. Ciò significa che gli eventi in ServiceNow possono attivare attività in Qualtrics, come la creazione di un ticket o la distribuzione di un sondaggio.

1. In QUALTRICS, impostare l’evento su Evento JSON.
   
2. Copiare l’URL.
   
3. In una nuova scheda, accedere alla propria istanza di ServiceNow developer.
4. Selezionare Messaggio REST.
   
5. Fare clic su Nuovo.
6. Date un nome al vostro messaggio di riposo.
   
7. Nel campo Endpoint, incollare l’URL copiato nel passaggio 2.
8. Cambiare il tipo di Autenticatore in Basic.
9. Andare alla scheda Richiesta HTTP.
   
10. Fare doppio clic per aggiungere X-API-TOKEN API.
11. Fare doppio clic per incollare il token API.
    
12. In una nuova riga, aggiungere il nome Content-type.
13. Impostare il valore su application/json.
14. Fai clic su Invia.
    
15. Riaprire il messaggio di riposo.
    
16. In Metodi HTTP, fare clic su Nuovo.
    
17. Assegnare un nome al metodo.
    
18. Impostare il metodo HTTP su POST.
19. Impostare il tipo di Autenticità su Eredita dal genitore.
20. Fai clic su Invia.
21. Riaprite il metodo HTTP POST appena creato.
    
22. In fondo alla pagina, selezionare Anteprima uso script.
    
23. Copiare il testo.
24. Cercare e selezionare Regole di business.
    
25. Selezionare Nuovo.
26. Selezionare una tabella.
    
27. Selezionare Avanzate.
28. Determinare quando viene eseguita la regola aziendale.
    Esempio: Se per la tabella è stato selezionato Incidente e si desidera inviare un sondaggio CSAT per i ticket risolti, è possibile aggiungere una condizione che indichi che la regola deve essere eseguita quando lo stato di Incidente cambia in Risolto.
    Consiglio Q: il Supporto Qualtrics può aiutarvi a configurare il vostro Evento JSON e a collegarlo tramite ServiceNow. Tuttavia, potrebbero esserci delle domande sulle funzionalità di ServiceNow a cui non possono rispondere. Se avete domande su come e quando vengono eseguite le regole aziendali, consultate la documentazione di ServiceNow sul funzionamento delle regole aziendali.
29. Andare alla scheda Avanzate.
    
30. Incollare il contenuto copiato dal passaggio 22, dove si dice Aggiungi il tuo codice qui.
    
31. Aggiungere un corpo. Qui si comunicano le informazioni che si desidera trasmettere a Qualtrics.
    

    Esempio: Questo è un esempio del codice finale da inserire in questo campo. La maggior parte di questo codice è il messaggio in uscita fornito da ServiceNow e varia da un esempio all’altro. Purtroppo, il Supporto Qualtrics non può aiutarvi con la codifica personalizzata; se avete problemi con il codice, rivolgetevi alla comunità di ServiceNow per ricevere assistenza.

    La parte in grassetto del codice include tre funzioni aggiuntive non incluse nel codice originale: un corpo JSON che estrae l’ID utente e lo stato dell’incidente e una chiamata che recupera l’indirizzo e-mail del cliente che ha subito l’incidente, in modo da inviargli il CSAT (in corsivo). Consultate la documentazione di ServiceNow e consultate la loro comunità se avete ulteriori domande.

    (function executeRule(current, previous /*null when async*/) {
    
        // Aggiungete il vostro codice qui
        
     try { 
         var r = new sn_ws.RESTMessageV2('Qualtrics JSON Event ', 'JSON Event POST')
         ;var body = {
             "User ID": gs.getUserID()
             "incident state": current.state.getDisplayValue()
          }
         ;
         
         var destinazione = new GlideRecord('sys_user');
         destinazione.addQuery('sys_id', '=', current.caller_id);
         destinazione.query(); 
         while(destinazione.next()) { 
             body["email"] = destinazione.email.getDisplayValue();
         }  
         var response = r.execute();
         var responseBody = response.getBody();
         var httpStatus = response.getStatusCode();
         gs.addInfoMessage(httpStatus);
        }
    catch(ex) {
         var message = ex.message;
         gs.addInfoMessage("Error communicating w QUALTRrics " + message);
    
    }
    
    }(current, previous);

32. Aggiungere il corpo alla richiesta. Aggiungete quanto segue sotto la parte di codice in grassetto e in corsivo del passo precedente:

     r.setRequestBody(JSON.stringify(body)); 

33. Fai clic su Invia.
34. In Qualtrics, terminate il flusso di lavoro. Per continuare con l’esempio del sondaggio CSAT, probabilmente aggiungeremmo un elemento Attività della DIRECTORY XM .
    
35. Non dimenticate di pubblicare le modifiche al sondaggio quando siete pronti a lanciarlo.

Esempio: Integrazione con Microsoft Dynamics attraverso Microsoft Flow

L’Evento JSON consente agli eventi di Microsoft Dynamics di attivare attività in Qualtrics, come la creazione di un ticket o la distribuzione di un sondaggio. Ad esempio, ogni volta che si elimina un account in Microsoft, è possibile distribuire al proprietario dell’account un sondaggio di Qualtrics che pone domande di uscita. (ad esempio, Ci dispiace vederti andare via! Com’è stato il tempo trascorso con noi? Come possiamo migliorare?)

Per integrare l’Evento JSON con le azioni che si svolgono in Microsoft Dynamics, è necessario eseguire l’impostazione all’interno di Microsoft Flow anziché in Dynamics. Non preoccupatevi: Microsoft Flow viene fornito gratuitamente con ogni account Microsoft Dynamics, quindi potete accedere a Flow con i vostri dati Dynamics qui.

1. In QUALTRICS, impostare l’evento su Evento JSON.
   
2. Copiare l’URL.
   
3. In una scheda separata, accedere a https://us.flow.microsoft.com/en-us/ e utilizzare i dati di Microsoft Dynamics per accedere a Flow.
4. Selezionare I miei flussi a sinistra.
   
5. Fare clic su Nuovo e selezionare Automatico – da vuoto.
6. Dare un nome al flusso.
   
7. Selezionare un trigger. Questo è l’evento che si verifica in Microsoft e che avvia l’attività in Qualtrics. Potete scegliere quello che vi serve, ma per questo esempio sceglieremo “Quando un record viene eliminato (Dynamics 365)”
8. Fare clic su Crea.
9. Alla voce Nome organizzazione, accedere al proprio account Dynamics.
   
10. In Nome entità, scegliere il tipo di record o di file. Per il nostro esempio, useremo “Account”
11. Fare clic su AVANTI e selezionare Aggiungi un’azione.
12. Selezionare HTTP.
    
13. Cambiare il metodo in POST.
14. Incollare l’URL dell’evento JSON nel campo URI.
15. Utilizzare un token di autenticazione. In Intestazioni, inserire X-API-TOKEN e nel campo avanti incollare il token API.
16. Alla voce Corpo, è possibile inserire un corpo JSON. Questo aiuta a decidere quali informazioni passare da Dynamics a Qualtrics.
    Consiglio Q: Utilizzate il pulsante Aggiungi contenuto dinamico per selezionare i campi del record Dynamics che desiderate trasferire a Qualtrics. Assicurarsi di seguire il formato JSON corretto, come mostrato nella schermata. Per assistenza nella risoluzione dei problemi relativi ai contenuti dinamici, rivolgersi all’assistenza Microsoft.
17. Al termine, fare clic su Salva.
18. In Qualtrics, terminate il flusso di lavoro. In questo esempio, probabilmente aggiungeremo un elemento Attività della DIRECTORY XM .
    
19. Non dimenticate di pubblicare le modifiche al sondaggio quando siete pronti a lanciarlo.

Esempio: Integrazione con Genesys PureCloud

Utilizzando eventi JSON, è possibile integrarsi con Genesys PureCloud per inviare ai clienti un follow-up del sondaggio dopo aver completato un’interazione telefonica o via chat.

1. Nel sondaggio che si desidera inviare, spostarsi su Flussi di lavoro.
   
2. Creare un nuovo flusso di lavoro basato su eventi.
3. Per l’evento del flusso di lavoro, selezionare l’evento JSON .
   
4. Fare clic su Copia URL per copiare l’endpoint dell’evento negli appunti.
   
5. Senza chiudere la finestra dell’evento JSON, aprire una nuova scheda nel browser e navigare verso Genesys.
6. Andare in Amministrazione.
   
7. Fare clic su Azioni.
8. Fare clic su Aggiungi azione.
   
9. Selezionare Azioni dati servizi web come nome dell’integrazione.
   
   Consiglio Q: se non si ha la possibilità di selezionare le Azioni dati dei servizi Web, è necessario abilitare l’integrazione. Per ulteriori informazioni, consultare questa pagina.
10. Assegnare un nome all’azione.
11. Fare clic su Aggiungi.
12. Passare alla scheda Impostazione.
    
13. Andare alla scheda Contratti.
14. In Contratto di input, selezionare JSON.
15. Configurare le proprietà che vengono inviate a Qualtrics.

    Esempio: Ad esempio, il codice seguente passerà l’indirizzo e-mail, il numero di telefono, il nome e il cognome.

    {
           "tipo": "object",
           "properties": {
             "emailAddress": {
               "type": "string"
             },
             "phoneNumber": {
               "type": "string"
             },
             "firstName": {
               "type": "string"
             },
             "lastname": {
               "tipo": "string"
             }
           },
           "additionalProperties": true
         }

16. Andare alla scheda Configurazione .
17. Cambiare il tipo di richiesta in POST.
18. Nel campo Modello di URL della richiesta, incollare l’URL dell’evento JSON in Qualtrics.
19. Fare clic su Aggiungi intestazione.
    
20. Nella casella Chiave , inserire X-API-TOKEN API.
21. Nella casella Valore, inserire il token API di Qualtrics.
22. Andare alla scheda Test.
23. Immettere i valori di prova per le proprietà.
24. Fare clic su Esegui azione.
25. Genesys vi dirà se l’azione è andata a buon fine. Se l’operazione non è riuscita, verrà visualizzata la risposta all’errore per aiutare l’utente a risolvere il problema.
    
26. Tornare all’Evento JSON in Qualtrics e verificare che le proprietà siano state passate a Qualtrics con successo.
27. Fai clic su Salva.
28. Fare clic sul segno più ( + ) e poi su Attività per impostare l’attività che si desidera seguire quando viene triggerato l’evento JSON. Nel nostro caso, vogliamo inviare un sondaggio ai rispondenti, quindi selezioniamo l’attività Directory XM.
    Consiglio Q: Quando si imposta l’attività, utilizzare il menu Testo trasferito per utilizzare i valori trasmessi da Genesys (ad esempio, e-mail del cliente, nome, ecc.).
29. Dopo aver impostato l’attività in Qualtrics, tornare a Genesys e fare clic su Salva e Pubblica.
    
30. Fare clic su Sì.
31. Andare in Amministrazione.
32. Fare clic su Architetto.
33. Selezionare Invito al sondaggio nel menu a discesa del flusso.
34. Fare clic su Aggiungi.
35. Date al vostro flusso un nome, una descrizione e una divisione.
36. Fare clic su Crea flusso.
37. Nella sezione Dati della casella degli strumenti, selezionare l’azione Chiama dati e trascinarla nella casella di riepilogo del flusso.
38. Date un nome alla vostra azione.
39. Per la categoria, selezionare Azione dati servizi web.
40. Per Azione dati, selezionare l’azione dati creata in precedenza.
41. Avanti a ciascuna proprietà, fare clic sul menu a discesa e selezionare Espressione.
42. Per i valori delle proprietà, inserire i dati da inviare per ciascuna proprietà. La casella compila automaticamente i campi man mano che si digita.
    Consiglio Q: in questa pagina sono presenti tutte le proprietà predefinite incluse nel flusso dell’invito al sondaggio. È possibile utilizzare espressioni complesse anche in situazioni in cui le informazioni sul contatto con il cliente sono mancanti o richiedono una formattazione aggiuntiva.
    Consiglio Q: le informazioni di contatto sono precedute da Sondaggio.CustomerContact.
43. Fare clic sulla casella più in basso del flusso.
44. Selezionare Casella degli strumenti, quindi Invito al sondaggio, quindi Interrompi sondaggio.
45. Selezionare optOut per la disposizione.
46. Fare clic su Pubblica. Genesys convalida il flusso e lo pubblica. Una volta fatto questo, il flusso è pronto e inizierà a inviare sondaggi ai clienti quando completano le interazioni di assistenza.

FAQ