Planificador
Este documento ofrece una base mínima para empezar con el módulo Scheduler de AWE, y explica cómo automatizar y planificar tareas dentro de AWE de forma sencilla.
El módulo Scheduler está basado en la librería Quartz Scheduler.
Toda la documentación relacionada con la librería Quartz Scheduler se puede encontrar en su página web.
Requisitos previos
El módulo scheduler necesita ser configurado antes de usarse.
Para ver cómo configurar el módulo scheduler en tu aplicación consulta la guía de configuración.
Configuración del planificador remoto
Puedes separar el planificador en una instancia de AWE dedicada y hacer que tu aplicación AWE principal le delegue la planificación.
1. Configurar la instancia del planificador
En el nodo dedicado al planificador, habilita el modo solo planificador y configura la devolución de llamada (callback) hacia tu aplicación AWE principal:
# Scheduler-only instance
awe.scheduler.scheduler-instance=true
# Callback to the main AWE instance
awe.scheduler.remote-callback-url=http://localhost:8080
awe.scheduler.remote-callback-secure-enabled=true
awe.scheduler.remote-callback-user=scheduler
awe.scheduler.remote-callback-password=ENC(yourEncryptedPassword)
2. Configurar la instancia principal de AWE
En la aplicación AWE principal, habilita el uso del planificador remoto y apunta a la URL base de la API del planificador:
awe.scheduler.remote-enabled=true
awe.scheduler.remote-scheduler-url=http://localhost:8090/scheduler/api/v1
Nota: La URL base del planificador remoto debe apuntar a la API de la instancia del planificador (por defecto:
/scheduler/api/v1).
La instancia del planificador ahora solo responde a /scheduler/api/** a las peticiones con un token bearer de AWE, y la instancia del planificador necesita el starter de AWE REST para validarlo. Por tanto, la instancia principal de AWE debe iniciar sesión con un usuario de la instancia del planificador, configurado en awe.scheduler.remote-scheduler-user y awe.scheduler.remote-scheduler-password. Consulta Seguridad de la API del planificador.
Tareas
Una tarea consiste en un trabajo asociado a un disparador que es ejecutado por el planificador en el momento configurado.
Una tarea también puede encadenarse con otras tareas para crear un flujo de trabajo. Esto se hace añadiendo esas otras tareas como dependencias en el asistente de configuración de la tarea padre.
Tipos
Hay dos tipos de tareas con los que puede trabajar el planificador: las tareas maintain y las tareas de comando.
| Tarea maintain | Tarea de comando |
|---|---|
| Una tarea maintain ejecuta un maintain público con una planificación definida. | Una tarea de comando ejecuta un comando de shell con una planificación definida, ya sea en el host local de AWE o en un host remoto mediante SSH. |
Ejecución de comandos: local y remota
Una tarea de comando ejecuta el valor introducido en el campo Command como un comando de shell. La Execution path, cuando se define, se usa como directorio de trabajo en el que se ejecuta el comando, y también actúa como ubicación alternativa para el propio comando: el comando se busca primero en el PATH del host, y solo cuando el PATH no lo proporciona se usa un archivo ejecutable con ese nombre dentro de la ruta de ejecución. Por tanto, un script que viva en la ruta de ejecución se ejecuta por su nombre simple, mientras que un comando del sistema como ls o python siempre se sigue resolviendo desde el PATH y nunca queda oculto por un archivo del mismo nombre en la ruta de ejecución. Un comando que ya contiene un separador de ruta (./my-script.sh, o una ruta absoluta) se usa exactamente como está escrito.
- Ejecución local (por defecto): cuando Run on remote server se deja sin marcar, el comando se ejecuta en el propio host de AWE.
- Ejecución remota mediante SSH: cuando Run on remote server está marcado, hay que seleccionar un Remote server. El comando se ejecuta en ese host a través de un canal de ejecución SSH, y tanto su salida estándar como su salida de error se capturan en el registro de ejecución de la tarea.
La ejecución remota de comandos requiere que el servidor seleccionado use el tipo de conexión ssh. La autenticación se realiza con el usuario del servidor junto con una contraseña, una clave privada (opcionalmente protegida con frase de contraseña), o ambas. Consulta Servidores para ver cómo configurarlos, y la guía de configuración para las opciones de verificación de claves de host SSH.
Ejecuciones diferidas
Una tarea maintain puede finalizar más tarde. Sirve para trabajo que otro sistema completa después de que el maintain devuelva su respuesta, y para el que no conviene mantener ocupado un hilo del planificador. El maintain responde que ha aceptado el trabajo, la ejecución queda en ejecución sin retener ningún hilo, y el otro sistema (o tu propio código) completa la ejecución cuando el trabajo termina.
- El planificador lanza el maintain, que inicia el trabajo en el otro sistema y responde diferido.
- El planificador libera su hilo. La ejecución sigue en ejecución y no se lanzan sus dependencias.
- Cuando el trabajo termina, quien lo ha terminado completa la ejecución con su estado final (consulta Completar la ejecución).
- Las dependencias de la tarea se lanzan con las reglas habituales (
Launch dependencies in case of warning/in case of error).
La respuesta diferida
Un maintain responde diferido cuando su último paso es un servicio que devuelve SchedulerDeferred.accepted(externalReference, description):
public ServiceData startExternalWork(Integer taskId, Integer executionId) {
// Start the work and hand the execution key to the system that will complete it
String reference = externalSystem.start(taskId, executionId);
return SchedulerDeferred.accepted(reference, "Waiting for the external system");
}
<!-- Services.xml -->
<service id="startExternalWork">
<java classname="com.example.ExternalWorkService" method="startExternalWork">
<service-parameter name="taskId" type="INTEGER"/>
<service-parameter name="executionId" type="INTEGER"/>
</java>
</service>
<!-- Maintain.xml -->
<target name="startExternalWork">
<serve service="startExternalWork">
<variable id="taskId" type="INTEGER" name="taskId"/>
<variable id="executionId" type="INTEGER" name="executionId"/>
</serve>
</target>
Después crea una tarea maintain que ejecute el maintain startExternalWork.
- La respuesta diferida debe ser la respuesta del último paso del maintain.
- Funciona igual cuando el planificador se ejecuta como aplicación externa: la respuesta vuelve a la instancia del planificador con la respuesta de la llamada al maintain.
externalReferencees una referencia opcional del trabajo en el otro sistema, que se guarda con la ejecución. Se recorta a 256 caracteres.descriptiones opcional. Se muestra como descripción de la ejecución mientras espera, y se recorta a 2000 caracteres.
La clave de la ejecución
El planificador da a cada maintain dos parámetros reservados: taskId y executionId. Declara variables con esos nombres en el target del maintain, como en el ejemplo anterior, para recibirlos. Identifican la ejecución, así que el maintain debe entregarlos a quien vaya a completarla. Tienen prioridad sobre un parámetro de la tarea con el mismo nombre.
Mientras la ejecución espera
- La ejecución se guarda como en ejecución con la descripción de la respuesta diferida.
- No se lanzan las dependencias de la tarea y la tarea se muestra como en ejecución en la pantalla de tareas.
- No se retiene ningún hilo del planificador.
Completar la ejecución
El sistema que termina el trabajo llama a la API del planificador (a la instancia del planificador cuando usas un planificador remoto):
POST /scheduler/api/v1/tasks/{taskId}/executions/{executionId}/complete
La petición necesita un token bearer de AWE, como el resto de /scheduler/api/** (consulta Seguridad de la API del planificador). El cuerpo es un objeto JSON:
| Campo | Descripción | Obligatorio |
|---|---|---|
status | Estado final: OK, WARNING, ERROR, STOPPED, INTERRUPTED o INFO (sin distinguir mayúsculas) | Obligatorio |
description | Descripción de la ejecución, 2000 caracteres como máximo | Opcional |
outputs | Objeto con valores de texto para las dependencias (consulta Salidas) | Opcional |
curl -X POST "https://scheduler.example.com/scheduler/api/v1/tasks/12/executions/340/complete" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"status": "OK", "description": "Calculation finished"}'
| Respuesta | Significado |
|---|---|
| 200 | La ejecución se ha completado. El cuerpo es {"taskId": 12, "executionId": 340, "status": "JOB_OK"} |
| 400 | Falta el status o no es uno de los valores permitidos, o la description supera los 2000 caracteres |
| 401 | La petición no tiene un token bearer válido |
| 404 | La ejecución no existe |
| 409 | La ejecución no se puede completar. El cuerpo es {"type": "...", "currentStatus": "JOB_OK"}, con uno de los tipos siguientes |
type del 409 | Significado |
|---|---|
execution-not-running | La ejecución ya se completó, se interrumpió por su plazo o se detuvo. currentStatus es el estado que tiene |
execution-not-deferred | La ejecución no está registrada como diferida, así que no se puede completar desde fuera. Con currentStatus JOB_RUNNING puede que el maintain aún no haya respondido: reintenta en breve si esperas que sea diferida |
Un 409 con execution-not-running es definitivo: la ejecución ya está cerrada y repetir la llamada no la cambiará, así que no lo reintentes.
El estado decide qué ocurre con las dependencias, con las reglas habituales: se lanzan tras OK, tras WARNING solo con Launch dependencies in case of warning, tras ERROR solo con Launch dependencies in case of error, y nunca tras STOPPED, INTERRUPTED o INFO. El planificador cierra la ejecución una sola vez, escribe su fin, envía el informe de la tarea y lanza las dependencias; cualquier otra finalización de la misma ejecución no hace nada.
El código que se ejecuta en la misma aplicación que el planificador puede completar la ejecución sin la API, con el bean SchedulerExecutionCompletionService:
CompletionResult result = completionService.complete(taskId, executionId, TaskStatus.JOB_OK,
"Calculation finished", null);
// result.outcome(): CLOSED, NOT_RUNNING, NOT_DEFERRED or UNKNOWN
Salidas
Los outputs de la finalización llegan a las dependencias que se lanzan cuando se cierra la ejecución, igual que los demás valores de la tarea padre: cada dependencia toma el valor de cada salida cuyo nombre coincide con uno de sus parámetros variables. Una salida sustituye a un parámetro de la tarea cerrada con el mismo nombre, y una salida sin nombre o sin valor se ignora.
curl -X POST "https://scheduler.example.com/scheduler/api/v1/tasks/12/executions/340/complete" \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"status": "OK", "outputs": {"resultFile": "/data/out/340.csv"}}'
Una dependencia con un parámetro variable resultFile se ejecuta con /data/out/340.csv.
Plazo, parada y reinicio
- Plazo: una ejecución que no se completa dentro del Timeout de la tarea, o dentro de
awe.scheduler.deferred.default-timeout(24 horas por defecto) cuando la tarea no tiene ninguno, contado desde el inicio de la ejecución, termina como interrumpida con el mensaje de timeout y no se lanzan sus dependencias. El planificador comprueba los plazos cadaawe.scheduler.deferred.timeout-check-interval(60 segundos por defecto), así que la ejecución puede terminar después de su plazo hasta ese intervalo. Una finalización que llegue más tarde recibe un409. Consulta la guía de configuración. - Parada: el botón Stop de la pantalla de tareas termina las ejecuciones en espera de la tarea seleccionada como detenidas, sin lanzar dependencias.
- Reinicio y clúster: el estado de una ejecución en espera se guarda en la base de datos, así que sobrevive a un reinicio. Al arrancar, el planificador interrumpe las ejecuciones que un nodo detenido dejó en marcha, salvo las que esperan a ser completadas. Todos los nodos comprueban los plazos y cualquier nodo puede recibir la finalización, pero solo la primera llamada que cierra una ejecución la termina.
Aviso de cancelación
Cuando un usuario detiene una ejecución diferida o se supera su plazo, el otro sistema puede seguir trabajando en ella. Rellena Mantenimiento de cancelación en la tarea (solo en tareas de mantenimiento) para avisarle: la llamada que cierra la ejecución lanza ese mantenimiento una sola vez, donde se ejecuta el mantenimiento de la tarea (en la aplicación AWE con un planificador externo), con estos parámetros:
| Parámetro | Valor |
|---|---|
taskId | Identificador de la tarea |
executionId | Identificador de la ejecución |
externalReference | El externalReference de la respuesta diferida |
Una finalización por la API o por SchedulerExecutionCompletionService no lo envía: el otro sistema cerró la ejecución. El aviso nunca reabre ni bloquea la ejecución: si el mantenimiento falla o responde un error, la ejecución sigue cerrada y el fallo se guarda en su traza.
Traza y contadores
Cada ejecución diferida guarda, tras cerrarse, quién la cerró y cuándo (API, DEADLINE o USER) y el resultado de su aviso de cancelación (SENT, o FAILED con el mensaje de error). El detalle de ejecución de la pantalla de tareas muestra la referencia, el plazo y esta traza. El panel del planificador muestra cuatro contadores: ejecuciones diferidas en curso, completadas por el otro sistema, interrumpidas por el plazo y detenidas por un usuario.
Base de datos de ejecución de la tarea
Una tarea maintain se ejecuta contra el datasource configurado mediante las propiedades spring.datasource.* de Spring Boot. Este es el caso en ambos modos de ejecución:
- Planificador local (embebido) — el maintain se ejecuta sobre el mismo datasource que la aplicación AWE principal.
- Instancia de planificador remota — el maintain se ejecuta sobre el datasource configurado para esa instancia del planificador.
Las tareas del planificador se ejecutan en un hilo de trabajo de Quartz sin sesión HTTP asociada. El enrutamiento interactivo multibase de datos en el que se apoya una petición web normal lee su destino del estado de la sesión/pantalla, que simplemente no existe aquí. Por ello, el planificador resuelve la conexión a partir del spring.datasource configurado en lugar de cualquier valor de sesión.
No existe un interruptor por tarea para "ejecutar esta tarea en la base de datos de la aplicación principal". Una instancia de planificador remota usa su propio spring.datasource. Para que apunte a la misma base de datos que tu aplicación principal, haz que el spring.datasource.url de esa instancia (y el usuario, la contraseña, …) apunten a la misma base de datos.
Apuntar a una base de datos diferente
Si una tarea maintain concreta debe ejecutarse contra una base de datos diferente de la configurada por defecto, añade un parámetro de tarea (consulta Parámetros de la tarea) cuyo nombre sea el criterio de base de datos y cuyo valor sea el alias del datasource de destino.
El nombre del parámetro no está fijado a database: es el valor de awe.database.parameter-name, que por defecto es _database_.
- Single-database (default)
- Multi-database
No hay nada que configurar. Con awe.database.multidatabase-enable establecido a false (el valor por defecto), cada tarea se ejecuta contra el único spring.datasource configurado, y un parámetro llamado _database_ se trata como un parámetro ordinario sin efecto de enrutamiento.
En un despliegue con awe.database.multidatabase-enable=true, añade un parámetro de tarea en el paso 2 (Parámetros de la tarea) del asistente:
| Campo | Valor |
|---|---|
| Name | _database_ (o tu awe.database.parameter-name configurado) |
| Source | Value |
| Value | El alias del datasource de destino (p. ej. reporting) |
Cuando la tarea se ejecuta, su maintain se enruta al datasource registrado bajo ese alias en lugar del predeterminado.
La conexión se resuelve de la siguiente manera:
awe.database.multidatabase-enabledebe sertrue. Cuando esfalse, el parámetro se ignora y la tarea siempre usa el datasource predeterminado.- El valor debe ser un alias de datasource registrado, no una URL JDBC sin procesar. Un alias desconocido genera un error de datasource no definido en tiempo de ejecución.
Esto se aplica solo a las tareas maintain. Una tarea de comando ejecuta un comando de shell y no tiene conexión a base de datos; consulta Ejecución de comandos: local y remota.
Configuración
Al crear una nueva tarea, se utiliza un asistente de creación de tareas para personalizar la configuración de la tarea.
El asistente de configuración consta de 5 pasos:
1. Información básica
En este paso tenemos que añadir la configuración básica de la tarea.
| Elemento | Definición | Uso |
|---|---|---|
| Name | Nombre de la tarea | Obligatorio |
| Active | Estado de la tarea; si no está activa, la tarea no se lanzará | Obligatorio |
| Description | Descripción de la tarea | Opcional |
| Max. stored executions | Número máximo de ejecuciones a almacenar en la base de datos (se utiliza para calcular el tiempo medio). El valor por defecto es 10. | Opcional |
| Timeout | Tiempo máximo para que la tarea finalice. Si el tiempo de ejecución de la tarea supera el tiempo de espera (expresado en segundos), la tarea se interrumpirá | Opcional |
| Execute | El tipo de ejecución de la tarea (Command o Maintain) | Obligatorio |
| Command | Comando a lanzar | Obligatorio (Solo necesario en el tipo de lanzamiento Command) |
| Execution path | Directorio de trabajo en el que se ejecuta el comando, y ubicación alternativa para el comando: primero se busca en el PATH del host, y después en esta ruta | Opcional (Solo necesario en el tipo de lanzamiento Command) |
| Run on remote server | Cuando está marcado, el comando se ejecuta en un host remoto mediante SSH en lugar de en el host local de AWE | Opcional (Solo necesario en el tipo de lanzamiento Command) |
| Remote server | El servidor SSH en el que se ejecuta el comando | Obligatorio cuando Run on remote server está marcado |
| Maintain | Maintain a lanzar | Obligatorio (Solo necesario en el tipo de lanzamiento Maintain) |
| Launch dependencies in case of warning | Lanzar las dependencias de la tarea en caso de advertencia | Opcional |
| Launch dependencies in case of error | Lanzar las dependencias de la tarea en caso de error | Opcional |
| Set execution as warning in case of error | Establece la ejecución padre como advertencia en caso de error en una dependencia | Opcional |
Nota: Para añadir un nuevo maintain al planificador, el maintain debe estar definido con
public="true".
2. Parámetros de la tarea
Este paso permite añadir los parámetros necesarios al maintain o comando para su ejecución.
Estos parámetros se cargan en el contexto de la aplicación cuando la tarea se va a ejecutar. De esta forma, la tarea puede obtener los parámetros en tiempo de ejecución.
| Elemento | Definición | Uso |
|---|---|---|
| Name | Nombre del parámetro | Obligatorio |
| Source | Origen del parámetro, el lugar del que tomará su valor | Obligatorio |
| Type | El tipo del parámetro (solo se usa para dar información adicional al usuario) | Obligatorio |
| Value | Para Value, el valor literal utilizado. Para Property, la clave de la propiedad de la aplicación a resolver. Para Variable, el valor por defecto precargado en el diálogo de lanzamiento manual (puede dejarse vacío) | Opcional |
Nota: Si el tipo de lanzamiento de la tarea es
Maintain, los parámetros necesarios para el maintain seleccionado se añadirán automáticamente a la pantalla de parámetros de la tarea.
Orígenes de los parámetros
El Source determina de dónde toma cada parámetro su valor en tiempo de ejecución:
- Value — el parámetro usa el valor literal escrito en el campo Value.
- Property — el valor se resuelve en tiempo de ejecución a partir de la propiedad de la aplicación cuya clave está en el campo Value (por ejemplo, un valor configurado en
application.yml). Úsalo para mantener los valores específicos de cada entorno fuera de la definición de la tarea. - Variable — el valor lo proporciona el operador cuando la tarea se lanza manualmente. Esto es para entradas que solo se conocen en tiempo de ejecución (una fecha de negocio, un id de entidad, un modo de ejecución…) y que no deberían estar fijadas en la tarea.
Cuando una tarea tiene uno o más parámetros Variable, al lanzarla desde la lista de tareas se abre un diálogo con un grid editable que lista exactamente esos parámetros. Cada fila se precarga con su Value configurado como valor por defecto editable; el operador revisa o cambia los valores y pulsa Launch, y la tarea se ejecuta con ellos. Las tareas sin parámetros Variable se lanzan directamente, sin diálogo.
Nota: El diálogo solo aparece en el lanzamiento manual, donde hay un operador presente para rellenarlo. En los lanzamientos programados y por archivo no hay nadie a quien preguntar, por lo que un parámetro
Variablerecurre a su Value configurado. En el lanzamiento por dependencia el valor se hereda de la tarea padre — consulta Propagación de parámetros a las dependencias.
3. Lanzamiento de la tarea
En este paso configuraremos el tipo de lanzamiento de la tarea.
Podemos elegir entre cuatro opciones diferentes:
1. Manual
La tarea solo se lanzará manualmente desde la pantalla de lista de tareas.
Nota: Para que una tarea pueda añadirse como dependencia, el tipo de lanzamiento debe estar establecido a
Manual.
2. Programado
La tarea se lanzará con una planificación basada en un patrón cron.
Consulta la guía de configuración de planificaciones para obtener más información sobre cómo crear planificaciones para una tarea.
3. Archivo
Con este tipo de lanzamiento, la tarea comprobará el/los archivo(s) seleccionado(s) con la planificación configurada.
Para saber cómo crear una planificación para la tarea, consulta la guía de configuración de planificaciones.
Los campos restantes son:
| Elemento | Definición | Uso |
|---|---|---|
| Search at | El servidor en el que el planificador debe comprobar los archivos | Obligatorio |
| File path | La ruta en la que se encuentran el/los archivo(s) | Obligatorio |
| File pattern | El patrón con el que deben coincidir los archivos | Obligatorio |
El tipo de conexión del servidor decide cómo se realiza la comprobación: folder lee una
carpeta local o compartida, ftp se conecta mediante FTP y ssh se conecta mediante SFTP.
Nota: Las credenciales de conexión no se configuran aquí. Tanto los servidores
ftpcomosshse autentican con las credenciales almacenadas en el propio servidor, las mismas que se usan para la ejecución remota de comandos, por lo que todas las tareas que apunten al mismo servidor las comparten.
4. Webhook
La tarea se lanza cuando otro sistema le envía un webhook firmado. Una tarea webhook no tiene planificación propia: cada webhook válido la lanza una vez, de inmediato, igual que un lanzamiento manual.
El hook de la tarea se define con estos campos:
| Elemento | Definición | Uso |
|---|---|---|
| Clave del hook | Última parte de la URL. Letras minúsculas, dígitos y guiones, de 1 a 64 caracteres. Otra tarea no puede usarla: una clave repetida se rechaza al guardar | Requerido |
| Hook activo | Un hook que no está activo se responde con 409 y no lanza nada | Requerido |
| Propiedad del secreto | Nombre de la propiedad de la aplicación que contiene el secreto de firma. El secreto en sí nunca se guarda ni se muestra | Requerido |
| Tipo de evento | Solo los webhooks de este type lanzan la tarea, el resto se almacenan y se ignoran. Vacío acepta cualquier tipo | Opcional |
El formulario muestra la URL del webhook de la clave, lista para copiar en el emisor:
https://<host>/<context-path>/scheduler/api/v1/webhooks/triggers/<hookKey>
La petición
La petición sigue Standard Webhooks: un POST con cuerpo JSON y las cabeceras webhook-id (identificador único del mensaje), webhook-timestamp (segundos Unix) y webhook-signature.
{
"type": "fit.market-data.loaded",
"timestamp": "2026-11-13T06:00:02Z",
"data": { "date": "2026-11-12", "entity": "0049" }
}
El cuerpo debe ser un objeto JSON con un objeto data y un type opcional. La firma es v1, seguido del base64 del HMAC-SHA256 de {webhook-id}.{webhook-timestamp}.{body} (los bytes exactos del cuerpo), con el secreto sin su prefijo whsec_ decodificado de base64 como clave:
import base64, hashlib, hmac
key = base64.b64decode("whsec_AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8=".removeprefix("whsec_"))
signed = f"{msg_id}.{timestamp}.{body}".encode()
signature = "v1," + base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest()).decode()
Para probar un emisor, este vector da la firma esperada (con la comprobación de la marca de tiempo desactivada o con el reloj fijado):
| Dato | Valor |
|---|---|
| Secreto | whsec_AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8= |
webhook-id | 0193f2a4-6c1e-7b3a-9d2e-5f8a1c4e7b20 |
webhook-timestamp | 1763029530 |
| Cuerpo | {"type":"job.finished","timestamp":"2025-11-13T10:25:30Z","data":{"jobId":"0193f2a0-1111-7aaa-8bbb-000000000001","status":"COMPLETED"}} |
webhook-signature | v1,A4hcS6QMtMJGUshESWRCI0SK2l7hfSW/LXYbcYD8Ef0= |
Las respuestas
| Respuesta | Cuándo |
|---|---|
202 {"messageId": "<webhook-id>"} | Aceptado, también cuando el webhook-id ya se había recibido. La tarea se lanza después, fuera de la petición |
400 | El cuerpo no es un objeto JSON con un objeto data |
401 | La firma o la marca de tiempo no son válidas, o la propiedad del secreto no tiene valor |
404 | Clave de hook desconocida |
409 | El hook o su tarea no están activos |
413 | El cuerpo es mayor que awe.scheduler.webhooks.max-body-size |
Deduplicación. Un webhook se identifica por su clave de hook y su webhook-id. Un webhook que ya se había recibido se responde de nuevo con 202 y no lanza la tarea por segunda vez, de modo que un emisor puede reintentar con seguridad.
Procesamiento. El webhook se almacena en una bandeja y se responde de inmediato. Un procesador lanza la tarea desde la bandeja cada awe.scheduler.webhooks.process-interval. Si el lanzamiento falla se reintenta tras una espera creciente, hasta 3 intentos en total, y después el webhook queda fallido con su error. Los webhooks procesados, ignorados y fallidos se purgan pasado awe.scheduler.webhooks.inbox-retention. La ejecución muestra webhook:<hookKey> como quien la lanzó. Si la tarea ya está en ejecución, el webhook lanza otra ejecución, igual que un lanzamiento manual. Mientras el scheduler está parado, los webhooks esperan en la bandeja y se lanzan cuando vuelve a arrancar.
Punteros de parámetros
El paso Parámetros de una tarea webhook tiene una columna Puntero JSON. Un puntero (por ejemplo /date) indica qué valor del data del webhook pasa al parámetro:
- Solo los parámetros
VARIABLEcon puntero reciben valores del webhook: los punteros son una lista blanca y nada más del webhook llega a la tarea. - Un puntero que no está en el webhook deja el valor almacenado del parámetro.
- Los valores mapeados pasan a ser los parámetros de la ejecución de flujo, de modo que llegan a todos los pasos del flujo que inicia la tarea (consulta Ejecuciones de flujo y fan-in).
Las propiedades, la rotación del secreto y la migración están en la guía de configuración.
4. Dependencias de la tarea
En este paso configuraremos qué tareas deben ejecutarse una vez que finalice la tarea actual.
Jugando con estas opciones, podemos crear un flujo de trabajo.
| Elemento | Definición | Uso |
|---|---|---|
| Task | La tarea a ejecutar | Obligatorio |
| Blocking | Define si la tarea es bloqueante o no. Si lo es, la tarea se ejecutará de forma síncrona y cancelará la pila de lanzamiento de dependencias si la tarea termina con un error. En caso contrario, la dependencia se lanzará de forma asíncrona | Obligatorio |
| Order | El orden en el que debe lanzarse la tarea síncrona en la pila de dependencias síncronas; las dependencias asíncronas se lanzarán según vayan llegando, sin un orden definido | Obligatorio |
Nota: Las dependencias también pueden tener sus propias dependencias para crear un flujo de trabajo.
Propagación de parámetros a las dependencias
Cuando una tarea lanza sus tareas dependientes (hijas), los valores de los parámetros del padre en el momento de la ejecución se propagan a cada hija. La hija define el contrato: solo los parámetros Variable de la hija cuyo nombre coincide con un parámetro del padre se sobrescriben con el valor del padre. Cualquier otro parámetro del padre es ignorado por esa hija, y los parámetros de la hija que no son Variable nunca se tocan.
- Qué se propaga — el valor del padre para un nombre dado, independientemente del origen del parámetro del padre (
Value,PropertyoVariable). Donde el padre obtuvo el valor es irrelevante; solo importa el nombre. - Valor por defecto cuando falta — si el padre no proporciona un nombre coincidente, la hija conserva su propio Value configurado como valor por defecto (sin regresión respecto al comportamiento anterior).
- Cascada — en cada salto el mapa de propagación se reconstruye a partir de la lista de parámetros propia de la tarea actual, de modo que un valor solo continúa más allá de una tarea intermedia si esa tarea también declara un parámetro con ese nombre. Un valor que el padre proporciona para un nombre que una hija intermedia no declara se detiene en esa hija y no se pasa a la nieta.
Ejemplo, con una tarea padre que tiene database = "prod" (origen Value):
| Declaración del parámetro de la hija | Valor efectivo en la hija | Motivo |
|---|---|---|
database como Variable | "prod" | El nombre coincide con un parámetro del padre y la hija optó por ello mediante Variable |
database como Value = "test" | "test" | No es una Variable; nunca se sobrescribe |
region como Variable (el padre no tiene region) | su valor por defecto configurado | El padre no proporciona ningún nombre coincidente |
Esto reutiliza el mismo mecanismo que los valores proporcionados por el operador en el lanzamiento manual, por lo que un valor que un operador escribió en el diálogo de lanzamiento del padre también fluye hacia sus dependientes.
La propagación se basa en el nombre: cualquier tarea dependiente que declare un parámetro Variable que coincida con el nombre de un parámetro del padre recibe el valor del padre en tiempo de ejecución — incluidos valores que pueden ser sensibles (credenciales, cadenas de conexión). La configuración de las tareas es un límite de confianza de los administradores; no añadas dependencias de procedencia no fiable a tareas que contengan parámetros sensibles.
5. Informe de la tarea
El último paso es elegir un tipo de informe.
El informe dará información sobre la tarea cuando esta finalice.
Podemos elegir una de estas cuatro opciones:
5.1 Ninguno
Se usa cuando no queremos obtener ningún informe de la tarea.
Esto podría compararse con la acción silenciosa (silent-action) de AWE.
5.2 Correo electrónico
Esta opción enviará un correo electrónico con la información de la tarea, y también añadirá la información de las dependencias, si las hay.
| Elemento | Definición | Uso |
|---|---|---|
| Send in case of | Establece el estado permitido (estado de la tarea al finalizar) para enviar el correo | Obligatorio |
| Email server | El servidor de correo desde el que se va a enviar el correo | Obligatorio |
| Send to users | La lista de usuarios a los que enviar el correo | Obligatorio |
| Title | El título del correo | Obligatorio |
| Message | El mensaje a añadir en el correo | Obligatorio |
Nota: El correo también añadirá información básica sobre la propia tarea y sus dependencias.
Variables dinámicas en Title y Message
Los campos Title y Message admiten marcadores ${variable} que se resuelven con valores propios de cada ejecución antes de enviar el correo. Esto permite que una única plantilla produzca un correo personalizado para cada ejecución de la tarea.
Los marcadores pueden hacer referencia a dos tipos de valores: metadatos de la tarea/ejecución (nombres reservados) y parámetros de la tarea (por nombre).
Variables de metadatos
| Variable | Descripción |
|---|---|
${taskName} | Nombre de la tarea |
${taskId} | Identificador de la tarea |
${taskDescription} | Descripción de la tarea |
${status} | Etiqueta del estado final de la ejecución (p. ej. OK, ERROR) |
${statusDetail} | Detalle adicional sobre el estado de la ejecución |
${executionId} | Identificador de la ejecución |
${command} | Comando/acción ejecutado por la tarea |
Variables de parámetros de la tarea
Cualquier marcador cuyo nombre coincida con un parámetro de la tarea (de la pestaña Parameters de la tarea) se reemplaza por el valor de ese parámetro. Por ejemplo, ${env} se resuelve al valor del parámetro env.
Reglas de resolución
- Los nombres reservados tienen prioridad. Si un parámetro de la tarea tiene el mismo nombre que una variable de metadatos (p. ej.
status), prevalece el valor de los metadatos y se registra una advertencia con el nombre del parámetro ensombrecido. - Los marcadores desconocidos se conservan literalmente. Un
${variable}sin clave de metadatos ni parámetro de tarea coincidente se deja intacto en la salida; nunca se deja en blanco ni se elimina. - El HTML se escapa de forma segura. En el cuerpo HTML, los valores sustituidos se escapan en HTML para que no puedan romper el marcado ni inyectar contenido; el cuerpo en texto plano recibe los valores sin procesar. El texto de la plantilla en sí nunca se escapa.
- Compatible con versiones anteriores. Un Title o Message sin ningún marcador
${...}se envía exactamente como está escrito.
Ejemplo
- Title:
Task ${taskName} finished: ${status} - Message:
Execution ${executionId} for environment ${env} ended with status ${status}.
Nota: La sustitución de variables se aplica solo a los campos Title y Message, no al bloque fijo de detalles de la tarea que el informe añade automáticamente.
5.3 Difusión (Broadcast)
Esta opción enviará un mensaje de difusión con el mensaje indicado solo a los usuarios seleccionados.
| Elemento | Definición | Uso |
|---|---|---|
| Send in case of | Establece el estado permitido (estado de la tarea al finalizar) para enviar la difusión | Obligatorio |
| Send to users | La lista de usuarios a los que enviar la difusión | Obligatorio |
| Message | El mensaje a enviar en la difusión | Obligatorio |
5.4 Maintain
Esta opción lanzará el maintain seleccionado como un informe.
| Elemento | Definición | Uso |
|---|---|---|
| Send in case of | Establece el estado permitido (estado de la tarea al finalizar) para ejecutar el maintain | Obligatorio |
| Message | El mensaje a enviar; se añadirá al contexto para que esté disponible para el maintain seleccionado | Opcional |
Nota: Los datos de la tarea se añadirán al contexto para que estén disponibles para el maintain seleccionado; para obtener los datos, se recomienda usar los nombres de variable de la interfaz TaskConstants del paquete Scheduler.
Gestión de tareas
Las tareas existentes se pueden gestionar desde la pantalla de tareas del planificador, donde tendremos una lista de las tareas creadas.
La lista mostrará información básica de cada tarea, como el nombre, el tipo de lanzamiento (icono), los tiempos de la última y la próxima ejecución, el estado de la tarea y el tiempo medio de ejecución.
Al seleccionar una tarea, se activarán algunas opciones:
| Opción | Definición | Múltiple |
|---|---|---|
| Update | Actualiza la tarea seleccionada | No |
| Delete | Elimina la(s) tarea(s) seleccionada(s) | Sí |
| Start | Lanza la tarea seleccionada como una tarea manual. No es necesario que sea una tarea manual para lanzar una instancia de la tarea manualmente | No |
| Activate/Deactivate | Activa / desactiva la tarea seleccionada; la etiqueta cambia según el estado actual de la tarea seleccionada | No |
Servidores
Los servidores creados para el módulo Scheduler se utilizan principalmente para ejecutar tareas, y en tareas que necesitan comprobar si un archivo ha cambiado.
Los servidores del planificador se usan con dos propósitos: ejecutar tareas de comando en un host remoto mediante SSH, y comprobar modificaciones de archivos en un servidor remoto.
Para la ejecución remota de comandos elige el tipo de conexión ssh y proporciona el usuario de conexión junto con una contraseña y/o una clave privada (que puede estar protegida con frase de contraseña). Para la comprobación de archivos elige ftp para conectar mediante FTP, o ssh para conectar mediante SFTP, preferible cuando FTP no está permitido, ya que reutiliza las credenciales SSH y la verificación de claves de host. Un servidor ftp también se autentica con el usuario y la contraseña del servidor; dejar el usuario vacío mantiene el acceso anónimo.
El mismo servidor puede ser usado por tantas tareas como sea necesario. Sus credenciales de conexión se almacenan en el propio servidor, por lo que todas ellas comparten el mismo usuario y contraseña.
Configuración
Al crear un nuevo servidor, hay que rellenar los siguientes campos:
| Elemento | Definición | Uso |
|---|---|---|
| Name | Nombre del servidor | Obligatorio |
| Server | Dirección IP del servidor | Obligatorio |
| Port | Puerto del servidor | Obligatorio |
| Type of connection | El protocolo a utilizar para conectar con el servidor | Obligatorio |
| User | Usuario para la conexión con el servidor (se muestra cuando el tipo de conexión es ssh o ftp) | Obligatorio para ssh |
| Password | Contraseña para la conexión con el servidor (se muestra cuando el tipo de conexión es ssh o ftp) | Opcional |
| Private key | Clave privada para la autenticación SSH basada en clave (se muestra cuando el tipo de conexión es ssh) | Opcional |
| Private key passphrase | Frase de contraseña que desbloquea la clave privada, si está cifrada (se muestra cuando el tipo de conexión es ssh) | Opcional |
| Active | Estado del servidor | Obligatorio |
Nota: Si un servidor se desactiva, la tarea que lo use ni siquiera intentará conectarse a él.
Nota: Un servidor
sshse autentica con el usuario más una contraseña, una clave privada (opcionalmente desbloqueada con su frase de contraseña), o ambas. Solo el usuario es obligatorio; proporciona al menos una de contraseña o clave.
Nota: Un servidor
ftpse autentica solo con el usuario y la contraseña, ambos opcionales: deja el usuario vacío para el acceso anónimo. Las claves privadas no se usan sobre FTP.
Nota: La autenticación SSH la gestiona Apache MINA SSHD. Se admiten los algoritmos de clave privada más comunes (RSA, ECDSA y Ed25519) en formatos OpenSSH y PEM.
Nota: Un servidor
sshse utiliza tanto para las tareas de comando remoto como para las tareas disparadas por existencia de archivos mediante SFTP. La política de claves de host configurada y el archivoknown_hostsse aplican a ambos, por lo que un host de confianza para la ejecución de comandos también lo es para la comprobación de archivos.
Nota: Las credenciales del servidor (contraseña, clave privada y frase de contraseña) se almacenan cifradas, por instancia de servidor, de modo que el mismo host puede registrarse varias veces con credenciales diferentes. En la pantalla de edición nunca se devuelven al cliente: deja un campo secreto en blanco para conservar el valor almacenado, o escribe un nuevo valor para reemplazarlo.
Gestión
La lista de servidores del planificador mostrará una lista de servidores con su información básica: nombre, ip del servidor, protocolo de conexión y estado.
Al seleccionar uno de los servidores de la lista, se habilitarán algunas opciones:
| Opción | Definición | Múltiple |
|---|---|---|
| Update | Actualiza el servidor seleccionado | No |
| Delete | Elimina el/los servidor(es) seleccionado(s) | Sí |
| Activate / Deactivate | Activa / desactiva el servidor seleccionado; la etiqueta cambia según el estado actual de los servidores seleccionados | No |
Calendarios
Las tareas dentro del planificador pueden modificarse para ignorar algunas fechas mediante calendarios de festivos.
Esos calendarios contienen las fechas que debe ignorar el planificador en la planificación de la tarea.
Cada una de las tareas solo puede asociarse a un calendario.
Los calendarios dentro del módulo Scheduler se usan para establecer las fechas en las que las tareas no tienen que ejecutarse, como, por ejemplo, festivos o fines de semana.
Cada tarea solo puede tener asociado un calendario, pero se pueden crear tantos calendarios como sean necesarios y luego simplemente cambiar el calendario asociado a la tarea.
Configuración
El procedimiento de configuración del calendario consta de dos pasos:
Crear calendario
El primer paso es crear el propio calendario, que tendrá la siguiente información básica.
| Elemento | Definición | Uso |
|---|---|---|
| Name | El nombre del calendario | Obligatorio |
| Description | La descripción del calendario | Obligatorio |
| Active | El estado del calendario | Obligatorio |
Nota: Si el estado del calendario se establece a
Active = No, la tarea ignorará el calendario y se lanzará como si no estuviera asociada a él.
Añadir fechas
Una vez creado el calendario, desde la pantalla de configuración del calendario, podemos añadir nuevas fechas seleccionando la opción de editar en la parte superior derecha de la pantalla.
Cuando lleguemos a la pantalla de edición tendremos que rellenar los siguientes campos para cada fecha.
| Elemento | Definición | Uso |
|---|---|---|
| Date | La fecha a añadir al calendario | Obligatorio |
| Name | Un nombre a asignar a la fecha, por ejemplo, el nombre de un festivo | Opcional |
Gestión
En la pantalla de lista de calendarios, al seleccionar uno de ellos, estarán disponibles las siguientes opciones:
| Opción | Definición | Múltiple |
|---|---|---|
| Edit | Redirige a la pantalla de edición donde podemos cambiar los datos del calendario y añadir/eliminar/actualizar fechas del calendario | No |
| Delete | Elimina el calendario y todas sus fechas asociadas | Sí |
| Activate/Deactivate | Activa / desactiva el calendario seleccionado; la etiqueta cambia según el estado actual de los calendarios seleccionados | No |