jAPS 2.0 entando – Plugin Mail

Do It The jAPS Way

Eugenio Santoboni

Reviser 
AgileTec s.r.l.

William Ghelfi

Reviser 
Tzente s.r.l.

Elia Mezzano

First and complete version in Italian 
AgileTec S.r.l.

Andrea Dessì

English translation  
AgileTec S.r.l.

Copyright © 2009 Tzente S.r.l.

Legal Notice

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the Appendix entitled "GNU Free Documentation License".

The copyright holders make no representation about the suitability of this Document for any purpose. It is provided “as is” without expressed or implied warranty. If you modify this Document in any way, identify your resulting Document as a variant of this Document.

2011-02-14

Revision History
Revision 1.82011-02-11MEM

revision for jAPS 2.0 entando version 2.2.0

Revision 1.72010-04-1MEM

Change of the order of chapters

Revision 1.62010-03-16EM

Third public version, update to 1.2 version

Revision 1.52009-07-30EM

Second public version, update to 1.1 version

Revision 1.42009-06-16EM

First public version

Revision 1.32009-05-04EM

Second internal version

Revision 1.22009-04-09EM

First internal version

Abstract

This document aims to describe the structure of the Mail (jpmail) plugin.

Table of Contents

1. Scope of the Document
Introduction
Target Audience
Prerequisites
Resources
2. Specifications
Characteristics of the Plugin Mail
Features
Back-end Interface
3. Plugin Installation and Integration
Jpmail installation and integration
Technical Specification
The package
Integration in Production Environment
Installation in a Development Environment
4. Plugin configuration
Configuration

List of Tables

2.1. Characteristics Summary

Chapter 1. Scope of the Document

Table of Contents

Introduction
Target Audience
Prerequisites
Resources

Introduction

The purpose of this document is to provide a complete description of the Plugin Mail (jpmail) structure.

Target Audience

This document is intended for those who wish to know the capabilities of the jAPSPlugin Mail (jpmail) and are considering the possible integration into a running production environment or in its Development Environment (IDE Eclipse Project).

The document is addressed to both System Administrators and java Developers with a basic understanding of the JAPS 2.0 entando platform.

Prerequisites

In order to take maximum advantage from the present document, it is necessary to have basic knowledge about: Java platform, Eclipse development tools, the servlet engine Apache Tomcat, PostgreSQL dbms, jAPS 2.0 Framework.

Moreover, it's necessary to have read jAPS 2.0 Plugin Pattern document.

Resources

Additional informations may be obtained through the official mailing-lists:

Is it also possible to refer to the documentation found in the:

jAPS 2.0 Entando Project - Developer Website

Chapter 2. Specifications

Table of Contents

Characteristics of the Plugin Mail
Features
Back-end Interface

The Plugin Mail provides basic functionality for sending email both in plain text or HTML, with or without attachments. This service is the basis for all the plugins that require sending emails.

The plugin is structured can be inserted in an instance of jAPS without affecting the core system.

Table 2.1. Characteristics Summary

CodeNameTypePlugin VersionVersion of jAPS 2.0 entando
jpmailMailPurePlugin1.32.2.0 -
jpmailMailPurePlugin1.22.0.10
jpmailMailPurePlugin1.12.0.6 - 2.0.8
jpmailMailPurePlugin1.02.0.2

Characteristics of the Plugin Mail

Features

This plugin provides the functionality of sending emails from a configured sender in the system.

The main goal of this plugin is to provide general functionalities in the service of particular implementations; exposed functionalities are in the exclusive service of other modules who need sending emails in order to work; for instance: User Registration, Newsletter etc.

Other modules can send emails, using the interface exposed by the Plugin Mail, customizing the following fields:

  • Sender (from senders configured in the service)
  • Subject
  • Body
  • Recipient (Primary recipients (to), Carbon Copy recipients (cc) and also Blind Carbon Copy recipients (bcc))
  • Message Body Type (plain text, HTML, mixed; with or without attachments)

The modules has an user interface of the Back-end area through which a superuser can configure the service. The user interface adheres perfectly to the graphics and setting of the Back-end area and is accessible through a menu item Plugins. Moreover, It allows to configure, separately, the smtp server and the system senders addresses.

Back-end Interface

This plugin provides user interface of the Back-end area accessible through a menu item Plugins, sub-menu eMail Management. There are two sub-items, the first leads to the SMTP server configuration page, the other leads to the Sender Configuration page.

Chapter 3. Plugin Installation and Integration

Table of Contents

Jpmail installation and integration
Technical Specification
The package
Integration in Production Environment
Installation in a Development Environment

Jpmail installation and integration

Technical Specification

This plugin is PurePlugin, its installation doesn't modify any existing system function already present.

The package

The package contains all the plugin directory (directory doc, src and the Readme file) defined by jAPS2.0 Plugin Pattern document.

In particular, the directory src is structured as described below:

  • The java directory. It contains java sources and the jUnit tests for the plugin.

  • The sql directory. It contains sql scripts for the Port and test databases.

  • The webapp directory. It contains all the necessary files for the webapp. In particular, the directory contains files (jsp) related to user interfaces and configuration files themselves. It contains also Spring beans configuration (Business layers), Struts 2 configuration (Presentation layer) and the static resources for the plugin (css, images and js).

Integration in Production Environment

From now we will use the name myportal when referring to your deployed jAPS 2.0 entando Application.

In order to execute the integration in a web application based on a jAPS 2.0 entando declared compatible with the plugin, follow this procedure:

Note

The integration activity must be performed after stopping the container.

  • Copy the content of src/webapp/WEB-INF/lib directory, from the provided package, to myportal/WEB-INF/lib/ directory.

  • Create the directory myportal/WEB-INF/plugins/ if it does not exist. Copy the content of src/webapp/WEB-INF/plugins/ directory, from the provided package, to myportal/WEB-INF/plugins/ just created.

  • Execute the queries in portScript.sql file (src/sql directory in the provided package) in the Port db or your jAPS application.

  • The script assumes production as value of version, modify It if version is different in the production environment. Modify also the smtp server configuration and sender addresses as needed.

Installation in a Development Environment

From now we will use the name myproject when referring to your jAPS 2.0 entando Eclipse project.

To perform the installation of jprss in an Eclipse IDE, on a version of jAPS 2.0 entando compatible with the plugin, follow these steps:

  • Copy the content of src/webapp/WEB-INF/lib/ directory, from the provided package, to myproject/WebContent/WEB-INF/lib/ directory excluding the file jAPSPlugin-jpmail-1.1.jar .

  • Copy the content of src/webapp/WEB-INF/plugins/ directory, from the provided package, to myproject/WebContent/WEB-INF/plugins/ directory. If myproject/WebContent/WEB-INF/plugins/ is not already present, create it.

  • Copy the content of src/webapp/resources/plugins/ directory, from the provided package, to myproject/WebContent/resources/plugins/ directory.

  • Execute the queries in portScript.sql file ( src/sql directory in the provided package) in the Port db or your jAPS application.

    The script is assumes production as value of version (modify It if version is different in the db of your application). Modify also the smtp server configuration and sender addresses as needed.

  • Execute the queries in portTestScript.sql file (src/sql directory in the provided package) in your test port db.

  • Copy the content of src/java/main/com directory, from the provided package, to myproject/src/com directory.

  • Copy the content of src/java/test/test directory, from the provided package, to myproject/src/test.

  • If the file myproject/src/japs-struts-plugin.xml is already present, copy the content of <struts> tag from src/java/main/jpphotogallery_japs-struts-plugin.xml file, of the provided package, to existent myproject/src/japs-struts-plugin.xml file .

    If the file myproject/src/japs-struts-plugin.xml is not already present, then copy the src/java/main/jpphotogallery_japs-struts-plugin.xml , from the provided package, to myproject/src/ directory and rename it as japs-struts-plugin.xml.

  • To verify proper sending of mails, in the jUnit tests, modify the MAIL_ADDRESSES constant of the test.com.agiletec.plugins.jpmail.util.JpmailTestHelper.java class.

After the steps just described, launch the Eclipse project and verify new menu items in the Back-end are present.

Chapter 4. Plugin configuration

Table of Contents

Configuration

Configuration

The configuration parameters of this plugin are kept in the Port database of the current jAPS installation. This includes not only the host network configuration with all the related parameters (as shown below), but also a list of senders associated with an alphanumeric code.

The configuration is easily changed in the administration interface.

An example of the configuration: 

<mailConfig>
  <senders>
    <sender code="CODE1">EMAIL1@EMAIL.COM</sender>
    <sender code="CODE2">EMAIL2@EMAIL.COM</sender>
  </senders>
  <smtp debug="true" >
    <host>out.virgilio.it</host>
    <user></user>
    <password></password>
  </smtp>
</mailConfig>

All these parameters are mandatory, except for the debug attribute that, when not present, is defaulted to "false".