engageone® deliver version 2.5 reference guide...this guide explains the design and configuration...

pitney bowes 0. Customer Engagement

EngageOne® Deliver

Version 2.5

Reference Guide US 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.orghttp://www.apache.org/licenses/http://www.apache.org/licenses/http://hibernate.org/community/license/http://hibernate.org/community/license/http://www.apache.org/licenses/http://www.apache.org/licenses/http://getbootstrap.com/getting-started/#license-faqshttp://getbootstrap.com/getting-started/#license-faqshttp://getbootstrap.com/getting-started/#downloadhttp://getbootstrap.com/getting-started/#downloadhttps://github.com/angular/angular.js/blob/master/LICENSEhttps://github.com/angular/angular.js/blob/master/LICENSEhttps://jquery.org/license/http://jquery.com/download/http://cdn.rawgit.com/paultuckey/urlrewritefilter/master/src/doc/manual/4.0/introduction.html#licensehttp://cdn.rawgit.com/paultuckey/urlrewritefilter/master/src/doc/manual/4.0/introduction.html#licensehttp://www.tuckey.org/urlrewrite/http://www.apache.org/licenses/https://github.com/FasterXML/jacksonhttps://github.com/FasterXML/jackson

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

https://opensource.org/licenses/lgpl-license/https://community.jaspersoft.com/project/jasperreports-library/releaseshttps://github.com/google/gcm/blob/master/LICENSEhttps://github.com/aws/aws-sdk-java/blob/master/LICENSE.txthttps://opensource.org/licenses/lgpl-licensehttps://github.com/FasterXML/jacksonhttp://cdn.rawgit.com/paultuckey/urlrewritefilter/master/src/doc/manual/4.0http:http://jquery.comhttps://github.com/angular/angular.js/blob/master/LICENSEhttp://getbootstrap.com/getting-started/#downloadhttp://getbootstrap.com/getting-started/#license-faqshttp://hibernate.org/community/licensehttp://www.apache.org/licenses

Contents

ABOUT THIS GUIDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Related documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Target audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Skills and training . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Updates to this guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Typographical conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

INTRODUCTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

On the outbound side Deliver: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

On the inbound side Deliver: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Secondary Deliver functions include: . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

TECHNICAL ARCHITECTURE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

System architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

EngageOne Deliver web . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

EngageOne Deliver core . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

EngageOne Deliver data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Outbound message processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Outbound . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Content converter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Mail servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

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

SMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Inbound message processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Inbound . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Content converter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Mail servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

3

Contents

ENGAGEONE COMMUNICATIONS SUITE AND DELIVER . . . . . . . . . . . . . . . . . . . 23

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

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

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

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

Custom DIJ fields required for Deliver . . . . . . . . . . . . . . . . . . . . . . . . . . . 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 . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Making Designer and Generate content available to Deliver . . . . . . . . . 36

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

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

HTML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

PDF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

Non-Designer/Generate content & Deliver . . . . . . . . . . . . . . . . . . . . . . . 40

Vault . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

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

Folder permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

Retrieving message content from Vault . . . . . . . . . . . . . . . . . . . . . . . . . . 48

Inlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

Schedule and control of Data Flow & Generate from EngageOne Deliver 54

General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

Local and remote control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

Data Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

Generate & Post Process command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

4

Contents

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

Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

HEADERS – SUPPRESSING E-MAIL HEADERS . . . . . . . . . . . . . . . . . . . . . . . . . . 66

MESSAGE DELIVERY RATE OPTIONS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

DIGITAL SIGNATURES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

Generating a Private Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

keys.properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

Triggering or Suppressing Digital Signing . . . . . . . . . . . . . . . . . . . . . . . . . . 73

Important Note . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

PROPERTY SETTINGS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

inbound-observer.properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

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

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

tableColumns.properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

Custom Vault index key mapping configuration . . . . . . . . . . . . . . . . . . . . . . 96

Sample custom index mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

Other property files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

ApplicationAlert.properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

ApplicationResources.properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

asyncProcesses.properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

aws.property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

blackoutWindow.properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

ClickatellMessageComposer.properties . . . . . . . . . . . . . . . . . . . . . . . . . 99

custom.properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

Ems.properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

encryptionKey.properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

5

Contents

engageone.properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

Executor.properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102

inlet.properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102

Install.properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102

jdbc.properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

log4j.xml . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

mail.properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

openoffice.properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

Proxy.properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

securityConfiguration.properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

PurgingSetup.properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

repositoryFacade.properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

RESTService.properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

rootfolder.properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

keys.properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

serverCluster.properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

servlet.properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

workflow.properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

autoNotification.properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109

inboundAsync.properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110

mPushNotification.properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111

FAILOVER CONFIGURATION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112

Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

ACTIVE-ACTIVE CLUSTERING CONFIGURATION . . . . . . . . . . . . . . . . . . . . . . . . 117

Configuring Active-Active clustering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118

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

6

Contents

SETTING UP THE LOAD BALANCER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

LDAP CONFIGURATION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123

Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123

Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123

Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123

Mapping an Activer Directory user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123

LDAP connection and search settings . . . . . . . . . . . . . . . . . . . . . . . . . . . 124

Authentication providers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126

LANGUAGE RESOURCE BUNDLES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130

Example Language Source Bundle file . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130

Browser configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

Mozilla Firefox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

Microsoft Internet Explorer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

Retry sending failed messages (Emails) due to ‘timed out’ error . . . . . . 133

REST WEB SERVICE APIS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

Outbound Profile Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

Node details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141

Error XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144

Restricting API Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144

Workflow item . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145

Outbound message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146


Message Processing APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149

Send email . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149

Send SMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153

Send Mobile Push Notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156

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

7

Contents

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

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

Retry sending failed message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165


Get message delivery status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167

Batch Message Processing APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169

Send email (batch) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169

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

Send SMS (batch) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174

Batch process invocation API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178

POST request API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178

GET request API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178

Report APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179

Report Download . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179

Report Count . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179

Dashboard APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180

Dashboard Summary API for email . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181

Dashboard Summary API for SMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184

Campaign Summary APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191

Batch Summary API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191

Batch List API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198

REST API Security over Basic Authentication . . . . . . . . . . . . . . . . . . . . . . . 199

Enable/disable Basic Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . 199

APPLICATION MONITORING SUPPORT USING JMX . . . . . . . . . . . . . . . . . . . . 200

EngageOne Deliver MBeans (Management Bean) . . . . . . . . . . . . . . . . . . . 200

Application Server built-in MBeans . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201

Notification types available to EngageOne Deliver . . . . . . . . . . . . . . . . . . 202

Configuring EngageOne Deliver to enable JMX notification . . . . . . . . . . . 203

8

Contents

Websphere configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203

Weblogic configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204

Jconsole configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205

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

APPENDIX B – PURGE VENDOR SCRIPTS . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216

Purge process errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216

Purge audit messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216

Purge reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216

Purge workflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217

Purge people . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217

Purge properties file configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217

APPENDIX C – APPLICATION CUSTOMIZATION . . . . . . . . . . . . . . . . . . . . . . . . 219

Changing the application logo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219

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

Background Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220

Using the SMS-APIs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221

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

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

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

Verify Email address . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244

Create SQS-Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245

Create SNS-Topic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246

Subscribe the SQS queues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246

SQS-Queue permission settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247

9

Contents

SES bounce notification settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249

Deliver settings for bounce . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250

APPENDIX G – CUSTOM EMAIL SUPPORT . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252

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

SMTP Email . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255

IMAP Email . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256

POP3 Email . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257

SMPP SMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257

MS SQL DB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258

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

APNS Gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259

Certificate File Upload . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259

Duplicate APNS Gateways Validation . . . . . . . . . . . . . . . . . . . . . . . . . . . 260

AWS APNS Gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260

Certificate File Upload . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264

Duplicate AWS APNS Gateways Validation . . . . . . . . . . . . . . . . . . . . . . . 265

Profile Creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265

APPENDIX J – RELAY/SEND INBOUND SMS DATA TO THIRD PARTY API (E.G. CONVERSE API) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266

Template Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266

Template JSON format for POST request (in Template Text field) . . . 267

Template JSON format for GET request (in Template Text field) . . . . 267

Inbound profile association with template . . . . . . . . . . . . . . . . . . . . . . . 268

APPENDIX K – PURGING THE DATABASE WITH PARTITIONS . . . . . . . . . . . . 269

Pre-Requisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269

10

Contents

Steps to Purge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270

Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272

INDEX 273

11

About this guide

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

Related documentation

The following guides provide useful reference material:

• EngageOne® Deliver User’s Guide

• EngageOne® Deliver Installation Guide

• EngageOne® Deliver Release Notes

Target audience

This guide is for an application developer who is responsible for supporting the EngageOne® Deliver 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.

12

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

13

Introduction

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

Deliver 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. Deliver 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, Deliver helps organizations maintain brand consistency across communication channels.

On the outbound side Deliver: • 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.

14

Introduction

On the inbound side Deliver: • 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.

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

Secondary Deliver 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

15

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.

16

Technical Architecture

This section outlines the high-level EngageOne Deliver architecture.

System architecture

17


EngageOne Deliver web

EngageOne Deliver 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 Deliver 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 Deliver comes with user interfaces in the following languages:

• English

• Spanish

• Portuguese (Brazilian)

• German

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

Deliver 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

• Responding to messages

18


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 Deliver core

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

EngageOne Deliver data

The EngageOne Deliver 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 Deliver 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 Deliver as part of messaging campaigns.

Message Formatting (optional) • EngageOne Generate applications can be triggered from Deliver to format message

content.

19


Post Process Formatting (optional) • Post Composition processes can be triggered by Deliver 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 Deliver 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.

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

For archiving outbound messages, Deliver 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

Deliver 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

Deliver 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, Deliver can interface with any mail servers that provide SMTP support.

After message content has been composed (either under the control of Deliver or externally to Deliver), Deliver 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 Designer and profile settings that are configured in the Deliver 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 Deliver supports formatting and sending the following e-mail formats:

20


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 Deliver 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 Deliver Reference Guide.

Inbound message processing The EngageOne Deliver 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 Deliver. Received messages could be messages that require archiving into Vault, messages that require a response or delivery status notifications reporting on messages sent by the Outbound component that could not be delivered. The Inbound component also takes care of associating inbound messages with outbound messages sent by Deliver so that reports can be provided on what messages bounced (including bounce category) and what messages have been replied to.

21

http:http://www.clickatell.com


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, Deliver 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, Deliver 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 Deliver 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 Deliver 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.

Deliver 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

Deliver 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 Deliver to index and archive these messages too. This process is sometimes called "e-mail journaling".

SMS

EngageOne Deliver 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 Deliver Reference Guide.

22

mailto:[email protected]:[email protected]

EngageOne Communications Suite and Deliver

EngageOne EngageOne Communications Suite components can integrate with EngageOne Deliver. Deliver 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. Deliver tightly integrates into EngageOne as an additional delivery channel. EngageOne is a separately licensed product and additional Deliver configuration is required to enable the product integration. See the EngageOne documents for more information.

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

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

23


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.

Deliver 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 Deliver can process the related content correctly. The rest of this section explains DIJ fields that are required by Deliver.

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 Number A code that uniquely identifies the customer.

Name The 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 Date The date on which statement is generated. This information will appear in the e-mail date header.

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

Publication ID This 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 Deliver

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

Email Create 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. Compulsory for e-mail messages and optional for SMS messages

24


Subject Create 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:

CC NDC SN

THE MSISDN MUST NOT BE PRECEDED WITH ANY “0”, "1" OR “+” CHARACTERS AND MUST NOT CONTAIN ANY SPACES.

420 603 123456

Optional for e-mail messages and compulsory for SMS messages

Sign Create 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 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 Deliver Inbound or Outbound profile.

25



AttachName1 Create 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 Deliver 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.

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

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

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. Deliver expects to find a file of the specified name in the folder that is configured for Attachment 1 in Deliver Outbound Profile. If a filename is specified which cannot be found in this folder then Deliver 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 Deliver Outbound Profile. Otherwise, if Attachment 1 is not optional, then Deliver will raise an exception.

For personalized PDF attachments, Deliver 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 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

26


generated by the same Generate job. Additional content verification based on Document Instance ID can be configured in an EngageOne Deliver 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 ... AttachNameX EngageOne Deliver 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, Deliver only supported up to four “AttachNameX” settings in the DIJ. As of version 1.3 Deliver supports any number of attachments and therefore any number of “AttachNameX” settings in the DIJ.

Encoding1,Encoding2...EncodingX The 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...ContentTypeX The 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 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

27


attach.doc

doc

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

Inbound Profiles can be configured in Deliver 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 Deliver’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 Deliver to send as an e-mail or SMS.

If the successful sending of a response message through Deliver 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 Deliver. Both web service and file based APIs are available. See REST API for Outmessage XML and Workflow XML section on page 134 for further details on these APIs.


WorkflowStage_Id WorkflowStage_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 Deliver. Other values will be ignored.

0 – Message requires manual content categorization*

1 – Message requires manual content conversion or checking*

2 – Message requires manual indexing*

3 – Delivery Status Notification (bounce message)*

4 – Indexed but open (requires response)*

40 – Archiving off but requires response*

28


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 Deliver 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

From Create 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 Deliver 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 Deliver 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-to Create 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 Deliver Outbound Profile and allows the Reply-to address of an e-mail to be personalized on a message by message basis.


Return-path Create 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 Deliver 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 Deliver Inbound Profile for processing all Delivery Status Notifications than it is to configure Inbound Profiles on a per message basis.


Errors-to Create 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 Deliver Outbound Profile and allows the Errors-to address of an e-mail to be

29


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 Deliver Inbound Profile for processing all Delivery Status Notifications than it is to configure Inbound Profiles on a per message basis.


Custom email headers EngageOne Deliver 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:

header1=value1,header2=value2

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

Example:

20100105164052Microsoft Windows

5F2E999D61D84A4693498E9BCECE2C62E:/emsg/appdoc1/sms/Output/63/SIRS_63_20091201.prmisSIRS_63_20091201.prmis

BatchTestIdBatchTestName1231/CustomerId>Source98

Auto Notification End point If 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

a5f18288cc294573879357cd5a47451d

30


5865F1950EB14D028BA999AF5DADE524Inbound10201508219999999999tocustomers@emessaging.comInbound1027828746377testfile1.pdf

Other Custom DIJ Fields If 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 Deliver. For outbound messages simply create custom DIJ fields with the names of your custom index keys and populate their values as required. Deliver will pass, non-Deliver 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 Deliver to your own custom attribute keys as required. Refer to Custom Vault Index Key Mapping Configuration section on page 96 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. Deliver 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.

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

31


Designer In 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.

Images It 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

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 Deliver Outbound Profile that will be sending your HTML. Please refer to the Designer User Guide for instructions on using Resource Maps.

ENGAGEONE DELIVER 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.

32


Fonts You 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 Layout When 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.

Fonts Use 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 Layout When 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. Deliver will raise an 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 Settings The following linedata driver settings are recommended when using the linedata output in the plain text part of an e-mail body:

33


• Format of logical records – CRLF

• Height of character placing grid – xxxx

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

• Output codepage – Unicode – UTF-8

• Force full width characters -unchecked

Special considerations for PDF content

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.

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.

Fonts Base14 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 Layout No special considerations

Output Driver Settings The 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 Deliver

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

Deliver 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 Deliver Reference Guide.

34

http:http://www.clickatell.com


For SMS via clickatell Deliver 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, Deliver 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 Deliver, then there needs to be a mapping between the inbound SMPP listener profile and the outbound SMPP gateway. See the EngageOne Deliver Users Guide for details.

The majority of the settings required to send and receive messages are configured in Deliver Outbound and Inbound Profiles. The mobile number which a message needs to be sent to is provided to Deliver 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, Deliver expects to find one or more of the following name value pairs in the journal file that is provided by Generate:

Message for:MSISDN unicode:{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 Deliver:

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

35


Examples:

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

Making Designer and Generate content available to Deliver

Outbound Profiles are configured in EngageOne Deliver 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 Deliver 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 Deliver with the necessary message header fields for each message as will as specifying other message fields such as attachment names.

Deliver 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 Deliver. Otherwise, Deliver 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

36


• “UniqueName123.jrn” or

• “UniqueName123.xml”

Plain text

E-mail Plain 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 34 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”.

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.

deliver DOES NOT SUPPORT DIRECT PROCESSING OF THE XML-PAK GENERATED BY THE DESIGNER/GENERATE HTML DRIVER.

37


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 earlier For batch Outbound Profiles, the HTML filenames should exist of two parts. The first part should equal the unique name (except for file extension) of the DIJ containing the metadata for the messages. The second part should be a sequence number, padded to seven digits, of the message in the DIJ that the HTML needs to be associated with. The two parts of the name should be separated by an underscore, “_”, and the file extension should be “.html” For example:

• “UniqueName123_0000001.html”



DOC1 version 5.5 and later DOC1 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 Deliver 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”.

PDF

An Outbound Profile can be configured to attach any number of attachments to an e-mail message. These attachments are configured in Deliver 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

38


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 Deliver 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 Deliver 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 Deliver will raise an exception.

For personalized PDF attachments, Deliver 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 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 Deliver 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.

39


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, Deliver 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, Deliver will apply the same name as the filename selected for attachment in the AttachNameX value in the DIJ.

Non-Designer/Generate content & Deliver

EngageOne Deliver 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 Deliver.

Vault General

Deliver can be con

engageone® deliver version 2.5 reference guide...this guide explains the design and configuration...

Documents