########### 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: .. code-block:: perl 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. .. code-block:: perl 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. .. code-block:: perl 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': .. code-block:: perl @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': .. code-block:: perl @Appointments = [ 1, 2, ... ] AppointmentDays() ================= get a hash of days with Appointments in all user calendars. .. code-block:: perl 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: .. code-block:: perl %AppointmentDays = { '2016-01-01' => 1, '2016-01-13' => 2, '2016-01-30' => 1, }; AppointmentGet() ================ Get appointment data. .. code-block:: perl 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: .. code-block:: perl %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. .. code-block:: perl my @RecurringAppointments = $AppointmentObject->AppointmentRecurringGet( AppointmentID => 1, # (required) # or UniqueID => '20160101T160000-71E386@localhost', # (required) CalendarID => 1, # (required) ); Returns an array: .. code-block:: perl @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. .. code-block:: perl 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. .. code-block:: perl 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. .. code-block:: perl 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``\ . .. code-block:: perl 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. .. code-block:: perl 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. .. code-block:: perl my $Success = $AppointmentObject->AppointmentFutureTasksDelete(); returns: .. code-block:: perl True if future task deletion was successful, otherwise false. AppointmentFutureTasksUpdate() ============================== Update OTRS daemon future task list for upcoming appointments. .. code-block:: perl my $Success = $AppointmentObject->AppointmentFutureTasksUpdate(); returns: .. code-block:: perl True if future task update was successful, otherwise false. _AppointmentNotificationPrepare() ================================= Prepare appointment notification data. .. code-block:: perl my $Success = $AppointmentObject->_AppointmentNotificationPrepare(); returns: .. code-block:: perl 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. .. code-block:: perl my $Success = $AppointmentObject->AppointmentNotification(); returns: .. code-block:: perl 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. .. code-block:: perl my $Result = $Self->_TimeCheck( OriginalTime => '2016-01-01 00:01:00', # (required) Time => '2016-02-01 00:02:00', # (required) ); Returns: .. code-block:: perl $Result = '2016-02-01 00:01:00'; _CWDiff() ========= Returns how many calendar weeks has passed between two unix times. .. code-block:: perl my $CWDiff = $Self->_CWDiff( CurrentTime => $CurrentTimeObject, (required) Date time object with current time OriginalTime => $OriginalTimeObject, (required) Date time object with original time ); returns: .. code-block:: perl $CWDiff = 5;