2.06. E-mail Services

General Presentation

SocrateCloud Email Services were created with the purpose of centralising and controlling emailing within the system. To activate this feature you need the SocrateCloud Email Service component.

The service structure contains a public component (core-framework) and a private component (SEMS). The public component contains the email engine, while the private component contains specific email service implementations. Given this structure, in future versions, further SocrateCloud components may be added, containing specific implementations for the email service.

The main functionality has not been changed, so that, if no settings are made, emails will be sent as before, using the tenant email settings. The only exceptions is that emails go through the SocrateCloud Email service and they are stored a new location in the database, in a new format.

The component architecture is illustrated in the diagram below. Depending on the email service settings made, the corresponding implementation is used:

User Interface - Email Services setup

To configure and activate a specific email service you need the following:

• email service types and an active service (default) - these are predefined by BIT Software. The system administrator can decide upon a service to activate. Attention: the settings are made at system level, so they will be available for all tenants;

• specific settings (optional) at tenant level.

Setup

• install the SEMS component;

• log in with a system role and open the Email Services window. Select an Email Service Type and enter the respective settings. For example, the picture below contains settings for a Gmail account, which requires only a username and password (Email Services window -> Settings tab);

• in order to use the service it needs to be checked as Active and Default;

• after saving the record, (master data and details) run the Cache Reset Client + Server process;

Settings used for sending emails

• settings made at tennant level will be used, from the Tenant window (default service implementation) if:

  • if the SEMS component is not installed;

  • if the SEMS component is installed and nothing is configured;

  • if the SEMS component is installed, services are added, but none are checked as default.

• if a standard SocrateOpen email service is defined and checked as default, the settings defined at system level will be used for sending emails (for all tenants);

• if any other service type is defined (other than standard SocrateOpen), the settings made will be used, independent of settings made at tennant or system level;

• if an email is sent on behalf of a user (by specific processes) then, the settings made at tennant level will be used, in addition to user settings (email account and password in the User window)

Notes

• you cannot set email services at tennant level;

• only a single setting made at tennant level is always used for sending emails: Reply To EMail - the address to which emails are replied to;

Send Email Workflow

• for the first email service request (using the Java class: org.bitsoftware.sems.SCEEmailService) or at cache reset, the specified implementation is loaded to the email service settings;

• if no settings are made, the default implementation is loaded, using the email settings made at tennant level;

• when loading a default email service, if any error is detected, the next email service is loaded automatically, using the sequence in which services were defined;

• an error free service will be used for email sending until the next cache reset;

• the email service can create an email (an instance of the org.compiere.util.EMail class) which is sent automatically or can be sent later;

• when sending an email, it is saved in the database table SEMS_Message (corresponding window is displayed below);

• if an email is not sent successfully, a retry will be attempted by the email processor (corresponding window and description displayed below);

Email Processor

This is standard and is used for all tenants. Email messages assigned to the processor queue, one by one;

Working order:

• queries the SEMS_Message table for active email messages which have not been sent and are not being sent;

• creates and email message using the current email service implementation (can be different from the initial implementation) using information from the database;

• if successful the email message is marked as sent and the processor goes to the next message;

• if unsuccessful, the maximum retry attempt number is checked (can be set in the corresponding window, displayed below):

  • If the maximum number has been reached, the message is marked as inactive.

  • If not, the retry number is updated for the message, the error message is saved and the processor goes to the next message;

The processor functionality is illustrated in the diagram below:

General Rules

• email addresses to which emails are sent must be correct syntactically and must comply with the RFC 822 standard;

• if an email address is not correct, the email is not sent and an "INVALID_EMAIL" error message containing the address is returned;

• email addresses can be used only once (no duplications are accepted);

• an address cannot be simultaneously used for To and Cc (duplications are deleted);

• if no email address (recipient) is specified, a "NO_RECIPIENTS" error message is returned;

• if the email has a recipient, but the recipient user does not have an "Email" Notification Type, a "NO_RECIPIENTS" error message containing the the address is returned;

• specific processes can send emails for which the sender is the same as the recipient. For this email types, email settings made at tennant level and user authentication data are used;

• the Reply To address, set on the email template, is used only when requested by processes, using a schedule. By default this is the email address set at tennant level in the Reply to field.

User Interface - email management windows

Window: Email Service Type

• Component: SEMS;

• Access: System;

• In this window, Java classes which execute the email service implementation are defined. The classes must respect the Java Interface: org.bitsoftware.sems.SCEmailServiceIImplInterface.

Window: Email Services

• Component: SEMS;

• Access: System;

• In this window email services are defined. You can define multiple email services, but only the default one is loaded.

• Only one record can be Active and Default;

• For the standard SocrateOpen service, the settings made at system level are used;

• The window below illustrates specific settings, based on the service chosen:

Window: Email Messages

• Component: SEMS;

• Access: System;

  • if the email would have been sent to Cc or Bcc recipients the corresponding fields (which are currently hidden in the pictures below) would have appeared;

  • if multiple recipients are assigned, their corresponding email addresses will be displayed in the To, Cc or Bcc fields;

  • the To, Cc and Bcc fields are virtual columns. Information is taken from the corresponding tabs, which represent the link (many-to-many link) between users and the email message. In the secondary tabs you can view all the email addresses;

  • the Without User tab contains the email addresses to which the message was sent to and for which there is no SocrateCloud user;

  • in the Advanced section you can find information about the email service used for sending the email, the ID, the email template and the web module from which the email was sent;

• in the Status section you can view:

  • if the email is being sent;

  • if the email has been sent;

    • if an email has not been succesfully sent;

    • the number of retry attempts;

    • the last error message.

Two images are displayed below, one with the Advanced and Status sections hidden and another the all the sections expanded:

Extended version:

Window: Email Messages (queue)

• Component: SEMS;

• Access: System+Tennant (at tennant level you cannot see system messages);

• The window has the same format as the Email Messages window with the exception that it displays only messages which have not been sent, and are due to be sent (active);

• This is the case for messages currently being sent or for messages that were unsuccessfully sent and retry attempts are still being made (according to the maximum number of attempts set at email processor level);

Window: Email Messages (no user)

• Component: SEMS;

• Access: System+Tennant (at tennant level you cannot see system messages);

• The window has the same format as the Email Messages window with the exception that it displays messages sent to email addresses not assigned to a SocrateCloud user

Window: Email Messages (unsent)

• Component: SEMS;

• Access: System+Tennant (at tennant level you cannot see system messages);

  • The window has the same format as the Email Messages window with the exception that it displays messages which have not been sent and no further attempts are possible (maximum number of attempts has been reached and the message is marked as inactive)

Window: Email Service Processor

• Component: SEMS;

• Access: System;

  • In this window you can make settings to the email processor. The processor queries email messages stored in the database which are active, have not been sent or are being sent. In the window you can set the maximum number of attempts when sending an email and the running frequency.

Window: Tennant

The Reply To EMail field has been added to the Request Management section in the Tennant window, where you can to specify a reply address when making system email service configurations:

Window: Utilizatori

• Component: Dictionary;

• Access: System+Tenant;

• In the User window, Email Messages tab you can see all the recipients (maximum 10 per group) for an email message, except for the ones entered as BC.

Process: Email Service Test

• Component: Dictionary;

• Access: System+Tenant;

• The process is used to send an email with the email service settings to a specific address (as illustrated in the image below).

Email example, sent by the process: