> For the complete documentation index, see [llms.txt](https://manuals.dialox.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://manuals.dialox.ai/store/skills/timeplans.md).

# Timeplans

The standard bot skills work with the opening hours that are managed in the Bot settings section, see [opening hours](https://manuals.dialox.ai/settings/app-settings/opening-hours.md).

However, sometimes more flexibility is required. For this the Timeplan skill can be used. It allows users to define one or more alternative timeplans, for instance to allow for Lunch time.

The skill will set a predefined tag when the current time fall within the defined day and time. Using the tag you can define [conditions](https://manuals.dialox.ai/studio/flows/conditions.md) in flow nodes, for instance to skip over a node or to [branch](https://manuals.dialox.ai/studio/flows/nodes/control-flow-branch.md).

## Installing the Timeplans skill

{% hint style="info" %}
The Timeplans skill isn't installed automatically with your template. Therefore you need to install it by request.

Ask the DialoX team to install it for you.
{% endhint %}

## What is a timeplan

A timeplan is a scheduled event that can overwrite your online or offline status set by the default Opening hours settings and even set an additional tag so you can define specific behaviour in your flow that needs to happen when this scheduled event occurs.

A timeplan can trigger weekly, yearly, at one single date and time, or for a period. Examples:

* use a yearly timeplan to schedule Christmas closing
* use a weekly timeplan to schedule daily lunch time closing
* use a one time timeplan to schedule closing due to a company offsite or event
* use a period timeplan to schedule closing for non-repeating holidays

## Adding a timeplan

The skill adds a page to manage your timeplans in the Settings section.

1. Go to settings and click Timeplans.

<figure><img src="https://3356808761-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEBQHGJABNTj5ISSOTRxM%2Fuploads%2FEtwaq5BSrHW6hWwgkUmC%2FScreenshot%202024-05-30%20at%2009.24.35.png?alt=media&amp;token=d157be1e-d2e9-4ace-a82b-d20333d354f4" alt=""><figcaption></figcaption></figure>

1. Click Add to add a new timeplan.

This will add a new line:

<figure><img src="https://3356808761-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEBQHGJABNTj5ISSOTRxM%2Fuploads%2F0QiPxVvLjmBf5RrvtIII%2Fimage.png?alt=media&amp;token=816d49ec-2333-4dfa-8f17-43fc2fc21cfe" alt=""><figcaption></figcaption></figure>

3. Click on the newly created line to unfold the form

<figure><img src="https://3356808761-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEBQHGJABNTj5ISSOTRxM%2Fuploads%2F1OpCyESFNgnCoWEnWwiJ%2Fimage.png?alt=media&amp;token=4e7c9c80-4029-48ea-bbe8-63a5f8807abf" alt=""><figcaption></figcaption></figure>

4. Now provide a description (for you to keep track of the different timeplans)
5. Select what kind of Timeplan it is: Weekly, Yearly, One time, Period or Fixed.
6. Choose the "Set system status" to be nothing when your timeplan doesn't affect the online or offline status of your bot, otherwise choose online or offline when it does impact the status.
7. Choose to add a specific tag which then can be used in your flow to make specific logic based on this tag, for instance when you want to say to the user "We are currently having lunch" or something.
8. Now, dependent on what kind of Timeplan you selected you can fill in the details (see examples below for more information):
   1. Weekly: days of the week followed by a from and until time
   2. Yearly: month, optionally a day, and a from and until time. Leave the day empty to apply the hours to every day of that month.
   3. One time: date and a from and until time
   4. Period: a range between a from and until date
   5. Fixed: a recurring predefined public holiday or public observatory day, like Easter or Christmas

## Fields

| Property               | Description                                                                        | Explanation                                                                                                                                                                                                                                                |
| ---------------------- | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Description            | A human readable description                                                       | For you to keep track of your timeplans. It has no utilitarian purpuse.                                                                                                                                                                                    |
| Kind                   | What type of timeplan? Weekly, Yearly, One time, Period or Fixed                   | This has effect on what date and time details are asked below                                                                                                                                                                                              |
| Set system status      | Does your timeplan affect the online or offline status of your bot?                | Choose online when it should set the status to **online**. Set offline when it should set the status to **offline** and leave empty if it doesn't impact the status.                                                                                       |
| Add tag                | Sets a specific tag when this Timeplan is active.                                  | This helps you to define specific logic in your flows for this Timeplan, for instance a special text that explains the company is heaving lunch.                                                                                                           |
| Office hours           | Define a time period per week day                                                  | Only visible when Kind is configured with "Weekly"                                                                                                                                                                                                         |
| Month and day          | Define the month and day at which this Timeplan should be active on a yearly basis | Only visible when Kind is configured with "Yearly". Leave Day empty to make the timeplan active every day of the selected month (Timeplans 8.2.0 and later). Notice that when 29/2 is selected for example, the system will automatically fallback to 28/2 |
| Date                   | Define the exact date at which this timeplan becomes active                        | Only when Kind is configured as "One time"                                                                                                                                                                                                                 |
| From and Until (dates) | Define the first and last date of the period                                       | Only when Kind is configured as "Period"                                                                                                                                                                                                                   |
| Day (Fixed)            | Pick a public holiday or observance day from the list                              | Only when Kind is configured as "Fixed". The date is worked out for every year, also for holidays that move, like Easter                                                                                                                                   |
| From                   | Define the exact time at which this timeplan becomes active on the given day       |                                                                                                                                                                                                                                                            |
| Until                  | Define the exact time until this timeplan is active on the given day               |                                                                                                                                                                                                                                                            |

## Examples

### One time: Beach day

A one time Timeplan that sets the general status to offline and even adds a tag to indicate there is a beach day going on that day.

<figure><img src="https://3356808761-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEBQHGJABNTj5ISSOTRxM%2Fuploads%2F2SDrAYaPqzH3ReJ6UrBY%2Fimage.png?alt=media&amp;token=e2fb4287-d510-4e05-b70b-6811a24637e0" alt=""><figcaption></figcaption></figure>

### Yearly: Christmas

A yearly timeplan to manage Christmas day as a closed day can be configured as following:

<figure><img src="https://3356808761-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEBQHGJABNTj5ISSOTRxM%2Fuploads%2FsWXZxEliAuzNbn8ZE6pX%2Fimage.png?alt=media&amp;token=c10cfc2e-e375-46ff-8236-e5df36613264" alt=""><figcaption></figcaption></figure>

### Yearly: extra evening hours in winter

When you are open longer in some months only, for instance evening hours during the winter months, use a yearly timeplan without a day. Leave Day empty and the From and Until times apply to every day of the selected month. Add one timeplan per month:

* Kind: Yearly
* Set system status: online
* Month: January (and the same timeplan again for February, December, …)
* Day: leave empty
* From: 18:00
* Until: 23:59

{% hint style="info" %}
A yearly timeplan without a day needs Timeplans 8.2.0 or later.
{% endhint %}

{% hint style="warning" %}
A timeplan cannot run past midnight: From and Until always fall on the same day. For a night shift, such as 22:00 to 06:00, add two timeplans: one from 22:00 until 23:59 and one from 00:00 until 06:00.
{% endhint %}

### Weekly: Lunch break

A weekly recurring schedule to manage a closed situation due to lunch can be configured as such:

<figure><img src="https://3356808761-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEBQHGJABNTj5ISSOTRxM%2Fuploads%2FVPfV2MxLfD6fpy5osBXF%2Fimage.png?alt=media&amp;token=ec4461e0-e89a-474e-9247-bbc70f86b406" alt=""><figcaption></figcaption></figure>

### Period: Spring break

When you're closed for a couple of days, e.g. during spring break, you can configure an offline situation as follows:

<figure><img src="https://3356808761-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEBQHGJABNTj5ISSOTRxM%2Fuploads%2FzO7erwz43hJeCm0NUW1K%2FCleanShot%202025-04-30%20at%2008.55.52%402x.png?alt=media&amp;token=107eb77a-ed94-40ea-bf5c-2d26394b062d" alt=""><figcaption></figcaption></figure>

Note that the "Until" date is inclusive. In the example above, that would mean that on the 25th of april, the system status would be offline.

### Fixed: Easter Sunday

There are many public holidays or public observatory days that are yearly recurring. When they have a fixed date every year, you can easily add a timeplan for them using the yearly timeplan type. But when it is a date that differs per year it can be a real pain to update the configuration every year. For instance Easter or any easter based event like Good Friday, Ash Wednesday, etc. For this reason we introduced the "fixed" timeplans type.

<figure><img src="https://3356808761-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEBQHGJABNTj5ISSOTRxM%2Fuploads%2FL6MwN06wKnhCqrvIfP0s%2Fimage.png?alt=media&amp;token=4452d128-3a7d-4eaa-8ec6-85b1333b0a2e" alt=""><figcaption></figcaption></figure>

## Timeplan tags

The tags you can add as part of a timeplan need to be part of the Timeplan group. This group is automatically added to your bot Tags at install of the Timeplans skill. This way, whenever you add a tag in your timeplan, it will group it as a Timeplan tag:

<figure><img src="https://3356808761-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEBQHGJABNTj5ISSOTRxM%2Fuploads%2FZQIY50e2oUwzgYeILJ7e%2Fimage.png?alt=media&amp;token=7d0a3b23-37ea-490f-971b-75284cf7a865" alt=""><figcaption></figcaption></figure>

So simply type the name of your tag and click on the "+ Create tag…" button that appears to create the tag inside the tag group "timeplan".

{% hint style="info" %}
Read more about tags [here](https://manuals.dialox.ai/settings/app-settings/tags.md).
{% endhint %}

The skill will set a predefined tag when the current time fall within the defined day and time. Using the tag you can define [conditions](https://manuals.dialox.ai/studio/flows/conditions.md) in flow nodes, for instance to skip over a node or to [branch](https://manuals.dialox.ai/studio/flows/nodes/control-flow-branch.md).

### Use Timeplan accordingly

To create a well-functioning time plan, you must ensure that your time plan comes before all other system tags. For instance, if you have the online and offline situations, you must put your timeplan on the left side of these statuses. This way the system knows that it must execute the time plan on that specific day and will overwrite the other statuses.

<figure><img src="https://3356808761-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEBQHGJABNTj5ISSOTRxM%2Fuploads%2FPh5b0JmtUoZJDnXQKcNH%2FScreenshot%202024-05-30%20at%2009.32.18.png?alt=media&amp;token=816d75c1-47b8-4673-a8f4-9794e2106f2e" alt=""><figcaption></figcaption></figure>
