E-Mail Send/Receive Application

The E-Mail Send/Receive application allows to send and receive e-mails.

You can perform following operations:

• Viewing and Editing Properties
  • Parameters
  • Response
  • Configuration
  • Test
  • Attachments
  • Comments

Viewing and Editing Properties

The following properties can be specified:

Figure: Properties - Script Invocation Application

• Application Name - Specify name of the application
• Description - Specify the description
• Public Visibility - By default, this check box is selected. It indicates that the element is visible and available for reference from any other model.

In case you switch to the Integrator profile, UUID and ID options are displayed additionally.

• UUID - A unique identifier ID gets generated as an identifier for client server communication
• ID - An ID generated automatically based on the application name. If element with the same name exists then during ID generation, a numerical suffix gets added to the ID. If the element is renamed, the ID gets regenerated.

Figure: UUID and UI Properties

Parameters

Predefined IN access points are created for to, from, cc, bcc and subject. You cannot create OUT access points. If IN data mappings are defined on predefined IN access points for meta-information, then at runtime available value overwrites the value defined in the UI. However, the OUT access point returnValue (String primitive) is created as soon as a response type is selected.

• Parameter Definition - To define input parameters, click the Add icon. The parameter gets added to parameter definition table.


Figure: Parameter Mapping

• Name - Specify name for the new parameter
• Direction - Select direction for the data from the Direction drop-down list. Following options are provided:
  • In - For read access. If IN data mappings defined on predefined IN access points for meta-information, then at runtime available value overwrites the value defined by the user.
• Data Type - Following data types are supported:
  • Primitive - If you select Primitive data type, you need to provide Primitive Type.

  
  Figure: Primitive Data

  • Structured Data - If you select structured data, you need to provide Structure Type. It also lists structured types from other models.

  
  Figure: Structured Data

  • Document Data - If you select document data, you need to provide Document Type. In the runtime, the user needs to select a document that will be added as an email attachment.

  
  Figure: Document Data

  Note: It is recommended to use small documents, because big files may cause memory issue and could be rejected by email server.

Accessing the parameters in data flows

The default and added parameters can be set as input access points in data flow to the E-Mail application.

Figure: Mail Application access points

Response

The http response type is supported which allows correlating back process data information via MailReceptionServlet. The http response type requires a server base URL. For example, http://myippruntime/mycontextroot. The E-Mail Overlay is implemented as asynchronous Camel application type if a response type is selected.

Figure: Response

The http response type requires an Enumeration type (SDT of type Enumeration) where each element in the Enumeration becomes a link in the email (e.g. Approve, Rejected, etc).

Figure: Response

Configuration

You can use configuration variables for user and password.

Figure: Configuration

• Mail Server - the mail server to be used to send the mail.
• Subject - Specify the subject for email.
  • Templating language could be used here (i.e. Meeting with {{Customer.fullName}}).
  • The Templating syntax works on access point IDs (i.e. Customer is an input access point (SDT) defined in the Parameters tab).
  • In Templating language, variables look like this: {{ variable }}.
  • Use a dot (.) to access attributes of a variable (access point). For example, {{Customer.fullName}} will be replaced with the fullName attribute of the Customer SDT access point.
  • If the "subject" access point is mapped to a data flow and templating syntax is used in the "Subject" field, the value provided from the access point mapping takes precedence.
  • This is applicable to the others fields too (From, To, CC, BCC and Embedded Email body).
• From - Specify the sender mail address. Templating language could be used.
• To - Specify the receiver mail address. Templating language could be used. Separate multiple addresses with a comma.
• CC - Specify the email address. Templating language could be used. Separate multiple addresses with a comma.
• BCC - Specify the email address. Templating language could be used. Separate multiple addresses with a comma.
• Format - Specify the format in which you want to send an email. By default, Text format is selected. You can also select HTTP format from the drop-down list.
• Include Unique Identifier in Subject - If selected, the details (like process and activity OIDs and activity name) are added to Subject line.
• User - Specify the user name.
• Password - Specify the password.
• Transacted - If selected transacted mode for sending e-mails will be used.
• Auto Startup - Specifies whether to auto startup the Camel route for this application.
• Attach E-mail to process - attach the e-mail to process.
• Store E-mail attachments - store the e-mail attachments in the documents repository.
• Template Source - Specify the source where the template is located. You can choose one of the following options:
  • Embedded - template detail to be defined in the input box below
  • Document Repository - The template file will be retrieved from the document repository (i.e. under Root\artifacts\templates folder).
  • Classpath - template file is located in the class path (for example under ipp-portal\WEB-INF\classes).
  • Data - template file is derived from process data of type document and defined as IN access point

The e-mail editor is provided to format and write email contents. You can format an email using the following icons:

Icon	Function	Description
	Source	Displays source of the content
	Cut	Using this icon you can move the content. It is enabled when some text is selected in the editor.
	Copy	Using this icon you can copy the cut or selected content in the editor. It is enabled when some text is selected.
	Paste	Using this icon you can paste the copied or cut content in the editor.
	Paste as Plain Text	Using this icon you can paste the copied content as plain text.
	Paste from Word	Using this icon you can paste the copied content from Microsoft Word.
	Undo/Redo	Using this icon you can undo or redo the most recent action taken.
	Spell-check	Enables you to check the spellings in the content.
	Bold, Italic and Strike through	Applies bold, italic and strike through formatting to selected text.
	Insert/Remove Numbered List	Inserts or removes numbered list
	Insert/Remove Bulleted List	Inserts or removes bulleted list
	Increase or Decrease Indent	Increases or decreases the text indentation.
	Block Quote	Format a block of text to identify quotations.
	Link, Unlink and Anchor	Adds link to the selected text or unlink the linked text or provide anchor for the text.
	Image	Inserts an image at specified location.
	Table	Inserts a table at specified location.
	Horizontal Line	Inserts horizontal line at specified location.
	Special Character	Inserts special characters at specified location.
	Styles	Enables you to specify styles for the content.
	Normal	Enables you to format paragraph of the content.
	Maximize	Increases the size of the editor.
	About CKEditor	Displays information about editor.

Test

You can test the application in this tab. Click Reset to initialize the input data and then click Run. You can view the email content to be sent. If you have provided response type as HTTP then the data values provided in the enumeration type are displayed as links.

Figure: Test

Attachments

You can add customized templates for attachments. The templates source could be:

• Data - attachment details defined in a Structured Data at runtime
• Embedded - attachment defined in this tab.
• Document Request - attachment defined in the "Document Request" IN Access Point.

For the embedded attachments, the details below should be defined.

• Template - Check-box that defines if the current attachment is a template or already the actual document.
• Name - The name specified will become the name of the output document.
• Source - Specify the source where the template file is located. You can choose one of the following options:
  • Document Repository - The template file will be retrieved from the document repository.
  • Classpath - template file is located in the class path (for example under ipp-portal\WEB-INF\classes).
  • Data - template file is derived from process data of type document and defined as IN access point
• Path - Specify the path of attachment template file.
  • For template files located in the Document Repository, the path can be relative or absolute.
    • Relative path - If you specify a relative path, the template will be looked up at Root/artifacts/templates (example of relative path : WeeklyMeeting.docx).
      You can add templates in sub folders under Root/artifacts/templates. (example of relative paths to sub folders : reports/AdminReport.docx, the template will be looked up at Root/attachments/templates/reports/AdminReport.docx).
    • Absolute path - If you specify an absolute path, it will be applied to Root folder (example of absolute path : /attachments/templates/ClientDetails.docx, the template will be looked up at Root/attachments/templates/ClientDetails.docx).
  • For template files located in the Classpath - the template will be looked up at the class path for example under ipp-portal\WEB-INF\classes.
  • For template files having Source as Data, the Path will be empty.
• Format - Specify if the attachment file will be converted to PDF file or not.
  • PDF - The attachment will be converted to a PDF file.
  • Plain - No conversion will be done on the attachment.

Figure: Attachment templates configuration

Figure: Document repository

More details about template creation are described here.

Load template location dynamically

In many situations, the end user would like to specify the attachments and the templates dynamically at runtime.

The following model shows how to do that. It has a manual activity where a "Person" details and "Template configuration" are entered. In the second activity, an email application is invoked using the entered data.

Figure: Dynamic email attachments model

Below the main steps to create the model.

• Create a SDT for the template configuration as follow:


Figure: Template configuration structured data

The SDT is a list of attachments with the attributes below:

• tTemplate: Boolean value to indicate if the attachement is a template or not.
• tName: Template Output Name
• tPath: Template Path (filename)
• tFormat: Template format (pdf or plain for text, html or xml format.)
• tSource: Template source (Repository, ClassPath).
• Create and configure an email application.
• Set the template source as "Data" and select the "templateConfiguration" SDT variable in the Attachments tab.


Figure: Dynamic Template Attachments

• The "templateConfiguration" SDT variable is added as an IN access point to the email application.


Figure: Template configuration access point

Figure: Dynamic Template runtime

If the template has the following content:

Dear Mr. $person.firstname $person.lastname!

Figure: Email sample with dynamic attachment

Figure: Email sample with pdf dynamic attachment

Attachments/Templates derived from process data

The attachment tab allows to define documents to be attached to the e-mail sent. Those documents have usually being processed by a template engine where the template is located in the document repository or class path and the actual values are derived from process data. This section explains how attachment documents could be derived from process data and sent as e-mail attachment too.

The following model shows how to derive templates from process data. It has a manual activity where a "Person" details and two templates are entered. In the second activity, an email application is invoked using the entered data.

Figure: Templates derived from process data model

The email application has two templates (document type) defined as IN parameters.

Figure: Email template Parameters

The two document types defined as IN access point are listed in attachment tab with "Source = Data" and "Path = EMPTY". The others are located in the Repository and ClassPath.

Figure: Email template Attachments

At runtime, enter person details and upload the template files as follow..

Figure: Email template Data Attachments Runtime

An email as follow is sent having four files as attachement.

Figure: Email sample with process data attachment

Document Request Attachment

To manage the correspondences with their clients, Clerks or Business Analysts want a model to indicate which documents are received, which one are missing, etc. In many cases, they want to send an email to:

• acknowledge documents reception
• request missing documents
• inform whether a document is accepted/required or not
• attach a received document, a user guide, a new form, etc.

To achieve this task, E-Mail overlay has been extented to derive attachments from a process data DOCUMENT_REQUEST. If Document Request is selected in the Attachment tab, an IN access point of type DOCUMENT_REQUEST is created.

The "DOCUMENT_REQUEST" data type is a list of "REQUEST_ITEM". Each REQUEST_ITEM has the following attributes:

• Name: the document name
• Exists: whether the document exists or missing
• Accepted: whether the document is accepted or not
• Required: whether the document is required or not
• DocumentLocation: repository path to HTML, Text or DOCX template
• IsAttachment: whether the document should be attached to the email or not
• IsTemplate: if true run the attachment through the templating engine before sending it.
• ConvertToPDF: if true convert the attachment to PDF before sending it (after processing it as template if applicable).
• DocumentID: the document ID
• DocumentType: optional document type (Passport, DriverLicense, etc)
• Comment: a comment about the document (i.e: "Please provide new driver license. The one you provided is expired")
• ACL: list or roles with read/modify/delete rights

A document is attached to the Email, if IsAttachment is TRUE. The configuration is mapped as follows:

• Template > IsTemplate
• Name > Name
• Source > Repository
• Path > DocumentLocation
• Format > ConvertToPDF (true/false)

In case DOCUMENT_REQUEST is selected, the additional attachments via IN data mappings (document type) are ignored (not possible anymore).

The variable $docreq could be used in an email template to access all/accepted/missing/required documents:

• $docreq.existing: Existing documents (returns document names and comments)
• $docreq.accepted: Accepted documents
• $docreq.required: list all required documents
• $docreq.all: list all documents

The following example shows how to loop over the documents and access their attributes

#foreach ( $item in $DOCUMENT_REQUEST.Documents)
	Document: $item.Name
	Comment:  $item.Comment
	Exits: $item.Exists
	Accepted: $item.Accepted
	Required: $item.Required
	DocumentType: $item.DocumentType
#end

The following example illustrates how to use the document request with email application

• Create a model where you you fill the document request and a person details.


Figure: Doc Request model

• Define the document request SDT


Figure: DocRequest SDT

• Create an email application and select document request as attachment source


Figure: Doc Request attach source

• The email application parameters are as follow

Figure: Email Doc Request Parameter

The email body is based on the following template file

Hi $person.firstname $person.lastname

$docreq.existing

Deploy the model and run it

Figure: Enter Document Request

In this example, the UserNotification document is a template (.docx) located in the Document Repository. It will be converted to PDF format and attached to the output email

Figure: The Document Request Template/attachment/Pdf

Enter a person details (first/lastname). Here is a sample email output:

Figure: Email with document request

The attachment is as follow:

Figure: Email with document request attachment

Comments

Click the Comments tab to add comments for the application. The newest comment gets displayed at the top of the table. To add the comment, specify the comment in the text box and click Submit. To delete the comment, select the comment and click the Delete icon. The user, who has submitted the comment, can delete that comment. If the other user selects the comment or no comment is selected, the Delete icon remains in disabled state.

Figure: Comments

Dependency

To use templating functionality, you have to add the following dependencies in your pom.xml file:

<dependency>
	<groupId>com.infinity.integration</groupId>
	<artifactId>camel-templating</artifactId>
	<version>3.0.1</version>
</dependency>

Camel context

To use templating functionality, you have also to add the defaultTemplatingRoutes context reference to your Camel Context file (e.g.:default-camel-context.xml file under \WEB-INF\config\ipp\spring folder.)

<camelContext id="defaultCamelContext" trace="true"
            xmlns="http://camel.apache.org/schema/spring">
      <routeContextRef ref="defaultTemplatingRoutes"/>
</camelContext>