EntityStateMail handler generates the user interface for viewing and sending e-mail. Typically, EntityStateMail handler is used in help desk incident templates. The format of the mail may depend on a selected mail template. This makes it possible to send differently formatted mails depending on receiver.

Configuring of this handler is different from other handlers. Most settings are configured in a separate configuration view, which opens up from the button in the metadata editor. With this mail template configuration, you can specify information that the EntityStateMail handler includes in the message automatically when opening a new message for composition or when replying to a received message. You can define, for example, a default mail subject, as well as recipient and sender information. In addition, you can also denote attributes whose values you want to include from the parent data card in the mail.

The following picture displays the appearance of an attribute with EntityStateMail handler. The second picture illustrates an example of an e-mail message based on a mail template which includes information that is denoted in the attribute metadata.

An attribute with EntityStateMail handler:

E-mail generated with the EntityStateMail handler:

You can insert email recipient addresses by typing to the 'To' field. Addresses are fetched from data cards based on configurations in platform settings.

The following tables provide information on the attribute settings and metadata requirements for EntityStateMail handler. In addition, the table provides proposals for possible metadata values.

Table 1.  Attribute Settings

Table 2.  Optional Attribute Metadata

The following picture describes EntityStateMail handler's mail template configuration screen. (To get to this screen, select the metadata and click the Edit button):

In first row, you can select a mail template to be edited. If Mail templates attribute is in use, the name must match with the values of the attribute, which was defined in meta data named Mail templates attribute. For creating a new configuration, select an empty slot for name. Then give a name for configuration. Finally press Save. If you want to change the name of a configuration, first select the wanted configuration. After that, write a new name in the "rename" field. At last, save the configuration. Now you can configure the mail template.

Next you will configure the outlook of the outgoing mail. You can define values for following fields and selections:

• From (sender of the mail)
• From field editable (defines whether the contents of the From field can be edited when user is sending the message)
• To (receiver(s) of the mail)
• Cc (receiver(s) of a copy of the mail)
• Bcc (receiver(s) of a blind copy of the mail)
• Subject (title for the mail)
• Message (body contents of the mail)
• Attachment

You can choose attachments to be included in the outgoing mail. You can either upload a new file to be included, or add a reference to a file that has already been uploaded to Efecte. The reference has to contain a name of a file, that is located in the upload directory of Efecte.

• An example: add an attribute with FileUpload handler to the class holding the attribute with EntityStateMail handler. Set the attribute code to job_attachments. Now in EntityStateMail handlers special configuration screen add an attachment reference with value $job_attachments$ and click "Add reference". After this, when you create a new mail using the configuration, files found in the FileUpload handler created above will also be included in the mail as attachments.

Normally when you send an a-mail with attachments, the attached files are removed from the server as soon as the e-mail gets sent. With Uploaded attachments attribute meta data you can choose to save the attachments in an attribute of your choice.

• An example: add an attribute with FileUpload handler to the class holding the attribute with EntityStateMail handler. Set the attribute code for Uploaded attachments attribute to saved_attachments. After this, when you create a new mail using the configuration, files that you explicitly added to the mail will be stored as values of the attribute with code saved_attachments.

All the fields listed above may contain hard coded text and values of the attributes of the data card. The values of the data card is entered as $attribute_code$. The fields can also contain values, which are retrieved from the referred data card.

• An example: let's assume that the template contains field $client$. The template of $client$ contains field $email$. You can get the client's email by using value $client:email$. Or, if the $client$ template contains reference attribute $contact_user$, you can use value $client:contact_user:email$. 

If you need some values to be URL encoded, you may use $[URL]attribute_code$. In addition to URL encoding, it makes static values to be printed as ID-numbers of the selected value.

In the last row of configuration view, you can select which attribute is used as Tracking attribute. This attribute is used by MailTask to match incoming reply-mails to existing data cards. Then you can select, whether the original mail(s) is appended to reply. And with the last option you can select whether the outgoing mail format is plain text or html. If your mail template contains HTML tags, select "html". Otherwise select "plain".

When user is viewing an email potential html part is shown. If html part is not found plain text part will be displayed. Following table provides information about Platform Setting affecting the mail viewing.

Table 3.  Platform Settings

You can find data cards containing read or unread mails by using the Advanced search conditions. Add a search condition for attribute with the EntityStateMail handler and you see the options for filtering data cards based on read or unread mails.