Preguntas Frecuentes (FAQ)
A continuación, se presentan algunas de las preguntas más comunes sobre la configuración y el uso de Admin Essentials.
P: ¿Por qué Jira no me deja guardar el issue y muestra un error en el campo Email?
R: El complemento valida el formato del correo en el servidor. El error aparece cuando: 1) el texto no respeta el formato de un correo electrónico estándar (por ejemplo, falta la @ o contiene espacios), 2) la dirección excede los 254 caracteres permitidos en total, o 3) la parte anterior a la @ excede los 64 caracteres. Corrija la dirección y vuelva a guardar.
P: ¿La validación también se aplica si creo o actualizo issues a través de la REST API?
R: Sí. La validación se ejecuta en el servidor como parte del ciclo de vida estándar de los campos personalizados de Jira, por lo que se aplica de forma uniforme tanto desde las pantallas de Jira como desde la REST API, importadores e integraciones externas. Esto evita que entren direcciones inválidas por caminos alternativos.
P: ¿Puedo buscar issues por el valor del campo Email desde JQL?
R: Sí. El campo se registra con un buscador (searcher) integrado al motor de Jira. Puede usar consultas como "Nombre del campo" = "cliente@ejemplo.com" reemplazando Nombre del campo por el nombre exacto que se asignó al crear el campo personalizado.
P: Creé el campo, pero los usuarios no lo ven en la pantalla del issue, ¿qué falta?
R: En Jira, los campos personalizados solo aparecen en las pantallas a las que han sido asociados explícitamente. Verifique que el campo Email esté incluido en el esquema de pantallas del proyecto correspondiente (por ejemplo, en la pantalla por defecto, la de creación y la de edición de issues).
P: ¿Puedo guardar más de una dirección de correo en el mismo campo?
R: No. El campo Email almacena una única dirección por issue. Si necesita capturar varias direcciones (por ejemplo, una lista de notificación), la recomendación es crear varios campos Email separados o usar un campo de texto libre acompañado de una convención interna.
P: ¿Qué pasa si el campo no está marcado como obligatorio y un usuario lo deja en blanco?
R: El valor vacío es válido cuando el campo no es obligatorio en la configuración del proyecto. No se mostrará error y el issue se podrá guardar normalmente.
P: ¿Por qué el plugin se llama ahora "Admin Essentials"?
R: A partir de la versión 1.0.0, el complemento adopta oficialmente el nombre Admin Essentials para reflejar su naturaleza como suite multi-módulo de utilidades para administradores de Jira. La primera versión incluye el campo Email; futuras versiones añadirán nuevos módulos bajo el mismo paquete.
P: Creé un campo Traffic Light KPI, le asigné un valor a un issue y el indicador aparece en gris. ¿Qué falta?
R: El campo Traffic Light KPI renderiza en gris mientras el contexto del campo no tenga umbrales (Red max y Yellow max) configurados. Vaya a Administración de Jira > Incidencias > Campos personalizados, abra la configuración del campo, localice la fila Thresholds del contexto correspondiente y haga clic en Edit para definir los umbrales. Una vez guardados, los issues de ese contexto comenzarán a mostrar el color resuelto.
P: ¿Puedo tener umbrales distintos por proyecto en el mismo campo Traffic Light KPI?
R: Sí. Los umbrales del campo Traffic Light KPI se guardan por contexto (FieldConfigContext). Cree un contexto por cada proyecto o tipo de issue al que quiera asignar reglas distintas y defina los umbrales de cada contexto de forma independiente desde la página de configuración del campo.
P: ¿El campo Traffic Light KPI se puede usar en JQL?
R: Sí. El campo se registra con el Number Range Searcher estándar de Jira, por lo que admite los operadores numéricos habituales (=, <, <=, >, >=). Por ejemplo: "Nivel de cumplimiento" < 30. Recuerde que las consultas operan sobre el valor numérico almacenado, no sobre el color resuelto.
P: ¿Puedo filtrar en JQL los issues "rojos", "amarillos" o "verdes" del Semáforo?
R: Sí, pero no mediante una sintaxis por color como "Mi Campo" = "ROJO". En Jira, JQL consulta el valor numérico almacenado, por lo que debe traducir cada zona a un rango usando los umbrales (Red max y Yellow max) del contexto correspondiente. Por ejemplo, en el modo por defecto, la zona roja se expresa como "Mi Campo" <= <LOW>. Para más detalle, consulte la sección Filtrar por zona del Semáforo con JQL dentro de la guía del campo Traffic Light KPI.
P: ¿La versión 2.0.0 funciona en Jira 10?
R: No. La versión 2.0.0 requiere Jira Data Center 11.3 o superior (Java 21) y no es compatible con Jira 10.x. Si su sitio permanece en Jira 10.x, continúe usando la versión 1.4.0.
P: ¿Tengo que reconfigurar campos, umbrales o reglas de workflow al actualizar a la versión 2.0.0?
R: No. La versión 2.0.0 es una actualización de plataforma: los campos, umbrales, contextos y reglas de workflow existentes se mantienen sin cambios tras la actualización.
P: ¿Qué límites tiene el campo de Adjuntos y quién los configura?
R: Los límites los define el administrador de Jira en la configuración de cada contexto del campo: número máximo de archivos (entero entre 1 y 100; por defecto 5), tipos de archivo permitidos (Imágenes, Hojas de cálculo, Documentos, Vídeos y Archivos comprimidos, más extensiones personalizadas), y tamaño máximo por archivo en KB, MB o GB (por defecto 10 MB; si se deja vacío, no hay límite de tamaño). Si no se marca ningún grupo de tipos, se admite cualquier archivo.
P: ¿En qué se diferencia el campo de Adjuntos del panel nativo de adjuntos de Jira?
R: El campo de Adjuntos se guarda como adjuntos nativos de Jira, pero es una vista filtrada: solo muestra los archivos que se subieron a través de ese campo concreto, mientras que el panel Attachments del issue lista todos los adjuntos de la incidencia, vengan de donde vengan. Además, el campo aplica las restricciones de cantidad, tipo y tamaño configuradas por el administrador, que el panel nativo no tiene. Los archivos del campo también aparecen en el panel nativo y los detecta attachments is not EMPTY, pero desde el panel no es posible saber de qué campo proviene cada archivo.
P: ¿Puedo buscar issues por el nombre o el tipo de un archivo del campo de Adjuntos en JQL?
R: No. El campo solo admite los operadores is EMPTY e is not EMPTY sobre el nombre del campo, que permiten filtrar issues que tienen o no tienen archivos en ese campo (por ejemplo, "Facturas" is not EMPTY). No es posible buscar por nombre de archivo, extensión ni tipo, ni en el campo ni en el panel nativo de adjuntos.
P: ¿El campo de Adjuntos necesita Jira Service Management?
R: No. El complemento funciona con normalidad sin JSM: el campo está disponible en la vista del issue, la creación, la edición y la transición. Si su instancia tiene Jira Service Management, el administrador puede habilitar además el campo en el portal de clientes, de modo que los clientes puedan adjuntar archivos al crear una solicitud y verlos en el detalle. Es una opción por contexto y está desactivada de forma predeterminada.
P: ¿Qué ocurre cuando quito un archivo desde el campo de Adjuntos?
R: Al quitar un archivo y guardar, se elimina de forma definitiva el adjunto nativo correspondiente del issue; no es posible recuperarlo. Jira pide confirmación antes de proceder ("¿Quitar {archivo}? Se eliminará de forma definitiva al guardar.").
P: ¿Qué pasa con los archivos del campo de Adjuntos si desinstalo el complemento?
R: Los archivos subidos al campo son adjuntos nativos de Jira y permanecen en el issue aunque se desinstale el complemento; solo el campo personalizado y su configuración de contexto dejan de estar disponibles.
P: ¿Puedo tener varios campos de Adjuntos en el mismo issue?
R: Sí. Cada campo mantiene su propia lista de archivos, independiente de los demás, y sus propios límites de cantidad, tipo y tamaño. Un campo "Facturas" y un campo "Evidencia fotográfica" en el mismo issue no mezclan sus archivos, aunque ambos aparezcan también en el panel nativo de adjuntos.
P: ¿Puedo guardar el issue mientras un archivo se está subiendo?
R: No. Mientras haya una subida en curso, Jira bloquea el guardado o la creación del issue y muestra el aviso "Espere a que terminen de subir los archivos antes de guardar o crear el issue.". Espere a que la subida termine y guarde después; los archivos quedarán asociados al campo automáticamente.