Plugin-Dokumentation - IMAP-Plugin 

Page / - last modified by gru on 29.01.2021, 16:51 

IMAP-Plugin 
last modified by gru
on 29.01.2021, 16:51

Table of Contents
Features
Installation
Plugin configuration . It contains settings for the email server connection and lets you define how the emails should look like.
Configuration of the mail servers
Configuration of the mail messages
Configuration of the synchronization
Configuration of the cache
Email contents and fields
Email client configuration
Example configuration for Thunderbird
Version history

Plugin-Download (requires login)
Content [ Hide ] 
•	Features
•	Installation
•	Plugin configuration . It contains settings for the email server connection and lets you define how the emails should look like.
•	Configuration of the mail servers
•	Configuration of the mail messages
•	Configuration of the synchronization
•	Configuration of the cache
•	Email contents and fields
•	Email client configuration
•	Example configuration for Thunderbird
•	Version history
The Imap plug-in for Xima® Formcycle lets you view the data submitted forms in your email client. This way you are notified of new submissions immediately. You can also move form records to different inboxes or delete them. This plugin is subject to additional charge.
Technically speaking, this plugin provides an Imap and Smtp server to which most common email client can connect.
Features
Immediate notification
Immediately notifies users about newly submitted forms via the Imap protocol
Configurable content
The content of the notifications as well as the subject, sender and recipient can be configured freely using corresponding templates. You can also use variables and insert links to the submitted form and values from the submitted form.
Users can upload files in the form, and backend users can also attach files in the inbox. These files are attached automatically to the email message, so that you can open them in your email client. Starting from version version major="2" minor="1"/ it is alternatively also possible to define limits, starting from which files should only be listed in an attached text file.
Mapped inboxes 
All inboxes to which you have access are created in your email client. In addition, the folder Inbox always points to the default inbox and contains all available form records.
Manage form entries
Other than just viewing submitted forms, you can also perform several actions such as moving form records to different inboxes. When you have read an email, the form record in the Xima® Formcycle inbox is also marked as read; and when you delete an email by moving it to the trash, the form record is deleted as well. Please note that when you lack permission to do so, the deleted email will reappear in the inbox.
The provided Smtp server is a stub, and messages send to it are discarded and not processed any further.
Installation
Install the plugin as a system plugin in the backend. Please note that the initial installation may take up to several minutes, depending on the number of form records, as they need to be prepared for the Imap server.
The Imap plugin does not consider the client scope where it is installed when logging in and delivering messages. It is always available to all users. Therefore it is recommended to install the plugin as a system plugin. This also avoids possible issues with duplicate ports and allows for the plugon to be configured centrally.
Plugin configuration . It contains settings for the email server connection and lets you define how the emails should look like.
 
The configuration page of the plugin
After installing the plugin, the configuration parameters shown in the figure are available. The following configuration options are possible:
Configuration of the mail servers

smtp.binding.address
Default: 0.0.0.0. Specifies the ip address of the Smtp server to use. The default value is 0.0.0.0, which attempts to detect the ip automatically. Changing this value is only necessary if multiple network adapters are in use or if the automatic detection fails.
smtp.binding.port
Default: 25. Specifies the port of the Smtp server to use. The default value should only be changed if the default port is not available.
imap.binding.address
Default: 0.0.0.0. Specifies the ip address to use for the Imap server. The default value is 0.0.0.0, which also uses an automatically detected ip. Changing this value is only necessary if multiple network adapters are in use or the automatic detection fails.
imap.binding.port
Default: 143. Specifies the port of the Imap server to use. The default value should only be changed if the default port is not available.
imap.batch.size (starting from 2.1.0+ )
Default: 50. Specifies the number of messages to be delivered simultaneously. A lower value will reduces the memory usage but also the performance.
Configuration of the mail messages

mail.to.template
Default: mail_to.txt. Specifies the name of a client or form file to be used as a template for the email recipient.
mail.from.template
Default: mail_from.txt. Specifies the name of a client or form file to be used as a template for the email sender.
mail.subject.template
Default: mail_subject.txt. Specifies the name of a client or form file to be used as a template for the email subject.
mail.body.template
Default: mail_body.txt. Specifies the name of a client or form file to be used as a template for the email content.
mail.attachment.limit (starting from  2.1.0+ )
Default: 10. Maximum size of a file (in MB) above which it should not be attached, but listed in a text file (-1 = deactivated, 0 = lists all attachments).
mail.attachment.sum.limit (starting from  2.1.0+ )
Default: -1. Maximum sum of all file sizes (in MB) above which they should not be attached but listed in a text file (-1 = deactivated, 0 = always list all attachments).
Configuration of the synchronization
sync.max.threads (starting from 2.1.0+ )
Default: 4. Number of threads with which the synchronization of messages should be performed.
sync.page.size (starting from 2.1.0+ )
Default: 50. Number of messages with which a thread should perform the synchronization.
Configuration of the cache
cache.heap.size (starting from 2.1.0+ )
Default: 200. Size of the RAM to be used in M.
cache.disk.size (starting from 2.1.0+ )
Default: 500. Size of the hard drive memory to be used in MB.
cache.tti (starting from 2.1.0+ )
Default: 900. Maximum age of a cache entry in seconds.
Email contents and fields
A template mechanism is used for the configuration of the content and fields of the email message that is sent.
The templates are specified by the email message configuration. When an email is sent, the plugin first looks for a template in the form files of the current form, and if none is found, it looks for a template in the client files. This lets you create global templates as client files and override them for specific forms, if neccessary.
You can use variables in all templates, such as when you want to insert data from the submitted form and would like to include a link to the form record.
The following templates can be configured:
Content
Default value: mail_body.txt. Specifies the content of the email message. This template allows you to use Html For example:
<html>
 <head></head>
 <body>
  <p><a href="[%$FORM_INBOX_LINK%]">Link</a> to form entry ([%$PROCESS_ID%]).</p>
 </body>
</html>
Subject
Default value: mail_subject.txt. Specifies the subject of the message and must not contain Html. For example:
 ID: [%$RECORD_ID%] - [%$STATUS_NAME%] 
Recipient
Default value: mail_to.txt. Specifies the recipient of the message and must not contain Html. This is to be entered according to the pattern name <user@example.com> and has no effect on the actual receipt of the message. Example:
  XIMA FORMCYCLE <no-reply@example.com>
Sender
Default value: mail_from.txt. Specifies the sender of the message and must not contain Html. You need to enter the sender using the pattern Name <user@example.com>. The sender has no effect on how the message is sent. Example:
  [%$PROJECT_NAME%] <[%$PROJECT_NAME%]@example.com>
Email client configuration
Use the the address and port of the email server, as configured in the plugin configuration must be used. Below you can find a list of all settings:
Smtp server
<server address>
Smtp port
see email server service configuration
Imap server
<server address>
Imap port
see email server service configuration
Username
<FORMCYCLE-user>@<FORMCYCLE-clientname>
Password
<FORMCYCLE-user-password>
Authentication
Normal password
SSL encryption and connection security
None
Example configuration for Thunderbird
 1.	Open the email account management via Preferences > Account Settings.
 
 2.	Click on Account Actions > Add Mail Account... to open the dialog for adding a new account.

 3.	Initially, Thunderbird tries to determine the email server automatically based on the entered email address (here user@imap.com). Since this is not possible here, you can cancel that attempt by clicking on the Manual config button.

 4.	Fill out the email server settings. See above for what you should enter in each field. In the example, the client name is imap.com and the user name user and the standard ports are used.

 5.	After you complete the configuration, the user's mailboxes now appear as folders (here central mailbox and demo mailbox) and contain the messages of the existing form records.
 
Version history
Version 2.1.0
•	Switching to Xima® Formcycle version 6.5.5
•	Updated the used libraries
•	Optimization of memory consumption and database queries
•	Integration of a cache for the header and body of messages
•	Correction of errors when reading the IMAP BODYSTRUCTURE
•	Reintegration of the configuration of the attachment limits
•	Extension of the configurability of IMAP batch size and synchronization
Version 2.0.0
•	Modifications for compatibility with Xima® Formcycle version 6.0.2
Version 1.0.1
•	Optimizations and extensions of the configurability
Version 1.0.0
•	Initial release