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 for Jira.
P: ¿Cuál es la diferencia entre la versión Cloud y la versión Data Center del complemento?
R: Ambas versiones comparten el mismo conjunto de funcionalidades para los módulos cubiertos en esta versión (Email, Semáforo KPI, Teléfono, Moneda, Porcentaje, validadores de Campos Requeridos y Field Dependency). La versión Cloud está construida sobre Atlassian Forge y se distribuye a través del Atlassian Marketplace con licenciamiento de Atlassian, mientras que la versión Data Center se instala manualmente como plugin (.jar). La experiencia de usuario final es equivalente; las diferencias se concentran en los flujos de instalación, licenciamiento, configuración y actualización.
P: ¿Cómo adquiero o renuevo la licencia de Admin Essentials for Jira?
R: La licencia se gestiona a través del Atlassian Marketplace y aparece en la facturación consolidada de su site. Un administrador del site puede comprar o renovar desde Configuración → Facturación → Gestionar suscripciones, o desde Apps → Manage apps → Admin Essentials for Jira. También puede iniciar una prueba gratuita de 30 días al instalar desde Marketplace. Consulte la Guía de Instalación y Licenciamiento Marketplace.
P: ¿Qué ocurre si la licencia expira o está inactiva?
R: Los valores ya guardados en issues siguen siendo visibles en modo vista, con un banner informativo. La edición de campos, la configuración de contextos (umbrales, moneda, país, etc.) y la creación o edición de validadores quedan bloqueadas con el mensaje License required. Los usuarios deben contactar al administrador de Jira para renovar la licencia en Marketplace.
P: ¿Por qué un validador de workflow sigue bloqueando transiciones aunque la licencia haya expirado?
R: Las reglas guardadas en un validador de workflow no pueden comprobar el estado de licencia en el momento de la transición. Es una limitación de la plataforma Jira. La protección de licencia se aplica al configurar validadores, no al ejecutarlos. Si necesita dejar de aplicar la validación tras expirar la licencia, el administrador debe eliminar o desactivar el validador en el workflow. Más detalle en Licenciamiento Marketplace.
P: ¿Instalé el complemento antes del listing en Marketplace, sigue siendo válido?
R: Los sites que instalaron el complemento mediante enlace Forge directo migran al modelo de licenciamiento de Marketplace al actualizar a la versión 4.0.0 o superior. Gestione la licencia desde el panel de facturación de Atlassian igual que cualquier otra app de Marketplace. Para soporte comercial, contacte a MB Group en support@mbgroup.pe.
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 mediante una Jira expression ejecutada 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 @, contiene espacios o tiene varios @), 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 Forge, por lo que se aplica de forma uniforme tanto desde las pantallas de Jira como desde la REST API de Jira Cloud o 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í, con los operadores de igualdad exacta: =, !=, in, not in, is EMPTY, is not EMPTY. Por ejemplo: "Nombre del campo" = "cliente@ejemplo.com". Los operadores de coincidencia parcial (~, !~) no son compatibles con campos personalizados Forge de tipo string; esta es una limitación de la plataforma de Atlassian, no del complemento.
P: Creé un campo Email 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 esté incluido en el esquema de pantallas del proyecto correspondiente (por defecto, las pantallas de creación, edición y vista). En Jira Cloud, esto se gestiona desde Project settings → Issues → Screens o desde la administración global de pantallas.
P: Creé un campo Semáforo KPI, le asigné un valor a un issue y el indicador aparece en gris. ¿Qué falta?
R: El campo Semáforo KPI renderiza en gris mientras el contexto del campo no tenga los umbrales (Low threshold y High threshold) configurados. Vaya a Configuración → Issues → Custom fields, abra el menú de acciones del campo (⋯) → Contexts and default value, seleccione el contexto correspondiente y complete los umbrales en la sección Traffic Light thresholds. 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 Semáforo KPI?
R: Sí. Los umbrales del campo se guardan por contexto del campo personalizado. 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 Contexts and default value.
P: ¿Qué hace exactamente el modo "Lower value is better"?
R: Invierte la asignación de colores sin alterar el orden de los umbrales. En el modo por defecto, valores bajos = rojo y valores altos = verde. Con "Lower value is better" activado, valores bajos = verde y valores altos = rojo. Es útil para KPIs como tiempo de resolución, defectos abiertos o retrasos, donde un valor bajo indica mejor desempeño. La leyenda y el tooltip reflejan automáticamente el cambio.
P: El campo Semáforo KPI, ¿se puede usar en JQL?
R: Sí. El campo se registra en Forge con type: number, por lo que admite los operadores numéricos estándar (=, !=, <, <=, >, >=, is EMPTY, is not EMPTY, in, not in). Recuerde que las consultas operan sobre el valor numérico almacenado, no sobre el color resuelto.
P: ¿El complemento es compatible con Jira Service Management (JSM)?
R: Sí. Los tipos de campo del complemento se declaran con las experiencias portal-view y portal-request, lo que les permite renderizarse correctamente tanto en la vista del agente como en el portal del cliente de JSM. La edición y la validación funcionan igual que en proyectos Jira Software o Jira Work Management.
P: ¿El complemento es compatible con el modo oscuro de Jira Cloud?
R: Sí. Tanto el indicador del Semáforo KPI, su leyenda y tooltip, como el campo Email se construyen con tokens de diseño de UI Kit 2 (color.text, color.text.subtlest, etc.). Esto significa que los colores se ajustan automáticamente al tema activo (claro u oscuro) manteniendo el contraste accesible.
P: El validador "Fields Required" no aplica a un campo personalizado, aunque lo seleccioné. ¿Por qué?
R: Por defecto, el validador omite los campos personalizados que no están configurados para el proyecto o el tipo de issue del que se está ejecutando la transición. Es el comportamiento esperado cuando un mismo workflow se reutiliza en varios proyectos con esquemas distintos. Si necesita exigir el campo de todas formas, marque la casilla Ignore context al editar el validador.
P: ¿El complemento Cloud puede coexistir con la versión Data Center del mismo complemento?
R: Sí, son productos independientes que viven en plataformas distintas. Una organización puede tener la versión DC en su instancia Data Center y la versión Cloud en su site Atlassian Cloud, en paralelo, sin conflictos.
P: ¿Las actualizaciones del complemento son automáticas?
R: Sí. Las aplicaciones Forge se actualizan automáticamente desde la infraestructura de Atlassian, sin necesidad de intervención manual del administrador. Si una versión futura introduce nuevos permisos (scopes), Atlassian le notificará y solicitará su aprobación antes de aplicar la actualización.
P: ¿Qué formatos de número de teléfono acepta el campo Phone Number Field?
R: El campo admite E.164 (+51 999 888 777, +1 800 555 0100) y formatos locales con separadores (999-888-777, (01) 234-5678), con longitud total entre 7 y 25 caracteres. Solo se aceptan dígitos y los separadores visuales +, espacio, ., -, (, ). Si el valor no cumple las reglas, Jira muestra "The value is not a valid phone number." y bloquea el guardado.
P: El campo Currency muestra el valor sin símbolo, ¿por qué?
R: El símbolo de moneda, su posición y los decimales se configuran por contexto del campo. Mientras un contexto no tenga configuración guardada, los valores se muestran como número plano (1,500.00) usando el locale del usuario. Vaya a Configuración → Issues → Custom fields, abra el menú ⋯ del campo → Contexts and default value, seleccione el contexto y complete los campos Currency symbol, Symbol position y Decimal places dentro de la sección Currency display.
P: ¿Puedo tener distintas monedas en un mismo campo Currency Field, según el proyecto?
R: Sí. La configuración (símbolo, posición, decimales) se guarda por contexto del campo personalizado. Cree un contexto por cada proyecto o tipo de issue al que quiera asignar una moneda distinta y guarde la configuración correspondiente en cada uno. No es necesario duplicar el campo.
P: La barra del campo Percentage Field aparece en un color que no esperaba, ¿por qué?
R: Los colores de la barra dependen de los umbrales definidos en el contexto del campo. Cuando un contexto no tiene umbrales configurados, el complemento aplica valores por defecto (rojo < 40, amarillo 40–69, verde ≥ 70). Si necesita umbrales distintos, vaya a Contexts and default value del campo y configure At-risk from y On-track from en la sección Percentage colour thresholds.
P: ¿Cuál es la diferencia entre el validador Fields Required y Field Dependency?
R: Fields Required exige uno o varios campos siempre que se ejecute la transición. Field Dependency exige un campo solo cuando otro campo tiene un valor concreto (por ejemplo, "requiere Assignee solo cuando Priority es Highest"). Ambos validadores pueden coexistir en la misma transición: el primero cubre los campos obligatorios fijos y el segundo añade reglas condicionales por encima.
P: ¿Puedo usar como disparador del validador Field Dependency un campo de texto o numérico?
R: Sí, desde la versión 3.1.0. Además de los campos con valores discretos (Priority, Issue Type, Single-select List y Radio Buttons), el validador admite campos numéricos (Currency, Percentage, Traffic Light KPI) con operadores =, !=, <, <=, >, >=, y campos de texto (Email, Phone Number) con operadores equals, does not equal, contains, is empty e is not empty.
P: ¿Por qué desaparecieron los botones Cancel/Save dentro de los campos del complemento en la pantalla de creación de issue?
R: En la versión 3.0.0 retiramos esos botones internos porque duplicaban la acción de los botones nativos Create / Cancel del propio diálogo de Jira. La nueva integración se siente más natural: el campo deja de comportarse como un mini-formulario aparte y se valida junto con el resto del diálogo cuando el usuario hace clic en Create. El comportamiento de validación y guardado no cambia: si el valor introducido es inválido, el campo muestra el error y bloquea el envío del diálogo hasta que se corrija.