Scheduler

Un Scheduler es una programación de ejecución recurrente que se registra en un Space. Cuando vincula un único Script con la hora a la que debe ejecutarse, el servidor ejecuta ese Script cada vez que llega esa hora. Por ejemplo, si en la tienda online de una tienda de ropa quiere ejecutar una vez al día un Script que busca los productos cuyo stock es 0 y llama al canal de pedidos del proveedor, cree un Scheduler que apunte a ese Script.

Un Scheduler es un recurso hijo de Space que se gestiona en CMA, y su ruta se basa en /spaces/{spaceId}/schedulers. No tiene el concepto de publicación (publish) ni sys.version. En cuanto se crea, entra de inmediato en la programación, y su modificación no requiere una cabecera de versión. En cambio, hay dos aspectos en los que se diferencia de otros recursos. El Script que se va a ejecutar no se puede cambiar tras la creación, y para crearlo o modificarlo se necesita, además del permiso de configuración del Space, el permiso de ejecución de ese Script por separado. El resultado de la ejecución queda como SchedulerLog: las ejecuciones correctas desaparecen al cabo de 1 hora y las fallidas, al cabo de 3 días.

Estructura del recurso

La siguiente es la respuesta al crear un Scheduler. En sys se incluyen el identificador y las referencias, y en el cuerpo, el nombre, la hora de ejecución y el estado de activación.

{
  "sys": {
    "id": "7kQm2ZbTn4Rc9WvXpL3dHsY6fJ",
    "type": "Scheduler",
    "space": { "sys": { "id": "HnQ32YiH", "type": "Refer", "targetType": "Space" } },
    "script": { "sys": { "id": "3trmXRMKq7bd0Prbef1NcZ", "type": "Refer", "targetType": "Script" } },
    "createdBy": { "sys": { "id": "9dLmQ2pVnRb8sTfWcXd3LhJ7gK", "type": "Refer", "targetType": "User" } },
    "createdAt": "2026-08-26T01:20:07.442Z",
    "updatedBy": { "sys": { "id": "9dLmQ2pVnRb8sTfWcXd3LhJ7gK", "type": "Refer", "targetType": "User" } },
    "updatedAt": "2026-08-26T01:20:07.442Z"
  },
  "name": "Reposición de stock",
  "cronExpression": "0 0 * * *",
  "activated": true
}

Claves principales:

• sys.id: identificador único del Scheduler. Se inserta en {schedulerId} de las rutas de consulta individual, modificación y eliminación.
• sys.script: el Script que ejecuta este Scheduler. Solo se puede definir al crear y no se puede cambiar después. Para ejecutar un Script distinto, cree un nuevo Scheduler.
• name: etiqueta que se muestra en la consola. No se usa en la ejecución.
• cronExpression: la hora de ejecución. Son cinco campos (minuto, hora, día, mes, día de la semana) y se interpretan en UTC. Consulte Escribir la hora de ejecución más abajo.
• activated: si está activado. Si es false, se conserva guardado pero simplemente no se ejecuta.

No existe sys.version. En la petición de modificación no se envía la cabecera X-Weegloo-Version.

Propiedades del sistema (sys)

space, script, createdBy y updatedBy se incluyen con la forma Refer ({ "sys": { "id", "type": "Refer", "targetType" } }).

Propiedades del cuerpo:

Escribir la hora de ejecución

Los cinco campos se escriben, de izquierda a derecha, en el orden minuto, hora, día, mes, día de la semana. No hay campo de segundos.

Puede usar * (todo), , (lista), - (rango) y / (intervalo), y el día de la semana se escribe con números (07, donde 0 y 7 son domingo) o con nombres (SUNSAT).

Todos los valores se interpretan en UTC. Debe calcular e incluir la diferencia respecto a su hora local, y en las horas ligadas a una fecha o a un día de la semana esa diferencia puede desplazarlas a otro día.

Un valor que no se dispara ni una sola vez no se guarda. Como 0 0 30 2 * (30 de febrero), si apunta a un día que nunca llega aunque el formato sea correcto, se rechaza.

Estado y restricciones

Reglas sobre el comportamiento y los permisos:

• Se necesitan dos permisos a la vez. El settings del rol (SpaceRole) debe incluir SETTING_SCHEDULER y, aparte de eso, se debe tener el permiso Execute sobre el Script de destino. Se comprueba no solo al crear, sino también al modificar y modificar parcialmente. Cambiar la hora de ejecución es decidir cuándo se ejecuta ese Script, y activar algo que estaba desactivado es iniciar su ejecución. Si falta alguno de los dos, la petición se rechaza.
• La ejecución se produce con los permisos de sys.createdBy. El filtro :self dentro del Script también se resuelve como ese usuario. Aunque quien modifica sea distinto, el sujeto de la ejecución no cambia.
• Si el autor pierde el permiso de ejecución, se desactiva automáticamente. En la siguiente hora de ejecución, el servidor lo comprueba, no lo ejecuta y pone activated en false. Aunque se restaure el permiso, no se vuelve a activar automáticamente.
• Hay un límite en la cantidad. El número de Scheduler que puede tener una sola Organization está fijado según el plan de precios (Free 1, Basic 5, Pro 30, Enterprise ilimitado). Al superar ese límite, la creación se rechaza.
• El número de ejecuciones se comparte con Script. Cada vez que se ejecuta, consume una ejecución de Script del plan. No hay un límite de ejecución exclusivo de Scheduler. Si se supera ese límite y se detienen las ejecuciones de Script de la Organization, los Scheduler que venzan a partir de entonces no se ejecutan y activated pasa a false. En ese caso queda un SchedulerLog y el motivo se recoge en sys.error. Una vez desactivado, ese Scheduler no se vuelve a programar.
• Las ejecuciones perdidas no se recuperan. Aunque haya turnos que no se pudieron ejecutar, no se ejecutan todos juntos más tarde, sino que se reanuda a partir de la siguiente hora.
• Un Script en uso no se puede eliminar. Si intenta borrar un Script al que hace referencia algún Scheduler, esa eliminación se rechaza (véase los errores de Script).
• No hay publicación. Sin valores de estado ni fase de publicación, al crearlo entra directamente en la programación, y también se elimina de inmediato sin pasos previos.

SchedulerLog

Cada vez que un Scheduler se ejecuta queda un registro de ejecución. Es de solo consulta y no tiene endpoints de creación, modificación ni eliminación. Su ruta es /spaces/{spaceId}/schedulers/{schedulerId}/logs.

{
  "sys": {
    "id": "5nRt8YcVm2Qb7WxZpK4dGhJ9sL",
    "type": "SchedulerLog",
    "space": { "sys": { "id": "HnQ32YiH", "type": "Refer", "targetType": "Space" } },
    "requestId": "3trmXRM8dNvQ2LbYpK7fHsJ3gWc4Rt",
    "success": true,
    "createdBy": { "sys": { "id": "7kQm2ZbTn4Rc9WvXpL3dHsY6fJ", "type": "Refer", "targetType": "Scheduler" } },
    "createdAt": "2026-09-03T00:00:02.503Z",
    "updatedBy": { "sys": { "id": "7kQm2ZbTn4Rc9WvXpL3dHsY6fJ", "type": "Refer", "targetType": "Scheduler" } },
    "updatedAt": "2026-09-03T00:00:02.503Z"
  }
}

Todos los valores están dentro de sys y no hay propiedades de cuerpo. Las claves sin valor se omiten de la respuesta (en el ejemplo anterior no está error).

No existe el campo scheduler. Qué Scheduler dejó el registro lo indica sys.createdBy, cuyo targetType es "Scheduler". sys.updatedBy es ese mismo Scheduler.

Tampoco existen los campos startedAt, endedAt ni result, ni ningún campo de duración. Cuánto tardó una ejecución y el valor que devolvió el Script están en el ScriptLog que tiene el mismo requestId (sys.durationMs, sys.value, sys.statusCode). La composición de sus campos se trata en Recurso Script y endpoints.

Una misma ejecución deja dos registros. Uno es este SchedulerLog ligero y el otro es el ScriptLog que contiene la ejecución en sí (el sys.trigger del ScriptLog apunta a este Scheduler). Los dos quedan enlazados por el mismo requestId.

El registro se escribe una sola vez al terminar la ejecución y luego no cambia. Las ejecuciones correctas desaparecen al cabo de 1 hora y las fallidas, al cabo de 3 días. Ningún campo de la respuesta contiene la hora de expiración: cuando llega el momento, el registro desaparece. Lo que haya que conservar más tiempo, guárdelo como Content desde dentro del Script.

Errores

Códigos que se encuentran al trabajar con Scheduler. Para los códigos comunes a todos los recursos, consulte Errores comunes.

API

La URL base de todos los endpoints siguientes es https://cma.weegloo.com/v1, y se requiere un token Bearer que autentique en CMA en la cabecera Authorization. Como Scheduler no tiene sys.version, en la modificación no se envía la cabecera X-Weegloo-Version.

Documentos relacionados

• Script: el recurso que ejecuta el Scheduler. Trata la estructura de definición y los tipos de statement.
• Webhook: el recurso que ejecuta un Script por eventos en lugar de por hora.
• SpaceRole: el rol que contiene el permiso de configuración SETTING_SCHEDULER y el permiso Execute del Script.
• Concepto de Scheduler: para qué sirve la función y cómo manejarla en la consola.