awe-108 Módulo scheduler
El módulo scheduler permite a AWE lanzar trabajos de forma planificada, ejecutar flujos de tareas e informar de los resultados. Esta página mantiene en primer plano el camino práctico: activar el módulo, crear una tarea, elegir un modo de lanzamiento y solo después pasar a la planificación avanzada, las dependencias, los servidores y los calendarios.
Ruta rápida
- Añade el starter del scheduler y la configuración del módulo.
- Aplica los módulos de migración de base de datos necesarios.
- Añade las opciones de menú del scheduler.
- Crea una tarea con el asistente.
- Elige lanzamiento manual, planificado o basado en ficheros.
- Añade dependencias, servidores y calendarios solo cuando el flujo básico ya funcione.
Antes de empezar
Ya deberías sentirte cómodo con:
Si necesitas la matriz exhaustiva de campos del scheduler, usa las guías específicas después de este tutorial:
Paso 1: Activar el módulo scheduler
Añade la dependencia del starter:
<dependency>
<groupId>com.almis.awe</groupId>
<artifactId>awe-scheduler-spring-boot-starter</artifactId>
</dependency>
Activa la entrada de la lista de módulos en el application.properties de tu aplicación generada añadiendo awe-scheduler a tu lista de módulos actual:
# Keep the rest of the list aligned with your application.
# The required scheduler addition is awe-scheduler.
awe.application.module-list=<your-existing-modules>,awe-scheduler
Por ejemplo, las aplicaciones Angular generadas suelen partir de <your-app>,awe, mientras que las aplicaciones React generadas incluyen también awe-react. Módulos como awe-tools son opcionales y solo deben ir en esta lista cuando tu aplicación los use realmente.
Activa las migraciones de base de datos relacionadas:
# Enable database update by Flyway
spring.flyway.enabled=true
awe.database.migration-modules=AWE,SCHEDULER,[YOUR_APP]
Añade las opciones de menú del scheduler:
<menu screen="home_horizontal" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://aweframework.gitlab.io/awe/docs/schemas/menu.xsd" context="screen/private/home" default-action="screen">
<option name="scheduler" label="MENU_SCHEDULER" icon="clock-o">
<option name="scheduler-management" label="MENU_SCHEDULER_MANAGEMENT" screen="scheduler-management" icon="cogs"/>
<option name="scheduler-tasks" label="MENU_SCHEDULER_TASKS" screen="scheduler-tasks" icon="tasks">
<option name="new-scheduler-task" screen="new-scheduler-task" invisible="true" />
<option name="update-scheduler-task" screen="update-scheduler-task" invisible="true" />
</option>
<option name="scheduler-servers" label="MENU_SCHEDULER_SERVERS" screen="scheduler-server" icon="server">
<option name="new-scheduler-server" screen="new-scheduler-server" invisible="true" />
<option name="update-scheduler-server" screen="update-scheduler-server" invisible="true" />
</option>
<option name="scheduler-calendars" label="MENU_SCHEDULER_CALENDARS" screen="scheduler-calendars" icon="calendar">
<option name="new-scheduler-calendar" screen="new-scheduler-calendar" invisible="true" />
<option name="update-scheduler-calendar" screen="update-scheduler-calendar" invisible="true" />
</option>
</option>
</menu>
Propiedades opcionales del scheduler
Si necesitas cambiar el comportamiento en ejecución, sobrescribe las propiedades del scheduler en tu configuración.
#################################################
# Scheduler properties
#################################################
awe.scheduler.tasks-load-on-start=true
awe.scheduler.stored-executions=5
#################################################
# Scheduler thread pool properties
#################################################
awe.scheduler.task-pool.size=20
awe.scheduler.task-pool.max-size=50
awe.scheduler.task-pool.queue-size=1000
awe.scheduler.task-pool.termination=120s
#################################################
# Scheduler log
#################################################
awe.scheduler.execution-log-path=/var/log/my-app/scheduler
#################################################
# Scheduler reporting
#################################################
awe.scheduler.report-email-from-value=scheduler@almis.com
Si activas la ejecución en clúster, todas las instancias participantes deben coordinarse a través del datasource configurado.
No ejecutes una planificación en clúster entre máquinas con relojes sin sincronizar. La coordinación basada en Quartz depende de que la hora sea lo bastante coherente entre los nodos participantes.
Para más detalles sobre el almacenamiento de Quartz y la configuración del job store, consulta la documentación oficial de Quartz.
Paso 2: Entender el modelo del scheduler
Una tarea del scheduler es un trabajo más su configuración de lanzamiento.
En la práctica, trabajarás con:
- tareas: qué ejecutar y cuándo
- dependencias: qué debe ejecutarse cuando termine una tarea
- servidores: dónde se ejecutan los trabajos de comando o basados en ficheros
- calendarios: fechas que las planificaciones deben ignorar
Tipos de tarea:
| Tipo de tarea | Finalidad |
|---|---|
| Tarea de maintain | Ejecuta un maintain público con una planificación definida. |
| Tarea de comando | Ejecuta un comando en el servidor seleccionado con la planificación definida. |
Paso 3: Crear una tarea con el asistente
El asistente de tareas es el punto de entrada principal para usar el scheduler.
1. Información básica de la tarea
Este paso define la identidad de la tarea y el tipo de ejecución.
| Elemento | Definición | Uso |
|---|---|---|
| Name | Nombre de la tarea | Obligatorio |
| Active | Estado de la tarea | Obligatorio |
| Description | Descripción de la tarea | Opcional |
| Max. stored executions | Número de ejecuciones almacenadas para las estadísticas | Opcional |
| Timeout | Tiempo máximo de ejecución en milisegundos | Opcional |
| Execute | Comando o maintain | Obligatorio |
| Command | Comando que se lanza | Obligatorio en tareas de comando |
| Execute path | Carpeta donde se ejecuta el comando | Opcional en tareas de comando |
| Run on remote server | Ejecuta el comando en un servidor SSH en lugar de en el host del scheduler | Opcional en tareas de comando |
| Remote server | Servidor SSH que ejecuta el comando | Obligatorio si se marca la ejecución remota |
| Maintain | Maintain que se lanza | Obligatorio en tareas de maintain |
| Launch dependencies in case of warning | Si las tareas dependientes pueden continuar ante un aviso | Opcional |
| Launch dependencies in case of error | Si las tareas dependientes pueden continuar ante un error | Opcional |
| Set execution as warning in case of error | Convierte la ejecución padre en aviso cuando falla una dependencia | Opcional |
Para exponer un maintain al scheduler, el maintain debe declararse con public="true".
2. Parámetros de la tarea
Este paso define el contexto de ejecución que se pasa al maintain o al comando seleccionado.
| Elemento | Definición | Uso |
|---|---|---|
| Name | Nombre del parámetro | Obligatorio |
| Source | De dónde procede el valor | Obligatorio |
| Type | Tipo de parámetro que se muestra al usuario | Obligatorio |
| Value | Valor literal o nombre de la variable referenciada | Opcional |
En las tareas de maintain, los parámetros requeridos del maintain suelen añadirse automáticamente.
3. Modo de lanzamiento de la tarea
Puedes elegir uno de tres estilos de lanzamiento:
Manual
La tarea se ejecuta solo cuando se lanza manualmente desde la lista de tareas.
Este es también el modo necesario cuando una tarea se va a usar como destino de una dependencia.
Planificado
La tarea se ejecuta según una configuración de planificación.
Usa este tutorial como orientación y pasa después a la guía de configuración de planificaciones para ver todas las opciones.
Fichero
El scheduler comprueba periódicamente los ficheros y lanza el trabajo según los criterios de fichero configurados.
Campos habituales:
| Elemento | Definición | Uso |
|---|---|---|
| Search at | Servidor donde se comprueban los ficheros | Obligatorio |
| File path | Ubicación de los ficheros | Obligatorio |
| File pattern | Patrón que deben cumplir los ficheros | Obligatorio |
Las credenciales FTP o SSH no forman parte de la tarea: se guardan en el servidor seleccionado en Search at (consulta Servidores).
4. Dependencias de la tarea
Las dependencias permiten convertir tareas aisladas en un flujo de trabajo.
| Elemento | Definición | Uso |
|---|---|---|
| Task | Tarea que se ejecuta después de la actual | Obligatorio |
| Blocking | Si es síncrona y puede detener la pila de dependencias ante un error | Obligatorio |
| Order | Orden de lanzamiento de las dependencias bloqueantes | Obligatorio |
Profundiza con la guía de dependencias.
5. Informe de la tarea
El último paso configura qué ocurre cuando la tarea termina.
Modos de informe disponibles:
- None: sin informe
- Email: envía la información de la ejecución por correo electrónico
- Broadcast: envía un mensaje de difusión a los usuarios seleccionados
- Maintain: ejecuta un maintain como acción de informe
Campos de ejemplo del correo electrónico:
| Elemento | Definición | Uso |
|---|---|---|
| Send in case of | Estados finales para los que se envía el correo | Obligatorio |
| Email server | Configuración del remitente | Obligatorio |
| Send to users | Usuarios destinatarios | Obligatorio |
| Title | Título del correo | Obligatorio |
| Message | Mensaje del correo | Obligatorio |
Paso 4: Elegir la profundidad de planificación adecuada
En los primeros usos, normalmente basta con elegir correctamente el modelo de lanzamiento.
Planificaciones repetitivas
Úsalas cuando la tarea deba ejecutarse cada X segundos, minutos, horas, días, meses o años.
Campos comunes habituales:
- calendario
- desde / hasta
- repetir cada
Las combinaciones exactas de campos dependen de la unidad elegida, así que usa la guía de configuración de planificaciones cuando necesites la matriz completa.
Planificaciones únicas
Úsalas cuando la tarea deba ejecutarse una sola vez en una fecha y hora concretas.
Planificaciones personalizadas
Úsalas cuando necesites un control a nivel de Quartz. Es la opción más flexible, pero también la menos adecuada para un tutorial, así que prefiere la guía específica de planificaciones cuando llegues a este nivel.
Paso 5: Añadir dependencias cuando el flujo de tareas sea estable
Las dependencias permiten que una tarea lance otras tareas cuando termina.
Dos modos prácticos son los más importantes:
Dependencias síncronas
- se configuran con
Blocking = Yes - se ejecutan en un orden configurable
- pueden detener la pila de dependencias si una tarea falla
Dependencias asíncronas
- no bloqueantes
- se lanzan en bloque
- el orden de ejecución no se configura de la misma forma
Regla importante: una tarea debe usar el modo de lanzamiento Manual antes de poder seleccionarse como destino de una dependencia.
Paso 6: Configurar servidores y calendarios solo cuando haga falta
Servidores
Los servidores se usan principalmente para la ejecución de comandos y las comprobaciones de tareas basadas en ficheros.
Campos principales:
| Elemento | Definición | Uso |
|---|---|---|
| Name | Nombre del servidor | Obligatorio |
| Server | Dirección del servidor | Obligatorio |
| Port | Puerto del servidor | Obligatorio |
| Type of connection | Protocolo de conexión (ftp, folder o ssh) | Obligatorio |
| Active | Estado del servidor | Obligatorio |
| Server user | Usuario para las conexiones SSH y FTP | Opcional |
| Server password | Contraseña para las conexiones SSH y FTP | Opcional |
| Private key | Clave privada para las conexiones SSH | Opcional |
| Private key passphrase | Frase de paso de la clave privada | Opcional |
Si un servidor está inactivo, las tareas que dependan de él no lo usarán.
Calendarios
Los calendarios definen las fechas que el scheduler debe ignorar.
Campos básicos del calendario:
| Elemento | Definición | Uso |
|---|---|---|
| Name | Nombre del calendario | Obligatorio |
| Description | Descripción del calendario | Obligatorio |
| Active | Estado del calendario | Obligatorio |
Las fechas del calendario suelen requerir:
| Elemento | Definición | Uso |
|---|---|---|
| Date | Fecha ignorada | Obligatorio |
| Name | Nombre legible de la fecha | Opcional |
Cada tarea puede asociarse a un calendario.
Qué hacer a continuación
- Usa la guía de configuración de planificaciones cuando necesites una configuración detallada al estilo cron.
- Usa la guía de dependencias cuando construyas flujos de tareas.
- Usa awe-104 si todavía tienes que definir los maintains que hay detrás de tus flujos del scheduler.