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
Visibility => 'Internal' # (optional) default 'Internal' (other values: External | ExternalRestricted | Public)
);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
DynamicFields => 0|1, # (optional, default 0) include dynamic field data as well
Result => 'HASH', # (optional), HASH|ARRAY
Visibility => '...' | [...] # (optional) Filter by visibility, multiple values supported
);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!,
Visibility => 'Internal',
},
...
];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)
DynamicFields => 0|1, # (optional, default 0) include dynamic field data as well
);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,
Visibility => 'Internal',
);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
TeamID => 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
Visibility => 'Internal' # (optional) default 'Internal' (other values: External | ExternalRestricted | Public)
);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.AppointmentSearch()
Search for appointments in the system.
my @AppointmentIDs = $AppointmentObject->AppointmentSearch(
# Result (required)
Result => 'ARRAY' || 'COUNT',
# Result limit
Limit => 10000,
# Use AppointmentSearch as a appointment filter on a single appointment
# or a predefined appointment list
AppointmentID => 1234,
AppointmentID => [1234, 1235],
# Appointment title (optional) as STRING or as ARRAYREF
Title => '%SomeText%',
Title => ['%SomeTest1%', '%SomeTest2%'],
# Appointment location (optional) as STRING or as ARRAYREF
Location => '%SomeText%',
Location => ['%SomeTest1%', '%SomeTest2%'],
# Appointment description (optional) as STRING or as ARRAYREF
Description => '%SomeText%',
Description => ['%SomeTest1%', '%SomeTest2%'],
# Appointment calendars
CalendarIDs => [1, 2, 3],
Calendars => ['CalendarA', 'CalendarB'],
# Appointment teams
TeamIDs => [1, 2, 3],
Teams => ['TeamA', 'TeamB'],
# Appointment resources
ResourceIDs => [1, 2, 3],
# AllDay appointments
AllDay => 1,
# Appointments created more than 60 minutes ago (appointment older than 60 minutes) (optional)
AppointmentCreateTimeOlderMinutes => 60,
# Appointments created less than 120 minutes ago (appointment newer than 120 minutes) (optional)
AppointmentCreateTimeNewerMinutes => 120,
# Appointments with create time after ... (appointment newer than this date) (optional)
AppointmentCreateTimeNewerDate => '2006-01-09 00:00:01',
# Appointments with created time before ... (appointment older than this date) (optional)
AppointmentCreateTimeOlderDate => '2006-01-19 23:59:59',
# Appointments started more than 60 minutes ago (appointment start time older than 60 minutes) (optional)
AppointmentStartTimeOlderMinutes => 60,
# Appointments started less than 120 minutes ago (appointment start time newer than 120 minutes) (optional)
AppointmentStartTimeNewerMinutes => 120,
# Appointments with start time after ... (appointment start time newer than this date) (optional)
AppointmentStartTimeNewerDate => '2006-01-09 00:00:01',
# Appointments with start time before ... (appointment start time older than this date) (optional)
AppointmentStartTimeOlderDate => '2006-01-19 23:59:59',
# Appointments ended more than 60 minutes ago (appointment end time older than 60 minutes) (optional)
AppointmentEndTimeOlderMinutes => 60,
# Appointments ended less than 120 minutes ago (appointment end time newer than 120 minutes) (optional)
AppointmentEndTimeNewerMinutes => 120,
# Appointments with end time after ... (appointment end time newer than this date) (optional)
AppointmentEndTimeNewerDate => '2006-01-09 00:00:01',
# Appointments with end time before ... (appointment end time older than this date) (optional)
AppointmentEndTimeOlderDate => '2006-01-19 23:59:59',
# Appointments which are inside the given period. Both values must be given for this filter. (optional)
AppointmentPeriodTimeNewerDate => '2006-01-09 00:00:01',
AppointmentPeriodTimeOlderDate => '2006-01-19 23:59:59',
# DynamicFields
# At least one operator must be specified. Operators will be connected with AND,
# values in an operator with OR.
# You can also pass more than one argument to an operator: ['value1', 'value2']
DynamicField_FieldNameX => {
Empty => 1, # will return dynamic fields without a value
# set to 0 to search fields with a value present
Equals => 123,
Like => 'value*', # "equals" operator with wildcard support
GreaterThan => '2001-01-01 01:01:01',
GreaterThanEquals => '2001-01-01 01:01:01',
SmallerThan => '2002-02-02 02:02:02',
SmallerThanEquals => '2002-02-02 02:02:02',
}
# OrderBy and SortBy (optional)
OrderBy => 'Down', # Down|Up
SortBy => 'Age', # AppointmentID, Title, Calendar, Location, StartTime, EndTime, AllDay, Age, Created, Changed
# OrderBy and SortBy as ARRAY for sub sorting (optional)
OrderBy => ['Down', 'Up'],
SortBy => ['Priority', 'Age'],
);Returns:
Result: 'ARRAY'
@AppointmentIDs = ( 1, 2, 3 );Result: 'COUNT'
$AppointmentIDs = 123;AppointmentSearchForCustomerUser()
Returns a list of appointments that are visible for general public or customer user.
my @List = $AppointmentObject->AppointmentSearchForCustomerUser(
CustomerUserLogin => '...', # optional
UserID => '...', # required
Group => '...', # optional (default:All; All|Personal|Company)
# only takes effect when a valid customer-user was passed.
DynamicFields => [...] # optional (list of dynamic fields to include)
);returns:
undef - in case of any error
(
{
...
}
)AppointmentGetForCustomerUser()
Get appointment data.
my %Appointment = $AppointmentObject->AppointmentGetForCustomerUser(
AppointmentID => 1, # (required)
DynamicFields => 0|1, # (optional, default 0) include dynamic field data as well
);Returns a hash:
%Appointment = (
...
);