- crear setups manualmente
- crear series numéricas
- rellenar configuraciones básicas
- rezar para que nadie se haya olvidado algo en producción
- inicialicen automáticamente sus datos
- creen configuraciones básicas
- asignen series numéricas
- y preparen upgrades futuros
Por ejemplo:
- una tabla de Setup
- un No. Series
- valores por defecto
- registros de configuración
Un ejemplo es nuestra extensión que gestiona Statistical Accounts.
Para que el sistema funcione correctamente necesitamos:
- un Setup record
- una serie numérica para crear nuevos registros
La forma clásica (y poco elegante) de resolver esto es:
- Instalar extensión
- Abrir página de Setup
- Crear registro manualmente
- Crear No. Series
- Asignarla
Esto tiene varios problemas:
- depende del usuario
- es fácil olvidarlo
- rompe automatizaciones
- complica despliegues CI/CD
El objetivo del BC Way es simple:
Cuando la extensión se instala, todo debe quedar listo para usar.
Business Central ofrece dos tipos de codeunits especialmente diseñadas para gestionar instalaciones y upgrades:
Install Codeunits
Se ejecutan automáticamente cuando se instala la extensión.
Sirven para:
- inicializar datos
- crear setups
- preparar configuraciones iniciales
- crear series numéricas
- Reportar por telemetría el estado de la instalación
Upgrade Codeunits
Se ejecutan cuando la extensión se actualiza a una nueva versión.
Sirven para:
- migrar datos
- inicializar nuevos campos
- transformar estructuras
- actualizar setups existentes
- Reportar por telemetría el estado de la actualización
Upgrade Tags
Los Upgrade Tags permiten controlar qué migraciones ya se han ejecutado.
Esto evita:
- ejecutar lógica de upgrade varias veces
- romper datos existentes
- repetir migraciones
Es una herramienta fundamental cuando tu extensión evoluciona con el tiempo.
1️⃣ Install Codeunit
Inicializa el Setup y crea una No. Series durante la instalación.
2️⃣ Upgrade Codeunit
Prepara la extensión para futuras migraciones.
3️⃣ Upgrade Tags Codeunit
Registra los tags que controlarán qué upgrades se ejecutan.
Install Codeunit
Esta codeunit se ejecuta cuando se instala la extensión.
El trigger clave es:
trigger OnInstallAppPerCompany()
Aquí detectamos si la extensión se está desplegando por primera vez.
NavApp.GetCurrentModuleInfo(...)
if ModuleInfo.DataVersion().IsEmpty() then
Si es el primer despliegue ejecutamos la inicialización:
DeployInstallationSetup();
Después marcamos todos los Upgrade Tags como ejecutados:
UpgradeTag.SetAllUpgradeTags();
Esto evita que las migraciones se ejecuten tras una instalación limpia.
Pequeño detalle… pero muy importante.
Inicialización del Setup
Durante la instalación llamamos a:
DeployInstallationSetup();
Este método se encarga de:
- Crear el Setup
- Crear una No. Series
- Asignarla al Setup
El patrón típico para inicializar el setup es:
if not Setup.Get() then begin
Setup.Init();
Setup.Insert();
end;
Este patrón asegura que:
- si el setup existe → no se modifica
- si no existe → se crea automáticamente
Creación automática de la No. Series
El siguiente paso es crear una serie numérica por defecto.
La instalación genera una serie específica para la extensión y devuelve el código.
Ese código se asigna al Setup:
Setup."Statistical Acc. Nos." := DefaultSeriesCode;
Setup.Modify();
Resultado:
Cuando el usuario abre la aplicación…
🎉 la serie ya existe y está asignada.
Upgrade Codeunit
Las migraciones futuras se gestionan con una Upgrade Codeunit.
El trigger principal es:
trigger OnUpgradePerCompany()
Aquí irán las migraciones cuando la extensión evolucione.
Por ejemplo:
- rellenar nuevos campos
- transformar datos
- inicializar nuevas configuraciones
Pero siempre controlado con Upgrade Tags.
Upgrade Tags
Los Upgrade Tags registran qué migraciones existen.
Esta codeunit se suscribe al evento:
UpgradeTag → OnGetPerCompanyUpgradeTags
Y registra todos los tags disponibles.
Ejemplo:
PerCompanyUpgradeTags.Add(GetFieldMigrationTag());
PerCompanyUpgradeTags.Add(GetSetupUpgradeTag());
Cada migración debe tener su propio tag único.
Ejemplo:
BCS-60705-StatAccFieldMigration-20260329
Una buena práctica del BC Way es incluir:
- extensión
- objeto
- tipo de migración
- fecha
Porque dentro de dos años…
no recordarás por qué existía ese tag.
Una vez desplegada la extensión, el comportamiento es el siguiente:
Durante la instalación
El sistema:
- ejecuta la Install Codeunit
- crea automáticamente el Setup
- crea la No. Series
- asigna la serie al Setup
Todo sin intervención del usuario.
Durante upgrades futuros
Cuando publiques una nueva versión:
- se ejecutará la Upgrade Codeunit
- se evaluarán los Upgrade Tags
- se ejecutarán sólo las migraciones necesarias
Esto permite evolucionar la extensión sin romper datos existentes.
Uno de los grandes errores en extensiones de Business Central es asumir que alguien configurará el sistema después de instalarla.
En proyectos reales eso termina generando:
- setups incompletos
- errores en producción
- soporte innecesario
Usando Install Codeunits, Upgrade Codeunits y Upgrade Tags conseguimos extensiones que:
- se instalan completamente configuradas
- inicializan sus datos automáticamente
- evolucionan de forma segura
- funcionan bien en despliegues automatizados
En otras palabras:
tu extensión pasa de ser algo que hay que configurar…
a ser algo que simplemente funciona.
Y ese, definitivamente, es el BC Way.
Nos vemos en la próxima parada del BC Scout Path 🧭