<?xml version='1.0' encoding='ISO-8859-1'?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
  "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<!-- $Id: time.xml,v 1.15 2010/01/04 13:10:05 mb Exp $ -->

<chapter id="time">
<title>Time related functions</title>

<sect1 id="time-settings">
<title>Setting up business hours, holidays and time zones</title>

<para>
Some functions in OTRS, like escalations
and <link linkend="unlock-tickets">automatic unlocking of tickets</link>,
depend on a proper configuration of business hours, time zones and holidays.
You can define default business hours and holidays for your system via the
<link linkend="sysconfig">
SysConfig interface.
</link>
in <link linkend="Framework:Core::Time">Framework > Core::Time</link>
and additionally you can define different sets of business hours, holidays and
time zones as separate 'Calendars' in
<link linkend="Framework:Core::Time::Calendar1">Framework > Core::Time::Calendar1</link>
until
<link linkend="Framework:Core::Time::Calendar9">Framework > Core::Time::Calendar9</link>.
You can define calendars on a <link linkend="adminarea-queue">queue</link> level
and on the SLA level. This means that you can specify a calendar with 5 x 8
business hours for your 'standard' SLA but create a separate calendar with
7 x 24 support for your 'gold' SLA. Also, you can have a calendar for your
'Support-USA' queue with a different time window than your 'Support-Japan' queue.
OTRS can handle up to 99 different calendars.
</para>

<sect2 id="TimeWorkingHours">
<title>Business Hours</title>

<para>
Set up the working hours for your system in SysConfig
<link linkend="Framework:Core::Time:TimeWorkingHours">
Framework> Core::Time::TimeWorkingHours
</link> or for your specific calendar, in the calendar's configuration.
OTRS can handle a granularity of one hour. Checking the marks in the boxes
8, 9, 10 ... 17 corresponds with business hours of 8 AM - 6 PM.
</para>

<para>
Only during the business hours tickets can escalate, notifications
for escalated and pending tickets will be send and tickets will be unlocked.
</para>
</sect2>

<sect2 id="TimeVacationDays">
<title>Fixed date holidays</title>

<para>
Holidays that are on a fixed date every year, such as New Year's Day and
Fourth of July, can be specified in
<link linkend="Framework:Core::Time:TimeVacationDays">
TimeVacationDays
</link>
or the corresponding section for the calendars 1-9.
</para>

<para>
Tickets will not escalate and
will not be unlocked on dates defined in TimeVacationDays.
</para>

<note>
<para>
By default, OTRS ships with the <emphasis>German</emphasis> holidays installed.
You would need to replace these with the days agreed on in your SLA, if you have
one, or to the days that are considered holidays in your company.
</para>
</note>


</sect2>

<sect2 id="TimeVacationDaysOneTime">
<title>TimeVacationDaysOneTime</title>

<para>
Holidays that do not fall on a fixed date each year, such as Easter, can be
specified in <link linkend="Framework:Core::Time:TimeVacationDaysOneTime">
TimeVacationDaysOneTime
</link>
.
</para>

<para>
Tickets will not escalate and will not be unlocked on dates defined in
TimeVacationDaysOneTime.
</para>

<note>
<para>
OTRS does not ship with any One-Time holidays pre-installed.
This means that you need to add holidays such as Eastern or Thanksgiving
to the system when configuring OTRS.
You should use the days agreed on in your SLA, if you have
one, or to the days that are considered holidays in your company.
</para>
</note>

</sect2>
</sect1>

<sect1 id="unlock-tickets">
<title>Automated Unlocking</title>

<para>
Locked tickets can be unlocked automatically by the system. This feature might
be useful if an agent has locked tickets that need to be processed, but the
agent can't work on this tickets because the agent is on holiday, for example.
The automated unlock feature unlocks tickets after a given time to ensure that
no locked tickets will be forgotten and other agents can process these.
</para>

<para>
The amount of time before a ticket is unlocked can be specified in the

<link linkend="adminarea-queue">
settings
</link>

for every queue. The module <filename>bin/UnlockTickets.pl</filename>,
which is executed periodically as a cron job, performs the
automated unlocking of tickets.
</para>

<para>
Notifications on unlocked tickets are send out only to those agents that
have the queue with the unlocked tickets set in "My queues" and that have
activated the notification on unlocked tickets in their personal

<link linkend="user-preferences">
preferences
</link>
.
</para>

<para>
Tickets will be unlocked if the following conditions are met:
</para>

<itemizedlist>
<listitem>
<para>
There is an <emphasis>unlock timeout</emphasis> defined at the queue the
ticket is in.
</para>
</listitem>
<listitem>
<para>
The ticket is set to <emphasis>locked</emphasis>
</para>
</listitem>
<listitem>
<para>
The ticket state is <emphasis>open</emphasis>.
</para>
</listitem>
</itemizedlist>

<para>
The unlock timer will be reset if an agent adds a new external article to the
ticket, of types <emphasis>email-external</emphasis>,
<emphasis>phone</emphasis>, <emphasis>fax</emphasis>,
<emphasis>sms</emphasis>, or <emphasis>note-external</emphasis>.</para>

<para>Also, if the last article in the ticket is created by an agent, and a
customer adds a new article to the ticket, either via the web or via an
email response, the unlock timer will be reset.</para>

<para>The last event that will reset the unlock timer is when the ticket
is assigned to another agent.</para>

</sect1>

</chapter>