Evento JSON

Sobre o Evento JSON

Você já quis que uma solicitação feita em seu site acionador um tíquete no Qualtrics? Você já quis criar uma integração perfeita entre o Qualtrics e seu próprio sistema interno? Você já quis acionador uma tarefa na guia Workflows, mas com um evento que acontece fora do Qualtrics?

Os eventos JSON permitem que softwares externos iniciem fluxos de trabalho por meio de solicitação HTTP. Em vez de esperar que um evento no Qualtrics acionador uma ação adicional na plataforma, você pode simplesmente configurar um evento JSON para receber solicitações de terceiros.

Limitações

O evento JSON não é compatível com as seguintes definições e configurações:

• Qualquer coisa que não seja HTTP (por exemplo, fila de mensagens, SMS).
• Chamadas HTTP de saída.
• Processar XML (o corpo da solicitação XML será ignorado).
• Processar qualquer coisa que não seja JSON.
• Autenticar de outra forma que não seja um cabeçalho X-API-TOKEN ou nossa autenticação básica de HTTP modificada.
  Qdica: O OAuth e outras formas de autenticação são incompatíveis com eventos JSON.
• Qualquer análise de JSON que não possa ser satisfeita com o uso de consultas JSONPath no corpo do JSON.
• Chamadas que excedem o limite de taxa de API de 3.000 por minuto.
• Cargas úteis superiores a 100 KB.

Tipos de autenticação suportados

Autenticação baseada em token / Autenticação de cabeçalho

Você pode se autenticar passando seu token de API pelo cabeçalho da solicitação como X-API-TOKEN.

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

 

surveyId": "SV_012345678912345",

  "format": "csv"

}'API

Autenticação básica de HTTP

A autenticação básica geralmente é uma versão codificada em Base64 de nome de usuário:senha. No entanto, para aumentar a segurança, a Qualtrics usa uma string codificada em Base64 de username:x-api-token.

Para usar o Basic Auth, você deve definir cabeçalhos na solicitação HTTP. O cabeçalho específico é Authorization.

 demo@qualtrics.com:f8gIK7G6GFH985Y4

 Básico ZGVtb0BxdWFsdHJpY3MuY29tOmY4Z0lLN0c2R0ZIOTg1WTQ=

Configuração de um Evento JSON

1. Primeiro, você precisará criar um fluxo de trabalho. Vá para a página de fluxos de trabalho autônomos.
   
   Qdica: você também pode usar eventos JSON no Guia Fluxos de trabalho em um projeto. Só recomendamos adicionar um fluxo de trabalho a um projeto específico se eles estiverem explicitamente relacionados. (Por exemplo, você está distribuindo esse projeto com o evento JSON)
2. Verifique se você está na guia Your workflows (Seus fluxos de trabalho ).
3. Clique em Criar um fluxo de trabalho.
4. Selecione Iniciado quando um evento for recebido.
5. Selecione o evento JSON .
   
6. Se desejar, especifique um resumo Acionador, que deve descrever a finalidade do evento JSON.
7. Você receberá um URL. Use isso para invocar seu novo fluxo de trabalho de fora do Qualtrics, usando o Postman, seu próprio sistema interno ou outros aplicativos semelhantes. Para copiá-lo, clique em Copiar URL.
8. Por padrão, os eventos JSON exigem autenticação. Se quiser permitir solicitações não autenticadas, você pode desativar a opção Require authentication by Qualtrics.
9. Agora, você pode definir os dados evento. Isso capturará os dados da solicitação de entrada. Para começar, clique em Configurações avançadas.
   
   Qdica: para obter informações sobre a seção Teste, consulte Captura de eventos abaixo.
10. Na caixa à esquerda, forneça o nome do campo JSON. Na caixa à direita, forneça o local nos dados evento (corpo da solicitação HTTP).
    Qdica: os locais devem estar no formato JSONPath! Consulte a tabela abaixo para obter um guia rápido da sintaxe JSONPath.
11. Para adicionar outro campo, clique em Add a JSON field (Adicionar um campo JSON).
12. Se quiser adicionar um parâmetro QUERY, adicione-o na seção Parâmetros QUERY . Para saber mais sobre o que são esses parâmetros e como eles funcionam na API, consulte nossa documentação API sobre parâmetros.
    Aviso: Não é aconselhável passar dados de identificação pessoal por meio de parâmetros QUERY. Todas as informações de identificação pessoal ou dados confidenciais devem ser transmitidos pelo corpo do POST sempre que possível, pois o POST é mais seguro. Entre contato suporte da Qualtrics se tiver dúvidas ou preocupações.
13. Para remover um campo, clique no sinal de menos ( – ).
14. Para salvar suas alterações, clique em Save (Salvar).
15. Agora você pode adicionar condições e uma tarefa ao seu fluxo de trabalho clicando no sinal de mais ( + ). As condições determinam quando um fluxo de trabalho é executado, enquanto as tarefas são o resultado do fluxo de trabalho. Veja o Visão geral dos fluxos de trabalho para mais informações
    

Capturando eventos

Quando estiver criando um evento API externo, talvez seja necessário analisar os dados do corpo do post. No entanto, às vezes pode ser difícil analisar esses dados. Se quiser descobrir o que sua API externa está enviando, siga estas etapas.

1. Clique em seu evento JSON.
   
2. Por padrão, a opção Capturar campos JSON dos resultados do teste para que possam ser usados como texto canalizado em outras tarefas desse fluxo de trabalho estará ativada. Essa opção faz com que os campos analisados no corpo da carga útil fiquem automaticamente disponíveis como texto transportado quando você adicionar suas tarefas fluxo de trabalho.
   
3. Clique em Executar um novo teste.
4. Você verá uma mensagem informando que o Qualtrics está aguardando para receber o evento do seu sistema externo. Acione sua API externa.
   Qdica: para cancelar esse teste, clique em Cancelar teste.
5. Se o teste for bem-sucedido, você verá a mensagem Successfully connected to the server (Conectado com sucesso ao servidor). A carga útil será analisada e adicionada à janela.
6. Se desejar, clique em Executar um novo teste para executar outro teste. Você precisará executar sua avançar chamada de API depois que essa opção for clicada.
7. Clique em Salvar.

Sintaxe de JSONPath

A tabela abaixo fornece alguns dos conceitos básicos da sintaxe JSONPath. Observe que eles não são estabelecidos pela Qualtrics, mas são padrões usados com JSON.

Exemplo de sintaxe JSONPath

Neste exemplo, mostraremos como, com um objeto JSON, a tabela JSONPath pode ser usada.

Esse é o nosso objeto JSON:

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

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

{ "price": "4", "description": "The Gob" }
},
{
"name": "Pizza Planet",
"total": 80000,
"topItem":

{ "price": "15", "description": "Pepperoni" }
}
]
}

Agora, devemos adicionar os valores de retorno que vemos na tabela JSONPath para deixar tudo mais claro.

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

{ "price": "50", "description": "Anvil" }
}
]
. -> Receita mensal
... -> 50

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

Macro desconhecida: { "name"}
]

**Altere o exemplo de [start:end:step] para "$.stores[1:3:1]"
[start:end:step] -> [
{
"name": "The Banana Stand",
"total": 250000,
"topItem":

{ "price": "4", "description": "The Gob" }
},
{
"name": "Pizza Planet",
"total": 80000,
"topItem":

{ "price": "15", "description": "Pepperoni" }
}
]

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

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

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

{ "price": "15", "description": "Pepperoni" }
}
]

Exemplo de API em Node Javascript

O exemplo abaixo é um modelo básico que você pode seguir ao formatar seus dados de Evento.

var request = require('request-promise');
var surveyId = "SV_XXXXXXXXXXXXXX";
var triggerId = "OC_XXXXXXXXXXX";
var brandId = "YOUR_BRAND_ID";
var userId = "UR_XXXXXXXXXXXXXXXXX";
var datacenter = "xx1";
var apiToken = "YOUR_QUALTRICS_API_TOKEN";

var url = "https://" + datacenter + ".qualtrics.evento" +
     "?contextId=" + surveyId + "&userId=" + userId + "&brandId=" + brandId + "&triggerId=" + triggerId;
var payload = {
    "text": "This is some text",
    "object": {
        "number": 4
    },
    "array": ["a", "b", "c", "d"]
};

var options = {
    url: url,
    json: true,
    body: payload,
    headers: {
        "Content-Type": "application/json", // OBRIGATÓRIO!!!
        "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);
});

Exemplo: Integração com o Freshdesk

O Evento JSON pode ser usado para integração com o Freshdesk como uma regra de webhook no Dispatch’r. Isso significa que os eventos no Freshdesk podem acionador tarefas no Qualtrics, como a criação de um tíquete ou a distribuição de uma pesquisa.

1. No Qualtrics, defina seu Evento como JSON Evento.
   
2. Copie o URL.
   
3. Em uma nova guia, faça login no Freshdesk.
4. Na seção Admin, navegue até a opção que melhor se adapta ao tipo de regra que você deseja definir.
   
   Qdica: saiba a diferença entre Dispatch’r, Supervisor e Observerna documentação de suporte do Freshdesk.
5. Criar uma nova regra.
   
6. Defina condições para determinar qual evento do Freshdesk deve acionador uma tarefa no Qualtrics.
   
   Exemplo: Talvez quando um agente do Freshdesk faz com que o status do tíquete seja alterado de qualquer status para Resolvido, você gostaria de enviar uma pesquisa CSAT usando o Qualtrics.
7. Adicione uma nova ação e selecione Acionador Web Hook.
   
8. Defina o tipo de solicitação como POST.
   
9. Em URL de retorno de chamada, cole o URL Evento JSON da Etapa 2.
10. Para usar a autenticação de token, adicione cabeçalhos personalizados, insira X-API-TOKEN: e defina-o como igual ao seu token de API.
    
11. Para usar a autenticação HTTP Basic, clique em Requires Authentication (Requer autenticação), adicione seu nome de usuário Qualtrics e, em vez de sua senha, insira seu token de API.
    
12. Certifique-se de que a codificação seja JSON.
    
13. Selecione manualmente o conteúdo a ser transmitido ou escolha Advanced para inserir um corpo JSON.
14. Salve sua regra.
15. No Qualtrics, conclua seu fluxo de trabalho. Neste exemplo, provavelmente adicionaríamos um TarefaDiretório XM .
    
16. Não se esqueça de publicar as alterações pesquisa quando estiver pronto para o lançamento.

Exemplo: Integração com o ServiceNow

O Evento JSON pode ser usado para integração com o ServiceNow. Isso significa que os eventos no ServiceNow podem acionador tarefas no Qualtrics, como a criação de um tíquete ou a distribuição de uma pesquisa.

1. No Qualtrics, defina seu Evento como JSON Evento.
   
2. Copie o URL.
   
3. Em uma nova guia, faça login na sua instância de desenvolvedor do ServiceNow.
4. Selecione Mensagem REST.
   
5. Clique em New.
6. Dê um nome à sua mensagem de descanso.
   
7. No campo Endpoint, cole o URL que você copiou na Etapa 2.
8. Altere o tipo de autenticação para Básico.
9. Vá para a guia HTTP Request (Solicitação HTTP ).
   
10. Clique duas vezes para adicionar o X-API-TOKEN.
11. Clique duas vezes para colar seu token de API.
    
12. Em uma nova linha, adicione o nome Content-type.
13. Defina o valor como application/json.
14. Clique em Enviar.
    
15. Reabra sua mensagem de descanso.
    
16. Em Métodos HTTP, clique em Novo.
    
17. Dê um nome ao método.
    
18. Defina o método HTTP como POST.
19. Defina o tipo de autenticação como Inherit from parent (Herdar do pai).
20. Clique em Enviar.
21. Reabra o método HTTP POST que você acabou de criar.
    
22. Na parte inferior da página, selecione Preview Script Usage (Visualizar uso do script).
    
23. Copie o texto.
24. Pesquise e selecione Business Rules.
    
25. Selecione Novo.
26. Selecione uma tabela.
    
27. Selecione Advanced (Avançado).
28. Determinar quando a regra de negócios é executada.
    Exemplo: Se você selecionou Incidente para sua tabela e deseja enviar uma pesquisa CSAT para tickets resolvidos, pode adicionar uma condição informando que essa regra deve ser executada quando o estado do Incidente for alterado para Resolvido.
    Qdica: suporte da Qualtrics pode ajudá-lo a configurar seu Evento JSON e conectá-lo por meio do ServiceNow. No entanto, pode haver algumas perguntas sobre a funcionalidade do ServiceNow que eles não podem responder. Se você tiver dúvidas sobre como e quando as regras de negócios são executadas, consulte a documentação da ServiceNow sobre como as regras de negócios funcionam.
29. Vá para a guia Advanced (Avançado ).
    
30. Cole o conteúdo que você copiou da Etapa 22, onde está escrito Add your code here (Adicione seu código aqui).
    
31. Adicione um corpo. É aqui que você comunica as informações que gostaria de passar para o Qualtrics.
    

    Exemplo: Este é um exemplo do código final que você incluiria nesse campo. A maior parte desse código é a mensagem de saída fornecida pelo ServiceNow e variará de um exemplo para outro. Infelizmente, suporte da Qualtrics não pode ajudá-lo com qualquer codificação personalizada; se você tiver problemas com seu código, entre em contato com a comunidade da ServiceNow para obter assistência.

    A parte em negrito do código inclui três funções adicionais não incluídas no código original: um corpo JSON que extrai o ID do usuário e o estado do incidente e uma chamada que recupera o endereço de e-mail do cliente do incidente para que ele possa receber o CSAT (em itálico abaixo). Consulte a documentação da ServiceNow e consulte a comunidade se tiver outras dúvidas.

    (function executeRule(current, previous /*null when async*/) {
    
        // Adicione seu código aqui
        
     try { 
         var r = new sn_ws.RESTMessageV2('Qualtrics JSON Evento ', 'JSON Evento POST')
         ;var body = {
             "User ID": gs.getUserID()
             "incident state": current.state.getDisplayValue()
          }
         ;
         
         var destino = new GlideRecord('sys_user');
         destino.addQuery('sys_id', '=', current.caller_id);
         destino.query(); 
         while(destino avançar()) { 
             body["email"] = destino.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 Qualtrics " + message);
    
    }
    
    })(current, previous);

32. Adicione o corpo à solicitação. Adicione o seguinte abaixo da parte em negrito e em itálico do código da etapa anterior:

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

33. Clique em Enviar.
34. No Qualtrics, conclua seu fluxo de trabalho. Para continuar com o exemplo da pesquisa CSAT, provavelmente adicionaríamos um TarefaDiretório XM .
    
35. Não se esqueça de publicar as alterações pesquisa quando estiver pronto para lançá-lo.

Exemplo: Integração com o Microsoft Dynamics por meio do Microsoft Flow

O Evento JSON faz com que os eventos no Microsoft Dynamics possam acionador tarefas no Qualtrics, como a criação de um tíquete ou a distribuição de uma pesquisa. Por exemplo, sempre que você excluir um registro conta na Microsoft, poderá distribuir uma pesquisa Qualtrics ao proprietário conta com perguntas de saída. (por exemplo, Lamentamos sua saída! Como foi seu tempo conosco? Como podemos melhorar?)

Para integrar o Evento JSON com ações que ocorrem no Microsoft Dynamics, você precisa fazer a configuração no Microsoft Flow em vez de no Dynamics. Não se preocupe – o Microsoft Flow é fornecido gratuitamente com todas as conta do Microsoft Dynamics, portanto, você pode fazer login no Flow com suas informações do Dynamics aqui.

1. No Qualtrics, defina seu Evento como JSON Evento.
   
2. Copie o URL.
   
3. Em uma guia separada, acesse https://us.flow.microsoft.com/en-us/ e use suas informações do Microsoft Dynamics para fazer login no Flow.
4. Selecione My Flows (Meus fluxos ) à esquerda.
   
5. Clique em New e selecione Automated – from blank.
6. Dê um nome ao fluxo.
   
7. Selecione um acionador. Esse é o evento que acontece na Microsoft e que iniciará a tarefa no Qualtrics. Você pode escolher o que for mais adequado aos seus objetivos, mas, neste exemplo, escolheríamos “When a record is deleted (Dynamics 365)”
8. Clique em Create.
9. Em Organização Name (Nome da organização), faça login em sua conta do Dynamics.
   
10. Em Nome da entidade, escolha o tipo de registro ou arquivo. Em nosso exemplo, usaríamos “Accounts” (Contas)
11. Clique em Avançar Step (Próxima etapa) e selecione Add an Action (Adicionar uma ação).
12. Selecione HTTP.
    
13. Altere o método para POST.
14. Cole o URL Evento JSON no campo URI.
15. Use a autenticação por token. Em Headers (Cabeçalhos), digite X-API-TOKEN e, no campo avançar, cole seu token de API.
16. Em Body (Corpo), você pode inserir um corpo JSON. Isso ajuda você a decidir as informações que deseja passar do Dynamics para o Qualtrics.
    Qdica: Use o botão Add dynamic content (Adicionar conteúdo dinâmico ) para selecionar os campos de registro do Dynamics que você gostaria de trazer para o Qualtrics. Certifique-se de seguir o formato JSON adequado, conforme exibido na captura de tela. Para obter ajuda na solução de problemas de conteúdo dinâmico, entre em contato com o Suporte da Microsoft.
17. Quando terminar, clique em Salvar.
18. No Qualtrics, conclua seu fluxo de trabalho. Neste exemplo, provavelmente adicionaríamos um TarefaDiretório XM .
    
19. Não se esqueça de publicar as alterações pesquisa quando estiver pronto para lançá-lo.

Exemplo: Integração com o Genesys PureCloud

Usando eventos JSON, você pode integrar-se ao Genesys PureCloud para enviar aos clientes uma pesquisa de acompanhamento após a conclusão de uma interação de suporte por telefone ou chat.

1. Na pesquisa que você deseja enviar, navegue até Fluxos de trabalho.
   
2. Criar um novo fluxo de trabalho baseado em eventos.
3. Para o evento fluxo de trabalho, selecione o evento JSON .
   
4. Clique em Copiar URL para copiar o endpoint evento para a área de transferência.
   
5. Sem fechar a janela do Evento JSON, abra uma nova guia em seu navegador e navegue até o Genesys.
6. Navegue até Admin.
   
7. Clique em Ações.
8. Clique em Add Action.
   
9. Selecione Web Services Data Actions como o nome da integração.
   
   Qdica: se você não tiver a opção de selecionar as ações de dados dos serviços da Web, precisará ativar a integração. Consulte esta página para obter mais informações.
10. Dê à sua ação um nome deação.
11. Clique em Adicionar.
12. Navegue até a guia Setup (Configuração ).
    
13. Vá para a guia Contratos.
14. Em Input Contract (Contrato de entrada), selecione JSON.
15. Configure as propriedades que são enviadas para o Qualtrics.

    Exemplo: Por exemplo, o código abaixo passará o endereço de e-mail, o número de telefone, o nome e o sobrenome.

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

16. Vá para a guia Configuration (Configuração ).
17. Altere o tipo de solicitação para POST.
18. No campo Request URL Template (Modelo de URL de solicitação ), cole o URL do Evento JSON no Qualtrics.
19. Clique em Add Header (Adicionar cabeçalho).
    
20. Na caixa Chave , digite X-API-TOKEN.
21. Na caixa Value (Valor ), insira seu token de API do Qualtrics.
22. Vá para a guia Teste.
23. Insira valores de teste para suas propriedades.
24. Clique em Run Action (Executar ação).
25. O Genesys lhe dirá se a ação foi bem-sucedida. Se houver falha, a resposta de erro será exibida para ajudá-lo a corrigir o problema.
    
26. Retorne ao seu Evento JSON no Qualtrics e verifique se suas propriedades foram passadas para o Qualtrics com sucesso.
27. Clique em Salvar.
28. Clique no sinal de mais ( + ) e depois em Tarefa ) para configurar a tarefa que você deseja seguir quando o evento JSON for acionado. Em nosso caso, queremos enviar uma pesquisa para os entrevistados, portanto, selecionamos a Diretório XM Tarefa.
    Qdica: Ao configurar sua tarefa, use o menu texto transportado para usar valores passados do Genesys (por exemplo, e-mail do cliente, nome, etc.).
29. Depois de configurar a tarefa no Qualtrics, retorne ao Genesys e clique em Save & Publicar (Salvar e publicar ).
    
30. Clique em Yes.
31. Navegue até Admin.
32. Clique em Architect.
33. Selecione Pesquisa Invite (Convite para pesquisa ) no menu suspenso do fluxo.
34. Clique em Adicionar.
35. Dê ao seu fluxo um nome, uma descrição e uma Divisão.
36. Clique em Criar fluxo.
37. Na seção Data (Dados) da Toolbox (Caixa de ferramentas), selecione Call Data Action (Chamar ação de dados ) e arraste-a para a caixa suspensa no fluxo.
38. Dê um nome à sua ação.
39. Para a categoria, selecione Web Services Data Action.
40. Em Data Action (Ação de dados), selecione a ação de dados que você criou anteriormente.
41. Avançar de cada propriedade, clique no menu suspenso e selecione Expression (Expressão).
42. Para os valores de propriedade, insira os dados que estão sendo enviados para cada propriedade. A caixa preencherá automaticamente seus campos à medida que você digitar.
    Qdica: Esta página tem todas as propriedades padrão incluídas no fluxo convite para pesquisa. Também é possível usar expressões complexas em situações em que as informações contato do cliente estão ausentes ou exigem formatação adicional.
    Qdica: as informações Contato são precedidas de Pesquisa.CustomerContact.
43. Clique na caixa mais abaixo em seu fluxo.
44. Selecione Toolbox, Pesquisa Invites e Abort Pesquisa.
45. Selecione optOut para a Disposição.
46. Clique em Publicar. O Genesys validará o fluxo e depois o publicar. Quando isso for feito, o fluxo estará em vigor e começará a enviar pesquisas aos clientes quando eles concluírem as interações de suporte.

Perguntas frequentes