Introducción
Cada vez que un usuario elige una prioridad de lead, selecciona un método de pago o marca un producto como activo o archivado en Odoo, es muy probable que esté interactuando con un campo de selección. Es uno de los tipos de campo más prácticos en el marco de Odoo y uno de los más importantes de entender si deseas construir modelos de datos limpios y fiables.
A diferencia de un campo de texto libre donde los usuarios pueden escribir cualquier cosa, el campo de selección restringe la entrada a una lista predefinida de opciones. Esa restricción es el objetivo principal. Mantiene tus datos consistentes, hace que el filtrado y la elaboración de informes sean más precisos y previene los errores tipográficos y variaciones que silenciosamente rompen agregaciones y paneles de control con el tiempo.
Esta guía cubre todo, desde lo que almacena el campo y cómo aparece en la interfaz, hasta cómo crearlo y personalizarlo a través de Odoo Studio, módulos de Python o la API XML-RPC. También encontrarás ejemplos prácticos de flujos de trabajo empresariales reales y una lista de errores comunes a evitar.
¿Qué es el campo de selección en Odoo?
En el ORM de Odoo, el campo de selección almacena un valor de cadena elegido de una lista fija de opciones. Cada opción se define como un par clave-valor: la clave es lo que se guarda en la base de datos y la etiqueta es lo que el usuario ve en la interfaz.
Por ejemplo, un campo de prioridad podría definirse con las siguientes opciones:
priority = fields.Selection([
('0', 'Normal'),
('1', 'Bajo'),
('2', 'Alto'),
('3', 'Muy Alto'),
], string='Prioridad', default='0')En este ejemplo, '0', '1', '2' y '3' son las claves almacenadas en la base de datos. Las etiquetas Normal, Bajo, Alto y Muy Alto son lo que los usuarios ven en pantalla. Esta separación es muy importante cuando se trata de cambiar etiquetas más tarde sin romper registros existentes.
En la interfaz, un campo de Selección aparece como una lista desplegable en las vistas de formulario. En las vistas de lista, muestra la etiqueta legible por humanos. Al usar el widget badge, cada opción se representa como una etiqueta de color, lo que hace que el valor sea inmediatamente visible en vistas de lista densas.
En Odoo Studio, este tipo de campo se llama campo de Selección. Cuando se crea a través de Studio, recibe un prefijo x_studio_. Cuando se crea a través de código o la API XML-RPC, eliges el nombre técnico.
Cómo funciona el campo
En el modelo de datos de Odoo, los campos de Selección se almacenan en PostgreSQL como una columna VARCHAR. La base de datos solo almacena la clave, nunca la etiqueta. Esto es importante tener en cuenta al escribir filtros de dominio o acciones del servidor, ya que necesitas usar la clave, no el valor legible por humanos.
Por ejemplo, para buscar todos los leads con alta prioridad, tu dominio sería [('priority', '=', '2')], no [('priority', '=', 'Alto')].
Atributos Clave del Campo
Aquí están las propiedades más importantes de un campo de Selección en el marco de Odoo:
- selection: La lista de
(clave, etiqueta)tuplas que definen las opciones disponibles. Esto también puede ser un nombre de método (cadena) que devuelve una lista dinámicamente. - default: La clave de la opción a utilizar cuando aún no se ha establecido ningún valor. Si se omite, el campo comienza vacío.
- required: Obliga al usuario a elegir una opción antes de guardar. Combinado con un valor predeterminado, este es un patrón común para campos de estado.
- selection_add: Se utiliza en la herencia de módulos para agregar nuevas opciones a un campo de Selección existente sin redefinir toda la lista. Este es el enfoque correcto al extender un campo nativo.
- ondelete: Funciona junto con
selection_addpara definir qué sucede con los registros que tienen una opción eliminada cuando se desinstala el módulo que la agregó.
Listas de Selección Estáticas vs Dinámicas
Por defecto, la lista de opciones se define de manera estática en la declaración del campo. Pero también puedes pasar un nombre de método como una cadena al parámetro selection. Odoo llamará a ese método en tiempo de ejecución para construir la lista, lo que te permite mostrar diferentes opciones dependiendo del usuario actual, la empresa actual o cualquier otro contexto.
contract_type = fields.Selection(
selection='_get_contract_types',
string='Tipo de Contrato'
)
def _get_contract_types(self):
if self.env.user.has_group('hr.group_hr_manager'):
return [('permanent', 'Permanente'), ('fixed', 'Plazo Fijo'), ('interim', 'Interino')]
return [('permanent', 'Permanente'), ('fixed', 'Plazo Fijo')]Cómo Aparece en las Vistas
En una vista de formulario, un campo de Selección se renderiza como un menú desplegable estándar. También puedes usar el atributo widget="badge" para renderizarlo como una etiqueta de color, que funciona bien en vistas de lista y kanban para campos de estado. El atributo widget="radio" renderiza las opciones como botones de radio en línea, lo que se adapta a campos con un pequeño número de opciones donde deseas que todas las opciones sean visibles a la vez.
Interacción con el ORM de Odoo
Leer y escribir campos de Selección en el ORM de Odoo funciona de manera sencilla. Asignas la clave directamente, y el marco maneja automáticamente el mapeo de visualización. Al leer un registro a través de la API XML-RPC con fields_get, el atributo selection del campo incluye la lista completa de pares [clave, etiqueta], que puedes usar para construir tu propia lógica de visualización en herramientas externas.
Casos de uso empresarial
El campo de Selección aparece en prácticamente todos los módulos en una implementación estándar de Odoo. Aquí hay cinco ejemplos concretos de flujos de trabajo empresariales comunes.
CRM: Prioridad de Lead y Tipo de Etapa de Pipeline
El campo de prioridad en los leads de CRM es un campo de Selección nativo con cuatro niveles: Normal, Bajo, Alto y Muy Alto. Los equipos de ventas lo utilizan para centrar su atención en las oportunidades más prometedoras. Se alimenta directamente en la codificación de colores de la vista Kanban y puede usarse en acciones automatizadas para activar tareas de seguimiento cuando un lead se escalona. Obtener la distribución de prioridades correcta es una de las primeras mejoras en la calidad de los datos que la mayoría de los equipos de CRM realizan después de entrar en funcionamiento.
Ventas: Término de Pago y Política de Facturación
El campo invoice_policy en los productos es un campo de Selección que controla si la facturación se basa en las cantidades ordenadas o en las cantidades entregadas. Este único campo determina todo el flujo de facturación para un producto. De manera similar, el modo de facturación en los contratos de suscripción utiliza un campo de Selección para distinguir entre ciclos de facturación prepagados y postpagados. Ambos son buenos ejemplos de campos de Selección que tienen consecuencias significativas en los flujos de trabajo financieros.
Inventario: Estados de Calidad de Producto y Lote
En los flujos de trabajo de fabricación y control de calidad, se utilizan campos de Selección para rastrear el estado de lotes, números de serie y órdenes de reparación. El campo de estado de la orden de reparación, por ejemplo, pasa por valores como borrador, confirmado, en reparación, listo y hecho. Cada transición puede activar correos electrónicos automáticos, movimientos de inventario o entradas contables. El campo de Selección actúa como el punto de control alrededor del cual se construye todo el flujo de trabajo.
Contabilidad: Método de Pago y Tipo de Diario
El campo de tipo de diario en Odoo Contabilidad es un campo de Selección que distingue entre diarios de venta, diarios de compra, diarios de efectivo y diarios bancarios. Odoo utiliza este valor para aplicar la lógica de publicación correcta, determinar qué cuentas están disponibles y restringir ciertas operaciones a los tipos de diario adecuados. Este es un buen ejemplo de un campo de Selección que controla las reglas de negocio en lugar de simplemente etiquetar un registro.
RRHH: Tipo de Empleo y Estado del Contrato
Los equipos de RRHH utilizan campos de Selección para rastrear tipos de empleo, estados de contrato y estados de solicitudes de licencia. El estado del contrato, por ejemplo, pasa de nuevo a abierto, a expirado o cancelado. Las automatizaciones pueden notificar al gerente de RRHH un mes antes de que un contrato expire, activar listas de verificación de incorporación cuando un nuevo empleado comienza y actualizar las reglas de nómina según el tipo de empleo. El campo de Selección contiene el estado que impulsa toda esta lógica.
Creación o personalización del campo de selección
Hay tres formas principales de agregar un campo de Selección a un modelo de Odoo, dependiendo de tu configuración y si necesitas que el cambio esté controlado por versiones o aplicado programáticamente.
Usando Odoo Studio (Sin Código)
Odoo Studio es la herramienta integrada de bajo código para agregar campos sin escribir ningún Python. Para agregar un campo de Selección a través de Studio:
- Abre Odoo Studio desde el menú principal.
- Navega hasta el formulario donde deseas el campo.
- Arrastra un campo de Selección desde la barra lateral al formulario.
- Agrega tus opciones en el panel de propiedades del campo, ingresando una etiqueta para cada opción.
- Opcionalmente, establece un valor predeterminado y marca el campo como obligatorio.
- Guarda y cierra Studio.
Studio almacena cada opción con una clave generada automáticamente y la etiqueta que proporcionaste. El campo recibe un prefijo x_studio_ y se añade automáticamente a la vista del formulario. Este es el enfoque más rápido para agregar un campo de Selección durante una sesión de análisis de negocio con un cliente.
Usando Python en un Módulo Personalizado
Para los desarrolladores que construyen módulos de Odoo, los campos de Selección se definen en archivos de modelo de Python. Este es el enfoque recomendado para personalizaciones que necesitan ser controladas por versiones y desplegadas en múltiples entornos:
from odoo import fields, models
class SaleOrder(models.Model):
_inherit = 'sale.order'
x_delivery_slot = fields.Selection([
('morning', 'Mañana (8h - 12h)'),
('afternoon', 'Tarde (13h - 17h)'),
('evening', 'Noche (18h - 20h)'),
], string='Franja Horaria de Entrega', default='morning')Después de definir el campo, lo agregas al archivo XML de vista relevante para que aparezca en la interfaz. Odoo maneja la creación de la columna de base de datos cuando instalas o actualizas el módulo.
Al extender un campo nativo con nuevas opciones, usa selection_add en lugar de redefinir el campo:
class SaleOrder(models.Model):
_inherit = 'sale.order'
state = fields.Selection(
selection_add=[('custom_approval', 'Pendiente de Aprobación')],
ondelete={'custom_approval': 'establecer predeterminado'}
)Uso de la API XML-RPC
Si estás gestionando personalizaciones de Odoo programáticamente, por ejemplo, como parte de un pipeline de despliegue o un cuaderno de configuración remota, puedes crear campos de Selección a través de la API XML-RPC:
field_id = models.execute_kw(
ODOO_DB, uid, ODOO_API_KEY,
'ir.model.fields', 'create',
[{
'name': 'x_contract_category',
'field_description': 'Categoría de Contrato',
'model_id': model_id,
'ttype': 'selection',
'selection': "[('standard', 'Estándar'), ('premium', 'Premium'), ('custom', 'Personalizado')]",
'state': 'manual',
}]
)Ten en cuenta que al crear un campo de Selección a través de la API, el valor de selection se pasa como una representación en cadena de la lista de Python. El valor state: manual le indica a Odoo que este campo fue creado manualmente, que es la configuración correcta para los campos creados a través de Studio o la API. Así es como Dasolo maneja la creación remota de campos para los clientes como parte de scripts de configuración automatizados.
Mejores prácticas
1. Usa claves significativas y estables
La clave es lo que se almacena en la base de datos y se utiliza en filtros de dominio, acciones automatizadas y lógica del lado del servidor. Elige una clave que describa claramente la opción y que no necesites cambiar más tarde. Las cadenas cortas en minúsculas funcionan bien: 'draft', 'confirmed', 'cancelled'. Evita claves numéricas a menos que la secuencia realmente importe, ya que dificultan la lectura y comprensión de tu código meses después.
2. Mantén la lista corta y exhaustiva
Un campo de Selección con más de ocho o diez opciones suele ser una señal de que el campo está tratando de hacer demasiado. Si la lista sigue creciendo, considera si una relación Many2one con un modelo de configuración sería más apropiada. Eso le da a los usuarios la capacidad de gestionar las opciones ellos mismos a través de la interfaz, sin requerir que un desarrollador actualice el código o la definición del campo de la base de datos.
3. Siempre establece un valor predeterminado para los campos requeridos
Si un campo de Selección es requerido, también establece un valor predeterminado sensato. Esto previene errores de validación cuando se crean registros programáticamente, a través de importaciones o mediante la API, donde el usuario no está presente para hacer una selección. El valor predeterminado debe representar el estado más común o menos comprometido en el flujo de trabajo.
4. Usa selection_add al extender campos nativos
Si necesitas agregar opciones a un campo existente de Odoo en un módulo personalizado, usa selection_add en lugar de redefinir el campo completo. Esto es más seguro y más compatible con otros módulos que también pueden extender el mismo campo. Siempre empareja esto con el parámetro ondelete para manejar lo que sucede cuando tu módulo es desinstalado.
5. Utiliza el widget de insignia para visibilidad en vistas de lista
En las vistas de lista y kanban, la representación predeterminada de un campo de Selección es solo texto. Agregar el widget="badge" atributo en el XML de la vista convierte cada valor en una etiqueta de color, lo que hace que el campo sea mucho más fácil de escanear de un vistazo. Esto es especialmente útil para campos de estado donde los usuarios necesitan identificar rápidamente los registros que requieren atención.
Errores comunes
Cambiar una clave rompe los datos existentes
La etiqueta de una opción de Selección se puede cambiar de forma segura en cualquier momento, ya que solo se almacena la clave en la base de datos. Sin embargo, la clave nunca debe cambiar una vez que existen registros con ese valor. Si cambias el nombre de una clave, todos los registros existentes con la clave antigua mostrarán un valor vacío o inválido en la interfaz, y cualquier filtro de dominio o automatización que utilice la clave antigua dejará de funcionar silenciosamente. Si una clave necesita cambiar genuinamente, debes ejecutar un script de migración de datos para actualizar primero todos los registros existentes.
Eliminar una opción deja registros huérfanos
Si eliminas una opción de la lista mientras los registros aún mantienen esa clave, esos registros mostrarán un valor faltante o roto. Antes de eliminar cualquier opción, busca registros que aún la utilicen y actualízalos a un valor válido o archívalos. Este es un problema común durante proyectos de limpieza de datos cuando la lista de opciones fue diseñada sin suficiente análisis previo.
Usar la etiqueta en lugar de la clave en filtros de dominio
Un error muy común, especialmente para usuarios menos técnicos que escriben reglas de automatización en la interfaz de Odoo, es filtrar por la etiqueta legible por humanos en lugar de la clave almacenada. Esto produce un dominio que devuelve cero resultados sin generar un error, lo que puede ser difícil de diagnosticar. Siempre verifica la definición del campo para confirmar qué clave corresponde a qué etiqueta antes de escribir un filtro.
Usar un campo de Selección donde un Many2one es más apropiado
Si la lista de opciones cambia con frecuencia, si los usuarios necesitan gestionarla ellos mismos sin la intervención de un desarrollador, o si las opciones llevan atributos adicionales como un color, una secuencia o una cuenta vinculada, entonces una relación Many2one con un modelo de configuración es la mejor opción. Los campos de Selección son ideales para listas estables gestionadas por desarrolladores. Para cualquier cosa más dinámica, Many2one es más mantenible a largo plazo.
No manejar el valor vacío en la lógica del lado del servidor
Un campo de Selección que no es obligatorio puede contener un valor False cuando no se ha seleccionado ninguna opción. Si tu código Python o acción automatizada compara el valor del campo con una cadena sin verificar primero si es False, obtendrás un comportamiento inesperado o errores. Siempre maneja el caso vacío explícitamente en las acciones del servidor y en los campos calculados que dependen de un campo de Selección.
Conclusión
El campo de selección es uno de esos tipos de campo que parece simple, pero tiene una verdadera profundidad una vez que entiendes cómo funciona internamente. Conocer la diferencia entre una clave y una etiqueta, entender cuándo usar selection_add en lugar de redefinir un campo, y reconocer cuándo un Many2one te serviría mejor son las distinciones que separan una implementación de Odoo bien diseñada de una que causa problemas un año después.
Ya sea que estés añadiendo un tipo de contrato a través de Odoo Studio, definiendo un campo de franja de entrega en un módulo de Python personalizado, o creando un campo de estado de calidad a través de la API, los patrones descritos en esta guía te brindan lo que necesitas para tomar la decisión correcta para tu caso de uso.
En el modelo de datos de Odoo, el campo de selección es una de las herramientas principales para hacer cumplir la calidad de los datos en la fuente. Usado correctamente, mantiene tus registros limpios, tus informes precisos y tus automatizaciones fiables.
En Dasolo, ayudamos a las empresas a implementar, personalizar y optimizar Odoo en todos los departamentos. Ya sea que necesites ayuda para diseñar un modelo de datos limpio, añadir campos personalizados a tus flujos de trabajo, o construir un módulo completo de Odoo desde cero, nuestro equipo está aquí para ayudar. Contáctanos y hablemos sobre tu proyecto de Odoo.