Neolane v6.0
This document, and the software it describes, are provided subject to a License Agreement and may not be used or copied outside of the
provisions of the License Agreement. No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any
form or by any means, electronic, mechanical, photocopying, recording or otherwise, without the prior written permission of Neolane.
The information contained in this document is provided for informational purposes only and may be revised without notice. It does not
constitute a commitment on the part of Neolane. Neolane does not guarantee the accuracy nor the completeness of the information
contained within this document. References to company names are intended to be ficticious and for illustrative purposes only and do not
refer to any real-world company.
Any brands cited are the property of their respective owners. Windows is the registered trademark of Microsoft Corporation in the United
States and other countries. Java, MySQL and Open Office are trademarks of Oracle Corporation in the United States and in other countries.
Linux is the registered trademark of Linus Torvalds in the United States and in other countries. This product includes software developed
by Apache Software Foundation (http://www.apache.org/).
For any questions or queries, please send a message to the following address: doc@neolane.com.
Neolane
18 rue Roger Simon Barboux, 94110 Arcueil - France
+33 1 41 98 35 35
www.neolane.com
Table of Contents
NmsOffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
NmsPropositionRcp . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
NmsOfferSpace . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
NmsOfferContext . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Campaign management . . . . . . . . . . . . . . . . . . . . . . . . . . 44
NmsOperation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
NmsDeliveryOutline . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
NmsDlvOutlineItem . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
NmsDeliveryCustomization . . . . . . . . . . . . . . . . . . . . . . . . 47
NmsBudget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
NmsDocument . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
XtkWorkflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
NmsTask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
NmsAsset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Message Center Module . . . . . . . . . . . . . . . . . . . . . . . . . . 55
NmsRtEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
NmsBatchEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Social Marketing Module . . . . . . . . . . . . . . . . . . . . . . . . . . 59
NmsVisitor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
NmsVisitorSub . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
NmsFriendShipRel . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
NmsVisitorInterestRel . . . . . . . . . . . . . . . . . . . . . . . . . . 61
NmsInterest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Neolap Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
XtkOlapCube . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
XtkOlapMeasure . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
XtkOlapAggregate . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
XtkOlapDimension . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Microsites Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
NmsTrackingUrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
NmsPurl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Delivery to mobile channels . . . . . . . . . . . . . . . . . . . . . . . . . 67
Status of messages sent via SMS according to NetSize . . . . . . . . . . . . . 67
4 | Neolane 2013
Configuration Guide
<element> element . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
<enumeration> element . . . . . . . . . . . . . . . . . . . . . . . . . 100
<help> element . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
<join> element . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
<key> element . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
<keyfield> element . . . . . . . . . . . . . . . . . . . . . . . . . . 106
<method> element . . . . . . . . . . . . . . . . . . . . . . . . . . 107
<methods> element . . . . . . . . . . . . . . . . . . . . . . . . . . 109
<param> element . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
<parameters> element . . . . . . . . . . . . . . . . . . . . . . . . . 112
<srcSchema> element . . . . . . . . . . . . . . . . . . . . . . . . . 113
<sysFilter> element . . . . . . . . . . . . . . . . . . . . . . . . . . 115
<value> element . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
6 | Neolane 2013
Configuration Guide
Table of Contents
Accessing the data schemas in Neolane . . . . . . . . . . . . . . . . . . 11
General information . . . . . . . . . . . . . . . . . . . . . . . . . 11
Physical and logical data . . . . . . . . . . . . . . . . . . . . . . . 11
Work tables . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Table structure . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Auto-incrementing primary keys . . . . . . . . . . . . . . . . . . . . 12
Zero-ID record . . . . . . . . . . . . . . . . . . . . . . . . . . 12
"Deleted" field . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Track changes . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Description of the main tables . . . . . . . . . . . . . . . . . . . . . . 14
Simplified diagram . . . . . . . . . . . . . . . . . . . . . . . . . 14
NmsRecipient . . . . . . . . . . . . . . . . . . . . . . . . . . 14
NmsGroup . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
NmsRcpGrpRel . . . . . . . . . . . . . . . . . . . . . . . . . . 17
NmsService . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
NmsSubscription . . . . . . . . . . . . . . . . . . . . . . . . . 19
NmsSubHisto . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
NmsDelivery . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
XtkFolder . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Delivery and tracking . . . . . . . . . . . . . . . . . . . . . . . . . 28
NmsBroadLogMsg . . . . . . . . . . . . . . . . . . . . . . . . . 28
Simulation and delivery . . . . . . . . . . . . . . . . . . . . . . . . 30
NmsSimulation . . . . . . . . . . . . . . . . . . . . . . . . . . 30
NmsDlvSimulationRel . . . . . . . . . . . . . . . . . . . . . . . . 32
NmsOfferSimulationRel . . . . . . . . . . . . . . . . . . . . . . . 32
Communication consistency and capacity rules . . . . . . . . . . . . . . . . 33
NmsTypologyRule . . . . . . . . . . . . . . . . . . . . . . . . . 33
NmsTypology . . . . . . . . . . . . . . . . . . . . . . . . . . 34
NmsTypologyRuleRel . . . . . . . . . . . . . . . . . . . . . . . . 35
NmsVolumeLine . . . . . . . . . . . . . . . . . . . . . . . . . . 35
NmsVolumeConsumed . . . . . . . . . . . . . . . . . . . . . . . 36
Response management . . . . . . . . . . . . . . . . . . . . . . . . 36
NmsRemaHypothesis . . . . . . . . . . . . . . . . . . . . . . . . 36
NmsRemaMatchRcp . . . . . . . . . . . . . . . . . . . . . . . . 39
Offer management . . . . . . . . . . . . . . . . . . . . . . . . . . 40
NmsOffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
NmsPropositionRcp . . . . . . . . . . . . . . . . . . . . . . . . 41
NmsOfferSpace . . . . . . . . . . . . . . . . . . . . . . . . . . 42
NmsOfferContext . . . . . . . . . . . . . . . . . . . . . . . . . 43
Campaign management . . . . . . . . . . . . . . . . . . . . . . . . 44
NmsOperation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
NmsDeliveryOutline . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
NmsDlvOutlineItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
NmsDeliveryCustomization . . . . . . . . . . . . . . . . . . . . . . . . . 47
NmsBudget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
NmsDocument . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
XtkWorkflow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
NmsTask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
NmsAsset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Message Center Module . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
NmsRtEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
NmsBatchEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Social Marketing Module . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
NmsVisitor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
NmsVisitorSub . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
NmsFriendShipRel . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
NmsVisitorInterestRel . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
NmsInterest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Neolap Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
XtkOlapCube . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
XtkOlapMeasure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
XtkOlapAggregate . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
XtkOlapDimension . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Microsites Module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
NmsTrackingUrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
NmsPurl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Delivery to mobile channels . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Status of messages sent via SMS according to NetSize . . . . . . . . . . . . . . . . 67
This chapter presents the architecture of the main business tables rather than internal operating tables,
as well as the specifics of the Neolane data model. The aim is to help the user understand the data model
in order to analyze data, configure new reports, perform targeting based on reactions to previous deliveries,
export data linked to a delivery and synchronize data with other systems.
10 | Neolane 2013
Neolane data model
General information
Before dealing with the data model as such, we will cover some general information.
Work tables
Work tables are created, then destroyed during application phases. The name and structure of some tables
are defined at run time (Data Management and targeting workflows, etc.), while others are persistent dynamic
tables (lists, answers to a survey, simulation results).
Table structure
Some table structures can be complex. For example:
n self-referent tables that point to themselves, such as campaign and budget tables;
n hierarchical tables such as xtkFolder for which access to information requires using the fullname
(complete tree structure).
Note:
The keys of the NmsBroadLog and NmsTrackingLogXXX tables have their own sequence.
Zero-ID record
For all the tables that use our sequence as a primary key, a record with the value 0 is inserted on
creation. This zero-ID record is used to avoid outer joins, which are not efficient for high-volume tables.
By placing the value 0 in the foreign key of a table when the data item is not populated, a join is made with
this zero-ID record, which contains no data. All queries made via the application ignore this record in results
returned. You only need to watch out for this if you implement SQL extraction procedures on the Neolane
tables.
Tip:
In workflows, you can configure the management of additional data and disable filtering. To do this, edit
additional data (in Query or Enrichment boxes, for example), click the Advanced settings link and check
the Disable automatic filtering of 0 identifier records option.
"Deleted" field
Certain tables contain an iDeleteStatus field (NmsDelivery, NmsService and NmsSubscription in
particular). This field is used for managing the Recycle Bin and performing time-consuming deletions during
the night.
The value 1 means that the record will be deleted by the cleanup workflow next time it is executed (mostly
scheduled to be executed every night). Records linked with integrity own are also deleted.
As a consequence, you should consider these records as destroyed even if they have not yet been physically
deleted from their tables.
In all the queries configured in the application, an iDeleteStatus = 0 clause is added implicitly. However,
when writing queries directly in SQL, you must take this field into consideration.
In the case of deliveries (NmsDelivery table), the value 2 means that the record is in the Recycle Bin.
Deleted deliveries are placed there by default and can be restored by the user if necessary. By default, the
cleanup task deletes the delivery after seven days. In this case, the tsDelete field gives the date on which
the record was moved to the recycle bin.
12 | Neolane 2013
Neolane data model
Track changes
Certain reserved field names enable you to track the creation and modification of certain records:
n tsCreated contains the creation date,
n tsLastModified contains the last modification date,
n iCreatedById contains the identifier of the operator who created the record (foreign key of a link to
XtkOperator),
n iModifiedById contains the ID of the last operator who modified the record (foreign key of a link to
XtkOperator).
These fields are added in the schemas using the auditTrail aggregate. Other schemas only use certain
fields. For example NmsRecipient contains tsCreated and tsLastModified only. These fields are populated
automatically for all creations and modifications made by the application: input interface, imports, web forms,
etc.
Warning:
The name of each field in the XML schema triggers this behavior, not the SQL names.
Creation and modification dates can only be changed via the Neolane console. Updates, deletions or insertions
carried out in the database and not via the console will have no effect on these dates.
Simplified diagram
The following is a diagram showing the joins between the main business tables of the Neolane data model
with the main fields shown for each.
NmsRecipient
This table matches the nms:recipient schema.
It is the default table used for the recipients of deliveries. As a result, it contains the information required
for deliveries via the various channels:
n sEmail: email address.
n iEmailFormat: preferred format for emails (1 for Text, 2 for HTML and 0 if undefined).
n sAddress1, sAddress2, sAddress3, sAddress4, sZipCode, sCity are used to build the postal address
(in keeping with the XPZ 10-011 AFNOR standard from May 1997).
n sPhone, sMobilePhone, sFax contain the phone, mobile phone and fax numbers respectively.
n iBlackList is the default opt-out flag used for the profiles (1 means "unsubscribed", 0 otherwise).
The iFolderId field is the foreign key that links the recipient to its execution folder. Refer to the description
of the XtkFolder table below for further details.
The sCountryCode field is the 3166-1 Alpha 2 ISO code (2 characters) of the country associated with the
recipient. This field is actually a foreign key on the country reference table (NmsCountry), which contains
the country labels and other country code data. If the country is not populated, the value 'XX' is stored (and
is used in place of a zero ID record).
sAccount
14 | Neolane 2013
Neolane data model
General information
Table keys
Time fields
NmsGroup
This table matches the nms:group schema.
It enables you to create statical groups of recipients. There is a many-to-many relation between recipients
and groups. For example, one recipient can belong to several groups and one group can contain several
recipients. Groups can be created manually, via an import or via delivery targeting. Groups are often used
as delivery targets. There is a unique index on the field representing the internal name of the sName group.
The group is linked to a folder (The key is iFolderId. See the description of the XtkFolder table below).
General information
16 | Neolane 2013
Neolane data model
Table keys
Time fields
NmsRcpGrpRel
The NmsRcpGrpRel relationship table only contains the two fields corresponding to the identifiers of the
iRecipientId and iGroupId linked tables.
Table keys
NmsService
This table matches the nms:service schema.
Services are entities which are similar to groups (static recipient groupings), except that they circulate more
information and enable easy management of subscriptions and unsubscriptions via forms.
There is a unique index on the field representing the internal name of the sName service. The service is
linked to a folder (The key is iFolderId. See the description of the XtkFolder table below). Finally, the
iType field specifies the delivery channel of this service (0 for email, 1 for SMS, 2 for telephone, 3 for direct
mail and 4 for fax).
General information
18 | Neolane 2013
Neolane data model
Table keys
Time fields
NmsSubscription
This table matches the nms:subscription schema.
It enables you to manage recipient subscriptions to information services.
General information
Table keys
Time fields
NmsSubHisto
This table matches the nms:subHisto schema.
If the subscriptions are managed using web forms or the interface of the application, all susbcriptions and
unsubscriptions are historized in the NmsSubHisto table. The iAction field specifies the action (0 for
unsubscription and 1 for subscription) performed on the date stored in the tsDate field.
General information
Table keys
Time fields
NmsDelivery
This table matches the nms:delivery schema.
Each record in this table represents a delivery action or a delivery template. It contains all the necessary
parameters for performing deliveries (the target, the content, etc.). Delivery (broadcast) logs (NmsBroadLog)
and associated tracking URLs (NmsTrackingUrl) are created during the analysis phase (see below for
further details on both of these tables).
There is a unique index on the field representing the internal name of the sInternalName delivery or
scenario. The delivery is linked to an execution folder (The foreign key is iFolderProcessId. See the
description of the XtkFolder table below).
General information
20 | Neolane 2013
Neolane data model
22 | Neolane 2013
Neolane data model
24 | Neolane 2013
Neolane data model
Table keys
Time fields
26 | Neolane 2013
Neolane data model
XtkFolder
It contains all the folders in the tree visible in the Navigation tab of the console.
The folders are typed: The value of the sModel field specifies the type of data that can be contained in the
folder. This field also enables the client console to display the data correctly with the corresponding forms.
The possible values for this field are defined in the navTree.
The tree is managed by the iParentId and iChildCount fields. The sFullName field gives the full path of
the folder in the tree. Finally, there is a unique index on the field representing the internal name of the
sName folder.
General information
Table keys
Time fields
NmsBroadLogMsg
This table matches the nms:broadLogMsg schema.
It is an extension of the delivery log table.
General information
28 | Neolane 2013
Neolane data model
Table keys
Time fields
NmsSimulation
This table matches the nms:simulation schema.
It represents a simulation for a set of deliveries or offers on a given population.
General information
30 | Neolane 2013
Neolane data model
Table keys
Time fields
NmsDlvSimulationRel
This table matches the nms:dlvSimulationRel schema.
It contains the list of deliveries taken into account in the simulation.
The scope of the simulation is stored in XML.
General information
Table keys
NmsOfferSimulationRel
This table matches the nms:offerSimulationRel schema. It lets you link up a simulation with an offer.
General information
Table keys
32 | Neolane 2013
Neolane data model
NmsTypologyRule
This table matches the nms:typologyRule schema.
It contains the rules which apply to deliveries depending on typologies.
General information
Table keys
Time fields
NmsTypology
This table matches the nms:typology schema.
It contains the set of rules to be applied to deliveries which match the typology.
General information
Table keys
34 | Neolane 2013
Neolane data model
Time fields
NmsTypologyRuleRel
This table matches the nms:typologyRuleRel schema.
It contains the relationships between typologies and their rules.
Table keys
NmsVolumeLine
This table matches the nms:volumeLine schema.
It contains the set of availability lines of the capacity rules.
General information
Table keys
Time fields
NmsVolumeConsumed
This table matches the nms:volumeConsumed schema.
It contains all the consumption lines of the capacity rules.
General information
Table keys
Time fields
Response management
NmsRemaHypothesis
This table coincides with the nms:remaHypothesis schema.
36 | Neolane 2013
Neolane data model
General information
38 | Neolane 2013
Neolane data model
Table keys
Time fields
NmsRemaMatchRcp
This table matches the nms:remaMatchRcp schema.
It contains a record representing an individual's reaction to a given hypothesis. These records were created
during hypothesis execution.
General information
Table keys
Offer management
NmsOffer
This table matches the nms:offer schema.
It contains the definition of each marketing offer.
General information
40 | Neolane 2013
Neolane data model
Table keys
Time fields
NmsPropositionRcp
This table matches the nms:propositionRcp schema.
It contains the cross-channel log of marketing propositions sent to each individual. The record is created
when a proposition is prepared or effectively made to an individual.
General information
Table keys
Time fields
NmsOfferSpace
This table matches the nms:offerSpace schema.
It contains the definition of locations on which propositions are made.
General information
42 | Neolane 2013
Neolane data model
Table keys
Time fields
NmsOfferContext
This table matches the nms:offerContext schema.
It contains additional criteria on the applicability of the proposition as well as the definition of the weight
calculation formula.
General information
Table keys
Time fields
Campaign management
NmsOperation
This table matches the nms:operation schema. It contains the data of marketing campaigns.
General information
44 | Neolane 2013
Neolane data model
Table keys
Time fields
NmsDeliveryOutline
This table matches the nms:deliveryOutline schema. It contains the extended properties of the delivery
(delivery outline).
General information
46 | Neolane 2013
Neolane data model
Table keys
NmsDlvOutlineItem
This table matches the nms:dlvOutlineItem schema. It contains the articles of a delivery outline.
General information
Table keys
NmsDeliveryCustomization
This table matches the nms:deliveryCustomization schema. It contains the personalization fields of a
delivery.
General information
Table keys
NmsBudget
This table matches the nms:budget schema. It contains the data of a budget on a campaign, a plan, a
program, a task and/or deliveries.
General information
Table keys
Time fields
48 | Neolane 2013
Neolane data model
NmsDocument
This table matches the nms:document schema. It contains the marketing documents of the campaign in
the form of files (images, excel or word files, etc.)
General information
Table keys
Time fields
XtkWorkflow
This table matches the xtk:workflow schema. It contains campaign targeting.
General information
50 | Neolane 2013
Neolane data model
Table keys
Time fields
NmsTask
This table matches the nms:task schema. It contains the definition of a marketing task.
General information
52 | Neolane 2013
Neolane data model
Table keys
Time fields
NmsAsset
This table matches the nms:asset schema. It contains the definition of a marketing resource.
General information
Table keys
54 | Neolane 2013
Neolane data model
Time fields
NmsRtEvent
Figure 1.1.
General information
Table keys
Time fields
56 | Neolane 2013
Neolane data model
NmsBatchEvent
Figure 1.2.
General information
Table keys
Time fields
58 | Neolane 2013
Neolane data model
NmsVisitor
This table matches the nms:visitor schema. It contains the information on visitors.
General information
Table keys
Time fields
NmsVisitorSub
This table matches the nms:visitorSub schema. It enables you to link up a visitor to the services which
they have subscribed to (Twitter or Facebook).
Table keys
Time fields
NmsFriendShipRel
This table matches the nms:friendshipRel schema. It enables you to link up visitors with their friends
within the context of the Facebook service.
60 | Neolane 2013
Neolane data model
Table keys
NmsVisitorInterestRel
This table matches the nms:visitorInterestRel schema. It enables you to link up visitors and their interests.
Table keys
NmsInterest
This table matches the nms:interest schema. It contains the list of interests for each visitor.
General information
Neolap Module
XtkOlapCube
This table matches the xtk:olapCube schema. It contains the general information for describing the Cube,
particularly its type (iType field) as well as the fact tables which define the input data (sSchema table).
General information
Table keys
62 | Neolane 2013
Neolane data model
Time fields
XtkOlapMeasure
This table matches the xtk:olapMeasure schema. It contains the list of measures used by the Cube as well
as their respective units (sUnit field).
General information
Table keys
Time fields
XtkOlapAggregate
This table matches the xtk:olapAggregate schema. It contains the list of aggregates designed to optimize
calculation for large volumes of data.
General information
Table keys
Time fields
XtkOlapDimension
This table matches the xtk:olapDimension schema. It contains the various dimensions defined for the
Cube.
General information
Table keys
Time fields
64 | Neolane 2013
Neolane data model
Microsites Module
NmsTrackingUrl
This table matches the nms:trackingUrl schema.
General information
Table keys
Time fields
NmsPurl
This table matches the nms:purl schema.
General information
Table keys
66 | Neolane 2013
Neolane data model
Time fields
Table of Contents
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Syntax of schemas . . . . . . . . . . . . . . . . . . . . . . . . . 70
Identification of a schema . . . . . . . . . . . . . . . . . . . . . . 71
Schema structure . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Description . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Data types . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Collections . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Referencing with XPath . . . . . . . . . . . . . . . . . . . . . . . 77
Building a string via the compute string . . . . . . . . . . . . . . . . . 78
Database mapping . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Description . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
XML fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
Calculated fields . . . . . . . . . . . . . . . . . . . . . . . . . 80
Indexed fields . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Management of keys . . . . . . . . . . . . . . . . . . . . . . . . 81
Links: relation between tables . . . . . . . . . . . . . . . . . . . . . 84
Dictionary of elements and attributes . . . . . . . . . . . . . . . . . . . 87
<attribute> element . . . . . . . . . . . . . . . . . . . . . . . . 87
<compute-string> element . . . . . . . . . . . . . . . . . . . . . . 91
<condition> element . . . . . . . . . . . . . . . . . . . . . . . . 92
<dbindex> element . . . . . . . . . . . . . . . . . . . . . . . . 93
<element> element . . . . . . . . . . . . . . . . . . . . . . . . 95
<enumeration> element . . . . . . . . . . . . . . . . . . . . . . 100
<help> element . . . . . . . . . . . . . . . . . . . . . . . . . 102
<join> element . . . . . . . . . . . . . . . . . . . . . . . . . 103
<key> element . . . . . . . . . . . . . . . . . . . . . . . . . 104
<keyfield> element . . . . . . . . . . . . . . . . . . . . . . . . 106
<method> element . . . . . . . . . . . . . . . . . . . . . . . . 107
<methods> element . . . . . . . . . . . . . . . . . . . . . . . 109
<param> element . . . . . . . . . . . . . . . . . . . . . . . . 110
<parameters> element . . . . . . . . . . . . . . . . . . . . . . . 112
<srcSchema> element . . . . . . . . . . . . . . . . . . . . . . . 113
<sysFilter> element . . . . . . . . . . . . . . . . . . . . . . . . 115
<value> element . . . . . . . . . . . . . . . . . . . . . . . . . 116
Introduction
This chapter describes how to configure extension schemas in order to extend the conceptual data model
of the Neolane database.
Overview
The physical and logical structure of the data carried in the application is described in XML. It obeys a grammar
specific to Neolane, called a schema.
A schema is an XML document associated with a database table. It defines data structure and describes the
SQL definition of the table:
n The name of the table,
n Fields,
n Indexes,
n Links with other tables,
It also describes the XML structure used to store data:
n Elements and attributes,
n Hierarchy of elements,
n Element and attribute types,
n Default values,
n Labels, descriptions, and other properties.
Schemas enable you to define an entity in the database. There is a schema for each entity.
The following illustration shows the location of schemas in the Neolane data system:
Syntax of schemas
The root element of the schema is <srcSchema>. It contains the <element> and <attribute>
sub-elements.
The first <element> sub-element coincides with the root of the entity.
<srcSchema name="recipient" namespace="cus">
<element name="recipient">
<attribute name="lastName"/>
<attribute name="email"/>
<element name="location">
<attribute name="city"/>
</element>
</element>
</srcSchema>
70 | Neolane 2013
Schema Reference (xtk:srcSchema)
Note:
The root element of the entity has the same name as the schema.
The <element> tags define the names of entity elements. <attribute> tags of the schema define the
names of the attributes in the <element> tags which they have been linked to.
Identification of a schema
A data schema is identified by its name and its namespace.
A namespace lets you group a set of schemas by area of interest. For example, the cus namespace is used
for customer-specific configuration (customers).
Warning:
As a standard, the name of the namespace must be concise and must contain only authorized characters in
accordance with XML naming rules.
Identifiers must not begin with numeric characters.
Certain namespaces are reserved for descriptions of the system entities required for the operation of the
Neolane application:
n xtk: concerning platform system data,
n nl: concerning the overall use of the application,
n nms: concerning delivery (recipient, delivery, tracking, etc.),
n ncm: concerning content management,
n temp: reserved for temporary schemas.
The identification key of a schema is a string built using the namespace and the name separated by a colon;
for example: cus:recipient.
Schema structure
The basic structure of an <srcSchema> is as follows:
<srcSchema>
<enumeration>
... //definition of enumerations
</enumeration>
</element>
</srcSchema>
The XML document of a data schema must contain the <srcSchema> root element with the name and
namespace attributes to populate the schema name and its namespace.
<srcSchema name="schema_name" namespace="namespace">
...
</srcSchema>
Let us use the following XML content to illustrate the structure of a data schema:
<recipient email="John.doe@aol.com" created="2009/03/12" gender="1">
<location city="London"/>
</recipient>
72 | Neolane 2013
Schema Reference (xtk:srcSchema)
Description
The point of entry of the schema is its main element. It is easy to identify because it has the same name as
the schema, and it should be the child of the root element. The description of the content begins with this
element.
In our example, the main element is represented by the following line:
<element name="recipient">
The elements <attribute> and <element> that follow the main element enable you to define the locations
and names of the data items in the XML structure.
In our sample schema, these are:
<attribute name="email"/>
<attribute name="created"/>
<attribute name="gender"/>
<element name="location">
<attribute name="city"/>
</element>
Warning:
The name of the element should be concise, preferably in English, and include only authorized characters
in accordance with XML naming rules.
n Only <element> elements can contain <attribute> elements and <element> elements in the XML
structure.
n An <attribute> element must have a unique name within an <element>.
n The use of <elements> in multi-line data strings is recommended.
Data types
The data type is entered via the type attribute in the <attribute> and <element> elements.
A detailed list is available in the description of the <attribute> element [page 87] and the <element> element
[page 95]
When this attribute is not populated, string is the default data type unless the element contains child
elements. If it does, it is used only to structure the elements hierarchically (<location> element in our
example).
The following data types are supported in schemas:
n string: character string. Examples: a first name, a town, etc.
The size can be specified via the length attribute (optional, default value "255").
n boolean: Boolean field. Example of possible values: true/false, 0/1, yes/no, etc.
n byte, short, long: integers (1 byte, 2 bytes, 4 bytes). Examples: an age, an account number, a number
of points, etc.
n double: double-precision floating point number. Examples: a price, a rate, etc.
n date, datetime: dates and dates + times. Examples: a birth date, a purchase date, etc.
n timespan: durations. Example: seniority.
n memo: long text fields (multiple lines). Examples: a description, a comment, etc.
n uuid: "uniqueidentifier" fields to support a GUID (supported in SQL Server only).
Note:
To contain a uuid field in engines other than SQL Server, the "newuuid()" function must be added and
completed with its default value.
Memo TEXT CLOB (NCLOB si Uni- CLOB (CLOB CHARAC- CLOB(6M) TEXT (NTEXT si Uni-
code) TER SET UNICODE si code)
Unicode)
Properties
The <elements> and <attributes> elements of the data schema can be enriched with various properties.
You can populate a label in order to describe the current element.
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:
74 | Neolane 2013
Schema Reference (xtk:srcSchema)
Note:
The description is associated with the current language of the instance.
Example :
<attribute name="email" type="string" length="80" label="Email" desc="Email of
recipient"/>
Default values
The default property lets you define an expression returning a default value on content creation.
The value must be an expression compliant with XPath language. For more on this, refer to Referencing with
XPath [page 77].
Example :
n Current date: default="GetDate()"
n Counter: default="'FRM'+CounterValue('myCounter')"
In this example, the default value is constructed using the concatenation of a string and calling the
CounterValue function with a free counter name. The number returned is incremented by one at each
insertion.
Note:
In the Neolane client console, the Administration>Counters node is used to manage counters.
Enumerations
Free enumeration
The userEnum property lets you define a free enumeration to memorize and display the values entered via
this field. The syntax is as follows:
userEnum="name of enumeration"
The name given to the enumeration can be chosen freely and shared with other fields.
These values are shown in a drop-down list from the input form:
Note:
In the Neolane client console, the Administration>Enumerations node is used to manage enumerations.
Set enumeration
The enum property lets you define a fixed enumeration used when the list of possible values is known in
advance.
The enum attribute refers to the definition of an enumeration class populated in the schema outside the
main element.
Enumerations allow the user to select a value from a drop-down list instead of entering the value in a regular
input field:
An enumeration is declared outside the main element via the <enumeration> element.
The enumeration properties are as follows:
n baseType: type of data associated with the values,
n label: description of the enumeration,
n name: name of the enumeration,
n default: default value of the enumeration.
The enumeration values are declared in the <value> element with the following attributes:
n name: name of the value stored internally,
n label: label displayed via the graphical interface.
dbenum enumeration
n The dbenum property lets you define an enumeration whose properties are similar to those of the enum
property.
However, the name attribute does not store the value internally, it stores a code which lets you extend
the concerned tables without modifying their schema.
The values are defined via the Administration>Enumerations node.
This enumeration is used for specifying the nature of campaigns, for example.
Example
Here is our example schema with the properties filled in:
<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
76 | Neolane 2013
Schema Reference (xtk:srcSchema)
recipient"/>
<attribute name="created" type="datetime" label="Date of creation" default="GetDate()"/>
Collections
A collection is a list of elements with the same name and the same hierarchical level.
The unbound attribute with the value "true" lets you populate a collection element.
Example: definition of the <group> collection element in the schema.
<element name="group" unbound="true" label="List of groups">
<attribute name="label" type="string" label="Label"/>
</element>
Note:
An additional constraint is added when the path crosses a sub-element. In this case, the following expression
must be placed between brackets:
n location/@city is not valid; please use [location/@city]
n [@email] and @email are equivalent
It is also possible to define complex expressions, such as the following arithmetic operations:
n @gender+1: adds 1 to the content of the gender attribute,
n @email + '('+@created+')': constructs a string by taking the value of the e-mail address added
to the creation date between parentheses (for the string type, put the constant in quotes).
High-level functions have been added to the expressions in order to enrich the potential of this language.
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.
Note:
If the schema does not contain a Compute string, a Compute string is populated by default with the values
of the primary key of the schema.
Database mapping
The SQL mapping of our example schema gives the following XML document:
<schema mappingType="sql" name="recipient" namespace="cus" xtkschema="xtk:schema">
<enumeration basetype="byte" name="gender">
<value label="Not specified" name="unknown" value="0"/>
<value label="Male" name="male" value="1"/>
<value label="Female" name="female" value="2"/>
</enumeration>
78 | Neolane 2013
Schema Reference (xtk:srcSchema)
userEnum="city"/>
</element>
</element>
</schema>
Description
The root element of the schema is no longer <srcSchema>, but <schema>.
This takes us to another type of document, which is generated automatically from the source schema, simply
referred to as the schema. This schema will be used by the Neolane application.
The SQL names are determined automatically based on element name and type.
The SQL naming rules are as follows:
n table: concatenation of the schema namespace and name
In our example, the name of the table is entered via the main element of the schema in the sqltable
attribute:
<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);
XML fields
By default, any typed <attribute> and <element> element is mapped onto an SQL field of the data
schema table. You can, however, reference this field in XML instead of SQL, which means that the data is
stored in a memo field ("mData") of the table containing the values of all XML fields. The storage of these
data is an XML document that observes the schema structure.
To populate a field in XML, you must add the xml attribute with the value "true" to the element concerned.
Example: here are two examples of XML field use.
n Multi-line comment field:
<element name="comment" xml="true" type="memo" label="Comment"/>
The "html" type lets you store the HTML content in a CDATA tag and display a special HTML edit check
in the Neolane client interface.
The use of XML fields lets you add fields without needing to modify the physical structure of the database.
Another advantage is that you use less resources (size allocated to SQL fields, limit on the number of fields
per table, etc.).
The main disadvantage is that it is impossible to index or filter an XML field.
Calculated fields
A calculated field is not stored physically in the table; it is a data item that is calculated dynamically when
the query is submitted.
There are two types of calculated fields: SQL calculated fields and XML calculated fields.
1 SQL calculated field: the data is calculated by the database engine from a simple expression. This
type of field is well suited to extracting a substring in order to display the domain of an e-mail address
or to calculate the age by subtracting the date of birth from the current date.
Note:
SQL expressions can be used directly via the [SQLDATA[expression_sql]] escape sequence. This
syntax must be used with care, however, because the populated SQL depends on the engine of the
current database.
2 XML calculated field: lets you use a more complex expression with XML fields or conditional tests. The
expression is evaluated by the application layer on receipt of the query data.
The disadvantage of using XML calculated fields is that not all SQL functions of the XPath expressions
are supported.
A calculated field must populate the expr attribute containing the expression to be submitted.
A calculated field is SQL type by default. To declare an XML calculated field, add the xml attribute (with the
value set to "true").
Example :
n Returns the e-mail domain:
<attribute expr="GetEmailDomain(@email)" label="Email domain" name="domain"/>
Indexed fields
Indexes let you optimize the performance of the SQL queries used in the application.
An index is declared from the main element of the data schema.
<dbindex name="name_of_index" unique="true/false">
<keyfield xpath="xpath_of_field1"/>
<keyfield xpath="xpath_of_field2"/>
...
</key>
Note:
As a standard, indexes are the first elements declared from the main element of the schema.
80 | Neolane 2013
Schema Reference (xtk:srcSchema)
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>
<dbindex name="email">
<keyfield xpath="@email"/>
</dbindex>
Management of keys
A table must have at least one key for identifying a record in the table.
A key is declared from the main element of the data schema.
<key name="name_of_key">
<keyfield xpath="xpath_of_field1"/>
<keyfield xpath="xpath_of_field2"/>
...
</key>
Note:
As a standard, keys are the elements declared from the main element of the schema after indexes have been
defined.
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>
<key name="email">
<keyfield xpath="@email"/>
<keyfield xpath="location/@city"/>
</key>
82 | Neolane 2013
Schema Reference (xtk:srcSchema)
Auto-incremental key
The primary key of most Neolane tables is a 32-bit long integer auto-generated by the database engine. The
calculation of the key value depends on a sequence (by default, the XtkNewId SQL function) generating a
number that is unique in the entire database. The content of the key is automatically entered on insertion
of the record.
The advantage of an incremental key is that it provides a non-modifiable technical key for the joins between
tables. In addition, this key does not occupy much memory because it uses a double-byte integer.
From version 4.05 onwards, in the source schema you can specify the name of the sequence to be used
with the pkSequence attribute. If this attribute is not given in the source schema, the XtkNewId default
sequence will be used. The application uses dedicated sequences for the nms:broadLog and
nms:trackingLog schemas (NmsBroadLogId and NmsTrackingLogId respectively) because these are
the tables that contain the most records.
Note:
A sequence referenced in a Neolane schema (NmsTrackingLogId for example) must be associated to a
SQL function that returns the number of IDs in the parameters, separated by commas. This function must
be called GetNewXXXIds, where XXX is the name of the sequence (GetNewNmsTrackingLogIds for
example). View the postgres-nms.sql, mssql-nms.sql or oracle-nms.sql files provided with the appliation
in the datakit/nms/fra/sql/ directory to recover the example of a 'NmsTrackingLogId' sequence creation
for each database engine.
To declare an auto-incremental key, populate the autopk attribute (with value "true") on the main element
of the data schema.
Example :
Declaring an incremental key in the source schema:
<srcSchema name="recipient" namespace="cus">
<element name="recipient" autopk="true">
...
</element>
</srcSchema>
In addition to the definition of the key and its index, a numeric field called "id" has been added to the extended
schema in order to contain the auto-generated primary key.
Important:
A record with a primary key set to 0 is automatically inserted on creation of the table. This record is used to
avoid outer joins, which are not effective on volume tables. By default, all foreign keys are initialized with
value 0 so that a result can always be returned on the join when the data item is not populated.
84 | Neolane 2013
Schema Reference (xtk:srcSchema)
Note:
As a standard, links are the elements declared at the end of the schema.
Example 1
1-N relation to the "cus:company" schema table:
<srcSchema name="recipient" namespace="cus">
<element name="recipient">
...
<element label="Company" name="company" revIntegrity="define" revLabel="Contact"
target="cus:company" type="link"/>
</element>
</srcSchema>
The link definition is supplemented by the fields making up the join, i.e. the primary key with its XPath ("@id")
in the destination schema, and the foreign key with its XPath ("@company-id") in the schema.
The foreign key is added automatically in an element that uses the same characteristics as the associated
field in the destination table, with the following naming convention: name of target schema followed by name
of associated field ("company-id" in our example).
Extended schema of the target ("cus:company"):
<schema mappingType="sql" name="company" namespace="cus" xtkschema="xtk:schema">
<element name="company" sqltable="CusCompany" autopk="true">
<dbindex 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 the
source schema).
Example 2
In this example, we will declare a link towards the "nms:address" schema table. The join is an outer join and
is populated explicitly with the recipient's e-mail address and the "@address" field of the linked table
("nms:address").
<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 3
1-1 relation to the "cus:extension" schema table:
<element integrity="own" label="Extension" name="extension" revCardinality="single"
revLink="recipient" target="cus:extension" type="link"/>
Example 4
Link to a folder ("xtk:folder" schema):
<element default="DefaultFolder('nmsFolder')" label="Folder" name="folder"
revDesc="Recipients in the folder" revIntegrity="own" revLabel="Recipients"
target="xtk:folder" type="link"/>
The default value returns the identifier of the first eligible parameter type file entered in the
"DefaultFolder('nmsFolder')" function.
Example 5
In this example, we wish to create a key on a link ("company" to "cus:company" schema) with the xlink
attribute and a field of the ("email") table:
<srcSchema name="recipient" namespace="cus">
<element name="recipient">
<key name="companyEmail">
<keyfield xpath="@email"/>
<keyfield xlink="company"/>
<key>
<key name="companyEmail">
<keyfield xpath="@email"/>
<keyfield xpath="@company-id"/>
</key>
86 | Neolane 2013
Schema Reference (xtk:srcSchema)
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.
<attribute> element
Content model
attribute:==help
Attributes
_operation (string), advanced (boolean), applicableIf (string), autoIncrement (boolean), belongsTo (string),
dataPolicy (string), dbEnum (string), defOnDuplicate (boolean), default (string), desc (string), edit (string),
enum (string), expr (string), feature (string), featureDate (boolean), img (string), inout (string), label (string),
length (string), localizable (boolean), name (MNTOKEN), notNull (boolean), pkgStatus (string), ref (string),
required (boolean), sql (boolean), sqlDefault (string), sqlname (string), sqltable (string), target (MNTOKEN),
template (string), translatedDefault (string), translatedExpr (string), type (MNTOKEN), user (boolean),
userEnum (string), visibleIf (string), xml (boolean)
Parents
<element>
Children
<help>
Description
<Attribute> elements let you define a field in the database.
Attribute description
n _operation (string): defines the type of writing in the database.
This attribute is mainly used when extending out-of-the-box schemas.
Accessible values are:
n "none": reconciliation alone. This means that Neolane will recover the element without updating it
or generating an error if it doesn't exist.
n "insertOrUpdate": update with insertion. This means that Neolane will update the element or create
it if it doesn't exist.
n "insert": insertion. This means that Neolane will insert the element without checking whether it exists.
n "update": update. This means that Neolane will update the element or generate an error if it doesn't
exist.
n "delete": deletion. This means that Neolane will recover and delete elements.
n advanced (boolean): when this option is activated (@advanced="true"), it lets you hide the attribute
on the list of available fields accessible for configuring a list in a form.
n applicableIf (string): this attribute lets you make fields optional. The <attribute> element will be
taken into account when updating the database when the constraint is complied with. "applicableIf"
receives an XTK expression.
n autoIncrement (boolean): if this option is activated, the field becomes a counter. This enables you
to increment a value (mostly IDs). (external use)
n belongsTo (string): takes the name and namespace of the table that shares the field, and populates
the schema where the attribute is declared. (used only in a <schema>).
n dataPolicy (string): enables you to specify approval constraints on values allowed in the SQL or XML
field. The values for this attribute are:
n "none": no value
n "smartCase": first letters upper case
n "lowerCase": all lower case
n "upperCase": all upper case
n "email": email adress
n "phone": telephone number
n "identifier": identifier name
n "resIdentifier": file name
n dbEnum (string): receives the internal name of a "closed" enumeration. The enumeration values must
be defined in the <srcSchema>.
n defOnDuplicate (boolean): if this attribute is activated, when a record is duplicated the default value
(defined in @default) is automatically reapplied to the record.
n default (string): lets you define the value of the default field (call to a function, default value). This
attribute receives an XTK expression.
n desc (string): lets you insert a description of the attribute. This description is displayed in the status
bar of the interface.
n edit (string): this attribute specifies the type of input which will be used in the form linked to the
schema.
n enum (string): receives the name of the enumeration linked to the field. The enumeration can be
inserted into the same schema or into a remote schema.
n expr (string): defines a field precalculation expression. This attribute receives an Xpath or an XTK
expression.
n feature (string): defines a characteristics field: These fields are used for extending the data in an
existing table, but with storage in an annex table. Accepted values are:
n "shared": the content is stored in a shared table per data type
n "dedicated": the content is stored in a dedicated table
SQL characteristics tables are built automatically based on the characteristic type:
n dedicated: Ft_[name_of_the_schema_containing_the_characteristic]_[name_of_the_characteristic]
n shared: Ft_[type_of_key_of_the_schema_containing_the_characteristic]_[type_of_the_characteristic]
There are two types of characteristics fields: simple o fields where a single value is authorized on the
characteristic, and o multiple choice fields, where the characteristic is linked to a collection element
which may contain several values.
When a characteristic is defined in a schema, this schema must have a main key based on a single field
(composite keys are not authorized).
n featureDate (boolean): attribute linked to the "@feature" characteristics field. If its value is "true", it
lets you find out when the value was last updated.
n img (string): lets you define a path for an image linked to a field (namespace + image name)(example:
img="cus:mypicture.jpg"). Physically, the image must be imported to the application server.
n label (string): label linked to the field, mostly destined to the user in the interface. It lets you avoid
naming constraints.
n length (string): max. number of characters for a value of the "string" type SQL field. If the "@length"
attribute isn't specified, Neolane automatically creates a field for 255 characters.
88 | Neolane 2013
Schema Reference (xtk:srcSchema)
n localizable (boolean): if it is activated, this attribute tells the collection tool to recover the value of
the "@label" attribute for translation (internal use).
n name (MNTOKEN): name of the attribute that will match the name of the field in the table. The value
of the "@name" attribute must be short, preferably in english, and comply with XML naming constraints.
When the schema is written to the database, prefixes are automatically added to the field name by
Neolane:
n "i": prefix for the 'integer' type.
n "d": prefix for the 'double' type.
n "s": prefix for the character string type.
n "ts": prefix for the 'date' type.
To fully define the name of the field in the table, use the "@sqlname" option when defining an attribute.
n notNull (boolean): lets you redefine Neolane's behavior regarding the management of NULL records
in the database. By default, numeric fields are not null and string and date type fields can be null.
n pkgStatus (string): during package exports, values are taken into account depending on the value of
the "@pkgStatus":
n "always": always present
n "never": never present
n "default (or nothing)": the value is exported except if it's the default value or if it isn't an internal
field which would not be compatible with other instances.
n ref (string): this attribute defines a reference to an <attribute> element shared by several schemas
(definition factoring). The definition isn't copied into the current schema.
n required (boolean): if this attribute is activated (@required="true"), the field is highlighted in the
interface. The label of the field will be red in forms.
n sql (boolean): if this attribute is activated (@sql="true"), it forces storage of the SQL attribute, even
when the element which contains the attribute has the xml="true" property.
n sqlDefault (string): this attribute enables you to define the default value taken into account for updating
the database if the @notNull attribute is activated.
n sqlname (string): of the field during table creation. If @sqlname isn't specified, the value of the
"@name" attribute is used by default. When the schema is written in the database, prefixes are added
automatically depending on the type of field.
n template (string): this attribute defines a reference to an <attribute> element shared by several
schemas. The definition is automatically copied into the current schema.
n translatedDefault (string): if a "@default" attribute is found, the "@translatedDefault" will enable
you to redefine an expression to match the one defined in @default, to be collected by the translation
tool (internal use).
n translatedExpr (string): if an "@expr" attribute is present, the "@translatedExpr" attibute enables
you to redefine an expression to match the one defined in @expr, to be collected by the translation tool
(internal use).
n type (MNTOKEN): field type.
Field types are generic. Depending on the type of database installed, NEOLANE changes the defined type
into a value specific to the database installed during structure update.
List of available types:
n ANY
n bin
n blob
n boolean
n byte
n CDATA
n datetime
n datetimetz
n datetimenotz
n date
n double
n enum
n float
n html
n int64
n link
n long
n memo
n MNTOKEN
n money
n percent
n primarykey
n short
n string
n time
n timespan
n uuid
If the "@type" attribute is left empty, Neolane will link a string of characters (STRING) with a length of
100 to the field by default.
If the field is of STRING type and the name of the field isn't specified by the presence of the "@sqlname"
attribute, the name of the field in the database will automatically be preceded by an 's'. This operating
mode will be similar with INTEGER (i), DOUBLE (d) and DATES (ts) type fields.
n userEnum (string): receives the internal name of an "open" enumeration. The values of the enumeration
can be defined by the user in the interface.
n visibleIf (string): defines a condition in the form of an XTK expression to show or hide the attribute.
n xml (boolean): if this option is activated, the values of the field don't have a linked SQL field. Neolane
creates a Text type "mData" field for record storage. This means there is not filtering or sorting on these
fields.
Examples
Example of enumeration values whose values are stored in the database:
<enumeration name="myEnum">
<value name="One" value="1"/>
<value name="Two" value="2"/>
</enumeration>
</element>
Example with an "@applicableIf": the "contains" attribute will only be created if the number of countries is
greater than 20.
90 | Neolane 2013
Schema Reference (xtk:srcSchema)
<compute-string> element
Content model
compute-string:==EMPTY
Attributes
@expr
Parents
<element>
Children
None
Description
The <compute-string> element enables you to generate a string based on an XTK expression to display a
"built" label in the interface based on several values.
Attribute description
n expr (string): XTK and/or Xpath expression
Examples
<compute-string expr="@label + Iif(@code='','', ' (' + [folder/@label] + ')')"/
<element name="recipient">
<compute-string expr="@lastName + ' ' + @firstName +' (' + @email + ')'
"/>
...
</element>
<condition> element
Content model
condition:==EMPTY
Attributes
n @boolOperator (string)
n @enabledIf (string)
n @expr (string)
Parents
<sysFilter>
Children
None
Description
This element lets you define a filtering condition.
Attribute description
n boolOperator (string): if several <conditions> are defined within the same <sysFilter> element, this
attribute lets you combine them. By default, the logical link is between <condition> elements is "AND".
The "@boolOperator" attribute lets you combine "OR" and "AND" type links.
n enabledIf (string): condition activation test.
n expr (string): an XTK expression.
Examples
<sysFilter inline="true"
<condition expr="@city=[currentOperator/location/@city]"
enabledIf="hasNamedRight('admin')=false"/
</sysFilter
92 | Neolane 2013
Schema Reference (xtk:srcSchema)
<dbindex> element
Content model
dbindex:==keyfield
Attributes
n @_operation (string)
n @applicableIf (string)
n @label (string)
n @name (MNTOKEN)
n @unique (boolean)
Parents
<element>
Children
<keyfield>
Description
This element lets you define an index linked to a table.
Attribute description
n _operation (string): defines the type of writing in the database.
This attribute is mainly used when extending out-of-the-box schemas.
Accessible values are:
n "none": reconciliation alone. This means that Neolane will recover the element without updating it
or generating an error if it doesn't exist.
n "insertOrUpdate": update with insertion. This means that Neolane will update the element or create
it if it doesn't exist.
n "insert": insertion. This means that Neolane will insert the element without checking whether it exists.
n "update": update. This means that Neolane will update the element or generate an error if it doesn't
exist.
n "delete": deletion. This means that Neolane will recover and delete elements.
n applicableIf (string): condition for taking the index into account - receives an XTK expression.
n label (string): index label.
n name (MNTOKEN): unique index name.
n unique (boolean): if this option is activated (@unique="true"), the attribute guarantees the uniqueness
of the index throughout its fields.
Examples
Creation of an index on the "id" field. (the "@unique" attribute on the <dbindex> element triggers adding
of the "UNIQUE" SQL key word when the index is created in the database (query)).
</dbindex>
<attribute name="id" type="long"/>
</element>
94 | Neolane 2013
Schema Reference (xtk:srcSchema)
<element> element
Content model
element:==(attribute | compute-string | dbindex | default | element | help | join | key | sysFilter |
translatedDefault)
Attributes
_operation (string), advanced (boolean), aggregate (string), applicableIf (string), autopk (boolean), belongsTo
(string), convDate (string), dataPolicy (string), dataSource (string), dbEnum (string), defOnDuplicate (boolean),
default (string), desc (string), displayAsField (boolean), doesNotSupportDiff (boolean), edit (string),
emptyKeyValue (string), enum (string), enumImage (string), expandSchemaTarget (string), expr (string),
externalJoin (boolean), feature (string), featureDate (boolean), filterPath (string), folderLink (string),
folderModel (string), folderProcess (string), fullLoad (boolean), hierarchical (boolean), hierarchicalPath (string),
img (string), inout (string), integrity (string), label (string), labelSingular (string), length (string), localizable
(boolean), name (MNTOKEN), noDbIndex (boolean), noKey (boolean), ordered (boolean), overflowtable
(boolean), pkSequence (string), pkgStatus (string), ref (string), required (boolean), revAdvanced (boolean),
revCardinality (string), revDesc (string), revExternalJoin (boolean), revIntegrity (string), revLabel (string),
revLink (string), revTarget (string), revVisibleIf (string), sql (boolean), sqlname (string), sqltable (string),
tableSpace (string), tableSpaceIndex (string), target (MNTOKEN), template (string), temporaryTable (boolean),
translatedDefault (string), translatedExpr (string), type (MNTOKEN), unbound (boolean), user (boolean),
userEnum (string), visibleIf (string), xml (boolean), xmlChildren (boolean)
Parents
<srcSchema>
<element>
Children
n <attribute>
n <compute-string>
n <dbindex>
n <default>
n <element>
n <help>
n <join>
n <key>
n <sysFilter>
n <translatedDefault>
Description
There are four types of <element> elements in Neolane:
n Root <element>: defines the name of the SQL table that matches the schema.
n Structure <element>: defines a group of <element> or <attribute> elements.
n Link <element>: defines a link. This elements must include the "@type=link" attribute.
n XML <element>: defines a Text type "mData" field. This element must include the "@type=xml" attribute.
Attribute description
n _operation (string): defines the type of writing in the database.
This attribute is mainly used when extending out-of-the-box schemas.
Accessible values are:
n "none": reconciliation alone. This means that Neolane will recover the element without updating it
or generating an error if it doesn't exist.
n "insertOrUpdate": update with insertion. This means that Neolane will update the element or create
it if it doesn't exist.
n "insert": insertion. This means that Neolane will insert the element without checking whether it exists.
n "update": update. This means that Neolane will update the element or generate an error if it doesn't
exist.
n "delete": deletion. This means that Neolane will recover and delete elements.
n advanced (boolean): when this option is activated (@advanced="true"), it lets you hide the attribute
on the list of available fields accessible for configuring a list in a form.
n aggregate (string): lets you copy the definition of an <element> via another schema. This attribute
receives a schema declaration in the form of a "namespace:name".
n applicableIf (string): condition for applying the index. This attribute receives an XTK expression.
n autopk (boolean): if this option is activated (autopk="true"), an auto-incremental key will be defined
automatically. This option may only be used on the main element of the schema.
n dataPolicy (string): enables you to specify approval constraints on values allowed in the SQL field.
The values for this attribute are:
n "none": no value
n "smartCase": first letters upper case
n "lowerCase": all lower case
n "upperCase": all upper case
n "email": email adress
n "phone": telephone number
n "identifier": identifier name
n "resIdentifier": file name
n dbEnum (string): receives the internal name of a "closed" enumeration. The enumeration values must
be defined in the <srcSchema>.
n defOnDuplicate (boolean): if this attribute is activated, when a record is duplicated the default value
(defined in @default) is automatically reapplied to the record.
n default (string): lets you define element behavior (call to a function, default value). This attribute
receives an XTK expression.
n desc (string): lets you insert a description of the element. This description is displayed in the status
bar of the interface.
n displayAsField (boolean): if this attribute is activated, a "link" type <element> will be displayed as a
field in the tree view of the schemas ("Structure" tab). This way, it's possible to display a link as a local
field and change it behavior during a query. When the element is found in the SELECT of a query, the
value of the link target will be used. When the element is found in the WHERE of a query, the underlying
key of the link will be used.
n edit (string): this attribute specifies the type of input that will be used in the form linked to the schema.
n enum (string): receives the name of the enumeration linked to the field. The enumeration can be
inserted into the same schema or into a remote schema.
n expr (string): this attribute defines a calculated field for which no definition is stored in the table. It
receives an Xpath or an XTK expression.
n externalJoin (boolean): external join in a "link" type element.
n feature (string): defines a characteristics field: These fields are used for extending the data in an
existing table, but with storage in an annex table. Accepted values are:
n "shared": the content is stored in a shared table per data type
n "dedicated": the content is stored in a dedicated table
SQL characteristics tables are built automatically based on the characteristic type:
n dedicated: Ft_[name_of_the_schema_containing_the_characteristic]_[name_of_the_characteristic]
n shared: Ft_[type_of_key_of_the_schema_containing_the_characteristic]_[type_of_the_characteristic]
There are two types of characteristics fields: simple o fields where a single value is authorized on the
characteristic, and o multiple choice fields, where the characteristic is linked to a collection element
which may contain several values.
When a characteristic is defined in a schema, this schema must have a main key based on a single field
(composite keys are not authorized).
n featureDate (boolean): attribute linked to the "@feature" characteristics field. If its value is "true", it
lets you find out when the value was last updated.
n filterPath (string): this attribute receives an Xpath and lets you define a filter on a field.
96 | Neolane 2013
Schema Reference (xtk:srcSchema)
n folderLink (string): this attribute receives the name of the link that lets you recover the files containing
entities.
n folderModel (string): defines the type of folder which enables entity storage. This attribute is only
defined if "@folderLink" is present.
n folderProcess (string): defines the link where entity model instances are stored. This attribute is only
defined if "@folderLink" is present.
n fullLoad (boolean): this attribute forces the display of all records in a table during field selection in a
form.
n img (string): receives the path of an image linked to an element. The value of this attribute is of
"namespace:image name" type. For example: img="cus:myImage.jpg". Physically, the image must be
imported to the application server.
n integrity (string): referential integrity of the occurrence of the source table towards the target table.
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 of
the "@label" attribute for translation (internal use).
n name (MNTOKEN): internal name of the element which matches the name of the table. The value of
the "@name" attribute must be short, preferably in English and comply with naming constraints linked
to XML.
When the schema is written to the database, prefixes are automatically added to the field name by
Neolane.
n "i": prefix for the 'integer' type.
n "d": prefix for the 'double' type.
n "s": prefix for the character string type.
n "ts": prefix for the 'date' type.
To define the name of the table in an autonomous way, you need to use the "@sqltable" attribute in the
definition of the main schema element.
n noDbIndex (boolean): lets you specify that the element will not be indexed.
n ordered (boolean): if the attribute is activated (ordered="true"), Neolane keeps the element declaration
sequence in an XML collection element.
n pkSequence (string): receives the name of the sequence to be used for calculating an auto-incremental
key. This attribute may only be used if an auto-incremental key is defined on the root element of the
schema.
n pkgStatus (string): during package exports, values will be taken into account as a function of the value
of this attribute:
n "always": the element will always be present
n "never": the element will never be present
n "default (or nothing)": the element is exported unless it is the default element or if it isn't an internal
field and would not be compatible with other instances
n ref (string): this attribute defines a reference to an <element> element shared by several schemas
(definition factoring). The definition isn't copied into the current schema.
n required (boolean): if this attribute is activated (@required="true"), the field is highlighted in the
interface. The label of the field will be red in forms.
n revAdvanced (boolean): when activated, this attribute specifies that the opposite link is an "advanced"
link.
n revCardinality: this attribute defines the cardinality of a link between two tables. It is used in a "link"
type <element>.
Possible values are:
98 | Neolane 2013
Schema Reference (xtk:srcSchema)
n percent
n primarykey
n short
n string
n time
n timespan
n uuid
n unbound (boolean): if the attribute is activated (unbound="true"), the link is declared as a collection
element for a 1-N cardinality.
n userEnum (string): receives the internal name of an "open" enumeration. Enumeration values can be
defined by the user in the interface.
n xml (boolean): if this option is activated, all values defined in the element are stored in XML in a TEXT
type "mData" field. This means that there will be no filtering or sorting on these fields.
n xmlChildren (boolean): forces storage for each child (<element> or <attribute>) of the <element>
element in an XML document.
<enumeration> element
Content model
enumeration:==(help| value)
Attributes
n @basetype (string)
n @default (string)
n @desc (string)
n @label (string)
n @name (string)
n @template (string)
Parents
<srcSchema>
Children
n <help>
n <value>
Description
This element enables us to define a value enumeration. An enumeration belongs to the schema which it is
defined in, but it is accessible via another schema.
Attribute description
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
n short
n string
n time
n timespan
n uuid
n default (string): Default value. The default value may also be one of the values defined in the
enumeration.
n desc (string): enumeration description.
n label (string): enumeration label.
n name (string): internal name of the enumeration.
n template (string): this attribute defines a reference to an <enumeration> element shared by several
schemas. The definition is automatically copied into the current schema.
Examples
Example of enumeration values whose values are stored in the database:
<enumeration name="myEnum">
<value name="One" value="1"/>
<value name="Two" value="2"/>
</enumeration>
</element>
<help> element
Content model
help:==EMPTY
Attributes
None
Parents
<srcSchema>, <element>, <attribute>, <enumeration>, <value>, <param>, <method>
Children
None
Description
This element lets you describe an <element> or <attribute> element. It may only contain text, and is stored
in XML in the database.
Attribute description
This element has no attributes.
Examples
<method name="CheckOperation" static="true"
<helpchecks the validity of a campaign</help
...
</method
<join> element
Content model
join:==EMPTY
Attributes
n @dstFilterExpr (string)
n @xpath-dst (string)
n @xpath-src (string)
Parents
<element>
Children
None
Description
Lets you define the fields that create a join between SQL tables.
Attribute description
n dstFilterExpr (string): this attribute lets you restrict the number of eligible values in the remote table.
n xpath-dst (string): this attribute receives an Xpath (@name attribute of the remote table).
n xpath-src (string): this attribute receives an Xpath (@name attribute in the current schema).
Examples
Link between the 'email' field of the current table and the "@compagny-id" field of the remote table:
<join xpath-dst="@compagny-id" xpath-src="@email"/>
Filtered link towards the "cus:Country" table based on the content of the "@country" field which must contain
the 'EN' value:
<element name="StockUS" type="link" label="MyLink" target="cus:Stock">
<join xpath-dst="@country" xpath-src="@code" dstFilterExpr="@country = 'US'"/>
</element>
<key> element
Content model
key:==keyfield
Attributes
n @allowEmptyPart (boolean)
n @applicableIf (string)
n @internal (boolean)
n @label (string)
n @name (MNTOKEN)
n @noDbIndex (boolean)
Parents
<element>
Children
<keyfield>
Description
This element lets you define a key for identifying a record in the table.
A table must have at least one key.
Attribute description
n allowEmptyPart (boolean): in the case of a composite key, if this attribute is activated, they key is
considered valid if at least one of its keys isn't empty. By default, all the keys that make up a composite
key need to be entered.
n applicableIf (string): this attribute lets you make the key optional. It defines the condition according
to which the key definition will be applied. This attribute receives an XTK expression.
n internal (boolean): if it is activated, this attribute lets Neolane know that the key is primary.
n label (string): label of the key.
n name (MNTOKEN): internal name of the key.
n noDbIndex (boolean): if it is activated (noDbIndex="true"), the field matching the key will not be
indexed.
Examples
Declaration of a composite key which authorizes either the "@expr" or the "alias" field to be empty:
Declaration of a primary key on the "Name" field of STRING type in an <srcSchema> and the matching SQL
query:
<keyfield> element
Content model
keyfield:==EMPTY
Attributes
n @xlink (MNTOKEN)
n @xpath (MNTOKEN)
Parents
<key>,<dbindex>
Children
None
Description
This element defines the fields to be integrated into an index or a key.
Attribute description
n xlink (MNTOKEN): lets you automatically reference foreign keys defined in the join for a relation table
(N-N link).
n xpath (MNTOKEN): definition of an index or a key on an <attribute> element. This attribute receives
an Xpath which defines the path to the schema attribute that defines the key or the index.
Examples
Selection of the "sName" field in an index with an Xpath on "@name":
<keyfield xpath="@name"/>
<method> element
Content model
method:==( help | parameters)
Attributes
n @_operation (string)
n @access (string)
n @const (boolean)
n @hidden (boolean)
n @label (string)
n @library (string)
n @name (MNTOKEN)
n @pkonly (boolean)
n @static (boolean)
Parents
<methods>,<interface>
Children
n <help>
n <parameters>
Description
This element lets you define a SOAP method.
Attribute description
n access (string): this attribute defines access control for using the method. If this attribute is missing,
identification is mandatory. Available values are: 'anonymous', 'admin' and 'sql'.
n const (boolean): if it is activated, this attribute means that the declared method will alter the entity
n label (string): label of the method.
n library (string): this method isn't native to the application. This attribute takes the value of the method
library where the method definition is found (nms:mylibrary.js).
n name (MNTOKEN): unique method name.
n static (boolean): if this attribute is activated, the method is considered to be autonomous, all parameters
must be specified to the method when it is called up.
Examples
Definition of the "Subscribe" out of the box method:
<method name="Subscribe" static="true">
<help>Creation of update of a recipient's subscription to an information service</help>
<parameters>
<param desc="Name of the information service(s) (separated with commas)"
name="serviceName" type="string"/>
<param desc="Recipient to subscribe and possibly create" name="recipient"
type="DOMElement"/>
<param desc="Create the recipient if they don't exist" name="create" type="boolean"/>
</parameters>
</method>
<methods> element
Content model
methods:==method
Attributes
None
Parents
<srcSchema>
Children
method
Description
This element lets you define a <method> element. It is mandatory for declaring a method.
Attribute description
This element has no attributes.
Examples
<methods async="true"
...// definition of one or more <method
</methods
<param> element
Content model
param:==help
Attributes
n @_operation (string)
n @desc (string)
n @enum (string)
n @inout (string)
n @label (string)
n @localizable (string)
n @name (MNTOKEN)
n @namespace (MNTOKEN)
n @type (string)
Parents
<parameters>
Children
<help>
Description
This element lets you define a parameter for calling up a SOAP method.
Attribute description
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 template (string): this attribute defines a reference to an <enumeration> element shared by several
schemas. The definition is automatically copied into the current schema.
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
n short
n string
n time
n timespan
n uuid
Examples
Definition of the "serviceName" inbound setting of character string type:
<param desc="Name of the information service(s) (separated with commas)"
name="serviceName" type="string" inout="in"/>
<parameters> element
Content model
parameters:==param
Attributes
None
Parents
<method>
Children
<param>
Description
This element defines a group of <parameter> elements.
Attribute description
None
Examples
<parameters
... //definition of one or more <param
</parameters
<srcSchema> element
Content model
srcSchema:==(attribute | createdBy | data | element | enumeration | help | interface | methods | modifiedBy)
Attributes
created (datetime), createdBy-id (long), desc (string), entitySchema (string), extendedSchema (string), img
(string), implements (string), label (string), labelSingular (string), lastModified (datetime), library (boolean),
mappingType (string), modifiedBy-id (long), name (string), namespace (string), useRecycleBin (boolean),
view (boolean), xtkschema (string)
Parents
None
Children
n <attribute>
n <createdBy>
n <data>
n <element>
n <enumeration>
n <help>
n <interface>
n <methods>
n <modifiedBy>
Description
root element of a schema
Attribute description
n created (datetime): this attribute provides information on the date and time of schema creation. It
has a "Date Time" form. The values displayed are taken from the server. The time is shown in UTC
format.
n createdBy-id (long): is the identifier of the operator who created the schema.
n desc (string): schema description.
n entitySchema (string): basic schema which syntax and approval are based on (by default for Neolane:
xtk:srcSchema). When you save the current schema, Neolane will approve its grammar with the schema
declared in the @xtkschema attribute.
n extendedSchema (string): receives the name of the out-of-the-box schema which the current schema
extension is based on. The form is "namespace:name".
n img (string): icon linked to the schema (may be defined in the schema creation wizard).
n label (string): schema label.
n labelSingular (string): label (singular) for display in the interface.
n lastModified (datetime): this attribute provides information on the date and time of the last modification.
It has a "Date Time" form. The values displayed are taken from the server. The time is shown in UTC
format.
n library (boolean): use of the schema as a library and not an entity. This schema may therefore be
referenced by other schemas thanks to the "@ref" and "@template" attributes.
n mappingType (string):
n "sql": database mapping
n "textFile": text file mapping
n "xmlFile": XML format text file mapping
n "binaryFile": binary file mapping
n modifiedBy-id (long): matches the identifier of the operator who changed the schema.
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">
<sysFilter> element
Content model
sysFilter:==condition
Attributes
@inline
Parents
<element>
Children
<condition>
Description
This element lets you define a filter.
Attribute description
This element has no attributes.
Examples
Definition of a filter with a condition on the @name attribute:
<sysFilter>
<condition expr="@name ='Doe'"/>
<sysFilter>
<value> element
Content model
value:==help
Attributes
n @applicableIf (string)
n @desc (string)
n @enabledIf (string)
n @img (string)
n @label (string)
n @name (string)
n @value (string)
Parents
<enumeration>
Children
<help>
Description
This element lets you define the values stored in an enumeration.
Attribute description
n applicableIf (string): this attribute lets you make an enumeration value optional. It receives an XTK
expression.
n desc (string): description of the enumeration value.
n enabledIf (string): condition for activating the enumeration value.
n img (string): image linked to the enumeration in the namespace:name_image form. The image must
be imported onto the application server.
n label (string): label of the enumeration value.
n name (string): internal name of the enumeration value.
n value (string): value of the enumeration value. The type of value is defined based on the type of
enumeration. If the enumeration is of character string type, it may only contain character string type
values.
Examples
<enumeration name="myEnum">
<value name="One" value="1"/>
<value name="Two" value="2"/>
</enumeration>
Table of Contents
Editing schemas . . . . . . . . . . . . . . . . . . . . . . . . . . 117
Presentation . . . . . . . . . . . . . . . . . . . . . . . . . . 117
Example: creating a contract table . . . . . . . . . . . . . . . . . . . 118
Schema of an existing table or a view . . . . . . . . . . . . . . . . . . . 121
Presentation . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Implementation . . . . . . . . . . . . . . . . . . . . . . . . . 121
Accessing an external database . . . . . . . . . . . . . . . . . . . . 123
Extending an existing schema . . . . . . . . . . . . . . . . . . . . . 125
Updating the physical structure of the database . . . . . . . . . . . . . . . 126
New field wizard . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Schema structure . . . . . . . . . . . . . . . . . . . . . . . . . . 129
Regenerating all schemas . . . . . . . . . . . . . . . . . . . . . . . 129
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
Extending a table . . . . . . . . . . . . . . . . . . . . . . . . . 129
Linked collection table . . . . . . . . . . . . . . . . . . . . . . . 130
Extension table . . . . . . . . . . . . . . . . . . . . . . . . . 131
Overflow table . . . . . . . . . . . . . . . . . . . . . . . . . . 132
Relationship table . . . . . . . . . . . . . . . . . . . . . . . . . 133
This chapter details the configuration of extension schemas for extending the conceptual data model
of the Neolane database.
Editing schemas
Presentation
To edit, create and configure the schemas, click the Administration>Configuration>Data
schemas node of the Neolane client console.
The edit field shows the XML content of the source schema:
Note:
The "Name" edit control lets you enter the schema key made up of the name and namespace. The "name"
and "namespace" attributes of the root element of the schema are automatically updated in the XML editing
zone of the schema.
Note:
When the source schema is saved, generation of the extended schema is automatically launched.
To do this, you need to create the schema of the table and update the database structure to generate the
corresponding table. Apply the following stages:
1 Edit the Administration>Configuration>Data schemas node of the Neolane tree and click New.
2 Choose the Create a new table in the data model option and click Next.
Note:
By default, schemas created by users are stored in the 'cus' namespace. For more on this, refer to
Identification of a schema [page 71].
4 Create the content of the table. We recommend using the entry wizard to make sure no settings are
missing. To do this, click the Insert button and choose the type of setting to be added.
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"/>
name="type" type="byte"/>
<attribute label="Contract number" name="noContrat" type="long"/>
<dbindex name="noContrat" unique="true">
<keyfield xpath="@noContrat"/>
</dbindex>
</element>
</srcSchema>
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 126].
Presentation
When the application needs to access the data of an existing table, an SQL view, or data from a remote
database, create its schema in Neolane with the following data:
n Name of table: enter the name of the table (with its alias when a dblink is used) with the "sqltable"
attribute,
n schema key: reference the reconciliation field(s),
n indexes: used to generate queries,
n The fields and their location in the XML structure: fill in only the fields used in the application,
n links: if there are joins with the other tables of the base.
Implementation
To create the corresponding schema, apply the following stages:
1 Edit the Administration>Configuration>Data schemas node of the Neolane tree and click New.
2 Select the Access data from an existing table or an SQL view option and click Next.
Important:
The schema must be populated with the view="true" attribute on the <srcSchema> root element in
order not to generate a table creation SQL script.
Example :
<srcSchema name="recipient" namespace="cus" view="true">
<element name="recipient" sqltable="dbsrv.recipient">
<key name="email">
<keyfield xpath="@email"/>
</key>
<attribute name="email" type="string" length="80" sqlname="email"/>
</element>
</srcSchema>
1 Edit the Administration>Configuration>Data schemas node of the Neolane tree and click New.
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.
Warning:
Some out-of-the-box schemas must not be extended: mainly those for which the following settings are
defined:
dataSource="file" and mappingType="xmlFile".
The following schemas must not be extended: xtk:entityBackupNew, xtk:entityBackupOriginal,
xtk:entityOriginal, xtk:form, xtk:srcSchema, ncm:publishing, nl:monitoring, nms:calendar,
nms:remoteTracking, nms:userAgentRules, xtk:builder, xtk:connections, xtk:dbInit, xtk:funcList,
xtk:fusion,xtk: jst, xtk:navtree, xtk:queryDef, xtk:resourceMenu, xtk:schema, xtk:scriptContext,
xtk:session, xtk:sqlSchema, xtk:strings.
This list is not exhaustive.
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 on
the extension schemas.
The belongsTo attribute on the field fills in the schema where it is declared.
Important:
Do not modify the standard schemas of the application, but rather the schema extension mechanism.
Otherwise, modified schemas will not be updated at the time of future upgrades of the application. This can
lead to malfunctions in the use of Neolane.
The Add stored procedures and Import initialization data options are used to launch the initial SQL
scripts and the data packages executed when the database is created.
You can import a set of data from an external data package. To do this, select Import a package and enter
the XML file of the package.
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.
1 The first page lets you enter the name of the schema to be extended and the namespace of the extension
schema where the modifications will be saved:
2 The next page lets you enter the properties of the field to be added.
Note:
By default, the added fields are declared with the property user (with the value "true"). This lets you display
and edit the field in the input form of the extended schema using a "treeEdit"-type control (refer to Input
forms [page 135]).
Schema structure
The structure of a data schema is shown in the form of a tree structure. To view it graphically in the Neolane
client console, select the targeted schema and click the Structure sub-tab.
As a standard, the fields are displayed first (Active, Activated, etc.) and in alphabetical order. The structuring
elements come next (Postal address, Location), and finally the links (E-mail information, Folder, etc.).
Primary keys are identified by a red key, and foreign keys are identified by a yellow key.
Links are distinguished graphically depending on whether they belong to the table. Those that start from the
table, i.e. that have the foreign key in the table, are displayed first (E-mail information, Folder, Country).
"Reverse" collection links (Subscription, Orders, etc.) are displayed at the end.
Examples
Extending a table
To extend the nms:recipient schema recipient table, apply the following procedure:
<element name="extension">
<dbindex name="area">
<keyfield xpath="location/@area"/>
</dbindex>
In this example, an indexed field (fidelity) is added, and the location element (which already existed
in the nms:recipient schema) is supplemented with an enumerated field (area).
Warning:
Remember to add the extendedSchema attribute to reference the extension schema.
2 Check that the extended schema is the nms:recipient schema and that the additional data is present:
<schema dependingSchemas="cus:extension" mappingType="sql" name="recipient"
namespace="nms" xtkschema="xtk:schema">
...
<enumeration basetype="string" default="area1" name="area">
<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);
The table type is autopk in order to create an auto-generated primary key to be used by the join of the link
to the recipient table.
Schema generated:
<schema label="Order" mappingType="sql" name="order" namespace="cus" xtkschema="xtk:schema">
<dbindex name="recipientId">
<keyfield xpath="@recipient-id"/>
</dbindex>
Note:
The SQL command INSERT INTO at the end of the script lets you insert an identifier record set to 0 in order
to simulate outer joins.
Extension table
An extension table lets you extend the content of an existing table in a linked table of cardinality 1-1.
The purpose of an extension table is to avoid limitations on the number of fields supported in a table, or to
optimize the space occupied by the data, which is consumed on demand.
Creating the extension table schema (cus:feature):
<srcSchema mappingType="sql" name="feature" namespace="cus" xtkschema="xtk:srcSchema">
<element autopk="true" name="feature">
<attribute label="Children" name="children" type="byte"/>
<attribute label="Single" name="single" type="boolean"/>
<attribute label="Spouse first name" length="100" name="spouseFirstName" type="string"/>
</element>
</srcSchema>
Creating an extension schema on the recipient table to add the link of cardinality 1-1:
<srcSchema extendedSchema="nms:recipient" label="Recipient" mappingType="sql"
name="recipient" namespace="cus" xtkschema="xtk:srcSchema">
<element 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 the
schema containing the foreign key.
Overflow table
An overflow table is an extension table (cardinality 1-1), but the declaration of the link to the table to be
extended is populated in the schema of the overflow table.
The overflow table contains the foreign key to the table to be extended. The table to be extended is therefore
not modified. The relation between the two tables is the value of the primary key of the table to be extended.
Creating the overflow table schema (cus:overflow):
<srcSchema label="Overflow" name="overflow" namespace="cus" xtkschema="xtk:srcSchema">
<element name="overflow">
<key internal="true" name="id">
<keyfield xlink="recipient"/>
</key>
Note:
The primary key of the overflow table is the link to the table to be extended ("nms:recipient" schema in our
example).
Relationship table
A relationship table lets you link two tables with cardinality N-N. This table contains only the foreign keys of
the tables to be linked.
Example of a relationship table between groups (nms:group) and recipients (nms:recipient).
Source schema of the relationship table:
<srcSchema name="rcpGrpRel" namespace="cus">
<element name="rcpGrpRel">
<key internal="true" name="id">
<keyfield xlink="rcpGroup"/>
<keyfield xlink="recipient"/>
</key>
<dbindex name="rcpGroupId">
<keyfield xpath="@rcpGroup-id"/>
</dbindex>
<dbindex name="recipientId">
<keyfield xpath="@recipient-id"/>
</dbindex>
</element>
</schema>
Table of Contents
Identifying a form . . . . . . . . . . . . . . . . . . . . . . . . . 135
Editing forms . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
Form structure . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
Formatting . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
Containers . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
Editing a link . . . . . . . . . . . . . . . . . . . . . . . . . . 141
List of links . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
Memory list controls . . . . . . . . . . . . . . . . . . . . . . . . 144
Non-editable fields . . . . . . . . . . . . . . . . . . . . . . . . 145
Radio button . . . . . . . . . . . . . . . . . . . . . . . . . . 146
Checkbox . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
Navigation hierarchy edit . . . . . . . . . . . . . . . . . . . . . . 146
Expression field . . . . . . . . . . . . . . . . . . . . . . . . . 146
Context of forms . . . . . . . . . . . . . . . . . . . . . . . . . 147
Wizards . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
An input form lets you edit an instance associated with a data schema from the Neolane client
console.
Identifying a form
An input form is identified by its name and namespace.
The identification key of a form is a string made up of the namespace and the name separated by
a colon (':') (for example: "cus:contact").
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:
Form structure
The description of a form is a structured XML document that observes the grammar of the form schema
xtk:form.
The XML document of the input form must contain the <form> root element with the name and namespace
attributes to populate the form name and namespace.
<form name="form_name" namespace="name_space">
...
</form>
By default, a form is associated with the data schema with the same name and namespace. To associate a
form with a different name, set the entity-schema attribute of the <form element to the name of the
schema key.
To illustrate the structure of an input form, let us describe an interface using the "cus:recipient" example
schema:
<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 description of the edit controls starts from the <form> root element.
An edit control is entered in an <input> element with the xpath attribute containing the path of the field
in its schema.
The edit control automatically adapts to the corresponding data type and uses the label defined in the schema.
Note:
You can overload the label defined in its data schema by adding the label attribute to the <input element:
<input xpath="@name" label="E-mail address"/>
By default, each field is displayed on a single line and occupies all available space depending on the type of
data.
Formatting
The layout of the controls looks like the layout used in HTML tables, with the possibility of dividing a control
into several columns, interlacing elements, or specifying the occupation of available space. Remember,
however, that formatting only lets you divide the area up by proportions; you cannot specify fixed dimensions
for an object.
To display the controls of the above example in two columns:
The <container> element with the colcount attribute lets you force the display of child controls onto two
columns.
The colspan attribute on a control extends the control by the number of columns entered in its value:
By populating the type="frame" attribute, the container adds a frame around the child controls with the
label contained in the label attribute:
The <static> tag with the separator type lets you add a separator bar with a label contained in the label
attribute.
A help text was added using the <static tag with a help type. The content of the text is entered in the label
attribute.
Containers
Containers let you group a set of controls. They are represented by the <container> element. They were
used above to format controls over several columns.
The xpath attribute on a <container lets you simplify the referencing of child controls. The referencing of
controls is then relative to the parent <container parent.
Example of a container without "xpath":
<container colcount="2">
<input xpath="location/@zipCode"/>
<input xpath="chapter/@city"/>
</container>
Types of container
Containers are used to construct complex controls using a set of fields formatted in pages.
Tab container
A tab container formats data in pages that are accessible from tabs.
<container type="notebook">
<container colcount="2" label="General">
<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 the
control. This feature is optional.
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 are
declared in the child containers. The label of the icons is populated from the label attribute.
The icon of a page is populated from the img="<image>" attribute, where <image> is the name of the
image corresponding to its key made up of the name and namespace (e.g., "xtk:properties.png").
The images are available from the Administration > Configuration > Images node.
Visibility container
You can mask a set of controls via a dynamic condition.
This example illustrates the visibility of controls on the value of the "Gender" field:
<container type="visibleGroup" visibleIf="@gender=1">
...
</container>
<container type="visibleGroup" visibleIf="@gender=2">
...
</container>
A visibility container is defined by the attribute type="visibleGroup". The visibleIf attribute contains the
visibility condition.
Examples of condition syntax:
n visibleIf="@email='peter.martinez@neeolane.net'": tests equality on string-type data. The
comparison value must be in quotes.
n visibleIf="@gender >= 1 and @gender!= 2": condition on a numeric value.
n visibleIf="@boolean1==true or @boolean2==false": test on Boolean fields.
Enabling container
This container lets you enable or disable a set of data from a dynamic condition. Disabling a control prevents
it from being edited. The following example illustrates the enabling of controls from the value of the "Gender"
field:
<container type="enabledGroup" enabledIf="@gender=1">
...
</container>
<container type="enabledGroup" enabledIf="@gender=2">
...
</container>
An enabling container is defined by the type="enabledGroup" attribute. The enabledIf attribute contains
the activation condition.
Editing a link
Remember that a link is declared in the data schema as follows:
<element label="Company" name="company" target="cus:company" type="link"/>
<input xpath="company"/>
Target selection is accessible via the edit field. Entry is assisted by type-ahead so that a target element can
easily be found from the first few characters entered. The search is then based on the Compute string
defined in the targeted schema. If the schema does not exist after validation in the control, a confirmation
message of on-the-fly target creation is displayed. The confirmation creates a new record in the target table
and associates it with the link.
A drop-down list is used to select a target element from the list of records already created.
The Modify the link (folder) icon launches a selection form with the list of targeted elements and a filter
zone:
The Edit link (magnifier) icon launches the edit form of the linked element. The form used is deduced by
default on the key of the targeted schema. The form attribute lets you force the name of the edit form (e.g.
"cus:company2").
You can restrict the choice of target elements by adding the <sysFilter> element from the link definition
in the input form:
<input xpath="company">
<sysFilter>
<condition expr="[location/@city] = 'Newton"/>
</sysFilter>
</input>
You can also sort the list with the <orderBy> element:
<input xpath="company">
<orderBy>
<node expr="[location/@zipCode]"/>
</orderBy>
</input>
Control properties
n noAutoComplete: disables type-ahead (with the value "true")
n createMode: creates the link on the fly if it does not exist. Possible values are:
n none: disables creation. An error message is displayed if the link does not exist
n inline: creates the link with the content in the edit field
n edition: displays the edit form on the link. When the form is validated, the data is saved (default
mode)
n noZoom: no edit form on the link (with the value "true")
n form: overloads the edit form of the targeted element
List of links
A link entered in the data schema as a collection element (unbound="true") must go through a list in order
to view all the elements associated with it.
The principle consists in displaying the list of linked elements with optimized data loading (downloading by
data batch, execution of the list only if it is visible).
Example of a collection link in a schema:
<element label="Events" name="rcpEvent" target="cus:event" type="link" unbound="true">
...
</element>
List control is defined by the type="linklist" attribute. The list path must refer to the collection link.
The columns are declared via the <input> elements of the list. The xpath attribute refers to the path of
the field in the target schema.
A toolbar with a label (defined on the link in the schema) is automatically placed above the list.
The list can be filtered via the Filters button and configured to add and sort the columns.
The Add and Delete buttons let you add and delete collection elements on the link. By default, adding an
element launches the edit form of the target schema.
The Detail button is automatically added when the zoom="true" attribute is completed on the <input>
tag of the list: it lets you launch the edit form of the selected line.
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 table
A relationship table lets you link two tables with N-N cardinality. The relationship table contains only the links
to the two tables.
Adding an element to the list should therefore let you complete a list from one of the two links in the
relationship table.
Example of a relationship table in a schema:
<srcSchema name="subscription" namespace="cus">
<element name="recipient" type="link" target="cus:recipient" label="Recipient"/>
<element name="service" type="link" target="cus:service" label="Subscription service"/>
</srcSchema>
For our example, we start with the input form of the "cus:recipient" schema. The list must display the
associations with subscriptions to services and must allow you to add a subscription by selecting an existing
service.
The xpathChoiceTarget attribute lets you launch a selection form from the link entered. Creating the
relationship table record will automatically update the link to the current recipient and the selected service.
Note:
The xpathEditTarget attribute lets you force editing of the selected line on the link entered.
List properties
n noToolbar: hides the toolbar (with value "true")
n toolbarCaption: overloads the toolbar label
n toolbarAlign: modifies the vertical or horizontal geometry of the toolbar (possible values:
"vertical"|"horizontal")
n img: displays the image associated with the list
Column list
This control displays an editable column list with a toolbar containing Add and Delete buttons.
The list control must be filled in with the type="list" attribute, and the path of the list must refer to the
collection element.
The columns are declared in the child <input> tags of the list. Column label and size can be forced with
the label and colSize attributes.
Note:
Sort-order arrows are added automatically when the ordered="true" attribute is added to the collection
element in the data schema.
The toolbarCaption attribute forces the horizontal alignment of the toolbar and enters the title above the
list.
Zoom in a list
Insertion and editing of the data in a list can be entered in a separate edit form.
The edit form is completed from the <form> element under list definition. Its structure is identical to that
of an input form.
The Detail button is added automatically when the zoom="true" attribute is completed on the <input>
tag of the list. This attribute lets you launch the edit form of the selected line.
Note:
Adding the zoomOnAdd="true" attribute forces the edit form to be called up when a list element is inserted.
List properties
n noToolbar: hides the toolbar (with value "true")
n toolbarCaption: overloads the toolbar label
n toolbarAlign: modifies the positioning of the toolbar (possible values: "vertical"|"horizontal")
n img: displays the image associated with the list
n form: overloads the edit form of the targeted element
n zoom: adds the Zoom button to edit the targeted element
n zoomOnAdd: launches the edit form on the addition
n xpathChoiceTarget: for addition, launches the selection form on the link entered
Non-editable fields
To display a field and prevent it from being edited, use the <value> tag or complete the readOnly="true"
attribute on the <input> tag.
Example on the "Gender" field:
<value value="@gender"/>
<input xpath="@gender" readOnly="true"/>
Radio button
A radio button lets you choose from several options. The <input> tags are used to list the possible options,
and the checkedValue attribute specifies the value associated with the choice.
Example on the "Gender" field:
<input type="RadioButton" xpath="@gender" checkedValue="0" label="Choice 1"/>
<input type="RadioButton" xpath="@gender" checkedValue="1" label="Choice 2"/>
<input type="RadioButton" xpath="@gender" checkedValue="2" label="Choice 3"/>
Checkbox
A checkbox reflects a Boolean state (selected or not). By default, this control is used by "Boolean" (true/false)
fields. A variable taking a default value of 0 or 1 can be associated with this button. This value can be
overloaded via the checkValue attributes.
<input xpath="@boolean1"/>
<input xpath="@field1" type="checkbox" checkedValue="Y"/>
Expression field
An expression field updates a field dynamically from an expression; the <input> tag is used with an xpath
attribute to enter the path of the field to be updated and an expr attribute containing the update expression.
<!-- Example: updating the boolean1 field from the value contained in the field with path
/tmp/@flag -->
<input expr="Iif([/tmp/@flag]=='On', true, false)" type="expr" xpath="@boolean1"/>
<input expr="[/ignored/@action] == 'FCP'" type="expr" xpath="@launchFCP"/>
Context of forms
The execution of an input form initializes an XML document containing the data of the entity being edited.
This document represents the context of the form, and can be used as a workspace.
Note:
The <enter> and <leave> tags can be used on the <container> of pages ("notebook" and "iconbox" types).
Expression language
A macro-language can be used in form definition in order to perform conditional tests.
The <if expr="<expression>"> tag executes the instructions specified under the tag if the expression
is verified:
<if expr="([/tmp/@test] == 'Test' or @lastName!= 'Doe') and @boolean2 == true">
<set xpath="@boolean1" expr="true"/>
</if>
The <check expr="<condition>"> tag combined with the <error> tag prevents validation of the
form and displays an error message if the condition is not satisfied:
<leave>
<check expr="/tmp/@test!= ''">
<error>You must populate the 'Test' field!</error>
</check>
</leave>
Wizards
A wizard guides you through a set of data entry steps in the form of pages. The data entered is saved when
you validate the form.
A wizard has the following structure:
<form type="wizard" name="example" namespace="cus" img="nms:rcpgroup32.png" label="Wizard
example" entity-schema="nms:recipient">
<container title="Title of page 1" desc="Long description of page 1">
<input xpath="@lastName"/>
<input xpath="comment"/>
</container>
<container title="Title of page 2" desc="Long description of page 2">
...
</container>
...
</form>
The presence of the type="wizard" attribute on the <form> element lets you define the wizard mode in
the construction of the form.
The pages are completed from <container elements, which are children of the <form> element. The
<container element of a page is populated with the title attributes for the title and desc to display the
description under the page title.
The Previous and Next buttons are automatically added to allow browsing between pages.
The Finish button saves the data entered and closes the form.
SOAP methods
SOAP method execution can be launched from a populated <leave> tag at the end of a page.
The <soapCall> tag contains the call for the method with the following input parameters:
<soapCall name="<name>" service="<schema>">
<param type="<type>" exprIn="<xpath>"/>
...
</soapCall>
The name of the service and its implementation schema are entered via the name and service attributes
of the <soapCall> tag.
The input parameters are described on the <param> elements under the <soapCall> tag.
The parameter type must be specified via the type attribute. The possible types are as follows:
n string: character string
n boolean: Boolean
n byte: 8-bit integer
n short: 16-bit integer
n long: 32-bit integer
n short: 16-bit integer
n double: double-precision floating point number
n DOMElement: element-type node
The exprIn attribute contains the location of the data to be passed as a parameter.
Example :
<leave>
<soapCall name="RegisterGroup" service="nms:recipient">
<param type="DOMElement" exprIn="/tmp/entityList"/>
<param type="DOMElement" exprIn="/tmp/choiceList"/>
<param type="boolean" exprIn="true"/>
</soapCall>
</leave>
Table of Contents
Presentation . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
Definition of Neolane APIs . . . . . . . . . . . . . . . . . . . . . 150
Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . 150
Using Neolane APIs . . . . . . . . . . . . . . . . . . . . . . . . 150
SOAP calls . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
Resources and exchanges . . . . . . . . . . . . . . . . . . . . . . 151
Example of a SOAP message on the "ExecuteQuery" method . . . . . . . . . . 151
Error management . . . . . . . . . . . . . . . . . . . . . . . . 152
URL of Web service server (or EndPoint) . . . . . . . . . . . . . . . . . 153
Web service calls . . . . . . . . . . . . . . . . . . . . . . . . . . 153
General information . . . . . . . . . . . . . . . . . . . . . . . . 153
Definition of Web services . . . . . . . . . . . . . . . . . . . . . . 153
Web service description: WSDL . . . . . . . . . . . . . . . . . . . . 154
Connectivity . . . . . . . . . . . . . . . . . . . . . . . . . . 155
Safety: authentication mechanism . . . . . . . . . . . . . . . . . . . 156
Data oriented API . . . . . . . . . . . . . . . . . . . . . . . . . 157
Overview of the datamodel . . . . . . . . . . . . . . . . . . . . . 157
Description of the model . . . . . . . . . . . . . . . . . . . . . . 157
Query and Writer . . . . . . . . . . . . . . . . . . . . . . . . . 158
ExecuteQuery (xtk:queryDef) . . . . . . . . . . . . . . . . . . . . 158
Write / WriteCollection (xtk:session) . . . . . . . . . . . . . . . . . . 165
Business oriented APIs . . . . . . . . . . . . . . . . . . . . . . . . 168
Subscribe (nms:subscription) . . . . . . . . . . . . . . . . . . . . . 168
Unsubscribe (nms:subscription) . . . . . . . . . . . . . . . . . . . . 169
SubmitDelivery (nms:delivery) . . . . . . . . . . . . . . . . . . . . 170
Implementing SOAP methods in JavaScript . . . . . . . . . . . . . . . . . 172
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . 172
Definition of a method library . . . . . . . . . . . . . . . . . . . . 172
Use SOAP methods in JavaScript . . . . . . . . . . . . . . . . . . . . 173
Static methods . . . . . . . . . . . . . . . . . . . . . . . . . . 173
Non-static methods . . . . . . . . . . . . . . . . . . . . . . . . 174
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
Appendix 1 - Examples . . . . . . . . . . . . . . . . . . . . . . . . 175
Examples of programs in various languages . . . . . . . . . . . . . . . . 175
PHP examples . . . . . . . . . . . . . . . . . . . . . . . . . . 178
C# example . . . . . . . . . . . . . . . . . . . . . . . . . . 181
JSP example . . . . . . . . . . . . . . . . . . . . . . . . . . 182
Appendix 2 - Using SOAP to collect data from a profile . . . . . . . . . . . . . 185
Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
Using data from the profile . . . . . . . . . . . . . . . . . . . . . 186
Presentation
Prerequisites
Before using the Neolane APIs, you need to be familliar with the following topics:
n Javascript
n SOAP protocol
n Neolane datamodel
SOAP calls
The SOAP protocol lets you invoke API methods, via the rich client, third-party applications using webservices,
or JSP using these methods natively.
Note:
The WSDL description of this service is completed in the example shown here: Web service description:
WSDL [page 154].
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'>___YXRFVThQ+PMj4PnTMCbfExx8FWqKjtCVK2wp0Nyej6E2yEkJUIAIA</__sessiontoken>
<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>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
The <SOAP-ENV:Envelope> element is the first element of the message representing the SOAP envelope.
The <SOAP-ENV:Body> element is the first child element of the envelope. It contains the description of the
message, i.e. the content of the query or the response.
The method to be invoked is entered in the <ExecuteQuery> element from the body of the SOAP message.
In SOAP, the parameters are recognized by order of appearance. The first parameter, <__sessiontoken>,
takes the authentication chain, the second parameter is the XML description of the query from the <queryDef>
element.
SOAP response
<?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>
Error management
Example 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
The <SOAP-ENV:Fault> element in the body of the SOAP message is used to convey the error signals arising
during the processing of the Web service. This is composed of the following sub-elements:
n <faultcode>: indicates the type of error. The error types are:
n "VersionMismatch" in the event of incompatibility with the SOAP version used,
n "MustUnderstand" in the event of a problem in the message header,
n "Client" in the event that the client is missing some information,
n "Server" in the event that the server has a problem executing the processing.
n <faultstring>: message describing the error
n <detail>: long error message
The success or failure of the service invocation is identified when the <faultcode> element is verified.
Important:
All Neolane Web services handle errors. It is therefore strongly recommended to test each call in order to
handle returned errors.
Example of error handling in C#:
try
{
// Invocation of method
...
}
catch (SoapException e)
{
System.Console.WriteLine("Soap exception: " + e.Message);
if (e.Detail!= null)
System.Console.WriteLine(e.Detail.InnerText);
}
General information
All API methods are presented in the form of Web services. This enables you to manage all Neolane functions
via SOAP calls, which are the native entry point of the Neolane application server. The Neolane console itself
only uses SOAP calls.
Web services let you create many applications from a third-party system:
n Synchronous alerts, notification, and real-time delivery template execution from a back office or transaction
system,
n Development of special interfaces with simplified functionality (Web interfaces, etc.),
n Feeding and lookup of data in the database while observing trade rules and remaining isolated from the
underlying physical model.
The description of the service starts with the <method> element. The list of parameters of the method is
completed from the <parameters> element. Each parameter is specified by a name, a type (Boolean, string,
DOMElement, etc.) and a description. The "inout" attribute with the "out" value lets you specify that the
"result" parameter is at the SOAP call output.
The presence of the "static" attribute (with the value "true") describes this method as static, which means
that all parameters of the method must be declared.
A "const" method implicitly has an XML document in the format of its associated schema as its input.
A full description of the <method element of a Neolane schema is available in the "Schema references"
chapter under <method> element [page 107].
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.
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">
<s:complexType mixed="true">
<s:sequence>
<s:any/>
</s:sequence>
</s:complexType>
</s:element>
</s:sequence>
</s:complexType>
</s:element>
Messages
The <message> describes the names and types of a set of fields to be sent. The method uses two messages
to pass as a parameter ("ExecuteQueryIn") and the return value ("ExecuteQueryOut").
<message name="ExecuteQueryIn">
<part element="tns:ExecuteQuery" name="parameters"/>
</message>
<message name="ExecuteQueryOut">
<part element="tns:ExecuteQueryResponse" name="parameters"/>
</message>
PortType
The <portType> associates the messages on the "ExecuteQuery" operation triggered by the query ("input")
generating a response ("output").
<portType name="queryDefMethodsSoap">
<operation name="ExecuteQuery">
<input message="tns:ExecuteQueryIn"/>
<output message="tns:ExecuteQueryOut"/>
</operation>
</portType>
Binding
The <blind> part specifies the SOAP communication protocol (<soap:binding>), data transport in HTTP
(value of the "transport" attribute) and the data format for the "ExecuteQuery" operation. The body of the
SOAP envelope contains the message segments directly without transformation.
<binding name="queryDefMethodsSoap" type="tns:queryDefMethodsSoap">
<soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
<operation name="ExecuteQuery">
<soap:operation soapAction="xtk:queryDef#ExecuteQuery" style="document"/>
<input>
<soap:body encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
namespace="urn:xtk:queryDef" use="literal"/>
</input>
<output>
<soap:body encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
namespace="urn:xtk:queryDef" use="literal"/>
</output>
</operation>
</binding>
Service
The <service> part describes the "XtkQueryDef" service with its URI on the URL of the Neolane application
server.
<service name="XtkQueryDef">
<port binding="tns:queryDefMethodsSoap" name="queryDefMethodsSoap">
<soap:address location="http://localhost/nl/jsp/soaprouter.jsp"/>
</port>
</service>
Connectivity
When you use external SOAP APIs, you need to use a session token that conveys the login used and ensures
authentication.
There are two possible authentication modes:
n via a logon: login + Neolane password which creates a session token. The session token expires
automatically after a certain amount of time,
or
n via the login + password stored in the application: this operating mode requires an https connection to
secure exchanges.
It is also possible to use an authentication via the IP address (trust), which enables you to sidestep the
password.
For more on this, refer to Safety: authentication mechanism [page 156]
Tip:
To retrieve a session token associated with a login, you must connect to the client console using the desired
login and retrieve the session token value ("__sessiontoken") from the page properties of the home page.
Important:
The application login used for authentication must be configured in the Neolane client console with the rights
and restrictions on the database data.
When the authentication string is not completed in the SOAP call, an intermediate page is automatically
displayed. This enables you to enter a login and password to return a valid session token.
Note:
You can use the "HTTPS" protocol to secure exchanges so that unencrypted data is not sent through the
network. You must then configure the Web server that hosts the Neolane Web services.
The validity period of the session token is defined via the shared/authentication/@sessionTimeOutSec
parameter of the serverConf.xml file. The default value is 86400, i.e. 1 day.
For the netreport application, the encrypted session token with an expiry deadline cannot be used. We
recommend using the monitoring login and authenticating it for the IP addresses of the machines to be
monitored. This will enable you to log on without a password. For more on this, refer to the "Automatic
surveillance via Neolane scripts" section of the Production guide.
<host name="neolane.customer.com" alias="Customer Instance" sessiontoken="monitoring/">
<ncs instance="customer" url="/nl/jsp/soaprouter.jsp" includeDead="false"/>
</host>
ExecuteQuery
For columns and conditions, you can use Queries.
This lets you isolate the underlying SQL. The query language does not depend on the underlying engine:
some functions will be re-mapped, which may generate several SELECT SQL orders.
For more on this, refer to Example on the "ExecuteQuery" method of schema "xtk:queryDef" [page 154].
The ExecuteQuery method is presented in ExecuteQuery (xtk:queryDef) [page 158].
An example is available in Appendix 2 - Using SOAP to collect data from a profile [page 185].
Write
Write commands let you write simple or complex documents, with entries in one or more tables of the base.
Transactional APIs let you manage reconciliations via the updateOrInsert command: one command lets
you create or update data. You can also configure modification merging (merge): this operating mode lets
you authorize partial updates.
The XML structure offers a logical view of the data and lets you sidestep the physical structure of the SQL
table.
The Write method is presented in Write / WriteCollection (xtk:session) [page 165].
ExecuteQuery (xtk:queryDef)
This method lets you perform queries from data associated with a schema. It takes an authentication string
(login/password or session token) and an XML document describing the query to be submitted as parameters.
The return parameter is an XML document containing the result of the query in the format of the schema to
which the query refers.
Definition of the "ExecuteQuery" method in the "xtk:queryDef" schema:
<method name="ExecuteQuery" const="true">
<parameters>
<param desc="Output XML document" name="output" type="DOMDocument" inout="out"/>
</parameters>
</method>
Note:
This is a "const" method. The input parameters are included in an XML document in the format of the
"xtk:queryDef" schema.
<node expr="@lastName+'-'+@firstName"/>
<!-- get year of birth date -->
<node expr="Year(@birthDate)"/>
</select>
<where>
<condition expr="[@folder-id] = 1234 and @domain like 'neolane%'"/>
<!-- equivalent SQL expression -->
<consition sql="iFolderId = 1234 and sDomain like 'neolane%'"/>
</where>
Expressions can be simple fields or complex expressions such as arithmetic operations or the concatenation
of strings.
It is possible to enter SQL code instead of XPath expressions using the sql attribute.
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:
<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">
...
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>
</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>
It is possible to replace the 'OR' operator with the 'IN' operation when several conditions apply to the same
field:
<where>
<condition>
<condition expr="@age IN (15, 45)"/>
<condition expr="@city IN ('Newton', 'Culver City')"/>
</condition>
</where>
This syntax simplifies the query when more than two data are used in the condition.
Examples on links
n Links 1-1 or N1: when the table has the foreign key (the link starts from the table), the fields of the linked
table can be filtered or retrieved directly.
Example of a filter on the folder label:
<where>
<condition expr="[folder/@label] like 'Segment%'"/>
</where>
n Collection links (1N): the filtering on the fields of a collection table must be performed via the EXISTS
or NOT EXISTS operator.
To filter the recipients who have subscribed to the 'Newsletter' information service:
<where>
<condition expr="subscription" setOperator="EXISTS">
<condition expr="@name = 'Newsletter'"/>
</condition>
</where>
Direct retrieval of the fields of a collection link from the <select> clause is not recommended because
the query returns a cardinal product. It is used only when the linked table contains only one record
(example <node expr="").
Example on the "subscription" collection link:
<select>
<node expr="subscription/@label"/>
</select>
It is possible to retrieve a sub-list containing the elements of a collection link in the <select> clause. The
XPaths of the referenced fields are contextual from the collection element.
The filtering (<orderBy>) and restriction (<where>) elements can be added to the collection element.
In this example, for each recipient the query returns the e-mail and list of information services to which
the recipient subscribes:
<queryDef schema="nms:recipient" operation="select">
<select>
<node expr="@email"/>
To avoid binding a parameter, the "noSqlBind" attribute must be populated with the value 'true'.
Important:
If the query includes "order-by" or "group-by" instructions, the database engines will not be able to "bind"
values. You must place the @noSqlBind="true" attribute on the "select" and/or "where" instructions of the
query.
Query-building tip:
To help with the syntax of a query, you can write the query using the generic query editor in the Neolane
client console (Tools/ Generic query editor... menu). To do this:
3 Execute the query and press CTRL+F4 to view the query source code.
Alias
An alias lets you modify the location of data in the output document. The alias attribute must specify an
XPath on the corresponding field.
<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:
<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="john.doe@neolane.com" lastName"Doe" firstName="John"/>
</pdomOutput>
</ExecuteQueryResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Note:
This is a "static" method. The input parameters are included in an XML document in the format of the schema
to be updated.
Overview
Data reconciliation operates based on the definition of the keys entered in the associated schema. The write
procedure looks for the first eligible key based on the data entered in the input document. The entity is
inserted or updated based on its existence in the database.
The key of the schema of the entity to be updated is completed based on the xtkschema attribute.
The reconciliation key can therefore be forced with the _key attribute containing the list of XPaths that make
up the key (separated by commas).
It is possible to force the type of operation by populating the _operation attribute with the following values:
n insert: forces the insertion of the record (the reconciliation key is not used),
n insertOrUpdate: updates or inserts the record depending on the reconciliation key (default mode),
n update: updates the record; does nothing if the data does not exist,
n delete: deletes the records,
n none: used only for link reconciliation, without update or insertion.
Deleting a recipient:
<recipient xtkschema="nms:recipient" _operation="delete" email="rene.dupont@neolane.com"
folder-id=1203 _key="@email, [@folder-id]"/>
Note:
For a deletion operation, the input document must contain only the fields that make up the reconciliation
key.
Example on links
Example 1
Associating the folder with a recipient based on its internal name (@name).
<recipient _key="[folder/@name], @email" email="john.doe@neolane.net" lastName="Doe"
firstName="John" xtkschema="nms:recipient">
<folder name="Folder2" _operation="none"/>
</recipient>
The "_key" and "_operation" attributes can be entered on a linked element. The behavior on this element is
the same as on the main element of the input schema.
The definition of the key of the main entity ("nms:recipient") consists of a field from a linked table (element
<folder> schema "xtk:folder") and the e-mail.
Note:
The operation "none" entered on the folder element defines a reconciliation on the folder without update or
insert.
Example 2
Updating the company (linked table in "cus:company" schema) from a recipient:
<recipient _key="[folder/@name], @email" email="john.doe@neolane.net" lastName="Doe"
firstName="John" xtkschema="nms:recipient">
<company name="Neolane" code="ERT12T" _key="@name" _operation="update"/>
</recipient>
Example 3
Adding a recipient to a group with the group relation table ("nms:rcpGrpRel"):
<recipient _key="@email" email="martin.ledger@neolane.net" xtkschema="nms:recipient">
<rcpGrpRel _key="[rcpGroup/@name]">
<rcpGroup name="GRP1"/>
</rcpGrpRel>
</recipient>
Note:
The definition of the key is not entered in the <rcpGroup> element because an implicit key based on the
group name is defined in the "nms:group" schema.
<domDoc xsi:type='ns:Element'
SOAP-ENV:encodingStyle='http://xml.apache.org/xml-soap/literalxml'
<recipient xtkschema="nms:recipient" email="john.doe@neolane.com"
firstName="John" lastName="Doe" _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
Important:
The JSAPI.chm document (available on the Neolane extranet) contains additional information on SOAP calls
and using Javascript in Neolane, as well as a full reference to all methods and functions used in the application.
Subscribe (nms:subscription)
This service lets you subscribe a recipient to an information service and update the recipient profile.
The following parameters are required in order to call the service:
n a session token (for authentication),
n internal name of the subscription service,
n an XML document containing the recipient information (from the "nms:recipient" schema),
The definition of the reconciliation key must be entered via the _key attribute on the <recipient element of
the XML document. The content of this attribute is a comma-separated XPath list.
This call does not return any data, except errors.
Examples
Subscription with recipient reconciliation key on the e-mail address: the input XML document must reference
the email address and the definition of the key on this field.
<recipient _key="email" email= "john.doe@neolane.com"/>
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:
The definition of the reconciliation key must be entered via the _key attribute on the <recipient element of
the XML document. The content of this attribute is a comma-separated XPath list.
If the recipient is not present in the database or is not subscribed to the concerned information service, the
service performs no action and does not generate an error.
This call does not return any data, except errors.
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 a session token (for authentication),
n internal name of the delivery template,
n an optional XML document containing additional delivery data.
Description of the method in its schema:
<method name="SubmitDelivery" static="true">
<parameters>
<param name="scenarioName" type="string" inout="in" desc="Internal name of the delivery
template"/>
<param name="content" type="DOMElement" inout="in" desc="XML content of the delivery
template" />
</parameters>
</method>
A delivery template must be created from the Neolane client console. It contains the parameters common
to all deliveries (sender address or duration of validity of the message).
The input XML document is a delivery template fragment that obeys the structure of the "nms:delivery"
schema. It will contain all additional data that could not be defined statically in the delivery template (e.g.,
list of recipients to target).
This call does not return any data, except errors.
<delivery xtkschema="nms:delivery"
<targets fromExternalSource="true"
<externalSource<![CDATA[MsgId|ClientId|Title|Name|
FirstName|Mobile|Email|Market_segment| Product_affinity1|Product_affinity2|
Product_affinity3|Product_affinity4| Support_Number|Amount|Threshold1|000001234|
M.|Phulpin|Herv|0650201020| herve.phulpin@neolane.com|1| A1|A2|A3|A4| E12|120000|
100000]]</externalSource
</targets
</delivery
</content
</m:SubmitDelivery
</SOAP-ENV:Body
</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>
Introduction
It is possible to create SOAP methods in JavaScript. This function simply enables applicative processes, it
can avoid developing JSPs and their calling in the forms.
These SOAP methods behave in the same way as those defined natively in the application. The same attributes
are supported: static, key only and const.
Declaration
Start by declaring the methods in the schemas. Their declaration is similar to that of native methods, except
that you need to add the 'library' attribute specifying the name of the method library where the definition is
located.
This name coincides with the name (with the namespace) of the 'JavaScript Code' type entity.
Example :
The testLog(msg) method is declared in an nms:recipient extension
<method name="testLog" static="true" library="cus:test">
<parameters>
<param name="message" type="string" inout="in"/>
</parameters>
</method>
Note:
The namespace and the name used for the library are independent from the namespace and schema name
where the declaration is found.
Definition
SOAP methods are implemented in the form of JavaScript function grouped in a script representing a library.
Note:
A method library can group functions for various schemas or vice versa, the functions of one schema can be
defined in separate libraries.
The script can contain code to be executed during initial library loading.
1. Name
The name of the function must comply with the following format:
<schema-namespace>_<schema-name>_<method-name>
Example:
The following JavaScript function is the implementation of the method described above. It shall be defined
in the 'JavaScript Code' type entity using the 'cus:test' name.
function nms_recipient_testLog(message)
{
logInfo("*** " + message)
}
2. Signature
The function's signature must include an argument for each 'in' or 'inout' parameter of the declaration.
Specific cases:
n non-static methods: the function must include an additional argument first, coinciding with the XML
entity passed in the form of an 'xml' (E4X) type object.
n "key only" type methods: the function must include an additional argument first, coinciding with the
key passed in the form of character strings.
3. Returned values
The function must return a value for each 'out' or 'inout' type parameter. Specific case: If the method is
declared without any of the 'static', 'key only' or 'const' attributes, the first returned value must coincide with
the modified entity. It is possible to return a new object or to return the first modified parameter.
For example:
function nms_recipient_setLastName(self, name)
{
self.@lastName = name
return self
}
Static methods
Static SOAP methods are accessed by invoking a method on the object representing the schema. Schemas
are properties of 'namespace' objects. These namespaces are global variables, thus, for example, xtk or nms
variables represent the corresponding namespaces
The following example invokes the static PostEvent method of the xtk:workflow schema:
n Query
<?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:ns='http://xml.apache.org/xml-soap'
xmlns:SOAP-ENV='http://schemas.xmlsoap.org/soap/envelope/'>
<SOAP-ENV:Body>
<PostEvent xmlns='urn:xtk:workflow'
SOAP-ENV:encodingStyle='http://schemas.xmlsoap.org/soap/encoding/'>
<__sessiontoken xsi:type='xsd:string'>
___bfBION4p4N90OyihicclVGUBGID4I1yFM/AmGdT8HJT/
Q9whwdIiusxkjsNGlNEscxrtiCAnhedJKyfPw9M4YdESzrLvGPj5EkJUIAIA</__sessiontoken>
<param xsi:type='xsd:string'>WKF76</param><param
xsi:type='xsd:string'>signal</param>
<param xsi:type='xsd:string'></param><param xsi:type='xsi:element'
SOAP-ENV:encodingStyle='http://xml.apache.org/xml-soap/literalxml'>
<variables recipientId="1234567890"/></param><param
xsi:type='xsd:boolean'>false</param>
</PostEvent>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
n Response
<?xml version='1.0'?>
<SOAP-ENV:Enveloppe 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>
<PostEventResponse xmlns='urn:xtk:workflow'
SOAP-ENV:encodingStyle='http://schemas.xmlsoap.org/soap/encoding/'></PostEventResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Enveloppe>
Non-static methods
To use non-static SOAP methods, it is necessary first to retrieve an entity using the "get" or "create" methods
on the corresponding schemas.
The following example invokes the ExecuteQuery method of the "xtk:queryDef" schema:
var query = xtk.queryDef.create(
<queryDef schema="xtk:workflow" operation="select">
<select>
<node expr="@internalName"/>
</select>
</queryDef>
)
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 = 'peter.martinez@neolane.com'"/>
</where>
</queryDef>)
logInfo(recipient.@firstName)
logInfo(recipient.@lastName)
logInfo(recipient.@lastName)
}
Appendix 1 - Examples
Java
// Session token for authentication
String strSessionToken =
"___+3RILwXYXaWyfCCw0WZpoybPHn46K+3rpwNHzNlD81LzKEp2Pz7ivunIfEkJUIAIA";
// Build SOAP envelope message
String strRequest = "<?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:ExecuteQuery xmlns:m='urn:xtk:queryDef' SOAP-
ENV:encodingStyle='http://xml.apache.org/xml-soap/literalxml'>"+
" <sessiontoken xsi:type='xsd:string'
SOAP-ENV:encodingStyle='http://schemas.xmlsoap.org/soap/encoding/'>"+strSessionToken+"</sessiontoken>"+
" <entity xsi:type='ns:Element'
SOAP-ENV:encodingStyle='http://xml.apache.org/xml-soap/literalxml'> +
" <queryDef operation="select" schema="nms:service" xtkschema="xtk:queryDef">
" ... " +
" </queryDef></entity></m:ExecuteQuery>"+
" </entity>"+
" </m:ExecuteQuery>"+
" </SOAP-ENV:Body>"+
"</SOAP-ENV:Envelope>";
// Display error
e.printStackTrace();
}
PHP
The following example uses the PEAR SOAP library.
<?
include("SOAP/Client.php");
include("XML/Parser.php");
?>
C#
To use the SOAP service, you must generate dedicated classes (wrapper) from the WSDL file. The steps to
apply are as follows:
namespace SoapSample
{
class SampleSoapApp
{
[STAThread] static void Main(string[] args)
{
// Build a query document to get list of services (schema nms:service)
XmlDocument docQuery = new XmlDocument();
XmlElement elemQuery = docQuery.CreateElement("queryDef");
elemQuery.SetAttribute("schema", "nms:service");
elemQuery.SetAttribute("operation", "select");
XmlElement elemSelect = docQuery.CreateElement("select");
XmlElement elemNode = docQuery.CreateElement("node");
elemNode.SetAttribute("expr", "@name");
elemSelect.AppendChild(elemNode);
elemNode = docQuery.CreateElement("node");
elemNode.SetAttribute("expr", "@label");
elemSelect.AppendChild(elemNode);
elemQuery.AppendChild(elemSelect);
}
}
}
Visual Basic
Dim elemRoot As IXMLDOMElement
Set elemRoot = xmlDoc.documentElement
Dim listResult As IXMLDOMNodeList
PHP examples
Writing to the database
Writing to the database with the "Write" method from an input form:
Source code:
<?
include("SOAP/Client.php");
include("XML/Parser.php");
if ($client->fault)
{
# Show eror if needed
echo '<h2>Fault (This is expected)</h2><pre>'; print_r($result); echo '</pre>';
}
else
{
# Traces (to dump client request and server response)
echo "<hr>REQUEST:\n" . htmlentities($client->__getLastRequest()) . "\n";
echo "<hr>RESPONSE:\n" . htmlentities($client->__getLastResponse()) . "\n";
}
?>
Subscription to a service
Subscription to a service with the "Subscribe" method and updating of certain profile fields.
Note:
A drop-down list displays the services that are active in the database.
Source code:
<?
#
# Update recipient
# Example of implementation of SOAP for PHP with Web Services
# Validated with the Pear SOAP PHP library (http://pear.php.net)
#
include("SOAP/Client.php");
$recipientElement .= "</recipient>";
$client=new SOAP_Client($url);
$client->setEncoding('ISO-8859-1');
$result = $client->call('Subscribe', $params, $options);
?>
C# example
Example of writing data to the recipient table with retrieval of a valid identifier.
using System;
using System.Xml;
using System.Web.Services.Protocols;
using System.Diagnostics;
namespace SoapSample
{
class SampleSoapApp
{
[STAThread]
static void Main(string[] args)
{
// Build a document to insert a recipient:
XmlDocument docRcp = new XmlDocument();
// User/password
string strSessiontoken = "internal/";
try
{
// Launch query to get new id
String strId = srvcSession.GetNewIds(strSessiontoken, 1);
catch (SoapException e)
{
System.Console.WriteLine("Soap exception: " + e.Message);
if (e.Detail!= null)
System.Console.WriteLine(e.Detail.InnerText);
}
}
}
}
JSP example
Reads from and writes to the database using the "ExecuteQuery" and "Write" methods from an input form.
This example uses the classes developed by Neolane in order to simplify SOAP method calls.
Source code:
<%@ page import="com.neolane.fwk.xtk.JSPContext, com.neolane.fwk.soap.SoapMethodCall"%>
<%@ page import="com.neolane.fwk.dom.DomUtil, org.w3c.dom.Element, org.w3c.dom.Document"
%>
<%@ page contentType="text/html" %>
<%@ page session="false" %>
<%!
// URL server
String s_strURLServer;
/**
* Helper function to execute a query and return element
*/
Element executeQuery(JSPContext ctx, String strQuery) throws Exception
{
// Do the soap call to writer
SoapMethodCall soapCall
= new SoapMethodCall("xtk:queryDef", "ExecuteQuery",
SoapMethodCall.SOAP_ENCODING_NATIVE,
ctx.getAsXML(ctx.STR_CTX_SESSION_TOKEN),
ctx.getRemoteAddr());
soapCall.writeDocument("document", strQuery);
soapCall.finalizeDocument();
ctx.executeSOAPCall(soapCall);
Element elem = soapCall.getNextElement();
soapCall.checkNoMoreArgs();
return elem;
}
/**
* Helper function to write entity
*/
public void writeEntity(JSPContext ctx, String strEntity) throws Exception
{
// Do the soap call to writer
SoapMethodCall soapCall
= new SoapMethodCall("xtk:persist", "Write",
SoapMethodCall.SOAP_ENCODING_NATIVE,
ctx.getAsXML(ctx.STR_CTX_SESSION_TOKEN),
ctx.getRemoteAddr());
soapCall.writeDocument("document", strEntity);
soapCall.finalizeDocument();
ctx.executeSOAPCall(soapCall);
}
/**
* Display html
*/
String Display(String strAction,
String strResult)
{
String strHtml = "";
return strHtml;
}
%>
<%
response.setContentType("text/html");
JSPContext ctx = new JSPContext(request, this);
s_strURLServer = "http://"+request.getHeader("host");
String strAction = "";
String strError = "";
String strResult = "";
try
{
ctx.loadContext();
// Display error
strError = e.getMessage();
}
%>
<html>
<body>
<%
if (strError.length() > 0)
// Display error
out.write(strError);
else
// Display html page
out.write(Display(strAction, strResult));
%>
</body>
</html>
Queries
The first step consists in collecting the data from the profile. To achieve this, you must use the ExecuteQuery
method of xtk:QueryDef :
This method involves two parameters:
n sessiontoken: identifier/password
n document: XML document defining the query
The following is an example of an XML document defining the query:
<queryDef operation="getIfExists" schema="nms:recipient" startPath="/"
xtkschema="xtk:queryDef">
<where>
<condition expr="@account = '00000GZ48'"/>
</where>
<select>
<node expr="@email"/>
<node expr="@mobilePhone"/>
<node expr="@format"/>
<node expr="@account"/>
<node expr="[subscription/service/@name]"/>
</select>
</queryDef>
The following is a full example of a SOAP query. Note that the identifier used is internal, temporarily without
a password.
<?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:ExecuteQuery xmlns:m='urn:xtk:queryDef'
SOAP-ENV:encodingStyle='http://schemas.xmlsoap.org/soap/encoding/'
<sessiontoken xsi:type='xsd:string'internal/</sessiontoken
<document xsi:type='' 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="@mobilePhone"/
<node expr="@format"/
<node expr="[subscription/service/@name]"/
</select
<where
<condition expr="[@folder-id] = 1073"/
<condition expr="@account = '00000GZ48'"/
</where
</queryDef
</document
</m:ExecuteQuery
</SOAP-ENV:Body
</SOAP-ENV:Envelope
This query must be made using the /nl/jsp/soaprouter.jsp URL of your Neolane application server:
http://myserver.neolane.net/nl/jsp/soaprouter.jsp
To recover the next 100 records, use the same query again and add the startLine attribute.
Example :
<queryDef firstRows="true" lineCount="100" startLine="100"
Tip:
The index of the first line is set to zero, therefore startLine="0" enables you to go to the start of the list.
In our example, we find the requested data from the profile (account, email, format and mobilePhone)
and the list of active subscriptions.
Submitting modifications
To submit the modifications made to the profile, you must create a Web form, then call the ValidateForm
method of the nms:webForm schema on this form.
This method involves three parameters:
n sessiontoken: identifier/password
n formName: name of the form,
n recipients: modified data of the profile.
Example of a SOAP call for modifying a profile:
<?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:ValidateForm xmlns:m='urn:nms:webForm'
SOAP-ENV:encodingStyle='http://schemas.xmlsoap.org/soap/encoding/'>
<sessiontoken xsi:type='xsd:string'>internal/</sessiontoken>
<formName xsi:type='xsd:string'>SAC</formName>
<recipients xsi:type=''
SOAP-ENV:encodingStyle='http://xml.apache.org/xml-soap/literalxml'><recipientsList>
<recipient account="00000GZ48" email="john.doe@neolane.net"
format="0" mobilePhone="06 80 75 21 59">
<subscribe name="SVC9" value="1"/>
<subscribe name="SVC10" value="1"/>
<subscribe name="SVC8" value="0"/>
<subscribe name="SVC11" value="0"/>
<subscribe name="SVC12" value="1"/>
</recipient>
</recipientsList>
</recipients>
</m:ValidateForm>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Table of Contents
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
Navigation hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . 189
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . 190
Edition . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
Home page . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
Content personalization (title, shortcuts) . . . . . . . . . . . . . . . . . 197
Advanced personalization . . . . . . . . . . . . . . . . . . . . . . 200
Introduction
The Neolane graphical interface can be configured to suit your needs. You can change:
n The browse tree: refer to Navigation hierarchy [page 189].
n The home page: refer to Home page [page 196].
You can also create or change the overviews of the various Neolane edit forms. To do this, you
need to use Web applications. This functionality is detailed in the "Web Applications" section of the
Web Functionalities guide.
Navigation hierarchy
Overview
The navigation hierarchy works like a file browser (e.g. Windows Explorer). Folders may contain
sub-folders. Selecting a node displays the view corresponding to the node.
The view displayed is a list associated with a schema and an input form to edit the selected line.
To add a new folder to the tree, right-click the folder in the branch where you wish to insert a folder, and
select Add new folder. In the shortcut menu, select the type of file to be created.
Configuration
The types of folders used by the navigation list are described in an XML document that obeys the grammar
of the xtk:navtree schema.
The XML document is structured as follows:
<navtree name="name" namespace="namespace">
<!-- Global orders -->
<orders>
...
</orders>
The XML document contains the <navtree> root element with the name and namespace attributes to
specify the document name and namespace. The name and namespace make up the document identification
key.
The global commands of the application are declared in the document from the <commands> element.
The declaration of file types is structured in the document with the following elements: <model> and
<nodeModel>.
Global commands
A global command lets you launch an action. This action can be an input form or a SOAP call.
Global commands are accessible from the main Tools menu.
The command configuration structure is as follows:
<commands>
<!-- Description of a command -->
<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>
<!-- Separator -->
<command label="-" name="<name>"/>
<!-- Command structure -->
<command name="<name>" label="<Label>">
<command...
</command>
</commands>
The description of a global command is entered in the <command> element with the following properties:
n name: internal name of the command: the name must be entered and unique
n label: label of the command.
n desc: description visible from the status bar of the main screen.
n form: form to be launched: the value to be entered is the identification key of the input form (e.g.
"cus:recipient")
n rights: list of named rights (separated by a comma) allowing access to this command. The list of available
rights is accessible from the Administration/Access management/Named rights folder.
n promptLabel: displays a confirmation box before execution of the command
A <command> element can contain <command> sub-elements. In this case, the parent element lets
you display a sub-menu made up of these child elements.
The commands are displayed in the same order as they are declared in the XML document.
A command separator lets you display a separation bar between commands. It is identified by the '-' value
contained in the command label.
The optional presence of the <soapCall> tag with its input parameters defines the call of a SOAP method
to be executed. For further information on the SOAP API, refer to the jsapi.chm online help section.
The form context can be updated on initialization from the <enter> tag. For further information on this
tag, refer to the documentation on input forms.
Example :
n Declaration of a global command to launch the "xtk:import" form:
<command desc="Start the data import wizard" form="xtk:import" label="&Data
import..." name="import" rights="import,recipientImport"/>
A keyboard shortcut is declared on the 'I' character by the presence of & in the command label.
n Example of a sub-menu with a separator:
Folder type
A folder type lets you give access to the data of a schema. The view associated with the folder consists of
a list and an input form.
The folder type configuration structure is as follows:
<!-- Structured space for adding a folder -->
<model name="name" label="Label">
<!-- Folder type -->
<nodeModel name="<name>" label="<Label>" img="<image>">
<view name="<name>" schema="<schema>" type="<listdet|list|form|editForm>">
<columns>
<node xpath="<field1>"/>
...
</columns>
</view>
</nodeModel>
<model name="<name>" label="<Sub model>">
...
</model>
</model>
The folder type declaration must be entered under a <model> element. This element lets you define a
hierarchical organization visible from the Add new folder menu. A <model> element must contain
<nodeModel> elements and other <model> elements.
The name and label attributes populate the internal name of the element and the label displayed in the
Add new folder menu.
The <nodeModel> element contains the description of the folder type with the following properties:
n name: internal name
n label: label used in the Add new folder menu and as a default label when inserting a folder.
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".
Note:
The name of the input form can be overloaded by entering the form attribute in the <view> element.
The default configuration of the list columns is entered via the <columns> element. A column is declared
on a <node> element containing the xpath attribute with the field to be referenced in its schema as its
value.
Example: declaration of a folder type on the "nms:recipient" schema.
<model label="Profiles and targets" name="nmsProfiles">
<nodeModel deleteRight="folderDelete" editRight="folderEdit" folderLink="folder"
img="nms:folder.png" insertRight="folderInsert" label="Recipients"
name="nmsFolder">
<view name="listdet" schema="nms:recipient" type="listdet">
<columns>
<node xpath="@firstName"/>
<node xpath="@lastName"/>
<node xpath="@email"/>
<node xpath="@account"/>
</columns>
</view>
</nodeModel>
<nodeModel name="nmsGroup" label="Groups"...
</model>
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 commands
A shortcut command lets you launch an action on selecting the list. The action can be an input form or a
SOAP call.
Commands are accessible from the Action menu of the list or the associated menu button.
The command configuration structure is as follows:
<nodeModel...
...
<command name="<name>" label="<label>" desc="<Description>" form="<form>"
rights="<rights>">
<soapCall 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 available
rights is accessible from the Administration/Access management/Named rights folder.
n promptLabel: displays a confirmation box before execution of the command
n monoSelection: forces mono-selection (multiple selection by default).
n refreshView: forces reloading of the list after execution of the command.
n enabledIf: activates the command depending on the expression entered.
n img: enters an image allowing access to the command from the list toolbar.
A <command> element can contain <command> sub-elements. In this case, the parent element lets
you display a sub-menu made up of these child elements.
The commands are displayed in the same order as they are declared in the XML document.
A command separator lets you display a separation bar between commands. It is identified by the '-' value
contained in the command label.
The optional presence of the <soapCall> tag with its input parameters defines the call of a SOAP method
to be executed. For further information about SOAP APIs, refer to the jsapi.chm online help section.
The form context can be updated on initialization via the <enter> tag. For further information about this
tag, refer to the input form documentation.
Example :
<command desc="Cancel execution of the job" enabledIf="EV(@status, 'running')"
img="nms:difstop.bmp" label="Cancel..." name="cancelJob"
promptLabel="Do you really want to cancel this job?" refreshView="true">
<soapCall name="Cancel" service="xtk:jobInterface"/>
</command>
<command label="-" name="sep1"/>
<command desc="Execute selected template" form="cus:form" lmonoSelection="true"
name="executeModel"
rights="import,export,aggregate">
<enter>
<set expr="0" xpath="@status"/>
</enter>
</command>
Linked folder
There are two types of folder management operations:
1 The folder is a view: the list displays all records associated with the schema, with the possibility of system
filtering entered in the folder properties.
2 The folder is linked: the records in the list are implicitly filtered on the folder link.
For a linked folder, the folderLink attribute on the <nodeModel> element must be populated. This attribute
contains the name of the link on the folder configured in the data schema.
Example of declaration of a linked folder in the data schema:
The configuration of the <nodeModel> on the link of the folder named "folder" is as follows:
<nodeModel deleteRight="folderDelete" editRight="folderEdit" folderLink="folder"
img="nms:folder.png" insertRight="folderInsert" label="Recipients" name="nmsFolder">
...
</nodeModel>
Edition
The screen for creating and configuring the navigation hierarchy configuration documents is accessible via
the Administration/Configuration/Navigation hierarchies node:
The navigation hierarchy configuration is divided over several XML documents. It operates on a similar
principle to schema extension: all documents are merged to generate a single document containing the whole
configuration. This document cannot be edited, and is displayed via the "Preview" tab.
The edit field provides the content of the XML document:
Note:
The "Name" edit control lets you enter the document key consisting of the name and namespace. The "name"
and "namespace" attributes of the <navtree> element are automatically updated in the XML edit field of
the schema.
The preview automatically generates the merged document containing the complete configuration:
Home page
During connection to the client interface, the Neolane home page is displayed by default. It is a configurable
dashboard which varies based on the applications installed and operator rights. It is made up of menus and
shortcuts which let you access the elements of the installed applications (Delivery, Campaign, MRM, etc.)
and the overall platform configurations.
This home page can be personalized if you want to change its content and layout. The section below details
the configuration of the Neolane home page to suit your needs, including to display shortcuts and menus
other than the default Neolane features. The screenshot below is an example of a Neolane Campaign default
home page.
The list of out-of-the-box dashboards is displayed in the upper right-hand section of the console. The home
page dashboard is called Welcome to Neolane v6.0.
Warning:
Remember that you must not modify the out-of-the-box files. The Neolane console will not let you do so
since the dashboards are in read-only format.
Configuration
There are two ways of personalizing the title and shortcuts on the home page:
n duplicate the home page dashboard if you want to start from the existing home page. To do this, right-click
the Welcome to Neolane v6.0 dashboard and select Duplicate.
n create a new dashboard if you'd rather start with a blank page: right-click the list of dashbords and click
New, or use the New button above the list of dashboards.
Then fill in the General, Views and Operators tabs of the dashboard and click the Save button in the
upper right-hand section of the dashboard editing window. The various tabs are detailed here:
General Tab
This tab lets you define the title which is displayed in the upper left-hand section of the home page (Label
field), select the main menu (refer to Advanced personalization [page 200]) and decide whether or not to set
this dashboard as the default home page. You can also hide certain menus (List of hidden menus field).
Views Tab
This screen lets you define the various sections or views or your home page as well as their content. It
contains a tab for each section of the home page. The buttons in the upper left-hand section of the window
let you add or delete sections and change their display sequence on the home page. In the following example
(Neolane Campaign default configuration), the Campaigns tab coincides with the first section of the home
page, and the Reports/Deliveries tab coincides with the second section which is made up of the Global
reports and the Deliveries blocks.
Each tab lets you personalize the matching section on the home page. Here is the list of fields to be filled
in:
Warning:
When entering text, you must comply with XHTML syntax rules. For instance, all open tags must be
closed.
n The List of links tab lets you add links to the block. Use buttons in the upper right-hand section of the
list of links to add or delete links, change their display sequence in the block or show their details.
In the upper section of the window, the drop-down menu lets you personalize the display of links on one
or two columns.
For each link, you need to define a label, an internal name, and a view type (view or report) as well as
the name of the view which the link will point to. You can also add an image, a description, and
display/access rights.
n The Page footer tab lets you enter a text to be displayed at the bottom of the block.
Warning:
When entering text, you must comply with XHTML syntax rules. For instance, all open tags must be
closed.
n The Web page tab lets you add a web page to your block. Select the type of web page you want to
insert: Web application, Report, website (URL) or Ajax component.
Then define the web application or the report which you want to display in the block. To insert a website,
simply enter its URL.
You can also choose to show or hide the title of the website and force page width and length. If you
enter 0 as a value, the layout will adapted automatically.
Operators tab
This tab lets you view the list of operators which the dashboard is assigned to. To find out how to assign a
dashboard to an operator, refer to Assigning to an operator [page 199].
Assigning to an operator
Note:
If nothing is assigned, operators logging on will access the default dashboard. If a dashboard is assigned to
an operator, they will access this particular dashboard even if it isn't the default one.
3 In the operator properties window, go to the General tab and enter the Dashboard field.
Advanced personalization
Menu personalization
The menus on the home page provide access to all the main screens of the platform. They vary based on
the applications installed and operator rights. The screenshot below is an example of the default menus
provided with Neolane Campaign. The following section details menu personalization.
Structure
Menus are configured in XML documents available via Administration/Configuration/Navigation
hierarchies.
For each out-of-the-box module or installed application, there is a document that obeys the grammar of the
xtk:navtree schema.
For example, the nms:core out-of-the-box file coincides with the Delivery module, the nms:campaign file
coincides with the Campaign module, and the nms:mrm file with the MRM module, etc.
For more information on the xtk:navtree schema, refer to Navigation hierarchy [page 189].
The following document coincides with the structure of the Deliveries menu:
...
<!--Description of the main "home" menu which contains the "Deliveries" menu-->
<menu img="nl:urlcnx.png" label="Main menu" name="home">
</command>
</command>
</menu>
</navtree>
Note:
If you don't enter the label and the menu links to a view, the menu will take the name of the view.
Warning:
If your menu contains sub-menus, you can't link it to a view. However, all sub-menus of this last level
need to be linked to a view.
Example of an Advanced menu declaration with its various menus and sub-menus:
<command img="xtk:admin.png" label="Advanced" name="advanced" order="50">
<command name="explorer" order="10" view="navtree"/>
<command name="operating" order="20" rights="admin"
view="nlOperating"/>
<command img="xtk:admin.png" label="Administration"
name="administration" order="30" rights="admin">
<command name="nlImportPackage" order="10" view="nlImportPackage"/>
<command name="nlExportPackage" order="20" view="nlExportPackage"/>
</command>
</command>
Configuration
Warning:
Remember that you must not change the out-of-the-box files. The Neolane console won't let you make
changes since the files are read only.
n To modify the content of the existing home page, create a new xtk:navtree document via
Administration/Configuration/Navigation hierarchies.
n Integrate the <menu> and <command> elements. Refer to the previous section for more information
on menu structure.
You can declare several menus in the same file if necessary; simply repeat the <command> element for
each one.
For example, to add a new menu with various sub-menus, you need to enrich the main menu with the home
internal name using the following syntax:
<navtree label="Example of the creation of a new " name="example" menu namespace="cus"
xtkschema="xtk:navtree">
<menu name="home">
<command label="New menu" name="newMenu" order="23">
<command label="Menu 1" name="menu1" order="10">
<command label="Sub-menu 1" name="subMenu1" order="10" view="newWorkflow"/>
<command label="Sub-menu 2" name="subMenu2" order="20" view="nlWorkflow"/>
</command>
<command label="Menu 2" name="menu2" order="20">
<command label="Sub-menu 1" name="subMenu1" order="10" view="newImport"/>
<command label="Sub-menu 2" name="subMenu2" order="20" view="newExport"/>
</command>
</command>
</menu>
</navtree>
It is also possible to extend the menus already in your xtk:navtree file to include new sub-menus or to hide
existing sub-menus.
For instance, to hide the Stocks sub-menu, insert the following syntax into your XML document:
<navtree label="Example of home page extension" name="example" namespace="cus"
xtkschema="xtk:navtree">
<menu name="home">
<command name="campaigns">
<command _operation="delete" label="Stocks" name="campaignStock"/>
</command>
</menu>
</navtree>
To change the name which appears on the tab and footer of the home page, you need to enrich the tab with
home as an internal name using the following syntax:
<windows>
<window name="home" label="My title">
<footer>
<![CDATA[<p>
New page footer</p>]]>
</footer>
</window>
</windows>
1 Create a new css stylesheet (dashboard2.css in this example) and store it on the application server.
For instance, to change the logo in the top left-hand corner of the home page, overload the styles of the
HTML rendering in keeping with the following syntax:
div#logo {
background-image: url(/cus/img/logo2.png);
}
2 Extend the parameters of your xtk:navtree document to reference the newly created stylesheet. The
default stylesheet is called dashboard.css. Create a new xtk:navtree type document and comply with
the following syntax:
<windows>
<window name="home" css="/cus/css/dashboard2.css">
</window>
</windows>
Table of Contents
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
Precisions . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
Recommendations and limitations . . . . . . . . . . . . . . . . . . . 206
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
The View attribute . . . . . . . . . . . . . . . . . . . . . . . . 206
Names of tables and columns . . . . . . . . . . . . . . . . . . . . 207
Indexed fields . . . . . . . . . . . . . . . . . . . . . . . . . . 207
Setting up a target mapping . . . . . . . . . . . . . . . . . . . . . . 207
Creating and configuring the schemas linked to the external table . . . . . . . . 208
Using target mapping . . . . . . . . . . . . . . . . . . . . . . . 211
Configuring the interface to use the new recipient table . . . . . . . . . . . . 211
Creating a new form . . . . . . . . . . . . . . . . . . . . . . . . 211
Creating a new type of folder in the navigation hierarchy . . . . . . . . . . . 212
Creating a new web application and displaying the table content . . . . . . . . 212
Configuring seed addresses based on an external recipient table . . . . . . . . . 216
Implementation . . . . . . . . . . . . . . . . . . . . . . . . . 217
Creating filters to manipulate the new recipient table . . . . . . . . . . . . . 218
Creating lists based on the external recipient table . . . . . . . . . . . . . . 218
Introduction
Overview
This section details the principles for using a non-standard recipient table. By default, Neolane offers
a standard recipient table to which out-of-the-box functions and processes are linked. Using a
non-standard table, or 'external recipient table', requires certain pre-installation precautions when
implementing it.
Precisions
This functionality allows Neolane to process data from an external database: this data will be used
as a set of profiles for deliveries. Implementing this process involves several precisions that may
be relevant according to the client's needs. Such as:
n No update stream to and from the Neolane database: data from this table can be updated
directly via the database engine that hosts it.
Note:
You can still create recipient lists using workflows. For more on this, refer to the Creating lists based on
the external recipient table [page 218] section.
We also recommend checking the default values used in the different out-of-the-box configurations: depending
on the functionalities used, several adaptations must be carried out.
For example:
n Certain standard reports, particularly those offered by the Interaction and Response Manager modules,
must be re-developed.
n The default configurations for certain workflow activities reference the standard recipient table
(nms:recipient): these configurations must be changed when used for an external recipient 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 recipient 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.
In this example, if the names of the tables and columns had not been explicitly specified, the application
would have used CusIndividual for the table, lastName and firstName for the columns.
In a schema, it is possible to populate only part of the columns of an existing table. Unpopulated columns
will not be user-accessible.
Indexed fields
When sorting the records of a list from the client console, better performance is obtained by sorting on
indexed fields. Declaring an index in a schema makes the console display the indexed fields with a red line
under the sort-order arrow to the left of the column label, as shown below:
That's why it is important to declare existing indexes of the external table in the matching schema.
An index is implicitly declared for each key and link declaration of the source schema. Index declaration can
be prevented by specifying the noDbIndex="true" attribute:
Example :
<key internal="true" name="customer" noDbIndex="true">
<keyfield xpath="@customerId"/>
</key>
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 69].
In our example, we will create a customer schema, a very simple table containing the following fields:
ID, first name, last name, email address, mobile phone number. The aim is to be able to send e-mail or
SMS alerts to the individuals stored in this table.
Example schema (cus:individual)
<srcSchema name="individual" namespace="cus" label="Individuals">
<element name="individual">
<key name="id" internal="true">
<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 206].
<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>
6 Enter the Label field and select the schema which you have just created in the Targeting dimension
field.
7 In the Edit address forms window, select the fields of the schema which match the various delivery
addresses. Here, we are able to map the @email and @mobile fields.
8 In the following Storage window, enter the Suffix of the extension schemas field to differentiate
the new schemas from the out-of-the-box schemas provided by Neolane.
By default, exclusion management is stored in the same tables as messages. Check the Generate a
storage schema for tracking box if you want to configure storage for the tracking linked to your target
mapping.
9 In the Extensions window, select the optional schemas which you want to generate (the list of available
schemas depends on the modules installed on the Neolane platform).
Important:
The name of the form must be identical to the name of the schema which it concerns.
Note:
To find out more about form type files, refer to Input forms [page 135].
In our current example, the form file must be based on the cus:individual schema and therefore have
the following layout:
<container colspan="2">
<input xpath="@id"/>
<static type="separator"/>
</container>
<container colcount="2">
<input xpath="@lastName"/>
<input xpath="@firstName"/>
<input xpath="@email"/>
<input xpath="@mobile"/>
</container>
Note:
For more on navtree type files, refer to Neolane Graphical interface [page 189].
In the current example, the navtree file must be based on the cus:individual schema and therefore
have the following form:
<model name="root">
<nodeModel img="nms:usergrp.png" label="My recipient table" name="cusindividual">
<view name="listdet" schema="cus:individual" type="listdet">
<columns>
<node xpath="@id"/>
<node xpath="@lastName"/>
<node xpath="@firstName"/>
<node xpath="@email"/>
<node xpath="@mobile"/>
</columns>
</view>
</nodeModel>
</model>
4 Select the name of the schema that matches the external recipients table (cus:individual) in the
Document type field.
10 Go to the Data tab of the List item and select the schema which matches your new recipient table.
11 Select the fields you want to display on the list. It is also possible to add sorting or apply filters for the
returned values.
Note:
For more on the functional scope of web applications, refer to the "Web Applications" chapter in the
Web functionalities guide.
The Dashboard of the web application must specify the schema which defines the external table, as
shown below:
<views>
<view folderModel="cusIndividual" img="nms:rcpFolder.png" label="Individuals"
name="cusIndividual" webApp="individual"/>
</views>
<menu name="home">
<command label="Profiles and targets" name="nlTarget" order="40">
<command name="Individual" view="cusIndividual" viewType="view"/>
</command>
</menu>
</navtree>
5 Log off and back on to view the new home page with the menu pointing towards the external recipient
table.
For more on using seed addresses, refer to the "Seed addresses" section of the Neolane Delivery guide.
Implementation
The nms:seedMember schema and the linked form which come out-of-the-box are meant to be extended
for customer configuration, to reference all necessary fields. The schema definition contains comments
detailing its configuration mode.
Definition of the recipients table extended schema:
<srcSchema label="Person" name="person" namespace="cus">
<element autopk="true" label="Person" name="person">
<attribute label="LastName" name="lastname" type="string"/>
<attribute label="FirstName" name="firstname" type="string"/>
<element label="Address" name="address">
<attribute label="Email" name="addrEnv" type="string"/>
</element>
attribute label="Code Offer" name="codeOffer" type="string"/>
</element>
</srcSchema>
This element must contain the fields required to export the campaigns. These fields should have the
same name as the corresponding fields in the external schema. For example, if the schema is cus:person,
the nms:seedMember schema should be extended as follows:
<element name="seedMember">
<element aggregate="cus:seedMember:common"/>
</element>
</srcSchema>
Note:
The extension of the nms:seedMember schema must comply with the structures of a campaign and a
delivery in Neolane.
Warning:
During the extension, you must specify an SQL name (@sqlname) for the 'email' field. The SQL name
must differ from the 'sEmail' that is reserved for the recipient schema.
Warning:
You must update the database structure with the schema created when extending nms:seedMember.
3 The seedMember form must be modified accordingly to define a new tab in the Seed addresses
window.
<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)">
If all attributes of the seed address aren't entered, Neolane automatically substitutes the profiles: they will
be entered automatically during personalization using data from an existing profile.
4 Double-click the Query activity, then click Edit the query to choose a targeting dimension based on
the schema of the new recipient table (in our example: Individual).
The dashboard specifies the schema which the list is based on, as shown below:
Table of Contents
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
Implementation steps . . . . . . . . . . . . . . . . . . . . . . . . 221
Building a report . . . . . . . . . . . . . . . . . . . . . . . . . . 222
Creating a new report . . . . . . . . . . . . . . . . . . . . . . . 222
Defining the content of the report . . . . . . . . . . . . . . . . . . . 223
Advanced configuration . . . . . . . . . . . . . . . . . . . . . . . 259
Laying out a descriptive analysis report . . . . . . . . . . . . . . . . . 264
Configuring data . . . . . . . . . . . . . . . . . . . . . . . . . . 271
Data in context . . . . . . . . . . . . . . . . . . . . . . . . . 271
Data filtering . . . . . . . . . . . . . . . . . . . . . . . . . . 273
Accessing reports . . . . . . . . . . . . . . . . . . . . . . . . . . 275
Report display . . . . . . . . . . . . . . . . . . . . . . . . . . 275
Creating a link to a report . . . . . . . . . . . . . . . . . . . . . . 280
Report preview . . . . . . . . . . . . . . . . . . . . . . . . . 282
Publishing the report . . . . . . . . . . . . . . . . . . . . . . . 282
Processing reports . . . . . . . . . . . . . . . . . . . . . . . . . 283
Export . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
Printing . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
History . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
Calculation and closure . . . . . . . . . . . . . . . . . . . . . . . 287
Opening in a web browser. . . . . . . . . . . . . . . . . . . . . . 288
Introduction
In order to produce statistics on the data in the bases, you can create reports and tailor them your
needs. You can also share these reports with other users.
You can create reports directly from the Neolane tree by going to the Report node .
You can also make these reports accessible in the descriptive analysis wizard. This wizard can be
used in another Neolane module (workflow or advanced targeting, for example). Refer to "Analyzing
populations: the descriptive analysis wizard" in the Neolane Platform guide for further information.
Implementation steps
Apply the following steps to create, publish and deliver an analysis report on your data:
Tip:
To avoid modifying the report templates, it is advisable to create a special sub-folder for the reports you are
going to create. To do this, right-click the Reports node in the tree and select Create a new 'Reports'
folder.
Building a report
4 Select the report template you need using the drop-down list. By default, the following templates are
available:
n Extended report to create a configured report using a diagram.
n Qualitative distribution to generate statistics on all types of data (e.g. company name, e-mail
domain, etc.). For further information, refer to the "Analyzing populations: the descriptive analysis
wizard" step in the Neolane Platform guide.
n Quantitative distribution to compile statistics on measurable or countable data (e.g. invoice
amount, recipient age). For additional information, refer to the "Analyzing populations: the descriptive
analysis wizard" step in the Neolane Platform guide.
5 Enter the name and description of the report in the appropriate fields. This information will be displayed
as the title and sub-title of the report when it is displayed in the list of Available reports.
'Start' activity
This activity lets you mark the start of the diagram graphically. It is mandatory when the diagram contains
a loop.
'Page' Activity
Important:
You can configure the page layout of the report and overload it for each container. The pages are arranged
in columns. Containers are also arranged in columns, except for static elements and charts, which are arranged
in cells.
For more information on layout, refer to the Element layout section of the Web functionalities guide.
n The General tab lets you change the page title, choose the position of labels, and configure browsing
between the various pages of the report.
The Title field lets you customize the label appearing in the header of the report page (not to be confused
with the window label, which is configurable via the Properties tab. For more on this, refer to the
Advanced configuration [page 259] section.
Tip:
If you decide to end your diagram with a Page activity, deselect the Enable outbound transitions
option.
The Display settings options let you choose the position of the controls caption in a report page and
define the number of columns on the page. For further information concerning page layout, refer to the
Element layout section of the Web functionalities guide.
Select the various options in the Navigation section to enable or disable moving between the various
pages of the report. When either the Disable Previous button or Disable Next button option are
selected, the Next or Previous buttons are not displayed in the report page.
n The Advanced tab lets you configure the page in view of exporting it. For further information, refer to
the Processing reports [page 283] section.
The Page activity can contain the following controls:
n Container, refer to the Standard container [page 227] section.
n Input areas, refer to the Input control [page 229] section.
n Static element, refer to the Static elements [page 231] section.
n Chart, refer to the Chart [page 231] section.
n Table, refer to the Table [page 234] section.
To insert a control, select it from the popup menu of the Page node or click the Add button in the toolbar.
The toolbar lets you add or delete controls and arrange their order of appearance in the pages of your report.
Standard container
For more information, refer to the Containers section of the Web functionalities guide.
The standard container lets you group several controls and configure their layout in columns and/or cells.
Example of a report with a container
In the following report, the page is built on two columns and includes four containers.
Each container is built on a column, except container 1, which contains two of them.
For more information on layout, refer to the Element layout section of the Web functionalities guide.
Input control
For more information on input areas, refer to the Form fields section of the Web Functionalities guide.
You can incorporate one or more input control into your reports. This type of control lets you filter the
information contained in the report.
The following input controls are available:
n Text: refer to the Input fields section of the Web Functionalities guide.
n Number: refer to the Input fields section of the Web Functionalities guide.
Examples:
Selection controls
For more on selection controls, refer to the Form fields section of the Web Functionalities guide.
You can integrate one or more selection controls into your reports. This type of control lets you filter the
information in the report.
n Combo box: refer to the Lists section of the Web Functionalities guide.
n Checkbox: refer to the Checkboxes section of the Web Functionalities guide.
n Radio button: refer to the Radio buttons section of the Web Functionalities guide.
n Multiple choice: refer to the Multiple choice section of the Additional features guide.
n Date: refer to the Dates section of the Web Functionalities guide.
n Matrix: view the Matrixes section of the Web Functionalities guide.
Examples:
Advanced controls
For more on advanced controls, refer to the Form fields section of the Web Functionalities guide.
You can integrate one or more advanced controls into your reports. These types of controls enable advanced
interactions with the report.
Static elements
Static elements let you simply display information in the report without any interaction with the user.
Warning:
If the report is to be exported, you are advised not to use any complex formatting in HTML. Refer to the
Export [page 284] section for further information.
Chart
This container lets you display your statistics in the form of a chart.
1 Select the desired type of chart in the popup menu of the Page activity.
2 In the General tab, indicate a name in the Label field and a caption for your chart.
3 Configure the number of cells the chart must occupy in the page of the report.
For more information on layout, refer to the Element layout section of the Web functionalities guide.
4 If necessary, configure an action for a click on the chart. Open the Interaction events window and
choose the action to be performed.
6 Choose the desired type of chart. You can select it in this window or choose it directly via the Add a
chart menu when it is created.
7 Refer to the "Analyzing populations: the descriptive analysis wizard" step in the Neolane Platform guide
for further information on data configuration.
Table
This container lets you display your statistics in various types of tables. These can be pivot tables or lists
with grouping.
Select the type of table from the popup menu of the Page activity.
Pivot table
1 In the General tab, specify a name in the Label field and a caption for your table.
2 For further information on data configuration, refer to "Analyzing populations: the descriptive analysis
wizard" step in the Neolane Platform guide.
You can also produce your statistics on the data in context.
Warning:
The Page activity containing the list must be preceded by a Query or Script activity in order to retrieve
the data to be analyzed in the report. Refer to the Script Activity [page 258] and Test Activity [page 257] section
for further information on these activities.
Grouping rule
You might need to analyze several categories of data at once. A list with a group lets you group certain data
and generate statistics on various data groups in the same table. To do this, you must create a group in the
table.
In the example below, grouping makes all the campaigns in your database appear, as well as deliveries and
the number of messages sent per delivery and per campaign.
It lets you list the campaigns (Label (Campaign)) and the deliveries (Label) attached to the campaign
and count the number of messages sent for each delivery (Processed), before adding them up for each
campaign (Sum(@processed)).
Procedure
Here is an example involving the creation of a table including a grouping list at the end of the section.
However, here is a summary of the steps required for creating this type of table:
1 Place a Query activity in the diagram of a report. (Refer to the Test Activity [page 257] section).
2 Complete the source table and select the fields of the table which the statistics will be based on.
3 Position a Page activity in the diagram. (Refer to the 'Page' Activity [page 225] section).
4 Insert a List with group table in the page (Refer to the Table design section below).
5 Specify the data path, i.e. the table chosen as the data source in the query.
Warning:
This step is essential in order to recover the fields of the source table and to insert them in the cells of
the table.
6 Create the table and insert the data (Refer to the Table design section below).
7 Preview the finalized report in the Preview tab.
8 Publish the report and export it to another format if necessary (Refer to the Export [page 284] section).
Ergonomics of lists with group
A group itself contains a header line, a detail line and a footer line.
n Table design
The group can be placed in any line of the table and contains its own header line, detail line and footer
line.
Line and column: to add or delete a line or column, go to an existing line or column and use the popup
menus.
The nature of the line you add depends on the location of the cursor. For example, to add a header line,
place your cursors on a header, then click Add >A line above/below.
The column width can be changed via Column format.
Grouping: likewise, to add a group, go to a line and select the appropriate entry in the popup menu.
The expressions correspond to the fields of the table previously defined as the source of the query. In
the example below, the available fields are those of the campaigns table.
If you need to place only one title in the cell of the table, simply complete the Label field and leave the
Expression field blank.
Aggregate: to perform calculations on your data, use the Aggregates menu entry and select the desired
operation.
Formatting tabs
The content and appearance of the cells can be formatted using the options available in the various tabs
of the Cell format window.
Note:
Use the Carriage return field when exporting data to Excel: select the Yes value to force the carriage
return. This value will be kept when exporting.
n Value tab: from this tab you can modify the font and attributes of values or assign a format to them
depending on their nature.
The format modifies the data display. For example, the Number, Currency and Percentage format
lets you align numbers on the right and display decimals.
n Borders tab: you can display the borders of your tables by selecting the appropriate options in this
tab.
n Click tab: you can trigger an action by clicking the content of a cell in the table.
In the example below, click the value in the cell to go to the second page of the report. For further
information, refer to the example below.
n Extra tab: The options available in this tab let you add a visual aid to your data, e.g. a color tab or
a bar graph. In the example below, the bar graph is used.
Next, you will configure both pages of your report, where each page must be preceded by a query specifying
the data to be processed.
Configuring Query N1
Apply the options to the output columns as indicated in the following table:
Foreign key of 'Campaign' link ('ID' Foreign key of 'Campaign' link ('id' No @campaignId
field) field) (@campaign-id)
Tip:
In our example, we assign an alias to each field. This operation is not mandatory, but allows easy selection
of the data in the table when configuring the first page of the report (see below).
4 Click Next until you reach the Data filtering page to create the following filter: "Foreign key of the
'Campaign' link greater than 0".
This filter lets you select only deliveries associated with a campaign.
5 Close the query configuration window and drop a Page activity in the diagram of the report. This page
must be linked to the query you have just created.
Configuring page N1
2 Check the Disable next page box to mask the Next button on the first page of the report.
3 Insert a list with group using the popup menu and give it a label, e.g. List of deliveries by
campaign.
4 Click the Table data XPath link and select the link for the deliveries, i.e. [query/delivery].
5 In the Data tab, add three columns to the right of the table.
This grouping will let you group the campaigns and the deliveries associated with them.
7 In the group window, reference the foreign key for the campaigns, then close the window.
8 Edit the first cell of the group header and insert the label of the campaigns as an expression.
9 Edit the second cell of the detail line and choose the delivery label as an expression.
12 Click Add in the context field and specify the value /vars/selectedDelivery for the path and the
value @deliveryId for the expression in order to configure the passage to the next page.
13 Edit the second cell of the group footer line and enter Total per campaign in the Label field of the
Expression window.
14 Edit the third cell of the group header line and enter Number of messages sent in the Label field
of the Expression window.
15 Edit the third cell of the detail line and select the indicator of the messages handled as an expression.
16 Edit the third cell of the group footer line, select the indicator of the deliveries processed and apply the
Sum aggregate to it.
17 Edit the fourth cell of the detail line and select the delivery error rate as an expression.
18 Select this same cell to apply a bar graph to the delivery error rate. To do this, access the cell format,
then the Plus tab. Then select Bar graph from the drop-down list and select the Hide the cell value
option.
You can now view your report if you wish. Click the Preview tab and select the Global option: you will
obtain the list of all deliveries related to a campaign.
Tip:
It is advisable to use the preview to check that you have selected and correctly configured the data in
your table. After performing this check, you may format your table.
19 Apply the Bold style to the cells containing the total per campaign and the sum of the messages processed.
20 Place your cursor on the first cell of the group header line and select Merge to right in the popup menu.
By merging the first two cells of the group header line, you reduce the gap between the campaign title
and the list of associated deliveries.
Warning:
Cells should not be merged until your report is complete, because this operation cannot be cancelled.
Configuring Query N2
The aim is to group the number of deliveries by e-mail domain. That's why you have to select the Group
option when configuring this query.
4 Click Next until you reach the Data filtering page in order to create the following filtering criterion:
"Foreign key of 'Delivery' link equal to the value of the $([vars/selectedDelivery]) parameter.
5 Close the query configuration window and add a page after this second query.
Configuring page N2
This is the last page of the report and will not be followed by any additional activity.
3 Add a list with grouping using the popup menu, and give it the E-mail domains by recipient
label.
4 Click the Table data XPath link and select the Recipient delivery logs link.
n In the first cell of the detail line, add the rowNum()-1 expression, then change the cell format: in
the Plus tab, select Color tab from the drop-down list of the Visual field. Then close the cell
formatting window.
This configuration will allow you to use the table as a caption for the graph.
n In the second cell of the detail line, add the Email domain(Recipient) expression.
n In the third cell of the detail line, add the count(primary key) expression.
6 Add a pie chart to the page via the popup menu, and give it the Email domains label . For further
information, refer to the Chart [page 231] section.
7 Click the Variants link and deselect the Show labels and Display legend options.
8 Check that no value sorting is configured. Refer to the Laying out a descriptive analysis report [page 264]
section for further information on this subject.
9 In the Data tab, modify the data source: select Context data in the drop-down list.
10 Next, click Advanced parameters and select the recipient delivery log link.
11 In the Chart type part, choose the e-mail domain.
12 In the Statistics part, choose the 'sum' operator, and close the page configuration window.
13 Click Detail to select the field on which the count will be based, then close the page configuration window.
Your page is now configured. To view the result, click the Preview tab and select the Global option.
The first page of your report gives a list of all deliveries contained in the database.
If you click the link of one of the deliveries, the graph representing the distribution by e-mail domain for this
delivery is displayed. You are on the second page of your report and can return to the previous page by
clicking the appropriate button.
Test Activity
In the diagram of an extended report, the Test activity lets you modify the sequence of pages in the report
using one or more conditions.
Note:
The query editor is presented in the User Guide.
4 Enable the Default fork option to add a transition if none of the configured conditions are true.
Refer to the Configuring page display section of the Web Functionalities guide for more information.
Script Activity
This activity lets you process your data and easily create complex queries not possible in SQL language.
Simply enter your query in the script window.
Note:
The use of JavaScript code to create aggregates is not recommended. If your query must contain aggregates,
it is preferable to use a Query activity [page 258].
Warning:
To create a history of your report, add the if( ctx.@_historyId.toString().length == 0 ) line
to your JavaScript query in order to keep your logged data. Otherwise, the current data will be displayed.
Refer to the Adding scripts section of the Web Functionalities guide for more information.
Query activity
This activity lets you create SQL queries via a query editor.
1 Specify the label of the query and the table which it will apply to in the Source field.
2 Click the Edit query link to create your query using the editor.
Note:
The query editor is presented in the "Creating queries" section of the Neolane Platform guide.
Jump activity
A jump is like an arrowless transition. It lets you go from one activity to another and access another report.
Advanced configuration
You can personalize and configure your reports to meet your needs via the properties window. Report
properties are accessible via the Edit tab for extended reports and descriptive analysis reports.
General
In this tab, you can enter or modify the Label of your report, but you are strongly advised not to modify
the Internal name.
The report template is chosen when the report is created and cannot be changed afterwards. You can,
however, select a different table in Document type by clicking Select link. To view the fields available in
the selected table, simply click the Magnifier icon.
A report can be accessible outside the Neolane console, e.g. from a web browser. In this case, it may be
necessary to configure access control to the report as shown below:
Refer to the Access Parameters section of the Web Functionalities guide for more information.
Page
From this tab, you can customize the page of the report, e.g. give the window a title.
The content configured in this tab will be visible on every page of the report, in the preview, and when the
report is open in a web browser.
Localization
You can configure the languages into which you want the report to be translated.
The editing language is the language which you write in. When you add a language, a sub-tab appears in
the report editing page.
Rendering
In this tab, you can choose the template or theme used for generating the pages of the report.
Refer to the Display parameters and Form rendering personalization sections of the Web Functionalities
guide for more information.
Parameters
In this tab, you can add additional parameters to your reports.
Refer to the URL parameters section of the Web Functionalities guide for more information.
Variables
This tab contains the list of variables configured in reports. They can be edited by clicking the Detail icon.
Scripts
For more information, refer to the Adding scripts section of the Web Functionalities guide.
Error page
In this tab, you can configure the error message to be shown when a report display error occurs.
Refer to the Error page personalization section of the Web Functionalities guide for more information.
Data
If you wish to modify the schema of the report, click Select link... and select another table in the
database.
Display parameters
You can choose whether to hide or display the names of the statistics and sub-totals as well as choose
their orientation of the statistics.
The name appears in a ToolTip when you place the cursor in a cell of the table.
If you deselect the labels and subtotals display option however, these items will not appear in the report.
To choose the orientation of the statistics, select the appropriate option from the drop-down list. Depending
on your selection, the data will be displayed as shown below:
Data layout
You can personalize the arrangement of the data directly in the descriptive analysis tables. To do this,
right-click the variable that interests you. Choose from the options available in the popup menu:
n Pivot to change the axis of the selected variable.
n Up / Down to interchange the variables found in a row.
For a pie chart, you can define the value of the inside radius in the corresponding field. For example:
The size of the chart corresponds to its displayed size, which includes its legend.
The Accumulate values option lets you add the returned values from one series to the next.
You can choose whether or not to display the chart legend: Clear the corresponding option to not display
it.
By default, the legend is displayed at the top right outside of the chart.
The legend can also be displayed on top of the chart in order to save on display space. To do this, select
the option Include in the chart.
Select the horizontal and vertical alignment from the drop-down list Position of the legend.
Configuring data
Data in context
For the table and chart elements, the data can come from two sources: from a query whose source is
specified in the Document type field or from the context of the report.
You can define the context of the report using a Query activity placed before the Page activity in which you
specify the table and the fields the report must concern.
Next, indicate the source of the data for your report. To do this, select Context data in the drop-down list.
The location of the data is deduced automatically, but you can choose if necessary.
When you choose the data based on which statistics must be calculated, the available fields match the data
specified in the query.
Data filtering
You can choose to display only certain data in your report. To do this, use the Filter data... option available
in the Edit tab. This link opens the expression editor and lets you apply a query to the database and define
a filter.
In the following example, the filter is configured so that only e-mail domains used by Neolane are displayed.
n Example of a filter in a chart
Click the Filter data... link and complete the Value, Operator and Value fields according to the data
you wish to display.
The rendering of the chart will be as follows (the values were accumulated and stacked in the Variants
window):
Create your query as in the previous example to remove Neolane from the list of companies.
Accessing reports
Report display
Define the report display context in the Neolane platform via the Display tab. Access to a report depends
on its type of selection, these display conditions, and access authorizations.
Type of selection
A report can concern the entire database or be accessible from a specific location such as a delivery, a
recipient, etc. This access is configured using the selection options.
n Mono-selection: the report is only accessible if a particular entity has been selected.
In the following example, the Recipient e-mail domain report is only displayed if recipients are selected
one at a time.
For example, the following report is displayed when several recipients are selected.
Display conditions
You can also use a query to place conditions on the display of a report.
In the example below, the display condition is that the recipient has an e-mail address.
The condition is applied in the following way: if a recipient with no e-mail address is selected, the report is
not displayed.
Access authorization
The report can be shared with other operators or not.
To make the report accessible, select the Report shared with other operators option. If this option is
not selected, only the operator who created the report (or any other operator using the creator's login
identifiers) can access the report.
The report can also be shared with specific operators or groups of operators, who are added in the
authorizations window.
1 Click New and select Create a link to an existing report in the report creation wizard.
2 Select the report which you wish to create a link towards using the drop-down list. In our example, we
select the Email domain/company report.
3 Specify a label and select the schema. In our example, we choose the recipient list table.
This means that the report will be accessible from any list of recipients and that the statistics will be
based on the recipients contained in the selected list.
4 Save and display your report.
5 Enter the link key. In our example, this is the foreign key of the lists.
Report preview
Before publishing your report, check that it is displayed correctly in the Preview tab.
3 Display the list of reports from the Neolane home page by clicking the Reports link, then select the
report you have just created.
4 Click the Enlarge icon to open the report in a web browser.
Processing reports
The reports provided out of the box with Neolane and the user reports which have been published are
accessible either via the Available reports window (associated with a program, via the home page) or via
the List of reports (associated with a delivery or a campaign). In these windows, a toolbar is available so
that you can work on any report.
The toolbar lets you export, print, and create a history or display in a web browser, for example.
Export
Choose the format to which you wish to export your report from the drop-down list. Depending on the chosen
format, the report is exported to .xls, .pdf, or .ods format.
Tip:
You can configure your report in view of exporting it to PDF, Excel or OpenOffice format. Open the Neolane
explorer and select the concerned report.
To display the export parameters, go to the Edit tab and the Export options sub-tab for a descriptive
analysis report.
In an extended report, the export options are accessible via the Page activities of the report, in the Advanced
tab.
Change the Paper and Margin parameters according to your requirements. For a descriptive analysis report,
you can disable exports by deselecting the option Exportable.
Printing
You can print your report from the Neolane console. To do this, click the print icon. An internet Explorer
browser opens, and so does the print dialog box.
Note:
For a better result, edit the printing options in Internet Explorer and select the Print background colors
and images option.
History
Logging a report enables you to create a view of the report at different points in time. This enables you to
make statistics appear at a given instant.
To create a history log, open the concerned report and click the history creation icon.
You can mask or display existing histories by clicking the display/hide icon.
History dates are displayed under the show/hide icon. Click a history to view it.
When you view a history, the Current data link is shown in the history list. Click this link to display the
current report again.
It is possible to delete the history of a report. To do this, go to the node where your reports are located in
the Neolane tree. Click the History tab, select the desired history, and click Delete.
3 Check that the history date appears on the left of the screen.
4 Modify your data in Neolane. In our example, new campaigns affecting budgets were created, creating
new cost lines.
5 Create a new history using the same procedure.
A new view of your data is now available.
You can navigate between the two histories to have two different views of your report.
You can keep the report open and refresh the data by clicking the refresh icon.
The data is kept if you return to the list of reports by clicking the Available reports link and re-open your
report from the list. However, the data is recalculated if you close the report by clicking the icon in the toolbar.
If the data has been modified in the database, simply reload the page in the browser to refresh the data in
the report.
Table of Contents
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289
Web tracking mode . . . . . . . . . . . . . . . . . . . . . . . . . 290
Web tracking tag: definition . . . . . . . . . . . . . . . . . . . . . . 292
Format of the data to be sent . . . . . . . . . . . . . . . . . . . . 292
Data transmission methods . . . . . . . . . . . . . . . . . . . . . 293
Setup stages . . . . . . . . . . . . . . . . . . . . . . . . . . . 293
Additional web tracking parameters . . . . . . . . . . . . . . . . . . . 294
Definition of parameters . . . . . . . . . . . . . . . . . . . . . . 294
Redirection server configuration . . . . . . . . . . . . . . . . . . . . 294
Creating web tracking tags . . . . . . . . . . . . . . . . . . . . . . 295
Defining the URLs to be tracked in the application . . . . . . . . . . . . . 296
On-the-fly creation of URLs to be tracked . . . . . . . . . . . . . . . . 296
Inserting tags in your site . . . . . . . . . . . . . . . . . . . . . . . 297
Simple method . . . . . . . . . . . . . . . . . . . . . . . . . 297
Optimum method . . . . . . . . . . . . . . . . . . . . . . . . . 298
Collecting all visits to a site . . . . . . . . . . . . . . . . . . . . . . 300
Server configuration . . . . . . . . . . . . . . . . . . . . . . . . 300
Configuring a default matching campaign . . . . . . . . . . . . . . . . 300
Anonymous tracking . . . . . . . . . . . . . . . . . . . . . . . . . 300
In addition to standard tracking that shows the behavior of an internet user clicking on a link in an
e-mail message, the Neolane platform lets you collect information on how internet users browse
your website. This data collection is performed by the web tracking module.
Overview
When an internet user clicks a tracked link in an e-mail from a given delivery, the redirection server
contacted deposits a temporary cookie containing the recipient identifier and delivery identifier.
The web client then sends this cookie to the server each time the user visits a page containing a
web tracking tag. This continues throughout the session, i.e. until the web client is closed.
The redirection server collects the following data in this way:
n URL of the page viewed, via an identifier sent as a parameter,
n the delivery from which the web page was visited, via the session cookie,
n identifier of the internet user who clicked, via the session cookie,
n additional information such as the business volume generated.
The following diagram shows the stages of the dialog between the client and the various servers.
Each mode has specific characteristics. The "permanent" Web tracking mode includes the characteristics of
the "session" Web tracking mode, while the "anonymous" mode includes the characteristics of the "permanent"
and "session" modes.
Important:
The "anonymous" Web tracking mode is enabled by default if the "Leads" package is enabled. In all other
cases, the "session" Web tracking mode is enabled by default.
At any time, the default mode can be changed in the instance deployment wizard.
Warning:
If you are using the permanent web or anonymous tracking mode, you must add an index to the "sourceID"
column (uuid230) in the tracking tables (trackingLogXXX):
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:
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.
tagid URL parameter Identifier of tracked web page: this is the only mandatory parameter.
jobid URL parameter Delivery identifier to be used if there is no session cookie. This value is
to be expressed in hexadecimal.
rcpid URL parameter Parameter used to identify the internet user. The format of this parameter
is "name=value", where the name is a field of the recipient schema. This
parameter takes priority over the identifier contained in the session
cookie.
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.
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 business
volume generated, for example (transaction amount, number of items purchased, etc.).
Apply the following steps to set up these tags:
1 Identify the pages you wish to track and determine their type (WEB or TRANSACTION).
2 Determine which additional information you wish to collect, and extend the nms:webTrackingLog
schema with the description of this information. By default, this schema can store the transaction amounts
and number of items per transaction.
3 Creating the web tracking tags. There are two ways of doing this:
n Insert the URLs corresponding to these pages in your Neolane platform, then generate and extract
the associated web-tracking tags (from the Campaign execution>Resources>Web tracking
tags node of the client console).
n Create the web-tracking tags yourself in "on-the-fly creation" mode: the URLs corresponding to these
pages will be automatically inserted in your Neolane platform.
4 Add these tags statically or dynamically in the pages you wish to track.
Note:
All WEB-type tags can be added as they are to the pages of your site. TRANSACTION tags must be
modified or added dynamically in order to contain the additional information (amount, items, etc.).
Example :
<script type="text/javascript">
var _f = "nmsWebTracking"
var _t = window.location.href.match(/.*:\/\/[^\/]*(\/[^\?\#\&]*)/)[1] + "|w|" + _f
document.write("<img height='0' width='0' alt='' src='" +
window.location.protocol + "//tsupport/r/" +
Math.random().toString() + "?tagid=" + escape(_t) + "'/>")
</script>
Definition of parameters
Your Neolane platform offers two TRANSACTION-type web-tracking parameters as a standard:
n amount: represents the amount of a transaction,
n article: represents the number of items in a transaction.
These parameters are defined in the nms:webTrackingLog schema, and are some of the indicators seen
in reporting.
To define additional parameters, you must extend this schema.
Example :
<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).
Warning:
The correct calculation of the number of characters to be taken into account is important for optimizing the
web tracking performance of your platform.
The default value is 32 characters. This value lets you take into account the amount and article
("amount=xxxxxxxx&article=xxxxxxxx") standard parameters.
By taking into account both parameters (size of name + size of value) indicated in the above extension
schema example, you can modify the configuration to take 60 characters into account
("amount=xxxxxxxx&article=xxxxxxxx&mode=xxxxxxxxxx&code=xxxxx").
<trackinglogd args="" autoStart="false" maxCreateFileRetry="5" maxLogsSizeOnDiskMb="500"
maxSharedLogs="10000" pre400LogsFormat="false" processRestartTime="06:00:00"
purgeLogsPeriod="50000" runLevel="10"
webTrackingParamSize="60"/>
Warning:
Remember to encode the value of the tagid parameter when it is used as a URL parameter.
Simple method
This method consists of sending an HTTP call to the redirection server by inserting an <IMG> HTML tag in
the HTML source code of the web page you wish to track.
Warning:
This method uses the cookies sent by the web browser to identify the recipient, and is not 100% reliable.
Example :
<img height='0' width='0' alt='' src='http://localhost/r/12343?tagid=home'
When you define a page to be tracked in the console, you can generate a sample web tracking tag to copy
and paste into the source code of your web page.
When you use TRANSACTION-type tags, however, you must modify the sample tag using JavaScript in order
to insert the transaction information (amount, number of items) and any information defined by an extension
schema.
<script>
function getURLparam(name)
{
var m = location.search.match new RegExp("[?&]" + name + "=([^&]+)"));
return m? unescape(m[1]): "";
}
<h1>Approval confirmation</h1>
</body>
</html>
Optimum method
If you wish to control the information sent to the redirection server, the most reliable way is to perform the
HTTP query synchronously yourself using a page generating language.
The URL you construct must obey the syntax rules defined in Web tracking tag: definition [page 292].
Note:
Redirection and web tracking use cookies, and it is important that the web server performing the synchronous
HTTP call be in the same domain as the redirection server. The various HTTP exchanges must convey the
'id', 'uuid', and 'uuid230' cookies.
Example: Dynamic generation in Java, with recipient authentication using their account number.
[...]
// Recipient account, amount and articles
String strAccount = request.getParameter("account");
String strAmount = request.getParameter("amount");
String strArticle = request.getParameter("article");
Warning:
The Neolane platform is not intended for use as a website tracking tool beyond the context of visiting the
site following a click in a message. When this option is enabled, it can cause very high use of resources on
the machines hosting your servers (redirection, application, and database). You are advised to ensure that
your hardware architecture can support this load, and to avoid placing web tracking tags in the most frequently
visited pages, such as the home page.
Server configuration
The servers are configured by overloading certain elements of the serverConf.xml file. These files are
saved in the conf subdirectory of the Neolane installation directory.
Redirection server
For the redirection server, set the trackWebVisitors attribute of the redirection element to true.
<redirection P3PCompactPolicy="CAO DSP COR CURa DEVa TAIa OUR BUS IND UNI COM NAV"
databaseId="" defLogCount="30" expirationURL="" maxJobsInCache="100"
startRedirection="true" startRedirectionInModule="true" trackWebVisitors="true"
trackingPassword=""
Anonymous tracking
Neolane lets you link collected Web tracking information to a recipient when they browse your site
anonymously. When a user browses the tagged pages of your website this browsing information is collected,
so that once they click in an email sent by Neolane, they are identified and the information is automatically
linked to them.
Warning:
Setting up anonymous tracking on a website can trigger the collection of a significant amount of tracking
logs, thereby impacting database operation. Configure it with care.
Tracking logs are saved in the database until the tracking data is purged. Use the deployment wizard to
configure the purge frequency. For more on this, refer to the Installation guide.
To enable anonymous Web tracking on your instance, the following elements must be configured:
n The trackWebVisitors parameter of the redirection element of the serverConf.xml file of the
tracking server must be set to 'true', to place a permanent cookie (uuid230) in the browsers of unknown
internet users who visit the site.
n The Anonymous Web Tracking mode must be selected in the tracking configuration screen of the
deployment wizard.
n Web forms and surveys must be published and executed on the tracking server. The matching option
must be selected in the deployment wizard.