Tarea de códigos

Acerca de las tareas de código

La tarea de código le permite utilizar JavaScript personalizado para realizar operaciones de tratamiento, formato y cálculo de datos antes o después de otras tareas en un workflow. Por ejemplo, puede utilizar la tarea de código para transformar la salida de devolución de una llamada API en un resultado más fácil de usar (por ejemplo, tenía que comunicar el resultado a su gestor no técnico). A continuación, puede dinamizar el resultado transformado en una tarea de correo electrónico que envía un correo electrónico a su gerente.

Configuración de tareas de código

1. Navegar a la página Flujos de trabajo independientes o el Pestaña Flujos de trabajo de una encuesta.
   
2. Haga clic en Crear un flujo de trabajo.
3. Seleccione Iniciado cuando se recibe un evento.
4. Asigne un nombre a su workflow.
   
5. Haga clic en Elegir evento y seleccione el evento que inicia el flujo de trabajo. Normalmente, se trata de un evento de respuesta de encuesta.
6. Si lo desea, haga clic en el signo más ( + ) y seleccione Condiciones para agregar condiciones al flujo de trabajo. Las condiciones ayudan a determinar cuándo se desencadena un flujo de trabajo. Consulte la página enlazada para obtener más información sobre las condiciones de creación.
   
7. Haga clic en el signo más (+) y seleccione Tarea.
   
8. Seleccione la tarea Código.
   
9. Introduzca la expresión JavaScript en el cuadro. Consulte la sección sobre mejores prácticas para obtener información útil al escribir el código.
   
   Consejo Q: El editor de código mantiene un historial de ediciones para que pueda deshacer los cambios de código pulsando CTRL + Z (PC) o CMD + Z (Mac). Utilice MAYÚS + CTRL + Y (PC) o MAYÚS + CMD + Y (Mac) para rehacer un cambio.
   Consejo Q: A medida que escribe el código, es posible que vea errores en la ventana. Estos errores son la verificación de errores de sintaxis, no errores de ejecución. Los errores de sintaxis siempre aparecerán en inglés, independientemente de la configuración de idioma de su cuenta. La ejecución no tiene lugar hasta que se guarda la tarea y se desencadena el workflow.
   
10. Si lo desea, introduzca un resumen de la tarea que explique lo que debe lograr el código JavaScript.
11. Haga clic en Código de prueba para ejecutar el código en su navegador local.
    Consejo Q: Dado que se llevan a cabo en diferentes entornos, es posible que las pruebas del código no den exactamente el mismo resultado que ejecutarlo en el flujo de trabajo.
12. Utilice el menú {a} Agregar texto dinámico para agregar texto dinámico a su expresión JavaScript. El texto dinámico es útil para extraer valores de su evento, como extraer las respuestas de la encuesta del encuestado. El texto dinámico se evalúa antes de que se ejecute la expresión JavaScript.
13. Si necesita borrar el código y volver a empezar, haga clic en Restablecer a los valores predeterminados.
14. Cuando termine, haga clic en Guardar.
15. La tarea de código a menudo se empareja con otra tarea para utilizar la salida de la tarea de código. Haga clic en el signo más ( + ), seleccione Tarea y elija su siguiente tarea. Consulte esta página para obtener un resumen de las tareas.
    
    Consejo Q: Al configurar las tareas posteriores, el resultado de la tarea de código estará disponible en el menú de texto dinámico de la tarea.
    

Límites de ejecución de JavaScript

Al escribir el código JavaScript para incluirlo en la tarea de código, tenga en cuenta los siguientes límites de ejecución:

• Tiempo de ejecución máximo: 10 segundos
• Longitud máxima de JavaScript: 6 KB
• Sin solicitudes de API de salida: por razones de seguridad, la tarea de código no puede realizar solicitudes de salida a otras API o servicios, ni puede recuperar otras bibliotecas JavaScript en tiempo de ejecución mediante solicitudes HTTP.

Si su código JavaScript supera estos límites, la tarea de código fallará. Si su flujo de trabajo falla, diríjase a Generación de informes de flujos de trabajo para obtener más información sobre por qué falló su flujo de trabajo.

Mejores prácticas

Al escribir su JavaScript, siga las siguientes mejores prácticas:

• • Su código debe ajustarse a la sintaxis ES6.
  • Su código se ejecutará a través de Node.js en un entorno protegido. La tarea actualmente utiliza Node.js versión 8.10.
  • Su código debe devolver el resultado como un objeto JavaScript. Cuando el resultado de la devolución se formatea de esta manera, el sistema puede inferir automáticamente qué campos devolverá su código personalizado y proporcionar el texto dinámico adecuado para las tareas posteriores.

    Ejemplo: En este ejemplo, devolvemos varios resultados:

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

    Ejemplo: En este ejemplo, devolvemos un único resultado:

    function codeTask() {
      return {
        result: "hello world",
      };
     }

  • En función del tipo de información que espere, es posible que deba encapsular la sintaxis del localizador entre comillas. Deberá añadir comillas si desea que el localizador las resuelva en una cadena. No necesita añadir ofertas si se resuelve en un objeto.

    Ejemplo: Por ejemplo, código como el siguiente necesitaría comillas:

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

  • Al utilizar texto dinámico para campos que pueden contener comillas, debe utilizar literales de plantilla (`) en lugar de comillas alrededor del texto dinámico.

Ejemplo: Uso de una tarea de código con una tarea de servicio web

En este ejemplo se explica cómo utilizar una tarea de código con una tarea de servicio web. Puede utilizar una tarea de código con una tarea de servicio web para transformar la respuesta de una encuesta del encuestado en un código compatible con la API y, a continuación, utilizar los valores devueltos para realizar una llamada a la API. A continuación, puede tomar los resultados de la llamada API y utilizar otra tarea de código para transformar los valores devueltos en una respuesta humana.

En este ejemplo, estamos construyendo un buscador de restaurantes en Qualtrics. Analizaremos los detalles un poco más tarde, pero a continuación incluimos una visión general de cómo lograrlo.

1. En nuestra encuesta, preguntaremos a los encuestados dónde quieren comer y cómo desean devolver los resultados.
2. Para realizar la búsqueda en nuestro restaurante, utilizaremos una aplicación de buscador de restaurantes de terceros. Utilizamos una tarea de código para transformar las respuestas de los encuestados en un formulario que la API del buscador de restaurantes de terceros puede utilizar.
3. A continuación, utilizamos una tarea de servicio web para realizar una llamada API al buscador de restaurantes de terceros, que devuelve nuestros resultados como JSON.
4. Utilizamos otra tarea de código para transformar el JSON resultante en una forma que los humanos puedan leer.
5. Podemos utilizar una última tarea para enviar esta información a los encuestados o a nosotros mismos. Por ejemplo, utilice una tarea de correo electrónico para enviar un correo electrónico al encuestado con los resultados devueltos.

Crear un buscador de restaurantes con tareas de código

1. En su encuesta, cree las preguntas que se introducirán en la tarea de código. En nuestro caso, se trata de una pregunta con entrada de texto sobre dónde buscar restaurantes y una pregunta de opción múltiple sobre cómo ordenar los resultados.
   
2. Navegue a Flujos de trabajo.
3. Cree un nuevo workflow.
4. Para el evento de workflow, seleccione el campo Respuesta de encuesta y configure el evento para que se desencadene cuando se cree una nueva respuesta. Consulte la página del enlace para obtener más información.
   
5. Haga clic en el signo más ( + ) y seleccione Tarea.
6. Seleccione la tarea Código.
   
7. Para el código, estamos transformando las respuestas de los encuestados en los valores necesarios para la API del buscador de restaurantes.
   
8. Utilizamos texto dinámico para introducir la pregunta en la que se originan las respuestas de los encuestados.
9. Haga clic en Guardar para guardar la tarea.
10. Haga clic en el signo más ( + ) y seleccione  Tarea.
    
11. Seleccione la tarea de servicio web y elija su autenticación. Consulte esta página para obtener más información.
    
12. Introduzca la URL a la que está intentando acceder.
    
13. Añada sus parámetros utilizando cadenas de consulta. Utilice el menú de texto dinámico, {a}, para utilizar valores de su encuesta y de una tarea de código anterior.

    Ejemplo: nuestra URL totalmente construida es

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

    Contiene dos parámetros: sort_by y location. Para sort_by, el valor es el resultado de nuestra primera tarea de código. Para la ubicación, el valor es la respuesta del encuestado a la pregunta de entrada de texto.

14. Finalice la configuración de la tarea según sea necesario. Consulte las tareas de servicio web si necesita ayuda.
    Consejo Q: En la tarea de servicio web, puede probar los valores devueltos esperados para asegurarse de que la llamada a la API funciona.
    
15. Si es necesario, cree vías de acceso JSON personalizadas que se puedan utilizar en otras tareas. En nuestro ejemplo, creamos una vía de acceso de “empresas” que devuelve una serie de empresas a partir de nuestros resultados de búsqueda.
    
    Consejo Q: Si probó su tarea de servicio web, Qualtrics identificará automáticamente las rutas JSON y las agregará aquí. No dude en eliminar los innecesarios haciendo clic en el icono de la papelera.
16. Haga clic en Guardar.
17. Haga clic en el signo más ( + ) y seleccione Tarea.
    
18. Seleccione la tarea Código.
    
19. Ahora, debemos transformar el JSON resultante de la tarea de servicio web en un formulario legible. En nuestro caso, lo estamos transformando en HTML para usarlo en un correo electrónico.
    
20. Para recuperar el JSON resultante de la tarea de servicio web, utilice el menú de texto dinámico, {a}.
21. Haga clic en Guardar.
    Consejo Q: Si utiliza texto dinámico, es posible que reciba una advertencia ya que el designador de texto dinámico no es un JavaScript válido. Sin embargo, esto se resolverá antes de la ejecución, ya que el designador de texto dinámico se reemplazará con el valor del campo antes de que se ejecute el código.
22. Haga clic en el signo más ( + ) y seleccione Tarea.
23. Seleccione Correo electrónico.
    
24. Configure su tarea de correo electrónico. Consulte la página del enlace para obtener más información.
25. Dinamice el resultado de la segunda tarea de código en el cuerpo del correo electrónico. Esto es lo que devuelve los resultados de la búsqueda del restaurante.
    
    Ejemplo: a continuación se muestra cómo se ve el editor de correo electrónico con las respuestas del encuestado dinámicas, junto con el resultado de la segunda tarea de código.
    
26. El correo electrónico resultante devuelve los resultados de búsqueda seleccionados por el encuestado.
    

Preguntas frecuentes