Adobe Campaign Configuration v6.1 en

Configuration Guide
Neolane v6.1
This document, and the software it describes, are provided subject to a License Agreement and may not be used or copied outside of the
provisions of the License Agreement. No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any
form or by any means, electronic, mechanical, photocopying, recording or otherwise, without the prior written permission of Neolane.
The information contained in this document is provided for informational purposes only and may be revised without notice. It does not
constitute a commitment on the part of Neolane. Neolane does not guarantee the accuracy nor the completeness of the information
contained within this document. References to company names are intended to be ficticious and for illustrative purposes only and do not
refer to any real-world company.
Any brands cited are the property of their respective owners. Windows is the registered trademark of Microsoft Corporation in the United
States and other countries. Java, MySQL and Open Office are trademarks of Oracle Corporation in the United States and in other countries.
Linux is the registered trademark of Linus Torvalds in the United States and in other countries. This product includes software developed
by Apache Software Foundation (http://www.apache.org/).
For any questions or queries, please send a message to the following address: doc@neolane.com.
Version number : 8141
Neolane
18 rue Roger Simon Barboux, 94110 Arcueil - France
+33 1 41 98 35 35
www.neolane.com
Table of Contents
Neolane v6.1 - Configuration Guide
Chapter 1. Neolane datamodel . . . . . . . . . . . . . . . . . . . . 9

Accessing the Neolane dataschemas . . . . . . . . . . . . . . . . . . 11
General information . . . . . . . . . . . . . . . . . . . . . . . . 11
Physical and logical data . . . . . . . . . . . . . . . . . . . . . 11
Work tables . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Table structure . . . . . . . . . . . . . . . . . . . . . . . . . 12
Auto-incrementing primary keys . . . . . . . . . . . . . . . . . . . 12
Zero-ID record . . . . . . . . . . . . . . . . . . . . . . . . . 12
"Deleted" field . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Track changes . . . . . . . . . . . . . . . . . . . . . . . . . 13
Description of the main tables . . . . . . . . . . . . . . . . . . . . 14
Simplified diagram . . . . . . . . . . . . . . . . . . . . . . . . 14
NmsRecipient . . . . . . . . . . . . . . . . . . . . . . . . . . 14
NmsGroup . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
NmsRcpGrpRel . . . . . . . . . . . . . . . . . . . . . . . . . 17
NmsService . . . . . . . . . . . . . . . . . . . . . . . . . . 17
NmsSubscription . . . . . . . . . . . . . . . . . . . . . . . . 19
NmsSubHisto . . . . . . . . . . . . . . . . . . . . . . . . . . 19
NmsDelivery . . . . . . . . . . . . . . . . . . . . . . . . . . 20
XtkFolder . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Delivery and tracking . . . . . . . . . . . . . . . . . . . . . . . . 28
NmsBroadLogMsg . . . . . . . . . . . . . . . . . . . . . . . . 28
Simulation and delivery . . . . . . . . . . . . . . . . . . . . . . . 30
Communication consistency and capacity rules . . . . . . . . . . . . . . 31
NmsTypologyRule . . . . . . . . . . . . . . . . . . . . . . . . 31
NmsTypology . . . . . . . . . . . . . . . . . . . . . . . . . . 32
NmsTypologyRuleRel . . . . . . . . . . . . . . . . . . . . . . . 33
Response management . . . . . . . . . . . . . . . . . . . . . . . 33
Campaign management . . . . . . . . . . . . . . . . . . . . . . . 34
NmsOperation . . . . . . . . . . . . . . . . . . . . . . . . . 34
NmsDeliveryOutline . . . . . . . . . . . . . . . . . . . . . . . 36
NmsDlvOutlineItem . . . . . . . . . . . . . . . . . . . . . . . 36
NmsDeliveryCustomization . . . . . . . . . . . . . . . . . . . . 37
NmsBudget . . . . . . . . . . . . . . . . . . . . . . . . . . 37
NmsDocument . . . . . . . . . . . . . . . . . . . . . . . . . 38
XtkWorkflow . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Neolane v6.1 - Configuration Guide | 3

Neolane
NmsTask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
NmsAsset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Interaction Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
NmsOffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
NmsPropositionRcp . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
NmsOfferSpace . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
NmsOfferView . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
NmsOfferCategory . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
NmsOfferEnv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Message Center Module . . . . . . . . . . . . . . . . . . . . . . . . . . 51
NmsRtEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
NmsBatchEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Social Marketing Module . . . . . . . . . . . . . . . . . . . . . . . . . . 55
NmsVisitor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
NmsVisitorSub . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
NmsFriendShipRel . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
NmsVisitorInterestRel . . . . . . . . . . . . . . . . . . . . . . . . . . 57
NmsInterest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Microsites Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
NmsTrackingUrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
NmsPurl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
NMAC Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
NmsMobileApp . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
NmsAppSubscriptionRcp . . . . . . . . . . . . . . . . . . . . . . . . . 61
NmsExcludeLogAppSubRcp . . . . . . . . . . . . . . . . . . . . . . . 62
NmsTrackingLogAppSubRcp . . . . . . . . . . . . . . . . . . . . . . . 62
NmsBroadLogAppSubRcp . . . . . . . . . . . . . . . . . . . . . . . . 63
Chapter 2. Schema Reference (xtk:srcSchema) . . . . . . . . . . . . . . . . 65

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Syntax of schemas . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Identification of a schema . . . . . . . . . . . . . . . . . . . . . . . . 67
Schema structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Collections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Referencing with XPath . . . . . . . . . . . . . . . . . . . . . . . . . 73
Building a string via the compute string . . . . . . . . . . . . . . . . . . . 74
Database mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
XML fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Calculated fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Indexed fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Management of keys . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Links: relation between tables . . . . . . . . . . . . . . . . . . . . . . . 80
Dictionary of elements and attributes . . . . . . . . . . . . . . . . . . . . . 83
<attribute> element . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
<compute-string> element . . . . . . . . . . . . . . . . . . . . . . . . 87
<condition> element . . . . . . . . . . . . . . . . . . . . . . . . . . 88
<dbindex> element . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
<element> element . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
<enumeration> element . . . . . . . . . . . . . . . . . . . . . . . . . 96
<help> element . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
<join> element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
<key> element . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
<keyfield> element . . . . . . . . . . . . . . . . . . . . . . . . . . 102
4 | Neolane 2013
Configuration Guide
<method> element . . . . . . . . . . . . . . . . . . . . . . . . . . 103

<methods> element . . . . . . . . . . . . . . . . . . . . . . . . . . 105
<param> element . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
<parameters> element . . . . . . . . . . . . . . . . . . . . . . . . . 108
<srcSchema> element . . . . . . . . . . . . . . . . . . . . . . . . . 109
<sysFilter> element . . . . . . . . . . . . . . . . . . . . . . . . . . 111
<value> element . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
Chapter 3. Editing and extending schemas . . . . . . . . . . . . . . . . . 113

Editing schemas . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
Example: creating a contract table . . . . . . . . . . . . . . . . . . . . . 115
Schema of an existing table or a view . . . . . . . . . . . . . . . . . . . . 118
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
Accessing an external database . . . . . . . . . . . . . . . . . . . . . 119
Extending an existing schema . . . . . . . . . . . . . . . . . . . . . . . 121
Protecting schemas . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
System filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Protecting out-of-the-box schemas . . . . . . . . . . . . . . . . . . . . 122
Modifying system filters of out-of-the-box schemas . . . . . . . . . . . . . . 123
Updating the physical structure of the database . . . . . . . . . . . . . . . . 124
New field wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
Schema structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Regenerating all schemas . . . . . . . . . . . . . . . . . . . . . . . . . 127
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Extending a table . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Linked collection table . . . . . . . . . . . . . . . . . . . . . . . . . 128
Extension table . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
Overflow table . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
Relationship table . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
Chapter 4. Input forms . . . . . . . . . . . . . . . . . . . . . . . . . 133

Identifying a form . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
Editing forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
Form structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
Formatting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
Containers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
Editing a link . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
List of links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
Memory list controls . . . . . . . . . . . . . . . . . . . . . . . . . . 142
Non-editable fields . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
Radio button . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
Checkbox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
Navigation hierarchy edit . . . . . . . . . . . . . . . . . . . . . . . . 144
Expression field . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
Context of forms . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
Wizards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
Chapter 5. API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
Definition of Neolane APIs . . . . . . . . . . . . . . . . . . . . . . . 148
Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
Using Neolane APIs . . . . . . . . . . . . . . . . . . . . . . . . . . 148
SOAP calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
Resources and exchanges . . . . . . . . . . . . . . . . . . . . . . . 149
Example of a SOAP message on the "ExecuteQuery" method . . . . . . . . . . 149

Neolane
Error management . . . . . . . . . . . . . . . . . . . . . . . . . . 150

URL of Web service server (or EndPoint) . . . . . . . . . . . . . . . . . . 151
Web service calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
General information . . . . . . . . . . . . . . . . . . . . . . . . . . 151
Definition of Web services . . . . . . . . . . . . . . . . . . . . . . . . 151
Web service description: WSDL . . . . . . . . . . . . . . . . . . . . . . 152
Connectivity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
Data oriented API . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
Overview of the datamodel . . . . . . . . . . . . . . . . . . . . . . . 156
Description of the model . . . . . . . . . . . . . . . . . . . . . . . . 156
Query and Writer . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
ExecuteQuery (xtk:queryDef) . . . . . . . . . . . . . . . . . . . . . . 157
Write / WriteCollection (xtk:session) . . . . . . . . . . . . . . . . . . . . 164
Business oriented APIs . . . . . . . . . . . . . . . . . . . . . . . . . . 166
Subscribe (nms:subscription) . . . . . . . . . . . . . . . . . . . . . . 167
Unsubscribe (nms:subscription) . . . . . . . . . . . . . . . . . . . . . 168
SubmitDelivery (nms:delivery) . . . . . . . . . . . . . . . . . . . . . . 169
Implementing SOAP methods in JavaScript . . . . . . . . . . . . . . . . . . 170
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
Definition of a method library . . . . . . . . . . . . . . . . . . . . . . . 170
Use SOAP methods in JavaScript . . . . . . . . . . . . . . . . . . . . . . 171
Static methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
Non-static methods . . . . . . . . . . . . . . . . . . . . . . . . . . 172
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
Adding additional SQL functions . . . . . . . . . . . . . . . . . . . . . . 173
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
General structure of package to import . . . . . . . . . . . . . . . . . . . 173
The <function> function descriptor . . . . . . . . . . . . . . . . . . . . 174
The "pass-through" function descriptor . . . . . . . . . . . . . . . . . . . 175
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
Chapter 6. Navigation hierarchy . . . . . . . . . . . . . . . . . . . . . . 177

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
Global commands . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
Folder type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
Edition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
Chapter 7. Using an external recipient table . . . . . . . . . . . . . . . . . 185

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
Precisions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
Recommendations and limitations . . . . . . . . . . . . . . . . . . . . . 186
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
The View attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
Names of tables and columns . . . . . . . . . . . . . . . . . . . . . . 187
Indexed fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
Setting up a target mapping . . . . . . . . . . . . . . . . . . . . . . . . 187
Creating and configuring the schemas linked to the external table . . . . . . . . . 188
Using target mapping . . . . . . . . . . . . . . . . . . . . . . . . . 191
Configuring the interface to use the new recipient table . . . . . . . . . . . . . . 191
Creating a new form . . . . . . . . . . . . . . . . . . . . . . . . . . 192
Creating a new type of folder in the navigation hierarchy . . . . . . . . . . . . 192
Configuring seed addresses based on an external recipient table . . . . . . . . . . 193
Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
Creating filters to manipulate the new recipient table . . . . . . . . . . . . . . . 194
6 | Neolane 2013
Configuration Guide
Creating lists based on the external recipient table . . . . . . . . . . . . . . . 195
Chapter 8. Setting up Web tracking . . . . . . . . . . . . . . . . . . . . 199

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
Web tracking mode . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
Web tracking tag: definition . . . . . . . . . . . . . . . . . . . . . . . . 202
Format of the data to be sent . . . . . . . . . . . . . . . . . . . . . . . 203
Data transmission methods . . . . . . . . . . . . . . . . . . . . . . . 203
Setup stages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
Additional web tracking parameters . . . . . . . . . . . . . . . . . . . . . 204
Definition of parameters . . . . . . . . . . . . . . . . . . . . . . . . 204
Redirection server configuration . . . . . . . . . . . . . . . . . . . . . 205
Creating web tracking tags . . . . . . . . . . . . . . . . . . . . . . . . 205
Defining the URLs to be tracked in the application . . . . . . . . . . . . . . . 206
On-the-fly creation of URLs to be tracked . . . . . . . . . . . . . . . . . . 206
Inserting tags in your site . . . . . . . . . . . . . . . . . . . . . . . . . 207
Simple method . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
Optimum method . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
Collecting all visits to a site . . . . . . . . . . . . . . . . . . . . . . . . 210
Server configuration . . . . . . . . . . . . . . . . . . . . . . . . . . 210
Configuring a default matching campaign . . . . . . . . . . . . . . . . . . 210
Anonymous tracking . . . . . . . . . . . . . . . . . . . . . . . . . . . 210

Neolane
8 | Neolane v6.1 - Configuration Guide

CHAPTER 1
Neolane datamodel
Table of Contents
Accessing the Neolane dataschemas . . . . . . . . . . . . . . . . . . . 11
General information . . . . . . . . . . . . . . . . . . . . . . . . . 11
Physical and logical data . . . . . . . . . . . . . . . . . . . . . . . 11
Work tables . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Table structure . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Auto-incrementing primary keys . . . . . . . . . . . . . . . . . . . . 12
Zero-ID record . . . . . . . . . . . . . . . . . . . . . . . . . . 12
"Deleted" field . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Track changes . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Description of the main tables . . . . . . . . . . . . . . . . . . . . . . 14
Simplified diagram . . . . . . . . . . . . . . . . . . . . . . . . . 14
NmsRecipient . . . . . . . . . . . . . . . . . . . . . . . . . . 14
NmsGroup . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
NmsRcpGrpRel . . . . . . . . . . . . . . . . . . . . . . . . . . 17
NmsService . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
NmsSubscription . . . . . . . . . . . . . . . . . . . . . . . . . 19
NmsSubHisto . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
NmsDelivery . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
XtkFolder . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Delivery and tracking . . . . . . . . . . . . . . . . . . . . . . . . . 28
NmsBroadLogMsg . . . . . . . . . . . . . . . . . . . . . . . . . 28
Simulation and delivery . . . . . . . . . . . . . . . . . . . . . . . . 30
Communication consistency and capacity rules . . . . . . . . . . . . . . . . 31
NmsTypologyRule . . . . . . . . . . . . . . . . . . . . . . . . . 31
NmsTypology . . . . . . . . . . . . . . . . . . . . . . . . . . 32
NmsTypologyRuleRel . . . . . . . . . . . . . . . . . . . . . . . . 33
Response management . . . . . . . . . . . . . . . . . . . . . . . . 33
Campaign management . . . . . . . . . . . . . . . . . . . . . . . . 34
NmsOperation . . . . . . . . . . . . . . . . . . . . . . . . . . 34
NmsDeliveryOutline . . . . . . . . . . . . . . . . . . . . . . . . 36
NmsDlvOutlineItem . . . . . . . . . . . . . . . . . . . . . . . . 36
NmsDeliveryCustomization . . . . . . . . . . . . . . . . . . . . . . 37
NmsBudget . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
NmsDocument . . . . . . . . . . . . . . . . . . . . . . . . . . 38
XtkWorkflow . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
NmsTask . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
NmsAsset . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Interaction Module . . . . . . . . . . . . . . . . . . . . . . . . . . 45
NmsOffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
NmsPropositionRcp . . . . . . . . . . . . . . . . . . . . . . . . 46
Neolane v6.1 - Configuration Guide - Neolane datamodel | 9

Neolane
NmsOfferSpace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
NmsOfferView . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
NmsOfferCategory . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
NmsOfferEnv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Message Center Module . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
NmsRtEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
NmsBatchEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Social Marketing Module . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
NmsVisitor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
NmsVisitorSub . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
NmsFriendShipRel . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
NmsVisitorInterestRel . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
NmsInterest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Microsites Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
NmsTrackingUrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
NmsPurl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
NMAC Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
NmsMobileApp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
NmsAppSubscriptionRcp . . . . . . . . . . . . . . . . . . . . . . . . . . 61
NmsExcludeLogAppSubRcp . . . . . . . . . . . . . . . . . . . . . . . . . 62
NmsTrackingLogAppSubRcp . . . . . . . . . . . . . . . . . . . . . . . . . 62
NmsBroadLogAppSubRcp . . . . . . . . . . . . . . . . . . . . . . . . . . 63
This chapter details the articulation of the main worktables rather than the internal operating tables, as
well as the specifics of the Neolane datamodel. The aim is to provide the user with a better understanding
of the model, in view of analyzing data, configuring new reports, performing targeting based on behavior
after a delivery, exporting data linked to the delivery or synchronizing data with an external system, etc.
10 | Neolane 2013
Neolane datamodel
Accessing the Neolane dataschemas

For a detailed description of the datamodel, refer to the Documentation tab of each dataschema:
General information
Before we address the datamodel as such, here is some general information.
Physical and logical data

Physical data (SQL vision) is inferred from logical schemas (XML vision)
As a consequence, a logical schema does not always give rise to a physical schema. As a result, some data
or parts of schemas are described in XML elements and are only stored in a single XML field. This is the case
with the link between deliveries and typology rules for HTML content, for example
Moreover, some tables are polymorphic; such as plans and programs stored in the same physical table
(xtkFolder), campaigns and deliveries containing instances, and delivery templates.
In addition, some data is not present in the datamodel and can only be found in the XML metadata. This is
the case for system enumerations (sysenum), for example.
Work tables
Work tables are created, then destroyed during application phases. The name and structure of some tables
are defined at run time (Data Management and targeting workflows, etc.), while others are persistent dynamic
tables (lists, answers to a survey, simulation results).

Neolane
Table structure
Some table structures can be complex. For example:
n self-referent tables that point to themselves, such as campaign and budget tables,
n hierarchical tables such as xtkFolder for which access to information requires using the fullname
(complete tree structure).
Auto-incrementing primary keys

The primary key (ID) for most Neolane tables is an auto-generated 32-bit integer.
All these primary keys use the same XtkNewId sequence. When creating the database, this sequence is
initialized to 1000, the first 1000 identifiers are reserved. As a result, if for any reason, you have to "hard
code" an identifier, you can use an identifier greater than 1000 to avoid any risk of conflict.
If necessary, negative values can be used.
Note:
The keys of the NmsBroadLog and NmsTrackingLogXXX tables have their own sequence.
Zero-ID record
For all tables that use our sequence as a primary key, a record with 0 as a value is inserted upon
creation. This 0 ID record is used to avoid external joins that aren't efficient for tables with a significant
volume. By highlighting the 0 value in the foreign key of a table when the data isn't recorded, a join is created
on this 0 value record that contains no data. All queries carried out via the application ignore this record in
the returned results. Only regard these if you are setting up SQL extraction procedures on Neolane tables.
Tip:
In workflows, you can configure the management of additional data and disable filtering. To do this, edit
additional data (in Query or Enrichment boxes, for example), click the Advanced settings link and check
the Disable automatic filtering of 0 identifier records option.
"Deleted" field
Certain tables contain an iDeleteStatus field (NmsDelivery, NmsService and NmsSubscription in
particular). This field is used for managing the Recycle Bin and performing time-consuming deletions during
the night.
The value 1 means that the record will be deleted by the cleanup workflow next time it is executed (mostly
scheduled to be executed every night). Records linked with integrity own are also deleted.
As a consequence, you should consider these records as destroyed even if they have not yet been physically
deleted from their tables.
In all the queries configured in the application, an iDeleteStatus = 0 clause is added implicitly. However,
when writing queries directly in SQL, you must take this field into consideration.
For deliveries (NmsDelivery table), the value 2 indicates that the record is in the Recycle bin. Deleted
deliveries will be placed in the recycle bin by default and can be restored by the user if necessary. By default,
the cleansing task will destroy the delivery after seven days. In this case, the tsDelete field specifies the
date on which the record was placed in the recycle bin.
12 | Neolane 2013
Neolane datamodel
Track changes
Certain reserved field names enable you to track the creation and modification of certain records:
n tsCreated contains the creation date,
n tsLastModified contains the last modification date,
n iCreatedById contains the identifier of the operator who created the record (foreign key of a link to
XtkOperator),
n iModifiedById contains the ID of the last operator who modified the record (foreign key of a link to
XtkOperator).
These fields are added in the schemas using the auditTrail aggregate. Other schemas only use certain
fields. For example NmsRecipient contains tsCreated and tsLastModified only. These fields are populated
automatically for all creations and modifications made by the application: input interface, imports, web forms,
etc.
Warning:
The name of each field in the XML schema triggers this behavior, not the SQL names.
Creation and modification dates can only be changed via the Neolane console. Updates, deletions or insertions
carried out in the database and not via the console will have no effect on these dates.

Neolane
Description of the main tables
Simplified diagram
The following is a diagram showing the joins between the main business tables of the Neolane data model
with the main fields shown for each.
NmsRecipient
This table matches the nms:recipient schema.
It is the default table used for the recipients of deliveries. As a result, it contains the information required
for deliveries via the various channels:
n sEmail: email address.
n iEmailFormat: preferred format for emails (1 for Text, 2 for HTML and 0 if undefined).
n sAddress1, sAddress2, sAddress3, sAddress4, sZipCode, sCity are used to build the postal address
(in keeping with the XPZ 10-011 AFNOR standard from May 1997).
n sPhone, sMobilePhone, sFax contain the phone, mobile phone and fax numbers respectively.
n iBlackList is the default opt-out flag used for the profiles (1 means "unsubscribed", 0 otherwise).
The iFolderId field is the foreign key that links the recipient to its execution folder. Refer to the description
of the XtkFolder table below for further details.
The sCountryCode field is the 3166-1 Alpha 2 ISO code (2 characters) of the country associated with the
recipient. This field is actually a foreign key on the country reference table (NmsCountry), which contains
the country labels and other country code data. If the country is not populated, the value 'XX' is stored (and
is used in place of a zero ID record).
14 | Neolane 2013
Neolane datamodel
General information
Field Type Description Values

iRecipientId long Primary key -
sAccount string Account # -
sOrigin string Origin -
iBlackList boolean No longer contact (by any channel) -
iBlackListEmail boolean No longer contact by email -
iBlackListPhone boolean No longer contact by phone -
iBlackListFax boolean No longer contact by fax -
iBlackListMobile boolean No longer contact by SMS/MMS -
iBlackListPostalMail boolean No longer contact by direct mail -
sLastName string Name -
sFirstName string First name -
sMiddleName string Middle name -
sSalutation string Salutation -
iGender byte Gender 0-None specified

1-Male
2-Female
sLanguage string Language -
sCompany string Company -
sEmail string Email -
iEmailFormat byte E-mail format 0-Unknown

1-Text
2-HTML
sMobilePhone string Mobile -
sPhone string Phone -
sFax string Fax -
sAddress1 string Address 1 (apartment) -
sAddress2 string Address 2 -
sAddress3 string Address 3 (Number and street) -
sAddress4 string Address 4 (county) -
sZipCode string Zip/Postcode -
sCity string City -
sStateCode string State/Province code -
sCountryCode string Country code -
iAddrQuality long Quality rating 0-0 - Incomplete address

1-1 - Unknown Town-PostalCode
2-2 - Empty street
3-3 - Unknown street
4-4 - Partially-recognized street
5-5 - Fully-recognized street
iAddrErrorCount long Number of errors -
sText1 string Text 1 -
iBoolean1 boolean Boolean 1 -

Neolane

iStatus byte Status 0-Prospect

1-Client
Table keys

iFolderId long Foreign key of link 'Folder' (field 'id') -
Time fields

tsCreated datetime Creation date -
tsLastModified datetime Modification date -
tsAddrLastCheck datetime Last qualification -
tsBirth date Birth date -
NmsGroup
This table matches the nms:group schema.
It enables you to create statical groups of recipients. There is a many-to-many relation between recipients
and groups. For example, one recipient can belong to several groups and one group can contain several
recipients. Groups can be created manually, via an import or via delivery targeting. Groups are often used
as delivery targets. There is a unique index on the field representing the internal name of the sName group.
The group is linked to a folder (The key is iFolderId. See the description of the XtkFolder table below).
General information

iGroupId long Primary key -
sName string Internal name -
sLabel string Label -
sSchema string Schema -
iBuiltIn boolean Built in import template -
iType byte List type 0-Group

1-List
2-File
3-Template
iDeleteStatus byte Deleted 0-No

1-Yes
2-Recycled
iCreatedFrom byte Origin 0-Neolane

1-SPSS
2-Business Objects
16 | Neolane 2013
Neolane datamodel

iCollectLineNumber boolean Use a line number as identifier -
Table keys

iCreatedById long Foreign key of link 'Created by' (field 'id') -
iModifiedById long Foreign key of link 'Modified by ' (field 'id') -
iFolderId long Foreign key of link 'List folder' (field 'id') -
iWorkflowId long Foreign key of link 'Workflow' (field 'id') -
iOperationId long Foreign key of link 'Marketing campaign' -

(field 'id')
Time fields

tsDelete datetime Delete date -
tsLastModified datetime Last modified -
NmsRcpGrpRel
The NmsRcpGrpRel relationship table only contains the two fields corresponding to the identifiers of the
iRecipientId and iGroupId linked tables.
Table keys

iRecipientId long Foreign key of link 'Recipient' (field 'id') -
iGroupId long Foreign key of link 'List' (field 'id') -
NmsService
This table matches the nms:service schema.
Services are entities which are similar to groups (static recipient groupings), except that they circulate more
information and enable easy management of subscriptions and unsubscriptions via forms.
There is a unique index on the field representing the internal name of the sName service. The service is
linked to a folder (The key is iFolderId. See the description of the XtkFolder table below). Finally, the
iType field specifies the delivery channel of this service (0 for email, 1 for SMS, 2 for telephone, 3 for direct
mail and 4 for fax).
General information

iServiceId long Primary key -

Neolane

iType byte Type 0-Email
1-Mobile (SMS)
20-Facebook
25-Twitter
40-Mobile application
iMode byte Mode 0-Newsletter

1-Viral
iUnlimited boolean Unlimited -
tsValidity timespan Expiration date -
iAudience long Audience -
sExternalId string External identifier -
sExternalPicture string Image -
sExternalUrl string Web link -
sCategory string Category -
sAccessToken string Access token -
sAccessTokenSecret string Access token secret -
sConsumerKey string Application ID -
sConsumerSecret string Application secret -
iSyncSubscription boolean Synchronize subscriptions -
Table keys

iSubScenarioId long Foreign key of link 'Subscription confirma- -

tion' (field 'id')
iUnsubScenarioId long Foreign key of link 'Unsubscription confirm- -

ation' (field 'id')
iFolderId long Foreign key of link 'Service Folder' (field -

'id')
iMobileAppsTargetMap- long Foreign key of link 'Target mapping linked -

pingId to mobile applications' (field 'id')
iVisitorFolderId long Foreign key of link 'Visitor folder' (field 'id') -
Time fields

18 | Neolane 2013
Neolane datamodel

NmsSubscription
This table matches the nms:subscription schema.
It enables you to manage recipient subscriptions to information services.
General information

sAddressSpecific string Specific Address -
iEmailFormat byte E-mail format 0-Unknown

1-Text
2-HTML

1-Yes
2-Recycled
iConfirmationId long Confirmation Id -
Table keys

iServiceId long Foreign key of link 'Service' (field 'id') -
Time fields

tsExpiration date Expiration date -
NmsSubHisto
This table matches the nms:subHisto schema.
If the subscriptions are managed using web forms or the interface of the application, all susbcriptions and
unsubscriptions are historized in the NmsSubHisto table. The iAction field specifies the action (0 for
unsubscription and 1 for subscription) performed on the date stored in the tsDate field.
General information

iSubHistoId long Primary key -
iAction short Action 0-Unsubscription

1-Subscription
Table keys


Neolane

Time fields

tsDate datetime Date -
NmsDelivery
This table matches the nms:delivery schema.
Each record in this table represents a delivery action or a delivery template. It contains all the necessary
parameters for performing deliveries (the target, the content, etc.). Delivery (broadcast) logs (NmsBroadLog)
and associated tracking URLs (NmsTrackingUrl) are created during the analysis phase (see below for
further details on both of these tables).
There is a unique index on the field representing the internal name of the sInternalName delivery or
scenario. The delivery is linked to an execution folder (The foreign key is iFolderProcessId. See the
description of the XtkFolder table below).
General information

iDeliveryId long Primary key -
iAttachmentId long Primary key -
sInternalName string Internal name -
iStatus short Analysis status 0-Being edited

2-Execution in progress
3-Cancel in progress
4-Canceled
5-Finished
6-Finished with errors
7-Pause in progress
8-Paused
9-Server shutdown in progress
sType string Job type -Import

-Export
-Subscription to services
-Subscription of groups
-Delivery
sXtkschema string Schema -
iBuiltIn boolean Application built-in scenario -
iIsModel boolean Template -
iFCPOrSeedCount long Messages to sent (FCP and seed ad- -

dresses)
iMidRemoteId long Remote identifier -
iToDeliver long Messages to send -
iImportReject long Rejected during import -
iSeedProcessed long Seed addresses -
iReject long Messages excluded by the rule -
iPropositionCount long Propositions -
iHtml long HTML messages -
20 | Neolane 2013
Neolane datamodel

iText long Text messages -
iMultipart long Multipart messages -
iUrl long Count of tracked URLs -
iToValidate long Messages to validate -
iCtrlGrpReject long Control group exclusions -
iWeightType byte Weight type 0-Constant

1-Depends on the recipient
2-Defined in each rule
iWeight long Delivery weight -
dRate double Handled call rate (in %) -
dDuration double Handled call duration for telephone chan- -

nel
sValidationMode string Approval mode -Manual

-Semi-automatic
-Automatic
iValidationMode byte Approval mode 0-Automatic

1-Manual
-Manual
-Semi-automatic
-Automatic
iDelayed boolean Schedule delivery start -
iWebResPurged boolean Online resources purged -
dDelayExtraction timespan Extraction wait period -
sIPAffinity string IP affinity -
iForecasted boolean Execute during downtime -
sLogin string Execution login -
iMsgPriority byte Priority 0-Low

1-Average
2-High
iSandboxMode byte Delivery mode 0-Target estimation and message person-

alization
1-Estimation and approval of the provision-
al target
2-Target evaluation
iUseBudgetValidation boolean Enable budget approval -
iUseTargetValidation boolean Enable target approval -
iUseContentValidation boolean Enable content approval -
iUseExtractionValidation boolean Enable extraction validation -
iUseFCPValidation boolean Enable the sending and validation of proofs -
iUseTaskCreation boolean Enable the automatic creation of approval -

tasks
iUseLinkedDeliveryValida- boolean Enable validation for associated deliveries -

tion
iDisableNotification boolean Do not enable notification sending -
iAssignEdition boolean Assign content editing -
iExternalValidation boolean External content approval -
iRetry short Number of retries -
iMaxRetry short Max. number of retries -
dRetryPeriod timespan Period of retries -

Neolane

iNeedMirrorPage byte Mirror page usage 0-unknown
1-yes
2-no
3-fromMsgId
iInsertMode byte Insertion mode 0-Respect the sort order

1-At the start of the file
2-At the end of the file
3-Random
iDirty byte Update 0-Up to date

1-Tracking
2-Errors
4-Reset tracking
8-Message counters
iErrorPending long Unqualified errors -
iTrackingPending long Tracking not taken into account -
iProcessed long Processed -
iSent long Sent -
iSuccess long Success -
iSuccessWithoutSeeds long Success excluding seed addresses -
iError long Errors -
iNewQuarantine long New quarantines -
iUnknownUser long Unknown users -
iInvalidDomain long Invalid domains -
iUnreachable long Unreachables -
iDisabled long Deactivated accounts -
iMailboxFull long Mailbox full -
iNotConnected long Not connected -
iRefused long Refused -
iRecipientOpen long Recipients who have opened -
iTotalRecipientOpen long Total count of opens -
iPersonClick long Persons who have clicked -
iRecipientClick long Number of distinct clicks -
iTotalRecipientClick long Total number of clicks -
iForward long Number of forwards -
iMirrorPage long Mirror page -
iOptOut long Opt-Out -
iTransaction long Transactions -
dAmount double Amount -
iArticle long Articles -
iWebPage long Distinct visited visited -
iTotalWebPage long Visited pages -
sMd5 string MD5 key -
sCompressMode string Compression -Screen

-Printing
-Press
iPublicationStatus byte Publication state 0-Not applicable

1-Being edited
2-Published
3-Publication failed
100-(In production)
22 | Neolane 2013
Neolane datamodel

sEventType string Event type -
sNature string Nature -
iUseDce boolean Use the new content editor ('DCE') -
iAnalysisStep byte Current analysis step 0-Starting

1-Delivery ready for analysis
2-Initialization finished
3-Typology rules applied
4-Finished creating working tables for de-
livery analysis
5-Finished preparing the delivery in the
working tables
6-SQL rules applied
7-Limit to delivery recipients applied
8-Items attached to the delivery
9-Finished assigning coupons
10-Finished preparing delivery fragments
11-Delivery logs exported
12-Finished preparing delivery logs
13-Delivery analysis finished
iMessageType byte Channel 0-Email

1-Mobile (SMS)
2-Phone
3-Direct Mail
4-Fax
20-Facebook
25-Twitter
41-iOS channel
42-Android channel
120-Other
iDeliveryMode byte Mode 0-External

1-Bulk delivery
2-Description
4-Mid-sourcing
iState byte State 0-Being edited

11-Targeting pending
12-Counting in progress
13-Arbitration in progress
15-Target ready
21-Personalization pending
22-Personalization in progress
25-Message finalized
37-Personalization or count failed
45-Ready to be delivered
51-Start pending
55-In progress
61-Retry pending
62-Retry in progress
71-Pause requested
72-Pause in progress
75-Paused
81-Stop requested
82-Stop in progress
85-Stopped
87-Failed
95-Finished
100-Deleted
iFCP boolean Send a Proof -
iMidSourcing boolean Mid-sourcing relay -

Neolane

iPriority byte Delivery priority 32-Very High
20-High
15-Higher than normal
10-Normal
5-Low
1-Very Low
sDeliveryCode string Delivery code -
iHasAttachments boolean Add attached files -

1-Yes
2-Recycled
iCommitmentLevel byte Commitment level 0-Planned

1-Reserved
2-Committed
dEstimatedCost double Estimated provisional cost -
dRealCost double Real cost -
dComputedCost double Calculated cost -
iComputationState byte Cost calculation status 0-Not defined

1-Pending calculation
2-Being calculated
3-Calculation finished
dTotalEstimatedRealized double Provisional revenue -
dTotalEstimatedMargin double Provisional margin -
dUnitaryCost double Unit revenue -
dResponseRatio double Response rate -
dUnitaryMargin double Fixed margin -
dPercentMargin double Margin as a percentage -
iMarginType byte Margin type 0-Fixed

1-Percent
iContentStatus byte Content status 0-Being edited

1-Pending approval
2-Approved
3-Rejected
4-Proof pending approval
5-Proof validated
6-Proof rejected
10-Being edited
11-Available
15-External validation pending
16-Rejected by external reviewer
iTargetStatus byte Targeting status 0-Being edited

1-Pending approval
2-Approved
3-Rejected
iBudgetStatus byte Budget status 0-Being edited

1-Pending approval
2-Approved
3-Rejected
iExtractionStatus byte Extraction status 0-Being edited

1-Pending approval
2-Approved
3-Rejected
4-Sent
24 | Neolane 2013
Neolane datamodel

iSandboxStatus byte Status of inclusion in the provisional calen- 0-Being edited
dar 1-Pending approval
2-Approved
3-Rejected
Table keys

iFolderProcessId long Foreign key of link 'Execution folder' (field -

'id')
iDeliveryProviderId long Foreign key of link 'Routing' (field 'id') -
iTypologyId long Foreign key of link 'Typology' (field 'id') -
iMappingId long Foreign key of link 'Delivery mapping' (field -

'id')
iProofedDeliveryId long Foreign key of link 'Parent delivery' (field -

'id')
iOfferSpaceId long Foreign key of link 'Offer space' (field 'id') -
iOfferCategoryId long Foreign key of link 'Category' (field 'id') -
iOfferAnonymousCategory- long Foreign key of link 'Anonymous category' -

Id (field 'id')
sPublishingNamespace string Foreign key of link 'Publication template' -

(field 'namespace')
sPublishingName string Foreign key of link 'Publication template' -

(field 'name')
iDeliveryId long Foreign key of link 'Deliveries' (field 'id') -
iOperationId long Foreign key of link 'Campaign' (field 'id') -
iOwnerOperationId long Foreign key of link 'Operation owned' (field -

'id')
iRoutingDeliveryId long Foreign key of link 'Routing delivery' (field -

'id')
iBudgetId long Foreign key of link 'Charge back' (field 'id') -
iSupplierModelId long Foreign key of link 'Service' (field 'id') -
iLinkedDeliveryId long Foreign key of link 'Main delivery' (field 'id') -
iDeliveryOutlineId long Foreign key of link 'Delivery outline' (field -

'id')
Time fields

tsStart datetime Analysis start -
tsEnd datetime Analysis completed -
tsScenarioModTime datetime Template modification date -
tsContact datetime Contact date -
tsValidity datetime Validity limit -
tsWebValidity datetime Validity limit date for resources -

Neolane

tsExtraction datetime Extraction request -
tsExtracted datetime Extraction date -
tsNextPass datetime Next retry -
tsBroadStart datetime Start date -
tsBroadEnd datetime End date -
tsPassStart datetime Pass start -
tsLastErrorComputation datetime Error update -
tsLastTrackingComputation datetime Tracking update -
tsContentModTime datetime Content modification date -
tsDelete datetime Delete date -
tsLastComputed datetime Last cost calculation date -
tsExpectedTarget date Target approval deadline -
tsExpectedContent date Content approval deadline -
tsExpectedBudget date Budget approval deadline -
tsExpectedExtraction date Extraction approval deadline -
tsExpectedFCP date Proof approval deadline -
tsExpectedForecast date Approval deadline for inclusion in provision- -

al calendar
tsExpectedEdition date Content editing dealine -
tsExpectedExternal date External approval deadline -
tsReminderTarget date Target reminder date -
tsReminderContent date Content reminder date -
tsReminderBudget date Budget reminder date -
tsReminderExtraction date Extraction reminder date -
tsReminderFCP date Proof reminder date -
tsReminderForecast date Reminder date for inclusion in provisional -

calendar
tsReminderEdition date Content editing deadline reminder -
tsReminderExternal date External approval deadline reminder -
XtkFolder
It contains all the folders in the tree visible in the Navigation tab of the console.
The folders are typed: The value of the sModel field specifies the type of data that can be contained in the
folder. This field also enables the client console to display the data correctly with the corresponding forms.
The possible values for this field are defined in the navTree.
The tree is managed by the iParentId and iChildCount fields. The sFullName field gives the full path of
the folder in the tree. Finally, there is a unique index on the field representing the internal name of the
sName folder.
General information

iFolderId long Primary key -
iBuiltIn boolean Native application folder -
sModel string Template -
iUnSelected boolean Unselectable folder -
26 | Neolane 2013
Neolane datamodel

sEntity string Schema of entity of folder -
iChildcount short Number of child nodes -
iOrder short Node position -
iIsView boolean This folder is a view -
iSystem boolean System folder -
sFullName string Full name -
Table keys

sImageNamespace string Foreign key of link 'Image' (field -

'namespace')
sImageName string Foreign key of link 'Image' (field 'name') -
iOrgUnitId long Foreign key of link 'Organizational entity' -

(field 'id')
iParentId long Foreign key of link 'Parent' (field 'id') -
Time fields


Neolane

Delivery and tracking
NmsBroadLogMsg
This table matches the nms:broadLogMsg schema.
It is an extension of the delivery log table.
General information

iBroadLogMsgId long Primary key -
sMd5 string Message MD5 -
sText string Text -
sFirstAddress string First address -
sFirstText string First text -
iFailureType byte Failure type 0-Not defined

1-Soft
2-Hard
3-Ignored
28 | Neolane 2013
Neolane datamodel

iFailureReason byte Reason 0-Not defined
1-User unknown
2-Invalid domain
3-Unreachable
4-Account disabled
5-Mailbox full
6-Not connected
20-Refused
25-Error ignored
7-Address not specified
8-Blacklisted address
9-Address in quarantine
10-Double
11-Excluded by a SQL rule
12-Excluded after arbitration
13-Delivery canceled
14-Bad-quality address
15-Unqualified address
16-Not eligible for the offers
17-Target limited in size
127-Control address
iQualifStatus byte Qualification status 0-To qualify

1-Keep
2-Ignore
Table keys

iRuleId long Foreign key of link 'Typology rule' (field -
'id')
Time fields


Neolane

Simulation and delivery
30 | Neolane 2013
Neolane datamodel
Communication consistency and capacity rules
NmsTypologyRule
This table matches the nms:typologyRule schema.
It contains the rules which apply to deliveries depending on typologies.
General information

iTypologyRuleId long Primary key -

1-Mobile (SMS)
2-Phone
3-Direct Mail
4-Fax
20-Facebook
25-Twitter
41-iOS channel
42-Android channel
120-Other
127-All channels
iActive boolean Active -
iBuiltIn boolean Application built-in rule -
sRuleType string Rule type -Filtering

-Control

Neolane

sRuleStep string Phase -At the start of targeting
-After targeting
-At the start of personalization
-At the end of the analysis
iOrder long Execution order -
iForceOnPrepareMessage boolean Re-apply the rule at the start of personal- -

ization
dValidity timespan Frequency -
Table keys

iFolderId long Foreign key of link 'Rule folder' (field 'id') -
Time fields

NmsTypology
This table matches the nms:typology schema.
It contains the set of rules to be applied to deliveries which match the typology.
General information

iTypologyId long Primary key -
iType byte Type 0-Standard

1-Filtering
sIPAffinity string IP affinity -
Table keys

Time fields

32 | Neolane 2013
Neolane datamodel

NmsTypologyRuleRel
This table matches the nms:typologyRuleRel schema.
It contains the relationships between typologies and their rules.
Table keys

iTypologyId long Foreign key of link 'Typology' (field 'id') -
iRuleId long Foreign key of link 'Typology rule' (field -

'id')
Response management

Neolane
Campaign management
NmsOperation
This table matches the nms:operation schema. It contains the data of marketing campaigns.
General information

iOperationId long Primary key -
iBuiltIn boolean Application built-in model -
iIsModel boolean Model -
iCancelState byte Cancel status 0-Not defined

3-Cancel in progress
4-Canceled
iType byte Campaign type 0-Unique

1-Recurring
2-Periodic
iMessageType byte Main channel 0-Email

1-Mobile (SMS)
2-Phone
3-Direct Mail
4-Fax
20-Facebook
25-Twitter
41-iOS channel
42-Android channel
120-Other
127-(Non-specified)
dDuration timespan Campaign duration -
dPeriodCovered timespan Created in advance for -
34 | Neolane 2013
Neolane datamodel

iPriority byte Priority 0-Low

1-Average
2-High

1-Reserved
2-Committed

2-Being calculated
iBudgetStatus byte Process status 0-Being edited

1-Defined
2-Carried out
dFixedCost double Fixed cost -
iUseBudget boolean Expenses and objectives -
iUseTask boolean Tasks -
iUseBudgetValidation boolean Enable budget approval -
iUseTargetValidation boolean Enable target approval -
iUseContentValidation boolean Enable content approval -
iUseExtractionValidation boolean Enable extraction validation -
iUseFCPValidation byte Enable the sending and validation of proofs -
iUseTaskCreation boolean Enable the automatic creation of approval -

tasks
iUseLinkedDeliveryValida- boolean Enable validation for associated deliveries -

tion
iDisableNotification boolean Do not enable notification sending -
iValidationMode byte Approval mode 0-Automatic

1-Manual
iSandboxMode byte Delivery mode 0-Target estimation and message person-

alization
1-Estimation and approval of the provision-
al target
2-Target evaluation
iAssignEdition boolean Assign content editing -
iExternalValidation boolean External content approval -
Table keys

iOwnerId long Foreign key of link 'Assigned to' (field 'id') -
iBudgetId long Foreign key of link 'Charge' (field 'id') -
iLinkedOperationId long Foreign key of link 'Linked campaign' (field -

'id')

Neolane

iProgramId long Foreign key of link 'Program' (field 'id') -
iProgramProcessId long Foreign key of link 'Execution program' -

(field 'id')
iFcpGroupId long Foreign key of link 'Proof group' (field 'id') -
Time fields

tsStart date Start -
tsEnd date End -
NmsDeliveryOutline
This table matches the nms:deliveryOutline schema. It contains the extended properties of the delivery
(delivery outline).
General information

iDeliveryOutlineId long Primary key -

1-Mobile (SMS)
2-Phone
3-Direct Mail
4-Fax
20-Facebook
25-Twitter
41-iOS channel
42-Android channel
120-Other
127-All channels
Table keys

NmsDlvOutlineItem
This table matches the nms:dlvOutlineItem schema. It contains the articles of a delivery outline.
General information

iDlvOutlineItemId long Primary key -
36 | Neolane 2013
Neolane datamodel

iType byte Type 0-Item

1-Personalization fields
2-Resource
3-Offer
Table keys

iAssetId long Foreign key of link 'Marketing resource' -
(field 'id')
iOfferId long Foreign key of link 'Marketing offer' (field -

'id')

'id')
NmsDeliveryCustomization
This table matches the nms:deliveryCustomization schema. It contains the personalization fields of a
delivery.
General information

iDeliveryCustomizationId long Primary key -
iType byte Type 6-Text

3-Integer
5-Floating point
7-Date+Time
sValue string Value -
Table keys

iDlvOutlineItemId long Foreign key of link 'Delivery outline item' -
(field 'id')

'id')
NmsBudget
This table matches the nms:budget schema. It contains the data of a budget on a campaign, a plan, a
program, a task and/or deliveries.

Neolane
General information

iBudgetId long Primary key -
dAllocated double Allocated -
dExpensed double Spent -
dInvoiced double Invoiced -
dReserved double Reserved -
dPlanned double Planned -
dCommitted double Committed -
Table keys

iCurrencyId long Foreign key of link 'Currency' (field 'id') -
iAttachedBudgetId long Foreign key of link 'Related budget' (field -

'id')
Time fields

tsStart date Start -
tsEnd date End -
NmsDocument
This table matches the nms:document schema. It contains the marketing documents of the campaign in
the form of files (images, excel or word files, etc.)
General information

iDocumentId long Primary key -
sNature string Document nature -
sOriginalName string Original name -
sContentType string Content-Type -
38 | Neolane 2013
Neolane datamodel

iStorageType byte Storage type 255-In memory
0-Database
1-Download folder
2-Working directory
3-Export directory
4-Image directory
5-Published on frontal servers
6-Publications folder
sFileName string File name -
sOriginalServer string Server name -
iUseMd5AsFilename boolean Unique file name -
sVersion string Document version -
iWidth long Width -
iHeight long Height -
sAlt string Substitute text -
iPublish boolean Publish file -
iResourceType byte Resource type 0-File

1-HTML
2-Text
5-URL
6-Content Management
Table keys

iContainerId long Foreign key of link 'Delivery (attachments)' -

(field 'id')
iPlanId long Foreign key of link 'Plan' (field 'id') -
iDeliveryId long Foreign key of link 'Delivery' (field 'id') -
iTaskId long Foreign key of link 'Task' (field 'id') -
iContentId long Foreign key of link 'Content' (field 'id') -
iNewsgroupId long Foreign key of link 'Discussion forum' (field -

'id')
Time fields

XtkWorkflow
This table matches the xtk:workflow schema. It contains campaign targeting.

Neolane
General information

iWorkflowId long Primary key -
sTimezone string Time zone -
iInProcess boolean Execute inside the engine -
iHistory long History in days -
iOnError byte In case of error 0-Suspend the process

1-Ignore
iErrorLimit long Consecutive errors -
sForm string List+Detail form -
sNextProcessingAfn string Affinity of the next task -
sNextProcessingHost string Next processing host -
iStatus byte Real status 0-Not started

1-In progress
3-Suspended
4-Stop in progress
5-Finished
iProduction boolean Production -
iFailed boolean Failed -
iUnlockedCount long Unlocked count -
iState byte State 0-Being edited

9-Request to start in simulation mode
10-Start requested
11-Started
12-Pause requested
13-Paused
14-Resume requested
15-Stop requested
16-Stop in progress
17-Restart requested
18-Restarting
20-Finished
iProcessId long Process (PID) -
sHostname string Execution server -
iPort long Port -
iStartState byte Start state 0-Not defined

1-Pending start
iPriority byte Priority 0-Low

1-Average
2-High
iOrder long Order -
40 | Neolane 2013
Neolane datamodel

iRecurrentMdl boolean Recurring workflow template -
Table keys

iSupervisorId long Foreign key of link 'Supervisor(s)' (field -

'id')
iFolderProcessId long Foreign key of link 'Execution folder' (field -

'id')
iRoutingOperationId long Foreign key of link 'Routing campaign' -

(field 'id')
iAggregateId long Foreign key of link 'Aggregate' (field 'id') -
Time fields

tsLastStart datetime Last start -
tsNextProcessing datetime Next processing -
tsProcess datetime Last processing -
tsExpiration datetime Expiration date -
NmsTask
This table matches the nms:task schema. It contains the definition of a marketing task.
General information

iTaskId long Primary key -
iStatus byte State 0-Being edited

1-Scheduled
2-In progress
3-Finished
4-Canceled
5-Pending approval
6-Finished
7-Rejected
iType byte Type 0-Task

1-Checkpoint
2-Grouping task
3-Notification
4-Marketing resources

Neolane

iProgress long Progress (as a %) -
iPriority byte Priority 3-Very High

2-High
1-Normal
0-Low
iValidationType byte Approval type 0-Target validation

1-Content validation
2-Budget validation
3-Approval of extraction file
4-Proof validation
5-Approval of inclusion in the provisional
calendar
6-Available content
7-External content approval
iValidationState byte Approval status 0-Not defined

1-Approved
2-Rejected
dStartDelay timespan Start -
dDuration timespan Duration -
dExecutionDelay timespan Execution -
iFromOperationEndDate boolean From the campaign end date -
dRealizedDuration timespan Workload performed -
dPlannedDuration timespan Workload planned -
iUseTaskValidation boolean enable task approval -
dInitialDelay timespan Initial notification -
iUseAssetPublication boolean Publish the marketing resource -

1-Reserved
2-Committed

2-Being calculated
dUnitaryCost double Unit revenue -
Table keys

iAlertAssigneeId long Foreign key of link 'Warning group' (field -

'id')
iBudgetId long Foreign key of link 'Charge' (field 'id') -
42 | Neolane 2013
Neolane datamodel

iSupplierModelId long Foreign key of link 'Service' (field 'id') -
iDependingTaskId long Foreign key of link 'Depends on' (field 'id') -
iLinkedTaskId long Foreign key of link 'Linked to' (field 'id') -
iAssetId long Foreign key of link 'Marketing resource' -

(field 'id')
iFolderProcessId long Foreign key of link 'Instances folder' (field -

'id')
iProgramId long Foreign key of link 'Program' (field 'id') -
Time fields

tsStart datetime Start -
tsEnd datetime End -
tsExecution datetime Execution date -
tsCompleted datetime End of execution -
tsReminder datetime Reminder date -
tsInitial datetime Initial notification date -
tsInitialExecution datetime Executed initial notification date -
tsAlertExecution datetime Executed warning notification date -
tsExpectedValidation date Approval deadline -
NmsAsset
This table matches the nms:asset schema. It contains the definition of a marketing resource.
General information

iAssetId long Primary key -
sNature string Document nature -
sOriginalName string Original name -
sContentType string Content-Type -
iStorageType byte Storage type 255-In memory

0-Database
1-Download folder
2-Working directory
3-Export directory
4-Image directory
5-Published on frontal servers
6-Publications folder

Neolane

sFileName string File name -
sOriginalServer string Server name -
iUseMd5AsFilename boolean Unique file name -
sVersion string Document version -
iWidth long Width -
iHeight long Height -
sAlt string Substitute text -
iPublish boolean Publish file -
iResourceType byte Resource type 0-File

1-HTML
2-Text
5-URL
6-Content Management

1-Pending approval
2-Approval in progress
3-Approved
4-Rejected
5-Pending publication
6-Publication in progress
7-Published
8-Cancelled
iLanguage byte Language 0-Not defined

1-French
2-English
3-German
Table keys

iContainerId long Foreign key of link 'Delivery (attachments)' -

(field 'id')

'id')
iEditedById long Foreign key of link 'Owner' (field 'id') -
iProofReaderId long Foreign key of link 'Proof reader' (field 'id') -
iWorkflowId long Foreign key of link 'Post-processing' (field -

'id')
Time fields

44 | Neolane 2013
Neolane datamodel

tsPublication datetime Publication date -
tsCheckOut datetime Check-out date -
tsExpectedCheckIn datetime Planned check-in date -
tsAvailability date Availability date -
tsExpiration date Expiry date -
tsExpectedValidation date Approval deadline -
tsExpectedPublication date Publication deadline -
tsReminder date Reminder date -
Interaction Module
NmsOffer
This table matches the nms:offer schema.
It contains the definition of each marketing offer.
General information

iOfferId long Primary key -
iEligibilityStatus byte Eligibility status 0-Being edited

1-Pending approval
3-Approved
4-Refused
5-Disabled
6-Online
7-Pending deployment
iContentStatus byte Content status 0-Being edited

1-Pending approval
3-Approved
4-Refused
5-Disabled
6-Online
7-Pending deployment
sCode string Offer code -
iBuiltIn boolean Native application offer -
sTargetSchema string Targeting dimension -
Table keys


Neolane

iCategoryId long Foreign key of link 'Category' (field 'id') -
Time fields

tsEligibilityValidation datetime Date on which eligibility was approved -
tsContentValidation datetime Content approval date -
tsStart datetime Start date -
tsEnd datetime End date -
tsProduction datetime Deployment date -
tsExpectedEligibility date Eligibility approval deadline -
tsReminderEligibility date Reminder date -
tsExpectedContent date Content approval deadline -
tsReminderContent date Reminder date -
NmsPropositionRcp
This table matches the nms:propositionRcp schema.
It contains the cross-channel log of marketing propositions sent to each individual. The record is created
when a proposition is prepared or effectively made to an individual.
General information

iPropositionId long Primary key -
iInteractionId long Interaction ID -
dWeight double Weight -
iRank byte Ranking -
iStatus byte Status 0-Generated

1-Presented
2-Interested
3-Accepted
4-Scheduled
5-Rejected
99-Control group
iEngineType byte Engine type 0-Batch engine

1-Unitary engine
Table keys

iOfferId long Foreign key of link 'Offer' (field 'id') -
iOfferSpaceId long Foreign key of link 'Offer space' (field 'id') -
46 | Neolane 2013
Neolane datamodel

Time fields

tsEvent datetime Event date -
NmsOfferSpace
This table matches the nms:offerSpace schema.
It contains the definition of locations on which propositions are made.
General information

iOfferSpaceId long Primary key -
iChannel byte Channel 0-Email

1-Mobile (SMS)
2-Phone
3-Direct Mail
4-Fax
20-Facebook
25-Twitter
41-iOS channel
42-Android channel
120-Other
50-Inbound Web
51-Inbound call center
iDefaultStatus byte Default status 0-Generated

1-Presented
2-Interested
3-Accepted
4-Scheduled
5-Rejected
99-Control group
iDefaultUpdateStatus byte Default value of the status when accepted 0-Generated

1-Presented
2-Interested
3-Accepted
4-Scheduled
5-Rejected
99-Control group
iDisablePropositionStorage boolean Disable the inserting of propositions -
sRandomizeAlternativeCon- string Randomly display alternative content -

tents
iUseTargetScript boolean Overload the target data load script -
iUseBuildPropositionsScript boolean Overload the proposition selection script -
iUseXmlFunction boolean Overload the XML rendering function -
iUseHtmlFunction boolean Overload the HTML rendering function -

Neolane

iUseTextFunction boolean Overload the text rendering function -
Table keys

iEnvId long Foreign key of link 'Environment' (field 'id') -
Time fields

tsDeployment datetime Deployment date -
NmsOfferView
This table matches the nms:offerView. It contains the offer representations.
General information

iOfferViewId long Primary key -

1-Pending approval
3-Approved
4-Refused
5-Disabled
6-Online
Table keys

iOfferId long Foreign key of link 'Offer' (field 'id') -
iSpaceId long Foreign key of link 'Offer space' (field 'id') -
Time fields

tsPublication datetime Publication date -
48 | Neolane 2013
Neolane datamodel

NmsOfferCategory
This table matches the nms:offerCategory. It contains the offer categories.
General information

Table keys


'namespace')

(field 'id')
iEnvId long Foreign key of link 'Environment' (field 'id') -
Time fields

tsProduction datetime Production deployment date -
NmsOfferEnv
This table matches the nms:offerEnv. It contains the offer environments.

Neolane
General information

iLive boolean Live -
sInputSchema string Call data schema -
Table keys


'namespace')

(field 'id')
iProdEnvId long Foreign key of link 'Live environment' (field -

'id')
Time fields

50 | Neolane 2013
Neolane datamodel

Message Center Module
NmsRtEvent
Figure 1.1.
This table matches the nms:rtEvent schema.

It contains a definition of real time events.
General information

iRtEventId long Primary key -
iStatus byte Status 0-Pending

1-Pending delivery
2-Sent
11-Ignored by the delivery
12-Delivery error
13-Event not covered
iRetry byte Number of errors -
sType string Event type -
iWishedChannel byte Channel 0-Email

1-Mobile (SMS)
2-Phone
3-Direct Mail
4-Fax
20-Facebook
25-Twitter
41-iOS channel
42-Android channel
120-Other

Neolane

iEmailFormat byte Email format 0-Unknown

1-Text
2-HTML
sMobilePhone string Mobile number -
sRegistrationToken string Registration token -
sLine1 string Line 1 -

2-2 - Empty street
Table keys

iDeliveryId long Foreign key of link 'Template' (field 'id') -
iMobileAppId long Foreign key of link 'Mobile application' -

(field 'id')
Time fields

tsSubmit datetime Submitted on -
tsScheduled datetime Process requested on -
tsExpiration datetime Expired on -
tsCreated datetime Created on -
tsProcessing datetime Process started on -
tsProcessed datetime Processed on -
tsLastModified datetime Modified on -
52 | Neolane 2013
Neolane datamodel

NmsBatchEvent
Figure 1.2.
This table matches the nms:batchEvent schema.

It contains the definition of events by batch.
General information

iBatchEventId long Primary key -
iStatus byte Status 0-Pending

1-Pending delivery
2-Sent
11-Ignored by the delivery
12-Delivery error
13-Event not covered
iRetry byte Number of errors -
sType string Event type -
iWishedChannel byte Channel 0-Email

1-Mobile (SMS)
2-Phone
3-Direct Mail
4-Fax
20-Facebook
25-Twitter
41-iOS channel
42-Android channel
120-Other

Neolane

iEmailFormat byte Email format 0-Unknown

1-Text
2-HTML
sMobilePhone string Mobile number -

2-2 - Empty street
Table keys

iDeliveryId long Foreign key of link 'Template' (field 'id') -

(field 'id')
Time fields

tsSubmit datetime Submitted on -
tsScheduled datetime Process requested on -
tsExpiration datetime Expired on -
tsCreated datetime Created on -
tsProcessing datetime Process started on -
tsProcessed datetime Processed on -
tsLastModified datetime Modified on -
54 | Neolane 2013
Neolane datamodel

Social Marketing Module
NmsVisitor
This table matches the nms:visitor schema. It contains the information on visitors.
General information

iVisitorId long Primary key -
sLastName string Name -
sFirstName string First name -
iDeliveryId long Identifier of the last delivery -
iRecipientId long Recipient identifier -
iReferrerId long Referrer identifier -
sReferrerLastName string Referrer last name -
sReferrerFirstName string Referrer first name -
sReferrerEmail string Referrer email -
sForwardUrl string Forward url -
sExternalId string External ID -
iOrigin byte Origin 0-Undefined

2-Facebook
3-Twitter
sScreenName string Username -
sName string Full name -
sPicture string Image -
sTimezone string Time zone -

Neolane

sLang string Language -
iGender byte Gender 0-None specified

1-Male
2-Female
sLocation string Location -
iFriendCount long Number of friends -
iVerified boolean Checked -
sSignInCountryCode string Sign in country code -
Table keys

iWebAppId long Foreign key of link 'Web application' (field -
'id')
Time fields

tsTokenExpiration datetime Token expiration date -
tsLastSynchronized datetime Last synchronized on -
tsBirth date Birth date -
NmsVisitorSub
This table matches the nms:visitorSub schema. It enables you to link up a visitor to the services which
they have subscribed to (Twitter or Facebook).
Table keys

iVisitorId long Foreign key of link 'Visitor' (field 'id') -
Time fields

tsCreated datetime Subscription date -
NmsFriendShipRel
This table matches the nms:friendshipRel schema. It enables you to link up visitors with their friends
within the context of the Facebook service.
56 | Neolane 2013
Neolane datamodel
Table keys

iFriendOfId long Foreign key of link 'Visitor' (field 'id') -
iFriendId long Foreign key of link 'Friend' (field 'id') -
NmsVisitorInterestRel
This table matches the nms:visitorInterestRel schema. It enables you to link up visitors and their interests.
General information

iVisitorInterestRelId long Primary key -
iActionType byte Activity 0-Uses

1-Likes
2-Listens to
3-Watches
4-Reads
5-Checks in
6-Visits
7-Installs
8-Comments
9-Liked deliveries
iCountLikes long Number of Likes -
iCountComments long Number of comments -
Table keys

iVisitorId long Foreign key of link 'Visitor' (field 'id') -
iInterestId long Foreign key of link 'Main interests' (field -

'id')
iMadeById long Foreign key of link 'Provided by' (field 'id') -
Time fields

tsStartTime datetime Start date -
tsEndTime datetime End date -
tsPublishTime datetime Publication date -
NmsInterest
This table matches the nms:interest schema. It contains the list of interests for each visitor.

Neolane
General information

iInterestId long Primary key -
sExternalId string External ID -
iOrigin byte Origin 0-Undefined

2-Facebook
3-Twitter
sUrl string url -
Microsites Module
NmsTrackingUrl
This table matches the nms:trackingUrl schema.
General information

iTrackingUrlId long Primary key -
sTagId string Identifier -
sSource string Source URL -
iOccurrence short Occurrence index -
iChecksum long CRC32 -
iWithParams boolean Customizable -
58 | Neolane 2013
Neolane datamodel

iType byte Type 0-Not defined
1-Email click
2-Open
3-Opt-out
4-Web
5-Transaction
6-Mirror page
7-Facebook Link
8-Facebook Action
9-Twitter Link
10-Click on mobile notification
11-Proposition update
iStep byte Stage -
sGoal string Objective -
sTrackerName string Name of the tracker -
Table keys

iFolderId long Foreign key of link 'Tag folder' (field 'id') -
iPurlId long Foreign key of link 'pURL' (field 'id') -
Time fields

tsValidity date Validity limit -
NmsPurl
This table matches the nms:purl schema.
General information

iPurlId long Primary key -
iBuiltIn boolean Native pURL template -
iIsCaseSensitive boolean Case sensitive -
sDomain string Domain name -
sSubDomain string Sub-domain name -
sPath string Site name -
sUrlTemplate string URL format -
sSchema string Recipient schema -
sGuestIdExpr string Guest ID personalization -
sGuestCodeExpr string Guest code personalization -
dValidityDuration timespan Expiration date of the pURL Code -

Neolane

sUrl string URL -
iProtocol byte Protocol 0-Non-secure (http)

1-Secure (https)
2-Secure and non-secure
Table keys


'id')
iWebAppId long Foreign key of link 'Microsite' (field 'id') -
iOriginId long Foreign key of link 'Traffic source' (field -

'id')
iModelId long Foreign key of link 'pURL template' (field -

'id')
Time fields

NMAC Module
NmsMobileApp
This table matches the nms:mobileApp schema. It contains the mobile applications defined in Neolane.
General information

iMobileAppId long Primary key -
sUuid string Integration key -
sImg string Application icon -
iPushPlatform byte Target platform 0-Apple

1-Android
sPassword string Password -
sSenderId string Project key -
60 | Neolane 2013
Neolane datamodel

iSandbox boolean Development -
Table keys

iServiceId long Foreign key of link 'service' (field 'id') -
NmsAppSubscriptionRcp
This table matches the nms:appSubscriptionRcp schema. It enables you to link up visitors who subscribed
to an application with the recipients table.
General information

iAppSubscriptionRcpId long Primary key -
sUserKey string User ID -
iDisabled boolean Disabled -
sDeviceId string ID -
sDeviceName string Name -
sSystemName string Name -
sDeviceModel string Template -
sDeviceBrand string Brand -
sDeviceManufacturer string Constructor -
sSystemVersion string Version -
sSystemLanguage string Language -
dLatitude double Latitude -
dLongitude double Longitude -
dAltitude double Altitude -
Table keys


(field 'id')
Time fields

tsRegistration datetime Registration date -
tsDisabled datetime De-activation date -
tsLastUpdate datetime Last saved -

Neolane

NmsExcludeLogAppSubRcp
This table matches the nms:excludeLogAppSubRcp schema.
General information

iBroadLogId long Primary key -
sAddress string Address -
iStatus byte Status 127-Non applicable

0-Ignored
1-Sent
2-Failed
3-Taken into account by the service pro-
vider
5-Received on mobile
6-Pending
7-Delivery canceled
8-Prepared
9-Sent to the service provider
iFlags byte Extended message flags -
Table keys

iMsgId long Foreign key of link 'Message' (field 'id') -
iAppSubscriptionId long Foreign key of link 'Subscriber applications' -

(field 'id')
Time fields

NmsTrackingLogAppSubRcp
This table matches the nms:trackingLogAppSubRcp schema.
General information

iTrackingLogId long Primary key -
sSourceId string Requester UUID -
sSourceType string Requester type -
iUserAgent long Browser -
62 | Neolane 2013
Neolane datamodel

sExternalId string External Id -
Table keys

iUrlId long Foreign key of link 'Url' (field 'id') -
iBroadLogId long Foreign key of link 'Message' (field 'id') -

(field 'id')
iRecipientId long Foreign key of link 'Recipients' (field 'id') -
Time fields

tsLog datetime Date -
NmsBroadLogAppSubRcp
This table matches the nms:broadLogAppSubRcp schema.
General information

iBroadLogId long Primary key -
sAddress string Address -
iStatus byte Status 127-Non applicable

0-Ignored
1-Sent
2-Failed
3-Taken into account by the service pro-
vider
5-Received on mobile
6-Pending
7-Delivery canceled
8-Prepared
9-Sent to the service provider
iFlags byte Extended message flags -
Table keys

iMsgId long Foreign key of link 'Message' (field 'id') -

(field 'id')

Neolane

iRecipientId long Foreign key of link 'Recipients' (field 'id') -
Time fields

64 | Neolane 2013
CHAPTER 2
Schema Reference
(xtk:srcSchema)
Table of Contents
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Syntax of schemas . . . . . . . . . . . . . . . . . . . . . . . . . 66
Identification of a schema . . . . . . . . . . . . . . . . . . . . . . 67
Schema structure . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Description . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Data types . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Collections . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Referencing with XPath . . . . . . . . . . . . . . . . . . . . . . . 73
Building a string via the compute string . . . . . . . . . . . . . . . . . 74
Database mapping . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Description . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
XML fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Calculated fields . . . . . . . . . . . . . . . . . . . . . . . . . 76
Indexed fields . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Management of keys . . . . . . . . . . . . . . . . . . . . . . . . 77
Links: relation between tables . . . . . . . . . . . . . . . . . . . . . 80
Dictionary of elements and attributes . . . . . . . . . . . . . . . . . . . 83
<attribute> element . . . . . . . . . . . . . . . . . . . . . . . . 83
<compute-string> element . . . . . . . . . . . . . . . . . . . . . . 87
<condition> element . . . . . . . . . . . . . . . . . . . . . . . . 88
<dbindex> element . . . . . . . . . . . . . . . . . . . . . . . . 89
<element> element . . . . . . . . . . . . . . . . . . . . . . . . 91
<enumeration> element . . . . . . . . . . . . . . . . . . . . . . . 96
<help> element . . . . . . . . . . . . . . . . . . . . . . . . . 98
<join> element . . . . . . . . . . . . . . . . . . . . . . . . . . 99
<key> element . . . . . . . . . . . . . . . . . . . . . . . . . 100
<keyfield> element . . . . . . . . . . . . . . . . . . . . . . . . 102
<method> element . . . . . . . . . . . . . . . . . . . . . . . . 103
<methods> element . . . . . . . . . . . . . . . . . . . . . . . 105
<param> element . . . . . . . . . . . . . . . . . . . . . . . . 106
<parameters> element . . . . . . . . . . . . . . . . . . . . . . . 108
<srcSchema> element . . . . . . . . . . . . . . . . . . . . . . . 109
<sysFilter> element . . . . . . . . . . . . . . . . . . . . . . . . 111
<value> element . . . . . . . . . . . . . . . . . . . . . . . . . 112
Neolane v6.1 - Configuration Guide - Schema Reference (xtk:srcSchema) | 65

Neolane
Introduction
This chapter describes how to configure extension schemas in order to extend the conceptual data model
of the Neolane database.
Overview
The physical and logical structure of the data carried in the application is described in XML. It obeys a grammar
specific to Neolane, called a schema.
A schema is an XML document associated with a database table. It defines data structure and describes the
SQL definition of the table:
n The name of the table,
n Fields,
n Indexes,
n Links with other tables,
It also describes the XML structure used to store data:
n Elements and attributes,
n Hierarchy of elements,
n Element and attribute types,
n Default values,
n Labels, descriptions, and other properties.
Schemas enable you to define an entity in the database. There is a schema for each entity.
The following illustration shows the location of schemas in the Neolane data system:
Syntax of schemas
The root element of the schema is <srcSchema>. It contains the <element> and <attribute>
sub-elements.
The first <element> sub-element coincides with the root of the entity.
<srcSchema name="recipient" namespace="cus">
<element name="recipient">
<attribute name="lastName"/>
<attribute name="email"/>
<element name="location">
<attribute name="city"/>
</element>
</element>
</srcSchema>
66 | Neolane 2013
Schema Reference (xtk:srcSchema)
Note:
The root element of the entity has the same name as the schema.
The <element> tags define the names of entity elements. <attribute> tags of the schema define the
names of the attributes in the <element> tags which they have been linked to.
Identification of a schema
A data schema is identified by its name and its namespace.
A namespace lets you group a set of schemas by area of interest. For example, the cus namespace is used
for customer-specific configuration (customers).
Warning:
As a standard, the name of the namespace must be concise and must contain only authorized characters in
accordance with XML naming rules.
Identifiers must not begin with numeric characters.
Certain namespaces are reserved for descriptions of the system entities required for the operation of the
Neolane application:
n xtk: concerning platform system data,
n nl: concerning the overall use of the application,
n nms: concerning delivery (recipient, delivery, tracking, etc.),
n ncm: concerning content management,
n temp: reserved for temporary schemas.
The identification key of a schema is a string built using the namespace and the name separated by a colon;
for example: cus:recipient.

Neolane
Schema structure
The basic structure of an <srcSchema> is as follows:
<srcSchema>
<enumeration>
... //definition of enumerations
</enumeration>
<element> //definition of the root <element> (mandatory)
<compute-string/> //definition of a compute-string

<dbindex>
... //definition of indexes
</dbindex>
<key>
... //definition of keys
</key>
<sysFilter>
... //definition of filters
</sysFilter>
<attribute>
... //definition of fields
</attribute>
<element> //definition of sub-<element>

<attribute> //(collection, links or XML)
... //and additional fields
</attribute>
...
</element>
</element>
<methods> //definition of SOAP methods

<method>
...
</method>
...
</methods>
</srcSchema>
The XML document of a data schema must contain the <srcSchema> root element with the name and
namespace attributes to populate the schema name and its namespace.
<srcSchema name="schema_name" namespace="namespace">
...
</srcSchema>
Let us use the following XML content to illustrate the structure of a data schema:
<recipient email="John.doe@aol.com" created="2009/03/12" gender="1">
<location city="London"/>
</recipient>
With its corresponding data schema:

<attribute name="created"/>
<attribute name="gender"/>
</element>
</element>
</srcSchema>
68 | Neolane 2013
Description
The point of entry of the schema is its main element. It is easy to identify because it has the same name as
the schema, and it should be the child of the root element. The description of the content begins with this
element.
In our example, the main element is represented by the following line:
The elements <attribute> and <element> that follow the main element enable you to define the locations
and names of the data items in the XML structure.
In our sample schema, these are:
<attribute name="created"/>
<attribute name="gender"/>
</element>
The following rules must be adhered to:

n Each <element> and <attribute> must be identified by name via the name attribute.
Warning:
The name of the element should be concise, preferably in English, and include only authorized characters
in accordance with XML naming rules.
n Only <element> elements can contain <attribute> elements and <element> elements in the XML
structure.
n An <attribute> element must have a unique name within an <element>.
n The use of <elements> in multi-line data strings is recommended.
Data types
The data type is entered via the type attribute in the <attribute> and <element> elements.
A detailed list is available in the description of the <attribute> element [page 83] and the <element> element
[page 91]
When this attribute is not populated, string is the default data type unless the element contains child
elements. If it does, it is used only to structure the elements hierarchically (<location> element in our
example).
The following data types are supported in schemas:
n string: character string. Examples: a first name, a town, etc.
The size can be specified via the length attribute (optional, default value "255").
n boolean: Boolean field. Example of possible values: true/false, 0/1, yes/no, etc.
n byte, short, long: integers (1 byte, 2 bytes, 4 bytes). Examples: an age, an account number, a number
of points, etc.
n double: double-precision floating point number. Examples: a price, a rate, etc.
n date, datetime: dates and dates + times. Ecamples: a birth date, a purchase date, etc.
n timespan: durations. Example: seniority.
n memo: long text fields (multiple lines). Examples: a description, a comment, etc.
n uuid: "uniqueidentifier" fields to support a GUID (supported in SQL Server only).
Note:
To contain a uuid field in engines other than SQL Server, the "newuuid()" function must be added and
completed with its default value.
Here is our example schema with the types entered:

Neolane

<attribute name="email" type="string" length="80"/>
<attribute name="created" type="datetime"/>
<attribute name="gender" type="byte"/>
<attribute name="city" type="string" length="50"/>
</element>
</element>
</srcSchema>
Mapping the types of Neolane/DBMS data

The table below lists the mappings for the types of data generated by Neolane for the different database
management systems.
Neolane PosgreSQL Oracle Teradata DB2 MS SQL
String VARCHAR(255) VARCHAR2 VARCHAR (VARCHAR VARCHAR VARCHAR

(NVARCHAR2 if uni- CHARACTER SET (NVARCHAR if uni-
code) UNICODE if Unicode) code)
Boolean SMALLINT NUMBER(3) NUMERIC(3) SMALLINT TINYINT
Byte SMALLINT NUMBER(3) NUMERIC(3) SMALLINT TINYINT
Short SMALLINT NUMBER(5) SMALLINT SMALLINT SMALLINT
Double DOUBLE PRECISION FLOAT FLOAT DOUBLE FLOAT
Long INTEGER NUMBER(10) INTEGER INTEGER INT
Int64 BIGINT NUMBER(20) NUMERIC(20) BIGINT BIGINT
Date DATE DATE TIMESTAMP DATE DATETIME
Time TIME FLOAT TIME TIME FLOAT
Datetime TIMESTAMPZ DATE TIMESTAMP TIMESTAMP DATETIME
Timespan DOUBLE PRECISION FLOAT FLOAT DOUBLE FLOAT
Memo TEXT CLOB (NCLOB if Uni- CLOB (CLOB CHARAC- CLOB(6M) TEXT (NTEXT if Uni-
code) TER SET UNICODE if code)
Unicode)
Blob BLOB BLOB BLOB BLOB(4M) IMAGE
Properties
The <elements> and <attributes> elemtns of the data schema can be enriched with various properties.
You can populate a label in order to describe the current element.
Labels and descriptions

n The label property lets you enter a brief description.
Note:
The label is associated with the current language of the instance.
Example:
<attribute name="email" type="string" length="80" label="Email"/>
The label can be seen from the Neolane client console input form:
n The desc property lets you enter a long description.

The description can be seen from the input form in the status bar of the Neolane client console main
window.
70 | Neolane 2013
Note:
The description is associated with the current language of the instance.
Example:
<attribute name="email" type="string" length="80" label="Email" desc="Email of
recipient"/>
Default values
The default property lets you define an expression returning a default value on content creation.
The value must be an expression compliant with XPath language. For more on this, refer to Referencing with
XPath [page 73].
Example:
n Current date: default="GetDate()"
n Counter: default="'FRM'+CounterValue('myCounter')"
In this example, the default value is constructed using the concatenation of a string and calling the
CounterValue function with a free counter name. The number returned is incremented by one at each
insertion.
Note:
In the Neolane client console, the Administration>Counters node is used to manage counters.
Enumerations
Free enumeration
The userEnum property lets you define a free enumeration to memorize and display the values entered via
this field. The syntax is as follows:
userEnum="name of enumeration"
The name given to the enumeration can be chosen freely and shared with other fields.
These values are shown in a drop-down list from the input form:
Note:
In the Neolane client console, the Administration>Enumerations node is used to manage enumerations.
Set enumeration
The enum property lets you define a fixed enumeration used when the list of possible values is known in
advance.
The enum attribute refers to the definition of an enumeration class populated in the schema outside the
main element.
Enumerations allow the user to select a value from a drop-down list instead of entering the value in a regular
input field:

Neolane
Example of an enumeration declaration in the data schema:

<enumeration name="gender" basetype="byte" default="0">
<value name="unknown" label="Not specified" value="0"/>
<value name="male" label="male" value="1"/>
<value name="female" label="female" value="2"/>
</enumeration>
An enumeration is declared outside the main element via the <enumeration> element.
The enumeration properties are as follows:
n baseType: type of data associated with the values,
n label: description of the enumeration,
n name: name of the enumeration,
n default: default value of the enumeration.
The enumeration values are declared in the <value> element with the following attributes:
n name: name of the value stored internally,
n label: label displayed via the graphical interface.
dbenum enumeration
n The dbenum property lets you define an enumeration whose properties are similar to those of the enum
property.
However, the name attribute does not store the value internally, it stores a code which lets you extend
the concerned tables without modifying their schema.
The values are defined via the Administration>Enumerations node.
This enumeration is used for specifying the nature of campaigns, for example.
Example
Here is our example schema with the properties filled in:
<enumeration name="gender" basetype="byte">
<value name="male" label="male" value="1"/>
<value name="female" label="female" value="2"/>
</enumeration>
<attribute name="email" type="string" length="80" label="Email" desc="Email of
72 | Neolane 2013
recipient"/>
<attribute name="created" type="datetime" label="Date of creation" default="GetDate()"/>
<attribute name="gender" type="byte" label="gender" enum="gender"/>

<element name="location" label="Location">
<attribute name="city" type="string" length="50" label="City" userEnum="city"/>
</element>
</element>
</srcSchema>
Collections
A collection is a list of elements with the same name and the same hierarchical level.
The unbound attribute with the value "true" lets you populate a collection element.
Example: definition of the <group> collection element in the schema.
<element name="group" unbound="true" label="List of groups">
<attribute name="label" type="string" label="Label"/>
</element>
With projection of the XML content:

<group label="Group1"/>
<group label="Group2"/>
Referencing with XPath

The XPath language is used in Neolane to reference an element or attribute belonging to a data schema.
XPath is a syntax that lets you locate a node in the tree of an XML document.
Elements are designated by their name, and attributes are designated by the name preceded by the character
"@".
Example:
n @email: selects the email,
n location/@city: selects the "city" attribute under the <location> element
n ../@email: selects the e-mail address from the parent element of the current element
n group[1]/@label: selects the "label" attribute that is the child of the first <group> collection element
n group[@label='test1']: selects the "label" attribute that is the child of the <group> element and
contains the value "test1"
Note:
An additional constraint is added when the path crosses a sub-element. In this case, the following expression
must be placed between brackets:
n location/@city is not valid; please use [location/@city]
n [@email] and @email are equivalent
It is also possible to define complex expressions, such as the following arithmetic operations:
n @gender+1: adds 1 to the content of the gender attribute,
n @email + '('+@created+')': constructs a string by taking the value of the e-mail address added
to the creation date between parentheses (for the string type, put the constant in quotes).
High-level functions have been added to the expressions in order to enrich the potential of this language.

Neolane
You can access the list of available functions via any expression editor in the Neolane client console:
Example:
n GetDate(): returns the current date
n Year(@created): returns the year of the date contained in the "created" attribute.
n GetEmailDomain(@email): returns the domain of the e-mail address.
Building a string via the compute string

A Compute string is an XPath expression used to construct a string representing a record in a table associated
with the schema. Compute string is mainly used in the graphical interface to display the label of a selected
record.
The Compute string is defined via the <compute-string> element under the main element of the data
schema. An expr attribute contains an XPath expression to calculate the display.
Example: compute string of the recipient table.
<srcSchema name="recipient" namespace="nms">
<compute-string expr="@lastName + ' ' + @firstName +' (' + @email + ')' "/>
...
</element>
</srcSchema>
Result of the computed string for a recipient: Doe John (john.doe@aol.com)
Note:
If the schema does not contain a Compute string, a Compute string is populated by default with the values
of the primary key of the schema.
Database mapping
The SQL mapping of our example schema gives the following XML document:
<schema mappingType="sql" name="recipient" namespace="cus" xtkschema="xtk:schema">
<enumeration basetype="byte" name="gender">
<value label="Not specified" name="unknown" value="0"/>
<value label="Male" name="male" value="1"/>
<value label="Female" name="female" value="2"/>
</enumeration>
<element name="recipient" sqltable="CusRecipient">

<attribute desc="Recipient e-mail address" label="Email" length="80" name="email"
sqlname="sEmail" type="string"/>
<attribute default="GetDate()" label="Date of creation" name="created"
sqlname="tsCreated" type="datetime"/>
<attribute enum="gender" label="Gender" name="gender" sqlname="iGender" type="byte"/>
<element label="Location" name="location">

<attribute label="City" length="50" name="city" sqlname="sCity" type="string"
74 | Neolane 2013
userEnum="city"/>
</element>
</element>
</schema>
Description
The root element of the schema is no longer <srcSchema>, but <schema>.
This takes us to another type of document, which is generated automatically from the source schema, simply
referred to as the schema. This schema will be used by the Neolane application.
The SQL names are determined automatically based on element name and type.
The SQL naming rules are as follows:
n table: concatenation of the schema namespace and name
In our example, the name of the table is entered via the main element of the schema in the sqltable
attribute:
n field: name of the element preceded by a prefix defined according to type ('i' for integer, 'd' for double,
's' for string, 'ts' for dates, etc.)
The field name is entered via the sqlname attribute for each typed <attribute> and <element>:
<attribute desc="E-mail address of recipient" label="Email" length="80" name="email"
Note:
SQL names can be overloaded from the source schema. To do this, populate the "sqltable" or "sqlname"
attributes on the element concerned.
The SQL script to create the table generated from the extended schema is as follows:
CREATE TABLE CusRecipient(
iGender NUMERIC(3) NOT NULL Default 0,
sCity VARCHAR(50),
sEmail VARCHAR(80),
tsCreated TIMESTAMP Default NULL);
The SQL field constraints are as follows:

n no null values in numeric and date fields,
n numeric fields are initialized to 0.
XML fields
By default, any typed <attribute> and <element> element is mapped onto an SQL field of the data
schema table. You can, however, reference this field in XML instead of SQL, which means that the data is
stored in a memo field ("mData") of the table containing the values of all XML fields. The storage of these
data is an XML document that observes the schema structure.
To populate a field in XML, you must add the xml attribute with the value "true" to the element concerned.
Example: here are two examples of XML field use.
n Multi-line comment field:
<element name="comment" xml="true" type="memo" label="Comment"/>
n Description of data in HTML format:

<element name="description" xml="true" type="html" label="Description"/>
The "html" type lets you store the HTML content in a CDATA tag and display a special HTML edit check
in the Neolane client interface.

Neolane
The use of XML fields lets you add fields without needing to modify the physical structure of the database.
Another advantage is that you use less resources (size allocated to SQL fields, limit on the number of fields
per table, etc.).
The main disadvantage is that it is impossible to index or filter an XML field.
Calculated fields
A calculated field is not stored physically in the table; it is a data item that is calculated dynamically when
the query is submitted.
There are two types of calculated fields: SQL calculated fields and XML calculated fields.
1 SQL calculated field: the data is calculated by the database engine from a simple expression. This
type of field is well suited to extracting a substring in order to display the domain of an e-mail address
or to calculate the age by subtracting the date of birth from the current date.
Note:
SQL expressions can be used directly via the [SQLDATA[expression_sql]] escape sequence. This
syntax must be used with care, however, because the populated SQL depends on the engine of the
current database.
2 XML calculated field: lets you use a more complex expression with XML fields or conditional tests. The
expression is evaluated by the application layer on receipt of the query data.
The disadvantage of using XML calculated fields is that not all SQL functions of the XPath expressions
are supported.
A calculated field must populate the expr attribute containing the expression to be submitted.
A calculated field is SQL type by default. To declare an XML calculated field, add the xml attribute (with the
value set to "true").
Example:
n Returns the e-mail domain:
<attribute expr="GetEmailDomain(@email)" label="Email domain" name="domain"/>
n Calculated field using an SQL expression:

<attribute expr="[SQLDATA[case when iTotal = 0 THEN 'Not specified' ELSE 'Specified'
END]]" label="Total" name="total" type="string"/>
Indexed fields
Indexes let you optimize the performance of the SQL queries used in the application.
An index is declared from the main element of the data schema.
<dbindex name="name_of_index" unique="true/false">
<keyfield xpath="xpath_of_field1"/>
...
</key>
Indexes obey the following rules:

n An index can reference one or more fields in the table.
n An index can be unique (to avoid duplicates) in all of the fields if the unique attribute contains the value
"true".
n The SQL name of the index is determined from the SQL name of the table and the name of the index.
Note:
As a standard, indexes are the first elements declared from the main element of the schema.
76 | Neolane 2013
Note:
Indexes are created automatically during table mapping (standard or FDA).
Example:
n Adding an index to the e-mail address and city:
<dbindex name="email">
<keyfield xpath="@email"/>
<keyfield xpath="location/@city"/>
</dbindex>
<attribute name="email" type="string" length="80" label="Email" desc="E-mail address

of recipient"/>
</element>
</element>
</srcSchema>
n Adding a unique index to the "id" name field:

<dbindex name="id" unique="true">
<keyfield xpath="@id"/>
</dbindex>
<dbindex name="email">
</dbindex>
<attribute name="id" type="long" label="Identifier"/>

of recipient"/>
</element>
</srcSchema>
Management of keys
A table must have at least one key for identifying a record in the table.
A key is declared from the main element of the data schema.
<key name="name_of_key">
...
</key>
Keys obey the following rules:

n A key can reference one or more fields in the table.
n A key is known as 'primary' (or 'priority') when it is the first in the schema to be populated or if it contains
the internal attribute with the value "true".
n A unique index is declared implicitly for each key definition. The creation of an index on the key can be
prevented by adding the noDbIndex attribute with the value "true".
Note:
As a standard, keys are the elements declared from the main element of the schema after indexes have been
defined.

Neolane
Note:
Keys are created during table mapping (standard or FDA), Neolane finds unique indexes.
Example:
n Adding a key to the e-mail address and city:
<key name="email">
</key>

of recipient"/>
</element>
</element>
</srcSchema>
The schema generated:

<dbindex name="email" unique="true">
</dbindex>
<key name="email">
</key>

<element label="Location" name="location">
<attribute label="City" length="50" name="city" sqlname="sCity" type="string"
userEnum="city"/>
</element>
</element>
</schema>
n Adding a primary or internal key on the "id" name field:

<key name="id" internal="true">
</key>
<key name="email" noDbIndex="true">

</key>
<attribute name="id" type="long" label="Identifier"/>

of recipient"/>
</element>
</srcSchema>

<key name="email">
</key>
78 | Neolane 2013

</dbindex>
<key internal="true" name="id">

</key>
<attribute label="Identifier" name="id" sqlname="iRecipientId" type="long"/>

</element>
</schema>
Auto-incremental key
The primary key of most Neolane tables is a 32-bit long integer auto-generated by the database engine. The
calculation of the key value depends on a sequence (by default, the XtkNewId SQL function) generating a
number that is unique in the entire database. The content of the key is automatically entered on insertion
of the record.
The advantage of an incremental key is that it provides a non-modifiable technical key for the joins between
tables. In addition, this key does not occupy much memory because it uses a double-byte integer.
From version 4.05 onwards, in the source schema you can specify the name of the sequence to be used
with the pkSequence attribute. If this attribute is not given in the source schema, the XtkNewId default
sequence will be used. The application uses dedicated sequences for the nms:broadLog and
nms:trackingLog schemas (NmsBroadLogId and NmsTrackingLogId respectively) because these are
the tables that contain the most records.
Note:
A sequence referenced in a Neolane schema (NmsTrackingLogId for example) must be associated to a
SQL function that returns the number of IDs in the parameters, separated by commas. This function must
be called GetNewXXXIds, where XXX is the name of the sequence (GetNewNmsTrackingLogIds for
example). View the postgres-nms.sql, mssql-nms.sql or oracle-nms.sql files provided with the appliation
in the datakit/nms/fra/sql/ directory to recover the example of a 'NmsTrackingLogId' sequence creation
for each database engine.
To declare a unique key, populate the autopk attribute (with value "true") on the main element of the data
schema.
Example:
Declaring an incremental key in the source schema:
<element name="recipient" autopk="true">
...
</element>
</srcSchema>

<element name="recipient" autopk="true" pkSequence="XtkNewId" sqltable="CusRecipient">

</dbindex>

</key>
<attribute desc="Internal primary key" label="Primary key" name="id"

sqlname="iRecipientId" type="long"/>
</element>
</schema>

Neolane
In addition to the definition of the key and its index, a numeric field called "id" has been added to the extended
schema in order to contain the auto-generated primary key.
Important:
A record with a primary key set to 0 is automatically inserted on creation of the table. This record is used to
avoid outer joins, which are not effective on volume tables. By default, all foreign keys are initialized with
value 0 so that a result can always be returned on the join when the data item is not populated.
Links: relation between tables

A link describes the association between one table and another.
The various types of associations (known as "cardinalities") are as follows:
n Cardinality 1-1: one occurrence of the source table can have at most one corresponding occurrence of
the target table.
n Cardinality 1-N: one occurrence of the source table can have several corresponding occurrences of the
target table, but one occurrence of the target table can have at most one corresponding occurrence of
the source table.
n Cardinality N-N: one occurrence of the source table can have several corresponding occurrences of the
target table, and vice-versa.
A link must be declared in the schema containing the foreign key of the table linked via the main element:
<element name="name_of_link" type="link" target="key_of_destination_schema">
<join xpath-dst="xpath_of_field1_destination_table"
xpath-src="xpath_of_field1_source_table"/>
<join xpath-dst="xpath_of_field2_destination_table"
xpath-src="xpath_de_champ2_table_source"/>
...
</element>
Links obey the following rules:

n The definition of a link is entered on a link-type <element> with the following attributes:
n name: name of link from the source table,
n target: name of target schema,
n label: label of link,
n revLink (optional): name of reverse link from the target schema (deduced automatically by default),
n integrity (optional): referential integrity of the occurrence of the source table to the occurrence of
the target table. Possible values are as follows:
n define: it is possible to delete the source occurrence if it is no longer referenced by a target
occurrence,
n normal: deleting the source occurrence initializes the keys of the link to the target occurrence
(default mode), this type of integrity initializes all foreign keys,
n own: deleting the source occurrence leads to the deletion of the target occurrence,
n owncopy: the same as own (in case of deletion) or duplicates the occurrences (in case of
duplication),
n neutral: does nothing.
n revIntegrity (optional): integrity on the target schema (optional, "normal" by default),
n revCardinality (optional): with value "single" populates cardinality with type 1-1 (1-N by default).
n externalJoin (optional): forces the outer join
n revExternalJoin (optional): forces the outer join on the reverse link
n A link references one or more fields from the source table to the destination table. The fields making up
the join (<join> element) need not be populated because they are automatically deduced by default
using the internal key of the target schema.
n An index is automatically added to the foreign key of the link in the extended schema.
n A link consists of two half-links, where the first is declared from the source schema and the second is
created automatically in the extended schema of the target schema.
n A join can be an outer join if the externalJoin attribute is added, with the true" value (supported in
PostgreSQL).
80 | Neolane 2013
Note:
As a standard, links are the elements declared at the end of the schema.
Example 1
1-N relation to the "cus:company" schema table:
...
<element label="Company" name="company" revIntegrity="define" revLabel="Contact"
target="cus:company" type="link"/>
</element>
</srcSchema>

<dbindex name="companyId">
<keyfield xpath="@company-id"/>
</dbindex>
...
<element label="Company" name="company" revLink="recipient" target="cus:company"
type="link">
<join xpath-dst="@id" xpath-src="@company-id"/>
</element>
<attribute advanced="true" label="Foreign key of 'Company' link (field 'id')"
name="company-id" sqlname="iCompanyId" type="long"/>
</element>
</schema>
The link definition is supplemented by the fields making up the join, i.e. the primary key with its XPath ("@id")
in the destination schema, and the foreign key with its XPath ("@company-id") in the schema.
The foreign key is added automatically in an element that uses the same characteristics as the associated
field in the destination table, with the following naming convention: name of target schema followed by name
of associated field ("company-id" in our example).
Extended schema of the target ("cus:company"):
<schema mappingType="sql" name="company" namespace="cus" xtkschema="xtk:schema">
<element name="company" sqltable="CusCompany" autopk="true">
</dbindex>
</key>
...
<attribute desc="Internal primary key" label="Primary key" name="id" sqlname="iCompanyId"
type="long"/>
...
<element belongsTo="cus:recipient" integrity="define" label="Contact" name="recipient"
revLink="company" target="nms:recipient" type="link" unbound="true">
<join xpath-dst="@company-id" xpath-src="@id"/>
</element>
</element>
</schema>
A reverse link to the "cus:recipient" table was added with the following parameters:
n name: automatically deduced from the name of the source schema (can be forced with the "revLink"
attribute in the link definition on the source schema)
n revLink: name of reverse link
n target: key of linked schema ("cus:recipient" schema)
n unbound: the link is declared as a collection element for a 1-N cardinality (by default)
n integrity: "define" by default (can be forced with the "revIntegrity" attribute in the link definition on the
source schema).

Neolane
Example 2
In this example, we will declare a link towards the "nms:address" schema table. The join is an outer join and
is populated explicitly with the recipient's e-mail address and the "@address" field of the linked table
("nms:address").
...
<element integrity="neutral" label="Info about email" name="emailInfo"
revIntegrity="neutral" revLink="recipient" target="nms:address" type="link"
externalJoin="true">
<join xpath-dst="@address" xpath-src="@email"/>
</element>
</element>
</srcSchema>
Example 3
1-1 relation to the "cus:extension" schema table:
<element integrity="own" label="Extension" name="extension" revCardinality="single"
revLink="recipient" target="cus:extension" type="link"/>
Example 4
Link to a folder ("xtk:folder" schema):
<element default="DefaultFolder('nmsFolder')" label="Folder" name="folder"
revDesc="Recipients in the folder" revIntegrity="own" revLabel="Recipients"
target="xtk:folder" type="link"/>
The default value returns the identifier of the first eligible parameter type file entered in the
"DefaultFolder('nmsFolder')" function.
Example 5
In this example, we wish to create a key on a link ("company" to "cus:company" schema) with the xlink
attribute and a field of the ("email") table:
<key name="companyEmail">
<keyfield xlink="company"/>
<key>
<attribute name="email" type="string" length="80" label="Email" desc="Recipient email"/>
<element label="Company" name="company" revIntegrity="define" revLabel="Contact"

target="cus:company" type="link"/>
</element>
</srcSchema>

<dbindex name="companyId">
</dbindex>
<dbindex name="companyEmail" unique="true">

</dbindex>
<key name="companyEmail">
</key>

82 | Neolane 2013
<element label="Company" name="company" revLink="recipient" target="sfa:company"

type="link">
<join xpath-dst="@id" xpath-src="@company-id"/>
</element>
<attribute advanced="true" label="Foreign key of link 'Company' (field 'id')"
name="company-id" sqlname="iCompanyId" type="long"/>
</element>
</schema>
The definition of the "companyEmail" name key was extended with the foreign key of the "company" link.
This key generates a unique index on both fields.
Dictionary of elements and attributes

When editing a schema, an approval system based on the source schema (xtk:srcSchema) is available. Some
errors can also be spotted when updating the database using the "Database structure update..." wizard.
By default, in Neolane schemas, all boolean type attributes are "false". To activate them, you need to specify
the attribute in the schema and set its value to "true".
<attribute> element
Content model
attribute:==help
Attributes
_operation (string), advanced (boolean), applicableIf (string), autoIncrement (boolean), belongsTo (string),
dataPolicy (string), dbEnum (string), defOnDuplicate (boolean), default (string), desc (string), edit (string),
enum (string), expr (string), feature (string), featureDate (boolean), img (string), inout (string), label (string),
length (string), localizable (boolean), name (MNTOKEN), notNull (boolean), pkgStatus (string), ref (string),
required (boolean), sql (boolean), sqlDefault (string), sqlname (string), sqltable (string), target (MNTOKEN),
template (string), translatedDefault (string), translatedExpr (string), type (MNTOKEN), user (boolean),
userEnum (string), visibleIf (string), xml (boolean)
Parents
<element>
Children
<help>
Description
<Attribute> elements let you define a field in the database.
Use and context of use

<Attribute> elements must be declared in an <element> element.
The sequence in which <attribute> elements are defined in an <srcSchema> does not affect the field creation
sequence in the database. The creation sequence will be alphabetical.
Attribute description
n _operation (string): defines the type of writing in the database.
This attribute is mainly used when extending out-of-the-box schemas.
Accessible values are:
n "none": reconciliation alone. This means that Neolane will recover the element without updating it
or generating an error if it doesn't exist.
n "insertOrUpdate": update with insertion. This means that Neolane will update the element or create
it if it doesn't exist.
n "insert": insertion. This means that Neolane will insert the element without checking whether it exists.

Neolane
n "update": update. This means that Neolane will update the element or generate an error if it doesn't
exist.
n "delete": deletion. This means that Neolane will recover and delete elements.
n advanced (boolean): when this option is activated (@advanced="true"), it lets you hide the attribute
on the list of available fields accessible for configuring a list in a form.
n applicableIf (string): this attribute lets you make fields optional. The <attribute> element will be
taken into account when updating the database when the constraint is complied with. "applicableIf"
receives an XTK expression.
n autoIncrement (boolean): if this option is activated, the field becomes a counter. This enables you
to increment a value (mostly IDs). (external use)
n belongsTo (string): takes the name and namespace of the table that shares the field, and populates
the schema where the attribute is declared. (used only in a <schema>).
n dataPolicy (string): enables you to specify approval constraints on values allowed in the SQL or XML
field. The values for this attribute are:
n "none": no value
n "smartCase": first letters upper case
n "lowerCase": all lower case
n "upperCase": all upper case
n "email": email adress
n "phone": telephone number
n "identifier": identifier name
n "resIdentifier": file name
n dbEnum (string): receives the internal name of a "closed" enumeration. The enumeration values must
be defined in the <srcSchema>.
n defOnDuplicate (boolean): if this attribute is activated, when a record is duplicated the default value
(defined in @default) is automatically reapplied to the record.
n default (string): lets you define the value of the default field (call to a function, default value). This
attribute receives an XTK expression.
n desc (string): lets you insert a description of the attribute. This description is displayed in the status
bar of the interface.
n edit (string): this attribute specifies the type of input which will be used in the form linked to the
schema.
n enum (string): receives the name of the enumeration linked to the field. The enumeration can be
inserted into the same schema or into a remote schema.
n expr (string): defines a field precalculation expression. This attribute receives an Xpath or an XTK
expression.
n feature (string): defines a characteristics field: These fields are used for extending the data in an
existing table, but with storage in an annex table. Accepted values are:
n "shared": the content is stored in a shared table per data type
n "dedicated": the content is stored in a dedicated table
SQL characteristics tables are built automatically based on the characteristic type:
n dedicated: Ft_[name_of_the_schema_containing_the_characteristic]_[name_of_the_characteristic]
n shared: Ft_[type_of_key_of_the_schema_containing_the_characteristic]_[type_of_the_characteristic]
There are two types of characteristics fields: simple o fields where a single value is authorized on the
characteristic, and o multiple choice fields, where the characteristic is linked to a collection element
which may contain several values.
When a characteristic is defined in a schema, this schema must have a main key based on a single field
(composite keys are not authorized).
n featureDate (boolean): attribute linked to the "@feature" characteristics field. If its value is "true", it
lets you find out when the value was last updated.
n img (string): lets you define a path for an image linked to a field (namespace + image name)(example:
img="cus:mypicture.jpg"). Physically, the image must be imported to the application server.
n label (string): label linked to the field, mostly destined to the user in the interface. It lets you avoid
naming constraints.
n length (string): max. number of characters for a value of the "string" type SQL field. If the "@length"
attribute isn't specified, Neolane automatically creates a field for 255 characters.
84 | Neolane 2013
n localizable (boolean): if it is activated, this attribute tells the collection tool to recover the value of
the "@label" attribute for translation (internal use).
n name (MNTOKEN): name of the attribute that will match the name of the field in the table. The value
of the "@name" attribute must be short, preferably in english, and comply with XML naming constraints.
When the schema is written to the database, prefixes are automatically added to the field name by
Neolane:
n "i": prefix for the 'integer' type.
n "d": prefix for the 'double' type.
n "s": prefix for the character string type.
n "ts": prefix for the 'date' type.
To fully define the name of the field in the table, use the "@sqlname" option when defining an attribute.
n notNull (boolean): lets you redefine Neolane's behavior regarding the management of NULL records
in the database. By default, numeric fields are not null and string and date type fields can be null.
n pkgStatus (string): during package exports, values are taken into account depending on the value of
the "@pkgStatus":
n "always": always present
n "never": never present
n "default (or nothing)": the value is exported except if it's the default value or if it isn't an internal
field which would not be compatible with other instances.
n ref (string): this attribute defines a reference to an <attribute> element shared by several schemas
(definition factoring). The definition isn't copied into the current schema.
n required (boolean): if this attribute is activated (@required="true"), the field is highlighted in the
interface. The label of the field will be red in forms.
n sql (boolean): if this attribute is activated (@sql="true"), it forces storage of the SQL attribute, even
when the element which contains the attribute has the xml="true" property.
n sqlDefault (string): this attribute allows you to define the default value taken into account for updating
the database only if the @notNull attribute is activated.
n sqlname (string): of the field during table creation. If @sqlname isn't specified, the value of the
"@name" attribute is used by default. When the schema is written in the database, prefixes are added
automatically depending on the type of field.
n template (string): this attribute defines a reference to an <attribute> element shared by several
schemas. The definition is automatically copied into the current schema.
n translatedDefault (string): if a "@default" attribute is found, the "@translatedDefault" will enable
you to redefine an expression to match the one defined in @default, to be collected by the translation
tool (internal use).
n translatedExpr (string): if an "@expr" attribute is present, the "@translatedExpr" attibute enables
you to redefine an expression to match the one defined in @expr, to be collected by the translation tool
(internal use).
n type (MNTOKEN): field type.
Field types are generic. Depending on the type of database installed, NEOLANE changes the defined type
into a value specific to the database installed during structure update.
List of available types:
n ANY
n bin
n blob
n boolean
n byte
n CDATA
n datetime
n datetimetz
n datetimenotz
n date
n double
n enum
n float

Neolane
n html
n int64
n link
n long
n memo
n MNTOKEN
n money
n percent
n primarykey
n short
n string
n time
n timespan
n uuid
If the "@type" attribute is left empty, Neolane will link a string of characters (STRING) with a length of
100 to the field by default.
If the field is of STRING type and the name of the field isn't specified by the presence of the "@sqlname"
attribute, the name of the field in the database will automatically be preceded by an 's'. This operating
mode will be similar with INTEGER (i), DOUBLE (d) and DATES (ts) type fields.
n userEnum (string): receives the internal name of an "open" enumeration. The values of the enumeration
can be defined by the user in the interface.
n visibleIf (string): defines a condition in the form of an XTK expression to show or hide the attribute.
n xml (boolean): if this option is activated, the values of the field don't have a linked SQL field. Neolane
creates a Text type "mData" field for record storage. This means there is not filtering or sorting on these
fields.
Examples
Example of enumeration values whose values are stored in the database:
<enumeration name="myEnum">
<value name="One" value="1"/>
<value name="Two" value="2"/>
</enumeration>
<element label="Sample" name="Sample">

<attribute dbEnum="myEnum" length="100" name="Number" required="true" type="string"/>
</element>
Declaration of an XML field with "@datapolicy":

<attribute dataPolicy="phone" desc="Mobile number" label="Mobile"
length="32" name="mobilePhone" sqlname="sMobilePhone" type="string"/>
Example with an "@applicableIf": the "contains" attribute will only be created if the number of countries is
greater than 20.
<attribute length="100" name="Continent" type="string" applicableIf="@country > 20"/>
Example with "@feature" of "shared" type:

<attribute name="field1" label="Field 1" type="long" feature="shared"/>
<attribute name="field1" label="Field 1" type="long" feature="shared" sqlname="126"
sqltable="Ft_Content_Long"/>
Example with "@feature" of "dedicated" type:

<attribute name="field1" label="Field 1" type="long" feature="dedicated"/>
<attribute name="field1" label="Field 1" type="long" feature="dedicated" sqlname="sField1"
sqltable="Ft_recipient_field1"/>
86 | Neolane 2013
<compute-string> element
Content model
compute-string:==EMPTY
Attributes
@expr
Parents
<element>
Children
None
Description
The <compute-string> element enables you to generate a string based on an XTK expression to display a
"built" label in the interface based on several values.

When no <compute-string> is defined, a <compute-string> element is entered by default with the values
of the primary key in the schema.
n expr (string): XTK and/or Xpath expression
Examples
<compute-string expr="@label + Iif(@code='','', ' (' + [folder/@label] + ')')"/
<compute-string expr="ToString([@centralCatalog-id]) + ',' + ToString([@localOrgUnit-id])"/
Result of the string calculated on a recipient: "John Doe (john.doe@aol.com)":
<compute-string expr="@lastName + ' ' + @firstName +' (' + @email + ')'
"/>
...
</element>

Neolane
<condition> element
Content model
condition:==EMPTY
Attributes
n @boolOperator (string)
n @enabledIf (string)
n @expr (string)
Parents
<sysFilter>
Children
None
Description
This element lets you define a filtering condition.

One <sysFiler> element can contain several filtering conditions.
n boolOperator (string): if several <conditions> are defined within the same <sysFilter> element, this
attribute lets you combine them. By default, the logical link is between <condition> elements is "AND".
The "@boolOperator" attribute lets you combine "OR" and "AND" type links.
n enabledIf (string): condition activation test.
n expr (string): an XTK expression.
Examples
<sysFilter>
<condition expr="@city=[currentOperator/location/@city]"
enabledIf="hasNamedRight('admin')=false"/>
</sysFilter>
88 | Neolane 2013
<dbindex> element
Content model
dbindex:==keyfield
Attributes
n @_operation (string)
n @applicableIf (string)
n @label (string)
n @name (MNTOKEN)
n @unique (boolean)
Parents
<element>
Children
<keyfield>
Description
This element lets you define an index linked to a table.

It's possible to define several indexes. One index can reference one or more fields of the table. Index
declaration usually follows the definition of the main schema element.
The order of the <keyfield> elements defined in a <dbindex> is very important. The first <keyfield> must
be the indexation criterion which the queries are mainly based on.
The name of the indext in the database is calculated by concatenating the name of the table and the name
of the index. For example: Table name "Sample", Namespace "Cus", index name "MyIndex"-> name of the
index field during index creation querying: "CusSample_myIndex".
exist.
n applicableIf (string): condition for taking the index into account - receives an XTK expression.
n label (string): index label.
n name (string): unique index name.
n unique (boolean): if this option is activated (@unique="true"), the attribute guarantees the uniqueness
of the index throughout its fields.
Examples
Creation of an index on the "id" field. (the "@unique" attribute on the <dbindex> element triggers adding
of the "UNIQUE" SQL key word when the index is created in the database (query)).

<dbindex name="myIndex" label="My index on the ID field" unique="true"
applicableIf="HasPackage('nms:social')">

Neolane
</dbindex>
<attribute name="id" type="long"/>
</element>
ALTER TABLE CusSample ADD iSampleId INTEGER;

UPDATE CusSample SET iSampleId = 0;
ALTER TABLE CusSample ALTER COLUMN iSampleId SET Default 0;
ALTER TABLE CusSample ALTER COLUMN iSampleId SET NOT NULL;
CREATE UNIQUE INDEX CusSample_myIndex ON CusSample(iSampleId);
Creation of a composite index on the "@mail" and "@phoneNumber" fields:
<element label="NewSchemaUser" name="NewSchemaUser">

<dbindex name="myIndex" label="My composite index">
<keyfield xpath="@phone"/>
</dbindex>
<attribute name="email" type="string"/>

<attribute name="phone" type="string"/>
</element>
CREATE INDEX DocNewSchemaUser_myIndex ON DocNewSchemaUser(sEmail, sPhone);
90 | Neolane 2013
<element> element
Content model
element:==(attribute | compute-string | dbindex | default | element | help | join | key | sysFilter |
translatedDefault)
Attributes
_operation (string), advanced (boolean), aggregate (string), applicableIf (string), autopk (boolean), belongsTo
(string), convDate (string), dataPolicy (string), dataSource (string), dbEnum (string), defOnDuplicate (boolean),
default (string), desc (string), displayAsField (boolean), doesNotSupportDiff (boolean), edit (string),
emptyKeyValue (string), enum (string), enumImage (string), expandSchemaTarget (string), expr (string),
externalJoin (boolean), feature (string), featureDate (boolean), filterPath (string), folderLink (string),
folderModel (string), folderProcess (string), fullLoad (boolean), hierarchical (boolean), hierarchicalPath (string),
img (string), inout (string), integrity (string), label (string), labelSingular (string), length (string), localizable
(boolean), name (MNTOKEN), noDbIndex (boolean), noKey (boolean), ordered (boolean), overflowtable
(boolean), pkSequence (string), pkgStatus (string), ref (string), required (boolean), revAdvanced (boolean),
revCardinality (string), revDesc (string), revExternalJoin (boolean), revIntegrity (string), revLabel (string),
revLink (string), revTarget (string), revVisibleIf (string), sql (boolean), sqlname (string), sqltable (string),
tableSpace (string), tableSpaceIndex (string), target (MNTOKEN), template (string), temporaryTable (boolean),
translatedDefault (string), translatedExpr (string), type (MNTOKEN), unbound (boolean), user (boolean),
userEnum (string), visibleIf (string), xml (boolean), xmlChildren (boolean)
Parents
<srcSchema>
<element>
Children
n <attribute>
n <compute-string>
n <dbindex>
n <default>
n <element>
n <help>
n <join>
n <key>
n <sysFilter>
n <translatedDefault>
Description
There are four types of <element> elements in Neolane:
n Root <element>: defines the name of the SQL table that matches the schema.
n Structure <element>: defines a group of <element> or <attribute> elements.
n Link <element>: defines a link. This elements must include the "@type=link" attribute.
n XML <element>: defines a Text type "mData" field. This element must include the "@type=xml" attribute.

-

Neolane
exist.
n advanced (boolean): when this option is activated (@advanced="true"), it lets you hide the attribute
on the list of available fields accessible for configuring a list in a form.
n aggregate (string): lets you copy the definition of an <element> via another schema. This attribute
receives a schema declaration in the form of a "namespace:name".
n applicableIf (string): condition for applying the index. This attribute receives an XTK expression.
n autopk (boolean): if this option is activated (autopk="true"), a unique key will be automatically defined.
This option may only be used on the main element of the schema. Warning, Neolane only guarantees
that the key generated is unique. It is not guaranteed that the key values are consecutive and incremental.
n dataPolicy (string): enables you to specify approval constraints on values allowed in the SQL field.
The values for this attribute are:
n "none": no value
n "smartCase": first letters upper case
n "lowerCase": all lower case
n "upperCase": all upper case
n "email": email adress
n "phone": telephone number
n "identifier": identifier name
n "resIdentifier": file name
n dbEnum (string): receives the internal name of a "closed" enumeration. The enumeration values must
be defined in the <srcSchema>.
n defOnDuplicate (boolean): if this attribute is activated, when a record is duplicated the default value
(defined in @default) is automatically reapplied to the record.
n default (string): lets you define element behavior (call to a function, default value). This attribute
receives an XTK expression.
n desc (string): lets you insert a description of the element. This description is displayed in the status
bar of the interface.
n displayAsField (boolean): if this attribute is activated, a "link" type <element> will be displayed as a
field in the tree view of the schemas ("Structure" tab). This way, it's possible to display a link as a local
field and change it behavior during a query. When the element is found in the SELECT of a query, the
value of the link target will be used. When the element is found in the WHERE of a query, the underlying
key of the link will be used.
n edit (string): this attribute specifies the type of input that will be used in the form linked to the schema.
n enum (string): receives the name of the enumeration linked to the field. The enumeration can be
inserted into the same schema or into a remote schema.
n expr (string): this attribute defines a calculated field for which no definition is stored in the table. It
receives an Xpath or an XTK expression.
n externalJoin (boolean): external join in a "link" type element.
n feature (string): defines a characteristics field: These fields are used for extending the data in an
existing table, but with storage in an annex table. Accepted values are:
n "shared": the content is stored in a shared table per data type
n "dedicated": the content is stored in a dedicated table
SQL characteristics tables are built automatically based on the characteristic type:
n dedicated: Ft_[name_of_the_schema_containing_the_characteristic]_[name_of_the_characteristic]
n shared: Ft_[type_of_key_of_the_schema_containing_the_characteristic]_[type_of_the_characteristic]
There are two types of characteristics fields: simple o fields where a single value is authorized on the
characteristic, and o multiple choice fields, where the characteristic is linked to a collection element
which may contain several values.
When a characteristic is defined in a schema, this schema must have a main key based on a single field
(composite keys are not authorized).
n featureDate (boolean): attribute linked to the "@feature" characteristics field. If its value is "true", it
lets you find out when the value was last updated.
n filterPath (string): this attribute receives an Xpath and lets you define a filter on a field.
92 | Neolane 2013
n folderLink (string): this attribute receives the name of the link that lets you recover the files containing
entities.
n folderModel (string): defines the type of folder which enables entity storage. This attribute is only
defined if "@folderLink" is present.
n folderProcess (string): defines the link where entity model instances are stored. This attribute is only
defined if "@folderLink" is present.
n fullLoad (boolean): this attribute forces the display of all records in a table during field selection in a
form.
n img (string): receives the path of an image linked to an element. The value of this attribute is of
"namespace:image name" type. For example: img="cus:myImage.jpg". Physically, the image must be
imported to the application server.
n integrity (string): referential integrity of the occurrence of the source table towards the target table.
n "define": Neolane does not delete the entity if it is referenced via the link
n "normal": deleting the source occurrence initializes the keys of the link on the target occurrence
(default mode), this type of integrity initializes all foreign keys
n "own": deleting the source occurrence triggers the deletion of the target occurrence
n "owncopy": similar to "own" (in case of deletion) or duplicates occurrences (in case of duplication)
n "neutral": does not do anything
n label (string): element label.
n labelSingular (string): label (singular form) of the element used in some parts of the interface.
n length (string): max. number of characters authorized for a value of the "string" type SQL field.
n localizable (boolean): if it is activated, this attribute tells the collection tool to recover the value of
the "@label" attribute for translation (internal use).
n name (MNTOKEN): internal name of the element which matches the name of the table. The value of
the "@name" attribute must be short, preferably in English and comply with naming constraints linked
to XML.
When the schema is written to the database, prefixes are automatically added to the field name by
Neolane.
n "i": prefix for the 'integer' type.
n "d": prefix for the 'double' type.
n "s": prefix for the character string type.
n "ts": prefix for the 'date' type.
To define the name of the table in an autonomous way, you need to use the "@sqltable" attribute in the
definition of the main schema element.
n noDbIndex (boolean): lets you specify that the element will not be indexed.
n ordered (boolean): if the attribute is activated (ordered="true"), Neolane keeps the element declaration
sequence in an XML collection element.
n pkSequence (string): receives the name of the sequence to be used for calculating an auto-incremental
key. This attribute may only be used if an auto-incremental key is defined on the root element of the
schema.
n pkgStatus (string): during package exports, values will be taken into account as a function of the value
of this attribute:
n "always": the element will always be present
n "never": the element will never be present
n "default (or nothing)": the element is exported unless it is the default element or if it isn't an internal
field and would not be compatible with other instances
n ref (string): this attribute defines a reference to an >element> element shared by several schemas
(definition factoring). The definition isn't copied into the current schema.
n required (boolean): if this attribute is activated (@required="true"), the field is highlighted in the
interface. The label of the field will be red in forms.
n revAdvanced (boolean): when activated, this attribute specifies that the opposite link is an "advanced"
link.
n revCardinality (string): this attribute defines the cardinality of a link between two tables. It is used
in a "link" type <element>.
Possible values are:

Neolane
n "single" : Simple 1-1 type link

n "unbound": 1-N type collection link
By default, if the attribute isn't specified during link creation, cardinality will be 1-N.
n revDesc (string): this attribute receives a description linked to the opposite link.
n revExternalJoin (boolean): when activated, this attribute lets you force the external join on the
opposite link.
n revIntegrity (string): this attribute defines the integrity on the target schema. The same values as
the "@integrity" attribute are authorized. By default, Neolane gives the "normal" value to this attribute.
n revLabel (string): label of the opposite link.
n revLink (string): name of the opposite link. If the value is "_NONE_", no opposite link will be created
in the destination schema.
n revTarget (string): target of the opposite link.
n sql (boolean): if this attribute is activated (@sql="true"), it forces storage of the SQL element, even if
the element has the xml="true" property.
n sqlname (string): name of the field during table creation. If "@sqlname" isn't specified, the value of
the "@name" attribute is used by default. When writing the schema to the table, prefixes are added
automatically depending on the type of field.
n sqltable (string): for the main element of the schema, this attribute overloads the name of the SQL
table generated by default. If "@sqltable" isn't specified, the default name will be structured like this:
namespace (first letter upper case) followed by the value of the SrcSchema "@name".
n tableSpace (string): this attribute lets you specify a new data storing tablespace for a table (valid on
the root <element>).
n tableSpaceIndex (string): this attribute lets you specify a new index storage tablespace for a table
(valid on the root <element>).
n target (MNTOKEN): receives the name of the target schema when creating a link between tables. This
attribute is only active for "link" type elements.
n template (string): this attribute defines a reference to an <element element shared by several schemas.
The definition is automatically copied into the current schema.
n translatedDefault (string): if a "@default" attribute is found, the "@translatedDefault" will enable
you to redefine an expression to match the one defined in @default, to be collected by the translation
n translatedExpr (string): if a "@expr" attribute is found, the "@translatedExpr" attribute lets you
redefine an expression matching the one defined in "@expr", and which will be collected by the translation
n type (MNTOKEN): defines the type of data stored in the element.
n ANY
n bin
n blob
n boolean
n byte
n CDATA
n datetime
n datetimetz
n datetimenotz
n date
n double
n enum
n float
n html
n int64
n link
n long
n memo
n MNTOKEN
n money
94 | Neolane 2013
n percent
n primarykey
n short
n string
n time
n timespan
n uuid
n unbound (boolean): if the attribute is activated (unbound="true"), the link is declared as a collection
element for a 1-N cardinality.
n userEnum (string): receives the internal name of an "open" enumeration. Enumeration values can be
defined by the user in the interface.
n xml (boolean): if this option is activated, all values defined in the element are stored in XML in a TEXT
type "mData" field. This means that there will be no filtering or sorting on these fields.
n xmlChildren (boolean): forces storage for each child (<element> or <attribute>) of the <element>
element in an XML document.

Neolane
<enumeration> element
Content model
enumeration:==(help| value)
Attributes
n @basetype (string)
n @default (string)
n @desc (string)
n @label (string)
n @name (string)
n @template (string)
Parents
<srcSchema>
Children
n <help>
n <value>
Description
This element enables us to define a value enumeration. An enumeration belongs to the schema which it is
defined in, but it is accessible via another schema.

Enumerations are defined at the start of a schema (before the main element is defined).
n basetype (string): type of the values stored in the enumeration.
n ANY
n bin
n blob
n boolean
n byte
n CDATA
n datetime
n datetimetz
n datetimenotz
n date
n DOMDocument
n DOMElement
n double
n enum
n float
n html
n int64
n link
n long
n memo
n MNTOKEN
n money
n percent
n primarykey
96 | Neolane 2013
n short
n string
n time
n timespan
n uuid
n default (string): Default value. The default value may also be one of the values defined in the
enumeration.
n desc (string): enumeration description.
n label (string): enumeration label.
n name (string): internal name of the enumeration.
n template (string): this attribute defines a reference to an <enumeration> element shared by several
schemas. The definition is automatically copied into the current schema.
Examples
Example of enumeration values whose values are stored in the database:
</enumeration>

<attribute dbEnum="myEnum" length="100" name="Number" required="true" type="string"/>
</element>
Definition of an enumeration with a default value:
<enumeration basetype="byte" default="email" name="canal">

<value label="Email" name="email" value="0"/>
<value label="Tlphone" name="phone" value="1"/>
<value label="Call Center" name="callcenter" value="2"/>
</enumeration>

Neolane
<help> element
Content model
help:==EMPTY
Attributes
None
Parents
<srcSchema>, <element>, <attribute>, <enumeration>, <value>, <param>, <method>
Children
None
Description
This element lets you describe an <element> or <attribute> element. It may only contain text, and is stored
in XML in the database.

-
This element has no attributes.
Examples
<method name="CheckOperation" static="true"
<helpchecks the validity of a campaign</help
...
</method
98 | Neolane 2013
<join> element
Content model
join:==EMPTY
Attributes
n @dstFilterExpr (string)
n @xpath-dst (string)
n @xpath-src (string)
Parents
<element>
Children
None
Description
Lets you define the fields that create a join between SQL tables.

A <join> element can only be used if the parent <element> element is of 'link' type. This means that the
parent element must have the "@type=link" attribute declared.
It is not necessary to specify the name and namespace of the remote table in the <join> element. They
need to be specified in the parent <element>.
By convention, links are defined at the end of the schema.
If the <join> element isn't specified when the link type element is defined, the link will automatically be
placed on the primary keys of both tables.
n dstFilterExpr (string): this attribute lets you restrict the number of eligible values in the remote table.
n xpath-dst (string): this attribute receives an Xpath (@name attribute of the remote table).
n xpath-src (string): this attribute receives an Xpath (@name attribute in the current schema).
Examples
Link between the 'email' field of the current table and the "@compagny-id" field of the remote table:
<join xpath-dst="@compagny-id" xpath-src="@email"/>
Filtered link towards the "cus:Country" table based on the content of the "@country" field which must contain
the 'EN' value:
<element name="StockFR" type="link" label="MyLink" target="cus:Stock"
<join xpath-dst="@country" xpath-src="@code" dstFilterExpr="@country = 'FR'"/
</element

Neolane
<key> element
Content model
key:==keyfield
Attributes
n @allowEmptyPart (boolean)
n @internal (boolean)
n @label (string)
n @name (MNTOKEN)
n @noDbIndex (boolean)
Parents
<element>
Children
<keyfield>
Description
This element lets you define a key for identifying a record in the table.
A table must have at least one key.

As a rule, keys are declared after the main element of the schema and the indexes.
A key is known as composite if it includes several fields (i.e. several <keyfield> children). Do not use a
composite key to define a primary key.
If the main element of the schema contains the "@autopk=true" attribute, the primary key is unique. We
can only have one primary key per schema.
The first 1000 identifiers are reserved, so if a range of values needs to be defined for keys, start at 1000.
n allowEmptyPart (boolean): in the case of a composite key, if this attribute is activated, the key is
considered valid if at least one of its keys isn't empty. If this is the case, the empty notion value is "0"
(boolean or for all types of numerical data). By default, all the keys that make up a composite key need
to be entered.
n applicableIf (string): this attribute lets you make the key optional. It defines the condition according
to which the key definition will be applied. This attribute receives an XTK expression.
n internal (boolean): if it is activated, this attribute lets Neolane know that the key is primary.
n label (string): label of the key.
n name (MNTOKEN): internal name of the key.
n noDbIndex (boolean): if it is activated (noDbIndex="true"), the field matching the key will not be
indexed.
Examples
Declaration of a composite key which authorizes either the "@expr" or the "alias" field to be empty:
<key name="node" allowEmptyPart="true">

<keyfield xpath="@expr"/>
<keyfield xpath="@alias"/>
</key>
Declaration of a primary key on the "Name" field of STRING type in an <srcSchema> and the matching SQL
query:
<key name="PrimaryKey" internal="true">

<keyfield xpath="@name"/>
100 | Neolane 2013

</key>
CREATE UNIQUE INDEX Schema_PrimaryKey ON Schema(sName);

Neolane
<keyfield> element
Content model
keyfield:==EMPTY
Attributes
n @xlink (MNTOKEN)
n @xpath (MNTOKEN)
Parents
<key>,<dbindex>
Children
None
Description
This element defines the fields to be integrated into an index or a key.

-
n xlink (MNTOKEN): lets you automatically reference foreign keys defined in the join for a relation table
(N-N link).
n xpath (MNTOKEN): definition of an index or a key on an <attribute> element. This attribute receives
an Xpath which defines the path to the schema attribute that defines the key or the index.
Examples
Selection of the "sName" field in an index with an Xpath on "@name":
<keyfield xpath="@name"/>
102 | Neolane 2013

<method> element
Content model
method:==( help | parameters)
Attributes
n @access (string)
n @const (boolean)
n @hidden (boolean)
n @label (string)
n @library (string)
n @name (MNTOKEN)
n @pkonly (boolean)
n @static (boolean)
Parents
<methods>,<interface>
Children
n <help>
n <parameters>
Description
This element lets you define a SOAP method.

SOAP methods enable application processes.
The "@library" is necessary for declaring a new method (non-native): the namespace and the name used
for the library are independent from the namespace and name of the schema where the declaration is.
n access (string): this attribute defines access control for using the method. If this attribute is missing,
identification is mandatory. Available values are: 'anonymous', 'admin' and 'sql'.
n const (boolean): if it is activated, this attribute means that the declared method will alter the entity
n label (string): label of the method.
n library (string): this method isn't native to the application. This attribute takes the value of the method
library where the method definition is found (nms:mylibrary.js).
n name (MNTOKEN): unique method name.
n static (boolean): if this attribute is activated, the method is considered to be autonomous, all parameters
must be specified to the method when it is called up.

Neolane
Examples
Definition of the "Subscribe" out of the box method:
<method name="Subscribe" static="true">
<help>Creation of update of a recipient's subscription to an information service</help>
<parameters>
<param desc="Name of the information service(s) (separated with commas)"
name="serviceName" type="string"/>
<param desc="Recipient to subscribe and possibly create" name="recipient"
type="DOMElement"/>
<param desc="Create the recipient if they don't exist" name="create" type="boolean"/>
</parameters>
</method>
104 | Neolane 2013

<methods> element
Content model
methods:==method
Attributes
None
Parents
<srcSchema>
Children
method
Description
This element lets you define a <method> element. It is mandatory for declaring a method.

-
Examples
<methods async="true"
...// definition of one or more <method
</methods

Neolane
<param> element
Content model
param:==help
Attributes
n @desc (string)
n @enum (string)
n @inout (string)
n @label (string)
n @localizable (string)
n @name (MNTOKEN)
n @namespace (MNTOKEN)
n @type (string)
Parents
<parameters>
Children
<help>
Description
This element lets you define a parameter for calling up a SOAP method.

-
n desc (string): description which concerns the <param> element.
n inout (string): this attribute defines whether or not the parameter is at the input (in) or output (out)
of the SOAP call. If this attribute isn't specified, the default parameter is input ("@inout=in").
n label (string): <param> label
n localizable (string): if it is activated, this attribute tells the collection tool to recover the value of the
"@label" attribute for translation (internal use).
n name (MNTOKEN): internal name of the <param>
n type (string): this attribute defines the type of <param> element
n ANY
n bin
n blob
n boolean
n byte
n CDATA
n datetime
n datetimetz
n datetimenotz
n date
n DOMDocument
n DOMElement
n double
n enum
n float
n html
106 | Neolane 2013

n int64
n link
n long
n memo
n MNTOKEN
n money
n percent
n primarykey
n short
n string
n time
n timespan
n uuid
Examples
Definition of the "serviceName" inbound setting of character string type:
<param desc="Name of the information service(s) (separated with commas)"
name="serviceName" type="string" inout="in"/>

Neolane
<parameters> element
Content model
parameters:==param
Attributes
None
Parents
<method>
Children
<param>
Description
This element defines a group of <parameter> elements.

This element is mandatory, even for a single <param> child element of the <method> element.
None
Examples
<parameters
... //definition of one or more <param
</parameters
108 | Neolane 2013

<srcSchema> element
Content model
srcSchema:==(attribute | createdBy | data | element | enumeration | help | interface | methods | modifiedBy)
Attributes
created (datetime), createdBy-id (long), desc (string), entitySchema (string), extendedSchema (string), img
(string), implements (string), label (string), labelSingular (string), lastModified (datetime), library (boolean),
mappingType (string), modifiedBy-id (long), name (string), namespace (string), useRecycleBin (boolean),
view (boolean), xtkschema (string)
Parents
None
Children
n <attribute>
n <createdBy>
n <data>
n <element>
n <enumeration>
n <help>
n <interface>
n <methods>
n <modifiedBy>
Description
root element of a schema

Schema presentation is available in Introduction [page 66] and Schema structure [page 68]
n created (datetime): this attribute provides information on the date and time of schema creation. It
has a "Date Time" form. The values displayed are taken from the server. The time is shown in UTC
format.
n createdBy-id (long): is the identifier of the operator who created the schema.
n desc (string): schema description
n entitySchema (string): basic schema which syntax and approval are based on (by default for Neolane:
xtk:srcSchema). When you save the current schema, Neolane will approve its grammar with the schema
declared in the @xtkschema attribute.
n extendedSchema (string): receives the name of the out-of-the-box schema which the current schema
extension is based on. The form is "namespace:name".
n img (string): icon linked to the schema (may be defined in the schema creation wizard).
n label (string): schema label.
n labelSingular (string): label (singular) for display in the interface.
n lastModified (datetime): this attribute provides information on the date and time of the last modification.
It has a "Date Time" form. The values displayed are taken from the server. The time is shown in UTC
format.
n library (boolean): use of the schema as a library and not an entity. This schema may therefore be
referenced by other schemas thanks to the "@ref" and "@template" attributes.
n mappingType (string):
n "sql": database mapping
n "textFile": text file mapping
n "xmlFile": XML format text file mapping
n "binaryFile": binary file mapping
n modifiedBy-id (long): matches the identifier of the operator who changed the schema.

Neolane
n name (string): unique schema name.

n namespace (string): namespace of the schema (default: nms, xtk, nl). When creating a new schema
for a project, we recommend that you use a dedicated namespace.
n useRecycleBin (boolean): activates the trash feature in the application. Deleted records will be placed
in the trash before final deletion. This function is only available in "Delivery" mode.
n view (boolean): if it is activated (@view="true"), the schema will be used as a view. The database
structure update wizard will not take the schema into account. This option is mainly used for referencing
external tables.
n xtkschema (string): name of the schema which defines schema grammar (xtk:srcSchema by default).
Examples
<srcSchema> element of the "nms:delivery" out of the box schema
<srcSchema desc="Defines all the settings of a delivery (or delivery template)."
entitySchema="xtk:srcSchema" img="nms:campaign.png" implements="xtk:persist"
label="Diffusions" labelSingular="Diffusion"
md5="DCD2164CD0276B1DCA6E1C9E2A75EC04"
name="delivery" namespace="nms" useRecycleBin="true" xtkschema="xtk:srcSchema">
110 | Neolane 2013

<sysFilter> element
Content model
sysFilter:==condition
Attributes
-
Parents
<element>
Children
<condition>
Description
This element lets you define a filter.

-
Examples
Definition of a filter with a condition on the @name attribute:
<sysFilter>
<condition expr="@name ='Doe'"/>
<sysFilter>

Neolane
<value> element
Content model
value:==help
Attributes
n @desc (string)
n @enabledIf (string)
n @img (string)
n @label (string)
n @name (string)
n @value (string)
Parents
<enumeration>
Children
<help>
Description
This element lets you define the values stored in an enumeration.

-
n applicableIf (string): this attribute lets you make an enumeration value optional. It receives an XTK
expression.
n desc (string): description of the enumeration value.
n enabledIf (string): condition for activating the enumeration value.
n img (string): image linked to the enumeration in the namespace:image_name form. The image must
be imported onto the application server.
n label (string): label of the enumeration value.
n name (string): internal name of the enumeration value.
n value (string): value of the enumeration value. The type of value is defined based on the type of
enumeration. If the enumeration is of character string type, it may only contain character string type
values.
Examples
</enumeration>
112 | Neolane 2013

CHAPTER 3
Editing and extending
schemas
Table of Contents
Editing schemas . . . . . . . . . . . . . . . . . . . . . . . . . . 114
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
Example: creating a contract table . . . . . . . . . . . . . . . . . . . 115
Schema of an existing table or a view . . . . . . . . . . . . . . . . . . . 118
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
Implementation . . . . . . . . . . . . . . . . . . . . . . . . . 118
Accessing an external database . . . . . . . . . . . . . . . . . . . . 119
Extending an existing schema . . . . . . . . . . . . . . . . . . . . . 121
Protecting schemas . . . . . . . . . . . . . . . . . . . . . . . . . 122
System filters . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Protecting out-of-the-box schemas . . . . . . . . . . . . . . . . . . . 122
Modifying system filters of out-of-the-box schemas . . . . . . . . . . . . . 123
Updating the physical structure of the database . . . . . . . . . . . . . . . 124
New field wizard . . . . . . . . . . . . . . . . . . . . . . . . . . 125
Schema structure . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Regenerating all schemas . . . . . . . . . . . . . . . . . . . . . . . 127
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Extending a table . . . . . . . . . . . . . . . . . . . . . . . . . 127
Linked collection table . . . . . . . . . . . . . . . . . . . . . . . 128
Extension table . . . . . . . . . . . . . . . . . . . . . . . . . 129
Overflow table . . . . . . . . . . . . . . . . . . . . . . . . . . 130
Relationship table . . . . . . . . . . . . . . . . . . . . . . . . . 131
This chapter details the configuration of extension schemas for extending the conceptual data model
of the Neolane database.
Neolane v6.1 - Configuration Guide - Editing and extending schemas | 113

Neolane
Editing schemas
Overview
To edit, create and configure the schemas, click the Administration>Configuration>Data schemas
node of the Neolane client console.
The edit field shows the XML content of the source schema:
Note:
The "Name" edit control lets you enter the schema key made up of the name and namespace. The "name"
and "namespace" attributes of the root element of the schema are automatically updated in the XML editing
zone of the schema.
114 | Neolane 2013

Editing and extending schemas
The preview automatically generates the extended schema:
Note:
When the source schema is saved, generation of the extended schema is automatically launched.
Example: creating a contract table

In the following example, we want to create a new table for contracts in the database model of the Neolane
database. This table lets you store first and last names and email addresses of holders and co-holders, for
each contract.
To do this, you need to create the schema of the table and update the database structure to generate the
corresponding table. Apply the following stages:
1 Edit the Administration>Configuration>Data schemas node of the Neolane tree and click New.
2 Choose the Create a new table in the data model option and click Next.

Neolane
3 Specify a name for the table and a namespace.
Note:
By default, schemas created by users are stored in the 'cus' namespace. For more on this, refer to
Identification of a schema [page 67].
4 Create the content of the table. We recommend using the entry wizard to make sure no settings are
missing. To do this, click the Insert button and choose the type of setting to be added.
5 Define the settings for the contract table:

<srcSchema desc="Active contracts" img="ncm:channels.png" label="Contracts"
labelSingular="Contract" mappingType="sql" name="Contracts" namespace="cus"
xtkschema="xtk:srcSchema"
<element desc="Active contracts" img="ncm:channels.png" label="Contracts"
labelSingular="Contract"
name="Contracts" autopk="true"
<attribute name="titulaireName" label="Holder last name" type="string"/
<attribute name="titulaireFirstName" label="Holder first name" type="string"/
<attribute name="titulaireEmail" label="Holder email" type="string"/

<attribute name="cotitulaireName" label="Co-holder last name" type="string"/
<attribute name="cotitulaireFirstName" label="Co-holder first name"

type="string"/
<attribute name="cotitulaireEmail" label="Co-holder email" type="string"/
116 | Neolane 2013

<attribute name="date" label="Subscription date" type="date"/

<attribute name="noContrat" label="Contract number" type="long"/
</element
</srcSchema
Add the type of contract and place an index on the contract number.
<srcSchema _cs="Contracts (cus)" desc="Active contracts" entitySchema="xtk:srcSchema"
img="ncm:channels.png"
label="Contracts" labelSingular="Contract" name="Contracts" namespace="cus"
xtkschema="xtk:srcSchema">
<enumeration basetype="byte" name="typeContract">
<value label="Home" name="home" value="0"/>
<value label="Car" name="car" value="1"/>
<value label="Health" name="health" value="2"/>
<value label="Pension fund" name="pension fund" value="2"/>
</enumeration>
<element autopk="true" desc="Active contracts" img="ncm:channels.png" label="Contracts"
labelSingular="Contract" name="Contracts">
<attribute label="Holder last name" name="titulaireName" type="string"/>
<attribute label="Holder first name" name="titulaireFirstName" type="string"/>
<attribute label="Holder email" name="titulaireEmail" type="string"/>
<attribute label="Co-holder last name" name="cotitulaireName" type="string"/>
<attribute label="Co-holder first name" name="cotitulaireFirstName" type="string"/>
<attribute label="Co-holder email" name="cotitulaireEmail" type="string"/>

<attribute label="Subscription date" name="date" type="date"/>
<attribute desc="Type of contract" enum="cus:Contrats:typeContrat" label="Type of
contract"
name="type" type="byte"/>
<attribute label="Contract number" name="noContrat" type="long"/>
<dbindex name="noContrat" unique="true">
<keyfield xpath="@noContrat"/>
</dbindex>
</element>
</srcSchema>
6 Save the schema to generate the structure:
7 Update the database structure to create the table which the schema will be linked to. For more on this,
refer to Updating the physical structure of the database [page 124].

Neolane
Schema of an existing table or a view
Overview
When the application needs to access the data of an existing table, an SQL view, or data from a remote
database, create its schema in Neolane with the following data:
n Name of table: enter the name of the table (with its alias when a dblink is used) with the "sqltable"
attribute,
n schema key: reference the reconciliation field(s),
n indexes: used to generate queries,
n The fields and their location in the XML structure: fill in only the fields used in the application,
n links: if there are joins with the other tables of the base.
Implementation
To create the corresponding schema, apply the following stages:
2 Select the Access data from an existing table or an SQL view option and click Next.
118 | Neolane 2013

3 Choose the table or the existing view:
4 Adapt the schema content to suit your needs.
Important:
The schema must be populated with the view="true" attribute on the <srcSchema> root element in
order not to generate a table creation SQL script.
Example :
<srcSchema name="recipient" namespace="cus" view="true">
<element name="recipient" sqltable="dbsrv.recipient">
<key name="email">
</key>
<attribute name="email" type="string" length="80" sqlname="email"/>
</element>
</srcSchema>
Accessing an external database

Purchasing the Federated Data Access option give you access to the data stored in an external database.
To do this, apply the following stages:

Neolane
2 Select the Access external data option and click Next.
3 Select the external account and choose the table you want.
Note:
For more information on configuring external accounts, refer to the Workflows guide.
Click the Next button to launch schema generation.
120 | Neolane 2013

4 Check and make any necessary alterations to the new schema settings and click Save.
Extending an existing schema
Warning:
Some out-of-the-box schemas must not be extended: mainly those for which the following settings are
defined:
dataSource="file" and mappingType="xmlFile".
The following schemas must not be extended: xtk:entityBackupNew, xtk:entityBackupOriginal,
xtk:entityOriginal, xtk:form, xtk:srcSchema, ncm:publishing, nl:monitoring, nms:calendar,
nms:remoteTracking, nms:userAgentRules, xtk:builder, xtk:connections, xtk:dbInit, xtk:funcList,
xtk:fusion,xtk: jst, xtk:navtree, xtk:queryDef, xtk:resourceMenu, xtk:schema, xtk:scriptContext,
xtk:session, xtk:sqlSchema, xtk:strings.
This list is not exhaustive.
There are two methods for extending an existing schema:
1 Modifying the source schema directly.

2 Creating another schema with the same name but a different namespace. The advantage is that you can
extend a table without needing to modify the original schema.
The root element of the schema must contain the extendedSchema attribute with the name of the
schema to be extended as its value.
An extension schema does not have its own schema: the schema generated from the source schema will
be filled in with the fields of the extension schema.
Example: extension of the nms:recipient schema.
<srcSchema extendedSchema="nms:recipient" name="recipient" namespace="cus">
<attribute name="code" label="Branch code" type="long"/>
</element>
</srcSchema>
The nms:recipient extended schema is filled in with the field populated in the extension schema:
<schema dependingSchemas="cus:recipient" name="recipient" namespace="nms">
...
<attribute belongsTo="cus:recipient" label="Branch code" name="code" sqlname="iCode"
type="long"/>
...
</schema>

Neolane
The dependingSchemas attribute on the root element of the schema references the dependences on
the extension schemas.
The belongsTo attribute on the field fills in the schema where it is declared.
Important:
Do not modify the standard schemas of the application, but rather the schema extension mechanism.
Otherwise, modified schemas will not be updated at the time of future upgrades of the application. This can
lead to malfunctions in the use of Neolane.
Protecting schemas
System filters
System filters let you manage the read and write permissions of entities detailed in schemas.
n readAccess: provides read only access to schema data.
n writeAccess: provides write access to schema data.
These filters are entered at the main <emphasis>element</emphasis> level of the schemas and, as shown
in the following examples, can be formed to restrict access:
n Example 1:
Here, the filter is used to disallow write permissions on the schema for operators without the named
admin permission. This means that only administrators will have write permissions on entities described
by this schema.
<sysFilter name="writeAccess">
<condition enabledIf="hasNamedRight('admin')=false" expr="FALSE"/>
</sysFilter>
n Example 2:
Here, the filter is used to disallow both read and write permissions on the schema for all operators. Only
the internal account, represented by the expression "$(loginId)!=0", has these permissions.
<sysFilter name="readAccess">
<condition enabledIf="$(loginId)!=0" expr="FALSE"/>
</sysFilter>
<sysFilter name="writeAccess">
<condition enabledIf="$(loginId)!=0" expr="FALSE"/>
</sysFilter>
Possible expr attribute values used to define the condition are TRUE and FALSE.
Note:
If no filter is specified, all operators will have read and write access to the schema.
Protecting out-of-the-box schemas

By default, out-of-the-box schemas are only accessible with write permissions for operators with admin
rights:
n ncm:publishing
n nl:monitoring
n nms:calendar
n xtk:builder
122 | Neolane 2013

n xtk:connections
n xtk:dbInit
n xtk:entityBackupNew
n xtk:entityBackupOriginal
n xtk:entityOriginal
n xtk:form
n xtk:funcList
n xtk:fusion
n xtk:image
n xtk:javascript
n xtk:jssp
n xtk:jst
n xtk:navtree
n xtk:operatorGroup
n xtk:package
n xtk:queryDef
n xtk:resourceMenu
n xtk:rights
n xtk:schema
n xtk:scriptContext
n xtk:specFile
n xtk:sql
n xtk:sqlSchema
n xtk:srcSchema
n xtk:strings
n xtk:xslt
Warning:
Read and write permissions for the xtk:sessionInfo schema are now only accessible via the internal account
of a Neolane instance.
Modifying system filters of out-of-the-box schemas

You can still modify the system filters of the out-of-the-box schemas which are by default protected due to
compatibility issues with older versions:
Note:
In order to guarantee optimal security, Neolane recommends you do not modify the default parameters.
1 Create an extension for the concerned schema or open an existing extension.

2 Add a child element <sysFilter name="<filter name>" _operation="delete"/> in the main element
to delete application of the filter under the same in the origin schema.
3 If you like, you can add a new filter, as detailed in System filters [page 122].

Neolane
Updating the physical structure of the database

To apply the modifications made to the schemas, launch the database update wizard. This wizard is accessible
via Tools>Advanced>Update database structure. It checks whether the physical structure of the
database matches its logical description and executes the SQL update scripts.
The modules in the database are automatically populated and activated.
The Add stored procedures and Import initialization data options are used to launch the initial SQL
scripts and the data packages executed when the database is created.
You can import a set of data from an external data package. To do this, select Import a package and enter
the XML file of the package.
124 | Neolane 2013

Follow the steps and view the database update SQL script:
Note:
This is in an editing field and can be modified in order to delete or add SQL code.
Next, launch the database update:
New field wizard

A wizard accessible via Tools>Advanced>Add new fields lets you add one or more fields to a table in
the database.
Validating the wizard updates the extension schema of the table to be extended and launches the SQL script
to modify the physical structure of the database.
This assistant has the advantage of quickly adding a field without needing to know the structure of a data
schema.
The main disadvantage is the limitation of the data and the properties to be extended.

Neolane
The wizard screens contain the following steps:
1 The first page lets you enter the name of the schema to be extended and the namespace of the extension
schema where the modifications will be saved:
2 The next page lets you enter the properties of the field to be added.
3 To confirm the changes, click the Finish button.

An extension file, called "cus:recipient" in our example, is automatically created and the corresponding SQL
script is executed:
<srcSchema extendedSchema="nms:recipient" label="Recipients" name="recipient"
namespace="cus">
126 | Neolane 2013

<attribute belongsTo="cus:recipient" dataPolicy="email" label="Email" length="80"

name="email1" sqlname="sEmail1" type="string" user="true"/>
</element>
</srcSchema>
Note:
By default, the added fields are declared with the property user (with the value "true"). This lets you display
and edit the field in the input form of the extended schema using a "treeEdit"-type control (refer to Input
forms [page 133]).
Schema structure
The structure of a data schema is shown in the form of a tree structure. To view it graphically in the Neolane
client console, select the targeted schema and click the Structure sub-tab.
As a standard, the fields are displayed first (Active, Activated, etc.) and in alphabetical order. The structuring
elements come next (Postal address, Location), and finally the links (E-mail information, Folder, etc.).
Primary keys are identified by a red key, and foreign keys are identified by a yellow key.
Links are distinguished graphically depending on whether they belong to the table. Those that start from the
table, i.e. that have the foreign key in the table, are displayed first (E-mail information, Folder, Country).
"Reverse" collection links (Subscription, Orders, etc.) are displayed at the end.
Regenerating all schemas

To regenerate all the schemas and solve certain dependency problems in the reverse links, launch the
following command from the Neolane application server:
nlserver config -postupgrade -instance:<instance_name> -force
You must then reboot the Neolane application server and reconnect to the client console.
Examples
Extending a table
To extend the nms:recipient schema recipient table, apply the following procedure:

Neolane
1 Create the extension schema (cus:extension) using the following data:

<srcSchema mappingType="sql" name="extension" namespace="cus" xtkschema="xtk:srcSchema"
extendedSchema="nms:recipient">
<enumeration basetype="string" default="area1" name="area">
<value label="Zone 1" name="area1"/>
</enumeration>
<element name="extension">
<dbindex name="area">
<keyfield xpath="location/@area"/>
</dbindex>
<attribute label="Loyalty code" name="fidelity" type="long"/>

<attribute name="area" label="Purchasing zone" type="string" length="50"
enum="area"/>
</element> </element>
</srcSchema>
In this example, an indexed field (fidelity) is added, and the location element (which already existed
in the nms:recipient schema) is supplemented with an enumerated field (area).
Warning:
Remember to add the extendedSchema attribute to reference the extension schema.
2 Check that the extended schema is the nms:recipient schema and that the additional data is present:
<schema dependingSchemas="cus:extension" mappingType="sql" name="recipient"
namespace="nms" xtkschema="xtk:schema">
...
<enumeration basetype="string" default="area1" name="area">
</enumeration>
...
<element autopk="true" name="recipient" sqltable="NmsRecipient">
<dbindex name="area">
<keyfield xpath="location/@area"/>
</dbindex>
...
<attribute belongsTo="cus:extension" label="Loyalty code" name="fidelity"
sqlname="iFidelity" type="long"/>
...
<attribute enum="area" label="Purchasing zone" length="50" name="area"
sqlname="sArea" type="string"/>
</element>
...
</element>
</schema>
The SQL script generated from the database update wizard is as follows:
ALTER TABLE NmsRecipient ADD iFidelity INTEGER;
UPDATE NmsRecipient SET iFidelity = 0;
ALTER TABLE NmsRecipient ALTER COLUMN iFidelity SET NOT NULL;ALTER TABLE NmsRecipient
ALTER COLUMN iFidelity SET Default 0;
ALTER TABLE NmsRecipient ADD sArea VARCHAR(50);
CREATE INDEX NmsRecipient_area ON NmsRecipient(sArea);
Linked collection table

This section describes how to create an order table linked to the recipient table with cardinality 1-N.
Order table source schema:
128 | Neolane 2013

<srcSchema label="Order" name="order" namespace="cus" xtkschema="xtk:srcSchema">

<element autopk="true" name="order">
<compute-string expr="@number" + '(' + ToString(@date) + ')'/>
<attribute label="Number" length="128" name="number" type="string"/>

<attribute desc="Order date" label="Date" name="date" type="datetime"
default="GetDate()"/>
<attribute desc="order total" label="Total" name="total" type="double"/>
<element label="Recipient" name="recipient" revDesc="Orders associated with this
recipient" revIntegrity="own" revLabel="Orders" target="nms:recipient" type="link"/>
</element>
</srcSchema>
The table type is autopk in order to create an auto-generated primary key to be used by the join of the link
to the recipient table.
Schema generated:
<schema label="Order" mappingType="sql" name="order" namespace="cus" xtkschema="xtk:schema">
<element autopk="true" label="Order" name="order" sqltable="CusOrder">

<compute-string expr="ToString(@date) + ' - ' + @number"/>

</dbindex>

</key>
<dbindex name="recipientId">
<keyfield xpath="@recipient-id"/>
</dbindex>
<attribute desc="Internal primary key" label="Primary key" name="id" sqlname="iOrderId"

type="long"/>
<attribute label="Number" length="128" name="number" sqlname="sNumber" type="string"/>
<attribute desc="Order date" label="Date" name="date" sqlname="tsDate" type="datetime"/>
<attribute desc="order total" label="Total" name="total" sqlname="Total" type="double"/>
<element label="Recipient" name="recipient" revLink="order" target="nms:recipient"

type="link">
<join xpath-dst="@id" xpath-src="@recipient-id"/>
</element>
<attribute advanced="true" label="Foreign key of 'Recipient' link ('id' field)"
name="recipient-id" sqlname="iRecipientId" type="long"/>
</element>
</schema>
The table creation SQL script is as follows:

CREATE TABLE CusOrder(dTotal DOUBLE PRECISION NOT NULL Default 0, iOrderId INTEGER NOT
NULL Default 0, iRecipientId INTEGER NOT NULL Default 0, sNumber VARCHAR(128), tsDate
TIMESTAMP Default NULL);
CREATE UNIQUE INDEX CusOrder_id ON CusOrder(iOrderId);
CREATE INDEX CusOrder_recipientId ON CusOrder(iRecipientId);
INSERT INTO CusOrder (iOrderId) VALUES (0);
Note:
The SQL command INSERT INTO at the end of the script lets you insert an identifier record set to 0 in order
to simulate outer joins.
Extension table
An extension table lets you extend the content of an existing table in a linked table of cardinality 1-1.

Neolane
The purpose of an extension table is to avoid limitations on the number of fields supported in a table, or to
optimize the space occupied by the data, which is consumed on demand.
Creating the extension table schema (cus:feature):
<srcSchema mappingType="sql" name="feature" namespace="cus" xtkschema="xtk:srcSchema">
<element autopk="true" name="feature">
<attribute label="Children" name="children" type="byte"/>
<attribute label="Single" name="single" type="boolean"/>
<attribute label="Spouse first name" length="100" name="spouseFirstName" type="string"/>
</element>
</srcSchema>
Creating an extension schema on the recipient table to add the link of cardinality 1-1:
<srcSchema extendedSchema="nms:recipient" label="Recipient" mappingType="sql"
name="recipient" namespace="cus" xtkschema="xtk:srcSchema">
<element desc="Features" integrity="own" label="Features" name="feature"
revCardinality="single" revLink="recipient" target="cus:feature" type="link"/>
</element>
</srcSchema>
Note:
The definition of the link between the recipient table and the extension table must be populated from the
schema containing the foreign key.
The SQL script for creating the extension table is as follows:

CREATE TABLE CusFeature( iChildren NUMERIC(3) NOT NULL Default 0, iFeatureId INTEGER NOT
NULL Default 0, iSingle NUMERIC(3) NOT NULL Default 0, sSpouseFirstName VARCHAR(100));
CREATE UNIQUE INDEX CusFeature_id ON CusFeature(iFeatureId);
INSERT INTO CusFeature (iFeatureId) VALUES (0);
The recipient table SQL update script is as follows:

ALTER TABLE NmsRecipient ADD iFeatureId INTEGER;
UPDATE NmsRecipient SET iFeatureId = 0;
ALTER TABLE NmsRecipient ALTER COLUMN iFeatureId SET NOT NULL;
ALTER TABLE NmsRecipient ALTER COLUMN iFeatureId SET Default 0;
CREATE INDEX NmsRecipient_featureId ON NmsRecipient(iFeatureId);
Overflow table
An overflow table is an extension table (cardinality 1-1), but the declaration of the link to the table to be
extended is populated in the schema of the overflow table.
The overflow table contains the foreign key to the table to be extended. The table to be extended is therefore
not modified. The relation between the two tables is the value of the primary key of the table to be extended.
Creating the overflow table schema (cus:overflow):
<srcSchema label="Overflow" name="overflow" namespace="cus" xtkschema="xtk:srcSchema">
<element name="overflow">
<keyfield xlink="recipient"/>
</key>
<attribute label="Children" name="children" type="byte"/>

<attribute label="Single" name="single" type="boolean"/>
<attribute label="Spouse first name" length="100" name="spouseFirstName" type="string"/>
<element label="Customer" name="recipient" revCardinality="single" revIntegrity="own"

revExternalJoin="true" target="nms:recipient" type="link"/>
</element>
</srcSchema>
130 | Neolane 2013

Note:
The primary key of the overflow table is the link to the table to be extended ("nms:recipient" schema in our
example).

CREATE TABLE CusOverflow(iChildren NUMERIC(3) NOT NULL Default 0, iRecipientId INTEGER NOT
NULL Default 0, iSingle NUMERIC(3) NOT NULL Default 0, sSpouseFirstName VARCHAR(100));
CREATE UNIQUE INDEX CusOverflow2_id ON CusOverflow2(iRecipientId);
Relationship table
A relationship table lets you link two tables with cardinality N-N. This table contains only the foreign keys of
the tables to be linked.
Example of a relationship table between groups (nms:group) and recipients (nms:recipient).
Source schema of the relationship table:
<srcSchema name="rcpGrpRel" namespace="cus">
<element name="rcpGrpRel">
<keyfield xlink="rcpGroup"/>
<keyfield xlink="recipient"/>
</key>
<element integrity="neutral" label="Recipient" name="recipient" revDesc="Groups to

which this recipient belongs" revIntegrity="own" revLabel="Groups" target="nms:recipient"
type="link"/>
<element integrity="neutral" label="Group" name="rcpGroup" revDesc="Recipients in the
group" revIntegrity="own" revLabel="Recipients" revLink="rcpGrpRel" target="nms:group"
type="link"/>
</element>
</srcSchema>
The schema generated is as follows:

<schema mappingType="sql" name="rcpGrpRel" namespace="cus" xtkschema="xtk:schema">
<element name="rcpGrpRel" sqltable="CusRcpGrpRel">
<compute-string expr="ToString([@rcpGroup-id]) + ',' + ToString([@recipient-id])"/>

<keyfield xpath="@rcpGroup-id"/>
</dbindex>

</key>
<dbindex name="rcpGroupId">
</dbindex>
<dbindex name="recipientId">
</dbindex>
<element integrity="neutral" label="Recipient" name="recipient" revLink="rcpGrpRel"

target="nms:recipient" type="link">
<join xpath-dst="@id" xpath-src="@recipient-id"/>
</element>
<attribute advanced="true" label="Foreign key of 'Recipient' link ('id' field)"
name="recipient-id" sqlname="iRecipientId" type="long"/>
<element integrity="neutral" label="Group" name="rcpGroup" revLink="rcpGrpRel"

target="nms:group" type="link">
<join xpath-dst="@id" xpath-src="@rcpGroup-id"/>
</element>
<attribute advanced="true" label="Foreign key of 'Group' link ('id' field)"
name="rcpGroup-id" sqlname="iRcpGroupId" type="long"/>

Neolane
</element>
</schema>

CREATE TABLE CusRcpGrpRel( iRcpGroupId INTEGER NOT NULL Default 0, iRecipientId INTEGER
NOT NULL Default 0);
CREATE UNIQUE INDEX CusRcpGrpRel_id ON CusRcpGrpRel(iRcpGroupId, iRecipientId);
CREATE INDEX CusRcpGrpRel_recipientId ON CusRcpGrpRel(iRecipientId);
132 | Neolane 2013

CHAPTER 4
Input forms
Table of Contents
Identifying a form . . . . . . . . . . . . . . . . . . . . . . . . . 133
Editing forms . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
Form structure . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
Formatting . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
Containers . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
Editing a link . . . . . . . . . . . . . . . . . . . . . . . . . . 139
List of links . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
Memory list controls . . . . . . . . . . . . . . . . . . . . . . . . 142
Non-editable fields . . . . . . . . . . . . . . . . . . . . . . . . 143
Radio button . . . . . . . . . . . . . . . . . . . . . . . . . . 144
Checkbox . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
Navigation hierarchy edit . . . . . . . . . . . . . . . . . . . . . . 144
Expression field . . . . . . . . . . . . . . . . . . . . . . . . . 144
Context of forms . . . . . . . . . . . . . . . . . . . . . . . . . 145
Wizards . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
An input form lets you edit an instance associated with a data schema from the Neolane client
console.
Identifying a form
An input form is identified by its name and namespace.
The identification key of a form is a string made up of the namespace and the name separated by
a colon (':') (for example: "cus:contact").
Neolane v6.1 - Configuration Guide - Input forms | 133

Neolane
Editing forms
The input form creation and configuration screen is accessible from the Administration > Configuration
> Input forms folder of the Neolane client console:
The editing zone lets you enter the XML content of the input form:
134 | Neolane 2013

Input forms
The preview generates a display of the input form:
Form structure
The description of a form is a structured XML document that observes the grammar of the form schema
xtk:form.
The XML document of the input form must contain the <form> root element with the name and namespace
attributes to populate the form name and namespace.
<form name="form_name" namespace="name_space">
...
</form>
By default, a form is associated with the data schema with the same name and namespace. To associate a
form with a different name, set the entity-schema attribute of the <form element to the name of the
schema key.
To illustrate the structure of an input form, let us describe an interface using the "cus:recipient" example
schema:
<enumeration name="gender" basetype="byte">
<value name="male" label="Male" value="1"/>
<value name="female" label="Female" value="2"/>
</enumeration>
of recipient"/>
<attribute name="birthDate" type="datetime" label="Date"/>
<attribute name="gender" type="byte" label="Gender" enum="gender"/>
</element>
</srcSchema>
The input form based on the example schema:

Neolane
<form name="recipient" namespace="cus">

<input xpath="@gender"/>
<input xpath="@birthDate"/>
<input xpath="@email"/>
</form>
The description of the edit controls starts from the <form> root element.
An edit control is entered in an <input> element with the xpath attribute containing the path of the field
in its schema.
The edit control automatically adapts to the corresponding data type and uses the label defined in the schema.
Note:
You can overload the label defined in its data schema by adding the label attribute to the <input element:
<input xpath="@name" label="E-mail address"/>
By default, each field is displayed on a single line and occupies all available space depending on the type of
data.
Formatting
The layout of the controls looks like the layout used in HTML tables, with the possibility of dividing a control
into several columns, interlacing elements, or specifying the occupation of available space. Remember,
however, that formatting only lets you divide the area up by proportions; you cannot specify fixed dimensions
for an object.
To display the controls of the above example in two columns:

<container colcount="2">
</container>
</form>
The <container> element with the colcount attribute lets you force the display of child controls onto two
columns.
The colspan attribute on a control extends the control by the number of columns entered in its value:

<input xpath="@email" colspan="2"/>
</container>
</form>
By populating the type="frame" attribute, the container adds a frame around the child controls with the
label contained in the label attribute:
136 | Neolane 2013

Input forms

<container colcount="2" type="frame" label="General">
</container>
</form>
A <static> element can be used to format the input form:

<static type="separator" colspan="2" label="General"/>
<static type="help" label="General information about recipient with date of birth, gender,
and e-mail address." colspan="2"/>
</form>
The <static> tag with the separator type lets you add a separator bar with a label contained in the label
attribute.
A help text was added using the <static tag with a help type. The content of the text is entered in the label
attribute.
Containers
Containers let you group a set of controls. They are represented by the <container> element. They were
used above to format controls over several columns.
The xpath attribute on a <container lets you simplify the referencing of child controls. The referencing of
controls is then relative to the parent <container parent.
Example of a container without "xpath":
<input xpath="location/@zipCode"/>
<input xpath="location/@city"/>
</container>
Example with the addition of "xpath" to the element called "location":

<container colcount="2" xpath="location">
<input xpath="@zipCode"/>
<input xpath="@city"/>
</container>
Types of container
Containers are used to construct complex controls using a set of fields formatted in pages.
Tab container
A tab container formats data in pages that are accessible from tabs.
<container type="notebook">
<container colcount="2" label="General">

Neolane
</container>
<container colcount="2" label="Location">
...
</container>
</container>
The main container is defined by the type="notebook" attribute. Tabs are declared in the child containers,
and the label of the tabs is populated from the label attribute.
Note:
A style="down|up(by default)" feature forces the vertical positioning of tab labels below or above the
control. This feature is optional.
<container type="notebook" style="down">

...
</container>
Icon list
This container displays a vertical icon bar that lets you select the pages to be displayed.
<container type="iconbox">
<container colcount="2" label="General" img="xtk:properties.png">
</container>
<container colcount="2" label="Location" img="nms:msgfolder.png">
...
</container>
</container>
The main container is defined by the type="iconbox" attribute. The pages associated with the icons are
declared in the child containers. The label of the icons is populated from the label attribute.
The icon of a page is populated from the img="<image>" attribute, where <image> is the name of the
image corresponding to its key made up of the name and namespace (e.g., "xtk:properties.png").
The images are available from the Administration > Configuration > Images node.
Visibility container
You can mask a set of controls via a dynamic condition.
This example illustrates the visibility of controls on the value of the "Gender" field:
<container type="visibleGroup" visibleIf="@gender=1">
...
</container>
<container type="visibleGroup" visibleIf="@gender=2">
...
</container>
138 | Neolane 2013

Input forms
A visibility container is defined by the attribute type="visibleGroup". The visibleIf attribute contains the
visibility condition.
Examples of condition syntax:
n visibleIf="@email='peter.martinez@neeolane.net'": tests equality on string-type data. The
comparison value must be in quotes.
n visibleIf="@gender >= 1 and @gender!= 2": condition on a numeric value.
n visibleIf="@boolean1==true or @boolean2==false": test on Boolean fields.
Enabling container
This container lets you enable or disable a set of data from a dynamic condition. Disabling a control prevents
it from being edited. The following example illustrates the enabling of controls from the value of the "Gender"
field:
<container type="enabledGroup" enabledIf="@gender=1">
...
</container>
<container type="enabledGroup" enabledIf="@gender=2">
...
</container>
An enabling container is defined by the type="enabledGroup" attribute. The enabledIf attribute contains
the activation condition.
Editing a link
Remember that a link is declared in the data schema as follows:
<element label="Company" name="company" target="cus:company" type="link"/>
The edit control of the link in its input form is as follows:
<input xpath="company"/>
Target selection is accessible via the edit field. Entry is assisted by type-ahead so that a target element can
easily be found from the first few characters entered. The search is then based on the Compute string
defined in the targeted schema. If the schema does not exist after validation in the control, a confirmation
message of on-the-fly target creation is displayed. The confirmation creates a new record in the target table
and associates it with the link.
A drop-down list is used to select a target element from the list of records already created.
The Modify the link (folder) icon launches a selection form with the list of targeted elements and a filter
zone:
The Edit link (magnifier) icon launches the edit form of the linked element. The form used is deduced by
default on the key of the targeted schema. The form attribute lets you force the name of the edit form (e.g.
"cus:company2").

Neolane
You can restrict the choice of target elements by adding the <sysFilter> element from the link definition
in the input form:
<input xpath="company">
<sysFilter>
<condition expr="[location/@city] = 'Newton"/>
</sysFilter>
</input>
You can also sort the list with the <orderBy> element:
<input xpath="company">
<orderBy>
<node expr="[location/@zipCode]"/>
</orderBy>
</input>
Control properties
n noAutoComplete: disables type-ahead (with the value "true")
n createMode: creates the link on the fly if it does not exist. Possible values are:
n none: disables creation. An error message is displayed if the link does not exist
n inline: creates the link with the content in the edit field
n edition: displays the edit form on the link. When the form is validated, the data is saved (default
mode)
n noZoom: no edit form on the link (with the value "true")
n form: overloads the edit form of the targeted element
List of links
A link entered in the data schema as a collection element (unbound="true") must go through a list in order
to view all the elements associated with it.
The principle consists in displaying the list of linked elements with optimized data loading (downloading by
data batch, execution of the list only if it is visible).
Example of a collection link in a schema:
<element label="Events" name="rcpEvent" target="cus:event" type="link" unbound="true">
...
</element>
The list in its input form:
<input xpath="rcpEvent" type="linklist">

<input xpath="@label"/>
<input xpath="@date"/>
</input>
List control is defined by the type="linklist" attribute. The list path must refer to the collection link.
The columns are declared via the <input> elements of the list. The xpath attribute refers to the path of
the field in the target schema.
A toolbar with a label (defined on the link in the schema) is automatically placed above the list.
The list can be filtered via the Filters button and configured to add and sort the columns.
The Add and Delete buttons let you add and delete collection elements on the link. By default, adding an
element launches the edit form of the target schema.
The Detail button is automatically added when the zoom="true" attribute is completed on the <input>
tag of the list: it lets you launch the edit form of the selected line.
140 | Neolane 2013

Input forms
Filtering and sorting can be applied when the list is being loaded:
<input xpath="rcpEvent" type="linklist">
<sysFilter>
<condition expr="@type = 1"/>
</sysFilter>
<orderBy>
<node expr="@date" sortDesc="true"/>
</orderBy>
</input>
Relationship table
A relationship table lets you link two tables with N-N cardinality. The relationship table contains only the links
to the two tables.
Adding an element to the list should therefore let you complete a list from one of the two links in the
relationship table.
Example of a relationship table in a schema:
<srcSchema name="subscription" namespace="cus">
<element name="recipient" type="link" target="cus:recipient" label="Recipient"/>
<element name="service" type="link" target="cus:service" label="Subscription service"/>
</srcSchema>
For our example, we start with the input form of the "cus:recipient" schema. The list must display the
associations with subscriptions to services and must allow you to add a subscription by selecting an existing
service.
<input type="linklist" xpath="subscription" xpathChoiceTarget="service"

xpathEditTarget="service" zoom="true">
<input xpath="recipient"/>
<input xpath="service"/>
</input>
The xpathChoiceTarget attribute lets you launch a selection form from the link entered. Creating the
relationship table record will automatically update the link to the current recipient and the selected service.
Note:
The xpathEditTarget attribute lets you force editing of the selected line on the link entered.
List properties
n noToolbar: hides the toolbar (with value "true")
n toolbarCaption: overloads the toolbar label
n toolbarAlign: modifies the vertical or horizontal geometry of the toolbar (possible values:
"vertical"|"horizontal")
n img: displays the image associated with the list

Neolane

n zoom: adds the Zoom button to edit the targeted element
n xpathEditTarget: sets editing on the link entered
n xpathChoiceTarget: for addition, launches the selection form on the link entered
Memory list controls

Memory lists let you edit the collection elements using list data preloading. This list cannot be filtered or
configured.
These lists are used on XML mapped collection elements or on low-volume links.
Column list
This control displays an editable column list with a toolbar containing Add and Delete buttons.
<input xpath="rcpEvent" type="list">

</input>
The list control must be filled in with the type="list" attribute, and the path of the list must refer to the
collection element.
The columns are declared in the child <input> tags of the list. Column label and size can be forced with
the label and colSize attributes.
Note:
Sort-order arrows are added automatically when the ordered="true" attribute is added to the collection
element in the data schema.
The toolbar buttons can be aligned horizontally:
<input nolabel="true" toolbarCaption="List of events" type="list" xpath="rcpEvent"

zoom="true">
</input>
The toolbarCaption attribute forces the horizontal alignment of the toolbar and enters the title above the
list.
142 | Neolane 2013

Input forms
Zoom in a list
Insertion and editing of the data in a list can be entered in a separate edit form.
<input nolabel="true" toolbarCaption="List of events" type="list" xpath="rcpEvent"

zoom="true" zoomOnAdd="true">
<form colcount="2" label="Event">

</form>
</input>
The edit form is completed from the <form> element under list definition. Its structure is identical to that
of an input form.
The Detail button is added automatically when the zoom="true" attribute is completed on the <input>
tag of the list. This attribute lets you launch the edit form of the selected line.
Note:
Adding the zoomOnAdd="true" attribute forces the edit form to be called up when a list element is inserted.
List properties
n noToolbar: hides the toolbar (with value "true")
n toolbarCaption: overloads the toolbar label
n toolbarAlign: modifies the positioning of the toolbar (possible values: "vertical"|"horizontal")
n img: displays the image associated with the list
n zoom: adds the Zoom button to edit the targeted element
n zoomOnAdd: launches the edit form on the addition
n xpathChoiceTarget: for addition, launches the selection form on the link entered
Non-editable fields
To display a field and prevent it from being edited, use the <value> tag or complete the readOnly="true"
attribute on the <input> tag.
Example on the "Gender" field:
<value value="@gender"/>
<input xpath="@gender" readOnly="true"/>

Neolane
Radio button
A radio button lets you choose from several options. The <input> tags are used to list the possible options,
and the checkedValue attribute specifies the value associated with the choice.
Example on the "Gender" field:
<input type="RadioButton" xpath="@gender" checkedValue="0" label="Choice 1"/>
Checkbox
A checkbox reflects a Boolean state (selected or not). By default, this control is used by "Boolean" (true/false)
fields. A variable taking a default value of 0 or 1 can be associated with this button. This value can be
overloaded via the checkValue attributes.
<input xpath="@boolean1"/>
<input xpath="@field1" type="checkbox" checkedValue="Y"/>
Navigation hierarchy edit

This control builds a tree on a set of fields to be edited.
The controls to be edited are grouped in a <container> entered under the <input> tag of the tree control:
<input nolabel="true" type="treeEdit">
<container label="Text fields">
<input xpath="@text1"/>
<input xpath="@text2"/>
</container>
<container label="Boolean fields">
</container>
</input>
Expression field
An expression field updates a field dynamically from an expression; the <input> tag is used with an xpath
attribute to enter the path of the field to be updated and an expr attribute containing the update expression.

<input expr="Iif([/tmp/@flag]=='On', true, false)" type="expr" xpath="@boolean1"/>
<input expr="[/ignored/@action] == 'FCP'" type="expr" xpath="@launchFCP"/>
144 | Neolane 2013

Input forms
Context of forms
The execution of an input form initializes an XML document containing the data of the entity being edited.
This document represents the context of the form, and can be used as a workspace.
Updating the context

To modify the context of the form, use the <set xpath="<field>" expr="<value>"/> tag, where
<field> is the destination field, and <value> is the update expression or value.
Examples of use of the <set> tag:
n <set xpath="/tmp/@test" expr="'Test'"/: positions the 'Test' value at temporary location
/tmp/@test1
n <set xpath="@lastName" expr="'Test'"/: updates the entity on the "lastName" attribute with
the 'Test' value
n <set xpath="@boolean1" expr="true"/: sets the value of the "boolean1" field to "true"
n <set xpath="/tmp/@test" expr="@lastName"/: updates with the content of the "lastName"
attribute
The context of the form can be updated when initializing and closing the form via the <enter> and <leave>
tags.
<enter>
<set...
</enter>
...
<leave>
<set...
</leave>
</form>
Note:
The <enter> and <leave> tags can be used on the <container> of pages ("notebook" and "iconbox" types).
Expression language
A macro-language can be used in form definition in order to perform conditional tests.
The <if expr="<expression>"> tag executes the instructions specified under the tag if the expression
is verified:
<if expr="([/tmp/@test] == 'Test' or @lastName!= 'Doe') and @boolean2 == true">
<set xpath="@boolean1" expr="true"/>
</if>
The <check expr="<condition>"> tag combined with the <error> tag prevents validation of the
form and displays an error message if the condition is not satisfied:
<leave>
<check expr="/tmp/@test!= ''">
<error>You must populate the 'Test' field!</error>
</check>
</leave>
Wizards
A wizard guides you through a set of data entry steps in the form of pages. The data entered is saved when
you validate the form.
A wizard has the following structure:
<form type="wizard" name="example" namespace="cus" img="nms:rcpgroup32.png" label="Wizard
example" entity-schema="nms:recipient">
<container title="Title of page 1" desc="Long description of page 1">
<input xpath="@lastName"/>
<input xpath="comment"/>
</container>
<container title="Title of page 2" desc="Long description of page 2">
...

Neolane
</container>
...
</form>
The presence of the type="wizard" attribute on the <form> element lets you define the wizard mode in
the construction of the form.
The pages are completed from <container elements, which are children of the <form> element. The
<container element of a page is populated with the title attributes for the title and desc to display the
description under the page title.
The Previous and Next buttons are automatically added to allow browsing between pages.
The Finish button saves the data entered and closes the form.
SOAP methods
SOAP method execution can be launched from a populated <leave> tag at the end of a page.
The <soapCall> tag contains the call for the method with the following input parameters:
<soapCall name="<name>" service="<schema>">
<param type="<type>" exprIn="<xpath>"/>
...
</soapCall>
The name of the service and its implementation schema are entered via the name and service attributes
of the <soapCall> tag.
The input parameters are described on the <param> elements under the <soapCall> tag.
The parameter type must be specified via the type attribute. The possible types are as follows:
n string: character string
n boolean: Boolean
n byte: 8-bit integer
n short: 16-bit integer
n long: 32-bit integer
n short: 16-bit integer
n double: double-precision floating point number
n DOMElement: element-type node
The exprIn attribute contains the location of the data to be passed as a parameter.
Example:
<leave>
<soapCall name="RegisterGroup" service="nms:recipient">
<param type="DOMElement" exprIn="/tmp/entityList"/>
<param type="DOMElement" exprIn="/tmp/choiceList"/>
<param type="boolean" exprIn="true"/>
</soapCall>
</leave>
146 | Neolane 2013

CHAPTER 5
API
Table of Contents
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
Definition of Neolane APIs . . . . . . . . . . . . . . . . . . . . . 148
Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . 148
Using Neolane APIs . . . . . . . . . . . . . . . . . . . . . . . . 148
SOAP calls . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
Resources and exchanges . . . . . . . . . . . . . . . . . . . . . . 149
Example of a SOAP message on the "ExecuteQuery" method . . . . . . . . . . 149
Error management . . . . . . . . . . . . . . . . . . . . . . . . 150
URL of Web service server (or EndPoint) . . . . . . . . . . . . . . . . . 151
Web service calls . . . . . . . . . . . . . . . . . . . . . . . . . . 151
General information . . . . . . . . . . . . . . . . . . . . . . . . 151
Definition of Web services . . . . . . . . . . . . . . . . . . . . . . 151
Web service description: WSDL . . . . . . . . . . . . . . . . . . . . 152
Connectivity . . . . . . . . . . . . . . . . . . . . . . . . . . 153
Data oriented API . . . . . . . . . . . . . . . . . . . . . . . . . 156
Overview of the datamodel . . . . . . . . . . . . . . . . . . . . . 156
Description of the model . . . . . . . . . . . . . . . . . . . . . . 156
Query and Writer . . . . . . . . . . . . . . . . . . . . . . . . . 156
ExecuteQuery (xtk:queryDef) . . . . . . . . . . . . . . . . . . . . 157
Write / WriteCollection (xtk:session) . . . . . . . . . . . . . . . . . . 164
Business oriented APIs . . . . . . . . . . . . . . . . . . . . . . . . 166
Subscribe (nms:subscription) . . . . . . . . . . . . . . . . . . . . . 167
Unsubscribe (nms:subscription) . . . . . . . . . . . . . . . . . . . . 168
SubmitDelivery (nms:delivery) . . . . . . . . . . . . . . . . . . . . 169
Implementing SOAP methods in JavaScript . . . . . . . . . . . . . . . . . 170
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . 170
Definition of a method library . . . . . . . . . . . . . . . . . . . . 170
Use SOAP methods in JavaScript . . . . . . . . . . . . . . . . . . . . 171
Static methods . . . . . . . . . . . . . . . . . . . . . . . . . . 171
Non-static methods . . . . . . . . . . . . . . . . . . . . . . . . 172
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
Adding additional SQL functions . . . . . . . . . . . . . . . . . . . . . 173
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . 173
Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
General structure of package to import . . . . . . . . . . . . . . . . . 173
The <function> function descriptor . . . . . . . . . . . . . . . . . . 174
The "pass-through" function descriptor . . . . . . . . . . . . . . . . . 175
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
Neolane v6.1 - Configuration Guide - API | 147

Neolane
Overview
Definition of Neolane APIs

The Neolane application server was designed for openness and easy integration with increasingly diverse
and complex company information systems.
Neolane APIs are used in JavaScript within the application and in SOAP outside of it. They make up a library
of generic functions that can be enriched. For further information, refer to Implementing SOAP methods in
JavaScript [page 170].
Warning:
Neolane APIs are optional and under license. Check your license contract.
Prerequisites
Before using Neolane APIs, you need to be familiar with the following topics:
n JavaScript
n SOAP protocol
n Neolane datamodel
Using Neolane APIs

Neolane uses two types of APIs:
n Generic data access APIs for querying the datamodel data. Refer to Data oriented API [page 156].
n Business specific APIs that let you act on each object: deliveries, workflows, subscriptions, etc. Refer to
Business oriented APIs [page 166].
In order to develop APIs and interact with Neolane, you need to be familiar with your datamodel. Neolane
lets you generate a complete description of the base. Refer to Description of the model [page 156].
SOAP calls
The SOAP protocol lets you invoke API methods, via the rich client, third-party applications using web services,
or JSP using these methods natively.
Figure 5.1. Neolane architecture
The structure of a SOAP message is as follows:

n an envelope which defines the structure of the message,
n an optional header,
148 | Neolane 2013

API
n a body containing the information about the call and the response,
n error management that defines the error condition.
Resources and exchanges

The following schema shows the various resources involved in the use of Neolane APIs:
Example of a SOAP message on the "ExecuteQuery" method

In this example, a SOAP query invokes the "ExecuteQuery" method, which takes a character string as a
parameter for authentication (session token) and an XML content for the description of the query to be
executed.
For further information, refer to ExecuteQuery (xtk:queryDef) [page 157].
Note:
The WSDL description of this service is completed in the example shown here: Web service description:
WSDL [page 152].
SOAP query
<?xml version='1.0' encoding='ISO-8859-1'?>
<SOAP-ENV:Envelope xmlns:xsd='http://www.w3.org/2001/XMLSchema'
xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
xmlns:ns='http://xml.apache.org/xml-soap'
xmlns:SOAP-ENV='http://schemas.xmlsoap.org/soap/envelope/'>
<SOAP-ENV:Body>
<ExecuteQuery xmlns='urn:xtk:queryDef'
SOAP-ENV:encodingStyle='http://schemas.xmlsoap.org/soap/encoding/'>
<__sessiontoken xsi:type='xsd:string'/>
<entity xsi:type='ns:Element'
SOAP-ENV:encodingStyle='http://xml.apache.org/xml-soap/literalxml'>
<queryDef firstRows="true" lineCount="200" operation="select"
schema="nms:rcpGrpRel" startLine="0" startPath="/" xtkschema="xtk:queryDef">
...
</queryDef>
</entity>
</ExecuteQuery>

Neolane
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
The <SOAP-ENV:Envelope> element is the first element of the message representing the SOAP envelope.
The <SOAP-ENV:Body> element is the first child element of the envelope. It contains the description of the
message, i.e. the content of the query or the response.
The method to be invoked is entered in the <ExecuteQuery> element from the body of the SOAP message.
In SOAP, the parameters are recognized by order of appearance. The first parameter, <__sessiontoken>,
takes the authentication chain, the second parameter is the XML description of the query from the <queryDef>
element.
SOAP response
<SOAP-ENV:Body>
<ExecuteQueryResponse xmlns='urn:xtk:queryDef'
<pdomOutput xsi:type='ns:Element'
<rcpGrpRel-collection><rcpGrpRel group-id="1872"
recipient-id="1362"></rcpGrpRel></rcpGrpRel-collection>
</pdomOutput>
</ExecuteQueryResponse>
</SOAP-ENV:Body>
The result of the query is entered from the <pdomOutput> element.
Error management
Example SOAP error response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV='http://schemas.xmlsoap.org/soap/envelope/'>
<SOAP-ENV:Body>
<SOAP-ENV:Fault>
<faultcode>SOAP-ENV:Server</faultcode>
<faultstring>Error while executing 'Write' of the 'xtk:persist'.</faultstring> service
<detail>ODBC error: [Microsoft][ODBC SQL Server Driver][SQL Server]Cannot insert

duplicate key row in object 'XtkOption' with unique index 'XtkOption_name'. SQLSTate: 23000
ODBC error: [Microsoft][ODBC SQL Server Driver][SQL Server]The statement has been terminated.
SQLSTate: 01000 Cannot save the 'Options (xtk:option)' document </detail>
</SOAP-ENV:Fault>
</SOAP-ENV:Body>
The <SOAP-ENV:Fault> element in the body of the SOAP message is used to convey the error signals arising
during the processing of the Web service. This is composed of the following sub-elements:
n <faultcode>: indicates the type of error. The error types are:
n "VersionMismatch" in the event of incompatibility with the SOAP version used,
n "MustUnderstand" in the event of a problem in the message header,
n "Client" in the event that the client is missing some information,
n "Server" in the event that the server has a problem executing the processing.
n <faultstring>: message describing the error
n <detail>: long error message
The success or failure of the service invocation is identified when the <faultcode> element is verified.
150 | Neolane 2013

API
Important:
All Neolane Web services handle errors. It is therefore strongly recommended to test each call in order to
handle returned errors.
Example of error handling in C#:
try
{
// Invocation of method
...
}
catch (SoapException e)
{
System.Console.WriteLine("Soap exception: " + e.Message);
if (e.Detail!= null)
System.Console.WriteLine(e.Detail.InnerText);
}
URL of Web service server (or EndPoint)

To submit the Web service, the Neolane server that implements the corresponding service method must be
contacted.
The server URL is as follows:
http://<server>/nl/jsp/soaprouter.jsp
With <server> the Neolane application server (nlserver web).
Web service calls
General information
All API methods are presented in the form of Web services. This enables you to manage all Neolane functions
via SOAP calls, which are the native entry point of the Neolane application server. The Neolane console itself
only uses SOAP calls.
Web services let you create many applications from a third-party system:
n Synchronous alerts, notification, and real-time delivery template execution from a back office or transaction
system,
n Development of special interfaces with simplified functionality (Web interfaces, etc.),
n Feeding and lookup of data in the database while observing trade rules and remaining isolated from the
underlying physical model.
Definition of Web services

The definition of the Web services implemented on the Neolane application server is available from the data
schemas.
A Web service is described in the grammar of the data schemas and is available from the <methods>
element.
<methods>
<method name="GenerateForm" static="true">
<help>Generates the form in Mail or Web mode</help>
<parameters>
<param name="formName" type="string" desc="Name of form"/>
<param name="mailMode" type="boolean" desc="Generate a form of type Mail"/>
<param name="result" type="string" inout="out" desc="Result "/>
</parameters>
</method>
</methods>
Here we have an example of the definition of the method called GenerateForm.

Neolane
The description of the service starts with the <method> element. The list of parameters of the method is
completed from the <parameters> element. Each parameter is specified by a name, a type (Boolean, string,
DOMElement, etc.) and a description. The "inout" attribute with the "out" value lets you specify that the
"result" parameter is at the SOAP call output.
The presence of the "static" attribute (with the value "true") describes this method as static, which means
that all parameters of the method must be declared.
A "const" method implicitly has an XML document in the format of its associated schema as its input.
A full description of the <method element of a Neolane schema is available in the "Schema references"
chapter under <method> element [page 103].
Example of the "const"-type "ExecuteQuery" method from the "xtk:queryDef" schema:
<method name="ExecuteQuery" const="true">
<help>Retrieve data from a query</help>
<parameters>
<param desc="Output xml document" name="output" type="DOMDocument" inout="out"/>
</parameters>
</method>
The input parameter of this method is an XML document in the format of the "xtk:queryDef" schema.
Web service description: WSDL

A WSDL (Web Service Description Library) file is available for each service. This XML file uses a metalanguage
to describe the service and to specify the available methods, parameters, and the server to contact for
executing the service.
WSDL file generation

To generate a WSDL file, you must enter the following URL from a Web browser:
https://<server>/nl/jsp/schemawsdl.jsp?schema=<schema>
With:
n <server>: the Neolane application server (nlserver web)
n <schema>: schema identification key (namespace:schema_name)
Example on the "ExecuteQuery" method of schema "xtk:queryDef"

The WSDL file is generated from the URL:
https://localhost/nl/jsp/schemawsdl.jsp?schema=xtk:queryDef
A WSDL description starts by defining the types used to form messages, associated in "ports", connected to
a protocol by "bindings" forming Web services.
Types
Type definitions are based on XML schemas. In our example, the "ExecuteQuery" method takes an "s:string"
string and an XML document (<s:complexType>) as parameters. The return value of the method
("ExecuteQueryResponse") is an XML document (<s:complexType>).
<types>
<s:schema elementFormDefault="qualified" targetNamespace="urn:xtk:queryDef">
<s:element name="ExecuteQuery">
<s:complexType>
<s:sequence>
<s:element maxOccurs="1" minOccurs="1" name="sessiontoken" type="s:string"/>
<s:element maxOccurs="1" minOccurs="1" name="entity">
<s:complexType>
<s:sequence>
<s:any/>
</s:sequence>
</s:complexType>
</s:element>
</s:sequence>
</s:complexType>
</s:element>
<s:element name="ExecuteQueryResponse">
<s:complexType>
<s:sequence>
<s:element maxOccurs="1" minOccurs="1" name="pdomOutput">
152 | Neolane 2013

API
<s:complexType mixed="true">
<s:sequence>
<s:any/>
</s:sequence>
</s:complexType>
</s:element>
</s:sequence>
</s:complexType>
</s:element>
Messages
The <message> describes the names and types of a set of fields to be sent. The method uses two messages
to pass as a parameter ("ExecuteQueryIn") and the return value ("ExecuteQueryOut").
<message name="ExecuteQueryIn">
<part element="tns:ExecuteQuery" name="parameters"/>
</message>
<message name="ExecuteQueryOut">
<part element="tns:ExecuteQueryResponse" name="parameters"/>
</message>
PortType
The <portType> associates the messages on the "ExecuteQuery" operation triggered by the query ("input")
generating a response ("output").
<portType name="queryDefMethodsSoap">
<operation name="ExecuteQuery">
<input message="tns:ExecuteQueryIn"/>
<output message="tns:ExecuteQueryOut"/>
</operation>
</portType>
Binding
The <binding> part specifies the SOAP communication protocol (<soap:binding>), data transport in HTTP
(value of the "transport" attribute) and the data format for the "ExecuteQuery" operation. The body of the
SOAP envelope contains the message segments directly without transformation.
<binding name="queryDefMethodsSoap" type="tns:queryDefMethodsSoap">
<soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
<operation name="ExecuteQuery">
<soap:operation soapAction="xtk:queryDef#ExecuteQuery" style="document"/>
<input>
<soap:body encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
namespace="urn:xtk:queryDef" use="literal"/>
</input>
<output>
<soap:body encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
namespace="urn:xtk:queryDef" use="literal"/>
</output>
</operation>
</binding>
Service
The <service> part describes the "XtkQueryDef" service with its URI on the URL of the Neolane application
server.
<service name="XtkQueryDef">
<port binding="tns:queryDefMethodsSoap" name="queryDefMethodsSoap">
<soap:address location="https://localhost/nl/jsp/soaprouter.jsp"/>
</port>
</service>
Connectivity
Neolane v6.1 has increased security for authentication mechanisms by introducing security zones (refer to
the Defining security zones chapter in the Installation guide) as well as session management settings.
There are two authentication modes available:

Neolane
n via a call to logon method(). This mode generates a session token and a security token. It is the most
secure mode and therefore the most recommended.
or
n via the Neolane login + password that creates a session token. The session token automatically
expires after a set period. This mode is not recommended and requires reducing the application security
settings for some zone settings (allowUserPassword="true" and sessionTokenOnly="true").
Session token characteristics

The session token has the following characteristics:
n a X hour life cycle (the life cycle is configurable in the 'serverConf.xml' file, the default period is 24 hours)
n a random construction (it no longer contains the user login and password)
n when accessed via the Web:
n the session token becomes a permanent token, it is not destroyed once the browser closes
n it is placed in an HTTP-ONLY cookie (cookies must be activated for operators)
Security token characteristics

The security token has the following characteristics:
n it is generated from the session token
n it has a 24 hour life cycle (configurable in the 'serverConf.xml' file, the default period is 24 hours)
n it is stored in the Neolane console
n when accessed via the Web:
n it is stored in a document.__securityToken property
n the page URLs are updated to update the security token
n the forms are also updated via a hidden field containing the token
Security token movement

When accessed via console, it is:
n transmitted in the logon response (in the HTTP header)
n used in each query (in the HTTP header)
From a POST and GET HTTP:
n the server completes the links with the token
n the server adds a hidden field to forms
From an SOAP call:
n it is added to call headers
Call examples
n Using HttpSoapConnection/SoapService:
var cnx = new HttpSoapConnection("https://serverURL/nl/jsp/soaprouter.jsp");

var session = new SoapService(cnx, 'urn:xtk:session');
session.addMethod("Logon", "xtk:session#Logon",
["sessiontoken", "string", "Login", "string", "Password", "string",
"Parameters", "NLElement"],
["sessionToken", "string", "sessionInfo", "NLElement",
"securityToken", "string"]);
var res = session.Logon("", "admin", "pwd", <param/>);

var sessionToken = res[0];
var securityToken = res[2];
cnx.addTokens(sessionToken, securityToken);
var query = new SoapService(cnx, 'urn:xtk:queryDef');
query.addMethod("ExecuteQuery", "xtk:queryDef#ExecuteQuery",
["sessiontoken", "string", "entity", "NLElement"],
["res", "NLElement"]);
154 | Neolane 2013

API
var queryRes = query.ExecuteQuery("", <queryDef operation="select"

schema="nms:recipient">
<select>
<node expr="@email"/>
<node expr="@lastName"/>
<node expr="@firstName"/>
</select>
<where>
<condition expr="@email = 'joe.doe@aol.com'"/>
</where>
</queryDef>);
logInfo(queryRes[0].toXMLString())
n Using HttpServletRequest:
Logon execution():
var req = new

HttpClientRequest("http://dev.nl61-ddo-debian.neolane.org/nl/jsp/soaprouter.jsp");
req.header["Content-Type"] = "text/xml; charset=utf-8";
req.header["SOAPAction"] = "xtk:session#Logon";
req.method = "POST";
req.body = '<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"

xmlns:urn="urn:xtk:session">' +
'<soapenv:Header/><soapenv:Body><urn:Logon>' +
'<urn:sessiontoken/>
<urn:strLogin>admin</urn:strLogin>
<urn:strPassword>pwd</urn:strPassword>
<urn:elemParameters/>' +
'</urn:Logon></soapenv:Body></soapenv:Envelope>';
req.execute();
var resp = req.response;

var xmlRes = new XML(String(resp.body).replace("<?xml version='1.0'?>",""));
var sessionToken = String(xmlRes..*::pstrSessionToken);;
var securityToken = String(xmlRes..*::pstrSecurityToken);
Query execution:
var req2 = new HttpClientRequest("http://serverURL/nl/jsp/soaprouter.jsp");

req2.header["Content-Type"] = "text/xml; charset=utf-8";
req2.header["SOAPAction"] = "xtk:queryDef#ExecuteQuery";
req2.header["X-Security-Token"] = securityToken;
req2.header["cookie"] = "__sessiontoken="+sessionToken;
req2.method = "POST";
req2.body = '<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"

xmlns:urn="urn:xtk:queryDef">' +
'<soapenv:Header/><soapenv:Body><urn:ExecuteQuery><urn:sessiontoken/><urn:entity>' +
'<queryDef operation="select" schema="nms:recipient">' +
'<select><node expr="@email"/><node expr="@lastName"/><node
expr="@firstName"/></select>' +
'<where><condition expr="@email = \'john.doe@aol.com\'"/></where>'
+
'</queryDef>' +
'</urn:entity></urn:ExecuteQuery></soapenv:Body></soapenv:Envelope>';
req2.execute();
var resp2 = req2.response;
logInfo(resp2.body)

Neolane
Data oriented API

Data oriented APIs let you address the entire datamodel.
Overview of the datamodel

Neolane does not offer a dedicated read API per entity (no getRecipient or getDelivery function, etc.). Use
the QUERY & WRITER data read and modification methods to access the data of the model.
Neolane lets you manage collections: queries enable you to recover a set of information collected throughout
the base. Unlike access in SQL mode, Neolane APIs return an XML tree instead of data columns. Neolane
thus creates composite documents with all the collected data.
This operating mode does not offer one-to-one mapping between the attributes and elements of the XML
documents and the columns of the tables in the database.
XML documents are stored in MEMO type fields of the database.
Description of the model

You must be familiar with the Neolane data model to be able to address the fields of the database in your
scripts.
For a presentation of the data model, refer to Neolane datamodel [page 9].
In order to generate its structure, use the following process:
1 Import the datakit\nms\fra\package\optional\dbdBuilder.xml package.

2 Launch the following command on your Neolane instance: nlserver javascript
-instance:<instance> cus:build-dbd.js
The database-description.odt file is generated in the Neolane installation folder and contains a
description of the Neolane tables. This file can be edited with Open Office and/or converted to PDF format
if necessary.
Query and Writer

The following introduction schema details low level exchanges for reading (ExecuteQuery) and writing (Writer)
between database and customer (web pages or Neolane client console).
ExecuteQuery
For columns and conditions, you can use Queries.
This lets you isolate the underlying SQL. The query language does not depend on the underlying engine:
some functions will be re-mapped, which may generate several SELECT SQL orders.
156 | Neolane 2013

API
For more on this, refer to Example on the "ExecuteQuery" method of schema "xtk:queryDef" [page 152].
The ExecuteQuery method is presented in ExecuteQuery (xtk:queryDef) [page 157].
Write
Write commands let you write simple or complex documents, with entries in one or more tables of the base.
Transactional APIs let you manage reconciliations via the updateOrInsert command: one command lets
you create or update data. You can also configure modification merging (merge): this operating mode lets
you authorize partial updates.
The XML structure offers a logical view of the data and lets you sidestep the physical structure of the SQL
table.
The Write method is presented in Write / WriteCollection (xtk:session) [page 164].
ExecuteQuery (xtk:queryDef)
This method lets you perform queries from data associated with a schema. It takes an authentication string
(must be logged in) and an XML document describing the query to be submitted as parameters. The return
parameter is an XML document containing the result of the query in the format of the schema to which the
query refers.
Definition of the "ExecuteQuery" method in the "xtk:queryDef" schema:
<method name="ExecuteQuery" const="true">
<parameters>
<param desc="Output XML document" name="output" type="DOMDocument" inout="out"/>
</parameters>
</method>
Note:
This is a "const" method. The input parameters are included in an XML document in the format of the
"xtk:queryDef" schema.
Format of the XML document of the input query

The structure of the XML document of the query is described in the "xtk:queryDef " schema. This document
describes the clauses of a SQL query: "select", "where", "order by", "group by", "having".
<queryDef schema="schema_key" operation="operation_type">
<select>
<node expr="expression1">
...
</select>
<where>
<condition expr="expression1"/>
...
</where>
<orderBy>
...
</ordery>
<groupBy>
...
</groupBy>
<having>
...
</having>
</queryDef>
A sub-query (<subQuery>) can be defined in a <condition> element. The syntax for a <subQuery> element
is based on the syntax of a <queryDef>.

Neolane
Example of a <subQuery>:
condition setOperator="NOT IN" expr="@id" enabledIf="$(/ignored/@ownerType)=1">

<subQuery schema="xtk:operatorGroup">
<select>
<node expr="[@operator-id]" />
</select>
<where>
<condition expr="[@group-id]=$long(../@owner-id)"/>
</where>
</subQuery>
</condition
A query must reference a start schema from the schema attribute.

The type of operation desired is entered in the operation attribute and contains one of the following values:
n get: retrieves a record from the table and returns an error if the data does not exist,
n getIfExists: retrieves a record from the table and returns an empty document if the data does not exist,
n select: creates a cursor to return several records and returns an empty document if there is no data,
n count: returns a data count.
The XPath syntax is used to locate data based on the input schema. For further information about XPaths,
refer to Editing and extending schemas [page 113].
Example with the "get" operation

Retrieves the last name and first name of a recipient ("nms:recipient" schema) with a filter on the e-mail.
<queryDef schema="nms:recipient" operation="get">

<select>
</select>


<where>
<condition expr="@email= 'john.doe@aol.com'"/>
</where>
</queryDef>
Example with the "select" operation

Returns the list of recipients filtered on a folder and the e-mail domain with a sort in descending order on
date of birth.
<queryDef schema="nms:recipient" operation="select">
<select>

<node expr="@lastName+'-'+@firstName"/>

<node expr="Year(@birthDate)"/>
</select>
<where>
<condition expr="[@folder-id] = 1234 and @domain like 'neolane%'"/>
</where>


<orderBy>
<node expr="@birthDate" sortDesc="true"/> 
</orderBy>
</queryDef>
Expressions can be simple fields or complex expressions such as arithmetic operations or the concatenation
of strings.
To limit the number of records to be returned, add the lineCount attribute to the <queryDef element.
To limit the number of records returned by the query to 100:
158 | Neolane 2013

API
<queryDef schema="nms:recipient" operation="select" lineCount="100">

...
To retrieve the next 100 records, run the same query again, adding the startLine attribute.
<queryDef schema="nms:recipient" operation="select" lineCount="100" startLine="100">
...
Example with the "count" operation

To count the number of records on a query:
<queryDef schema="nms:recipient" operation="count"">

<where>
<condition expr="[@folder-id] = 1234" and @domain like 'neolane%'"/>
</where>
</queryDef>
Note:
Again we use the condition from the previous example. The <select> and <orderBy> clauses are not used.
Data grouping
To retrieve e-mail addresses referenced more than once:
<select>
<node expr="count(@email)"/>
</select>


<groupby>
</groupby>


<having>
<condition expr="count(@email) > 1"/>
</having>
</queryDef>
The query can be simplified by adding the groupBy attribute directly to the field to be grouped:
<select>
<node expr="@email" groupBy="true"/>
</select>
Note:
It is no longer necessary to populate the <groupBy> element.
Bracketing in conditions
Here are two examples of bracketing on the same condition.
n The simple version in a single expression:
<where>
<condition expr="(@age > 15 or @age <= 45) and (@city = 'Newton' or @city = 'Culver
City') "/>
</where>
n The structured version with <condition> elements:

<where>
<condition bool-operator="AND">
<condition expr="@age > 15" bool-operator="OR"/>
<condition expr="@age <= 45"/>

Neolane
</condition>
<condition>
<condition expr="@city = 'Newton'" bool-operator="OR"/>
<condition expr="@city = 'Culver City'"/>
</condition>
</where>
It is possible to replace the 'OR' operator with the 'IN' operation when several conditions apply to the same
field:
<where>
<condition>
<condition expr="@age IN (15, 45)"/>
<condition expr="@city IN ('Newton', 'Culver City')"/>
</condition>
</where>
This syntax simplifies the query when more than two data are used in the condition.
Examples on links
n Links 1-1 or N1: when the table has the foreign key (the link starts from the table), the fields of the linked
table can be filtered or retrieved directly.
Example of a filter on the folder label:
<where>
<condition expr="[folder/@label] like 'Segment%'"/>
</where>
To retrieve the fields of the folder from the "nms:recipient" schema:

<select>

<node expr="[folder/@label]"/>

<node expr="partition"/>
</select>
n Collection links (1N): the filtering on the fields of a collection table must be performed via the EXISTS
or NOT EXISTS operator.
To filter the recipients who have subscribed to the 'Newsletter' information service:
<where>
<condition expr="subscription" setOperator="EXISTS">
<condition expr="@name = 'Newsletter'"/>
</condition>
</where>
Direct retrieval of the fields of a collection link from the <select> clause is not recommended because
the query returns a cardinal product. It is used only when the linked table contains only one record
(example <node expr="").
Example on the "subscription" collection link:
<select>
<node expr="subscription/@label"/>
</select>
It is possible to retrieve a sub-list containing the elements of a collection link in the <select> clause. The
XPaths of the referenced fields are contextual from the collection element.
The filtering (<orderBy>) and restriction (<where>) elements can be added to the collection element.
In this example, for each recipient the query returns the e-mail and list of information services to which
the recipient subscribes:
<select>


<node expr="subscription">
<node expr="[service/@label]"/>
160 | Neolane 2013

API


<where>
<condition expr="@expirationDate >= GetDate()"/>
</where>
<orderBy>
<node expr="@expirationDate"/>
</orderBy>
</node>
</select>
</queryDef>
Binding the parameters of the "where" and "select" clause

The binding of parameters lets the engine set the values of the parameters used in the query. This is very
useful, since the engine is in charge of the escaping of values, and there is the additional benefit of a cache
for the parameters to be retrieved.
When a query is constructed, the "bound" values are replaced by a character (? in ODBC, #[index]# in
postgres...) in the body of the SQL query.
<select>

<node expr="@startDate = #2002/02/01#"/>

<node expr="@startDate = #2002/02/01#" noSqlBind="true"/>
</select>
To avoid binding a parameter, the "noSqlBind" attribute must be populated with the value 'true'.
Important:
If the query includes "order-by" or "group-by" instructions, the database engines will not be able to "bind"
values. You must place the @noSqlBind="true" attribute on the "select" and/or "where" instructions of the
query.
Query-building tip:
To help with the syntax of a query, you can write the query using the generic query editor in the Neolane
client console (Tools/ Generic query editor... menu). To do this:
1 Select the data to be retrieved:

Neolane
2 Define the filter condition:
3 Execute the query and press CTRL+F4 to view the query source code.
Output document format

The return parameter is an XML document in the format of the schema associated with the query.
Example of a return from the "nms:recipient" schema on a "get" operation:
<recipient email="john.doe@neolane.com" lastName"Doe" firstName="John"/>
On a "select" operation, the document returned is an enumeration of elements:


<recipient-collection>
162 | Neolane 2013

API
<recipient email="peter.martinez@neolane.com" lastName"Martinez" firstName="Peter"/>

<recipient...
</recipient-collection>
Example of a document returned for "count" type operation:

<recipient count="3"/>
Alias
An alias lets you modify the location of data in the output document. The alias attribute must specify an
XPath on the corresponding field.
<select>
<node expr="@firstName" alias="@firstName"/>
<node expr="[folder/@label]" alias="@My_folder"/>
</select>
</queryDef>
Returns:
<recipient My_folder="Recipients" First name ="John" lastName="Doe"/>
Instead of:
<recipient firstName="John" lastName="Doe">
<folder label="Recipients"/>
</recipient>
Example of SOAP messages

n Query:
<SOAP-ENV:Body>
<ExecuteQuery xmlns='urn:xtk:queryDef'
<entity xsi:type='ns:Element'
<queryDef operation="get" schema="nms:recipient" xtkschema="xtk:queryDef">
<select>
</select>
<where>
<condition expr="@id = 3599"/>
</where>
</queryDef>
</entity>
</ExecuteQuery>
</SOAP-ENV:Body>
n Response:
<SOAP-ENV:Body>
<ExecuteQueryResponse xmlns='urn:xtk:queryDef'
<pdomOutput xsi:type='ns:Element'

Neolane
</pdomOutput>
</ExecuteQueryResponse>
</SOAP-ENV:Body>
Write / WriteCollection (xtk:session)

These services are used to insert, update, or delete an entity ("Write" method) or a collection of entities
("WriteCollection" method).
The entities to be updated are associated with a data schema. The input parameters are an authentication
string (must be logged in) and an XML document containing the data to be updated.
This document is supplemented by instructions for configuring the write procedures.
The call does not return any data, except errors.
Definition of the "Write" and "WriteCollection" methods in the "xtk:session" schema:
<method name="Write" static="true">
<parameters>
<param name="doc" type="DOMDocument" desc="Difference document"/>
</parameters>
</method>
<method name="WriteCollection" static="true">
<parameters>
<param name="doc" type="DOMDocument" desc="Difference collection document"/>
</parameters>
</method>
Note:
This is a "static" method. The input parameters are included in an XML document in the format of the schema
to be updated.
Overview
Data reconciliation operates based on the definition of the keys entered in the associated schema. The write
procedure looks for the first eligible key based on the data entered in the input document. The entity is
inserted or updated based on its existence in the database.
The key of the schema of the entity to be updated is completed based on the xtkschema attribute.
The reconciliation key can therefore be forced with the _key attribute containing the list of XPaths that make
up the key (separated by commas).
It is possible to force the type of operation by populating the _operation attribute with the following values:
n insert: forces the insertion of the record (the reconciliation key is not used),
n insertOrUpdate: updates or inserts the record depending on the reconciliation key (default mode),
n update: updates the record; does nothing if the data does not exist,
n delete: deletes the records,
n none: used only for link reconciliation, without update or insertion.
Example with the "Write" method

Updating or inserting a recipient (implicit "insertOrUpdate" operation) with e-mail address, date of birth and
town:
<recipient xtkschema="nms:recipient" email="john.doe@neolane.com" birthDate="1956/05/04"
folder-id=1203 _key="@email, [@folder-id]">
<location city="Newton"/>
</recipient>
Deleting a recipient:
<recipient xtkschema="nms:recipient" _operation="delete" email="rene.dupont@neolane.com"
folder-id=1203 _key="@email, [@folder-id]"/>
164 | Neolane 2013

API
Note:
For a deletion operation, the input document must contain only the fields that make up the reconciliation
key.
Example with the "WriteCollection" method

Update or insertion for several recipients:
<recipient-collection xtkschema="nms:recipient">
<recipient email="john.doe@neolane.com" firstName="John" lastName="Doe" _key="@email"/>
<recipient email="peter.martinez@neolane.com" firstName="Peter" lastName="Martinez"

_key="@email"/>
<recipient ...
</recipient-collection>
Example on links
Example 1
Associating the folder with a recipient based on its internal name (@name).
<recipient _key="[folder/@name], @email" email="john.doe@neolane.net" lastName="Doe"
firstName="John" xtkschema="nms:recipient">
<folder name="Folder2" _operation="none"/>
</recipient>
The "_key" and "_operation" attributes can be entered on a linked element. The behavior on this element is
the same as on the main element of the input schema.
The definition of the key of the main entity ("nms:recipient") consists of a field from a linked table (element
<folder> schema "xtk:folder") and the e-mail.
Note:
The operation "none" entered on the folder element defines a reconciliation on the folder without update or
insert.
Example 2
Updating the company (linked table in "cus:company" schema) from a recipient:
<recipient _key="[folder/@name], @email" email="john.doe@neolane.net" lastName="Doe"
firstName="John" xtkschema="nms:recipient">
<company name="Neolane" code="ERT12T" _key="@name" _operation="update"/>
</recipient>
Example 3
Adding a recipient to a group with the group relation table ("nms:rcpGrpRel"):
<recipient _key="@email" email="martin.ledger@neolane.net" xtkschema="nms:recipient">
<rcpGrpRel _key="[rcpGroup/@name]">
<rcpGroup name="GRP1"/>
</rcpGrpRel>
</recipient>
Note:
The definition of the key is not entered in the <rcpGroup> element because an implicit key based on the
group name is defined in the "nms:group" schema.
XML collection elements

By default, all the collection elements must be populated in order to update the XML collection elements.
Data from the database will be replaced with data from the input document. If the document contains only
the elements to be updated, you must populate the "_operation" attribute on all collection elements to be
updated in order to force a merge with the XML data of the database.

Neolane

n Query:
<SOAP-ENV:Body>
<Write xmlns='urn:xtk:persist'
<domDoc xsi:type='ns:Element'
<recipient xtkschema="nms:recipient" email="rene.dupont@neolane.com"
firstName="Ren" lastName="Dupont" _key="@email">
</domDoc>
</Write>
</SOAP-ENV:Body>
n Response:
<SOAP-ENV:Body>
<WriteResponse xmlns='urn:'
</WriteResponse>
</SOAP-ENV:Body>
Return with error:

<?xml version='1.0'?>
<SOAP-ENV:Envelope xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
<SOAP-ENV:Body>
<SOAP-ENV:Fault>
<faultcode>SOAP-ENV:Server</faultcode>
<faultstring xsi:type="xsd:string">Error while executing the method 'Write' of
service 'xtk:persist'.</faultstring>
<detail xsi:type="xsd:string">PostgreSQL error: ERROR: duplicate key violates
unique constraint "nmsrecipient_id"Impossible to save document of type
'Recipients (nms:recipient)'</detail>
</SOAP-ENV:Fault>
</SOAP-ENV:Body>
Business oriented APIs

Business API are specific to each type of object. They have an effect on:
n Deliveries, for:
n Creating a delivery action, refer to SubmitDelivery (nms:delivery) [page 169],
n sending a campaign (start, pause, stop, send proof),
n recovering delivery logs,
n Workflows:
n starting a workflow,
n verifying processes, etc.
Refer to Use SOAP methods in JavaScript [page 171].
166 | Neolane 2013

API
n Content management
n Subscription management, refer to Subscribe (nms:subscription) [page 167] and Unsubscribe
(nms:subscription) [page 168].
n Data processes: imports, exports.
This section details the use of the "Subscribe", "Unsubscribe" and "SubmitDelivery" services.
Important:
The JSAPI.chm document (under license) contains additional information on SOAP calls and using Javascript
in Neolane, as well as a full reference to all methods and functions used in the application.
Subscribe (nms:subscription)
This service lets you subscribe a recipient to an information service and update the recipient profile.
The following parameters are required in order to call the service:
n an authentication,
n internal name of the subscription service,
n an XML document containing the recipient information (from the "nms:recipient" schema),
n a Boolean for recipient creation if there isn't already one.
Description of the "subscribe" method in the "nms:subscription" schema:
<method name="Subscribe" static="true">
<parameters>
<param name="serviceName" type="string" desc="List of information service names
(comma separated)"/>
<param name="recipient" type="DOMElement" desc="Recipient"/>
<param name="create" type="Boolean" desc="Create recipient if it does not exist"/>
</parameters>
</method>
The definition of the reconciliation key must be entered via the _key attribute on the <recipient element of
the XML document. The content of this attribute is a comma-separated XPath list.
This call does not return any data, except errors.
Examples
Subscription with recipient reconciliation key on the e-mail address: the input XML document must reference
the email address and the definition of the key on this field.
<recipient _key="email" email= "john.doe@neolane.com"/>
Updating the recipient as well as the subscription.

<recipient _key="email, [folder-id]" email= "john.doe@neolane.com" folder-id="1305"
firstName="John" lastName="Doe"/>

n Query:
<SOAP-ENV:Body>
<m:Subscribe xmlns:m='urn:nms:subscription'
<sessiontoken xsi:type='xsd:string'/>
<service xsi:type='xsd:string'>SVC1</service>
<content xsi:type=''
<recipient _key="@email" email= "john.doe@neolane.com/>
</content>
<create xsi:type='xsd:boolean'>true</create>
</m:Subscribe>

Neolane
</SOAP-ENV:Body>
n Response:
<SOAP-ENV:Body>
<m:SubscribeResponse xmlns:m='urn:nms:subscription'
</m:SubscribeResponse>
</SOAP-ENV:Body>
Unsubscribe (nms:subscription)
This service lets you unsubscribe a recipient from an information service and update the recipient profile.
n Internal name of the service to unsubscribe from,
n an XML document containing the recipient information (from the "nms:recipient" schema),
Description of the "Unsubscribe" method in the "nms:subscription" schema:
<method name="Unsubscribe" static="true">
<parameters>
<param name="serviceName" type="string" desc="List of information service names (comma
separated)"/>
<param name="recipient" type="DOMElement" desc="Recipient"/>
</parameters>
</method>
The definition of the reconciliation key must be entered via the _key attribute on the <recipient element of
the XML document. The content of this attribute is a comma-separated XPath list.
If the recipient is not present in the database or is not subscribed to the concerned information service, the
service performs no action and does not generate an error.
Note:
If the service name is not specified as a parameter, the recipient is then automatically blacklisted
(@blackList="1").

Query:
<SOAP-ENV:Body>
<m:Unsubscribe xmlns:m='urn:nms:subscription'
<sessiontoken xsi:type='xsd:string'/>
<service xsi:type='xsd:string'>SVC1</service>
<content xsi:type='' SOAP-ENV:encodingStyle='http://xml.apache.org/xml-soap/literalxml'>
<recipient _key="@email" email= "john.doe@neolane.com/>

</content>
</m:Unsubscribe>
</SOAP-ENV:Body>
168 | Neolane 2013

API
Response:
<SOAP-ENV:Body>
<m:UnsubscribeResponse xmlns:m='urn:nms:subscription'
</m:UnsubscribeResponse>
</SOAP-ENV:Body>
SubmitDelivery (nms:delivery)
This service lets you create and submit a delivery action.
n internal name of the delivery template,
n an optional XML document containing additional delivery data.
Description of the method in its schema:
<method name="SubmitDelivery" static="true">
<parameters>
<param name="scenarioName" type="string" inout="in" desc="Internal name of the delivery
template"/>
<param name="content" type="DOMElement" inout="in" desc="XML content of the delivery
template" />
</parameters>
</method>
A delivery template must be created from the Neolane client console. It contains the parameters common
to all deliveries (sender address or duration of validity of the message).
The input XML document is a delivery template fragment that obeys the structure of the "nms:delivery"
schema. It will contain all additional data that could not be defined statically in the delivery template (e.g.,
list of recipients to target).
XML document example:

This example is based on a delivery template from an external data source (a file in this case). The
configuration is fully described in the delivery template, so all that remains to be sent when the call occurs
is the content of the file from the <externalSource> element.
<delivery>
<targets fromExternalSource="true">
<externalSource>
MsgId|ClientId|Title|Name|FirstName| Mobile|Email| Market_segment|Product_affinity1
|Product_affinity2|Product_affinity3| Product_affinity4|
Support_Number|Amount|Threshold1|000001234|M.| Doe|John|0650201020| john.doe@neolane.com
|1| A1|A2|A3|A4|E12|120000|100000
</externalSource>
</target>
</delivery>

Query:
<SOAP-ENV:Body>
<m:SubmitDelivery xmlns:m='urn:nms:delivery'
<sessiontoken xsi:type='xsd:string'>
<scenarioName xsi:type='xsd:string'>test</scenarioName>

Neolane
<content xsi:type=''
<delivery xtkschema="nms:delivery">
<targets fromExternalSource="true">
<externalSource><![CDATA[MsgId|ClientId|Title|Name|FirstName|Mobile|Email|Market_segment|
Product_affinity1|Product_affinity2| Product_affinity3|Product_affinity4|
Support_Number|Amount|Threshold1|000001234|M.|Phulpin|Herv|0650201020|herve.phulpin@neolane.com|1|
A1|A2|A3|A4| E12|120000|100000]]></externalSource>
</targets>
</delivery>
</content>
</m:SubmitDelivery>
</SOAP-ENV:Body>
Response:
<SOAP-ENV:Envelope xmlns:SOAP-ENV='http://schemas.xmlsoap.org/soap/envelope/'>
<m:SubmitDeliveryResponse xmlns:m='urn:nms:delivery'
</m:SubmitDeliveryResponse>
<SOAP-ENV:Body>
</SOAP-ENV:Body>
Implementing SOAP methods in JavaScript
Introduction
It is possible to create SOAP methods in JavaScript. This function simply enables applicative processes, it
can avoid developing JSPs and their calling in the forms.
These SOAP methods behave in the same way as those defined natively in the application. The same attributes
are supported: static, key only and const.
Definition of a method library

Creating a method library involves two stages:
n The SOAP method declaration,
n Definition (or implementation) in JavaScript.
Declaration
Start by declaring the methods in the schemas. Their declaration is similar to that of native methods, except
that you need to add the 'library' attribute specifying the name of the method library where the definition is
located.
This name coincides with the name (with the namespace) of the 'JavaScript Code' type entity.
Example:
The testLog(msg) method is declared in an nms:recipient extension.
<method name="testLog" static="true" library="cus:test">
<parameters>
<param name="message" type="string" inout="in"/>
</parameters>
</method>
Note:
The namespace and the name used for the library are independent from the namespace and schema name
where the declaration is found.
170 | Neolane 2013

API
Definition
SOAP methods are implemented in the form of JavaScript function grouped in a script representing a library.
Note:
A method library can group functions for various schemas or vice versa, the functions of one schema can be
defined in separate libraries.
The script can contain code to be executed during initial library loading.
1. Name
The name of the function must comply with the following format:
<schema-namespace>_<schema-name>_<method-name>
Example:
The following JavaScript function is the implementation of the method described above. It shall be defined
in the 'JavaScript Code' type entity using the 'cus:test' name.
function nms_recipient_testLog(message)
{
logInfo("*** " + message)
}
2. Signature
The function's signature must include an argument for each 'in' or 'inout' parameter of the declaration.
Specific cases:
n non-static methods: the function must include an additional argument first, coinciding with the XML
entity passed in the form of an 'xml' (E4X) type object.
n "key only" type methods: the function must include an additional argument first, coinciding with the
key passed in the form of character strings.
3. Returned values
The function must return a value for each 'out' or 'inout' type parameter. Specific case: If the method is
declared without any of the 'static', 'key only' or 'const' attributes, the first returned value must coincide with
the modified entity. It is possible to return a new object or to return the first modified parameter.
For example:
function nms_recipient_setLastName(self, name)
{
self.@lastName = name
return self
}
When several values are to be returned, they must be displayed in a table.

Example:
function nms_recipient_getKey(self)
{
return [self.@firstName, self.@lastName]
}
Use SOAP methods in JavaScript

This is the JavaScript executed on the Neolane server.
Static methods
Static SOAP methods are accessed by invoking a method on the object representing the schema. Schemas
are properties of 'namespace' objects. These namespaces are global variables, thus, for example, xtk or nms
variables represent the corresponding namespaces.
The following example invokes the static PostEvent method of the xtk:workflow schema:

Neolane
xtk.workflow.PostEvent("WKF1", "signal", "", $recipient-id='123', false)
Non-static methods
To use non-static SOAP methods, it is necessary first to retrieve an entity using the "get" or "create" methods
on the corresponding schemas.
The following example invokes the ExecuteQuery method of the "xtk:queryDef" schema:
var query = xtk.queryDef.create(
<queryDef schema="xtk:workflow" operation="select">
<select>
<node expr="@internalName"/>
</select>
</queryDef>
)
var res = query.ExecuteQuery()
for each (var w in res.workflow)

logInfo(w.@internalName)
Examples
n Query on the recipient table with a "get" operation:
<select>
</select>
<where>
<condition expr="@email = 'peter.martinez@neolane.com'"/>
</where>
</queryDef>)
var recipient = query.ExecuteQuery()
logInfo(recipient.@firstName)
logInfo(recipient.@lastName)
n Query on the recipient table with a "select" operation:

<select>
</select>
<where>
<condition expr="@age > 25"/>
</where>
</queryDef>)
var res = query.ExecuteQuery()
for each (var recipient in res.recipient)

{
logInfo(recipient.@email)
logInfo(recipient.@firstName)
logInfo(recipient.@lastName)
}
n Writing data to the recipient table:

xtk.session.Write(<recipient _operation="insert" lastName="Martinez" firstName="Peter"
xtkschema="nms:recipient"/>);
172 | Neolane 2013

API
Adding additional SQL functions
Introduction
Neolane allows the user to define their own functions that can access SQL functions, both those offered
by the database and those which are not already available in the console. This is useful for aggregate functions
(average, maximum, sum) for example, which can only be calculated on the server or when the database
provides an easier way to implement certain functions, rather than "manually" write the expression in the
console (e.g. date management).
This mechanism can also be used if you wanted to use a recent or uncommon database engine SQL function,
which is not yet offered by the Neolane console.
Once these functions have been added, they will appear in the expression editor just like other predefined
functions.
Warning:
From version 6.1 (build 8100), SQL function calls in the console are no longer naturally sent to the server.
The mechanism described here therefore becomes the only way to call on the unplanned SQL function
server.
Installation
The function(s) to add are in a "package" file in XML format whose structure is detailed in the following
paragraph.
To install it from the console, select the Tools/Advanced/Import package options from the menu, then
the Install from file, and follow the instructions in the import wizard.
Warning:
Warning: even if the list of imported functions appears in the function editor straight away, they will not be
usable until Neolane has been restarted.
General structure of package to import

The function(s) to be added can be found in the "package" file in XML format. Here is an example:
<?xml version="1.0" encoding='ISO-8859-1' ?>


<package
namespace = "nms"
name = "package-additional-funclist"
label = "Additional functions"
buildVersion= "6.1"
buildNumber = "10000">
<entities schema="xtk:funcList">
<funcList name="myList" namespace="cus">
<group name="date" label="Personalized date">
<function name="relativeMaturity" type="long" args="(<ge>)" help="Returns
the difference between a date and 18 years"
minArgs="1" maxArgs="1" display="Relative maturity of the person born
on the date $1">
<providerPart provider="MSSQL,Sybase,PostgreSQL" body="extract(year from
age($1))-18"/>
</function>
</group>
</funcList>
</entities>

Neolane
</package>
n The name, namespace and label are for information purposes only. They let you view a summary of
the package in the installed packages list (Explorer/Administration/Package management/Installed
packages).
n The buildVersion and buildNumber fields are mandatory. They must correspond to the server number
to which the console is connected. This information can be found in the "Help/About" box.
n The following blocks, entities and funclist are mandatory. In funcList, the fields "name" and "namespace"
are mandatory, but their names are left up to the user to decide, and they uniquely designate the function
list.
This means that if another list of functions with the same namespace/name pair (here "cus::myList") is
imported, the previously imported functions will be deleted. Conversely, if you change this
namespace/name pair, the new series of imported functions will be added to the previous one.
n The group element lets you specify the function group in which the imported function(s) will appear in
the function editor. The @name attribute can either be a name that already exists (in which case the
functions will be added to the considered group) or a new name (in which case it will appear in a new
group).
n Reminder: possible values for the @name attribute in the <group> element are:
name="aggregate" ( label="Aggregates" )
name="string" ( label="String" )
name="date" ( label="Date" )
name="numeric" ( label="Numeric" )
name="money" ( label="Money" )
name="geomarketing" ( label="Geomarketing" )
name="other" ( label="Others" )
name="window" ( label="Windowing functions" )
Warning:
Make sure to complete the @label attribute: this is the name that will be displayed in the list of available
functions. If you do not enter anything, the group will not have a name. However, if you enter a name other
than the existing name, the name of the entire group will change.
If you wish to add functions to several different groups, you can make several <group> elements become
tracked in the same list.
Finally, a <group> element can contain the definition of one or several functions, that is the purpose of the
package file. The <function> element is detailed in the following paragraph.
The <function> function descriptor

The case presented here is a general case whereby we wish to provide function implementation.
Below is an example of a "relative maturity" function which, using an age, indicates for how many years the
person has been considered mature.
<function name="relativeMaturity" type="long" args="(<ge>)" help="Returns the

difference between a date and 18 years"
minArgs="1" maxArgs="1" display="Relative maturity of the person born on the
date $1">
<providerPart provider="PostgreSQL" body="extract(year from age($1))-18"/>
<providerPart provider="MSSQL,Sybase,Teradata" body="[Other implementation]"/>
</function>
The @name field refers the name of the function, and "args" is the list of parameters that will be displayed
in the description. In this case, the function will appear as "relativeMaturity (<Age>)" in the function selection
window.
n help is the field displayed at the bottom of the expression editor window.
174 | Neolane 2013

API
n @display is an informative message.
Note:
In the @help and @display attributes, the string "$1" represents the name that was given in the first
function parameter (here, "Age"). $2, $3... would represent the following parameters. In the @body
attribute detailed below, $1 designates the argument value passed to the function during the call.
Note:
The description must be a string of valid XML characters: please note the use of '<' and '>' instead of <
and >.
n @type is the function return type and is a standard value (long, string, byte, datetime...). If it is omitted,
the server determines the best type among the available types within the expression implementing the
function.
n @minArgs and maxArgs designates the number of parameters (minimum and maximum) for a
parameter. For example, for a function with 2 parameters, minArgs and maxArgs will be 2 and 2. For 3
parameters, plus 1 optional, they will be 3 and 4 respectively.
n Finally, the providerPart element provides the function implementation.
n The provider attribute is mandatory, it specifies the database systems for which the implementation
is provided. As shown in the example, when expression syntaxes or underlying functions differ,
alternative implementations can be provided according to the database.
n The @body attribute contains the function implementation. Please note: this implementation must
be an expression, in database language (not a block of code). Depending on the databases, expressions
can be sub-queries ("(select column from table where...)") returning only a single value. For example,
this is the case in Oracle (the query must be written in brackets).
Note:
If only one or two databases are likely to be queried by the function defined, we can always provide only
the definitions corresponding to these databases.
The "pass-through" function descriptor

An special function descriptor is the <body> "pass-through" block, with an unspecified "provider" database
system. In this case, "body" implementation can only contain a single function call with a syntax that is not
dependent on the database used. Meanwhile, the "ProviderPart" block is unique.
<function name="CountAll" args="()" help="Counts the values returned (all fields

together)"
type="long" minArgs="0" maxArgs="0">
<providerPart body="Count(*)"/>
</function>
In this case, adding a function only serves to make a database function that would not have been available
by default, now visible to the client.
Examples
Further function examples can be found in the predefined package "xtk\datakit\funcList.xml".

Neolane

CHAPTER 6
Navigation hierarchy
Table of Contents
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
Global commands . . . . . . . . . . . . . . . . . . . . . . . . . 179
Folder type . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
Edition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
Overview
The navigation hierarchy works like a file browser (e.g. Windows Explorer). Folders may contain
sub-folders. Selecting a node displays the view corresponding to the node.
Neolane v6.1 - Configuration Guide - Navigation hierarchy | 177

Neolane
The view displayed is a list associated with a schema and an input form to edit the selected line.
Figure 6.1. Neolane Browser
To add a new folder to the tree, right-click the folder in the branch where you wish to insert a folder, and
select Add new folder. In the shortcut menu, select the type of file to be created.
Configuration
The types of folders used by the navigation list are described in an XML document that obeys the grammar
of the xtk:navtree schema.
The XML document is structured as follows:
178 | Neolane 2013

<navtree name="name" namespace="name_space">


<commands>
...
</commands>


<model name="<name>" label="<Label>">

<nodeModel>
...
</nodeModel>
<model name="<name>" label="<Sub model>">
...
</model>
</model>
</navtree>
The XML document contains the <navtree> root element with the name and namespace attributes to
specify the document name and namespace. The name and namespace make up the document identification
key.
The global commands of the application are declared in the document from the <commands> element.
The declaration of file types is structured in the document with the following elements: <model> and
<nodeModel>.
Global commands
A global command lets you launch an action. This action can be an input form or a SOAP call.
Global commands are accessible from the main Tools menu.
The command configuration structure is as follows:
<commands>

<command name="<name>" label="<label>" desc="<Description>" form="<form>"
rights="<rights>">
...
</soapCall>
<enter>
...
</enter>
</command>

<command label="-" name="<name>"/>

<command name="<name>" label="<Label>">
<command...
</command>
</commands>
The description of a global command is entered in the <command> element with the following properties:
n name: internal name of the command: the name must be entered and unique
n label: label of the command.
n desc: description visible from the status bar of the main screen.
n form: form to be launched: the value to be entered is the identification key of the input form (e.g.
"cus:recipient")
n rights: list of named rights (separated by a comma) allowing access to this command. The list of available
rights is accessible from the Administration/Access management/Named rights folder.
n promptLabel: displays a confirmation box before execution of the command
A <command> element can contain <command> sub-elements. In this case, the parent element lets
you display a sub-menu made up of these child elements.
The commands are displayed in the same order as they are declared in the XML document.
A command separator lets you display a separation bar between commands. It is identified by the '-' value
contained in the command label.

Neolane
The optional presence of the <soapCall> tag with its input parameters defines the call of a SOAP method
to be executed. For further information on the SOAP API, refer to the jsapi.chm online help section.
The form context can be updated on initialization from the <enter> tag. For further information on this
tag, refer to the documentation on input forms.
Example:
n Declaration of a global command to launch the "xtk:import" form:
<command desc="Start the data import wizard" form="xtk:import" label="&Data
import..." name="import" rights="import,recipientImport"/>
A keyboard shortcut is declared on the 'I' character by the presence of & in the command label.
n Example of a sub-menu with a separator:
<command label="Administration" name="admin">

<command name="cmd1" label="Example 1" form="cus:example1"/>
<command name="sep" label="-"/>
<command name="cmd1" label="Example 2" form="cus:example2">
<enter>
<set xpath="@type" expr="1"/>
</enter>
</command>
</command>
n Execution of a SOAP method:

<command name="cmd3" label="Example 3" promptLabel="Do you really want to execute the
command?">
<soapCall name="Execute" service="xtk:sql"/>
</command>
Folder type
A folder type lets you give access to the data of a schema. The view associated with the folder consists of
a list and an input form.
The folder type configuration structure is as follows:

<model name="name" label="Labelled">

<nodeModel name="<name>" label="<Labelled>" img="<image>">
<view name="<name>" schema="<schema>" type="<listdet|list|form|editForm>">
<columns>
<node xpath="<field1>"/>
...
</columns>
</view>
</nodeModel>
<model name="<name>" label="<Sous modle>">
...
</model>
</model>
The folder type declaration must be entered under a <model> element. This element lets you define a
hierarchical organization visible from the Add new folder menu. A <model> element must contain
<nodeModel> elements and other <model> elements.
The name and label attributes populate the internal name of the element and the label displayed in the
Add new folder menu.
The <nodeModel> element contains the description of the folder type with the following properties:
n name: internal name
n label: label used in the Add new folder menu and as a default label when inserting a folder.
180 | Neolane 2013

n img: default image on folder insertion.

n hiddenCommands: list of commands (separated by a comma) to be masked. Possible values: "insert",
"delete", "update" and "duplicate".
n newFolderShortCuts: list of shortcuts on models (<nodeModel> separated by a comma) in folder
creation.
n insertRight, editRight, deleteRight: rights for inserting, editing and deleting folders.
The <view> element under the <nodeModel> element contains the configuration of the list associated
with the view. The schema of the list is entered in the schema attribute of the <view> element.
To edit the records of the list, the input form with the same name as the list schema is implicitly used. The
type attribute on the <view> element affects the display of the form. Possible values are:
n listdet: displays the form at the bottom of the list.
n list: displays the list alone. The form is launched by double-clicking or via the "Open" in the menu on
selecting the list.
n form: displays a read-only form.
n editForm: displays a form in edit mode.
Note:
The name of the input form can be overloaded by entering the form attribute in the <view> element.
The default configuration of the list columns is entered via the <columns> element. A column is declared
on a <node> element containing the xpath attribute with the field to be referenced in its schema as its
value.
Example: declaration of a folder type on the "nms:recipient" schema.
<model label="Profiles and targets" name="nmsProfiles">
<nodeModel deleteRight="folderDelete" editRight="folderEdit" folderLink="folder"
img="nms:folder.png" insertRight="folderInsert" label="Recipients"
name="nmsFolder">
<view name="listdet" schema="nms:recipient" type="listdet">
<columns>
<node xpath="@firstName"/>
<node xpath="@lastName"/>
<node xpath="@email"/>
<node xpath="@account"/>
</columns>
</view>
</nodeModel>
<nodeModel name="nmsGroup" label="Groups"...
</model>
The corresponding folder insertion menu:
Filtering and sorting can be applied when the list is being loaded:
<view name="listdet" schema="nms:recipient" type="listdet">
<columns>
...
</columns>
<orderBy>
<node expr="@lastName" desc="true"/>
</orderBy>
<sysFilter>
<condition expr="@type = 1"/>
</sysFilter>
</view>

Neolane
Shortcut commands
A shortcut command lets you launch an action on selecting the list. The action can be an input form or a
SOAP call.
Commands are accessible from the Action menu of the list or the associated menu button.
The command configuration structure is as follows:
<nodeModel...
...
<command name="<name>" label="<label>" desc="<Description>" form="<form>"
rights="<rights>">
...
</soapCall>
<enter>
...
</enter>
</command>
</nodeModel>
The description of a command is entered on the <command> element with the following properties:
n name: internal name of the command: the name must be entered and unique.
n label: label of the command.
n desc: description visible from the status bar of the main screen.
n form: form to be launched: the value to be entered is the identification key of the input form (e.g.
"cus:recipient").
n rights: list of named rights (separated by a comma) allowing access to this command. The list of available
rights is accessible from the Administration/Access management/Named rights folder.
n promptLabel: displays a confirmation box before execution of the command
n monoSelection: forces mono-selection (multiple selection by default).
n refreshView: forces reloading of the list after execution of the command.
n enabledIf: activates the command depending on the expression entered.
n img: enters an image allowing access to the command from the list toolbar.
A <command> element can contain <command> sub-elements. In this case, the parent element lets
you display a sub-menu made up of these child elements.
The commands are displayed in the same order as they are declared in the XML document.
A command separator lets you display a separation bar between commands. It is identified by the '-' value
contained in the command label.
The optional presence of the <soapCall> tag with its input parameters defines the call of a SOAP method
to be executed. For further information about SOAP APIs, refer to the jsapi.chm online help section.
The form context can be updated on initialization via the <enter> tag. For further information about this
tag, refer to the input form documentation.
Example:
<command desc="Cancel execution of the job" enabledIf="EV(@status, 'running')"
img="nms:difstop.bmp" label="Cancel..." name="cancelJob"
promptLabel="Do you really want to cancel this job?" refreshView="true">
<soapCall name="Cancel" service="xtk:jobInterface"/>
</command>
<command label="-" name="sep1"/>
<command desc="Execute selected template" form="cus:form" lmonoSelection="true"
name="executeModel"
rights="import,export,aggregate">
<enter>
<set expr="0" xpath="@status"/>
</enter>
</command>
Linked folder
There are two types of folder management operations:
1 The folder is a view: the list displays all records associated with the schema, with the possibility of system
filtering entered in the folder properties.
182 | Neolane 2013

2 The folder is linked: the records in the list are implicitly filtered on the folder link.
For a linked folder, the folderLink attribute on the <nodeModel> element must be populated. This attribute
contains the name of the link on the folder configured in the data schema.
Example of declaration of a linked folder in the data schema:
<element default="DefaultFolder('nmsFolder')" label="Folder" name="folder"
revDesc="Recipients in the folder" revIntegrity="own" revLabel="Recipients"
target="xtk:folder" type="link"/>
The configuration of the <nodeModel> on the link of the folder named "folder" is as follows:
<nodeModel deleteRight="folderDelete" editRight="folderEdit" folderLink="folder"
img="nms:folder.png" insertRight="folderInsert" label="Recipients" name="nmsFolder">
...
</nodeModel>
Edition
The screen for creating and configuring the navigation hierarchy configuration documents is accessible via
the Administration/Configuration/Navigation hierarchies node:
The navigation hierarchy configuration is divided over several XML documents. It operates on a similar
principle to schema extension: all documents are merged to generate a single document containing the whole
configuration. This document cannot be edited, and is displayed via the "Preview" tab.
The edit field provides the content of the XML document:

Neolane
Note:
The "Name" edit control lets you enter the document key consisting of the name and namespace. The "name"
and "namespace" attributes of the <navtree> element are automatically updated in the XML edit field of
the schema.
The preview automatically generates the merged document containing the complete configuration:
184 | Neolane 2013

CHAPTER 7
Using an external recipient
table
Table of Contents
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
Precisions . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
Recommendations and limitations . . . . . . . . . . . . . . . . . . . 186
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
The View attribute . . . . . . . . . . . . . . . . . . . . . . . . 186
Names of tables and columns . . . . . . . . . . . . . . . . . . . . 187
Indexed fields . . . . . . . . . . . . . . . . . . . . . . . . . . 187
Setting up a target mapping . . . . . . . . . . . . . . . . . . . . . . 187
Creating and configuring the schemas linked to the external table . . . . . . . . 188
Using target mapping . . . . . . . . . . . . . . . . . . . . . . . 191
Configuring the interface to use the new recipient table . . . . . . . . . . . . 191
Creating a new form . . . . . . . . . . . . . . . . . . . . . . . . 192
Creating a new type of folder in the navigation hierarchy . . . . . . . . . . . 192
Configuring seed addresses based on an external recipient table . . . . . . . . . 193
Implementation . . . . . . . . . . . . . . . . . . . . . . . . . 193
Creating filters to manipulate the new recipient table . . . . . . . . . . . . . 194
Creating lists based on the external recipient table . . . . . . . . . . . . . . 195
Introduction
Overview
This section details the principles for using a non-standard recipient table. By default, Neolane offers
a standard recipient table to which out-of-the-box functions and processes are linked. Using a
non-standard table, or 'external recipient table', requires certain pre-installation precautions when
implementing it
Precisions
This functionality allows Neolane to process data from an external database: this data will be used
as a set of profiles for deliveries. Implementing this process involves several precisions that may
be relevant according to the client's needs. Such as:
n No update stream to and from the Neolane database: data from this table can be updated
directly via the database engine that hosts it.
n No changes in the processes operating on the existing database.
Neolane v6.1 - Configuration Guide - Using an external recipient table | 185

Neolane
n Using a profile database with a non-standard structure: possibility of delivering to profiles saved in various
tables with various structures, using a single instance.
This section describes the key points that let you map existing tables in Neolane and the configuration to
apply to execute deliveries based on any table. Finally, it describes how to provide users with querying
interfaces as practical as those available with the standard recipient table. To understand the material
presented in this section, good knowledge of the principles of screen and schema design is required.
Recommendations and limitations

Using an external recipient table has the following limitations:
n You cannot use the standard Services and Subscriptions offered in the product.
This means the overall operation detailed in the Delivery guide is not applicable.
n The link with the visitor table does not work.
Thus, to use the Social Marketing module you must configure the storage step to reference the correct
table.
Similarly, when using referral functions, the standard initial message transfer template must be adapted.
n You cannot manually add profiles in a list.
Therefore, the procedure detailed in the Platform Guide is not applicable without an additional
configuration.
Note:
You can still create recipient lists using workflows. For more on this, refer to Creating lists based on the
external recipient table [page 195].
We also recommend checking the default values used in the different out-of-the-box configurations: depending
on the functionalities used, several adaptations must be carried out.
For example:
n Certain standard reports, particularly those offered by the Interaction and Response Manager modules,
must be redeveloped
n The default configurations for certain workflow activities reference the standard recipients table
(nms:recipient): these configurations must be changed when used for an external recipients table.
n The standard Unsubscription link personalization block must be adapted.
n The target mapping of the standard delivery templates must be modified.
n V4 forms are not compatible for use with an external recipients table: you must use Web applications.
Overview
The characteristics of a schema that references an existing table are as follows:
n Neolane must not modify SQL objects relative to existing tables,
n The names of tables and columns must be specified explicitly,
n Indexes must be declared.
The View attribute

Source schemas accept the view attribute for the srcSchema root element. It must be used when Neolane
is manipulated in external tables. The view="true" attribute tells the database structure update wizard to
ignore this schema. The application is therefore prohibited from synchronizing the table, its columns and its
indexes with the corresponding schema.
When this attribute is set to true, the schema is used only to generate SQL queries to access the data of
this table.
186 | Neolane 2013

Using an external recipient table
Names of tables and columns

When tables are created by the table update wizard, the names of tables and columns are generated
automatically based on the names of the respective schemas and attributes. It is however possible to force
the SQL names to be used by entering the following attributes:
n sqltable within the main element of the schema, to specify the table,
n sqlname within each attribute, to specify the columns.
Example:
<element label="Individual" name="individual" sqltable="individual">
</key>
<attribute name="id" type="long" length="32" />
<attribute name="lastName" type="string" length="100" sqlname="Last_Name"/>
<attribute name="firstName" type="string" length="100" sqlname="First_Name"/>
<attribute name="mobile" type="string" length="100"/>
</element>
In this example, if the names of the tables and columns had not been explicitly specified, the application
would have used CusIndividual for the table, lastName and firstName for the columns.
In a schema, it is possible to populate only part of the columns of an existing table. Unpopulated columns
will not be user-accessible.
Indexed fields
When sorting the records of a list from the client console, better performance is obtained by sorting on
indexed fields. Declaring an index in a schema makes the console display the indexed fields with a red line
under the sort-order arrow to the left of the column label, as shown below:
In a schema, an index is defined as follows:

<dbindex name="name_of_index" unique="true/false"
<keyfield xpath="xpath_1st_field"/
<keyfield xpath="xpath_2nd_field"/
...
</dbindex
That's why it is important to declare existing indexes of the external table in the matching schema.
An index is implicitly declared for each key and link declaration of the source schema. Index declaration can
be prevented by specifying the noDbIndex="true" attribute:
Example:
<key internal="true" name="customer" noDbIndex="true">
<keyfield xpath="@customerId"/>
</key>
Setting up a target mapping

Target mapping creation is necessary in two cases:
n if you use a recipient table other than the one provided by Neolane,
n if you configure a filtering dimension which is different from the standard targeting dimension on the
target mapping screen.
The target mapping creation wizard will help you create all schemas required to use your external table.

Neolane
Creating and configuring the schemas linked to the external table

Before you create a target mapping, several configurations are necessary in order for Neolane to operate
with a new recipient data schema.
To do this, apply the following steps:
1 Create a new data schema which integrates the fields of the external table which you want to use.
Note:
For further information, refer to Schema Reference (xtk:srcSchema) [page 65].
In our example, we will create a customer schema, a very simple table containing the following fields:
ID, first name, last name, email address, mobile phone number. The aim is to be able to send e-mail or
SMS alerts to the individuals stored in this table.
Example schema (cus:individual)
<srcSchema name="individual" namespace="cus" label="Individuals">
<element name="individual">
<key name="id" internal="true">
</key>
<attribute name="id" type="long" length="32"/>
<attribute name="lastName" type="string" length="100"/>
<attribute name="firstName" type="string" length="100"/>
<attribute name="mobile" type="string" length="100"/>
</element>
</srcSchema>
2 Declare your schema as an external view using the ="true" attribute. Refer to The View attribute [page 186].
<srcSchema desc="External recipient table" namespace="cus" view="true"....>
...
</srcSchema>
3 If you need to add a direct mail address, please use the following type of structure:
<element advanced="true" name="postalAddress" template="nms:common:postalAddress">
<attribute expr="SubString(JuxtWords(Smart([../infos/@firstname]),
Upper([../infos/@name])), 1, 80)"
name="line1"/>
<attribute expr="Upper([../address/@ligne2Afnor])" name="line2"/>
<attribute _operation="delete" name="line7"/>
<attribute _operation="delete" name="addrErrorCount"/>
<attribute _operation="delete" name="addrQuality"/>
<attribute _operation="delete" name="addrLastCheck"/>
<element expr="@line1+'\n'+@line2+'\n'+@line3+'\n'+@line4+'\n'+@line5+'\n'+@line6"
name="serialized"/>
<attribute expr="AllNonNull2([../address/@ligne6Afnor], [../infos/@name])"
name="addrDefined"/>
</element>
4 Click the Administration>Campaign management>Target mappings node.

5 Click the New button to open the target mapping creation wizard.
188 | Neolane 2013

6 Enter the Label field and select the schema which you have just created in the Targeting dimension
field.
7 In the Edit address forms window, select the fields of the schema which match the various delivery
addresses. Here, we are able to map the @email and @mobile fields.
8 In the following Storage window, enter the Suffix of the extension schemas field to differentiate
the new schemas from the out-of-the-box schemas provided by Neolane.

Neolane
By default, exclusion management is stored in the same tables as messages. Check the Generate a
storage schema for tracking box if you want to configure storage for the tracking linked to your target
mapping.
9 In the Extensions window, select the optional schemas which you want to generate (the list of available
schemas depends on the modules installed on the Neolane platform).
10 Click the Save button to close the wizard.
190 | Neolane 2013

The wizard uses the start schema to create all the other schemas required to make the new target
mapping work.
Using target mapping

There are two ways of using the new schema as the target of a delivery:
n Create one or more delivery templates based on mapping
n Select mapping directly during target selection when creating a delivery, as shown below:
Configuring the interface to use the new recipient table

To view and dialog with the new recipient table in the Neolane interface, apply the following steps:
n Create a new form to edit the content of the new recipient table.
n Enter a new type in the folder of the explorer tree.
n Create a new web application to access the external table via the Neolane home page.
Neolane uses a "Nms_DefaultRcpSchema" global variable to dialog with the default recipient database
(nms:recipient). This variable therefore needs to be altered.

Neolane
1 Go to the Administration>Platform>Options node of the explorer.

2 Change the value of the Nms_DefaultRcpSchema variable with the name of the schema which matches
the external recipient table (in this case: cus:individual).
3 Save changes.
Creating a new form

Creating a new form will enable you to view and edit the data of the external recipient table.
Important:
The name of the form must be identical to the name of the schema which it concerns.
1 Go to the Administration>Configuration>Input forms node of the explorer.

2 Create a new xtk:form type form file.
3 Describe all the monitorings and fields which you need depending on your table template.
Note:
To find out more about form type files, refer to Input forms [page 133].
In our current example, the form file must be based on the cus:individual schema and therefore have
the following layout:
<container colspan="2">
<input xpath="@id"/>
<static type="separator"/>
</container>
<input xpath="@lastName"/>
<input xpath="@firstName"/>
<input xpath="@mobile"/>
</container>
4 Save the creation.
Creating a new type of folder in the navigation hierarchy

1 Go to the Administration>Configuration>Navigation hierarchies node.
2 Create a new xtk:navtree type navtree document.
3 Describe all the monitorings and fields which you need depending on your table template.
Note:
For more on navtree type files, refer to Navigation hierarchy [page 177].
In the current example, the navtree file must be based on the cus:individual schema and therefore
have the following form:
<model name="root">
<nodeModel img="nms:usergrp.png" label="My recipient table" name="cusindividual">
<view name="listdet" schema="cus:individual" type="listdet">
<columns>
<node xpath="@id"/>
<node xpath="@lastName"/>
<node xpath="@firstName"/>
<node xpath="@email"/>
<node xpath="@mobile"/>
</columns>
</view>
</nodeModel>
</model>
192 | Neolane 2013

4 Save the creation.
Configuring seed addresses based on an external recipient table

If the recipient table is an external table, additional configurations are required. The nms:seedMember
schema must be extended. An additional tab is added to the seed addresses for defining the adequate fields,
as shown below:
For more on using seed addresses, refer to the "Seed addresses" section of the Neolane Delivery guide.
Implementation
The nms:seedMember schema and the linked form which come out-of-the-box are meant to be extended
for customer configuration, to reference all necessary fields. The schema definition contains comments
detailing its configuration mode.
Definition of the recipients table extended schema:
<srcSchema label="Person" name="person" namespace="cus">
<element autopk="true" label="Person" name="person">
<attribute label="LastName" name="lastname" type="string"/>
<attribute label="FirstName" name="firstname" type="string"/>
<element label="Address" name="address">
<attribute label="Email" name="addrEnv" type="string"/>
</element>
attribute label="Code Offer" name="codeOffer" type="string"/>
</element>
</srcSchema>
Apply the following steps:
1 Create an extension of the nms:seedMember schema. For more on this, refer to Extending an existing
schema [page 121].
2 In this new extension, add a new element at the root of seedMember with the following parameters:
name="custom_customNamespace_customSchema"

Neolane
This element must contain the fields required to export the campaigns. These fields should have the
same name as the corresponding fields in the external schema. For example, if the schema is cus:person,
the nms:seedMember schema should be extended as follows:
<srcSchema extendedSchema="nms:seedMember" label="Seed addresses"
labelSingular="Seed address" name="seedMember" namespace="cus">
<element name="common">
<element name="custom_cus_person">
<attribute name="lastname" template="cus:person:person/@lastname"/>
<attribute name="firstname" template="cus:personne:person/@firstname"/>
<attribute name="email" sqlname="myEmailField"
template="cus:personne:person/address/@addrEnv" xml="false" />
</element>
</element>
<element name="seedMember">
<element aggregate="cus:seedMember:common"/>
</element>
</srcSchema>
Note:
The extension of the nms:seedMember schema must comply with the structures of a campaign and a
delivery in Neolane.
Warning:
n During the extension, you must specify an SQL name (@sqlname) for the 'email' field. The SQL
name must differ from the 'sEmail' that is reserved for the recipient schema.
n You must update the database structure with the schema created when extending nms:seedMember.
3 Modify the seedMember form accordingly to define a new "Internal recipient" tab in the Seed addresses
window. For more on this, refer to Form structure [page 135].
<container colcount="2" label="Internal recipient" name="internal"
xpath="custom_cus_person">
<input colspan="2" editable="true" nolabel="true" type="treeEdit">
<container label="Recipient (cus:person)">
<input xpath="@last name"/>
<input xpath="@first name"/>
</container>
</input>
</container>
If all attributes of the seed address aren't entered, Neolane automatically substitutes the profiles: they will
be entered automatically during personalization using data from an existing profile.
Creating filters to manipulate the new recipient table

Just like the out-of-the-box recipient table provided with Neolane, the new recipient table may receive a
batch of predefined filters
These filters will be available in the target selection window with the same functionalities as segments for
recipients (using parameter input forms, folders, etc.).
1 Go to the Administration>Configuration>Predefined filters node.

2 Create a new filter.
3 Enter the Label of the filter, then select the schema which matches the external recipient table in the
Document type field.
4 Create your filtering conditions based on the fields of your schema.
5 Save the filter.
194 | Neolane 2013

Creating lists based on the external recipient table

To create a list based on the new recipient table, you need to create a targeting workflow which will generate
the list.
1 Go to the Profiles and Targets >Jobs>Targeting workflows node of the explorer.

2 Create a new targeting workflow.
3 Place a Query activity followed by a List update activity.
4 Double-click the Query activity, then click Edit the query to choose a targeting dimension based on
the schema of the new recipient table (in our example: Individual).
5 Approve this configuration.

Neolane
6 Double-click the Update list activity, then select the Created if necessary (Calculated name) radio
button.
7 Select the creation folder for the new list.

8 Execute the workflow to create the list.
9 View the result in the node of the tree which you selected during the Update list activity.
196 | Neolane 2013

The dashboard specifies the schema which the list is based on, as shown below:

Neolane

CHAPTER 8
Setting up Web tracking
Table of Contents
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
Web tracking mode . . . . . . . . . . . . . . . . . . . . . . . . . 200
Web tracking tag: definition . . . . . . . . . . . . . . . . . . . . . . 202
Format of the data to be sent . . . . . . . . . . . . . . . . . . . . 203
Data transmission methods . . . . . . . . . . . . . . . . . . . . . 203
Setup stages . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
Additional web tracking parameters . . . . . . . . . . . . . . . . . . . 204
Definition of parameters . . . . . . . . . . . . . . . . . . . . . . 204
Redirection server configuration . . . . . . . . . . . . . . . . . . . . 205
Creating web tracking tags . . . . . . . . . . . . . . . . . . . . . . 205
Defining the URLs to be tracked in the application . . . . . . . . . . . . . 206
On-the-fly creation of URLs to be tracked . . . . . . . . . . . . . . . . 206
Inserting tags in your site . . . . . . . . . . . . . . . . . . . . . . . 207
Simple method . . . . . . . . . . . . . . . . . . . . . . . . . 207
Optimum method . . . . . . . . . . . . . . . . . . . . . . . . . 208
Collecting all visits to a site . . . . . . . . . . . . . . . . . . . . . . 210
Server configuration . . . . . . . . . . . . . . . . . . . . . . . . 210
Configuring a default matching campaign . . . . . . . . . . . . . . . . 210
Anonymous tracking . . . . . . . . . . . . . . . . . . . . . . . . . 210
In addition to standard tracking that shows the behavior of an internet user clicking on a link in an
e-mail message, the Neolane platform lets you collect information on how internet users browse
your website. This data collection is performed by the web tracking module.
Overview
When an internet user clicks a tracked link in an e-mail from a given delivery, the redirection server
contacted deposits a session cookie containing the broadlog identifier (broadlogId) and the delivery
identifier (deliveryId).
The web client then sends this cookie to the server each time the user visits a page containing a
web tracking tag. This continues throughout the session, i.e. until the web client is closed.
The redirection server collects the following data in this way:
n URL of the page viewed, via an identifier sent as a parameter,
n the delivery from which the web page was visited, via the session cookie,
n identifier of the internet user who clicked, via the session cookie,
n additional information such as the business volume generated.
Neolane v6.1 - Configuration Guide - Setting up Web tracking | 199

Neolane
The following diagram shows the stages of the dialog between the client and the various servers.
Figure 8.1. Client/web server/redirection server exchanges
Web tracking mode

Neolane lets you select a web tracking mode which defines the way in which tracking logs are processed in
the application.
There are three available Web tracking modes: "Session tracking", "Permanent tracking" and
"Anonymous tracking".
200 | Neolane 2013

Each mode has specific characteristics. The "permanent" Web tracking mode includes the characteristics of
the "session" Web tracking mode, while the "anonymous" mode includes the characteristics of the "permanent"
and "session" modes.
Important:
The "anonymous" Web tracking mode is enabled by default if the "Leads" package is enabled. In all other
cases, the "session" Web tracking mode is enabled by default.
At any time, the default mode can be changed in the instance deployment wizard.
Warning:
If you are using the permanent web or anonymous tracking mode, you must add an index to the "sourceID"
column (uuid230) in the tracking tables (trackingLogXXX):
1 Identify the tracking table(s) concerned by permanent tracking.

2 Extend the schemas that match these tables by adding the following lines:
<dbindex name="sourceId">
<keyfield xpath="@sourceId"/>
</dbindex>
Permanent and Anonymous Web tracking modes include two options: Forced delivery and Last delivery.
The Forced delivery option enables you to specify the identifier of the delivery (@jobid) during tracking.
The Last delivery option lets you link the current tracking log to the last tracked delivery.
Characteristics of session Web tracking:
This mode creates a tracking log for people with a session cookie. These are people who clicked a URL in
an email sent by Neolane, thus enabling us to track the following information:
n Delivery ID
n Contact ID
n delivery log
n permanent cookie (uuid230)
n Tracking URL
n date of the tracking log
With this Web tracking mode, if part of the information is missing, no tracking log will be created in the
application.
This mode is economical in terms of volume (limited number of records in the trackingLog table) and calculation
(no reconciliation).
Characteristics of the permanent Web tracking mode:

This Web tracking mode lets you create a tracking log based on the presence of the permanent uuid230
cookie. If a visitor closes their session, Neolane uses the permanent cookie to recover information on them
from previous tracking logs. Neolane re-inserts a tracking log if the uuid230 of the current session has the
same value as a uuid230 already stored in the tracking table.
This means that the visitor needs to have been previously identified in Neolane (via a delivery) to enable
reconciliation on uuid230 values.
By default, searches in previous tracking logs are performed in the "trackingLog" table. If the Leads package
is enabled, before searching the "trackingLog" table, Neolane will search the "incomingLead" table for previous
tracking log records.
This mode is costly in terms of calculation during log reconciliation.
Characteristics of the anonymous Web tracking mode:

This Web tracking mode lets you retrieve a tracking log linked to anonymous browsing in Neolane. A tracking
log is created automatically for each click on a tracked URL. This log only has the value of the uuid230.
During a marketing campaign, a tracking log is created automatically with all identification information (refer
to session tracking). Neolane will automatically search previous logs for a "uuid230" value equal to the value

Neolane
from the tracking log for this marketing campaign. If identical values are found, all previous tracking logs
are entered with all the information from the marketing campaign tracking log.
This mode is the most costly in terms of calculation and volume.
Note:
If the Neolane Leads package is installed, you need to do the same for the activity table
(crm:incomingLead)
The following schema sums up the functionalities of all three Web tracking modes:
Example of Permanent web tracking based on the last delivery:

Florence receives a delivery, opens the email, clicks the link, browses on the retail site but doesn't make any
purchases. The next day, Florence returns to the retail site, browses and makes a purchase. Since permanent
web tracking (last delivery) is enabled, all the logs for her second visit will be linked to the delivery that was
sent to her the previous day.
Web tracking tag: definition

A web tracking tag is simply a URL constructed with the appropriate parameters, sent to the redirection
server via an HTTP query.
202 | Neolane 2013

Format of the data to be sent

The format of a web-tracking URL is as follows:
http://<name_of_redirection_server:<port/r/<random_number?<parameters
Note:
The random number added to the URL avoids problems caused by browsers caching web pages.
The following table gives a list of special parameters supported by the redirection server.
Name Type Description

ID Session cookie Delivery identifier and recipient identifier.
uuid230 Permanent cookie Recipient identifier (useful if session cookie is absent).
tagid URL parameter Identifier of tracked web page: this is the only mandatory parameter.
jobid URL parameter Delivery identifier to be used if there is no session cookie. This value is
to be expressed in hexadecimal.
rcpid URL parameter Parameter used to identify the internet user. The format of this parameter
is "name=value", where the name is a field of the recipient schema. This
parameter takes priority over the identifier contained in the session
cookie.
A few web tracking URLs

n Visit to a 'home' identifier page
http://myserver.neolane.com/r/9862?tagid=home
n Collecting business volume data
http://myserver.neolane.com/r/4567?tagid=command&amount=100&article=2l
n Specifying a field to find the recipient
http://myserver.neolane.com/r/2353?tagid=home&rcpid=saccount%3D10
A recipient whose account number is 10 is sent to the home page.
n Using a default delivery
http://myserver.neolane.com/r/2456?tagid=home&jobid=e6
A recipient is sent to the home page. This information will be stored in the delivery with identifier 230
(e6 in database 16) unless a session cookie containing a delivery identifier is sent with this query.
Note:
All values sent to the redirection server via URL parameters must be URL encoded. In the examples given,
note that the characters '=' and '|' are encoded as '%3D' and '%7C' respectively.
Data transmission methods

The following methods are possible:
n Inserting the URL in the "src" attribute of an HTML <img> tag incorporated in the web page you wish
to track.
n Direct call to the redirection server when the web page you wish to track is generated.
Setup stages
The basic principle is the insertion of web tracking tags in certain pages of your website.
There are two types of tags:
n WEB: this tag tells you if the page has been visited,

Neolane
n TRANSACTION: operates like a Web tag, but with the possibility of adding information on the business
volume generated, for example (transaction amount, number of items purchased, etc.).
Apply the following steps to set up these tags:
1 Identify the pages you wish to track and determine their type (WEB or TRANSACTION).
2 Determine which additional information you wish to collect, and extend the nms:webTrackingLog
schema with the description of this information. By default, this schema can store the transaction amounts
and number of items per transaction.
3 Creating the web tracking tags. There are two ways of doing this:
n Insert the URLs corresponding to these pages in your Neolane platform, then generate and extract
the associated web-tracking tags (from the Campaign execution>Resources>Web tracking
tags node of the client console).
n Create the web-tracking tags yourself in "on-the-fly creation" mode: the URLs corresponding to these
pages will be automatically inserted in your Neolane platform.
4 Add these tags statically or dynamically in the pages you wish to track.
Note:
All WEB-type tags can be added as they are to the pages of your site. TRANSACTION tags must be
modified or added dynamically in order to contain the additional information (amount, items, etc.).
Example:
<script type="text/javascript">
var _f = "nmsWebTracking"
var _t = window.location.href.match(/.*:\/\/[^\/]*(\/[^\?\#\&]*)/)[1] + "|w|" + _f
document.write("<img height='0' width='0' alt='' src='" +
window.location.protocol + "//tsupport/r/" +
Math.random().toString() + "?tagid=" + escape(_t) + "'/>")
</script>
Additional web tracking parameters
Definition of parameters
Your Neolane platform offers two TRANSACTION-type web-tracking parameters as a standard:
n amount: represents the amount of a transaction,
n article: represents the number of items in a transaction.
These parameters are defined in the nms:webTrackingLog schema, and are some of the indicators seen
in reporting.
To define additional parameters, you must extend this schema.
Example:
<srcSchema extendedSchema="nms:webTrackingLog" label="Web Tracking"

mappingType="sql" name="webTrackingLog"
namespace="cus" xtkschema="xtk:srcSchema">
<element name="webTrackingLog">
<attribute desc="Payment method" label="Payment method" length="10" name="mode"
type="string"/>
<attribute desc="Offer code" label="Offer code" length="5" name="code" type="string"/>
</element>
</srcSchema>
You can display the values of these parameters by configuring the tracking log list (of a delivery or recipient).
204 | Neolane 2013

Redirection server configuration

In the server configuration, you can define the maximum number of characters to be taken into account for
your web tracking parameters.
Warning:
The correct calculation of the number of characters to be taken into account is important for optimizing the
web tracking performance of your platform.
To do this, modify the webTrackingParamSize attribute of the <trackinglogd> element in the

serverConf.xml file. This file is saved in the conf subdirectory of the Neolane installation directory.
Example:
The default value is 32 characters. This value lets you take into account the amount and article
("amount=xxxxxxxx&article=xxxxxxxx") standard parameters.
By taking into account both parameters (size of name + size of value) indicated in the above extension
schema example, you can modify the configuration to take 60 characters into account
("amount=xxxxxxxx&article=xxxxxxxx&mode=xxxxxxxxxx&code=xxxxx").
<trackinglogd args="" autoStart="false" maxCreateFileRetry="5" maxLogsSizeOnDiskMb="500"
maxSharedLogs="10000" pre400LogsFormat="false" processRestartTime="06:00:00"
purgeLogsPeriod="50000" runLevel="10"
webTrackingParamSize="60"/>
When the configuration has been modified, you must:

n Stop the web server that hosts the redirection module (Apache, IIS, etc.),
n Stop the Neolane server: net stop nlserver5 in Windows, /etc/init.d/nlserver5 stop in
Linux,
n In Linux, delete the shared memory segments using the ipcrm command,
n Restart the Neolane server: net start nlserver5 in Windows, /etc/init.d/nlserver5 start
in Linux,
n Restart the web server.
Example: taking into account of the configuration under Linux.
neolane@selma:~$ /etc/init.d/nlserver5 stop
neolane@selma:~$ /etc/init.d/apache stop
neolane@selma:~$ ipcs shm
------ Shared Memory Segments --------

key shmid owner perms bytes nattch status
0x52020679 2097153 neolane 666 93608 8
------ Semaphore Arrays --------

key semid owner perms nsems
0x52020678 4227081 neolane 666 1
------ Message Queues --------

key msqid owner perms used-bytes messages
neolane@selma:~$ ipcrm shm 2097153

1 resource(s) deleted
neolane@selma:~$ /etc/init.d/nlserver5 start
neolane@selma:~$ /etc/init.d/apache start
Creating web tracking tags

Each page of the site that you wish to track must be referenced in your Neolane platform. This referencing
can be performed in two ways:
1 Manual definition of URLs to be tracked,

2 On-the-fly creation of URLs to be tracked.

Neolane
Defining the URLs to be tracked in the application

This method lets you manually define the pages to be tracked and then generate an example of the associated
web tracking tag. This operation is defined in the Campaign execution>Resources>Web tracking tags
node of the client console.
To generate the HTML code to be inserted in the page:

n Enter the label of the tag: it will be shown in the tracking logs,
n Indicate the source URL: this field is for information purposes and lets you indicate the tracked page
(optional),
n If needed, enter a validity period,
n Click Generate HTML code.
Then copy the generated code and paste it into the page to be tracked.
On-the-fly creation of URLs to be tracked

You can create the web tracking URLs on the fly by adding information to the value of the tagid parameter:
n Type of page tracked: 'w' for WEB or 't' for TRANSACTION,
n The internal name of the folder where the URL must be created.
These two pieces of information must be concatenated with the identifier of the tracked page by adding the
character '|':
tagid=<identifier>|<type>|<foldername>
Warning:
Remember to encode the value of the tagid parameter when it is used as a URL parameter.
Example: creation of a transaction-type web tracking URL.

http://myserver.neolane.com/r/a?tagid=home%7Ct%7CMyFolder
206 | Neolane 2013

Inserting tags in your site
Simple method
This method consists of sending an HTTP call to the redirection server by inserting an <IMG> HTML tag in
the HTML source code of the web page you wish to track.
Warning:
This method uses the cookies sent by the web browser to identify the recipient, and is not 100% reliable.
Example:
<img height='0' width='0' alt='' src='http://localhost/r/12343?tagid=home'
The inserted tag contacts the redirection server.
Figure 8.2. Client/redirection server/web server exchanges
When you define a page to be tracked in the console, you can generate a sample web tracking tag to copy
and paste into the source code of your web page.
When you use TRANSACTION-type tags, however, you must modify the sample tag using JavaScript in order
to insert the transaction information (amount, number of items) and any information defined by an extension
schema.
Static insertion of tags

To perform static tag insertion, simply copy and paste the tags generated by the console or constructed
manually into the source of your web page.
Example: insertion of a web tracking tag on a page displaying a form.
<html>
<...>
<body>
<script>
document.write("<img height='0' width='0' alt='' src='http://localhost/r/" +
Math.random().toString() + "?tagid=home'>");
</script>
<noscript>
<img height='0' width='0' alt='' src='http://localhost/r/?tagid=home'>
</noscript>
<h1>My site</h1>
<form action="http://localhost/amount.html">
Quantity: <input type="text" name="quantity"/><br/><br/>
Amount: <input type="text" name="amount"/><br/><br/>
<input value="Save" type="submit">
</form>
</body>
</html>
Insertion of a TRANSACTION-type web tracking tag in the confirmation page ("amount.html").

<html>
<body>

Neolane
<script>
function getURLparam(name)
{
var m = location.search.match new RegExp("[?&]" + name + "=([^&]+)"));
return m? unescape(m[1]): "";
}
var params = "http://localhost/r/" + Math.random().toString() +

"?tagid=amount&amount="
+getURLparam("amount")+"&article="+getURLparam("quantity");
document.write("<img height='0' width='0' src='"+params+"'/>");
</script>
<h1>Approval confirmation</h1>
</body>
</html>
Dynamic generation of web tracking tags

When your web pages are generated dynamically, you can add the web tracking tag at page generation
time.
Example: Web tracking added to JSPs.
<%@page import="java.util.Random" %>
<html>
<body>
<img height='0' width='0' alt='' src='http://localhost/r/<%=new
Random().nextInt()%>?tagid=home'>
<h1>My site</h1>
<form action="http://localhost/amount.html">
Quantity: <input type="text" name="quantity"/><br/><br/>
Amount: <input type="text" name="amount"/><br/><br/>
<input value="Save" type="submit">
</form>
</body>
</html>
<%@page import="java.util.Random" %>

<html>
<body>
<%
String strParams = new Random().nextInt() + "?tagid=amount";
strParams += "&amount="+request.getParameter("amount");
strParams += "&article="+request.getParameter("quantity");
%>
<img height='0' width='0' alt=''
src='http://localhost/r/<%=strParams%>'>
<h1>Approval confirmation</h1>
</body>
</html>
Optimum method
If you wish to control the information sent to the redirection server, the most reliable way is to perform the
HTTP query synchronously yourself using a page generating language.
208 | Neolane 2013

The URL you construct must obey the syntax rules defined in Web tracking tag: definition [page 202].
Figure 8.3. Client/redirection server/web server exchanges
Note:
Redirection and web tracking use cookies, and it is important that the web server performing the synchronous
HTTP call be in the same domain as the redirection server. The various HTTP exchanges must convey the
'id', 'uuid', and 'uuid230' cookies.
Example: Dynamic generation in Java, with recipient authentication using their account number.
[...]
// Recipient account, amount and articles
String strAccount = request.getParameter("account");
String strAmount = request.getParameter("amount");
String strArticle = request.getParameter("article");
StringBuffer strCookies = new StringBuffer();

String strSetCookie = null;
// Get cookies from client request

Cookie[] cookies = request.getCookies();
for(int i=0; i< cookies.length; i++ )
{
Cookie c = cookies[i];
String strName = c.getName();
if( strName.equals("id") || strName.equals("uuid") || strName.equals("uuid230") )
// Helper function to add cookies in string
AddCookie(strCookies, c);
}
// Now perform a synchronous HTTP request to inform redirection server
// Add a tagid in auto-discover mode, and a default jobId to use (in hexa)
StringBuffer strURL = new
StringBuffer("http://www.neolane.com/r/a?tagid=cmd_page%7Ct&jobid=27EE");
if( strAccount!= null )
AddParameter(strURL, "rcpid", "saccount="+strAccount);
if( strAmount!= null )
AddParameter(strURL, "amount", strAmount);
if( strArticle!= null )
AddParameter(strURL, "article", strArticle);
URL url = new URL(strURL.toString());

HttpURLConnection connection = (HttpURLConnection)url.openConnection();
// Add the client cookies

Neolane
if( strCookies.length() > 0 )

connection.setRequestProperty("Cookie", strCookies.toString());
int errcode = connection.getResponseCode();
// Now add the Neolane cookies if the server returned one:

if( errcode == 200 )
{
strSetCookie = connection.getHeaderField("Set-Cookie");
if( strSetCookie!= null && strSetCookie.length() > 0 )
response.addHeader("Set-Cookie", strSetCookie);
}
[...]
Collecting all visits to a site

The web tracking module supplied by Neolane lets you collect the visits to certain pages of the site performed
by a recipient in the context of site tracking following a click in a message.
You can, however, configure your platform so that it collects all visits to pages with a web tracking tag by a
user known to the platform.
A user known to the platform is a recipient who has already been targeted by a delivery and who has clicked
in a received message at least once. A permanent cookie is used to identify this recipient.
Warning:
The Neolane platform is not intended for use as a website tracking tool beyond the context of visiting the
site following a click in a message. When this option is enabled, it can cause very high use of resources on
the machines hosting your servers (redirection, application, and database). You are advised to ensure that
your hardware architecture can support this load, and to avoid placing web tracking tags in the most frequently
visited pages, such as the home page.
Server configuration
The servers are configured by overloading certain elements of the serverConf.xml file. These files are
saved in the conf subdirectory of the Neolane installation directory.
Redirection server
For the redirection server, set the trackWebVisitors attribute of the redirection element to true.
<redirection P3PCompactPolicy="CAO DSP COR CURa DEVa TAIa OUR BUS IND UNI COM NAV"
databaseId="" defLogCount="30" expirationURL="" maxJobsInCache="100"
startRedirection="true" startRedirectionInModule="true" trackWebVisitors="true"
trackingPassword=""
Configuring a default matching campaign

To view tracking information via your client console, you must:
n Create a dummy delivery (the delivery mapping must be identical to the mapping of the target schema),
n Enter the internal name of this delivery in the NmsTracking_WebTrackingDelivery option.
All site tracking information not directly subsequent to a click in an e-mail can be viewed in the dummy
delivery created.
Anonymous tracking
Neolane lets you link collected Web tracking information to a recipient when they browse your site
anonymously. When a user browses the tagged pages of your website this browsing information is collected,
so that once they click in an email sent by Neolane, they are identified and the information is automatically
linked to them.
210 | Neolane 2013

Warning:
Setting up anonymous tracking on a website can trigger the collection of a significant amount of tracking
logs, thereby impacting database operation. Configure it with care.
Tracking logs are saved in the database until the tracking data is purged. Use the deployment wizard to
configure the purge frequency. For more on this, refer to the Installation guide.
To enable anonymous Web tracking on your instance, the following elements must be configured:
n The trackWebVisitors parameter of the redirection element of the serverConf.xml file of the
tracking server must be set to 'true', to place a permanent cookie (uuid230) in the browsers of unknown
internet users who visit the site.
n The Anonymous Web Tracking mode must be selected in the tracking configuration screen of the
deployment wizard.

Neolane
n Web forms and surveys must be published and executed on the tracking server. The matching option
must be selected in the deployment wizard.
212 | Neolane 2013

Adobe Campaign Configuration v6.1 en

Caricato da

Informazioni sul documento

Titolo originale

Copyright

Formati disponibili

Condividi questo documento

Condividi o incorpora il documento

Opzioni di condivisione

Hai trovato utile questo documento?

Questo contenuto è inappropriato?

Copyright:

Formati disponibili

Adobe Campaign Configuration v6.1 en

Caricato da

Copyright:

Formati disponibili

Configuration Guide

Version number : 8141

Neolane v6.1 - Configuration Guide

Chapter 1. Neolane datamodel . . . . . . . . . . . . . . . . . . . . 9

Neolane v6.1 - Configuration Guide | 3

Chapter 2. Schema Reference (xtk:srcSchema) . . . . . . . . . . . . . . . . 65

<method> element . . . . . . . . . . . . . . . . . . . . . . . . . . 103

Chapter 3. Editing and extending schemas . . . . . . . . . . . . . . . . . 113

Chapter 4. Input forms . . . . . . . . . . . . . . . . . . . . . . . . . 133

Chapter 5. API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147

Neolane v6.1 - Configuration Guide | 5

Error management . . . . . . . . . . . . . . . . . . . . . . . . . . 150

Chapter 6. Navigation hierarchy . . . . . . . . . . . . . . . . . . . . . . 177

Chapter 7. Using an external recipient table . . . . . . . . . . . . . . . . . 185

Creating lists based on the external recipient table . . . . . . . . . . . . . . . 195

Chapter 8. Setting up Web tracking . . . . . . . . . . . . . . . . . . . . 199

Neolane v6.1 - Configuration Guide | 7

8 | Neolane v6.1 - Configuration Guide

Neolane v6.1 - Configuration Guide - Neolane datamodel | 9

Accessing the Neolane dataschemas

Physical and logical data

Neolane v6.1 - Configuration Guide - Neolane datamodel | 11

Auto-incrementing primary keys

Neolane v6.1 - Configuration Guide - Neolane datamodel | 13

Description of the main tables

Field Type Description Values

sAccount string Account # -

sOrigin string Origin -

iBlackList boolean No longer contact (by any channel) -

iBlackListEmail boolean No longer contact by email -

iBlackListPhone boolean No longer contact by phone -

iBlackListFax boolean No longer contact by fax -

iBlackListMobile boolean No longer contact by SMS/MMS -

iBlackListPostalMail boolean No longer contact by direct mail -

sLastName string Name -

sFirstName string First name -

sMiddleName string Middle name -

sSalutation string Salutation -

iGender byte Gender 0-None specified

sLanguage string Language -

sCompany string Company -

sEmail string Email -

iEmailFormat byte E-mail format 0-Unknown

sMobilePhone string Mobile -

sPhone string Phone -

sFax string Fax -

sAddress1 string Address 1 (apartment) -

sAddress2 string Address 2 -

sAddress3 string Address 3 (Number and street) -

sAddress4 string Address 4 (county) -

sZipCode string Zip/Postcode -

sCity string City -

sStateCode string State/Province code -

sCountryCode string Country code -

iAddrQuality long Quality rating 0-0 - Incomplete address

iAddrErrorCount long Number of errors -

sText1 string Text 1 -

sText2 string Text 2 -

sText3 string Text 3 -

sText4 string Text 4 -

sText5 string Text 5 -

iBoolean1 boolean Boolean 1 -

Neolane v6.1 - Configuration Guide - Neolane datamodel | 15