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;