Timers#

Administration.Timer

A Timer is a scheduled task execution object in the Critical Manufacturing MES system. It's designed to automatically trigger business Rules at defined intervals or specific times. It supports flexible scheduling patterns, error handling, and automatic lifecycle management to ensure reliable task execution across the system.

A Timer is identified by a unique name and is defined by a specific recurrence, containing:

• A Rule that will be executed when the recurrence time is reached (your business logic).
• An optional Recurrence Rule that calculates WHEN to execute (custom scheduling logic).
• An optional On Error Rule that will be automatically executed if the original Rule fails, receiving the timer and exception as input parameters.

Additional information can be viewed in each Timer page, including:

• Start Date
• Number of times the Timer has been executed
• Expire Date
• State
• Recurrence information
  • Type
  • Frequency

Key Concepts#

Execution Times vs Executed Times#

Table: Timer execution limit and counter properties

Next Execution#

The Next Execution is automatically calculated by the system and displayed in the timer details.

• You cannot manually change this value.
• When you create a timer, the Next Execution is initially set to the timer Start Date.
• When you edit a timer, the value is recalculated if you change the Start Date or Recurrence settings.
• All dates are displayed in your local timezone.

Rule vs Recurrence Rule#

Table: Timer rule and recurrence logic properties

Example: A timer with Daily recurrence uses built-in scheduling. A timer with Recurrence set to Rule uses a custom Recurrence Rule to calculate the next execution date (for example, skip weekends/holidays).

Browsing existing Timers#

The Timers page in the Administration menu lists all the available Timers.

The Timers search page displays:

• Last Executed - When the timer last ran.
• Last Execution Result - Color-coded status (green for success, red for errors).

Use these indicators to quickly identify timers that are experiencing issues.

If you select a Timer, its Details page opens:

On the Details page, you can:

• Edit - Modify timer configuration.
• Enable/Disable - Activate or deactivate the timer.
• Terminate - Permanently stop the timer.
• Unterminate - Undo termination.

On this page, you can monitor:

• Last Executed - When the timer last ran (displayed in your local timezone).
• Next Execution - When the timer will run next (displayed in your local timezone, calculated automatically).
• Executed Times - How many times the timer has run (counts both successful and failed executions).
• Execution Times - Maximum number of runs allowed (if set).
• State - Shows "Success" in green for successful execution, or error message in red for failures.
• Is Enabled - Shows if the timer is currently active (checked) or inactive (unchecked).
• State - Current status (Active, Terminated, etc.).

System Timers#

Creating a Timer#

CmfTimer.Create

To create a new Timer, select Create on the top ribbon of the Timers page and follow the information below.

Step 1 - General data#

1. Provide a Name for the Timer.
2. Optionally, provide a Description for the Timer.
3. Select whether the Timer is Enabled (default).

4. Select a Scope for the Timer. The scope determines what the timer works with:

   • General - For system-wide tasks like cleanup, maintenance, or scheduled operations. The timer can automatically terminate when finished.
   • Integration Entry - For processing integration messages and external system synchronization. The timer can automatically terminate when finished.
   • Maintenance Management - For maintenance-related tasks. Works with maintenance orders to trigger notifications or updates at specific times.
   • Order Management - For production order tasks. Works with production orders to send notifications or perform actions at scheduled times.
   • Planning - For planning and scheduling tasks. Works with plans to synchronize time frames and update schedules.
   • Time Constraints - For material time management. Works with materials to enforce time limits and send warnings before expiration.

   Scope Impact on Automatic Termination

   Automatic termination (via Terminate After Execution Mode) ONLY works for General and Integration Entry scopes. For other scopes, the parent entity (maintenance order, production order, material, or plan) is responsible for terminating the timer when appropriate.

5. Select a Start Date when the Timer will become active. The Start Date must not be in the past (must be greater than or equal to the current time).

6. Select the Rule that will run when the recurrence period elapses. The rule receives different inputs based on the selected Scope.

   Rule Result

   The DEE Action associated with the Rule must set a "Result" on the output/return dictionary.

7. Select the maximum number of times the Timer can run (Execution Times). Set to 0 for unlimited executions. When the timer has executed this many times, it will stop scheduling new executions.

8. Select Terminate After Execution Mode. This defines the termination mode that the Timer entity will follow upon finishing the last execution (according to the value set on Execution Times) of the Rule:

   • None - Timer entity will remain Active, even though there are no more future executions.
   • Always - Timer entity is terminated after Execution Times is reached (there are no next executions), regardless of the last outcome of the Rule.
   • On Success - Timer entity is terminated after Execution Times is reached (there are no next executions), only if the last execution of the Rule succeeded.

   Scope Restriction

   Automatic termination only applies to General and Integration Entry scopes. For other scopes, the parent entity controls the termination.

9. Optionally, select a date for the Timer to expire and stop executing.

10. Select the type of Recurrence to apply to the Timer, and set other mandatory value(s) as follows:

    Recurrence Type	When to Use	Required Fields
    One Time	Execute once at a specific time	None (executes at Start Date)
    Daily	Execute every N days	Recurrence Frequency (days)
    Weekly	Execute every N weeks	Recurrence Frequency (weeks)
    Monthly	Execute every N months	Recurrence Frequency (months)
    Yearly	Execute every N years	Recurrence Frequency (years)
    Defined Seconds	Execute at precise intervals	Recurrence Seconds AND Recurrence Frequency
    Rule	Custom schedule (skip weekends/holidays)	Recurrence Rule

    Table: Recurrence types and their required configuration fields

    Recurrence Rule Requirements

    When using recurrence type Rule, the Recurrence Rule must:

    • Be active and not a template.
    • Return a DateTime value (not null or any other types).
    • Return a future date (greater than current UTC time).
    • Accept RecurrenceRuleData as input parameter (optional JSON string).

    If the rule returns null or a past date, the timer will set an error in Last Execution Result and will not have further executions.

    When using a recurrence Rule, you can provide additional data in JSON format in the Additional Information field. Example: {"businessDaysOnly": true, "excludeHolidays": true}.

    

11. Optionally, configure error handling:

    • On Error Rule - A rule to be executed automatically when the main rule fails. This rule receives two input parameters: CmfTimer (the timer instance) and ExecutionError (the exception that occurred). Use this for custom error handling, recovery actions, or notifications.
    • Send Email On Error - Enable to send email notifications when execution fails.
    • Error Email Distribution List - Semicolon-separated list of email addresses to receive error notifications. If not specified, falls back to the LocalSupport configuration.
12. Select Create to complete the operation.

Editing a Timer#

CmfTimer.Edit

You can edit a Timer from the main details page by selecting the Edit button on the top ribbon.

Execution Behavior#

How Timers Execute#

When a timer's scheduled execution time is reached:

1. The timer's Rule is executed based on the Scope#

• General - Rule executes with the timer as context.
• Maintenance Management / Order Management / Time Constraints - Rule executes for each related entity.
• Integration Entry - Processes time-based integration entries.
• Planning - Rule executes with Timer Id parameter.

2. After execution#

• Executed Times counter is incremented.
• Last Executed timestamp is updated.
• Next Execution is calculated based on recurrence settings.
• Timer is re-queued if Next Execution is not null.

3. Automatic termination occurs when#

• Next Execution cannot be calculated (returns null).
• Scope is General or Integration Entry.
• Terminate After Execution Mode conditions are met:
• On Success - Terminates only if last execution was successful.
• Always - Terminates after last execution (success or error).

Error Handling#

When a timer execution fails, the system follows this sequence:

1. Capture Error#

• The error is captured and Last Execution Result is updated with the error message.
• The Executed Times counter is incremented (counts both success and failure).
• The Last Executed is set to the scheduled execution time.

2. Calculate Next Execution#

• The Next Execution is calculated based on recurrence settings.
• The Timer continues to the next scheduled execution unless termination conditions are met.

3. Send Email Notification (if configured)#

• If Send Email On Error is enabled, an email is sent to Error Email Distribution List.
• The email includes: timer name, error message, execution timestamp, and timer details.
• If the Error Email Distribution List is empty, the system defaults back to the LocalSupport configuration.

4. Execute On Error Rule (if configured)#

• If an On Error Rule is configured, it is automatically executed.
• The rule receives two input parameters:
  • "CmfTimer" - The timer instance (full timer object).
  • "ExecutionError" - The exception that occurred (exception object).

5. Termination Decision#

• The Timer is only terminated on error if Terminate After Execution Mode is set to Always and it has no Next Execution.
• On Success mode does NOT terminate on errors (only on successful executions).
• Termination only applies to General and Integration Entry scopes.

Result: The timer continues to execute at scheduled intervals unless explicitly terminated or Next Execution becomes null.

Next Execution Calculation#

The next execution time is calculated as follows:

• One Time - Runs only once (no next execution).
• Daily/Weekly/Monthly/Yearly - Adds the frequency to the Start Date iteratively until a future date is found.
• Defined Seconds - Adds the seconds interval (Recurrence Frequency times Recurrence Seconds) to the Start Date iteratively until a future date is found.
• Rule - Evaluates the Recurrence Rule with RecurrenceRuleData to get the next execution date.

The timer will not execute if:

• Next Execution ≥ Expire Date (if Expire is set).
• Executed Times ≥ Execution Times (if Execution Times is set and > 0).
• Recurrence Rule returns null or a past date.
• Timer is disabled.

Terminating a Timer#

CmfTimer.Terminate

It is possible to terminate an existing Timer by selecting it from the list and then selecting the Terminate button.

Unterminating a Timer#

CmfTimer.Unterminate

It is possible to unterminate an existing Timer by selecting it from the list and then selecting the Unterminate button.

Frequently Asked Questions#

Q: Can I change a timer's schedule while it's running?

A: Yes, but it's recommended to disable the timer first, make the necessary changes, then re-enable it to ensure a clean state and avoid unexpected behavior.

Q: What happens if a timer execution takes longer than the interval?

A: The system prevents the same timer from running multiple times simultaneously. The next execution will wait until the current one completes. This ensures each timer execution finishes before the next one starts.

Q: What if the system is down during a scheduled execution?

A: The timer will execute at the next opportunity when the system is available. It does not retroactively execute missed runs. The Next Execution is recalculated based on the Start Date and recurrence pattern.

Q: How do I stop a timer temporarily?

A: Disable the timer using the Edit button. It retains its configuration and can be re-enabled later. However, the Next Execution is not recalculated when disabling.

Q: How do I stop a timer permanently?

A: Terminate the timer using the Terminate button. This sets the Universal State to Terminated. You can unterminate it later if needed.

Q: Can multiple timers execute the same rule?

A: Yes, multiple timers can use the same rule with different schedules or scopes. Each timer maintains its own execution state.

Q: What's the minimum execution interval?

A: Technically 1 second using Defined Seconds recurrence, but intervals under 10 seconds should be carefully evaluated for system load and performance impact.

Q: Why is my timer not automatically terminating?

A: Automatic termination only works for General and Integration Entry scopes. It only applies on the last timer execution. For other scopes (Maintenance Management, Order Management, Time Constraints, Planning), the parent entity controls termination. Timer with ExecutionTimes set to 0, are not automatically terminated.

Q: Can I set the Next Execution manually?

A: No, the Next Execution is automatically calculated by the system based on your recurrence settings. You cannot manually override it. However, if using Recurrence Rule, the Next Execution will be set to the value obtained from the Rule execution.

Q: What happens to Executed Times on errors?

A: The Executed Times counter increments on every execution attempt, regardless of success or failure. This ensures accurate tracking of total execution attempts.

Q: What happens if the system has multiple application servers?

A: The implementation is based on a distributed architecture using database-level locking to ensure timers execute once and only once across multiple application servers.

Q: How do you create a timer that keeps running until it achieves a set number of successful executions?

A: To implement this scheduling pattern, set the timer’s Execution Times to the required number of successful executions. When an error occurs, use the Error Rule to increment Execution Times by one, then save the timer. This ensures the timer continues running until the target number of successful runs is reached, regardless of unsuccessful attempts. You can add additional actions to the Error Rule as needed.

Best Practices#

• Test rules before enabling timers: Ensure your business rules work correctly before scheduling them. Make sure that they are fast, performant and scalable.
• Use appropriate scopes: Select the scope that matches your timer's purpose and understand how it affects termination behavior.
• Configure error handling: Set up On Error Rule and email notifications for critical timers.
• Set execution limits: Use Execution Times and Expire Date to prevent runaway timers.
• Monitor execution results: Regularly check the Last Execution Result for errors.
• Disable before editing: Disable timers before making significant configuration changes to avoid unexpected executions.
• Document timer purpose: Use clear, descriptive names and descriptions.
• Validate recurrence rules: Test that Rule-based recurrence returns future DateTime values.
• Consider system load: Intervals under 10 seconds should be carefully evaluated for performance impact.