Scheduler Endpoint (Trigger)

The Scheduler component is a Mule event source that triggers the execution of a flow based on a time-based condition. For example, a Scheduler might create and send a message that will trigger the flow processing every 5 seconds or every day at 12:00 in a given time zone.

Consider the following when adding a Scheduler to your Mule application:

Schedulers use the same timezone as the machine on which Mule is running. However, if an application is running in CloudHub, the Scheduler conforms to the UTC timezone, regardless of the geographic region in which the application is running.

To set a different time zone for the Scheduler, see timeZone in Cron (<cron/>).
The disallowConcurrentExecution property enables you to prevent the Scheduler from triggering the execution of the flow while a previously-triggered execution is running.
If back-pressure occurs because no resources are available at the time of the scheduled trigger, Mule skips that execution.
In a Mule runtime engine cluster or multi-worker CloudHub deployment, the Scheduler executes only on the primary node (that is, only in one Mule instance).

Architecture

Like other Mule event source components, a Scheduler is the first component in a Mule flow.

The XML for the Scheduler consists of the following elements:

<scheduler />: Top-level element of the Scheduler.
<scheduling-strategy />: Second-level element that accepts one of the following children:
- <fixed-frequency />: For common scheduling frequencies, such as every second.
- <cron />: For cron expressions and time zone settings.

The Scheduler sets a scheduling strategy at a fixed frequency or an interval based on a cron expression. For example:

The fixed frequency setting in the following Scheduler executes every fifteen seconds:

<flow name="ex-fixed-frequency-flow" >
  <scheduler doc:name="Scheduler">
    <scheduling-strategy>
      <fixed-frequency frequency="15" timeUnit="SECONDS" />
    </scheduling-strategy>
  </scheduler>
  <!-- One or more processors here. -->
</flow>

The cron expression in this Scheduler triggers the generation of a Mule message in a new execution of the flow every fifteen seconds:

<flow name="ex-cron-expression-flow" >
  <scheduler doc:name="Scheduler" >
    <scheduling-strategy >
      <cron expression='0/15 * * * * ? '/>
    </scheduling-strategy>
  </scheduler>
  <!-- One or more processors here. -->
</flow>

At least one processor must follow the Scheduler. Processors include Mule components and connector operations, such as an HTTP Request operation or Transform Message component. Failure to provide a processor produces a MuleRuntimeException and causes the deployment of the Mule application to fail with the following ERROR message in the logs (edited for readability):

ERROR ...MuleRuntimeException ...
The content of element 'flow' is not complete.
One of '{"http://www.mulesoft.org/schema/mule/core":abstract-message-processor,
"http://www.mulesoft.org/schema/mule/core":abstract-mixed-content-message-processor}'
is expected.

For Scheduler attributes, see Reference.

Reference

The Scheduler elements accept attributes for configuring the execution interval and concurrency.

Scheduler (`<scheduler/>`)

By default, the Scheduler does not wait for one execution of a given flow to complete before executing another instance of the flow at the configured cadence. You can change this behavior by setting the disallowConcurrentExecution="true" attribute directly in the configuration XML.

Attribute XML Description

Attribute XML	Description
`disallowConcurrentExecution`	When this attribute is set to `true`, the Scheduler skips its scheduled execution if a previous execution is still running. Once the flow finishes, the Scheduler executes at the next configured interval. The default value is `false`.

disallowConcurrentExecution

When this attribute is set to true, the Scheduler skips its scheduled execution if a previous execution is still running. Once the flow finishes, the Scheduler executes at the next configured interval. The default value is false.

In the following example, the Scheduler skips its execution if the flow takes longer to complete than the fixed frequency of 10 milliseconds:

<flow name="scheduler-disallowConcurrentExecution-ex" >
  <scheduler doc:name="Scheduler" disallowConcurrentExecution="true" >
    <scheduling-strategy>
      <fixed-frequency frequency="10" timeUnit="MILLISECONDS"/>
    </scheduling-strategy>
  </scheduler>
  <!-- processors here -->
</flow>

Each time a Scheduler skips its execution, Mule logs an Execution skipped message, for example (edited for readability):

INFO  2022-11-09 15:15:43,082 ...
...scheduler.DefaultSchedulerMessageSource:
Flow 'scheduler-disallowConcurrentExecution-ex' is already running and
'disallowConcurrentExecution' is set to 'true'. Execution skipped.

INFO  2022-11-09 15:15:43,083 ...
...scheduler.DefaultSchedulerMessageSource:
Flow 'scheduler-disallowConcurrentExecution-ex' is already running and
'disallowConcurrentExecution' is set to 'true'. Execution skipped.

Fixed Frequency (`<fixed-frequency/>`)

The fixed frequency scheduling strategy accepts the following attributes:

Attribute XML Default Description

Attribute	XML	Default	Description
Frequency	`frequency`	`1000`	The frequency at which the Scheduler triggers the flow given the `timeUnit` setting.
Start Delay	`startDelay`	`0`	The amount of time to delay execution of the Scheduler for the first time after the application starts. This property uses the same `timeUnit` as the frequency.
Time Unit	`timeUnit`	`MILLISECONDS`	One of the following time units for the values of `frequency` and `startDelay`: `MILLISECONDS`, `SECONDS`, `MINUTES`, `HOURS`, or `DAYS`

Frequency

frequency

1000

The frequency at which the Scheduler triggers the flow given the timeUnit setting.

Start Delay

startDelay

0

The amount of time to delay execution of the Scheduler for the first time after the application starts. This property uses the same timeUnit as the frequency.

Time Unit

timeUnit

MILLISECONDS

One of the following time units for the values of frequency and startDelay:

MILLISECONDS, SECONDS, MINUTES, HOURS, or DAYS

This strategy delays executes the Scheduler every 10 seconds after an initial 10 second delay:

<scheduler doc:name="Scheduler" >
  <scheduling-strategy >
    <fixed-frequency frequency="10" timeUnit="SECONDS" startDelay="10"/>
  </scheduling-strategy>
</scheduler>

Cron (`<cron/>`)

For more complex scheduling strategies, you can use a cron expression.

Attribute XML Description

Attribute	XML	Description
Expression	`expression`	A cron expression for triggering the Scheduler. There is no default cron expression. For guidance with expressions, see Cron Expressions. Example: `expression="1 1 1 1,7 * ?"`
Time Zone	`timeZone`	Time zone passed as a system property, or in a machine’s operating system. Java time zone values are supported. Avoid Java abbreviations, such as `PST` and `AGT`, and instead use the full-name Java equivalents, such as `America/Los_Angeles`. Example: `timeZone="America/Argentina/Buenos_Aires"`

Expression

expression

A cron expression for triggering the Scheduler. There is no default cron expression. For guidance with expressions, see Cron Expressions. Example: expression="1 1 1 1,7 * ?"

Time Zone

timeZone

Time zone passed as a system property, or in a machine’s operating system. Java time zone values are supported. Avoid Java abbreviations, such as PST and AGT, and instead use the full-name Java equivalents, such as America/Los_Angeles. Example: timeZone="America/Argentina/Buenos_Aires"

The following example uses a cron expression to trigger the flow at 12:00 every day in the America/Los_Angeles time zone.

<flow name="componentsFlow">
  <scheduler>
    <scheduling-strategy>
      <cron expression="0 0 12 * * ?" timeZone="America/Los_Angeles"/>
    </scheduling-strategy>
  </scheduler>
  <logger message="my message"/>
</flow>

Cron Expressions

Cron is a widely used standard for describing time and date information. The Cron Expression (<cron expression /> scheduling strategy (<scheduling-strategy >) is useful for triggering a flow at intervals not available through the Fixed Frequency scheduling strategy.

The Scheduler keeps track of every second and creates a Mule event when the Quartz Cron expression matches your time-date setting. You can trigger the event just once or at regular intervals.

A date-time expression consists of six required settings and can include the optional year setting. Specify the settings in the following order:

Seconds (0-59)
Minutes (0-59)
Hours (0-23)
Day of month (1-31)
Month (1-12 or JAN-DEC)
Day of the week (1-7 or SUN-SAT)
Year (empty or a 4-digit year between 1970-2099, for example, 2019)

The Scheduler supports Quartz Cron expressions. Here are a few examples:

Expression Behavior

Expression	Behavior
`1/2 * * * * ?`	Run every 2 seconds of the day, every day.
`0 15 10 ? * *`	Run at 10:15 a.m., every day. `0 15 10 * * ? ` and `0 15 10 * ?` produce the same effect.
`0 15 10 * * ? 2019`	Run at 10:15 a.m., every day during the year 2019.
`0 * 14 * * ?`	Run every minute starting at 2pm and ending at 2:59pm, every day.
`0 0/5 14 * * ?`	Run every 5 minutes starting at 2pm and ending at 2:55pm, every day
`1 1 1 1,7 * ?`	Run the first second of the first minute of the first hour, on the first and seventh day, every month.

1/2 * * * * ?

Run every 2 seconds of the day, every day.

0 15 10 ? * *

Run at 10:15 a.m., every day. 0 15 10 * * ? * and 0 15 10 * * ? produce the same effect.

0 15 10 * * ? 2019

Run at 10:15 a.m., every day during the year 2019.

0 * 14 * * ?

Run every minute starting at 2pm and ending at 2:59pm, every day.

0 0/5 14 * * ?

Run every 5 minutes starting at 2pm and ending at 2:55pm, every day

1 1 1 1,7 * ?

Run the first second of the first minute of the first hour, on the first and seventh day, every month.

The Scheduler component also supports Quartz Scheduler special characters:

*: All values.
?: No specific value.
-: Range of values, for example, 1-3.
,: Additional values, for example, 1,7.
/: Incremental values, for example, 1/7.
L: Last day of the week or month, or last specific day of the month (such as 6L for the last Saturday of the month).
W: Weekday, which is valid in the month and day-of-the-week fields.
#: "nth" day of the month. For example, #3 is the third day of the month.

See CronExpression for more information.

This example logs the message "hello" every second:

<flow name="cronFlow" >
  <scheduler doc:name="Scheduler" >
    <scheduling-strategy >
      <cron expression="* * * * * ?" />
    </scheduling-strategy>
  </scheduler>
  <logger level="INFO" doc:name="Logger" message='"hello"'/>
</flow>

Note that there are a number of free online tools that can help you build Cron expressions.

Examples in Anypoint Exchange

The following examples in Anypoint Exchange show use cases for a Scheduler component:

Data Sync Using Watermarking and Batch
Import Contacts into Microsoft Dynamics CRM
Import Leads into Salesforce
Importing a CSV File into mongoDB
Importing an Email Attachment Using the IMAP Connector
Salesforce to MySQL Database Using Batch Processing
Sending a CSV File Through Email Using SMTP

To download and open the project from Anypoint Studio, see Import a Mule Project from Exchange.

Debugging in Anypoint Studio

In Anypoint Studio debug mode, the Mule application disables the triggering of events. You can manually execute the Scheduler component when debugging by clicking the green arrow icon in Studio that appears at the bottom of the component, for example:

Debug arrow in the Scheduler