Business hours – working time for durations and date calculations¶
Business hours describe when work happens: the working days and hours of a week and the days that deviate from it, such as public holidays. Expressions use them to measure durations and to add time in working time instead of calendar time. This chapter describes how to set up business hours and how expressions use them. It is intended for administrators who configure nexxcite.
1. Business hours at a glance¶
Summary¶
- Business hours consist of regular periods per weekday (for example Monday to Friday, 08:00 to 17:00) and exceptions for single dates (holidays, a Saturday that is worked).
- They are used by expressions: a duration can count only working time, a date calculation can add working hours or business days, and a value can be checked against the working time.
- You can have several business hours side by side – one per location, team or service level – and choose the right one per expression, also dynamically.
- Business hours have no time zone. They are applied to date and time values exactly as the values come in (section 4).
Where business hours are used¶
| Where | What it does with business hours |
|---|---|
| Duration expression, setting "Use Business Hours" | Counts only the working time between a start and an end |
| Date/time calculation expression, setting "Use Business Hours" | Adds or subtracts working hours, business days or weeks |
Value modification IsDateWithInBusinessHours |
Returns true if a date is a working day |
Value modification IsDateTimeWithInBusinessHours |
Returns true if a point in time lies within the working time |
Example: With the working time Monday to Friday, 08:00 to 17:00, a ticket opened on Friday at 16:00 is three hours old on Monday at 10:00 – not 66 hours.
2. Setting up business hours¶
Admin Studio → Automation → Business Hours. The editor ("Business Hours Editor") has three tabs.
| Tab | Content |
|---|---|
| "General" | "Display Name", "Description", "Tags" |
| "Periods" | The regular working time of the week |
| "Exceptions" | Dates that deviate from the regular week |
Regular periods¶
The + on the tab "Periods" adds a period, the minus button removes it.
| Setting | Meaning | Default |
|---|---|---|
| "Day" | The weekday of the period, "Monday" to "Sunday" | "None" – must be set |
| "Begin" | Start of work on that day | empty = 00:00 |
| "End" | End of work on that day; must be after "Begin" | empty = end of the day (23:59:59) |
| "Closed" | The period is ignored, whatever its times are | off |
- A weekday without a period is closed. Business hours without any period have no working time at all.
- A day with a break gets two periods, for example Monday 08:00–12:00 and Monday 13:00–17:00.
- Work across midnight is entered as two periods: Monday 22:00 with an empty end, and Tuesday with an empty begin and the end 06:00.
- When you save, the periods are sorted by weekday.
Every period needs a weekday. A period that is left at "None" makes every calculation with these business hours fail.
Exceptions¶
The + on the tab "Exceptions" adds an exception.
| Setting | Meaning | Default |
|---|---|---|
| "Date" | The calendar date of the exception | required – an exception without a date never applies |
| "Closed" | The whole day is not worked | off |
| "Periods" | Only while "Closed" is off: the working time of that date, with "Begin" and "End" | empty |
- An exception replaces the regular periods of its date.
- An exception that is not closed and has no periods of its own has no effect: the regular periods apply. To work on a day that is normally closed, add the periods of that day to the exception.
- Enter one exception per date. When you save, the exceptions are sorted by date.
Permissions¶
| Task | Permission |
|---|---|
| Open the business hours manager | "Open Business Hours Manager" |
| Create, change, delete business hours | "Add Business Hours", "Edit Business Hours", "Delete Business Hours" |
By default, system administrators have these permissions (see Roles and permissions).
3. Holidays¶
nexxcite does not include holiday calendars. Every holiday is an exception with a fixed date and has to be entered for every year. Movable holidays such as Easter Monday change their date every year.
Recommendation: enter the holidays of the coming year before the year begins, and keep separate business hours for locations with different holidays (for example one per federal state or country).
4. Time zones¶
Business hours have no time zone setting. nexxcite compares a date and time value with the periods exactly as the value comes in, without converting it into another time zone first. The period 08:00–17:00 therefore means 08:00–17:00 in whatever time zone the value is in.
What this means in practice:
- A value in UTC is compared as UTC. For a location in Berlin, 08:00 UTC is 09:00 or 10:00 local time, depending on daylight saving time – the working time appears shifted by one or two hours.
- The system functions for the current time exist in two variants: the local time of the server and UTC (see Expressions). The local time of the server is the time zone of the server, not that of the user.
- Business hours for several time zones need one business hours definition each, and the values passed in must be in the time zone of that location.
Recommendation: decide for each use which time zone the date and time values are in, and write the periods in that time zone. Test the result with a known value before going live – for example a ticket created at 16:30 local time on a Friday.
5. Using business hours in expressions¶
Both the duration expression and the date/time calculation expression have the same settings for business hours:
| Setting | Meaning | Default |
|---|---|---|
| "Use Business Hours" | Count in working time | off |
| "Business Hours" | The business hours to use | – |
| "Use Business Hours By Expression" | The business hours are determined by an expression instead of being selected | off |
| "Business Hours Expression" | Only with "Use Business Hours By Expression": an expression that returns the id of the business hours or their name. The name is the display name without spaces, as nexxcite derives it (for example OfficeHoursBerlin for "Office hours Berlin"). |
– |
If no business hours can be found – none selected, or the expression returns an unknown value – the expression calculates in plain calendar time, as if "Use Business Hours" were off. The reason is written to the application log.
Use "Use Business Hours By Expression" when the business hours depend on the record – for example when each customer has a service level with its own business hours stored in a field.
Durations¶
A duration with business hours counts only the time that lies within the working periods between start and end. The unit converts this working time:
| Unit | Result with business hours |
|---|---|
| Seconds, minutes, hours | the working time in this unit |
| Days | the working time divided by 24 hours – not the number of business days |
| Weeks, months, years | the working time divided by 7, 30 or 365 days of 24 hours |
Example: Monday to Friday, 08:00–17:00. Start Friday 16:00, end Monday 10:00. Working time: 1 hour on Friday and 2 hours on Monday. The duration in hours is 3, in days 0.125 (3 / 24).
- If the end lies before the start, the duration with business hours is 0; without business hours it would be negative.
- With "Return Time Remaining", the working time is returned as a readable text, for example "3 hours".
Date calculations¶
A date/time calculation with business hours adds (or, with a negative number, subtracts) time along the working time. The setting "Unit interpretation" decides how the unit is read:
| Unit | "Business calendar units (days and weeks are business days)" – default | "Elapsed business time (a day is 24 working hours)" |
|---|---|---|
| Milliseconds to hours | working time | working time |
| Days | business days; the time of day stays | 24 hours of working time |
| Weeks | business days: the number × the open weekdays of a week (5 for Monday to Friday) | 168 hours of working time |
| Months, years | calendar months and years | 30 or 365 days of 24 working hours |
| Afterwards | the result is moved onto the next working time (or the previous one when subtracting) | – the result already lies within the working time |
A business day is a date with at least one open period. In the mode "Business calendar units", fractions of days, weeks, months and years are rounded to whole units (2.5 days become 3); hours and smaller units may have fractions.
Examples with Monday to Friday, 08:00–17:00, mode "Business calendar units":
| Start | Calculation | Result | Why |
|---|---|---|---|
| Friday 16:00 | + 4 hours | Monday 11:00 | 1 hour on Friday, 3 hours on Monday from 08:00 |
| Saturday 10:00 | + 2 hours | Monday 10:00 | The working time starts on Monday at 08:00 |
| Thursday 10:00 | + 2 days | Monday 10:00 | Friday is the first, Monday the second business day |
| Friday 18:00 | + 1 day | Tuesday 08:00 | Monday 18:00 lies outside the working time and is moved to the next start |
| Wednesday 10:00 | + 1 week | Wednesday 10:00 a week later | 5 business days |
The same "+ 1 day" from Thursday 10:00 in the mode "Elapsed business time" adds 24 working hours – 7 on Thursday, 9 on Friday and 8 on Monday – and ends on Monday at 16:00.
Checking a point in time¶
The value modifications IsDateWithInBusinessHours and IsDateTimeWithInBusinessHours return true
or false. Their parameter BusinessHours takes the id or the name of the business hours. Without
business hours, or if none are found, the result is false.
IsDateWithInBusinessHours: true if the date has at least one open period.IsDateTimeWithInBusinessHours: true if the time lies within an open period of its day, start and end included.
6. Example: response time of a service level¶
A support team works Monday to Friday, 08:00–17:00, and promises a first response within 4 working hours.
- Create the business hours "Support Berlin" with five periods Monday to Friday, 08:00–17:00, and the public holidays of the year as closed exceptions.
- On the entity Ticket, a calculation rule or a default value rule fills Response due with a date/time calculation: Created at + 4 hours, "Use Business Hours" on, "Business Hours" = "Support Berlin".
- A duration from Created at to First response at in hours, with the same business hours, shows how long the first response actually took.
A ticket created on Friday at 15:00 is due on Monday at 10:00. Answered on Monday at 09:00, the response took 3 working hours.
7. Limitations¶
- No time zone. Values are not converted (section 4).
- No holiday calendars. Holidays are entered as exceptions, year by year.
- A day open around the clock counts one second short. A period without begin and end covers 00:00 to 23:59:59; one such day contributes 23 hours, 59 minutes and 59 seconds of working time.
- "Days" in a duration are 24-hour units of working time, not business days.
- Business hours without any open period do not give meaningful results: durations are 0, and date calculations either leave the start unchanged or fall back to calendar time.
- A period with the day "None" makes calculations with these business hours fail.
- Searches for the next working time stop after about ten years of closed days.
8. Frequently asked questions¶
Do I have to enter holidays again every year? Yes. Every exception applies to one date only.
Can a business day end after midnight? Not in one period. Enter two periods: one up to the end of the day, one from the start of the next day.
Why does "+ 1 day" on a Friday evening give Tuesday morning? In the mode "Business calendar units", one business day after Friday 18:00 is Monday 18:00. That is outside the working time, so the result is moved to the next start of work, Tuesday 08:00.
Why does my duration in days show 0.375 for one working day? A working day of 9 hours is 9 / 24 = 0.375 days of 24 hours. Use the unit hours and divide by the length of your working day if you need working days.
Which business hours does an expression use if I change them? The changed ones, from the next evaluation. Values that rules have already stored are not recalculated.