Campo Personalizado Teléfono

El campo personalizado Phone Number Field permite registrar un número de teléfono por work item, con validación de formato y renderizado como un enlace clicable tel: desde la vista del issue. Es útil para fichas de cliente, requesters de mesa de servicio, contactos comerciales y, en general, cualquier caso en el que se necesite capturar un número que luego pueda llamarse con un clic.

Crear el campo Teléfono

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

2. Seleccione Issues (Incidencias).

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

4. Haga clic en Create custom field en la esquina superior derecha.

5. En la pantalla "Select a field type", busque y seleccione Phone Number Field. Haga clic en Next.

   💡 Lo reconocerá por su descripción: "Stores a single phone number." y por el icono de teléfono.

   

6. Nombre y descripción:

   • Introduzca un Name (Nombre) para el campo (por ejemplo, "Teléfono del solicitante", "Contacto comercial").
   • Añada una Description opcional.

7. Haga clic en Create.

8. Asociar a pantallas: Marque las pantallas donde aparecerá el campo (creación, edición, transición, vista) y haga clic en Update.

A partir de este momento el campo está disponible para capturarse en los issues.

Formatos aceptados

El complemento valida cada número en el cliente (mientras el usuario escribe) y en el servidor (al guardar) usando el mismo patrón, para que un número inválido no pueda colarse a través de la REST API.

Se aceptan estos formatos:

• Internacional (E.164): +51999888777, +1 800 555 0100.
• Local con separadores: 999-888-777, (01) 234-5678.
• Mezcla razonable de espacios, puntos, guiones y paréntesis alrededor de los dígitos.

Restricciones:

• Longitud total entre 7 y 25 caracteres (incluido el + opcional inicial y el código de marcación).
• Solo dígitos y los separadores visuales +, espacio, ., -, (, ).
• El primer carácter útil debe ser un dígito o + (no se aceptan letras ni símbolos como & o #).

A partir de la versión 3.1.0, el campo almacena el número en el formato +<dialCode> <localNumber>, por ejemplo +51 943 824 375. Los valores anteriores (sin código de marcación) se complementan automáticamente con el país configurado en el contexto al editar el issue.

Validación permisiva por diseño

La validación del complemento comprueba que el valor sea un número de teléfono razonable (longitud, caracteres permitidos, primer carácter), pero no realiza una verificación por país: un número con código +51 no se comprueba contra las reglas de longitud específicas de Perú. Esta es una decisión de diseño deliberada para dar flexibilidad máxima y minimizar falsos negativos.

Si el valor no cumple las reglas, Jira muestra "The value is not a valid phone number." y no permite guardar.

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 números inválidos saltándose la validación del navegador.

Captura con selector de país

A partir de la versión 3.1.0, la interfaz de edición del campo Teléfono presenta una UI estructurada en dos partes en disposición inline:

1. Selector de país (desplegable buscable): lista ~250 países según la norma ISO 3166-1, mostrando la bandera, el nombre del país y el código de marcación (+51, +1, etc.). El usuario puede escribir en el desplegable para filtrar por nombre de país o por código.
2. Campo de número local (texto libre): el usuario escribe únicamente la parte local del número, sin necesidad de anteponer el código de país.

El complemento combina ambas partes al guardar: +<dialCode> <localNumber>.

Al abrir la pantalla de creación con el campo vacío, el selector se preselecciona con el país configurado en el contexto del campo (véase la sección "Configuración del país por defecto por contexto"). Al editar un número ya guardado, el complemento lo separa automáticamente en país y número local mediante phoneParser.js. Si el valor guardado no contiene código de marcación (valores anteriores a v3.1.0), se completa con el país del contexto. Si no hay país configurado en el contexto, el sistema usa PE (Perú) como reserva.

Captura desde la pantalla de creación

En el diálogo de Create issue, el campo aparece con la nueva UI estructurada: el selector de país preseleccionado según la configuración del contexto y el campo de número local listo para escribir. El usuario solo necesita verificar el país (o cambiarlo si es necesario) y escribir su número local. El complemento valida el formato al cabo de un segundo; si el valor es inválido se muestra el mensaje de error debajo del campo y el botón Create del diálogo bloqueará el envío hasta corregirlo.

Configuración del país por defecto por contexto

Los administradores pueden fijar el país predeterminado que aparecerá preseleccionado en el selector para cada contexto del campo. Esto es especialmente útil cuando distintos proyectos o tipos de issue operan en diferentes países.

Para configurar el país por defecto de un contexto:

1. En Jira, haga clic en el icono de Configuración (rueda dentada) en la esquina superior derecha.
2. En la barra lateral, bajo la sección Work items, haga clic en Custom fields.
3. Localice el campo Phone Number Field que desea configurar y haga clic en Configure.
4. En la pantalla "Configure custom field", seleccione el contexto que desea configurar.
5. En el campo Default country, seleccione el país deseado (por ejemplo, PE para Perú, ES para España, MX para México).
6. Haga clic en Save.

Contextos independientes por proyecto o tipo de issue

Puede tener varios contextos para el mismo campo, cada uno asociado a un conjunto distinto de proyectos o tipos de issue, y fijar un país diferente en cada uno. Por ejemplo, el campo "Teléfono del solicitante" puede usar PE en el contexto de proyectos latinoamericanos y ES en el contexto de proyectos de España.

Reserva automática

Si un contexto no tiene país configurado, el selector usará PE (Perú) como valor de reserva. Configure siempre el país en todos los contextos activos para evitar que aparezca una preselección incorrecta para sus usuarios.

Renderizado en la vista del issue

Una vez guardado, el número aparece en la vista del issue acompañado por el icono mobile y se renderiza como un enlace tel: clicable. El formato de visualización es:

📱 PE +51 943 824 375

Donde se muestra el código de país (ISO), el código de marcación y el número local. Al hacer clic, el dispositivo del usuario abre la aplicación de llamadas predeterminada (en macOS / Windows con una app de llamadas configurada, en móviles directamente el marcador).

El enlace solo contiene dígitos (más un + opcional al inicio): los separadores visuales se eliminan al construir el href, para que el marcador no intente teclearlos. El número que el usuario ve mantiene los separadores que escribió.

Soporte de búsqueda y JQL

El campo se registra con type: string, lo que habilita los operadores de cadena de igualdad exacta en JQL. A partir de la versión 3.1.0 el valor almacenado incluye el código de marcación, por lo que las búsquedas deben incluirlo:

Operador	Soportado	Ejemplo
=	✅	"Teléfono del solicitante" = "+51 943 824 375"
!=	✅	"Teléfono del solicitante" != "+51 000 000 000"
in / not in	✅	"Teléfono del solicitante" in ("+51 943 824 375", "+51 998 765 432")
is EMPTY / is not EMPTY	✅	"Teléfono 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 teléfonos use el operador in (...).

Cuando el campo es opcional

Si el campo no está marcado como obligatorio en su proyecto, puede dejarse en blanco sin que se produzca ningún error y el issue se guarda sin valor.

Novedades en la versión 3.1.0

Actualización desde v3.0.0

A partir de la versión 3.1.0, el campo Phone Number Field incorpora un selector de país y permite definir el país por defecto por contexto desde la pantalla Contexts and default value del campo.

Las actualizaciones del complemento se aplican automáticamente en Jira Cloud; no es necesaria ninguna acción manual por parte del administrador para recibir esta versión.

Los números guardados con versiones anteriores siguen siendo válidos. Al editar un valor existente, el complemento separa automáticamente el país y el número local.