# MessagesS

## About

Messages are needed to store and organize process-related information exchange between among executors and customers: notes, calls, emails.. So that all the history of communications around a process is always available there.

## Setup

Following settings should be done in the configuration, preferably as an include.

### Types

Any message has a type that should be added with the records:

    messageType.<ID>.title=<TITLE>
    messageType.<ID>.class=<CLASS>

Где:

- <ID> - unique numeric positive ID, must not change after; there are some recommended values provided for each class;

- <TITLE> - type’s title;

- <CLASS> - the class of the message type.

The following <CLASS> values are supported in the app’s kernel.

#### MessageTypeNote

Used for appending process notes. Recommended <ID> is 1

Optional config:

    # create notes in unread state
    #messageType.<ID>.create.unread=1
    # do not check empty subject on saving
    #messageType.<ID>.check.empty.subject=0

Example:

    messageType.1.title=Note
    messageType.1.class=MessageTypeNote

#### MessageTypeCall

The only single possible message type with the <CLASS> recommended to have <ID> is 50 Notifications about calls itself should be provided by Asterisk plugin or external HTTP requests.

Optional config:

    messageType.<ID>.offerNumberFromParamId=<OFFER_NUMBER_FROM_PARAM_ID>
    # disable automatic registering number from <OFFER_NUMBER_FROM_PARAM_ID> parameter on user login
    #messageType.<ID>.autoNumberRegister=0

Where:

- <OFFER_NUMBER_FROM_PARAM_ID> - ID of user text parameter, containing his number.

That number has been occupied by a user during message processing.

#### Message Type <CLASS> in plugins

<CLASS> | Plugin | Recommended values of <ID>
--- | --- | ---
MessageTypeEmail | Email | 100-199
MessageTypeHelpDesk | BGBilling | 200-249

#### Search Modes

The search modes are used to search objects during message processing, those will be linked to a created process.

Search mode added to a message type with configuration:

    messageType.<ID>.search.{@inc:cnt}.title=<TITLE>
    messageType.<ID>.search.{@cnt}.class=<CLASS>

Where:

- <TITLE> - the mode’s title, shown in drop-down;

- <CLASS> - the class, implementing its logic, can be one of the following values:

##### MessageTypeSearchCustomerByTitle

Can be used for any message type, provides search customer by title.

Example:

    messageType.50.search.{@inc:cnt}.title=Customer by Title
    messageType.50.search.{@cnt}.class=MessageTypeSearchCustomerByTitle

##### MessageTypeSearchCall

Automatically running search mode by calling number of MessageTypeCall

Configuration:

    messageType.<ID>.search.{@cnt}.commands=<COMMANDS>
    # optional
    messageType.<ID>.search.{@cnt}.expressionNumberPreprocess=<JEXL>

Where:

- <COMMANDS> - semicolon-separated command, defining searched objects, possible values:

  - customerByPhoneParam:<PARAM_IDS> - search customers by comma-separated parameters <PARAM_IDS> with type phone;

- <JEXL> - JEXL expression for pre-processing the calling number, passed in numberFrom variable.

Example:

    messageType.50.search.{@inc:cnt}.title=Customer by Phone
    messageType.50.search.{@cnt}.class=MessageTypeSearchCall
    # search customers by phone parameter with ID=10
    messageType.50.search.{@cnt}.commands=customerByPhoneParam:10
    # if numberFrom has 11 digits length than cut the first symbol of if off
    messageType.50.search.{@cnt}.expressionNumberPreprocess=if (numberFrom.length() == 11) { numberFrom = numberFrom.substring(1) }; return numberFrom;

##### Search Mode <CLASS> in plugins

<CLASS> | Plugin | Description
--- | --- | ---
MessageTypeSearchEmail | Email | Search customers by sender email
BGBillingMessageTypeSearchContractByTitleAndComment | BGBilling | Поиск договоров по номеру и примечанию
BGBillingMessageTypeSearchCall | BGBilling | Поиск договоров по номеру звонящего в MessageTypeCall
BGBillingMessageTypeSearchEmail | BGBilling | Поиск договоров по адресу отправителя email MessageTypeEmail

#### Contact Saver

Contact saver allows to store in the system a message’s address, like calling phone number or sender’s email.

Configuration:

    messageType.<ID>.saver.class=<CLASS>

Where <CLASS> can take the following values:

##### MessageTypeContactSaverPhone

Save the calling phone number of MessageTypeCall to parameter with type phone of process or a linked customer

Configuration:

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

Where:

- <PARAM_ID> - the parameter ID type phone

Example:

    messageType.50.saver.class=MessageTypeContactSaverPhone
    messageType.50.saver.paramId=37

##### Contact Saver <CLASS> in plugins

<CLASS> | Plugin | Description
--- | --- | ---
MessageTypeContactSaverEmail | Email | Stores sender email to customer parameter
BGBillingMessageTypeContactSaverPhone | BGBilling | Сохраняет номер звонящего в параметр договора биллинга

### Tags

Colored message tags allow to separate messages in process tab. Example of configuration:

    tag.1.title=Access
    tag.1.color=red
    tag.2.title=Requirements
    tag.2.color=green
    tag.3.title=TODO
    tag.3.color=magenta

### Templates

Message Templates allow to create pre-defined subject and text content, to begin typical messages.

To add a template, add the following configuration block.

    message.template.{@inc:cnt}.title=<TITLE>
    message.template.{@cnt}.subject=<subject>
    message.template.{@cnt}.text=<text>

All the values are self-explainable, here is the sample of configured template.

    // PzdcDoc snippet of: 'MessageTest.config.txt', lines: 33 - 39

    message.template.{@inc:cnt}.title=Greetings from BGERP
    message.template.{@cnt}.subject=Hello from BGERP
    message.template.{@cnt}.text=<<END
    Dear Friend,

    the Team BGERP wishes you all the best!
    END

And how does it look like.

### Possible Processes

| You can see (message Kernel Message Possible Process Unprocessed message) the feature operation in Demo System. The configuration for that has the name Kernel Message Possible Process.

To configure Possible Processes to be found during message processing add to configuration following blocks:

    message.possible.process.<ID>.class=<CLASS>
    message.possible.process.<ID>.color=<color>

Where:

- <ID> - unique block’s numeric ID, found processes are sorted by the IDs

- <color> - optional HTML color for table rows with found processes

- <CLASS> - search type, one of the following values:

  - MessagePossibleProcessSearchMessageFrom - processes with messages from the same from address (Email sender or calling number) as the processed message.

  - MessagePossibleProcessSearchFoundLinks - processes with the same links as found for the processed message.

  - MessagePossibleProcessSearchFoundLinksCustomerAddressCity - processes with a list parameter values, matching to city IDs of address parameter of found customers. That type requires additional properties set:

    - processCityParamId, ID of the list parameter.

  - BGBillingMessagePossibleProcessSearchFoundLinksContractAddressCity - processes with a list parameter values, matching to city IDs of address parameter of found contracts in BGBilling system. That type requires additional properties set:

    - processCityParamId, ID of the list parameter;

    - contractAddressParamId.<billingId>, ID of address parameter in BGBilling system with ID <billingId>.

| If no block is defined then a single ones with class MessagePossibleProcessSearchMessageFrom is added.

### Scheduler

Recieving new process messages and sending them does scheduler task Kernel Message Exchange. Optional task’s configuration:

- messageTypeIds - comma-separated message type IDs for only those the exchange must be executed.

## Usage

### Messages

The Messages tool is used to process incoming messages, that means relating them to appropriate processes. Not all the supported message types require processing, currently it is used for emails and Asterisk calls.

| Quantity of unprocessed messages has been shown in notifications.

To be processed a message it must be opened. For calls to an occupied number (333 on the screen) that happens automatically, after accepting the call. Emails have to be clicked in the table, found with .

The processing interface is shown under that. The right area of a processed message shows its type-depending content, here is the sample for a call.

In the left-top area can be created a new process for the message.

For the process must be defined a type from the tree, can be optionally linked found using search modes objects. After that can be defined process’s description and the creation has to be confirmed with the button below. The message contact (calling number or email) can be stored to a linked object using contact saver of the message type, if configured.

In the left-bottom area an existing process may be assigned to the message.

The possible processes are searched by:

- the same contact as the message has (calling number or email);

- having links to the same objects as found for the message;

- additionally configured possible processes.

At the end you have a field to select process directly by its ID. For a processed message the left part of the process card is shown on the left.

It can be opened completely by clicking on its ID (2001 for this case).

### Process

The process messages are shown in the Messages tab of a process card.

| The tab can be hidden in process type configuration.

Background color of message header depends on its type and direction (incoming/outgoing).

The messages can be filtered by containing attachments or tags.

There is a pinning functionality for messages, to keep them always on top.

On scrolling down the messages are expanded automatically to the full screen width for better readability of large texts.

Also for better readability long lines in messages can be wrapped or scrolled horizontally, that can be toggled in the message menu.

Some message types (note, email) support read/unread status, the last is shown with bold text in message header.

The unread messages counted differently and can be reflected in process queues. MIUC column on the screen below shows Message Incoming Unread Count.

Beside of assigning messages during processing an editable message can be directly added to a process with the creation button. The type has to be selected in the top-left drop-down, for text messages you can use configured templates with subject and text.

To reply a message use the dedicated button on the item in message menu. For this case a message type can’t be changed, the subject is copied from the original message and the text is prefixed as a citation.

Editable messages can be modified with the Edit operation in message menu, for some types this is possible only before message was sent (email) or read by client (BGBilling HelpDesk).

| Editing or deletion is allowed only for its author unless the special permission is granted.

As message attachments can be added files from your local disk, process parameters with type file or plugin-supported values (invoices). The needed option has to be selected in the drop-down and confirmed with the button next to it.

#### Change

Original message process can be changed to another existing or to a newly created one using the Change process to operation in message menu.

##### Another existing

The process can be selected over opened in objects buffer.

##### Independent copy of current

The new process is created as a copy of the current one, all the links are copied there too.

##### Dependent copy of current

The new process is created as a copy of the current one, and related to the current as processDepend.

##### Made copy of current

The new process is created as a copy of the current one, and related to the current as processMade.

##### Linked copy of current

The new process is created as a copy of the current one, and related to the current as processLink.