Tarefa do código

Sobre tarefas de código

A tarefa de código permite que você use JavaScript personalizado para executar manipulação de dados, formatação e operações de cálculo antes ou depois de outras tarefas em um fluxo de trabalho. Por exemplo, você pode usar a tarefa de código para transformar a saída de retorno de uma chamada de API em um resultado mais fácil de usar (digamos, você precisava comunicar o resultado ao seu gerente não técnico). Em seguida, você pode transportar o resultado transformado em uma tarefa de e-mail que envia um e-mail ao seu gerente.

Configuração de tarefas de código

1. Navegar para o Página Fluxos de Trabalho independentes ou o Guia Fluxos de trabalho de uma pesquisa.
   
2. Clique em Criar um fluxo de trabalho.
3. Selecione Iniciado quando um evento é recebido.
4. Dê um nome ao seu fluxo de trabalho.
   
5. Clique em Escolher evento e selecione o evento que inicia o fluxo de trabalho. Normalmente, este é um evento de resposta de pesquisa.
6. Se desejar, clique no sinal de mais ( + ) e selecione Condições para adicionar condições ao seu workflow. As condições ajudam a determinar quando um fluxo de trabalho é disparado. Consulte a página vinculada para obter mais informações sobre a criação de condições.
   
7. Clique no sinal de mais ( +) e selecione Tarefa.
   
8. Selecione a tarefa Código.
   
9. Insira sua expressão JavaScript na caixa. Consulte a seção sobre práticas recomendadas para obter informações úteis ao escrever seu código.
   
   Qdica: O editor de código mantém um histórico de edições para que você possa desfazer as alterações de código pressionando CTRL + Z (PC) ou CMD + Z (Mac). Use SHIFT + CTRL + Y (PC) ou SHIFT + CMD + Y (Mac) para refazer uma alteração.
   Qdica: Ao escrever seu código, você poderá ver erros na janela. Estes erros são a verificação de erros de sintaxe, não erros de execução. Os erros de sintaxe sempre aparecerão em inglês, independentemente da configuração de idioma da sua conta. A execução não ocorre até a tarefa ser gravada e o workflow ser acionado.
   
10. Se desejado, insira um resumo da tarefa que explique o que o código JavaScript deve realizar.
11. Clique em Testar código para executar o código em seu browser local.
    Qdica: Como elas ocorrem em um ambiente diferente, testar o código pode não dar o mesmo resultado que executá-lo no fluxo de trabalho.
12. Use o menu {a} Adicionar texto transportado para adicionar texto transportado à sua expressão JavaScript. O texto transportado é útil para extrair valores do seu evento, como extrair as respostas da pesquisa do respondente. O texto transportado é avaliado antes da execução da sua expressão JavaScript.
13. Se você precisar limpar seu código e começar de novo, clique em Redefinir como padrão.
14. Quando terminar, clique em Salvar.
15. A tarefa de código geralmente é emparelhada com outra tarefa para usar a saída da tarefa de código. Clique no sinal de mais ( + ), selecione Tarefa e escolha sua próxima tarefa. Consulte esta página para obter uma visão geral das tarefas.
    
    Qdica: Ao configurar suas tarefas subsequentes, a saída da tarefa de código estará disponível no menu de texto transportado da tarefa.
    

Limites de execução JavaScript

Ao escrever seu código JavaScript para incluir na tarefa de código, tenha em atenção os seguintes limites de execução:

• Tempo máximo de execução: 10 segundos
• Comprimento máximo de JavaScript: 6KB
• Nenhuma solicitação de API de saída: por motivos de segurança, a tarefa de código não pode fazer solicitações de saída para outras APIs ou serviços, nem pode recuperar outras bibliotecas JavaScript no tempo de execução usando solicitações HTTP.

Se seu código JavaScript exceder esses limites, a tarefa de código falhará. Se o fluxo de trabalho falhar, vá para Relatórios de fluxos de trabalho para obter mais informações sobre o motivo da falha no fluxo de trabalho.

Práticas Recomendadas

Ao escrever seu JavaScript, siga as melhores práticas abaixo:

• • Seu código deve estar em conformidade com a sintaxe ES6.
  • Seu código será executado via Node.js em um ambiente protegido. A tarefa utiliza atualmente a versão 8.10 do Node.js.
  • Seu código deve retornar seu resultado como um objeto JavaScript. Quando o resultado de retorno é formatado dessa forma, o sistema pode inferir automaticamente quais campos seu código personalizado retornará e fornecer o texto transportado apropriado para as tarefas subsequentes.

    Exemplo: neste exemplo, retornamos vários resultados:

    function codeTask() {
      return {
        hello: "world",
        foo: "bar",
        status: 200
      };
     }

    Exemplo: neste exemplo, retornamos um único resultado:

    função codeTask() {
      return {
        result: "hello world",
      };
     }

  • Dependendo do tipo de informação que você espera, pode precisar encapsular a sintaxe do localizador entre aspas. Você precisará adicionar aspas se quiser que seu localizador se resolva em uma string. Você não precisa adicionar cotações se elas forem resolvidas a um objeto.

    Exemplo: por exemplo, o código como o abaixo precisaria de cotações:

    function codeTask() {
        let ticketId = "~{ch://OCAC_31HNMUuEpm3Jg/exports.data.key}";
        ...
     }

  • Ao usar texto transportado para campos que podem conter aspas, você deve usar literais de modelo (`) em vez de aspas ao redor do texto transportado.

Exemplo: usar uma tarefa de código com uma tarefa de serviço web

Este exemplo percorre o uso de uma tarefa de código com uma tarefa de serviço da Web. Você pode usar uma tarefa de código com uma tarefa de serviço da Web para transformar a resposta da pesquisa de um entrevistado em um código amigável à API e, em seguida, usar os valores retornados para executar uma chamada de API. Em seguida, você pode pegar os resultados da chamada da API e usar outra tarefa de código para transformar os valores retornados em uma resposta amigável.

Neste exemplo, estamos criando um localizador de restaurantes na Qualtrics. Vamos nos aprofundar um pouco mais adiante, mas abaixo temos uma visão geral de como realizaremos isso.

1. Em nossa pesquisa, perguntaremos aos entrevistados onde eles querem comer e como eles querem retornar resultados.
2. Para fazer nossa pesquisa de restaurantes, usaremos um aplicativo de localizador de restaurantes de terceiros. Usamos uma tarefa de código para transformar as respostas do respondente da pesquisa em um formulário que a API de localizador de restaurantes de terceiros pode usar.
3. Em seguida, usamos uma tarefa de serviço da Web para executar uma chamada de API para o localizador de restaurantes de terceiros, que retorna nossos resultados como JSON.
4. Utilizamos outra tarefa de código para transformar o JSON resultante em uma forma que os humanos podem ler.
5. Podemos usar uma última tarefa para depois enviar essas informações aos entrevistados ou a nós mesmos. Por exemplo, use uma tarefa de e-mail para enviar um e-mail ao participante com os resultados retornados.

Criação de um localizador de restaurantes com tarefas de código

1. Em sua pesquisa, crie as perguntas que alimentarão a tarefa de código. No nosso caso, é uma pergunta de entrada de texto perguntando onde procurar restaurantes e uma pergunta de múltipla escolha perguntando como ordenar os resultados.
   
2. Navegue para Workflows.
3. Criar um novo workflow.
4. Para o evento workflow, selecione o Resposta à pesquisa evento e configure o evento para acionar quando uma nova resposta é criada. Consulte a página vinculada para obter mais informações.
   
5. Clique no sinal de mais ( + ) e selecione Tarefa.
6. Selecione a tarefa Código.
   
7. Para o código, estamos transformando as respostas do respondente nos valores necessários para a API do localizador de restaurantes.
   
8. Usamos texto transportado para inserir a pergunta na qual as respostas dos entrevistados são originadas.
9. Clique em Salvar para salvar a tarefa.
10. Clique no sinal de mais ( + ) e selecione  Tarefa.
    
11. Selecione a tarefa Serviço web e escolha sua autenticação. Consulte esta página para obter mais informações.
    
12. Insira o URL que você está tentando alcançar.
    
13. Anexe seus parâmetros usando cadeias de consulta. Use o menu de texto transportado, {a}, para usar valores da sua pesquisa e da tarefa de código anterior.

    Exemplo: nosso URL totalmente criado é

    https://api.example.com/v3/businesses/search?sort_by=~{ch://OCAC_Zt2TNQYggAb6u89/sort_by}&location=${q://QID1/ChoiceTextEntryValue}

    Isso contém dois parâmetros: sort_by e localização. Para sort_by, o valor é o resultado de nossa primeira tarefa de código. Para local, o valor é a resposta do participante à pergunta de entrada de texto.

14. Conclua a configuração da tarefa conforme necessário. Consulte Tarefas de serviço da Web se precisar de ajuda.
    Qdica: Na tarefa do serviço Web, você pode testar seus valores esperados retornados para garantir que a chamada da API funcione.
    
15. Se necessário, crie caminhos JSON personalizados que possam ser utilizados em outras tarefas. Em nosso exemplo, criamos um caminho de “negócios” que retorna uma série de empresas a partir de nossos resultados de pesquisa.
    
    Qdica: Se você testou sua tarefa de serviço web, a Qualtrics identificará automaticamente os caminhos JSON e os adicionará aqui. Você pode excluir os desnecessários clicando no ícone da lixeira.
16. Clique em Salvar.
17. Clique no sinal de mais ( + ) e selecione Tarefa.
    
18. Selecione a tarefa Código.
    
19. Agora, precisamos transformar o JSON resultante da tarefa de Web Service em um formulário legível. No nosso caso, estamos transformando-o em HTML para utilização em um e-mail.
    
20. Para recuperar o JSON resultante da tarefa de serviço da Web, use o menu de texto transportado {a}.
21. Clique em Salvar.
    Qdica: Se estiver usando texto transportado, você poderá receber um aviso porque o designador de texto transportado não é um JavaScript válido. No entanto, isso será resolvido antes da execução, pois o designador de texto transportado será substituído pelo valor do campo antes da execução do código.
22. Clique no sinal de mais ( + ) e selecione Tarefa.
23. Selecione E-mail.
    
24. Configure sua tarefa de e-mail. Consulte a página vinculada para obter mais informações.
25. Transfira o resultado de sua segunda tarefa de código para o corpo do e-mail. É o que retorna os resultados da pesquisa de restaurante.
    
    Exemplo: abaixo está a aparência do editor de e-mail com as respostas do respondente transportadas, juntamente com o resultado da segunda tarefa de código.
    
26. O e-mail resultante retorna os resultados da pesquisa selecionados do seu respondente!
    

Perguntas frequentes