Jira Issue Handler

El Jira Issue Handler te permite interactuar directamente con tu instancia de Jira Cloud dentro de los flujos de trabajo de Nappai. Con él puedes crear nuevas incidencias, actualizar las existentes, añadir subtareas, actualizar subtareas y eliminar incidencias o subtareas, todo desde el mismo panel de control.

¿Cómo funciona?

El componente se conecta a la API de Jira Cloud usando una credencial de tipo Jira API que ya debe estar configurada en Nappai. Cuando se activa, envía peticiones HTTP a los endpoints de Jira (por ejemplo, /rest/api/3/issue) con los datos que le proporciones. La respuesta de Jira se devuelve como un objeto JSON que puedes usar en pasos posteriores del flujo.

Operaciones

Este componente ofrece varias operaciones que puedes seleccionar según lo que necesites hacer. Solo puedes usar una operación a la vez:

• Create Issue: Crea una nueva incidencia en el proyecto seleccionado.
• Update Issue: Modifica los campos de una incidencia existente.
• Create Subtask: Crea una subtarea vinculada a una incidencia padre.
• Update Subtask: Actualiza los campos de una subtarea existente.
• Delete Issue / Subtask: Elimina una incidencia o una subtarea.

Para usar el componente, primero selecciona la operación que necesitas en el campo “Operation” (Operación).

Entradas

Modo de Mapeo (Mapping Mode)

Este componente cuenta con un modo especial llamado “Mapping Mode” (Modo de Mapeo). Cuando activas este modo mediante el interruptor, se habilita una entrada adicional llamada “Mapping Data” y cada campo de entrada te ofrece tres formas diferentes de proporcionar datos:

• Fixed (Fijo): Escribes el valor directamente en el campo.
• Mapped (Mapeado): Conectas la salida de otro componente para usar su resultado como valor.
• Javascript: Escribes código Javascript para calcular el valor dinámicamente.

Esta flexibilidad te permite crear flujos de trabajo más dinámicos y conectados.

Campos de Entrada

Los siguientes campos están disponibles para configurar este componente. Cada campo puede estar visible en diferentes operaciones:

• Operation: Selecciona la acción que quieres realizar (Create Issue, Update Issue, Create Subtask, Update Subtask, Delete Issue / Subtask).

  • Visible en: Create Issue, Update Issue, Create Subtask, Update Subtask, Delete Issue / Subtask

• Assignee Account ID: ID de la cuenta de usuario a quien asignar la incidencia.

  • Visible en: Create Issue, Update Issue, Create Subtask, Update Subtask

• Comment: Comentario opcional que se añadirá a la incidencia.

  • Visible en: Update Issue, Update Subtask

• Description: Descripción detallada de la incidencia.

  • Visible en: Create Issue, Update Issue, Create Subtask, Update Subtask

• Issue Key: Clave única de la incidencia que se modificará.

  • Visible en: Update Issue, Update Subtask, Delete Issue / Subtask

• Issue Parent Key: Clave única de la incidencia que actuará como padre de la subtarea que se está creando.

  • Visible en: Create Subtask, Update Subtask

• Issue Status: Estado actual de la incidencia (To Do, In Progress, Done, etc.).

  • Visible en: Update Issue, Update Subtask

• Issue Type: Tipo de incidencia, por ejemplo, Task, Bug, Subtask.

  • Visible en: Create Issue, Update Issue, Create Subtask, Update Subtask

• Mapping Mode: Habilita el modo de mapeo para procesar múltiples registros en lote.

  • Visible en: Create Issue, Update Issue, Create Subtask, Update Subtask, Delete Issue / Subtask

• Mode: Elige entre una configuración simplificada con opciones predeterminadas o un control completo con ajustes avanzados.

  • Visible en: Create Issue, Update Issue, Create Subtask, Update Subtask

• Issue Summary: Título principal o resumen de la incidencia.

  • Visible en: Update Issue, Update Subtask

• Priority: Nivel de prioridad de la incidencia (Low, Medium, High, etc.).

  • Visible en: Create Issue, Update Issue, Create Subtask, Update Subtask

• Project Key: Selecciona el proyecto de Jira donde se realizará la operación.

  • Visible en: Create Issue, Update Issue, Create Subtask, Update Subtask

• Tool Name: Nombre del instrumento que se usará cuando este componente esté conectado como herramienta. Este nombre se mostrará al agente al elegir herramientas.

  • Visible en: Create Issue, Update Issue, Create Subtask, Update Subtask, Delete Issue / Subtask

• Tool Description: Descripción detallada de lo que hace esta herramienta. Ayuda al agente a entender cuándo y cómo usarla eficazmente.

  • Visible en: Create Issue, Update Issue, Create Subtask, Update Subtask, Delete Issue / Subtask

• Tools arguments metadata: Define los metadatos de los argumentos para las herramientas.

  • Visible en: Create Issue, Update Issue, Create Subtask, Update Subtask, Delete Issue / Subtask

Credencial
Para que el componente funcione, primero debes configurar una credencial de tipo Jira API en la sección de credenciales de Nappai. Esta credencial incluye:

• Jira Base URL (ejemplo: https://.atlassian.net)
• Jira Email (tu correo de cuenta Atlassian)
• Jira API Token (token generado en https://id.atlassian.com/manage/api-tokens)

Una vez creada, selecciona esa credencial en el campo “Credential” del componente. Los campos de la credencial no aparecen en la lista de entradas.

Salidas

• Jira Response: Respuesta JSON devuelta por la API de Jira (método: send_to_jira).
• Tool: Objeto de herramienta que puede ser usado por el agente (método: to_toolkit).

Ejemplo de Uso

Crear una nueva incidencia

1. Arrastra el componente Jira Issue Handler al flujo.
2. Selecciona la operación Create Issue.
3. Configura los campos obligatorios:
   • Project Key: PROJ
   • Issue Summary: Error en la carga de datos
   • Description: El proceso de carga falla con un error 500.
   • Issue Type: Bug
   • Priority: High
   • Assignee Account ID: 12345678-90ab-cdef-1234-567890abcdef
4. Si quieres añadir un comentario, escribe el texto en el campo Comment.
5. Guarda y ejecuta el flujo.
6. La salida Jira Response contendrá el ID de la incidencia creada, que puedes usar en pasos posteriores.

Componentes Relacionados

• Jira Comment Handler – Añade comentarios a incidencias existentes.
• Jira Search Issues – Busca incidencias según criterios y devuelve resultados.
• Jira Transition Issue – Cambia el estado de una incidencia.

Consejos y Mejores Prácticas

• Usa el modo de mapeo cuando necesites procesar listas de incidencias en lote; evita errores de configuración manual.
• Define un proyecto por defecto en el campo Project Key para acelerar la creación de incidencias.
• Incluye comentarios claros cuando actualices incidencias; facilita el seguimiento histórico.
• Revisa la respuesta de Jira antes de usarla en pasos posteriores; verifica que el campo id esté presente.
• Mantén la credencial actualizada; los tokens de API caducan y pueden romper tus flujos.

Consideraciones de Seguridad

• La credencial Jira API contiene información sensible (email y token). Asegúrate de que solo usuarios autorizados tengan acceso a la sección de credenciales.
• No compartas la salida Jira Response con datos confidenciales en logs públicos.
• Si tu flujo incluye datos sensibles, considera encriptar la salida antes de almacenarla o enviarla a otros sistemas.