Appointment From ICS
====================

Rexpondo can automatically extract appointment information (start time, end
time and meeting link) from **ICS calendar attachments** received by e-mail
and write the values into dynamic fields on the ticket or on the article.
This is implemented as a Generic Agent module
(``Kernel::System::GenericAgent::AppointmentFromICS``) that can be plugged
into any event-based or scheduled Generic Agent job.


How ICS Attachments Are Recognised
----------------------------------

For every article processed by the job, all attachments are inspected. An
attachment is treated as an ICS file when at least one of the following
conditions is true:

- the file name ends with ``.ics``;
- the MIME content type is ``text/calendar``;
- the attachment has no file extension at all (some mail clients send the
  invite as a body part without a name).

The module parses the ``DTSTART`` and ``DTEND`` properties of the first
``VEVENT`` found and looks for the meeting URL in the following ICS
properties (in order):

- ``X-MICROSOFT-SKYPETEAMSMEETINGURL``
- ``X-GOOGLE-CONFERENCE``


Prerequisites
-------------

Create the dynamic fields you want to populate **before** configuring the
job (see :doc:`dynamic-fields`):

- one *Date / Time* dynamic field for the appointment start (required);
- optionally a *Date / Time* dynamic field for the appointment end;
- optionally a *Text* dynamic field for the meeting link. To render it as
  a clickable link in the ticket sidebar, set the *Show link* template of
  the dynamic field to::

     [% Data.Value | uri %]


Configuring the Generic Agent Job
---------------------------------

1. Open *Generic Agent* (see :doc:`generic-agent`) and create a new job.
2. In the *Job Trigger* section select the **event-based** trigger and pick
   the ``ArticleCreate`` event so that every incoming article is inspected.
3. In the *Execute Custom Module* section fill in:

   - **Module**: ``Kernel::System::GenericAgent::AppointmentFromICS``
   - **Params**:

     +-------------------------------+--------------------------------------+----------+
     | Key                           | Value                                | Required |
     +===============================+======================================+==========+
     | ``DynamicFieldStart``         | name of the start date/time DF       | yes      |
     +-------------------------------+--------------------------------------+----------+
     | ``DynamicFieldEnd``           | name of the end date/time DF         | no       |
     +-------------------------------+--------------------------------------+----------+
     | ``DynamicFieldMeetingLink``   | name of the meeting-link text DF     | no       |
     +-------------------------------+--------------------------------------+----------+

4. Restrict the job with the usual *Select Tickets* filter (e.g. only on a
   specific queue or for a specific sender domain) to avoid scanning every
   single article.
5. Save the job.

The module automatically detects whether each configured dynamic field is
attached to the *Ticket* or to the *Article* object and writes the value
accordingly.