BC Blueprint - Job Queue

BC Blueprint - Job Queue

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 Entry es el contrato administrable; Task Scheduler es el mecanismo de plataforma; la background session es el contexto real de ejecución.

La arquitectura completa

Arquitectura de Job Queue en Business Central La entrada se encola como tarea programada. La plataforma abre una sesión en segundo plano, el dispatcher ejecuta el objeto y el resultado queda registrado. De una política administrativa a una sesión real La hora abre una posibilidad de ejecución; capacidad, categorías y permisos deciden lo demás. Job Queue Entry Object · Schedule User · Category · Retry Estado funcional Task Scheduler Scheduled Task System Task ID Infraestructura de plataforma Background Session Company · User Language · Timeout Sin interfaz de usuario Job Queue Dispatcher Valida · Serializa Inicia · Reprograma Objeto de negocio Codeunit.OnRun() Report o proceso estándar Evidencia operativa Log Entry · Error Register · Telemetry
La entrada no es la tarea ni la sesión. Es la definición que Business Central transforma en una tarea programada y después ejecuta dentro de una sesión de fondo.

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.

Ciclo de vida de una Job Queue Entry La entrada pasa de On Hold a Ready, después In Process y termina o se reprograma. Los errores pueden reintentarse o dejar la entrada en Error. Estados visibles, decisiones invisibles Un estado no demuestra que el trabajo avanzó; describe dónde lo dejó la orquestación. On Hold Configurada, no activa Ready Tarea programada Waiting Categoría ocupada In Process Sesión ejecutando Finished O próxima recurrencia Error Log y error registrados On Hold Due to Inactivity Espera por inactividad On Hold no detiene una sesión que ya está ejecutándose
Un trabajo recurrente vuelve a calcular su siguiente ejecución; un error puede regresar a `Ready` si quedan intentos o permanecer en `Error` cuando se agota la política de reintento.

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.

Serialización mediante Job Queue Category Tres trabajos de importación comparten categoría y se ejecutan uno a uno, mientras un trabajo de reporting con otra categoría puede ejecutarse en paralelo. La categoría es una puerta de una sola plaza Serializa recursos compartidos sin impedir que otras categorías utilicen capacidad disponible. Categoría IMPORT High · In Process Importar pedidos Normal · Waiting Importar tracking Low · Waiting Exclusión mutua Una sesión atraviesa la categoría a la vez Prioridad solo dentro de IMPORT Categoría REPORT Normal · In Process Informe de ventas Puede ejecutarse en paralelo Categoría compartida = recurso compartido protegido
Dos categorías diferentes pueden usar sesiones simultáneas. Dentro de una categoría, prioridad decide el orden; no concede prioridad global sobre toda la cola.

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:

  1. abre la empresa;
  2. valida la scheduled task;
  3. ejecuta Job Queue Dispatcher;
  4. comprueba expiración, ventana y categoría;
  5. cambia la entrada a In Process;
  6. crea un Job Queue Log Entry;
  7. Job Queue Start Codeunit ejecuta el objeto;
  8. finaliza el log;
  9. 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 ID forma 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;
  • ProcessingOnly suele 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:

  1. El job selecciona hasta 200 filas Pending o Retry cuya fecha haya vencido.
  2. Las marca con un Run Id y estado Processing.
  3. Procesa cada una con correlación estable.
  4. Un 404 funcional puede llevar a Blocked; un 429 calcula backoff.
  5. Confirma checkpoints en lotes pequeños.
  6. Emite contadores: seleccionados, completados, reintentados y bloqueados.
  7. Termina antes del timeout.
  8. 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;
  • 429 y 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 Hold hasta 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

Post a Comment

Previous Post Next Post