> For the complete documentation index, see [llms.txt](https://docs.octoo.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.octoo.com/general/agreements/triggered-policies.md).

# Triggered Policies

Octoo supports four different ways to count the time between a request and a cancellation or short notice event.

Triggered policies in our API measure the time between when a policy is triggered and when a job starts. The system supports four different time type measurements, each serving different business needs. Understanding how these time types work is crucial for setting up appropriate notification and escalation policies.

{% hint style="info" %}
The "trigger" time for short notice policies is determined by the request's **Requested At** timestamp. See [Requested At Timestamp](/general/requests/requested-timestamp.md) for details on how this value is set and how it can be backdated by admins.
{% endhint %}

**Assuming the following business hours for all time calculations below:**

* Monday through Friday: 8:00 AM - 5:00 PM
* Weekends: Closed (Saturday & Sunday)
* Holidays: Closed (when observed)

Each partner can set their own business hours, but the default is as above.

## 1. Calendar Hours

Definition: Measures the actual elapsed time in hours/minutes between trigger and job start, regardless of business hours, weekends, or holidays.

How it works:

* Counts every minute continuously
* Returns the total number of minutes between trigger and start time
* Rounds up to the nearest minute

Examples:

| Scenario           | Triggered At                | Job Starts At                      | Calendar Hours Result    |
| ------------------ | --------------------------- | ---------------------------------- | ------------------------ |
| Same day           | Friday 2:00 PM              | Friday 4:00 PM                     | 120 minutes (2 hours)    |
| Over weekend       | Friday 2:00 PM              | Monday 2:00 PM                     | 4,320 minutes (72 hours) |
| Over holiday       | Thursday 2:00 PM (July 1st) | Monday 2:00 PM (July 5th, holiday) | 5,760 minutes (96 hours) |
| Late night trigger | Thursday 10:00 PM           | Friday 2:00 PM                     | 960 minutes (16 hours)   |

## 2. Calendar Days

Definition: Counts the number of complete calendar days between trigger and job start.

How it works:

* Only counts full days that fall completely between the trigger and start dates
* Does not count the trigger day or start day themselves
* Returns 0 if triggered and started on the same day

Examples:

| Scenario       | Triggered At      | Job Starts At  | Calendar Days Result       |
| -------------- | ----------------- | -------------- | -------------------------- |
| Same day       | Friday 9:00 AM    | Friday 5:00 PM | 0 days                     |
| Next day       | Thursday 2:00 PM  | Friday 2:00 PM | 0 days                     |
| Two days later | Wednesday 2:00 PM | Friday 2:00 PM | 1 day (Thursday)           |
| Over weekend   | Friday 2:00 PM    | Monday 2:00 PM | 2 days (Saturday & Sunday) |
| Week span      | Saturday 2:00 PM  | Monday 2:00 PM | 1 day (Sunday)             |

## 3. Business Hours

Definition: Measures time between trigger and job start in 24-hour blocks, counting back from the job start and skipping days the business is closed (weekends and observed holidays).

{% hint style="warning" %}
**Business hours are not added together.** The length of the business day does not matter. With business hours of 8 AM - 5 PM, a "24 business hour" policy does **not** mean 24 open hours (about 2.7 days of 9-hour days). It means a full 24-hour window with closed days skipped: a job on Monday at 1:00 PM must be cancelled before Friday at 1:00 PM.
{% endhint %}

How it works:

1. **The trigger rolls forward.** A trigger outside business hours is treated as happening when the business next opens (a trigger at 10:00 PM Thursday counts as 8:00 AM Friday).
2. **The job start rolls back.** A job that starts outside business hours is measured from the last time the business was open (a job at 3:00 AM Friday is measured from 5:00 PM Thursday).
3. **Same day is zero.** If the trigger and the job start fall on the same day (before or after rolling), the result is 0.
4. **Count 24-hour blocks.** Otherwise, each open day between them counts as 24 hours. A partial day rounds **up** to the next 24 hours, so the result is always 0, 24, 48, 72, etc.

A policy applies when the result is at or below its trigger. Business hour policies must be set in 24-hour increments for this reason. For a 24 business hour policy, the deadline is the job's start time on the previous open day, and a trigger **at** the deadline is inside the policy.

Examples:

| Scenario              | Triggered At      | Job Starts At     | Business Hours Result    |
| --------------------- | ----------------- | ----------------- | ------------------------ |
| Same business day     | Friday 10:00 AM   | Friday 2:00 PM    | 0 minutes                |
| Next business day     | Thursday 2:00 PM  | Friday 2:00 PM    | 1,440 minutes (24 hours) |
| Partial day rounds up | Thursday 1:00 PM  | Friday 2:00 PM    | 2,880 minutes (48 hours) |
| After hours trigger   | Thursday 10:00 PM | Friday 2:00 PM    | 0 minutes                |
| Weekend trigger       | Saturday 2:00 PM  | Monday 2:00 PM    | 0 minutes                |
| Early morning trigger | Wednesday 2:00 AM | Friday 2:00 PM    | 4,320 minutes (72 hours) |
| Cross weekend         | Friday 2:00 PM    | Monday 2:00 PM    | 1,440 minutes (24 hours) |
| Before business hours | Thursday 2:00 AM  | Friday 2:00 PM    | 2,880 minutes (48 hours) |
| Overnight job         | Wednesday 4:59 PM | Friday 3:00 AM    | 2,880 minutes (48 hours) |
| Overnight job, late   | Thursday 9:00 AM  | Friday 3:00 AM    | 0 minutes                |
| Weekend job           | Thursday 4:59 PM  | Saturday 10:00 AM | 2,880 minutes (48 hours) |
| Weekend job, late     | Friday 9:00 AM    | Saturday 10:00 AM | 0 minutes                |

**Deadlines for a 24 business hour policy** (cancel *before* this time to avoid the policy):

| Job Starts At               | Measured From    | Deadline          |
| --------------------------- | ---------------- | ----------------- |
| Friday 2:00 PM              | Friday 2:00 PM   | Thursday 2:00 PM  |
| Monday 1:00 PM              | Monday 1:00 PM   | Friday 1:00 PM    |
| Friday 3:00 AM (overnight)  | Thursday 5:00 PM | Wednesday 5:00 PM |
| Saturday 10:00 AM (weekend) | Friday 5:00 PM   | Thursday 5:00 PM  |
| Monday 3:00 AM (overnight)  | Friday 5:00 PM   | Thursday 5:00 PM  |

{% hint style="info" %}
Jobs outside business hours have an earlier deadline on purpose: the partner always gets a full 24 hours of business time to respond before the job.
{% endhint %}

## 4. Business Days

Definition: Counts the number of complete business days between trigger and job start.

How it works:

* Only counts full business days (8 AM - 5 PM periods)
* A trigger before 8:00 AM counts that day as a full business day
* A trigger after 8:00 AM does not count that day as a full business day
* Does not count weekends or holidays
* Returns 0 if triggered and started on the same day

Examples:

| Scenario                  | Triggered At      | Job Starts At            | Business Days Result |
| ------------------------- | ----------------- | ------------------------ | -------------------- |
| Same day                  | Friday 10:00 AM   | Friday 5:00 PM           | 0 days               |
| Early trigger, same week  | Wednesday 2:00 AM | Friday 2:00 PM           | 2 days (Wed & Thu)   |
| Normal trigger, same week | Wednesday 9:00 AM | Friday 2:00 PM           | 1 day (Thursday)     |
| Over weekend              | Friday 2:00 PM    | Monday 2:00 PM           | 0 days               |
| Early Friday trigger      | Friday 7:00 AM    | Monday 2:00 PM           | 1 day (Friday)       |
| Weekend trigger           | Saturday 2:00 PM  | Monday 2:00 PM           | 0 days               |
| Holiday Monday            | Thursday 2:00 PM  | Monday 2:00 PM (holiday) | 1 day (Friday)       |
| Multiple days             | Monday 9:00 AM    | Wednesday 2:00 PM        | 1 day (Tuesday)      |

## Special Considerations

**Holidays**

* Holidays are treated as non-business days
* Calendar time types continue counting through holidays
* Business time types skip holidays entirely

**Weekend Handling**

* Calendar Types: Count weekends normally
* Business Types: Skip weekends completely

## Edge Cases

1. Same-Day Triggers: Business hours/days always return 0 if the trigger and start are on the same calendar day
2. After-Hours Adjustments:

* Triggers after 5:00 PM are treated as starting the next business day at 8:00 AM
* Triggers before 8:00 AM may count that day as a full business day (for business\_days type)

3. Cross-Weekend Policies:

* Friday 2:00 PM trigger for Monday 2:00 PM start:
  * Calendar: 72 hours
  * Business: 24 hours (Saturday and Sunday are skipped, so Friday 2:00 PM is one 24-hour block before Monday 2:00 PM)

4. 48-Hour Threshold:

* Many business hour calculations use a 48-hour business time threshold
* This equals two 24-hour blocks with closed days skipped (a Wednesday 2:00 PM job must be cancelled before Monday 2:00 PM), not 48 open hours added together