Campo Personalizado Email

El campo personalizado Email Custom Field permite registrar una dirección de correo electrónico asociada a un work item (incidencia), con validación de formato tanto en el cliente como en el servidor, y soporte de búsqueda integrado con el motor de Jira Cloud.

Este apartado describe cómo crear el campo, asociarlo a sus pantallas y entender las reglas de validación que aplica el complemento.

Crear el campo Email

1. En Jira, haga clic en el icono de Configuración (rueda dentada) en la esquina superior derecha.

2. Seleccione Issues (Incidencias) en el menú.

3. En la barra lateral izquierda, dentro de la sección Fields (Campos), haga clic en Custom fields (Campos personalizados).

4. Haga clic en Create custom field (Crear campo personalizado) en la esquina superior derecha.

5. En la pantalla "Select a field type", busque y seleccione Email Custom Field (proporcionado por Admin Essentials). Haga clic en Next.

   💡 Lo reconocerá por su descripción: "Stores a single email address." y por el icono de sobre azul.

   

6. Nombre y descripción:

   • Introduzca un Name (Nombre) para el campo (por ejemplo, "Correo del solicitante", "Email de contacto").
   • Añada una Description (Descripción) opcional para guiar a los usuarios.

7. Haga clic en Create.

8. Asociar a pantallas: Jira le solicitará seleccionar las pantallas donde aparecerá el campo (creación, edición, transición). Marque las que correspondan y haga clic en Update.

A partir de este momento, el campo estará disponible en las pantallas configuradas y los usuarios podrán capturar direcciones de correo en sus issues.

¿No ve el tipo "Email Custom Field" en la lista?

Verifique que la instalación de Admin Essentials se haya completado correctamente (vea Apps → Manage apps). Si la app está instalada pero el tipo de campo no aparece, espere unos minutos a que Forge sincronice los módulos con su site y refresque la página.

Reglas de validación

El complemento aplica validación en dos niveles:

1. Cliente (al editar): El componente de edición inline muestra mensajes de error específicos mientras el usuario escribe.
2. Servidor (al guardar): Forge ejecuta una Jira expression definida en el manifiesto del complemento que comprueba la dirección antes de persistir el valor. Esta es la fuente de verdad.

Las reglas aplicadas son:

• Formato: El valor debe ajustarse al patrón de un correo electrónico estándar (local@dominio.tld), sin espacios y con un único @.
• Longitud total: La dirección no puede exceder 254 caracteres (límite de RFC 5321).
• Longitud de la parte local: El segmento anterior a la @ no puede exceder 64 caracteres (límite de RFC 5321).
• Vacío permitido: Si el campo no es obligatorio en la configuración de Jira, dejarlo en blanco es válido.

Si el valor no cumple alguna regla, Jira mostrará el mensaje "The value is not a valid email address." (o su equivalente en español según el idioma del usuario) y no permitirá guardar el cambio.

Validación uniforme también en la REST API

Como la validación final se ejecuta en el servidor mediante una Jira expression, también se aplica cuando un issue es creado o editado mediante la REST API de Jira Cloud o por integraciones externas. Esto evita huecos donde se podrían introducir direcciones inválidas saltándose la validación del navegador.

Soporte de búsqueda y JQL

El campo Email se registra en Forge con type: string, lo que habilita los operadores de cadena de igualdad exacta en JQL:

Operador	Soportado	Ejemplo
=	✅	"Correo del solicitante" = "cliente@ejemplo.com"
!=	✅	"Correo del solicitante" != "spam@no.com"
in / not in	✅	"Correo del solicitante" in ("a@x.com", "b@y.com")
is EMPTY / is not EMPTY	✅	"Correo del solicitante" is not EMPTY
~ / !~ (parcial)	❌	(no soportado por Forge para type: string)

Búsqueda parcial no disponible

Los operadores de coincidencia parcial (~, !~) no son soportados para campos personalizados Forge de tipo string. Esta es una limitación de la plataforma de Atlassian Forge, no del complemento. Para listas de direcciones, use el operador in (...).

Renderizado en la vista del issue

Una vez guardado, el correo aparece en la vista del issue como un enlace mailto: clicable precedido por un icono de sobre (✉). Al hacer clic, el sistema operativo abre el cliente de correo predeterminado del usuario con un nuevo mensaje dirigido a esa dirección, listo para escribir.

El complemento aplica codificación segura del valor (RFC 6068) antes de construir el enlace, garantizando que caracteres no estándar se serialicen correctamente.

Edición inline

El campo soporta edición inline en la vista del issue: basta con hacer clic sobre el valor para que aparezca un cuadro de texto editable. Las mismas reglas de validación se aplican; los errores se muestran debajo del campo en rojo y bloquean el guardado hasta que la dirección sea válida.