# Plugin EmailS

## About

The plugin allows to organize corporate Email exchange by separation incoming customers' messages over multiple processes for dedicated executors. After the primary separation the information exchange with the customers happens for the executers inside that processes.

As an additional feature, the plugin provides Email notifications about process' changes for its executors.

## Setup

Make sure the plugin is enabled and append to the configuration:

# areas to search recipient’s addresses in message editor, other possible values: users
#email:recipients.search.area=process,executors,process_customers

### Message Type

Configure a message type for every mailbox, is going to be connected to the system:

    messageType.<ID>.title=<TITLE>
    messageType.<ID>.class=MessageTypeEmail
    messageType.<ID>.email=<EMAIL>
    messageType.<ID>.pswd=<IMAP_PASSWORD>
    messageType.<ID>.host=<IMAP_HOST>
    messageType.<ID>.mail.smtp.host=<SMTP_HOST>

    # optional
    # IMAP without SSL
    #messageType.<ID>.store=imap
    # IMAP port instead of 993 for IMAP SSL and 143 for IMAP without SSL
    #messageType.<ID>.port=993
    # IMAP login
    #messageType.<ID>.login=<EMAIL>
    # IMAP folder for incoming messages
    #messageType.<ID>.folderIn=INBOX
    # IMAP folder for processed messages
    #messageType.<ID>.folderProcessed=CRM_PROCESSED
    # IMAP folder for skipped with parsing error messages
    #messageType.<ID>.folderSkipped=CRM_SKIPPED
    # IMAP folder for moving sent messages in
    #messageType.<ID>.folderSent=CRM_SENT
    # IMAP folder for moving deleted messages in
    #messageType.<ID>.folderTrash=Trash

    # SMTP without SSL
    #messageType.<ID>.mail.transport.protocol=smtp
    # SMTP port instead of 465 for SMTP SSL and 25 for SMTP without SSL
    #messageType.<ID>.mail.smtp.port=465
    # SMTP login
    #messageType.<ID>.mail.smtp.user=<EMAIL>
    # SMTP password
    messageType.<ID>.mail.smtp.pswd=<IMAP_PASSWORD>

    # debug IMAP and SMTP exchange
    #messageType.<ID>.debug=1

    # do not inform about new unprocessed messages of the type
    #messageType.<ID>.unprocessedMessageNotify=0
    # leave processed messages unread
    #messageType.<ID>.processed.read=0

    # do not check empty subject on saving
    #messageType.<ID>.check.empty.subject=0
    # address From
    #messageType.<ID>.from=<EMAIL>
    # address Reply-To
    #messageType.<ID>.replayTo=<EMAIL>

    # disable default signature
    #messageType.<ID>.sign.standard=0
    # JEXL expression for generation signature text
    #messageType.<ID>.sign.expression=<SIGN_EXPRESSION>

<SIGN_EXPRESSION> - JEXL expression for building signature, context variables:

- user - object of class ru.bgcrm.model.user.User, the current user;

- message - object of class org.bgerp.model.msg.Message, the message;

See configuration examples for different Email providers below.

#### Examples

##### Zoho Mail EU

Log to the account on https://mail.zoho.eu in, click Setting on the top right corner, and enable IMAP access there.

    messageType.100.title==account@domain.com
    messageType.100.class=MessageTypeEmail
    messageType.100.email=account@domain.com
    messageType.100.host=imappro.zoho.eu
    messageType.100.pswd=*****
    messageType.100.mail.smtp.host=smtppro.zoho.eu

##### Yandex

    messageType.100.title=account@domain.com
    messageType.100.class=MessageTypeEmail
    messageType.100.email=account@domain.com
    messageType.100.host=imap.yandex.com
    messageType.100.pswd=*****
    messageType.100.folderTrash=trash
    messageType.100.mail.smtp.host=smtp.yandex.com

##### GMail

| Obtaining regular IMAP/SMTP access for an GMail account might be especially tricky because of constantly changed Google security policy

    messageType.100.title=account@gmail.com
    messageType.100.class=MessageTypeEmail
    messageType.100.email=account@gmail.com
    messageType.100.host=imap.gmail.com
    messageType.100.pswd=*****
    messageType.100.folderProcessed=INBOX.CRM_PROCESSED
    messageType.100.folderSkipped=INBOX.CRM_SKIPPED
    messageType.100.folderSent=INBOX.CRM_SENT
    messageType.100.folderTrash=[Gmail]/Bin
    messageType.100.mail.smtp.host=smtp.gmail.com

#### Search Mode <CLASS> MessageTypeSearchEmail

Automatically running search mode for MessageTypeEmail. Finds customers by all their email parameters containing address from or its domain of a processed message.

Example:

    messageType.100.search.{@inc:cnt}.title=Customer by EMail
    messageType.100.search.{@cnt}.class=MessageTypeSearchEmail

#### Contact Saver <CLASS> MessageTypeContactSaverEmail

The contact saver for MessageTypeEmail stores a sender’s email to a linked customer param.

Configuration:

    messageType.<ID>.saver.class=MessageTypeContactSaverEmail
    messageType.<ID>.saver.paramId=<PARAM_ID>

Where:

- <PARAM_ID> - the customer email parameter ID

Example:

    messageType.100.saver.class=MessageTypeContactSaverEmail
    messageType.100.saver.paramId=27

#### Quick Answer

Received process change notifications might be directly replied with assigning that responses to the process. This feature can be enabled for the Email message type with <EMAIL> equals to the one used for app’s outgoing messages, including the notifications. Append to the message type’s configuration:

    messageType.<ID>.quickAnswerEmailParamId=<USER_EMAIL_PARAM_ID>

Where <USER_EMAIL_PARAM_ID> - ID of user parameter type email, used for identification of process executor.

Once the feature is enabled, process change notification mails will become subject suffix QA:<MESSAGE_ID>, preserved in reply subject. The <MESSAGE_ID> in a subject allows to identify the message and process for an incoming reply email. The message ID is taken from the message type, by <USER_EMAIL_PARAM_ID> found a process executor, who has replied and therefore shouldn’t be notified again about the new incoming message in the process.

#### Automatic Process Creation

For creation new processes out of all the newly incoming messages for a type, append to its configuration:

    messageType.<ID>.autoCreateProcess.typeId=<PROCESS_TYPE_ID>
    # optional
    #messageType.<ID>.autoCreateProcess.notification=1
    #messageType.<ID>.autoCreateProcess.notification.text.message=Dear customer, your request has been registered

Where <PROCESS_TYPE_ID> - ID of the required process type

#### Debug

After configuration a new email message type, open Messages tool and try to retrieve new messages from the email box. If the messages do not appear there, see logs for the reason.

For testing email sending add a process message and execute the <<scheduler task.

### Process Type

#### Process Change Notifications

Plugin can send Email notifications about process related updates:

- changes of process status or executors list;

- new incoming process messages, notification email subject contains in this case Quick Answer identifier;

- paid process invoices.

These mails are sent to process executor users, excluding ones, performed the update.

The feature can be enabled in process type configuration:

    email:change.notification.user.email.param=<PARAM_ID>

Where <PARAM_ID> can be 0 for selecting first user parameter with type email or point to a definite user param ID.

Links for opening processes are built from configuration parameters.

#### Sending Mails from JEXL

Email can be sent using simple processor, here is the sample of configuration.

    onProcessEvent.{@inc:cnt}.events=statusChanged
    onProcessEvent.{@cnt}.doExpression=<<END
        text = process.getDescription();
        email.sendMessageToUsers({1}, 0, "Changed process status", text);
    END

Object email of class org.bgerp.plugin.msg.email.ExpressionObject with API methods is provided by the plugin.

## Usage

### Messages

Newly incoming email messages have to be processed in Messages tool, where they are separated over processes or being deleted.

Process for a processed message can be opened by the link.

### Process

After the first process assignment, process-related message exchange happens in Messages tab.

That message can be replied.

Or you can create a new process email.

In any of these cases, an email sent from here will contain marker with process ID in its subject, that allows automatically assign all new customer’s replies to the same process.

#### Search Recipients

| The feature has a separated permission Plugin Email / Search Recipients.

During message editing recipient addresses might be chooses over parameter values with type email.

Areas where recipients are searched are defined in configuration. Possible values:

- process - current process;

- executors - current process executors;

- process_customers - customers, linked to current process;

- users - all the users in the system.

#### Attach History

In drop-down Attach history may be chosen the following options:

- Exchange with the address;

- All messages.

For both modes for each sent message has attached a file named `History.txt`, containing exchange with:

- used Email address

- all message history for second case

For the second mode in message signature also added process link to open interface, case it is configured.