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: ¿Qué versión tengo instalada?
R: La versión verificable en Jira Cloud es la que aparece en Apps → Manage apps (por ejemplo, 4.2.0). Esa es la versión Forge.
En este sitio de documentación, el selector de versión muestra la versión Forge para releases publicadas en producción. Consulte la tabla de mapeo en el changelog para relacionar cada release MB Group con su versión Forge.
P: ¿Cuál es la diferencia entre la versión Cloud y la versión Data Center del complemento?
R: Ambas versiones comparten Email, Semáforo KPI, Teléfono, Moneda, Porcentaje y los 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; la versión Data Center se instala como plugin (.jar). El Campo de Adjuntos y la Condición de Workflow por Expresión son exclusivos de Cloud (release 1.7.0) y no tienen equivalente en Data Center. En los módulos compartidos, la experiencia de usuario final es equivalente; las diferencias se concentran en 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 work item 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 work items 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 work item, ¿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 espacio correspondiente (por defecto, las pantallas de creación, edición y vista). En Jira Cloud, esto se gestiona desde Space settings → Work items → Screens o desde la administración global de pantallas.
P: Creé un campo Semáforo KPI, le asigné un valor a un work item 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 → Work items → 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 work items de ese contexto comenzarán a mostrar el color resuelto.
P: ¿Puedo tener umbrales distintos por espacio 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 espacio o tipo de work item 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 espacios 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 espacio o el tipo de work item del que se está ejecutando la transición. Es el comportamiento esperado cuando un mismo workflow se reutiliza en varios espacios 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: En general sí. Las aplicaciones Forge se actualizan automáticamente desde la infraestructura de Atlassian. Si una versión introduce nuevos permisos (scopes) o un cambio de versión mayor de Forge, Atlassian solicita aprobación explícita antes de aplicarla.
Excepción — 1.7.0 (Forge 6.0.0): este release incorpora Forge Object Store y exige que el administrador del site vaya a Apps → Manage apps, pulse Update y vuelva a consentir los permisos. Hasta entonces, el Campo de Adjuntos y la Condición de Workflow no quedan operativos. Consulte la Guía de Instalació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 → Work items → 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 espacio?
R: Sí. La configuración (símbolo, posición, decimales) se guarda por contexto del campo personalizado. Cree un contexto por cada espacio o tipo de work item 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 del work item?
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.
P: ¿Qué debo hacer al actualizar a la versión 1.7.0?
R: Hay que completar dos pasos: Update en Apps → Manage apps y re-consentimiento de los permisos que pide Atlassian (Object Store / versión mayor de Forge). Sin ambos, los módulos nuevos no funcionan. Las configuraciones de campos y validadores de 1.6.0 se conservan; el Campo de Adjuntos y la Condición de Workflow se configuran desde cero. El detalle está en la Guía de Instalación.
P: ¿En qué se diferencia el campo de Adjuntos del panel nativo de adjuntos de Jira?
R: Son mecanismos de almacenamiento independientes. Los archivos subidos al campo de Adjuntos (Attachment Field) viven en ese campo concreto y no aparecen en el panel Attachments nativo del work item. La consulta JQL attachments is not EMPTY no detecta los archivos del campo de Adjuntos; para filtrar issues con archivos en el campo use "Nombre del campo" is not EMPTY. El campo de Adjuntos está pensado para categorizar documentos por tipo o etapa (Facturas, Fotos de evidencia, Documentos PQR) con independencia del panel nativo y de los adjuntos de otros campos del mismo work item.
P: ¿Puedo buscar en JQL por el nombre o el tipo de un archivo concreto en el campo de Adjuntos?
R: No. El campo de Adjuntos solo admite los operadores is EMPTY e is not EMPTY en JQL, que permiten filtrar work items que tienen o no tienen archivos en ese campo. No es posible buscar por nombre de archivo, extensión ni tipo de archivo mediante JQL.
P: ¿Qué ocurre con los archivos del campo de Adjuntos si borro el work item?
R: Borrar el work item no elimina automáticamente los archivos del campo del Forge Object Store. Los objetos permanecen en el almacén y no son accesibles desde Jira. Para evitar objetos huérfanos, se recomienda borrar los archivos del campo (en edición) antes de borrar el work item. Esta es una limitación de la plataforma Forge Object Store (Preview) en su versión actual.
P: ¿Cuál es la diferencia entre una condición de workflow y un validador?
R: Una condición actúa antes del intento de transición: si el work item no cumple el criterio, el botón de transición directamente no aparece. Un validador actúa después: el botón siempre se muestra, pero al confirmar la transición se bloquea con un mensaje de error si no se cumplen las reglas. Use la condición cuando quiera simplificar la vista del workflow ocultando transiciones que no aplican. Use el validador cuando quiera que el usuario siempre vea la transición, pero con una verificación explícita al confirmar.
P: ¿La Condición de Workflow por Expresión usa JQL clásico?
R: No. La condición evalúa Jira expressions, que es un lenguaje de expresiones propio de Atlassian Forge. No admite operadores de historial como WAS, CHANGED ni la sintaxis JQL libre. Las consultas deben escribirse como expresiones booleanas sobre los campos del work item (por ejemplo, issue.priority != null && issue.priority.name == 'High'). Consulte la Guía de la Condición de Workflow para ver ejemplos.
P: ¿La Condición de Workflow por Expresión está disponible en espacios team-managed?
R: No. La condición está disponible únicamente en espacios company-managed. Los espacios team-managed no admiten extensiones de workflow de terceros. Además, el módulo subyacente (jira:workflowCondition) está actualmente en estado Preview de la plataforma Atlassian Forge, por lo que sus capacidades y disponibilidad pueden cambiar en versiones futuras.