Neolane v6.1 - Configuration Guide - Adobe and extending schemas . . . . . . . . . . . . . . . . . 113 ... Server configuration ... Configuration Guide - Neolane

Configuration GuideNeolane 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 theprovisions of the License Agreement. No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in anyform 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 notconstitute a commitment on the part of Neolane. Neolane does not guarantee the accuracy nor the completeness of the informationcontained within this document. References to company names are intended to be ficticious and for illustrative purposes only and do notrefer 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 UnitedStates 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 developedby Apache Software Foundation (http://www.apache.org/).

For any questions or queries, please send a message to the following address: [email protected].

Version number : 8141

Neolane18 rue Roger Simon Barboux, 94110 Arcueil - France+33 1 41 98 35 35www.neolane.com

Neolane v6.1 - Configuration Guide

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

Accessing the Neolane dataschemas . . . . . . . . . . . . . . . . . . 11General information . . . . . . . . . . . . . . . . . . . . . . . . 11

Physical and logical data . . . . . . . . . . . . . . . . . . . . . 11Work tables . . . . . . . . . . . . . . . . . . . . . . . . . . 11Table structure . . . . . . . . . . . . . . . . . . . . . . . . . 12Auto-incrementing primary keys . . . . . . . . . . . . . . . . . . . 12Zero-ID record . . . . . . . . . . . . . . . . . . . . . . . . . 12"Deleted" field . . . . . . . . . . . . . . . . . . . . . . . . . . 12Track changes . . . . . . . . . . . . . . . . . . . . . . . . . 13

Description of the main tables . . . . . . . . . . . . . . . . . . . . 14Simplified diagram . . . . . . . . . . . . . . . . . . . . . . . . 14NmsRecipient . . . . . . . . . . . . . . . . . . . . . . . . . . 14NmsGroup . . . . . . . . . . . . . . . . . . . . . . . . . . . 16NmsRcpGrpRel . . . . . . . . . . . . . . . . . . . . . . . . . 17NmsService . . . . . . . . . . . . . . . . . . . . . . . . . . 17NmsSubscription . . . . . . . . . . . . . . . . . . . . . . . . 19NmsSubHisto . . . . . . . . . . . . . . . . . . . . . . . . . . 19NmsDelivery . . . . . . . . . . . . . . . . . . . . . . . . . . 20XtkFolder . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Delivery and tracking . . . . . . . . . . . . . . . . . . . . . . . . 28NmsBroadLogMsg . . . . . . . . . . . . . . . . . . . . . . . . 28

Simulation and delivery . . . . . . . . . . . . . . . . . . . . . . . 30Communication consistency and capacity rules . . . . . . . . . . . . . . 31

NmsTypologyRule . . . . . . . . . . . . . . . . . . . . . . . . 31NmsTypology . . . . . . . . . . . . . . . . . . . . . . . . . . 32NmsTypologyRuleRel . . . . . . . . . . . . . . . . . . . . . . . 33

Response management . . . . . . . . . . . . . . . . . . . . . . . 33Campaign management . . . . . . . . . . . . . . . . . . . . . . . 34

NmsOperation . . . . . . . . . . . . . . . . . . . . . . . . . 34NmsDeliveryOutline . . . . . . . . . . . . . . . . . . . . . . . 36NmsDlvOutlineItem . . . . . . . . . . . . . . . . . . . . . . . 36NmsDeliveryCustomization . . . . . . . . . . . . . . . . . . . . 37NmsBudget . . . . . . . . . . . . . . . . . . . . . . . . . . 37NmsDocument . . . . . . . . . . . . . . . . . . . . . . . . . 38XtkWorkflow . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Neolane v6.1 - Configuration Guide | 3

Table of Contents

NmsTask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41NmsAsset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Interaction Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45NmsOffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45NmsPropositionRcp . . . . . . . . . . . . . . . . . . . . . . . . . . . 46NmsOfferSpace . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47NmsOfferView . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48NmsOfferCategory . . . . . . . . . . . . . . . . . . . . . . . . . . . 49NmsOfferEnv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

Message Center Module . . . . . . . . . . . . . . . . . . . . . . . . . . 51NmsRtEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51NmsBatchEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

Social Marketing Module . . . . . . . . . . . . . . . . . . . . . . . . . . 55NmsVisitor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55NmsVisitorSub . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56NmsFriendShipRel . . . . . . . . . . . . . . . . . . . . . . . . . . . 56NmsVisitorInterestRel . . . . . . . . . . . . . . . . . . . . . . . . . . 57NmsInterest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

Microsites Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58NmsTrackingUrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58NmsPurl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

NMAC Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60NmsMobileApp . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60NmsAppSubscriptionRcp . . . . . . . . . . . . . . . . . . . . . . . . . 61NmsExcludeLogAppSubRcp . . . . . . . . . . . . . . . . . . . . . . . 62NmsTrackingLogAppSubRcp . . . . . . . . . . . . . . . . . . . . . . . 62NmsBroadLogAppSubRcp . . . . . . . . . . . . . . . . . . . . . . . . 63

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

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66Syntax of schemas . . . . . . . . . . . . . . . . . . . . . . . . . . . 66Identification of a schema . . . . . . . . . . . . . . . . . . . . . . . . 67

Schema structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69Data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70Collections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73Referencing with XPath . . . . . . . . . . . . . . . . . . . . . . . . . 73Building a string via the compute string . . . . . . . . . . . . . . . . . . . 74

Database mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75XML fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75Calculated fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76Indexed fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76Management of keys . . . . . . . . . . . . . . . . . . . . . . . . . . 77Links: 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

Neolane

<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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114Example: creating a contract table . . . . . . . . . . . . . . . . . . . . . 115

Schema of an existing table or a view . . . . . . . . . . . . . . . . . . . . 118Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118Accessing an external database . . . . . . . . . . . . . . . . . . . . . 119

Extending an existing schema . . . . . . . . . . . . . . . . . . . . . . . 121Protecting schemas . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

System filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122Protecting out-of-the-box schemas . . . . . . . . . . . . . . . . . . . . 122Modifying system filters of out-of-the-box schemas . . . . . . . . . . . . . . 123

Updating the physical structure of the database . . . . . . . . . . . . . . . . 124New field wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125Schema structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127Regenerating all schemas . . . . . . . . . . . . . . . . . . . . . . . . . 127Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127

Extending a table . . . . . . . . . . . . . . . . . . . . . . . . . . . 127Linked collection table . . . . . . . . . . . . . . . . . . . . . . . . . 128Extension table . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129Overflow table . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130Relationship table . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

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

Identifying a form . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133Editing forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134Form structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135

Formatting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136Containers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137Editing a link . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139List of links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140Memory list controls . . . . . . . . . . . . . . . . . . . . . . . . . . 142Non-editable fields . . . . . . . . . . . . . . . . . . . . . . . . . . . 143Radio button . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144Checkbox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144Navigation hierarchy edit . . . . . . . . . . . . . . . . . . . . . . . . 144Expression field . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144Context of forms . . . . . . . . . . . . . . . . . . . . . . . . . . . 145Wizards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145

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

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


Configuration Guide

Error management . . . . . . . . . . . . . . . . . . . . . . . . . . 150URL of Web service server (or EndPoint) . . . . . . . . . . . . . . . . . . 151

Web service calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151General information . . . . . . . . . . . . . . . . . . . . . . . . . . 151Definition of Web services . . . . . . . . . . . . . . . . . . . . . . . . 151Web service description: WSDL . . . . . . . . . . . . . . . . . . . . . . 152Connectivity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153

Data oriented API . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156Overview of the datamodel . . . . . . . . . . . . . . . . . . . . . . . 156Description of the model . . . . . . . . . . . . . . . . . . . . . . . . 156Query and Writer . . . . . . . . . . . . . . . . . . . . . . . . . . . 156ExecuteQuery (xtk:queryDef) . . . . . . . . . . . . . . . . . . . . . . 157Write / WriteCollection (xtk:session) . . . . . . . . . . . . . . . . . . . . 164

Business oriented APIs . . . . . . . . . . . . . . . . . . . . . . . . . . 166Subscribe (nms:subscription) . . . . . . . . . . . . . . . . . . . . . . 167Unsubscribe (nms:subscription) . . . . . . . . . . . . . . . . . . . . . 168SubmitDelivery (nms:delivery) . . . . . . . . . . . . . . . . . . . . . . 169

Implementing SOAP methods in JavaScript . . . . . . . . . . . . . . . . . . 170Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170Definition of a method library . . . . . . . . . . . . . . . . . . . . . . . 170

Use SOAP methods in JavaScript . . . . . . . . . . . . . . . . . . . . . . 171Static methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171Non-static methods . . . . . . . . . . . . . . . . . . . . . . . . . . 172Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172

Adding additional SQL functions . . . . . . . . . . . . . . . . . . . . . . 173Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173General structure of package to import . . . . . . . . . . . . . . . . . . . 173The <function> function descriptor . . . . . . . . . . . . . . . . . . . . 174The "pass-through" function descriptor . . . . . . . . . . . . . . . . . . . 175Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175

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

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178

Global commands . . . . . . . . . . . . . . . . . . . . . . . . . . . 179Folder type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180

Edition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183

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

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185Precisions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185Recommendations and limitations . . . . . . . . . . . . . . . . . . . . . 186

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186The View attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . 186Names of tables and columns . . . . . . . . . . . . . . . . . . . . . . 187Indexed fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187

Setting up a target mapping . . . . . . . . . . . . . . . . . . . . . . . . 187Creating and configuring the schemas linked to the external table . . . . . . . . . 188Using target mapping . . . . . . . . . . . . . . . . . . . . . . . . . 191

Configuring the interface to use the new recipient table . . . . . . . . . . . . . . 191Creating a new form . . . . . . . . . . . . . . . . . . . . . . . . . . 192Creating a new type of folder in the navigation hierarchy . . . . . . . . . . . . 192

Configuring seed addresses based on an external recipient table . . . . . . . . . . 193Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193

Creating filters to manipulate the new recipient table . . . . . . . . . . . . . . . 194

6 | © Neolane 2013

Neolane

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

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

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199Web tracking mode . . . . . . . . . . . . . . . . . . . . . . . . . . . 200Web tracking tag: definition . . . . . . . . . . . . . . . . . . . . . . . . 202

Format of the data to be sent . . . . . . . . . . . . . . . . . . . . . . . 203Data transmission methods . . . . . . . . . . . . . . . . . . . . . . . 203

Setup stages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203Additional web tracking parameters . . . . . . . . . . . . . . . . . . . . . 204

Definition of parameters . . . . . . . . . . . . . . . . . . . . . . . . 204Redirection server configuration . . . . . . . . . . . . . . . . . . . . . 205

Creating web tracking tags . . . . . . . . . . . . . . . . . . . . . . . . 205Defining the URLs to be tracked in the application . . . . . . . . . . . . . . . 206On-the-fly creation of URLs to be tracked . . . . . . . . . . . . . . . . . . 206

Inserting tags in your site . . . . . . . . . . . . . . . . . . . . . . . . . 207Simple method . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207Optimum method . . . . . . . . . . . . . . . . . . . . . . . . . . . 208

Collecting all visits to a site . . . . . . . . . . . . . . . . . . . . . . . . 210Server configuration . . . . . . . . . . . . . . . . . . . . . . . . . . 210Configuring a default matching campaign . . . . . . . . . . . . . . . . . . 210

Anonymous tracking . . . . . . . . . . . . . . . . . . . . . . . . . . . 210


Configuration Guide

8 | Neolane v6.1 - Configuration Guide

Neolane

Table of ContentsAccessing the Neolane dataschemas . . . . . . . . . . . . . . . . . . . 11General information . . . . . . . . . . . . . . . . . . . . . . . . . 11

Physical and logical data . . . . . . . . . . . . . . . . . . . . . . . 11Work tables . . . . . . . . . . . . . . . . . . . . . . . . . . . 11Table structure . . . . . . . . . . . . . . . . . . . . . . . . . . 12Auto-incrementing primary keys . . . . . . . . . . . . . . . . . . . . 12Zero-ID record . . . . . . . . . . . . . . . . . . . . . . . . . . 12"Deleted" field . . . . . . . . . . . . . . . . . . . . . . . . . . 12Track changes . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Description of the main tables . . . . . . . . . . . . . . . . . . . . . . 14Simplified diagram . . . . . . . . . . . . . . . . . . . . . . . . . 14NmsRecipient . . . . . . . . . . . . . . . . . . . . . . . . . . 14NmsGroup . . . . . . . . . . . . . . . . . . . . . . . . . . . 16NmsRcpGrpRel . . . . . . . . . . . . . . . . . . . . . . . . . . 17NmsService . . . . . . . . . . . . . . . . . . . . . . . . . . . 17NmsSubscription . . . . . . . . . . . . . . . . . . . . . . . . . 19NmsSubHisto . . . . . . . . . . . . . . . . . . . . . . . . . . . 19NmsDelivery . . . . . . . . . . . . . . . . . . . . . . . . . . . 20XtkFolder . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Delivery and tracking . . . . . . . . . . . . . . . . . . . . . . . . . 28NmsBroadLogMsg . . . . . . . . . . . . . . . . . . . . . . . . . 28

Simulation and delivery . . . . . . . . . . . . . . . . . . . . . . . . 30Communication consistency and capacity rules . . . . . . . . . . . . . . . . 31

NmsTypologyRule . . . . . . . . . . . . . . . . . . . . . . . . . 31NmsTypology . . . . . . . . . . . . . . . . . . . . . . . . . . 32NmsTypologyRuleRel . . . . . . . . . . . . . . . . . . . . . . . . 33

Response management . . . . . . . . . . . . . . . . . . . . . . . . 33Campaign management . . . . . . . . . . . . . . . . . . . . . . . . 34

NmsOperation . . . . . . . . . . . . . . . . . . . . . . . . . . 34NmsDeliveryOutline . . . . . . . . . . . . . . . . . . . . . . . . 36NmsDlvOutlineItem . . . . . . . . . . . . . . . . . . . . . . . . 36NmsDeliveryCustomization . . . . . . . . . . . . . . . . . . . . . . 37NmsBudget . . . . . . . . . . . . . . . . . . . . . . . . . . . 37NmsDocument . . . . . . . . . . . . . . . . . . . . . . . . . . 38XtkWorkflow . . . . . . . . . . . . . . . . . . . . . . . . . . . 39NmsTask . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41NmsAsset . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Interaction Module . . . . . . . . . . . . . . . . . . . . . . . . . . 45NmsOffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45NmsPropositionRcp . . . . . . . . . . . . . . . . . . . . . . . . 46

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

CHAPTER 1

Neolane datamodel

NmsOfferSpace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47NmsOfferView . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48NmsOfferCategory . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49NmsOfferEnv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

Message Center Module . . . . . . . . . . . . . . . . . . . . . . . . . . . 51NmsRtEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51NmsBatchEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

Social Marketing Module . . . . . . . . . . . . . . . . . . . . . . . . . . . 55NmsVisitor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55NmsVisitorSub . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56NmsFriendShipRel . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56NmsVisitorInterestRel . . . . . . . . . . . . . . . . . . . . . . . . . . . 57NmsInterest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

Microsites Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58NmsTrackingUrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58NmsPurl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

NMAC Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60NmsMobileApp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60NmsAppSubscriptionRcp . . . . . . . . . . . . . . . . . . . . . . . . . . 61NmsExcludeLogAppSubRcp . . . . . . . . . . . . . . . . . . . . . . . . . 62NmsTrackingLogAppSubRcp . . . . . . . . . . . . . . . . . . . . . . . . . 62NmsBroadLogAppSubRcp . . . . . . . . . . . . . . . . . . . . . . . . . . 63

This chapter details the articulation of the main worktables rather than the internal operating tables, aswell as the specifics of the Neolane datamodel. The aim is to provide the user with a better understandingof the model, in view of analyzing data, configuring new reports, performing targeting based on behaviorafter a delivery, exporting data linked to the delivery or synchronizing data with an external system, etc.

10 | © Neolane 2013

Neolane

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 dataPhysical 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 dataor parts of schemas are described in XML elements and are only stored in a single XML field. This is the casewith the link between deliveries and typology rules for HTML content, for exampleMoreover, 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 isthe case for system enumerations (sysenum), for example.

Work tablesWork tables are created, then destroyed during application phases. The name and structure of some tablesare defined at run time (Data Management and targeting workflows, etc.), while others are persistent dynamictables (lists, answers to a survey, simulation results).


Neolane datamodel

Table structureSome 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 keysThe 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 isinitialized to 1000, the first 1000 identifiers are reserved. As a result, if for any reason, you have to "hardcode" 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 recordFor all tables that use our sequence as a primary key, a record with 0 as a value is inserted uponcreation. This 0 ID record is used to avoid external joins that aren't efficient for tables with a significantvolume. By highlighting the 0 value in the foreign key of a table when the data isn't recorded, a join is createdon this 0 value record that contains no data. All queries carried out via the application ignore this record inthe 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, editadditional data (in Query or Enrichment boxes, for example), click the Advanced settings link and checkthe Disable automatic filtering of 0 identifier records option.

"Deleted" fieldCertain tables contain an iDeleteStatus field (NmsDelivery, NmsService and NmsSubscription inparticular). This field is used for managing the Recycle Bin and performing time-consuming deletions duringthe night.The value 1 means that the record will be deleted by the cleanup workflow next time it is executed (mostlyscheduled 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 physicallydeleted 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. Deleteddeliveries 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 thedate on which the record was placed in the recycle bin.

12 | © Neolane 2013

Neolane

Track changesCertain 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 toXtkOperator),

n iModifiedById contains the ID of the last operator who modified the record (foreign key of a link toXtkOperator).

These fields are added in the schemas using the auditTrail aggregate. Other schemas only use certainfields. For example NmsRecipient contains tsCreated and tsLastModified only. These fields are populatedautomatically 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 insertionscarried out in the database and not via the console will have no effect on these dates.


Neolane datamodel

Description of the main tables

Simplified diagramThe following is a diagram showing the joins between the main business tables of the Neolane data modelwith the main fields shown for each.

NmsRecipientThis table matches the nms:recipient schema.It is the default table used for the recipients of deliveries. As a result, it contains the information requiredfor 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 descriptionof 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 therecipient. This field is actually a foreign key on the country reference table (NmsCountry), which containsthe country labels and other country code data. If the country is not populated, the value 'XX' is stored (andis used in place of a zero ID record).

14 | © Neolane 2013

Neolane

General information

ValuesDescriptionTypeField

-Primary keylongiRecipientId

-Account #stringsAccount

-OriginstringsOrigin

-No longer contact (by any channel)booleaniBlackList

-No longer contact by emailbooleaniBlackListEmail

-No longer contact by phonebooleaniBlackListPhone

-No longer contact by faxbooleaniBlackListFax

-No longer contact by SMS/MMSbooleaniBlackListMobile

-No longer contact by direct mailbooleaniBlackListPostalMail

-NamestringsLastName

-First namestringsFirstName

-Middle namestringsMiddleName

-SalutationstringsSalutation

0-None specified

1-Male

2-Female

GenderbyteiGender

-LanguagestringsLanguage

-CompanystringsCompany

-EmailstringsEmail

0-Unknown

1-Text

2-HTML

E-mail formatbyteiEmailFormat

-MobilestringsMobilePhone

-PhonestringsPhone

-FaxstringsFax

-Address 1 (apartment)stringsAddress1

-Address 2stringsAddress2

-Address 3 (Number and street)stringsAddress3

-Address 4 (county)stringsAddress4

-Zip/PostcodestringsZipCode

-CitystringsCity

-State/Province codestringsStateCode

-Country codestringsCountryCode

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

Quality ratinglongiAddrQuality

-Number of errorslongiAddrErrorCount

-Text 1stringsText1

-Text 2stringsText2

-Text 3stringsText3

-Text 4stringsText4

-Text 5stringsText5

-Boolean 1booleaniBoolean1


Neolane datamodel




0-Prospect

1-Client

StatusbyteiStatus

Table keys


-Foreign key of link 'Folder' (field 'id')longiFolderId

Time fields


-Creation datedatetimetsCreated

-Modification datedatetimetsLastModified

-Last qualificationdatetimetsAddrLastCheck

-Birth datedatetsBirth

NmsGroupThis table matches the nms:group schema.It enables you to create statical groups of recipients. There is a many-to-many relation between recipientsand groups. For example, one recipient can belong to several groups and one group can contain severalrecipients. Groups can be created manually, via an import or via delivery targeting. Groups are often usedas 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


-Primary keylongiGroupId

-Internal namestringsName

-LabelstringsLabel

-SchemastringsSchema

-Built in import templatebooleaniBuiltIn

0-Group

1-List

2-File

3-Template

List typebyteiType

0-No

1-Yes

2-Recycled

DeletedbyteiDeleteStatus

0-Neolane

1-SPSS

2-Business Objects

OriginbyteiCreatedFrom

16 | © Neolane 2013

Neolane


-Use a line number as identifierbooleaniCollectLineNumber

Table keys


-Foreign key of link 'Created by' (field 'id')longiCreatedById

-Foreign key of link 'Modified by ' (field 'id')longiModifiedById

-Foreign key of link 'List folder' (field 'id')longiFolderId

-Foreign key of link 'Workflow' (field 'id')longiWorkflowId

-Foreign key of link 'Marketing campaign'(field 'id')

longiOperationId

Time fields


-Delete datedatetimetsDelete


-Last modifieddatetimetsLastModified

NmsRcpGrpRelThe NmsRcpGrpRel relationship table only contains the two fields corresponding to the identifiers of theiRecipientId and iGroupId linked tables.

Table keys


-Foreign key of link 'Recipient' (field 'id')longiRecipientId

-Foreign key of link 'List' (field 'id')longiGroupId

NmsServiceThis table matches the nms:service schema.Services are entities which are similar to groups (static recipient groupings), except that they circulate moreinformation 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 islinked to a folder (The key is iFolderId. See the description of the XtkFolder table below). Finally, theiType field specifies the delivery channel of this service (0 for email, 1 for SMS, 2 for telephone, 3 for directmail and 4 for fax).

General information


-Primary keylongiServiceId


-LabelstringsLabel


Neolane datamodel


0-Email

1-Mobile (SMS)

20-Facebook

25-Twitter

40-Mobile application

TypebyteiType

0-Newsletter

1-Viral

ModebyteiMode

-UnlimitedbooleaniUnlimited

-Expiration datetimespantsValidity

-Text 1stringsText1

-Text 2stringsText2

-Text 3stringsText3

-Text 4stringsText4

-Text 5stringsText5




-AudiencelongiAudience

-External identifierstringsExternalId

-ImagestringsExternalPicture

-Web linkstringsExternalUrl

-CategorystringsCategory

-Access tokenstringsAccessToken

-Access token secretstringsAccessTokenSecret

-Application IDstringsConsumerKey

-Application secretstringsConsumerSecret

-Synchronize subscriptionsbooleaniSyncSubscription

Table keys




-Foreign key of link 'Subscription confirma-tion' (field 'id')

longiSubScenarioId

-Foreign key of link 'Unsubscription confirm-ation' (field 'id')

longiUnsubScenarioId

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

longiFolderId

-Foreign key of link 'Target mapping linkedto mobile applications' (field 'id')

longiMobileAppsTargetMap-pingId

-Foreign key of link 'Visitor folder' (field 'id')longiVisitorFolderId

Time fields



18 | © Neolane 2013

Neolane



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

General information


-Specific AddressstringsAddressSpecific

0-Unknown

1-Text

2-HTML

E-mail formatbyteiEmailFormat

0-No

1-Yes

2-Recycled


-Confirmation IdlongiConfirmationId

Table keys


-Foreign key of link 'Service' (field 'id')longiServiceId


Time fields



-Expiration datedatetsExpiration

NmsSubHistoThis table matches the nms:subHisto schema.If the subscriptions are managed using web forms or the interface of the application, all susbcriptions andunsubscriptions are historized in the NmsSubHisto table. The iAction field specifies the action (0 forunsubscription and 1 for subscription) performed on the date stored in the tsDate field.

General information


-Primary keylongiSubHistoId

0-Unsubscription

1-Subscription

ActionshortiAction

Table keys




Neolane datamodel



Time fields


-DatedatetimetsDate

NmsDeliveryThis table matches the nms:delivery schema.Each record in this table represents a delivery action or a delivery template. It contains all the necessaryparameters 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 forfurther details on both of these tables).There is a unique index on the field representing the internal name of the sInternalName delivery orscenario. The delivery is linked to an execution folder (The foreign key is iFolderProcessId. See thedescription of the XtkFolder table below).

General information


-Primary keylongiDeliveryId

-Primary keylongiAttachmentId

-LabelstringsLabel

-LabelstringsLabel

-Internal namestringsInternalName

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

Analysis statusshortiStatus

-Import

-Export

-Subscription to services

-Subscription of groups

-Delivery

Job typestringsType

-SchemastringsXtkschema

-Application built-in scenariobooleaniBuiltIn

-TemplatebooleaniIsModel

-Messages to sent (FCP and seed ad-dresses)

longiFCPOrSeedCount

-Remote identifierlongiMidRemoteId

-Messages to sendlongiToDeliver

-Rejected during importlongiImportReject

-Seed addresseslongiSeedProcessed

-Messages excluded by the rulelongiReject

-PropositionslongiPropositionCount

-HTML messageslongiHtml

20 | © Neolane 2013

Neolane


-Text messageslongiText

-Multipart messageslongiMultipart

-Count of tracked URLslongiUrl

-Messages to validatelongiToValidate

-Control group exclusionslongiCtrlGrpReject

0-Constant

1-Depends on the recipient

2-Defined in each rule

Weight typebyteiWeightType

-Delivery weightlongiWeight

-Handled call rate (in %)doubledRate

-Handled call duration for telephone chan-nel

doubledDuration

-Manual

-Semi-automatic

-Automatic

Approval modestringsValidationMode

0-Automatic

1-Manual

-Manual

-Semi-automatic

-Automatic

Approval modebyteiValidationMode

-Schedule delivery startbooleaniDelayed

-Online resources purgedbooleaniWebResPurged

-Extraction wait periodtimespandDelayExtraction

-IP affinitystringsIPAffinity

-Execute during downtimebooleaniForecasted

-Execution loginstringsLogin

0-Low

1-Average

2-High

PrioritybyteiMsgPriority

0-Target estimation and message person-alization

1-Estimation and approval of the provision-al target

2-Target evaluation

Delivery modebyteiSandboxMode

-Enable budget approvalbooleaniUseBudgetValidation

-Enable target approvalbooleaniUseTargetValidation

-Enable content approvalbooleaniUseContentValidation

-Enable extraction validationbooleaniUseExtractionValidation

-Enable the sending and validation of proofsbooleaniUseFCPValidation

-Enable the automatic creation of approvaltasks

booleaniUseTaskCreation

-Enable validation for associated deliveriesbooleaniUseLinkedDeliveryValida-tion

-Do not enable notification sendingbooleaniDisableNotification

-Assign content editingbooleaniAssignEdition

-External content approvalbooleaniExternalValidation

-Number of retriesshortiRetry

-Max. number of retriesshortiMaxRetry

-Period of retriestimespandRetryPeriod


Neolane datamodel


0-unknown

1-yes

2-no

3-fromMsgId

Mirror page usagebyteiNeedMirrorPage

0-Respect the sort order

1-At the start of the file

2-At the end of the file

3-Random

Insertion modebyteiInsertMode

0-Up to date

1-Tracking

2-Errors

4-Reset tracking

8-Message counters

UpdatebyteiDirty

-Unqualified errorslongiErrorPending

-Tracking not taken into accountlongiTrackingPending

-ProcessedlongiProcessed

-SentlongiSent

-SuccesslongiSuccess

-Success excluding seed addresseslongiSuccessWithoutSeeds

-ErrorslongiError

-New quarantineslongiNewQuarantine

-Unknown userslongiUnknownUser

-Invalid domainslongiInvalidDomain

-UnreachableslongiUnreachable

-Deactivated accountslongiDisabled

-Mailbox fulllongiMailboxFull

-Not connectedlongiNotConnected

-RefusedlongiRefused

-Recipients who have openedlongiRecipientOpen

-Total count of openslongiTotalRecipientOpen

-Persons who have clickedlongiPersonClick

-Number of distinct clickslongiRecipientClick

-Total number of clickslongiTotalRecipientClick

-Number of forwardslongiForward

-Mirror pagelongiMirrorPage

-Opt-OutlongiOptOut

-TransactionslongiTransaction

-AmountdoubledAmount

-ArticleslongiArticle

-Distinct visited visitedlongiWebPage

-Visited pageslongiTotalWebPage

-MD5 keystringsMd5

-Screen

-Printing

-Press

CompressionstringsCompressMode

0-Not applicable

1-Being edited

2-Published

3-Publication failed

100-(In production)

Publication statebyteiPublicationStatus

22 | © Neolane 2013

Neolane


-Event typestringsEventType

-NaturestringsNature

-Use the new content editor ('DCE')booleaniUseDce

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

Current analysis stepbyteiAnalysisStep

0-Email

1-Mobile (SMS)

2-Phone

3-Direct Mail

4-Fax

20-Facebook

25-Twitter

41-iOS channel

42-Android channel

120-Other

ChannelbyteiMessageType

0-External

1-Bulk delivery

2-Description

4-Mid-sourcing

ModebyteiDeliveryMode

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

StatebyteiState

-Send a ProofbooleaniFCP

-Mid-sourcing relaybooleaniMidSourcing


Neolane datamodel


32-Very High

20-High

15-Higher than normal

10-Normal

5-Low

1-Very Low

Delivery prioritybyteiPriority

-Delivery codestringsDeliveryCode

-Add attached filesbooleaniHasAttachments

0-No

1-Yes

2-Recycled


0-Planned

1-Reserved

2-Committed

Commitment levelbyteiCommitmentLevel

-Estimated provisional costdoubledEstimatedCost

-Real costdoubledRealCost

-Calculated costdoubledComputedCost

0-Not defined

1-Pending calculation

2-Being calculated

3-Calculation finished

Cost calculation statusbyteiComputationState

-Provisional revenuedoubledTotalEstimatedRealized

-Provisional margindoubledTotalEstimatedMargin

-Unit revenuedoubledUnitaryCost

-Response ratedoubledResponseRatio

-Fixed margindoubledUnitaryMargin

-Margin as a percentagedoubledPercentMargin

0-Fixed

1-Percent

Margin typebyteiMarginType

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

Content statusbyteiContentStatus

0-Being edited

1-Pending approval

2-Approved

3-Rejected

Targeting statusbyteiTargetStatus

0-Being edited

1-Pending approval

2-Approved

3-Rejected

Budget statusbyteiBudgetStatus

0-Being edited

1-Pending approval

2-Approved

3-Rejected

4-Sent

Extraction statusbyteiExtractionStatus

24 | © Neolane 2013

Neolane


0-Being edited

1-Pending approval

2-Approved

3-Rejected

Status of inclusion in the provisional calen-dar

byteiSandboxStatus

Table keys



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

longiFolderProcessId



-Foreign key of link 'Routing' (field 'id')longiDeliveryProviderId

-Foreign key of link 'Typology' (field 'id')longiTypologyId

-Foreign key of link 'Delivery mapping' (field'id')

longiMappingId

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

longiProofedDeliveryId

-Foreign key of link 'Offer space' (field 'id')longiOfferSpaceId

-Foreign key of link 'Category' (field 'id')longiOfferCategoryId

-Foreign key of link 'Anonymous category'(field 'id')

longiOfferAnonymousCategory-Id

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

stringsPublishingNamespace

-Foreign key of link 'Publication template'(field 'name')

stringsPublishingName

-Foreign key of link 'Deliveries' (field 'id')longiDeliveryId

-Foreign key of link 'Campaign' (field 'id')longiOperationId

-Foreign key of link 'Operation owned' (field'id')

longiOwnerOperationId

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

longiRoutingDeliveryId


-Foreign key of link 'Charge back' (field 'id')longiBudgetId

-Foreign key of link 'Service' (field 'id')longiSupplierModelId

-Foreign key of link 'Main delivery' (field 'id')longiLinkedDeliveryId

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

longiDeliveryOutlineId

Time fields


-Analysis startdatetimetsStart

-Analysis completeddatetimetsEnd



-Template modification datedatetimetsScenarioModTime

-Contact datedatetimetsContact

-Validity limitdatetimetsValidity

-Validity limit date for resourcesdatetimetsWebValidity


Neolane datamodel


-Extraction requestdatetimetsExtraction

-Extraction datedatetimetsExtracted

-Next retrydatetimetsNextPass

-Start datedatetimetsBroadStart

-End datedatetimetsBroadEnd

-Pass startdatetimetsPassStart

-Error updatedatetimetsLastErrorComputation

-Tracking updatedatetimetsLastTrackingComputation

-Content modification datedatetimetsContentModTime

-Delete datedatetimetsDelete

-Last cost calculation datedatetimetsLastComputed

-Target approval deadlinedatetsExpectedTarget

-Content approval deadlinedatetsExpectedContent

-Budget approval deadlinedatetsExpectedBudget

-Extraction approval deadlinedatetsExpectedExtraction

-Proof approval deadlinedatetsExpectedFCP

-Approval deadline for inclusion in provision-al calendar

datetsExpectedForecast

-Content editing dealinedatetsExpectedEdition

-External approval deadlinedatetsExpectedExternal

-Target reminder datedatetsReminderTarget

-Content reminder datedatetsReminderContent

-Budget reminder datedatetsReminderBudget

-Extraction reminder datedatetsReminderExtraction

-Proof reminder datedatetsReminderFCP

-Reminder date for inclusion in provisionalcalendar

datetsReminderForecast

-Content editing deadline reminderdatetsReminderEdition

-External approval deadline reminderdatetsReminderExternal

XtkFolderIt 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 thefolder. 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 ofthe folder in the tree. Finally, there is a unique index on the field representing the internal name of thesName folder.

General information


-Primary keylongiFolderId


-LabelstringsLabel

-Native application folderbooleaniBuiltIn

-TemplatestringsModel

-Unselectable folderbooleaniUnSelected

26 | © Neolane 2013

Neolane


-Schema of entity of folderstringsEntity

-Number of child nodesshortiChildcount

-Node positionshortiOrder

-This folder is a viewbooleaniIsView

-System folderbooleaniSystem

-Full namestringsFullName

Table keys




-Foreign key of link 'Image' (field'namespace')

stringsImageNamespace

-Foreign key of link 'Image' (field 'name')stringsImageName

-Foreign key of link 'Organizational entity'(field 'id')

longiOrgUnitId

-Foreign key of link 'Parent' (field 'id')longiParentId

Time fields




Neolane datamodel



Delivery and tracking

NmsBroadLogMsgThis table matches the nms:broadLogMsg schema.It is an extension of the delivery log table.

General information


-Primary keylongiBroadLogMsgId

-Message MD5stringsMd5

-TextstringsText

-First addressstringsFirstAddress

-First textstringsFirstText

0-Not defined

1-Soft

2-Hard

3-Ignored

Failure typebyteiFailureType

28 | © Neolane 2013

Neolane


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

ReasonbyteiFailureReason

0-To qualify

1-Keep

2-Ignore

Qualification statusbyteiQualifStatus

Table keys


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

longiRuleId

Time fields




Neolane datamodel



Simulation and delivery

30 | © Neolane 2013

Neolane

Communication consistency and capacity rules

NmsTypologyRuleThis table matches the nms:typologyRule schema.It contains the rules which apply to deliveries depending on typologies.

General information


-Primary keylongiTypologyRuleId


-LabelstringsLabel

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-All channels


-ActivebooleaniActive

-Application built-in rulebooleaniBuiltIn

-Filtering

-Control

Rule typestringsRuleType


Neolane datamodel


-At the start of targeting

-After targeting

-At the start of personalization

-At the end of the analysis

PhasestringsRuleStep

-Execution orderlongiOrder

-Re-apply the rule at the start of personal-ization

booleaniForceOnPrepareMessage

-FrequencytimespandValidity

Table keys




-Foreign key of link 'Rule folder' (field 'id')longiFolderId

Time fields




NmsTypologyThis table matches the nms:typology schema.It contains the set of rules to be applied to deliveries which match the typology.

General information


-Primary keylongiTypologyId


-LabelstringsLabel

0-Standard

1-Filtering

TypebyteiType

-IP affinitystringsIPAffinity

Table keys





Time fields



32 | © Neolane 2013

Neolane



NmsTypologyRuleRelThis table matches the nms:typologyRuleRel schema.It contains the relationships between typologies and their rules.

Table keys


-Foreign key of link 'Typology' (field 'id')longiTypologyId

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

longiRuleId

Response management


Neolane datamodel

Campaign management

NmsOperationThis table matches the nms:operation schema. It contains the data of marketing campaigns.

General information


-Primary keylongiOperationId

-LabelstringsLabel


-Application built-in modelbooleaniBuiltIn

-ModelbooleaniIsModel

0-Not defined

3-Cancel in progress

4-Canceled

Cancel statusbyteiCancelState

0-Unique

1-Recurring

2-Periodic

Campaign typebyteiType

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)

Main channelbyteiMessageType

-Campaign durationtimespandDuration

-Created in advance fortimespandPeriodCovered

34 | © Neolane 2013

Neolane



0-Low

1-Average

2-High

PrioritybyteiPriority



0-Planned

1-Reserved

2-Committed





0-Not defined


2-Being calculated



0-Being edited

1-Defined

2-Carried out

Process statusbyteiBudgetStatus

-Fixed costdoubledFixedCost

-Expenses and objectivesbooleaniUseBudget

-TasksbooleaniUseTask

-Enable budget approvalbooleaniUseBudgetValidation

-Enable target approvalbooleaniUseTargetValidation

-Enable content approvalbooleaniUseContentValidation

-Enable extraction validationbooleaniUseExtractionValidation

-Enable the sending and validation of proofsbyteiUseFCPValidation

-Enable the automatic creation of approvaltasks

booleaniUseTaskCreation

-Enable validation for associated deliveriesbooleaniUseLinkedDeliveryValida-tion

-Do not enable notification sendingbooleaniDisableNotification

0-Automatic

1-Manual

Approval modebyteiValidationMode

0-Target estimation and message person-alization

1-Estimation and approval of the provision-al target

2-Target evaluation

Delivery modebyteiSandboxMode

-Assign content editingbooleaniAssignEdition

-External content approvalbooleaniExternalValidation

Table keys




-Foreign key of link 'Assigned to' (field 'id')longiOwnerId

-Foreign key of link 'Charge' (field 'id')longiBudgetId

-Foreign key of link 'Linked campaign' (field'id')

longiLinkedOperationId


Neolane datamodel


-Foreign key of link 'Program' (field 'id')longiProgramId

-Foreign key of link 'Execution program'(field 'id')

longiProgramProcessId

-Foreign key of link 'Proof group' (field 'id')longiFcpGroupId

Time fields





-StartdatetsStart

-EnddatetsEnd

NmsDeliveryOutlineThis table matches the nms:deliveryOutline schema. It contains the extended properties of the delivery(delivery outline).

General information


-Primary keylongiDeliveryOutlineId


-LabelstringsLabel

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-All channels



Table keys



NmsDlvOutlineItemThis table matches the nms:dlvOutlineItem schema. It contains the articles of a delivery outline.

General information


-Primary keylongiDlvOutlineItemId

36 | © Neolane 2013

Neolane



-LabelstringsLabel

0-Item

1-Personalization fields

2-Resource

3-Offer

TypebyteiType

Table keys


-Foreign key of link 'Marketing resource'(field 'id')

longiAssetId

-Foreign key of link 'Marketing offer' (field'id')

longiOfferId



NmsDeliveryCustomizationThis table matches the nms:deliveryCustomization schema. It contains the personalization fields of adelivery.

General information


-Primary keylongiDeliveryCustomizationId


-LabelstringsLabel


6-Text

3-Integer

5-Floating point

7-Date+Time

TypebyteiType

-ValuestringsValue

Table keys


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

longiDlvOutlineItemId




NmsBudgetThis table matches the nms:budget schema. It contains the data of a budget on a campaign, a plan, aprogram, a task and/or deliveries.


Neolane datamodel

General information


-Primary keylongiBudgetId


-LabelstringsLabel

-AllocateddoubledAllocated

-SpentdoubledExpensed

-InvoiceddoubledInvoiced

-ReserveddoubledReserved

-PlanneddoubledPlanned

-CommitteddoubledCommitted

Table keys




-Foreign key of link 'Currency' (field 'id')longiCurrencyId

-Foreign key of link 'Related budget' (field'id')

longiAttachedBudgetId


Time fields


-StartdatetsStart

-EnddatetsEnd



NmsDocumentThis table matches the nms:document schema. It contains the marketing documents of the campaign inthe form of files (images, excel or word files, etc.)

General information


-Primary keylongiDocumentId


-LabelstringsLabel

-Document naturestringsNature

-Original namestringsOriginalName

-Content-TypestringsContentType

38 | © Neolane 2013

Neolane


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

Storage typebyteiStorageType

-File namestringsFileName

-Server namestringsOriginalServer

-MD5 keystringsMd5

-Unique file namebooleaniUseMd5AsFilename

-Document versionstringsVersion

-WidthlongiWidth

-HeightlongiHeight

-Substitute textstringsAlt

-Publish filebooleaniPublish

0-File

1-HTML

2-Text

5-URL

6-Content Management

Resource typebyteiResourceType

Table keys



-Foreign key of link 'Delivery (attachments)'(field 'id')

longiContainerId




-Foreign key of link 'Plan' (field 'id')longiPlanId

-Foreign key of link 'Delivery' (field 'id')longiDeliveryId

-Foreign key of link 'Task' (field 'id')longiTaskId

-Foreign key of link 'Content' (field 'id')longiContentId

-Foreign key of link 'Discussion forum' (field'id')

longiNewsgroupId

Time fields




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


Neolane datamodel

General information


-Primary keylongiWorkflowId


-LabelstringsLabel

-Time zonestringsTimezone

-Execute inside the enginebooleaniInProcess

-History in dayslongiHistory

0-Suspend the process

1-Ignore

In case of errorbyteiOnError

-Consecutive errorslongiErrorLimit



-List+Detail formstringsForm

-Affinity of the next taskstringsNextProcessingAfn

-Next processing hoststringsNextProcessingHost

0-Not started

1-In progress

3-Suspended

4-Stop in progress

5-Finished

Real statusbyteiStatus

-ProductionbooleaniProduction

-FailedbooleaniFailed

-Unlocked countlongiUnlockedCount

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

StatebyteiState

-Process (PID)longiProcessId

-Execution serverstringsHostname

-PortlongiPort

0-Not defined

1-Pending start

Start statebyteiStartState

0-Low

1-Average

2-High




-OrderlongiOrder

40 | © Neolane 2013

Neolane


-Recurring workflow templatebooleaniRecurrentMdl

Table keys




-Foreign key of link 'Supervisor(s)' (field'id')

longiSupervisorId


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



-Foreign key of link 'Routing campaign'(field 'id')

longiRoutingOperationId

-Foreign key of link 'Aggregate' (field 'id')longiAggregateId

Time fields




-Last startdatetimetsLastStart

-Next processingdatetimetsNextProcessing

-Last processingdatetimetsProcess

-Expiration datedatetimetsExpiration

NmsTaskThis table matches the nms:task schema. It contains the definition of a marketing task.

General information


-Primary keylongiTaskId



-LabelstringsLabel

0-Being edited

1-Scheduled

2-In progress

3-Finished

4-Canceled

5-Pending approval

6-Finished

7-Rejected

StatebyteiStatus

0-Task

1-Checkpoint

2-Grouping task

3-Notification

4-Marketing resources

TypebyteiType


Neolane datamodel



-Progress (as a %)longiProgress

3-Very High

2-High

1-Normal

0-Low


0-Target validation

1-Content validation

2-Budget validation

3-Approval of extraction file

4-Proof validation

5-Approval of inclusion in the provisionalcalendar

6-Available content

7-External content approval

Approval typebyteiValidationType

0-Not defined

1-Approved

2-Rejected

Approval statusbyteiValidationState

-StarttimespandStartDelay

-DurationtimespandDuration

-ExecutiontimespandExecutionDelay

-From the campaign end datebooleaniFromOperationEndDate

-Workload performedtimespandRealizedDuration

-Workload plannedtimespandPlannedDuration



-enable task approvalbooleaniUseTaskValidation

-Initial notificationtimespandInitialDelay

-Publish the marketing resourcebooleaniUseAssetPublication

0-Planned

1-Reserved

2-Committed





0-Not defined


2-Being calculated



-Unit revenuedoubledUnitaryCost

Table keys





-Foreign key of link 'Warning group' (field'id')

longiAlertAssigneeId

-Foreign key of link 'Charge' (field 'id')longiBudgetId


42 | © Neolane 2013

Neolane



-Foreign key of link 'Service' (field 'id')longiSupplierModelId

-Foreign key of link 'Depends on' (field 'id')longiDependingTaskId

-Foreign key of link 'Linked to' (field 'id')longiLinkedTaskId


-Foreign key of link 'Marketing resource'(field 'id')

longiAssetId


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


-Foreign key of link 'Program' (field 'id')longiProgramId

Time fields




-StartdatetimetsStart

-EnddatetimetsEnd

-Execution datedatetimetsExecution

-End of executiondatetimetsCompleted

-Reminder datedatetimetsReminder

-Initial notification datedatetimetsInitial

-Executed initial notification datedatetimetsInitialExecution

-Executed warning notification datedatetimetsAlertExecution


-Approval deadlinedatetsExpectedValidation

NmsAssetThis table matches the nms:asset schema. It contains the definition of a marketing resource.

General information


-Primary keylongiAssetId


-LabelstringsLabel

-Document naturestringsNature

-Original namestringsOriginalName

-Content-TypestringsContentType

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

Storage typebyteiStorageType


Neolane datamodel


-File namestringsFileName

-Server namestringsOriginalServer

-MD5 keystringsMd5

-Unique file namebooleaniUseMd5AsFilename

-Document versionstringsVersion

-WidthlongiWidth

-HeightlongiHeight

-Substitute textstringsAlt

-Publish filebooleaniPublish



0-File

1-HTML

2-Text

5-URL

6-Content Management

Resource typebyteiResourceType

0-Being edited

1-Pending approval

2-Approval in progress

3-Approved

4-Rejected

5-Pending publication

6-Publication in progress

7-Published

8-Cancelled

StatebyteiStatus

0-Not defined

1-French

2-English

3-German

LanguagebyteiLanguage

Table keys



-Foreign key of link 'Delivery (attachments)'(field 'id')

longiContainerId





-Foreign key of link 'Owner' (field 'id')longiEditedById


-Foreign key of link 'Proof reader' (field 'id')longiProofReaderId

-Foreign key of link 'Post-processing' (field'id')

longiWorkflowId

Time fields




44 | © Neolane 2013

Neolane


-Publication datedatetimetsPublication

-Check-out datedatetimetsCheckOut

-Planned check-in datedatetimetsExpectedCheckIn

-Availability datedatetsAvailability

-Expiry datedatetsExpiration

-Approval deadlinedatetsExpectedValidation

-Publication deadlinedatetsExpectedPublication

-Reminder datedatetsReminder

Interaction Module

NmsOfferThis table matches the nms:offer schema.It contains the definition of each marketing offer.

General information


-Primary keylongiOfferId


-LabelstringsLabel

0-Being edited

1-Pending approval


3-Approved

4-Refused

5-Disabled

6-Online

7-Pending deployment

Eligibility statusbyteiEligibilityStatus

0-Being edited

1-Pending approval


3-Approved

4-Refused

5-Disabled

6-Online

7-Pending deployment

Content statusbyteiContentStatus

-Offer codestringsCode


-Native application offerbooleaniBuiltIn

-Targeting dimensionstringsTargetSchema

Table keys






Neolane datamodel


-Foreign key of link 'Category' (field 'id')longiCategoryId

Time fields




-Date on which eligibility was approveddatetimetsEligibilityValidation

-Content approval datedatetimetsContentValidation

-Start datedatetimetsStart

-End datedatetimetsEnd

-Deployment datedatetimetsProduction

-Eligibility approval deadlinedatetsExpectedEligibility

-Reminder datedatetsReminderEligibility

-Content approval deadlinedatetsExpectedContent

-Reminder datedatetsReminderContent

NmsPropositionRcpThis table matches the nms:propositionRcp schema.It contains the cross-channel log of marketing propositions sent to each individual. The record is createdwhen a proposition is prepared or effectively made to an individual.

General information


-Primary keylongiPropositionId

-Interaction IDlongiInteractionId

-WeightdoubledWeight

-RankingbyteiRank

0-Generated

1-Presented

2-Interested

3-Accepted

4-Scheduled

5-Rejected

99-Control group

StatusbyteiStatus

0-Batch engine

1-Unitary engine

Engine typebyteiEngineType

Table keys


-Foreign key of link 'Offer' (field 'id')longiOfferId

-Foreign key of link 'Offer space' (field 'id')longiOfferSpaceId


46 | © Neolane 2013

Neolane



Time fields


-Event datedatetimetsEvent


NmsOfferSpaceThis table matches the nms:offerSpace schema.It contains the definition of locations on which propositions are made.

General information


-Primary keylongiOfferSpaceId


-LabelstringsLabel

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

ChannelbyteiChannel

0-Generated

1-Presented

2-Interested

3-Accepted

4-Scheduled

5-Rejected

99-Control group

Default statusbyteiDefaultStatus

0-Generated

1-Presented

2-Interested

3-Accepted

4-Scheduled

5-Rejected

99-Control group

Default value of the status when acceptedbyteiDefaultUpdateStatus

-Disable the inserting of propositionsbooleaniDisablePropositionStorage

-Randomly display alternative contentstringsRandomizeAlternativeCon-tents

-Overload the target data load scriptbooleaniUseTargetScript

-Overload the proposition selection scriptbooleaniUseBuildPropositionsScript

-Overload the XML rendering functionbooleaniUseXmlFunction

-Overload the HTML rendering functionbooleaniUseHtmlFunction


Neolane datamodel


-Overload the text rendering functionbooleaniUseTextFunction

Table keys


-Foreign key of link 'Environment' (field 'id')longiEnvId




Time fields




-Deployment datedatetimetsDeployment

NmsOfferViewThis table matches the nms:offerView. It contains the offer representations.

General information


-Primary keylongiOfferViewId

0-Being edited

1-Pending approval

3-Approved

4-Refused

5-Disabled

6-Online

StatebyteiStatus

Table keys




-Foreign key of link 'Offer' (field 'id')longiOfferId

-Foreign key of link 'Offer space' (field 'id')longiSpaceId

Time fields


-Publication datedatetimetsPublication


48 | © Neolane 2013

Neolane



NmsOfferCategoryThis table matches the nms:offerCategory. It contains the offer categories.

General information




-LabelstringsLabel










Table keys








longiOrgUnitId


-Foreign key of link 'Environment' (field 'id')longiEnvId

Time fields




-Production deployment datedatetimetsProduction

NmsOfferEnvThis table matches the nms:offerEnv. It contains the offer environments.


Neolane datamodel

General information




-LabelstringsLabel










-LivebooleaniLive

-Call data schemastringsInputSchema

Table keys








longiOrgUnitId


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

longiProdEnvId

Time fields



50 | © Neolane 2013

Neolane



Message Center Module

NmsRtEvent

Figure 1.1.

This table matches the nms:rtEvent schema.It contains a definition of real time events.

General information


-Primary keylongiRtEventId

0-Pending

1-Pending delivery

2-Sent

11-Ignored by the delivery

12-Delivery error

13-Event not covered

StatusbyteiStatus

-Number of errorsbyteiRetry


-Event typestringsType

0-Email

1-Mobile (SMS)

2-Phone

3-Direct Mail

4-Fax

20-Facebook

25-Twitter

41-iOS channel

42-Android channel

120-Other

ChannelbyteiWishedChannel


Neolane datamodel




-EmailstringsEmail

0-Unknown

1-Text

2-HTML

Email formatbyteiEmailFormat

-Mobile numberstringsMobilePhone

-Registration tokenstringsRegistrationToken

-Line 1stringsLine1

-Line 2stringsLine2

-Line 3stringsLine3

-Line 4stringsLine4

-Line 5stringsLine5

-Line 6stringsLine6

-Line 7stringsLine7



2-2 - Empty street







Table keys


-Foreign key of link 'Template' (field 'id')longiDeliveryId

-Foreign key of link 'Mobile application'(field 'id')

longiMobileAppId



Time fields


-Submitted ondatetimetsSubmit

-Process requested ondatetimetsScheduled

-Expired ondatetimetsExpiration

-Created ondatetimetsCreated

-Process started ondatetimetsProcessing

-Processed ondatetimetsProcessed

-Modified ondatetimetsLastModified

52 | © Neolane 2013

Neolane



NmsBatchEvent

Figure 1.2.

This table matches the nms:batchEvent schema.It contains the definition of events by batch.

General information


-Primary keylongiBatchEventId

0-Pending

1-Pending delivery

2-Sent

11-Ignored by the delivery

12-Delivery error

13-Event not covered

StatusbyteiStatus

-Number of errorsbyteiRetry


-Event typestringsType

0-Email

1-Mobile (SMS)

2-Phone

3-Direct Mail

4-Fax

20-Facebook

25-Twitter

41-iOS channel

42-Android channel

120-Other

ChannelbyteiWishedChannel




Neolane datamodel


-EmailstringsEmail

0-Unknown

1-Text

2-HTML

Email formatbyteiEmailFormat

-Mobile numberstringsMobilePhone


-Line 1stringsLine1

-Line 2stringsLine2

-Line 3stringsLine3

-Line 4stringsLine4

-Line 5stringsLine5

-Line 6stringsLine6

-Line 7stringsLine7



2-2 - Empty street







Table keys


-Foreign key of link 'Template' (field 'id')longiDeliveryId


longiMobileAppId



Time fields


-Submitted ondatetimetsSubmit

-Process requested ondatetimetsScheduled

-Expired ondatetimetsExpiration

-Created ondatetimetsCreated

-Process started ondatetimetsProcessing

-Processed ondatetimetsProcessed

-Modified ondatetimetsLastModified

54 | © Neolane 2013

Neolane



Social Marketing Module

NmsVisitorThis table matches the nms:visitor schema. It contains the information on visitors.

General information


-Primary keylongiVisitorId

-NamestringsLastName

-First namestringsFirstName

-EmailstringsEmail

-Identifier of the last deliverylongiDeliveryId

-Recipient identifierlongiRecipientId

-Referrer identifierlongiReferrerId

-Referrer last namestringsReferrerLastName

-Referrer first namestringsReferrerFirstName

-Referrer emailstringsReferrerEmail

-Forward urlstringsForwardUrl

-External IDstringsExternalId

0-Undefined

2-Facebook

3-Twitter

OriginbyteiOrigin

-UsernamestringsScreenName

-Full namestringsName

-ImagestringsPicture

-Time zonestringsTimezone


Neolane datamodel


-LanguagestringsLang

0-None specified

1-Male

2-Female

GenderbyteiGender

-LocationstringsLocation

-Number of friendslongiFriendCount


-CheckedbooleaniVerified

-Sign in country codestringsSignInCountryCode

Table keys


-Foreign key of link 'Web application' (field'id')

longiWebAppId


Time fields




-Token expiration datedatetimetsTokenExpiration

-Last synchronized ondatetimetsLastSynchronized

-Birth datedatetsBirth

NmsVisitorSubThis table matches the nms:visitorSub schema. It enables you to link up a visitor to the services whichthey have subscribed to (Twitter or Facebook).

Table keys


-Foreign key of link 'Visitor' (field 'id')longiVisitorId


Time fields


-Subscription datedatetimetsCreated

NmsFriendShipRelThis table matches the nms:friendshipRel schema. It enables you to link up visitors with their friendswithin the context of the Facebook service.

56 | © Neolane 2013

Neolane

Table keys


-Foreign key of link 'Visitor' (field 'id')longiFriendOfId

-Foreign key of link 'Friend' (field 'id')longiFriendId

NmsVisitorInterestRelThis table matches the nms:visitorInterestRel schema. It enables you to link up visitors and their interests.

General information


-Primary keylongiVisitorInterestRelId


0-Uses

1-Likes

2-Listens to

3-Watches

4-Reads

5-Checks in

6-Visits

7-Installs

8-Comments

9-Liked deliveries

ActivitybyteiActionType


-Number of LikeslongiCountLikes

-Number of commentslongiCountComments

Table keys


-Foreign key of link 'Visitor' (field 'id')longiVisitorId

-Foreign key of link 'Main interests' (field'id')

longiInterestId

-Foreign key of link 'Provided by' (field 'id')longiMadeById



Time fields




-Start datedatetimetsStartTime

-End datedatetimetsEndTime

-Publication datedatetimetsPublishTime

NmsInterestThis table matches the nms:interest schema. It contains the list of interests for each visitor.


Neolane datamodel

General information


-Primary keylongiInterestId

-External IDstringsExternalId

0-Undefined

2-Facebook

3-Twitter

OriginbyteiOrigin

-LabelstringsLabel


-urlstringsUrl

Microsites Module

NmsTrackingUrlThis table matches the nms:trackingUrl schema.

General information


-Primary keylongiTrackingUrlId

-IdentifierstringsTagId

-Source URLstringsSource

-Occurrence indexshortiOccurrence

-LabelstringsLabel


-CRC32longiChecksum

-CustomizablebooleaniWithParams

58 | © Neolane 2013

Neolane


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

TypebyteiType

-StagebyteiStep

-ObjectivestringsGoal

-Name of the trackerstringsTrackerName

Table keys



-Foreign key of link 'Tag folder' (field 'id')longiFolderId

-Foreign key of link 'pURL' (field 'id')longiPurlId

Time fields


-Validity limitdatetsValidity

NmsPurlThis table matches the nms:purl schema.

General information


-Primary keylongiPurlId


-LabelstringsLabel

-Native pURL templatebooleaniBuiltIn


-Case sensitivebooleaniIsCaseSensitive

-Domain namestringsDomain

-Sub-domain namestringsSubDomain

-Site namestringsPath

-URL formatstringsUrlTemplate

-Recipient schemastringsSchema

-Guest ID personalizationstringsGuestIdExpr

-Guest code personalizationstringsGuestCodeExpr

-Expiration date of the pURL CodetimespandValidityDuration


Neolane datamodel



-URLstringsUrl

0-Non-secure (http)

1-Secure (https)

2-Secure and non-secure

ProtocolbyteiProtocol

Table keys







-Foreign key of link 'Microsite' (field 'id')longiWebAppId

-Foreign key of link 'Traffic source' (field'id')

longiOriginId

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

longiModelId

Time fields




NMAC Module

NmsMobileAppThis table matches the nms:mobileApp schema. It contains the mobile applications defined in Neolane.

General information


-Primary keylongiMobileAppId

-Integration keystringsUuid

-LabelstringsLabel

-Application iconstringsImg

0-Apple ®

1-Android ®

Target platformbyteiPushPlatform

-PasswordstringsPassword

-Project keystringsSenderId

60 | © Neolane 2013

Neolane


-DevelopmentbooleaniSandbox

Table keys


-Foreign key of link 'service' (field 'id')longiServiceId

NmsAppSubscriptionRcpThis table matches the nms:appSubscriptionRcp schema. It enables you to link up visitors who subscribedto an application with the recipients table.

General information


-Primary keylongiAppSubscriptionRcpId


-User IDstringsUserKey

-DisabledbooleaniDisabled

-IDstringsDeviceId

-NamestringsDeviceName

-NamestringsSystemName

-TemplatestringsDeviceModel

-BrandstringsDeviceBrand

-ConstructorstringsDeviceManufacturer

-VersionstringsSystemVersion

-LanguagestringsSystemLanguage

-LatitudedoubledLatitude

-LongitudedoubledLongitude

-AltitudedoubledAltitude

Table keys





longiMobileAppId



Time fields


-Registration datedatetimetsRegistration

-De-activation datedatetimetsDisabled

-Last saveddatetimetsLastUpdate



Neolane datamodel



NmsExcludeLogAppSubRcpThis table matches the nms:excludeLogAppSubRcp schema.

General information


-Primary keylongiBroadLogId

-AddressstringsAddress

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

StatusbyteiStatus

-Extended message flagsbyteiFlags

Table keys


-Foreign key of link 'Message' (field 'id')longiMsgId


-Foreign key of link 'Subscriber applications'(field 'id')

longiAppSubscriptionId


Time fields




NmsTrackingLogAppSubRcpThis table matches the nms:trackingLogAppSubRcp schema.

General information


-Primary keylongiTrackingLogId

-Requester UUIDstringsSourceId

-Requester typestringsSourceType

-BrowserlongiUserAgent

62 | © Neolane 2013

Neolane


-External IdstringsExternalId

Table keys


-Foreign key of link 'Url' (field 'id')longiUrlId


-Foreign key of link 'Message' (field 'id')longiBroadLogId



-Foreign key of link 'Recipients' (field 'id')longiRecipientId

Time fields


-DatedatetimetsLog

NmsBroadLogAppSubRcpThis table matches the nms:broadLogAppSubRcp schema.

General information


-Primary keylongiBroadLogId

-AddressstringsAddress

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

StatusbyteiStatus

-Extended message flagsbyteiFlags

Table keys


-Foreign key of link 'Message' (field 'id')longiMsgId






Neolane datamodel


-Foreign key of link 'Recipients' (field 'id')longiRecipientId

Time fields




64 | © Neolane 2013

Neolane

Table of ContentsIntroduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66Syntax of schemas . . . . . . . . . . . . . . . . . . . . . . . . . 66Identification of a schema . . . . . . . . . . . . . . . . . . . . . . 67

Schema structure . . . . . . . . . . . . . . . . . . . . . . . . . . 68Description . . . . . . . . . . . . . . . . . . . . . . . . . . . 69Data types . . . . . . . . . . . . . . . . . . . . . . . . . . . 69Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70Collections . . . . . . . . . . . . . . . . . . . . . . . . . . . 73Referencing with XPath . . . . . . . . . . . . . . . . . . . . . . . 73Building a string via the compute string . . . . . . . . . . . . . . . . . 74

Database mapping . . . . . . . . . . . . . . . . . . . . . . . . . . 74Description . . . . . . . . . . . . . . . . . . . . . . . . . . . 75XML fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75Calculated fields . . . . . . . . . . . . . . . . . . . . . . . . . 76Indexed fields . . . . . . . . . . . . . . . . . . . . . . . . . . 76Management of keys . . . . . . . . . . . . . . . . . . . . . . . . 77Links: 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

CHAPTER 2

Schema Reference(xtk:srcSchema)

Introduction

This chapter describes how to configure extension schemas in order to extend the conceptual data modelof the Neolane database.

OverviewThe physical and logical structure of the data carried in the application is described in XML. It obeys a grammarspecific to Neolane, called a schema.A schema is an XML document associated with a database table. It defines data structure and describes theSQL 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 schemasThe 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

Neolane

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 thenames of the attributes in the <element> tags which they have been linked to.

Identification of a schemaA 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 usedfor customer-specific configuration (customers).

Warning:

As a standard, the name of the namespace must be concise and must contain only authorized characters inaccordance 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 theNeolane 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.


Schema Reference (xtk:srcSchema)

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 andnamespace 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="[email protected]" created="2009/03/12" gender="1"> <location city="London"/></recipient>

With its corresponding data schema:

<srcSchema name="recipient" namespace="cus"> <element name="recipient"> <attribute name="email"/> <attribute name="created"/> <attribute name="gender"/> <element name="location"> <attribute name="city"/> </element> </element></srcSchema>

68 | © Neolane 2013

Neolane

DescriptionThe point of entry of the schema is its main element. It is easy to identify because it has the same name asthe schema, and it should be the child of the root element. The description of the content begins with thiselement.In our example, the main element is represented by the following line:

<element name="recipient">

The elements <attribute> and <element> that follow the main element enable you to define the locationsand names of the data items in the XML structure.In our sample schema, these are:

<attribute name="email"/><attribute name="created"/><attribute name="gender"/><element name="location"> <attribute name="city"/></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 charactersin accordance with XML naming rules.

n Only <element> elements can contain <attribute> elements and <element> elements in the XMLstructure.

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 typesThe 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 childelements. If it does, it is used only to structure the elements hierarchically (<location> element in ourexample).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 numberof 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 andcompleted with its default value.

Here is our example schema with the types entered:



<srcSchema name="recipient" namespace="cus"> <element name="recipient"> <attribute name="email" type="string" length="80"/> <attribute name="created" type="datetime"/> <attribute name="gender" type="byte"/> <element name="location"> <attribute name="city" type="string" length="50"/> </element> </element></srcSchema>

Mapping the types of Neolane/DBMS dataThe table below lists the mappings for the types of data generated by Neolane for the different databasemanagement systems.

MS SQLDB2TeradataOraclePosgreSQLNeolane

VARCHAR(NVARCHAR if uni-code)

VARCHARVARCHAR (VARCHARCHARACTER SETUNICODE if Unicode)

VARCHAR2(NVARCHAR2 if uni-code)

VARCHAR(255)String

TINYINTSMALLINTNUMERIC(3)NUMBER(3)SMALLINTBoolean

TINYINTSMALLINTNUMERIC(3)NUMBER(3)SMALLINTByte

SMALLINTSMALLINTSMALLINTNUMBER(5)SMALLINTShort

FLOATDOUBLEFLOATFLOATDOUBLE PRECISIONDouble

INTINTEGERINTEGERNUMBER(10)INTEGERLong

BIGINTBIGINTNUMERIC(20)NUMBER(20)BIGINTInt64

DATETIMEDATETIMESTAMPDATEDATEDate

FLOATTIMETIMEFLOATTIMETime

DATETIMETIMESTAMPTIMESTAMPDATETIMESTAMPZDatetime

FLOATDOUBLEFLOATFLOATDOUBLE PRECISIONTimespan

TEXT (NTEXT if Uni-code)

CLOB(6M)CLOB (CLOB CHARAC-TER SET UNICODE ifUnicode)

CLOB (NCLOB if Uni-code)

TEXTMemo

IMAGEBLOB(4M)BLOBBLOBBLOBBlob

PropertiesThe <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 mainwindow.

70 | © Neolane 2013

Neolane

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 valuesThe 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 withXPath [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 theCounterValue function with a free counter name. The number returned is incremented by one at eachinsertion.

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 viathis 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 inadvance.The enum attribute refers to the definition of an enumeration class populated in the schema outside themain element.Enumerations allow the user to select a value from a drop-down list instead of entering the value in a regularinput field:



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 enumproperty.However, the name attribute does not store the value internally, it stores a code which lets you extendthe 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.

ExampleHere is our example schema with the properties filled in:

<srcSchema name="recipient" namespace="cus"> <enumeration name="gender" basetype="byte"> <value name="unknown" label="Not specified" value="0"/> <value name="male" label="male" value="1"/> <value name="female" label="female" value="2"/> </enumeration>

<element name="recipient"> <attribute name="email" type="string" length="80" label="Email" desc="Email of

72 | © Neolane 2013

Neolane

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>

CollectionsA 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 XPathThe 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 andcontains the value "test1"

Note:

An additional constraint is added when the path crosses a sub-element. In this case, the following expressionmust 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 addedto 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.



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 stringA Compute string is an XPath expression used to construct a string representing a record in a table associatedwith the schema. Compute string is mainly used in the graphical interface to display the label of a selectedrecord.The Compute string is defined via the <compute-string> element under the main element of the dataschema. An expr attribute contains an XPath expression to calculate the display.Example: compute string of the recipient table.

<srcSchema name="recipient" namespace="nms"> <element name="recipient"> <compute-string expr="@lastName + ' ' + @firstName +' (' + @email + ')' "/> ... </element></srcSchema>

Result of the computed string for a recipient: Doe John ([email protected])

Note:

If the schema does not contain a Compute string, a Compute string is populated by default with the valuesof 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

Neolane

userEnum="city"/> </element> </element></schema>

DescriptionThe 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, simplyreferred 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 nameIn our example, the name of the table is entered via the main element of the schema in the sqltableattribute:

<element name="recipient" sqltable="CusRecipient">

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" sqlname="sEmail" type="string"/>

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 fieldsBy default, any typed <attribute> and <element> element is mapped onto an SQL field of the dataschema table. You can, however, reference this field in XML instead of SQL, which means that the data isstored in a memo field ("mData") of the table containing the values of all XML fields. The storage of thesedata 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 checkin the Neolane client interface.



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 fieldsper table, etc.).The main disadvantage is that it is impossible to index or filter an XML field.

Calculated fieldsA calculated field is not stored physically in the table; it is a data item that is calculated dynamically whenthe 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. Thistype of field is well suited to extracting a substring in order to display the domain of an e-mail addressor 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. Thissyntax must be used with care, however, because the populated SQL depends on the engine of thecurrent database.

2 XML calculated field: lets you use a more complex expression with XML fields or conditional tests. Theexpression 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 expressionsare 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 thevalue 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 fieldsIndexes 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"/> <keyfield xpath="xpath_of_field2"/> ...</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

Neolane

Note:

Indexes are created automatically during table mapping (standard or FDA).

Example:

n Adding an index to the e-mail address and city:

<srcSchema name="recipient" namespace="cus"> <element name="recipient"> <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 name="location" label="Location"> <attribute name="city" type="string" length="50" label="City" userEnum="city"/> </element> </element></srcSchema>

n Adding a unique index to the "id" name field:

<srcSchema name="recipient" namespace="cus"> <element name="recipient"> <dbindex name="id" unique="true"> <keyfield xpath="@id"/> </dbindex>

<dbindex name="email"> <keyfield xpath="@email"/> </dbindex>

<attribute name="id" type="long" label="Identifier"/> <attribute name="email" type="string" length="80" label="Email" desc="E-mail address of recipient"/> </element></srcSchema>

Management of keysA 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"> <keyfield xpath="xpath_of_field1"/> <keyfield xpath="xpath_of_field2"/> ...</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 containsthe 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 beprevented 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 beendefined.



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:

<srcSchema name="recipient" namespace="cus"> <element name="recipient"> <key name="email"> <keyfield xpath="@email"/> <keyfield xpath="location/@city"/> </key>

<attribute name="email" type="string" length="80" label="Email" desc="E-mail address of recipient"/> <element name="location" label="Location"> <attribute name="city" type="string" length="50" label="City" userEnum="city"/> </element> </element></srcSchema>

The schema generated:

<schema mappingType="sql" name="recipient" namespace="cus" xtkschema="xtk:schema"> <element name="recipient" sqltable="CusRecipient"> <dbindex name="email" unique="true"> <keyfield xpath="@email"/> <keyfield xpath="location/@city"/> </dbindex>

<key name="email"> <keyfield xpath="@email"/> <keyfield xpath="location/@city"/> </key>

<attribute desc="E-mail address of recipient" label="Email" length="80" name="email" sqlname="sEmail" type="string"/> <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:

<srcSchema name="recipient" namespace="cus"> <element name="recipient"> <key name="id" internal="true"> <keyfield xpath="@id"/> </key>

<key name="email" noDbIndex="true"> <keyfield xpath="@email"/> </key>

<attribute name="id" type="long" label="Identifier"/> <attribute name="email" type="string" length="80" label="Email" desc="E-mail address of recipient"/> </element></srcSchema>


<schema mappingType="sql" name="recipient" namespace="cus" xtkschema="xtk:schema"> <element name="recipient" sqltable="CusRecipient"> <key name="email"> <keyfield xpath="@email"/> </key>

78 | © Neolane 2013

Neolane

<dbindex name="id" unique="true"> <keyfield xpath="@id"/> </dbindex>

<key internal="true" name="id"> <keyfield xpath="@id"/> </key>

<attribute label="Identifier" name="id" sqlname="iRecipientId" type="long"/> <attribute desc="E-mail address of recipient" label="Email" length="80" name="email" sqlname="sEmail" type="string"/> </element></schema>

Auto-incremental keyThe primary key of most Neolane tables is a 32-bit long integer auto-generated by the database engine. Thecalculation of the key value depends on a sequence (by default, the XtkNewId SQL function) generating anumber that is unique in the entire database. The content of the key is automatically entered on insertionof the record.The advantage of an incremental key is that it provides a non-modifiable technical key for the joins betweentables. 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 usedwith the pkSequence attribute. If this attribute is not given in the source schema, the XtkNewId defaultsequence will be used. The application uses dedicated sequences for the nms:broadLog andnms:trackingLog schemas (NmsBroadLogId and NmsTrackingLogId respectively) because these arethe tables that contain the most records.

Note:

A sequence referenced in a Neolane schema (NmsTrackingLogId for example) must be associated to aSQL function that returns the number of IDs in the parameters, separated by commas. This function mustbe called GetNewXXXIds, where XXX is the name of the sequence (GetNewNmsTrackingLogIds forexample). View the postgres-nms.sql, mssql-nms.sql or oracle-nms.sql files provided with the appliationin the datakit/nms/fra/sql/ directory to recover the example of a 'NmsTrackingLogId' sequence creationfor each database engine.

To declare a unique key, populate the autopk attribute (with value "true") on the main element of the dataschema.Example:Declaring an incremental key in the source schema:

<srcSchema name="recipient" namespace="cus"> <element name="recipient" autopk="true"> ... </element></srcSchema>


<schema mappingType="sql" name="recipient" namespace="cus" xtkschema="xtk:schema"> <element name="recipient" autopk="true" pkSequence="XtkNewId" sqltable="CusRecipient">



<attribute desc="Internal primary key" label="Primary key" name="id" sqlname="iRecipientId" type="long"/> </element></schema>



In addition to the definition of the key and its index, a numeric field called "id" has been added to the extendedschema 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 toavoid outer joins, which are not effective on volume tables. By default, all foreign keys are initialized withvalue 0 so that a result can always be returned on the join when the data item is not populated.

Links: relation between tablesA 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 ofthe target table.

n Cardinality 1-N: one occurrence of the source table can have several corresponding occurrences of thetarget table, but one occurrence of the target table can have at most one corresponding occurrence ofthe source table.

n Cardinality N-N: one occurrence of the source table can have several corresponding occurrences of thetarget 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 ofthe 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 targetoccurrence,

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 ofduplication),

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 upthe join (<join> element) need not be populated because they are automatically deduced by defaultusing 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 iscreated 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 inPostgreSQL).

80 | © Neolane 2013

Neolane

Note:

As a standard, links are the elements declared at the end of the schema.

Example 11-N relation to the "cus:company" schema table:

<srcSchema name="recipient" namespace="cus"> <element name="recipient"> ... <element label="Company" name="company" revIntegrity="define" revLabel="Contact" target="cus:company" type="link"/> </element></srcSchema>


<schema mappingType="sql" name="recipient" namespace="cus" xtkschema="xtk:schema"> <element name="recipient" sqltable="CusRecipient"> <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 associatedfield in the destination table, with the following naming convention: name of target schema followed by nameof 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 name="id" unique="true"> <keyfield xpath="@id"/> </dbindex> <key internal="true" name="id"> <keyfield xpath="@id"/> </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 thesource schema).



Example 2In this example, we will declare a link towards the "nms:address" schema table. The join is an outer join andis populated explicitly with the recipient's e-mail address and the "@address" field of the linked table("nms:address").

<srcSchema name="recipient" namespace="cus"> <element name="recipient"> ... <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 31-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 4Link 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 5In this example, we wish to create a key on a link ("company" to "cus:company" schema) with the xlinkattribute and a field of the ("email") table:

<srcSchema name="recipient" namespace="cus"> <element name="recipient"> <key name="companyEmail"> <keyfield xpath="@email"/> <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>


<schema mappingType="sql" name="recipient" namespace="cus" xtkschema="xtk:schema"> <element name="recipient" sqltable="CusRecipient"> <dbindex name="companyId"> <keyfield xpath="@company-id"/> </dbindex>

<dbindex name="companyEmail" unique="true"> <keyfield xpath="@email"/> <keyfield xpath="@company-id"/> </dbindex>

<key name="companyEmail"> <keyfield xpath="@email"/> <keyfield xpath="@company-id"/> </key>

<attribute desc="E-mail address of recipient" label="Email" length="80" name="email" sqlname="sEmail" type="string"/>

82 | © Neolane 2013

Neolane

<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. Someerrors 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 specifythe attribute in the schema and set its value to "true".

<attribute> element

Content modelattribute:==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 creationsequence 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 itor generating an error if it doesn't exist.

n "insertOrUpdate": update with insertion. This means that Neolane will update the element or createit if it doesn't exist.

n "insert": insertion. This means that Neolane will insert the element without checking whether it exists.



n "update": update. This means that Neolane will update the element or generate an error if it doesn'texist.

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 attributeon 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 betaken 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 youto increment a value (mostly IDs). (external use)

n belongsTo (string): takes the name and namespace of the table that shares the field, and populatesthe 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 XMLfield. 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 mustbe 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). Thisattribute receives an XTK expression.

n desc (string): lets you insert a description of the attribute. This description is displayed in the statusbar of the interface.

n edit (string): this attribute specifies the type of input which will be used in the form linked to theschema.

n enum (string): receives the name of the enumeration linked to the field. The enumeration can beinserted into the same schema or into a remote schema.

n expr (string): defines a field precalculation expression. This attribute receives an Xpath or an XTKexpression.

n feature (string): defines a characteristics field: These fields are used for extending the data in anexisting 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 thecharacteristic, and oà¹ multiple choice fields, where the characteristic is linked to a collection elementwhich 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", itlets 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 avoidnaming 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

Neolane

n localizable (boolean): if it is activated, this attribute tells the collection tool to recover the value ofthe "@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 valueof 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 byNeolane:

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 recordsin 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 ofthe "@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 internalfield 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 theinterface. 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, evenwhen 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 updatingthe 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 addedautomatically depending on the type of field.

n template (string): this attribute defines a reference to an <attribute> element shared by severalschemas. The definition is automatically copied into the current schema.

n translatedDefault (string): if a "@default" attribute is found, the "@translatedDefault" will enableyou to redefine an expression to match the one defined in @default, to be collected by the translationtool (internal use).

n translatedExpr (string): if an "@expr" attribute is present, the "@translatedExpr" attibute enablesyou 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 typeinto 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



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 of100 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 operatingmode 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 enumerationcan 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. Neolanecreates a Text type "mData" field for record storage. This means there is not filtering or sorting on thesefields.

ExamplesExample 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 isgreater 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

Neolane

<compute-string> element

Content modelcompute-string:==EMPTY

Attributes@expr

Parents<element>

ChildrenNone

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

Use and context of useWhen no <compute-string> is defined, a <compute-string> element is entered by default with the valuesof 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 ([email protected])":

<element name="recipient"><compute-string expr="@lastName + ' ' + @firstName +' (' + @email + ')'"/>...</element>



<condition> element

Content modelcondition:==EMPTY

Attributes

n @boolOperator (string)

n @enabledIf (string)

n @expr (string)

Parents<sysFilter>

ChildrenNone

DescriptionThis element lets you define a filtering condition.

Use and context of useOne <sysFiler> element can contain several filtering conditions.


n boolOperator (string): if several <conditions> are defined within the same <sysFilter> element, thisattribute 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

Neolane

<dbindex> element

Content modeldbindex:==keyfield

Attributes

n @_operation (string)

n @applicableIf (string)

n @label (string)

n @name (MNTOKEN)

n @unique (boolean)

Parents<element>

Children<keyfield>

DescriptionThis element lets you define an index linked to a table.

Use and context of useIt's possible to define several indexes. One index can reference one or more fields of the table. Indexdeclaration 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> mustbe 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 nameof the index. For example: Table name "Sample", Namespace "Cus", index name "MyIndex"-> name of theindex field during index creation querying: "CusSample_myIndex".








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 uniquenessof the index throughout its fields.

ExamplesCreation of an index on the "id" field. (the "@unique" attribute on the <dbindex> element triggers addingof the "UNIQUE" SQL key word when the index is created in the database (query)).

<element label="Sample" name="Sample"> <dbindex name="myIndex" label="My index on the ID field" unique="true" applicableIf="HasPackage('nms:social')"> <keyfield xpath="@id"/>



</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="@email"/> <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

Neolane

<element> element

Content modelelement:==(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>

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

Use and context of use-










n advanced (boolean): when this option is activated (@advanced="true"), it lets you hide the attributeon 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 attributereceives 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 guaranteesthat 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 mustbe 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 attributereceives an XTK expression.

n desc (string): lets you insert a description of the element. This description is displayed in the statusbar of the interface.

n displayAsField (boolean): if this attribute is activated, a "link" type <element> will be displayed as afield in the tree view of the schemas ("Structure" tab). This way, it's possible to display a link as a localfield and change it behavior during a query. When the element is found in the SELECT of a query, thevalue of the link target will be used. When the element is found in the WHERE of a query, the underlyingkey 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 beinserted 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. Itreceives 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 anexisting 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 thecharacteristic, and oà¹ multiple choice fields, where the characteristic is linked to a collection elementwhich 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", itlets 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

Neolane

n folderLink (string): this attribute receives the name of the link that lets you recover the files containingentities.

n folderModel (string): defines the type of folder which enables entity storage. This attribute is onlydefined if "@folderLink" is present.

n folderProcess (string): defines the link where entity model instances are stored. This attribute is onlydefined if "@folderLink" is present.

n fullLoad (boolean): this attribute forces the display of all records in a table during field selection in aform.

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 beimported to the application server.

n integrity (string): referential integrity of the occurrence of the source table towards the target table.Accessible values are:

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 ofthe "@label" attribute for translation (internal use).

n name (MNTOKEN): internal name of the element which matches the name of the table. The value ofthe "@name" attribute must be short, preferably in English and comply with naming constraints linkedto XML.When the schema is written to the database, prefixes are automatically added to the field name byNeolane.

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 thedefinition 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 declarationsequence in an XML collection element.

n pkSequence (string): receives the name of the sequence to be used for calculating an auto-incrementalkey. This attribute may only be used if an auto-incremental key is defined on the root element of theschema.

n pkgStatus (string): during package exports, values will be taken into account as a function of the valueof 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 internalfield 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 theinterface. 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 usedin a "link" type <element>.Possible values are:



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 theopposite link.

n revIntegrity (string): this attribute defines the integrity on the target schema. The same values asthe "@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 createdin 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 ifthe element has the xml="true" property.

n sqlname (string): name of the field during table creation. If "@sqlname" isn't specified, the value ofthe "@name" attribute is used by default. When writing the schema to the table, prefixes are addedautomatically depending on the type of field.

n sqltable (string): for the main element of the schema, this attribute overloads the name of the SQLtable 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 onthe 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. Thisattribute 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 enableyou to redefine an expression to match the one defined in @default, to be collected by the translationtool (internal use).

n translatedExpr (string): if a "@expr" attribute is found, the "@translatedExpr" attribute lets youredefine an expression matching the one defined in "@expr", and which will be collected by the translationtool (internal use).

n type (MNTOKEN): defines the type of data stored in the element.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

n html

n int64

n link

n long

n memo

n MNTOKEN

n money

94 | © Neolane 2013

Neolane

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 collectionelement for a 1-N cardinality.

n userEnum (string): receives the internal name of an "open" enumeration. Enumeration values can bedefined 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 TEXTtype "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.



<enumeration> element

Content modelenumeration:==(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>

DescriptionThis element enables us to define a value enumeration. An enumeration belongs to the schema which it isdefined in, but it is accessible via another schema.

Use and context of useEnumerations 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.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 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

Neolane

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

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 severalschemas. The definition is automatically copied into the current schema.

ExamplesExample of enumeration values whose values are stored in the database:


<element label="Sample" name="Sample"> <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="Téléphone" name="phone" value="1"/> <value label="Call Center" name="callcenter" value="2"/> </enumeration>



<help> element

Content modelhelp:==EMPTY

AttributesNone

Parents<srcSchema>, <element>, <attribute>, <enumeration>, <value>, <param>, <method>

ChildrenNone

DescriptionThis element lets you describe an <element> or <attribute> element. It may only contain text, and is storedin XML in the database.


Attribute descriptionThis element has no attributes.

Examples

<method name="CheckOperation" static="true" <helpchecks the validity of a campaign</help...</method

98 | © Neolane 2013

Neolane

<join> element

Content modeljoin:==EMPTY

Attributes

n @dstFilterExpr (string)

n @xpath-dst (string)

n @xpath-src (string)

Parents<element>

ChildrenNone

DescriptionLets you define the fields that create a join between SQL tables.

Use and context of useA <join> element can only be used if the parent <element> element is of 'link' type. This means that theparent 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. Theyneed 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 beplaced 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).

ExamplesLink 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 containthe 'EN' value:

<element name="StockFR" type="link" label="MyLink" target="cus:Stock" <join xpath-dst="@country" xpath-src="@code" dstFilterExpr="@country = 'FR'"/ </element



<key> element

Content modelkey:==keyfield

Attributes

n @allowEmptyPart (boolean)


n @internal (boolean)

n @label (string)

n @name (MNTOKEN)

n @noDbIndex (boolean)

Parents<element>

Children<keyfield>

DescriptionThis element lets you define a key for identifying a record in the table.A table must have at least one key.

Use and context of useAs 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 acomposite key to define a primary key.If the main element of the schema contains the "@autopk=true" attribute, the primary key is unique. Wecan 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 isconsidered 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 needto be entered.

n applicableIf (string): this attribute lets you make the key optional. It defines the condition accordingto 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 beindexed.

ExamplesDeclaration 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 SQLquery:

<key name="PrimaryKey" internal="true"> <keyfield xpath="@name"/>

100 | © Neolane 2013

Neolane

</key>

CREATE UNIQUE INDEX Schema_PrimaryKey ON Schema(sName);



<keyfield> element

Content modelkeyfield:==EMPTY

Attributes

n @xlink (MNTOKEN)

n @xpath (MNTOKEN)

Parents<key>,<dbindex>

ChildrenNone

DescriptionThis 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 receivesan Xpath which defines the path to the schema attribute that defines the key or the index.

ExamplesSelection of the "sName" field in an index with an Xpath on "@name":

<keyfield xpath="@name"/>

102 | © Neolane 2013

Neolane

<method> element

Content modelmethod:==( 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>

DescriptionThis element lets you define a SOAP method.

Use and context of useSOAP methods enable application processes.The "@library" is necessary for declaring a new method (non-native): the namespace and the name usedfor 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 methodlibrary 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 parametersmust be specified to the method when it is called up.



ExamplesDefinition 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

Neolane

<methods> element

Content modelmethods:==method

AttributesNone

Parents<srcSchema>

Childrenmethod

DescriptionThis 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



<param> element

Content modelparam:==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>

DescriptionThis 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> elementList of available types:

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

Neolane

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

ExamplesDefinition 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"/>



<parameters> element

Content modelparameters:==param

AttributesNone

Parents<method>

Children<param>

DescriptionThis element defines a group of <parameter> elements.

Use and context of useThis element is mandatory, even for a single <param> child element of the <method> element.

Attribute descriptionNone

Examples

<parameters... //definition of one or more <param</parameters

108 | © Neolane 2013

Neolane

<srcSchema> element

Content modelsrcSchema:==(attribute | createdBy | data | element | enumeration | help | interface | methods | modifiedBy)

Attributescreated (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)

ParentsNone

Children

n <attribute>

n <createdBy>

n <data>

n <element>

n <enumeration>

n <help>

n <interface>

n <methods>

n <modifiedBy>

Descriptionroot element of a schema

Use and context of useSchema 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. Ithas a "Date Time" form. The values displayed are taken from the server. The time is shown in UTCformat.

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 schemadeclared in the @xtkschema attribute.

n extendedSchema (string): receives the name of the out-of-the-box schema which the current schemaextension 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 UTCformat.

n library (boolean): use of the schema as a library and not an entity. This schema may therefore bereferenced 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.



n name (string): unique schema name.

n namespace (string): namespace of the schema (default: nms, xtk, nl). When creating a new schemafor a project, we recommend that you use a dedicated namespace.

n useRecycleBin (boolean): activates the trash feature in the application. Deleted records will be placedin 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 databasestructure update wizard will not take the schema into account. This option is mainly used for referencingexternal 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

Neolane

<sysFilter> element

Content modelsysFilter:==condition

Attributes-

Parents<element>

Children<condition>

DescriptionThis element lets you define a filter.



ExamplesDefinition of a filter with a condition on the @name attribute:

<sysFilter> <condition expr="@name ='Doe'"/> <sysFilter>



<value> element

Content modelvalue:==help

Attributes


n @desc (string)

n @enabledIf (string)

n @img (string)

n @label (string)

n @name (string)

n @value (string)

Parents<enumeration>

Children<help>

DescriptionThis 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 XTKexpression.

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 mustbe 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 ofenumeration. If the enumeration is of character string type, it may only contain character string typevalues.

Examples


112 | © Neolane 2013

Neolane

Table of ContentsEditing schemas . . . . . . . . . . . . . . . . . . . . . . . . . . 114

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 114Example: creating a contract table . . . . . . . . . . . . . . . . . . . 115

Schema of an existing table or a view . . . . . . . . . . . . . . . . . . . 118Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 118Implementation . . . . . . . . . . . . . . . . . . . . . . . . . 118Accessing an external database . . . . . . . . . . . . . . . . . . . . 119

Extending an existing schema . . . . . . . . . . . . . . . . . . . . . 121Protecting schemas . . . . . . . . . . . . . . . . . . . . . . . . . 122

System filters . . . . . . . . . . . . . . . . . . . . . . . . . . 122Protecting out-of-the-box schemas . . . . . . . . . . . . . . . . . . . 122Modifying system filters of out-of-the-box schemas . . . . . . . . . . . . . 123

Updating the physical structure of the database . . . . . . . . . . . . . . . 124New field wizard . . . . . . . . . . . . . . . . . . . . . . . . . . 125Schema structure . . . . . . . . . . . . . . . . . . . . . . . . . . 127Regenerating all schemas . . . . . . . . . . . . . . . . . . . . . . . 127Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127

Extending a table . . . . . . . . . . . . . . . . . . . . . . . . . 127Linked collection table . . . . . . . . . . . . . . . . . . . . . . . 128Extension table . . . . . . . . . . . . . . . . . . . . . . . . . 129Overflow table . . . . . . . . . . . . . . . . . . . . . . . . . . 130Relationship table . . . . . . . . . . . . . . . . . . . . . . . . . 131

This chapter details the configuration of extension schemas for extending the conceptual data modelof the Neolane database.

Neolane v6.1 - Configuration Guide - Editing and extending schemas | 113

CHAPTER 3

Editing and extendingschemas

Editing schemas

OverviewTo edit, create and configure the schemas, click the Administration>Configuration>Data schemasnode 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 editingzone of the schema.

114 | © Neolane 2013

Neolane

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 tableIn the following example, we want to create a new table for contracts in the database model of the Neolanedatabase. This table lets you store first and last names and email addresses of holders and co-holders, foreach contract.To do this, you need to create the schema of the table and update the database structure to generate thecorresponding 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.


Editing and extending schemas

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 toIdentification of a schema [page 67].

4 Create the content of the table. We recommend using the entry wizard to make sure no settings aremissing. 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

Neolane

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



Schema of an existing table or a view

OverviewWhen the application needs to access the data of an existing table, an SQL view, or data from a remotedatabase, 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.

ImplementationTo 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

Neolane

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 inorder 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"> <keyfield xpath="@email"/> </key> <attribute name="email" type="string" length="80" sqlname="email"/> </element></srcSchema>

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




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

Neolane

workflow-v6.1-en.pdf#nameddest=ASN-Access_an_external_DB

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 aredefined: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 canextend a table without needing to modify the original schema.The root element of the schema must contain the extendedSchema attribute with the name of theschema to be extended as its value.An extension schema does not have its own schema: the schema generated from the source schema willbe filled in with the fields of the extension schema.Example: extension of the nms:recipient schema.

<srcSchema extendedSchema="nms:recipient" name="recipient" namespace="cus"> <element name="recipient"> <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>



The dependingSchemas attribute on the root element of the schema references the dependences onthe 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 canlead to malfunctions in the use of Neolane.

Protecting schemas

System filtersSystem 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 shownin 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 namedadmin permission. This means that only administrators will have write permissions on entities describedby 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. Onlythe 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 schemasBy default, out-of-the-box schemas are only accessible with write permissions for operators with adminrights:

n ncm:publishing

n nl:monitoring

n nms:calendar

n xtk:builder

122 | © Neolane 2013

Neolane

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 accountof a Neolane instance.

Modifying system filters of out-of-the-box schemasYou can still modify the system filters of the out-of-the-box schemas which are by default protected due tocompatibility 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 elementto 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].



Updating the physical structure of the database

To apply the modifications made to the schemas, launch the database update wizard. This wizard is accessiblevia Tools>Advanced>Update database structure. It checks whether the physical structure of thedatabase 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 SQLscripts 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 enterthe XML file of the package.

124 | © Neolane 2013

Neolane

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 inthe database.Validating the wizard updates the extension schema of the table to be extended and launches the SQL scriptto 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 dataschema.The main disadvantage is the limitation of the data and the properties to be extended.



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 extensionschema 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 SQLscript is executed:

<srcSchema extendedSchema="nms:recipient" label="Recipients" name="recipient" namespace="cus"> <element name="recipient">

126 | © Neolane 2013

Neolane

<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 displayand edit the field in the input form of the extended schema using a "treeEdit"-type control (refer to Inputforms [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 Neolaneclient 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 structuringelements 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 thetable, 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 thefollowing 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 tableTo extend the nms:recipient schema recipient table, apply the following procedure:



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"/> <value label="Zone 2" name="area2"/> </enumeration>

<element name="extension"> <dbindex name="area"> <keyfield xpath="location/@area"/> </dbindex>

<attribute label="Loyalty code" name="fidelity" type="long"/> <element name="location"> <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 existedin 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"> <value label="Zone 1" name="area1"/> <value label="Zone 2" name="area2"/> </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"/> <element name="location"> ... <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 tableThis section describes how to create an order table linked to the recipient table with cardinality 1-N.Order table source schema:

128 | © Neolane 2013

Neolane

<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 linkto 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 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 orderto simulate outer joins.

Extension tableAn extension table lets you extend the content of an existing table in a linked table of cardinality 1-1.



The purpose of an extension table is to avoid limitations on the number of fields supported in a table, or tooptimize 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 name="recipient"> <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 theschema 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 tableAn overflow table is an extension table (cardinality 1-1), but the declaration of the link to the table to beextended 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 thereforenot 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"> <key internal="true" name="id"> <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

Neolane

Note:

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


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 tableA relationship table lets you link two tables with cardinality N-N. This table contains only the foreign keys ofthe 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"> <key internal="true" name="id"> <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])"/>

<dbindex name="id" unique="true"> <keyfield xpath="@rcpGroup-id"/> <keyfield xpath="@recipient-id"/> </dbindex>

<key internal="true" name="id"> <keyfield xpath="@rcpGroup-id"/> <keyfield xpath="@recipient-id"/> </key>

<dbindex name="rcpGroupId"> <keyfield xpath="@rcpGroup-id"/> </dbindex> <dbindex name="recipientId"> <keyfield xpath="@recipient-id"/> </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"/>



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

Neolane

Table of ContentsIdentifying a form . . . . . . . . . . . . . . . . . . . . . . . . . 133Editing forms . . . . . . . . . . . . . . . . . . . . . . . . . . . 134Form structure . . . . . . . . . . . . . . . . . . . . . . . . . . . 135

Formatting . . . . . . . . . . . . . . . . . . . . . . . . . . . 136Containers . . . . . . . . . . . . . . . . . . . . . . . . . . . 137Editing a link . . . . . . . . . . . . . . . . . . . . . . . . . . 139List of links . . . . . . . . . . . . . . . . . . . . . . . . . . . 140Memory list controls . . . . . . . . . . . . . . . . . . . . . . . . 142Non-editable fields . . . . . . . . . . . . . . . . . . . . . . . . 143Radio button . . . . . . . . . . . . . . . . . . . . . . . . . . 144Checkbox . . . . . . . . . . . . . . . . . . . . . . . . . . . 144Navigation hierarchy edit . . . . . . . . . . . . . . . . . . . . . . 144Expression field . . . . . . . . . . . . . . . . . . . . . . . . . 144Context of forms . . . . . . . . . . . . . . . . . . . . . . . . . 145Wizards . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145

An input form lets you edit an instance associated with a data schema from the Neolane clientconsole.

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 bya colon (':') (for example: "cus:contact").

Neolane v6.1 - Configuration Guide - Input forms | 133

CHAPTER 4

Input forms

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

Neolane

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 schemaxtk:form.The XML document of the input form must contain the <form> root element with the name and namespaceattributes 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 aform with a different name, set the entity-schema attribute of the <form element to the name of theschema key.To illustrate the structure of an input form, let us describe an interface using the "cus:recipient" exampleschema:

<srcSchema name="recipient" namespace="cus"> <enumeration name="gender" basetype="byte"> <value name="unknown" label="Not specified" value="0"/> <value name="male" label="Male" value="1"/> <value name="female" label="Female" value="2"/> </enumeration>

<element name="recipient"> <attribute name="email" type="string" length="80" label="Email" desc="E-mail address 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:


Input forms

<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 fieldin 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 ofdata.

FormattingThe layout of the controls looks like the layout used in HTML tables, with the possibility of dividing a controlinto 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 dimensionsfor an object.To display the controls of the above example in two columns:

<form name="recipient" namespace="cus"> <container colcount="2"> <input xpath="@gender"/> <input xpath="@birthDate"/> <input xpath="@email"/> </container></form>

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

<form name="recipient" namespace="cus"> <container colcount="2"> <input xpath="@gender"/> <input xpath="@birthDate"/> <input xpath="@email" colspan="2"/> </container></form>

By populating the type="frame" attribute, the container adds a frame around the child controls with thelabel contained in the label attribute:

136 | © Neolane 2013

Neolane

<form name="recipient" namespace="cus"> <container colcount="2" type="frame" label="General"> <input xpath="@gender"/> <input xpath="@birthDate"/> <input xpath="@email" colspan="2"/> </container></form>

A <static> element can be used to format the input form:

<form name="recipient" namespace="cus"> <static type="separator" colspan="2" label="General"/> <input xpath="@gender"/> <input xpath="@birthDate"/> <input xpath="@email" colspan="2"/> <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 labelattribute.A help text was added using the <static tag with a help type. The content of the text is entered in the labelattribute.

ContainersContainers let you group a set of controls. They are represented by the <container> element. They wereused above to format controls over several columns.The xpath attribute on a <container lets you simplify the referencing of child controls. The referencing ofcontrols is then relative to the parent <container parent.Example of a container without "xpath":

<container colcount="2"> <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 containerContainers 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">


Input forms

<input xpath="@gender"/> <input xpath="@birthDate"/> <input xpath="@email" colspan="2"/> </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 thecontrol. 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"> <input xpath="@gender"/> <input xpath="@birthDate"/> <input xpath="@email" colspan="2"/> </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 aredeclared 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 theimage 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

Neolane

A visibility container is defined by the attribute type="visibleGroup". The visibleIf attribute contains thevisibility condition.Examples of condition syntax:

n visibleIf="@email='[email protected]'": tests equality on string-type data. Thecomparison 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 preventsit 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 containsthe activation condition.

Editing a linkRemember 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 caneasily be found from the first few characters entered. The search is then based on the Compute stringdefined in the targeted schema. If the schema does not exist after validation in the control, a confirmationmessage of on-the-fly target creation is displayed. The confirmation creates a new record in the target tableand 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 filterzone:

The Edit link (magnifier) icon launches the edit form of the linked element. The form used is deduced bydefault on the key of the targeted schema. The form attribute lets you force the name of the edit form (e.g."cus:company2").


Input forms

You can restrict the choice of target elements by adding the <sysFilter> element from the link definitionin 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 (defaultmode)

n noZoom: no edit form on the link (with the value "true")

n form: overloads the edit form of the targeted element

List of linksA link entered in the data schema as a collection element (unbound="true") must go through a list in orderto view all the elements associated with it.The principle consists in displaying the list of linked elements with optimized data loading (downloading bydata 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 ofthe 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 anelement 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

Neolane

Filtering and sorting can be applied when the list is being loaded:

<input xpath="rcpEvent" type="linklist"> <input xpath="@label"/> <input xpath="@date"/> <sysFilter> <condition expr="@type = 1"/> </sysFilter> <orderBy> <node expr="@date" sortDesc="true"/> </orderBy></input>

Relationship tableA relationship table lets you link two tables with N-N cardinality. The relationship table contains only the linksto the two tables.Adding an element to the list should therefore let you complete a list from one of the two links in therelationship 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 theassociations with subscriptions to services and must allow you to add a subscription by selecting an existingservice.

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


Input forms


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 controlsMemory lists let you edit the collection elements using list data preloading. This list cannot be filtered orconfigured.These lists are used on XML mapped collection elements or on low-volume links.

Column listThis control displays an editable column list with a toolbar containing Add and Delete buttons.

<input xpath="rcpEvent" type="list"> <input xpath="@label"/> <input xpath="@date"/></input>

The list control must be filled in with the type="list" attribute, and the path of the list must refer to thecollection element.The columns are declared in the child <input> tags of the list. Column label and size can be forced withthe label and colSize attributes.

Note:

Sort-order arrows are added automatically when the ordered="true" attribute is added to the collectionelement 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 xpath="@label"/> <input xpath="@date"/></input>

The toolbarCaption attribute forces the horizontal alignment of the toolbar and enters the title above thelist.

142 | © Neolane 2013

Neolane

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"> <input xpath="@label"/> <input xpath="@date"/>

<form colcount="2" label="Event"> <input xpath="@label"/> <input xpath="@date"/> </form></input>

The edit form is completed from the <form> element under list definition. Its structure is identical to thatof 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 fieldsTo 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"/>


Input forms

Radio buttonA 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"/><input type="RadioButton" xpath="@gender" checkedValue="1" label="Choice 2"/><input type="RadioButton" xpath="@gender" checkedValue="2" label="Choice 3"/>

CheckboxA 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 beoverloaded via the checkValue attributes.

<input xpath="@boolean1"/><input xpath="@field1" type="checkbox" checkedValue="Y"/>

Navigation hierarchy editThis 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"> <input xpath="@boolean1"/> <input xpath="@boolean2"/> </container></input>

Expression fieldAn expression field updates a field dynamically from an expression; the <input> tag is used with an xpathattribute 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

Neolane

Context of formsThe 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 contextTo 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 withthe '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.

<form name="recipient" namespace="cus"> <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 languageA 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 expressionis 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 theform 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>

WizardsA wizard guides you through a set of data entry steps in the form of pages. The data entered is saved whenyou 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"> ...


Input forms

</container> ...</form>

The presence of the type="wizard" attribute on the <form> element lets you define the wizard mode inthe 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 thedescription 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 methodsSOAP 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 attributesof 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

Neolane

Table of ContentsOverview . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148

Definition of Neolane APIs . . . . . . . . . . . . . . . . . . . . . 148Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . 148Using Neolane APIs . . . . . . . . . . . . . . . . . . . . . . . . 148SOAP calls . . . . . . . . . . . . . . . . . . . . . . . . . . . 148Resources and exchanges . . . . . . . . . . . . . . . . . . . . . . 149Example of a SOAP message on the "ExecuteQuery" method . . . . . . . . . . 149Error management . . . . . . . . . . . . . . . . . . . . . . . . 150URL of Web service server (or EndPoint) . . . . . . . . . . . . . . . . . 151

Web service calls . . . . . . . . . . . . . . . . . . . . . . . . . . 151General information . . . . . . . . . . . . . . . . . . . . . . . . 151Definition of Web services . . . . . . . . . . . . . . . . . . . . . . 151Web service description: WSDL . . . . . . . . . . . . . . . . . . . . 152Connectivity . . . . . . . . . . . . . . . . . . . . . . . . . . 153

Data oriented API . . . . . . . . . . . . . . . . . . . . . . . . . 156Overview of the datamodel . . . . . . . . . . . . . . . . . . . . . 156Description of the model . . . . . . . . . . . . . . . . . . . . . . 156Query and Writer . . . . . . . . . . . . . . . . . . . . . . . . . 156ExecuteQuery (xtk:queryDef) . . . . . . . . . . . . . . . . . . . . 157Write / WriteCollection (xtk:session) . . . . . . . . . . . . . . . . . . 164

Business oriented APIs . . . . . . . . . . . . . . . . . . . . . . . . 166Subscribe (nms:subscription) . . . . . . . . . . . . . . . . . . . . . 167Unsubscribe (nms:subscription) . . . . . . . . . . . . . . . . . . . . 168SubmitDelivery (nms:delivery) . . . . . . . . . . . . . . . . . . . . 169

Implementing SOAP methods in JavaScript . . . . . . . . . . . . . . . . . 170Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . 170Definition of a method library . . . . . . . . . . . . . . . . . . . . 170

Use SOAP methods in JavaScript . . . . . . . . . . . . . . . . . . . . 171Static methods . . . . . . . . . . . . . . . . . . . . . . . . . . 171Non-static methods . . . . . . . . . . . . . . . . . . . . . . . . 172Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 172

Adding additional SQL functions . . . . . . . . . . . . . . . . . . . . . 173Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . 173Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . 173General structure of package to import . . . . . . . . . . . . . . . . . 173The <function> function descriptor . . . . . . . . . . . . . . . . . . 174The "pass-through" function descriptor . . . . . . . . . . . . . . . . . 175Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 175

Neolane v6.1 - Configuration Guide - API | 147

CHAPTER 5

API

Overview

Definition of Neolane APIsThe Neolane application server was designed for openness and easy integration with increasingly diverseand complex company information systems.Neolane APIs are used in JavaScript within the application and in SOAP outside of it. They make up a libraryof generic functions that can be enriched. For further information, refer to Implementing SOAP methods inJavaScript [page 170].

Warning:

Neolane APIs are optional and under license. Check your license contract.

PrerequisitesBefore using Neolane APIs, you need to be familiar with the following topics:

n JavaScript

n SOAP protocol

n Neolane datamodel

Using Neolane APIsNeolane 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 toBusiness oriented APIs [page 166].

In order to develop APIs and interact with Neolane, you need to be familiar with your datamodel. Neolanelets you generate a complete description of the base. Refer to Description of the model [page 156].

SOAP callsThe 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

Neolane

n a body containing the information about the call and the response,

n error management that defines the error condition.

Resources and exchangesThe following schema shows the various resources involved in the use of Neolane APIs:

Example of a SOAP message on the "ExecuteQuery" methodIn this example, a SOAP query invokes the "ExecuteQuery" method, which takes a character string as aparameter for authentication (session token) and an XML content for the description of the query to beexecuted.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>


API

</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 themessage, 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

<?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> <ExecuteQueryResponse xmlns='urn:xtk:queryDef' SOAP-ENV:encodingStyle='http://schemas.xmlsoap.org/soap/encoding/'> <pdomOutput xsi:type='ns:Element' SOAP-ENV:encodingStyle='http://xml.apache.org/xml-soap/literalxml'> <rcpGrpRel-collection><rcpGrpRel group-id="1872" recipient-id="1362"></rcpGrpRel></rcpGrpRel-collection> </pdomOutput> </ExecuteQueryResponse> </SOAP-ENV:Body></SOAP-ENV:Envelope>

The result of the query is entered from the <pdomOutput> element.

Error managementExample SOAP error response:

<?xml version='1.0' encoding='ISO-8859-1'?><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: 23000ODBC 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></SOAP-ENV:Envelope>

The <SOAP-ENV:Fault> element in the body of the SOAP message is used to convey the error signals arisingduring 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

Neolane

Important:

All Neolane Web services handle errors. It is therefore strongly recommended to test each call in order tohandle 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 becontacted.The server URL is as follows:http://<server>/nl/jsp/soaprouter.jsp

With <server> the Neolane application server (nlserver web).

Web service calls

General informationAll API methods are presented in the form of Web services. This enables you to manage all Neolane functionsvia SOAP calls, which are the native entry point of the Neolane application server. The Neolane console itselfonly 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 transactionsystem,

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 theunderlying physical model.

Definition of Web servicesThe definition of the Web services implemented on the Neolane application server is available from the dataschemas.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.


API

https://XXXX//nl/jsp/soaprouter.jsp

The description of the service starts with the <method> element. The list of parameters of the method iscompleted 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 meansthat 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: WSDLA WSDL (Web Service Description Library) file is available for each service. This XML file uses a metalanguageto describe the service and to specify the available methods, parameters, and the server to contact forexecuting the service.

WSDL file generationTo 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 toa 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

Neolane

http://XXXX/nl/jsp/schemawsdl.jsp?schema=YYYY

http://mon_serveur/nl/jsp/schemawsdl.jsp?schema=xtk:queryDef

<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 messagesto 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 theSOAP 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 applicationserver.

<service name="XtkQueryDef"> <port binding="tns:queryDefMethodsSoap" name="queryDefMethodsSoap"> <soap:address location="https://localhost/nl/jsp/soaprouter.jsp"/> </port></service>

ConnectivityNeolane v6.1 has increased security for authentication mechanisms by introducing security zones (refer tothe Defining security zones chapter in the Installation guide) as well as session management settings.There are two authentication modes available:


API

installation-v6.1-en.pdf#nameddest=csturges-36892

n via a call to logon method(). This mode generates a session token and a security token. It is the mostsecure mode and therefore the most recommended.

or

n via the Neolane login + password that creates a session token. The session token automaticallyexpires after a set period. This mode is not recommended and requires reducing the application securitysettings for some zone settings (allowUserPassword="true" and sessionTokenOnly="true").

Session token characteristicsThe 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 characteristicsThe 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

Neolane

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 = '[email protected]'"/> </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 = \'[email protected]\'"/></where>' + '</queryDef>' + '</urn:entity></urn:ExecuteQuery></soapenv:Body></soapenv:Envelope>';

req2.execute();var resp2 = req2.response;logInfo(resp2.body)


API

Data oriented API

Data oriented APIs let you address the entire datamodel.

Overview of the datamodelNeolane does not offer a dedicated read API per entity (no getRecipient or getDelivery function, etc.). Usethe 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 throughoutthe base. Unlike access in SQL mode, Neolane APIs return an XML tree instead of data columns. Neolanethus 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 XMLdocuments and the columns of the tables in the database.XML documents are stored in MEMO type fields of the database.

Description of the modelYou must be familiar with the Neolane data model to be able to address the fields of the database in yourscripts.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 adescription of the Neolane tables. This file can be edited with Open Office and/or converted to PDF formatif necessary.

Query and WriterThe following introduction schema details low level exchanges for reading (ExecuteQuery) and writing (Writer)between database and customer (web pages or Neolane client console).

ExecuteQueryFor 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

Neolane

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

WriteWrite 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 letsyou create or update data. You can also configure modification merging (merge): this operating mode letsyou authorize partial updates.The XML structure offers a logical view of the data and lets you sidestep the physical structure of the SQLtable.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 returnparameter is an XML document containing the result of the query in the format of the schema to which thequery 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 queryThe structure of the XML document of the query is described in the "xtk:queryDef " schema. This documentdescribes the clauses of a SQL query: "select", "where", "order by", "group by", "having".

<queryDef schema="schema_key" operation="operation_type"> <select> <node expr="expression1"> <node expr="expression2"> ... </select> <where> <condition expr="expression1"/> <condition expr="expression2"/> ... </where> <orderBy> <node expr="expression1"> <node expr="expression2"> ... </ordery> <groupBy> <node expr="expression1"> <node expr="expression2"> ... </groupBy> <having> <condition expr="expression1"/> <condition expr="expression2"/> ... </having></queryDef>

A sub-query (<subQuery>) can be defined in a <condition> element. The syntax for a <subQuery> elementis based on the syntax of a <queryDef>.


API

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> <node expr="@firstName"/> <node expr="@lastName"/> </select>

 <where> <condition expr="@email= '[email protected]'"/> </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 ondate of birth.

<queryDef schema="nms:recipient" operation="select"> <select> <node expr="@email"/>  <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 concatenationof 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

Neolane

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

<queryDef schema="nms:recipient" operation="select"> <select> <node expr="@email"/> <node expr="count(@email)"/> </select>

 <groupby> <node expr="@email"/> </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"/>


API

</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 samefield:

<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 linkedtable 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 EXISTSor 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 becausethe 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. TheXPaths 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 whichthe recipient subscribes:

<queryDef schema="nms:recipient" operation="select"> <select> <node expr="@email"/>

 <node expr="subscription"> <node expr="[service/@label]"/>

160 | © Neolane 2013

Neolane

 <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 veryuseful, since the engine is in charge of the escaping of values, and there is the additional benefit of a cachefor the parameters to be retrieved.When a query is constructed, the "bound" values are replaced by a character (? in ODBC, #[index]# inpostgres...) 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 thequery.

Query-building tip:

To help with the syntax of a query, you can write the query using the generic query editor in the Neolaneclient console (Tools/ Generic query editor... menu). To do this:

1 Select the data to be retrieved:


API

2 Define the filter condition:

3 Execute the query and press CTRL+F4 to view the query source code.

Output document formatThe 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="[email protected]" lastName"Doe" firstName="John"/>

On a "select" operation, the document returned is an enumeration of elements:

<recipient-collection> <recipient email="[email protected]" lastName"Doe" firstName="John"/>

162 | © Neolane 2013

Neolane

<recipient email="[email protected]" 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 anXPath on the corresponding field.

<queryDef schema="nms:recipient" operation="get"> <select> <node expr="@firstName" alias="@firstName"/> <node expr="@lastName"/> <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:

<?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 operation="get" schema="nms:recipient" xtkschema="xtk:queryDef"> <select> <node expr="@email"/> <node expr="@lastName"/> <node expr="@firstName"/> </select> <where> <condition expr="@id = 3599"/> </where> </queryDef> </entity> </ExecuteQuery> </SOAP-ENV:Body></SOAP-ENV:Envelope>

n Response:

<?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> <ExecuteQueryResponse xmlns='urn:xtk:queryDef' SOAP-ENV:encodingStyle='http://schemas.xmlsoap.org/soap/encoding/'> <pdomOutput xsi:type='ns:Element' SOAP-ENV:encodingStyle='http://xml.apache.org/xml-soap/literalxml'> <recipient email="[email protected]" lastName"Doe" firstName="John"/>


API

</pdomOutput> </ExecuteQueryResponse> </SOAP-ENV:Body></SOAP-ENV:Envelope>

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 authenticationstring (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 schemato be updated.

OverviewData reconciliation operates based on the definition of the keys entered in the associated schema. The writeprocedure looks for the first eligible key based on the data entered in the input document. The entity isinserted 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 makeup 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" methodUpdating or inserting a recipient (implicit "insertOrUpdate" operation) with e-mail address, date of birth andtown:

<recipient xtkschema="nms:recipient" email="[email protected]" 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="[email protected]" folder-id=1203 _key="@email, [@folder-id]"/>

164 | © Neolane 2013

Neolane

Note:

For a deletion operation, the input document must contain only the fields that make up the reconciliationkey.

Example with the "WriteCollection" methodUpdate or insertion for several recipients:

<recipient-collection xtkschema="nms:recipient"> <recipient email="[email protected]" firstName="John" lastName="Doe" _key="@email"/>

<recipient email="[email protected]" 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="[email protected]" 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 isthe 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 orinsert.

Example 2

Updating the company (linked table in "cus:company" schema) from a recipient:

<recipient _key="[folder/@name], @email" email="[email protected]" 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="[email protected]" 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 thegroup name is defined in the "nms:group" schema.

XML collection elementsBy 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 onlythe elements to be updated, you must populate the "_operation" attribute on all collection elements to beupdated in order to force a merge with the XML data of the database.


API


n 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> <Write xmlns='urn:xtk:persist' SOAP-ENV:encodingStyle='http://schemas.xmlsoap.org/soap/encoding/'> <__sessiontoken xsi:type='xsd:string'/> <domDoc xsi:type='ns:Element' SOAP-ENV:encodingStyle='http://xml.apache.org/xml-soap/literalxml'> <recipient xtkschema="nms:recipient" email="[email protected]" firstName="René" lastName="Dupont" _key="@email"> </domDoc> </Write> </SOAP-ENV:Body></SOAP-ENV:Envelope>

n Response:

<?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> <WriteResponse xmlns='urn:' SOAP-ENV:encodingStyle='http://schemas.xmlsoap.org/soap/encoding/'> </WriteResponse> </SOAP-ENV:Body></SOAP-ENV:Envelope>

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" xmlns:SOAP-ENV='http://schemas.xmlsoap.org/soap/envelope/'> <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></SOAP-ENV:Envelope>

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

Neolane

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 Javascriptin 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 ofthe XML document. The content of this attribute is a comma-separated XPath list.This call does not return any data, except errors.

ExamplesSubscription with recipient reconciliation key on the e-mail address: the input XML document must referencethe email address and the definition of the key on this field.

<recipient _key="email" email= "[email protected]"/>

Updating the recipient as well as the subscription.

<recipient _key="email, [folder-id]" email= "[email protected]" folder-id="1305" firstName="John" lastName="Doe"/>


n 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:SOAP-ENV='http://schemas.xmlsoap.org/soap/envelope/'> <SOAP-ENV:Body> <m:Subscribe xmlns:m='urn:nms:subscription' SOAP-ENV:encodingStyle='http://schemas.xmlsoap.org/soap/encoding/'> <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= "[email protected]/> </content> <create xsi:type='xsd:boolean'>true</create> </m:Subscribe>


API

</SOAP-ENV:Body></SOAP-ENV:Envelope></SOAP-ENV:Envelope>

n Response:

<?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> <m:SubscribeResponse xmlns:m='urn:nms:subscription' SOAP-ENV:encodingStyle='http://schemas.xmlsoap.org/soap/encoding/'> </m:SubscribeResponse> </SOAP-ENV:Body></SOAP-ENV:Envelope>

Unsubscribe (nms:subscription)This service lets you unsubscribe a recipient from an information service and update the recipient profile.The following parameters are required in order to call the service:


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 ofthe 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, theservice 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").

This call does not return any data, except errors.

Example of SOAP messagesQuery:

<?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:SOAP-ENV='http://schemas.xmlsoap.org/soap/envelope/'> <SOAP-ENV:Body> <m:Unsubscribe xmlns:m='urn:nms:subscription' SOAP-ENV:encodingStyle='http://schemas.xmlsoap.org/soap/encoding/'> <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= "[email protected]/> </content> </m:Unsubscribe></SOAP-ENV:Body>

168 | © Neolane 2013

Neolane

Response:

<?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> <m:UnsubscribeResponse xmlns:m='urn:nms:subscription' SOAP-ENV:encodingStyle='http://schemas.xmlsoap.org/soap/encoding/'> </m:UnsubscribeResponse> </SOAP-ENV:Body></SOAP-ENV:Envelope>

SubmitDelivery (nms:delivery)This service lets you create and submit a delivery action.The following parameters are required in order to call the service:


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 commonto 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).This call does not return any data, except errors.

XML document example:This example is based on a delivery template from an external data source (a file in this case). Theconfiguration is fully described in the delivery template, so all that remains to be sent when the call occursis 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| [email protected]|1| A1|A2|A3|A4|E12|120000|100000 </externalSource> </target></delivery>

Example of SOAP messagesQuery:

<?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:SOAP-ENV='http://schemas.xmlsoap.org/soap/envelope/'> <SOAP-ENV:Body> <m:SubmitDelivery xmlns:m='urn:nms:delivery' SOAP-ENV:encodingStyle='http://schemas.xmlsoap.org/soap/encoding/'> <sessiontoken xsi:type='xsd:string'><scenarioName xsi:type='xsd:string'>test</scenarioName>


API

<content xsi:type='' SOAP-ENV:encodingStyle='http://xml.apache.org/xml-soap/literalxml'> <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|[email protected]|1| A1|A2|A3|A4| E12|120000|100000]]></externalSource> </targets> </delivery> </content> </m:SubmitDelivery> </SOAP-ENV:Body></SOAP-ENV:Envelope>

Response:

<?xml version='1.0' encoding='ISO-8859-1'?><SOAP-ENV:Envelope xmlns:SOAP-ENV='http://schemas.xmlsoap.org/soap/envelope/'> <m:SubmitDeliveryResponse xmlns:m='urn:nms:delivery' SOAP-ENV:encodingStyle='http://schemas.xmlsoap.org/soap/encoding/'> </m:SubmitDeliveryResponse> <SOAP-ENV:Body> </SOAP-ENV:Body></SOAP-ENV:Envelope>

Implementing SOAP methods in JavaScript

IntroductionIt is possible to create SOAP methods in JavaScript. This function simply enables applicative processes, itcan 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 attributesare supported: static, key only and const.

Definition of a method libraryCreating a method library involves two stages:

n The SOAP method declaration,

n Definition (or implementation) in JavaScript.

DeclarationStart by declaring the methods in the schemas. Their declaration is similar to that of native methods, exceptthat you need to add the 'library' attribute specifying the name of the method library where the definition islocated.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 namewhere the declaration is found.

170 | © Neolane 2013

Neolane

DefinitionSOAP 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 bedefined in separate libraries.

The script can contain code to be executed during initial library loading.1. NameThe 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 definedin the 'JavaScript Code' type entity using the 'cus:test' name.

function nms_recipient_testLog(message) { logInfo("*** " + message) }

2. SignatureThe 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 XMLentity 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 thekey passed in the form of character strings.

3. Returned valuesThe function must return a value for each 'out' or 'inout' type parameter. Specific case: If the method isdeclared without any of the 'static', 'key only' or 'const' attributes, the first returned value must coincide withthe 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 methodsStatic SOAP methods are accessed by invoking a method on the object representing the schema. Schemasare properties of 'namespace' objects. These namespaces are global variables, thus, for example, xtk or nmsvariables represent the corresponding namespaces.The following example invokes the static PostEvent method of the xtk:workflow schema:


API

xtk.workflow.PostEvent("WKF1", "signal", "", $recipient-id='123', false)

Non-static methodsTo use non-static SOAP methods, it is necessary first to retrieve an entity using the "get" or "create" methodson 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:

var query = xtk.queryDef.create( <queryDef schema="nms:recipient" operation="get"> <select> <node expr="@firstName"/> <node expr="@lastName"/> <node expr="@email"/> </select> <where> <condition expr="@email = '[email protected]'"/> </where> </queryDef>)

var recipient = query.ExecuteQuery()

logInfo(recipient.@firstName)logInfo(recipient.@lastName)

n Query on the recipient table with a "select" operation:

var query = xtk.queryDef.create( <queryDef schema="nms:recipient" operation="select"> <select> <node expr="@email"/> <node expr="@lastName"/> <node expr="@firstName"/> </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

Neolane

Adding additional SQL functions

IntroductionNeolane allows the user to define their own functions that can access SQL functions, both those offeredby 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 databaseprovides an easier way to implement certain functions, rather than "manually" write the expression in theconsole (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 predefinedfunctions.

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

InstallationThe function(s) to add are in a "package" file in XML format whose structure is detailed in the followingparagraph.To install it from the console, select the Tools/Advanced/Import package options from the menu, thenthe 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 beusable until Neolane has been restarted.

General structure of package to importThe 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>


API

</package>

n The name, namespace and label are for information purposes only. They let you view a summary ofthe package in the installed packages list (Explorer/Administration/Package management/Installedpackages).

n The buildVersion and buildNumber fields are mandatory. They must correspond to the server numberto 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 functionlist.This means that if another list of functions with the same namespace/name pair (here "cus::myList") isimported, the previously imported functions will be deleted. Conversely, if you change thisnamespace/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 inthe function editor. The @name attribute can either be a name that already exists (in which case thefunctions will be added to the considered group) or a new name (in which case it will appear in a newgroup).

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 availablefunctions. If you do not enter anything, the group will not have a name. However, if you enter a name otherthan 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 becometracked in the same list.Finally, a <group> element can contain the definition of one or several functions, that is the purpose of thepackage file. The <function> element is detailed in the following paragraph.

The <function> function descriptorThe 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 theperson 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 displayedin the description. In this case, the function will appear as "relativeMaturity (<Age>)" in the function selectionwindow.

n help is the field displayed at the bottom of the expression editor window.

174 | © Neolane 2013

Neolane

n @display is an informative message.

Note:

In the @help and @display attributes, the string "$1" represents the name that was given in the firstfunction parameter (here, "Age"). $2, $3... would represent the following parameters. In the @bodyattribute 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 thefunction.

n @minArgs and maxArgs designates the number of parameters (minimum and maximum) for aparameter. For example, for a function with 2 parameters, minArgs and maxArgs will be 2 and 2. For 3parameters, 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 implementationis 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 mustbe an expression, in database language (not a block of code). Depending on the databases, expressionscan 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 onlythe definitions corresponding to these databases.

The "pass-through" function descriptorAn special function descriptor is the <body> "pass-through" block, with an unspecified "provider" databasesystem. In this case, "body" implementation can only contain a single function call with a syntax that is notdependent 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 availableby default, now visible to the client.

ExamplesFurther function examples can be found in the predefined package "xtk\datakit\funcList.xml".


API


Neolane

Table of ContentsOverview . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . 178

Global commands . . . . . . . . . . . . . . . . . . . . . . . . . 179Folder type . . . . . . . . . . . . . . . . . . . . . . . . . . . 180

Edition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183

Overview

The navigation hierarchy works like a file browser (e.g. Windows Explorer). Folders may containsub-folders. Selecting a node displays the view corresponding to the node.

Neolane v6.1 - Configuration Guide - Navigation hierarchy | 177

CHAPTER 6

Navigation hierarchy

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, andselect 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 grammarof the xtk:navtree schema.The XML document is structured as follows:

178 | © Neolane 2013

Neolane

<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 tospecify the document name and namespace. The name and namespace make up the document identificationkey.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 commandsA 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 name="<name>" service="<schema>"> <param type="<type>" exprIn="<xpath>"/> ... </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 availablerights 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 letsyou 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 '-' valuecontained in the command label.



The optional presence of the <soapCall> tag with its input parameters defines the call of a SOAP methodto 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 thistag, 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 typeA folder type lets you give access to the data of a schema. The view associated with the folder consists ofa 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 modèle>"> ... </model></model>

The folder type declaration must be entered under a <model> element. This element lets you define ahierarchical 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 theAdd 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

Neolane

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

n insertRight, editRight, deleteRight: rights for inserting, editing and deleting folders.

The <view> element under the <nodeModel> element contains the configuration of the list associatedwith 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. Thetype 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 onselecting 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 declaredon a <node> element containing the xpath attribute with the field to be referenced in its schema as itsvalue.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>



Shortcut commandsA shortcut command lets you launch an action on selecting the list. The action can be an input form or aSOAP 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 name="<name>" service="<schema>"> <param type="<type>" exprIn="<xpath>"/> ... </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 availablerights 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 letsyou 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 '-' valuecontained in the command label.The optional presence of the <soapCall> tag with its input parameters defines the call of a SOAP methodto 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 thistag, 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 folderThere 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 systemfiltering entered in the folder properties.

182 | © Neolane 2013

Neolane

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 attributecontains 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 viathe Administration/Configuration/Navigation hierarchies node:

The navigation hierarchy configuration is divided over several XML documents. It operates on a similarprinciple to schema extension: all documents are merged to generate a single document containing the wholeconfiguration. This document cannot be edited, and is displayed via the "Preview" tab.The edit field provides the content of the XML document:



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 ofthe schema.

The preview automatically generates the merged document containing the complete configuration:

184 | © Neolane 2013

Neolane

Table of ContentsIntroduction . . . . . . . . . . . . . . . . . . . . . . . . . . . 185

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 185Precisions . . . . . . . . . . . . . . . . . . . . . . . . . . . 185Recommendations and limitations . . . . . . . . . . . . . . . . . . . 186

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186The View attribute . . . . . . . . . . . . . . . . . . . . . . . . 186Names of tables and columns . . . . . . . . . . . . . . . . . . . . 187Indexed fields . . . . . . . . . . . . . . . . . . . . . . . . . . 187

Setting up a target mapping . . . . . . . . . . . . . . . . . . . . . . 187Creating and configuring the schemas linked to the external table . . . . . . . . 188Using target mapping . . . . . . . . . . . . . . . . . . . . . . . 191

Configuring the interface to use the new recipient table . . . . . . . . . . . . 191Creating a new form . . . . . . . . . . . . . . . . . . . . . . . . 192Creating a new type of folder in the navigation hierarchy . . . . . . . . . . . 192

Configuring seed addresses based on an external recipient table . . . . . . . . . 193Implementation . . . . . . . . . . . . . . . . . . . . . . . . . 193

Creating filters to manipulate the new recipient table . . . . . . . . . . . . . 194Creating lists based on the external recipient table . . . . . . . . . . . . . . 195

Introduction

OverviewThis section details the principles for using a non-standard recipient table. By default, Neolane offersa standard recipient table to which out-of-the-box functions and processes are linked. Using anon-standard table, or 'external recipient table', requires certain pre-installation precautions whenimplementing it

PrecisionsThis functionality allows Neolane to process data from an external database: this data will be usedas a set of profiles for deliveries. Implementing this process involves several precisions that maybe 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 updateddirectly 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

CHAPTER 7

Using an external recipienttable

n Using a profile database with a non-standard structure: possibility of delivering to profiles saved in varioustables with various structures, using a single instance.

This section describes the key points that let you map existing tables in Neolane and the configuration toapply to execute deliveries based on any table. Finally, it describes how to provide users with queryinginterfaces as practical as those available with the standard recipient table. To understand the materialpresented in this section, good knowledge of the principles of screen and schema design is required.

Recommendations and limitationsUsing 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 correcttable.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 additionalconfiguration.

Note:

You can still create recipient lists using workflows. For more on this, refer to Creating lists based on theexternal recipient table [page 195].

We also recommend checking the default values used in the different out-of-the-box configurations: dependingon 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 attributeSource schemas accept the view attribute for the srcSchema root element. It must be used when Neolaneis manipulated in external tables. The view="true" attribute tells the database structure update wizard toignore this schema. The application is therefore prohibited from synchronizing the table, its columns and itsindexes with the corresponding schema.When this attribute is set to true, the schema is used only to generate SQL queries to access the data ofthis table.

186 | © Neolane 2013

Neolane

delivery-v6.1-en.pdf#nameddest=ASN-00120

platform-v6.1-en.pdf#nameddest=ASN-00019

Names of tables and columnsWhen tables are created by the table update wizard, the names of tables and columns are generatedautomatically based on the names of the respective schemas and attributes. It is however possible to forcethe 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 internal="true" name="id"> <keyfield xpath="@id"/> </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="email" type="string" length="100"/> <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 applicationwould 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 columnswill not be user-accessible.

Indexed fieldsWhen sorting the records of a list from the client console, better performance is obtained by sorting onindexed fields. Declaring an index in a schema makes the console display the indexed fields with a red lineunder 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 canbe 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 thetarget mapping screen.

The target mapping creation wizard will help you create all schemas required to use your external table.


Using an external recipient table

Creating and configuring the schemas linked to the external tableBefore you create a target mapping, several configurations are necessary in order for Neolane to operatewith 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 orSMS 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"> <keyfield xpath="@id"/> </key> <attribute name="id" type="long" length="32"/> <attribute name="lastName" type="string" length="100"/> <attribute name="firstName" type="string" length="100"/> <attribute name="email" 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 expr="Upper([../address/@ligne3Afnor])" name="line3"/> <attribute expr="Upper([../address/@ligne4Afnor])" name="line4"/> <attribute expr="Upper([../address/@ligne5Afnor])" name="line5"/> <attribute expr="Upper([../address/@ligne6Afnor])" name="line6"/> <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

Neolane

6 Enter the Label field and select the schema which you have just created in the Targeting dimensionfield.

7 In the Edit address forms window, select the fields of the schema which match the various deliveryaddresses. 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 differentiatethe new schemas from the out-of-the-box schemas provided by Neolane.



By default, exclusion management is stored in the same tables as messages. Check the Generate astorage schema for tracking box if you want to configure storage for the tracking linked to your targetmapping.

9 In the Extensions window, select the optional schemas which you want to generate (the list of availableschemas depends on the modules installed on the Neolane platform).

10 Click the Save button to close the wizard.

190 | © Neolane 2013

Neolane

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

Using target mappingThere 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.



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 matchesthe external recipient table (in this case: cus:individual).

3 Save changes.

Creating a new formCreating 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 havethe following layout:

<container colspan="2"> <input xpath="@id"/> <static type="separator"/></container><container colcount="2"> <input xpath="@lastName"/> <input xpath="@firstName"/> <input xpath="@email"/> <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 thereforehave 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

Neolane

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:seedMemberschema 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.

ImplementationThe nms:seedMember schema and the linked form which come out-of-the-box are meant to be extendedfor customer configuration, to reference all necessary fields. The schema definition contains commentsdetailing 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 existingschema [page 121].

2 In this new extension, add a new element at the root of seedMember with the following parameters:

name="custom_customNamespace_customSchema"



delivery-v6.1-en.pdf#nameddest=ASN-00331

This element must contain the fields required to export the campaigns. These fields should have thesame 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 adelivery in Neolane.

Warning:

n During the extension, you must specify an SQL name (@sqlname) for the 'email' field. The SQLname 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 addresseswindow. 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"/> <input xpath="@email"/> </container> </input> </container>

If all attributes of the seed address aren't entered, Neolane automatically substitutes the profiles: they willbe 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 abatch of predefined filtersThese filters will be available in the target selection window with the same functionalities as segments forrecipients (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 theDocument type field.

4 Create your filtering conditions based on the fields of your schema.

5 Save the filter.

194 | © Neolane 2013

Neolane

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 generatethe 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 onthe schema of the new recipient table (in our example: Individual).

5 Approve this configuration.



6 Double-click the Update list activity, then select the Created if necessary (Calculated name) radiobutton.

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

Neolane

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




Neolane

Table of ContentsOverview . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199Web tracking mode . . . . . . . . . . . . . . . . . . . . . . . . . 200Web tracking tag: definition . . . . . . . . . . . . . . . . . . . . . . 202

Format of the data to be sent . . . . . . . . . . . . . . . . . . . . 203Data transmission methods . . . . . . . . . . . . . . . . . . . . . 203

Setup stages . . . . . . . . . . . . . . . . . . . . . . . . . . . 203Additional web tracking parameters . . . . . . . . . . . . . . . . . . . 204

Definition of parameters . . . . . . . . . . . . . . . . . . . . . . 204Redirection server configuration . . . . . . . . . . . . . . . . . . . . 205

Creating web tracking tags . . . . . . . . . . . . . . . . . . . . . . 205Defining the URLs to be tracked in the application . . . . . . . . . . . . . 206On-the-fly creation of URLs to be tracked . . . . . . . . . . . . . . . . 206

Inserting tags in your site . . . . . . . . . . . . . . . . . . . . . . . 207Simple method . . . . . . . . . . . . . . . . . . . . . . . . . 207Optimum method . . . . . . . . . . . . . . . . . . . . . . . . . 208

Collecting all visits to a site . . . . . . . . . . . . . . . . . . . . . . 210Server configuration . . . . . . . . . . . . . . . . . . . . . . . . 210Configuring 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 ane-mail message, the Neolane platform lets you collect information on how internet users browseyour 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 servercontacted deposits a session cookie containing the broadlog identifier (broadlogId) and the deliveryidentifier (deliveryId).The web client then sends this cookie to the server each time the user visits a page containing aweb 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

CHAPTER 8

Setting up Web tracking

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 inthe application.There are three available Web tracking modes: "Session tracking", "Permanent tracking" and"Anonymous tracking".

200 | © Neolane 2013

Neolane

Each mode has specific characteristics. The "permanent" Web tracking mode includes the characteristics ofthe "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 othercases, 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 inan 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 theapplication.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 uuid230cookie. If a visitor closes their session, Neolane uses the permanent cookie to recover information on themfrom previous tracking logs. Neolane re-inserts a tracking log if the uuid230 of the current session has thesame 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 enablereconciliation on uuid230 values.By default, searches in previous tracking logs are performed in the "trackingLog" table. If the Leads packageis enabled, before searching the "trackingLog" table, Neolane will search the "incomingLead" table for previoustracking 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 trackinglog 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 (referto session tracking). Neolane will automatically search previous logs for a "uuid230" value equal to the value



from the tracking log for this marketing campaign. If identical values are found, all previous tracking logsare 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 anypurchases. The next day, Florence returns to the retail site, browses and makes a purchase. Since permanentweb tracking (last delivery) is enabled, all the logs for her second visit will be linked to the delivery that wassent 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 redirectionserver via an HTTP query.

202 | © Neolane 2013

Neolane

Format of the data to be sentThe 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.

DescriptionTypeName

Delivery identifier and recipient identifier.Session cookieID

Recipient identifier (useful if session cookie is absent).Permanent cookieuuid230

Identifier of tracked web page: this is the only mandatory parameter.URL parametertagid

Delivery identifier to be used if there is no session cookie. This value isto be expressed in hexadecimal.

URL parameterjobid

Parameter used to identify the internet user. The format of this parameteris "name=value", where the name is a field of the recipient schema. Thisparameter takes priority over the identifier contained in the sessioncookie.

URL parameterrcpid

A few web tracking URLs

n Visit to a 'home' identifier pagehttp://myserver.neolane.com/r/9862?tagid=home

n Collecting business volume datahttp://myserver.neolane.com/r/4567?tagid=command&amount=100&article=2l

n Specifying a field to find the recipienthttp://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 deliveryhttp://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 methodsThe following methods are possible:

n Inserting the URL in the "src" attribute of an HTML <img> tag incorporated in the web page you wishto 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,



n TRANSACTION: operates like a Web tag, but with the possibility of adding information on the businessvolume 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:webTrackingLogschema with the description of this information. By default, this schema can store the transaction amountsand 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 extractthe associated web-tracking tags (from the Campaign execution>Resources>Web trackingtags node of the client console).

n Create the web-tracking tags yourself in "on-the-fly creation" mode: the URLs corresponding to thesepages 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 bemodified 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|" + _fdocument.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 parametersYour 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 seenin 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

Neolane

Redirection server configurationIn the server configuration, you can define the maximum number of characters to be taken into account foryour web tracking parameters.

Warning:

The correct calculation of the number of characters to be taken into account is important for optimizing theweb tracking performance of your platform.

To do this, modify the webTrackingParamSize attribute of the <trackinglogd> element in theserverConf.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 extensionschema 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 inLinux,

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 startin Linux,

n Restart the web server.

Example: taking into account of the configuration under Linux.

neolane@selma:~$ /etc/init.d/nlserver5 stopneolane@selma:~$ /etc/init.d/apache stopneolane@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) deletedneolane@selma:~$ /etc/init.d/nlserver5 startneolane@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 referencingcan be performed in two ways:

1 Manual definition of URLs to be tracked,

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



Defining the URLs to be tracked in the applicationThis method lets you manually define the pages to be tracked and then generate an example of the associatedweb tracking tag. This operation is defined in the Campaign execution>Resources>Web tracking tagsnode 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 trackedYou 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 thecharacter '|':

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

Neolane

Inserting tags in your site

Simple methodThis method consists of sending an HTTP call to the redirection server by inserting an <IMG> HTML tag inthe 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 copyand 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 orderto insert the transaction information (amount, number of items) and any information defined by an extensionschema.

Static insertion of tagsTo perform static tag insertion, simply copy and paste the tags generated by the console or constructedmanually 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>



<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 tagsWhen your web pages are generated dynamically, you can add the web tracking tag at page generationtime.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 methodIf you wish to control the information sent to the redirection server, the most reliable way is to perform theHTTP query synchronously yourself using a page generating language.

208 | © Neolane 2013

Neolane

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 synchronousHTTP 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 articlesString 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 requestCookie[] 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 stringAddCookie(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



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 performedby 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 auser known to the platform.A user known to the platform is a recipient who has already been targeted by a delivery and who has clickedin 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 thesite following a click in a message. When this option is enabled, it can cause very high use of resources onthe machines hosting your servers (redirection, application, and database). You are advised to ensure thatyour hardware architecture can support this load, and to avoid placing web tracking tags in the most frequentlyvisited pages, such as the home page.

Server configurationThe servers are configured by overloading certain elements of the serverConf.xml file. These files aresaved in the conf subdirectory of the Neolane installation directory.

Redirection serverFor 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 campaignTo 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 dummydelivery created.

Anonymous tracking

Neolane lets you link collected Web tracking information to a recipient when they browse your siteanonymously. 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 automaticallylinked to them.

210 | © Neolane 2013

Neolane

Warning:

Setting up anonymous tracking on a website can trigger the collection of a significant amount of trackinglogs, 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 toconfigure 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 thetracking server must be set to 'true', to place a permanent cookie (uuid230) in the browsers of unknowninternet users who visit the site.

n The Anonymous Web Tracking mode must be selected in the tracking configuration screen of thedeployment wizard.



installation-v6.1-en.pdf#nameddest=ACY-23398

n Web forms and surveys must be published and executed on the tracking server. The matching optionmust be selected in the deployment wizard.

212 | © Neolane 2013

Neolane

Documents

Neolane v6.1 - Configuration Guide - Adobe and extending schemas . . . . . . . . . . . . . . . . . 113 ... Server configuration ... Configuration Guide - Neolane