Scheduler
This document gives a minimum base to start with the AWE Scheduler module, and explains how to automate and schedule tasks inside AWE in a simple way.
The Scheduler module is based on the Quartz Scheduler library.
All documentation related to the Quartz Scheduler library can be found on its web page.
Prerequisites
The scheduler module needs to be configure before it is used.
To see how to configure the scheduler module for your application see the Configuration guide.
Remote scheduler setup
You can split the scheduler into a dedicated AWE instance and have your main AWE application delegate scheduling to it.
1. Configure the scheduler instance
On the dedicated scheduler node, enable scheduler-only mode and configure the callback to your main AWE app:
# 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. Configure the main AWE instance
On the main AWE app, enable remote scheduler usage and point to the scheduler base API URL:
awe.scheduler.remote-enabled=true
awe.scheduler.remote-scheduler-url=http://localhost:8090/scheduler/api/v1
Note: The remote scheduler base URL must target the scheduler instance API (default:
/scheduler/api/v1).
Tasks
A task consists on a job associated to a trigger that is executed by the Scheduler in the configured time / moment.
A task can also be concatenated with other tasks to create a workflow. This can be done by adding those other tasks as dependencies in the parent task configuration wizard.
A task consists on a job associated to a trigger that is executed by the Scheduler in the configured time / moment.
A task can also be concatenated with other tasks in order to create a workflow. This can be done by adding those other tasks as dependencies in the parent task configuration wizard.
Types
There are two type of tasks that the scheduler can work with, the maintain tasks and the command tasks.
| Maintain Task | Command Task |
|---|---|
| A maintain task executes a public maintain with a defined schedule. | A command task runs a shell command with a defined schedule, either on the local AWE host or on a remote host over SSH. |
Command execution: local and remote
A command task runs the value entered in the Command field as a shell command. The Execution path, when set, is used as the working directory the command runs in; the command itself is resolved from the host PATH. To run a script that lives in the execution path, invoke it explicitly (for example, ./my-script.sh).
- Local execution (default): when Run on remote server is left unchecked, the command runs on the AWE host itself.
- Remote execution over SSH: when Run on remote server is checked, a Remote server must be selected. The command is executed on that host through an SSH exec channel, and both its standard output and standard error are captured into the task execution log.
Remote command execution requires the selected server to use the ssh connection type. Authentication is done with the server user together with either a password, a private key (optionally passphrase-protected), or both. See Servers for how to configure them, and the Configuration guide for the SSH host-key verification options.
Task execution database
A maintain task runs against the datasource configured through Spring Boot's spring.datasource.* properties. This is the case in both execution modes:
- Local (embedded) scheduler — the maintain runs on the same datasource as the main AWE application.
- Remote scheduler instance — the maintain runs on the datasource configured for that scheduler instance.
spring.datasource instead of any session value. :::spring.datasource. To make it target the same database as your main application, point that instance's spring.datasource.url (and user, password, …) at the same database. :::Targeting a different database
If a specific maintain task must run against a different database than the configured default, add a task parameter (see Task parameters) whose name is the database criterion and whose value is the target datasource alias.
The parameter name is not hardcoded to database: it is the value of awe.database.parameter-name, which defaults to _database_.
- Single-database (default)
- Multi-database
Nothing to configure. With awe.database.multidatabase-enable set to false (the default), every task runs against the single configured spring.datasource, and a parameter named _database_ is treated as an ordinary parameter with no routing effect.
On a deployment with awe.database.multidatabase-enable=true, add a task parameter in step 2 (Task parameters) of the wizard:
| Field | Value |
|---|---|
| Name | _database_ (or your configured awe.database.parameter-name) |
| Source | Value |
| Value | The alias of the target datasource (e.g. reporting) |
When the task executes, its maintain is routed to the datasource registered under that alias instead of the default one.
The connection is resolved as follows:
awe.database.multidatabase-enablemust betrue. When it isfalse, the parameter is ignored and the task always uses the default datasource.- The value must be a registered datasource alias, not a raw JDBC URL. An unknown alias raises an undefined datasource error at execution time. :::
Configuración
When creating a new task, a task creation wizard is used to personalize the task configuration.
The configuration wizard consists in 5 steps:
1. Basic information.
In this step we have to add the task basic configuration.
| Elemento | Definition | Uso |
|---|---|---|
| Name | Task name | Obligatorio |
| Active | Task status, if not active the task would not be launched | Obligatorio |
| Descripción | Task description | Opcional |
| Max. stored executions | Maximum number of executions to be stored in the database (Used to calculate the average time). The default value is 10. | Opcional |
| Timeout | Maximum time for the task to finish. If the task execution time exceeds the timeout time (represented in seconds) the task will be interrupted | Opcional |
| Execute | The task execution type (Command or Maintain) | Obligatorio |
| Command | Command to launch | Required (Only needed in Command launch type) |
| Execution path | Working directory the command runs in. The command is resolved from the host PATH; use ./<script> to run a script located in this path | Optional (Only needed in Command launch type) |
| Run on remote server | When checked, the command runs on a remote host over SSH instead of on the local AWE host | Optional (Only needed in Command launch type) |
| Remote server | The SSH server on which the command is executed | Required when Run on remote server is checked |
| Maintain | Maintain to launch | Required (Only needed in Maintain launch type) |
| Launch dependencies in case of warning | Launch the task dependencies in case of warning | Opcional |
| Launch dependencies in case of error | Launch the task dependencies in case of error | Opcional |
| Set execution as warning in case of error | Sets the parent execution as warning in case of dependency error | Opcional |
Note: To add a new maintain to the Scheduler, the maintain must be set to
public="true".
2. Task parameters
This step allows to add the needed parameters to the maintain or command for its execution.
These parameters are loaded to the application context when the task is going to be executed. In this way, the task can get the parameters in the execution time.
| Elemento | Definition | Uso |
|---|---|---|
| Name | Parameter name | Obligatorio |
| Source | Parameter source, the place from which the parameter will take its value | Obligatorio |
| Tipo | The parameter type (Only used to give extra information to the user) | Obligatorio |
| Value | For Value, the literal value used. For Property, the key of the application property to resolve. For Variable, the default value pre-filled in the manual-launch dialog (may be left empty) | Opcional |
Note: If the task launch type is
Maintain, the needed parameters for the selected maintain will be automatically added to the task parameters screen.
Parameter sources
The Source determines where each parameter takes its value from at execution time:
- Value — the parameter uses the literal value typed in the Value field.
- Property — the value is resolved at execution time from the application property whose key is in the Value field (for example a value configured in
application.yml). Use it to keep environment-specific values out of the task definition. - Variable — the value is supplied by the operator when the task is launched manually. This is for inputs that are only known at run time (a business date, an entity id, a run mode…) and should not be hardcoded in the task.
When a task has one or more Variable parameters, launching it from the task list opens a dialog with an editable grid listing exactly those parameters. Each row is pre-filled with its configured Value as an editable default; the operator reviews or changes the values and presses Launch, and the task runs with them. Tasks without Variable parameters launch directly, with no dialog.
Note: The dialog only appears on manual launch, where an operator is present to fill it in. On scheduled and file launches there is nobody to prompt, so a
Variableparameter falls back to its configured Value. On dependency launch the value is inherited from the parent task — see Parameter propagation to dependencies.
3. Task launch
In this step we will configure the launch type for the task.
We can choose from three different options:
1. Manual
The task will only be launched manually from the task list screen.
Note: For a task to be added as a dependency, the launch type must be set to
Manual.
2. Scheduled
The task will be launched with a cron pattern based schedule.
See schedule configuration guide for more information about how to create schedules for a task.
3. File
With this launch type, the task will launch a check in the selected file/s with the configured schedule.
To know how to create a schedule for the task see schedule configuration guide.
The remaining fields are:
| Elemento | Definition | Uso |
|---|---|---|
| Search at | The server in which the scheduler has to check for the files | Obligatorio |
| File path | The path in which the file/s are located | Obligatorio |
| File pattern | The pattern that the files have to match with | Obligatorio |
| User | The user for the FTP connection | Opcional |
| Password | The password for the FTP connection | Opcional |
4. Task dependencies
In this step we will configure which tasks have to be executed after the current task finishes.
Playing with these options, we can create a workflow.
| Elemento | Definition | Uso |
|---|---|---|
| Task | The task to be executed | Obligatorio |
| Blocking | Defines if the task is blocking or not. If it is, the task will be executed synchronously, and it will cancel the dependency launch stack if the task ends with an error. Otherwise, the dependency will be launched asynchronously | Obligatorio |
| Order | The order in which the synchronous task has to be launched in the synchronous dependency stack, the asynchronous dependencies will be launched as they come, with no defined order | Obligatorio |
Note: The dependencies can also have their own dependencies to create a workflow.
Parameter propagation to dependencies
When a task launches its dependent (child) tasks, the parent's parameter values at execution time are propagated to each child. The child defines the contract: only the child's Variable parameters whose name matches a parent parameter are overridden with the parent's value. Every other parent parameter is ignored by that child, and the child's non-Variable parameters are never touched.
- What propagates — the parent's value for a given name, regardless of the parent parameter's source (
Value,PropertyorVariable). Where the parent obtained the value is irrelevant; only the name matters. - Default when absent — if the parent does not supply a matching name, the child keeps its own configured Value as the default (no regression versus previous behavior).
- Cascade — at each hop the propagation map is rebuilt from the current task's own parameter list, so a value only continues past an intermediate task if that task also declares a parameter with that name. A value the parent supplies for a name an intermediate child does not declare stops at that child and is not passed on to the grandchild.
Example, with a parent task that holds database = "prod" (source Value):
| Child parameter declaration | Effective value in the child | Why |
|---|---|---|
database as Variable | "prod" | Name matches a parent parameter and the child opted in via Variable |
database as Value = "test" | "test" | Not a Variable; never overridden |
region as Variable (parent has no region) | its configured default | Parent supplies no matching name |
This reuses the same mechanism as the operator-supplied values on manual launch, so a value an operator typed into the parent's launch dialog also flows down to its dependents.
Variable parameter matching a parent parameter name receives the parent's value at execution time — including values that may be sensitive (credentials, connection strings). Task configuration is an administrator-trusted boundary; do not attach dependencies of untrusted provenance to tasks holding sensitive parameters. :::3. Task report
The last step is to choose a report type.
The report will give information about the task when it finishes.
We can choose one of these four options:
3.1 None
Used when we don't want to retrieve any report from the task.
This could be compared to the silent-action in AWE.
3.2 Email
This option will send an email with the task information, and it will also add the dependencies information if any.
| Elemento | Definition | Uso |
|---|---|---|
| Send in case of | Set the allowed status (task status when it finishes) for sending the email | Obligatorio |
| Email server | The email server form where the email is going to be sent | Obligatorio |
| Send to users | The list of users to send the email | Obligatorio |
| Title | The title of the email | Obligatorio |
| Mensaje | The message to be added in the email | Obligatorio |
Note: The email will also add basic information about the task itself and its dependencies.
Dynamic variables in Title and Message
The Title and Message fields support ${variable} placeholders that are resolved with per-execution values before the email is sent. This lets a single template produce a customized email for every task execution.
Placeholders can reference two kinds of values: task/execution metadata (reserved names) and task parameters (by name).
Metadata variables
| Variable | Descripción |
|---|---|
${taskName} | Name of the task |
${taskId} | Task identifier |
${taskDescription} | Task description |
${status} | Final execution status label (e.g. OK, ERROR) |
${statusDetail} | Additional detail about the execution status |
${executionId} | Execution identifier |
${command} | Command/action executed by the task |
Task parameter variables
Any placeholder whose name matches a task parameter (from the task Parameters tab) is replaced with that parameter's value. For example, ${env} resolves to the value of the env parameter.
Resolution rules
- Reserved names take precedence. If a task parameter has the same name as a metadata variable (e.g.
status), the metadata value wins and a warning is logged naming the shadowed parameter. - Unknown placeholders are kept literally. A
${variable}with no matching metadata key or task parameter is left untouched in the output; it is never blanked or removed. - HTML is escaped safely. In the HTML body, substituted values are HTML-escaped so they cannot break the markup or inject content; the plain-text body receives the raw values. The template text itself is never escaped.
- Backward compatible. A Title or Message without any
${...}placeholder is sent exactly as written.
Example
- Title:
Task ${taskName} finished: ${status} - Message:
Execution ${executionId} for environment ${env} ended with status ${status}.
Note: Variable substitution applies only to the Title and Message fields, not to the fixed task-details block that the report appends automatically.
3.3 Broadcast
This option will send a broadcast message with the given message to the selected users only.
| Elemento | Definition | Uso |
|---|---|---|
| Send in case of | Set the allowed status (task status when it finishes) for sending the broadcast | Obligatorio |
| Send to users | The list of users to send the broadcast | Obligatorio |
| Mensaje | The message to be sent in the broadcast | Obligatorio |
4. Maintain
This option will launch the selected maintain as a report.
| Elemento | Definition | Uso |
|---|---|---|
| Send in case of | Set the allowed status (task status when it finishes) for executing the maintain | Obligatorio |
| Mensaje | The message to be sent, it will be added to the context in order to be available for the selected maintain | Opcional |
Note: The task data will be added to the context in order to be available for the selected maintain, to get the data, it is recommended to use the TaskConstants interface variable names from the Scheduler package.
Task management
The existing tasks can be managed from the scheduler tasks screen, where we will have a list of the created tasks.
The list will show some basic information of each task, like the name, the launch type (icon), the last and next execution times, the task status and the execution average time.
When selecting one task, some options will be activated:
| Option | Definition | Multiple |
|---|---|---|
| Update | Update the selected task | No |
| Delete | Delete the selected task/s | Si |
| Start | Launch the selected task as a manual task. It doesn't need to be a manual task in order to launch an instance of the task manually | No |
| Activate/Deactivate | Act |
Servers
The servers created for the Scheduler module are mainly used to execute tasks, and in tasks that need to check if a file has changed.
The servers can be instantiated multiple times, and each instantiation can use its own user and password to connect to the server with the selected protocol.
The scheduler servers are used with two purposes: to run command tasks on a remote host over SSH, and to check for file modifications on an FTP server.
For remote command execution choose the ssh connection type and provide the connection user together with a password and/or a private key (which may be passphrase-protected); for file checking use the ftp connection type.
Regarding the FTP servers, the same server can be used as many times as needed, in different tasks, with different credentials.
Configuración
When creating a new server, the next fields have to be filled:
| Elemento | Definition | Uso |
|---|---|---|
| Name | Server name | Obligatorio |
| Server | Server IP address | Obligatorio |
| Port | Server port | Obligatorio |
| Type of connection | The protocol to be used to connect to the server | Obligatorio |
| User | User for the SSH connection (shown when the connection type is ssh) | Required for ssh |
| Password | Password for the SSH connection (shown when the connection type is ssh) | Opcional |
| Private key | Private key for SSH key-based authentication (shown when the connection type is ssh) | Opcional |
| Private key passphrase | Passphrase that unlocks the private key, if it is encrypted (shown when the connection type is ssh) | Opcional |
| Active | Server status | Obligatorio |
Note: If a server is deactivated, the task using it won't even try to connect to it.
Note: An SSH server authenticates with the user plus a password, a private key (optionally unlocked with its passphrase), or both. Only the user is mandatory; provide at least one of password or key.
Note: SSH authentication is handled by Apache MINA SSHD. The most common private-key algorithms are supported — RSA, ECDSA and Ed25519 — in OpenSSH and PEM formats.
Note: SSH credentials (password, private key and passphrase) are stored encrypted, per server instance, so the same host can be registered several times with different credentials. On the edit screen they are never sent back to the client: leave a secret field blank to keep the stored value, or type a new value to replace it.
Management
The scheduler server list will show a list of servers with their basic information: name, server ip, connection protocol and status.
When selecting one of the servers from the list, some options will be enabled:
| Option | Definition | Multiple |
|---|---|---|
| Update | Update the selected server | No |
| Delete | Deletes the selected server/s | Si |
| Activate / Deactivate | Activates / deactivates the selected server, the label changes depending on the selected servers current status | No |
Calendars
The task inside the scheduler can be modified to ignore some dates by using holiday calendars.
Those calendars contain the dates that have to be ignored by the scheduler in the task schedule.
Each of the tasks can only be associated with one calendar.
The calendars inside Scheduler module are used to set the dates where the tasks won't have to be executed, like for example, holidays, or weekends.
Each task can only have associated one calendar, but there can be created as many calendars as needed, and then just change the calendar associated to the task.
Configuración
The calendar configuration procedure consists in two steps:
Create calendar
The first step is to create the calendar itself, which will have the next basic information.
| Elemento | Definition | Uso |
|---|---|---|
| Name | The calendar name | Obligatorio |
| Descripción | The calendar description | Obligatorio |
| Active | The calendar status | Obligatorio |
Note: If the calendar status is set to
Active = Nothe task will ignore the calendar, and it will be launch as if it wasn't associated with it.
Add dates
Once the calendar is created, from the calendar configuration screen, we can add new dates by selecting the option edit on the top right side of the screen.
When we get to the edition screen we will have to fill the next fields for each date.
| Elemento | Definition | Uso |
|---|---|---|
| Date | The date to add to the calendar | Obligatorio |
| Name | A name to assign to the date, for example, a holiday name | Opcional |
Management
On the calendar list screen, when selecting one of them, the next options will be available:
| Option | Definition | Multiple |
|---|---|---|
| Edit | Redirects to the edition screen where we can change the calendar data, and add/remove/update calendar dates | No |
| Delete | Delete calendar and all its associated dates | Si |
| Activate/Deactivate | Activates / deactivates the selected calendar, the label changes depending on the selected calendars current status | No |