Evento JSON

Informazioni sull’evento JSON

Hai mai voluto che venisse inviata una richiesta sul tuo sito web per attivare un ticket in Qualtrics? Hai mai voluto creare un’integrazione fluida tra Qualtrics e il tuo sistema interno? Hai mai voluto attivare un’attività nella scheda Flussi di lavoro, ma con un evento che si verifica al di fuori di Qualtrics?

Gli eventi JSON consentono al software esterno di avviare workflow tramite richiesta HTTP. Anziché attendere un evento in Qualtrics per attivare ulteriori azioni nella piattaforma, è sufficiente configurare un evento JSON per ricevere richieste da terze parti.

Limitazioni

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

• Tutto ciò che non è HTTP (ad es. coda messaggi, SMS).
• Chiamate HTTP in uscita.
• Elaborare XML (il corpo della richiesta XML verrà ignorato).
• Elabora qualsiasi elemento diverso da JSON.
• Autenticare in qualsiasi modo diverso da un’intestazione X-API-TOKEN o dall’autorizzazione di base HTTP modificata.
  Qtip: OAuth e altre forme di autenticazione sono incompatibili con gli eventi JSON.
• Qualsiasi analisi JSON che non può essere soddisfatta utilizzando le query JSONPath nel corpo JSON.
• Chiamate che superano il limite percentuale API di 3.000 al minuto.
• Payload superiori a 100 KB.

Tipi di autorizzazione supportati

Autenticazione basata su token/autorizzazione testata

È possibile eseguire l’autenticazione trasmettendo il token API tramite l’intestazione della richiesta come X-API-TOKEN.

body.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

Autenticazione di base è generalmente una versione codificata Base64 di username:password. Tuttavia, per una maggiore sicurezza, Qualtrics utilizza una stringa con codifica Base64 di nome utente:x-api-token.

Per utilizzare l’autorizzazione di base, è necessario impostare le testate nella richiesta HTTP. La testata specifica è Autorizzazione.

 demo@qualtrics.com:f8gIK7G6GFH985Y4

 Base ZGVtb0BxdWFsdHJpY3MuY29tOmY4Z0lLN0c2R0ZIOTg1WTQ=

Configurazione di un evento JSON

1. In primo luogo, sarà necessario creare un workflow. Passare alla pagina Workflow standalone.
   
   Consiglio Q: È anche possibile utilizzare gli eventi JSON nel Scheda Flussi di lavoro di un progetto. Si consiglia di aggiungere un workflow a un progetto specifico solo se sono esplicitamente correlati. (Ad esempio, si sta distribuendo quel progetto con l’evento JSON).
2. Assicurarsi di trovarsi nella scheda Flussi di lavoro.
3. Fare clic su Crea un workflow.
4. Selezionare Avviato alla ricezione di un evento.
5. Selezionare l’evento JSON.
   
6. Se lo si desidera, specificare un riepilogo Trigger, che descriva lo scopo dell’evento JSON.
7. Verrà fornito un URL. Utilizza questa opzione per richiamare il tuo nuovo flusso di lavoro dall’esterno di Qualtrics, utilizzando Postman, il tuo sistema interno o altre applicazioni simili. Per copiarlo, fare clic su Copia URL.
8. Per impostazione predefinita, gli eventi JSON richiedono l’autenticazione. Se vuoi consentire richieste non autenticate, puoi disabilitare Richiedi autenticazione da parte di Qualtrics.
9. Ora è possibile definire i dati dell’evento. Ciò acquisirà i dati dalla richiesta in entrata. Per iniziare, fare clic su Impostazioni avanzate.
   
   Consiglio Q: per informazioni sulla sezione Test, consultare Acquisizione di eventi di seguito.
10. Nella casella a sinistra, assegnare il nome del campo JSON. Nella casella a destra, indicare la posizione all’interno dei dati dell’evento (corpo della richiesta HTTP).
    Qtip: le ubicazioni devono essere in formato JSONPath Consultare la tabella sottostante per una guida rapida alla sintassi 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 QUERY Parameters. Per maggiori informazioni su quali sono questi parametri e come funzionano nell’API, consultare la Documentazione API su Parametri.
    Avviso: non è consigliabile passare i dati personali identificabili tramite i parametri QUERY. Eventuali informazioni personali o dati sensibili devono essere trasmessi al corpo POST ogniqualvolta possibile, poiché POST è più sicuro. Contatta il Supporto Qualtrics in caso di domande o dubbi.
13. Per rimuovere un campo, fare clic sul segno meno ( – ).
14. Per salvare le modifiche, fare clic su Salvare.
15. Ora è possibile aggiungere condizioni e un task al workflow facendo clic sul segno più ( + ). Le condizioni determinano quando viene eseguito un workflow, mentre i task sono il risultato del workflow. Vedere la Riepilogo workflow per ulteriori informazioni.
    

Acquisizione di 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 sintatticamente questi dati. Se si desidera scoprire cosa sta inviando l’API esterna, attenersi alla seguente procedura.

1. Fare clic sul proprio evento JSON.
   
2. Di default, verranno attivati i campi JSON di acquisizione dai risultati del test in modo che possano essere utilizzati come testo trasferito in altri task in questa opzione di workflow. Questa opzione la rende in modo che i campi analizzati sintatticamente nel corpo del payload siano automaticamente disponibili come testo trasferito quando si aggiungono i task del workflow.
   
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. Generare l’API esterna.
   Consiglio Q: per annullare questo test, fare clic su Annulla test.
5. Se il test ha avuto esito positivo, verrà visualizzato il messaggio Connessione al server riuscita. Il payload verrà analizzato sintatticamente e aggiunto alla finestra.
6. Se lo si desidera, fare clic su Esegui un nuovo test per eseguire un altro test. Sarà necessario eseguire la prossima chiamata API dopo aver fatto clic su questa opzione.
7. Fare clic su Salvare.

Sintassi JSONPath

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

Esempio di sintassi JSONPath

In questo esempio, verrà mostrato come, in base a un oggetto JSON, è possibile utilizzare la tabella JSONPath.

Questo è il nostro oggetto JSON:

{
 "eventDescription": "Monthly Revenue",
 "store": [
 {
 "name": "Acme Store",
 "total": 1000000,
 "topItem":

 { "price": "50", "description": "Anvil" }
 },
 {
 "name": "The Banana Stand", "total": 250000:
 "topItem": "}
 { "price": "4", }
, "description", "The
 Banana Stand",
 "total": 250000: "topItem":

 "} {"price": "4", },
 "}",
 "Gob": "Planet:

 "}" "price": "4", "}
",
 "Gob": "Planet: "}
" "price"

Ora, dovremmo aggiungere i valori di ritorno che vediamo nella tabella JSONPath per renderlo più chiaro.

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

 { "price": "50", "description": "Anvil" }
 }

 -> Ricavi mensili
 .. -> 50

 -> ["Acme Store", "The Banana Stand", "Pizza Planet"]

 [] -&tt; Acme Store





 [,] -> [
 Nome sconosciuto: {"name:

end:

end" 






 "Unknown macro: {"name" store}



 alla pari 

 **Modificare il nome dell'elemento: [
start:end:end:1]() -> [{
 "name": "Acme Store",
 "total": 1000000,
 "topItem":

 {"price": "50", "description": "Anvil" }
 }]

 () -> [
 {
 "name": "Pizza Planet",

 "total": "80000,
 "topItem": 

 "topItem" 

API di esempio nel nodo Javascript

L’esempio seguente è un modello di base che è possibile seguire durante la formattazione dei dati evento.

var request = request('request-promise');
 var geometyId = "SV_XXXXXXXXXXXX";
 var triggerId = "OC_XXXXXXXXXXX";
 var brandId = "YOUR_BRAND_ID";
 var userId = "UR_XXXXXXXXXXXXXXX";var datacenter = "xx1";var TOacd-Tokapien + "YOXXXXXXXXXXX";
 var datacenter = "xx1";
 var TOacd-APapien = "YOUR_XXXXXXXXXXX";

 var datacenter = "xx1";
      var TOacd-1"contextId=" + geometyId + "&userId=" + userId + "&brandId=" + brandId + "&triggerId=" + triggerId;
 var payload = {
     "text": "This is some text",
     "object": {
         "number": 4
     } head,
     "array": ["a",type", "urc", "object": {
 "number": 4

 } head,
     "array": ["a",
    type", "urc", "bbb", "it
    ", "object": {
         "number": 4
    
        "X-API-TOKEN": apiToken
     }
 };

 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 Smistamento. Ciò significa che gli eventi in Freshdesk possono quindi attivare attività in Qualtrics, come la creazione di un ticket o la distribuzione di un sondaggio.

1. In Qualtrics, imposta il tuo evento su Evento JSON.
   
2. Copiare l’URL.
   
3. In una nuova scheda, accedere a Freshdesk.
4. Nella sezione Amministrazione, passare all’opzione più adatta al tipo di regola che si desidera impostare.
   
   Qtip: apprendere la differenza tra Dispatch’r, Supervisor e Observer nella documentazione di supporto di Freshdesk.
5. Creare una nuova regola.
   
6. Impostare le condizioni per determinare quale evento Freshdesk debba attivare un’attività in Qualtrics.
   
   Esempio: Forse quando un agente Freshdesk lo fa in modo che lo stato del ticket venga modificato da qualsiasi stato a Risolto, vorresti inviare un sondaggio CSAT utilizzando Qualtrics.
7. Aggiungere una nuova azione e selezionare Avvia 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 token, aggiungere intestazioni personalizzate, immettere X-API-TOKEN: e impostarlo su Uguale al token API.
    
11. Per utilizzare l’autenticazione di base HTTP, fare clic su Richiede l’autenticazione, aggiungere il nome utente Qualtrics e, invece della password, immettere il token API.
    
12. Assicurarsi che la codifica sia JSON.
    
13. Selezionare manualmente il contenuto da trasmettere o selezionare Avanzato per inserire un corpo JSON.
14. Salvare la regola.
15. In Qualtrics, termina il tuo flusso di lavoro. In questo esempio, probabilmente aggiungeremmo un Attività Directory XM.
    
16. Non dimenticare di pubblicare le modifiche al tuo sondaggio quando sei pronto per il lancio.

Esempio: Integrazione con ServiceNow

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

1. In Qualtrics, imposta il tuo evento su Evento JSON.
   
2. Copiare l’URL.
   
3. In una nuova scheda, accedere all’istanza sviluppatore ServiceNow.
4. Selezionare Messaggio REST.
   
5. Fare clic su Nuovo.
6. Nomina il tuo messaggio di riposo.
   
7. Nel campo Punto finale, incollare l’URL copiato nella fase 2.
8. Modificare il tipo di autenticazione in Basic.
9. Passare alla scheda Richiesta HTTP.
   
10. Fare doppio clic per aggiungere X-API-TOKEN.
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 Rest.
    
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 autenticazione su Eredita da elemento sovraordinato.
20. Fai clic su Invia.
21. Riaprire il metodo POST HTTP appena creato.
    
22. In fondo alla pagina, selezionare Anteprima utilizzo script.
    
23. Copiare il testo.
24. Cercare e selezionare Regole commerciali.
    
25. Selezionare Nuovo.
26. Selezionare una tabella.
    
27. Selezionare Avanzate.
28. Determinare quando viene eseguita la regola commerciale.
    Esempio: se è stato selezionato Incidente per la tabella e si intende inviare un questionario CSAT per i ticket risolti, è possibile aggiungere una condizione che indica che questa regola deve essere eseguita quando lo stato Incidente cambia in Risolto.
    Qtip: il supporto Qualtrics può aiutarti a configurare il tuo evento JSON e a collegarlo tramite ServiceNow. Tuttavia, potrebbero esserci alcune domande sulla funzionalità ServiceNow a cui non possono rispondere. Per domande su come/quando vengono eseguite le regole aziendali, consultare la documentazione ServiceNow sul funzionamento delle regole aziendali.
29. Passare alla scheda Avanzate.
    
30. Incolla il contenuto copiato dalla fase 22 dove dice Aggiungi qui il tuo codice.
    
31. Aggiungere un corpo. Qui comunichi le informazioni che vorresti trasferire a Qualtrics.
    

    Esempio: questo è un esempio del codice finale che si includerebbe in questo campo. La maggior parte di questo codice è il messaggio in uscita fornito da ServiceNow e varierà da esempio a esempio. Purtroppo, il supporto Qualtrics non può aiutarti con la programmazione personalizzata; se hai problemi con il tuo codice, contatta la community di ServiceNow per ricevere assistenza.

    La parte in grassetto del codice include tre funzioni aggiuntive non incluse nel codice originale: un corpo JSON che rileva l’ID utente e lo stato dell’incidente e una chiamata che recupera l’indirizzo di posta elettronica del cliente dell’incidente in modo che possa essere inviato al CSAT (in corsivo sotto). Consultare la documentazione di ServiceNow e consultare la comunità per ulteriori domande.

    (function executeRule(attuale, precedente /*null quando async*/) {
    
         // Aggiungi il tuo codice qui
        
      prova { 
         var r = new sn_ws.RESTMessageV2('Qualtrics JSON Event ', 'JSON Event POST');
         var body = {
              "ID utente": gs.getUserID()
              "stato incidente": current.state.getDisplayValue( 
         )
         
         var target = new GlideRecord('sys_user');
          target.addQuery('sys_id', '=', current.caller_id);
          target.query();
          mentre(target.next()) {
              body["email"] = target.email.getDisplayValue();
          }      
          var response = r.run();
          var responseBody = response.getBody();
          var httpStatus = response.getStatusCode();
          gs.addInfoMessage(httpStatus);
         }
     catch(ex) {
          var message = ex.message;
          gs.addInfoMessage("Error communication w Qualtrics " + message);
    
     }
    
     })(current, Previous);

32. Aggiungere il corpo alla richiesta. Aggiungere quanto segue sotto la parte in grassetto in corsivo del codice della fase precedente:

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

33. Fai clic su Invia.
34. In Qualtrics, termina il tuo flusso di lavoro. Per continuare l’esempio di sondaggio CSAT, probabilmente aggiungeremo un Attività Directory XM.
    
35. Non dimenticare di pubblicare le modifiche al tuo sondaggio quando sei pronto per il lancio.

Esempio: Integrazione con Microsoft Dynamics tramite Microsoft Flow

L’evento JSON lo rende così gli eventi in Microsoft Dynamics possono quindi attivare attività in Qualtrics, come la creazione di un ticket o la distribuzione di un sondaggio. Ad esempio, ogni volta che elimini un record dell’account in Microsoft, puoi distribuire un sondaggio Qualtrics al proprietario dell’account che pone domande in uscita. (Es., siamo spiacenti di vederti andare! Com’è stato il tuo tempo con noi? Come possiamo migliorare?)

Per integrare l’evento JSON con le azioni che si verificano in Microsoft Dynamics, è necessario eseguire la configurazione all’interno di Microsoft Flow invece che in Dynamics. Non preoccuparti: Microsoft Flow viene fornito gratuitamente con ogni account Microsoft Dynamics, in modo da poter accedere a Flow con le informazioni relative a Dynamics qui.

1. In Qualtrics, imposta il tuo evento su Evento JSON.
   
2. Copiare l’URL.
   
3. In una scheda separata, passare a https://us.flow.microsoft.com/en-us/ e utilizzare le informazioni di Microsoft Dynamics per accedere a Flusso.
4. Selezionare I miei flussi a sinistra.
   
5. Fare clic su Nuovo e selezionare Automatico – vuoto.
6. Assegnare un nome al flusso.
   
7. Seleziona un trigger. Questo è l’evento che si verifica in Microsoft che avvierà l’attività in Qualtrics. Puoi scegliere qualsiasi cosa serva ai tuoi scopi, ma per questo esempio sceglieremmo “Quando un record viene cancellato (Dynamics 365)”.
8. Fare clic su Crea.
9. In Nome organizzazione, accedere all’account Dynamics.
   
10. In Nome entità, selezionare il tipo di record o file. Nel nostro esempio, usiamo “Conti”.
11. Fare clic su Fase successiva e selezionare Aggiungi un’azione.
12. Selezionare HTTP.
    
13. Modificare il metodo in POST.
14. Incollare l’URL dell’evento JSON nel campo URI.
15. Utilizzare l’autenticazione token. In Intestazioni, inserire X-API-TOKEN e, nel campo accanto ad esso, incollare il token API.
16. In Corpo, è possibile inserire un corpo JSON. Questo ti aiuta a decidere quali informazioni vuoi trasmettere da Dynamics a Qualtrics.
    Qtip: utilizza il pulsante Aggiungi contenuto dinamico per selezionare i campi dei record Dynamics che desideri portare in Qualtrics. Assicurarsi di seguire il corretto formato JSON, come visualizzato nello screenshot. Per assistenza nella risoluzione dei problemi relativi ai contenuti dinamici, contattare il supporto Microsoft.
17. Al termine, fare clic su Salva.
18. In Qualtrics, termina il tuo flusso di lavoro. In questo esempio, probabilmente aggiungeremmo un Attività Directory XM.
    
19. Non dimenticare di pubblicare le modifiche al tuo sondaggio quando sei pronto per il lancio.

Esempio: Integrazione con Genesys PureCloud

Utilizzando gli eventi JSON, è possibile eseguire l’integrazione con Genesys PureCloud per inviare ai clienti un questionario di follow-up dopo aver completato un’interazione tramite telefono o chat di supporto.

1. Nel sondaggio che si desidera inviare, navigare fino a Workflow.
   
2. Creare un nuovo workflow basato su eventi.
3. Per l’evento workflow, selezionare l’evento JSON.
   
4. Fare clic su Copia URL per copiare l’endpoint dell’evento negli Appunti.
   
5. Senza chiudere la finestra Evento JSON, aprire un nuovo tab nel browser e navigare a Genesys.
6. Passare ad Amministrazione.
   
7. Fare clic su Azioni.
8. Fare clic su Aggiungi azione.
   
9. Selezionare Servizi Web Azioni dati come Nome integrazione.
   
   Qtip: se non si ha la possibilità di selezionare le azioni dati dei servizi Web, è necessario attivare l’integrazione. Consultare questa pagina per ulteriori informazioni.
10. Assegnare un Nome azione all’azione.
11. Fare clic su Aggiungi.
12. Navigare alla scheda Configurazione.
    
13. Passare al tab Contratti.
14. In Contratto di input, selezionare JSON.
15. Configura le proprietà inviate a Qualtrics.

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

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

16. Passare al tab Configurazione.
17. Modificare il tipo di richiesta in POST.
18. Nel campo Richiedi modello URL, incolla l’URL dall’evento JSON in Qualtrics.
19. Fare clic su Aggiungi intestazione.
    
20. Nella casella Chiave, inserire X-API-TOKEN.
21. Nella casella Valore, immettere il token dell’API Qualtrics.
22. Passare alla scheda Verifica.
23. Inserire i valori test per le proprietà.
24. Fare clic su Esegui azione.
25. Genesys vi dirà se l’azione è riuscita. Se l’errore non è riuscito, verrà visualizzata la risposta di errore per aiutare l’utente a risolvere il problema.
    
26. Torna al tuo evento JSON in Qualtrics e controlla che le tue proprietà siano state trasferite correttamente a Qualtrics.
27. Fai clic su Salva.
28. Fare clic sul segno più ( + ), quindi su Attività per configurare il task che si intende seguire quando viene attivato l’evento JSON. Nel nostro caso, vogliamo inviare un sondaggio ai partecipanti, quindi selezioniamo il task Directory XM.
    Qtip: quando imposti il tuo task, utilizza il menu del testo trasferito per utilizzare i valori passati da Genesys (ad esempio, e-mail cliente, nome, ecc.).
29. Dopo aver impostato l’attività in Qualtrics, torna su Genesys e fai clic su Salva & Pubblica.
    
30. Fare clic su Sì.
31. Passare ad Amministrazione.
32. Fare clic su Architetto.
33. Selezionare Invito al sondaggio nel menu a discesa del flusso.
34. Fare clic su Aggiungi.
35. Assegna un Nome, una Descrizione e una Divisione al tuo flusso.
36. Fare clic su Crea flusso.
37. Nella sezione Dati della casella degli strumenti, selezionare Chiama azione dati e trascinarla nella casella di riepilogo a discesa del flusso.
38. Assegnare un Nome all’azione.
39. Per la Categoria, selezionare Azione dati servizi Web.
40. Per Azione dati, selezionare l’azione dati creata in precedenza.
41. Accanto a ogni proprietà, fare clic sul menu di riepilogo a discesa e selezionare Espressione.
42. Per i valori delle proprietà, immettere i dati inviati per ogni proprietà. La casella completerà automaticamente i campi durante la digitazione.
    Qtip: questa pagina ha tutte le proprietà predefinite incluse nel flusso di invito al sondaggio. È anche possibile utilizzare espressioni complesse in situazioni in cui le informazioni di contatto del cliente sono mancanti o richiedono una formattazione aggiuntiva.
    Qtip: le informazioni di contatto sono precedute da Survey.CustomerContact.
43. Fare clic sulla casella più in basso del flusso.
44. Seleziona la casella degli strumenti, quindi Invita al sondaggio, quindi Interrompi sondaggio.
45. Selezionare optOut per la decisione d’impiego.
46. Fare clic su Pubblica. Genesys convaliderà il flusso e quindi lo pubblicherà. Una volta fatto questo, il flusso è attivo e inizierà a inviare sondaggi ai clienti al completamento delle interazioni con il supporto.

FAQ