BC Blueprint - Job Queue
Un análisis funcional y técnico en profundidad sobre el mecanismo
que ejecuta procesos cuando nadie está mirando; cómo
Job Queue Entry se apoya en Task Scheduler;
qué ocurre desde Ready hasta Finished o
Error; cómo funcionan categorías, prioridades, recurrencia,
reintentos y timeouts; y qué necesita un proceso AL para sobrevivir a
bloqueos, reinicios y ejecuciones duplicadas sin convertir la
automatización en una máquina de fabricar incidencias
nocturnas.
Nota de versión: los nombres, identificadores, límites y responsabilidades de objetos se han contrastado con la documentación pública de Microsoft disponible el 18 de octubre de 2026. Los textos funcionales están en español; los nombres de objetos, campos, procedimientos, eventos y valores AL conservan su denominación original en inglés. Verifica siempre los símbolos y límites aplicables a la versión y modalidad —online u on-premises— de tu entorno.
El proceso que ocurre cuando el usuario ya se ha ido
Business Central está lleno de trabajos que no deberían depender de una persona mirando una barra de progreso:
- ajustar costes de inventario;
- contabilizar valores en G/L;
- sincronizar Dataverse;
- enviar documentos;
- procesar integraciones;
- registrar pedidos en segundo plano;
- limpiar históricos;
- generar informes;
- revisar aprobaciones;
- importar ficheros recibidos;
- reintentar conexiones con servicios externos.
La respuesta habitual es «lo ponemos en la Job Queue».
Suena casi tan completo como «lo subimos a la nube».
Una Job Queue Entry no ejecuta código por el mero hecho
de existir. Define un trabajo, una identidad de ejecución, una política
temporal, un contexto de usuario, una estrategia de reintento y una
relación con la infraestructura de Task Scheduler. Cuando
se establece en Ready, Business Central crea una tarea
programada. Cuando la plataforma dispone de capacidad y ha llegado el
momento permitido, abre una sesión en segundo plano y entrega el trabajo
a Job Queue Dispatcher.
La cola resuelve la orquestación. El código que ejecuta debe resolver todavía:
- qué registros pertenecen al lote;
- cómo evita procesarlos dos veces;
- cómo continúa después de un fallo parcial;
- cuánto bloquea;
- qué considera un error transitorio;
- qué telemetría emite;
- qué usuario y permisos necesita;
- cómo se comporta sin interfaz;
- cómo termina dentro de su ventana y timeout.
Por eso Job Queue no convierte automáticamente un proceso síncrono en un buen proceso asíncrono. Solo permite que sus problemas ocurran sin un usuario delante.
Primero, el modelo mental
Conviene separar cinco piezas que la interfaz presenta como una sola función.
1. La definición:
Job Queue Entry
Describe qué objeto debe ejecutarse, cuándo, con qué recurrencia, usuario, parámetros, categoría, intentos y timeout.
2. La infraestructura:
Task Scheduler
Es el componente de plataforma que conserva y dispara la tarea. Una
entrada en estado Ready se materializa como una scheduled
task identificada por System Task ID.
3. La sesión
Cuando la tarea puede ejecutarse, la plataforma crea una nueva background session. Esa sesión tiene empresa, usuario, idioma, permisos, timeout y recursos propios.
4. El dispatcher y el runner
Job Queue Dispatcher valida la entrada, coordina
categorías y ciclo de vida; Job Queue Start Codeunit o la
ruta de informes inicia el objeto configurado.
5. La evidencia
Job Queue Log Entry,
Error Message Management y la telemetría de Application
Insights explican qué se intentó, cuánto tardó y por qué falló.
La idea clave es esta:
Job Queue Entryes el contrato administrable;Task Scheduleres el mecanismo de plataforma; la background session es el contexto real de ejecución.
La arquitectura completa
Mapa de objetos esenciales
El núcleo actual se encuentra en el namespace
System.Threading y se apoya en componentes de
plataforma.
| ID | Tipo | Objeto | Responsabilidad |
|---|---|---|---|
| 471 | Table | Job Queue Category |
Define categorías utilizadas para serializar trabajos. |
| 472 | Table | Job Queue Entry |
Configuración, planificación, usuario, estado, reintentos, timeout y relación con la scheduled task. |
| 474 | Table | Job Queue Log Entry |
Historial de ejecuciones, duración, estado, error y call stack. |
| 470 | Enum | Job Queue Priority |
Prioridad High, Normal o Low
dentro de una misma categoría. |
| 672 | Page | Job Queue Entries |
Administración y monitorización de entradas. |
| 674 | Page | Job Queue Log Entries |
Consulta del historial y detalles de errores. |
| 448 | Codeunit | Job Queue Dispatcher |
Coordina validación, categorías, ejecución, recurrencia y reprogramación. |
| 449 | Codeunit | Job Queue Start Codeunit |
Ejecuta el codeunit o deriva la ejecución de report configurada. |
| 450 | Codeunit | Job Queue Error Handler |
Registra el error y actualiza la entrada desde una ruta de fallo separada. |
| 453 | Codeunit | Job Queue - Enqueue |
Encola la entrada y crea la scheduled task subyacente. |
| 456 | Codeunit | Job Queue Management |
Alta, ejecución única, control de entradas inactivas y recuperación. |
| 462 | Codeunit | Job Queue Activate Next |
Activa el siguiente trabajo aplicable en una categoría. |
| 2000000175 | System table | Scheduled Task |
Registro de plataforma creado y gestionado por
Task Scheduler. |
| — | AL data type | TaskScheduler |
API de plataforma para crear, activar, consultar o cancelar tareas. |
El mapa no implica que una extensión deba llamar directamente a todos
esos objetos. Job Queue Entry ya publica procedimientos
como ScheduleTask, Restart,
Cancel, ScheduleJobQueueEntry y
ScheduleJobQueueEntryWithParameters; además existen
fachadas de gestión. La arquitectura interna debe conocerse para
diagnosticarla, no para sustituirla con una reproducción artesanal.
Job Queue Entry:
el contrato operativo
La tabla 472 combina varias responsabilidades. Sus campos pueden leerse por grupos.
Identidad y objeto
| Campo | Función |
|---|---|
ID |
GUID funcional de la entrada. |
Entry No. |
Identificador secuencial interno actual. |
Object Type to Run |
Tipo de objeto, normalmente Codeunit o
Report. |
Object ID to Run |
Objeto que ejecutará el trabajo. |
Object Caption to Run |
Descripción visible del objeto. |
Description |
Propósito funcional del trabajo. |
Record ID to Process |
Registro concreto que puede acompañar al trabajo. |
Parameter String |
Parámetro libre de hasta 250 caracteres. |
XML |
Contenido utilizado, entre otros casos, para parámetros de report. |
Planificación
| Campo | Función |
|---|---|
Earliest Start Date/Time |
Momento antes del cual la tarea no debe ejecutarse. |
Expiration Date/Time |
Límite después del cual la entrada deja de ser válida. |
Recurring Job |
Indica que debe calcularse otra ejecución. |
No. of Minutes between Runs |
Intervalo recurrente básico. |
Run on Mondays ... Run on Sundays |
Días habilitados. |
Starting Time / Ending Time |
Ventana diaria permitida. |
Next Run Date Formula |
Regla alternativa para calcular la siguiente fecha. |
Reference Starting Time |
Referencia para mantener coherencia temporal. |
Ejecución y seguridad
| Campo | Función |
|---|---|
User ID |
Usuario bajo cuya identidad se ejecutará. |
User Language ID |
Idioma de la sesión. |
Job Timeout |
Duración máxima solicitada para la tarea. |
System Task ID |
GUID de la scheduled task creada en plataforma. |
Scheduled |
Indica que existe programación subyacente. |
Job Queue Category Code |
Categoría de serialización. |
Priority Within Category |
Orden relativo dentro de la categoría. |
Resultado y recuperación
| Campo | Función |
|---|---|
Status |
Estado funcional actual. |
Maximum No. of Attempts to Run |
Número máximo de intentos fallidos antes de detenerse. |
No. of Attempts to Run |
Intentos acumulados para la ejecución. |
Rerun Delay (sec.) |
Espera entre intentos. |
Error Message |
Resumen visible del último fallo. |
Error Message Register Id |
Relación con el registro detallado de errores. |
Last Ready State |
Último momento en el que quedó lista. |
Esta densidad explica por qué crear una entrada con un
Insert() y dos asignaciones suele producir una
automatización incompleta. Una job queue es una política, no una pareja
de campos Object Type y Object ID.
El ciclo de vida real
Una entrada nueva nace en On Hold. Cuando se pone en
Ready, Job Queue - Enqueue crea una scheduled
task. A partir de ahí, los estados reflejan tanto intención funcional
como disponibilidad de infraestructura.
On Hold
Es el estado inicial y la pausa administrativa. Evita que se inicie una nueva ejecución, pero no cancela una sesión ya arrancada. Para detener un trabajo activo hay que actuar sobre la sesión o diseñar cancelación cooperativa.
Ready
Significa que la entrada está encolada y dispone de una tarea programada. No significa «se ejecutará exactamente a las 02:00:00».
Waiting
Se utiliza cuando la entrada tiene
Job Queue Category Code y otro trabajo de esa categoría
está ejecutándose. La tarea espera a que la categoría quede
disponible.
In Process
El dispatcher ha iniciado el trabajo. Se crea un
Job Queue Log Entry y el objeto configurado entra en
ejecución.
Error
La ejecución lanzó una excepción, agotó un timeout o no pudo
completar la ruta. El error handler conserva mensaje, call stack y
relación con Error Message Register. Si quedan intentos y
el error permite reintento, puede reprogramarse.
Finished
Un trabajo no recurrente se completa y puede desaparecer de la lista activa según el flujo. Un trabajo recurrente calcula la próxima fecha y vuelve a encolarse.
Earliest Start Date/Time
no es una reserva de calendario
El nombre está bien elegido: earliest, no exact.
El valor expresa «no ejecutar antes de este momento». La ejecución real depende de:
- capacidad disponible del scheduler;
- límite de concurrencia;
- otros trabajos del usuario;
- categoría ocupada;
- prioridad dentro de la categoría;
- sesiones largas;
- bloqueos de base de datos;
- mantenimiento o reinicio del servicio;
- empresa y entorno habilitados;
- ventana
Starting Time/Ending Time; - permisos y validez del usuario.
Si un negocio exige completar una exportación antes de las 06:00,
programarla a las 05:59 no es una estrategia; es una apuesta con formato
DateTime.
Hay que diseñar una ventana:
Objetivo empresarial: disponible antes de las 06:00
Inicio más temprano: 04:30
Duración normal: 18 minutos
Duración p95: 31 minutos
Alerta: no iniciada a las 05:00
Alerta crítica: no finalizada a las 05:30
La programación dispara el intento. El SLA necesita observabilidad.
Recurrencia: intervalo, días y ventana
Una entrada recurrente puede combinar:
- minutos entre ejecuciones;
- días concretos de la semana;
- hora inicial y final;
Next Run Date Formula;- una fecha de referencia.
Después de una ejecución, Job Queue Dispatcher calcula
la próxima fecha válida y vuelve a encolar.
Intervalo no significa ritmo perfecto
Si un trabajo configurado cada 15 minutos tarda 12, queda poco margen. Si tarda 20, no puede mantener un ritmo real de cuatro ejecuciones por hora sin solapamiento o acumulación.
Pregunta correcta:
¿Queremos iniciar cada 15 minutos o procesar todo lo pendiente con una latencia máxima de 15 minutos?
La segunda formulación suele conducir a un worker por lotes, más estable que una fábrica de tareas diminutas.
Ventanas que cruzan medianoche
Las configuraciones nocturnas deben probarse con cambios de día, horario de verano y zona horaria. El usuario ve horas locales, mientras que telemetría y ciertos contextos administrativos pueden presentarse en UTC. Documentar ambas evita investigar «retrasos de dos horas» que son en realidad conversiones correctas.
Categorías: un mutex funcional
Job Queue Category suele entenderse como agrupación
visual. Su función importante es otra: serializar
trabajos.
Si varias entradas usan la misma categoría, solo una debe ejecutarse
a la vez. Las demás pasan a Waiting. Al terminar, Business
Central activa la siguiente según disponibilidad y
Priority Within Category.
Cuándo usar una categoría
Cuando los trabajos comparten un recurso que no tolera concurrencia:
- el mismo diario o batch;
- una secuencia externa;
- una carpeta de entrada;
- un endpoint con límite estricto;
- una tabla de staging procesada por estado;
- una rutina que adquiere bloqueos incompatibles;
- un proceso de cierre con orden funcional.
Cuándo no usar una categoría común
No metas todos los trabajos de la compañía en DEFAULT
«para evitar problemas». El resultado es un monorraíl: seguro, sencillo
y capaz de transportar una sola cosa cada vez.
Categorías demasiado amplias destruyen paralelismo; categorías
demasiado específicas no protegen el recurso. El código debería expresar
el dominio de exclusión: BANKIMPORT,
WAREHOUSE, COSTING, DATAVERSE, no
el estado de ánimo del consultor.
Ruta de éxito y ruta de error
Cuando Task Scheduler inicia la tarea:
- abre la empresa;
- valida la scheduled task;
- ejecuta
Job Queue Dispatcher; - comprueba expiración, ventana y categoría;
- cambia la entrada a
In Process; - crea un
Job Queue Log Entry; Job Queue Start Codeunitejecuta el objeto;- finaliza el log;
- elimina o reprograma la entrada.
Si el código lanza una excepción, la ruta de éxito se interrumpe.
Job Queue Error Handler se ejecuta en otra background
session para que el registro del error no dependa de la transacción que
acaba de fallar.
Esta separación importa mucho:
La operación de negocio puede hacer rollback y, aun así, el sistema necesita confirmar el log que explica ese rollback.
El handler actualiza la entrada, el log y
Error Message Register; después decide si reprograma o deja
el trabajo en Error.
Reintentos: recuperarse sin repetir el daño
Maximum No. of Attempts to Run y
Rerun Delay (sec.) permiten reintentar fallos temporales,
por ejemplo una API no disponible.
Pero un reintento seguro exige idempotencia.
Qué significa idempotencia aquí
Ejecutar el mismo trabajo dos veces debe producir el mismo estado final que ejecutarlo una vez, o al menos detectar de forma fiable lo ya realizado.
Un job puede fallar después de:
- enviar una petición externa que sí fue aceptada;
- registrar 300 de 500 documentos;
- guardar un fichero y fallar antes de marcarlo;
- confirmar un
Commit()intermedio; - recibir un timeout del cliente aunque el servidor remoto siga procesando.
Al reintentarlo, asumir «si hubo error, nada ocurrió» es una forma eficiente de duplicar operaciones.
Patrones de idempotencia
| Patrón | Aplicación |
|---|---|
| Clave natural o externa | Guardar External Id con índice único antes de crear el
documento. |
| Estado de staging | Pending → Processing →
Completed / Error. |
| Idempotency key | Enviar una clave estable al servicio externo. |
| Checkpoint | Conservar el último elemento confirmado del lote. |
| Upsert | Crear o actualizar por identidad estable. |
| Outbox | Confirmar el evento local y publicarlo de manera reintentable. |
| Compensación | Revertir explícitamente una operación parcial que no puede repetirse. |
Qué no debe reintentarse ciegamente
- datos maestros inválidos;
- permisos insuficientes;
- configuración ausente;
- violaciones de reglas empresariales;
- incompatibilidad de esquema;
- errores de programación deterministas.
Retrasar 60 segundos un dato imposible no lo vuelve posible. Solo consigue que falle con más experiencia.
Timeouts y lotes
Job Timeout define cuánto puede durar la sesión
programada. En Business Central online, el valor predeterminado actual
para TaskScheduler.CreateTask cuando no se proporciona
timeout es de 12 horas, aunque Microsoft advierte que puede cambiar. Los
límites máximos efectivos dependen del servicio y modalidad.
Un timeout no es un sustituto de la partición. Un proceso de seis horas es difícil de:
- reintentar;
- observar;
- desplegar alrededor;
- cancelar;
- probar;
- mantener dentro de ventanas;
- aislar de bloqueos.
La alternativa es trabajar por lotes pequeños y confirmables.
1. Seleccionar hasta 200 registros Pending
2. Marcar el lote con Run Id
3. Procesar un registro de forma idempotente
4. Confirmar checkpoints controlados
5. Emitir métricas del lote
6. Salir antes del timeout
7. Dejar la siguiente ejecución continuar
El tamaño correcto no es un número universal. Debe medirse con volumen, bloqueo, latencia externa y coste de reintento.
El usuario invisible sigue siendo un usuario
La sesión usa el usuario que puso la entrada en Ready.
Ese usuario necesita permisos para:
- ejecutar el objeto;
- leer y modificar las tablas afectadas;
- registrar documentos;
- acceder a empresas aplicables;
- usar servicios o secretos configurados;
- ejecutar objetos dependientes.
Consecuencias operativas:
- si se deshabilita el usuario, el job puede dejar de funcionar;
- si cambian sus permission sets, cambia la ejecución;
- una cuenta personal crea dependencia de una persona;
- un delegated administrator puede configurar una entrada, pero solo usuarios licenciados o administradores apropiados pueden ejecutarla según las reglas del servicio;
- el
User IDforma parte de auditoría y telemetría.
Conviene usar una identidad operativa gobernada, con mínimo
privilegio, propietario definido y revisión de licencia.
SUPER elimina errores de permisos y también elimina
información sobre qué permisos necesitaba realmente el proceso.
Código sin
interfaz: GuiAllowed() no es decoración
Una background session no puede responder preguntas.
Operaciones como Confirm, Page.RunModal,
Upload, Download, Hyperlink o
determinados usos de Report.RunModal no pertenecen a un
job. Pueden producir excepciones de callback no permitido o
comportamientos suprimidos.
procedure ProcessOrders(ShowProgress: Boolean)
var
ProgressDialog: Dialog;
begin
if ShowProgress and GuiAllowed() then
ProgressDialog.Open(ProcessingLbl);
ProcessPendingOrders();
if ShowProgress and GuiAllowed() then
ProgressDialog.Close();
end;
La mejor arquitectura separa interfaz y servicio:
Page action
└─ confirma intención del usuario
└─ llama a Processing Service
Job Queue Codeunit
└─ llama al mismo Processing Service
El core no debería mostrar mensajes ni abrir páginas. La capa interactiva decide cómo informar; el job registra resultados y telemetría.
Un codeunit preparado para Job Queue
La ejecución utiliza OnRun(). Si el codeunit declara
TableNo = "Job Queue Entry", recibe la entrada y puede
acceder a Parameter String,
Record ID to Process y demás contexto.
codeunit 50140 "SCP Tracking Sync Job"
{
TableNo = "Job Queue Entry";
trigger OnRun()
var
TrackingSync: Codeunit "SCP Tracking Sync";
BatchSize: Integer;
begin
BatchSize := ParseBatchSize(Rec."Parameter String");
TrackingSync.RunPending(BatchSize, Rec.ID);
end;
local procedure ParseBatchSize(ParameterString: Text[250]): Integer
var
BatchSize: Integer;
begin
if not Evaluate(BatchSize, ParameterString) then
Error('Parameter String must contain a numeric batch size.');
if not (BatchSize in [1 .. 1000]) then
Error('Batch size must be between 1 and 1000.');
exit(BatchSize);
end;
}
El codeunit orquestador debe ser delgado. La lógica empresarial vive en un servicio reutilizable y testeable.
Parameter String:
útil, pero pequeño
Sus 250 caracteres sirven para opciones sencillas:
BATCHSIZE=200;MODE=INCREMENTAL
No es un sistema de configuración completo. Para parámetros complejos
utiliza una tabla de setup o un registro de control y pasa una identidad
estable mediante Record ID to Process o una clave
sencilla.
No guardes secretos en Parameter String: aparece en
páginas, logs y puede terminar en telemetría o soporte.
Crear una entrada desde AL
Un setup de extensión puede crear una entrada idempotentemente. El objetivo es evitar duplicados después de reinstalaciones, upgrades o reconfiguraciones.
procedure EnsureTrackingJobExists()
var
JobQueueEntry: Record "Job Queue Entry";
begin
JobQueueEntry.SetRange("Object Type to Run", JobQueueEntry."Object Type to Run"::Codeunit);
JobQueueEntry.SetRange("Object ID to Run", Codeunit::"SCP Tracking Sync Job");
JobQueueEntry.SetRange("Job Queue Category Code", 'TRACKING');
if JobQueueEntry.FindFirst() then
exit;
JobQueueEntry.Init();
JobQueueEntry.ID := CreateGuid();
JobQueueEntry.Validate("Object Type to Run", JobQueueEntry."Object Type to Run"::Codeunit);
JobQueueEntry.Validate("Object ID to Run", Codeunit::"SCP Tracking Sync Job");
JobQueueEntry.Validate(Description, 'Synchronize carrier tracking states');
JobQueueEntry.Validate("Job Queue Category Code", 'TRACKING');
JobQueueEntry.Validate("Parameter String", '200');
JobQueueEntry.Validate("Recurring Job", true);
JobQueueEntry.Validate("No. of Minutes between Runs", 15);
JobQueueEntry.Validate("Maximum No. of Attempts to Run", 3);
JobQueueEntry.Validate("Rerun Delay (sec.)", 120);
JobQueueEntry.Insert(true);
// Mantener On Hold hasta que un usuario autorizado revise
// configuración, permisos, frecuencia y entorno.
end;
El ejemplo deja la entrada en On Hold deliberadamente.
Crear infraestructura automáticamente puede ser apropiado; activarla sin
consentimiento puede lanzar tráfico externo, registros o correos durante
instalación y pruebas.
En escenarios soportados también pueden utilizarse procedimientos
estándar como ScheduleJobQueueEntryWithParameters,
ScheduleTask o Job Queue Management. La
elección depende de si se busca una entrada administrable permanente, un
trabajo único o una tarea de infraestructura.
Job Queue, Task Scheduler, StartSession o Page Background Task
No toda asincronía necesita una job queue.
| Mecanismo | Inicio | Persistencia | Recurrencia | Log en BC | Caso adecuado |
|---|---|---|---|---|---|
Page Background Task |
Vinculado a página | No | No | No | Cálculo ligero y de solo lectura para refrescar UI. |
Session.StartSession |
Inmediato | No sobrevive igual como tarea | No | No | Trabajo inmediato en otra sesión, controlado por código. |
TaskScheduler.CreateTask |
Encolado y programado | Sí | Una ejecución | No en Job Queue | Infraestructura técnica sin necesidad de administración funcional. |
Job Queue |
Programado | Sí | Sí | Sí | Procesos administrables, recurrentes y operables por usuarios. |
Usa Job Queue cuando importan configuración, estado, recurrencia,
historial y soporte desde el cliente. Usa TaskScheduler
directamente cuando necesitas una tarea técnica de una sola ejecución y
aceptas construir tu propia observabilidad. Usa
StartSession para inicio inmediato, no para un proceso que
deba sobrevivir y reintentarse mañana. Usa page background tasks solo
para enriquecer la experiencia de una página, no para registrar medio
inventario mientras el usuario navega.
Informes y parámetros de request page
Job Queue puede ejecutar reports. Los parámetros se conservan
mediante contenido XML y métodos como SetReportParameters y
GetReportParameters. El output depende de
Job Queue Report Output Type y de las implementaciones
disponibles.
Precauciones:
- un report diseñado para interacción puede pedir filtros o confirmar acciones;
ProcessingOnlysuele ser más apropiado para batches;- los filtros deben ser reproducibles y auditables;
- un informe con salida necesita destino y formato válidos;
- la request page no debe ocultar parámetros críticos que nadie revisará después;
- cambios de esquema del report pueden invalidar parámetros guardados.
Para procesos complejos suele ser más claro ejecutar un codeunit que llame explícitamente a servicios o reports con parámetros controlados.
Caso completo: sincronización de tracking de transportistas
Una empresa quiere consultar cada 15 minutos el estado de envíos abiertos.
Diseño ingenuo
Un job recorre todos los envíos y llama a la API. Si una llamada
falla, lanza Error() y el job completo se reintenta.
Problemas:
- relee miles de envíos ya finalizados;
- duplica llamadas al reintentar;
- un envío defectuoso bloquea a todos;
- mantiene transacciones largas;
- no distingue fallo remoto de datos inválidos;
- el log solo dice «HTTP 400».
Diseño robusto
Tabla de control:
| Campo | Función |
|---|---|
Shipment SystemId |
Identidad local estable. |
Carrier Code |
Proveedor y configuración aplicable. |
External Tracking No. |
Identidad remota. |
Status |
Pending, Processing,
Completed, Retry, Blocked. |
Next Attempt At |
Backoff por registro. |
Attempt Count |
Intentos del elemento, no solo del job. |
Last Error |
Diagnóstico funcional resumido. |
Last Correlation Id |
Correlación con API y telemetría. |
Last Modified At |
Control incremental. |
Flujo:
- El job selecciona hasta 200 filas
PendingoRetrycuya fecha haya vencido. - Las marca con un
Run Idy estadoProcessing. - Procesa cada una con correlación estable.
- Un
404funcional puede llevar aBlocked; un429calcula backoff. - Confirma checkpoints en lotes pequeños.
- Emite contadores: seleccionados, completados, reintentados y bloqueados.
- Termina antes del timeout.
- La siguiente recurrencia recoge el resto.
Categoría:
TRACKING
Evita que dos workers actualicen el mismo staging, pero no bloquea informes o procesos de costes.
Política de job:
Interval: 15 minutes
Batch size: 200
Maximum attempts: 3
Rerun delay: 120 seconds
Job timeout: 10 minutes
Category: TRACKING
La política de reintento del job protege ante un fallo global. La política por registro protege ante fallos individuales. Son dos niveles diferentes.
Concurrencia y límites online
Business Central online permite actualmente un máximo de cinco scheduled tasks concurrentes por usuario. Más usuarios operativos pueden aumentar el paralelismo total, pero hacerlo solo para esquivar límites sin gobernar seguridad y carga es una mala arquitectura.
Cinco sesiones no significan cinco veces más velocidad:
- pueden bloquear las mismas tablas;
- consumir el mismo límite de API;
- competir por el mismo diario;
- aumentar deadlocks;
- degradar sesiones interactivas;
- saturar un recurso externo.
La capacidad útil depende de la parte más estrecha del sistema.
Frecuencia
Microsoft recomienda utilizar el intervalo más amplio compatible con el negocio. Antes de programar polling cada minuto, considera:
- webhooks;
- eventos;
- APIs delta;
- staging push;
- una única ejecución que procese todo lo pendiente;
- triggers externos controlados.
Una integración que pregunta 1.440 veces al día si ocurrió algo está documentando su impaciencia.
Copias de entorno
Al copiar un entorno, las tareas programadas se detienen como
protección. En el sandbox resultante hay que revisar
Scheduled Tasks y activar conscientemente lo necesario.
Esta medida evita que una copia:
- envíe correos reales;
- consuma endpoints de producción;
- registre operaciones externas;
- duplique sincronizaciones;
- procese ficheros compartidos.
No reactives todo en bloque. Primero cambia endpoints, secretos, cuentas y banderas de simulación.
Observabilidad en tres niveles
1. Job Queue Entry
Responde a la situación actual:
- estado;
- próxima ejecución;
- intentos;
- último error;
- usuario;
- categoría;
- scheduled task asociada.
2. Job Queue Log Entry
Responde a la historia:
- inicio y fin;
- duración;
- objeto;
- resultado;
- error;
- call stack;
- parámetros;
- sesión y task ID.
El log necesita limpieza y retención. Guardarlo para siempre aumenta volumen; borrarlo cada noche elimina la capacidad de demostrar patrones semanales.
3. Application Insights
La telemetría de ciclo de vida incluye, entre otros:
| Event ID | Evento |
|---|---|
AL0000E24 |
Entrada encolada. |
AL0000FNY |
Fallo al encolar; no se creó scheduled task. |
AL0000E25 |
Ejecución iniciada. |
AL0000E26 |
Ejecución finalizada. |
AL0000HE7 |
Ejecución fallida, quizá reintentable. |
AL0000JRG |
Último intento fallido; entrada detenida en error. |
AL0000FMG |
Ejecución manual Run once. |
AL0000KZV |
Entrada cancelada. |
Dimensiones como alJobQueueId,
alJobQueueObjectId, alJobQueueObjectName,
alJobQueueStatus, alJobQueueScheduledTaskId y
alJobQueueExecutionTimeInMs permiten correlacionar.
KQL: duración por objeto
traces
| where timestamp > ago(7d)
| where customDimensions.eventId == 'AL0000E26'
| extend ObjectName = tostring(customDimensions.alJobQueueObjectName)
| extend DurationMs = todouble(customDimensions.alJobQueueExecutionTimeInMs)
| summarize Runs = count(),
AvgMs = avg(DurationMs),
P95Ms = percentile(DurationMs, 95),
MaxMs = max(DurationMs)
by ObjectName
| order by P95Ms desc
KQL: trabajos con fallo final
traces
| where timestamp > ago(24h)
| where customDimensions.eventId == 'AL0000JRG'
| project timestamp,
companyName = tostring(customDimensions.companyName),
jobId = tostring(customDimensions.alJobQueueId),
objectName = tostring(customDimensions.alJobQueueObjectName),
message
| order by timestamp desc
KQL: latencia entre encolado e inicio
let Enqueued = traces
| where timestamp > ago(24h)
| where customDimensions.eventId == 'AL0000E24'
| project jobId = tostring(customDimensions.alJobQueueId),
taskId = tostring(customDimensions.alJobQueueScheduledTaskId),
enqueuedAt = timestamp;
let Started = traces
| where timestamp > ago(24h)
| where customDimensions.eventId == 'AL0000E25'
| project jobId = tostring(customDimensions.alJobQueueId),
taskId = tostring(customDimensions.alJobQueueScheduledTaskId),
startedAt = timestamp;
Enqueued
| join kind=inner Started on jobId, taskId
| extend QueueLatencySeconds = datetime_diff('second', startedAt, enqueuedAt)
| summarize P50 = percentile(QueueLatencySeconds, 50),
P95 = percentile(QueueLatencySeconds, 95),
Maximum = max(QueueLatencySeconds)
La consulta es un punto de partida. En jobs recurrentes y reintentos puede ser necesario correlacionar por task ID, ventana temporal y ejecución concreta para evitar emparejamientos ambiguos.
Diagnóstico: el orden que evita perder una tarde
1. ¿Existe
System Task ID?
Una entrada Ready sin scheduled task funcional apunta a
fallo de encolado. Busca AL0000FNY y revisa
Scheduled Tasks.
2. ¿La hora ya era elegible?
Comprueba:
Earliest Start Date/Time;- zona horaria;
- días habilitados;
- ventana inicial/final;
- expiración;
- entorno actual.
3. ¿La categoría está ocupada?
Un estado Waiting puede ser correcto. Revisa trabajos
In Process con la misma categoría y duración anormal.
4. ¿La sesión arrancó?
Busca AL0000E25, sesión activa y log. Si fue encolado
pero no iniciado, investiga capacidad, usuario y plataforma.
5. ¿Falló el objeto?
Abre Job Queue Log Entry, copia detalles y call stack.
Distingue:
- error funcional;
- permiso;
- callback UI;
- timeout;
- deadlock;
- servicio externo;
- configuración;
- extensión propietaria del stack.
6. ¿El job terminó pero el negocio no avanzó?
Un estado Finished solo confirma que el objeto no lanzó
una excepción. Puede haber capturado errores y continuar, no seleccionar
registros o registrar cero elementos.
La observabilidad del proceso debe incluir sus propios contadores.
Síntomas frecuentes
| Síntoma | Causa probable | Primera comprobación |
|---|---|---|
Ready durante horas |
Capacidad, scheduled task ausente, usuario o fecha no elegible. | System Task ID, Scheduled Tasks y telemetría. |
Waiting permanente |
Otro job de la categoría no termina o quedó obsoleto. | Categoría, In Process y recovery task. |
In Process permanente |
Proceso largo, bloqueo, llamada externa o sesión huérfana. | Sesiones, locks, timeout y trazas. |
| Falla solo en background | UI, permisos, idioma, ruta de fichero o contexto de usuario. | GuiAllowed(), user ID y call stack. |
| Se ejecuta dos veces | Reintento después de efecto parcial o duplicación de entradas. | Idempotencia, commits y búsqueda de jobs equivalentes. |
| Siempre empieza tarde | Earliest Start interpretado como hora exacta o
saturación. |
Latencia enqueue-start y duración de otros jobs. |
| Sandbox envía datos reales | Tareas reactivadas sin cambiar setup. | Endpoints, credenciales y entorno. |
| Muchos deadlocks nocturnos | Jobs paralelos compiten por tablas o diarios. | Categorías, orden de bloqueo y tamaño de lote. |
| Log exitoso, cero resultados | Filtros vacíos o errores capturados internamente. | Métricas funcionales del worker. |
| Error repetido cientos de veces | Reintento aplicado a error permanente. | Clasificación del fallo y attempts. |
Antipatrones
El job infinito
while true do con pausas internas ocupa una sesión,
complica despliegues y elude la recurrencia. Un job debe procesar una
unidad finita de trabajo y terminar.
Un job por registro
Crear miles de scheduled tasks para miles de filas introduce más orquestación que trabajo. Agrupa en lotes salvo que cada elemento necesite aislamiento real.
Capturar todos los errores
if not TryProcess() then
exit;
El job termina Finished y nadie descubre que no hizo
nada. Un TryFunction necesita clasificación, persistencia,
métricas y decisión explícita.
Commit() como
analgésico
Añadir commits frecuentes puede reducir rollback, pero crea estados parciales. Cada commit debe corresponder a un checkpoint que el reintento comprenda.
UI dentro del core
El código funciona desde una acción y falla por la noche. El servicio empresarial debe ser headless; la página es solo un consumidor.
Todas las categorías iguales
Evita concurrencia convirtiendo el sistema en secuencial. Protege el recurso mínimo necesario.
Polling frenético
Un job cada minuto para una API que cambia tres veces al día desperdicia capacidad y acerca rate limits. Utiliza eventos, webhooks o un intervalo justificado.
Diseño de una operación cancelable
Poner una entrada en On Hold no detiene lo ya iniciado.
Si el negocio necesita cancelación, el worker debe comprobar una señal
entre unidades de trabajo.
local procedure CancellationRequested(RunId: Guid): Boolean
var
JobRunControl: Record "SCP Job Run Control";
begin
if not JobRunControl.Get(RunId) then
exit(false);
exit(JobRunControl."Cancellation Requested");
end;
El bucle comprueba la bandera, finaliza limpiamente el registro actual, guarda checkpoint y sale. No conviene comprobarla dentro de cada línea SQL si eso añade carga innecesaria; el punto de control debe equilibrar respuesta y coste.
Detener la sesión administrativamente es una medida de emergencia. La cancelación cooperativa es un comportamiento de producto.
Pruebas necesarias
Unidad
- parsing de parámetros;
- selección del lote;
- transición de estados;
- idempotencia por external ID;
- clasificación de errores;
- cálculo de backoff;
- checkpoints;
- cancelación.
Integración
- primera ejecución exitosa;
- segunda ejecución sobre los mismos datos;
- fallo después de un efecto parcial;
429y reintento;- dato inválido que pasa a
Blocked; - dos workers concurrentes;
- categoría compartida;
- usuario sin un permiso;
- timeout;
- empresa equivocada;
- ejecución sin GUI.
Operación
- entrada creada una sola vez tras upgrade;
- job permanece
On Holdhasta aprobación; - telemetría contiene correlación;
- alerta detecta falta de ejecución;
- limpieza conserva retención acordada;
- copia de entorno no contacta servicios productivos.
La prueba más importante es ejecutar dos veces. Muchos jobs parecen perfectos hasta que hacen exactamente aquello para lo que fueron configurados: volver a ejecutarse.
Gobierno operativo
Cada job de producción debería tener una ficha mínima.
| Dato | Ejemplo |
|---|---|
| Propietario funcional | Logística |
| Propietario técnico | Equipo BC |
| Objeto | SCP Tracking Sync Job |
| Frecuencia | Cada 15 minutos |
| Ventana | 06:00–23:00 Europe/Madrid |
| Identidad | Usuario operativo BC-JOBS |
| Categoría | TRACKING |
| Timeout | 10 minutos |
| Lote | 200 registros |
| Reintentos globales | 3, delay 120 s |
| SLA | Pendientes menores de 30 minutos |
| Alerta | Sin éxito durante 30 minutos |
| Runbook | Revisar API, staging, log y correlation ID |
| Retención | 90 días de métricas; log BC según política |
Sin propietario, una entrada en rojo es solo decoración navideña en el Role Center.
Checklist de arquitectura
Antes de crear el job
En el código
En producción
Referencia rápida
| Pregunta | Mira primero |
|---|---|
| ¿Qué se ejecuta? | Object Type to Run y Object ID to Run |
| ¿Cuándo puede empezar? | Earliest Start Date/Time y ventana |
| ¿Existe tarea real? | System Task ID, Scheduled y Scheduled
Tasks |
| ¿Quién lo ejecuta? | User ID y permisos efectivos |
| ¿Por qué espera? | Categoría, prioridad y capacidad |
| ¿Qué ocurrió? | Job Queue Log Entry |
| ¿Por qué falló? | Error register, call stack y telemetría |
| ¿Volverá a intentarlo? | Attempts, maximum attempts y rerun delay |
| ¿Puede duplicar efectos? | Idempotencia y checkpoints del worker |
| ¿Está cumpliendo el SLA? | Latencia, duración y métricas funcionales |
Conclusión
Job Queue no es un despertador que llama a un codeunit. Es una capa
de orquestación sobre Task Scheduler que conecta
configuración funcional, scheduled tasks, sesiones en segundo plano,
seguridad, serialización, reintentos, logs y telemetría.
La plataforma puede responder:
- cuándo un trabajo queda elegible;
- cómo se crea su sesión;
- qué categoría debe respetar;
- cómo se registra el resultado;
- cuándo vuelve a intentarlo.
El diseño de la extensión debe responder a lo difícil:
- qué unidad de trabajo es segura;
- cómo se recupera después de un fallo parcial;
- cómo evita duplicados;
- cómo demuestra que avanzó;
- cómo alerta cuando no lo hizo.
Una buena Job Queue Entry ejecuta código sin usuario. Un buen proceso de Job Queue también puede explicar, repetir y recuperar ese código sin necesitar al desarrollador que lo escribió.
Ese es el mecanismo invisible que mantiene Business Central trabajando de madrugada. Cuando está bien diseñado, nadie habla de él. Cuando está mal diseñado, todo el mundo lo descubre a primera hora.
Fuentes oficiales y lecturas adicionales
- Job queue
- Use job queues to schedule tasks
- Task scheduler
- Asynchronous processing overview
- Service scalability for Business Central online
- Analyzing Job Queue Lifecycle Trace Telemetry
- Table "Job Queue Entry"
- Table "Job Queue Log Entry"
- Table "Job Queue Category"
- Codeunit "Job Queue Dispatcher"
- Codeunit "Job Queue - Enqueue"
- Codeunit "Job Queue Error Handler"