e-Messaging Reference Guide - Pitney Bowes · This product contains GCM Java Server Client library (gcm-server), version number 1.0.0, which is licensed under the Apache license,

Customer Engagement

EngageOne® Digital Delivery

Version 2.4

Reference GuideUS English Edition

Copyright ©2018 Pitney Bowes 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. Inc. (PB). To the fullest extent permitted by applicable laws PB 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 PB is prohibited to the fullest extent permitted by applicable laws.Nothing in this notice shall limit or exclude PB 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 product includes software developed by the Apache Software Foundation (http://www.apache.org/).

Copyright (c) 2000 - 2017 The Legion of the Bouncy Castle Inc. (https://www.bouncycastle.org)

This product contains Spring framework libraries, version number 3.2.9.RELEASE, which is licensed under the Apache license version 2.0. The license can be downloaded from http://www.apache.org/licenses/.

This product contains Hibernate, version number 4.1.8.Final, which is licensed under the Apache and LGPL license, version numbers 2.0 and 2.1. The license can be downloaded from http://hibernate.org/community/license/.

This product contains MyFaces, version number 2.2.8, which is licensed under the Apache license version 2.0. The license can be downloaded from http://www.apache.org/licenses/.

This product contains AppFuse, version number 2.2.1, which is licensed under the Apache license version 2.0. The license can be downloaded from http://www.apache.org/licenses/.

This product contains Bootstrap, version number 3.3.7, which is licensed under the MIT license. The license can be downloaded from http://getbootstrap.com/getting-started/#license-faqs . The source code for this software is available from http://getbootstrap.com/getting-started/#download.

This product contains AngularJS, version number 1.5.8, which is licensed under the MIT license. The license can be downloaded from https://github.com/angular/angular.js/blob/master/LICENSE .

This product contains jQuery, version number 3.1.0, which is licensed under the MIT license. The license can be downloaded from https://jquery.org/license/ . The source code for this software is available from http://jquery.com/download/.

This product contains URLRewriterFilter, version number 3.1.0, which is licensed under the BSD 2- Clause license. The license can be downloaded from http://cdn.rawgit.com/paultuckey/urlrewritefilter/master/src/doc/manual/4.0/introduction.html#license .The source code for this software is available from http://www.tuckey.org/urlrewrite/.

This product contains FasterXML Jackson, version number 2.5.1, which is licensed under the Apache license, version number 2.0. The license can be downloaded from http://www.apache.org/licenses/ . The source code for this software is available from https://github.com/FasterXML/jackson .

This product contains JasperReports, version number 1.3.4, which is licensed under the LGPL license. The license can be downloaded from https://opensource.org/licenses/lgpl-license/ . This software is available from https://community.jaspersoft.com/project/jasperreports-library/releases.

This product contains AWS Java SDK (aws-sdk-java), version number 1.11.86, which is licensed under the Apache license, version number 2.0. The license can be downloaded from https://github.com/aws/aws-sdk-java/blob/master/LICENSE.txt

This product contains GCM Java Server Client library (gcm-server), version number 1.0.0, which is licensed under the Apache license, version number 2.0. The license can be downloaded from https://github.com/google/gcm/blob/master/LICENSE.

http://www.apache.org/

https://www.bouncycastle.org

http://www.apache.org/licenses/


http://hibernate.org/community/license/

http://hibernate.org/community/license/



http://getbootstrap.com/getting-started/#license-faqs

http://getbootstrap.com/getting-started/#license-faqs

http://getbootstrap.com/getting-started/#download

http://getbootstrap.com/getting-started/#download

https://github.com/angular/angular.js/blob/master/LICENSE

https://github.com/angular/angular.js/blob/master/LICENSE

https://jquery.org/license/

http://jquery.com/download/

http://cdn.rawgit.com/paultuckey/urlrewritefilter/master/src/doc/manual/4.0/introduction.html#license

http://cdn.rawgit.com/paultuckey/urlrewritefilter/master/src/doc/manual/4.0/introduction.html#license

http://www.tuckey.org/urlrewrite/


https://github.com/FasterXML/jackson

https://github.com/FasterXML/jackson

https://opensource.org/licenses/lgpl-license/

https://opensource.org/licenses/lgpl-license/

https://community.jaspersoft.com/project/jasperreports-library/releases

Contents

ABOUT THIS GUIDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Related documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Target audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Skills and training . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Updates to this guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Typographical conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

INTRODUCTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

On the outbound side Digital Delivery: . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

On the inbound side Digital Delivery: . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Secondary Digital Delivery functions include: . . . . . . . . . . . . . . . . . . . . . 14

TECHNICAL ARCHITECTURE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

System architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

EngageOne Digital Delivery web . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

EngageOne Digital Delivery core . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

EngageOne Digital Delivery data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Outbound message processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Outbound . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Content converter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Mail servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

E-mail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

SMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Inbound message processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Inbound . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Content converter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Mail servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

3

Contents

ENGAGEONE COMMUNICATIONS SUITE AND DIGITAL DELIVERY . . . . . . . . . . 23

EngageOne . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Designer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

DIJ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Standard DIJ fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Custom DIJ fields required for Digital Delivery . . . . . . . . . . . . . . . . . . . . 24

Preparing different content for different message parts . . . . . . . . . . . . 31

Designing e-mail content in Designer . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Special considerations for PDF content . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Special considerations for SMS content . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Making Designer and Generate content available to Digital Delivery . . 36

DIJ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Plain text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

HTML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

PDF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Non-Designer/Generate content & Digital Delivery . . . . . . . . . . . . . . . . 40

Vault . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Automatic or minimum click indexing . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Folder permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

Retrieving message content from Vault . . . . . . . . . . . . . . . . . . . . . . . . . . 49

Inlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

Schedule and control of Data Flow & Generate from EngageOne Digital Delivery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

Local and remote control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

Data Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

Generate & Post Process command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

4

Contents

HEADERS – CONFIGURING ADDITIONAL E-MAIL HEADERS . . . . . . . . . . . . . . 64

Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

HEADERS – SUPPRESSING E-MAIL HEADERS . . . . . . . . . . . . . . . . . . . . . . . . . . 67

MESSAGE DELIVERY RATE OPTIONS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

DIGITAL SIGNATURES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

Generating a Private Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

keys.properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

Triggering or Suppressing Digital Signing . . . . . . . . . . . . . . . . . . . . . . . . . . 74

Important Note . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

PROPERTY SETTINGS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

inbound-observer.properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

outboundProcessor.properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

SMPPService.properties (SMPPSERVER configuration) . . . . . . . . . . . . . . . 85

tableColumns.properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87

Custom Vault index key mapping configuration . . . . . . . . . . . . . . . . . . . . . . 95

Sample custom index mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

Other property files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

ApplicationAlert.properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

ApplicationResources.properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

asyncProcesses.properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

aws.property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

blackoutWindow.properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

ClickatellMessageComposer.properties . . . . . . . . . . . . . . . . . . . . . . . . . 98

custom.properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

Ems.properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

encryptionKey.properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

5

Contents

engageone.properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

Executor.properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

inlet.properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

Install.properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

jdbc.properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102

log4j.xml . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102

mail.properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

openoffice.properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

Proxy.properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

securityConfiguration.properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

PurgingSetup.properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

repositoryFacade.properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

RESTService.properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

rootfolder.properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107

keys.properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107

serverCluster.properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107

servlet.properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107

workflow.properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

autoNotification.properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

inboundAsync.properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

FAILOVER CONFIGURATION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110

Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114

ACTIVE-ACTIVE CLUSTERING CONFIGURATION . . . . . . . . . . . . . . . . . . . . . . . . 115

Configuring Active-Active clustering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

Mapping clustered nodes to profiles using UI . . . . . . . . . . . . . . . . . . . . . . 117

SETTING UP THE LOAD BALANCER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120

LDAP CONFIGURATION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

6

Contents

Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

Mapping an Activer Directory user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

LDAP connection and search settings . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

Authentication providers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124

LANGUAGE RESOURCE BUNDLES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128

Example Language Source Bundle file . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128

Browser configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

Mozilla Firefox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

Microsoft Internet Explorer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130

REST WEB SERVICE APIS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

Outbound Profile Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

Node details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138

Error XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141

Restricting API Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141

Workflow item . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142

Outbound message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143


Message Processing APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146

Send email . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147

Send SMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150

Send Mobile Push Notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153

Issues while sending Mobile Push Notification using FCM . . . . . . . . . . 161

Upload image file(s) for email . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162

Upload attachment file(s) for email . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163

Retry sending failed message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163


Get message delivery status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165

7

Contents

Batch Message Processing APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167

Send email (batch) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167

Send email (batch) using ZIP files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172

Send SMS (batch) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172

Report APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175

Report Download . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175

Report Count . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176

Dashboard APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177

Dashboard Summary API for email . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177

Dashboard Summary API for SMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181

Campaign Summary APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188

REST API Security over Basic Authentication . . . . . . . . . . . . . . . . . . . . . . . 196

Enable/disable Basic Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . 196

APPLICATION MONITORING SUPPORT USING JMX . . . . . . . . . . . . . . . . . . . . 197

EngageOne Digital Delivery MBeans (Management Bean) . . . . . . . . . . . . 197

Application Server built-in MBeans . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198

Notification types available to EngageOne Digital Delivery . . . . . . . . . . . 199

Configuring EngageOne Digital Delivery to enable JMX notification . . . . 200

Websphere configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200

Weblogic configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201

Jconsole configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202

APPENDIX A – ARCHIVING OF GENERIC E-MAIL MESSAGES . . . . . . . . . . . . 205

APPENDIX B – PURGE VENDOR SCRIPTS . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213

Purge process errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213

Purge audit messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213

Purge reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213

Purge workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214

8

Contents

Purge people . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214

Purge properties file configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214

APPENDIX C – APPLICATION CUSTOMIZATION . . . . . . . . . . . . . . . . . . . . . . . . 216

Changing the application logo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216

APPENDIX D – SMS APPLICATION PROGRAMMING INTERFACES . . . . . . . . 217

Background Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217

Using the SMS-APIs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218

The SMS API Test Harness and Sample Code . . . . . . . . . . . . . . . . . . . . . . . 229

APPENDIX E– SECURITY CONFIGURATIONS FOR WEBSPHERE APPLICATION SERVER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240

APPENDIX F – CONFIGURING AWS BOUNCES FOR SES SERVICES . . . . . . 242

Verify Email address . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242

Create SQS-Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243

Create SNS-Topic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244

Subscribe the SQS queues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245

SQS-Queue permission settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246

SES bounce notification settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247

Digital Delivery settings for bounce . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248

APPENDIX G – CUSTOM EMAIL SUPPORT . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250

APPENDIX H – TLS VERSION & CIPHER SUITE CONFIGURATION . . . . . . . . 253

SMTP Email . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253

IMAP Email . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254

POP3 Email . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255

9

Contents

SMPP SMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255

MS SQL DB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256

APPENDIX I – CONFIGURING APNS AND AWS APNS GATEWAYS . . . . . 257

APNS Gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257

Certificate File Upload . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257

Duplicate APNS Gateways Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . 258

AWS APNS Gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258

Certificate File Upload . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262

Duplicate AWS APNS Gateways Validation . . . . . . . . . . . . . . . . . . . . . . . 263

Profile Creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263

INDEX 264

10

About this guide

Introduction

This guide explains the design and configuration of the Digital Delivery components and its integration with other Pitney Bowes EngageOne Communications Suite.

Related documentation

The following guides provide useful reference material:

• EngageOne® Digital Delivery User’s Guide

• EngageOne® Digital Delivery Installation Guide

• EngageOne® Digital Delivery Release Notes

Target audience

This guide is for an application developer who is responsible for supporting the EngageOne® Digital Delivery application deployment or integration with other Pitney Bowes EngageOne Communications Suite products.

Skills and training

It is assumed that personnel reading this guide would have skills in a Java programming language and J2EE technologies.

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.

11

About this guide

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).

12

Introduction

EngageOne® Digital Delivery is a complete, enterprise class, solution for managing in- and out-bound e-mail and SMS customer communications. Digital Delivery leverages and extends existing Pitney Bowes Software Customer Engagement software components such as Designer, Generate, Vault and Data Flow.

Digital Delivery allows organizations to take a customer centric view on customer communications. Designing content for all delivery channels in a single design environment and associating communications from all delivery channels, in- and out-bound, with a single customer centric view in your contact centers. Digital Delivery enables organizations to give their customers the freedom to communicate anything on any channel at any time and still maintain an up to date customer centric view of their customer communications throughout the organization. Furthermore, Digital Delivery helps organizations maintain brand consistency across communication channels.

On the outbound side Digital Delivery:

• Receives content that has been formatted by Designer and Generate or other systems.

• Packages it into the required message format for the chosen delivery channel:

• Text e-mail messages

• HTML e-mail messages with embedded or referenced images

• Multipart/alternative e-mail messages (text & HTML)

• E-mails with single or multiple attachments. Different file formats supported including PDF, text, CSV, XML and ZIP. Attachments may be static or personalized on a per message basis.

• Plain text SMS messages

• Optionally digitally signs the e-mail body.

• Sends message through selected gateway for the chosen delivery channel.

• Optionally indexes and archives messages sent.

• Creates database records of sent messages.

• Updates the sent message records with Delivery Status Notifications to report on:

• Messages sent

• Messages bounced (including reason for bounce)

• Messages replied-to

• Messages opened (wherever possible)

• Provides API access to the sent message records to facilitate URL links to personalized web landing pages in the e-mails sent.

13

Introduction

On the inbound side Digital Delivery:

• Retrieves inbound messages from any e-mail server or using HTTP / call-back URLs.

• Processes Delivery Status Notifications (e.g. bounce messages) to update sent message records for reporting.

• Optionally converts content, including e-mail attachments, ZIP contents and RTF e-mail content to PDF for archive and retrieval - avoiding the need for specialized file viewers. HTML e-mail can also be optionally converted to MHT format, embedding referenced images for version control, prior to archiving.

• Automatic indexing and archiving of messages into Vault repository.

• Response management to inbound messages, including the auto categorization and routing of messages based on their content.

• Mail list management for CAN-SPAM act compliance.

• Digital Delivery supports both real-time and batch processing of in-and out-bound messages.

Secondary Digital Delivery functions include:

Workflow

Both built-in workflow as well as integration with third-party workflow solutions for the efficient management of:

• Message responses using local e-mail client or business system of choice.

• Managing Delivery Status Notifications (bounced messages).

• Content conversion failures and verification.

• Indexing of messages for archiving.

• Bulk close of workflows.

Reporting

Comprehensive and graphic reporting including:

• Messages sent (selected by various criteria)

• Message delivery statuses

• Temporary & permanent delivery failures

• Replies

• Opens

14

Introduction

General and trend overviews as pie and line charts:

• Inbound messages and their stages of processing

• Audit reports

• Error reports

• Export to PDF

• Export to CSV

Scheduling

Scheduling of when batch messages are sent.

15

Technical Architecture

This section outlines the high-level EngageOne Digital Delivery architecture.

System architecture

16


EngageOne Digital Delivery web

EngageOne Digital Delivery is based on an MVC (Model, View, Controller) architecture. The web component is the View component that provides a web-based interface to users.

Security (authentication and authorization) is applied at the web layer for each incoming web request. Users can be created and maintained in Digital Delivery itself or optionally imported through LDAP from an organization’s existing user management system.

The web component generates dynamic web pages with data provided by the core component (the Controller component). By default Digital Delivery comes with user interfaces in the following languages:

• English

• Spanish

• Portuguese (Brazilian)

• German

• Chinese (simplified)

• Japanese

New language interfaces can easily be added to Digital Delivery. Refer to Language Resource Bundles section of this EngageOne Digital Delivery Reference Guide for instructions on how to add new language resource bundles.

Digital Delivery includes interfaces for the following:

Configuration

• User Management, User Groups and Roles, Internal or through LDAP

• Inbound Profiles

• Content Categorization

• Outbound Profiles

• Data Flow (data preparation) controls

• Designer (content formatting) controls

• Scheduling

• Gateways (e-mail & SMS)

Workflow Built-in and Integration with External for:

• Content conversion

• Indexing

• Managing bounced messages

• Categorize messages based on their content

17


• Responding to messages

Filtered Graphic Reporting

• Messages by scheduled job, profile or individual

•Sent

•Bounced (temporary and permanent)

•Out of office replies

•Replied to

• Message response handling status / workflow

• User Groups

• Audit

• Error

EngageOne Digital Delivery core

The EngageOne Digital Delivery core is the central controller of Digital Delivery. It provides key functions for the processing of both outbound and inbound messages, which will be explained in more detail later.

EngageOne Digital Delivery data

The EngageOne Digital Delivery core uses a data access layer that stores and retrieves data from a relational database management system (RDBMS) (e.g. SQL Server, 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.

Outbound message processing

The EngageOne Digital Delivery Core uses the Outbound component to manage the preparation of data, message formatting, and message sending.

Outbound

The Outbound component orchestrates the different processes required for:

Data Preparation and Formatting (optional)

• Data Flow Plans can be triggered from Digital Delivery as part of messaging campaigns.

18


Message Formatting (optional)

• EngageOne Generate applications can be triggered from Digital Delivery to format message content.

Post Process Formatting (optional)

• Post Composition processes can be triggered by Digital Delivery to manipulate content that has been formatted by EngageOne Generate 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 Digital Delivery 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.

Digital Delivery supports sending of messages in both batch and real-time modes.

For archiving outbound messages, Digital Delivery 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.

Content converter

Digital Delivery 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

Digital Delivery uses SMTP (Simple Mail Transfer Protocol) for sending of 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, Digital Delivery can interface with any mail servers that provide SMTP support.

After message content has been composed (either under the control of Digital Delivery or externally to Digital Delivery), Digital Delivery 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 EngageOne

19


Designer and profile settings that are configured in the Digital Delivery Core. This provides maximum flexibility in terms of being able to personalize subject lines and attachment filenames on a message-by-message basis.

E-mail

EngageOne Digital Delivery supports formatting and sending the following e-mail formats:

1. Plain text e-mail (text/plain)

2. HTML e-mail (text/html)

• With images embedded or referenced externally

3. Multipart/alternative e-mail with a text part for display when the e-mail client does not support HTML and a HTML part for when it does.

4. Attachments to any of the above e-mail formats.

• PDF attachments formatted by Generate

• CSV attachments formatted by Data Flow or third-party system

• ZIP attachments prepared by Data Flow or third-party system

• XML attachments formatted by Data Flow or third-party system

SMS

EngageOne Digital Delivery supports formatting and sending single SMS (Short Message Service) messages any of the following ways:

• using the SMTP interface of http://www.clickatell.com.

• via an SMPP outbound transmitter or transceiver that connects to an SMS gateway directly over TCP/IP.

• via the Java API described in this EngageOne Digital Delivery Reference Guide.

Inbound message processing

The EngageOne Digital Delivery Core uses the Inbound component to manage delivery status notifications (e.g. bounce messages), user originated messages that require a response and/or messages that require archiving in Vault.

Inbound

The Inbound component processes messages received by Digital Delivery. 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

20


associating inbound messages with outbound messages sent by Digital Delivery 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, Digital Delivery will present an operator with a dropdown list of index options so that messages are still indexed with minimum clicks / human intervention.

For archiving inbound messages, Digital Delivery 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

EngageOne Digital Delivery provides a content conversion service so that the content of inbound messages can (optionally) be converted to a more appropriate format, such as PDF, for archiving. Open Office is leveraged to handle PDF or PDF/a conversion and the Javamail API is used for converting HTML to MHT. It is possible to configure Digital Delivery to convert all content or only convert selected content types to PDF (or PDF/a) prior to archiving to ensure that message content, of MS Office attachments for example, can be retrieved and viewed from business applications without the need for any specialized viewers.

Digital Delivery also supports the handling (extraction) of files contained in ZIP attachments and Rich Text e-mails sent by MS Outlook. For Rich Text e-mails, Outlook uses Microsoft’s proprietary TNEF (Transport Neutral Encapsulation Format) encoding which most e-mail solutions, other than Outlook, are unable to handle.

Mail servers

E-mail

Digital Delivery accesses e-mail messages via POP3 (Post Office Protocol version 3) or IMAP (Internet Message Access Protocol, and previously called Internet Mail Access Protocol, Interactive Mail Access Protocol). It is possible to process messages sent to [email protected] style e-mail addresses, however, it is equally possible to set up forwarding rules on the mail server to forward messages to or from specified accounts to an address like [email protected] and then configure Digital Delivery to index and archive these messages too. This process is sometimes called "e-mail journaling".

21


SMS

EngageOne Digital Delivery supports the receipt of inbound SMS messages in one of three ways

• using an HTTP-based 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 this EngageOne Digital Delivery Reference Guide.

22

EngageOne Communications Suite and Digital Delivery

EngageOne

EngageOne Communications Suite components can integrate with EngageOne Digital Delivery. Digital Delivery allows organizations to leverage EngageOne technology to enable interactive e-mail and short message service (SMS) communications in their contact centers. That is, it allows end-customers to receive any communication they currently receive on paper via e-mail too, without the need for any redesign of content. Digital Delivery tightly integrates into EngageOne as an additional delivery channel. EngageOne is a separately licensed product and additional Digital Delivery configuration is required to enable the product integration. See the EngageOne documents for more information.

Designer

The EngageOne Digital Delivery solution is designed to process e-mail and SMS content that has been formatted by Designer or other systems.

The Digital Delivery solution can process content formatted by Designer (Version 4 or later).

Using Designer has the following advantages over other composition products:

1. eHTML driver (version 5.3 and later). This driver outputs HTML that is specially formatted to ensure correct display in the vast majority of e-mail clients. Some commonly used e-mail clients do not support the use of CSS (Cascading Style Sheets) and therefore the eHTML driver avoids the use of CSS. This restricts the accuracy with which content can be defined but has the benefit of displaying properly in most e-mail clients that support HTML.

2. Producing multiple streams in a single job. Designer (version 5 and later) has the concept of a Publication which exists of multiple documents destined for the same envelope. The concept of a Publication lends itself well to the formatting of content for an e-mail communication too, where multiple documents destined for the same envelope equates to multiple e-mail parts (e.g. plain text, HTML, attachments) being

23


destined for the same e-mail message. Designer's ability to output multiple output streams in a single job allows it to be configured to format all the parts of an e-mail in a single job, from a single design template (HIP file).

DIJ

The DIJ (Document Interchange Journal) is the standard way in which metadata on Generate produced content is exchanged between the different components of Pitney Bowes EngageOne Communications Suite. It is an XML based file that Designer (version 4.1 and beyond) is able to generate in parallel to the formatted output it generates.

Digital Delivery uses the DIJ as a control file for the message content it is preparing to send. Therefore certain fields in the DIJ must be configured correctly in the Work Center to ensure that Digital Delivery can process the related content correctly. The rest of this section explains DIJ fields that are required by Digital Delivery.

Please refer to the Generate Users Guide for instructions on how to configure the DIJ.

Standard DIJ fields

The following are standard DIJ fields that should be populated for all messages.

Account NumberA code that uniquely identifies the customer.

NameThe customer’s full name. Best practice is to format the value of this field “FirstName SecondName” – i.e. with a space between the names and no salutation or middle initial.

Statement DateThe date on which statement is generated. This information will appear in the e-mail date header.

AddressIt is best practice, but optional, to populate all the address fields for the recipient.

Publication IDThis may be left as Default unless it is required for an Account Management or iProof environment. Refer to the respective manuals for additional details.

Custom DIJ fields required for Digital Delivery

The following are custom DIJ fields that should be populated for messages requiring processing by Digital Delivery.

EmailCreate a custom DIJ field with the name Email and populate its value with the plain e-mail address to which the message will be sent.

24


Compulsory for e-mail messages and optional for SMS messages

SubjectCreate a custom DIJ field with the name Subject and populate its value with the text that is to appear in the subject line of the e-mail. This allows the subject line of an e-mail to be personalized on a message by message basis. For SMS messages it is recommended to populate this field with a copy of the SMS message text. In case, if the subject length (both for outbound and inbound) exceeds size limit (255 characters), then extra length will be truncated to fit in the limit including three dots at the end.

Optional for e-mail messages and optional for SMS messages

MSISDN (Mobile Station Integrated Services Digital Network)Create a custom DIJ field with the name MSISDN and populate its value with the mobile phone number to which a SMS is to be sent. The number should be formatted as defined in the by ITU-T (International Telecommunication Union) and is at most 15 digits long and consists of:

• CC - Country Code (1-3 digits e.g."420" for Czech Republic)

• NDC - National Destination Code (e.g. 3 digits in Czech Republic)

• SN - Subscriber Number (e.g. 6 remaining digits (123456))

MSISDN example:

Optional for e-mail messages and compulsory for SMS messages

SignCreate a custom DIJ field with the name Sign and populate its value with 1, true or yes if you want to enable the digital signing of outbound e-mail messages regardless of the Digitally Sign Message Body setting in the Outbound Profile that sends them. Alternatively set the value to 0, false or no, if you want to disable the digital signing of outbound e-mail messages regardless of the Digitally Sign Message Body setting in the Outbound Profile.

Optional for e-mail messages and not applicable for SMS messages

Expire (for future use)Create a custom DIJ field with the name Expire and populate its value with the date, formatted YYYYMMDD, that the message should be purged from the document repository. This value will get associated with messages archived in Vault as a custom attribute called Expire. It should be noted that purging of individual messages in this fashion is not currently

CC NDC SN

420 603 123456

THE MSISDN MUST NOT BE PRECEDED WITH ANY

“0”, "1" OR “+” CHARACTERS AND MUST NOT

CONTAIN ANY SPACES.

25


supported by Vault. Purging is currently only possible by profile. That is purging is set at the same number of months, from the date of archiving, for all messages processed by a given Digital Delivery Inbound or Outbound profile.


AttachName1Create a custom DIJ field with the name AttachName1 and populate its value with the full filename, including the correct filename extension, that you would like applied to the e-mail attachment that is configured as Attachment 1, in Digital Delivery Outbound Profile that will be sending this content as an e-mail message. This approach allows you to personalize the attachment name, for example including an account number in the attachment name, on a message by message basis – even when messages are being sent in batch mode.

Digital Delivery supports both static and personalized e-mail attachments and in some cases the attachment may be set to optional. The following table explains the scenarios that are supported.

As indicated above for batch Outbound Profiles, only Static or Split Personalized PDF Content may be optional. In other words if the personalized PDF attachments are being submitted to a batch Outbound Profile as a single compound file then an attachment is expected to be in that compound file for every message represented in the associated DIJ. For real-time Outbound Profiles there is no restriction on when either Static or Personalized Content may be set to optional.

An optional static attachment is attached to an e-mail by setting the value of the AttachName1 DIJ field to the name of the file that needs to be attached. Digital Delivery expects to find a file of the specified name in the folder that is configured for Attachment 1 in Digital Delivery Outbound Profile. If a filename is specified which cannot be found in this folder then Digital Delivery will raise an exception. If the value of the AttachName1 DIJ field is left blank then no file will be attached to the e-mail for Attachment 1, provided Attachment 1 is set to optional in Digital Delivery Outbound Profile. Otherwise, if Attachment 1 is not optional, then Digital Delivery will raise an exception.

For personalized PDF attachments, Digital Delivery expects to find either a single compound PDF file, or an individual PDF file for each message. In the case of a single compound PDF file, the main part of the filename must equal that of the DIJ being processed and the order of documents in the compound PDF file MUST match the order of the message descriptions in the DIJ. In the case of individual PDF files, the PDF file to be

Sending Mode

Static Attachment

Personalized Attachment

Optional Static Attachment

Optional Personalized Attachment

Batch X X X Only Split Personalized PDF

Real-time X X X All

26


attached to the first message described in the DIJ is main_part_of_DIJ_filename_0000001.pdf, then main_part_of_DIJ_filename_0000002.pdf, etc. The numbering in the individual PDF filenames MUST match the order of the message descriptions in the DIJ being processed. By default, this would always be the case, provided the compound or split PDF and DIJ are generated by the same Generate job. Additional content verification based on Document Instance ID can be configured in an EngageOne Digital Delivery Outbound Profile, to guarantee that the correct content is always attached to a given message.

Note: You are recommended to turn OFF Content Verification option when using EngageOne.

Optional for e-mail messages and not applicable for SMS messages.

AttachName2, AttachName3 ... AttachNameXEngageOne Digital Delivery supports attaching unlimited attachments to a single e-mail. These are configured in the Attachments settings table in the Outbound Profile page. The DIJ configuration guidelines provided above for AttachName1 also apply to AttachName2, AttachName3…AttachNameX.

Prior to version 1.3, Digital Delivery only supported up to four “AttachNameX” settings in the DIJ. As of version 1.3 Digital Delivery supports any number of attachments and therefore any number of “AttachNameX” settings in the DIJ.

Encoding1,Encoding2...EncodingXThe purpose of this field is to provide custom encoding for attachments. If this field is not included, then by default encoding is “UTF-8”. If this field is included then encoding for the respective attachment will be as per the field value. Therefore Encoding1 is associated with AttachName1, Encoding 2 with AttachName2 and so on.

ContentType1,ContentType2...ContentTypeXThe purpose of this field is to provide custom content type for attachments. By default, content type is what has been defined in attachment configuration for an outbound profile. But in the case for a particular record where a different content type is required, then ContentTypeX field needs to be included. For example, suppose content type for

27


AttachName1 has been configured as “PDF” in outbound profile configuration and for a particular record content type “DOC” is required, then ContentTypeX field needs to be included with value as DOC (value is case insensitive).

Example

<DDSDocValue name="AttachName1" type="text" len="10">attach.doc</DDSDocValue>

<DDSDocValue name="ContentType1" type="text" len="3">doc</DDSDocValue>

WorkflowItem_IdThe purpose of this custom DIJ field, and WorkflowStage_Id described below, is for Digital Delivery to be able to update a workflow item upon the successful sending of a response message.

Inbound Profiles can be configured in Digital Delivery to process inbound messages, manage delivery status notifications (e.g. bounce messages), automated indexing and archiving of messages and generally managing message responses. Inbound Profiles create workflow items for each inbound message processed. These workflow items can be processed by Digital Delivery’s built-in workflow functions or exported to third-party workflow or business correspondence solutions. In the case of the latter, the business correspondence solution can format a message response and pass its content to Digital Delivery to send as an e-mail or SMS.

If the successful sending of a response message through Digital Delivery should update or close the status of an (inbound) workflow item automatically then you should use the WorkflowItem_id and WorkflowStage_id custom DIJ parameters as described below.

Create a custom DIJ field with the name WorkflowItem_id and populate its value with the Workflow Item ID of the inbound message that is being responded to. The Workflow Item ID must form part of the input data for Generate and can be acquired through the XML based workflow APIs provided by Digital Delivery. Both web service and file based APIs are available. See REST API for Outmessage XML and Workflow XML section on page 131 for further details on these APIs.


WorkflowStage_IdWorkflowStage_Id is to be used in combination with WorkflowItem_id described above. Create a custom DIJ field with the name WorkflowStage_Id and populate its value with the WorkflowStage_Id value that the workflow item of the original inbound message should be updated to when this outbound response message is successfully sent. The following WorkflowStage_Id values will be processed by Digital Delivery. Other values will be ignored.

0 – Message requires manual content categorization*

1 – Message requires manual content conversion or checking*

28


2 – Message requires manual indexing*

3 – Delivery Status Notification (bounce message)*

4 – Indexed but open (requires response)*

40 – Archiving off but requires response*

5 – In progress, locked by a workflow user*

6 – Closed

60 – Passed to external system to close*

Note that these workflow stages would generally NOT get used by response messages. The successful sending of a response message would generally close the workflow item associated with the inbound message it is responding to. That means that response messages processed through Digital Delivery would generally have their WorkflowStage_Id value set to “6” or “60”.

Optional for e-mail and SMS messages but compulsory if WorkflowItem_id is included in DIJ

FromCreate a custom DIJ field with the name From and populate its value with the text that is to appear in the From header of the e-mail. This overrides the From address specified in an Digital Delivery Outbound Profile and allows the From address of an e-mail to be personalized on a message by message basis. If Digital Signatures are used by Digital Delivery Outbound Profile then the private key provided to digitally sign e-mails must be derived from a digital certificate that was created using this From address.


Reply-toCreate a custom DIJ field with the name Reply-to and populate its value with the text that is to appear in the Reply-to header of the e-mail. This overrides the Reply-to address specified in an Digital Delivery Outbound Profile and allows the Reply-to address of an e-mail to be personalized on a message by message basis.


Return-pathCreate a custom DIJ field with the name Return-path and populate its value with the text that is to appear in the Return-path header of the e-mail. This overrides the Return-path address specified in an Digital Delivery Outbound Profile and allows the Return-path address of an e-mail to be personalized on a message by message basis. It is not generally recommended to use this DIJ setting, because it is easier to set up a single Digital Delivery Inbound Profile for processing all Delivery Status Notifications than it is to configure Inbound Profiles on a per message basis.

29



Errors-toCreate a custom DIJ field with the name Errors-to and populate its value with the text that is to appear in the Errors-to header of the e-mail. This overrides the Errors-to address specified in an Digital Delivery Outbound Profile and allows the Errors-to address of an e-mail to be personalized on a message by message basis. It is not generally recommended to use this DIJ setting, because it is easier to set up a single Digital Delivery Inbound Profile for processing all Delivery Status Notifications than it is to configure Inbound Profiles on a per message basis.


Custom email headersEngageOne Digital Delivery also supports customized email headers. Create a custom DIJ field with the name emailHeaders and populate its value with the text that is to appear in the header of the e-mail. This is an optional header.

You can specify custom email headers as shown below:

<DDSDocValue name="emailHeaders" type="text" len="53">header1=value1,header2=value2</DDSDocValue>

Batch/Campaign information in DIJEngageOne Digital Delivery also supports fields for providing batch/campaign informationwith DIJ data. Following fields can be added in the DIJ at file level (not at record level):BatchId, BatchName, CustomerId and SourceId.

Example:

<jobdata><datetime>20100105164052</datetime><platform>Microsoft Windows</platform><Version major="4" minor="3"/><JobGUID>5F2E999D61D84A4693498E9BCECE2C62</JobGUID><JobName>E:/emsg/appdoc1/sms/Output/63/SIRS_63_20091201.prmis</JobName><JobShortName>SIRS_63_20091201.prmis</JobShortName><NativeFormat value="eHTML"/><ResourceGUID p="1" value="054A0B0A8D3942DAB1349A69423024B4"/></jobdata><BatchData><BatchId>BatchTestId</BatchId><BatchName>BatchTestName</BatchName><CustomerId>1231/CustomerId><SourceId>Source98</SourceId></BatchData><document docID="1" docMasterID="27202E30D6FA4C995986976A41D9366D"docInstanceID="22scvv2ayy11a">

30


Auto Notification End pointIf auto-notification on email failure is enabled on inbound profile, notification end point (Mobile number or Email address) can be specified through a new DIJ attribute as below

<document docID="1" docMasterID="B28E54DA2BCC2D5FCA8A0DBFDCF2B691" docInstanceID="E1D644DD53784ACF9BC2D95E6EBE7A15"><VendorId>a5f18288cc294573879357cd5a47451d</VendorId><DocTypeId>5865F1950EB14D028BA999AF5DADE524</DocTypeId><AccNo>Inbound10</AccNo><StmtDate>20150821</StmtDate><AutoNotificationEndPoint>9999999999</AutoNotificationEndPoint><DDSDocValue name="Email" type="text" len="60">[email protected]</DDSDocValue><DDSDocValue name="Subject" type="text" len="33">Inbound10</DDSDocValue><DDSDocValue name="MSISDN" type="text" len="11">27828746377</DDSDocValue><DDSDocValue name="AttachName1" type="text" len="53">testfile1.pdf</DDSDocValue></document>

Other Custom DIJ FieldsIf your company is an existing user of Vault and requires specific index values in Vault which are already set-up, then you can continue to use your current index key names and values for messages sent by Digital Delivery. For outbound messages simply create custom DIJ fields with the names of your custom index keys and populate their values as required. Digital Delivery will pass, non-Digital Delivery related custom fields in the DIJ, as attribute values, directly into the text journal it creates as part of its archive process.

For inbound messages it is also possible to map index values created by Digital Delivery to your own custom attribute keys as required. Refer to Custom Vault Index Key Mapping Configuration section on page 95 for additional details.

Preparing different content for different message parts

The simplest e-mail messages are plain text e-mail messages which only have one body part – the plain text. Digital Delivery also supports the sending of multi-part e-mail messages, for example, including all or some of the following in a single e-mail message:

• A plain text version of the main e-mail body for display in e-mail clients that do not support HTML. This avoids the display of distorted HTML due to images not appearing when displayed in e-mail clients that do not support HTML.

• An HTML version of the main e-mail body for display in e-mail clients that support HTML. This allows you to create graphic message content to create maximum impact when displayed in e-mail clients that support HTML.

• Any number of e-mail attachments.

31


In order to design and format the content for each of the above parts in Designer we make use of the DOC1 Series 5 concept of a Publication. A publication consists of multiple documents destined for the same envelope. In the context of e-mail, a publication equates to multiple e-mail parts (e.g. plain text, HTML and PDF attachments) being destined for the same e-mail message. Series 5’s ability to output multiple output streams in a single job allows it to be configured to format all the parts of an e-mail in a single job, from a single design template (HIP file).

DesignerIn Designer, create a separate document within the same Publication for each of the e-mail message parts. Design the content as you would normally for each of the message parts/documents. For each message part/document, open the Document’s Properties. Select the Supported Output Devices tab and select the output formats that you wish that message part /document to be formatted in. In order to create more than one PDF attachment for a given message you will need to create a different PDF Output Device (in the Work Center’s Environment tab) for each of the PDF documents to be generated and attached to an e-mail in a single run.

For further information, refer to the Designer’s User’s Guide.

Designing e-mail content in Designer

Special considerations for HTML content

Refer to the Designer User Guide for restrictions that apply to Designer and Generate applications producing HTML.

The remainder of this section outlines some additional considerations that will help ensure HTML generated by Designer displays properly in most e-mail clients.

ImagesIt is recommended to follow the following guidelines when incorporating images in content that is to be output to HTML:

• Only use GIF or JPEG images

• Size images at the correct resolution for HTML presentment (i.e. 96 dpi) prior to importing the images into the Designer Work Center

• Do not include directory paths in filenames that reference images

• Give images short names, with no spaces in the name and convert them to the right format prior to loading into the Designer Work Center

32


Use Resource Maps in the Designer Work Center to map all image names to names of images you want to be referenced in the HTML output and ensure that images with these names are present in the image folder specified in Digital Delivery Outbound Profile that will be sending your HTML. Please refer to the Designer User Guide for instructions on using Resource Maps.

FontsYou can vary font size and style (bold, underline and italic) but cannot specify the font type beyond this in HTML v3.2. With later HTML versions you are also dependent on the fonts that the end user has installed on their client PC when viewing the message.

Page LayoutWhen designing content for display on a monitor, you generally do not know the resolution of the screen that the recipient will view the content on. Furthermore, different users will view the content on different resolution screens. Therefore in order to ensure that the content you are designing will display predictably on any monitor, the following guidelines are recommended:

• Set page width in the Page Set-up to 6.667 inches. This equates to 640 pixels wide at the HTML resolution of 96 dpi.

• Set margins in the Page Set-up to zero – particularly the left and right margins.

• Uses tables (static or dynamic) wherever possible to control the layout / positing of text and image content in the message.

Special considerations for plain text content

Plain text content is generated by Generate’s linedata driver.

The remainder of this section outlines some special considerations that will help ensure linedata generated by Generate displays properly in most e-mail clients.

FontsUse a single size font for all text and avoid the use of bold, underline and italic text. Such formatting gets lost in the plain text format.

Page LayoutWhen designing content that is to be output by the linedata driver for insertion in the plain text part of an e-mail body you will need to consider the following:

• The page height of the document containing the plain text should be enough to fit the entire message’s content, including variable content, onto a single page. Otherwise there is a risk that the wrong content could be sent to the wrong customer. Digital Delivery will raise an

ENGAGEONE DIGITAL DELIVERY SUPPORTS BOTH

EMBEDDING IMAGES REFERENCED BY HTML, AS

MULTIPART/RELATED MESSAGE PARTS, IN THE

E-MAIL ITSELF OR LEAVING THEM TO BE

REFERENCED ON AN EXTERNAL WEB SERVER.

IMAGES, WHOSE SOURCE STARTS WITH “HTTP” ARE

ASSUMED TO BE REFERENCED IMAGES. IT IS

ASSUMED THAT IMAGES WITH OTHER SOURCES

REQUIRE EMBEDDING. THE “HTTP://...” PATH TO AN

IMAGE CAN BE CONFIGURED IN THE eHTML

OUTPUT DRIVER SETTINGS. PLEASE REFER TO

THE DESIGNER USER’S GUIDE FOR FURTHER

DETAILS.

33


exception (provided Content Verification option is enabled) to prevent this from occurring. More recent versions of the Designer Work Center (version 5.5 and later) include a linedata output driver setting to “Merge Document Pages” which eliminates the need for this consideration.

• The page height of the document should approximately equal the height of character placing grid that is set for the linedata Output Device (Environment tab) in order to avoid rogue CR/LF characters appearing in the linedata output

Output Driver SettingsThe following linedata driver settings are recommended when using the linedata output in the plain text part of an e-mail body:

• Format of logical records – CRLF

• Height of character placing grid – xxxx

• Width of character placing grid – 132Leave as default value

• Output codepage – Unicode – UTF-8

• Force full width characters - unchecked

Special considerations for PDF content

PDF content is generated by Generate’s PDF driver.

The remainder of this section outlines some special considerations that will help ensure PDF generated by Generate is suitable for use as e-mail attachments.

FontsBase14 fonts are available by default in all Acrobat Readers. Using custom fonts, may require the fonts to be embedded in the PDF which can drastically increase the size of the PDF and therefore the e-mail that you send.

Page LayoutNo special considerations

Output Driver SettingsThe following PDF driver settings are recommended when using the PDF output as an e-mail attachment:

• Embed Fonts – disabled, unless custom fonts are used and then enable Font Subsetting

• Embed Images – enabled, if PDF contains images

• Compression – SMALLEST, to minimize the size of the PDF and therefore the e-mail size too

• Document Processing – COMPOUND, for direct processing through Digital Delivery

WHERE “XXXX” IS LARGE ENOUGH TO ENSURE

THAT ALL OF A DOCUMENT’S CONTENT, INCLUDING

VARIABLE CONTENT FITS ONTO A SINGLE LINEDATA

PAGE. OTHERWISE THE WRONG CONTENT COULD

GET SENT TO THE WRONG CUSTOMER. THE HEIGHT

OF CHARACTER PLACING GRID SHOULD BE MORE

OR LESS PROPORTIONATE TO THE SIZE OF THE

PAGE IN THE WORK CENTER IN ORDER TO AVOID

INCONSISTENT CR/LF CHARACTERS APPEARING IN

THE LINEDATA.

34


• Refer to Generate User Guide for details on the other PDF driver settings.

Special considerations for SMS content

SMS stands for Short Message Service and is the mobile text messaging that can be used to communicate with mobile phones.

Digital Delivery supports in- and out-bound SMS processing through:

• Your SMSC of choice using the SMPP protocol.

• Via a SMS service provider called Clickatell (http://www.clickatell.com).

• Using the Java APIs described in Appendix D of this EngageOne Digital Delivery Reference Guide.

For SMS via clickatell Digital Delivery processes outbound messages using Clickatell's SMTP interface and inbound messages (including message delivery status notifications) using an HTTP-based callback URL.

For SMS via SMPP, Digital Delivery sends outbound messages via an SMPP transmitter or SMPP transceiver on a TCP/IP socket connected to the SMS gateway and inbound SMS messages using an inbound listener on a different TCP/IP socket in the case of an SMPP receiver and on the same socket in the case of an SMPP transceiver. Where the inbound messages are message delivery status notifications received for the outbound messages sent to the SMS gateway by Digital Delivery, then there needs to be a mapping between the inbound SMPP listener profile and the outbound SMPP gateway. See the EngageOne Digital Delivery Users Guide for details.

The majority of the settings required to send and receive messages are configured in Digital Delivery Outbound and Inbound Profiles. The mobile number which a message needs to be sent to is provided to Digital Delivery in the custom DIJ field called MSISDN and described in MSISDN (Mobile Station Integrated Services Digital Network) section on page 25 of this guide.

It is recommended to format the text content of an SMS message using Generate journal files. Please refer to the Generate User Guide for instructions on how to set up journal files.

When sending content from Generate as an SMS, Digital Delivery expects to find one or more of the following name value pairs in the journal file that is provided by Generate:

Message for:MSISDNunicode:{0|1}text:message text

Message for – MSISDN specifies the mobile number to which the SMS message should be sent. See MSISDN (Mobile Station Integrated Services Digital Network) section on page 25 for details on how to format the mobile number according to the MSISDN specification. This setting serves two purposes for Digital Delivery:

35


• It is used as a message separator when processing messages in batch mode – i.e. when messages for multiple customers exist in a single journal file

• It is used to double check that the content is being sent to the right customer by comparing the MSISDN value in the journal with the MSISDN value in the DIJ

unicode – {0|1} specifies whether the message content should be converted to Unicode [UCS-2 encoding] prior to sending. By default Unicode is disabled. When enabled, a single message may only contain 70 characters instead of the usual 160 characters.

text – message text specifies the text to be inserted in the SMS message. This may contain a maximum of 160 characters (70 characters if Unicode text is enabled)

urltext – URL%20encoded%20message%20text as an alternative to the text: setting above text may also be URL encoded to support special Greek characters etc. Use the keyword urltext: instead of text: when specifying message text with URL encoding.

Examples:

Message for: 31648123456unicode: 0text: This is some SMS content for customer number 12345678Message for: 31648123456unicode: 0urltext: This%20is%20some%20SMS%20content%20for%20customer%20number 12345678

Making Designer and Generate content available to Digital Delivery

Outbound Profiles are configured in EngageOne Digital Delivery to package and send e-mail and SMS content from Designer and Generate or other systems. Outbound Profiles can be configured to send messages in both real-time, one message at a time, or in batch mode, where many messages are sent as a batch job.

To view / update Batch or Real-time field: select Home / Operational Settings / Outbound Profiles and click on appropriate Outbound Profile under the Name column of the Outbound Profiles page. When the Outbound Profiles Setting page is displayed, scroll down to the Message Processing Settings section to view/update settings.

Separate Outbound Profiles need to be configured for the sending of e-mail and SMS messages.

When an Outbound Profile is configured in Digital Delivery it will specify the folders where it expects to find content for insertion into messages processed by that Outbound Profile.

DIJ

The DIJ is treated as a control file for the messages needing to be processed. It provides Digital Delivery with the necessary message header fields for each message as will as specifying other message fields such as attachment names.

36


Digital Delivery expects to locate a DIJ file for processing in the folder specified for a given Outbound Profile. It is important that all other content required by an Outbound Profile exists in the specified folders before the DIJ is made available to Digital Delivery. Otherwise, Digital Delivery will raise an exception if it cannot find the content required for the creation of the messages described in the DIJ.

A real-time Outbound Profile expects to find metadata for a single message in the DIJ file (i.e. there should only be one document element in the DIJ).

A batch Outbound Profile expects to find metadata for multiple messages in the DIJ file (i.e. there should be one or more document elements in the DIJ).

The DIJ should be given a unique name when it gets written into the DIJ folder. For example:

• “UniqueName123.dij” or

• “UniqueName123.jrn” or

• “UniqueName123.xml”

Plain text

E-mailPlain text generated by the Designer/Generate Linedata output driver that is intended for placement in the plain text body part of an e-mail should get written into text folder specified by an Outbound Profile.

A real-time Outbound Profile expects to find a single page in the text file (i.e. there should only be one “1” in column one of the entire linedata file).

A batch Outbound Profile expects to find multiple pages in the text file, one for each message (i.e. there may be multiple “1”s in column one of the linedata file – one for each message).

SMS

An Outbound Profile for sending SMS expects to find the message content in a journal file of the format described in Special considerations for SMS content section on page 35 of this guide in the text folder specified by an Outbound Profile.

A real-time Outbound Profile expects to find a single entry in the journal file (i.e. there should only be one “Message for:” line in the entire journal file).

A batch Outbound Profile expects to find multiple entries in the journal file, one for each message (i.e. there may be multiple “Message for:” lines in the journal file – one for each message).

The text filenames should have the same unique name (except for file extension) as the DIJ containing the metadata for the messages. For example: “UniqueName123.txt”.

37


HTML

HTML generated by the Designer/Generate eHTML output driver that is intended for placement in the HTML body part of an e-mail is written into the HTML folder specified by an Outbound Profile.

A real-time Outbound Profile expects to find a single message in a single HTML file (i.e. there should only be one HTML document in the file). A batch Outbound Profile expects to find either:

multiple individual HTML files, one for each message (i.e. there should be separate HTML files for each message) -or-a single compound HTML file. A compound eHTML file is a single file that contains all eHTML documents, which are formatted for a given run, concatenated together in a single file.

Filenames (for Real-time Outbound Profiles)For real-time Outbound Profiles, the HTML filenames should have the same unique name (except for file extension) as the DIJ containing the metadata for the messages. For example: “UniqueName123.html”.

Filenames (for Batch Outbound Profiles)DOC1 version 5.4 and earlierFor batch Outbound Profiles, the HTML filenames should exist of two parts. The first partshould equal the unique name (except for file extension) of the DIJ containing the metadatafor the messages. The second part should be a sequence number, padded to seven digits, ofthe message in the DIJ that the HTML needs to be associated with. The two parts of the nameshould be separated by an underscore, “_”, and the file extension should be “.html” Forexample:

• “UniqueName123_0000001.html”



DOC1 version 5.5 and laterDOC1 version 5.5 introduced an eHTML driver option to output compound eHTML. A compound eHTML file is a single file that contains all eHTML documents, which are formatted for a given run, concatenated together in a single file. Compound eHTML that is being submitted to Digital Delivery for processing by a batch Outbound Profile should have the same unique name (except for file extension) as the DIJ containing the metadata for the messages. For example: “UniqueName123.html”.

digital delivery DOES NOT SUPPORT DIRECT

PROCESSING OF THE XML-PAK GENERATED BY THE

DESIGNER/GENERATE HTML DRIVER.

38


PDF

An Outbound Profile can be configured to attach any number of attachments to an e-mail message. These attachments are configured in Digital Delivery Outbound Profile as Attachment 1, Attachment 2, Attachment 3… Attachment X. Each attachment can be configured to be:

Static or personalized – Static implies that the attachment content does not change from one message to the next and personalized means that the attachment is specific to a particular message

Optional or compulsory – An optional attachment may be selected for attachment to some messages and skipped by other messages processed using the same Outbound Profile

Archived or not – Specifies if the attachment is to get archived

To view / update configuration for each attachment: select Home / Operational Settings / Outbound Profiles and click on appropriate 0utbound Profile under the Name column of the Outbound Profiles page. When the Outbound Profiles Setting page is displayed, scroll down to the attachments settings table to view / update configuration fields.

PDFs generated by the Designer/Generate PDF output driver intended as e-mail attachments are written into one of the Attachment folders specified for “Attachment 1", “Attachment 2", “Attachment 3" or any “Attachment X” in an Outbound Profile. The settings for the attachment should be appropriate for the content being written. For example if an attachment is configured to be compulsory (i.e. not optional) then an exception will be raised by Digital Delivery if it is unable to locate the required attachment for a message.

Attachments configured to be static in an Outbound Profile can have multiple files placed in the attachment folder. The attachment that gets attached is the file whose name is equal to the AttachNameX value in the DIJ. If this attachment is set to optional in the Outbound Profile then no attachment is used when the AttachNameX value in the DIJ is left blank. If this value is blank and the attachment is not set to be optional then Digital Delivery will raise an exception.

For personalized attachments, a real-time Outbound Profile expects to find a single file, containing content for a single message, in the attachment folder. If the attachment is configured to be optional in the Outbound Profile then the attachment may be skipped for a given message (i.e. nothing gets placed in the attachment folder) provided the AttachNameX value in the DIJ is also left blank, otherwise Digital Delivery will raise an exception.

For personalized PDF attachments, Digital Delivery expects to find either a single compound PDF file, or an individual PDF file for each message. In the case of a single compound PDF file, the main part of the filename must equal that of the DIJ being processed and the order of documents in the compound PDF file MUST match the order of

39


the message descriptions in the DIJ. In the case of individual PDF files, the PDF file to be attached to the first message described in the DIJ is main_part_of_DIJ_filename_0000001.pdf, then main_part_of_DIJ_filename_0000002.pdf, etc. The numbering in the individual PDF filenames MUST match the order of the message descriptions in the DIJ being processed. By default, this would always be the case, provided the compound or split PDF and DIJ are generated by the same Generate job. Additional content verification based on Document Instance ID can be configured in an Digital Delivery Outbound Profile, to guarantee that the correct content is always attached to a given message.

Note: You are recommended to turn OFF Content Verification option when using EngageOne.

Filenames (Personalized PDF)

The PDF filenames should have the same unique name (except for file extension) as the DIJ containing the metadata for the messages to which they are to be attached. For example: “UniqueName123.pdf”.

When the PDF document gets attached to a message, Digital Delivery will apply the name provided in the AttachNameX value in the DIJ. That way the filename applied to e-mail attachments can be personalized on a message by message basis.

Filenames (Static PDF)

As outlined above, the PDF filenames for static attachments should be as they are to appear when attached to an e-mail. For example:

• Terms & Conditions.pdf

• Cancellation Policy.pdf

When the PDF document is attached to a message, Digital Delivery will apply the same name as the filename selected for attachment in the AttachNameX value in the DIJ.

Non-Designer/Generate content & Digital Delivery

EngageOne Digital Delivery can be configured to package and send content coming from non-Designer/Generate systems into e-mail or SMS messages. Contact Pitney Bowes Software Professional Services if you require advice on processing non-Designer/Generate content through Digital Delivery.

40


Vault

General

Digital Delivery can be configured to prepare both in- and out-bound e-mail and SMS messages for archiving in Vault. Archive preparation functions performed by Digital Delivery include:

• Automatic or minimum click indexing of e-mail and 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 or PDF/a prior to archiving including the following options:

• Extraction of files in ZIP attachments 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. Please refer to the Vault Customizing Guide for additional information on the “collections” format.

The rest of this section explains how to configure Vault to work with Digital Delivery. Please refer to Outbound Profiles and Inbound Profiles sections of the EngageOne Digital Delivery Users Guide for instructions on how to configure Digital Delivery to prepare message content for archiving in Vault.

Automatic or minimum click indexing

General

Vault can receive index data in either a plain text or XML journal file. Content archived using the Vault “collection” format, as is used exclusively by Digital Delivery, must use the plain text journal in order to load correctly.

Digital Delivery can be configured to generate the required plain text journal file for the archiving of both in- and out-bound e-mail and SMS messages which it processes.

Outbound content

EngageOne Digital Delivery indexes outbound content based on the index values provided in the DIJ. See the DIJ section on page 24 for details on how to configure the correct DIJ values in Designer.

41


Custom index settings in the Vault profiles.ini file instruct Vault as to which settings to apply to the index values it gets from journal files provided by Digital Delivery. The filemap section of the profiles.ini should map the name of each Digital Delivery Outbound Profile (that has archiving enabled) to a profile that is able to load and index the “collections” and journal files provided by Digital Delivery. See Vault Configuration File Settings section on page 46 for the minimum profile settings required to load content prepared by Digital Delivery into Vault.

It should be noted that besides the Digital Delivery specific index keys and values outlined in Other Custom DIJ Fields section above, you can continue to use any other custom index values you wish and apply these to e-mail and SMS messages too by simply including them as custom values in the DIJ that is processed by Digital Delivery. Digital Delivery passes these values directly through, as attribute key / value pairs, in the plain text journal it produces.

Inbound content

GeneralIt should be noted that EngageOne Digital Delivery can be configured to archive ad-hoc e-mail messages, inbound or outbound, by configuring rules on your mail server to forward or copy messages to a specific e-mail account, sometimes called a journaling account. An Digital Delivery Inbound Profile can then be configured to access these messages as it does any other inbound messages.

Associating messages with a Vault customer recordEngageOne Digital Delivery indexes inbound messages by performing Vault API look ups. Depending on the Inbound Profile settings, Digital Delivery will take the “To” or “From” header field from an e-mail or SMS and perform the following Vault API look ups to try and associate the message content with a specific customer and thereby maintain a customer centric view with minimum user intervention:

• Request matches for the complete, plain e-mail address, e.g. [email protected], by searching the e-mail index in Vault. The index number for the e-mail index is specified in the Inbound Profile

• If there are multiple matches on the above search, then Digital Delivery will request an operator to select the most appropriate match from a dropdown of options

• If there are zero matches on the above search, Digital Delivery will extract the likely surname from the e-mail address based on the following rules; [email protected], [email protected], or [email protected], and request matches for, e.g. “smith”, by searching the name index in Vault. The index number for the name index is specified in the Inbound Profile


42


• If there are zero matches on the above search, then Digital Delivery will request an operator to enter an account number, name and address for the sender (or receiver) of the message to create a new customer record in Vault. Vault API lookups are available in this operator interface too to minimize the number of keystrokes required to index messages with zero matches

In the case of an inbound SMS message, Digital Delivery would perform the following Vault API look ups to try and associate the message content with a specific customer and thereby maintain a customer centric view with minimum user intervention:

• Request matches for the MSISDN (mobile number), e.g. “447795504506”, by searching the MSISDN index in Vault. The index number for the MSISDN index is specified in the Inbound Profile


• If there are zero matches on the above search, then Digital Delivery will request an operator to enter an account number, name and address for the sender (or receiver) of the message to create a new customer record in Vault. Vault API lookups are available in this operator interface too to minimize the number of keystrokes required to index messages with zero matches

The EngageOne Digital Delivery Inbound Profile settings dictate the level of automation and accuracy that is achieved when indexing inbound messages. Automatic indexing can be configured in an Inbound Profile to take place in one of the following scenarios:

• Never

• On single match for e-mail address search (or single match for MSISDN search in the case of SMS)

• On single match for name search

Custom index settings in the Vault profiles.ini file instruct Vault as to which settings to apply to the index values it gets from journal files provided by Digital Delivery. The filemap section of the profiles.ini should map the name of each Digital Delivery Inbound Profile (that has archiving enabled) to a profile that is able to load and index the “collections” and journal files provided by Digital Delivery. See Vault Configuration File Settings section on page 46 of this guide for the minimum profile settings that are required to load content prepared by Digital Delivery into Vault.

Single instance storage and message IDBesides the customer record indexes that are applied to every message to link messages to a customer centric view, Digital Delivery can optionally be configured to ensure single instance storage of messages that have multiple addressees. This is achieved by creating a unique Message ID index for every message stored. When “Delete Duplicates” is enabled in an Inbound Profile Digital Delivery will check if messages with the same Message ID have been archived previously and skip archiving of duplicates.

The index number of the Message ID index in Vault is specified in an Inbound Profile setting to enable Digital Delivery to perform the above mentioned API look-ups.

43


It is important to note that even when only a single instance of a message is stored, the message can still be located and retrieved using any of the e-mail recipient addresses on the original e-mail header. This is achieved by the configuration of the Content Pointer (Cpointer) indexes described in the next section.

The Message ID is also used in the workflow XML objects created by Digital Delivery to allow external systems, for example third-party workflow solutions, to connect directly to messages and their related message parts (e.g. attachments) via a URL link or directly through Vault’s API set.

Content pointer (Cpointer) indexesA Cpointer is an index that directly locates content that has been archived in Vault by Digital Delivery. A single message can exist of multiple content parts (e.g. body, attachments, etc.) and each part can have multiple Cpointers for the sender and different recipients of the message.

Cpointer indexes and their values are automatically created by Digital Delivery. The format of Cpointer index values is as follows:

1. From Sender@ domain.com_20071001173425_Part_Subpart or

2. To recipient@ domain.com_20071001173425_Part_Subpart or

3. CC recipient @ domain.com_20071001173425_Part_Subpart or

4. BCC recipient @ domain.com_20071001173425_Part_Subpart

Additional message metadataBesides the indexes listed above, Digital Delivery also creates the following message attributes. These are not intended to be searchable indexes but useful values to return with the results of searches on searchable indexes to, for example, be able to differentiate the different parts of a message when presented to a user in a list.

MIMEThe MIME attribute value is populated with the content-type value of content as it was in the original (e-mail) message prior to any conversion.

DescriptionThe description attribute value is populated as follows:

• If the entire e-mail message is stored in its raw (RFC-822) format then the description attribute value equals the contents of the e-mail’s subject line. The option exists to append the subject with a fixed descriptor, for example “(whole)”. Refer to Property Settings on page 76 for details.

THERE IS A SPACE AFTER [FROM, TO OR CC] AND

A SPACE AFTER THE @ SYMBOL. THIS IS TO

ENABLE ENHANCED SEARCHING IN VAULT, E.G.

FILTERING MESSAGES SENT TO, RECEIVED FROM,

CC’D OR BCC’D TO AN ADDRESS AS WELL AS

SEARCHING FOR E-MAIL EXCHANGED WITH ALL

INDIVIDUALS AT A PARTICULAR COMPANY / DOMAIN

NAME.

44


• If a main e-mail body part (i.e. not an attachment) is stored separately then the description attribute value equals the contents of the e-mail’s subject line. The option exists to append the subject with a fixed descriptor, for example “(body)”. Refer to Property Settings on page 76 for details.

• If an e-mail’s attachment is stored separately then the description attribute value equals the original name of the attachment, or the original filename within a ZIP file if ZIP extraction is enabled. The option exists to append the filename with a fixed descriptor, for example “(attachment)”. Refer to Property Settings on page 76 for details.

In case, if the description length exceeds size limit (255 characters), then extra length will be truncated to fit in the limit including three dots at the end keeping the suffix parts ( (whole), (body) and (attachment)) intact.

ExpireFor future use. This populates an attribute with a content expiry date, formatted YYYYMMDD, to allow a document repository to purge content at the end of its life. This feature is not currently supported by Vault. It is currently possible to set the retention in months for all messages or documents processed by a single profile (Inbound or Outbound profile)

45


Vault configuration file settings

Profiles.iniThis file has important settings for compressing, decompressing and indexing content that is loaded into Vault. The following profile settings are recommended to make Vault correctly load and index content that is prepared by Digital Delivery.

[SampleProfile]Format=collectionDocuments=ujournalJournalCodePage=UTF-8Database=defaultMaxInstances=200PurgeMonths=84CustomIndexing=1IndexQueuing=1Index1=account,cust.account,jcrtul,Account NumberIndex2=name,cust.name,jcrtul,NameIndex3=address,cust.address,jcrtul,AddressIndex4=invlink,doc.date,dhasb,Document Date (YYYYMMDD)Index5=email,email,jctul,EmailIndex6=msisdn,msisdn,jcrtul,Mobile Phone NumberIndex7=MessageID,MessageID,dhb,Message IDIndex8=Cpointer,Cpointer,dhmrb,Cpointer (Header E-mail_Datetime_Part)

Format=collection allows ad-hoc content of any format to be stored in a combined compressed file and retrieved in its original format

Document=ujournal sets the journal file format to Unicode plain text. Plain text journals are required for archiving content in the “collection” format. The Unicode setting serves two purposes: 1) support for international characters in the index values and 2) an increased storage allocation for the storage of document attributes. This can be important when archiving messages with many recipients where a Cpointer index gets created for each recipient

JournalCodePage=UTF-8 specifies the codepage used by the journal file.

Database=default a comma separated list of databases in which index tables will be built for messages indexed by this profile

MaxInstances=200 sets the maximum number of entries for a single index key per message. Defaults to 8 but a considerably higher number is required if you are planning to archive messages with many recipients and create Cpointer indexes for each recipient

PurgeMonths=84 specifies the retention period for messages loaded by this profile. This setting is optional

CustomIndexes=1 enable custom indexing in support of the message indexes created and provided by Digital Delivery

46


IndexQueuing=1 speeds up index building process

IndexX=… copy these custom index settings directly into your profile. You may change the last field of the value to a more appropriate description. Some of the indexes have the “r” flag set to enable rotations. This allows searching for archived content using partial index values, e.g. searching by phone number commencing with or without International dialling code or searching for messages using the e-mail username or the domain name part of the address, etc. Additional custom indexes may also be configured as required. The order of these indexes does not matter. However, the correct number for each index must be configured in Digital Delivery Inbound and Outbound profiles to allow Digital Delivery to perform the necessary API look-ups.

Please refer to the Vault Customizing Guide for additional details on the profiles.ini settings.

Database.iniThis file specifies:

• Searches available against different Vault databases and their descriptions

• Settings for the above

• The default values to return in a table, including table column headings, for searches against the different index keys

• The default language and sort order

The following database settings are recommended for Digital Delivery to correctly perform the API look-ups it needs against Vault for the successful indexing and retrieval of message content.

[default]LanguageDefault=*LanguageN=*description=Default DatabaseIndex1=account,cust.account,jcrtul,Account NumberIndex2=name,cust.name,jcrtul,NameIndex3=address,cust.address,jcrtul,AddressIndex4=invlink,doc.date,dhasb,Document Date (YYYYMMDD)Index5=email,email,jctul,EmailIndex6=msisdn,msisdn,jcrtul,Mobile Phone NumberIndex7=MessageID,MessageID,dhb,Message IDIndex8=Cpointer,Cpointer,jdhmrb,Cpointer (Header E-mail_Datetime_Part)Render1=Account;Name;Address,cust.account;cust.name;cust.addressRender2=Name;Account;Address,cust.name;cust.account;cust.addressRender3=Address;Account Number;Name,cust.address;cust.account;cust.nameRender4=Date;Content-type;Description,doc.date;mime;DescriptionRender5=E-mail;Account;Name;Address,int.match;cust.account;cust.name;cust.addressRender6=Mobile Phone Number;Account;Name;Address,int.match;cust.account;cust.name;cust.addressRender7=Message

47


MS)

S)

MS)

S, if

MS)

S)

MS)

ID;Date;Content-type;Description,MessageID;doc.date;mime;DescriptionRender8=Cpointer;Date;Content-type;Description,int.match;doc.date;mime;Description

Additional custom indexes may also be configured as required. The order of these indexes does not matter. However, the correct number for each index must be configured in Digital Delivery Inbound and Outbound profiles to allow Digital Delivery to perform the necessary API look-ups.

Refer to the Vault Reference Guide for additional details on the database.ini settings.

Sample journal fileThis section is purely for informational purposes to provide you with an overview of the layout of a typical journal file created by Digital Delivery.

Text journal file example for single piece of content, e.g. e-mail with no attachment or SMS message:

Text journal file example for related pieces of content, e.g. e-mail with one attachment:

NOTE THAT A SINGLE PIECE OF CONTENT CAN

HAVE MULTIPLE CPOINTER INDEXES AND THAT

THERE IS A SPACE AFTER [FROM, TO, CC OR

BCC] AND A SPACE AFTER THE @ SYMBOL. THIS

IS TO ENABLE ENHANCED SEARCHING IN VAULT,

E.G. FILTERING MESSAGES SENT TO, RECEIVED

FROM OR CC’D TO AN ADDRESS AS WELL AS

SEARCHING FOR E-MAIL EXCHANGES WITH ALL

INDIVIDUAL AT A PARTICULAR COMPANY / DOMAIN

NAME.

J|InProfile|datetime (or OutProfile)A|MessageID|mthomas@comp_a.com_20070110163110_32432452 (mthomas@comp_a.com_datetime_MsgIndexID)

A|Cpointer|From mthomas@ comp_a.com_20070110163110_1 (From mthomas@ comp_a.com_datetime_part)

A|Cpointer|To jsmith@ comp_b.com_20070110163110_1 (To jsmith@ comp_b.com_datetime_part, not for S

A|Cpointer|To m.lee@ comp_c.com_20070110163110_1 (To m.lee@ comp_c.com_datetime_part, not for SM

A|Cpointer|CC a.hall@ comp_c.com_20070110163110_1 (CC a.hall@ comp_c.com_datetime_part, not for S

A|email|from (if inbound email), to (if outbound email)

A|MSISDN|FromMobPhoneNo (if inbound SMS), to (if outbound SMS)

A|Description|Description (Email subject header, first 40 characters of SMSMS)

A|Expire|YYYYMMDD

A|mime|mime

A|Name|Value (for each additional DDSDocValue in DIJ)

D|account|YYYYMMDD|Filename_incl_ext|Full Name|Full Address

J|InProfile|datetime (or OutProfile)A|MessageID|mthomas@comp_a_20070110163110_32432452 (mthomas@comp_a.com_datetime_MsgIndexID)





48


MS, if

MS)

S)

MS)

Folder permissions

When EngageOne Digital Delivery prepares content and indexes for batching into “collections” and loading into Vault, it creates subfolders in the Vault’s Download folder and writes the content and indexes requiring loading into this folder. If Vault resides in a server different from where Digital Delivery is hosted, Vault’s download folder will need to be shared (UNC-accessible) to provide Digital Delivery with remote access. You can secure the shared folder by allowing read-write access only to the remote account running the Digital Delivery service. Consult your Digital Delivery administrator to obtain the account information for the logged-in user who started the Digital Delivery web application.

Retrieving message content from Vault

Messages archived in Vault can be retrieved using any of the following interfaces:

• Vault Web View Generic Interface (the sample Perl web application provided with Vault Web View/Render Server)

• Vault Desktop (Thick) Clients

• Your business systems using the Vault Render API sets

The rest of this section explains how to configure the search and retrieval from Vault for messages that have been loaded by Digital Delivery.



A|Description|Description (Email subject header, first 40 characters of SSMS)

A|Expire|YYYYMMDD

A|mime|mime



A|MessageID|mthomas@comp_a.com_20070110163110_32432452 (mthomas@comp_a.com_datetime_MsgIndexID)







A|Description|Description (if inbound SMS), to (if outbound SMS)

A|Description|Description (Filename of attachment)

A|Expire|YYYYMMDD

A|mime|mime



49


Vault Web View

No special settings required other than the profiles.ini and database.ini settings described in Vault Configuration File Settings section on page 46 of this guide.

Vault Desktop (Thick) Clients

No special settings required other than the profiles.ini and database.ini settings described in Vault Configuration File Settings section on page 46 of this guide.

Vault Render API Sets

This section describes special considerations and tips when configuring your business applications to access the Vault Render API to retrieve messages which were prepared for archiving by Digital Delivery. This section is not intended as a comprehensive guide on using the Vault Render APIs. Refer to the Vault Reference Guide for further details.

The rest of this section assumes that the Vault profile and database settings have been configured as described Vault Configuration File Settings section on page 46 of this guide.

Customer centric searchesCustomer centric searches are searches to locate a customer’s virtual folder in Vault. A virtual folder is presented as scrollable lists of metadata describing all communications that have been archived for a given customer. Communications are linked to a customer’s virtual folder by the Account Number index. Virtual folders are easily located by searching against the Account Number index with a specific or partial Account Number value. If the Account Number is not known by a user, it and its associated virtual folder can be located by performing searches against any of the following customer indexes:

• Customer Name (standard index). It is possible to search the name index using the full name, first name or last name

• Customer Address (standard index). It is possible to search the address index using the full address, with spaces between the address lines, or using a single address line value such as ZIP

• E-mail (Digital Delivery custom index)

• MSISDN (Digital Delivery custom index). To comply with the MSISDN format (see MSISDN), other 0’s, 1’s or +’s should not be appended to the front of the number. The number must also not contain any spaces.

Customer centric searches follow the standard Vault behavior, there are no special considerations to be taken into account, other than the fact that customers and their virtual folders can be located using a customer’s e-mail or mobile number too.

Whole messages versus message partsE-mail messages can consist of multiple parts, e.g. a text part, a HTML part and attachments. If an attachment is a ZIP file then sub-parts will also exist. The ZIP file is considered as the message part and each of the files inside the ZIP file a sub-part.

50


Depending on EngageOne Digital Delivery Inbound and Outbound profiles settings, any of the following may be archived:

• Nothing

• Complete Original Message Only

• Original Parts & Complete Original

• Original Parts – ZIP content extracted & Complete Original

• Converted Parts – PDF & Complete Original

• Original Parts only

• Original Parts – ZIP content extracted only

• Converted Parts – PDF only

Depending on the archive settings configured in Digital Delivery, multiple pieces of content may be archived for a single message. The purpose being to allow contact center agents to retrieve and view any part of a message, including its attachments, without the need for any specialized e-mail client or viewing software.

When the multiple parts of a message are archived separately, they remain associated together by their Message ID index. In this scenario a search on a unique Message ID could return multiple results, one for each of the message parts. By default the Vault profile and database settings recommended above would return:

• MessageID

• Date

• Original Content Type

• Description

• Expiry Date

Certain Vault Render API calls such as Mode 86 (Extended Index Query with Page Count) and the Unicode “search” function will also return:

• Document type

• Document file (compressed file name)

• Document offset (in the compressed file)

The message parts data listed above should be presented to the user in a tabular format with a URL for each message part that can be used to submit a subsequent API request to retrieve the actual content of any of the message parts. The requested display format for any of these parts should always be set to “collection” (D=10) for any content that has been archived by Digital Delivery. This is the default behavior for the generic Vault Service Web application when using the profile and database settings provided above.

51


If you are using your own application to access the Vault Render API then you might need to modify its behavior to support retrieving single messages that consist of multiple message parts as outlined above.

Retrieving message contentActual message content can be retrieved in various ways using the Vault Render APIs.

By Account Number, Date, Document Type, File and Offset Information

If the above information is available from a previous API request, e.g. Mode 86 (Extended Index Query with Page Count) or the Unicode “search” function, then this can be used to retrieve the content of a specific message part using Mode 84 (Extended Render Document) or the Unicode “render” function.

Remember to set the display format to “collection” (D=10), for the correct display of content that has been archived by Digital Delivery.

By Message IDWhen the multiple parts of a message are archived separately, they remain associated together by their Message ID index. That means that a search on a unique Message ID could return multiple results, one for each of the message parts. By default the Vault profile and database settings recommended above in section would return:

• MessageID

• Date

• Original Content Type

• Description

• Expiry Date

Certain Vault Render API calls such as Mode 86 (Extended Index Query with Page Count) and the Unicode “search” function will also return:

• Document type

• Document file (compressed file name)

• Document offset (in the compressed file)

The message part data listed above should be presented to the user in a tabular format with a URL for each message part that can be used to submit a subsequent API request to retrieve the actual content of any of the message parts. The requested display format for any of these parts should always be set to “collection” (D=10) for any content that has been archived by Digital Delivery. This is the default behavior for the generic Vault Service Web application when using the profile and database settings provided in here.

If you are using your own application to access the Vault Render API then you might need to modify its behavior to support retrieving single messages that consist of multiple message parts as outlined above.

52


By Content Pointer (Cpointer)A Cpointer is an index that directly locates content that has been archived in Vault by Digital Delivery. A single message can exist of multiple content parts (e.g. body, attachments, etc.) and each part can have multiple Cpointers for the sender and different recipients of the message.

Cpointer indexes and their values are automatically created by Digital Delivery. The format of Cpointer index values is as follows:

• “From Sender@ domain.com_20071001173425_Part_Subpart” or

• “To recipient@ domain.com_20071001173425_Part_Subpart” or

• “CC recipient @ domain.com_20071001173425_Part_Subpart” or

• “BCC recipient @ domain.com_20071001173425_Part_Subpart”

Note that there is a space after [From, To or CC] and a space after the @ symbol. This is to enable enhanced searching in Vault, e.g. filtering messages sent To, received From, CC’d or BCC’d to an address as well as searching for e-mail exchanges with all individuals at a particular company / domain name.

Therefore despite only storing a single instance of each message part, the message parts can be located using the full e-mail address or only the domain part of the e-mail address for any of the recipients.

Example 1Searching the Cpointer index for the value “To [email protected]” will return a list of all message parts of all messages sent to [email protected] and archived by Digital Delivery.

Example 2Searching the Cpointer index for the value “[email protected]” will return a list of all message parts of all messages sent to, From, cc or bcc [email protected] and archived by Digital Delivery.

Example 3Searching the Cpointer index for the value “domain.com” will return a list of all message parts of all messages sent to, From, cc or bcc anyone at domain.com and archived by Digital Delivery.

Example 4Searching the Cpointer index for the value “domain.com_20071011” will return a list of all message parts of all messages sent to, From, cc or bcc anyone at domain.com, after the date 11 October 2007 and archived by Digital Delivery.

Retrieving message metadataThe Vault Render API provides several functions to retrieve all metadata that has been associated with a specific message or message part. These API calls include Mode 85 (Extended Document Attributes) and the Unicode “list.attributes” API function. These API

53


calls can be used to retrieve information such as all of the recipients of a specific message or message part. Below is an example of the values that a Mode 85 (Extended Document Attributes) call returns. All the message recipients can be determined from the Cpointer values.

int.file;20070110-e-mail-39965-39965-schiphol-txtint.pointer;0000005000000000doc.account=123456789doc.date=2007/01/10doc.name=Michael Thomasdoc.address=1096 High Street, London SW12 7JKdoc.invoice=doc.type=.jpgdoc.pages=1file.name=michael.thomas@company_a.com_20070110125434000_1.txtfile.size=59442file.block=262144Description=ConfirmationMime=text/plainExpire=20070710MessageID= michael.thomas@company_a.com_20070110125434_324534875Cpointer=from michael.thomas@ company_a.com_20070110125434_1Cpointer=to m.lee@ company_d.com_20070110125434_1Cpointer=to h.harris@ company_d.com_20070110125434_1Cpointer=cc j.smith@ company_d.com_20070110125434_1Cpointer=cc s.roberts@ company_d.com_20070110125434_1Cpointer=cc j.rodriguez@ company_d.com_20070110125434_1Cpointer=cc p.byrnes@ company_d.com_20070110125434_1Cpointer=cc a.bennett@ company_d.com_20070110125434_1doc.sections=0

Workflow URLs – Ensuring that they workThe URL that is inserted in the Digital Delivery generated XML workflow objects to allow external systems to view archived message content uses the Message ID index inserted in the URL as a HTTP GET parameter.If you are not using the default Vault Web View application but your own, you must ensure your application responds as required when receiving the MessageID index number and a specific Message ID value in a URL generated by Digital Delivery.

The URL provided by Digital Delivery in the XML based workflow objects it generates is constructed by concatenating the following fields:

• e2_Web_URL (from the Inbound or Outbound profile) e.g “http://somehost/e2/interface.plx?db=default”

54


• “&K=”

MessageID_index (from the Inbound or Outbound profile)

“&Q=”

MessageID constructed from “from” or “to” address, depending on the Inbound Profile PrimaryIndexingOn setting joined by underscore to datetime joined by underscore with MD5 hash of Message-ID value in header

For example:http://somehost/e2/interface.plx?db=default&K=7&Q=michael.thomas@company_a.com_20070110163110_1234567890ABCDEF1234567890ABCDEF

Inlet

EngageOne Digital Delivery also supports Inlet (message type 'Inlet') as a channel to delivery PDF documents to Cloud storage, such as Dropbox, OneDrive, and Evernote. Digital Delivery will provide PDF documents and associated journal (XML) as input to Inlet. Based on the information provided in the journal, Inlet will deliver the documents to the appropriate recipients.

Digital Delivery will upload the documents and associated journal on configured FTP location and will also send an email to the configured email address. How to configure FTP server and email address, refer “inlet.properties” on page 101.

Schedule and control of Data Flow & Generate from EngageOne Digital Delivery

General

Besides submitting content formatted by DOC1, or other systems, directly to Digital Delivery for processing and sending as e-mail or SMS messages as described in Real-Time and Batched Sending of Messages section in the EngageOne Digital Delivery Users Guide, it is also possible to configure Digital Delivery to control and schedule the following tasks through an easy to use web browser interface:

• Execution of Data Flow Plans for the preparation of input data.

• Execution of Generate to format input data into the required message content.

• Execution of Post Process Commands to manipulate output generated by Generate prior to sending.

55


The benefit of being able to control the above from Digital Delivery is that non-technical users can perform e-mail and SMS communications management themselves without being dependent on IT, Designer/Generate or Data Flow specialists for each campaign or batch of messages they wish to send.

In order to control Data Flow Plans, Generate Applications and Post Process commands from Digital Delivery, Digital Delivery needs to be configured to control these processes. Configuration should be done by users with knowledge of these systems. The user will require Edit Data Flow and Edit DOC1 permissions to be associated with their role in Digital Delivery.

Apart from scheduling the actual sending of messages, Digital Delivery scheduled jobs can also include data preparation of uploaded files and content formatting by Generate prior to sending - all through a simple web browser interface.

The rest of this section explains how to configure Digital Delivery to control Data Flow Plans, Generate Applications and Post Process commands.

Local and remote control

EngageOne Digital Delivery can be configured to control Data Flow Plans, Generate Applications and Post Process commands running locally on the same physical server as Digital Delivery or on a separate server.

Digital Delivery controls Data Flow Plans, Generate Applications and Post Process commands using a small Java application that needs to be installed on the remote server. This Java application is controlled by Digital Delivery using Remote Method Invocation (RMI). When running on separate servers it is recommended to use Uniform Naming Convention (UNC) to specify the input and output locations for all files that require processing. This ensures that there is no confusion between file inputs and outputs on different servers.

Data Flow

EngageOne Digital Delivery executes Data Flow Plans using Data Flow’s sarun command. The full sarun command needs to be specified to Digital Delivery as if it were being called locally from the server where the Data Flow Service is running. Please refer to the Data Flow User Guides for full instructions on using sarun.

Data Flow Plans can only be executed from Digital Delivery in combination with a subsequent Generate job to format the data into the required message content.

To avoid files overwriting each other Digital Delivery creates unique names for the input and output files processed by Data Flow. Digital Delivery passes these unique input and output filenames to sarun using command line arguments. That means that the Data Flow Plan being called should be configured to accept input and output filenames as Custom Plan Properties.

56


The Custom Plan Property for the input file should be called CPP_In_File and Custom Plan Property for the output f3ile should be called CPP_Out_File. This allows Digital Delivery to establish which parts of the command string to replace with its own unique input and output filenames for a given scheduled job before it calls sarun.

Example of sarun command:

sarun "Maintenance Data" "sagentuser:sagentpass:ODBC:MySQL:sagent_repository:dbuser:dbpass" "CPP_In_File=\\DFShost\In\Uploaded.csv" "CPP_Out_File==\\DFShost \Out\DOC1_Input.csv" -w

It is recommended to use the –w flag in the sarun command, as in the example above, to ensure that the Data Flow Plan completes execution prior to subsequent processes being triggered.

The sarun command can be given an easy to recognize name and description to allow non-technical users to select a Data Flow Plan to prepare their input data using the simple web browser interface provided by Digital Delivery.

The Data Flow Plan needs to output data in a format that has been defined as the input Data Format used by the Designer application that is called after Data Flow completes.

Sarun must execute on the server where the Data Flow Service is running. It is important to ensure that the user account that runs the Data Flow Service has the necessary read and write permissions to the folders being read from and written to. Generally the user account that runs the Data Flow Service should be given both read and write permissions for the root folder that is specified for Digital Delivery. See the Folder Permissions section on page 49 of this guide for details.

When Digital Delivery calls sarun it waits for the exit code before continuing the processing of a Scheduled Job (provided the sarun command includes the -w flag). If the exit code is “0” then Digital Delivery will call the subsequent Generate Job. Digital Delivery raises an exception and discontinues the processing of a scheduled job for all other sarun exit codes.

Generate & Post Process command

Generate

EngageOne Digital Delivery executes Generate jobs using the doc1gen commands. The full doc1gen command must be specified to Digital Delivery as if it were being called locally from the server where Generate is installed. Refer to the Designer User’s Guides for full instructions on executing doc1gen.

Generate jobs can be executed with or without a preceding Data Flow Plan to format input data. If there is no Data Flow Plan preceding the Generate Job then the input file needs to match the Data Format defined in the Designer application.

57


To avoid files overwriting each other Digital Delivery creates unique names for the input and output files processed by Generate. Digital Delivery passes these unique input and output filenames to doc1gen through the OPS file. Refer to the Designer User’s Guide for additional information on the OPS file settings used with Generate.

The command line specified to call doc1gen may optionally specify an OPS file. It is recommended that the complete doc1gen command entered in Digital Delivery is tested on the server where doc1gen is to be run prior to entering it into Digital Delivery. It should be noted that the server running Digital Delivery must have read access to the folder where the OPS files is located. This could be achieved by referencing the OPS folder using an UNC path, or simply by placing a copy of the OPS file in a folder on the Digital Delivery server, ensuring that this folder has the same local path as the path to the OPS file on the remote server.

If no OPS file is specified in the command line that is calling doc1gen, Digital Delivery will create one that only specifies the I/O for the input data, output stream(s), DIJ(s) and journal(s). If an OPS file is specified in the command line that is calling doc1gen, Digital Delivery will comment out the input and output file specifications and create new ones using the unique filenames it generates for a given scheduled job. Other settings such as software license key will remain unchanged in the OPS file. It is important that settings, other than I/O, are specified correctly either in the HIP file itself or in an OPS file to allow Digital Delivery to be able to call doc1gen successfully.

Example of doc1gen command:doc1gen =\\server\doc1files\Mult_Alt_Attach.hip ops=\\server\doc1files\Mult_Alt_Attach.ops

Digital Delivery requires metadata on the outputs that have been configured in your HIP (create when publishing the template in Designer) so that it can create the correct output, DIJ and journal settings in the OPS file – based on the unique filenames it generates. This is done by associating the Output Aliases in the HIP file (determined from the Publish settings in Designer) with a “Generate Output” and “Message Type” on the Digital Delivery’s Designer/Generate Settings page.

The “Output Format” setting is used to indicate to Digital Delivery the type of output being specified so that an appropriate entry can be created in the OPS file. The Message Type setting tells Digital Delivery the folders that the output should get written to ensure it gets processed by the correct Outbound Profile. The Trash option discards the output and Digital Delivery does not process it any further after doc1gen. This setting is useful when a HIP file is outputting multiple DIJ files, one for each output format, despite Digital Delivery only requiring a single DIJ for the entire message / publication. It is also useful if a HIP file is generating outputs that are not required by Digital Delivery – an AFP print stream for example. For Digital Delivery to be able to successfully call doc1gen, it is important that every output generated by the HIP is correctly specified in Digital Delivery.

The doc1gen command can be given an easy to recognize name and description to allow non-technical users to select a Generate application to format their data into message content using the simple web browser interface provided by Digital Delivery.

58


When Digital Delivery calls doc1gen it waits for the exit code before continuing the processing of a scheduled job. If the exit code is “0” then Digital Delivery will call the subsequent Post Process Command, or sending process. Digital Delivery raises an exception and discontinues the processing of a scheduled job for all other doc1gen exit codes.

Post Process Command

It is possible to specify a Post Process Command to be called after Digital Delivery has successfully executed a Generate Job. A Post Process Command can be used to manipulate the Generated Outputs prior to Digital Delivery sending it.

59


EngageOne Digital Delivery will replace the following special command line arguments with their actual values prior to calling the Post Process Command.

Post Process commands can use Perl, PHP, Ruby or other scripting languages that have been enabled in the Digital Delivery remoteservice.properties file. For further details on this file, please see remoteservice.properties section on page 61 of this guide. The full Post Process Command needs to be specified to Digital Delivery as if it were being called locally from the server where Generate is installed. Note: Digital Delivery always assumes that Post Process Commands will be run on the same server as Generate.

_DIJ_ This command line argument is replaced with the full path and filename of the DIJ generated by the preceding Generate job

Folder_HTML This command line argument is replaced with the full path to the folderthat HTML generated by the preceding Generate job was written to

Folder_Text This command line argument is replaced with the full path to the folderthat text (linedata or journal for e-mail or SMS respectively) generated bythe preceding Generate job was written to

Folder_Attach1 This command line argument is replaced with the full path to the folder that the PDF associated with “PDF Attachment (1)” generated by the preceding Generate job was written to




Folder_AttachX This command line argument is replaced with the full path to the folder that the PDF associated with “PDF Attachment (X)” generated by the preceding Generate job was written to.

An example of a Post Process Command could be:perl sript.pl _DIJ_ Folder_HTML Folder_Text Folder_Attach1 Folder_Attach2Folder_Attach3 Folder_Attach4 Folder_Attach5 Folder_Attach6 Folder_Attach7 Folder_Image

Folder_Image This command line argument is replaced with the full path to the folder specified for images in the Outbound Profile that will send the content, i.e. the folder where images are expected to be located for the HTML generated by the preceding Generate job

60


When specified, a Post Process Command is always executed upon the successful completion of the preceding Generate Job.

An example of a Post Process Command could be:

perl sript.pl _DIJ_ Folder_HTML Folder_Text Folder_Attach1 Folder_Attach2 Folder_Attach3 Folder_Attach4 Folder_Image

When Digital Delivery calls a Post Process Command it waits for the exit code before continuing the processing of a scheduled job. If the exit code is “0” then Digital Delivery will call the subsequent message sending process. Digital Delivery raises an exception and discontinues the processing of a scheduled job for all other exit codes from the Post Process Command.

Security

Digital Delivery limits the security threat that results from allowing users to enter commands for execution by the server operating system in a web browser interface as follows:

User permissions and roles

Access to the pages, where commands for calling Data Flow Plans, Generate and Post Process Commands are entered, is limited to users who have Edit Data Flow and Edit DOC1 permissions enabled in their role. These permissions should only be enabled for users that are allowed to run Data Flow Plans, Generate or Post Process Commands on the servers configured to be controlled by Digital Delivery. That means that users with the required permissions to specify operating system commands through the Digital Delivery interfaces would generally have access to execute the same commands directly on the servers too, therefore reducing the additional risk posed by the Digital Delivery web browser interface to almost zero.

remoteservice.properties file

Commands specified for calling Data Flow Plans, Generate and Post Process Commands from Digital Delivery are only executed if they match the patterns specified in the remoteservice.properties file.

During Digital Delivery set-up an administrator can set the acceptable execution parameter(s) for Data Flow Plans, Generate and Post Process Commands.

Data Flow exampleFor Data Flow, the administrator could enter the following values in the remoteservice.properties file*:

allowed.command.dfs=sarun,sarun.exe,C:\\PathTo\\Sagent\\sarun.exe,C:\\PathTo\\Sagent\\sarun

61


Digital Delivery parses the command entered in the Data Flow Settings web interface to check that it starts with one of the items on this list and raises a validation error if there is no match.

Generate exampleFor Generate, the administrator could enter the following values in the remoteservice.properties file*:

allowed.command.doc1=doc1gen,doc1gen.exe, C:\\PathTo\\doc1gen.exe,C:\\PathTo\\doc1gen

Digital Delivery parses the command entered in the Designer/Generate Settings web interface to check that it starts with one of the items on this list and raises a validation error if there is no match.

Post Process Command exampleFor the Post Process Command, the administrator could enter the following values in the remoteservice.properties file*:

allowed.command.postdoc1=perl,perl.exe,php.exe,php,c:\\perl\\perl.exe,c:\\perl\\perl,c:\\php\\php.exe,c:\\php\\php,*.cmd

Digital Delivery parses the Post Process Command entered in the Designer/Generate Settings web interface to check that it starts with one of the items on this list and raises a validation error if there is no match.

All values specified in the remoteservice.properties file are NOT case sensitive. However, you will need to escape any backslash character you may use (i.e. use two backslashes “\\” to escape a single backslash “\”).

Scheduled jobs

Digital Delivery allows non-technical users to manage and schedule e-mail and SMS customer communications through the Scheduling page.

A scheduled job can include any of the following processes:

• Data Flow for the preparation of input data for Generate

• Generate for the formatting of data into message content

• Post Process Command to manipulate Generate output prior to sending

• Sending of messages

Data Flow PlanIf a Data Flow Plan is selected to be called as part of a scheduled job then the input data that is either uploaded or specified on the server needs to be of the correct input format for the Data Flow Plan being called, otherwise Digital Delivery will raise an exception.

62


GenerateIf a Generate application is selected to be called as part of a scheduled job, in combination with a preceding Data Flow Plan, then the input data that is either uploaded or specified on the server needs to be of the correct input format for the Data Flow Plan being called, otherwise Digital Delivery will raise an exception. Alternatively if a Generate Application is selected without a preceding Data Flow Plan, then the input data that is either uploaded or specified on the server needs to be of the correct input format for the Generate application (in the Data Format defined in Designer), otherwise Digital Delivery will raise an exception.

If a Post Process Command has been configured in the Designer/Generate Settings then this will always get called after Generate successfully completes generating its output.

Scheduling without using Data Flow or GenerateIf neither a Data Flow Plan nor a Generate template is selected to be called as part of a scheduled job, then the input data that is either uploaded or specified on the server needs to be a DIJ that belongs to the outputs that are already present in the folders specified by the selected Outbound Profile. The naming of the DIJ and related content file should be as specified in the DIJ section on page 24 of this guide. If content is not available in the correct folders when the scheduled job starts or if files are named incorrectly then Digital Delivery will raise an exception.

Outbound ProfileThe Digital Delivery Outbound Profile required to send message content is selected from the dropdown.

Start Date & TimeThe date and time that the scheduled job is to commence is specified using the dropdowns. It should be noted that the first process, e.g. Data Flow Plan, of a scheduled job is what will be triggered at the specified start time. Subsequent processes such as Generate, Post Process Commands and message sending are only executed upon the successful completion of the previous steps.

63

Headers – Configuring Additional E-mail Headers

This section explains how to add extra header information for Outbound Messages.

By default, EngageOne Digital Delivery gets the header information for Outbound Messages from Outbound Profile settings first and then from Document Interchange Journal (DIJ) files. DIJ files are XML based and generated during publishing in Designer, or other systems. In cases where a header attribute (e.g. Reply-To) is present in both and contains different values, EngageOne Digital Delivery will disregard the value found in the Outbound Profile settings and will follow the value from the DIJ file.

EngageOne Digital Delivery also allows custom e-mail headers to be defined.

To add or modify extra header information for an outbound profile: modify the header.xml file under <install_path>/core.war/WEB-INF/classes EngageOne Digital Delivery will read the updated file and apply it to the corresponding Outbound Profiles. A sample configuration is given below:

<vendors><vendor name=”Vendor 1”><profile name=”Profile 1”><headers><header name=”Return-Receipt-To” value=”[email protected]” /><header name=”Disposition-Notification-To” value=”[email protected]” /><header name=”X-Confirm-Reading-To” value=”[email protected]” /><header name=”X-Confirm-Delivery-To” value=”[email protected]” /></headers></profile><profile name=”default”><headers><header name=”Return-Receipt-To” value=”[email protected]” /><header name=”Disposition-Notification-To” value=”[email protected]” /><header name=”X-Confirm-Reading-To” value=”[email protected]” /><header name=”X-Confirm-Delivery-To” value=”[email protected]” /></headers></profile></vendor><vendor name=”Vendor 2”><profile name=”Profile 1”><headers><header name=”Return-Receipt-To” value=”[email protected]” /><header name=”Disposition-Notification-To” value=”[email protected]” /><header name=”X-Confirm-Reading-To” value=”[email protected]” /><header name=”X-Confirm-Delivery-To” value=”[email protected]” /></headers></profile>

64


<profile name=”default”><headers><header name=”Return-Receipt-To” value=”[email protected]” /><header name=”Disposition-Notification-To” value=”[email protected]” /><header name=”X-Confirm-Reading-To” value=”[email protected]” /><header name=”X-Confirm-Delivery-To” value=”[email protected]” /></headers></profile></vendor></vendors>

The file structure is per vendor, per Outbound Profile. The syntax of the header names and their values should be in accordance with section 3.2 of RFC822 (Standard for the Format of ARPA Internet Text Messages). Refer to the Validations section on page 66 for further details.

To add or modify vendor-wide extra header information: modify the default-header.xml file under <install_path>/core.war/WEB-INF/classes, EngageOne Digital Delivery will also automatically read the updated file and apply it to all Outbound Profiles of the corresponding vendor. A sample configuration is given below.

<vendors><vendor name=”Vendor 1”><profiles><profile name=” default”><headers><header name=”Return-Receipt-To” value=”[email protected]” /><header name=”Disposition-Notification-To” value=”[email protected]” /><header name=”X-Confirm-Reading-To” value=”[email protected]” /><header name=”X-Confirm-Delivery-To” value=”[email protected]” /></headers></profile></profiles></vendor></vendors>

65


Due to additional configurations, it adds a little complexity to EngageOne Digital Delivery in terms of resolving header configuration. Hence, the retrieval of header information will now always be checked from these 4 sources, and EngageOne Digital Delivery follows a rule for resolving headers for a given Outbound Profile, such that it will evaluate the configuration headers based on order of priority:

i. Will first try to retrieve values from the Journal files

ii. Then, on the Outbound Profile settings on the database,

iii. Then, on the profile-specific configuration defined in the “header.xml”

iv. Finally, on the vendor-wide configuration defined in the “default-header.xml”

Validation

The content of “header.xml “and “default-header.xml” is validated based on the rules defined in the Standard for the Format of ARPA Internet Text Messages in creating the xml file.

field-name (header-name) = 1*<any CHAR, excluding CTLs, SPACE, and ":">field-body (header-value) = field-body-contents [CRLF LWSP-char field-body]field-body-contents = <the ASCII characters making up the field-body, as

defined in the following sections, and consisting of combinations of atom, quoted-string, and specialstokens, or else consisting of texts>

atom = 1*<any CHAR except specials, SPACE and CTLs>quoted-string = <"> *(qtext/quoted-pair) <">; Regular qtext or;quoted chars.

In case of incorrect tags or file format resulting in XML parsing errors, EngageOne Digital Delivery will still continue with the outbound message processing and an error log will be written to corresponding log file for those configuration files that incurred parsing error. In such cases headers will still be evaluated in the order of priority mentioned above and parsing of the badly formatted configuration files will be skipped.

IT IS IMPORTANT NOT TO MODIFY THE NAME

ATTRIBUTE OF THE <PROFILE> TAG, “DEFAULT”.

ENGAGEONE DIGITAL DELIVERY WOULD ALWAYS

LOOKUP FOR THAT VALUE WHEN LOADING THIS

CONFIGURATION FILE. SAME VALIDATION APPLIES

TO THIS CONFIGURATION AS WITH “HEADER.XML”.

A HIGH PRIORITY RULE WILL ALWAYS OVERRIDE

THE VALUE DEFINED ON A LOWER LEVEL PRIORITY

RULE. NOTE ALSO THAT THE VALUES THAT ARE

UNIQUE FOR THE TWO CONFIGURATION FILES,

“HEADER.XML” AND “DEFAULT-HEADER.XML” WILL

BE TREATED AS ADDITIONAL HEADERS FOR THAT

OUTBOUND PROFILE.

66

Headers – Suppressing E-mail headers


Sometimes it is necessary to suppress e-mail message headers for messages destined to certain ISPs. For example the commonly used Return-path header used for routing delivery status information back to the sender can cause messages to be rejected by AOL mail servers (AOL is a large ISP). Therefore EngageOne Digital Delivery provides configurable settings that allow specified e-mail headers to be suppressed from messages destined for certain e-mail addresses. This is configurable on a domain by domain basis using settings in the outbound-settings.xml file. This file is located in <install_path>/core.war/WEB-INF/classes.

For example if you want to remove the Return-path headers for all outbound messages addressed to an AOL e-mail address, then you would modify outbound-settings.xml as follows:

<?xml version="1.0" encoding="utf-8"?><outbound-settings> <suppress-headers> <suppress-header name="RETURN-PATH"> <domain name="aol.com" /> </suppress-header> </suppress-headers></outbound-settings>

You can remove the Return-path headers for messages addressed to other domains by adding additional domain elements as follows:

<?xml version="1.0" encoding="utf-8"?><outbound-settings> <suppress-headers> <suppress-header name="RETURN-PATH"> <domain name="aol.com" /> <domain name=”yahoo.com />” </suppress-header> </suppress-headers></outbound-settings>

NOTE THAT THE NAME ATTRIBUTE FOR BOTH THE

SUPPRESS-HEADER AND DOMAIN ELEMENTS IS NOT

CASE SENSITIVE.

67


You can request certain headers to be omitted for all messages regardless of the domain to which they are address by using an asterisk as follows:

<?xml version="1.0" encoding="utf-8"?><outbound-settings> <suppress-headers> <suppress-header name="RETURN-PATH"> <domain name="*" /> </suppress-header> </suppress-headers></outbound-settings>

If there is more than one e-mail header you wish to suppress then add additional suppress-header elements to outbound-settings.xml as follows:

<?xml version="1.0" encoding="utf-8"?><outbound-settings> <suppress-headers> <suppress-header name="RETURN-PATH"> <domain name="aol.com" /> </suppress-header> <suppress-header name=”ERRORS-TO”> <domain name=”gmail.com” /> </suppress-header> </suppress-headers></outbound-settings>

68

Message Delivery Rate Options

Message Delivery Rate Options

Certain ISPs consider any e-mail server that delivers e-mail to their networks faster than a specific rate to be sending SPAM and places the messages sent by such servers in the SPAM folder. This threshold varies from one ISP to the other.

EngageOne Digital Delivery allows the maximum message sending rate to be set on a domain by domain basis. These settings are system wide and are also in the outbound-settings.xml file. This file is located in <install_path>/core.war/WEB-INF/classes.

For example if you want your EngageOne Digital Delivery installation to never send more than 20 messages per minute to aol.com e-mail addresses, then you would modify outbound-settings.xml as follows:

<delivery-rates><delivery-rate domain="aol.com" rate="20" unit="min" />

</delivery-rates>

Specified domain values are case insensitive. The following units are supported:

Unit Description

sec For second

min For minute

hr For hour

69

Digital Signatures

Digital Signatures

The digital signature feature is only applicable to outbound e-mail messages sent by EngageOne Digital Delivery. If you are sending important communications to your customers via e-mail then it is important for your customers to be sure that the messages they receive:

• Are from the sender they appear to be

• Contain original and authentic content that has not been tampered with on route

The above can be ensured by the use of digital signatures. Therefore your organization should consider digitally signing the e-mail messages it sends to its customers. Applying a digital signature to the “complete” body of outbound e-mail messages is a standard feature that can be configured in EngageOne Digital Delivery. Signing the “complete” body means that all content, including attachments, get signed by the EngageOne Digital Delivery Digital Signature feature.

Digital signatures are based on Public Key Infrastructure (a.k.a. PKI). That means private and public keys are required for digital signatures to work. These keys are associated with digital certificates (format x.509 v3) which can be purchased from a Certificate Authority. Well known certificate authorities include Verisign and Thawte (see www.verisign.com and www.thawte.com). The Certificate Authority makes your public key available to recipient’s e-mail clients to validate that messages they receive from you are authentic. Your private key is, as its name suggests, private and should not be shared. EngageOne Digital Delivery needs the private key to create a digital signature for the messages it sends. It is important that the From address used by Outbound Profiles to send digitally signed messages is the same as the From address associated with the digital certificate! Otherwise the recipients of the messages will be warned by their e-mail client that your messages might be from a different sender to the one in the From address!

There are two files required by EngageOne Digital Delivery in order for it to digitally sign outbound messages. These are the private key file and keys.properties. The private key file store is an encrypted format and has a .p12 filename extension. The password to access the private key is specified when you download a digital certificate or when you export a digital certificate from your browser in .p12 format. This password also needs to be specified in keys.properties so that EngageOne Digital Delivery can access the private key.

When a new Vendor is created in EngageOne Digital Delivery using the Vendor Creation page, a folder called <install_path>/core.war/WEB-INF/classes/<vendor_name>/Default_Keys is created and contains two files called replace_with_real_private_key.p12 and keys.properties. You must replace replace_with_real_private_key.p12 with a real digital certificate / private key combination and update the settings in keys.properties before you can use the digital signature function. Detailed instructions are provided below.

70

http://www.verisign.com

http://www.verisign.com

http://www.thawte.com

Digital Signatures

Whenever an Outbound Profile is saved with the Digitally Sign Message Body setting enabled:

• The folders for that Outbound Profile will include an <outbound_profile_name>/key folder containing a copy of the (default) digital certificate and associated private key (.p12 file) from: <install_path>/core.war/WEB-INF/classes/<vendor_name>/Default_Keys

• A folder called <install_path>/core.war/WEB-INF/classes/<vendor_name>/<outbound_profile_name>is created containing a copy of the (default) keys.properties file from:<install_path>/core.war/WEB-INF/classes/<vendor_name>/Default_Keys

Hence, if the From address used by the Outbound Profile is the same as the From address associated with the default digital certificate /private key then the Outbound Profile can be used immediately. If the From address is different then you will need to update the default digital certificate / private key in <outbound_profile_name>/key with one associated with that Outbound Profile’s From address and update the keys.properties file in: <install_path>/core.war/WEB-INF/classes/<vendor_name>/Default_Keys accordingly.

For installations using WebLogic 12c, the keys.properties and .p12 files need to be copied to the DOMAIN_HOME folder which is usually located under \user_projects\domains\

For example:<WL install>/user-projects/domains/<EM domain>

71

Digital Signatures

Generating a Private Key

A private key is associated with a digital certificate.

Some certificate authorities like www.thawte.com offer digital certificates free of charge if they are for personal use. You can order such a free digital certificate for test purposes by visiting the “Free Personal Email Certificate” section of the Thawte web site.

If your certificate authority provides you your digital certificate and associated private key as a .p12 file together with an associated password then this can be used directly in EngageOne Digital Delivery. Otherwise import the digital certificate into your browser. Some certificate authorities automatically install the digital certificate and associated private key on your web browser as part of their download process.

If this happens then you will need to export the digital certificate and associated private key for use with EngageOne Digital Delivery. This can be done as follows:

• For Internet Explorer:

• Go to Tools -> Internet Options

• Select the Content tab

• Click on the Certificates button found in the Certificates section

• Locate the certificate you wish to export and click on the Export button

• Specify a directory/filename and password for the private key

• For Mozilla Firefox:

• Go to Tools -> Options

• Select Advance tab

• Select Encryption tab

• Click on the View Certificates button

• On the Your Certificate tab, select the certificate and click on the BackUp button

• Specify a directory/filename and password for the private key

NOTE THAT SOME CERTIFICATE AUTHORITIES

REQUIRE YOU USE THE SAME WEB BROWSER ON

THE SAME PC TO:

* PURCHASE A DIGITAL CERTIFICATE.

* DOWNLOAD THE CERTIFICATE ONCE IT HAS BEEN

GRANTED.

* GENERATE A PRIVATE KEY FROM THE DIGITAL

CERTIFICATE.

72

Digital Signatures

keys.properties

This property file contains settings to access your digital certificate’s private key so that EngageOne Digital Delivery can digitally sign outbound messages. The default keys.properties file for a given Vendor is located in:

<install_path>/core.war/WEB-INF/classes/<vendor_name>/Default_Keys

The keys.properties file actually used by a given Outbound Profile is located in:

<install_path>/core.war/WEB-INF/classes/<vendor_name>/<outbound_profile_name>

keys.properties contains the following settings:

If you do not know the alias of the private key you wish to use, then this can be found by viewing the details of your digital certificate in your web browser.

• For Internet Explorer:

• Go to Tools -> Internet Options

• Select the Content tab

• Click on the Certificates button in the Certificates section

• Select the certificate you wish to view the alias name for and click on the View button

• Click the Details tab

• The alias is the value of the Friendly Name field

• For Mozilla Firefox:

• Go to Tools -> Options

• Select Advance tab

• Click on the View Certificates button

• Select the certificate you wish to view the alias name for and click on the View button

Property Description

keystore.password the password to access the private key

keystore.key.alias the alias of the private key in the keystore that is to be used

keystore.filename the base filename of the keystore file located in outprofiles/<outbound_profile_name>/key. Note that generally this file has a .p12 file extension

AS DESCRIBED ABOVE THE DEFAULT

KEYS.PROPERTIES IS COPIED TO

<INSTALL_PATH>/CORE.WAR/WEB_INF/CLASSES/

<VENDOR_NAME>/<OUTBOUND_PROFILE_NAME>

THE FIRST TIME AN OUTBOUND PROFILE IS SAVED

WITH THE DIGITALLY SIGN MESSAGE BODY

SETTING ENABLED. UPDATE THIS SETTING IN

KEYS.PROPERTIES IF YOU DO NOT WISH TO USE

THE DEFAULT PRIVATE KEY. FOR EXAMPLE IF THE

DEFAULT PRIVATE KEY HAS A DIFFERENT E-MAIL

ADDRESS ASSOCIATED THAN THE FROM ADDRESS

USED BY AN OUTBOUND PROFILE, THEN THE

DEFAULT PRIVATE KEY SHOULD BE REPLACED.

73

Digital Signatures

• Click the Details tab

• The alias is the value at the top of the tree in the Certificate Fields section

Triggering or Suppressing Digital Signing

There are two ways to enable the digital signature feature for e-mail messages sent by EngageOne Digital Delivery:

• In the Outbound Profile settings page, select the option Digitally Sign Message Body. This will cause all messages sent by an Outbound Profile to be digitally signed by default.

• Alternatively include a custom field in the DIJ (XML journal) with the name Sign and any of the following values: 1, true or yes.

When Digitally Sign Message Body is enabled for an Outbound profile, it is still possible to disable the digital signature function on a message by message basis by:

• Including a custom field in the DIJ (XML journal) with the name Sign and any of the following values: 0, false or no.

Important Note

Due to import control restrictions, the version of Java (TM) Cryptography Extension (JCE) Policy files that are bundled in the JDK(TM) 7.0 environment allow "strong" but limited cryptography to be used. Your digital certificate might have been configured to use stronger encryption than the encryption supported by the default JCE policy files. This can result in error messages being written to the log files that start with:

Cannot unwrap key …

This means that the digital signing process is failing and therefore the messages are also failing to be sent.

The solution is to upgrade your default JCE policy files with the "unlimited strength" policy files which contain no restrictions on cryptographic strengths.

For Sun's JDK, these can be downloaded from the following URL:

http://www.oracle.com/technetwork/java/javase/downloads/jce-7-download-432124.html

Replace your default JRE policy located in Program Files/java/jdk1.7.0_10/jre/lib/security with the local_policy.jar and US_export_policy.jar that you just downloaded. You will need to restart your application server for the new JCE policy files to take effect.

Note that the newly downloaded files do NOT contain any encryption functionality since such functionality is supported in Sun's JDK 7.0. Therefore, this installation applies only to Sun's JDK 7.0, and assumes that the JDK 7.0 is already installed

74

http://www.oracle.com/technetwork/java/javase/downloads/jce-6-download-429243.html

Digital Signatures

For IBM's JDK (WebSphere), these can be downloaded from the following URL:

http://www.ibm.com/developerworks/java/jdk/security/50/#sdkpolhttps://www14.software.ibm.com/webapp/iwm/web/preLogin.do?source=jcesdk

IBM's SDKs ship with strong but limited jurisdiction policy files. Unlimited jurisdiction policy files can be obtained from the link above. The ZIP file should be unpacked and the two JAR files placed in the JRE's jre/lib/security/ directory. These policy files are for use with IBM developed SDKs. The same files are used for the Version 1.4 and Version 5 SDKs. Details of downloads of unlimited jurisdiction policy files for the Linux platform can be found in the IBM Security Guide for those platforms.

Replace your JRE policy located in: Program Files\IBM\WebSphere\AppServer\java\jre\lib\security with the local_policy.jar and US_export_policy.jar that you just downloaded. You will need to restart your application server for the new JCE policy files to take effect.

75

http://www.ibm.com/developerworks/java/jdk/security/50/#sdkpol

https://www14.software.ibm.com/webapp/iwm/web/preLogin.do?source=jcesdk

Property Settings

inbound-observer.properties

Inbound message processing can be configured using the inbound-observer.properties file. This file can be found in <install_path>/core.war/WEB-INF/classes.

The following properties are available for configuration:


observer.msgPartIndexBuilder.bodySuffix mail message body part description suffix

observer.msgPartIndexBuilder.wholeSuffix whole mail message description suffix

observer.msgPartIndexBuilder.attachmentSuffix mail message attachment description suffix

inbound.smsSubjectSuffix SMS message description suffix

inbound.subjectLength number of SMS message characters to go into the SMS message description field

Inbound.outOfOffice.subject A semicolon separated list of subject line text values that EngageOne Digital Delivery uses to determine if an inbound message is an “Out of Office” message. This is used for reporting purposes. Values are case insensitive. These settings allow EngageOne Digital Delivery to report on “Out of Office” messages in any language

76

Property Settings

inbound.charset When processing inbound email or SMS messages, EngageOne Digital Delivery relies on the charset values set in the inbound message headers to be able to display these inbound messages correctly in its workflow pages and prepare the content correctly for archiving into Vault. When the charset header of any inbound message processed by EngageOne Digital Delivery is not set or omitted then EngageOne Digital Delivery assumes that the inbound content is encoded with the charset specified here.

mail.imap.properties=mail.imap.timeout=120000;

IMAP properties settings(timeout, connectiontimeout, all values in milli seconds), semi-colon separated properties.

mail.pop3.properties=mail.pop3.timeout=120000;

POP3 properties settings(timeout, connectiontimeout, all values in milli seconds), semi-colon separated properties.

mail.imap.ssl.tls.version=TLSv1 TLSv1.1 TLSv1.2

To provide the configuration/setting for TLS version to be used for inbound mail IMAP, applicable for all inbound profiles using IMAP gateways(if SSL enabled on gateway page) for reading mails.

mail.pop3.ssl.tls.version=TLSv1 TLSv1.1 TLSv1.2

To provide the configuration/setting for TLS version to be used for inbound mail POP3, applicable for all inbound profiles using POP3 gateways(if SSL enabled on gateway page) for reading mails

mail.imap.ssl.tls.cipherSuite=TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA

To provide the configuration/setting for Cipher Suite(SSL/TLS enabled) to be used for inbound mail IMAP, applicable for all inbound profiles using IMAP gateways(if SSL enabled on gateway page) for reading mails

77

Property Settings

For example, to set the suffix of message part index descriptions for message attachments to (Message Attachment), put the following entry in the properties file:

observer.msgPartIndexBuilder.attachmentSuffix=(Message Attachment)

If none of the above are configured, the following default values are used for inbound message processing:

mail.pop3.ssl.tls.cipherSuite=TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA

To provide the configuration/setting for Cipher Suite (SSL/TLS enabled) to be used for inbound mail POP3, applicable for all inbound profiles using POP3 gateways (if SSL enabled on gateway page) for reading mails.

Property Default Value

observer.msgPartIndexBuilder.bodySuffix (body)

observer.msgPartIndexBuilder.wholeSuffix (whole)

observer.msgPartIndexBuilder.attachmentSuffix (attachment)

inbound.smsSubjectSuffix …(SMS)

inbound.subjectLength 40

Inbound.outOfOffice.subject Out of Office; Not in Office; Out of Town

inbound.charset UTF-8

IN THE ABOVE EXAMPLE, THE PARENTHESES ARE

INCLUDED IN THE SUFFIX THAT WILL BE APPENDED

TO THE DESCRIPTION.

AFTER DOING THIS, YOU NEED TO RESTART YOUR

WEB SERVER FOR CHANGES TO TAKE EFFECT.

78

Property Settings

outboundProcessor.properties

Outbound message processing can be configured using the outboundProcessor.properties file. This file can be found in <install_path>/core.war/WEB-INF/classes.

The following properties are available for configuration


outbound.bodySuffix message body part description suffix

outbound.wholeSuffix whole message description suffix

outbound.attachmentSuffix message attachment description suffix

outbound.smsSubjectSuffix SMS message description suffix

outbound.smsSubjectLength number of SMS message characters to go into the SMS message description field

outbound.smsSubjectSuffix SMS message description suffix

outbound.smsSubjectLength number of SMS message characters to go into the SMS message description field

outbound.connectionAttempt number of connection attempts to a SMTP server before raising an error.

outbound.image.request.listener when using message beacons (transparent images embedded into HTML messages by EngageOne Digital Delivery) to track when messages are opened, you need to enter the address of the EngageOne Digital Delivery listener that will monitor messages being opened. The format of this setting needs to be: http://<server>:<port>/<contextPath>/receipt/ReadReceiptServl

et

For example: http://www.company.com/emessaging/receipt/ReadReceiptServ

let

outbound.attachment.maxAttach maximum number of attachments

header.refresh.delay defines minimum delay period in milliseconds for reloading of header.xml configuration.

header.default.refresh.delay defines minimum delay period in milliseconds for reloading of default-header.xml configuration.

79

Property Settings

outbound.validateEmailByRegEx For switching on or off the outbound email validation

Note: This Optional filter has been added for the outbound message processor to detect invalid email character before EngageOne Digital Delivery even tries to send them.

Upon detection of invalid email characters, EngageOne Digital Delivery generates the necessary outbound message records in the database for reporting purposes and also sends a bounce message describing the illegal email characters to the return-path address specified for the outbound message. This will result in a workflow item being generated to correct the invalid email address - so long as an Inbound Profile has been configured to process messages reaching the return-path address and that Inbound Profile has Workflow Bounce enabled.

outbound.validateNumberOfRecordsInFiles

For switching on or off the validation of number of records in the DIJ and the corresponding resource files (HTML or Text file).

outbound.saveFirstRecipientFromMultipleRecipients

For switching on or off for keeping records only for first email_id hence corresponding Message-Id from the list of multiple recipients in Email tag of DIJ/JRN file. For this feature to work outbound.validateEmailByRegEx must be set to true.

outbound.emailSeperator For providing email id delimiter for configured mail server to support multiple recipients of email. The separator should contain "@" between two delimiters. e.g.,@;

outbound.pollingFrequency Defines the time in seconds after which outbound profile will poll again the DIJ/JRN file from the configured Poll folder.

outbound.reuseEmailConnectionForBatch

For switching ON or OFF the outbound e-mail transport connection reuse/cache for a batch of records (messages).

outbound.profile.threadPool.maxSize

For configuring the number of threads in a thread pool used for outbound profiles (inclusive of all profiles).

80

Property Settings

outbound.profile.email.parallelThreadCount

For configuring the number of threads that can be run simultaneously for an Email outbound profile.

outbound.profile.sms.parallelThreadCount

For configuring the number of threads that can be run simultaneously for a SMS outbound profile.

outbound.attachment.pdf.readBufferSize

For configuring the "read" buffer-size in Bytes for an outbound pdf attachment. Preferably, the value should be close to the size of an individual pdf attachment file in a compound pdf file.

outbound.email.messageCountPerConnection

Number of messages that can be sent through a connection. After this number, existing connection will be closed and a new one will be created.

outbound.attachment.pdf.header For specifying the compound PDF file header constant/string (for Compound PDF file attachment type). This is a Required property and value cannot be blank.

outbound.attachment.pdf.documentProvider

For specifying the compound PDF document provider constant/string (for Compound PDF file attachment type). You can also leave the property value blank. For Generate applications, the generated compound PDF file is %DOC1/DIME:, this property is located between # endstream and PDF footer tag(%%EOF) tag.

outbound.messageCount.toRunGC For setting the number of processed messages after which garbage collection call is executed.

outbound.messageid.format For setting Message-Id format for email header. Supported values: default,rfc5322

mail.smtp.starttls.enable For setting the "starttls" flag value as true/false for outbound e-mail SMTP connection. This property will be applicable for all outbound profiles using SMTP gateways for sending e-mails.

messageCountPerConnection For setting the number of e-mails allowed per SMTP connection. Once the specified limit is reached, a new connection should be created. This property is applicable only when outbound.reuseEmailConnectionForBatch=true.

spl.chars.not.allowed For setting the special characters not allowed in password input field.

roleName.chars.not.allowed For setting the special characters not allowed in role names.

81

Property Settings

emailSend.connectionRetryInterval.inSecond

For setting the retry interval in Seconds if connection fails while sending email.

Note: This interval will not be applicable on the first 10 retries. The default interval of one second will apply on first 10 retries.

gatewayUserName.chars.not.allowed

For specifying the special characters that should not be allowed in Gateway user name field.

validate.onlyEmailAddress.forDigitalSign

Applicable for Digital Signing only. If set to false, will work as earlier but, if set to true, it will compare only the email address portion from fromAddress header with email address in digital certificate; e.g. in PB Messaging <[email protected]>, only email address portion will be matched.

mail.smtp.properties=mail.smtp.timeout=120000;mail.smtp.connectiontimeout=120000;mail.smtp.writetimeout=120000

Comma separated SMTP property settings (timeout, connectiontimeout, and writetimeout) with all values in milli seconds.

mpush.notification.properties=mpush.timetolive=86400

FCM will wait to deliver the notification on phone up to this time. max value 4 weeks (2,419,200 seconds) allowed by FCM, default set as 1 day

mail.smtp.ssl.tls.version=TLSv1 TLSv1.1 TLSv1.2

To provide the configuration/settings for TLS version to be used for outbound mail SMTP, applicable for all outbound profiles using SMTP gateways (if SSL enabled on gateway page) for sending mails.

mail.smtp.starttls.tls.version=TLSv1 TLSv1.1 TLSv1.2

To provide the configuration/settings for TLS version to be used for outbound mail SMTP, applicable for all outbound profiles using SMTP gateways (if SSL NOT enabled on gateway page, but starttls property is set to true) for sending mails

mail.smtp.ssl.tls.cipherSuite=TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA

To provide the configuration/settings for Cipher Suite(SSL/TLS enabled) to be used for outbound mail SMTP, applicable for all outbound profiles using SMTP gateways(if SSL enabled on gateway page) for sending mails

mail.smtp.starttls.tls.cipherSuite=TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA

To provide the configuration/settings for Cipher Suite to be used for outbound mail SMTP, applicable for all outbound profiles using SMTP gateways (if SSL NOT enabled on gateway page, but starttls property is set to true) for sending mails

82

Property Settings

If none of the above are configured, the following default values are used for outbound message processing:

sms.smpp.ssl.tls.version=TLSv1 TLSv1.1 TLSv1.2

To provide the configuration/setting for TLS version to be used for outbound SMPP SMS, applicable for all outbound profiles using SMPP gateways(if SSL enabled on gateway page) for sending SMS

sms.smpp.ssl.tls.cipherSuite=TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA

To provide the configuration/setting for Cipher Suite(SSL/TLS enabled) to be used for outbound SMPP SMS, applicable for all outbound profiles using SMPP gateways(if SSL enabled on gateway page) for sending SMS

Property Default Value

outbound.bodySuffix (body)

outbound.wholeSuffix (whole)

outbound.attachmentSuffix (attachment)

outbound.smsSubjectLength …(SMS)

outbound.smsSubjectLength 40

header.refresh.delay 5000

header.default.refresh.delay 5000

outbound.validateEmailByRegEx True

outbound.validateNumberOfRecordsInFiles False

outbound.saveFirstRecipientFromMultipleRecipients

True

outbound.emailSeperator ,

outbound.pollingFrequency 30

outbound.reuseEmailConnectionForBatch True

outbound.profile.threadPool.maxSize 50

outbound.profile.email.parallelThreadCount 2

outbound.profile.sms.parallelThreadCount 1

outbound.attachment.pdf.readBufferSize 1024

THE WEB APPLICATION SERVER RUNNING

ENGAGEONE DIGITAL DELIVERY NEEDS TO BE

RESTARTED FOR NEW PROPERTY SETTINGS TO

TAKE EFFECT

83

Property Settings

outbound.email.messageCountPerConnection 100

outbound.attachment.pdf.header %PDF-

outbound.attachment.pdf.documentProvider %DOC1/DIME:

outbound.messageCount.toRunGC 10000

outbound.messageid.format default

mail.smtp.starttls.enable True

messageCountPerConnection 19

spl.chars.not.allowed ` ~ * < > . ! ' ; :

roleName.chars.not.allowed ()<>?\\/:;*|\"`%&

emailSend.connectionRetryInterval.inSecond 120

gatewayUserName.chars.not.allowed ()<>\\/:;\"`

84

Property Settings

SMPPService.properties (SMPPSERVER configuration)

If EngageOne Digital Delivery is being configured to send or receive SMS messages via the SMPP protocol then some system wide settings related to the SMPP connections are configured in the SMPPService.properties file. This file can be found in <install_path>/core.war/WEB-INF/classes.



smpp.server.retry.bind.attempts The number of times that EngageOne Digital Delivery will send an SMPP bind request to the SMSC before reporting an error and ceasing to process SMS messages. When the retry attempts expire, EngageOne Digital Delivery will have to be restarted to re-start the bind request cycle. The cycle also ends when a bind request succeeds.

smpp.server.retry.bind.interval.milliseconds The time that EngageOne Digital Delivery will wait between failed SMPP bind attempts to the SMSC. Specified in milliseconds.

smpp.server.enquirelink.interval.milliseconds

The interval at which ENQUIRE_LINK requests are sent to the SMSC in order to keep the SMPP connection between EngageOne Digital Delivery and the SMSC alive during periods of no messages being sent or received. Specified in milliseconds. This should NOT be set to less than 5000. The default value is 60000.

smpp.server.system.type SMPP System Type. Default is set to blank.

smpp.server.send.waittime.messagequeuefull.milliseconds

The time that EngageOne Digital Delivery will wait before sending the next request to the SMSC after the SMSC has reported message queue full. Specified in milliseconds.

smpp.server.receive.timeout.milliseconds The timeout used for receiving data from the SMPP TCP/IP connection. This timeout may need to be increased if the connection to the SMSC is very slow.

85

Property Settings

smpp.server.comms.timeout.milliseconds The timeout used for calls to underlying communication functions of the SMPP TCP/IP connection. This timeout may need to be increased if the connection to the SMSC is very slow.

smpp.server.send.service.type SMPP server send Service Type. The default is set to blank.

smpp.server.bind.TON SMPP server bind TON (Type of Number).

smpp.server.bind.NPI SMPP server bind NPI (Numbering plan Indicator).

smpp.server.send.src.TON SMPP server send source TON.

smpp.server.send.src.NPI SMPP server send source NPI.

smpp.server.send.dest.TON SMPP server send destination TON.

smpp.server.send.dest.NPI SMPP server send destination NPI.

smpp.server.bind.addressRange SMPP server bind address_range.

smpp.server.send.protocol_id SMPP server send protocol id.

smpp.server.send.priorityFlag SMPP server send Priority Flag.

smpp.server.interface.version SMPP interface version (0x34=52) for 3.4 version or (0x33=51) for 3.3 version.

smpp.server.sms.ASCII.maxLength SMPP server send message maximum length for ASCII type.

smpp.server.sms.unicode.maxLength SMPP server send message maximum length for UNICODE type.

smpp.server.newConnectionForProfileAndThread

A flag to specify whether a new connection will be created or not for a new profile or thread. If set to “true”, a new connection will be created for each new profile or thread. If set to “false”, a single connection will be used for all the profiles and threads using same gateway.

smpp.server.send.dataCoding SMPP server data coding (DC) of the text to be sent. For example, ASCII (DC=1), UTF8 (DC=8), ISO8859_1 (DC=3), UTF16_BEM (DC=8), UTF16_BE (DC=8), UTF16_LEM (DC=8), UTF16_LE (DC=8), UTF16 (DC=8), Cp1252 (DC=3), GSM7BIT (DC=0))

86

Property Settings

tableColumns.properties

This property file contains system wide information specifying how the tables on all the workflow user interfaces, categorization user interfaces and the Individual Sent Message Report will be displayed. This file can be found in <install_path>/core.war/WEB-INF/classes.

These settings may be adjusted to configure the number of characters that will be displayed in a particular table column. Abbreviated column values are followed by “…” and their full value can be viewed as a tooltip when hovering over the abbreviated value with the cursor.

Each field has two values. The first is the column’s width as a percentage of the total table width. This is not configurable and provided as a guideline only. The second value is configurable and specifies the number of characters to be displayed in a given table cell. If a table column contains an icon then this is indicated by the setting icon and cannot be adjusted. The following properties are available for configuration:1111111111111111111111111111111111111111111111111111111111111111111111111111111

enable.InboundSmpp.ThreadPool To switch on/off inbound SMPP thread pool (true/false)

inboundSmpp.core.thread.pool.size Number of threads to keep in the pool, even if they are idle

inboundSmpp.maximum.thread.pool.size Maximum number of threads to allow in the pool. corePoolSize < maximumPoolSize.

inboundSmpp.thread.keep.alive.time When number of threads is greater than the core, this is the maximum time (in SECONDS) that idle threads will wait for new tasks before terminating.

inboundSmpp.message.queue.size Inbound SMPP new/fresh message(MO) queue size


workflowOverview.customerId For “Customer ID” column on the Workflow Overview page. Column width as a percentage and the maximum number of characters to be displayed. Default = 5,10

workflowOverview.from For “From” column on the Workflow Overview page. Column width as a percentage and the maximum number of characters to be displayed. Default = 15,10

87

Property Settings

workflowOverview.to For “To” column on the Workflow Overview page. Column width as a percentage and the maximum number of characters to be displayed. Default = 15,10

workflowOverview.subject For “Subject” column on the Workflow Overview page. Column width as a percentage and the maximum number of characters to be displayed. Default = 20,10

workflowOverview.date For “Date” column on the Workflow Overview page. Column width as a percentage and the maximum number of characters to be displayed. Default = 5,10

workflowOverview.stage For “Workflow Stage” column on the Workflow Overview page. Column width as a percentage and the maximum number of characters to be displayed. Default = 5,10

workflowOverview.co For “Checked Out” column on the Workflow Overview page. Column width as a percentage and the maximum number of characters to be displayed. Default = 1,10

workflowOverview.lastActionDate

For “Date of Last Workflow Action” column on the Workflow Overview page. Column width as a percentage and the maximum number of characters to be displayed. Default = 5,10

workflowOverview.user For “User” column on the Workflow Overview page. Column width as a percentage and the maximum number of characters to be displayed. Default = 5,10

workflowOverview.view For “View Message” column on the Workflow Overview page. Column width as a percentage and the maximum number of characters to be displayed. Default = 5,icon

workflowOverview.history For “View History” column on the Workflow Overview page. Column width as a percentage and the maximum number of characters to be displayed. Default = 5,icon

workflowOverview.unlock For “Unlock” column on the Workflow Overview page. Column width as a percentage and the maximum number of characters to be displayed. Default = 5,icon

indexingEntryList.custId For “Customer ID” column on the Indexing Entry page. Column width as a percentage and the maximum number of characters to be displayed. Default = 5,10

indexingEntryList.matchedOn For “Matched On” column on the Indexing Entry page. Column width as a percentage and the maximum number of characters to be displayed. Default = 5,12

88

Property Settings

indexingEntryList.from For “From” column on the Indexing Entry page. Column width as a percentage and the maximum number of characters to be displayed. Default = 5,10

indexingEntryList.to For “To” column on the Indexing Entry page. Column width as a percentage and the maximum number of characters to be displayed. Default = 5,10

indexingEntryList.subject For “Subject” column on the Indexing Entry page. Column width as a percentage and the maximum number of characters to be displayed. Default = 5,12

indexingEntryList.size For “Size” column on the Indexing Entry page. Column width as a percentage and the maximum number of characters to be displayed. Default = 5,7

indexingEntryList.date For “Date” column on the Indexing Entry page.Column width as a percentage and the maximum number of characters to be displayed. Default = 5,11

indexingEntryList.expDate For “Expiry Date” column on the Indexing Entry page. Column width as a percentage and the maximum number of characters to be displayed. Default = 5,11

indexingEntryList.index For “Index” column on the Indexing Entry page. Column width as a percentage and the maximum number of characters to be displayed. Default = 5,icon

processAlertsList.custId For “Customer ID” column on the Message Alerts page. Column width as a percentage and the maximum number of characters to be displayed. Default = 5,10

processAlertsList.from For “From” column on the Message Alerts page. Column width as a percentage and the maximum number of characters to be displayed. Default = 5,10

processAlertsList.to For “To” column on the Message Alerts page. Column width as a percentage and the maximum number of characters to be displayed. Default = 5,10

processAlertsList.subject For “Subject” column on the Message Alerts page. Column width as a percentage and the maximum number of characters to be displayed. Default = 5,12

processAlertsList.date For “Date” column on the Message Alerts page. Column width as a percentage and the maximum number of characters to be displayed. Default = 5,11

89

Property Settings

processAlertsList.raisedBy For “Raised By” column on the Message Alerts page. Column width as a percentage and the maximum number of characters to be displayed. Default = 5,8

processAlertsList.attOf For “For Attention Of” column on the Message Alerts page. Column width as a percentage and the maximum number of characters to be displayed. Default = 5,8

processAlertsList.stage For “Workflow Stage” column on the Message Alerts page. Column width as a percentage and the maximum number of characters to be displayed. Default = 5,3

processAlertsList.view For “View Message” column on the Message Alerts page. Column width as a percentage and the maximum number of characters to be displayed. Default = 1,icon

processAlertsList.history For “View History” column on the Message Alerts page. Column width as a percentage and the maximum number of characters to be displayed. Default = 1,icon

processAlertsList.close For “Close” column on the Message Alerts page. Column width as a percentage and the maximum number of characters to be displayed. Default = 5,icon

conversionEntryList.custId For “Customer ID” column on the Message Alerts page. Column width as a percentage and the maximum number of characters to be displayed. Default = 5,10

conversionEntryList.matchedOn For “Matched On” column on the Message Alerts page. Column width as a percentage and the maximum number of characters to be displayed. Default = 5,12

conversionEntryList.from For “From” column on the Message Alerts page. Column width as a percentage and the maximum number of characters to be displayed. Default = 5,10

conversionEntryList.to For “To” column on the Message Alerts page. Column width as a percentage and the maximum number of characters to be displayed. Default = 5,10

conversionEntryList.subject For “Subject” column on the Message Alerts page. Column width as a percentage and the maximum number of characters to be displayed. Default = 5,12

conversionEntryList.size For “Size” column on the Message Alerts page. Column width as a percentage and the maximum number of characters to be displayed. Default = 5,7

90

Property Settings

conversionEntryList.date For “Date” column on the Message Alerts page. Column width as a percentage and the maximum number of characters to be displayed. Default = 5,11

conversionEntryList.process For “Process” column on the Message Alerts page. Column width as a percentage and the maximum number of characters to be displayed. Default = 5,icon

bouncedMessageList.custId For “Customer ID” column on the Bounced Messages page. Column width as a percentage and the maximum number of characters to be displayed. Default = 5,10

bouncedMessageList.type For “Bounce Type” column on the Bounced Messages page. Column width as a percentage and the maximum number of characters to be displayed. Default = 5,11

bouncedMessageList.from For “From” column on the Bounced Messages page. Column width as a percentage and the maximum number of characters to be displayed. Default = 5,10

bouncedMessageList.to For “To” column on the Bounced Messages page. Column width as a percentage and the maximum number of characters to be displayed. Default = 5,10

bouncedMessageList.subject For “Subject” column on the Bounced Messages page. Column width as a percentage and the maximum number of characters to be displayed. Default = 5,12

bouncedMessageList.size For “Size” column on the Bounced Messages page. Column width as a percentage and the maximum number of characters to be displayed. Default = 5,7

bouncedMessageList.date For “Date” column on the Bounced Messages page. Column width as a percentage and the maximum number of characters to be displayed. Default = 5,11

bouncedMessageList.indexed For “Indexed” column on the Bounced Messages page. Column width as a percentage and the maximum number of characters to be displayed. Default = 5,icon

bouncedMessageList.view For “View Message” column on the Bounced Messages page. Column width as a percentage and the maximum number of characters to be displayed. Default = 5,icon

bouncedMessageList.close For “Close” column on the Bounced Messages page. Column width as a percentage and the maximum number of characters to be displayed. Default = 5,icon

91

Property Settings

respondList.custId For “Customer ID” column on the Respond to Messages page. Column width as a percentage and the maximum number of characters to be displayed. Default = 5,10

respondList.from For “From” column on the Respond to Messages page. Column width as a percentage and the maximum number of characters to be displayed. Default = 5,10

respondList.to For “To” column on the Respond to Messages page. Column width as a percentage and the maximum number of characters to be displayed. Default = 5,10

respondList.subject For “Subject” column on the Respond to Messages page. Column width as a percentage and the maximum number of characters to be displayed. Default = 5,12

respondList.stage For “Workflow Stage” column on the Respond to Messages page. Column width as a percentage and the maximum number of characters to be displayed. Default = 5,3

respondList.date For “Date” column on the Respond to Messages page. Column width as a percentage and the maximum number of characters to be displayed. Default = 5,11

respondList.indexed For “Indexed” column on the Respond to Messages page. Column width as a percentage and the maximum number of characters to be displayed. Default = 5,icon

respondList.view For “View Message” column on the Respond to Messages page. Column width as a percentage and the maximum number of characters to be displayed. Default = 5, icon

respondList.respond For “Respond” column on the Respond to Messages page. Column width as a percentage and the maximum number of characters to be displayed. Default = 5, icon

respondList.close For “Close” column on the Respond to Messages page. Column width as a percentage and the maximum number of characters to be displayed. Default = 5, icon

individualReport.email For “Email” column on the Sent (Individual) Report page. Column width as a percentage and the maximum number of characters to be displayed. Default = 5,12

individualReport.date For “Date” column on the Sent (Individual) Report page. Column width as a percentage and the maximum number of characters to be displayed. Default = 5,11

92

Property Settings

individualReport.dateOpened For “Date Opened” column on the Sent (Individual) Report page. Column width as a percentage and the maximum number of characters to be displayed. Default = 5,11

individualReport.status For “Status” column on the Sent (Individual) Report page. Column width as a percentage and the maximum number of characters to be displayed. Default = 5,13

individualReport.subject For “Subject” column on the Sent (Individual) Report page. Column width as a percentage and the maximum number of characters to be displayed. Default = 5,20

individualReport.profile For “OtProfile” column on the Sent (Individual) Report page. Column width as a percentage and the maximum number of characters to be displayed. Default = 5,12

individualReport.stage For “Workflow Stage” column on the Sent (Individual) Report page. Column width as a percentage and the maximum number of characters to be displayed. Default = 5,3

individualReport.history For “History” column on the Sent (Individual) Report page. Column width as a percentage and the maximum number of characters to be displayed. Default = 5,4

individualReport.view For “View” column on the Sent (Individual) Report page. Column width as a percentage and the maximum number of characters to be displayed. Default = 5, icon

categoriseMessageList.msgFrom

For “From” column on the Categorize Messages page. Column width as a percentage and the maximum number of characters to be displayed. Default = 10,50

categoriseMessageList.firstPerson

For “To” column on the Categorize Messages page. Column width as a percentage and the maximum number of characters to be displayed. Default = 10,50

categoriseMessageList.subject For “Subject” column on the Categorize Messages page. Column width as a percentage and the maximum number of characters to be displayed. Default = 25, 50

categoriseMessageList.date For “Date” column on the Categorize Messages page. Column width as a percentage and the maximum number of characters to be displayed. Default = 5, 12

categoriseMessageList.stage For “Workflow Stage” column on the Categorize Messages page. Column width as a percentage and the maximum number of characters to be displayed. Default = 10,11

93

Property Settings

categoriseMessageList.inboundProfileName

For “Inbound Profile” column on the Categorize Messages page. Column width as a percentage and the maximum number of characters to be displayed. Default = 20,22

categoriseMessageList.view For “Category” column on the Categorize Messages page. Column width as a percentage and the maximum number of characters to be displayed. Default = 20,20

multipleInProfile.inProfileName For “Inbound Profile Name” column on the intermediate report pages. Column width as a percentage and the maximum number of characters to be displayed. Default = 10,20

multipleInProfile.email For “Email Address” column on the intermediate report pages. Column width as a percentage and the maximum number of characters to be displayed. Default = 10,20

multipleInProfile.msgCount For “Message Count” column on the intermediate report pages. Column width as a percentage and the maximum number of characters to be displayed. Default = 5,4

94

Property Settings

Custom Vault index key mapping configuration

EngageOne Digital Delivery supports mapping of custom Vault index settings defined in the journal file generated both by inbound and outbound profiles prior to archiving. These custom keys are defined using the repositoryFacade property file.

This file can be found in <install_path>/core.war/WEB-INF/classes.

The following values can be mapped in the reposiotryFacade property file:

Sample custom index mapping

The resulting journal file adds a corresponding entry for each of the custom index keys mapped above:

[SampleMapping]journal.e2.messageId=DocGUIDjournal.e2.email=FromAddrjournal.e2.expiry=journal.e2.mime=journal.e2.msisdn=TelNojournal.e2.description=journal.e2.cpointer=


journal.e2.messageId MessageId mapping

journal.e2.email E-mail mapping

journal.e2.expiry Expiry mapping

journal.e2.mime Mime mapping

journal.e2.msisdn MSISDN mapping

journal.e2.description Description mapping

journal.e2.cpointer Cpointer mapping

95

Property Settings

The above settings would, for example, result in writing the additional underlined entries into the journal files.

J|InProfile|20070110163110A|MessageID|[email protected]_20070110163110_32432452A|DocGUID|[email protected]_20070110163110_32432452A|Cpointer|From john.smith@ 123.com_20070110163110_1A|Cpointer|To edward.smith@ 123.com_20070110163110_1A|email|[email protected]|FromAddr|[email protected]|MSISDN|NoNumberA|TelNo|NoNumberA|Description|Description (body)A|Expire|20071231A|mime|text/plainD|account|20071231|Filename_incl_ext|John Smith|Full Address

Other property files

Note that unless otherwise indicated all property files listed in this section are located in the <install_path>/core.war/WEB-INF/classes directory.

ApplicationAlert.properties

This property file contains settings related with alert messages. Alert messages can be viewed by a JMX console.

The properties that can be set here include messages for:

• Application Core Monitor

• Database Monitor

• Vault Monitor

• Inbound Service Monitor

• Outbound Service Monitor

• LDAP Monitor

• Conversion Monitor

• Job Execution Monitor

• Report Generation Monitor

96

Property Settings

ApplicationResources.properties

This contains labels and messages that are displayed in EngageOne Digital Delivery front-end User Interface based on the locale selected. Settings for different locales can be set in their corresponding ApplicationResources_<country_code>.properties file, where <country_code> is an ISO 639-1 code. Current country codes that are supported by EngageOne Digital Delivery are:

• ‘en’ for English language (default)

• es’ for Spanish.

• ‘de’ for German

• ‘ja’ for Japanese

• ‘pt_BR’ for Brazilian Portuguese

• ‘zh’ for Simplified Chinese

asyncProcesses.properties

This property file contains settings to run the EngageOne Digital Delivery application in sync or async mode. If you set the application to run in async mode, then this file also contains additional settings to specify maximum pool size of threads for different processes.


outbound.process.type defines process type, sync and async. Default set to sync. If you set this property to async, only then you need to set the below properties.

outbound.sender.max.pool.thread

defines maximum pool size of thread for outbound send process. Default set to 20.

outbound.sender.core.pool.thread

defines core pool size of thread for outbound send process. Default set to 10.

outbound.sender.queue.size defines queue size of sender thread pool. Default set to 100.

outbound.middle.queue.size defines middle queue for processor and sender, where processor puts the object and sender gets from it. Default set to 100.

outbound.email.transport.min.pool.size

defines the minimum transport object in pool. Default set to 10.

outbound.email.transport.max.pool.size

defines the maximum transport object in pool. Default set to 20.

97

Property Settings

aws.property

This property file specifies AWS Gateway details used by EngageOne Digital Delivery. This setting is used by EngageOne Digital Delivery when sending out SMS.

sns.sms.maxPrice – the price limit for sending uninterrupted messages. Once the specified limit is reached, you will not be able to send the messages using AWS.

blackoutWindow.propertiesThis property file specifies settings that you may want to configure time period during which EngageOne Digital Delivery will not do inbound polling to Email Server and SMS server.


ClickatellMessageComposer.properties

This property file contains settings for the Clickatell SMS gateway provider including e-mail address used in sending SMS messages, e-mail format, and SMS maximum length.

custom.properties

This property file contains properties that are used for defining the report formats. For example, you can use these properties to define how many rows will be displayed on a report page and what will be the orientation (portrait or landscape) of the page.

Property Description Default Value

blackout.inbound.email.profile

Flag to switch ON/OFF inbound email profile blackout

True

blackout.inbound.sms.profile

Flag to switch ON/OFF inbound SMS profile blackout

True

blackout.startTime.inbound.email

Blackout start time in 24 hour format (HH:mm:ss) for Email

11:23:25

blackout.endTime.inbound.email

Blackout end time in 24 hour format (HH:mm:ss) for Email

23:23:25

blackout.startTime.inbound.sms

Blackout start time in 24 hour format (HH:mm:ss) for SMS

11:23:25

blackout.endTime.inbound.sms

Blackout end time in 24 hour format (HH:mm:ss) for SMS

23:23:25


98

Property Settings

Ems.propertiesThis property file mainly provides configuration for background thread responsible for processing failed messages. Currently this is supported only for outbound message notification. So in case notification call to EngageOne has not succeeded due to any reason say EO server was down, the background thread will resend this failed message. Ems.properties file provides required parameters to be configured for background thread.

encryptionKey.propertiesThis property file provides configuration settings for password encryption.

table.size The number of rows to be displayed at a time on the workflow and message categorization screens; and the Individual Sent Message Report. Default value is 10.

individualReportPdfExport.pageOrientation

The orientation in which reports are saved as PDF. The dfault value is blank which means a report PDF will be saved in portrait orientation. To change the orientation to landscape, you have to specify the following value:

size: A4 Landscape

The landscape orientation is needed when the size of e-mail addresses in the reports is so long that the PDF gets cropped from right side.

outboundProfileReport.downloadbuttons.visible

To enable/disable the Download button on the individualReport and outboundProfileReport pages. By default, the property is set to true to keep the Download button visible.

outboundProfileReport.reportlink.enabled

To enable/disable the Report links on the outboundProfileReport page. By default, the property is set to true to keep the links visible.


ems.retry.thread.frequency The frequency at which the background thread will run. Supported units are second, minutes and hour. E.g. if you want to run it at every 1 hour then value should be 1h. For 30 seconds it should be 30s and for 15 minutes it should be 15m.

ems.retry.count Maximum number of times background thread will try to process a failed message. Once the count has reached to maximum message will be not be processed further.

ems.save.before.queue If true, then the record in the db will be created before putting the message in queue. Otherwise the record will be created only if notification fails.

99

Property Settings

engageone.propertiesThe properties mentioned in this file are used for making a connection to EngageOne server or a different calling system, in order to pass back message processing and delivery updates back as they happen. The status updates are for content given to EngageOne Digital Delivery for email and SMS delivery.


encryptionKey.K2 This is half of the Encryption Key for AES algorithm, which is used for password Encryption/Decryption. This key must be 16 characters long. By default, set to “tionDecrytion256”.

security.useEncryptedPassword

If true, then all passwords need to be in encrypted format. If false (default value), then passwords will be in plain text format.


engageone.wsdlURL The IP address and port of a web service on EngageOne, or another calling system that is set up to consume message processing and delivery status updates from EngageOne Digital Delivery.

Default value is: http://IP_ADDRESS:PORT/EngageOneWS/RequestStatusUpdateService?wsdl

engageone.domain The domain in EngageOne which is set up to receive processing and delivery updates from EngageOne Digital Delivery.

Default value is: DOMAIN_NAME

engageone.userId USER_ID that will be used to make calls to this EngageOne Web Service.

Default value is: USER_ID

engageone.password The Password that will be used to make calls to this EngageOne Web Service.

Default value is: PASSWORD

THE WEB APPLICATION SERVER RUNNING

ENGAGEONE DIGITAL DELIVERY NEEDS TO BE

RESTARTED FOR NEW PROPERTY SETTINGS TO

TAKE EFFECT

100

Property Settings

Executor.propertiesA notification call to EngageOne is asynchronous. It has been implemented using a queue mechanism where notification messages are queued in memory and processed simultaneously by multiple threads. This property file is meant for configuring queue size and thread pool. There are two types of configuration a. Shared Executor and b. Dedication Executors. Until flag for dedicated executor e.g. (outbound.message.notification=true) has been set as true, shared executor configuration will be used. Currently all the threads configured for shared executor will be used only for outbound message notification and hence there is no need for configuring dedicated executor.

inlet.propertiesThis property file is meant for configuring file server where EngageOne Digital Delivery will place the input files for Inlet.

Install.properties

This property file contains installation settings and specifies how dates, times and tables are displayed in the EngageOne Digital Delivery user interfaces. The date and time format is specified during the installation. However, these settings can be modified after installation by adjusting the following settings in this property file.


shared.executor.queue.size Maximum number of messages that the queue can contain.

shared.executor.core.thread.pool.size

Maximum number of threads that will remain in pool even if there is no message to be processed.

shared.executor.thread.pool.size Maximum number of threads that the pool can contain.

shared.executor.alive.time Represents time in seconds. If no message is added in queue for mentioned time, non core threads will be removed from the pool.


inlet.ftp.host File server hostname where files (input to Inlet) will be placed

inlet.ftp.port File server port where files will be placed

inlet.ftp.user Username for FTP connection

inlet.ftp.password Password for FTP connection

inlet.ftp.folder Folder location on the file server

inlet.to.email.address Email address to which files will be sent

101

Property Settings

• dateTimePattern – override the date and time format display in EngageOne Digital Delivery UI. See table for customized date and time formats. Default is “dd MMM yyyy, HH:mm '[GMT' Z']'”

• dateOnlyPattern – override the date only format display in EngageOne Digital Delivery UI. See table for customized date and time formats. Default is " dd MMM yyyy ".

jdbc.properties

This property file contains JDBC connection settings that EngageOne Digital Delivery will use to connect to its database.

log4j.xml

This property file contains settings on the level of the logs produced by EngageOne Digital Delivery.

The following are the levels which can be assigned to specific packages (modules) used EngageOne Digital Delivery.

• TRACE

• DEBUG

• INFO

• WARN

• ERROR

• FATAL

Customized Date and Time Formats

Pattern Output

dd.MM.yy 09.04.98

yyyy.MM.dd G 'at' hh:mm:ss z 1998.04.09 AD at 06:15:55 PDT

EEE, MMM d, ''yy Thu, Apr 9, '98

h:mm a 6:15 PM

H:mm 18:15

H:mm:ss:SSS 18:15:55:624

K:mm a,z 6:15 PM,PDT

yyyy.MMMMM.dd GGG hh:mm aaa 1998.April.09 AD 06:15 PM

102

Property Settings

The output can be configured to be in a log file, console, or any other appenders that are supported by log4j. For more information on appenders, see documentation of log4j.

mail.properties

This property file specifies mail server connection details used by EngageOne Digital Delivery. These settings are used by EngageOne Digital Delivery when sending out e-mail notifications related with internal housekeeping such as change password notifications. The settings include.

• mail.transport.protocol – the protocol used in sending e-mail. This will generally be set to SMTP unless the e-mail server requires a SSL (Secure Socket Layer) connection in which case it should be set to SMTPS.

• mail.host – the machine IP or name that EngageOne Digital Delivery connects to for sending mails

• mail.port – port number used for sending mails

• mail.username – usename used by EngageOne Digital Delivery to connect to the mail server.

• mail.password – corresponding password for the username specified

• mail.starttls.enable – "starttls" flag for e-mail SMTP connection. The value can be set to “true” or “false”. Default value is “true”.

openoffice.properties

This property file specifies the OpenOffice server instances that EngageOne Digital Delivery will use for content conversion.

The following is the syntax on how to specify an OpenOffice instance:

openoffice.servers=<server>:<port>

• where server can be an Internet Protocol (IP) address or the server’s machine name

• port is the OpenOffice instance’s port that listens for requests for conversion.

Proxy.propertiesWhen EngageOne Digital Delivery prepares HTML contained in mail messages for archiving, options exist to embed externally referenced images into the content and transform it into an HTML Archive format (MHT file), PDF or PDF/a prior to archiving. In order to embed externally referenced images into the content that is prepared for archiving, the images need to be accessible from the EngageOne Digital Delivery server. When access to these images is only possible via a proxy server then the settings for that proxy server can be set in this properties file.

103

Property Settings

The following properties are available for configuration

securityConfiguration.propertiesThis property file specifies settings to enhance the Web security of your application server. These settings are included in the HTTP response header by EngageOne Digital Delivery server.


PurgingSetup.properties

This property file specifies SQL statements used by EngageOne Digital Delivery to perform data purging operations for the databases supported by EngageOne Digital Delivery.

repositoryFacade.properties

This property file specifies settings used by the journal generator. See “Custom Vault index key mapping configuration” on page 95 for further details.

RESTService.propertiesThis property file specifies settings that you may want to configure while using REST APIs for sending messages (email/SMS) and getting their delivery status.



proxy.host Internet Proxy Address

proxy.port Internet Proxy Port

proxy.username Valid username for authentication

proxy.password Correct password for authentication


cacheControl.header.value

Used to specify various Cache-Control directives that control how and for how long a response can be cached by the browser and other intermediate caches.

no-cache,no-store,max-age=0,must-revalidate

pragma.header.value

Implementation-specific fields that may have various effects anywhere along the request-response chain.

no-cache

expires.header.value

Used to specify the date/time after which the response is considered stale.

0

104

Property Settings


restservice.core.thread.pool.size

Minimum number of core threads in the pool, even if some of them are idle

30

restservice.maximum.thread.pool.size

Maximum number of threads allowed in the thread pool

50

restservice.thread.keep.alive.time

Maximum time (seconds) an additional thread, which is added to share the load with core threads, will remain idle in the pool. Once this time is elapsed, that additional thread will be removed from the pool.

300

restservice.message.queue.size

Message (email/SMS) queue size submitted through REST API

50

restservice.smppadapter.pool.size

SMPP adapter pool size to handle SMS submitted via REST API

5

rest.delivery.status.baseURL

Base URL for the message delivery status submitted via REST API

http://localhost:8080/EODigitalDelivery/resource/v1/messages/deliveryStatus

restservice.valid.attachment.types

File types (COMMA separated) supported as email attachment while sending email messagges via REST API

Note: .bat and .exe file types are not supported

pdf, eml, doc, docx, ppt, pptx, xls, xlsx, html, htm, text, txt, csv, zip, xml

restservice.valid.image.types

Image file types (COMMA separated) supported for email while sending email messagges via REST API.

Note: .bat and .exe file types are not supported

gif, bmp, jpg, jpeg, tiff, tif, png

rest.retry.old.files.delay

The time duration in minutes. The poll process will retry processing the files, which are older than current time minus this time duration.

120

rest.retry.poll.interval

Poll time interval for retry from DIJ folder (in seconds)

120

105

Property Settings

inital.rest.retry.delay The time duration in minutes. When the server starts, it will retry processing the files, which are older than the server_starttime minus this value. If this value is -1, then DIJ folder retry will be disabled.

3

rest.retry.threadPool.size

REST retry thread pool size. 10

rest.retry.fromErrorFolder.createdTimeBefore

Retrying messages from Error folder, which were moved due to connection failure (to mail server/SMS gateway). This will process all database records, which are created before current_time minus rest.retry.fromErrorFolder.dateCreatedBefore and after current_time minus (rest.retry.fromErrorFolder.dateCreatedBefore + rest.retry.fromErrorFolder.createdTimeAfter). If this value is -1, then retry from error folder will be disabled.

120

rest.retry.fromErrorFolder.createdTimeAfter

600

rest.retry.error.status.codes

Status codes of failed messages for retry from Error folder. The default status code messages are related to connection failure or some other system failure.

9,11,30,31,32

restapi.report.maxRecordCount

Maximum number of records that can be fetched on REST API call for Report.

10000

restapi.messageCount.profileUpdate.fromDB

Count of messages to be processed (through REST API) after which profile information needs to be updated from Database.

500

restapi.timeInterval.profileUpdate.fromDB

Time interval in milli seconds after which profile information needs to be updated from Database.

300000

106

Property Settings

rootfolder.properties

This property file specifies EngageOne Digital Delivery root folder settings.

keys.properties

This property file specifies settings for accessing a digital certificate’s private key for use by the EngageOne Digital Delivery Digital Signature functions. See the Digital Signatures on page 70 for further details.

serverCluster.properties

This property file specifies settings for the fail-over of background processes between different EngageOne Digital Delivery instances. See the Failover Configuration on page 110 for further details.

servlet.propertiesThis property file specifies settings that you may want to configure for securing API access.



folder.root Specify the Vendor folder location.

NOTE: Need to escape the backslash (\)

folder.report.downloadLocation Specify the location to save the reports when Save CSV at Server button is clicked on the Reports Downlaod page.


workflow.provider.allowed

IPs/Hostnames allowed to access the WorkflowItemProvider servlet. Comma-delimited, no spaces in between.

localhost,127.0.0.1

outmessage.provider.allowed

IPs/Hostnames allowed to access the OutMessageProvider servlet. Comma-delimited, no spaces in between.

localhost,127.0.0.1

outprofile.provider.allowed

IPs/Hostnames allowed to access the Outbound Profile Rest API. Comma-delimited, no spaces in between.

localhost,127.0.0.1,0:0:0:0:0:0:0:1

messageprocessor.provider.allowed

IPs/Hostnames allowed to access the REST API to send Email/SMS, get message delivery status, upload attachment and image files. Comma-delimited, no spaces in between.

localhost,127.0.0.1,0:0:0:0:0:0:0:1

107

Property Settings

workflow.propertiesThis properties file specifies workflow settings. This is used by the EngageOne Digital Delivery system to create the URL to access workflow items.

autoNotification.propertiesThis property file specifies settings to be used by Auto Notification process.


reportprocessor.provider.allowed

IPs/Hostnames allowed to access the REST API to generate report. Comma-delimited, no spaces in between. For IP Range, provide IP separated with hyphen (-) e.g. 127.0.0.1-127.0.0.255

localhost,127.0.0.1,0:0:0:0:0:0:0:1

validate.api.user This property is to validate API user/caller, if set to false then the user will be allowed to access APIs without validating on IP/Host. Blank value will be considered as to validate user

true, false

basic.authentication.enforced.apilist

This property is to enable/diable basic authentication for REST APIs. Blank value will be considered as no basic authentication applied on any of the REST API's.

workflow, messages, outboundprofiles, messageprocessor, report


autonotification.outbound.sender.max.pool.thread

Max size of sending thread pool 20

autonotification.outbound.sender.core.pool.thread

Core size of sending thread pool 10

autonotification.outbound.sender.queue.size

Queue size of sending thread pool 100

autonotification.outbound.middle.queue.size

Size of middle queue (between processor and sending thread pool)

100

autonotification.outbound.thread.keep.alive.time

keepAlive time (sec) for excess idle threads 600

108

Property Settings

inboundAsync.propertiesThis property file contains settings to run the inbound email (like bounce, reply) module of EngageOne Digital Delivery application in sync (single-threaded) or async (multi-threaded) mode.

If you set the inbound module (email) to run in async mode, then this file also contains additional settings to specify maximum pool size of threads for different processes.


autonotification.email.subject

Email subject of Auto failure notification email Auto Notification on Email failure


inbound.process.type

sync is single thread and async is multi-threaded Sync(other properties are valid for async setting)

inbound.receiver.max.pool.thread

maximum number of threads in thread pool for inbound email account (POP3 or IMAP) profiles(inclusive of all profiles)

20

inbound.receiver.core.pool.thread

core number of threads in thread pool for inbound email account (POP3 or IMAP) profiles(inclusive of all profiles)

10

inbound.receiver.queue.size

Queue size of receiver thread pool 100

inbound.middle.queue.size

middle queue for Inbound processor and receiver, where the processor puts the object and the receiver gets from it

100

inbound.receiver.BUFFER_SIZE

BUFFER_SIZE to control number of message to be read per pool request.

10

109

Failover Configuration


EngageOne Digital Delivery utilizes the clustering support provided by the application servers on which it is deployed. Multiple instances of EngageOne Digital Delivery can be deployed in an application server cluster to provide load balancing and / or failover for EngageOne Digital Delivery functions such as:

• User interface requests

• REST API requests

• Message beacon requests

• Receiving inbound SMS messages

It is, however, not possible to cluster all resources used by EngageOne Digital Delivery. For example, operating system resources such as file handles cannot be clustered. This means that some background processes used by EngageOne Digital Delivery cannot rely on application server clustering to provide high availability. These background processes include:

• Processing of input files submitted to the polled folders for processing through an Outbound Profile.

• Polling and collection of inbound e-mail messages from a mail server.

Therefore, the EngageOne Digital Delivery application itself provides failover functionality for these background processes between multiple instances of EngageOne Digital Delivery. Failover settings for these inbound and outbound processes can be configured in serverCluster.properties which is located in the <install_path>/core.war/WEB-INF/classes directory. serverCluster.properties should be configured separately for each EngageOne Digital Delivery instance. The following properties are available for configuration:

#true for clustered mode, false for non-clustered#isClustered=false#true for Active-Active clustering, false for #Active-Failover(Active-Passive)#active.active.clustering.enabled=false# isPrimary=false# primary=<HOSTNAME>,<PORT>,<CONTEXT_PATH># s1=<HOSTNAME>,<PORT>,<CONTEXT_PATH># s2=<HOSTNAME>,<PORT>,<CONTEXT_PATH># s3=<HOSTNAME>,<PORT>,<CONTEXT_PATH># Pause (sleep) time (in second) between start/stop check of secondary

BASIC INSTRUCTIONS FOR CONFIGURING

ENGAGEONE DIGITAL DELIVERY IN A CLUSTER

ENVIRONMENT ARE PROVIDED IN THIS SECTION.

ENGAGEONE DIGITAL DELIVERY SUPPORTS

VARIATIONS ON CLUSTERING ARCHITECTURE AND

DEPLOYMENT MODELS, BUT SHOULD BE

DEVELOPED AND SUPPORTED INDEPENDENTLY OR

IN COORDINATION WITH PITNEY BOWES

SOFTWARE PROFESSIONAL SERVICES.

PLEASE MAKE SURE THAT YOU ALWAYS USE

PRIMARY SERVER FOR CREATING PROFILES

(OUTBOUND/INBOUND).

110


#nodes#pauseTime.inSecond.between.StartStop.check=30# Http mode/scheme (Http/Https server mode))# httpMode=http

Above are the default entries for serverCluster.properties that exist after installing EngageOne Digital Delivery. With these default settings, the failover feature is disabled.

If you want to enable failover feature, change the value of isClustered to true and disable active-active clustering:

# true for clustered mode, false for non-clusteredisClustered=true# true for Active-Active clustering, false for #Active-Failover(Active-Passiveactive.active.clustering.enabled=false# isPrimary=false# primary=<HOSTNAME>,<PORT>,<CONTEXT_PATH># s1=<HOSTNAME>,<PORT>,<CONTEXT_PATH># s2=<HOSTNAME>,<PORT>,<CONTEXT_PATH># s3=<HOSTNAME>,<PORT>,<CONTEXT_PATH># Pause (sleep) time (in second) between start/stop check of secondary #nodes#pauseTime.inSecond.between.StartStop.check=30# Http mode/scheme (Http/Https server mode))# httpMode=http

By doing so, you should also uncomment the isPrimary property and make its value true or false:

# true for clustered mode, false for non-clusteredisClustered=true# true for Active-Active clustering, false for #Active-Failover(Active-Passiveactive.active.clustering.enabled=falseisPrimary=true# primary=<HOSTNAME>,<PORT>,<CONTEXT_PATH># s1=<HOSTNAME>,<PORT>,<CONTEXT_PATH># s2=<HOSTNAME>,<PORT>,<CONTEXT_PATH># s3=<HOSTNAME>,<PORT>,<CONTEXT_PATH># Pause (sleep) time (in second) between start/stop check of secondary #nodes#pauseTime.inSecond.between.StartStop.check=30# Http mode/scheme (Http/Https server mode))# httpMode=http

The above configuration is correct for an EngageOne Digital Delivery instance that is your primary server. If the value of isPrimary is false, then you should uncomment the primary property and specify hostname, port and context_path settings of the primary EngageOne Digital Delivery instance:

111


#true for clustered mode, false for non-clusteredisClustered=true#true for Active-Active clustering, false for #Active-Failover(Active-Passiveactive.active.clustering.enabled=falseisPrimary=falseprimary=172.16.0.1,8080,/EODigitalDelivery# s1=<HOSTNAME>,<PORT>,<CONTEXT_PATH># s2=<HOSTNAME>,<PORT>,<CONTEXT_PATH># s3=<HOSTNAME>,<PORT>,<CONTEXT_PATH># Pause (sleep) time (in second) between start/stop check of secondary #nodes#pauseTime.inSecond.between.StartStop.check=30# Http mode/scheme (Http/Https server mode))# httpMode=http

The above configuration is correct for an Digital Delivery instance that is the first secondary server (s1). I.E. it is not the primary instance but it is the first instance that should takeover background processes from the primary instance if the primary instance fails. It is possible to configure a chain of Digital Delivery instances where each instance takes over background processes from the previous instance in the event of failure. If an Digital Delivery instance is to take over background processes from the first secondary instance, after both the primary and first secondary have failed then you should also declare the s1 property, for the first secondary instance, and so on if there are any other secondary servers that should start background processes before the current server. You can also set the polling frequency and the httpMode:

#true for clustered mode, false for non-clusteredisClustered=true#true for Active-Active clustering, false for #Active-Failover(Active-Passiveactive.active.clustering.enabled=falseisPrimary=falseprimary=172.16.0.1,8080,/EODigitalDeliverys1=172.16.0.2,8080,/EODigitalDelivery# s2=<HOSTNAME>,<PORT>,<CONTEXT_PATH># s3=<HOSTNAME>,<PORT>,<CONTEXT_PATH># Pause (sleep) time (in second) between start/stop check of secondary #nodespauseTime.inSecond.between.StartStop.check=30# Http mode/scheme (Http/Https server mode))httpMode=http

or

#true for clustered mode, false for non-clusteredisClustered=true#true for Active-Active clustering, false for #Active-Failover(Active-Passiveactive.active.clustering.enabled=false

112


isPrimary=falseprimary=172.16.0.1,8080,/EODigitalDeliverys1=172.16.0.2,8080,/EODigitalDeliverys2=172.16.0.3,8080,/EODigitalDelivery# s3=<HOSTNAME>,<PORT>,<CONTEXT_PATH># Pause (sleep) time (in second) between start/stop check of secondary #nodespauseTime.inSecond.between.StartStop.check=30# Http mode/scheme (Http/Https server mode))httpMode=http

If the primary EngageOne Digital Delivery instance fails and is restarted then it will take over background processes back from the currently active EngageOne Digital Delivery instance, allowing the currently active instance to complete the processing of any files or messages that it has already started.

113


Example

The following example will help you to understand the failover configuration:

1. Install EngageOne Digital Delivery on two servers named Server A and Server B.

2. Both these instances of EngageOne Digital Delivery (Server A and Server B) will point to a common database and a common Vendor folder.

The disk(s) hosting the Vendor folder may become a single point of failure for both the servers. To avoid this, it is recommended to provide a UNC path to the Vendor folder on a storage device that has in-built redundancy, for example, SAN. There can be a very intensive IO (Input-Output) between EngageOne Digital Delivery and the Vendor folder when EngageOne Digital Delivery will be processing the outbound messages. Therefore, you need to ensure that there is a fast connection between the EngageOne Digital Delivery servers and the Vendor folder.

3. Configure servercluster.properties on Server A to make it the primary server. Server B will be the secondary server and will behave like the primary server in case of Server A failure. It means that under normal operations, server A will be the only server that will poll/process input files in the Vendor folder and will poll the inboxes for bounce mails, delivery receipts, out of office replies and customer replies. Server A (primary) configuration:

isClustered=trueisPrimary=true

4. Configure servercluster.properties on Server B to make it the secondary server, which should also be aware of the IP address & port of Server A (primary server). It means that under normal operations, server B will not poll/process input files in the Vendor folder and will not poll the inboxes for bounce mails, delivery receipts, out of office replies and customer replies.

Once configured in servercluster.properties, Server B will poll Server A after every ten seconds to see if it is alive or not. If Server A goes down, Server B starts polling/processing input files in the Vendor folder and also starts polling inboxes for bounce mails, delivery receipts, out of office replies and customer replies. When Server A recovers, Server B continues the processing of files/messages that it has already started processing, but does not process new files/messages.

isClustered=trueisPrimary=falseprimary=<HOSTNAME_OR_IP_ADDRESS_OF_PRIMARY_SERVER>,<HTTP_PORT_ON_PRIMARY_SERVER>,/EODigitalDelivery

114

Active-Active clustering configuration


In Active-Active clustering, all the nodes will be active to process both, outbound and inbound messages. To share the load, you can assign the available nodes to different profiles (outprofile and inprofile), so that the messages associated with a profile are processed by the node assigned to that profile only. For data (DIJ, HTML, PDF, and Image files), all the active nodes will poll a shared vendor folder and will access a common database.

You can aslo configure the failover settings for all the active nodes. Based on your configuration, cluster will decide which node will take over which node when that node goes down. Once that node becomes active again, the node, which took over will stop processing further and pass the control to the original node. A nodes will monitor each other through the http servlet calls. You can also configure the polling frequency for nodes to monitor each other in property file. Following diagram explains the processing in active-active clustering.

You can update the profile parameters on the UI through either load balancer URL or any of the cluster node's URL.

If you do not assign any node (base node) to a profile, then the profile will not be active and will not process any message. Selecting a node on the Cluster Setup UI and saving will activate/de-activate that profile on the selected node.

115


Configuring Active-Active clustering

You can use the servercluster.properties file to configure the Active-Active Clustering. To enable the desired clustering mode, you have to uncomment and set all the settings in that section. Following sections will explain how to configure a specific clustering mode.

To enable this mode, set isClustered to true and enable the active-active clustering:

# true for clustered mode, false for non-clusteredisClustered=true# true for Active-Active clustering, false for #Active-Failover(Active-Passive)active.active.clustering.enabled=true

Define the nodes as shown below:#Cluster nodes (<HOSTNAME>, <PORT>, <CONTEXT_PATH>, <NODE_NAME

For example:N1=localhost,8080,/emessaging,Node1N2=localhost,8082,/emessaging,Node2N3=localhost,8084,/emessaging,Node3

Define the current node. For example:this.node=N2

Define the secondary nodes. When a node goes down, current (this) node will take over:# Secondary nodes, if any of the below secondary nodes goes down, #current (this) node will take the loads1=N1#s2=N3

Set the polling frequency (in seconds):# Pause (sleep) time (in second) between start/stop check of #secondary nodespauseTime.inSecond.between.StartStop.check=30

Set the httpMode (http or https):# Http mode/scheme (Http/Https server mode))httpMode=http

The following diagram depicts the Active-Active clustering with four nodes where,

• N1 will take load of N2 and N3 when they will be down

• N3 will take load of N4

• N4 will take load of N1

• N2 will not take load of any of the nodes, it does not have any secondary node

116


Mapping clustered nodes to profiles using UI

To assign a node to one or more profiles, login the UI to display the Home screen. Click the Cluster Setup link. This link will be active if and only if you have enabled active-active clustering as explained in the previous section.

117


On the Cluster Setup screen, Node Details tab will list the available nodes.

On the Outbound Profiles tab, for an outbound profile, assign a desired node by selecting from the Base Node drop-down list.

118


Similarly, on the Inbound Profiles tab, assign a desired node to an inbound profile by selecting from the Base Node drop-down list.

119

Setting up the load balancer

Setting up the load balancer

To setup Apache HTTP server as load balancer with two Digital Delivery nodes on Tomcat:

1. Download and install the Apache HTTP server in a folder say, D:\ApacheSoftwareFoundation2\Apache2).

2. Download and extract the Apache clustering module, mod_jk, and copy the mod_jk.so to the modules folder of http server (D:\ApacheSoftwareFoundation2\Apache2\modules).

3. Create mod-jk.conf file and copy it to the Apache conf folder (D:\ApacheSoftwareFoundation2\Apache2\conf).

4. Create uriworkermap.properties for URL mapping of Digital Delivery nodes and load balancer, copy to Apache conf folder (D:\ApacheSoftwareFoundation2\Apache2\conf).

5. Create workers.properties to configure the Digital Delivery nodes and copy the file to Apache conf folder (D:\ApacheSoftwareFoundation2\Apache2\conf).

6. Append the Include conf/mod-jk.conf command to the Apache httpd.conf located inside the conf folder (D:\ApacheSoftwareFoundation2\Apache2\conf).

7. Modify tomcat server.xml to enable clustering setup (jvmRoute="node1", uncomment Cluster tag - SimpleTcpCluster) at D:\14m4uatdrop1\e-Messaging14m4_uat1\Tomcat\conf)

120

LDAP Configuration

The Lightweight Directory Access Protocol (LDAP) is an application protocol for querying and modifying directory services running over TCP/IP. EngageOne Digital Delivery can be configured to interface with an LDAP server as its user account authenticator and as a data source for initial information when auto-populating a user account.

Prerequisites

Prior to configuring EngageOne Digital Delivery to use LDAP as an authentication provider ensure that the following exist:

• Installed EngageOne Digital Delivery

• A pre-configured LDAP server

Steps

To use LDAP as the EngageOne Digital Delivery authentication provider:

1. Install necessary components (see “Prerequisites”)

2. Edit security.xml (see “Configuration”)

3. Restart EngageOne Digital Delivery web application for changes to take effect

Configuration

EngageOne Digital Delivery configuration for security related features such as LDAP is stored in a file named “security.xml”. The file can be found within “WEB-INF” folder of EngageOne Digital Delivery web application. Editing this file requires a text editor such as notepad.

Mapping an Activer Directory user

To map an Active Directory user in the EngageOne Digital Delivery application:

1. Create a new vendor or you can also use an existing vendor. You must ensure that the vendor for which you want to authenticate the Active Directory user, is also set as the default vendor. Refer “vendorProvider” on page 127.

2. In the vendor, create a role. You must ensure that name of the role is same as name of the Active Directory group, which the user you want to autneticate belongs to. You have to create a separate role for all those Active Directory groups, which the user is member of and you want to assign those group permissions to the user.

121

LDAP Configuration

3. Specify the LDAP settings in the security.xml file. How to specify the settings, refer “LDAP connection and search settings” on page 122.

4. Specify the authentication settings to configure an authentication provider, a vendor, and a role. Refer “Authentication providers” on page 124.

5. Now, you can login EngageOne Digital Delivery with the Active Directory username & password.

LDAP connection and search settings

This section of the document will explain various settings that you need to configure for authenticating LDAP users in EngageOne Digital Delivery.

initialDirContextFactory

The initialDirContextFactory setting contains information on how EngageOne Digital Delivery will communicate with an LDAP server. The parameters are as follows:

• providerURL – The LDAP URL of the server (and root context) to connect to.

• managerDN – Specify a “manager” user's DN to log in with if the LDAP server does not allow anonymous searches.

• managerPassword – Password for “manager”.

<bean id="contextSource" class="org.springframework.security.ldap.DefaultSpringSecurityContextSource">

<constructor-arg value="providerURL"/><property name="userDn" value="userDN"/><property name="password" value="userPassword"/>

</bean>

Sample configuration:

<bean id="contextSource" class="org.springframework.security.ldap.DefaultSpringSecurityContextSource"><constructor-arg value="ldap://161.228.116.82:389"/><property name="userDn" value="cn=E O. System,cn=users,dc=mneoqa1,dc=com"/><property name="password" value="Password1"/></bean>

122

LDAP Configuration

Following is a sample set-up of an Active Directory:

userSearch

The userSearch setting contains information on what field in the LDAP configuration EngageOne Digital Delivery will use to search for the account that is to be authenticated.

• searchBase – The DN where user accounts will be searched.

• searchFilter – The filter expression used in the user search. This is an LDAP search filter (as defined in 'RFC 2254') with optional arguments.

• initialDirContextFactory – reference to initialDirContextFactory configuration (see previous section)

• searchSubtree – If true then searches the entire subtree as identified by context, if false (the default) then only searches the level identified by the context.

<bean id="userSearch" class="org.springframework.security.ldap.search.FilterBasedLdapUserSearch"><constructor-arg index="0">

<value> searchBase</value></constructor-arg><constructor-arg index="1">

<value>searchFilter</value></constructor-arg>

123

LDAP Configuration

<constructor-arg index="2" ref="contextSource"/><property name="searchSubtree">

<value> searchSubtree </value></property>

</bean>


<bean id="userSearch" class="org.springframework.security.ldap.search.FilterBasedLdapUserSearch"><constructor-arg index="0">

<value>cn=users,dc=mneoqa1,dc=com</value></constructor-arg><constructor-arg index="1">

<value>(sAMAccountName={0})</value></constructor-arg><constructor-arg index="2" ref="contextSource"/>

<property name="searchSubtree"><value>true</value>

</property></bean>

Authentication providers

EngageOne Digital Delivery Authentication Providers

The eMessagingAuthenticationProvider setting contains configurations on specifying how EngageOne Digital Delivery will authenticate an account.

authenticateOnLdap – If true, EngageOne Digital Delivery will use LDAP as authentication provider. If false, the default EngageOne Digital Delivery authentication provider will be used.

ldapAuthenticationProvider – reference to an ldapAuthenticationProvider. This does not need to be changed.

daoAuthenticationProvider – reference to a daoAuthenticationProvider. This is the default authentication provider used by EngageOne Digital Delivery. This does not need to be changed.

<bean id="eMessagingAuthenticationProvider"class="com.g1.emessaging.security.providers.EMessagingAuthentication

Provider"><property name="authenticateOnLdap" value="authenticateOnLdap" /><property name="ldapAuthenticationProvider"

ref="ldapAuthenticationProvider" /><property name="daoAuthenticationProvider"

ref="daoAuthenticationProvider"/></bean>

124

LDAP Configuration


<bean id="eMessagingAuthenticationProvider"class="com.g1.emessaging.security.providers.EMessagingAuthentication

Provider"><property name="authenticateOnLdap" value="true" /><property name="ldapAuthenticationProvider"

ref="ldapAuthenticationProvider" /><property name="daoAuthenticationProvider"

ref="daoAuthenticationProvider"/></bean>

Auto-population

The auto-population mechanism enables EngageOne Digital Delivery to automatically add/create or update system specific user information from an LDAP data source.

userPopulator

The userPopulator setting contains information on how EngageOne Digital Delivery will auto-populate an LDAP account to EngageOne Digital Delivery.

userDao – A data access object used by EngageOne Digital Delivery in auto-population. This does not need to be changed.

roleDao – A data access object used by EngageOne Digital Delivery in auto population of roles.

privilegeDao – A data access object used by EngageOne Digital Delivery in auto population of privileges for roles.

vendorProvider – A reference to vendorProvider. See section below regarding vendorProvider. This does not need to be changed.

roleProvider – A reference to roleProvider. See section below regarding roleProvider. This does not need to be changed.

passwordEncoder – The encoder that will be used against the password retrieved from LDAP prior to saving to EngageOne Digital Delivery database. This does not need to be changed.

fieldMappings – Provides the mapping of EngageOne Digital Delivery user info fields to LDAP fields. The following are the EngageOne Digital Delivery user info fields that can be mapped to an LDAP field:

• username

• firstName

• initials

• lastName

125

LDAP Configuration

• jobTitle

• e-mail

• phone

• fax

• role

<bean id="userPopulator" class="com.g1.emessaging.security.providers.EMessagingUserPopulator">

<property name="userDao" ref="emUserDao" /><property name="roleDao" ref="emRoleDao" /><property name="privilegeDao" ref="privilegeDao" /><property name="vendorProvider" ref="vendorProvider" /><property name="roleProvider" ref="roleProvider" /><property name="passwordEncoder" ref="passwordEncoder" /><property name="fieldMappings">

<props><prop key="username">LDAP_field_to_username</prop><prop key="firstName">LDAP_field_to_firstName</prop><prop key="initials">LDAP_field_to_initials</prop><prop key="lastName">LDAP_field_to_lastName</prop><prop key="jobTitle">LDAP_field_to_jobTitle</prop><prop key="e-mail">LDAP_field_to_e-mail</prop><prop key="phone">LDAP_field_to_phone</prop><prop key="fax">LDAP_field_to_fax</prop><prop key="role">LDAP_field_to_memberOf</prop>

</props></property>

</bean>

Sample configuration (using Microsoft Active Directory as the LDAP server):

<bean id="userPopulator" class="com.g1.emessaging.security.providers.EMessagingUserPopulator">

<property name="userDao" ref="emUserDao" /><property name="roleDao" ref="emRoleDao" /><property name="privilegeDao" ref="privilegeDao" /><property name="vendorProvider" ref="vendorProvider" /><property name="roleProvider" ref="roleProvider" /><property name="passwordEncoder" ref="passwordEncoder" /><property name="fieldMappings">

<props><prop key="username">samaccountname</prop><prop key="firstName">givenname</prop><prop key="initials">initials</prop><prop key="lastName">sn</prop><prop key="jobTitle"></prop><prop key="e-mail">mail</prop><prop key="phone">telephonenumber</prop><prop key="fax">facsimiletelephonenumber</prop>

ENGAGEONE DIGITAL DELIVERY REQUIRES AT

LEAST A MAPPING FOR THE E-MAIL FIELD AND MUST

BE A MEMBER OF A GROUP EXISTING IN BOTH

emESSAGING AND LDAP. FOR MORE INFORMATION

ON HOW TO GET THE FIELDS OF THE LDAP

SERVER, PLEASE CONSULT THE DOCUMENTATION

OF YOUR LDAP SERVER.

126

LDAP Configuration

<prop key="role">memberOf</prop></props>

</property></bean>

vendorProvider

The vendorProvider setting provides information on what vendor the auto-populated account will belong to.

defaultVendor – The name of the default vendor the auto-populated account will be a member of.

vendorDao – A data access object used be EngageOne Digital Delivery to find the vendor specified in defaultVendor. This does not need to be changed.

<bean id="vendorProvider" class="com.g1.emessaging.security.providers.DefaultVendorProvider">

<property name="defaultVendor" value="defaultVendor" /><property name="vendorDao" ref="vendorDao" />

</bean>

roleProvider

The roleProvider setting provides information on what role the auto-populated account will have.

roleDao – A data access object used by EngageOne Digital Delivery to find the role specified in defaultRole. This does not need to be changed.

privilegeDao – A data access object used by EngageOne Digital Delivery in auto population of privileges for roles.

<bean id="roleProvider" class="com.g1.emessaging.security.providers.DefaultRoleProvider">

<property name="roleDao" ref="emRoleDao" /><property name="privilegeLdapDao" ref="privilegeLdapDao" />

</bean>

THE VENDOR SPECIFIED IN DEFAULTVENDOR MUST

ALREADY BE EXISTING IN ENGAGEONE DIGITAL

DELIVERY

WHEN MULTIPLE ROLES IN LDAP ARE MAPPED TO

A USER IN ENGAGEONE DIGITAL DELIVERY, THE

SYSTEM RETRIEVES ALL ROLES ON THE LDAP

LIST

127

Language Resource Bundles

Adding support for a specific language in the EngageOne Digital Delivery Web-UI can be done by adding / modifying ApplicationResources_<LANGUAGE_ISO_CODE>_<COUNTRY_ISO_CODE>.properties (e.g. ApplicationResources_en.properties) Language Resource Bundle file which resides in <install_path>/core.war/WEB-INF/classes. This is implemented through the Internationalization feature of the solution.

By default EngageOne Digital Delivery fully supports the following languages:

– Chinese (Simplified)– English– French (Canadian)– German– Japanese– Portuguese (Brazilian)– Spanish (Unified)

If you do not specify some of the values in a given Language Resource Bundle file then the values from the default ApplicationResources.properties Language Resource Bundle file will apply.

Example Language Source Bundle file

For instance, if you want to create local support for Portuguese, create a file named ApplicationResources_pt.properties. Consider the country code used in the file, it should be the registered ISO (International Organization for Standardization) country code for Portugal, in this case.

For the contents of this file you must use the default property file for reference. You can copy-paste its values into your own property file and then modify the values. For example, if you want to add a Login Title’s text for Portuguese support, just change the value of the login.title variable:

Before: login.title=Login

After: login.title=Registrar

128


Modify the file faces-config.xml. This file can be found under the "WEB-INF" folder of EngageOne Digital Delivery web application. Locate the tag <locale-config> and add the new locale to be supported. Note: the application parses the locale entries sequentially. If you need to include a country-specific locale, define it before the more generic locale. For example:

<locale-config>...<supported-locale>pt_BR</supported-locale><supported-locale>pt</supported-locale>...<locale-config>

The Portuguese-Brazil (pt-br) should precede the generic Portuguese (pt) locale definition.

Browser configuration

To see the changes that you have added, you must configure your browser’s language setting.

Mozilla Firefox

On the Main Menu, select Tools / Options / Content then in the Languages panel click Choose button. This will take you to the Languages window similar to the image below.

If the language is not in the language list as shown above, add it using the dropdown menu then click Add button to include it in the list.

To make it the default language used by EngageOne Digital Delivery click the language in the list then click Move Up button until it is at the top most part of the list then click OK button. Refresh/restart Firefox.

129


Microsoft Internet Explorer

On the Main Menu, select Tools / Internet Options / General (tab) and then click Languages button. This will take you to the window similar to the image below.

If the language is not in the language list add it using the Add button.

To make it the default language used by EngageOne Digital Delivery click the language in the list then click Move Up button until it is at the top most part of the list then click OK button

Refresh/restart IE.

130

REST Web Service APIs

Outbound Profile Settings

EngageOne Digital Delivery has the ability to allow integration with third-party business systems by providing a set of APIs that return XML-formatted data for the messages being processed.

EngageOne Digital Delivery provides an API to access Outbound Profile details in XML format. You can call this API via HTTP GET requests formatted as specified below

http://<server>:<port>/<contextPath>/resource/v1/outboundprofiles

This request will return all the Outbound Profiles configured in the system across all vendors. If you want Outbound Profiles for specific vendors, provide the name of the vendor in the request parameter as shown below.

http://<server>:<port>/<contextPath>/resource/v1/outboundprofiles?vendor=Pitney%20Bowes

In this case, all the Outbound Profiles configured for vendor “Pitney Bowes” will be returned. In case you are only interested in getting Outbound Profiles configured only for EngageOne, send “source=engageone” parameter in request as shown below. In this case if you don't provide “vendor” parameter then the Outbound Profiles across all vendors configured for EngageOne will be returned.

http://<server>:<port>/<contextPath>/resource/v1/outboundprofiles?vendor=Pitney%20Bowes&source=engageone

At times you might be interested in getting details of just one Outbound Profile, for example to see if it has been modified. This can be done if you already know the “id” of the Outbound Profile. Initially you can fetch all profiles using any of the above mentioned request calls and store the Outbound Profile id at in the calling system in order to be able to request future updates. Later if you’re interested in getting the updated details of any specific profile, you can request it as outlined below.

Suppose you want to get Outbound Profile details for id “5100”, then the HTTP GET request would be:

http://<server>:<port>/<contextPath>/resource/v1/outboundprofiles/5100

131


XML Response from REST Outbound Profile API sample

<?xml version="1.0" encoding="UTF-8” standalone="yes"?><OutboundProfiles><OutboundProfile>

<id>5300</id><Vendor><id>5100</id><name>Pitney Bowes</name></Vendor><NameAndDescription><name>HTMLBatchProfile</name><version>1</version><description>HTML Batch Profile</description><dateLastUpdate>2011-03-08T15:51:11+05:30</dateLastUpdate><userLastUpdate>SUPER S SUPER</userLastUpdate></NameAndDescription><MessageProcessingSettings><gateway>localhost - SMTP - [email protected]</gateway><pollForDij>true</pollForDij><maxBandwidth>0</maxBandwidth><batch>true</batch><messageType>HTML Email</messageType><folderDIJ>c:\vendors\Pitney_Bowes\OutProfiles\HTMLBatchProfile\dij</folderDIJ><folderHTML>c:\vendors\Pitney_Bowes\OutProfiles\HTMLBatchProfile\html</folderHTML><folderText>c:\vendors\Pitney_Bowes\OutProfiles\HTMLBatchProfile\text</folderText><folderImage>c:\vendors\Pitney_Bowes\OutProfiles\HTMLBatchProfile\image</folderImage><folderError>c:\vendors\Pitney_Bowes\OutProfiles\HTMLBatchProfile\error</folderError><archive>false</archive><loadFrequency>0</loadFrequency><archiveFormat>Original Parts only</archiveFormat><archiveFolder></archiveFolder><e2WebURL></e2WebURL><messageIdIndex>0</messageIdIndex><availableForApplications><application>engageone</application></availableForApplications></MessageProcessingSettings><MessageContentAndHeaderSettings><dijCharset>UTF-8</dijCharset><messageHeaderCharset>UTF-8</messageHeaderCharset><htmlCharset>UTF-8</htmlCharset>

132


<textCharset>UTF-8</textCharset><overrideImageDimension>false</overrideImageDimension><contentVerification>true</contentVerification><digitallySignMessageBody>false</digitallySignMessageBody><insertMessageBeacon>false</insertMessageBeacon>

<displayLocation>Default</displayLocation><displayWidth>Default</displayWidth><priority>Normal</priority><fromAddress>[email protected]</fromAddress><replyToAddress>[email protected]</replyToAddress><returnPathAddress>[email protected]</returnPathAddress><errorsToAddress>[email protected]</errorsToAddress></MessageContentAndHeaderSettings><Attachments/><SMSGatewaySettings><smsApiID></smsApiID><clickatellUserName></clickatellUserName><sourceAddress></sourceAddress><deliveryAcknowledgement>0</deliveryAcknowledgement><enableCallback>0</enableCallback><deliveryTime>0</deliveryTime><maximumCredits>1.0</maximumCredits><deliveryQueue>1</deliveryQueue><gatewayEscalation>0</gatewayEscalation><mobileOriginated>0</mobileOriginated><validityPeriod>1440</validityPeriod></SMSGatewaySettings><Permissions><sendJobsPermissions><group>Manager</group><group>All / Default</group><user> </user></sendJobsPermissions><editOutboundProfilePermissions><group>Manager</group><group>All / Default</group><user> </user></editOutboundProfilePermissions><viewReportsPermissions><group>Manager</group><group>All / Default</group><user> </user></viewReportsPermissions></Permissions><Status>

133


<active>true</active></Status></OutboundProfile>

<OutboundProfile><id>5301</id><Vendor><id>5100</id></Vendor><NameAndDescription><name>HTMLBatchProfileWithAttachments</name><version>1</version><description>Html batch profile with attachments</description><dateLastUpdate>2011-03-08T15:52:47+05:30</dateLastUpdate><userLastUpdate>SUPER S SUPER</userLastUpdate></NameAndDescription><MessageProcessingSettings><gateway>localhost - SMTP - [email protected]</gateway><pollForDij>true</pollForDij><maxBandwidth>0</maxBandwidth><batch>true</batch><messageType>HTML Email</messageType><folderDIJ>c:\vendors\Pitney_Bowes\OutProfiles\HTMLBatchProfileWithAttachments\dij</folderDIJ><folderHTML>c:\vendors\Pitney_Bowes\OutProfiles\HTMLBatchProfileWithAttachments\html</folderHTML><folderText>c:\vendors\Pitney_Bowes\OutProfiles\HTMLBatchProfileWithAttachments\text</folderText><folderImage>c:\vendors\Pitney_Bowes\OutProfiles\HTMLBatchProfileWithAttachments\image</folderImage><folderError>c:\vendors\Pitney_Bowes\OutProfiles\HTMLBatchProfileWithAttachments\error</folderError><archive>false</archive><loadFrequency>0</loadFrequency><archiveFormat>Original Parts only</archiveFormat><archiveFolder></archiveFolder><e2WebURL></e2WebURL><messageIdIndex>0</messageIdIndex><availableForApplications/></MessageProcessingSettings><MessageContentAndHeaderSettings><dijCharset>UTF-8</dijCharset><messageHeaderCharset>UTF-8</messageHeaderCharset><htmlCharset>UTF-8</htmlCharset><textCharset>UTF-8</textCharset><overrideImageDimension>false</overrideImageDimension><contentVerification>true</contentVerification><digitallySignMessageBody>false</digitallySignMessageBody>

134


<insertMessageBeacon>false</insertMessageBeacon><displayLocation>Default</displayLocation><displayWidth>Default</displayWidth><priority>Normal</priority><fromAddress>[email protected]</fromAddress><replyToAddress>[email protected]</replyToAddress><returnPathAddress>[email protected]</returnPathAddress><errorsToAddress>[email protected]</errorsToAddress><Attachments><attachment name="Attachment1"><fileType>PDF</fileType><charset>UTF-8</charset><folder>c:\vendors\Pitney_Bowes\OutProfiles\HTMLBatchProfileWithAttachments\attach1</folder><static>false</static><optional>true</optional><archive>false</archive></attachment><attachment name="Attachment2"><fileType>PDF</fileType><charset>UTF-8</charset><folder>c:\vendors\Pitney_Bowes\OutProfiles\HTMLBatchProfileWithAttachments\attach2</folder><static>false</static><optional>true</optional><archive>false</archive></attachment><attachment name="Attachment3"><fileType>PDF</fileType><charset>UTF-8</charset><folder>c:\vendors\Pitney_Bowes\OutProfiles\HTMLBatchProfileWithAttachments\attach3</folder><static>true</static><optional>true</optional><archive>false</archive><staticFiles><fileName>document1.pdf</fileName><fileName>document2.pdf</fileName></staticFiles></attachment></Attachments><SMSGatewaySettings><smsApiID></smsApiID><clickatellUserName>

</clickatellUserName><sourceAddress></sourceAddress><deliveryAcknowledgement>0</deliveryAcknowledgement>

135


<enableCallback>0</enableCallback><deliveryTime>0</deliveryTime><maximumCredits>1.0</maximumCredits><deliveryQueue>1</deliveryQueue><gatewayEscalation>0</gatewayEscalation><mobileOriginated>0</mobileOriginated><validityPeriod>1440</validityPeriod></SMSGatewaySettings><Permissions><sendJobsPermissions><group>Manager</group><group>All / Default</group><user> </user></sendJobsPermissions><editOutboundProfilePermissions><group>Manager</group><group>All / Default</group><user> </user></editOutboundProfilePermissions><viewReportsPermissions><group>Manager</group><group>All / Default</group><user> </user></viewReportsPermissions></Permissions><Status><active>true</active></Status></OutboundProfile><OutboundProfile><id>5302</id><Vendor><id>5101</id><name>Test</name></Vendor><NameAndDescription><version>1</version><description>html batch profile</description><dateLastUpdate>2011-03-08T15:55:19+05:30</dateLastUpdate><userLastUpdate>SUPER S SUPER</userLastUpdate></NameAndDescription><MessageProcessingSettings><gateway>localhost - SMTP - [email protected]</gateway><pollForDij>true</pollForDij><maxBandwidth>0</maxBandwidth><batch>true</batch><messageType>HTML Email</messageType><folderDIJ>c:\vendors\Test\OutProfiles\HTMLTestBatchProfile\dij</folderDIJ><folderHTML>c:\vendors\Test\OutProfiles\HTMLTestBatchProfile\html</folderHTML>

136


<folderText>c:\vendors\Test\OutProfiles\HTMLTestBatchProfile\text</folderText><folderError>c:\vendors\Test\OutProfiles\HTMLTestBatchProfile\error</folderError><archive>false</archive><loadFrequency>0</loadFrequency><archiveFormat>Original Parts only</archiveFormat><archiveFolder></archiveFolder><e2WebURL></e2WebURL><messageIdIndex>0</messageIdIndex><availableForApplications><application>engageone</application></availableForApplications></MessageProcessingSettings><MessageContentAndHeaderSettings><dijCharset>UTF-8</dijCharset><messageHeaderCharset>UTF-8</messageHeaderCharset><htmlCharset>UTF-8</htmlCharset><textCharset>UTF-8</textCharset><overrideImageDimension>false</overrideImageDimension><contentVerification>true</contentVerification><digitallySignMessageBody>false</digitallySignMessageBody><insertMessageBeacon>false</insertMessageBeacon><displayLocation>Default</displayLocation><displayWidth>Default</displayWidth><priority>Normal</priority><replyToAddress>[email protected]</replyToAddress><returnPathAddress>[email protected]</returnPathAddress><errorsToAddress>[email protected]</errorsToAddress></MessageContentAndHeaderSettings><Attachments/><SMSGatewaySettings><smsApiID></smsApiID><clickatellUserName></clickatellUserName><sourceAddress></sourceAddress><deliveryAcknowledgement>0</deliveryAcknowledgement>

<enableCallback>0</enableCallback><deliveryTime>0</deliveryTime><maximumCredits>1.0</maximumCredits><deliveryQueue>1</deliveryQueue><gatewayEscalation>0</gatewayEscalation><mobileOriginated>0</mobileOriginated><validityPeriod>1440</validityPeriod></SMSGatewaySettings>

137


<Permissions><sendJobsPermissions><group>All / Default</group><user> </user></sendJobsPermissions><editOutboundProfilePermissions><group>All / Default</group><user> </user></editOutboundProfilePermissions><viewReportsPermissions><group>All / Default</group><user> </user></viewReportsPermissions></Permissions><Status><active>true</active></Status></OutboundProfile></OutboundProfiles>

Node details

<OutboundProfiles> - Root node and contains all the Outbound Profiles.

<OutboundProfile> - Represents one Outbound Profile <id> - Unique identifier of Outbound Profile.

<Vendor> - Contains vendor details to which this Outbound Profile belongs. <id> - Unique identifier of vendor <name> - Vendor Name

<NameAndDescription> - Contains child nodes to provide details of Outbound Profile. <name> - Name of Outbound Profile <version> - Version of Outbound Profile <description> - Description of Outbound Profile <dateLastUpdate> - Date when this Outbound Profile was last updated <userLastUpdate> - User by whom this Outbound Profile was last updated.

<MessageProcessingSettings> - Contains child nodes to provide details of Message Processing Settings.

<gateway> - Contains Gateway details configured for this Outbound Profile in following format: Name - Type - Username

Where:

Name - Gateway IP/Host Name

Type - Gateway Type e.g. SMTP, POP3, IMAP etc.

Username - Gateway Username

138


<pollForDij> - Contains true or false. If true, this profile will continuously poll for DIJ (XML journal file) in "dij" folder <maxBandwidth> - Maximum bandwitdh consumption for Outbound Profile in kbps <batch> - If true, this profile is configured to process "Batch" input files. False implies "Real-time" input files expected, i.e. one message represented per input file. <messageType> - Represents Message Type e.g HTML email, plain text email, SMS and more. <folderDIJ> - Directory from which DIJ (XML journal) files will be processed <folderHTML> - Directory from which (e)HTML will be processed <folderText> - Directory from plain text content can be found <folderImage> - Directory where images referenced by HTML can be found <folderError> - Directory where content that fails to process gets written <archive> - If true, archiving is enabled for this profile. <loadFrequency> - Specifies time in seconds to wait before batching content up for archiving <archiveFormat> - Format of the content to be archived. E.g. Original Parts only, Converted Parts - PDF only etc. <archiveFolder> - Specify Vault's polled directory for new messages needing to be archived <e2WebURL> - The base URL to an Vault Service web interface <messageIdIndex> - Specify the index number (IndexX=...) in the Vault's profile that is configured for the MessageID indexes <availableForApplications> - Provides the list of all the applications for which this profile is enabled. <application> - Name of the application. E.g "engageone"

<MessageContentAndHeaderSettings> - Contains child nodes to provide message content and header settings. <dijCharset> - Charset used by DIJ <messageHeaderCharset> - Charset to be used for email headers. <htmlCharset> - Charset used by HTML content <textCharset> - Charset used by Plain Text content <overrideImageDimension> - If true, height and width of actual images will override height and width specified in HTML image tags <contentVerification> - If true, EngageOne Digital Delivery performs additional checks to verify that correct content is inserted into each message <digitallySignMessageBody> - If true, email bodies processed by this Outbound Profile will include a digital signature by default. <insertMessageBeacon> - If true, EngageOne Digital Delivery will insert a transparent image into each HTML message to track when it is opened <displayLocation> - Specifies where HTML should be displayed on screen <displayWidth> - Specifies width (in pixels) at which HTML should be displayed on screen <priority> - Message priority - only applicable to outbound email <fromAddress> - Email address that will appear in "from" email header.

139


<replyToAddress> - Email address that will appear in "Reply-to" email header. <returnPathAddress> - Email address for delivery failure notifications <errorsToAddress> - Alternative email address for delivery failure notifications

<Attachments> - Contains child nodes to provide attachment details <attachment name="Attachment1"> - Contains child nodes to provide details of one attachment mentioned in name attribute <fileType> - Attachment Type e.g. PDF, Text, XML etc. <charset> - Charset of attachment file <folder> - Directory from which attachment will be processed. <static> - If true, this attachment is of type static, else Personalized <optional> - If true, this attachment is optional, else compulsory. <archive> - If true, this attachment will be archived. <staticFiles> - Provides list of all the static files present in directory if static is true. <fileName> - Contains name of static file

<SMSGatewaySettings> - Contains child nodes to provide SMS Gateway Settings <smsApiID> - ApiID required for sending messages through SMS gateway <clickatellUserName> - Clickatell User Name <sourceAddress> - The source / sender address that the message will appear to come from <deliveryAcknowledgement> - Where possible this will return a delivery acknowledgement for any message upon successful delivery to mobile handset or upstream gateway. <enableCallback> - If true, enables you to receive message delivery statuses via an HTTP callback which is posted to a URL of yours using the GET method <deliveryTime> - Delays delivery of SMS to mobile device in minutes relative to the time at which the SMS was received by our gateway <maximumCredits> - Overrides the maximum charge specified online in "profiles" <deliveryQueue> - Delivers the message through one of three queues assigned to each client account <gatewayEscalation> - If 1, Prompts an escalation to an alternative delivery gateway, should the message be delayed for a set length of time <mobileOriginated> - If 1, Route via a pre-defined carrier to enable the ability for a reply to be received back <validityPeriod> - The validity period in minutes relative to the time at which the SMS was received by the gateway

<Permissions> - Contains child elements to provide details of all the permissions <sendJobsPermissions> - Provides list of groups and users with "Send Jobs" Permission <group> - Represents all users with a "Role" of this name. There can be multiple group elements <user> - Represents "User". There can be multiple user elements. <editOutboundProfilePermissions> - Provides list of groups and users with

140


the permission to edit this Outbound Profile in EngageOne Digital Delivery. The group and user element are same as mentioned above. <viewReportsPermissions> - Provides list of groups and users with the permission to view delivery reports in EngageOne Digital Delivery for the messages that have been sent by this Outbound Profile. The group and user element are same as mentioned above.

<Status> - Provides status of Outbound Profile<active> - If true, Outbound Profile is active.

Error XMLIf any error occurs while processing an API request, then the API will return an error message formatted in XML, similar in format to the examples shown below:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?><error><type>BAD_REQUEST</type><description>Vendor 'Dummy' does not exists</description></error>

Possible error types and messages are described below.

Type : BAD_REQUESTMessages : 1.Vendor "Vendor_Name" does not exists.2.No Outbound Profile found for ID : "Outbound Profile ID"

Type : INTERNAL_SERVER_ERRORMessages : 1.An unexpected error occurred at server end. Please check server logs.

Type : AUTHENTICATION_FAILEDMessages :1.Access Denied.

Restricting API Access

To secure the exposed API, only specific IP addresses and/or hostnames are allowed to access the API. A list of such IP addresses and/or hostnames is maintained in the <install_path>/core.war/WEB-INF/servlet.properties file under the “outprofile.provider.allowed” property setting. The REST API for Outbound Profile settings will accept requests from a server only if the IP address or hostname of that server is mentioned in the list.

However, if the IP address of your server is dynamic, then specifying that IP address in the servlet.properties file will not work. In that case, you have to specify the FQDN (Fully Qualified Domain Name) in place of IP address in the servlet.properties file. However, in some cases, you may still face issues if you are using Tomcat application servers.

141


In that case, you have to edit some property settings related to the Tomcat servers as explained below.

For TomcatIf you are using Tomcat, then complete the following steps:

1. Navigate to the “conf” directory in the installation directory of Tomcat and open the server.xml file in edit mode.

2. Replace the “<Connector connectionTimeout="20000" port="8080" protocol="HTTP/1.1" redirectPort="8443"/>....” property settings with the following:

<Connector connectionTimeout="20000" enableLookups="true" port="8080" protocol="HTTP/1.1" redirectPort="8443"/>...

Setting enableLookups="true" will resolve the IP addresses to hostnames.

Workflow item

EngageOne Digital Delivery provides an API to access a specific workflow item’s state. You can call this API via HTTP GET requests formatted as specified below.

http://<server>:<port>/<contextPath>/workflow/WorkflowItemProvider?workflowId=workflow_item_id you_want_to_retrieve

The API will return XML containing the workflow item state, similar to the one below.

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?><WorkflowItem id=”1”> <MessageID>[email protected]_20070730170622_abc123def458</MessageID><Subject>Subject 1</Subject><From>[email protected]</From><CustomerID>123456789</CustomerID><URL>http://www.company.com/e2ServiceWeb/interface.plx?DB=default &[email protected]_20070730170622_abc123def458</URL><Stage>1</Stage><InProfile>eMessagingUser</InProfile><Category>Complaint</Category><CategoryURL>http://www.company.com/emessaging/url/to/categorisationpage/workflowItemId</CategoryURL><Date>20090113000000</Date></WorkflowItem>

where:

WorkflowItem id – unique identifier of the workflow item

142


MessageID – unique Message ID assigned to the item

Subject – e-mail subject

From – e-mail sender

CustomerID – Vault Account Number for the sender or receiver

URL – link to view the item

Stage – workflow stage the item is currently on

InProfile – inbound profile name used when this item was generated

Category – category that has been associated with the message. If the Message Categorization feature is disabled then the value of this element is Undefined

CategoryURL – link to a page where the associated message category can be updated. If the Message Categorization feature is disabled then this element is omitted

Date – date the message was sent

Should an error occur while processing the retrieval request, then the API will return an error message formatted in XML, similar to the one below.

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?><error>No workflow item id specified.</error>

Outbound message

EngageOne Digital Delivery provides an API to access specific outbound message’s state. You can call this API via HTTP GET requests formatted as specified below:

http://<server>:<port>/<contextPath>/workflow/OutMessageProvider?<search>=<value>&...

You can specify one or more search criteria for retrieving an outbound message. The following criteria can be passed as query string parameters:

customerId – account number obtained from DIJ

workflowId – unique workflow item identifier

to – outbound message recipient

subject – outbound message subject

sentDate – outbound message sent date (in YYYYMMDD format)

143


docInstanceId – document instance id for the outbound message

For example, to retrieve details on outbound message having customer ID set to “ABCD”, submit:

http://<server>:<port>/<contextPath>/workflow/OutMessageProvider?customerId=ABCD

To further limit the search by specifying ‘to’ value, submit:

http://<server>:<port>/<contextPath>/workflow/[email protected]&sentDate=20090707

The API will return XML containing the outbound message state, similar to the one below:

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?><OutMessage id="5158"><SendJob id="" version="" name=""/><OutProfile id="5300"/><Customer id="PB554"/><WorkflowItem id="5111"/><WorkflowStage id="3"/><MessageID>ro.nald1@domain.com.20100707025942.0886FC074484B34E899B1A63F01E4AB5</MessageID><To>[email protected]</To><From>[email protected]</From><ReplyTo>[email protected]</ReplyTo><ErrorsTo>[email protected]</ErrorsTo><ReturnPath>[email protected]</ReturnPath><Subject>Software Maintenance Payment Reminder (PB554)</Subject><attachments><attachment name="Attach1"> Newport News Ship Building.pdf </attachment><attachment name="Attach2"> Attachment2_PB554.pdf </attachment><attachment name="Attach3"> Attachment3_PB554.pdf </attachment><attachment name="Attach4"> Attachment4_PB554.pdf </attachment><attachment name="Attach5"> Attachment5_PB554.pdf </attachment><attachment name="Attach6"> Attachment6_PB554.pdf </attachment></attachments> <DateSent>20100707145942</DateSent><DateExpire>20100820000000</DateExpire><DateFirstOpened></DateFirstOpened><DateLastOpened></DateLastOpened><OutOfOfficeDate></OutOfOfficeDate><DateResponse></DateResponse><StatusCode id="PERMANENT_DELIVERY_FAILURE " code ="550"/><Charge></Charge><Bill_JobNo></Bill_JobNo></OutMessage>

where:

144


OutMessage id – unique identifier for the outbound message

SendJob id – unique job id, message sent using EngageOne Digital Delivery Scheduling function

SendJob version – version of Scheduled job to that sent the message

SendJob name – name of Scheduled job that sent the message

OutProfile id – id of the Outbound Profile used to send the outbound message

Customer id – account number specified in the DIJ

WorkflowItem id – related workflow item, if any

WorkflowStage id – stage of related workflow item, if any

MessageID – unique id for the message

To – outbound message recipient

From – From e-mail header

ReplyTo – Reply-to e-mail header

ErrorsTo – Errors-to e-mail header

Subject – message subject

Attachments – a new Attachments element has been introduced. The Attachments element can have any number of Attachment child elements - one for each attachment that has been configured for the Outbound Profile that processed the message.

Attachment – An attachment entry is present for each attachment that has been configured for the Outbound Profile that sent the message. It provides details including the attachment's filename.

DateSent – date message was sent

DateExpire – message expiration date

DateFirstOpened – date and time that the message was first opened

DateLastOpened – date and time that the message was last opened

OutOfOfficeDate – date and time that an out of Office reply was received for the message

DateResponse – date message was replied to

StatusCode – status of the message including the actual SMTP or SMS status code that was returned by the Gateway

145


Charge – credits charged for sending SMS

Bill JobNo – currently unused

Should an error occur while processing the API request, then the API will return an error message formatted in XML, similar to the one below.

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?><error>No Outbound Message match found.</error>

Possible error messages are:

No Outbound Message match found – if no outbound message matched the search criteria specified

Multiple Outbound Message matches found – if multiple outbound messages matched the search criteria specified

Calls to the REST “Outbound message” API can optionally trigger an update for the “DateOpened” field for a message by including “update=1” in the API request string. For example:http://<server>:<port>/<contextPath>/workflow/[email protected]&sentDate=20090707&update=1


To secure the exposed API, only specific IP addresses and/or hostnames are allowed access. This address list is maintained in the <install_path>/core.war/WEB-INF/servlet.properties file.

If an unspecified machine tries to access the API, it will receive the error message below,

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?><error>Access denied.</error>

Note: In the servlet.properties file, if you specify an IP address, which is dynamic, then you may face some issues. How to resolve such issues, please refer information under “Restricting API Access” on page 141.

Message Processing APIs

This section lists the REST APIs that can be used to submit and process messages (email/SMS).

146


Send email

EngageOne Digital Delivery provides a REST API to process an email message. You can call this API via POST requests formatted as specified below.

URI Format:

http://<server>:<port>/<contextPath>/resource/{version}/messages/email

In this format, you can specify the following default values:

<contextPath> : EODigitalDelivery

{version} : v1

For example:

http://localhost:8080/EODigitalDelivery/resource/v1/messages/email

Request Header:

Content-Type - multipart/form-data

Accept : application/json

Request Body:

Following is the list of parameters:

Parameter Description Mandatory (Y/N)

toAddress Recipient email addresses separated by comma Y

subject Email subject N

fromAddress Sender email address N

htmlContent HTML content of the email message body N

htmlFile HTML file containing email message and must be part of the multipart POST (upload file). EngageOne Digital Delivery will give preference to htmlFile over htmlContent, if both are present.

N

textContent Plain text content of the email message body N

textFile Plain text file containing email message and must be part of the multipart POST (upload file). EngageOne Digital Delivery will give preference to textFile over textContent, if both are present.

N

147


Image1Image2…..ImageN

Images embeded in the email message body. Image files must be part of the multipart POST. The preferred size of the image files should be less than 5MB.

N

Attachment1Attachment2…..AttachmentN

Email message personalized attachments. EngageOne Digital Delivery supports multiple file types, which is configurable. Refer “RESTService.properties”. Attachment file contents, must be part of the multipart POST (upload file). These are considered as personalized attachments specific to an email message and deleted after successful processing.

N


Email message static (reusable) attachments. You can specify already uploaded attachment file (using “Upload attachment file(s) for email”) names as value to these parameters.

For example:Attachment1:abc.pdfAttachment2:xyz.doc

N

profileName EngageOne Digital Delivery profile that will process the message. The profile must be active and poll for DIJ should be disabled.

Y

accNo Account number or customer ID N

stmtDate Statement date. Should be in the YYYYMMDD format.

N

custName Customer name N

custCity Customer city N

custPhoneNumber Customer telephone number N

custAdd1 Customer address 1 N


emailHeaders Comma separated custom email headers in key value pairFor example:X-Accept-Language1=eng, X-Mailer2=MyApp2

N

148


Following is the sample email data for this REST API call (Multi part form data):

toAddress:[email protected]:[email protected]:Sending TEXT Message using REST API CallhtmlContent: <html><title>HTML data for REST API</title><body>Using REST API Call</body></html>subject:Sending message through REST API CallprofileName:smtp_emailaccNo:111111stmtDate:01012015custName:Test USercustAddr1:Line 1, KT roadcustAddr2:Line 2, MT roadcustCity:NYcustPhoneNumber:657656Attachment1:abc.pdfAttachment2:xyz.docbatchName:BatchTestIdcustomerId:123233batchId:BatchTestName

customArchiveFields comma separated custom fields in name-value pair to be archived in Vault.For example:fieldname1=fieldvalue1, fieldname2=fieldvalue2

N

cc Comma separated email addresses for CC N

bcc Comma separated email addresses for BCC N

replyTo Reply-to email address N

returnPath ReturnPath email address N

errorTo ErrorTo email address N

digitalSign To enable digital signing of email (true/false) N

batchName Name of the batch N

customerId Id of the customer N

batchId Id of the batch N

soureId Id of the source system providing data N

autoNotificationEndPoint emailId/SMS where message will be sent N

Note: In case you provide batch information, either batchId or batchName is mandatory alongwith customerId. If you do not specify batchId, then batchName will be treated as batchId. If a batch is executed again with same batch information, then a new batch is not created.

149


sourceId:source01autoNotificationEndPoint:9999999999 or (autoNotificationEndPoint:[email protected])

Service Response:

The API will return the following response (JSON) on successfully receiving the client request for further processing of the email message:

{status: "Success"docInstanceId: "1444045961689PIFTGRKTKKSJBDF5Q23"description: "Message accepted for processing and detailed validation"statusCode: "1"deliveryStatusURL: "http://localhost:8080/EODigitalDelivery/resource/v1/messages/deliveryStatus?docInstanceId=1444045961689PIFTGRKTKKSJBDF5Q23"}

Where:

status - status (accepted/rejected) of the request

docInstanceId - a unique transaction id for the message

description - description of the status

statusCode - status code (1/0) accepted/rejected

deliveryStatusURL - service URI to check status of the message delivery.

In case of failure, the API will return the following response (JSON):

{status: "Error"description: "Invalid To email address customer@@emessaging.com"statusCode: "0"}

Send SMS

EngageOne Digital Delivery provides a REST API to process SMS. You can call this API via POST requests formatted as specified below.

URI Format:

http://<server>:<port>/<contextPath>/resource/{version}/messages/sms

For example:

http://localhost:8080/EODigitalDelivery/resource/v1/messages/sms

150


Request Header:

Content-Type - application/json

Request Body:



msisdn Mobile handset number of the customer Y

textContent Plain text content of the SMS N

fromAddress This is where the SMS will appear to originate from for the recipient

N

profileName EngageOne Digital Delivery profile that will process the SMS. The profile must be active and poll for DIJ should be disabled.

Y

smsDataCoding To dynamically set SMS data coding (ASCII, UTF8, ISO8859_1, etc.) for each message.

N



N






customArchiveFields Comma separated custom fields in name-value pair to be archived in VaultFor example:fieldname1=fieldvalue1,fieldname2=fieldvalue2

N





151


Following is the sample SMS data for REST API call (JSON data):

{"msisdn":"987898899776","fromAddress":"TD-CITI","textContent":"Sending SMS Message using REST API Call","profileName":"smpp_trx_profile","smsDataCoding":"UTF8""custData" :{"custName" : "custName","custAddr1": {"lineNumber" : "1","value" : "custAddr1"},"custAddr2": {"lineNumber" : "2","value" : "custAddr2"},"custCity" : "custCity","custPhoneNumber" : "565656"}"batchId":"B1","batchName":"Batch1","customerId":"Cust1",“sourceId”:”source01”}

Service Response:

The API will return the following response (JSON) on successfully receiving the client request for further processing of the SMS:



152


Where:



description - status description


deliveryStatusURL - service URI to check status of SMS delivery.


{status: "Error"description: "Invalid mobile number 9999999999"statusCode: "0"}

Send Mobile Push Notification

When using Mobile Push Notification, there should be different outbound profiles for different target environment, for example:

Android devicesthe outbound profile should point to AWS_SNS_Mobile_Push or FCM_Mobile_Push type of gateway.

iOS/OS X devicesthe outbound profile should point to APNS_Mobile_Push or AWS_APNS_Mobile_Push type of gateway.

Therefore, the message processing API responsible for sending Mobile Push Notification requests should point to these different profiles depending on the device type.

Send Mobile Push Notification (to single device)

Digital Delivery provides a REST API to process a mobile push notification. You can call this API via POST requests formatted as specified below.

URI Format:

http://<server>:<port>/<contextPath>/resource/{version}/messages/mobilePushNotification



{version} : v1

153


For example:

http://localhost:8080/EODigitalDelivery/resource/v1/messages/mobilePushNotification

Request Header:


154


Request Body:


Following is the single mobile push notification request (JSON format):

{

"textContent":"Bonjour, cela émet une poussée mobile","title" : "Emessaging notification","deviceRegId" :["dNF53zOufhE:APA91bFuMy18vjT2QfTbDCT4bJFrjGjv9O1PwB9Vlu2_c-Gy7ixLWiViWmiO","dNF53zOufhE:APA91bFuMy18vjT2QfTbDCT4bJFrjGjv9O1PwB9Vlu2_c-Gy7ixLWiViWmiO"],"profileName":"mpush_profile_aws","imageUrl":"https://s28.postimg.org/hexoto9gt/image.jpg","videoUrl": "https://www.youtube.com/watch?v=NK40rupmZu4","likeUnlikeTrack": true,"callToAction": 9810137222,"fromAddress" :"Pitney bowes"}

Service Response:

The API will return the following response (JSON) on successfully receiving the client request:


textContent Text content of notification N

title Title of notification N

deviceRegId Alphanumeric string which identifies a device Y

profileName Digital Delivery profile that will process the message

N

imageUrl Image URL part of notification, which will show on notification

N

videoUrl Video URL part of notification, which will play when notification is clicked

N

likeUnlikeTrack Flag to enable/disable the like/unlike feature on notification

N

callToAction Enables the calling feature on notification, if set to mobile number/ land line number

N

fromAddress Represents the notification sender N

155


[{"status": "Success","docInstanceId": "1505056787311RWYM8FBFUDJK50B9ID1","description": "Message accepted for processing and detailed validation", "statusCode": "1","deliveryStatusURL": "http://localhost:8080/EODigitalDelivery/resource/v1/messages/deliveryStatus?docInstanceId=1505056787311RWYM8FBFUDJK50B9ID1"}]

Send a Single Notification to Different Devices

Digital Delivery provides a REST API to process a same mobile push notification to different devices. You can call this API via POST requests formatted as specified below.

URI Format:

http://<server>:<port>/<contextPath>/resource/{version}/messages/mobilePushNotification



{version} : v1

For example:

http://localhost:8080/EODigitalDelivery/resource/v1/messages/mobilePushNotification

Request Header:


Request Body:





deviceRegIds Array of device IDs Y

156


Following is the same mobile push notification request for multiple device registration ids (JSON format):

{"textContent":"Bonjour, cela émet une poussée mobile","title" : "Emessaging notification","deviceRegIds" :["dNF53zOufhE:APA91bFuMy18vjT2QfTbDCT4bJFrjGjv9O1PwB9Vlu2_c-Gy7ixLWiViWmiO1WiIF0TgFqnsRuDCNjtO9lL2dAp3OJ57dMcIU2pvaO9NocQk5zQn9Tjd5D3SGuWNCiI1cu1D0ha2px6p",:["dNF53zOufhE:APA91bFuMy18vjT2QfTbDCT4bJFrjGjv9O1PwB9Vlu2_c-Gy7ixLWiViWmiO1WiIF0TgFqnsRuDCNjtO9lL2dAp3OJ57dMcIU2pvaO9NocQk5zQn9Tjd5D3SGuWNCiI1cu1D0ha2px6p"],"profileName":"mpush_profile_aws","imageUrl":"https://s28.postimg.org/hexoto9gt/image.jpg","videoUrl": "https://www.youtube.com/watch?v=NK40rupmZu4","likeUnlikeTrack": true,"callToAction": 9810137222,"fromAddress" :"Pitney bowes"}

Service Response:


[{"status": "Success","docInstanceId": "1505112063587TBMQDSIU6WQTSGCV4LV","description": "Message accepted for processing and detailed validation","statusCode": "1","deliveryStatusURL": "http://localhost:8080/EODigitalDelivery/resource/v1/messages/deliveryStatus?docInstanceId=1505112063587TBMQDSIU6WQTSGCV4LV"


N


N


N


N


N


157


},{"status": "Success","docInstanceId": "1505112063589NNQZPE4IG4RLMUJXZX2","description": "Message accepted for processing and detailed validation","statusCode": "1","deliveryStatusURL": "http://localhost:8080/EODigitalDelivery/resource/v1/messages/deliveryStatus?docInstanceId=1505112063589NNQZPE4IG4RLMUJXZX2"}]

Batch for Sending Mobile Push Notification

Digital Delivery provides a REST API to process different mobile push notifications to different devices. You can call this API via POST requests formatted as specified below.

URI Format:

http://<server>:<port>/<contextPath>/resource/{version}/messages/mobilePushNotification/batch



{version} : v1

For example:

http://localhost:8080/EODigitalDelivery/resource/v1/messages/mobilePushNotification/batch

Request Header:


Request Body:





deviceRegIds Alphanumeric string which identifies a device Y

158


Following is the batch request for sending mobile push notification (JSON format):

{"messages":[{"textContent":"Mobile Push Notification from emessaging ","title" : "Emessaging notification","deviceRegId" :"eY92An3Uxe0:APA91bE_k-qxMg1z7r1Z_Pne28BIwl2RS9dY3aIby_691uKpFhI_Y2cOyLl4ip8ILcOVRW5uWPWmK6oy9KxSO1wBdKoHM2AKZowFD3XJjr6ZW7LCUtpnqh9mskSVIdpZfuszxFlIxshu","profileName":"mpush_profile_aws","imageUrl":"https://s28.postimg.org/hexoto9gt/image.jpg","videoUrl": "https://www.youtube.com/watch?v=NK40rupmZu4","likeUnlikeTrack": true,"callToAction": 9810137222,"fromAddress" :"Pitney bowes" },{"textContent":"Mobile Push Notification","title" : "Emessaging notification","deviceRegId" :"ftbf2Rb-NW0:APA91bF9FLTUyiWMUvOEEZ-1MCUuW7PWaebrY6FrB_6qHJuviYNiTvMCGCdL0B-8wXtmE-uNxtvgR-SzKZI_WXORsY6YPTPYF1P7oa2Fevf3j97F2eulpgVb6ugOXH4GjnEYr5uZELMz","profileName":"mpush_profile_aws","imageUrl":"https://s28.postimg.org/hexoto9gt/image.jpg","videoUrl": "https://www.youtube.com/watch?v=NK40rupmZu4","likeUnlikeTrack": true,"callToAction": 9810137222,"fromAddress" :"Pitney bowes" },


N


N


N


N


N


159


{"textContent":"Mobile Push Notification","title" : "Emessaging notification","deviceRegId" :"dv1WgOKdsFw:APA91bHLzhqt3RQtp-BaLqBoD57dKDFYt8HGVLT-B1Stdj75AR_C0aXPuzPPkOr6Ct97M0gELMwbhtgfs65kzcpdNxBG-yKqXk8QjRcisDaKBAkzPWfBhQMwWa18_-7ICFDER1EvKcd0","profileName":"mpush_profile_aws","imageUrl":"https://s28.postimg.org/hexoto9gt/image.jpg","videoUrl": "https://www.youtube.com/watch?v=NK40rupmZu4","likeUnlikeTrack": true,"callToAction": 9810137222,"fromAddress" :"Pitney bowes" }]}

Service Response:


[{"status": "Success","docInstanceId": "1505112063587TBMQDSIU6WQTSGCV4LV","description": "Message accepted for processing and detailed validation","statusCode": "1","deliveryStatusURL": "http://localhost:8080/EODigitalDelivery/resource/v1/messages/deliveryStatus?docInstanceId=1505112063587TBMQDSIU6WQTSGCV4LV"},{"status": "Success","docInstanceId": "1505112063589NNQZPE4IG4RLMUJXZX2","description": "Message accepted for processing and detailed validation","statusCode": "1","deliveryStatusURL": "http://localhost:8080/EODigitalDelivery/resource/v1/messages/deliveryStatus?docInstanceId=1505112063589NNQZPE4IG4RLMUJXZX2"}]

160


Issues while sending Mobile Push Notification using FCM

1. While using FCM to send Mobile Push Notifications, you may encounter SSL Handshake exceptions in WebSphere. To resolve this, you need to add the certificate in application server.

i. The signer needs to be added to the local trust store. You can use the Retrieve from port option in the administrative console to retrieve the certificate and resolve the problem. If you determine that the request is trusted, complete the following steps:

ii. Log into the administrative console.

iii. Expand Security and click SSL certificate and key management. Under Configuration settings, click Manage endpoint security configurations.

iv. Select the appropriate outbound configuration to get to the (cell):Node1Cell:(node):Node1 management scope.

v. Under Related Items, click Key stores and certificates and click the NodeDefaultTrustStore key store.

vi. Under Additional Properties, click Signer certificates and Retrieve From Port.

vii. Enter the following:Host : gcm-http.googleapis.comPort : 443Alias : NodeDefaultSSLSettings

viii. Click Retrieve Signer Information.

ix. Verify that the certificate information is for a certificate that you can trust.

x. Click Apply and Save.

xi. Restart WebSphere.

2. While using FCM to send Mobile Push Notifications, you may encounter “failed hostname verification check” exceptions in WebLogic. To resolve this, you need to do following steps:

i. Go to the WebLogic admin console -> Environment -> Servers -> your server -> Configuration -> SSL

ii. Click Lock & Edit

iii. Open the Advanced flap

iv. Change Hostname Verification from BEA Hostname Verifier to Custom Hostname Verifier

v. Set Custom Hostname Verifier to weblogic.security.utils.SSLWLSWildcardHostnameVerifier

161


vi. Click Save and then Activate Changes

vii. Restart your server.

Upload image file(s) for email

EngageOne Digital Delivery provides an API to upload image files to EngageOne Digital Delivery server. The uploaded image files are referenced in the htmlFile containing HTML content to be displayed as email body. You can call this API via POST requests formatted as specified below.

URI Format:

http://<server>:<port>/<contextPath>/resource/{version}/messages/image

For example:

http://localhost:8080/EODigitalDelivery/resource/v1/messages/image

Request Header:


Request Body:

Parameter: profileName

For example:

profileName:smtp_email

This is the only parameter that you need to pass for this service call. On successful execution, the specified image files will be saved to the following location on the EngageOne Digital Delivery server:

...\vendors\TestVendor\OutProfiles\smtp_email\image

Service Response:

The API will return the following response (JSON) containing the list of uploaded image files:

{description: "Image files uploaded for profileName : smtp_email - Logo.jpg, metlife.gif, promo_check_for_error_12345.jpg"}

162


Upload attachment file(s) for email

EngageOne Digital Delivery provides an API to upload attachment files to EngageOne Digital Delivery server. You can attach the uploaded files with the email messages to be processed in subsequent requests to the “Send email” API. In other words, you can attach these files in addition to the personalized attachments. You can call this API via POST requests formatted as specified below.

URI Format:

http://<server>:<port>/<contextPath>/resource/{version}/messages/attachment

For example:

http://localhost:8080/EODigitalDelivery/resource/v1/messages/attachment

Request Header:


Request Body:

Parameter: profileName

For example:

profileName:smtp_email

This is the only parameter that you need to pass for this service call. On successful execution, the specified files will be saved to the following location on the EngageOne Digital Delivery server:

...\vendors\TestVendor\OutProfiles\smtp_email\attach1

Service Response:

The API will return the following response (JSON) containing the list of uploaded files:

{description: "Attachment files uploaded for profileName : smtp_email - email_1message.pdf"}

Retry sending failed message

EngageOne Digital Delivery provides an API to retry processing of failed messages. You can call this API via POST requests formatted as specified below.

163


URI Format:

http://<server>:<port>/<contextPath>/resource/{version}/messages/retryMessage

For example:

http://localhost:8080/EODigitalDelivery/resource/v1/messages/retryMessage

Request Header:


Request Body:


Following is the sample data for this REST API call (application/json):

{

"docInstanceId": "1444045961689PIFTGRKTKKSJBDF5Q23",

"profileName": "smtp_email"

}

Service Response:

The API will return the following response (JSON) on successfully receiving the client request for further processing of the failed message:



docInstanceId a unique transaction id for the message (email/SMS)

Y

profileName EngageOne Digital Delivery profile that will process the message

Y

164



To secure the exposed APIs, only specific IP addresses and/or hostnames are allowed access. This address list is maintained in the <install_path>/core.war/WEB-INF/servlet.properties file through the following property:

messageprocessor.provider.allowed=localhost,127.0.0.1,0:0:0:0:0:0:0:1

Note: In the servlet.properties file, if you specify an IP address, which is dynamic, then you may face some issues. How to resolve such issues, please refer information under “Restricting API Access” on page 141.

Get message delivery status

EngageOne Digital Delivery provides an API to check status of a message (email/SMS) delivery. You can call this API via GET requests formatted as specified below.

URI Format:

http://<server>:<port>/<contextPath>/resource/{version}/messages/deliveryStatus?...

For example:

http://localhost:8080/EODigitalDelivery/resource/v1/messages/deliveryStatus?...



docInstanceId a unique transaction id for the message (email/SMS)

Y

to toAddress for email message or msisdn for SMS N

customerId Account number or customer ID N

sentDate Date on which the message is sent. Should be in the YYYYMMDD or YYYYMMDDHHmmSS format.

N

fromDate Starting date if you want to search in a date range. Should be in the YYYYMMDD or YYYYMMDDHHmmSS format.

N

165


Request Header:


Accept : application/json

Request Body:

Not required.

Sample Request:

Following is the sample request with some parameters:

http://localhost:8080/EODigitalDelivery/resource/v1/messages/deliveryStatus?docInstanceId=1444045961689PIFTGRKTKKSJBDF5Q23&[email protected]&fromDate=20160101&toDate=20160909&maxRecordCount=1000&sentDate=20150101&workflowId=5351&subject=Message through REST API Call&customerId=111111

Service Response:

Following is a successful service response after message processing:

[1]0: "status": "Success""docInstanceId": "1444045961689PIFTGRKTKKSJBDF5Q23""description": "Successful"

"deliveryDateTime": "20160715155500""to": "[email protected]""fromAddress": "[email protected]""messageId": "[email protected]_20160715035500_180""errorsTo": "[email protected]""returnPath": "[email protected]""subject": "Subject1""deliveryStatusURL": "http://localhost:8080/EODigitalDelivery/resource/v1/messages/deliveryStatus?docInstanceId=1444045961689PIFTGRKTKKSJBDF5Q23"}

toDate Ending date if you want to search in a date range. Should be in the YYYYMMDD or YYYYMMDDHHmmSS format.

N

workflowId Unique workflow item identifier N


maxRecordCount Maximum number of records to be retrieved. Default value is 20 and maximum value is 1000.

N

166


In case failed status, the response will look like:

[1]{"status": "Success""docInstanceId": "1468578300122OGX1TLTBD7A35FS1I2G""description": "Permanent Failure""statusCode": "550""deliveryDateTime": "20160715155500""customerId": "12323445""to": "[email protected]""fromAddress": "[email protected]""messageId": "[email protected]_20160715035500_180""errorsTo": "[email protected]""returnPath": "[email protected]""subject": "Subject1""deliveryStatusURL": "http://localhost:8080/EODigitalDelivery/resource/v1/messages/deliveryStatus?docInstanceId=1444045961689PIFTGRKTKKSJBDF5Q23"}

Batch Message Processing APIs

Send email (batch)

EngageOne Digital Delivery provides a REST API to process email messages in batches. You can call this API via POST requests formatted as specified below.

URI Format:

http://<server>:<port>/<contextPath>/resource/{version}/messages/batchEmail



{version} : v1

For example:

http://localhost:8080/EODigitalDelivery/resource/v1/messages/batchEmail

Request Header:


Request Body:

In the request body, you need to pass the following parameters:

167


• profileName - EngageOne Digital Delivery profile that will process the message. The profile must be active and poll for DIJ should be disabled.

• json - JSON metadata input parameter, if you are passing the input in a string

• jsonFile - JSON metadata input parameter, if you are passing the input in a file. If you pass both, string and file, as input, then file will be given preference.

In a json string/file, you have to proovide the following parameters for each email recepient:


toAddress Recipient email addresses separated by comma Y


fromAddress Sender email address N

htmlContent HTML content of the email message body N

htmlFile1htmlFile2…..htmlFileN

HTML file containing email message and must be part of the multipart POST (upload file). EngageOne Digital Delivery will give preference to htmlFile over htmlContent, if both are present.

N

textContent Plain text content of the email message body N

textFile1textFile2…..textFileN

Plain text file containing email message and must be part of the multipart POST (upload file). EngageOne Digital Delivery will give preference to textFile over textContent, if both are present.

N

Image1Image2…..ImageN

Images embeded in the email message body. Image files must be part of the multipart POST. The preferred size of the image files should be less than 5MB.

N


Email message personalized attachments. EngageOne Digital Delivery supports multiple file types, which is configurable. Refer “RESTService.properties”. Attachment file contents, must be part of the multipart POST (upload file). These are considered as personalized attachments specific to an email message and deleted after successful processing.

N

168



Email message static (reusable) attachments. You can specify already uploaded attachment file (using “Upload attachment file(s) for email”) names as value to these parameters.

For example:Attachment1:abc.pdfAttachment2:xyz.doc

N



N






emailHeaders Comma separated custom email headers in key value pairFor example:X-Accept-Language1=eng, X-Mailer2=MyApp2

N

customArchiveFields comma separated custom fields in name-value pair to be archived in Vault.For example:fieldname1=fieldvalue1, fieldname2=fieldvalue2

N

cc Comma separated email addresses for CC N

bcc Comma separated email addresses for BCC N

replyTo Reply-to email address N

returnPath ReturnPath email address N

errorTo ErrorTo email address N

digitalSign To enable digital signing of email (true/false) N





169


Following is the sample email data (JSON string) for this REST API call (Multi part form data):

[{

"toAddress": "[email protected]","fromAddress": "[email protected]","replyTo": "[email protected]","subject": "Subject - Bulk/Batch message through REST API Call","textContent": "Text Message content for REST API","htmlContent": "<html>HTML Message for REST API</html>","htmlFile": {"fileName": "email_1message.html","isStaticHtml": "true"},"textFile": {"fileName": "1.txt","isStaticText": "false"},"attachmentList": [{"fileName": "email_1message.pdf","isStaticAttachment": "true"}]},{"toAddress": "[email protected]","fromAddress": "[email protected]","replyTo": "[email protected]","subject": "Subject - Bulk/Batch message through REST API Call","textContent": "Text Message content for REST API","htmlContent": "<html>HTML Message for REST API</html>","htmlFile": {"fileName": "email_2message.html","isStaticHtml": "true"},"textFile": {"fileName": "2.txt","isStaticText": "false"},"attachmentList": [{"fileName": "email_2message.pdf","isStaticAttachment": "true"},{"fileName": "BatchData.pdf","isStaticAttachment": "false"},{"toAddress": "[email protected]","fromAddress": "[email protected]","replyTo": "[email protected]",


170


"subject": "Subject - Bulk/Batch message through REST API Call","textContent": "Text Message content for REST API","htmlContent": "<html>HTML Message for REST API</html>","htmlFile": {"fileName": "email_3message.html","isStaticHtml": "true"},"textFile": {"fileName": "3.txt","isStaticText": "false"},"attachmentList": [{"fileName": "email_3message.pdf","isStaticAttachment": "true"},{"fileName": "BatchData.pdf","isStaticAttachment": "false"}]"batchId":"B1","batchName":"Batch1","customerId":"Cust1",“sourceId”:”source01”}]

Service Response:

The API will return the following response (JSON) on successfully receiving the client request for further processing of the email message:


Where:



description - description of the status


deliveryStatusURL - service URI to check status of the message delivery.


171


{status: "Error"description: "Invalid To email address customer@@emessaging.com"statusCode: "0"}

Send email (batch) using ZIP files

EngageOne Digital Delivery provides a REST API to process email messages in batches using ZIP files. You can call this API via POST requests formatted as specified below.

URI Format:

http://<server>:<port>/<contextPath>/resource/{version}/messages/batchEmailCompressed



{version} : v1

For example:

http://localhost:8080/EODigitalDelivery/resource/v1/messages/batchEmailCompressed

Request Header:


Request Body:

List of parameters will be similar as given under “Send email (batch)”. There is one additional parameter:

zipFile1, zipFile2, ....zipFileN

Service Response:

Response will be similar as given under “Send email (batch)”.

Send SMS (batch)

EngageOne Digital Delivery provides a REST API to process SMS in batches. You can call this API via POST requests formatted as specified below.

URI Format:

http://<server>:<port>/<contextPath>/resource/{version}/messages/batchSMS

172


For example:

http://localhost:8080/EODigitalDelivery/resource/v1/messages/batchSMS

Request Header:


Request Body:

In the request body, you need to pass the following parameters:

• profileName - EngageOne Digital Delivery profile that will process the message. The profile must be active and poll for DIJ should be disabled.

• json - JSON metadata input parameter, if you are passing the input in a string

• jsonFile - JSON metadata input parameter, if you are passing the input in a file. If you pass both, string and file, as input, then file will be given preference.

In a json string/file, you have to proovide the following parameters:

Following is the sample SMS data for REST API call (JSON data):


msisdn Mobile handset number of the customer Y

textContent Plain text content of the SMS N

fromAddress This is where the SMS will appear to originate from for the recipient

N



N






customArchiveFields Comma separated custom fields in name-value pair to be archived in VaultFor example:fieldname1=fieldvalue1,fieldname2=fieldvalue2

N

173


[{"msisdn":"987898899764","fromAddress":"TD-PBI","textContent":"Sending SMS Message using REST API Call",}{"msisdn":"987898899765","fromAddress":"TD-PBI","textContent":"Sending SMS Message using REST API Call",}{"msisdn":"987898899766","fromAddress":"TD-PBI","textContent":"Sending SMS Message using REST API Call",}{"msisdn":"987898899767","fromAddress":"TD-PBI","textContent":"Sending SMS Message using REST API Call",}{"msisdn":"987898899768","fromAddress":"TD-PBI","textContent":"Sending SMS Message using REST API Call",}{"msisdn":"987898899769","fromAddress":"TD-PBI","textContent":"Sending SMS Message using REST API Call",}{"msisdn":"987898899770","fromAddress":"TD-PBI","textContent":"Sending SMS Message using REST API Call",}{"msisdn":"987898899779","fromAddress":"TD-PBI","textContent":"Sending SMS Message using REST API Call",}{"msisdn":"987898899778","fromAddress":"TD-PBI","textContent":"Sending SMS Message using REST API Call",}{"msisdn":"987898899777","fromAddress":"TD-PBI","textContent":"Sending SMS Message using REST API Call",}]

174


Service Response:

The API will return the following response (JSON) on successfully receiving the client request for further processing of the SMS:


Where:



description - status description


deliveryStatusURL - service URI to check status of SMS delivery.


{status: "Error"description: "Invalid mobile number 9999999999"statusCode: "0"}

Report APIs

Report Download

EngageOne Digital Delivery provides an API to download the Sent (Global) report in the CSV format. You can call this API via GET requests formatted as specified below.

URI Format:

http://<server>:<port>/<contextPath>/resource/{version}/report/download?...

For example:

175


http://localhost:8080/EODigitalDelivery/resource/v1/report/download?...


Request Header:

Not required

Request Body:

Not required.

Sample Request:

Following is the sample request with parameters:

http://localhost:8080/EODigitalDelivery/resource/v1/report/download?outProfName=Test_Profile&dateFrom=2015-10-01&dateTo=2015-12-01

Service Response:

Successful request will return the data in CSV format that you can save.

Report Count

EngageOne Digital Delivery provides an API to fetch the count of records, which will be downloaded when you will call the Report Download API for a specified date range. You can call this API via GET requests formatted as specified below.

URI Format:

http://<server>:<port>/<contextPath>/resource/{version}/report/count?...

For example:

http://localhost:8080/EODigitalDelivery/resource/v1/report/count?...



outProfName Outbound profile name. You can specify multiple profile names separated by comma ",".

Y

dateFrom & dateTo Date range for which the report will be downloaded. Date format: yyyy-mm-dd

Y


176


Request Header:

Not required

Request Body:

Not required

Sample Request:

Following is the sample request with some parameters:

http://localhost:8080/EODigitalDelivery/resource/v1/report/count?outProfName=Test_Profile&dateFrom=2015-10-01&dateTo=2015-12-01

Service Response:

The API will return the following response:

Info : Total records found for Profile Test_Profile is : 200

Dashboard APIs

This section lists the REST APIs that can be used to get dashboard details for email and SMS.

Dashboard Summary API for email

EngageOne Digital Delivery provides a REST API to get dashboard summary details for email. You can call this API via GET requests formatted as specified below.

URI Format:

http://<server>:<port>/<contextPath>/resource/{version}/dashboard/summary/email?startDate=<value>&endDate=<value>



{version} : v1

outProfName Outbound profile name. You can specify multiple profile names separated by comma ",".

Y

dateFrom & dateTo Date range for which the report will be downloaded. Date format: yyyy-mm-dd

Y

177


For example:

http://localhost:8080/EODigitalDelivery/resource/v1/dashboard/summary/email?startDate=2016-10-10&endDate=2016-10-16

Request Header:

Accept-Language: en

userName: super

Service Response:


{

"key": "total"

"label": "Total"

"count": "3440"

"data":

[

2]

0:

{

"key": "succesful"

"label": "Successful"

"count": 1730

"data":

[

3]

0:

{

"key": "repliedOn"

"label": "Replied On"

"count": 647

178


}

-

1:

{

"key": "Opened"

"label": "Opened"

"count": 104

}

-

2:

{

"key": "outOfOffice"

"label": "Out Of Office"

"count": 587

}

-

-

}

-

1:

{

"key": "Error"

"label": "Error"

"count": 1710

"data":

[

4]

0:

179


{

"key": "contentFailure"

"label": "Content Failure"

"count": 978

}

-

1:

{

"key": "temporaryFailure"

"label": "Temporary Failure"

"count": 0

}

-

2:

{

"key": "permanentFailure"

"label": "Permanent Failure"

"count": 732

}

-

3:

{

"key": "unknownDeliveryFailure"

"label": "Unknown Delivery Failure"

"count": 0

}

-

-

180


}

-

-

"status": "success"

"statusCode": "200"

}

Dashboard Summary API for SMS

EngageOne Digital Delivery provides a REST API to get dashboard summary details for email. You can call this API via GET requests formatted as specified below.

URI Format:

http://<server>:<port>/<contextPath>/resource/{version}/dashboard/summary/sms?startDate=<value>&endDate=<value>



{version} : v1

For example:

http://localhost:8080/EODigitalDelivery/resource/v1/dashboard/summary/sms?startDate=2016-10-10&endDate=2016-10-16

Request Header:

Accept-Language: en

userName: super

Service Response:


{

"key": "total"

"label": "Total"

"count": "210"

"data":

181


[

3]

0:

{

"key": "succesful"

"label": "Successful"

"count": 20

"data":

[

3]

0:

{

"key": "deliveredToGateway"

"label": "Delivered To Gateway"

"count": 12

}

-

1:

{

"key": "receivedByRecipient"

"label": "Received By Recipient"

"count": 8

}

-

2:

{

"key": "ok"

"label": "OK"

182


"count": 0

}

-

-

}

-

1:

{

"key": "inProgress"

"label": "In Progress"

"count": 170

"data":

[

2]

0:

{

"key": "messageQueuedForLaterDelivery"

"label": "Message Queued For Later Delivery"

"count": 170

}

-

1:

{

"key": "messageQueued"

"label": "Message Queued"

"count": 0

}

-

183


-

}

-

2:

{

"key": "Error"

"label": "Error"

"count": 20

"data":

[

12]

0:

{

"key": "contentFailure"

"label": "Content Failure"

"count": 20

}

-

1:

{

"key": "temporaryFailure"

"label": "Temporary Failure"

"count": 0

}

-

2:

{

"key": "permanentFailure"

184


"label": "Permanent Failure"

"count": 0

}

-

3:

{

"key": "messageUnknown"

"label": "Message Unknown"

"count": 0

}

-

4:

{

"key": "errorWithMessage"

"label": "Error With Message"

"count": 0

}

-

5:

{

"key": "userCancelledMessageDelivery"

"label": "User Cancelled Message Delivery"

"count": 0

}

-

6:

{

"key": "errorDeliveryMessage"

185


"label": "Error Delivery Message"

"count": 0

}

-

7:

{

"key": "routingError"

"label": "Routing Error"

"count": 0

}

-

8:

{

"key": "messageExpired"

"label": "Message Expired"

"count": 0

}

-

9:

{

"key": "outOfCredit"

"label": "Out Of Credit"

"count": 0

}

-

10:

{

"key": "unsent"

186


"label": "Unsent"

"count": 0

}

-

11:

{

"key": "unknownDeliveryFailure"

"label": "Unknown Delivery Failure"

"count": 0

}

-

-

}

-

-

"status": "success"

"statusCode": "200"

}

Error in response incase invalid date

{

"status": "Invalid date format"

"statusCode": "4001"

}

Error in response incase username is missing in header

{

"status": "userName is missing in request header,"

"statusCode": "4004"

}

187


Campaign Summary APIs

EngageOne Digital Delivery provides a REST APIs to get campaign summary details for a batch and a list of batches associated with a user. You can call this API via GET requests formatted as specified below.

Batch Summary API

This API can be used to fetch batch summary information.

URI Format:

http://<server>:<port>/<contextPath>/resource/{version}/dashboard/batchSummary?startDate=<value>&endDate=<value>&batchName=<value>&customerId=<value>&vendorName=<value>&batchId=<value>&sourceId=<value>

Here, batchId and vendorName are optional parameters. If you do not specify batchId, then API response will provide collated summary counts based on batchName, startDate, endDate and customerId.

In case, a super user wants to view any vendor specific information in this format, then you can also specify the vendorName parameter. You can specify the following default values:


{version} : v1

For example:

http://localhost:8080/EODigitalDelivery/resource/v1/dashboard/batchSummary?startDate=2016-10-20&endDate=2017-01-17&batchName=Batch1&customerId=Cust1&vendorName=test_vendor&batchId=test&sourceId=s1

Request Header:

userName:<value>

Request Body:

Not required.

Sample Request:


http://localhost:8080/EODigitalDelivery/resource/v1/dashboard/batchSummary?startDate=2016-10-20&endDate=2017-01-17&batchName=Batch1&customerId=Cust1&vendorName=test_vendor&batchId=test&sourceId=s1

188


Service Response:


{

"email": {

"key": "total",

"label": "Total",

"count": "1",

"data": [

{

"key": "success",

"label": "Success",

"count": 0,

"data": [

{

"key": "messageReplied",

"label": "Replied",

"count": 0

},

{

"key": "messageOpened",

"label": "Opened",

"count": 0

},

{

"key": "outOfOffice",

"label": "Out Of Office",

"count": 0

}

189


]

},

{

"key": "failure",

"label": "Failure",

"count": 1,

"data": [

{

"key": "contentFailure",

"label": "Content Failure",

"count": 1

},

{

"key": "temporaryFailure",

"label": "Temporary Failure",

"count": 0

},

{

"key": "permanentFailure",

"label": "Permanent Failure",

"count": 0

},

{

"key": "unknownDeliveryFailure",

"label": "Unknown Delivery Failure",

"count": 0

}

]

190


}

],

"status": "Success",

"statusCode": "200"

},

"sms": {

"key": "total",

"label": "Total",

"count": "0",

"data": [

{

"key": "success",

"label": "Success",

"count": 0,

"data": [

{

"key": "deliveredToGateway",

"label": "Delivered to Gateway",

"count": 0

},

{

"key": "receivedByRecipient",

"label": "Received by Recipient",

"count": 0

},

{

"key": "ok",

"label": "OK",

191


"count": 0

}

]

},

{

"key": "queued",

"label": "Queued",

"count": 0,

"data": [

{

"key": "messageQueuedForLaterDelivery",

"label": "Message Queued for later delivery",

"count": 0

},

{

"key": "messageQueued",

"label": "Message Queued",

"count": 0

}

]

},

{

"key": "failure",

"label": "Failure",

"count": 0,

"data": [

{

"key": "contentFailure",

192


"label": "Content Failure",

"count": 0

},

{

"key": "messageUnknown",

"label": "Message Unknown",

"count": 0

},

{

"key": "errorWithMessage",

"label": "Error with message",

"count": 0

},

{

"key": "userCancelledMessageDelivery",

"label": "User Cancelled Message Delivery",

"count": 0

},

{

"key": "errorDeliveryMessage",

"label": "Error Delivery Message",

"count": 0

},

{

"key": "routingError",

"label": "Routing Error",

"count": 0

},

193


{

"key": "messageExpired",

"label": "Message Expired",

"count": 0

},

{

"key": "outOfCredit",

"label": "Out Of Credit",

"count": 0

},

{

"key": "unsent",

"label": "Unsent",

"count": 0

},

{

"key": "unknownDeliveryFailure",

"label": "Unknown Delivery Failure",

"count": 0

}

]

}

],

"status": "Success",

"statusCode": "200"

}

}

194


Batch List API

This API can be used to fetch list of batches associated with a username.

URI Format:

http://<server>:<port>/<contextPath>/resource/{version}/dashboard/batchList/userName?

You can specify the following default values:


{version} : v1

For example:

http://localhost:8080/EODigitalDelivery/resource/v1/dashboard/batchList/userName?testuser

Request Header:

Not required

Request Body:

Not required.

Sample Request:


http://localhost:8080/EODigitalDelivery/resource/v1/dashboard/batchList/userName?testuser

Service Response:


{

"id": 5050,

"batchId": "BId_D01",

"batchName": "BN_D01",

"customerId": "C_D01",

"startDate": 1482391396950,

"endDate": 1482391482810,

195


"vendorName": "test_anshul",

"vendorId": 5050

}

REST API Security over Basic Authentication

Authentication is the process of identifying whether a client is eligible to access a resource or not. The HTTP protocol supports authentication as a means of negotiating access to a secure resource like API.

Basic authentication sends a Base64-encoded string that contains a user name and password for the client. Base64 is not a form of encryption and should be considered same as sending the user name and password in clear text.

Enable/disable Basic Authentication

Digital Delivery supports basic authentication for REST APIs. To enable/disable it, you need to update basic.authentication.enforced.apilist property in the bservlet.properties file. You can specify comma separated multiple URL context names of the APIs to be protected.

For example: basic.authentication.enforced.apilist=workflow,messages,outboundprofiles,messageprocessor,report

Setting blank value will be considered as no basic authentication applied on any of the REST API's.

196

Application Monitoring Support Using JMX

It is possible to enable an event notification facility within EngageOne Digital Delivery processes. This is made possible by JMX (Java Management Extensions), a Java standard solution for application and network management.

EngageOne Digital Delivery MBeans (Management Bean)

EngageOne Digital Delivery provides MBeans which basically provides interfaces for all notifications it generates using JMX. The application provides 6 MBeans which cover basic notifications for its different components.

• ApplicationCoreMonitor – Monitor which provides notification for the core components of the application, e.g. VaultRender server

The ApplicationCoreMonitor provides additional operations that can be invoked from a JMX console, getE2ServerStatus(). The operation expects VaultRender server address, port, and database name, when invoked, it will return you whether the server you queried is online or offline.

• ConversionServiceMonitor – Monitor which provides notifications for the conversion component of the application - provides notifications when the OpenOffice server is offline

• InboundMailServiceMonitor – Monitor which provides notifications for the inbound component of the application which includes inbound gateway connection failure notification

• OutboundMailServiceMonitor – Monitor which provides notifications for the outbound component of the application which includes outbound SMTP and SMS gateway connection failure notifications

OTHER MBEAN DOES NOT PROVIDE ANY

OPERATION OTHER THAN THE TOGGLE FOR

ENABLENOTIFICATION ATTRIBUTE.

197


• ReportGenerationMonitor – Monitor which provides notifications for unsuccessful generation of the reports in the web interface.

• ScheduledJobMonitor – Monitor which provides notifications for the scheduling component of the application, specifically for outbound scheduled jobs, which includes notifications of scheduled job success and command execution failure.

All MBeans have a writable attribute EnableNotification, by default it will be set to true which indicates that the MBean is capable of sending notifications to its subscribers. When set to false publishing of notifications is disabled.

Application Server built-in MBeans

Some application servers provide basic manageability mechanisms for resources running in its container. You can turn on such MBeans from the application server to manage components that are not present in the EngageOne Digital Delivery current release.

Here are some components of the application that can be managed using the application server built-in MBeans.

• SmsServlet availability – Monitor which indicates whether the SmsServlet is available for transaction.

• EngageOne Digital Delivery web application availability – Monitor which indicates whether is EngageOne Digital Delivery is online and ready for transaction.

All Mbeans in the application are available under the domain name com.g1.emessaging.monitoring.mbean.

ALL MBEANS IN THE APPLICATION ARE AVAILABLE

UNDER THE DOMAIN NAME

COM.G1.EMESSAGING.MONITORING.MBEAN

enableNotification attributeMBeans for

EngageOne

198


itor

itor

itor

itor

itor

Notification types available to EngageOne Digital Delivery

The following section describes notifications that can be subscribed to when EngageOne Digital Delivery is running.

Notification types

Type Triggered when… Managed-Bean

Repository Façade initialization failure

A profile was updated/created, resulting in initialization of a Repository Façade agent but fails to complete it

ApplicationCore Mon

Internal mail server connection failure

The application attempts to send a message, i.e. password e-mail, but failed to send it

ApplicationCore Mon

User has been lock-out A user fails to login and exceeds the allowed log-in attempts

ApplicationCore Mon

Vault Render server connection failure

An Vault look-up has been made but failed to connect to the Vault Render Server

ApplicationCore Mon

LDAP connection failure LDAP authentication failed due to failure in connecting with the LDAP server

ApplicationCore Mon

Open Office connection failure

PDF conversion fails because it is not possible to connect to the specified instances of Open Office

ConversionService Monitor

Inbound mail gateway connection failure

Mailbox polling failed InboundMailService Monitor

Outbound mail gateway connection failure

Sending e-mail through the outbound gateway failed OutboundMailServiceMonitor

199


Configuring EngageOne Digital Delivery to enable JMX notification

You require a JMX-capable notification console to subscribe to notifications produced by EngageOne Digital Delivery,. Many application servers provide a built-in JMX console that can be used to perform operations on an MBean and view notifications.

This section provides guidance on application monitoring settings for different application servers supported by EngageOne Digital Delivery.

Websphere configuration

This section covers Websphere 8.5.5 version. As with other servers, JMX is enabled on Websphere start-up. There is no graphical JMX console available for Websphere. MBeans running on Websphere are only accessible through its proprietary scripting interface. Check your Websphere documentation on how to create scripts to perform operations on the MBeans running on it. For Websphere 8.5.5, check if JMX has already been enabled or not (if accessible through JMX console). If not then this can be enabled as described below.

After deploying EngageOne Digital Delivery, enable the PMI (Performance Monitoring Infrastructure) data. Select Monitoring and Tuning in the left pane, click Performance Monitoring Infrastructure (PMI) in the Configuration tab, enable PMI, and set all the statistics enabled. Also, set all the statistics in the Runtime tab and save the changes. Now, EngageOne Digital Deliverygo to Severs -> Server Types -> WebSphere Application Servers and click on the server. In the right pane, go to Server Infrastructure -> Java and Process Management and click on Process definition. In the Additional Properties of the Configuration tab, click on Java Virtual Machine. Set -Djavax.management.builder.initial= -Dcom.sun.management.jmxremote in the Generic JVM Argument field and save the changes. Finally, update management.properties (File: Websphere directory \AppServer\java\jre\lib\management\management.properties).

Specify the below values if not already added (configured as per requirement):

com.sun.management.jmxremote.port=9001

com.sun.management.jmxremote.ssl=false

com.sun.management.jmxremote.authenticate=false

Save the master data and restart the server to load the changes.

YOU CAN ALSO USE THIRD-PARTY MANAGEMENT

TOOLS SUCH AS IBM TIVOLI, HP OPENVIEW AND

CA UNICENTER FOR MONITORING APPLICATION

EVENTS. HOWEVER, SOME OF THESE TOOLS DO

NOT DIRECTLY SUPPORT JMX, AND INSTEAD

PROVIDE PLUG-INS FOR JMX SUPPORT. PLEASE

CHECK THEIR RESPECTIVE DOCUMENTATION ON

HOW YOU COULD USE THEM AS YOUR JMX

MANAGEMENT CONSOLE. YOU CAN ALSO USE THE

BUNDLED JCONSOLE PROVIDED WITH THE JDK

INSTALL AS YOUR JMX VIEWER. SEE THE

JCONSOLE CONFIGURATION SECTION FOR

FURTHER DETAILS.

200


To access built-in Websphere MBean

1. To display the SmsServlet MBean, search for it under the Cell <cell_name>/Node <node_name>/Process <server_name> domain

2. To display the EODigitalDelivery.war MBean, search for it under the Cell <cell_name>/Node <node_name>/Process <server_name> domain.

Viewing notifications using Websphere

There is no graphical JMX console available for Websphere.

Weblogic configuration

JMX is enabled on Weblogic start-up (if not already enabled, below are the instructions to enable it). There is no graphical JMX console for Weblogic, although, you may still be able to access EngageOne Digital Delivery MBean using third party JMX console.

If JMX is not enabled on start-up, then this can be enabled as mentioned below. The required JAVA_OPTIONS need to be set for JMX in the bat file (e.g. in startWeblogic.bat, set JAVA_OPTIONS=%JAVA_OPTIONS%, Dcom.sun.management.jmxremote=127.0.0.1,

SmsServlet MBean

SCREENSHOT WERE TAKEN USING WEBSPHERE

MBEANINSPECTOR.

EngageOne Digital Delivery Bean

Identifies when the EngageOne Digital Delivery application is online or offline.

PLEASE CHECK YOUR WEBLOGIC DOCUMENTATION

FOR FUTHER DETAILS ON HOW TO ACCESS AND

VIEW NOTIFICATIONS FOR JMX MBEANS

OUT-OF-BOX. THIS DOCUMENT COVERS BEA

WEBLOGIC 12C VERSION.

201


Dcom.sun.management.jmxremote.port=7009, Dcom.sun.management.jmxremote.ssl=false, and Dcom.sun.management.jmxremote.authenticate=false). From the Admin Console, enable the protocol and IIOP port. In the left pane of the Admin Console, expand Environment and select Servers, click the Protocols tab, and then select IIOP. Enable the IIOP check box to enable the IIOP protocol. To modify the default configuration, click Advanced and if you need to specify a default IIOP username and password, then enter a username and password. To activate these changes, restart the server.

To access built-in Weblogic MBeans

1. To display the SmsServlet MBean, search for it under the com.bea domain and AdminServer.

2. To display the EODigitalDelivery.war MBean, search for it under the com.bea domain and AdminServer.

Viewing notifications using Weblogic

There is no graphical JMX console available for Weblogic.

Jconsole configuration

The most basic and free tool available for JMX monitoring is the JDK Jconsole. JConsole software is bundled with the JDK (Java Development Kit) 1.7 package. The Jconsole executable is located in the bin directory relative to the JDK install directory. Jconsole, can be used to perform basic management operations and view JMX notifications both locally and remotely.

SCREENSHOT TAKEN USING JDK 7 JCONSOLE

web application status

202


To access the EngageOne Digital Delivery MBeans using Jconsole:

1. Start the application server with the following java properties specified

• Dcom.sun.management.jmxremote

• Dcom.sun.management.jmxremote.port=<<remote_port>>

2. Start Jconsole and connect using the Remote tab.

You can also connect using the Jconsole locally, just select the PID exposed by your application server on its start-up from the Local tab of Jconsole. For a detailed reference, please check documentation on Local Monitoring and Management

3. Navigate to com.g1.emessaging.monitoring.mbean domain for the list of application MBeans under the MBeans tab. In the right frame, you can perform operations on the service provided by each MBean under the Attributes and Operations tabs.

THIS WILL ALSO TURN-ON JMX MBEANS AVAILABLE

ON THE JVM USED BY YOUR APPLICATION SERVER.

FOR A COMPLETE REFERENCE ON AVAILABLE

PROPERTIES THAT COULD BE SET FOR JMX

MONITORING, PLEASE CHECK DOCUMENTATION ON

JMX MANAGEMENT AND MONITORING

PROPERTIES.

EngageOne Digital Delivery MBeans

203


To view notifications using Jconsole: Select an MBean in the left frame of the Jconsole, then select the Notifications tab in the right frame, and click Subscribe to receive notifications.

FOR A DETAILED REFERENCE ON PERFORMING

JMX OPERATIONS WITH JCONSOLE, REFER TO THE

DOCUMENTATION ON USING JCONSOLE.

204

Appendix A – Archiving of Generic e-Mail Messages

It should be noted that EngageOne Digital Delivery can be configured to archive ad-hoc e-mail messages, inbound or outbound, by configuring rules on your mail server to forward or copy messages to a specific e-mail account, sometimes called a journaling account. An EngageOne Digital Delivery Inbound Profile can then be configured to access these messages as it does any other inbound messages and prepare them for archiving.

The rest of this section explains how to configure such e-mail forwarding rules on two commonly used e-mail servers – Lotus Domino and Microsoft Exchange. The content provided in this Appendix is provided for informational purposes only. You should refer to and follow instructions provided in the Lotus Domino and Microsoft Exchange user manuals prior to setting up e-mail forwarding on these servers. Pitney Bowes Software accepts no responsibility for the accuracy of the content provided in this Appendix.

Setting Up E-mail Forwarding on Lotus Domino

1. From the Inbox, select Create / Design / Agent.

205


This will launch Lotus Domino Designer.

2. In the Agent dialog box, type in the agent name (e.g. ToArchiveDB).

3. In the Action Menu selection, choose After new mail has arrived.

206


4. Close the Agent dialog box by clicking the Close icon.

5. In the Action drop-down list, select Copy to Database.

6. Click the Choose Database button. This will bring up the Choose Database dialog box.

Click Add Action in the designer screen to access the Add Action screen.

207


7. From the Server drop-down list, choose a server.

8. From the Database selection list, choose the database where the document should be copied to.

9. Click the Open button.

10. Click the Select button to select a database from the list box.

208


11. Click the OK button to add the action to the agent.

12. Save the agent by clicking the Save button.

209


Setting Up E-mail Forwarding on Microsoft Exchange

1. From Administrative tools in the start menu, open the Active Directory User and Computers window.

2. Select the forwarding mailbox/account then click on Action / Properties.

3. In the Exchange General tab, click the Delivery Options button.

210


4. Select Forward to: then click Modify.

5. Select the mailbox that will receive the forwarded messages then click OK.

211


6. Tick the Deliver messages to both forwarding address and mailbox then click OK.

7. Click OK to save the changes made and to close the mailbox.

212

Appendix B – Purge Vendor Scripts

EngageOne Digital Delivery provides purging of data generated within its processes. This is done through an agent included in the core module, which runs at midnight each day by default (for advanced settings please refer to“Purge properties file configuration” on page 214) to purge EngageOne Digital Delivery data according to the criteria below.

In the Vendors table each Vendor record specifies the following purge period in months/days:

• Purge_Process_Errors

• Purge_Audit

• Purge_Reports

• Purge_People

• Purge_Workflow

The value of these fields can be configured using EngageOne Digital Delivery Web-UI by going to Vendor Environment page under Vendor / System Settings menu. Please see the Vendor Environment section in the EngageOne Digital Delivery Users Guide.

Purge process errors

This will delete records in the Process_Errors table where the date in the Date_Created field subtracted from the current system date is greater than the months specified in the Purge_Process_Errors value in the Vendor record.

Purge audit messages

This will delete records in the Audit_Message table where the date in the Date_Created field subtracted from the current system date is greater than the months specified in the Purge_Audit value in the Vendor record and records created by SUPER user will be deleted on the basis of the highest “Purge_Audit” value of all vendors in the Vendor table.

Purge reports

This task deals with different tables in the EngageOne Digital Delivery database and the actual files in the vendors’ folder.

This will delete records in the Outbound_Message table and corresponding records from Message_Attachment table where:

• Date in the date_last_updated field of outbound_message table subtracted from the current system date is greater than the months specified in the Purge_Reports value in the Vendor record.

• No inbound record exists against the corresponding outbound_message.

213


Purge workflow

This will delete each record in the Workflow_Item table where:

Modified_At in Workflow_Item record subtracted from the current system date is greater than the days specified in the Purge_Workflow value in the Vendor table.

AND

WorkflowStage_Id = 6 or WorkflowStage_Id = 60

Part of purging Workflow_Item this will also includes Deletion of:

• Associated Workflow_History records

• Associated Workflow_Item record

• Associated Msg_Part_Index_History

• Associated Msg_Part_Index

• Associated MsgIndex_People records

• Associated Msg_Index record

• Associated files in Folder_Temp referenced by associated Msg_Part_Index

Purge people

This will delete records in the People table where the Date_Modified field subtracted from current system date is greater than the days specified in the Purge_People value in the Vendor table.

Purge properties file configuration

EngageOne Digital Delivery allows you to migrate from the one you used during installation to a new database server. This can be done by editing the PurgingSetup.properties file which resides in: <install_path>/core.war/WEB-INF/classesThis file should also be updated when you change jdbc.properties file to make the purging function works.

To change the database server name, edit the database value at the upper most part of property file as shown below.

#Purging Setup Properties

purgeDatabase=<DATABASE_SERVER_NAME>

Currently there are three database servers supported in this release that you must use in editing this property file. The following are the valid database server names that you can use:

• Oracle

• MsSQL

214


Note that the Database Server name is case sensitive so please follow the casing as shown above.

To change the default schedule time (e.g. midnight of each day):

scheduleTime=<At what Time Purging starts (yyyy/mm/dd HH:mm)>

To change the schedule interval (by default set to one day):

scheduleInterval=<At what frequency Purging will occur (a numeric value to specify the number of days)>

To enable or disable the Purge feature (by default, enabled), set the following property:

purgeEnabled=<Set to “true” for enabling Purging or set to “false” for disabling Purging>

Restart your application server for the changes to take effect.

215

216

Appendix C – Application Customization

Changing the application logo

If your company is the licensed owner of EngageOne Digital Delivery, you can replace the EngageOne Digital Delivery logo with an image customized for your company. Follow the steps below to replace the logo.

1. Prepare your replacement logo. Name this image file as “Group1Logo.gif”.

2. Navigate to: <EngageOne Digital Delivery Home>/core.war/images

3. Copy the file to this location. Overwrite the existing file when prompted.

Appendix D – SMS Application Programming Interfaces

Background Information

Clickatell (www.clickatell.com) is the one of the SMS providers used by EngageOne Digital Delivery to send and receive SMS messages. Configuring EngageOne Digital Delivery to interface with Clickatell requires no more than a few settings to be specified on the EngageOne Digital Delivery configuration web pages. See the EngageOne Digital Delivery Users Guide for additional details.

EngageOne Digital Delivery interfaces with Clickatell:

• through an SMTP interface for sending messages.

• through an HTTP / callback URL for receiving inbound messages-both status and user originated messages.

As of EngageOne Digital Delivery version 1.3, EngageOne Digital Delivery supports connecting to SMSC gateways via SMPP (Simple Message Peer to Peer protocol) for both processing of outbound and inbound SMS messages. That includes support for processing delivery status updates for the outbound messages.

By default the content for SMS messages is provided to EngageOne Digital Delivery by writing XML journal files and text files into the folders that are polled by an EngageOne Digital Delivery Outbound Profile.

Several customers expressed a requirement to:

• Have EngageOne Digital Delivery send messages through SMS gateways other than Clickatell and via different protocols.

• Receive messages from SMS gateways other than Clickatell and via different protocols and process these messages in EngageOne Digital Delivery.

• Be able to call the EngageOne Digital Delivery SMS sending process directly through a Java API as opposed to the polled folders.

The exposed SMS APIs allow the above three requirements to be implemented in a flexible manner with limited professional services.

217

http://www.clickatell.com


Using the SMS-APIs

Extending the SMS API to Send an Outbound Message through a Custom Gateway

The following steps are required:

Step 1 – Create the custom extension classes (service and composer)Create the custom extension classes (service and composer). To implement CustomService, emessaging-client-api.jar has to be in the classpath. To implement MessageComposer, emessaging-outbound.jar and mail-1.4.jar (part of JavaMail API) has to be in the classpath.

CustomService – This interface is implemented to handle the communication with the custom gateway.

The sendMessage() method accepts an OutboundContextObject parameter. This object stores profile information into a java.util.Map. You can retrieve the SMS settings that have been set in an EngageOne Digital Delivery Outbound Profile as follows:

• SMS API ID: OutboundContextObject.SMS_API_ID_KEY

• Clickatell username: OutboundContextObject.CLICKATELL_USERNAME_KEY

• Clickatell password: OutboundContextObject.CLICKATELL_PASSWORD_KEY

• Source address: OutboundContextObject.SOURCE_ADDRESS_KEY

• Delivery acknowledgement: OutboundContextObject.DELIVERY_ACK_KEY

• Enable callback: OutboundContextObject.ENABLE_CALLBACK_KEY

• Delivery time : OutboundContextObject.DELIVERY_TIME_KEY

• Maximum credits: OutboundContextObject.MAX_CREDITS_KEY

• Delivery queue: OutboundContextObject.DELIVERY_QUEUE_KEY

• Gateway escalation: OutboundContextObject.GATEWAY_ESCALATION_KEY

• Mobile originated: OutboundContextObject.MOBILE_ORIGINATED_KEY

218


• Validity period: OutboundContextObject.VALIDITY_PERIOD_KEY

Other information can be retrieved from an instance of OutboundContextObject:

• Profile name – the name of the associated outbound profile

outboundContextObject. getOutboundProfileName();

• Message ID - unique identifier for the message being sent

outboundContextObject. getMessageId();

• Message type - valid values for SMS-API are single sms or custom

outboundContextObject. getMessageType();

Message parameters submitted to EngageOne Digital Delivery in the XML journal (or via EngageOne Digital Delivery’s Invocation API) can be retrieved from an instance of OutboundContextObject. The information is wrapped inside a value object. The following can be retrieved from the value object:

DocumentObject doc = (DocumentObject) outboundContextObj.getDocument();

• DocumentID : doc.getDocID();

• Document master ID: doc.getDocMasterID();

• Document instance ID:doc.getDocInstanceID();

• Document type ID: doc.getDocTypeId();

• Vendor ID: doc.getVendorId();

• Account number: doc.getAccNo();

• Statement date: doc.getStmtDate();

Customer parameters submitted to EngageOne Digital Delivery in the XML journal (or via EngageOne Digital Delivery’s Invocation API) can be retrieved from an instance of DocumentObject. The information is wrapped inside a value object. The following can be retrieved from the value object:

CustDataObject custData = doc.getCustDataObject();

• Customer name:

• custData.getName();

• Customer city

• custData.getCity();

• Customer phone number

• custData.getPhoneNumber();

219


The customer address is retrieved as an attribute of OutboundContextObject:

• outboundContextObj.getAttribute("document.custdata.Address")

DDS values can be retrieved from the OutboundContextObject map using keys with the following format:

document.ddsDocValues. + <value of the name attribute>

Note that the key is case-sensitive as shown in the example that follows:.

The raw contents of the input text (or message value submitted via EngageOne Digital Delivery’s Invocation API) file that contains the message to be sent can be retrieved as a StringBuffer:

outboundContextObj.getMessageBuffer();

See the sample class com.g1.emessaging.api.sample.CustomGatewayService for usage.

MessageComposer – This interface is implemented to handle the composition of the message to be sent.

Step 2 – Deploy to EngageOne Digital Delivery. These files can be packaged as a jar file and dropped in the folder core.war/WEB-INF/lib

Step 3 – Define the new beans incore.war/WEB-INF/applicationContext.xml

Example

Journal entry

<DDSDocValue name="Expiry" type="text" len="8">20090820</DDSDocValue>

Key to retrieve the value

document.ddsDocValues.Expiry

Code

(String)outboundContextObj.getAttribute("document.ddsDocValues.Expiry");

220


Step 4– Replace the property references of bean customMessageProcessorand serviceCustomMessageProcessor with the newly defined beans.

Old definition:

New definition:

serviceCustomMessageProcessor – is called when the invoking component is submitted via EngageOne Digital Delivery’s Invocation API as opposed to the polled folders and profile message type is custom.

customMessageProcessor – is called when the invoking is via EngageOne Digital Delivery’s polled folders and the profile message type is custom.

Step 5 – Start the application server in which EngageOne Digital Delivery has been deployed.

Step 6 – The custom extension classes can be invoked by either of the following scenarios:

• If the associated Outbound Profile is configured to have Single SMS Message Type, the custom extension classes are invoked through the usual outbound message process (i.e. batch or real-time).

• If the associated Outbound Profile is configured to have a Custom Message Type, the custom extension classes are invoked through the exposed RMI port configured in the property file core.war/WEB-INF/classes/RMIService.properties.

221


Sample classes

The Custom ComposerThis class implements the MessageComposer interface.The emessaging-outbound.jar needs to be imported to compile. This is responsible for the construction of the message to be sent. This method can return null for custom message types. The implementing class can set context (OutboundContext) attributes such as the message content, subject, etc. See the sample class com.g1.emessaging.api.sample.CustomGatewayComposer in the client/build/src folder.

context.setSmsSubject("Some SMS Subject");context.setTextMessage("This is a message to the custom gateway.");//Put some other attributecontext.setAttribute("attr1", "Some attribute value");return null;

The Custom ServiceThis class implements the CustomService interface. The emessaging-client-api.jar needs to be imported to compile. This is responsible for connecting to the third-party gateway and sending the message. The implementing class can extract profile information like the SMS gateway settings from the OutboundContextObject reference. See the sample class com.g1.emessaging.api.sample.CustomGatewayService in the client/build/src folder.

Invoking EngageOne Digital Delivery to Send an SMS through the SMS-API as Opposed to the Polled Folders

This section describes how an invoking class can set parameters, that are normally provided by the XML journal (DIJ) and text files, through the SMS-API. The emessaging-client-api.jar needs to be imported to compile. See sample class com.g1.emessaging.service.client.OutboundContextFileReader in the client/source folder.

The invoker needs to populate the OutboundContextObject with parameters needed by the third-party gateway.

222


The following are attributes of OutboundContextObject:OutboundContextObject outContextObj = new OutboundContextObject();

• Message ID: outContextObj.setMessageId(String messageID);

• Profile name: outContextObj.setOutboundProfileName(String profileName);

• Message text – the message content

outContextObj.setMessageBuffer(StringBuffer text);

• Message type – single sms or custom. single sms if EngageOne Digital Delivery is to send the message through the default Clickatell interface and custom if EngageOne Digital Delivery is to send the message through a custom gateway using the API described in section “Extending the SMS API to Send an Outbound Message through a Custom Gateway” on page 218

outContextObj.setMessageType(String messageType);

• Document parameters: outContextObj.setDocumentObject(DocumentObject docObj);

The following are attributes of DocumentObject:DocumentObject documentObject = new DocumentObject();

• Document ID: documentObject.setDocID(String docID);

• Document master ID: documentObject.setDocMasterID(String docMasterID);

• Document instance ID: documentObject.setDocInstanceID(String docInstID);

• Vendor ID: documentObject.setVendorId(String vendorID);

• Document type ID: documentObject.setDocTypeId(String DocTypeID);

• Account number: documentObject.setAccNo(String acctNumber);

• Statement date: documentObject.setStmtDate(String statementDate);Note that the format of statementDate is YYMMDD

• Customer data: documentObject.setCustDataObject(CustDataObject custDataObj);

• DDS values: documentObject.setDdsDocValues(List<DDSDocValueObject> ddsObjects)

DDSDocValueObject ddsObj = new DDSDocValueObject(String key, String value);

key is “document.ddsDocValues.” + <attribute name>

value is the DDS attribute value.

The following are attributes of CustDataObject:CustDataObject custDataObject = new CustDataObject();

• Name: custDataObject.setName(String name);

223


• City: custDataObject.setCity(String city);

• Phone number: custDataObject.setPhoneNumber(String phoneNumber);

• Address – this can be represented by a collection of variable address lines

custDa0taObject.setAddressObjectMap(Collection<AddressObject> addressLines)

AddessObject addObj = new AddressObj(String lineNumber, String value);

lineNumber is the order of the address line

value is the address string.

If the invoker runs externally, it can communicate with EngageOne Digital Delivery through an exposed RMI port. The exposed remote method has the following signature:

void processOutboundContext(OutboundContextObject outboundProfileObject) throws Exception;

Connection details of the RMI port to connect to are defined by the invoker.

There is a corresponding internal bean definition in EngageOne Digital Delivery exposing the RMI port.

Default RMI port is 1199. This default can be overridden in the file core.war/WEB-INF/classes/RMIService.properties

If the invoker runs internally with EngageOne Digital Delivery, it could simply inject the bean outboundContextService to call its method directly.

224


Using the SMS API to submit an Inbound Message to EngageOne Digital Delivery

EngageOne Digital Delivery receives incoming requests through an exposed RMI service

The remote method signature is as follows:void processSmsInfo(SmsInfoObject smsInfoObject) throws Exception;


Step 1 – Create the invoking classSee sample class com.g1.emessaging.service.client.InboundContextFileReader

225


Step 2 – Populate the SmsInfoObject value object with parametersTo use this object, emessaging-client-api.jar must be in the classpath. SmsInfoObject list of attributes:

Value Description

api_id Compulsory. This is issued by Clickatell when you register to use their SMS gateway service. This value tells EngageOne Digital Delivery which Inbound Profile should process the message. If you are not using Clickatell then you can make up your own value but make sure that it matches the SMS API ID that is specified in the Inbound Profile that you want to process this message.

apiMsgId Optional. If the inbound message is a status message reporting on the delivery of an outbound message then this is the unique message ID that the Clickatell gateway applied to the original outbound message. It is not used by EngageOne Digital Delivery.

cliMsgId Compulsory for delivery status messages. Not required for user originated messages. This is used by EngageOne Digital Delivery to associate a delivery status message with the original outbound message to which the status relates.

status Compulsory for delivery status messages. Not required for user originated messages. It can have any of the values listed in the Status table below.

charge Optional for delivery status messages. Not required for user originated messages. This is a way for reporting the number of credits that have been consumed for the sending of a particular outbound message. The charging information gets written to EngageOne Digital Delivery’s Outbound Message table and can be used for charging purposes.

from Compulsory for all messages. The MSISDN (mobile number formatted to the MSISDN format) that originated the message. In the case of a delivery status message this would be set to the source (a.k.a. from) address of the outbound message that is being reported on.

to Compulsory for all messages. The MSISDN (mobile number formatted to the MSISDN format) that the message was sent to. In the case of a delivery status message this would be set to the to address of the outbound message that is being reported on.

timestamp A date and time stamp format, e.g. 2009-07-17 12:32:10.

226


Possible “status” values for inbound delivery status messages:

text Compulsory for user originated messages. Not required for delivery status messages. This is the message content that the end user sent in a SMS.

udh Allows you to set your own message types. Do not use if you set the message type parameter. Not used by EngageOne Digital Delivery.

charset Optional. The character set encoding of the above text

value. Defaults to UTF-8.

Value Description Detail

001 Message unknown The message ID is incorrect or reporting is delayed.

002 Message queued The message could not be delivered and has been queued for attempted redelivery.

003 Delivered to gateway Delivered to the upstream gateway or network (delivered to the recipient).

004 Received by recipient Confirmation of receipt on the handset of the recipient.

005 Error with message There was an error with the message, probably caused by the content of the message itself.

006 User cancelled message delivery

The message was terminated by an internal mechanism.

007 Error delivering message An error occurred delivering the message to the handset.

008 OK Message received by gateway.

009 Routing error The routing gateway or network has had an error routing the message.

010 Message expired Message has expired at the network due to the handset being off, or out of reach.

011 Message queued Message has been queued at the gateway for delivery at a later time (delayed delivery).

Value Description

227


Step 3 – Invoke the exposed remote method by EngageOne Digital Delivery.

This should be configured in the invoking application. For example:

The processSmsInfo() is the remote method exposed by EngageOne Digital Delivery to process inbound SMS calls. There is no need to extend anything inside EngageOne Digital Delivery to override the default implementation of handling inbound messages.

012 Out of credit The message cannot be delivered due to a lack of funds in your account. Please re-purchase credits.

Value Description Detail

228


The SMS API Test Harness and Sample Code

Introduction

The SMS API Test Harness and sample code can be found under the client folder of the installation directory:

It has the following contents:

build – this folder contains a sample Ant application for the sample classes of the SMS API. It contains two sample classes:

• CustomGatewayComposer.java – a sample message composer

• CustomGatewayService.java – a sample message service/sender.

javadoc – this folder contains javadoc files for the classes of the SMS API and the interfaces that need to be extended.

source – this folder contains the source files for the classes of the sample SMS API application.

thirdparty.bat and thirdpartyCustom.bat start the sample third-party SMS gateway simulator for testing purposes. thirdpartyCustom.bat allows overriding default parameters:

• fileacceptor.directory – the directory location of the output file that simulates a message being sent.

229


• fileacceptor.socket.port – the port the sample third-party gateway listens to.

clientoutbound.bat and clientoutboundCustom.bat simulate the invocation of the SMS API outbound process. This is an alternative to invoking outbound messages through the writing of XML journal and text files to the polled folders. clientoutbound.Custom.bat allows overriding default parameters:

• outboundcontext.directory – the directory location of the input file

• emessaging.rmi.port – the EngageOne Digital Delivery RMI port (default is 1199)

• emessaging.rmi.server – the EngageOne Digital Delivery RMI location (default is localhost)

clientinbound.bat and clientinboundCustom.bat simulate the injection of an SMS message into the SMS API inbound process. clientinboundCustom.bat allows overriding default parameters:

• inboundcontext.directory – the directory location of the input file

• emessaging.rmi.port – the EngageOne Digital Delivery RMI port (default is 1199)

• emessaging.rmi.server – the EngageOne Digital Delivery RMI location (default is localhost)

emessaging-client-jar-with-dependencies.jar is the JAR file required to run the above mentioned batch files.

Sending an Outbound Message Using the Sample third-party SMS Gateway Simulator

Legend:

(1) – e-Messaging

(2) – 3rd Party Gateway Simulator

230



Step 1 – Configure EngageOne Digital Delivery to point to the third-party SMS gateway simulator by specifying its properties in core.war/WEB-INF/CustomServiceImpl.properties.

• The socket server is where the third-party gateway is running

• The socket port is where the third-party gateway is listening

Step 2 – For the third-party SMS gateway simulator, create a property file (e.g. mygateway.properties) specifying:

• The location for the output to be written to.

• The third-party SMS gateway simulator will write the outbound message content to files in this folder to simulate a message being sent.

• Socket settings

• The socket port should match the port defined in step 1 above

Example:

Step 3 – For the third-party SMS gateway simulator, update thirdpartyCustom.bat

Set the parameter fileacceptor.props to point to the file created in the last step (e.g. mygateway.properties)


Step 5 – Start the third-party SMS gateway simulator by running thirdpartyCustom.bat.

Step 6 – Submit an XML journal and text file of the required format to the polled folders of the Outbound Profile that is configured to send the message.

For the required formats see the “DIJ” on page 24 and “Making Designer and Generate content available to Digital Delivery” on page 36 of this guide. Alternatively invoke the sending of an SMS using the SMS-API described in section “EngageOne Digital DeliveryInvoking EngageOne Digital Delivery to Send an Outbound SMS Message using the SMS-API Invocation Sample Application as an Alternative to the Polled Folders” on page 235.

Step 7 – check the results as follows:

• Expect a new file to get written in the folder specified in fileacceptor.directory setting in mygateway.properties

231


• The above mentioned file will contain the details of the message that was submitted to EngageOne Digital Delivery for sending

Receiving an Inbound Message Using the Sample Inbound Message Invoker Application


Step 1 – Configure the EngageOne Digital Delivery RMI port where the Sample Inbound Message Invoker Application will connect to in core.war/WEB-INF/classes/RMIService.properties

Example:emessaging.rmi.port=1199

Step 2 – Create an input file for the Sample Inbound Message Invoker Application with the following contents:

Example to simulate a delivery status inbound message:api_id=3063989apiMsgId=23453645cliMsgId=12345status=004charge=1from=45698123123to=31648088566timestamp=2009-0707 07:45:23

Example to simulate a user originated inbound message:api_id=3063989from=31648088566to=45698123123timestamp=2009-0707 07:45:23text=This is an user originated inbound messageudh=charset=UTF-8

Value Description

api_id Compulsory. This is issued by Clickatell when you register to use their SMS gateway service. This value tells EngageOne Digital Delivery which Inbound Profile should process the message. If you are not using Clickatell then you can make up your own value but make sure that it matches the SMS API ID that is specified in the Inbound Profile that you want to process this message.

232


Refer to page 227 for Possible status values for inbound delivery status messages.

apiMsgId Optional. If the inbound message is a status message reporting on the delivery of an outbound message then this is the unique message ID that the Clickatell gateway applied to the original outbound message. It is not used by EngageOne Digital Delivery.

cliMsgId Compulsory for delivery status messages. Not required for user originated messages. This is used by EngageOne Digital Delivery to associate a delivery status message with the original outbound message to which the status relates.

status Compulsory for delivery status messages. Not required for user originated messages. It can have any of the values listed in the Status table below.

charge Optional for delivery status messages. Not required for user originated messages. This is a way for reporting the number of credits that have been consumed for the sending of a particular outbound message. The charging information gets written to EngageOne Digital Delivery’s Outbound Message table and can be used for charging purposes.

from Compulsory for all messages. The MSISDN (mobile number formatted to the MSISDN format) that originated the message. In the case of a delivery status message this would be set to the source (a.k.a. from) address of the outbound message that is being reported on.

to Compulsory for all messages. The MSISDN (mobile number formatted to the MSISDN format) that the message was sent to. In the case of a delivery status message this would be set to the to address of the outbound message that is being reported on.

timestamp A date and time stamp format, e.g. 2009-07-17 12:32:10.

text Compulsory for user originated messages. Not required for delivery status messages. This is the message content that the end user sent in a SMS.

udh Allows you to set your own message types. Do not use if you set the message type parameter. Not used by EngageOne Digital Delivery.

charset Optional. The character set encoding of the above text value. Defaults to UTF-8.

Value Description

233


Step 3 – Create a property file which will contain the location of the input file for the Sample Inbound Message Invoker Application and the RMI settings for EngageOne Digital Delivery(e.g. myclient.properties).

Example:

• The inboundcontext.directory should point to the location of the input file described in step 2 above

• The RMI details are optional and only used to override the default (localhost/1199)


Step 5 – Update clientinboundCustom.bat and set the parameter inboundcontext.props to point to the file created in step above (e.g. myclient.properties).

Step 6 – Start the Sample Inbound Message Invoker Application by executing clientinboundCustom.bat.

Step 7 – Check in EngageOne Digital Delivery to verify that the inbound message has been received and processed. For example check if the message can be seen in the workflow screens for the Inbound Profile that processed the message.

Step 8 – The input file to Sample Inbound Message Invoker Application will be renamed as “.processed”.

234


EngageOne Digital DeliveryInvoking EngageOne Digital Delivery to Send an Outbound SMS Message using the SMS-API Invocation Sample Application as an Alternative to the Polled Folders


Step 1 – Configure the EngageOne Digital Delivery RMI port where the SMS (API) Invocation Sample Application will connect to in core.war/WEB-INF/classes/RMIService.properties

Example:

Step 2 – For the SMS (API) Invocation Sample Application, create a property file which will contain the location of the input file and the RMI settings for EngageOne Digital Delivery (e.g. myclient.properties).

Example:

• The RMI port should correspond to the setting in step 1 above.

• The RMI server is where EngageOne Digital Delivery is running.

• The input file is any text file which contains properties for the message that is to be sent. These properties are equivalent to the values provided in input XML journal and text files when the polled folders are used to submit content.

Legend:

(1) – e-Messaging

(3) – SMS (API) Invocation Sample Application

235


Example:lineseparator=\nprofilename=SMSmessageType=custommessageId=someUniqueIdmessage=3rd party through APIdocument.DocID=1document.DocMasterID=6CE27A956F47AB0E479E7A553B6797C4document.DocInstanceID=AAJ8BC5A30FE34CAC73901D5E9B4276document.VendorId=165dd5f6c05843d38fc1a8fa7dee5c02document.DocTypeId=12AA73CF840746518855826DF59250B3document.AccNo=PB485document.StmtDate=20081028document.custdata.Name=Jean Tsengdocument.custdata.City=nulldocument.custdata.PhoneNumber=nulldocument.custdata.Address=1 Market Plazadocument.ddsDocValues.MSISDN=31648088576document.ddsDocValues.Email=caparisonuser@caparison.orgdocument.ddsDocValues.Subject=3rd party through API

236


Value Description

profilename The name of the Outbound Profile in EngageOne Digital Delivery that is to send the message.

messageType This should be the same as the Message Type specified in the Outbound Profile that will be sending the messages. Possible values are:

• Single SMS

• Custom

Use Single SMS if the message is to be sent through EngageOne Digital Delivery’s default interface with Clickatell.

Use custom if the message is to be sent through a third-party SMS gateway using bespoke code that connects the EngageOne Digital Delivery SMS-API described in “Extending the SMS API to Send an Outbound Message through a Custom Gateway” on page 218.

messageId This is an optional value. If it is omitted then EngageOne Digital Delivery will generate its own unique ID for every message it sends.

message The actual content of the message that needs to be sent

In the case of the message being sent through EngageOne Digital Delivery’s default interface with Clickatell, this should be formatted similar to the text file that is submitted to EngageOne Digital Delivery’s polled folders. For example:Message for:31648088576\nunicode:0\ntext:message content

document.DocID This is the equivalent to the docID attribute of the document element in the DIJ. It may always be set to 1.

document.DocMasterID This is the equivalent to the docMasterID attribute of the document element in the DIJ. It should be unique for each message sent.

237


document.DocInstanceID This is the equivalent to the docInstanceID attribute of the document element in the DIJ. It must be unique for each message sent. No message is sent if the message contains a docInstanceID that has been previously sent.

document.VendorId This is the equivalent to the VendorId element in the DIJ. It should be a 32 character HEX value but is not used by EngageOne Digital Delivery.

document.DocTypeId This is the equivalent to the DocTypeId element in the DIJ. It should be a 32 character HEX value but is not used by EngageOne Digital Delivery.

document.AccNo This is the equivalent to the AccNo element in the DIJ. It should be a unique customer identifier. Its value is populated into the account field of the index journal that EngageOne Digital Delivery prepares for Vault to archive messages.

document.StmtDate This is the equivalent to the StmtDate element in the DIJ. It should specify message date in the format YYYYMMDD.

document.custdata.Name This is the equivalent to the Name element in the DIJ. Its value is populated into the Name field of the index journal that EngageOne Digital Delivery prepares for Vault.

document.custdata.City This is the equivalent to the City element in the DIJ. Its value is populated into the Address field of the index journal that EngageOne Digital Delivery prepares for Vault.

document.custdata.PhoneNumber

This is the equivalent to the Phone element in the DIJ. Is not used by EngageOne Digital Delivery.

document.custdata.Address This is the equivalent to the Addr line=”1” element in the DIJ. Its value is populated into the Address field of the index journal that EngageOne Digital Delivery prepares for Vault.

document.ddsDocValues.MSISDN

This is the mobile number formatted according to the MSISDN standard. See the definition of MSISDN in the “Custom DIJ fields required for Digital Delivery” on page 24. It equates to the custom MSISDN DIJ field.

Value Description

238


Step 3 – For the SMS (API) Invocation Sample Application, update clientoutboundCustom.bat and set the parameter outboundcontext.props to point to the file created in step 2 above (e.g. myclient.properties).

Step 4 – Ensure you have an input file at the correct location for the SMS (API) Invocation Sample Application. See steps 2 and 3 above.

Step 5 – Trigger the SMS (API) Invocation Sample Application by executing clientoutboundCustom.bat.

Step 6 – The input file to the SMS (API) Invocation Sample Application will be renamed as “.processed”.

document.ddsDocValues.Email This is the email address of the customer. It is optional for SMS messages. It equates to the custom email DIJ field and is populated into the email field of the index journal that EngageOne Digital Delivery prepares for Vault.

document.ddsDocValues.Subject

This is optional for SMS messages. It is, however, recommended to set this to the same value as message text specified above. This allows for the message text to also appear in the Sent (Individual) reports provided by EngageOne Digital Delivery.

Value Description

239

Appendix E– Security Configurations for WebSphere Application Server

This section explains how to configure your WebSphere application servers to enhance the Web security.

Set “HttpOnly” and “secure” flags when setting session identifiers

1. In the WebSphere application server, navigate to the following path:

Servers > Server Types > Websphere Application Servers > server1 > Container Settings > Web container Settings > Web container > Custom properties

2. Add the following property-value:

com.ibm.ws.webcontainer.HTTPOnlyCookies = *

3. Navigate to the following path and select the Restrict cookies to HTTPS sessions check box.

Applications > Application Types > Websphere enterprise Applications > EODigitalDelivery_war > Web Module Properties > Session Management > Enable Cookies

4. Navigate to the following path and select the Restrict cookies to HTTPS sessions check box.

Servers > Server Types > Websphere Application Servers > server1 > Container Settings > Session management > Enable Cookies

240

Appendix E– Security Configurations for WebSphere Application Server

Set session expiry (logout) duration

To set the timeout duration of T in minutes, specify a value less than T. For example, to set the timeout of 15 minutes, set the value equal to 10. Complete the following steps:

1. Navigate to the following path and set the appropriate timeout duration in minutes:

Servers > Server Types > Websphere Application Servers > server1 > Container Settings > Session management

2. Navigate to the following path and set the appropriate timeout duration in minutes. Also, select the Override session management check box.

Applications > Application Types > Websphere enterprise Applications > EODigitalDelivery_war > Web Module Properties > Session Management

3. In the EngageOne Digital Delivery War file, go to \WEB-INF\web.xml and specify the appropriate value (say 10 minutes) as shown below:

<session-config>

<session-timeout>10</session-timeout>

</session-config>

4. In the administrative console:

i. Click Security > Global security.

ii. Under Custom properties, click New.

iii. In the Name field, enter om.ibm.ws.security.web.logoutOnHTTPSessionExpire.

iv. In the Value field, enter true.

v. Navigate to Application servers > server1 > Session management > Custom properties Enterprise Applications > EODigitalDelivery_war > Session management > Custom properties and set the following properties:

Custom Property name - timeout.resume.session

Custom Property value - false

241

Appendix F – Configuring AWS Bounces for SES services

This section provides instructions to enable the bounces for sending emails using the AWS SES service. As a pre-requisite, you should have the privileges to sign in the AWS console. This is one time configuration for AWS account and you do not need to apply these changes every time you deploy your application binaries.

Verify Email address

As a pre-requisite, ensure that you have verified the From email id for sending emails using the AWS SES Account. You also have to specify this email ID as sender mail id in Digital Delivery.

To verify the email Id in AWS:

1. Sign in the AWS management console.

2. Open the SES service.

3. On the left panel, click the Email Addresses link.

4. Specify the Email address that you want to verify and click Verify This Email Address button. The specified address will receive a verification email.

242


5. In the email, click the verification link. The email will be verified by AWS. On successful verification, the status will change to verified. Once verified, email address is ready to configure the bounces.

Create SQS-Queue

You can use the AWS SQS services to create the queues. You need to create the following queues:

• ses-bounces-queue: to send notification for bounces

• ses-complaints-queue: to send notification for complaints

• ses-reply-queue: to send notification for reply


2. Open the SQS service.

3. Click Create New Queue.

4. Specify the queue attributes and click Create Queue.

243


5. Once the queue is created, this can be seen under Queue list as shown below.

6. Similarly, create other queues mentioned above.

Create SNS-Topic

You can use AWS SNS service to notify the bounces and reply. To use this service, you have to create the SNS Topics, which are linked to SQS Queues you have created in previous section. So, if any reply and bounces occur, then these SNS Topics will add data to SQS Queues. You need to create the following AWS SNS Topics in the required regions (AWS SES Account):

• ses-bounces-topic: to notify bounces

• ses-complaints-topic: to notify complaints

• ses-reply-topic: to notify reply


2. Open the SNS service.

3. Click Create topic link.

4. Specify the Topic name and Display name and click Create Topic. The newly created topic will appear under the topic list as shown below.

244


5. Similarly, you can create the other required topics.

Subscribe the SQS queues

You need to subscribe the SQS Queues with the SNS Topics. In other words, you need to attach SNS topics with SQS queues.


2. On the left panel, click the Topics link to display the list of created topics.

3. Select the topic for which you want to create the subscription.

4. Under Subscriptions, click Create Subscription button.

5. Provide the Protocol and Endpoint.

• Protocol - Amazon SQS (for SQS Queues)

• Endpoint - ARN of the queue. To get the ARN, go to SQS service and select the queue that you want to subscribe. From the Detail tab, you can copy the ARN and specify here.

6. Now, the SQS Queue is linked to SNS Topic. You can see the newly added subscription as shown below.

245


7. Complete the above steps for all the queues.

SQS-Queue permission settings

You need to provide permission to different SNS topics for sending a message in different queues.


2. Open the SQS services.

3. Select a queue say, ses-bounces-queue.

4. On the Permissions tab, click Add a Permission.

5. Provide permission to ses-bounces-topic ONLY for sending message to this queue.

246


6. Click Add Conditions link and specify the attributes as shown above. In the Value field, you have to specify ARN of the corresponding Topic.

7. Click the Save Changes button.

8. Complete the above steps to provide permission to all other queues.

SES bounce notification settings

You need to provide permission to different SNS topics for sending a message in different queues.


2. Open the SES services.

3. On the left panel, click the Email addresses link.

4. Select the From email address that you created and verified in the previous section.

5. Click the Notifications link.

247


6. Click the Edit Configurations button.

7. Now, select the corresponding Topic for Bounce and Complaints as shown below. Please ensure that the Email Feedback Forwarding is Disabled. Click the Save Configuration button.

Digital Delivery settings for bounce

After completing the above steps, you need to do some settings to allow Digital Delivery to listen all bounces. Make sure you have specified the following:

248


1. In the Outbound Profile, add the verified mail id as shown below:

2. While creating the inbound profile, select the gateway option, AWS_SNS_SQS as shown below.

3. In inbound profile, provide the queue name that you have created in previous steps. For example, if you have created with name, ses-bounces-queue, then specify as shown below.

249

Appendix G – Custom Email Support

You have to configure custom email gateway-spring definition in the …/WEB-INF/applicationContext.xml.

<bean id="serviceCustomEmailMessageProcessor" parent="customEmailMessageProcessor" class="com.g1.emessaging.outbound.processor.ServiceCustomEmailMessageProcessor"><property name="outboundMessageMgr" ref="outboundMessageManager" /> <property name="outProfileMgr" ref="outboundProfileManager" /><property name="workflowItemMgr" ref="workflowItemManager" /><property name="workflowHistoryMgr" ref="workflowHistoryManager" /><property name="sendJobMgr" ref="sendJobManager" /><property name="transferOutboundToArchive" ref="transferOutboundToArchive" /><property name="logManager" ref="logManager" /><property name="messageSenderFactory" ref="serviceMessageSenderFactory" /><property name="textContentManager" ref="textContentManager" /><property name="htmlContentManager" ref="htmlContentManager" /><property name="attachmentManager" ref="attachmentManager" /><property name="outboundSettingsBuilder" ref="outboundSettingsBuilder" /><property name="messageComposer" ref="compoundMessageComposer"/><property name="customService" ref="customService" /> </bean>

You can change email message composer to any of (compoundMessageComposer for multipart/alternative, htmlMessageComposer for html email and textMessageComposer for Text email) Or customMessageComposer for any other user defined/preference type.

You need to select the Custom Email check box on the Vendor Environment page as shown below.

250


Following is sample Gateway configuration for Custom Email.

Following is outbound profile configurations using Custom Email gateway and message type:

251


252

Appendix H – TLS version & Cipher Suite configuration

TLS version and Cipher suite configuration is supported for the protocols/connectivity below:

SMTP, IMAP, POP3, SMPP and MS SQL DB connectivity.

This feature is either configurable through certain properties files or, using system properties while starting the application server.

SMTP Email

Property file – outboundProcessor.properties

# Examples of Cipher suites for SSL/TLS communication

#TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256 TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256

# TLS_DHE_RSA_WITH_AES_128_CBC_SHA256 TLS_DHE_DSS_WITH_AES_128_CBC_SHA256 TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA

#TLS_RSA_WITH_AES_128_CBC_SHA TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA

# To provide the configuration/setting for Cipher Suite (SSL/TLS enabled) to be used for outbound mail SMTP,

# applicable for all outbound profiles using SMTP gateways(if SSL enabled

# on gateway page) for sending mails.

# Multiple Cipher Suite values can be given with white space separated [TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA]

mail.smtp.ssl.tls.cipherSuite=TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA

# To provide the configuration/setting for Cipher Suite to be used for outbound mail SMTP,

# applicable for all outbound profiles using SMTP gateways (if SSL NOT enabled on

#gateway page, but starttls property is set to true) for sending mails.

253



mail.smtp.starttls.tls.cipherSuite=TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA

IMAP Email

Property file – inbound-observer.properties

# To provide the configuration/setting for TLS version to be used for inbound mail IMAP,

# applicable for all inbound profiles using IMAP gateways(if SSL enabled

# on gateway page) for reading mails.

# Multiple TLS version values can be given with white space separated [TLSv1 TLSv1.1 TLSv1.2]

mail.imap.ssl.tls.version=TLSv1 TLSv1.1 TLSv1.2

# To provide the configuration/setting for Cipher Suite(SSL/TLS enabled) to be used for inbound mail IMAP,

# applicable for all inbound profiles using IMAP gateways(if SSL enabled


# Multiple Cipher Suite values can be given with white space separated[TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA]

mail.imap.ssl.tls.cipherSuite=TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA

254


POP3 Email

Property file – inbound-observer.properties

# To provide the configuration/setting for TLS version to be used for inbound mail POP3,

# applicable for all inbound profiles using POP3 gateways(if SSL enabled


# Multiple TLS version values can be given with white space separated[TLSv1 TLSv1.1 TLSv1.2]

mail.pop3.ssl.tls.version=TLSv1 TLSv1.1 TLSv1.2

# To provide the configuration/setting for Cipher Suite (SSL/TLS enabled) to be used for inbound mail POP3,

# applicable for all inbound profiles using POP3 gateways(if SSL enabled



mail.pop3.ssl.tls.cipherSuite=TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA

SMPP SMS

Property file – outboundProcessor.properties

# To provide the configuration/setting for Cipher Suite(SSL/TLS enabled) to be used for outbound SMPP SMS,# applicable for all outbound profiles using SMPP gateways(if SSL enabled# on gateway page) for sending SMS.# Multiple Cipher Suite values can be given with white space separated [TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA]

sms.smpp.ssl.tls.cipherSuite=TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA

# To provide the configuration/setting for TLS version to be used for outbound SMPP SMS,# applicable for all outbound profiles using SMPP gateways(if SSL enabled # on gateway page) for sending mails.# Multiple TLS version values can be given with white space separated [TLSv1 TLSv1.1 TLSv1.2]

sms.smpp.ssl.tls.version=TLSv1 TLSv1.1 TLSv1.2

255


MS SQL DB

JDTS jar for MS SQL is modified to support Cypher & TLS version enforcement for MS SQL Server.

Below system parameters to be added into catalina.bat (for Tomcat) and configure the cypher suite and TLS version as per requirement. For other application servers (WAS, Weblogic, JBoss) these system properties can be configured through admin console or supported batch file.

set JAVA_OPTS=%JAVA_OPTS% -Ddb.mssql.ssl.tls.cipherSuite=TLS_RSA_WITH_AES_128_CBC_SHA256 -Ddb.mssql.ssl.tls.version=”TLSv1.1 TLSv1.2 TLSv1”

Example jdbc.properties file contents with SSL attributes:

jdbc.driverClassName=net.sourceforge.jtds.jdbc.Driverjdbc.url=jdbc:jtds:sqlserver://CCM64-W12-SQL12.pbi.global.pvt:1433/eMessaging_SSL;ssl=require;TrustServerCertificate=True;[email protected]=org.hibernate.dialect.SQLServerDialect

256

Appendix I – Configuring APNS AND AWS APNS Gateways

APNS Gateway

Apple Push Notification Service (APNS) is a service that enables you to send push notification messages to iOS and OS X applications. We have integrated APNS with Digital Delivery.

Now with the Digital Delivery, you can send push notification to iOS and OS X applications using APNS. For this, you will need to create an APNS-gateway, as shown below.

Certificate File UploadWhile creating the gateways, a certificate file is required. Certificate files have an file extension of .p12 and can be created through your Apple iOS Developer account as per steps given in the link: https://calvium.com/how-to-make-a-p12-file/

You need to upload this certificate file into Digital Delivery.

257

https://calvium.com/how-to-make-a-p12-file/

https://calvium.com/how-to-make-a-p12-file/


Duplicate APNS Gateways ValidationAPNS gateway validation is performed based on the unique combination of TYPE, NAME and APP NAME. If these three fields are repeated, then you will not be allowed to create a gateway; a duplicate gateways error message will be thrown. As shown below:

AWS APNS GatewayThis gateway will use Amazon SNS API to send a push notification message to your iOS application. Internally Amazon SNS uses APNS for sending notifications to iOS devices. Before creating AWS APNS gateway in Digital Delivery you will need to:

1. Obtain the private key and certificate from AWS SNS,

2. Create the .key file from the information provided and upload it when creating the gateway in Digital Delivery.

Obtaining a private key and certificate from AWS:-

1. Login into AWS account

2. Go to SNS -> Select Applications

258


3. Click on Create platform application button as shown on the screen below:

259


4. The Create platform application screen is presented as shown below. Select Push notification platform and upload .p12 file, which is generated using steps shown in above APNS discussion. Provide necessary details and press Load credentials from file button. The Certificate and Private key content is presented in their corresponding fields as below:

5. Create a .key file (e.g. aws_apns_mpush.key) in the format shown below. Copy private key and certificate content from above screen and paste it into your key file.

cert:-----BEGIN CERTIFICATE-----

MIIFnzCCBIegAwIBAgIIfWuiBbc4zEgwDQYJKoZIhvcNAQEFBQAwgZYxCzAJBgNVBAYTAlVTMRMwEQYDVQQKDApBcHBsZSBJbmMuMSwwKgYDVQQLDCNBcHBsZSBXb3JsZHdpZGUgRGV2ZWxvcGVyIFJlbGF0aW9uczFEMEIGA1UEAww7QXBwbGUgV29ybGR3aWRlIERldmVsb3BlciBSZWxhdGlvbnMgQ2VydGlmaWNhdGlvbiBBdXRob3JpdHkwHhcNMTcwOTE0MDgzMTU4WhcNMTgwOTE0MDgzMTU4WjCBnjEtMCsGCgmSJomT8ixkAQEMHWNvbS5wYi5tcHVzaC5ub3RpZmljYXRpb24uYXBwMUswSQYDVQQDDEJBcHBsZSBEZXZlbG9wbWVudCBJT1MgUHVzaCBTZXJ2aWNlczogY29tLnBiLm1wdXNoLm5vdGlmaWNhdGlvbi5hcHAxEzARBgNVBAsMCjRONzdFNVdOS1MxCzAJBgNVBAYTAlVTMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA6s94jErxJxmmSGBYh+A6Y6ZME++JOdmEmpqDHaeRxsaG4lC5DI85GlBjHLqL6RlxFIfncf74uO/Y/lIYgnQa8VF4j8tQKuqXfJYA61pxQrrS4qhzFDzxHNaAMKNg5LPNGBUFo1O7ZmynOw8kLTHdPIqOh6hp6jzhz4sV4szhGXzr0at2L10+3TEqwQm5/8Wdn1dsFJV7kX6z5z8GwjadIPtGYagItHua7ppj/IAf0l6+3XhQleXfdlPhVIbcffEEt6NmAx7vouG7NMLW8SLpG8ci35x8u21tC9tZgUyHe4fStvVjdFytZ5QK+UoTQXc8avSPwKU8t5k/ABcQfc+GtwIDAQABo4IB5TCCAeEwHQYDVR0OBBYEFDWRNWG+V37SSthMDr35UgZTXkYlMAkGA1UdEwQCMAAwHwYDVR0jBBgwFoAUiCcXCam2GGCL7Ou69kdZxVJUo7cwggEPBgNVHSAEggEGMIIBAjCB/wYJKoZIhvdjZAUBMIHxMIHDBggrBgEFBQcCAjCBtgyBs1JlbGlhbmNlIG9uIHRoaXMgY2VydGlmaWNhdGUgYnkgYW55IHBhcnR5IGFzc3VtZXMgYWNjZXB0YW5jZSBvZiB0aGUgdGhlbiBhcHBsaWNhYmxlIHN0YW5kYXJkIHRlcm1zIGFuZCBjb25kaXRpb25zIG9mIHVzZSwgY2VydGlmaWNhdGUgcG9saWN5IGFuZC

260


BjZXJ0aWZpY2F0aW9uIHByYWN0aWNlIHN0YXRlbWVudHMuMCkGCCsGAQUFBwIBFh1odHRwOi8vd3d3LmFwcGxlLmNvbS9hcHBsZWNhLzBNBgNVHR8ERjBEMEKgQKA+hjxodHRwOi8vZGV2ZWxvcGVyLmFwcGxlLmNvbS9jZXJ0aWZpY2F0aW9uYXV0aG9yaXR5L3d3ZHJjYS5jcmwwCwYDVR0PBAQDAgeAMBMGA1UdJQQMMAoGCCsGAQUFBwMCMBAGCiqGSIb3Y2QGAwEEAgUAMA0GCSqGSIb3DQEBBQUAA4IBAQDF0ki34MujGvowUbT+0NlHrBUuAOy28A1llSYTLDK6EGLv49C60hGV8MaVol8hAV1Dh93XcvQOKvipIsspkmYvemfFxPlfaFFhHqzSFT5fa1UR4jfLhyEJZaFGKjufyqIJofdI8y9Fkz70t0jzvC7Jx/arD5BfagfsIV6TLj72RCqmByHWwXu5QpBDDOb44M6A6FAcSMq5CQTnCEjsJK3UcF2aYQp7K6OyW6nXzJ8h3pZeUjR6pTsW1w6l/gQLOMiSPhVe+cZY8XPOos8uVNOpB7pgvbMrAGi04zg3zE6EL7E6FWh01p7X78e4x1rVBwe07YH3PzOgWhn0Q09MF8ls

-----END CERTIFICATE-----

key:-----BEGIN PRIVATE KEY-----

MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQDqz3iMSvEnGaZIYFiH4DpjpkwT74k52YSamoMdp5HGxobiULkMjzkaUGMcuovpGXEUh+dx/vi479j+UhiCdBrxUXiPy1Aq6pd8lgDrWnFCutLiqHMUPPEc1oAwo2Dks80YFQWjU7tmbKc7DyQtMd08io6HqGnqPOHPixXizOEZfOvRq3YvXT7dMSrBCbn/xZ2fV2wUlXuRfrPnPwbCNp0g+0ZhqAi0e5rummP8gB/SXr7deFCV5d92U+FUhtx98QS3o2YDHu+i4bs0wtbxIukbxyLfnHy7bW0L21mBTId7h9K29WN0XK1nlAr5ShNBdzxq9I/ApTy3mT8AFxB9z4a3AgMBAAECggEANQpwnKBBISf2G9tHpEnOZrwl60rsoJi2D4Zfn88+arxls7GwW1nu+Da4bMDm4dzRYmXgrit+W6gySCCbULyRaXmR1kmC7m7XkVkBFCj19LDm+jQ66pNpk64Qfuwo8wB6j7oP7/j2GAjrLbgZ3+unoglacOJmKndeOtecNgM5xdu3VMY4uTdslv2IRGUuUro61nwfAGq4AUu/GQhAUw0bwtK3P4JjbaWPho+pPfy8i5JP5Ui5d6twjXLTZ682/9M5s8S4V+WOI3euDWdxeLgEyc63ty8b5Hc6BSWQJwkMczT2JL8LI+BQcoS2UYUPW2HGeRcGLjSEtRNFtkmcCWOz4QKBgQD2TV0rlFtjCNWk4DLtNf0XXABPBzMSUBXgiZfq4Saj1sb5FnoQ9MMk2EhWX1Q997Mjk5sQPb/9gJvvDU9VDUk1TxyvjZFzF4mtJvJQgPF1vMu8hlClApKfolSfScAgDoRrgpDS+F2tU4zhpTIUDbyQpHZmHdm2HkrpKhmgJRWr7QKBgQD0DkYsLiFehR7fjx+onRbvzguNuMJX5Lmt3Kk6z3fjbuQY9lkmBfsNXGd/2ugNJksfevbvaHTfG8XncbYiQp5gaDUopiWOpjhHhBH62XHkOcbfgKyyhAYPZPfeLOAb9Nb46tgUwcxuWy8yWeow29zyjnBXVhuBc+KWsNtvml+QswKBgQCdI3aR2zEC2hwT+MYE+TDjulqoENvQjy+l9aLqw4K3fMutF14Be2cVFrfwAxnn/yRXSlDf58WZonfZ6A/5H2TZkgOnLRbi6t13jyWBnwJuL2l8eeTxodaR6is7BP6CdUCepspnDvYVIvz66T4t9SWc0pCHTfwcaO86GxYGSiKtcQKBgDnyvbS1y1SPFTKN4D1/9zc/XDztVq/Z7kCa+U+ufU/yP5SxwZ8momKcwzJ3fsvIgOPbpZBY5A8poAcBV/awjLxlYeHh+V7ylsBcWoyOXt2K3m6pNdg5Qtsa5UPKsffRXc3CrUXYcjrtyboR4WpyefbZ3VDPcD5/jpirK59HL1PDAoGAReVVYy2onyI23l63mS/EyUvHbkaiccB9BZupVC1np2oEDd7QM/LjiOY2NWbS68mGYVmZ9iXDLmDJ/3UfSYovQ/XB/ZgEWi58l/N5LX8cWg6knmjHAlNXovnWQ+Jaw51rx+FrY6TaCgNIsJewlOnE1+fuZqQkFrHdAFGAXhIszLA=

-----END PRIVATE KEY-----

261


6. Now create AWS APNS gateway in Digital Delivery as below:

Certificate File UploadWhile creating the AWS APNS gateway, you need to upload .key file as created in the above step.

262


Duplicate AWS APNS Gateways ValidationAWS APNS gateway validation based on the unique combination of TYPE, REGION and APP NAME. If these three fields are repeated, then you will not be allowed to create a gateway; a duplicate gateways error message will be thrown. As shown below:

Profile CreationYou need to create corresponding outbound profiles (as per requirement) using gateways created in “AWS APNS Gateway”.

263

Index
A
ApplicationAlert.properties 96ApplicationResources.properties 97architecture 16authentication 124auto-population 125

B

browserconfiguration 129Microsoft Internet Explorer 130Mozilla Firefox 129

C

ClickatellMessageComposer.properties 98clustering 110content converter 19, 21control

data flow 55local 56

custom.properties 98

D

data flow 55, 56plan 62

database.ini 47Designer 23DIJ 24, 36

standard fields 24DIJ fields

account number 24address 24AttachName1 26AttachName2 27AttachName3 27AttachName4 27e-mail 24errors-to 30expire 25from 29MSISDN 25name 24other 31publication ID 24reply-to 29return-path 29statement date 24subject 25WorkflowItem_Id 28WorkflowStage_Id 28

Document Interchange Journal, see DIJ

E

e-mail 20, 21Ems.properties 99encryptionKey.properties 99engageone.properties 100Executor.properties 101

F

failover 110clustering 110

folder permissions 48

G

Generate 57, 63generic e-Mail

archive 205

H

header informationadd 64, 65modify 64

HTML 38special considerations 32

http//www.oracle.com/technetwork/java/javase/

downloads/jce-7-download-432124.html 74

I

inbound 20content 42message processing 20

inbound-observer.properties 76initialDirContextFactory 122Install.properties 101

J

Jconsoleconfiguration 202

jdbc.properties 102journal file 48

K

keys.properties 107

L

language

264

Index M

resource bundles 128LDAP

Configuration 121configuration 121connection settings 122search settings 122

load balancing 110local control 56log4j.xml 102

M

mail servers 19, 21mail.properties 103MIME 44modify 65

O

openoffice.properties 103outbound 18

content 41message processing 18profile 63

outbound message 143outboundProcessor.properties 79

P

PDF 39PDF content

special considerations 34plain text 37post process command 59Profiles.ini 46property files 96property settings 76proxy.properties 103PurgingSetup.properties 104

R

remote 56remote control 56remoteservice.properties file 61repositoryFacade.properties 104Rest API for Outmessage XML and Workflow XML 131restrict 146restricting servlet access 146roleProvider 127roles 61rootfolder.properties 107

S

sample journal file 48schedule

data flow 55scheduled jobs 62security 61

serverCluster.properties 107Service 41servlet access 146SMS 20, 22special considerations

Plain text content 33SMS content 35

standard DIJ fieldsstatement date 24

start date 63start time 63system architecture 16

T

tableColumns.properties 87technical architecture 16

U

user permissions 61userPopulator 125userSearch 123

V

validations 66Vault 41

configuration 46index key 95

Vault Desktop 50Vault Render API sets 50Vault Service web 50vendorProvider 127

W

Weblogicconfiguration 201viewing notification 202

Websphereconfiguration 200viewing notification 201

workflow 142workflow.properties 108

265