Appointment#
NAME#
Kernel::System::Calendar::Appointment - calendar appointment lib
DESCRIPTION#
All appointment functions.
PUBLIC INTERFACE#
new()#
create an object. Do not use it directly, instead use:
use Kernel::System::ObjectManager;
local $Kernel::OM = Kernel::System::ObjectManager->new();
my $AppointmentObject = $Kernel::OM->Get('Kernel::System::Calendar::Appointment');
AppointmentCreate()#
creates a new appointment.
my $AppointmentID = $AppointmentObject->AppointmentCreate(
ParentID => 1, # (optional) valid ParentID for recurring appointments
CalendarID => 1, # (required) valid CalendarID
UniqueID => 'jwioji-fwjio', # (optional) provide desired UniqueID; if there is already existing Appointment
# with same UniqueID, system will delete it
Title => 'Webinar', # (required) Title
Description => 'How to use Process tickets...', # (optional) Description
Location => 'Straubing', # (optional) Location
StartTime => '2016-01-01 16:00:00', # (required)
EndTime => '2016-01-01 17:00:00', # (required)
AllDay => 0, # (optional) default 0
TeamID => [ 1 ], # (optional) must be an array reference if supplied
ResourceID => [ 1, 3 ], # (optional) must be an array reference if supplied
Recurring => 1, # (optional) flag the appointment as recurring (parent only!)
RecurringRaw => 1, # (optional) skip loop for recurring appointments (do not create occurrences!)
RecurrenceType => 'Daily', # (required if Recurring) Possible "Daily", "Weekly", "Monthly", "Yearly",
# "CustomWeekly", "CustomMonthly", "CustomYearly"
RecurrenceFrequency => [1, 3, 5], # (required if Custom Recurring) Recurrence pattern
# for CustomWeekly: 1-Mon, 2-Tue,..., 7-Sun
# for CustomMonthly: 1-1st, 2-2nd,.., 31th
# for CustomYearly: 1-Jan, 2-Feb,..., 12-Dec
# ...
RecurrenceCount => 1, # (optional) How many Appointments to create
RecurrenceInterval => 2, # (optional) Repeating interval (default 1)
RecurrenceUntil => '2016-01-10 00:00:00', # (optional) Until date
RecurrenceID => '2016-01-10 00:00:00', # (optional) Expected start time for this occurrence
RecurrenceExclude => [ # (optional) Which specific occurrences to exclude
'2016-01-10 00:00:00',
'2016-01-11 00:00:00',
],
NotificationTime => '2016-01-01 17:00:00', # (optional) Point of time to execute the notification event
NotificationTemplate => 'Custom', # (optional) Template to be used for notification point of time
NotificationCustom => 'relative', # (optional) Type of the custom template notification point of time
# Possible "relative", "datetime"
NotificationCustomRelativeUnitCount => '12', # (optional) minutes, hours or days count for custom template
NotificationCustomRelativeUnit => 'minutes', # (optional) minutes, hours or days unit for custom template
NotificationCustomRelativePointOfTime => 'beforestart', # (optional) Point of execute for custom templates
# Possible "beforestart", "afterstart", "beforeend", "afterend"
NotificationCustomDateTime => '2016-01-01 17:00:00', # (optional) Notification date time for custom template
TicketAppointmentRuleID => '9bb20ea035e7a9930652a9d82d00c725', # (optional) Ticket appointment rule ID (for ticket appointments only!)
UserID => 1, # (required) UserID
);
returns parent AppointmentID if successful
- Events:
AppointmentCreate
AppointmentList()#
get a hash of Appointments.
my @Appointments = $AppointmentObject->AppointmentList(
CalendarID => 1, # (required) Valid CalendarID
Title => '*', # (optional) Filter by title, wildcard supported
Description => '*', # (optional) Filter by description, wildcard supported
Location => '*', # (optional) Filter by location, wildcard supported
StartTime => '2016-01-01 00:00:00', # (optional) Filter by start date
EndTime => '2016-02-01 00:00:00', # (optional) Filter by end date
TeamID => 1, # (optional) Filter by team
ResourceID => 2, # (optional) Filter by resource
Result => 'HASH', # (optional), HASH|ARRAY
);
returns an array of hashes with select Appointment data or simple array of AppointmentIDs:
Result => ‘HASH’:
@Appointments = [
{
AppointmentID => 1,
CalendarID => 1,
UniqueID => '20160101T160000-71E386@localhost',
Title => 'Webinar',
Description => 'How to use Process tickets...',
Location => 'Straubing',
StartTime => '2016-01-01 16:00:00',
EndTime => '2016-01-01 17:00:00',
AllDay => 0,
Recurring => 1, # for recurring (parent) appointments only
},
{
AppointmentID => 2,
ParentID => 1, # for recurred (child) appointments only
CalendarID => 1,
UniqueID => '20160101T180000-A78B57@localhost',
Title => 'Webinar',
Description => 'How to use Process tickets...',
Location => 'Straubing',
StartTime => '2016-01-02 16:00:00',
EndTime => '2016-01-02 17:00:00',
TeamID => [ 1 ],
ResourceID => [ 1, 3 ],
AllDay => 0,
},
{
AppointmentID => 3,
CalendarID => 1,
UniqueID => '20160101T180000-A78B57@localhost',
Title => 'Webinar',
Description => 'How to use Process tickets...',
Location => 'Straubing',
StartTime => '2016-01-02 16:00:00',
EndTime => '2016-01-02 17:00:00',
TimezoneID => 1,
TeamID => [ 1 ],
ResourceID => [ 1, 3 ],
NotificationDate => '2016-01-02 16:10:00',
NotificationTemplate => 'Custom',
NotificationCustom => 'relative',
NotificationCustomRelativeUnitCount => '10',
NotificationCustomRelativeUnit => 'minutes',
NotificationCustomRelativePointOfTime => 'afterstart',
NotificationCustomDateTime => '2016-01-02 16:00:00',
TicketAppointmentRuleID => '9bb20ea035e7a9930652a9d82d00c725', # for ticket appointments only!
},
# ...
];
Result => ‘ARRAY’:
@Appointments = [ 1, 2, ... ]
AppointmentDays()#
get a hash of days with Appointments in all user calendars.
my %AppointmentDays = $AppointmentObject->AppointmentDays(
StartTime => '2016-01-01 00:00:00', # (optional) Filter by start date
EndTime => '2016-02-01 00:00:00', # (optional) Filter by end date
UserID => 1, # (required) Valid UserID
);
returns a hash with days as keys and number of Appointments as values:
%AppointmentDays = {
'2016-01-01' => 1,
'2016-01-13' => 2,
'2016-01-30' => 1,
};
AppointmentGet()#
Get appointment data.
my %Appointment = $AppointmentObject->AppointmentGet(
AppointmentID => 1, # (required)
# or
UniqueID => '20160101T160000-71E386@localhost', # (required) will return only parent for recurring appointments
CalendarID => 1, # (required)
);
Returns a hash:
%Appointment = (
AppointmentID => 2,
ParentID => 1, # only for recurred (child) appointments
CalendarID => 1,
UniqueID => '20160101T160000-71E386@localhost',
Title => 'Webinar',
Description => 'How to use Process tickets...',
Location => 'Straubing',
StartTime => '2016-01-01 16:00:00',
EndTime => '2016-01-01 17:00:00',
AllDay => 0,
TeamID => [ 1 ],
ResourceID => [ 1, 3 ],
Recurring => 1,
RecurrenceType => 'Daily',
RecurrenceFrequency => 1,
RecurrenceCount => 1,
RecurrenceInterval => 2,
RecurrenceUntil => '2016-01-10 00:00:00',
RecurrenceID => '2016-01-10 00:00:00',
RecurrenceExclude => [
'2016-01-10 00:00:00',
'2016-01-11 00:00:00',
],
NotificationTime => '2016-01-01 17:0:00',
NotificationTemplate => 'Custom',
NotificationCustomUnitCount => '12',
NotificationCustomUnit => 'minutes',
NotificationCustomUnitPointOfTime => 'beforestart',
TicketAppointmentRuleID => '9bb20ea035e7a9930652a9d82d00c725', # for ticket appointments only!
CreateTime => '2016-01-01 00:00:00',
CreateBy => 2,
ChangeTime => '2016-01-01 00:00:00',
ChangeBy => 2,
);
AppointmentRecurringGet()#
Get data of all of an appointment’s recurring appointments.
my @RecurringAppointments = $AppointmentObject->AppointmentRecurringGet(
AppointmentID => 1, # (required)
# or
UniqueID => '20160101T160000-71E386@localhost', # (required)
CalendarID => 1, # (required)
);
Returns an array:
@RecurringAppointment = (
{
AppointmentID => 2,
ParentID => 1,
CalendarID => 1,
UniqueID => '20160101T160000-71E386@localhost',
Title => 'Webinar',
Description => 'How to use Process tickets...',
Location => 'Straubing',
StartTime => '2016-01-01 16:00:00',
EndTime => '2016-01-01 17:00:00',
AllDay => 0,
TeamID => [ 1 ],
ResourceID => [ 1, 3 ],
Recurring => 1,
RecurrenceType => 'Daily',
RecurrenceFrequency => 1,
RecurrenceCount => 1,
RecurrenceInterval => 2,
RecurrenceUntil => '2016-01-10 00:00:00',
RecurrenceID => '2016-01-10 00:00:00',
RecurrenceExclude => [
'2016-01-10 00:00:00',
'2016-01-11 00:00:00',
],
NotificationTime => '2016-01-01 17:0:00',
NotificationTemplate => 'Custom',
NotificationCustomUnitCount => '12',
NotificationCustomUnit => 'minutes',
NotificationCustomUnitPointOfTime => 'beforestart',
TicketAppointmentRuleID => '9bb20ea035e7a9930652a9d82d00c725', # for ticket appointments only!
CreateTime => '2016-01-01 00:00:00',
CreateBy => 2,
ChangeTime => '2016-01-01 00:00:00',
ChangeBy => 2,
},
# ...
);
AppointmentUpdate()#
updates an existing appointment.
my $Success = $AppointmentObject->AppointmentUpdate(
AppointmentID => 2, # (required)
CalendarID => 1, # (required) Valid CalendarID
Title => 'Webinar', # (required) Title
Description => 'How to use Process tickets...', # (optional) Description
Location => 'Straubing', # (optional) Location
StartTime => '2016-01-01 16:00:00', # (required)
EndTime => '2016-01-01 17:00:00', # (required)
AllDay => 0, # (optional) Default 0
Team => 1, # (optional)
ResourceID => [ 1, 3 ], # (optional) must be an array reference if supplied
Recurring => 1, # (optional) flag the appointment as recurring (parent only!)
RecurrenceType => 'Daily', # (required if Recurring) Possible "Daily", "Weekly", "Monthly", "Yearly",
# "CustomWeekly", "CustomMonthly", "CustomYearly"
RecurrenceFrequency => 1, # (required if Custom Recurring) Recurrence pattern
# for CustomWeekly: 1-Mon, 2-Tue,..., 7-Sun
# for CustomMonthly: 1-Jan, 2-Feb,..., 12-Dec
# ...
RecurrenceCount => 1, # (optional) How many Appointments to create
RecurrenceInterval => 2, # (optional) Repeating interval (default 1)
RecurrenceUntil => '2016-01-10 00:00:00', # (optional) Until date
NotificationTime => '2016-01-01 17:00:00', # (optional) Point of time to execute the notification event
NotificationTemplate => 'Custom', # (optional) Template to be used for notification point of time
NotificationCustom => 'relative', # (optional) Type of the custom template notification point of time
# Possible "relative", "datetime"
NotificationCustomRelativeUnitCount => '12', # (optional) minutes, hours or days count for custom template
NotificationCustomRelativeUnit => 'minutes', # (optional) minutes, hours or days unit for custom template
NotificationCustomRelativePointOfTime => 'beforestart', # (optional) Point of execute for custom templates
# Possible "beforestart", "afterstart", "beforeend", "afterend"
NotificationCustomDateTime => '2016-01-01 17:00:00', # (optional) Notification date time for custom template
TicketAppointmentRuleID => '9bb20ea035e7a9930652a9d82d00c725', # (optional) Ticket appointment rule ID (for ticket appointments only!)
UserID => 1, # (required) UserID
);
- returns 1 if successful:
$Success = 1;
- Events:
AppointmentUpdate
AppointmentDelete()#
deletes an existing appointment.
my $Success = $AppointmentObject->AppointmentDelete(
AppointmentID => 1, # (required)
UserID => 1, # (required)
);
- returns 1 if successful:
$Success = 1;
- Events:
AppointmentDelete
AppointmentDeleteOccurrence()#
deletes a single recurring appointment occurrence.
my $Success = $AppointmentObject->AppointmentDeleteOccurrence(
UniqueID => '20160101T160000-71E386@localhost', # (required)
RecurrenceID => '2016-01-10 00:00:00', # (required)
UserID => 1, # (required)
);
- returns 1 if successful:
$Success = 1;
GetUniqueID()#
Returns UniqueID containing appointment start time, random hash and system FQDN
.
my $UniqueID = $AppointmentObject->GetUniqueID(
CalendarID => 1, # (required)
StartTime => '2016-01-01 00:00:00', # (required)
UserID => 1, # (required)
);
$UniqueID = '20160101T000000-B9909D@localhost';
AppointmentUpcomingGet()#
Get appointment data for upcoming appointment start or end.
my @UpcomingAppointments = $AppointmentObject->AppointmentUpcomingGet(
Timestamp => '2016-08-02 03:59:00', # get appointments for the related notification timestamp
);
Returns appointment data of AppointmentGet().
AppointmentFutureTasksDelete()#
Delete all calendar appointment future tasks.
my $Success = $AppointmentObject->AppointmentFutureTasksDelete();
returns:
True if future task deletion was successful, otherwise false.
AppointmentFutureTasksUpdate()#
Update OTRS daemon future task list for upcoming appointments.
my $Success = $AppointmentObject->AppointmentFutureTasksUpdate();
returns:
True if future task update was successful, otherwise false.
_AppointmentNotificationPrepare()#
Prepare appointment notification data.
my $Success = $AppointmentObject->_AppointmentNotificationPrepare();
returns:
True if preparation was successful, otherwise false.
AppointmentNotification()#
Will be triggered by the OTRS daemon to fire events for appointments, that reaches it’s reminder (notification) time.
my $Success = $AppointmentObject->AppointmentNotification();
returns:
True if notify action was successful, otherwise false.
_TimeCheck()#
Check if Time and OriginalTime have same hour, minute and second value, and return timestamp with values (hour, minute and second) as in Time.
my $Result = $Self->_TimeCheck(
OriginalTime => '2016-01-01 00:01:00', # (required)
Time => '2016-02-01 00:02:00', # (required)
);
- Returns:
$Result = ‘2016-02-01 00:01:00’;
_CWDiff()#
Returns how many calendar weeks has passed between two unix times.
my $CWDiff = $Self->_CWDiff(
CurrentTime => $CurrentTimeObject, (required) Date time object with current time
OriginalTime => $OriginalTimeObject, (required) Date time object with original time
);
- returns:
$CWDiff = 5;