Why Flowable business calendars decide when your SLA timers really fire
Business calendars control how the duration on a Flowable timer or due date is interpreted, so they decide whether a three-working-day response deadline counts Saturday, Sunday and public holidays. Consider a process that must respond to a customer within three working days. A plain timer set to a fixed period of days keeps running over a weekend and through a holiday, so the escalation fires before anyone in the business has had three working days to act. In that case the business calendar, not the timer definition alone, determines when the event actually triggers. Teams need a business calendar whenever an SLA, service window, or regulatory response period is written in working time. A plain timer is usually enough for waits that are truly elapsed time, such as a reminder that should fire 24 hours after an event regardless of the calendar.
The behavior depends on the calendar in use. Every timer event has a default business calendar, so a process can run with sensible behavior before anyone configures anything. When the default does not match your working hours, your organization's holidays, or a regional rota, you define a custom calendar in the process engine configuration and reference it by name from the timer using the flowable:businessCalendarName attribute. Confirm in the Flowable BPMN constructs documentation which calendar types and attribute names your engine version supports before you design around them. The decision is not only technical. Someone in the business must own the working calendar, including who maintains holiday lists for each region and how changes apply to instances already waiting on a timer.
Treat the calendar as a versioned input to your SLA design, and test it before go-live. Choose the calendar for each timer during process design, record the expected trigger dates for weekends, holiday weeks, and the day before a holiday, and run those cases against the deployed engine rather than reasoning about them from the model. Ask whether a change to the calendar affects timers that are already running, because that answer shapes how you roll out holiday updates. Give the business owner a short list of dates to check each year. A timer that fires at the wrong time is usually a calendar decision that nobody reviewed, not a fault in the engine.
Which calendar option fits which deadline
This table compares the three ways a Flowable timer can measure time: the default business calendar, a custom calendar referenced by name, and a plain elapsed-time timer. Read each row against the deadline you are modeling, then check the maintenance and risk columns before choosing. The main takeaway is that any deadline counted in working days depends on a calendar someone must keep correct.
| Option | When it fits | What the team must maintain | Main risk |
|---|---|---|---|
| Default business calendar | Timers that should follow the engine's standard working-time rules without extra configuration | Confirm the default rules match your operating hours, then retest any timer that depends on them | Working hours or holidays differ from the default, so due dates land on the wrong day |
| Custom calendar via flowable:businessCalendarName | Deadlines tied to your own working hours, regional holidays or service-specific schedules | A named calendar in the process engine configuration, plus updates whenever hours or holidays change | A calendar name typo or missing definition, or holiday data left stale after a year-end |
| Plain elapsed-time timer | Deadlines that run on fixed clock time, such as a payment hold of a set number of hours regardless of weekends | Timer durations in the model and a check that the business owner really means calendar-free time | Weekend or holiday deadlines fire when nobody can act on them, so SLAs look missed |
| Mixed model with several calendars | Processes where different steps follow different service calendars | A documented mapping from each timer to its calendar, reviewed when a process version changes | Timers in a new version point at a calendar that the running environment does not define |
| Calendar tested before go-live | Any SLA whose breach has a customer, financial or regulatory consequence | Test cases with dates around weekends, holidays and daylight-saving changes, run in a non-production engine | Testing only with weekday dates, so edge cases appear first in production |
How to set up and reference a business calendar
This sequence turns a list of working-time deadlines into timer events that Flowable schedules against a named business calendar, with checks at each stage so a missing or misspelled calendar name is caught before the process reaches production.
Decide which deadlines are working-time based
Before touching the engine, the process owner and an analyst list every timer and due date in the model and mark each one as either elapsed time (a wall-clock interval that runs through nights and holidays) or working time (hours that count only during business days and open periods). Record the working week, the business hours, the holiday dates and the time zone each rule applies to, and note which deadlines belong to which team. The output is a short table that maps each timer to one calendar rule, or to none. Confirm the list with the people who own the SLA, since a wrong classification here carries through every later step.
Define the calendar in the engine configuration
A developer defines each working-time calendar in the process engine configuration, as a business calendar bean or entry that the engine can look up by name. Each calendar carries the working days, hours and holiday exclusions agreed in the previous step, and the team keeps the definitions in version control next to the process models. The check for this step is a unit test or startup log that loads the engine, lists the calendar names it registered, and confirms that each entry matches the table from the first step. Confirm the exact configuration keys and calendar types against the Flowable configuration and BPMN documentation for your version, because these details differ between releases.
Reference the calendar from each timer event
In the BPMN model, the developer sets the flowable:businessCalendarName attribute on each timer event that must follow working time, using the exact name registered in the previous step. Timers that should run on elapsed time keep the default business calendar, which Flowable applies to every timer event when no custom calendar is named. Reviewers check the model against the mapping table so that no SLA timer is left on the default when it should use working time. The output is a model where each timer's calendar choice is explicit and matches the documented decision.
Check the referenced name against the configured calendars
A validation step compares every value of flowable:businessCalendarName in the BPMN files with the calendar names registered in the engine configuration. A script or a build test reads the models, collects the referenced names, and fails the build when a name has no matching configured calendar, or when a timer that should use working time has no reference at all. Catching this in the build means a typo such as a changed capitalization does not reach the running engine, where the timer would otherwise fall back silently to a different calendar. The check passes only when every reference resolves and every working-time timer is accounted for.
Deploy the process to a test environment
The team deploys the validated process definitions to a non-production environment that uses the same engine version and calendar configuration as production. The deployment runs through the same pipeline used for release, so the test environment exposes configuration differences before go-live. The check at this point is that the deployment succeeds and the process definitions are visible with their calendar references intact. Keep the test database and engine version identical to production wherever possible, and record which configuration file version was deployed.
Confirm the scheduled due dates for test cases
QA engineers start process instances with inputs chosen to cover the calendar edges: a start just before the end of a business day, a start on a Friday evening, a start on a listed holiday and a start across a weekend. For each case they compare the due date that the engine schedules with the date the business owner expects from the agreed calendar rule, and they record both values. A mismatch means either the calendar definition or the model reference is wrong, so the team fixes it and repeats the case. Use the Flowable BPMN timer documentation to confirm how each timer type is computed before writing the expected values.
Record the verified calendar mapping for release
The final step is a release record that lists each timer, its calendar name, the test cases that confirmed it and the approver. The record is stored with the process model in version control so that anyone changing a timer later can see which calendar it depends on. The owner signs off that every SLA deadline in the production release has a verified calendar reference. This record also helps during later audits or disputes, because it shows how each due date was calculated and who approved that calculation.
How to test SLA deadlines before go-live
Test every deadline against a fixed set of expected due dates before go-live. Build a test matrix of process start times that cover the cases where calendar logic usually breaks: starts on a Friday afternoon, starts on a Saturday or Sunday, starts on the day before a public holiday, starts on the holiday itself, and starts that fall across a boundary where working hours end. For each case, write down the due date your business owners expect, then run the process with the same timer definition and compare that expected value with the due date the engine actually schedules. If your organization operates across time zones, add cases for each zone and confirm which zone the business calendar and the server use, because a deadline that looks correct in one zone can land on the wrong working day in another. Keep the expected results in version control next to the process definition so they are reviewed whenever the timer or calendar changes.
Holiday data and working hours are business inputs, not engineering defaults. Ask the operations or compliance owner of each SLA to supply the working-day rules, the holiday list for each year in scope, and the cut-off times, and have them sign off the expected results in your matrix. Confirm with that owner how far ahead the holiday list must be maintained, who updates it, and what happens when a holiday is announced late. Engineering should not infer these rules from the code. Then check the test results against the custom calendar configuration you deploy, and confirm the calendar name referenced by flowable:businessCalendarName matches the one in the engine configuration, since a mismatch is easy to miss in a test that only uses the default calendar.
Timers do not fire inside the request that created them. The async executor picks up timer jobs from a thread pool, and when several nodes run the same engine, they coordinate through lock owners and lock expiration times stored in the database. Your tests should therefore run on a deployment that uses the same async executor settings and database as production, and they should check that a due timer is executed by the expected job on time, and that a job whose lock expires is picked up by another node. Ask your DBA or platform team which database engine and version will hold production data, because timestamp precision and time zone handling differ between the supported databases, and test on that engine rather than on H2. Record the job execution time as well as the due date, so a late job is not mistaken for a wrong calendar result.
Operational risks in calendar-driven deadlines
A business calendar decides when a timer fires, so a change to working hours or holidays changes deadlines across running processes. The cards below cover the controls that keep those deadlines defensible, from who edits calendar data to how the change is proven before it reaches production.
Ownership of calendar and holiday data
Business calendars are configuration that encodes working hours, time zones and holiday lists, and each of those values sets when an SLA clock stops and restarts. Decide who may edit that data, usually a named business owner with a platform engineer as reviewer, and keep the change in version control. Ask whether your engineers can alter calendars in a running environment without a deployment record. The calendar owner must be named before the first timer goes live.
Review of calendar changes
A holiday added late or a corrected working-hours window can move dozens of deadlines at once, so each change needs a second reviewer who checks the effective dates and the calendar name it targets. Require a written reason and an approver record for every change. Confirm with your change board whether calendar edits fall under the same control as process deployments or need their own workflow.
Behavior of deployed definitions after a change
A process definition references a calendar by name, so the timers it creates are evaluated against whatever calendar the engine holds at that moment. Instances already waiting on a timer may compute their next due date differently after a calendar change. Test which open timers are affected before the change, and decide whether to let them run on the new calendar or to migrate them. Confirm the exact behavior with the Flowable BPMN docs for your version.
Audit evidence of deadlines
When a regulator or internal auditor asks why a case was escalated late, the answer depends on which calendar and which due date applied at the time. Store the calendar version, the timer's computed due date and the event that set it in your retained records. Confirm with your auditor which deadline evidence they expect, and whether your history level captures the timer creation and firing events you would need to reconstruct the decision.
Monitoring timer jobs
Timers run as jobs through the async executor, so a stuck or failing job delays an escalation without any visible error in the business application. Use the Flowable actuator endpoint at /actuator/flowable to watch running process activity, and set alerts on failed or growing job queues in your monitoring stack. Check the engine logs after each calendar change, because a timer that fails to fire is easy to miss.
Testing calendar changes before production
Each calendar change should run first in a non-production environment that holds a copy of the calendar and a sample of open timers. Compare the computed due dates before and after the change, including dates across a holiday, a daylight saving transition and a weekend. Record the results as the release evidence for that change. Confirm with your team how production data is copied into that environment without exposing personal information.
Questions teams ask before building SLA deadlines in Flowable
How much effort does a business calendar setup take in Flowable?
The effort depends on how many calendars you need, how many timer events reference them, and how good your holiday and working-hour data is. A single default calendar for one team is a small change. Several calendars for regions, business units or service tiers add modeling, configuration and test cases for each one. Holiday data is often the largest hidden task, because someone must collect, verify and maintain it for every jurisdiction the process touches. Ask any partner to break the estimate into calendar design, timer mapping, holiday data and test cases, so you can see which component drives the number.
What drives the cost of timer and deadline work in Flowable?
Cost follows the number of distinct calendar rules, the number of timer events that depend on them, and the number of edge cases your SLAs define, such as deadlines that cross weekends, public holidays or shift changes. Each timer adds a mapping decision and a test. One-time costs include designing the calendars, configuring the engine, and building the test suite. Recurring costs include maintaining holiday data each year and reviewing deadlines when policies change. When you request a quote, ask which items are one-time and which are recurring, and whether holiday maintenance is included.
Can an internal team set up business calendars in Flowable alone?
Yes, a team with Java and Flowable experience can configure a business calendar and reference it from a timer, because the behavior is defined in the process engine configuration and the BPMN model. The harder part is usually the agreement on rules: what counts as a working hour, which holidays apply and who owns the answer. Internal teams often underestimate the testing needed to prove that a deadline lands correctly across time zones and daylight saving changes. A partner can help when you need a second review of the design, an outside test plan, or a fixed-scope delivery with a written list of deliverables.
What does the business need to provide for SLA deadlines?
The business must define each SLA in operational terms: the start event, the clock it runs on, the working days and hours, the holidays that pause it, and what happens when a deadline is missed. Without these answers, engineers will encode assumptions that nobody reviewed. Ask the business owner to sign off a written rule for each timer, with example dates worked by hand. Those worked examples become the expected results in your automated tests, which keeps the discussion concrete and prevents later disputes about whether a timer fired correctly.
What does engineering need to deliver calendar-aware timers?
Engineering needs access to the Flowable process definitions, the engine configuration where calendars are registered, and a test environment with a controllable clock or a way to set due dates for testing. The team must decide where holiday data lives, how it is loaded and how changes are deployed. Timer references in BPMN must use the correct calendar name, and the team must confirm that the default calendar behaves as expected for timers that do not name one. Plan for version control of the calendar configuration alongside the process models, so that a deadline change is reviewed like any other code change.
How long does testing SLA deadlines take, and what does it depend on?
Testing time depends on the number of calendars, the number of timer paths, and the number of holiday and boundary cases you want to cover. Each timer typically needs cases for a normal working day, a weekend start, a public holiday inside the window and a deadline that falls exactly at a boundary. Testing also depends on whether your team can control the clock in test runs, and on how many people must review the expected dates. Ask for a test plan that lists each case and its expected result, and confirm which cases run automatically in your pipeline before go-live.
What changes after go-live for business calendars?
Holiday data changes every year, working patterns change when staffing or regions change, and new SLAs introduce new timers. Each change should go through the same review and test path as the original build. Operationally, you need a named owner for the calendar data, a schedule for reviewing it, and monitoring of timers that fire unexpectedly. Running instances keep the due dates they were given when they started, so confirm how a calendar change affects open work before you deploy it. Recurring work is usually a small maintenance task per year plus whatever new SLAs the business adds.
What DeployOpen delivers for calendar-based deadlines
A scoped engagement on business calendars starts with calendar design: deciding which working hours, weekend rules and holidays apply to each timer and due date in your processes, and which of them can use the default business calendar that every Flowable timer event has. Where a process needs its own rules, the work covers defining a named calendar in the process engine configuration and referencing it from the timer event through flowable:businessCalendarName. DeployOpen also reviews the holiday and working-hour data with your operations or HR owner, since the engine will only calculate deadlines as correctly as the data it is given. The exact scope, including which processes and calendars are covered, is agreed in writing before work begins.
Timer configuration and testing form the second part of the work. DeployOpen wires the timer events to the agreed calendars, then builds test cases that set known start times across weekends, public holidays and the boundaries of working hours, and checks the due dates the engine produces against expected values written down in advance. These tests run against the same Flowable version and async executor settings your production environment uses, so that the results carry over. The deliverables typically include the calendar definitions, the timer configuration, the test suite and a short review record that shows which SLA cases were checked and what was found.
Your team keeps several decisions that no partner can make for you. Someone must own the holiday calendar and approve changes to it, including regional or site-specific closures. You must decide how escalation timers behave when a deadline falls outside working hours, and whether a late task should be reported before or after the business calendar rolls forward. Ask any partner to confirm in the statement of work how calendar changes will be tested before they reach production, and who maintains the calendar data after the engagement ends. Confirm these answers with your own service owners before scope is signed, because they determine how much of the calendar logic belongs in code and how much in data.
How DeployOpen scopes and supports Flowable deadline work
DeployOpen plans, implements, tests, documents and supports self-hosted open-source platforms inside the client's own infrastructure, including Flowable engines. For business calendars and timers, we agree a written scope first, then build and verify deadline behavior against the working hours and holidays your SLAs depend on.
How we scope
- We list every timer and due date that depends on working time, including escalations and reminders.
- We record which business calendars apply to each timer event and where holiday and time zone rules come from.
- Engagements are fixed-scope, so deliverables and test cases are agreed in writing before work starts.
How we build
- We define default and custom business calendars in the engine configuration and reference them from timer events.
- We write tests that move the clock across weekends, public holidays and daylight saving changes.
- We confirm how the async executor fires timers across nodes so deadlines are not missed or doubled.
How we hand over
- We document each calendar, its owner, the timers that use it and the update steps for new holidays.
- We provide a deadline test matrix that your team can rerun before every process release.
- We walk your operations and business owners through expected behavior and how to read timer jobs.
How we support
- Ongoing support, upgrades and continuous testing are available as a retainer after handover.
- Support can cover calendar updates each year and re-testing when Flowable versions change.
- Your team keeps ownership of the calendar data, with us advising on changes that affect running instances.
