Campo de Referencia en Odoo: Guía Completa

Introduction

La mayoría de los desarrolladores de Odoo optan por el campo Many2one cuando necesitan vincular un registro a otro. Funciona perfectamente en la gran mayoría de los casos. Pero a veces te encuentras en una situación en la que el documento vinculado podría ser uno de varios tipos diferentes: una orden de venta, una orden de compra, una orden de fabricación, o algo completamente diferente dependiendo del contexto. Eso es exactamente para lo que se creó el campo de Referencia.

El campo de Referencia es uno de los tipos de campo más flexibles en el ORM de Odoo. Te permite crear un enlace a un registro de cualquier modelo en una lista predefinida, en lugar de apuntar siempre al mismo modelo. El usuario primero selecciona el tipo de documento, luego elige el registro específico. El resultado es un enlace polimórfico que puede adaptarse a diferentes flujos de trabajo.

Esta guía cubre lo que almacena el campo de Referencia, cómo se comporta en el modelo de datos de Odoo, cómo crearlo y personalizarlo utilizando Odoo Studio o Python, y casos de uso empresarial prácticos donde realmente añade valor.

What is the Reference Field in Odoo

En el ORM de Odoo, el campo Reference es un tipo de campo especial que almacena un enlace a un registro de cualquier modelo que incluyas en su lista de selection. Esto lo hace fundamentalmente diferente de un campo Many2one, que siempre apunta a un modelo fijo.

En la base de datos, el campo Reference almacena su valor como una cadena de texto simple en el formato model_name,record_id. Por ejemplo, una referencia al número de orden de venta 42 se almacenaría como sale.order,42. Esto es importante entender si alguna vez necesitas consultar o filtrar estos registros directamente.

Desde la perspectiva de la interfaz de usuario, un campo Reference aparece como una entrada de dos pasos. El usuario primero selecciona un tipo de documento de una lista desplegable (por ejemplo: Orden de Venta, Factura o Tarea de Proyecto), y luego elige el registro específico de ese modelo utilizando un campo de búsqueda. La interfaz es limpia y directa una vez que los usuarios entienden la selección en dos pasos.

Aquí está lo que una definición básica de campo Reference se ve en Python:

from odoo import fields, models

class HelpDeskTicket(models.Model):
    _inherit = 'helpdesk.ticket'

    related_document = fields.Reference(
        selection=[
            ('sale.order', 'Orden de Venta'),
            ('purchase.order', 'Orden de Compra'),
            ('account.move', 'Factura'),
            ('project.task', 'Tarea de Proyecto'),
        ],
        string='Documento Relacionado',
    )

El parámetro selection es una lista de tuplas. Cada tupla contiene el nombre técnico del modelo (como sale.order) y la etiqueta legible por humanos que los usuarios verán en la lista desplegable. Tú controlas exactamente qué modelos están disponibles en esta lista.

También hay una variante dinámica donde la lista de selección se llena desde la tabla ir.model en tiempo de ejecución, haciendo que todos los modelos instalados estén disponibles. Esto es útil para herramientas altamente configurables, pero puede volverse abrumador para los usuarios finales si no se filtra adecuadamente.

En Odoo Studio, el campo Reference está disponible en el panel de tipos de campo y etiquetado como Reference. Al agregarlo a través de Studio, puedes configurar la lista de modelos seleccionables directamente desde la interfaz sin escribir ningún código. Esto lo convierte en una de las opciones más accesibles entre los campos avanzados de Odoo Studio.

How the Field Works

Entender cómo el campo Reference almacena y recupera datos es clave para usarlo correctamente en tus proyectos de desarrollo de Odoo.

Almacenamiento en la Base de Datos

A diferencia de un campo Many2one, que almacena solo un entero (la clave externa), el campo Reference almacena un valor de cadena que incluye tanto el nombre del modelo como el ID del registro. Por ejemplo: sale.order,15. Esto se almacena en una columna VARCHAR en PostgreSQL. Significa que la base de datos no impone ninguna restricción de clave externa en esta columna, lo cual es una elección de diseño deliberada para soportar la naturaleza polimórfica del campo.

Debido a que no hay una clave externa a nivel de base de datos, Odoo no limpia automáticamente los valores del campo Reference cuando se elimina el registro vinculado. Si se elimina una orden de venta, un campo Reference que apunta a ella seguirá conteniendo el antiguo valor de cadena. Esta es una de las diferencias de comportamiento más importantes a tener en cuenta durante el desarrollo de Odoo.

Accediendo al Registro Vinculado en Python

Cuando lees un valor de campo de Referencia en Python, Odoo devuelve el objeto de registro real del modelo referenciado. Puedes acceder a sus campos directamente, tal como lo harías con un resultado Many2one. Si el campo está vacío, devuelve False.

ticket = self.env['helpdesk.ticket'].browse(1)
doc = ticket.related_document

if doc:
    print(doc._name)   # por ejemplo, 'sale.order'
    print(doc.name)    # por ejemplo, 'S00042'
    print(doc.id)      # por ejemplo, 15

Este es uno de los aspectos convenientes de la abstracción ORM de Odoo. Aunque el almacenamiento subyacente es una cadena de texto simple, el marco lo resuelve a un objeto de registro adecuado cuando lo accedes en el código.

Atributos Clave del Campo

Estos son los atributos más relevantes que puedes configurar en un campo de Referencia en el marco de Odoo:

• selection: Una lista de tuplas que definen qué modelos son seleccionables. También puede ser un nombre de método (cadena) que devuelve dicha lista dinámicamente.
• string: La etiqueta del campo que se muestra a los usuarios en la interfaz.
• required: Hace que el campo sea obligatorio. El usuario debe seleccionar tanto un tipo de modelo como un registro antes de guardar.
• readonly: Impide que los usuarios modifiquen el valor del campo desde la interfaz. Útil cuando la referencia se establece programáticamente.
• help: Un tooltip que se muestra cuando el usuario pasa el cursor sobre la etiqueta del campo. Útil para guiar a los usuarios sobre qué seleccionar.
• compute: Al igual que cualquier otro tipo de campo en Odoo, un campo de Referencia puede ser calculado dinámicamente utilizando un método de Python. Esto es útil para establecer automáticamente una referencia basada en la lógica empresarial.

Filtrado y Búsqueda

Debido a que el valor se almacena como una cadena de texto simple, filtrar en un campo de Referencia requiere una sintaxis de dominio específica. Para buscar registros vinculados a un documento específico, necesitas componer el valor de la cadena tú mismo:

tickets = self.env['helpdesk.ticket'].search([
    ('related_document', '=', 'sale.order,15')
])

También puedes filtrar por tipo de modelo utilizando un operador like:

tickets = self.env['helpdesk.ticket'].search([
    ('related_document', 'like', 'sale.order,')
])

Ten en cuenta este comportamiento de filtrado basado en cadenas al diseñar informes o campos computados que dependan de los valores del campo de Referencia. Se comporta de manera diferente a un filtro de dominio típico de Many2one.

Casos de Uso Empresariales

El campo de Referencia es más valioso en situaciones donde el mismo tipo de enlace contextual puede apuntar a documentos de diferentes tipos dependiendo de la situación. Aquí hay cinco ejemplos prácticos de flujos de trabajo empresariales reales.

1. Tickets de Helpdesk Vinculados a Cualquier Documento

Un equipo de soporte maneja tickets que pueden relacionarse con cosas muy diferentes: una disputa de factura, un problema de entrega, una pregunta sobre un contrato o un producto defectuoso. En lugar de crear un campo separado para cada tipo de documento, un solo campo de Referencia en el modelo de ticket permite al agente vincularse al documento que sea relevante. El agente elige el tipo primero (Factura, Orden de Venta, Entrega, etc.) y luego elige el registro específico. Todo el contexto está en un solo campo.

2. Actividades de CRM Vinculadas a Múltiples Documentos de Origen

En un equipo de ventas, las actividades y tareas de seguimiento a veces provienen de diferentes fuentes: un lead, una cotización, un contrato existente o un caso de soporte. Un campo de Referencia en un modelo de actividad personalizado o nota de CRM permite a los vendedores etiquetar el documento de origen sin estar atados a un solo modelo. Esto es un ajuste natural para el campo de Referencia en una personalización de CRM de Odoo.

3. Notas y Anotaciones a Través de Módulos

Algunas empresas construyen un modelo simple de notas internas o anotaciones para registrar observaciones en diferentes objetos de negocio. Un campo de Referencia permite que un único registro de nota se adjunte a un registro de cliente, una tarea de proyecto, una orden de fabricación o una orden de compra, todo dentro del mismo campo. Esto evita duplicar el modelo de nota para cada tipo de documento.

4. Flujo de Trabajo de Aprobación de Documentos

Al implementar un flujo de trabajo de aprobación genérico, la solicitud de aprobación debe apuntar al documento que se está aprobando. Dado que las aprobaciones pueden aplicarse a órdenes de compra, informes de gastos, solicitudes de licencia o contratos, un campo de Referencia en el modelo de aprobación mantiene la arquitectura limpia. La misma lógica de aprobación maneja todos los tipos de documentos sin necesidad de modelos separados para cada uno.

5. Informes de Gastos Vinculados a Proyectos u Órdenes de Clientes

En algunas configuraciones contables, un gasto necesita estar vinculado a un proyecto de cliente o a una orden de venta dependiendo de la naturaleza del costo. Un campo de Referencia con tanto project.project como sale.order en su lista de selección le da al contador la flexibilidad de adjuntar el gasto al documento que corresponda. Esto es particularmente útil en empresas de servicios profesionales y consultorías que utilizan Odoo.

Creación o Personalización del Campo de Referencia

Hay dos formas principales de agregar un campo de Referencia a un modelo de Odoo: utilizando Odoo Studio para un enfoque sin código, o escribiéndolo directamente en Python para tener control total.

Usando Odoo Studio

Odoo Studio facilita la adición de un campo de Referencia a cualquier formulario sin tocar el código. Abre Studio en el modelo que deseas extender, ve al panel de Campos y agrega un nuevo campo de tipo Referencia. Se te pedirá que selecciones qué modelos deben aparecer en la lista desplegable. Studio almacena el campo como un campo manual con un prefijo x_, al igual que otros campos de Odoo Studio creados a través de la interfaz.

Este enfoque es ideal para personalizaciones rápidas y para analistas de negocio que desean extender formularios sin la participación de desarrolladores. Ten en cuenta que los campos de Referencia creados en Studio pueden tener un soporte limitado para configuraciones avanzadas como métodos de selección dinámica o valores computados.

Implementación Técnica en Python

Para un enfoque completo de desarrollo en Odoo, define el campo de Referencia directamente en un modelo de Python. Aquí hay un ejemplo más completo que muestra cómo crear un campo de Referencia con un método de selección dinámica:

from odoo import api, fields, models

class ApprovalRequest(models.Model):
    _name = 'approval.request'
    _description = 'Solicitud de Aprobación'

    name = fields.Char(string='Nombre de la Solicitud', required=True)

    @api.model
    def _get_document_types(self):
        return [
            ('purchase.order', 'Orden de Compra'),
            ('hr.expense.sheet', 'Informe de Gastos'),
            ('hr.leave', 'Solicitud de Tiempo Libre'),
            ('sale.order', 'Orden de Venta'),
        ]

    document_ref = fields.Reference(
        selection='_get_document_types',
        string='Documento',
        help='Selecciona el documento al que se relaciona esta aprobación.',
    )

Usar un método para el selection (pasando su nombre como una cadena) te da más flexibilidad. Puedes agregar lógica condicional, filtrar según los módulos instalados o construir la lista dinámicamente a partir de registros de configuración.

Creando a través de la API XML-RPC

También puedes crear un campo de Referencia programáticamente utilizando la API XML-RPC de Odoo. Esto es útil al implementar campos como parte de un cuaderno de configuración remota. El tipo de campo a utilizar es reference y la selección se pasa como una representación en cadena de la lista:

field_id = models.execute_kw(
    ODOO_DB, uid, ODOO_API_KEY,
    'ir.model.fields', 'create',
    [{
        'name': 'x_related_document',
        'field_description': 'Documento Relacionado',
        'model_id': model_id,
        'ttype': 'reference',
        'selection': "[('sale.order', 'Orden de Venta'), ('purchase.order', 'Orden de Compra')]",
        'state': 'manual',
    }]
)

Ten en cuenta que al crear un campo de Referencia a través de la API, el valor de selection se pasa como una cadena evaluable en Python en lugar de una lista real. Así es como Odoo lo almacena y lo lee de la tabla ir.model.fields.

Mejores Prácticas

Aquí están las pautas más útiles a seguir al trabajar con campos de Referencia en tu modelo de datos de Odoo.

• Mantén la lista de selección corta y significativa. No incluyas todos los modelos solo porque puedes. Limita la lista a los tipos de documentos que realmente tienen sentido para el caso de uso. Una lista larga confunde a los usuarios y hace que el campo sea más difícil de usar correctamente.
• Usa Many2one cuando siempre te vincules al mismo modelo. El campo de Referencia está diseñado para relaciones polimórficas. Si el modelo vinculado nunca cambia, un campo estándar Many2one es más simple, más rápido de consultar y mejor soportado por las herramientas de informes de Odoo.
• Siempre verifica los valores nulos en los campos computados. Cuando un campo de Referencia está vacío, devuelve False en Python. Cualquier código que acceda al registro vinculado debe verificar esto primero para evitar errores.
• Maneja referencias huérfanas en acciones automatizadas. Dado que la base de datos no impone integridad referencial en los campos de Referencia, es una buena idea agregar una acción automatizada o una acción programada que verifique periódicamente y limpie referencias obsoletas que apunten a registros eliminados.
• Usa etiquetas descriptivas para cada modelo en la selección. El segundo elemento de cada tupla es lo que los usuarios ven en el menú desplegable. Usa etiquetas claras y amigables para el negocio en lugar de nombres de modelos técnicos. Escribe "Factura de Cliente" en lugar de "account.move".
• Documenta el campo claramente en tus especificaciones técnicas. Debido a que los campos de Referencia se comportan de manera diferente a los campos estándar Many2one, cualquier desarrollador que herede tu código se beneficiará de una explicación clara de por qué se eligió una Referencia y a qué modelos se vincula.

Errores Comunes

Estos son los errores que vemos con más frecuencia cuando los desarrolladores o analistas de negocio trabajan con campos de Referencia por primera vez.

Tratarlo como un Many2one en Filtros de Dominio

A veces, los desarrolladores escriben filtros de dominio para un campo de Referencia utilizando la misma sintaxis que un Many2one, por ejemplo [('document_ref', '=', 15)]. Esto no funcionará. El valor almacenado es una cadena como sale.order,15, no solo un entero. Debes componer el valor de cadena completo al construir filtros de dominio en un campo de Referencia.

Olvidar que los Registros Eliminados Dejan Valores Huérfanos

Debido a que no hay una restricción de clave externa en la base de datos, eliminar un registro referenciado no borra el valor del campo de Referencia. Si se elimina un pedido de venta y un ticket aún tiene sale.order,42 en su campo de Referencia, leer ese campo devolverá False en lugar de generar un error. El código que depende de que la referencia sea válida siempre debe manejar este caso.

Abusar de la Selección Dinámica de Todos los Modelos

Odoo te permite pasar un método para la selection que devuelve todos los modelos instalados de ir.model. Si bien esto es poderoso, casi siempre es demasiado amplio para un campo orientado al usuario. Presentar cientos de modelos en un menú desplegable es confuso y conduce a entradas de datos incorrectas. Siempre restringe la selección a una lista curada de tipos de documentos significativos.

Esperar Agrupación Nativa en Informes

Los campos de Referencia se almacenan como cadenas de texto simples en la base de datos. No son claves externas, por lo que la funcionalidad estándar de agrupación y pivote de Odoo no funciona en ellos de la misma manera que lo hace en los campos Many2one. Si necesitas agrupar o agregar registros por su documento vinculado, deberás manejar esto a través de código personalizado o un campo calculado que extraiga el nombre del modelo como una selección separada o campo char.

Confundir Referencia y Many2one en Odoo Studio

Al usar Odoo Studio, algunos usuarios confunden el campo de Referencia y el campo Many2one porque ambos te permiten vincular a otro registro. La diferencia clave es que un Many2one siempre se vincula a un modelo específico (lo eliges en el momento de crear el campo y nunca cambia), mientras que un campo de Referencia permite al usuario elegir el modelo cada vez que completa el campo. Si creaste un Many2one cuando necesitabas una Referencia, deberás reconstruir el campo en lugar de intentar adaptar el existente.

Conclusión

El campo de Referencia llena un vacío que el campo Many2one no puede cubrir por sí solo. Cuando un enlace necesita ser lo suficientemente flexible como para apuntar a diferentes tipos de documentos dependiendo de la situación, el campo de Referencia es la herramienta adecuada en el marco de Odoo. Es sencillo de definir, funciona con Odoo Studio para configuraciones sin código e integra de manera natural en modelos de Python para implementaciones técnicas.

Las principales cosas a tener en cuenta son el formato de almacenamiento basado en cadenas, la ausencia de limpieza automática de claves foráneas y la necesidad de filtrar utilizando valores de cadena compuestos en lugar de ID simples. Una vez que comprendas esas diferencias, el campo se comporta de manera predecible y confiable en todo tu modelo de datos de Odoo.

Ya sea que estés construyendo un flujo de trabajo de aprobación genérico, vinculando tickets de soporte a diferentes tipos de documentos, o diseñando un sistema de notas flexible que abarque múltiples módulos, el campo de Referencia te ofrece una solución limpia y mantenible sin necesidad de duplicar tu lógica para cada tipo de modelo.

¿Necesitas ayuda con tu implementación de Odoo?

En Dasolo, ayudamos a las empresas a implementar, personalizar y optimizar Odoo para que se ajuste a sus flujos de trabajo comerciales reales. Ya sea que necesites construir lógica de campo personalizada, diseñar un modelo de datos desde cero, o extender una configuración existente de Odoo con nueva funcionalidad, nuestro equipo tiene la profundidad técnica para hacerlo correctamente.

Si estás trabajando en un proyecto de Odoo y necesitas orientación sobre tipos de campos, arquitectura de datos o mejores prácticas de desarrollo, no dudes en ponerte en contacto. Estamos encantados de discutir tu situación y ayudarte a encontrar el enfoque adecuado.

Contacta a Dasolo