Introducción a Admin Essentials

¡Bienvenido a la documentación oficial del complemento Admin Essentials for Jira! 🎉

Admin Essentials — campos personalizados avanzados y extensiones de workflow para Jira Cloud sobre Forge.

El complemento está construido sobre Atlassian Forge y se distribuye a través del Atlassian Marketplace, por lo que se beneficia del modelo de seguridad, despliegue y actualización de la plataforma oficial de Atlassian.

Vídeo introductorio

Conoce en pocos minutos qué es Admin Essentials for Jira y cómo puede ayudarte a ampliar Jira Cloud con campos personalizados y extensiones de workflow.

Admin Essentials for Jira está disponible en el Atlassian Marketplace como producto de pago con periodo de evaluación. Siga la Guía de Instalación para instalarlo o iniciar una prueba gratuita en su site.

Instalar desde Marketplace

v4.0.0+

A partir de la versión 4.0.0, la edición y configuración de campos y validadores requiere una licencia activa de Marketplace. Los valores ya guardados en issues siguen siendo visibles sin licencia. Consulte Licenciamiento Atlassian Marketplace para el detalle por superficie.

¿Para quién es este complemento?

Audiencia objetivo

Admin Essentials está diseñado para Administradores de Jira Cloud, Líderes de Proyecto y equipos operativos (soporte, mesas de servicio, comerciales, operaciones) que necesiten ampliar Jira con utilidades transversales que cubran necesidades cotidianas sin sumar complementos adicionales a la instancia.

Funcionalidades incluidas en la versión 1.9.0 (Forge 7.0.0)

La versión 1.9.0 (Forge 7.0.0) incorpora diez módulos. Siete de ellos mantienen paridad funcional con la versión Data Center. El Campo de Adjuntos, la Condición de Workflow por Expresión y el Validador de Cantidad de Adjuntos son exclusivos de Cloud.

Actualización desde 1.8.0

Esta versión es un minor sobre 1.8.0: añade la búsqueda JQL por color en Semáforo KPI y Porcentaje, el validador de cantidad de adjuntos, y la descarga desde la vista previa del Campo de Adjuntos. Corrige además el guardado de varios archivos en ese campo. Incluye permisos nuevos que el administrador debe aprobar. Consulte la Guía de Instalación para el detalle de la actualización.

Versión anterior: 1.8.0 (Forge 6.1.0)

La 1.8.0 cambió el almacenamiento del Campo de Adjuntos a adjuntos nativos de Jira y su vista a tarjetas (miniatura o icono).

Campo personalizado Email

• Tipo de campo personalizado que almacena una dirección de correo electrónico por work item.
• Validación de formato en el cliente (al editar) y en el servidor (mediante una Jira expression).
• Renderizado automático como enlace mailto: clicable en la vista del work item.
• Edición inline desde la vista del work item, pantallas de creación, edición, transición y el portal de JSM.
• Búsqueda JQL con operadores de igualdad exacta (=, !=, in, is EMPTY, etc.).

Campo personalizado Semáforo KPI (Traffic Light)

• Tipo de campo numérico que se renderiza como un indicador visual de tres colores (🔴 rojo / 🟡 amarillo / 🟢 verde).
• Umbrales configurables por contexto del campo: distintos umbrales para distintos espacios o tipos de work item.
• Modo "Lower is better" (menor es mejor) para invertir la semántica de colores en KPIs donde un valor bajo es deseable.
• Leyenda descriptiva y tooltip que explican la regla activa.
• Soporte nativo de modo oscuro mediante tokens de diseño de UI Kit 2.
• Búsqueda JQL por color con la función trafficLightBand (por ejemplo, issue in trafficLightBand("red")), además de los operadores numéricos sobre el valor.

Campo personalizado Teléfono (Phone Number)

• Almacena un número de teléfono por work item con selector de país (buscable, ~250 países ISO) y campo de número local en disposición inline.
• País por defecto configurable por contexto (contextConfig): los administradores fijan el país predeterminado por espacio o tipo de work item.
• Validación uniforme en cliente y servidor (E.164, formatos locales con separadores); longitud total entre 7 y 25 caracteres (incluido el código de marcación).
• Renderizado como 📱 PE +51 943 824 375 con enlace tel: clicable.
• Edición inline y búsqueda JQL con operadores de igualdad exacta.

Campo personalizado Moneda (Currency)

• Campo numérico que almacena un importe y lo renderiza con símbolo, posición y decimales configurables por contexto.
• Búsqueda JQL sobre el valor numérico almacenado, no sobre la cadena formateada.

Campo personalizado Porcentaje (Percentage)

• Campo numérico restringido al rango 0–100, renderizado como barra de progreso con tres bandas de color.
• Umbrales configurables por contexto (At-risk from, On-track from).
• Búsqueda JQL por color con la función percentageBand (por ejemplo, issue in percentageBand("green")).

Campo personalizado Adjuntos (Attachment Field)

• Tipo de campo personalizado para adjuntar archivos directamente a un campo concreto del work item (por ejemplo, Facturas, Fotos de evidencia, Documentos PQR), manteniendo cada campo independiente de los demás.
• Almacenamiento en adjuntos nativos de Jira: los archivos subidos desde esta versión se guardan como adjuntos nativos del work item; el campo guarda solo sus identificadores y filtra la vista a los que le pertenecen.
• Vista de tarjetas: cada archivo se muestra como una tarjeta con miniatura (imágenes) o icono de tipo (PDF, Word, Excel…), nombre, tipo y tamaño, y un icono de vista previa o descarga. Disponible en la vista del work item, el portal JSM y la vista de agente.
• Vista previa con descarga: imágenes y archivos de texto se abren en una ventana de vista previa con los botones Descargar y Cerrar.
• Configuración por contexto: máximo de archivos (de 1 a 7), tipos permitidos (imágenes, hojas, documentos, vídeos, comprimidos), extensiones personalizadas y tamaño máximo por archivo.
• JQL: is EMPTY / is not EMPTY por campo; el panel nativo attachments is not EMPTY también detecta los archivos nuevos del campo.

Validador de Workflow "Campos Requeridos"

• Validador de transición que bloquea el avance si determinados campos están vacíos.
• Configuración mediante lista dual (campos disponibles / campos seleccionados).
• Mensaje de error personalizado y opción de ignorar el contexto para forzar la validación incluso en contextos no configurados.

Validador de Workflow "Field Dependency"

• Validador condicional que bloquea la transición cuando un campo disparador cumple una condición y un campo requerido está vacío.
• Múltiples reglas por validador, cada una con su propio mensaje de error personalizado.
• Disparadores de lista (Priority, Issue Type, Single-select List, Radio Buttons), numéricos (Currency, Percentage, Traffic Light KPI) y texto (Email, Phone Number).
• Operadores numéricos (=, !=, <, <=, >, >=) y de texto (equals, does not equal, contains, is empty, is not empty).

Validador de Workflow "Cantidad de adjuntos"

• Validador de transición que bloquea el avance si un Campo de Adjuntos tiene menos o más archivos de los configurados.
• Mínimo, máximo o ambos por campo, para uno o varios campos de Adjuntos en el mismo validador.
• Mensaje de error personalizado opcional; por defecto, el mensaje nombra el campo, el límite y la cantidad actual.
• Cuenta también los archivos añadidos en la pantalla de transición.

Condición de Workflow por Expresión (Expression Condition)

• Nueva condición de workflow que oculta el botón de transición cuando el work item no cumple una expresión Jira.
• A diferencia de los validadores, actúa antes del intento: si el work item no cumple el criterio, el botón no aparece.
• Útil para simplificar la vista del workflow eliminando opciones que no son aplicables.
• Solo disponible en espacios company-managed.

Diferencias frente a la versión Data Center

Aspecto	Data Center	Cloud (Forge)
Plataforma	Plugin tradicional (P2)	Atlassian Forge
Distribución	Archivo .jar / .obr	Atlassian Marketplace
Licenciamiento	Licencia de plugin Atlassian	Licencia de Marketplace (edición/config requieren licencia activa desde v4.0.0)
Tecnología UI	Velocity / AUI	UI Kit 2 (@forge/react) + Custom UI
Compatibilidad	Jira Data Center 10.3.18+	Jira Cloud (cualquier site)
Actualizaciones	Manuales por el administrador	Automáticas, salvo upgrades de versión mayor de Forge (p. ej. 1.7.0) que exigen Update y re-consentimiento
Modo oscuro	Estilo CSS clásico	Nativo con tokens de diseño

Cloud

Si ya conoce Admin Essentials para Jira Data Center, encontrará una experiencia equivalente en Cloud para Email, Semáforo KPI, Teléfono, Moneda, Porcentaje y los validadores Fields Required y Field Dependency. El Campo de Adjuntos y la Condición de Workflow por Expresión se añadieron en 1.7.0, y el Validador de Cantidad de Adjuntos en 1.9.0. Ninguno tiene equivalente en Data Center. Las diferencias de plataforma se concentran en instalación (Marketplace), licenciamiento, configuración de pantallas y administración de campos.

Compatibilidad

• Jira Cloud: Cualquier site de Jira Cloud (Free, Standard, Premium, Enterprise).
• Jira Service Management (JSM): Los campos personalizados son compatibles con la vista del agente y el portal del cliente.
• Plataforma: Atlassian Forge, runtime nodejs24.x.

Bienvenido a Admin Essentials: lo esencial para que su Jira Cloud hable el mismo idioma que sus procesos.