This extension runs in the background to scan the defined mail inbox(es) and either create or update tickets based on the content of the incoming emails.

• Connect to any mailbox using either the POP3 or IMAP protocol
• Interactive configuration of the mail inboxes
• Processes the incoming eMails in both HTML or plain text format
• Determines whether a Ticket must be created or updated based either on the custom headers added by iTop in the eMail (in case of replies) or based on a configurable pattern in the title
• Support both Incidents and User Request tickets
• Ticket's attachments are automatically turned into attachments of the Ticket (“dangerous” types of attachments can be excluded)
• Automatic detection of duplicate attachments (like signature images)
• Keeps the messages in the mailbox until the corresponding Ticket is either closed or deleted
• Manual retry in case an error occurs when processing an eMail
• Images embedded inside an HTML mail are displayed inline in iTop as well.
• Images “too small” (below configurable dimensions) are not imported as attachments (to exclude signatures)
• Images bigger than configurable dimensions can be resized automatically before uploading into iTop
• “Inline images” are displayed at a reduced (configurable) size and can be “zoomed-in” by clicking on them.
• Automatically reject “Autoreply” emails, based on a set of configurable patterns to be tested against the subject of the email

• Each mail inbox configured corresponds to one type of Ticket (i.e. User Requests or Incidents, but not both).
• Connecting to a POP3 mailbox via the php IMAP extension does not work. You must use the POP3 configuration via PEAR::NetSocket for such a case.
• There is no validation that the target class of the Mail Inbox is an existing class in iTop. (i.e. don't try to create incidents if the Incident Management module is not installed).
• The support on inline images works only if the preferred order for email parts is configured as “text/html,text/plain” (i.e. HTML first), which is now the default for all new installations.

• PHP 5.2.1+ with the IMAP extension enabled if you want to connect to an IMAP server, or PEAR::NetSocket (iTop comes with its own copy of PEAR::POP3) if you want to connect to a POP3 server.
• A connection to a POP3 or IMAP server with a valid mailbox.
• cron.php must be running to enable the processing of incoming eMails.
• For resizing big images, PHP GD must be installed.

1. Expand the content of the zip file in the “extensions” folder of iTop (two folders will be created: combodo-email-synchro and itop-standard-email-synchro).
2. Make sure that the web server has enough rights to read all the files in the “extensions” folder.
3. Launch the setup program, and when prompted for the list of extensions to install, check “Ticket Creation from Emails (Standard)” from the list

sudo apt-get install php5-imap
sudo php5enmod imap
sudo service apache2 restart

When creating a new ticket from an incoming email message, the application automatically fills the following fields of the ticket:

• Title = subject of the mail
• Description = body of the mail
• Caller (caller_id) = sender of the mail (identified by her/his email address)
• Organization (org_id) = organization of the caller
• Origin (if this field exists on the ticket) = 'mail'

Default (i.e. constant) values must be supplied, via the “Ticket Default Values” setting, for any other mandatory field of the Ticket, otherwise the creation of the Ticket will fail.

When updating an existing Ticket, the application add an entry into the public_log field (configurable, see below), with the “new part” of the message. See below for more explanation about how the “new part” is extracted from the message.

The syntax for specifying default values is the following:

• One field per line, with the syntax:
• field_code:default_value

If the field to initialize is a key to another object (for the fields like org_id, service_id, etc…) you can specify either the numeric identifier of the target object (e.g. service_id:153) or its name (e.g. org_id:Demo), provided that the name is unique.

The behavior for each mailbox (which messages to process and whether to create or update a Ticket) is managed via the menu “Incoming eMail Inboxes” in the “Admin tools” section:

Click, “Create a new Mail Inbox” to create a new configuration for a mail inbox. This displays the following form:

The “Mailbox configuration” defines how the application connects to the mail inbox:

This section defines the behavior when an incoming email cannot be processed properly. The email can be either kept in the mailbox (and remembered as an “Error” and no longer processed) or deleted immediately from the mailbox. Furthermore the original message can be forwarded to an administrator (as an attachment) along with some explanation about the cause of the error.

This section defines the behavior of the application when processing incoming emails.

This section determines the behavior of the application when the sender of an email (From:) does not correspond to a known email address in the application. There are two possibilites:

• Reject the eMail: the incoming email is treated as an error and thus either forwarded to an administrator or deleted.
• Create a new person: a new Person will be created based on the email of the sender and constant values defined below.

In addition to the configuration performed by creating a Mail Inbox object using the user interface of the application, a few parameters are available in the configuration file to fine tune the behavior of the application.

        'combodo-email-synchro' => array (
                'debug' => false,
                'periodicity' => 30,
                'body_parts_order' => 'text/html,text/plain',
                'pop3_auth_option' => 'USER',
                'imap_options' => array (
                          0 => 'imap',
                        ),
                'exclude_attachment_types' => array (
                          0 => 'application/exe',
                        ),
                'maximum_email_size' => '10M',
                'introductory-patterns' => array (
                          0 => '/^le .+ a écrit :$/i',
                          1 => '/^on .+ wrote:$/i',
                          2 => '|^[0-9]{4}/[0-9]{1,2}/[0-9]{1,2} .+:$|',
                        ),
                'multiline-delimiter-patterns' => array (
                          0 => '/\\RFrom: .+\\RSent: .+\\R/m',
                          1 => '/\\R_+\\R/m',
                          2 => '/\\RDe : .+\\R\\R?Envoyé : /m',
                          3 => '/\\RDe : .+\\RDate d\'envoi : .+\\R/m',
                          4 => '/\\R-----Message d\'origine-----\\R/m',
                          5 => '/\\RExpéditeur: .+\\RDate:/m',
                          6 => '/\\RDe : .+\\RDate : /m',
                          7 => '/\\TO:.+\\RCC:/m',
                        ),
                'big_files_dir' => '',
                'use_message_id_as_uid' => false, // Don't change this unless you know what you are doing!
                'images_minimum_size' => '100x20',
                'images_maximum_size' => '',
                'undesired-subject-patterns' => array (
                          0 => '/^Out Of Office/i',
                          1 => '/^Automatic answer$/i',
                          2 => '/^Réponse automatique:/',
                        ),
 
        ),

array (
  0 => '/^le .+ a écrit :$/i',
  1 => '/^on .+ wrote:$/i',
  2 => '|^[0-9]{4}/[0-9]{1,2}/[0-9]{1,2} .+:$|', 
)

array (
  0 => '/\\RFrom: .+\\RSent: .+\\R/m',
  1 => '/\\R_+\\R/m',
  2 => '/\\RDe : .+\\R\\R?Envoyé : /m',
  3 => '/\\RDe : .+\\RDate d\'envoi : .+\\R/m',
  4 => '/\\R-----Message d\'origine-----\\R/m',
  5 => '/\\RExpéditeur: .+\\RDate:/m',
  6 => '/\\RDe : .+\\RDate : /m',
  7 => '/\\TO:.+\\RCC:/m',
)

        'itop-standard-email-synchro' => array (
                'ticket_log' => array (
                          'UserRequest' => 'public_log',
                          'Incident' => 'public_log',
                        ),
        ),

array (
  'ticket_log' => array (
    'UserRequest' => 'public_log',
    'Incident' => 'public_log',
  ),
)

Once the Mail Inbox object has been created, you can use the tab “Mailbox Content” in the details of the object to check that the application can properly connect to the mail server and retrieve messages from it.

This view also allows to perform two different kind of actions on a set of messages:

• “Reset Status”: for messages which are either flagged as “Error” or “Already processed”, this status will be reset and the email will considered again as “New” and thus candidate for processing the next time cron.php runs.
• “Delete eMail”: deletes the message(s) from the mailbox. No confirmation will be asked !!

Since the processing of the incoming emails occurs in the background, it is not always easy to understand what happens when a ticket is not processed as expected. In order to trace the execution of this background task, several levels of tracing are available:

• by setting the “Debug trace” field to “Yes”, more trace will be generated when processing the mailbox. This trace goes to the output of the cron job, and is also captured (limited to 256 KB) in the database. This captured trace is visible in the “Debug Trace” tab of the Mail Inbox object.
• the configuration setting debug for the module combodo-email-synchro can be set to true in the configuration file. This activates even more traces for all the configured mail inboxes. This additional trace appears only in the output of the cron job.
• the cron job can be passed the optional parameter --verbose=1 to activate some debug trace for all the background tasks. This additional trace also goes into the output of the cron job.

If the cron job is not already running in the background it is convenient to run it manually from the command line, to see what's happening:

  php cron.php --auth_user=<user> --auth_pwd=<pwd> --verbose=1