EngageOne Communication Suite e-Messaging Installation Guide
Version 1.4M8 Issue 1 Copyright ©2015 Pitney Bowes Software, Inc. All rights reserved.
This publication and the software described in it is supplied under license and may only be used or copied in accordance with the terms of such license. The information in this publication is provided for information only, is subject to change without notice, and should not be construed as a commitment by Pitney Bowes Software (PBS), Inc. To the fullest extent permitted by applicable laws PBS excludes all warranties, representations and undertakings (express or implied) in relation to this publication and assumes no liability or responsibility for any errors or inaccuracies that may appear in this publication and shall not be liable for loss or damage of any kind arising from its use. Except as permitted by such license, reproduction of any part of this publication by mechanical, electronic, recording means or otherwise, including fax transmission, without the express permission of PBS is prohibited to the fullest extent permitted by applicable laws. Nothing in this notice shall limit or exclude PBS liability in respect of fraud or for death or personal injury arising from its negligence. Statutory rights of the user, if any, are unaffected.
This software contains open source code listed below and governed by the following licenses: • COMMON DEVELOPMENT AND DISTRIBUTION LICENSE (CDDL). License can be downloaded from: http://www.sun.com/cddl/cddl.html • Software licensed under the Apache License, Version 2.0 (the “license”); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0. Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. • Licensed under GNU Lesser General Public License, Version 2.1, February 1999. License can be downloaded from: http://www.gnu.org/licenses/lgpl-2.1.html
Copyright © 1991, 1999 Free Software Foundation, Inc. 59 Temple Place, Suite 300, Boston, MA 02111-1307 USA
Open source libraries included in this product are listed below: • Java code, including the JavaMail API, from Sun Microsystems. • COMMON DEVELOPMENT AND DISTRIBUTION LICENSE (CDDL). • Source code is available from: http://java.sun.com/products/javamail/downloads/index.html • Software developed by the OpenSSL Project for use in the OpenSSL Toolkit (http://www.openssl.org/). • Apache License, Version 2. • Copyright © 1998 – 2007 The OpenSSL Project. All rights reserved. • This software contains code from the Acegi Security Project. (http://www.acegisecurity.org/) • Apache License, Version 2.0 • Source code is available from: http://www.acegisecurity.org/ • Code from the AppFuse.5 Project. (http://appfuse.org/) • Apache License, Version 2.0 • Source code is available from: http://appfuse.org/ • Code from the Apache Lucene Project. (http://lucene.apache.org/) • Apache License, Version 2.0 • Source code is available from: http://lucene.apache.org/ • Code from the Apache Commons Project (http://commons.apache.org/) • Apache License, Version 2.0 • Source code is available from: http://svn.apache.org/viewvc/commons/proper/configuration/ • Code from the JODConverter Project. (http://www.artofsolving.com/opensource/jodconverter) • Licensed under GNU Lesser General Public License, Version 2.1, February 1999. • Source code is available from: http://www.artofsolving.com/opensource/jodconverter • Code from the iText Project (http://www.lowagie.com/iText/) • Licensed under GNU Lesser General Public License, Version 2.1, February 1999. • Source code is available from: http://www.lowagie.com/iText/ • Code from the JFreeChart Project (http://www.jfree.org/) • Licensed under GNU Lesser General Public License, Version 2.1, February 1999. • Source code is available from: http://www.jfree.org/ • Code from the JasperReports Project (http://jasperforge.org/sf/projects/jasperreports) • Licensed under GNU Lesser General Public License, Version 2.1, February 1999. • Source code is available from: http://jasperforge.org/sf/projects/jasperreports • Code from JavaMail-Crypto API. • Licensed under GNU Lesser General Public License, Version 2.1, February 1999. • Source code is available from: http://sourceforge.net/projects/javamail-crypto/ • Code from Bouncy Castle Java cryptography API. • Licensed under GNU Lesser General Public License, Version 2.1, February 1999. • Source code is available from: http://www.bouncycastle.org/latest_releases.html • Freemarker code from Visigoth Software Society • Licensed under BSD-style license, http://freemarker.org/docs/app_license.html • Source code is available from: http://freemarker.org/freemarkerdownload.html • OpenSMPP code from Logica • Licensed under Logica Open Source License Version 1.0, http://opensmpp.logica.com/CommonPart/Download/Download.htm • Source code is available from: http://opensmpp.logica.com/CommonPart/Download/download2.html Contents
ABOUT THIS GUIDE ...... 9
Introduction ...... 9 Related documentation ...... 9 Target audience ...... 9 Skills and training ...... 10
Updates to this guide ...... 10
GETTING STARTED ...... 11
e-Messaging Core Architecture ...... 11 e-Messaging core ...... 11 e-Messaging data ...... 11 Outbound ...... 12 Inbound ...... 12 Content converter ...... 13 Mail servers ...... 13
e-Messaging physical architecture ...... 14
Pre-Installation ...... 15
System Requirements ...... 16 Hardware requirements ...... 16 Server system requirements ...... 19 e-Messaging client system requirements ...... 20 LDAP requirements ...... 21 Supported connectivity software ...... 21 Email gateway requirements ...... 21 SMS gateway requirement ...... 21 System performance recommendations ...... 22
5 Contents
INSTALLING E-MESSAGING ...... 24
Installing on Windows ...... 24 Uninstalling e-Messaging on Windows ...... 47
Installing on Solaris, AIX, Red Hat Linux and Suse zLinux ...... 48 Uninstalling on Solaris, AIX, Red Hat Linux and Suse zLinux ...... 53
SETTING UP DATABASES ...... 54
Microsoft SQL Server 2005/2008/2012 configuration ...... 54
Oracle 10g/11g configuration...... 55
DEPLOYING E-MESSAGING ON WEB APPLICATION SERVERS ...... 57
Setting up e-Messaging on JBoss ...... 57 JBoss 5.1.0 configuration ...... 58 JBoss EAP 6.2.0 configuration ...... 59 WildFly 8.0.0 configuration ...... 61
Setting up e-Messaging on Tomcat ...... 62 Tomcat 6.0 configuration ...... 62
Setting up e-Messaging on WebSphere ...... 64 WebSphere 7.0/8.5.5 configuration ...... 64
Setting up e-Messaging on WebLogic ...... 72 WebLogic 10.3 configuration ...... 72
Additional configurations for e-Messaging upgrade ...... 77
Providing access to remote Data Flow / Generate and Designer servers . 78 Updating the listener properties file ...... 79
Starting Open Office service ...... 79
INITIAL SETUP ...... 82
First log-in ...... 82
Creating the initial vendor ...... 82
6 Contents
CONFIGURATION SETTINGS ...... 84
System configuration ...... 84 Installation options selected ...... 84 Configuration settings defined ...... 84 e-Messaging languages ...... 85 Receiving messages ...... 85 Sending messages ...... 86 Working with workflows ...... 89 Generating reports ...... 89
Login and security ...... 90
Roles and permissions ...... 91
Menus and screen navigation ...... 95
Vendor and system settings ...... 99 Vendor creation ...... 99 Secret questions ...... 103 Roles ...... 105 Initial user ...... 109 Vendor environment ...... 110 Gateways and servers ...... 113
APPENDIX A – SSL CONNECTIONS TO MAIL SERVER ...... 117
IBM WebSphere v7.0 and v8.5.5 with security certificates ...... 117
Tomcat and JBoss with security certificates ...... 119
Weblogic 10.3 application servers with security certificates...... 120
APPENDIX B – UPGRADING THE LICENSE FILE ...... 126
Optional MAC address licensing on Windows ...... 127
7 Contents
APPENDIX C – CONFIGURING WEBSPHERE TO WRITE A TRACE LOG . . . . . 128
APPENDIX D – CONFIGURING THE PASSWORD RULES ...... 131
8 About this guide
About this guide
Introduction
This guide describes how to install e-Messaging. It is intended for system administrators and professional services personnel who are responsible for installing e-Messaging.
These instructions assume you are familiar with Microsoft Windows, Solaris, Linux, and/or AIX operating systems.
The following summarizes the content of each section of this manual: • Getting started – lists the system requirements for e-Messaging. This includes the server, client and databases. • Installing e-Messaging – describes the procedure for installing e-Messaging server software on Windows, Solaris, Linux, and AIX. • Setting up databases – describes how to configure the e-Messaging database. • Deploying e-Messaging on Web application servers – guides you through the process of configuring your Web servers to work with e-Messaging. • Initial Setup – describes initial log in and vendor creation. • Configuration settings – describes how e-Messaging can be configured to suit your organizational or individual requirements. Configuration settings can be defined at the vendor, system, operational or user management levels. Related documentation
The following guides provide useful reference material: • e-Messaging Reference Guide • e-Messaging User’s Guide • e-Messaging Release Notes Target audience
The document is intended mainly for system administrators responsible for installing e-Messaging but could also provide information for: • Database Administrator – preparation and running of database scripts
9 About this guide
Skills and training
It is assumed that personnel reading this guide would have an understanding of the following: • J2EE concepts and technologies • Installing of supported application servers
Updates to this guide
This guide is issued in electronic format (PDF) only. It may be reissued from time to time to include corrections or additions that have been made since the original issue. These changes will be indicated with a change bar in the margins.
Typographical conventions
The following are used throughout this manual. [...] parameters between square brackets are optional. { opt1 | opt2 parameters between curly } braces represent a list of options, one of which must be chosen. Text in italics represents parameter data which should be replaced with customized values. UPPER CASE text represents constant command text which should be typed exactly as written. • space character (used only if spaces are not apparent).
10 Getting started
e-Messaging is a complete, enterprise class, solution for managing in- and out-bound e-mail and SMS customer communications. e-Messaging leverages and extends existing Pitney Bowes Software Customer Communication Management components such as Designer, Generate, Vault and Data Flow. e-Messaging Core Architecture
Outbound Inbound Converter
Web Services
Core Web Remote
e-Messaging core
The e-Messaging core is the central controller of e-Messaging. It provides key functions for the processing of both, outbound and inbound messages, which will be explained in more detail later. e-Messaging data
The e-Messaging core uses a data access layer that stores and retrieves data from a relational database management system (RDBMS), such as SQL Server and Oracle. This forms the Model component in the MVC architecture. Though, not shown as a separate box in the architecture diagram, this data access layer uses object relational mapping (ORM) technology to store and retrieve data in an RDBMS.
11 Getting started
Outbound
The Outbound component orchestrates the different processes required for:
Data Preparation and Formatting (optional) • Data Flow Plans can be triggered from e-Messaging as part of messaging campaigns.
Message Formatting (optional) • Designer Applications can be triggered from e-Messaging to format message content.
Post Process Formatting (optional) • Post Composition processes can be triggered by e-Messaging to manipulate content that has been formatted by Designer prior to the content being sent.
The Core component coordinates between the Outbound and Remote components to allow Data Flow and Generate processes to be managed on either the same physical server as the e-Messaging Core, or on a separate server. Post Process Formatting is expected to be performed on the same server as the Message Formatting, i.e. the server running Generate.
The Outbound component detects files or content in polled directories that requires sending. It should be noted that the Outbound component includes a scheduling component so that e-mail or SMS campaigns can be triggered at specific dates and times, e.g. when the network infrastructure is least busy. e-Messaging supports sending of messages in both, batch and real-time modes.
For archiving outbound messages, e-Messaging accesses the download folder of a Vault instance. The Core component coordinates with the Outbound component to take care of batching up content into “collections” and providing Vault with batched content and the required index values to store content in an efficient and compressed manner. Inbound
The Inbound component processes messages received by e-Messaging. Received messages could be messages that require archiving into Vault, messages that require a response or delivery status notifications reporting on messages sent by the Outbound component that could not be delivered. The Inbound component also takes care of associating inbound messages with outbound messages sent by e-Messaging so that reports can be provided on what messages bounced (including bounce category) and what messages have been replied to.
The Core component coordinates with the Inbound component to call the Vault Render Server API to automatically index inbound messages wherever possible. When automatic indexing is disabled or not possible, e-Messaging will present an operator with a dropdown list of index options so that messages are still indexed with minimum clicks / human intervention.
12 Getting started
For archiving inbound messages, e-Messaging accesses the download folder of an Vault instance. The Core component coordinates with the Inbound component to take care of batching up content into “collections” and providing Vault with batched content and the required index values to store content in an efficient and compressed manner. Content converter e-Messaging provides a content conversion service so that the content of outbound messages can (optionally) be converted to a more appropriate format for archiving such as PDF. Open Office is leveraged to handle PDF or PDF/a conversion and the Javamail API is used for converting HTML to MHT – embedding images for version control. Mail servers e-Messaging uses SMTP (Simple Mail Transfer Protocol) for sending outbound e-mail. Most e-mail systems that send mail over the Internet use SMTP to send messages from one server to another; the messages can then be retrieved with an e-mail client using either POP or IMAP (discussed further in inbound message processing). Thus, e-Messaging can interface with any mail servers that provide SMTP support.
After message content has been composed (either under the control of e-Messaging or externally to e-Messaging), e-Messaging takes care of packaging the message headers and bodies into the right format for the required e-mail or SMS delivery. The header information comes from two sources: an XML journal provided by DOC1 and profile settings that are configured in the e-Messaging Core. This provides maximum flexibility in terms of being able to personalize subject lines and attachment filenames on a message-by-message basis.
13 Getting started e-Messaging physical architecture
14 Getting started
Pre-Installation
e-Messaging may be used in combination with other Pitney Bowes Software CCM software solutions such as Vault, Designer, Generate, EngageOne Server, and Data Flow. Vault is a required component for archiving of inbound and outbound messages in e-Messaging. Archiving of messages in e-Messaging is not possible without Vault. Designer and Generate can be used for generating message content. e-Messaging also makes use of Open Office’s conversion capabilities. Depending on your configuration, you can install all or some server software components on a single server or distributed across multiple servers.
The following list of tasks provides the order for installing e-Messaging: 1. Review the system requirements for Windows servers, Solaris servers, Linux servers, AIX servers, and Windows client systems. For more information, see “System Requirements” on page 16. 2. Verify that there is an accessible database server, Web server, SMPP server (for SMS), and SMTP server (for emails). For more information, see “Supported connectivity software” on page 21. 3. Run the provided e-Messaging installer for the appropriate operating system. For more information, see “Installing e-Messaging” on page 24. 4. Install the Web application server e-Messaging will use. For more information, see “Deploying e-Messaging on Web application servers” on page 57. 5. Perform the initial e-Messaging setup. For more information, see “Initial Setup” on page 82. 6. Configure e-Messaging and other server software. For more information, see “Configuration settings” on page 84. 7. Install the following client software on Windows client machines: • Any of the following Web browser: FOR MORE INFORMATION, SEE “E-MESSAGING Internet Explorer 6.x or later CLIENT SYSTEM REQUIREMENTS” ON PAGE 20. versions or Note: Please enable compatibility mode, if you are using Internet Explorer 7 or higher versions. Mozilla Firefox 2.x or later versions • Adobe Acrobat Reader 6.0+ or later versions. (Note: Please use version 8.0+ when using Internet Explorer version 6.x) 8. Install the following client software on Solaris, Linux, and AIX client machines:
15 Getting started
• The following Web browser: Mozilla Firefox 2.0.0.11 or higher for Solaris Mozilla Firefox 3.5.13.1 or higher for AIX and Linux
System Requirements
Topics in this section: • Hardware requirements • Server system requirements • Supported connectivity software • e-Messaging client system requirements • LDAP requirements • Email gateway requirements • SMS gateway requirement Hardware requirements
Topics in this section: • Server system requirements for Windows • Server system requirements for Solaris • Server system requirements for AIX • Server system requirements for Red Hat Linux • Server system requirements for Suse zLinux
16 Getting started
Server system requirements for Windows
Before installing e-Messaging on a Windows server, ensure that your system meets the minimum requirements listed below:
Server system requirements for Windows The system is verified to work under the following operating systems: • Microsoft Windows Server 2012 R2 • Microsoft Windows Server 2008 R2 SP1 64-bit 2 GB of RAM 1 GB of available disk space One of the following Web Application Servers installed: •Apache Tomcat 6 • JBoss 5.1.0 • JBoss EAP 6.2.0 •WildFly 8.0.0 • WebSphere 7.0.0.13 • WebSphere 8.5.5 •WebLogic 10.3.5 Java Runtime Environment (JRE) 6
The number of transactions, amount of data, IF YOU ARE RUNNING E-MESSAGING APPLICATION and the intended number of vendors will ON A 64-BIT JVM (JAVA VIRTUAL MACHINE), THEN affect the required amount of disk space, MEMORY REQUIREMENT WILL BE 30% TO 40% HIGHER AS COMPARED TO A 32-BIT JVM. FOR memory and processing power. Analysis of EXAMPLE, YOU CAN SET THE FOLLOWING JVM your maximum required message throughput PARAMETERS IN TOMCAT AND JBOSS SERVER is recommended when determining the STARTUP FILES: -XMS512M -XMX1024M -XX:MAXPERMSIZE=256M. minimum hardware requirements for e-Messaging.
17 Getting started
Server system requirements for Solaris Server system requirements for Solaris Solaris version 10 including the most current Patch Cluster available at Sun website. 1 GHZ SPARC processor or x86 processor 2 GB of RAM 1 GB of available disk space One of the following Web Application Servers installed: •Apache Tomcat 6.x •WebLogic 10.3.5 Java Runtime Environment (JRE) 6
Server system requirements for AIX Server system requirements for AIX AIX version 6.1 or 7.1 Any system from the POWER® family of processors (64-bit) At least 16GB RAM (Large production servers may require more than the recommended amount of memory) 1 GB of available disk space One of the following Web Application Servers installed: •Apache Tomcat 6 • WebSphere 7.0.0.13 • WebSphere 8.5.5 Java Runtime Environment (JRE) 6
18 Getting started
Server system requirements for Red Hat Linux Server system requirements for Red Hat Linux Red Hat Enterprise Linux Server 6.4 Intel(R) Xeon(R) family processor @ 2 GHz At least 8 GB RAM (Large production servers may require more than the recommended amount of memory) 1 GB of available disk space The following Web Application Server installed:
WebSphere 8.5.5 Java Runtime Environment (JRE) 6
Server system requirements for Suse zLinux Server system requirements for Suse zLinux Suse zLinux (SUSE Linux Enterprise Server 10 (s390x) VERSION = 10) At least 8 GB RAM (Large production servers may require more than the recommended amount of memory) 1 GB of available disk space The following Web Application Server installed: Websphere 7.0.0.19 Java Runtime Environment (JRE) 6
Server system requirements
Operating systems • AIX 6.1 or 7.1 • Solaris 10 SPARC or x86 • Windows Server 2008 R2 SP1 64-bit • Windows Server 2012 R2 • Red Hat Enterprise Linux Server 6.4 • Suse zLinux (SUSE Linux Enterprise Server 10)
Application servers •Tomcat 6.x
19 Getting started
• WebLogic 10.3.5.x • WebSphere 7.0.0.x • WebSphere 8.5.5 • JBoss 5.1.0 • JBoss EAP 6.2.0 • WildFly 8.0.0
Database server • Microsoft SQL Server 2005 • Microsoft SQL Server 2008 • Microsoft SQL Server 2012 •Oracle 10g •Oracle 11g e-Messaging client system requirements
Before installing e-Messaging, ensure that your client system meets the minimum requirements listed below:
e-Messaging Client System Requirements The client system is verified to work under the following operating systems: • Microsoft Windows Server 2012 R2 • Microsoft Windows 2008 Server Service Pack 1 • Microsoft Windows 7 • Microsoft Windows XP Service Pack 2 Any of the following Web browsers: • Internet Explorer 6.x or later Note: Please enable compatibility mode, if you are using Internet Explorer 7 or higher versions. • Mozilla Firefox 2.0 or later Adobe Acrobat Reader 6 or later (Note: Please use version 8.0+ when using Internet Explorer version 6.)
20 Getting started
LDAP requirements
Users can be created and maintained in e-Messaging itself or optionally imported through LDAP from an organization's existing user management system. Since LDAP is optional, it is not covered in detail in the Installation Guide. See the "LDAP Configuration" section of the e-Messaging Reference Guide for details on configuring e-Messaging to use LDAP for user account authentication. • Microsoft Active Directory •Apache Directory Server Supported connectivity software
In addition to the software on your e-Messaging CD, you need a compatible connectivity software. It is desirable but not essential to install the connectivity software before installing e-Messaging.
Required connectivity software e-Messaging requires an email gateway and an SMS gateway (if SMS is used). • An e-mail gateway must be available for e-Messaging to interface with while using the SMTP protocol for outbound messages and the POP3 or IMAP protocol for inbound message processing. A dedicated e-mail server is recommended for e-Messaging. • An SMS gateway must be available for e-Messaging to interface with while using either the SMPP protocol or one of the other optional access methods for SMS. Email gateway requirements e-Messaging uses SMTP (Simple Mail Transfer Protocol) for sending outbound e-mails. Most e-mail systems that send mails over the Internet use SMTP to send messages from one server to another; the messages can then be retrieved with an e-mail client using either POP or IMAP. Thus, e-Messaging can interface with any mail servers that provide SMTP support. An e-mail gateway must be available for e-Messaging to interface with while using the SMTP protocol for outbound messages and the POP3 or IMAP protocol for inbound message processing. A dedicated e-mail server is recommended for e-Messaging.
For more information, see "Inbound Message Processing" in the e-Messaging Reference Guide. SMS gateway requirement e-Messaging supports formatting and sending single SMS (Short Message Service) messages using any of the following ways: • using the SMTP interface of http://www.clickatell.com.
21 Getting started
• via an SMPP outbound transmitter or transceiver that connects to an SMS gateway directly over TCP/IP. • via the Java API described in the e-Messaging Reference Guide.
By default e-Messaging exchanges SMS messages (inbound and outbound) with SMS gateways via SMPP (Simple Message Peer to Peer Protocol). This protocol is supported by all SMS gateways, however, some gateways require a commitment to process over 5,000 or 10,000 SMS messages per month. An SMPP account with an SMS gateway provider such as http://www.clickatell.com is required. Clickatell offers global coverage and competitive rates, however, e-Messaging can interface with any SMS gateway that supports SMPP.
If the customers use Clickatell, then they need to open an account with Clickatell online and generate a SMS API ID and other credentials that are required when configuring an e-Messaging Outbound Profile to send SMS messages through Clickatell. e-Messaging can also interface with Clickatell's SMTP interface, which can be useful for organizations willing to send less than 5,000 messages per month. If this option is chosen, then a local e-mail account will be required for e-Messaging to transmit SMTP messages through. The e-Messaging server needs to be able to access the e-mail server where this account is hosted; i.e. it should not be blocked by firewalls etc.
Besides the SMS gateway interfaces described above, e-Messaging provides a published Java API for custom integration with SMS gateways using protocols other than SMPP and SMTP. See the e-Messaging Reference Guide for more details on using the API. System performance recommendations
Description CPU Cores CPU Speed Memory e-Messaging application server 8 2.39 GHz 32 GB Database Server 8 2.39 GHz 32 GB
The primary factors in achieving maximum e-Messaging performance include the following: • Disk Drive IOPS (Input/Output Operations Per Second): Persistent storage performance is vital in achieving optimum results. High Performance RAID (RAID 10) storage with Serial Attached SCSI (SAS) drives, such as 15K RPM Hard Drives or High Performance SLC SSD is highly recommended. • CPU (quantity and speed): 2 Quad processor is recommended • RAM (quantity and speed): 32GB or more of high-speed RAM is recommended. • Multiple disks: If separate and independent high-performance drives are available, configure each of the following directories on a separate drive on the same server. If only one high-performance drive is available, keep all these directories on that drive.
22 Getting started
• Directories containing the DIJ, HTML, text, images, error, and vendor files • Archive Folder (if archiving enabled) • It is recommended to keep the Vendor folder on the same server where e-Messaging application is deployed. • Latency to the e-mail and SMS gateways should be kept to a minimum; 10 ms maximum, zero latency when possible. • Bandwidth to the e-mail and SMS gateways should be sufficient enough to handle the expected amount of traffic. • We suggest a connection of at least double the expected traffic size since any binary data (such as PDF attachments) must be UUEncoded which increases the size of the email. For example, if your e-mail body is 15KB and your attachment is 120KB, then your total e-mail size will be 135KB. If you want to send 10 e-mail per second, you would need at least 2.7MB/sec Internet connectivity (2 * 10 * 135KB/sec. = 2.7MB/sec). Note that if e-mails and SMS will be sent simultaneously, then ensure your bandwidth requirements include both. • Firewalls can reduce performance and should be avoided when possible. • Make sure that the e-Messaging database purge scripts are set to run on a regular basis. • Regularly perform server health check and database maintenance activities: • Update Statistics, Purge SQL Logs and tempDB • Application logs - Review logging levels • Disk Defragmentation
23 Installing e-Messaging
Installing on Windows
Setup installs e-Messaging and optional components.
Before installing e-Messaging, see “Pre-Installation” on page 15 and “System Requirements” on page 16. This will ensure that you have all the required items before starting the installation process.
| To install e-Messaging: 1. Insert the e-Messaging CD and the installer will start automatically. If it doesn’t start then browse your CD drive and run emessagingsetup.hta
2. Click the Install e-Messaging link to start the installation process. e-Messaging Installation Wizard appears.
24 Installing e-Messaging
3. Welcome dialog displays. Ensure that you have exited all applications. Click Next.
25 Installing e-Messaging
4. License Agreement dialog displays. Click I accept the agreement. Click Next.
26 Installing e-Messaging
5. Product License dialog displays. Locate the Product license key file that comes with e-Messaging. Click Next.
An error message displays for an invalid, expired, or incomplete product key. Contact your e-Messaging support if any of the above error messages are displayed.
27 Installing e-Messaging
6. Select the license environment you wish to use for your installation.
On selecting a license environment, the screen displays a summary of the selected environment’s configuration.
NOTE:
Optional MAC address licensing on Windows: As of version 1.3 MAC Address validation may optionally be used when deploying on a Windows operating system. When MAC Address is included in an e-Messaging environment section of G1Keys.xml then e-Messaging will only install and run on a computer with the specified MAC address. When the MAC address field is omitted from an e-Messaging environment section of G1Keys.xml then e-Messaging works regardless of the MAC address of the computer.
The support for old G1Keys.xml license file which did not include MAC Address is also maintained.
28 Installing e-Messaging
7. Select Destination Directory dialog displays. Specify the directory for all the e-Messaging components to be installed. Click Next.
29 Installing e-Messaging
8. Previous Installation Detected dialog displays. If the installer detects a previous version of e-Messaging installed then the Previous Installation Detection dialog will display. If Yes is selected then the installer will proceed to upgrade the current installation of e-Messaging as outlined in the section “To upgrade e-Messaging”on page 42. If No is selected then the installer will exit.
30 Installing e-Messaging
9. Select Components dialog displays. For a new installation, the Select Components dialog allows you to select the components to be installed. The “core” component is pre-selected and is mandatory. An optional Tomcat Web server is available. Note that checking this component installs a new instance of Tomcat even if you have an existing one. To use your existing Tomcat instance, uncheck this component and manually configure the existing instance. For further information refer to “Setting up e-Messaging on Tomcat” on page 62. Click Next.
31 Installing e-Messaging
10. JRE Detected information message displays. The installer will try to detect an existing installation of the Java Runtime Environment (JRE). If an existing JRE is detected on the server, then the installer will notify you that it will try to use the detected JRE.
If no JRE is detected on the server, then the installer will notify you and use the Java Virtual Machine (JVM) that is bundled with the e-Messaging Installer to complete the installation.
You will normally only be given this notification if you have not installed the required “Java Virtual Machine 1.5+” on the server as outlined in “System Requirements” on page 16 for the selected OS. Note that the JVM included in the e-Messaging installer is only suitable for completing e-Messaging installation and not for running e-Messaging after it is installed. Even if you use the JVM included in the e-Messaging installer you will still need to install “Java Virtual Machine 1.5+” on the server, together with the other prerequisite software, before you can run e-Messaging. Generally, when you install a JRE on a Windows operating system the installer will automatically create a Windows Environment Variable called JAVA_HOME which points to C:\Program Files\jdk1.5.x. As part of the installation e-Messaging will check that the JAVA_HOME Environment Variable has been set. If JAVA_HOME has not been set on your server then you will be given a warning.
Clicking OK will complete the installation but you will need to ensure that a JRE is installed and JAVA_HOME set before you can run e-Messaging. You can set the JAVA_HOME Windows Environment Variable manually as follows:
32 Installing e-Messaging
i. In the Control Panel select System. ii. Select Environment Variables on the Advanced tab. iii. Create a new System Variable by clicking the New button in the appropriate section. iv. The Variable Name should be set to JAVA_HOME. v. The Variable Value should be set to the location of your JRE, for example: C:\Program Files\jdk1.5.x. vi. Click OK. 11 . Installing dialog displays. Wait while the selected components are being installed. If Tomcat is selected during installation, then the installer will create an environment variable called EM_CATALINA_HOME.
33 Installing e-Messaging
12. Database Settings dialog displays. Specify the database settings. Supported databases are MS SQL Server 2005/2008/2012, and Oracle 10g R2/11g. Note that the Database/Service Name will be used to refer to the schema. The last field in the screen only applies to Microsoft SQL Server, choosing any other database will ignore this field (Important MS SQL Server Notes: The SQL Server Browser service must be running. The default install does not configure the SQL Browser service to start automatically so you must do it manually). Click Next to apply the database settings.
34 Installing e-Messaging
13 . Optional Settings dialog displays Enter optional parameters to override the default values for formatting dates and times in the user interface. Click Next.
35 Installing e-Messaging
14 . Mail Settings dialog displays Specify the SMTP mail settings to be used by e-Messaging admin functions such as issuing of passwords. Default values are provided. Click Next.
36 Installing e-Messaging
15 . Converter Settings dialog displays Specify the PDF converter servers. The default setting assumes Open Office. Click Next.
37 Installing e-Messaging
16 . Root Folder Settings dialog displays Specify the root folder. The Root Folder is for vendor-specific settings and interfacing such as submitting content to be sent by e-Messaging. You may optionally specify the Root Folder as a UNC path. Click Next.
38 Installing e-Messaging
17. The screen below is displayed if the Tomcat component was not selected in step 9 of the installation. Select the application server to which you intend to deploy e-Messaging. The installer will create a package for deployment on the selected application server. The deployment package created by e-Messaging still needs to be deployed on your selected application server, refer to “Deploying e-Messaging on Web application servers” on page 57 for further details.
39 Installing e-Messaging
18 . Select Start Menu Folder dialog displays Specify the start menu folder. Uncheck Create shortcuts for all users if you only require an e-Messaging Start Menu folder to be created for the user currently logged in. The default (checked) setting will create e-Messaging Start Menu folders for all users of this server. Select Don’t create start menu folder if you do not wish e-Messaging to create a Start Menu folder for any users on this server. Click Next.
40 Installing e-Messaging
19 . Completing the e-Messaging Setup Wizard dialog displays The system displays a confirmation message of the installation process. Now run the database setup (build) or upgrade (update) scripts on the database server before e-Messaging is ready to run. Click Finish to exit Setup.
41 Installing e-Messaging
| To upgrade e-Messaging: 1. If the Upgrade option was selected at step 8 in the previous section, then the Installing dialog box displays. Wait while the currently installed version of e-Messaging is upgraded.
42 Installing e-Messaging
2. Select the application server you intend to deploy the upgraded e-Messaging to. The installer will create a package for deployment on the selected application server. The deployment package created by e-Messaging still needs to be deployed on your selected application server, refer to “Deploying e-Messaging on Web application servers” on page 57 for further details.
43 Installing e-Messaging
3. Installing dialog displays. Wait while your e-Messaging instance is upgrading.
44 Installing e-Messaging
4. During an upgrade, the e-Messaging installer automatically transfers customized settings from the property files of the current e-Messaging installation to the upgraded version. A summary list of the property files whose settings have been transferred to the upgraded e-Messaging instance is displayed, together with the location where a backup of the files containing the settings on the original e-Messaging instance can be found. The list of files displayed will vary depending on the version of e-Messaging that is being upgraded from and to.
45 Installing e-Messaging
5. Completing the e-Messaging Setup Wizard dialog displays The system displays a confirmation message of the installation process. Now run the database upgrade (update) scripts on the database server before e-Messaging is ready to run. Click Finish to exit Setup.
6. Complete the steps mentioned in the “Additional configurations for e-Messaging upgrade” section of this document. 7. Now, you can proceed with the deployment steps.
46 Installing e-Messaging
Uninstalling e-Messaging on Windows
| To uninstall e-Messaging on Windows: 1. Click Windows startup / All Programs / PBBI CCM/ e-Messaging / Uninstall e-Messaging. Note that this is just the default path and may vary depending on your installation.
2. Uninstall Confirmation dialog displays Click Next or Cancel to exit the process
3. Uninstall Progress dialog displays Wait while e-Messaging is being uninstalled. 4. Uninstall status confirmation dialog displays Click Finish to close the window.
47 Installing e-Messaging
Installing on Solaris, AIX, Red Hat Linux and Suse zLinux
| To install e-Messaging on Solaris, AIX, Red Hat Linux and Suse zLinux: 1. Login to your server. Check the java version that it has installed by typing: java -version The e-Messaging installer requires Java 1.6 or later. 2. Navigate to the folder where the e-Messaging installer is located. The installer is e-Messaging-UNIX.sh. 3. If e-Messaging is to be run under the WebLogic Application Server add the WebLogic bin directory to the LD_LIBRARY_PATH environment variable: LD_LIBRARY_PATH=\
OS Name: AIX OS version: 6.1 OS architecture: ppc Java version: 1.6.0 Java vendor: IBM Corporation For environment name: 'Config 19' select 14 Select a license environment: Config 19 [14]
48 Installing e-Messaging
8. Choose the appropriate license environment, the following is displayed: Customer: Netherlands Office Environment Name: e-Messaging on Solaris\ Language: English Maximum vendors: 1 Maximum monthly Email: 100000 Maximum monthly SMS: 100000 Expiration date: Fri Jan 28 00:00:00 GMT 2015 Features: - email outbound - SMS outbound - email archiving - SMS archiving - PDF conversion Platforms: Solaris Servers: JBoss Tomcat WebSphere WebLogic Proceed or select another? Yes [y], No [n]
Type “y” to continue. 9. Type the location where e-Messaging is to be installed.
Where should e-Messaging be installed? [/opt/PBBI_CCM/e-Messaging]
10. Choose the components to be installed by typing the appropriate numbers. Type “1” to install the core only, otherwise type “2” to include tomcat in the installation.
Which components should be installed? 1: core 2: Tomcat [1,2]
11. Choose the desired database by entering the appropriate keys.
49 Installing e-Messaging
Configure Database Settings Choose database: MS SQL Server 2005 [1, Enter] MS SQL Server 2008 [2] MS SQL Server 2012 [3] Oracle 10g [4] Oracle 11g [5]
12. Enter the name of the database.
Database Name [emessaging] orclsrv1
13. Enter the location of the database host.
Database Host [localhost] 172.16.0.152
14. Enter the port for the database connection.
Default ports: MS SQL Server (1433); Oracle (1521) Database Port: [] 1433
15. Enter the username and password for the database connection.
Username: [] emessaging Password: []
For MS SQL Server database only. Instance Name: []
16. Enter the desired date format. Press enter to use the default format.
Date Format: [dd MMM yyyy]
50 Installing e-Messaging
17. Enter the date format for the page. Press enter to use the default format.
This is the date format for the pages (e.g. dd MMM yyyy) Datetime Format: [dd MMM yyyy, HH:mm]
18. Enter the default SMTP host address and the port number associated with it. This is used by the e-Messaging admin function to distribute passwords, etc.
SMTP Mail Settings SMTP Host: [localhost] 172.16.0.153 SMTP Port: [25]
19. Enter the server address and port for the OpenOffice converter settings. Multiple converters may be specified as a comma separated list. Note: The OpenOffice converter is only supported when installed locally with the e-Messaging server.
Converter Settings PDF Converter Servers [hostname:port]: [localhost:8100]
20. Enter the folder location for the Root Folder settings.
Root Folder Settings Root Folder: [/vendors] /ust/installDir/vendors 21. Select the Application Server from the list.
To install e-Messaging, please select a server. Choose server: Tomcat 6.x [1, Enter] JBoss 5.1.0 [2] JBoss EAP 6.2.0 [3] Wildfly 8.0.0 [4] WebSphere 7.x [5] WebSphere 8.5.5 [6] WebLogic 10.3.5.x [7]
22. If the installation has been for either version of WebSphere and there has been an error message at the end of the installation relating to a failure to create the emessaging.war file, you will have to create the emessaging.war file manually. The error usually occurs because the "jar" command is not on your PATH; type "jar" to confirm this. If you do not
51 Installing e-Messaging
have the jar command available then you need to install a JDK (Java Development Kit) 1.5 or later onto your server. Ensure that the JDK that you download and install matches the architecture of your server. To create the emessaging.war file then navigate to the emessaging installation core.war folder (e.g. /opt/PBBI_CCM/e-Messaging/core.war) then type the following command and press enter:
jar cvf../emessaging.war *
This will create the emessaging.war file that you can deploy into the WebSphere Application Server. See the Deployment section in this guide. 23. The installation is now complete.
24. Before starting the application server ensure that the DISPLAY environment variable is not set. You can do this using one of the following: commands. – for the 'C' shell: unsetenv DISPLAY – for the Bourne, bash or Korn shells: unset DISPLAY 25. If the built-in Tomcat was installed as part of the e-Messaging installation then navigate to the Tomcat folder under the installation root folder (e.g. /opt/PBBI_CCM/e-Messaging/Tomcat) and execute the following commands:
EM_CATALINA_HOME=$PWD export EM_CATALINA_HOME cd bin chmod 755 *.sh
To start e-Messaging under the built-in Tomcat then navigate to the Tomcat/bin folder under the installation root folder (e.g. /opt/PBBI_CCM/e-Messaging/Tomcat/bin) and execute the following command:
./startup.sh
52 Installing e-Messaging
Uninstalling on Solaris, AIX, Red Hat Linux and Suse zLinux
| To uninstall e-Messaging on Solaris, AIX, Red Hat Linux and Suse zLinux: 1. Navigate to the directory where e-Messaging is installed (e.g. /opt/PBBI_CCM/e-Messaging). 2. If you are using the built-in Tomcat, remember to stop this first by navigating to the Tomcat directory (e.g. /opt/PBBI_CCM/e-Messaging/Tomcat) then executing the following commands:
EM_CATALINA_HOME=$PWD export EM_CATALINA_HOME cd bin ./shutdown.sh
3. Run the uninstall script from the directory where e-Messaging is installed.
./uninstall -c
4. The Uninstall Confirmation dialog displays.
Are you sure you want to completely remove e-Messaging and all of its components?
Yes [y, Enter], No [n]
Type y to continue. 5. The Tomcat reminder dialog appears. Click Next to continue.
If you are using the bundled Tomcat, make sure it is not running before uninstalling the product.
Proceed [1], Cancel [2]
Type 1 to continue. 6. The Uninstall message is displayed. Wait while e-Messaging is being uninstalled.
Uninstalling e-Messaging 1.4M8...
7. The Uninstall Status Confirmation message appears.
e-Messaging was successfully removed from your computer.
Finishing installation...
53 Setting up databases
Microsoft SQL Server 2005/2008/2012 configuration
For installing the e-Messaging database, the user running the installation scripts is recommended to have full ADMIN rights (for one-time operation), as these scripts will create/drop/alter various e-Messaging tables, indexes, functions etc.
Whereas, the runtime user requires the following permissions for tables and stored procedures within the e-Messaging schema: SELECT, INSERT, UPDATE, DELETE and EXECUTE.
| To populate the database: 1. Create a folder named “mssqldb” in your drive C:\. 2. Backup and drop the e-Messaging database if it already exists. 3. Go to the e-Messaging installation directory, and browse to the scripts directory. Copy the MSSQL folder to the server where your database is installed. 4. On the server where your database is installed, open the MSSQL\Build New e-Messaging Database Schema directory then run MSSQL_create_emessaging_init_db.bat. This batch file contains your database connectivity settings entered in the installation wizard and looks similar to: osql -S172.16.12.107\MSSQL2 -Usa -Pem4dm1n -iMSSQL_create_emessaging_init_db.sql
| To upgrade database from a previous version: Use MSSQL_update_emessaging_db.bat to upgrade via the command line. This script can be found under scripts/MSSQL/Update Existing e-Messaging Database Schema in e-Messaging's installation folder. This batch file contains the database connectivity settings from your previous e-Messaging installation:
osql -S172.16.12.107\MSSQL2 -Usa -Pem4dm1n –iMSSQL_update_emessaging_db.sql
Warning: If you are upgrading from an earlier version of e-Messaging to 1.4M8, ensure that you back up your e-Messaging database before running the database update scripts. Please note that significant database updates are required in order to upgrade earlier versions of e-Messaging to version 1.4M8. This includes data migration from existing database tables into new child tables in order to support unlimited attachments outbound emails sent by e-Messaging. This also means that the database update might take several hours to complete if your e-Messaging database currently holds a lot of message data.
54 Setting up databases
Oracle 10g/11g configuration
| To populate the database: 1. Create a folder named ORADB on your drive “C”. This is where e-Messaging datafiles will be stored. 2. e-Messaging assumes that your default temporary tablespace is named TEMP. If you are using a different default temporary tablespace, please edit ORA_create_tbspc_user.sql to reflect what you have in your Oracle database. 3. Locate the e-Messaging installation folder, and browse to the scripts > Oracle > Build New e-Messaging Database Schema folder. 4. Run the ORA_create_tbspc_user.bat to create the tablespace. Note that you must edit the batch file to replace the username and password with a user that has a privilege to create tablespace (ex. system).
An example of an edited batch file contains the following texts: sqlplus system/admin@adminorcl @c:\dbbkup\ORA_create_tbspc_user.sql Note that if you created a different folder name or location in step 1, you must also edit ORA_create_tbspc_user.sql file to point to your created ORADB folder.
An example of an edited ORA_create_tbspc_user.sql file contains the following texts: CREATE TABLESPACE EM_TBSPC DATAFILE 'C:\ORADB\EM_TBSPC_01.DBF' SIZE 512M; 5. Run the ORA_create_emessaging_init_db.bat. Please check that this batch file contains the correct username and password you have chosen and entered in the e-Messaging installation steps. An example of an edited batch file contains the following lines: sqlplus emessaging/admin@adminorcl @D:\dbbkup\ORA_create_emessaging_init_db.sql
| To upgrade database from a previous version: 1. Go to your e-Messaging installation directory, and browse to the scripts / Oracle /Update Existing e-Messaging Database Schema directory. 2. Run ORA_update_emessaging_db.bat. Please check that this batch file contains the correct username and password you have chosen and entered in the e-Messaging installation steps.
An example of an edited batch file contains the following lines sqlplus emessaging/admin@adminorcl @D:\dbbkup\1.01\ORA_update_emessaging_db.sql
55 Setting up databases
Warning: If you are upgrading from an earlier version of e-Messaging to 1.4M8, ensure that you back up your e-Messaging database before running the database update scripts. Please note that significant database updates are required in order to upgrade earlier versions of e-Messaging to version 1.4M8. This includes data migration from existing database tables into new child tables in order to support unlimited attachments outbound emails sent by e-Messaging. This also means that the database update might take several hours to complete if your e-Messaging database currently holds a lot of message data
56 Deploying e-Messaging on Web application servers
This section guides you through the process of configuring your Web servers to work with e-Messaging.
Setting up e-Messaging on JBoss
This section assumes that e-Messaging has been installed correctly. For more information see “Installing e-Messaging” on page 24.
If you are deploying e-Messaging and EngageOne on the same JBoss server, then there might be a RMI port conflict. This is because e-Messaging uses port 1090 for RMI and the same port might be used by JBoss also. In that case, you are recommended to change the port number in the JBoss environment. To change the port, open the JBoss\server\
IF YOU ARE PLANNING TO ACCESS E-MESSAGING WEB SERVICE API FROM A REMOTE SERVER, THEN YOU WILL HAVE TO MAKE SOME ADDITIONAL CONFIGURATION CHANGES FOR JBOSS. PLEASE REFER THE “REST WEB SERVICE APIS -> OUTBOUND PROFILE SETTINGS -> RESTRICTING API ACCESS” SECTION OF THE E-MESSAGING REFERENCE GUIDE.
57 Deploying e-Messaging on Web application servers
JBoss 5.1.0 configuration
| To configure an existing JBoss 5.1.0 server to run with e-Messaging:
1. Copy the core.war folder from IF UPGRADING FROM AN EARLIER VERSION OF
3. Populate the database you are using. For more information see “Setting up databases” on page 54. 4. Start your JBoss server.
58 Deploying e-Messaging on Web application servers
JBoss EAP 6.2.0 configuration
| To configure an existing JBoss EAP 6.2.0 server to run with e-Messaging: 1. Copy the core.war folder from
59 Deploying e-Messaging on Web application servers
iv. In the
Note: After deploying e-Messaging on JBoss EAP 6.2.0, you need to apply some configuration changes to integrate e-Messaging with EngageOne. You need to update the servlet.properties and engageone.properties files located at
60 Deploying e-Messaging on Web application servers
| To configure an existing WildFly 8.0.0 server to run with e-Messaging: 1. Copy the core.war folder from
61 Deploying e-Messaging on Web application servers
Setting up e-Messaging on Tomcat
Tomcat 6.0 is bundled with e-Messaging's installation package. Selecting the Tomcat component during installation sets up a new instance of Tomcat on your machine and pre-configures the server to run with e-Messaging. Tomcat 6.0 configuration
| To configure an existing Tomcat Server to run with e-Messaging: 1. Locate your Tomcat 6.0/conf folder. Create an XML file of the specified name at the specified location: Tomcat 6.0/conf/Catalina/localhost/emessaging.xml” 2. Insert the following line into your newly created emessaging.xml file:
3. Save the file. The name for this file will IF UPGRADING FROM AN EARLIER VERSION OF be the context path when running E-MESSAGING, YOU MUST FIRST REMOVE THE e-Messaging. For example, if saved as EXISTING LICENSE MANAGEMENT FILES emessaging.xml, use (G1LICVAL.DLL, http://localhost:8080/emessaging/... to JAVALICENSEVALIDATORACCESS.DLL, access the solution. LIBEAY32.DLL, SSLEAY32.DLL, XERCES-C-LICENSE.DLL, MSVCP71.DLL AND 4. Populate your database. For more MSVCR71.DLL, G1LICGEN.DLL, G1LICVER.DLL, information, see “Setting up databases” JLICVER.DLL, MSVCP71.DLL, AND on page 54 to configure the database XERCES-C_2_7-G1LM.DLL) FROM THE you are using. TOMCAT BIN FOLDER IN ORDER FOR E-MESSAGING TO RUN. 5. To enable Unicode character request handling support, add the URIEncoding attribute to your HTTP connector defined in the
An example is shown as below:
62 Deploying e-Messaging on Web application servers
6. Start the Tomcat Server.
NOTE THAT "LOCALHOST" IS THE DEFAULT HOST AND "8080" IS THE DEFAULT PORT BUT THIS CAN BE CONFIGURED IN THE SERVER.XML FILE FOUND IN THE CONF FOLDER OF TOMCAT.
IF YOU ARE PLANNING TO ACCESS E-MESSAGING WEB SERVICE API FROM A REMOTE SERVER, THEN YOU WILL HAVE TO MAKE SOME ADDITIONAL CONFIGURATION CHANGES FOR TOMCAT. PLEASE REFER THE “REST WEB SERVICE APIS -> OUTBOUND PROFILE SETTINGS -> RESTRICTING API ACCESS” SECTION OF THE E-MESSAGING REFERENCE GUIDE.
63 Deploying e-Messaging on Web application servers
Setting up e-Messaging on WebSphere
WebSphere 7.0/8.5.5 configuration
| To configure an existing WebSphere 7.0.0.x/8.5.5 Server to run e-Messaging:
1. Run WebSphere's administrative IF UPGRADING FROM E-MESSAGING VERSION 1.3 console. This will open the Integrated OR EARLIER, YOU MUST REMOVE THE EXISTING Solutions Console in your Web browser. LICENSE MANAGEMENT FILES (G1LICVAL.DLL, JAVALICENSEVALIDATORACCESS.DLL, Enter your WebSphere username and LIBEAY32.DLL, SSLLEAY32.DLL, password. Click Log In. XERCES-C-LICENSE.DLL, MSVCP71.DLL AND MSVCR71.DLL, G1LICGEN.DLL, G1LICVER.DLL, 2. Click ApplicationTypes under Applications, JLICVER.DLL, MSVCP71.DLL, XERCES-C_2_7-G1LM.DLL) FROM THE WEBSPHERE then click WebSphere enterprise BIN FOLDER IN ORDER FOR E-MESSAGING TO RUN. applications. If there is an emessaging.war already installed, select it and click Stop if it is running. When emessaging.war has stopped, select it and click Uninstall. After the emessaging.war has been uninstalled, click Save to save the new configuration. 3. Click New Enterprise Application under Applications > New Application.
4. Select Local File System if the browser instance is local to the system on which e-Messaging is being deployed, or select Remote File System if it is remote. 5. Click the Browse button and browse to the e-Messaging installation folder found in C:\Program Files\PBBI CCM\e-messaging on a Windows server and /opt/PBBI_CCM/e-messaging on a Solaris, Linux, or AIX server. Select the emessaging.war file; this file is required by WebSphere to deploy a web archive file instead of an exploded Web application. Note: While deploying on WebSphere 8.5.5, in place of the following screen, the File Upload dialog box will appear. You can use that dialog box to browse the emessaging.war file.
64 Deploying e-Messaging on Web application servers
Click Next. 6. The Preparing for the application installation screen appears:
Select FastPath and click Next. 7. A series of Install New Application screens appear:
Step 1: Select your installation options. Click Next.
65 Deploying e-Messaging on Web application servers
8. Step 2: Map modules to servers. Click Next.
66 Deploying e-Messaging on Web application servers
9. Step 3: Map virtual hosts for Web Modules. Click Next.
10. Step 4: Map context roots for Web modules i. Type emessaging into the Context Root field.
ii. Click Next.
11. Step 5: A summary of installation options is shown. Click Finish to start the installation.
12. Wait while the e-Messaging application is being installed.
67 Deploying e-Messaging on Web application servers
13. After a successful installation, click the Save link in the bottom part of the screen.
14. Click WebSphere enterprise applications under Applications > Application Types. Click the emessaging_war link under the Name column.
68 Deploying e-Messaging on Web application servers
15. Click the Manage Modules link.
16. Click the e-Messaging link under the Module column
69 Deploying e-Messaging on Web application servers
17. C h a n g e t h e Class loader order to Classes loaded with local class loader first (parent last). Click Apply.
18. A confirmation message regarding the “
20. Select emessaging.war in the list by IF YOU ARE RUNNING WEBSPHERE WITH THE EJB selecting the check box. Click Start to SERVICE PACK APPLIED, YOU WILL NEED TO deploy the application. REMOVE THE FILE XML-APIS-1.3.04.JAR FROM THE CORE/WEB-INF/LIB FOLDER. THIS CAN EITHER BE 21. A confirmation message that DONE INSIDE THE WAR FILE PRIOR TO DEPLOYMENT OR IN THE WEBSPHERE’S INSTALLED e-Messaging has been started APPLICATIONS FOLDER AFTER DEPLOYMENT. successfully is shown. IF CHOOSING THE LATTER METHOD, THE FILE SHOULD BE IN:
After the e-Messaging database tables WHEN E-MESSAGING DEPLOYED ON WEBSPHERE are configured, access the e-Messaging THE DATA THAT GETS WRITTEN INTO through the following URL: E-MESSAGING’S EMSGLOL4J.LOG FILE IS LESS DETAILED THAN WHEN E-MESSAGING IS DEPLOYED http://
70 Deploying e-Messaging on Web application servers
ii. Navigate to Servers -> Server Types -> WebSphere Application Servers -> server-name -> Java and Process Management -> Process Definition -> Java Virtual Machine -> Custom Properties. Here,
71 Deploying e-Messaging on Web application servers
Setting up e-Messaging on WebLogic
WebLogic 10.3 configuration
| To configure an existing WebLogic 10.3 Server to run with e-Messaging:
1. Populate the database you are using. For For Windows Installation Only more information see “Setting up databases” on page 54. IF UPGRADING FROM AN EARLIER VERSION OF 2. Open a Web browser and access the E-MESSAGING, YOU MUST FIRST REMOVE THE WebLogic control panel. EXISTING LICENSE MANAGEMENT FILES (G1LICVAL.DLL, JAVALICENSEVALIDATORACCESS.DLL, 3. Type in the WebLogic username and LIBEAY32.DLL, SSLEAY32.DLL, password to proceed to the control XERCES-C-LICENSE.DLL, MSVCP71.DLL AND panel. MSVCR71.DLL) FROM THE WEBLOGIC DOMAIN (E.G. “C:\BEA\WEBLOGIC92\USER_PROJECTS\DOMAINS\E 4. In the Administration Console click the M_DOMAIN”) IN ORDER FOR E-MESSAGING TO RUN. Deployments link from the Domain structure tree.
72 Deploying e-Messaging on Web application servers
5. Click Install to proceed.
6. Locate the e-Messaging installation folder and then locate the core.war folder.
7. Click Next.
8. Choose Install this deployment as an application.
73 Deploying e-Messaging on Web application servers
9. Click Next.
10. Choose the Security and Source Accessibility options according to the following screenshot (default options):
11. Click Next.
74 Deploying e-Messaging on Web application servers
12. Choose Yes, take me to the deployment's configuration screen option and click Next.
13. View the installation configuration settings and Click Save.
14. The following screen appears.
15. Start Admin Server for the domain in which e-messaging application is deployed. 16. Open Admin Console for the domain in which e-messaging application is deployed.
75 Deploying e-Messaging on Web application servers
17. Select the check-box against the name of the application and then click Start, followed by Servicing all requests.
18 . T h e S tart requests have been sent to the selected deployments message (in green text) will appear:
19. On Solaris, if you are facing problems while generating reports on e-Messaging, please follow the steps below: i. Stop Weblogic Server if it's already running. ii. Issue command "unset DISPLAY".
76 Deploying e-Messaging on Web application servers
iii. At the end of the setDomainEnv.sh file add the following: JAVA_OPTIONS="${JAVA_OPTIONS} -Djava.awt.headless=true" iv. Start Weblogic Server. v. Generate the report in e-Messaging. 20. If you are using a non-English language and some of the characters are not displaying correctly, add the following line at the end of setDomainEnv.sh and restart weblogic server: JAVA_OPTIONS="${JAVA_OPTIONS} -Dfile.encoding=utf8"
Additional configurations for e-Messaging upgrade
You also need to configure some additional settings, if you are upgrading your e-Messaging application from a previous version to 1.4M8. To do so, complete the following steps: 1. In the e-Messaging installation directory, navigate to the ...\PBBI CCM\e-Messaging\core.war\WEB-INF folder. 2. Open the security.xml configuration file in edit mode and replace the following tag:
77 Deploying e-Messaging on Web application servers
4. Open the outboundProcessor.properties file in edit mode and append the following property: # Special characters not allowed in password input field spl.chars.not.allowed=` ~ * < > . ! ' ; :
Providing access to remote Data Flow / Generate and Designer servers
e-Messaging includes a message scheduling function. The scheduling function provides business users with the possibility to manage sending outbound messages from a simple browser interface. Scheduled jobs in e-Messaging can optionally call Data Flow to prepare uploaded data for Designer and/or call Designer to format message content. For a given scheduled job, the business user can select preconfigured Data Flow Plans and Designer Templates (that have been associated with e-Messaging) to process their uploaded data prior to e-Messaging sending the composed content as email or SMS messages.
The Data Flow Server (DFS) and Designer server may reside on a different server to where e-Messaging. If e-Messaging is expected to communicate with DFS and/or Designer services on a remote server, a listener application should be installed on the remote server. At runtime, the listener will listen for incoming requests from e-Messaging and execute the requests on the DFS/Designer server.
| To install the listener application on the remote server: 1. Go to the
78 Deploying e-Messaging on Web application servers
Updating the listener properties file
The remote folder comes with a properties NOTE THAT THIS PROPERTIES FILE file ("service.properties") for storing (SERVICE.PROPERTIES) IS A MIRROR OF THE configurable settings. These settings include E-MESSAGING APPLICATION'S OWN the RMI port on which the listener will “REMOTESERVICE.PROPERTIES” FILE. THE VALUES listen, and the service names for the Designer ASSIGNED TO THE PROPERTIES DEFINED IN THESE / DFS service classes. The properties file also TWO PROPERTIES FILES SHOULD BE THE SAME TO contains the list of allowed DFS, Designer, and ENSURE SEAMLESS COMMUNICATION BETWEEN Post-Designer executable commands. THE E-MESSAGING APPLICATION AND THE Commands not found in the list will not be LISTENER APPLICATION. UPDATING THE PROPERTIES FILES WILL REQUIRE A executed by the service classes. RESTART OF THE LISTENER APPLICATION.
Starting Open Office service
To enable the conversion capabilities of THE OPENOFFICE SERVICE SHOULD BE INSTALLED e-Messaging, Open Office Service 3 has to be LOCALLY ON THE SAME SERVER AS E-MESSAGING started manually. FOR SUCCESSFUL OPERATION. To start the service in Windows, execute the command below:
soffice -headless -accept="socket,host=
The
To load balance conversion requests, multiple instances of the Open Office service can be started. To benefit from performance gains, it is recommended that only a single instance runs on each machine. Additional instances can be started on different machines by manually executing the command above.
Due to limitations in the Open Office implementation, a service may terminate unexpectedly while converting specific corrupted input files. As a work around, you may opt to loop the execution of the start-up command so that the service can immediately restart should this unexpected event occur.
79 Deploying e-Messaging on Web application servers
| To loop the execution: 1. Create a batch file that contains the following script:
c: cd c:\Program Files\OpenOffice.org 3\program :loop echo off echo soffice started %date% %time% echo on soffice -headless -accept="socket,host=
2. Run the batch file on the machines you AFTER INSTALLING OPEN OFFICE, YOU WILL NEED would like to start the Open Office TO ACCEPT ITS SOFTWARE LICENSE AGREEMENT Service. BEFORE YOU CAN USE THE OPEN OFFICE SERVICE. TO DO THIS, OPEN AN OFFICE APPLICATION (E.G. OPENOFFICE.ORG WRITER), AND ACCEPT THE LICENSE AGREEMENT. BEFORE RUNNING THE SCRIPT, CLOSE ALL OPEN OPEN OFFICE APPLICATIONS (E.G. OPENOFFICE.ORG WRITER) AND ALSO END THE To start the Open Office service on Solaris, SOFFICE.BIN AND SOFFICE.EXE PROCESSES, USING WINDOWS TASK MANAGER. execute the command below:
soffice -headless "-accept=socket,host=
The
soffice -headless "-accept=socket,host=0,port=8100;urp"
To load balance conversion requests, multiple instances of the Open Office service can be started. To benefit from performance gains, it is recommended that only a single instance runs on each machine. Additional instances can be started on different machines by manually executing the command above.
Due to limitations in the Open Office implementation, a service may terminate unexpectedly while converting specific corrupted input files. As a work around, you may opt to loop the execution of the start-up command so that the service can immediately restart should this unexpected event occur.
80 Deploying e-Messaging on Web application servers
| To loop the execution create a shell script that contains the following:
#!/bin/sh
cd
while [ true ]
do
echo "`date`: Starting soffice"
./soffice -headless "-accept=socket,host=
echo "`date`: soffice failed"
done
81 Initial Setup
First log-in
e-Messaging includes a default Super User account. Upon installation, this is the only account which you can use to login to e-Messaging.
| To login: 1. Access the deployed e-Messaging application by opening a browser and pointing it to: http://
Username: super Password: tomcat 3. You will be presented with the Vendor Creation page.
Creating the initial vendor
After installation, e-Messaging will not yet have a vendor setup. Upon login, the Super User will be forced to create a new vendor before being allowed access to the other pages within the system.
| To create a vendor: 1. Select the Vendor Type from the dropdown menu.
Licensed - configured for single vendor environment, e.g. a customer has purchased an e-Messaging software license.
Hosted - configured for multiple vendor hosting, e.g. in a hosted environment or a service bureau customer purchasing a software license to set up different end-customers to be able to use e-Messaging independently. 2. Enter a name in the Vendor Name field. This will be used for identifying the vendor across the system.
82 Initial Setup
3. Enter the address information. 4. Click the Create Vendor button to add the new vendor. 5. Refer to the e-Messaging User's Guide for details on navigating through the e-Messaging application, including configuration and the steps for changing the Super User's default password.
83 Configuration settings
This section describes how e-Messaging can be configured to suit your organizational or individual requirements. Configuration settings can be defined at the vendor, system, operational or user management levels.
System configuration
e-Messaging can be configured to support your organization's specific site requirements. What you can see and do with the application depends on the options selected at installation and the configuration settings defined for you by the System Administrator or your Manager. Installation options selected
During installation, the following options are defined: • The date and date-time format can be set during installation. The default is dd-MMM -yyyy and dd-MMM-yyyy, HH-mm '[GMT' Z']'. • Database - This latest release supports Microsoft SQL Server and Oracle. • SMTP Mail Settings - SMTP Host and Port are defined. • PDF Converter Settings - OpenOffice Converter Host and Port are defined. • Root Folder Settings (Root) - Base location for vendor specific operations. Configuration settings defined
After installation, your System Administrator or Manager defines the following groups of settings: • Vendor and System - Defines the roles in the company, the default secret questions for forgotten password, the initial user of the company that can create other users, vendor environment parameters, gateways and optionally integration with existing user authentication systems using LDAP. • User Management - Defines users belonging to a company and the role for each user. • Operational - Defines the Inbound and Outbound Profiles to be used by your company. These profiles determine how inbound and outbound messages are to be processed. This also covers settings for using Data Flow Server (DFS) and Generate when these are to be controlled by the e-Messaging Scheduled Jobs function.
84 Configuration settings
The following sections provide a short introduction to some of these settings and how they affect what you can see and do within e-Messaging.
The System Configuration section discusses the basic system requirements for you to get started and perform basic functions of the application. Other sections will provide information on how to login, know what roles and permissions are set, basic guidelines on working with menus and navigating through the Web pages.
The following sections describe prerequisites required prior to using e-Messaging. e-Messaging languages
The e-Messaging application detects your browser’s default language setting and displays e-Messaging Web pages in that language, if they are available. By default e-Messaging comes with user interfaces in the following languages: • Chinese (Simplified) •English • French (Canadian) •German • Japanese • Portuguese (Brazilian) • Spanish (Unified)
New language interfaces can easily be added to e-Messaging. Refer to the e-Messaging Reference Guide for instructions on how to add new language resource bundles. Receiving messages
In order for your company to receive messages and process them (e.g. categorize, convert content, index and archive), Inbound Profiles must be set-up in the application. This will define the Gateway through which e-mail and SMS messages will be routed as well as define the processing rules to be performed on the message received. e-Messaging interfaces with e-mail servers using the POP3 or IMAP protocol for retrieving inbound messages. By default e-Messaging receives inbound SMS messages in one of three ways: • using a callback URL in the case of Clickatell • via an SMPP inbound listener that connects to an SMS gateway directly over TCP/IP • via the Java API described in the e-Messaging Reference Guide
To receive inbound SMS messages via SMPP, an inbound profile should be configured as outlined below.
85 Configuration settings
The e-mail account from which e-Messaging is to collect inbound messages must be specified. In the case of processing inbound SMS messages, an SMS API ID is required. The SMS API ID is provided by the SMS gateway (www.clickatell.com is the default gateway). Shown below is a portion of an Inbound Profile set-up page.
In order for you to access the content from these messages and process them via a workflow, your login name or the user group (Role) you belong to must be associated with these Inbound Profiles. Refer to the Roles and Permissions section on page 91 for more details on associating Inbound Profiles. Sending messages
In order for your company to compose and send messages, Outbound Profiles must be set-up in e-Messaging. This will define the Gateway server to send messages through and the processing rules for composing, digitally signing, sending and archiving messages. The Gateway server could be an SMTP server or one of the supported connections to an SMS Gateway: • SMSo - to send messages via SMTP to the Clickatell SMS Gateway. • SMPP_transmitter or SMPP_transceiver - to send messages directly to an SMS gateway via SMPP.
86 Configuration settings
• Custom - to pass message content to an SMS gateway via the Java SMS API that is described in the e-Messaging Reference guide.
Gateways that need to be defined for sending messages.
For SMSo the outbound profile SMS APP ID configuration is done as shown below in this section of a sample of an Outbound profile configuration.
For Outbound Profiles that reference SMPP_transmitter and SMPP_transceiver gateways (SMPP-SMS), the configuration is the same as above except that the Clickatell username and password do not have to be specified.
For SMPP-SMS delivery acknowledgements to be received and handled correctly, there needs to be an Inbound Profile that references either an SMPP_receiver or SMPP_transceiver gateway. In the Inbound Profile that references an SMPP_receiver gateway, Workflow Bounce must be checked and the SMPP_transmitter gateway, that is to send SMPP-SMS messages, must be specified. This is known as an inbound-to-outbound mapping. Shown below is the section of a sample SMPP Inbound Profile that demonstrates this inbound-outbound mapping:
Data Flow Server and/or Generate can be used to prepare data and format content for the messages sent by e-Messaging. Once Data Flow Plans and Generate Applications have been created, their details may be imported into e-Messaging. Composed output may also be processed directly by e-Messaging by writing it into the folders specified by an Outbound Profile. Alternatively, messaging campaigns can be managed and scheduled by non-technical users through the Scheduling Web browser interface of e-Messaging. Scheduling jobs can use Data Flow Plans (for data preparation and formatting) and Generate Applications (for message content formatting). However, you can also schedule jobs without the use of Data Flow or Generate by either uploading directly the DIJ files or specifying their location on the
87 Configuration settings
server.Refer to the Operational Settings for more details on setting up Data Flow Plans and DOC1 Applications. They must also be enabled for your company in the Vendor Environment Settings page.
In order for you to be able to schedule jobs for specific Outbound Profiles and view/edit them, your login name or the user group (Role) you belong to must be associated with these Outbound Profiles. Refer to the Roles and Permissions section on page 91 for more details on associating Outbound Profiles.
Indexing and archiving messages e-Messaging can be configured to prepare both in- and out-bound e-mail and SMS messages for archiving in Vault. Archive preparation functions performed by e-Messaging include: • Automatic or minimum click indexing of e-mail and/or SMS content. Including the generation of journal files for Vault in the required format • Single instance storage of messages addressed to more than one recipient • Optional conversion of content including e-mail attachments to PDF prior to archiving including the following options: • Extraction of attached ZIP files prior to conversion, including nested ZIP files • Extraction of MS Outlook rich text content (MS-TNEF / winmail.dat files) prior to conversion • Conversion of HTML to MHT format - embedding images (already embedded or externally referenced) to ensure version control of complete content • Safely batching up content into Vault “collections” for efficient loading, compression, storage and retrieval. Refer to the Vault Customizing Guide for additional information on the “collections” format.
Before you begin working with e-Messaging, be sure that Vault has been configured to work with e-Messaging. Refer to the e-Messaging Reference Guide for instructions on configuring Vault. Similarly, be sure that e-Messaging has been configured to prepare message content for archiving in Vault. This is done through the Vault settings section of the Inbound Profile page. Vault must also be enabled for your company in the Vendor Environment Settings page.
88 Configuration settings
Working with workflows e-Messaging provides two workflow options: 1. Basic workflow built into the solution to allow users to: i. Manage content conversion for messages that fail to convert automatically or simply check conversion prior to archiving. ii. Index creation for inbound messages - when automated indexing is not possible. iii. Manage bounced messages. iv. Manage response creation for inbound messages including the automatic categorization and routing of messages based on their content. v. Close bulk workflows that are open. 2. Provide file based "XML workflow objects" that can be loaded into a third-party workflow solution. When this option is selected the built-in workflow (1 above) would still get used for content conversion and index creation for inbound messages - when automated conversion and / or indexing is not possible.
The workflow options enabled for your company are specified on the Vendor Environment Settings page.
The built-in (or integrated) workflow options allow you to perform the actions as listed above. However, restrictions can be imposed on what workflow actions a user can execute for specific Inbound Profiles associated to their login name or the user group (Role) they belong to. Refer to Roles and Permissions section on page 91 for more details on associating workflow actions in Inbound Profiles.
Working with workflows may require you to view content in PDF format. Hence, it is recommended that you have Adobe Acrobat 8 installed in your work station. Some Workflow pages also use HTML iFrames. For example, when viewing message content on the Workflow Conversion or Workflow Indexing pages, another instance of e-Messaging appears in the iFrame. Generating reports e-Messaging provides a comprehensive and graphic reporting capability. The content of the reports generated is restricted to the messages received or created by Inbound and Outbound Profiles associated directly to a user’s login name or the Role assigned to their login name.
89 Configuration settings
Refer to Roles and Permissions section on page 91 for more details on associating reports to Inbound and Outbound Profiles.
Login and security
For you to be able to login to e-Messaging, you must either have received an e-mail providing you with your login and one time password or you have been given instructions that you can use your corporate login to access the application.
| To login: Click on the e-Messaging icon displayed on your desktop if it is installed on your workstation, select Start/All Programs/PBBI CCM/e-Messaging or click on the e-Messaging URL that will be provided to you by your System Administrator or Manager.
The Start/All Programs/PBBI CCM/e-Messaging option is only applicable to Windows platforms. The user has the option to change the program grouping name (i.e. PBBI CCM) during the installation. The convention in accessing the application is “http://
Enter Username and Password indicated in user notification e-mail.
Password is case sensitive.
The application has its own built-in security REFER TO THE E-MESSAGING REFERENCE GUIDE for managing users, roles, authentication, FOR MORE DETAILS ON LDAP. access control and encryption. However, it can also integrate with existing user authentication systems using LDAP.
If you are using the application's built-in user management module and your login NO PASSWORD CHANGE IS ALLOWED IN E-MESSAGING IF YOU ARE USING YOUR credentials (including one time password) CORPORATE LOGIN TO ACCESS THE APPLICATION. are authenticated properly, you will immediately be asked to change your password.
90 Configuration settings
After your password has been accepted, the Home page will be displayed and you can now begin working with e-Messaging.
Roles and permissions
Roles and permissions play a very important role in what you see, gain access to and functions you may perform in e-Messaging. There are several levels in which this is implemented across the application.
Role based restriction
With role based restriction, the pages you are allowed to access are limited by the privileges assigned to the role that your user login is attached to.
91 Configuration settings
| To view the role attached to you: Select Home/My Settings.
Roles attached to user
| To view the privileges assigned to the role: From the My Settings page, click on View description of roles button.
Privileges of the role Role name
92 Configuration settings
Vendor based restriction
With vendor based restriction, the pages and reports you are allowed to view / update is filtered by the vendor assigned to you when your login was created. It's easy to check what vendor you belong to as it is normally displayed as a header on most pages you can navigate to.
User type based restriction
There are three types of users: initial user, regular user and super user. The initial user is the default user created automatically when a vendor is created while the regular users are the users created by the initial user or the super user for the specified vendor. The initial user has the highest privilege settings for a vendor. It is set to "All / Default" role. On the other hand, the super user is the single user that has the highest privilege settings in e-Messaging. The super user can access data from all vendors defined in the application.
If you are a super user, you can filter by vendor the data you want to view or work on. Initial users or regular users do not have this facility displayed on their pages because they are associated with a single vendor.
Profile based restriction This filter option is only visible to super users. The Inbound and Outbound profile pages specify how inbound and outbound messages are to be processed by e-Messaging. You can set-up a vendor to have several Inbound and Outbound Profiles. Within each of these profiles, permissions are defined for specific tasks.
| To quickly view the Inbound Profiles attached to you: Select Workflow from main menu tabs then click on the Inbound Profile dropdown button.
List of inbound profiles associated with the user.
93 Configuration settings
| To view a specific Inbound Profile: Select Configure/Inbound Profiles and then select the Inbound Profile name from the Inbound Profile page.
Your privileges to view or edit the contents of the Inbound Profile page is dependent on the "EditInProfiles" permission. If your name or role is on the left pane, you only have view rights while those on the right have both view and edit rights.
You are permitted to perform the specific workflow task only if your name or your role has been associated explicitly to the task (those on the right pane).
| To view a specific Outbound Profile: Select Configure/ Outbound Profiles and then select the Outbound Profile name from the Outbound Profile page.
You are permitted to send jobs only if your name or your role has been associated explicitly to the task (those on the right pane).
Your privileges to view or edit the contents of the Outbound Profile page is dependent on the “EditOutProfiles” permission. If your name or role is on the left pane, you only have view rights while those on the right have both view and edit rights.
94 Configuration settings
Menus and screen navigation
There are a number of alternative ways by which you can get to the page you want to view or create / update transactions in the e-Messaging application. The alternative you select will largely depend on your experience with other applications and your personal preference. Regardless of the alternative you select, the look and feel of the application as well as the navigation options has been standardized across all the Web pages to help reduce the learning curve for first time users of e-Messaging.
If your company owns the application REFER TO THE E-MESSAGING REFERENCE GUIDE (licensed owner), the branding and colors of FOR INSTRUCTIONS OR CONTACT YOUR SYSTEM all user interfaces can easily be modified to ADMINISTRATOR TO APPLY THE CHANGES. suit your particular company needs.
All interfaces comply with W3C guidelines for accessibility.
All interfaces function in Web browsers with Javascript enabled or disabled.
Home page
The Home page is the very first page that will be displayed once your login and password has been accepted by the application.
Use these tabs to select the main menu options to work on.
When a tab is selected, you can click directly on the sub-menu options displayed to bring you to the page you need to view.
95 Configuration settings
Menu options available
Depending on the roles associated with your user login, a number of sub-menu options may not be available to you. e-Messaging implements this by either not showing the sub-menu option on the screen or graying it out. The manner of implementation is defined in the Roles page. Shown here is an example of a grayed-out An example of a implementation of denied sub-menus. grayed-out menu option.
The Help sub-menu option will be THE HELP PAGES WILL NOT DISPLAY ON visible to all users. Clicking on the link will JAVASCRIPT-DISABLED BROWSERS. YOU WILL open a new browser loaded with HAVE TO ENABLE JAVASCRIPT TO VIEW THE HELP e-Messaging’s help topics. TOPICS.
96 Configuration settings
Page layout and navigation
The typical page that you will work with will have the following page lay-out and navigation options
1 Application logo 3 Highlighted Main menu tabs
2 Main menu tabs
5 Search icon
7 Links 4 Dropdown icon
6 Sorting icon
10 Highlighted 8 Action button 9 Sub-menu sub-menu option options
11 Logged in user
1. Application logo - This is the default e-Messaging logo. If your company is the licensed owner of the e-Messaging application, it can be customized for your company as needed. Contact your System Administrator for details. 2. Main menu tabs - This displays the main menu options available. You can click on any of the tabs while working on a page. This will take you to the tab with the sub-menus displayed. 3. Highlighted main menu tab - This indicates to which main menu the current page belongs. 4. Dropdown icon - You can click on this icon to select from a list 5. Search icon - You can click on this icon to initiate a search for records that meet the filter conditions you have specified. 6. Sorting icon - This indicates how the records are sorted for the specified field. You can click on this button to reverse the current sorting.
97 Configuration settings
7. Links - These allow you to go to the details of the displayed record. This is underlined in pages with multi-record tabular displays and in regular blue font in single record display pages. 8. Action buttons - You can click on this icon to trigger an action based on the current record or records you are working on. 9. Sub-menu options - This displays the sub-menu options available for the highlighted main menu tab. You can click on any of the sub-menu options while working on a page. This will take you directly to the selected page. 10. Highlighted sub-menu option - This indicates the page you are currently working on. 11. Logged in user - This is the name of the user currently logged in.
When you click on another Tab or Sub-menu option and you want to return to the previous page you were working on, you can click on the previous page icon of your Web browser.
View only page
Some pages are view only pages. Typical examples of these are description pages.
Click on this button to return to the current page you are working on.
98 Configuration settings
Viewing tabular display pages
For multi-record tabular display pages, the maximum number of records that are displayed per view is 10, by default. On initial display of the page or after clicking on the Search icon, only the first 10 records will be displayed if there are more than 10 records to be displayed. The other records can be displayed using the Pagination toolbar or the Vertical scrollbar.
For the columns displayed, there is no maximum number of columns that can be displayed. It all depends on the width of the columns. If not all columns can be displayed on the screen, the hidden columns can be displayed using the Horizontal scrollbar.
| To view sets of records on screen: Click on the Pagination toolbar displayed below the tabular display.
Pagination toolbar
The pagination toolbar will only appear if the number of records to be displayed exceeds10.
Vendor and system settings
The Vendor and System Settings sub-menu of e-Messaging allows you to configure vendor and system parameters that are used by the application. This includes defining the roles for the company, the default secret questions for forgotten password, the initial user of the company that can create other users, vendor environment parameters and gateways. Vendor creation
e-Messaging users are normally associated with a vendor. The Vendor Creation page allows you to add a vendor in the system or edit information for an existing vendor. Only Super Users are allowed to access this page.
99 Configuration settings
On the Super User’s very first login to e-Messaging, he will immediately be redirected to the Vendor Creation page. He will need to create at least one vendor before the rest of the e-Messaging system can be made accessible.
| To create a vendor: 1. Select Home / Vendor/System Settings / Vendor Creation.
The initial display allows you to enter the information necessary to create a new vendor. 2. Select the Vendor Type from the dropdown menu. Licensed – configured for single vendor environment, e.g. a customer has purchased an e-Messaging software license. Hosted – configured for multiple vendor hosting, e.g. in a hosted environment or a service bureau customer purchasing a software license to set up different end-customers to be able to use e-Messaging independently.
100 Configuration settings
3. Enter a name in the Vendor Name field. FOR A HOSTED VENDOR TYPE, THE NAME MUST BE This will be used for identifying the UNIQUE ACROSS ALL VENDORS. NAME, ADDRESS vendor across the system. LINE 1, ADDRESS LINE 2, TOWN, REGION, POSTCODE, AND COUNTRY FIELDS ARE REQUIRED 4. Enter the address information. FIELDS.
5. Click the Create Vendor button to add ONLY THE NAME FIELD IS MANDATORY FOR A the new vendor. LICENSED VENDOR TYPE. 6. After successfully creating a vendor, you will be redirected to the Secret Questions page. Refer to the Secret Questions section on page 103 for details on how to create Secret Questions.
The creation of a new vendor will trigger the creation of a default user for this vendor (named after the specified vendor name) associated with a default role (“All/Default”).
| To edit a vendor: 1. Select Home / Vendor/System Settings / Vendor Creation.
Click this button to display vendor information.
Clicking the Change Vendor button also changes this button from Create Vendor to Edit Vendor.
2. Select the vendor name from the Filter by-Vendor dropdown menu. 3. Click the Change Vendor button. This will fill the respective fields with the selected vendor’s information. This will also change the Create Vendor button’s label to “Edit Vendor”. 4. Change the field entries you want to YOU CAN EDIT ALL VENDOR RELATED edit. INFORMATION EXCEPT FOR THE TYPE AND NAME. 5. Click the Edit Vendor button to save your changes.
101 Configuration settings
6. After successfully editing the vendor details, you will be redirected to the Secret Questions page. Refer to the Secret Questions section on page 103 for details on how to create Secret Questions.
While updating or viewing existing vendor information, you may opt to return to creating a new vendor. You can do this by choosing “[New Vendor]” from the Filter by-Vendor dropdown menu and clicking on the Change Vendor button. This will clear out the displayed information on the page and allow you to proceed with creating a new vendor.
Importing and exporting vendor information
It is possible to export the e-Messaging settings for a given vendor as a ZIP file containing both database settings and Vendor Folder Structure that can be imported into a different e-Messaging environment of the same software version as the file was exported from.
| To export a vendor: 1. Select Home / Vendor/System IF VOLUME OF DATA PRESENT IN THE "IMAGES" Settings/Vendor Creation FOLDER OR ANY OTHER FOLDER WITHIN THE 2. Select the name of the vendor to be "VENDOR" FOLDER IS VERY HIGH, YOU MAY FACE AN ISSUE WHILE DOING VENDOR EXPORT. exported using the Filter by-Vendor POSSIBILITY OF AN ISSUE IS MORE WHEN THE dropdown menu. VENDOR FOLDER IS LOCATED ON A REMOTE 3. Click the Export Vendor button. You will MACHINE. THEREFORE, IT IS RECOMMENDED TO be requested to select the location you REMOVE THE INSIGNIFICANT DATA FROM THESE FOLDERS ON REGULAR BASIS. wish to export the selected vendor’s settings to. 4. After selecting a directory click the Save button. 5. The selected vendor’s settings will be exported as a ZIP file.
| To import a vendor: 1. Select Home / Vendor/System Settings/Vendor Creation. 2. Click the Browse button and select an IF E-MESSAGING IS DEPLOYED IN WILDFLY 8.0.0, e-Messaging vendor’s settings ZIP file PLEASE MAKE SURE THAT THE VENDOR ZIP FILE TO that was exported from an e-Messaging BE IMPORTED IS PRESENT IN THE VENDOR ROOT system of the same software version. FOLDER OF THE E-MESSAGING APPLICATION. 3. Click the Import Vendor button.
102 Configuration settings
4. If a vendor of the name specified in the NOTE THAT ONLY THE VENDOR, VENDOR’S FOLDER ZIP import file already exists, all of its STRUCTURE ALONG WITH STATIC DATA (IMAGES, settings will be updated. If a vendor of STATIC ATTACHMENTS, SIGNING KEYS), the specified name does not exist then OPERATIONAL AND USER SETTINGS CAN BE one will be created. EXCHANGED BETWEEN DIFFERENT INSTANCES OF E-MESSAGING USING THIS ZIP FILE. IMPORT AND EXPORT IS DONE FOR ONE VENDOR AT A TIME AND MUST BE BETWEEN THE SAME VERSIONS OF E-MESSAGING SOFTWARE.
Secret questions
Secret Questions allow the vendor to provide a “backup password” facility for you, in case you forgot your account password. The backup password comes in the form of an answer to a question only you should know. A correct answer to a secret question validates your identity and allows the system to take steps to re-set your account password.
Users assigned with the Edit Vendor permission can access the Secret Questions page.
Viewing secret questions
Use the Filter and Search options to view existing Secret Questions.
| To view secret questions: Select Home / Secret Questions.
| To change active status: Click the active status field.
Only Secret Questions for the vendor will be Select the Language to displayed. display Secret Questions in another language.
For Super Users
A Filter by Vendor dropdown menu is displayed and you can select the vendor name and language (if necessary) before clicking Search.
103 Configuration settings
| To add a secret question: Click the Add button.
Select language for the question. Only one vendor will be displayed.
Enter additional question for the selected language.
Click Add to save the new question. Cancel will return you to the previous page.
Changing vendors
A Filter by Vendor dropdown menu is displayed and you have the option to select the vendor name and language that will be associated with the new question.
On successful addition of the new question, the system will display the updated list of Secret Questions.
104 Configuration settings
Roles
Roles define the tasks you can perform in the e-messaging application. Roles are assigned to users during user creation in the Manage User page. Alternatively roles can be mapped to the groups that a user belongs to in an LDAP system. Refer to the “Configuring LDAP” section of the e-Messaging Reference Guide for more details on the latter.
Roles are uniquely identified for each vendor in the e-Messaging application. Users assigned with Edit Vendor or Manage Users tasks can access the Roles page.
You can view the Roles page by clicking the Roles link under the Vendor/System Settings column on the Home Page.
This page will allow you to do the following: • Add a new role • Edit the privilege settings of existing users
The Roles for Vendor page contains a table which displays information on the particular privileges or tasks that a user can perform if mapped to the different roles.
The Name column lists Checkmarks indicate the The upper row displays the Role names to whom ability of the user, the available privileges or you can assign various assigned to a role, to tasks that can be assigned privileges and tasks. perform tasks. to a user. You may have to scroll right to view the other privileges or task.
105 Configuration settings
Below are the privileges and tasks that can be assigned to a user:
Privileges and Tasks description
Type Description Primary Contact Allows the user to set the primary contact of the vendor. Edit Roles Allows the user to edit / create new roles for their Vendor. Send Jobs Allows the user to set up Send Jobs or call a message sending process from a command line. View Reports Allows the user to access all reports except the Audit and Error reports. View Audit Allows the user to view Audit and Error reports. Edit Outbound Profiles Allows the user to create and edit Outbound Profiles for the Vendor the user belongs to. Edit DOC1 Allows the user to create and edit Designer settings through the interfaces described in Designer Templates for the Vendor the user belongs to. Edit Data Flow Allows the user to create and edit DFS settings through the interfaces described in Data Flow for the Vendor the user belongs to. Edit Inbound Profile Allows the user to create and edit Inbound Profiles for the Vendor the user belongs to. Edit Vendor Allows the user to edit Vendor details for the Vendor that the user belongs to. Edit Gateways Allows the user to create and edit Gateway details for the Vendor that the user belongs to. Workflow Index Allows the user to index messages associated with the Inbound Profiles they have been granted access to. Workflow Close Allows the user to close Workflow Items for messages associated with the Inbound Profiles they have been granted access to. Workflow Manager Users that can be alerted by other Workflow users if they do no know how to handle a Workflow item. Workflow Expire Allows the user to modify the default expiry date (set in Inbound Profile) for messages associated with the Inbound Profiles they have been granted access to. Workflow Bounce Allows the user to manage bounced messages associated with the Inbound Profiles they have been granted access to.
106 Configuration settings
(continued) Privileges and Tasks description Workflow Delete Allows the user to delete messages or parts of messages at the indexing stage prior to archiving for messages associated with the Inbound Profiles they have been granted access to. Workflow Convert Allows the user to manage inbound messages that contain content that e-Messaging is unable to convert to the required archiving format. Teach Classifier Allows the user to create content based inbound message categories, associate users or groups with the right to respond to messages of particular categories and to manually categorize messages when the “Initial Learning” function is enabled for the categorization feature. Note that only users with the “Workflow Close” permission can be associated with a message category. Manage User Allows the user to create, edit, activate and deactivate users for the Vendor that the user belongs to. Hide Denied Functions When this option is checked, denied functions will not be visible. Gray Out Denied When this option is checked, denied functions will be grayed out. Functions
Managing user roles
Roles are created and edited for a vendor via the Roles page. Upon creation of a vendor, a default role called All / Default is also created and assigned to the initial user for that vendor. More roles can be added as needed.
THE ROLE NAME ENTRY MUST BE UNIQUE FOR THE | To add a new role: SELECTED VENDOR. 1. From the main menu, click Roles under the Vendor/System Settings section. 2. Click the Add button on the bottom of the screen. The next screen will require you to type a role name.
107 Configuration settings
3. Type a role name and select the AT THE BOTTOM OF THE SCREEN, YOU HAVE THE appropriate checkboxes which indicate OPTION TO HIDE OR GRAY OUT DENIED FUNCTIONS. the privilege settings to be associated with that Role.
Type a unique Role The Privilege Settings Name in this field. list allows you to select the privileges you may want to grant to the Role you created. You may have to scroll down to view the other available privileges. To cancel the changes and return to the role list screen, click Cancel. Select one of these options to change the view of the Privilege Settings. Functions that were Click the Save button not selected can be hidden or when you want to finalize grayed out. your work.
| To edit the privileges: 1. Click on a role name in the Roles page to open the profile of the role. The next screen displays all the privileges assigned to the selected role. 2. Click the appropriate checkboxes to define the privilege settings. 3. Once all the appropriate checkboxes have been selected, proceed to the bottom of the page. Again, you have the option to hide or gray out denied functions, and cancel or save the changes you have made.
You will be taken back to the Roles page after clicking Save or Cancel.
For Super Users
The Filter by - Vendor dropdown menu and the icon are accessible for super users.
Changing vendors
The Filter by - Vendor dropdown menu lists all the available vendors.
| To list the roles associated with a specific vendor: Click the dropdown menu. Select the desired vendor, and then click the icon.
108 Configuration settings
Initial user
When a new vendor is created, an Initial User is automatically created by e-Messaging. The user name will be the same as the vendor name and the password will be set to "default". With this, the initial user can immediately login using default username/password generated. As an Initial User, you can then create other users for the company (vendor) you are assigned to.
The Initial User has the highest privileges (defaulted to “All/Default” role) within the company and you can edit your own profile settings except for Vendor, Username and User Role.
| To edit the Initial User profile settings: Select Home / Initial User. The Vendor, Username, and User role fields cannot be modified.
YOU CAN REQUEST FOR ADDITIONAL LANGUAGE | To edit the Language field: Click the RESOURCE BUNDLES FROM YOUR SYSTEM Language dropdown menu to select from the ADMINISTRATOR. available languages.
If JavaScript is enabled in the client browser, selecting a language from the Language dropdown menu automatically updates the Secret Question dropdown menu list with a new options based on the selected language. Otherwise, click the Change Language button to effect the change. Currently, the available languages are: • Chinese (Simplified) •English • French (Canadian) •German • Japanese • Portuguese (Brazilian) • Spanish (Unified)
It is recommended to change or translate the Secret Answer when you change the Language and/or Secret Question.
You cannot change the language if there is no corresponding Secret Questions set-up for that language. Refer to Secret Questions section on page 103 for details on how to set-up Secret Questions.
| To change the set of secret questions: THE INITIAL USER CANNOT BE DISABLED AND WILL Click the Secret Questions dropdown menu to ALWAYS BE ASSIGNED THE “ALL/DEFAULT” ROLE. select from the Secret Questions available for THIS ROLE HAS ALL PRIVILEGES ALLOCATED TO the current vendor and language displayed PERFORM ALL AVAILABLE FUNCTIONS IN THE on screen. E-MESSAGING APPLICATION FOR THE VENDOR IT IS ASSOCIATED WITH.
109 Configuration settings
To save the settings click the Submit button to apply the settings. You will be redirected to the Vendor Environment setup page.
For Super Users IF JAVASCRIPT IS ENABLED, THE ASSOCIATED The Vendor dropdown menu is editable only if VENDOR INFORMATION IS DISPLAYED you are logged-in as a “Super” user. AUTOMATICALLY. OTHERWISE, CLICK THE CHANGE VENDOR BUTTON TO TRIGGER THE CHANGE IN Otherwise, the dropdown menu will be VENDOR INFORMATION. read-only.
| To change vendor: Select the desired vendor in the Vendor dropdown menu. Vendor environment
The Vendor Environment page allows you to manage the settings for a Vendor in e-Messaging. Only a Super User or a user with EditVendor privileges can access this page. You can access this page when you are diverted to the page after updating the initial user or through the application main menu.
| To access the Vendor Environment page: From the main menu select Home / Vendor/System Settings / Vendor Environment.
| To update the Vendor Environment details: The system will display your assigned Vendor settings for configuration. You can find the following Vendor Environment details:
Vendor Environment page
Field Description Enable Message Types The checkboxes allow you to specify the type of messages the vendor can send. By default, no message types are checked.
HTML – allows use of images or special formatting in the e-mail.
Text – no images or special formatting is included in the e-mail.
Multipart/Alternative – system uses both HTML and text in a single message and the e-mail client decides which type will be displayed.
Single SMS – system sends one SMS text message of up to 160 characters.
SMPP SMS – system sends single or bulk messages of up to 160 characters using SMPP protocol.
Note: if SMS length > 160 then it will not be processed and will be displayed in error logs.
110 Configuration settings
(continued) Vendor Environment page Enable CCM Components Selecting the following options allow you to specify which CCM for e-Messaging component the vendor’s e-Messaging will integrate with.
DOC1 Composition – allows Generate to be managed from e-Messaging.
Data Flow Server – allows Data Flow Plans to be managed from e-Messaging. Can only be selected if Generate (above) is selected. Integrates with Data Flow Server (DFS) for ETL processing. The output from running a DFS plan will serve as input to Generate’s content generator.
Vault – enables archive functions for this vendor. Integrates with Vault repository for archival and retrieval of messages.
EngageOne - enables tight EngageOne integration.
Workflow settings section Workflow type Integrated Workflow will allow you to use the workflow system built into e-Messaging and allows you to: • manually manage content conversion, if automated conversion is enabled but not possible • optionally verify all content conversion manually • manually index inbound messages, if automated indexing is not possible • manage bounced messages • manage response creation for inbound messages External Workflow will generate XML file-based workflow objects that you can load into a third-party workflow solution.
If you select External Workflow, Integrated Workflow can still be used to index inbound messages and manage content that fails to convert. Folder Workflow Displays the location where the external workflow objects will be written. The directory is only used if you enable External Workflow. See the e-Messaging Reference Guide for full specification of external workflow objects. Message Categorization Enables the content categorization feature for categorizing and routing inbound messages based on their content.
111 Configuration settings
(continued) Vendor Environment page
Expiration and Purge Settings section Password Expiry Sets the length of time (in months) before the system prompts the Vendor’s users to renew their passwords. Enter “0” to prevent password expiry. Permitted Login Attempts Sets the maximum number of invalid login attempts permitted before the user account is locked. Default = 3. Enter "0" for unlimited attempts. Permitted Answer Attempts Sets the maximum number of invalid attempts permitted when answering a user’s Secret Question. Default = 1. Enter "0" for unlimited attempts. Purge Process Errors Sets the number of months to keep Process Error records. Enter "0" to store records indefinitely. Purge Audit Sets the number of months to keep Audit records. Enter "0" to store records indefinitely. Purge Reports Sets the number of months to keep Reports on sent messages. Enter "0" to store records indefinitely. Purge Workflow Sets the number of days to keep closed Workflow Items. Enter "0" to store workflow items indefinitely. Purge People Sets the number of days to keep unused message recipient data in e-Messaging. Enter "0" to store unused data indefinitely.
Log file settings section Folder Log Displays the location where the vendor specific log files generated by the system get written.
Time zone settings Specify Default Time Zone Specify the vendor's default offset from GMT. This is used by the scheduling function. If a user scheduling a batch of messages has Javascript disabled in their browser then the time zone specified here will be the default for jobs scheduled by that user. If Javascript is enabled in the user’s browser then the time zone setting of the user’s browser will be the default for jobs scheduled by that user.
Click Done to save your changes. You will be redirected to the Gateways Configuration page for your Vendor.
112 Configuration settings
For Super Users
The same Vendor Environment page is shown IF JAVASCRIPT IS ENABLED IN YOUR WEB except that a Filter by Vendor dropdown list menu BROWSER, THE VENDOR ENVIRONMENT is displayed. The initial vendor settings displayed SETTINGS ASSOCIATED WITH THE SELECTED is filtered by the first vendor in the vendor list. VENDOR ARE DISPLAYED AUTOMATICALLY. Super Users can maintain vendor settings for all OTHERWISE, CLICK THE CHANGE VENDOR vendors. BUTTON TO CHANGE THE DISPLAYED VENDOR INFORMATION.
| To view vendor environment settings for other vendors:
Select a vendor from the Filter by Vendor dropdown list menu. Once the vendor has been selected and the Vendor Environment settings displayed, the Super User can edit the current settings similar to a regular user as discussed above. Gateways and servers
The Configure Gateways page allows e-Messaging users with Edit Gateways privilege to maintain external gateway settings for the e-Messaging System. A Gateway in this context could be a third party e-mail server or SMS gateway. The gateway settings allow e-Messaging to communicate with these external third party systems.
| To view gateway settings: Select Home / Vendor/System Settings / Gateways to display the Configure Gateways page. The page is automatically filtered to list all gateways managed by users associated with the vendor you belong to. By default, the list is sorted by Name in ascending order.
The gateways displayed are limited to the vendor you belong to.
Click the gateway name to edit its details.
Click to add a new Click the icons under the Used By gateway for the column to view the profiles displayed vendor. associated with the Gateway.
113 Configuration settings
| To view Outbound or Inbound Profiles associated with a specific gateway: Click the icons in the Used by column. This will display the Outbound Profiles List or Inbound Profiles List page depending on the Gateway type.
Click to return to the Configure Gateway page.
| To create a gateway setting: 1. From the Configure Gateways page, click the Add button. This will redirect you to a blank Gateway Settings page. 2. Enter the gateway Name and the Description. 3. Select the gateway type from the Gateway Type dropdown menu. Choosing an outbound type
114 Configuration settings
gateway (SMTP, SMSo, SMPP_Transceiver, or SMPP_Transmitter) will require you to fill in the Username, Password, and Confirm Password fields. SMSo is an outbound SMS Gateway. For SMSo Gateways, by default, e-Messaging expects details of an e-mail account to be entered that will be used to send SMS messages to the Clickatell (www.clickatell.com) SMTP interface. SMSi is an inbound SMS Gateway. For SMSi Gateways, by default, e-Messaging expects that the call back URL from Clickatell will be used. SMPP_Transceiver is an outbound SMS Gateway. For SMPP_Transceiver Gateways, by Default, e-Messaging expects details of an SMSC account to be entered that will be used to send/receive SMS to/from the SMSC. SMPP_Transmitter is an outbound SMS Gateway. For SMPP_Transmitter Gateways, by Default, e-Messaging expects details of an SMSC account to be entered that will be used to send SMS to the SMSC. SMPP_Receiver is an inbound SMS Gateway. For SMPP_Receiver Gateways, by default, e-Messaging expects details of an SMSC account to be entered that will be used to receive SMS from the SMSC. 4. Tick the SSL box if you want the gateway to support the Secure Sockets Layer protocol. If JavaScript is enabled in your Web browser, the Port field is automatically filled with a default port number once the gateway type is selected, but you can still change the port number manually. Note that if an e-mail server requests a TLS connection then e-Messaging automatically enables this. The Load capacity number field is for an SMPP gateway. It is the anticipated maximum message rate of the target SMS gateway in messages/second. This value is also used to specify how many messages e-Messaging will send to the SMS gateway without processing acknowledgements before pausing to let the acknowledgements be processed. See the Appendices in the Installation Guide for details of how to set up your application server with security certificates. 5. Click the Save button to save your changes or you may discard your changes by clicking the Cancel button. Either action will bring you back to the Configure Gateways page.
| To edit an existing gateway setting: From the IF JAVASCRIPT IS ENABLED IN YOUR WEB Configure Gateways page, click the hostname link BROWSER, EDITING THE GATEWAY TYPE under the Name column. This will open the CHANGES THE PORT VALUE TO THE DEFAULT Gateway Settings page where you can edit the PORT FOR THAT GATEWAY TYPE. CHANGING current values of gateway fields like Name, THE GATEWAY TYPE TO OUTBOUND (SMTP Description, Type, Port, and Username AND SMSO) REQUIRES YOU TO FILL IN THE USERNAME, PASSWORD, AND CONFIRM PASSWORD FIELDS.
115 Configuration settings
For Super Users
The same Configure Gateways page is shown except that a Filter by Vendor dropdown list menu is displayed with the initial Gateways list filtered by the first vendor in the vendor list. Super Users can maintain gateway settings for all vendors.
IF JAVASCRIPT IS ENABLED IN YOUR WEB | To view gateways for other vendors: Select a BROWSER, THE GATEWAYS ASSOCIATED vendor from the Filter by Vendor dropdown list WITH THE SELECTED VENDOR ARE menu. DISPLAYED AUTOMATICALLY. OTHERWISE, CLICK THE SEARCH BUTTON TO TRIGGER THE CHANGE IN THE LIST OF GATEWAYS DISPLAYED.
116 Appendix A – SSL connections to mail server
IBM WebSphere v7.0 and v8.5.5 with security certificates
The following is required to ensure that the IBM Websphere understands that the SSL certificate used by mail server is a trusted one.
| To set up IBM WebSphere Application Server v7.0 and v8.5.5 with security certificates for SSL connection to mail server: 1. Run the ikeyman.bat file which is located in the <%WAS_HOME%>\bin folder. 2. Click Key Database File > Open. Select key database type PKCS12 whose location is <%WAS_HOME%>\profiles\
3. Type the password WebAS; this is the default password for the Websphere Trust store.
4. Select the Signer Certificates in Key database content and select Add.
117 Appendix A – SSL connections to mail server
5. Select the data type of the certificate file you want to add and select the location where the file is located. Generally the file extensions will be *.CER or *.DER. These files can be obtained by exporting the SSL certificates from Internet Explorer.
6. Give the certificate name for the certificate being added. Ensure that the certificate name is the same as the one that is being used (while this new one was created). 7. Once the certificate is added you can view it in ikeyman. 8. Restart WebSphere.
118 Appendix A – SSL connections to mail server
Tomcat and JBoss with security certificates
| To set up the Tomcat 6.0, JBoss 5.1.0, JBoss EAP 6.2.0, and WildFly 8.0.0 application servers with security certificates for SSL: 1. Copy the server.crt certificate file to any folder. 2. Add your security certificate to your jre for java mail api with ssl go to the folder <%JAVA_HOME%>\jre\lib\security, for example C:\Program Files\Java\jre6\lib\security>
Run the following command in a command prompt:
keytool -import -file
This will update your carcert file under <%JAVA_HOME%>\jre\lib 3. Restart the Tomcat or JBoss server and configure inbound and outbound profile with SSL enabled.
119 Appendix A – SSL connections to mail server
Weblogic 10.3 application servers with security certificates
| To set up the Weblogic 10.3 application servers with security certificates for SSL connection to mail server: 1. Copy the server.crt certificate file to any folder. 2. Add your security certificate to Weblogic Server with ssl. For Windows Platform: Add your security certificate to Weblogic Server with ssl. To do this go to the folder: "
120 Appendix A – SSL connections to mail server
keytool -import -file
121 Appendix A – SSL connections to mail server
5. From the list of the servers you are using, select the one on which the e-messaging application is deployed or the one you are planning to deploy as shown below:
122 Appendix A – SSL connections to mail server
6. Under the Configuration tab, select the Keystores sub-tab. Under it in the drop-down list (next to Custom Identity Keystore) select Custom Identity and Java Standard Trust.
123 Appendix A – SSL connections to mail server
7. Provide the password of the Trust keystores. Click Save.
124 Appendix A – SSL connections to mail server
8. Select the SSL tab (next to Keystores tab). Confirm when the following screen looks as shown below, then click Save.
9. Restart the Weblogic Server and configure inbound and outbound profile with SSL enabled.
125 Appendix B – Upgrading the license file
When e-Messaging is installed or upgraded and the G1Keys.xml file is read, the e-Messaging installer writes the selected configuration into the install.properties file found in the
em.home=C\:\\PBBICCM\\e-Messaging version=1.4m8 build=
# Custom properties # Note: Set data/time format to dd MMM yyyy, HH:mm '[GMT' Z']' to enable timezone dateOnlyPattern=dd MMM yyyy dateTimePattern=dd MMM yyyy, HH:mm '[GMT' Z']'
# Table size table.size=10
When e-Messaging starts it creates a file in the
If the user wishes to replace the existing license key file G1Keys.xml in
126 Appendix B – Upgrading the license file
When the e-Messaging server restarts after this procedure, it creates a new file called
Optional MAC address licensing on Windows
As of version 1.3, MAC Address validation may optionally be used when deploying on a Windows operating system. When MAC Address is included in an e-Messaging environment section of G1Keys.xml then e-Messaging will only install and run on a computer with the specified MAC address. When the MAC address field is omitted from an e-Messaging environment section of G1Keys.xml then e-Messaging works regardless of the MAC address of the computer. The support for old G1Keys.xml license file which did not include MAC Address is also maintained.
127 Appendix C – Configuring WebSphere to write a trace log
When e-Messaging is deployed on WebSphere, the data that gets written into e-Messaging's emsglog4j.log file is less detailed than when e-Messaging is deployed on other application servers. WebSphere can be configured to write the data that is omitted from the emsglog4j.log file into its own trace log file. Follow the instructions below for configuring WebSphere to write this additional e-Messaging log data into its own trace log file. 1. Launch the Administrative Console of WebSphere. 2. Click Troubleshooting > Logs and Trace.
3. Click server1 > Change Log Detail Levels.
128 Appendix C – Configuring WebSphere to write a trace log
4. For the “Configuration” option, scroll to com.g1.emessagaging. When you click it, you will find options for logging. Next, click All Messages & Traces.
5. Repeat the same for the “Runtime” option.
129 Appendix C – Configuring WebSphere to write a trace log
6. You will now find “trace.log” on -
130 Appendix D – Configuring the password rules
e-Messaging allows you to configure the rules that a user must follow while setting a new password. These rules will help the users to enhance the application security by setting up strong passwords.
| To define the password rules: 1. In the e-Messaging installation directory, navigate to the ...\PBBI CCM\e-Messaging\core.war\WEB-INF folder. 2. Open the security.xml configuration file in edit mode. 3. Set the appropriate values for the following properties:
Property Description Default value minLength Defines the minimum length of password 8 alphaNumericRequired Defines whether password will include both, true alphabets and numbers or only alphabet/numeric. splCharactersNotAllowed Defines the special characters that will not be ` ~ * < > . ! ' ; : allowed in the password. Note: This property takes value from the spl.chars.not.allowed property defined in the outboundProcessor.properties file. For more information about the spl.chars.not.allowed property, refer e-Messaging Reference Guide. maxLength Defines the maximum length of password 20
4. Save and close the file. 5. Restart e-Messaging web application for changes to take effect.
131