Adobe Campaign v6.1 - Configuration Guide Campaign v6.1 - Configuration Guide | 9 ... The name of the element should be concise, preferably in English, and include only authorized

Configuration GuideTechnical Documentation

Adobe Campaign v6.1

© 2017, Adobe System Incorporated

All rights reserved.

Published by Adobe Systems Inc.

Terms of use | Privacy Center

A trademark symbol (®, ™, etc.) denotes an Adobe trademark.

All third-party trademarks are the property of their respective owners. Updated Information/Additional Third Party Code Information available athttp://www.adobe.com/go/thirdparty

Neolane, an Adobe Company18 rue Roger Simon Barboux, 94110 Arcueil - France+33 1 41 98 35 35www.adobe.com

http://www.adobe.com/misc/terms.html

http://www.adobe.com/privacy.html

http://www.adobe.com/go/thirdparty

Adobe Campaign v6.1 - Configuration Guide

Chapter 1. Schema Reference . . . . . . . . . . . . . . . . . . . . . . . . . 7

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8Syntax of schemas . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8Identification of a schema . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Schema structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11Data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12Collections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15Referencing with XPath . . . . . . . . . . . . . . . . . . . . . . . . . . 15Building a string via the compute string . . . . . . . . . . . . . . . . . . . . 16

Database mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17XML fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17Indexed fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18Management of keys . . . . . . . . . . . . . . . . . . . . . . . . . . . 18Links: relation between tables . . . . . . . . . . . . . . . . . . . . . . . . 21

Elements and attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . 24<attribute> element . . . . . . . . . . . . . . . . . . . . . . . . . . . 24<compute-string> element . . . . . . . . . . . . . . . . . . . . . . . . . 29<condition> element . . . . . . . . . . . . . . . . . . . . . . . . . . . 30<dbindex> element . . . . . . . . . . . . . . . . . . . . . . . . . . . 31<element> element . . . . . . . . . . . . . . . . . . . . . . . . . . . 33<enumeration> element . . . . . . . . . . . . . . . . . . . . . . . . . . 38<help> element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40<join> element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41<key> element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42<keyfield> element . . . . . . . . . . . . . . . . . . . . . . . . . . . 43<method> element . . . . . . . . . . . . . . . . . . . . . . . . . . . 44<methods> element . . . . . . . . . . . . . . . . . . . . . . . . . . . 46<param> element . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47<parameters> element . . . . . . . . . . . . . . . . . . . . . . . . . . 49<srcSchema> element . . . . . . . . . . . . . . . . . . . . . . . . . . 50<sysFilter> element . . . . . . . . . . . . . . . . . . . . . . . . . . . 52<value> element . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

Adobe Campaign v6.1 - Configuration Guide | 3

Table of Contents

Chapter 2. Editing schemas . . . . . . . . . . . . . . . . . . . . . . . . . 55

Getting started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56Extending or creating schemas . . . . . . . . . . . . . . . . . . . . . . . 56Enumerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57Attributes (Fields) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58Audit trail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59Updating the database structure . . . . . . . . . . . . . . . . . . . . . . . 59

Editing schemas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59Example: creating a contract table . . . . . . . . . . . . . . . . . . . . . . 61

Schema of an existing table . . . . . . . . . . . . . . . . . . . . . . . . . . 63Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63Accessing an external database . . . . . . . . . . . . . . . . . . . . . . . 65

Extending a schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65Protecting schemas . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

System filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66Protecting out-of-the-box schemas . . . . . . . . . . . . . . . . . . . . . . 66Modifying system filters of out-of-the-box schemas . . . . . . . . . . . . . . . . 67

Restricting PII view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68Recommendation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

Updating the database structure . . . . . . . . . . . . . . . . . . . . . . . . 69New field wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70Schema structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72Regenerating all schemas . . . . . . . . . . . . . . . . . . . . . . . . . . 72Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

Extending a table . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73Linked collection table . . . . . . . . . . . . . . . . . . . . . . . . . . 74Extension table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75Overflow table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75Relationship table . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

Chapter 3. Input forms . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

Identifying a form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79Editing forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80Form structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

Formatting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82Containers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83Editing a link . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85List of links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86Memory list controls . . . . . . . . . . . . . . . . . . . . . . . . . . . 87Non-editable fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89Radio button . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90Checkbox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90Navigation hierarchy edit . . . . . . . . . . . . . . . . . . . . . . . . . 90Expression field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90Context of forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91Wizards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

Chapter 4. API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93

About web services . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94

4

Definition of Adobe Campaign APIs . . . . . . . . . . . . . . . . . . . . . . 94Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94Using Adobe Campaign APIs . . . . . . . . . . . . . . . . . . . . . . . . 94SOAP calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94Resources and exchanges . . . . . . . . . . . . . . . . . . . . . . . . . 95Example of a SOAP message on the 'ExecuteQuery' method . . . . . . . . . . . . . 95Error management . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96URL of Web service server (or EndPoint) . . . . . . . . . . . . . . . . . . . . 97

Web service calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97General information . . . . . . . . . . . . . . . . . . . . . . . . . . . 97Definition of Web services . . . . . . . . . . . . . . . . . . . . . . . . . 97Web service description: WSDL . . . . . . . . . . . . . . . . . . . . . . . 98Connectivity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

Data oriented APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101Overview of the datamodel . . . . . . . . . . . . . . . . . . . . . . . . 102Description of the model . . . . . . . . . . . . . . . . . . . . . . . . . 102Query and Writer . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102ExecuteQuery (xtk:queryDef) . . . . . . . . . . . . . . . . . . . . . . . 103Write / WriteCollection (xtk:session) . . . . . . . . . . . . . . . . . . . . . 110

Business oriented APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . 112Subscribe (nms:subscription) . . . . . . . . . . . . . . . . . . . . . . . 113Unsubscribe (nms:subscription) . . . . . . . . . . . . . . . . . . . . . . . 114SubmitDelivery (nms:delivery) . . . . . . . . . . . . . . . . . . . . . . . 115

Implementing SOAP methods . . . . . . . . . . . . . . . . . . . . . . . . 116Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116Defining a method library . . . . . . . . . . . . . . . . . . . . . . . . . 116

SOAP methods in JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . 117Static methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117Non-static methods . . . . . . . . . . . . . . . . . . . . . . . . . . . 117Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

Adding additional SQL functions . . . . . . . . . . . . . . . . . . . . . . . 118Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118General structure of package to import . . . . . . . . . . . . . . . . . . . . 119Function descriptor <function> . . . . . . . . . . . . . . . . . . . . . . . 120'Pass-through' function descriptor . . . . . . . . . . . . . . . . . . . . . . 121Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

Chapter 5. Navigation hierarchy . . . . . . . . . . . . . . . . . . . . . . . 123

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124

Global commands . . . . . . . . . . . . . . . . . . . . . . . . . . . 125Folder type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126

Edition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

Chapter 6. Use a custom recipient table . . . . . . . . . . . . . . . . . . . . 131

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131Precisions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132Recommendations and limitations . . . . . . . . . . . . . . . . . . . . . 132

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132The view attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . 133Names of tables and columns . . . . . . . . . . . . . . . . . . . . . . . 133Indexed fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133

Target mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134Creating and configuring schemas linked to the custom table . . . . . . . . . . . . 134Using target mapping . . . . . . . . . . . . . . . . . . . . . . . . . . 137

Configuring the interface . . . . . . . . . . . . . . . . . . . . . . . . . . 137


Creating a new form . . . . . . . . . . . . . . . . . . . . . . . . . . 138Creating a new type of folder in the navigation hierarchy . . . . . . . . . . . . . . 138

Seed addresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139

Creating filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140Creating lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141Managing workflows . . . . . . . . . . . . . . . . . . . . . . . . . . . 143Managing reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144

Chapter 7. Setting up web tracking . . . . . . . . . . . . . . . . . . . . . . 145

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145Web tracking mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146Web tracking tag: definition . . . . . . . . . . . . . . . . . . . . . . . . . 148

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

Setup stages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149Additional parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . 150

Definition of parameters . . . . . . . . . . . . . . . . . . . . . . . . . 150Redirection server configuration . . . . . . . . . . . . . . . . . . . . . . 150

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

Inserting tags in your site . . . . . . . . . . . . . . . . . . . . . . . . . . 153Simple method . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153Optimum method . . . . . . . . . . . . . . . . . . . . . . . . . . . 154

Collecting all visits . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156Server configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . 156Configuring a default matching campaign . . . . . . . . . . . . . . . . . . . 156

Anonymous tracking . . . . . . . . . . . . . . . . . . . . . . . . . . . 156

6

Table of ContentsIntroduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8Syntax of schemas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8Identification of a schema . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Schema structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11Data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12Collections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15Referencing with XPath . . . . . . . . . . . . . . . . . . . . . . . . . . . 15Building a string via the compute string . . . . . . . . . . . . . . . . . . . . . . 16

Database mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17XML fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17Indexed fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18Management of keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18Links: relation between tables . . . . . . . . . . . . . . . . . . . . . . . . . 21

Elements and attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24<attribute> element . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24<compute-string> element . . . . . . . . . . . . . . . . . . . . . . . . . . 29<condition> element . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30<dbindex> element . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31<element> element . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33<enumeration> element . . . . . . . . . . . . . . . . . . . . . . . . . . . 38<help> element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40<join> element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41<key> element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42<keyfield> element . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43<method> element . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44<methods> element . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46<param> element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47<parameters> element . . . . . . . . . . . . . . . . . . . . . . . . . . . 49<srcSchema> element . . . . . . . . . . . . . . . . . . . . . . . . . . . 50<sysFilter> element . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52<value> element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53


CHAPTER 1

Schema Reference

Introduction

This chapter describes how to configure extension schemas in order to extend the conceptual data model of theAdobe Campaign database.

OverviewThe physical and logical structure of the data carried in the application is described in XML. It obeys a grammarspecific to Adobe Campaign, called a schema.

A schema is an XML document associated with a database table. It defines data structure and describes the SQLdefinition 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 Adobe Campaign data system:

Syntax of schemasThe root element of the schema is <srcSchema>. It contains the <element> and <attribute> sub-elements.

The first <element> sub-element coincides with the root of the entity.

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

8

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

Identification of a schemaA data schema is identified by its name and its namespace.

A namespace lets you group a set of schemas by area of interest. For example, the cus namespace is used forcustomer-specific configuration (customers).

Warning:

As a standard, the name of the namespace must be concise and must contain only authorized characters in accordancewith 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 AdobeCampaign 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; forexample: cus:recipient.


Schema Reference

Schema structure

The basic structure of an <srcSchema> is as follows:

<srcSchema> <enumeration> ... //definition of enumerations </enumeration>

<element> //definition of the root <element> (mandatory)

<compute-string/> //definition of a compute-string <dbindex> ... //definition of indexes </dbindex> <key> ... //definition of keys </key> <sysFilter> ... //definition of filters </sysFilter> <attribute> ... //definition of fields </attribute>

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

</element>

<methods> //definition of SOAP methods <method> ... </method> ... </methods>

</srcSchema>

The XML document of a data schema must contain the <srcSchema> root element with the name and namespaceattributes to populate the schema name and its namespace.

<srcSchema name="schema_name" namespace="namespace">...</srcSchema>

Let us use the following XML content to illustrate the structure of a data schema:

<recipient email="[email protected]" created="2009/03/12" gender="1"> <location city="London"/></recipient>

With its corresponding data schema:

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

10

DescriptionThe 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 andnames of the data items in the XML structure.

In our sample schema, these are:

<attribute name="email"/><attribute name="created"/><attribute name="gender"/><element name="location"> <attribute name="city"/></element>

The following rules must be adhered to:

n Each <element> and <attribute> must be identified by name via the name attribute.

Warning:

The name of the element should be concise, preferably in English, and include only authorized characters inaccordance 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 typesThe data type is entered via the type attribute in the <attribute> and <element> elements.

A detailed list is available in the description of the <attribute> element [page 24] and the <element> element[page 33].

When this attribute is not populated, string is the default data type unless the element contains child elements. If itdoes, 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 datetimenotz: date + time without time zone data.

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 completedwith its default value.

Here is our example schema with the types entered:

<srcSchema name="recipient" namespace="cus"> <element name="recipient">


Schema Reference

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

Mapping the types of Adobe Campaign/DBMS data

The table below lists the mappings for the types of data generated by Adobe Campaign for the different databasemanagement systems.

MS SQLDB2TeradataOraclePosgreSQLAdobe Campaign

VARCHAR(NVARCHAR if uni-code)

VARCHARVARCHAR (VARCHARCHARACTER SET UNI-CODE if Unicode)

VARCHAR2(NVARCHAR2 if uni-code)

VARCHAR(255)String

TINYINTSMALLINTNUMERIC(3)NUMBER(3)SMALLINTBoolean

TINYINTSMALLINTNUMERIC(3)NUMBER(3)SMALLINTByte

SMALLINTSMALLINTSMALLINTNUMBER(5)SMALLINTShort

FLOATDOUBLEFLOATFLOATDOUBLE PRECISIONDouble

INTINTEGERINTEGERNUMBER(10)INTEGERLong

BIGINTBIGINTNUMERIC(20)NUMBER(20)BIGINTInt64

DATETIMEDATETIMESTAMPDATEDATEDate

FLOATTIMETIMEFLOATTIMETime

MS SQL < 2008: DATE-TIME

MS SQL >= 2012:DATETIMEOFFSET

TIMESTAMPTIMESTAMPDATETIMESTAMPZDatetime

MS SQL < 2008: DATE-TIME

MS SQL >= 2012:DATETIME2

TIMESTAMPTIMESTAMPDATETIMESTAMPZDatetimenotz

FLOATDOUBLEFLOATFLOATDOUBLE PRECISIONTimespan

TEXT (NTEXT if Uni-code)

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

CLOB (NCLOB if Uni-code)

TEXTMemo

IMAGEBLOB(4M)BLOBBLOBBLOBBlob

PropertiesThe <elements> and <attributes> elemtns of the data schema can be enriched with various properties. You canpopulate a label in order to describe the current element.

Labels and descriptions

n The label property lets you enter a brief description.

Note:

The label is associated with the current language of the instance.

Example:

<attribute name="email" type="string" length="80" label="Email"/>

The label can be seen from the Adobe Campaign client console input form:

12

n The desc property lets you enter a long description.

The description can be seen from the input form in the status bar of the Adobe Campaign client console mainwindow.

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

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 CounterValuefunction with a free counter name. The number returned is incremented by one at each insertion.

Note:

In the Adobe Campaign client console, the Administration>Counters node is used to manage counters.

To link a default value to a field, you can use the <default> or <sqlDefault> field.

<default>: allows you to pre-fill the field with a default value when creating entities. The value will not be a defaultSQL value.

<sqlDefault>: allows you have an added value when creating a field. This value appears as an SQL result. During aschema update, only the new records will be impacted by this value.

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 Adobe Campaign 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.


Schema Reference

The enum attribute refers to the definition of an enumeration class populated in the schema outside the mainelement.

Enumerations allow the user to select a value from a drop-down list instead of entering the value in a regular inputfield:

Example of an enumeration declaration in the data schema:

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

An enumeration is declared outside the main element via the <enumeration> element.

The enumeration properties are as follows:

n baseType: type of data associated with the values,

n label: description of the enumeration,

n name: name of the enumeration,

n default: default value of the enumeration.

The enumeration values are declared in the <value> element with the following attributes:

n name: name of the value stored internally,

n label: label displayed via the graphical interface.

dbenum enumeration

n The dbenum property lets you define an enumeration whose properties are similar to those of the enum property.

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

14

<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 recipient"/> <attribute name="created" type="datetime" label="Date of creation" default="GetDate()"/>

<attribute name="gender" type="byte" label="gender" enum="gender"/> <element name="location" label="Location"> <attribute name="city" type="string" length="50" label="City" userEnum="city"/> </element> </element></srcSchema>

CollectionsA collection is a list of elements with the same name and the same hierarchical level.

The unbound attribute with the value "true" lets you populate a collection element.

Example: definition of the <group> collection element in the schema.

<element name="group" unbound="true" label="List of groups"> <attribute name="label" type="string" label="Label"/></element>

With projection of the XML content:

<group label="Group1"/><group label="Group2"/>

Referencing with XPathThe XPath language is used in Adobe Campaign to reference an element or attribute belonging to a data schema.

XPath is a syntax that lets you locate a node in the tree of an XML document.

Elements are designated by their name, and attributes are designated by the name preceded by the character "@".

Example:

n @email: selects the email,

n location/@city: selects the "city" attribute under the <location> element

n ../@email: selects the e-mail address from the parent element of the current element

n group[1]/@label: selects the "label" attribute that is the child of the first <group> collection element

n group[@label='test1']: selects the "label" attribute that is the child of the <group> element and containsthe value "test1"

Note:

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


Schema Reference

You can access the list of available functions via any expression editor in the Adobe Campaign client console:

Example:

n GetDate(): returns the current date

n Year(@created): returns the year of the date contained in the "created" attribute.

n GetEmailDomain(@email): returns the domain of the e-mail address.

Building a string via the compute stringA Compute string is an XPath expression used to construct a string representing a record in a table associated withthe schema. Compute string is mainly used in the graphical interface to display the label of a selected record.

The Compute string is defined via the <compute-string> element under the main element of the data schema. Anexpr attribute contains an XPath expression to calculate the display.

Example: compute string of the recipient table.

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

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

Note:

If the schema does not contain a Compute string, a Compute string is populated by default with the values of theprimary key of the schema.

Database mapping

The SQL mapping of our example schema gives the following XML document:

<schema mappingType="sql" name="recipient" namespace="cus" xtkschema="xtk:schema"> <enumeration basetype="byte" name="gender"> <value label="Not specified" name="unknown" value="0"/> <value label="Male" name="male" value="1"/> <value label="Female" name="female" value="2"/> </enumeration>

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

<element label="Location" name="location"> <attribute label="City" length="50" name="city" sqlname="sCity" type="string" userEnum="city"/>

16

</element> </element></schema>

DescriptionThe root element of the schema is no longer <srcSchema>, but <schema>.

This takes us to another type of document, which is generated automatically from the source schema, simply referredto as the schema. This schema will be used by the Adobe Campaign 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' forstring, '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" attributeson the element concerned.

The SQL script to create the table generated from the extended schema is as follows:

CREATE TABLE CusRecipient( iGender NUMERIC(3) NOT NULL Default 0, sCity VARCHAR(50), sEmail VARCHAR(80), tsCreated TIMESTAMP Default NULL);

The SQL field constraints are as follows:

n no null values in numeric and date fields,

n numeric fields are initialized to 0.

XML fieldsBy default, any typed <attribute> and <element> element is mapped onto an SQL field of the 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 thatobserves the schema structure.

To populate a field in XML, you must add the xml attribute with the value "true" to the element concerned.

Example: here are two examples of XML field use.

n Multi-line comment field:

<element name="comment" xml="true" type="memo" label="Comment"/>

n Description of data in HTML format:

<element name="description" xml="true" type="html" label="Description"/>

The "html" type lets you store the HTML content in a CDATA tag and display a special HTML edit check in theAdobe Campaign client interface.

The use of XML fields lets you add fields without needing to modify the physical structure of the database. Anotheradvantage 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.


Schema Reference

Indexed fieldsIndexes let you optimize the performance of the SQL queries used in the application.

An index is declared from the main element of the data schema.

<dbindex name="name_of_index" unique="true/false"> <keyfield xpath="xpath_of_field1"/> <keyfield xpath="xpath_of_field2"/> ...</key>

Indexes obey the following rules:

n An index can reference one or more fields in the table.

n An index can be unique (to avoid duplicates) in all of the fields if the unique attribute contains the value "true".

n The SQL name of the index is determined from the SQL name of the table and the name of the index.

Note:

As a standard, indexes are the first elements declared from the main element of the schema.

Note:

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

Example:

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

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

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

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

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

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

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

Management of keysA table must have at least one key for identifying a record in the table.

A key is declared from the main element of the data schema.

18

<key name="name_of_key"> <keyfield xpath="xpath_of_field1"/> <keyfield xpath="xpath_of_field2"/> ...</key>

Keys obey the following rules:

n A key can reference one or more fields in the table.

n A key is known as 'primary' (or 'priority') when it is the first in the schema to be populated or if it contains theinternal attribute with the value "true".

n A unique index is declared implicitly for each key definition. The creation of an index on the key can be preventedby adding the noDbIndex attribute with the value "true".

Note:

As a standard, keys are the elements declared from the main element of the schema after indexes have been defined.

Note:

Keys are created during table mapping (standard or FDA), Adobe Campaign finds unique indexes.

Example:

n Adding a key to the e-mail address and city:

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

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

The schema generated:

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

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

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

n Adding a primary or internal key on the "id" name field:

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


Schema Reference

</key>

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

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


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

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

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

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

Auto-incremental key

The primary key of most Adobe Campaign 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 anumber that is unique in the entire database. The content of the key is automatically entered on insertion of therecord.

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 thepkSequence attribute. If this attribute is not given in the source schema, the XtkNewId default sequence will beused. 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 an Adobe Campaign schema (NmsTrackingLogId for example) must be associated to aSQL function that returns the number of IDs in the parameters, separated by commas. This function must be calledGetNewXXXIds, where XXX is the name of the sequence (GetNewNmsTrackingLogIds for example). View thepostgres-nms.sql, mssql-nms.sql or oracle-nms.sql files provided with the appliation in thedatakit/nms/eng/sql/ directory to recover the example of a 'NmsTrackingLogId' sequence creation for eachdatabase engine.

To declare a unique key, populate the autopk attribute (with value "true") on the main element of the data schema.

Example:

Declaring an incremental key in the source schema:

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


20

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



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

In addition to the definition of the key and its index, a numeric field called "id" has been added to the extendedschema in order to contain the auto-generated primary key.

Important:

A record with a primary key set to 0 is automatically inserted on creation of the table. This record is used to avoidouter joins, which are not effective on volume tables. By default, all foreign keys are initialized with value 0 so thata result can always be returned on the join when the data item is not populated.

Links: relation between tablesA link describes the association between one table and another.

The various types of associations (known as "cardinalities") are as follows:

n Cardinality 1-1: one occurrence of the source table can have at most one corresponding occurrence of the targettable.

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

n Cardinality N-N: one occurrence of the source table can have several corresponding occurrences of the targettable, and vice-versa.

A link must be declared in the schema containing the foreign key of the table linked via the main element:

<element name="name_of_link" type="link" target="key_of_destination_schema"> <join xpath-dst="xpath_of_field1_destination_table" xpath-src="xpath_of_field1_source_table"/> <join xpath-dst="xpath_of_field2_destination_table" xpath-src="xpath_de_champ2_table_source"/> ...</element>

Links obey the following rules:

n The definition of a link is entered on a link-type <element> with the following attributes:

n name: name of link from the source table,

n target: name of target schema,

n label: label of link,

n revLink (optional): name of reverse link from the target schema (deduced automatically by default),

n integrity (optional): referential integrity of the occurrence of the source table to the occurrence of the targettable. Possible values are as follows:

n define: it is possible to delete the source occurrence if it is no longer referenced by a target occurrence,

n normal: deleting the source occurrence initializes the keys of the link to the target occurrence (defaultmode), this type of integrity initializes all foreign keys,

n own: deleting the source occurrence leads to the deletion of the target occurrence,

n owncopy: the same as own (in case of deletion) or duplicates the occurrences (in case of duplication),

n neutral: does nothing.

n revIntegrity (optional): integrity on the target schema (optional, "normal" by default),

n revCardinality (optional): with value "single" populates cardinality with type 1-1 (1-N by default).


Schema Reference

n externalJoin (optional): forces the outer join

n revExternalJoin (optional): forces the outer join on the reverse link

n A link references one or more fields from the source table to the destination table. The fields making up the join(<join> element) need not be populated because they are automatically deduced by default using the internalkey of the target schema.

n An index is automatically added to the foreign key of the link in the extended schema.

n A link consists of two half-links, where the first is declared from the source schema and the second is createdautomatically in the extended schema of the target schema.

n A join can be an outer join if the externalJoin attribute is added, with the value "true" (supported in PostgreSQL).

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>


<schema mappingType="sql" name="recipient" namespace="cus" xtkschema="xtk:schema"> <element name="recipient" sqltable="CusRecipient"> <dbindex name="companyId"> <keyfield xpath="@company-id"/> </dbindex> ... <element label="Company" name="company" revLink="recipient" target="cus:company" type="link"> <join xpath-dst="@id" xpath-src="@company-id"/> </element> <attribute advanced="true" label="Foreign key of 'Company' link (field 'id')" name="company-id" sqlname="iCompanyId" type="long"/> </element></schema>

The link definition is supplemented by the fields making up the join, i.e. the primary key with its XPath ("@id") in thedestination 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 thedestination table, with the following naming convention: name of target schema followed by name of associatedfield ("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>

22

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" attributein 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 sourceschema).

Example 2

In this example, we will declare a link towards the "nms:address" schema table. The join is an outer join and ispopulated 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 attributeand a field of the ("email") table:

<srcSchema name="recipient" namespace="cus"> <element name="recipient"> <key name="companyEmail"> <keyfield xpath="@email"/> <keyfield xlink="company"/> </key>

<attribute name="email" type="string" length="80" label="Email" desc="Recipient email"/>

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


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

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


Schema Reference

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

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

<attribute desc="E-mail address of recipient" label="Email" length="80" name="email" sqlname="sEmail" type="string"/> <element label="Company" name="company" revLink="recipient" target="sfa:company" type="link"> <join xpath-dst="@id" xpath-src="@company-id"/> </element> <attribute advanced="true" label="Foreign key of link 'Company' (field 'id')" name="company-id" sqlname="iCompanyId" type="long"/> </element></schema>

The definition of the "companyEmail" name key was extended with the foreign key of the "company" link. This keygenerates a unique index on both fields.

Elements and attributes

When editing a schema, an approval system based on the source schema (xtk:srcSchema) is available. Some errorscan also be spotted when updating the database using the "Database structure update..." wizard.

By default, in Adobe Campaign schemas, all boolean type attributes are "false". To activate them, you need to specifythe attribute in the schema and set its value to "true".

<attribute> element

Content model

attribute:==help

Attributes

_operation (string), advanced (boolean), applicableIf (string), autoIncrement (boolean), belongsTo (string), dataPolicy(string), dbEnum (string), defOnDuplicate (boolean), default (string), desc (string), edit (string), enum (string), expr(string), feature (string), featureDate (boolean), img (string), inout (string), label (string), length (string), localizable(boolean), name (MNTOKEN), notNull (boolean), pkgStatus (string), ref (string), required (boolean), sql (boolean),sqlDefault (string), sqlname (string), sqltable (string), target (MNTOKEN), template (string), translatedDefault (string),translatedExpr (string), type (MNTOKEN), user (boolean), userEnum (string), visibleIf (string), xml (boolean)

Parents

<element>

Children

<help>

Description

<Attribute> elements let you define a field in the database.

Use and context of use

<Attribute> elements must be declared in an <element> element.

The sequence in which <attribute> elements are defined in an <srcSchema> does not affect the field creation sequencein the database. The creation sequence will be alphabetical.

Attribute description

n _operation (string): defines the type of writing in the database.

This attribute is mainly used when extending out-of-the-box schemas.

Accessible values are:

24

n "none": reconciliation alone. This means that Adobe Campaign will recover the element without updatingit or generating an error if it doesn't exist.

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

n "insert": insertion. This means that Adobe Campaign will insert the element without checking whether itexists.

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

n "delete": deletion. This means that Adobe Campaign will recover and delete elements.

n advanced (boolean): when this option is activated (@advanced="true"), it lets you hide the attribute on the listof 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 intoaccount when updating the database when the constraint is complied with. "applicableIf" receives an XTKexpression.

n autoIncrement (boolean): if this option is activated, the field becomes a counter. This enables you to incrementa value (mostly IDs). (external use)

n belongsTo (string): takes the name and namespace of the table that shares the field, and populates the schemawhere 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. Thevalues 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 definedin the <srcSchema>.

n defOnDuplicate (boolean): if this attribute is activated, when a record is duplicated the default value (definedin @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 attributereceives an XTK expression.

n desc (string): lets you insert a description of the attribute. This description is displayed in the status bar of theinterface.

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 intothe 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 thecharacteristic, and oà¹ multiple choice fields, where the characteristic is linked to a collection element whichmay contain several values.

When a characteristic is defined in a schema, this schema must have a main key based on a single field (compositekeys are not authorized).

n featureDate (boolean): attribute linked to the "@feature" characteristics field. If its value is "true", it lets you findout 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.


Schema Reference

n label (string): label linked to the field, mostly destined to the user in the interface. It lets you avoid namingconstraints.

n length (string): max. number of characters for a value of the "string" type SQL field. If the "@length" attributeisn't specified, Adobe Campaign automatically creates a field for 255 characters.

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

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 Adobe Campaign's behavior regarding the management of NULL recordsin the database. By default, numeric fields are not null and string and date type fields can be null.

n pkgStatus (string): during package exports, values are taken into account depending on the value 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 whichwould not be compatible with other instances.

n ref (string): this attribute defines a reference to an <attribute> element shared by several schemas (definitionfactoring). 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. Thelabel 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 theelement 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 thedatabase 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" attributeis used by default. When the schema is written in the database, prefixes are added automatically depending onthe type of field.

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

n translatedDefault (string): if a "@default" attribute is found, the "@translatedDefault" will enable you to redefinean 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 redefinean 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, Adobe Campaign changes the defined typeinto a value specific to the database installed during structure update.

List of available types:

n ANY

n bin

n blob

n boolean

n byte

n CDATA

n datetime

n datetimetz

n datetimenotz

n date

n double

n enum

26

n float

n html

n int64

n link

n long

n memo

n MNTOKEN

n percent

n primarykey

n short

n string

n time

n timespan

n uuid

If the "@type" attribute is left empty, Adobe Campaign will link a string of characters (STRING) with a length of100 to the field by default.

If the field is of STRING type and the name of the field isn't specified by the presence of the "@sqlname" attribute,the name of the field in the database will automatically be preceded by an 's'. This operating mode will be similarwith 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 canbe 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.

Warning:

The attribute is hidden but its data can still be accessed.

n xml (boolean): if this option is activated, the values of the field don't have a linked SQL field. Adobe Campaigncreates a Text type "mData" field for record storage. This means there is not filtering or sorting on these fields.

Examples

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

<enumeration name="myEnum"> <value name="One" value="1"/> <value name="Two" value="2"/> </enumeration>

<element label="Sample" name="Sample"> <attribute dbEnum="myEnum" length="100" name="Number" required="true" type="string"/>

</element>

Declaration of an XML field with "@datapolicy":

<attribute dataPolicy="phone" desc="Mobile number" label="Mobile" length="32" name="mobilePhone" sqlname="sMobilePhone" type="string"/>

Example with an "@applicableIf": the "contains" attribute will only be created if the number of countries is greaterthan 20.

<attribute length="100" name="Continent" type="string" applicableIf="@country > 20"/>

Example with "@feature" of "shared" type:

<attribute name="field1" label="Field 1" type="long" feature="shared"/><attribute name="field1" label="Field 1" type="long" feature="shared" sqlname="126" sqltable="Ft_Content_Long"/>

Example with "@feature" of "dedicated" type:


Schema Reference

<attribute name="field1" label="Field 1" type="long" feature="dedicated"/><attribute name="field1" label="Field 1" type="long" feature="dedicated" sqlname="sField1" sqltable="Ft_recipient_field1"/>

28

<compute-string> element

Content model

compute-string:==EMPTY

Attributes

@expr

Parents

<element>

Children

None

Description

The <compute-string> element enables you to generate a string based on an XTK expression to display a "built"label in the interface based on several values.


When no <compute-string> is defined, a <compute-string> element is entered by default with the values of theprimary key in the schema.


n expr (string): XTK and/or Xpath expression

Examples

<compute-string expr="@label + Iif(@code='','', ' (' + [folder/@label] + ')')"/

<compute-string expr="ToString([@centralCatalog-id]) + ',' + ToString([@localOrgUnit-id])"/

Result of the string calculated on a recipient: "John Doe ([email protected])":

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


Schema Reference

<condition> element

Content model

condition:==EMPTY

Attributes

n @boolOperator (string)

n @enabledIf (string)

n @expr (string)

Parents

<sysFilter>

Children

None

Description

This element lets you define a filtering condition.


One <sysFiler> element can contain several filtering conditions.


n boolOperator (string): if several <conditions> are defined within the same <sysFilter> element, this attributelets you combine them. By default, the logical link is between <condition> elements is "AND". The "@boolOperator"attribute lets you combine "OR" and "AND" type links.

n enabledIf (string): condition activation test.

n expr (string): an XTK expression.

Examples

<sysFilter> <condition expr="@city=[currentOperator/location/@city]" enabledIf="hasNamedRight('admin')=false"/></sysFilter>

30

<dbindex> element

Content model

dbindex:==keyfield

Attributes

n @_operation (string)

n @applicableIf (string)

n @label (string)

n @name (MNTOKEN)

n @unique (boolean)

Parents

<element>

Children

<keyfield>

Description

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


It's possible to define several indexes. One index can reference one or more fields of the table. Index declarationusually follows the definition of the main schema element.

The order of the <keyfield> elements defined in a <dbindex> is very important. The first <keyfield> must be theindexation criterion which the queries are mainly based on.

The name of the index in the database is calculated by concatenating the name of the table and the name of theindex. For example: Table name "Sample", Namespace "Cus", index name "MyIndex"-> name of the index field duringindex creation querying: "CusSample_myIndex".










n applicableIf (string): condition for taking the index into account - receives an XTK expression.

n label (string): index label.

n name (MNTOKEN): unique index name.

n unique (boolean): if this option is activated (@unique="true"), the attribute guarantees the uniqueness of theindex 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)).

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


Schema Reference

<attribute name="id" type="long"/></element>

ALTER TABLE CusSample ADD iSampleId INTEGER; UPDATE CusSample SET iSampleId = 0;ALTER TABLE CusSample ALTER COLUMN iSampleId SET Default 0;ALTER TABLE CusSample ALTER COLUMN iSampleId SET NOT NULL;

CREATE UNIQUE INDEX CusSample_myIndex ON CusSample(iSampleId);

Creation of a composite index on the "@mail" and "@phoneNumber" fields:

<element label="NewSchemaUser" name="NewSchemaUser"> <dbindex name="myIndex" label="My composite index"> <keyfield xpath="@email"/> <keyfield xpath="@phone"/> </dbindex>

<attribute name="email" type="string"/> <attribute name="phone" type="string"/></element>

CREATE INDEX DocNewSchemaUser_myIndex ON DocNewSchemaUser(sEmail, sPhone);

32

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

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.


-









Schema Reference



n advanced (boolean): when this option is activated (@advanced="true"), it lets you hide the attribute on the listof 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 aschema declaration in the form of a "namespace:name".

n applicableIf (string): condition for applying the index. This attribute receives an XTK expression.

n autopk (boolean): if this option is activated (autopk="true"), a unique key will be automatically defined. Thisoption may only be used on the main element of the schema. Warning, Adobe Campaign only guarantees thatthe key generated is unique. It is not guaranteed that the key values are consecutive and incremental.

n dataPolicy (string): enables you to specify approval constraints on values allowed in the SQL field. The valuesfor 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 definedin the <srcSchema>.

n defOnDuplicate (boolean): if this attribute is activated, when a record is duplicated the default value (definedin @default) is automatically reapplied to the record.

n default (string): lets you define element behavior (call to a function, default value). This attribute receives anXTK expression.

n desc (string): lets you insert a description of the element. This description is displayed in the status bar of theinterface.

n displayAsField (boolean): if this attribute is activated, a "link" type <element> will be displayed as a field in thetree view of the schemas ("Structure" tab). This way, it's possible to display a link as a local field and change itbehavior during a query. When the element is found in the SELECT of a query, the value of the link target willbe 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 intothe 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 anXpath or an XTK (string) 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 fields where a single value is authorized on the characteristic,and multiple choice fields, where the characteristic is linked to a collection element which may contain severalvalues.

When a characteristic is defined in a schema, this schema must have a main key based on a single field (compositekeys are not authorized).

n featureDate (boolean): attribute linked to the "@feature" characteristics field. If its value is "true", it lets you findout when the value was last updated.

n filterPath (string): this attribute receives an Xpath and lets you define a filter on a field.

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.

34

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:imagename" type. For example: img="cus:myImage.jpg". Physically, the image must be imported to the applicationserver.

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


n "define": Adobe Campaign 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 (defaultmode), 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 AdobeCampaign.

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 definitionof 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"), Adobe Campaign keeps the element declarationsequence in an XML collection element.

n pkSequence (string): receives the name of the sequence to be used for calculating an auto-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 thisattribute:

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 fieldand would not be compatible with other instances

n ref (string): this attribute defines a reference to an >element> element shared by several schemas (definitionfactoring). 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. Thelabel of the field will be red in forms.

n revAdvanced (boolean): when activated, this attribute specifies that the opposite link is an "advanced" link.

n revCardinality (string): this attribute defines the cardinality of a link between two tables. It is used in a "link"type <element>.

Possible values are:

n "single" : Simple 1-1 type link

n "unbound": 1-N type collection link

By default, if the attribute isn't specified during link creation, cardinality will be 1-N.

n revDesc (string): this attribute receives a description linked to the opposite link.

n revExternalJoin (boolean): when activated, this attribute lets you force the external join on the opposite link.

n revIntegrity (string): this attribute defines the integrity on the target schema. The same values as the "@integrity"attribute are authorized. By default, Adobe Campaign gives the "normal" value to this attribute.

n revLabel (string): label of the opposite link.


Schema Reference

n revLink (string): name of the opposite link. If the value is "_NONE_", no opposite link will be created in thedestination schema.

n revTarget (string): target of the opposite link.

n sql (boolean): if this attribute is activated (@sql="true"), it forces storage of the SQL element, even if the elementhas the xml="true" property.

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

n sqltable (string): for the main element of the schema, this attribute overloads the name of the SQL table generatedby default. If "@sqltable" isn't specified, the default name will be structured like this: namespace (first letter uppercase) followed by the value of the SrcSchema "@name".

n tableSpace (string): this attribute lets you specify a new data storing tablespace for a table (valid on the root<element>).

n tableSpaceIndex (string): this attribute lets you specify a new index storage tablespace for a table (valid on theroot <element>).

n target (MNTOKEN): receives the name of the target schema when creating a link between tables. This attributeis only active for "link" type elements.

n template (string): this attribute defines a reference to an <element element shared by several schemas. Thedefinition is automatically copied into the current schema.

n translatedDefault (string): if a "@default" attribute is found, the "@translatedDefault" will enable you to redefinean expression to match the one defined in @default, to be collected by the translation tool (internal use).

n translatedExpr (string): if a "@expr" attribute is found, the "@translatedExpr" attribute lets you redefine anexpression matching the one defined in "@expr", and which will be collected by the translation tool (internaluse).

n type (MNTOKEN): defines the type of data stored in the element.


n ANY

n bin

n blob

n boolean

n byte

n CDATA

n datetime

n datetimetz

n datetimenotz

n date

n double

n enum

n float

n html

n int64

n link

n long

n memo

n MNTOKEN

n 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 elementfor a 1-N cardinality.

n userEnum (string): receives the internal name of an "open" enumeration. Enumeration values can be definedby the user in the interface.

36

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 inan XML document.


Schema Reference

<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 definedin, but it is accessible via another schema.


Enumerations are defined at the start of a schema (before the main element is defined).


n basetype (string): type of the values stored in the enumeration.


n ANY

n bin

n blob

n boolean

n byte

n CDATA

n datetime

n datetimetz

n datetimenotz

n date

n DOMDocument

n DOMElement

n double

n enum

n float

n html

n int64

n link

n long

n memo

n MNTOKEN

n percent

n primarykey

n short

n string

38

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:


<element label="Sample" name="Sample"> <attribute dbEnum="myEnum" length="100" name="Number" required="true" type="string"/>

</element>

Definition of an enumeration with a default value:

<enumeration basetype="byte" default="email" name="canal"> <value label="Email" name="email" value="0"/> <value label="Téléphone" name="phone" value="1"/> <value label="Call Center" name="callcenter" value="2"/> </enumeration>


Schema Reference

<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 XMLin the database.


-


This element has no attributes.

Examples

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

40

<join> element

Content model

join:==EMPTY

Attributes

n @dstFilterExpr (string)

n @xpath-dst (string)

n @xpath-src (string)

Parents

<element>

Children

None

Description

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


A <join> element can only be used if the parent <element> element is of 'link' type. This means that the parentelement must have the "@type=link" attribute declared.

It is not necessary to specify the name and namespace of the remote table in the <join> element. They need to bespecified in the parent <element>.

By convention, links are defined at the end of the schema.

If the <join> element isn't specified when the link type element is defined, the link will automatically be placed onthe primary keys of both tables.


n dstFilterExpr (string): this attribute lets you restrict the number of eligible values in the remote table.

n xpath-dst (string): this attribute receives an Xpath (@name attribute of the remote table).

n xpath-src (string): this attribute receives an Xpath (@name attribute in the current schema).

Examples

Link between the 'email' field of the current table and the "@compagny-id" field of the remote table:

<join xpath-dst="@compagny-id" xpath-src="@email"/>

Filtered link towards the "cus:Country" table based on the content of the "@country" field which must contain the'EN' value:

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


Schema Reference

<key> element

Content model

key:==keyfield

Attributes

n @allowEmptyPart (boolean)


n @internal (boolean)

n @label (string)

n @name (MNTOKEN)

n @noDbIndex (boolean)

Parents

<element>

Children

<keyfield>

Description

This element lets you define a key for identifying a record in the table.

A table must have at least one key.


As a rule, keys are declared after the main element of the schema and the indexes.

A key is known as composite if it includes several fields (i.e. several <keyfield> children). Do not use a compositekey to define a primary key.

If the main element of the schema contains the "@autopk=true" attribute, the primary key is unique. We can onlyhave one primary key per schema.

The first 1000 identifiers are reserved, so if a range of values needs to be defined for keys, start at 1000.


n allowEmptyPart (boolean): in the case of a composite key, if this attribute is activated, they key is consideredvalid if at least one of its keys isn't empty. If this is the case, the empty notion value is "0" (boolean or for all typesof numerical data). By default, all the keys that make up a composite key need to be entered.

n applicableIf (string): this attribute lets you make the key optional. It defines the condition according to whichthe key definition will be applied. This attribute receives an XTK expression.

n internal (boolean): if it is activated, this attribute lets Adobe Campaign know that the key is primary.

n label (string): label of the key.

n name (MNTOKEN): internal name of the key.

n noDbIndex (boolean): if it is activated (noDbIndex="true"), the field matching the key will not be indexed.

Examples

Declaration of a composite key which authorizes either the "@expr" or the "alias" field to be empty:

<key name="node" allowEmptyPart="true"> <keyfield xpath="@expr"/> <keyfield xpath="@alias"/> </key>

Declaration of a primary key on the "Name" field of STRING type in an <srcSchema> and the matching SQL query:

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

CREATE UNIQUE INDEX Schema_PrimaryKey ON Schema(sName);

42

<keyfield> element

Content model

keyfield:==EMPTY

Attributes

n @xlink (MNTOKEN)

n @xpath (MNTOKEN)

Parents

<key>,<dbindex>

Children

None

Description

This element defines the fields to be integrated into an index or a key.


-


n xlink (MNTOKEN): lets you automatically reference foreign keys defined in the join for a relation table (N-Nlink).

n xpath (MNTOKEN): definition of an index or a key on an <attribute> element. This attribute receives an Xpathwhich 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"/>


Schema Reference

<method> element

Content model

method:==( help | parameters)

Attributes


n @access (string)

n @const (boolean)

n @hidden (boolean)

n @label (string)

n @library (string)

n @name (MNTOKEN)

n @pkonly (boolean)

n @static (boolean)

Parents

<methods>,<interface>

Children

n <help>

n <parameters>

Description

This element lets you define a SOAP method.


SOAP methods enable application processes.

The "@library" is necessary for declaring a new method (non-native): the namespace and the name used for thelibrary are independent from the namespace and name of the schema where the declaration is.


n access (string): this attribute defines access control for using the method. If this attribute is missing, identificationis 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 librarywhere 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 mustbe specified to the method when it is called up.

44

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>


Schema Reference

<methods> element

Content model

methods:==method

Attributes

None

Parents

<srcSchema>

Children

method

Description

This element lets you define a <method> element. It is mandatory for declaring a method.


-



Examples

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

46

<param> element

Content model

param:==help

Attributes


n @desc (string)

n @enum (string)

n @inout (string)

n @label (string)

n @localizable (string)

n @name (MNTOKEN)

n @namespace (MNTOKEN)

n @type (string)

Parents

<parameters>

Children

<help>

Description

This element lets you define a parameter for calling up a SOAP method.


-


n desc (string): description which concerns the <param> element.

n inout (string): this attribute defines whether or not the parameter is at the input (in) or output (out) of the SOAPcall. If this attribute isn't specified, the default parameter is input ("@inout=in").

n label (string): <param> label

n localizable (string): if it is activated, this attribute tells the collection tool to recover the value of the "@label"attribute for translation (internal use).

n name (MNTOKEN): internal name of the <param>

n type (string): this attribute defines the type of <param> element


n ANY

n bin

n blob

n boolean

n byte

n CDATA

n datetime

n datetimetz

n datetimenotz

n date

n DOMDocument

n DOMElement

n double

n enum

n float

n html

n int64

n link


Schema Reference

n long

n memo

n MNTOKEN

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

48

<parameters> element

Content model

parameters:==param

Attributes

None

Parents

<method>

Children

<param>

Description

This element defines a group of <parameter> elements.


This element is mandatory, even for a single <param> child element of the <method> element.


None

Examples

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


Schema Reference

<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

The <srcSchema> is the root element of a schema. It is the input point for the definition of the schema.


Schema presentation is available in Introduction [page 8] and Schema structure [page 10].


n created (datetime): this attribute provides information on the date and time of schema creation. It has a "DateTime" 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 Adobe Campaign:xtk:srcSchema). When you save the current schema, Adobe Campaign will approve its grammar with the schemadeclared in the @xtkschema attribute.

n extendedSchema (string): receives the name of the out-of-the-box schema which the current schema extensionis 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 hasa "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 referencedby other schemas thanks to the "@ref" and "@template" attributes.

n mappingType (string):

n "sql": database mapping

n "textFile": text file mapping

n "xmlFile": XML format text file mapping

n "binaryFile": binary file mapping

n modifiedBy-id (long): matches the identifier of the operator who changed the schema.

n name (string): unique schema name.

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

50

n useRecycleBin (boolean): activates the trash feature in the application. Deleted records will be placed in thetrash before final deletion. This function is only available in "Delivery" mode.

n view (boolean): if it is activated (@view="true"), the schema will be used as a view. The database structureupdate wizard will not take the schema into account. This option is mainly used for referencing external tables.

n xtkschema (string): name of the schema which defines schema grammar (xtk:srcSchema by default).

Examples

<srcSchema> element of the "nms:delivery" out of the box schema

<srcSchema desc="Defines all the settings of a delivery (or delivery template)." entitySchema="xtk:srcSchema" img="nms:campaign.png" implements="xtk:persist" label="Diffusions" labelSingular="Diffusion" md5="DCD2164CD0276B1DCA6E1C9E2A75EC04" name="delivery" namespace="nms" useRecycleBin="true" xtkschema="xtk:srcSchema">


Schema Reference

<sysFilter> element

Content model

sysFilter:==condition

Attributes

-

Parents

<element>

Children

<condition>

Description

This element lets you define a filter.


-



Examples

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

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

52

<value> element

Content model

value:==help

Attributes


n @desc (string)

n @enabledIf (string)

n @img (string)

n @label (string)

n @name (string)

n @value (string)

Parents

<enumeration>

Children

<help>

Description

This element lets you define the values stored in an enumeration.


-


n applicableIf (string): this attribute lets you make an enumeration value optional. It receives an XTK expression.

n desc (string): description of the enumeration value.

n enabledIf (string): condition for activating the enumeration value.

n img (string): image linked to the enumeration in the "namespace:image_name" form. The image must beimported 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



Schema Reference

54

Table of ContentsGetting started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56Extending or creating schemas . . . . . . . . . . . . . . . . . . . . . . . . . 56Enumerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57Attributes (Fields) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58Audit trail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59Updating the database structure . . . . . . . . . . . . . . . . . . . . . . . . 59

Editing schemas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59Example: creating a contract table . . . . . . . . . . . . . . . . . . . . . . . 61

Schema of an existing table . . . . . . . . . . . . . . . . . . . . . . . . . . . 63Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63Accessing an external database . . . . . . . . . . . . . . . . . . . . . . . . 65

Extending a schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65Protecting schemas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

System filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66Protecting out-of-the-box schemas . . . . . . . . . . . . . . . . . . . . . . . 66Modifying system filters of out-of-the-box schemas . . . . . . . . . . . . . . . . . . 67

Restricting PII view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68Recommendation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

Updating the database structure . . . . . . . . . . . . . . . . . . . . . . . . . 69New field wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70Schema structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72Regenerating all schemas . . . . . . . . . . . . . . . . . . . . . . . . . . . 72Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

Extending a table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73Linked collection table . . . . . . . . . . . . . . . . . . . . . . . . . . . 74Extension table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75Overflow table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75Relationship table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76


CHAPTER 2

Editing schemas

Getting started

IntroductionAdobe Campaign employs Data Schemas to:

n Define how data objects within the application are tied to underlying database tables.

n Define links between the different data objects within the Campaign application.

n Define and describe the individual fields included in each object.

Extending or creating schemasTo add a field or index or other element to one of the core data schemas in Campaign, such as the recipient table(nms:recipient), you have to extend that schema. For more on this, refer to the Extending a schema [page 65] section.

To add an entirely new type of data that does not exist out-of-the-box in Adobe Campaign (a table of contracts forexample) you can create a custom schema directly. For more on this, refer to the Editing schemas [page 59] section.

Once you have extended or created a schema to work in, the best practice is to define its XML content elements inthe same order they appear in below.

EnumerationsEnumerations are defined first, before the main element of the schema. They allow you to display values in a list inorder to restrict the choices that the user has for a given field.

Example:

<enumeration basetype="byte" name="exTransactionTypeEnum" default="store"><value label="Website" name="web" value="0"/><value label="Call Center" name="phone" value="1"/><value label="In Store" name="store" value="2"/></enumeration>

When defining fields, you can then use this enumeration like so:

<attribute desc="Type of Transaction" label="Transaction Type" name="transactionType" type="string" enum="exTransactionTypeEnum"/>

Note:

You can also employ user-managed enumerations (usually under Administration > Platform) to specify the valuesfor a given field. These are effectively global enumerations, and a better choice if your enumeration may be usedoutside of the specific schema you are working in.

To find out more about enumerations, refer to the Enumerations [page 13] and <enumeration> element [page 38]sections.

56

IndexIndexes are the first elements declared in the main element of the schema.

They can be unique or not, and reference one or more fields.

Examples:

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

<dbindex name="lastNameAndZip"> <keyfield xpath="@lastName"/> <keyfield xpath="location/@zipCode"/></dbindex>

The xpath attribute points to the field in your schema that you wish to index.

Warning:

It is important to remember that the SQL query read performance gains provided by indexes also come with aperformance hit on writing records. The indexes should therefore be used with precaution.

For more on indexes, refer to the Indexed fields [page 18] section.

KeysEvery table must have at least one key, and often it is automatically established in the main element of the schemaby using the @autopk=true attribute set to "true".

The primary key can also be defined using the internal attribute.

Example:

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

In this example, instead of letting the @autopk attribute create a default primary key named “id” we are specifyingour own “householdId” primary key.

To find out more about keys, refer to the Management of keys [page 18] section.

Attributes (Fields)Attributes allow you to define the fields which make up your data object. You can use the Insert button in the schemaedition toolbar to drop empty attribute templates into your XML where your cursor is. For more on this, refer to theEditing schemas [page 59] section.

The full list of attributes is available in the <attribute> element [page 24] section. Here are some of the more commonlyused attributes:


Editing schemas

n @advanced

n @dataPolicy

n @default

n @desc

n @enum

n @expr

n @label

n @length

n @name

n @notNull

n @required

n @ref

n @xml

n @type

To view a table listing the mappings for the data types generated by Adobe Campaign for the different databasemanagement systems, refer to the Mapping the types of Adobe Campaign/DBMS data [page 12] section.

For more information on each attribute, refer to the Attribute description [page 24] section.

Examples

Example of defining a default value:

<attribute name="transactionDate" label="Transaction Date" type="datetime" default="GetDate()"/>

Example of using a common attribute as a template for a field also marked as mandatory:

<attribute name="mobile" label="Mobile" template="nms:common:phone" required="true" />

Example of a computed field that is hidden using the @advanced attribute:

<attribute name="domain" label="Email domain" desc="Domain of recipient email address" expr="GetEmailDomain([@email])" advanced="true" />

Example of an XML field also stored in an SQL field and which has an @dataPolicy attribute.

<attribute name="secondaryEmail" label="Secondary email address" length="100" xml="true" sql="true" dataPolicy="email" />

Warning:

Although most attributes are linked according to a 1-1 cardinality to a physical field of the database, this is not thecase for the XML fields or the computed fields.

An XML field is stored in a memo field ("mData") of the table.

A computed field however is created dynamically each time a query is started, it therefore only exists in the applicativelayer.

LinksLinks are some of the last elements in the main element of your schema. They define how all of the different schemasin your instance relate to one another.

Links are declared in the schema that contains the foreign key of the table to which it is linked.

There are three types of cardinality: 1-1, 1-N, and N-N. It is the 1-N type that is used by default.

Examples

An example of a 1-N link between the recipient table (out-of-the-box schema) and a table of custom transactions:

<element label="Recipient" name="lnkRecipient" revLink="lnkTransactions" target="nms:recipient" type="link"/>

An example of a 1-1 link between a custom schema "Car" (in the "cus" namespace) and the recipient table:

58

<element label="Car" name="lnkCar" revCardinality="single" revLink="recipient" target="cus:car" type="link"/>

Example of an external join between the recipient table and a table of addresses based on the email address andnot a primary key:

<element name="emailInfo" label="Email Info" revLink="recipient" target="nms:address" type="link" externalJoin="true"> <join xpath-dst="@address" xpath-src="@email"/></element>

Here "xpath-dst" corresponds to the primary key in the target schema and "xpath-src" corresponds to the foreignkey in the source schema.

Audit trailOne useful element you may want to include at the bottom of your schema is a tracking element (Audit trail).

Use the example below to include fields relating to the creation date, the user that created the data, the date, andthe author of the last modification for all data in your table:

<element aggregate="xtk:common:auditTrail" name="auditTrail"/>

Updating the database structureOnce your changes are completed and saved, any changes that may impact the SQL structure need to be appliedto the database. To do this, use the database update wizard.

For more on this, refer to the Updating the database structure [page 69] section.

Editing schemas

OverviewTo edit, create and configure the schemas, click the Administration>Configuration>Data schemas node of theAdobe Campaign client console.


Editing schemas

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

The preview automatically generates the extended schema:

Note:

When the source schema is saved, generation of the extended schema is automatically launched.

60

Example: creating a contract tableIn the following example, we want to create a new table for contracts in the database model of the Adobe Campaigndatabase. This table lets you store first and last names and email addresses of holders and co-holders, for eachcontract.

To do this, you need to create the schema of the table and update the database structure to generate the correspondingtable. Apply the following stages:

1 Edit the Administration>Configuration>Data schemas node of the Adobe Campaign tree and click New.

2 Choose the Create a new table in the data model option and click Next.

3 Specify a name for the table and a namespace.

Note:

By default, schemas created by users are stored in the 'cus' namespace. For more on this, refer to Identificationof a schema [page 9].


Editing schemas

4 Create the content of the table. We recommend using the entry wizard to make sure no settings are missing. Todo this, click the Insert button and choose the type of setting to be added.

5 Define the settings for the contract table:

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

<attribute name="holderEmail" label="Holder email" type="string"/> <attribute name="co-holderName" label="Co-holder last name" type="string"/>

<attribute name="co-holderFirstName" label="Co-holder first name" type="string"/> <attribute name="co-holderEmail" label="Co-holder email" type="string"/>

<attribute name="date" label="Subscription date" type="date"/> <attribute name="noContract" label="Contract number" type="long"/> </element></srcSchema>

Add the type of contract and place an index on the contract number.

<srcSchema _cs="Contracts (cus)" desc="Active contracts" entitySchema="xtk:srcSchema" img="ncm:channels.png" label="Contracts" labelSingular="Contract" name="Contracts" namespace="cus" xtkschema="xtk:srcSchema"> <enumeration basetype="byte" name="typeContract"> <value label="Home" name="home" value="0"/> <value label="Car" name="car" value="1"/> <value label="Health" name="health" value="2"/> <value label="Pension fund" name="pension fund" value="2"/> </enumeration> <element autopk="true" desc="Active contracts" img="ncm:channels.png" label="Contracts"

labelSingular="Contract" name="Contracts"> <attribute label="Holder last name" name="holderName" type="string"/> <attribute label="Holder first name" name="holderFirstName" type="string"/> <attribute label="Holder email" name="holderEmail" type="string"/> <attribute label="Co-holder last name" name="co-holderName" type="string"/> <attribute label="Co-holder first name" name="co-holderFirstName" type="string"/> <attribute label="Co-holder email" name="co-holderEmail" type="string"/> <attribute label="Subscription date" name="date" type="date"/> <attribute desc="Type of contract" enum="cus:Contracts:typeContract" label="Type of contract" name="type" type="byte"/> <attribute label="Contract number" name="noContract" type="long"/>

62

<dbindex name="noContract" unique="true"> <keyfield xpath="@noContract"/> </dbindex> </element></srcSchema>

6 Save the schema to generate the structure:

7 Update the database structure to create the table which the schema will be linked to. For more on this, refer toUpdating the database structure [page 69].

Schema of an existing table

OverviewWhen the application needs to access the data of an existing table, an SQL view, or data from a remote database,create its schema in Adobe Campaign with the following data:

n Name of table: enter the name of the table (with its alias when a dblink is used) with the "sqltable" attribute,

n schema key: reference the reconciliation field(s),

n indexes: used to generate queries,

n The fields and their location in the XML structure: fill in only the fields used in the application,

n links: if there are joins with the other tables of the base.

ImplementationTo create the corresponding schema, apply the following stages:

1 Edit the Administration>Configuration>Data schemas node of the Adobe Campaign tree and click New.


Editing schemas

2 Select the Access data from an existing table or an SQL view option and click Next.

3 Choose the table or the existing view:

4 Adapt the schema content to suit your needs.

64

Important:

The schema must be populated with the view="true" attribute on the <srcSchema> root element in order notto generate a table creation SQL script.

Example :

<srcSchema name="recipient" namespace="cus" view="true"> <element name="recipient" sqltable="dbsrv.recipient"> <key name="email"> <keyfield xpath="@email"/> </key> <attribute name="email" type="string" length="80" sqlname="email"/> </element></srcSchema>

Accessing an external databasePurchasing the Federated Data Access option give you access to the data stored in an external database.

The configuration to be carried on the schemas to access data in an external database is detailed in the Connectorschapter.

Extending a schema

Warning:

Some out-of-the-box schemas must not be extended: mainly those for which the following settings are defined:

dataSource="file" and mappingType="xmlFile".

The following schemas must not be extended: xtk:entityBackupNew, xtk:entityBackupOriginal,xtk:entityOriginal, xtk:form, xtk:srcSchema, ncm:publishing, nl:monitoring, nms:calendar,nms:remoteTracking, nms:userAgentRules, xtk:builder, xtk:connections, xtk:dbInit, xtk:funcList,xtk:fusion,xtk: jst, xtk:navtree, xtk:queryDef, xtk:resourceMenu, xtk:schema, xtk:scriptContext,xtk:session, xtk:sqlSchema, xtk:strings.

This list is not exhaustive.

There are two methods for extending an existing schema:

1 Modifying the source schema directly.

2 Creating another schema with the same name but a different namespace. The advantage is that you can extenda table without needing to modify the original schema.

The root element of the schema must contain the extendedSchema attribute with the name of the schema tobe extended as its value.

An extension schema does not have its own schema: the schema generated from the source schema will befilled in with the fields of the extension schema.

Example: extension of the nms:recipient schema.

<srcSchema extendedSchema="nms:recipient" name="recipient" namespace="cus"> <element name="recipient"> <attribute name="code" label="Branch code" type="long"/> </element></srcSchema>

The nms:recipient extended schema is filled in with the field populated in the extension schema:

<schema dependingSchemas="cus:recipient" name="recipient" namespace="nms"> ... <attribute belongsTo="cus:recipient" label="Branch code" name="code" sqlname="iCode" type="long"/> ...</schema>


Editing schemas

platform-v6.1-en.pdf#nameddest=CST-13189

The dependingSchemas attribute on the root element of the schema references the dependences on theextension 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 malfunctionsin the use of Adobe Campaign.

Protecting schemas

System filtersSystem filters let you manage the read and write permissions of entities detailed in schemas:

n readAccess: provides read only access to schema data.

n writeAccess: provides write access to schema data.

&These filters are entered at the main element level of the schemas and, as shown in the following examples, canbe formed to restrict access:

n Example 1:

Here, the filter is used to disallow write permissions on the schema for operators without the named adminpermission. This means that only administrators will have write permissions on entities described by this schema.

<sysFilter name="writeAccess"> <condition enabledIf="hasNamedRight('admin')=false" expr="FALSE"/> </sysFilter>

n Example 2:

Here, the filter is used to disallow both read and write permissions on the schema for all operators. Only theinternal account, represented by the expression "$(loginId)!=0", has these permissions.

<sysFilter name="readAccess"> <condition enabledIf="$(loginId)!=0" expr="FALSE"/></sysFilter>

<sysFilter name="writeAccess"> <condition enabledIf="$(loginId)!=0" expr="FALSE"/></sysFilter>

Possible expr attribute values used to define the condition are TRUE and FALSE.

Note:

If no filter is specified, all operators will have read and write permissions to the schema.

Protecting out-of-the-box schemasBy default, out-of-the-box schemas are only accessible with write permissions for operators with admin rights:

n ncm:publishing

n nl:monitoring

n nms:calendar

n xtk:builder

n xtk:connections

n xtk:dbInit

66

n xtk:entityBackupNew

n xtk:entityBackupOriginal

n xtk:entityOriginal

n xtk:form

n xtk:funcList

n xtk:fusion

n xtk:image

n xtk:javascript

n xtk:jssp

n xtk:jst

n xtk:navtree

n xtk:operatorGroup

n xtk:package

n xtk:queryDef

n xtk:resourceMenu

n xtk:rights

n xtk:schema

n xtk:scriptContext

n xtk:specFile

n xtk:sql

n xtk:sqlSchema

n xtk:srcSchema

n xtk:strings

n xtk:xslt

Warning:

Read and write permissions for the xtk:sessionInfo schema are only accessible by the internal account of an AdobeCampaign instance.

Modifying system filters of out-of-the-box schemasYou can still modify the system filters of the out-of-the-box schemas which are by default protected due tocompatibility issues with older versions:

Note:

However, Adobe recommends you do not modify the default parameters to guarantee optimal security.

1 Create an extension for the concerned schema or open an existing extension.

2 Add a child element <sysFilter name="<filter name>" _operation="delete"/> in the main element to deleteapplication of the filter under the same in the origin schema.

3 If you like, you can add a new filter, as detailed in System filters [page 66].

Restricting PII view

OverviewSome customers need marketing users to be able to access data records but do not want them to see PersonallyIdentifiable Information (PII), such as first name, last name, email. Adobe Campaign proposes a way to protect privacyand prevent data from being misused by regular campaign operators.


Editing schemas

ImplementationA new attribute that can be applied to any element or attribute has been added to the schemas, it complements theexisting attribute visibleIf. This attribute is: accessibleIf. When containing an XTK expression related to the currentuser context, it can leverage HasNamedRight or $(login), for instance.

You can find a sample of a recipient schema extension that shows this usage below:

<srcSchema desc="Recipient table (profiles" entitySchema="xtk:srcSchema" extendedSchema="nms:recipient" img="nms:recipient.png" label="Recipients" labelSingular="Recipient" name="recipient" namespace="sec" xtkschema="xtk:srcSchema"> <element desc="Recipient table (profiles" img="nms:recipient.png" label="Recipients" labelSingular="Recipient" name="recipient"> <attribute name="firstName" accessibleIf="$(login)=='admin'"/> <attribute name="lastName" visibleIf="$(login)=='admin'"/> <attribute name="email" accessibleIf="$(login)=='admin'"/> </element></srcSchema>

The main properties are:

n visibleIf : hides the fields from the metadata, hence they cannot be accessed within a schema view, or columnselection, or an expression builder. But this does not hide any data, if the field name is manually entered in anexpression the value will show up.

n accessibleIf : hides the data (replacing it with empty values) from resulting query. If visibleIf is empty, then it getsthe same expresion as accessibleIf.

Here are the consequences of using this attribute in Campaign:

n Data will not be shown using generic query editor in the console,

n Data will not be visible in overview lists and record list (console).

n Data will become read-only in detailed view.

n Data will only be usable within filters (meaning that using some dichotomy strategies, you can still guess values).

n Any expression that is built using a restricted field becomes restricted too: lower(@email) becomes as accessibleas @email.

n In a workflow, you can add the restricted column to the targeted population as an extra column of the transition,but it is still inaccessible to Adobe Campaign users.

n When storing the targeted population in a group (list), the characteristics of the stored fields are the same as thesource of data.

n Data is not accessible to JS code by default.

RecommendationIn each delivery, email addresses are copied into the broadLog and the forecastLog tables: as a consequence, thosefields needs to be protected too.

Here is a sample of log table extension to address this:

<srcSchema entitySchema="xtk:srcSchema" extendedSchema="nms:broadLogRcp" img="nms:broadLog.png" label="Recipient delivery logs" labelSingular="Recipient delivery log" name="broadLogRcp" namespace="sec" xtkschema="xtk:srcSchema"> <element img="nms:broadLog.png" label="Recipient delivery logs" labelSingular="Recipient delivery log" name="broadLogRcp"> <attribute accessibleIf="$(login)=='admin'" name="address"/> </element></srcSchema><srcSchema desc="Delivery messages being prepared." entitySchema="xtk:srcSchema" extendedSchema="nms:tmpBroadcast" img="" label="Messages being prepared" labelSingular="Message" name="tmpBroadcast" namespace="sec" xtkschema="xtk:srcSchema"> <element desc="Delivery messages being prepared." label="Messages being prepared" labelSingular="Message" name="tmpBroadcast"> <attribute accessibleIf="$(login)=='admin'" name="address"/> </element></srcSchema><srcSchema entitySchema="xtk:srcSchema" extendedSchema="nms:excludeLogRcp" img="nms:excludeLog.png" label="Recipient exclusion logs" labelSingular="Recipient exclusion log"

68

name="excludeLogRcp" namespace="sec" xtkschema="xtk:srcSchema"> <element img="nms:excludeLog.png" label="Recipient exclusion logs" labelSingular="Recipient exclusion log" name="excludeLogRcp"> <attribute accessibleIf="$(login)=='admin'" name="address"/> </element></srcSchema>

Note:

This accessibleIf restriction applies to non technical users: a technical user, with related permissions, will be able toretrieve data. This method is therefore not 100% secure.

Updating the database structure

To apply the modifications made to the schemas, launch the database update wizard. This wizard is accessible viaTools>Advanced>Update database structure. It checks whether the physical structure of the database matches itslogical description and executes the SQL update scripts.

The modules in the database are automatically populated and activated.


Editing schemas

The Add stored procedures and Import initialization data options are used to launch the initial SQL scripts and thedata 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 XMLfile 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.

Next, launch the database update:

New field wizard

A wizard accessible via Tools>Advanced>Add new fields lets you add one or more fields to a table in the database.

Validating the wizard updates the extension schema of the table to be extended and launches the SQL script tomodify the physical structure of the database.

70

This assistant has the advantage of quickly adding a field without needing to know the structure of a data schema.

The main disadvantage is the limitation of the data and the properties to be extended.

The wizard screens contain the following steps:

1 The first page lets you enter the name of the schema to be extended and the namespace of the extension schemawhere the modifications will be saved:

2 The next page lets you enter the properties of the field to be added.

3 To confirm the changes, click the Finish button.

An extension file, called "cus:recipient" in our example, is automatically created and the corresponding SQL scriptis executed:


Editing schemas

<srcSchema extendedSchema="nms:recipient" label="Recipients" name="recipient" namespace="cus"> <element name="recipient"> <attribute belongsTo="cus:recipient" dataPolicy="email" label="Email" length="80" name="email1" sqlname="sEmail1" type="string" user="true"/> </element></srcSchema>

Note:

By default, the added fields are declared with the property user (with the value "true"). This lets you display and editthe field in the input form of the extended schema using a "treeEdit"-type control (refer to Input Form).

Schema structure

The structure of a data schema is shown in the form of a tree structure. To view it graphically in the Adobe Campaignclient 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 elementscome 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" collectionlinks (Subscription, Orders, etc.) are displayed at the end.

Regenerating all schemas

To regenerate all the schemas and solve certain dependency problems in the reverse links, launch the followingcommand from the Adobe Campaign application server:

nlserver config -postupgrade -instance:<instance_name> -force

You must then reboot the Adobe Campaign application server and reconnect to the client console.

72

Examples

Extending a tableTo extend the nms:recipient schema recipient table, apply the following procedure:

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

<srcSchema mappingType="sql" name="extension" namespace="cus" xtkschema="xtk:srcSchema" extendedSchema="nms:recipient"> <enumeration basetype="string" default="area1" name="area"> <value label="Zone 1" name="area1"/> <value label="Zone 2" name="area2"/> </enumeration>

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

<attribute label="Loyalty code" name="fidelity" type="long"/> <element name="location"> <attribute name="area" label="Purchasing zone" type="string" length="50" enum="area"/> </element> </element> </srcSchema>

In this example, an indexed field (fidelity) is added, and the location element (which already existed in thenms: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);


Editing schemas

Linked collection tableThis section describes how to create an order table linked to the recipient table with cardinality 1-N.

Order table source schema:

<srcSchema label="Order" name="order" namespace="cus" xtkschema="xtk:srcSchema"> <element autopk="true" name="order"> <compute-string expr="@number" + '(' + ToString(@date) + ')'/>

<attribute label="Number" length="128" name="number" type="string"/> <attribute desc="Order date" label="Date" name="date" type="datetime" default="GetDate()"/> <attribute desc="order total" label="Total" name="total" type="double"/> <element label="Recipient" name="recipient" revDesc="Orders associated with this recipient" revIntegrity="own" revLabel="Orders" target="nms:recipient" type="link"/> </element></srcSchema>

The table type is autopk in order to create an auto-generated primary key to be used by the join of the link to therecipient table.

Schema generated:

<schema label="Order" mappingType="sql" name="order" namespace="cus" xtkschema="xtk:schema">

<element autopk="true" label="Order" name="order" sqltable="CusOrder"> <compute-string expr="ToString(@date) + ' - ' + @number"/>



<dbindex name="recipientId"> <keyfield xpath="@recipient-id"/> </dbindex>

<attribute desc="Internal primary key" label="Primary key" name="id" sqlname="iOrderId" type="long"/> <attribute label="Number" length="128" name="number" sqlname="sNumber" type="string"/>

<attribute desc="Order date" label="Date" name="date" sqlname="tsDate" type="datetime"/>

<attribute desc="order total" label="Total" name="total" sqlname="Total" type="double"/>

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

The table creation SQL script is as follows:

CREATE TABLE CusOrder(dTotal DOUBLE PRECISION NOT NULL Default 0, iOrderId INTEGER NOT NULL Default 0, iRecipientId INTEGER NOT NULL Default 0, sNumber VARCHAR(128), tsDate TIMESTAMP Default NULL);CREATE UNIQUE INDEX CusOrder_id ON CusOrder(iOrderId);CREATE INDEX CusOrder_recipientId ON CusOrder(iRecipientId); INSERT INTO CusOrder (iOrderId) VALUES (0);

Note:

The SQL command INSERT INTO at the end of the script lets you insert an identifier record set to 0 in order to simulateouter joins.

74

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

The purpose of an extension table is to avoid limitations on the number of fields supported in a table, or to optimizethe 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 schemacontaining the foreign key.

The SQL script for creating the extension table is as follows:

CREATE TABLE CusFeature( iChildren NUMERIC(3) NOT NULL Default 0, iFeatureId INTEGER NOT NULL Default 0, iSingle NUMERIC(3) NOT NULL Default 0, sSpouseFirstName VARCHAR(100));CREATE UNIQUE INDEX CusFeature_id ON CusFeature(iFeatureId); INSERT INTO CusFeature (iFeatureId) VALUES (0);

The recipient table SQL update script is as follows:

ALTER TABLE NmsRecipient ADD iFeatureId INTEGER;UPDATE NmsRecipient SET iFeatureId = 0;ALTER TABLE NmsRecipient ALTER COLUMN iFeatureId SET NOT NULL;ALTER TABLE NmsRecipient ALTER COLUMN iFeatureId SET Default 0;CREATE INDEX NmsRecipient_featureId ON NmsRecipient(iFeatureId);

Overflow tableAn overflow table is an extension table (cardinality 1-1), but the declaration of the link to the table to be extendedis 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 notmodified. The relation between the two tables is the value of the primary key of the table to be extended.

Creating the overflow table schema (cus:overflow):

<srcSchema label="Overflow" name="overflow" namespace="cus" xtkschema="xtk:srcSchema"> <element name="overflow"> <key internal="true" name="id"> <keyfield xlink="recipient"/> </key>

<attribute label="Children" name="children" type="byte"/> <attribute label="Single" name="single" type="boolean"/> <attribute label="Spouse first name" length="100" name="spouseFirstName" type="string"/>

<element label="Customer" name="recipient" revCardinality="single" revIntegrity="own" revExternalJoin="true" target="nms:recipient" type="link"/> </element> </srcSchema>


Editing schemas

Note:

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


CREATE TABLE CusOverflow(iChildren NUMERIC(3) NOT NULL Default 0, iRecipientId INTEGER NOT NULL Default 0, iSingle NUMERIC(3) NOT NULL Default 0, sSpouseFirstName VARCHAR(100));CREATE UNIQUE INDEX CusOverflow2_id ON CusOverflow2(iRecipientId);

Relationship tableA relationship table lets you link two tables with cardinality N-N. This table contains only the foreign keys of thetables to be linked.

Example of a relationship table between groups (nms:group) and recipients (nms:recipient).

Source schema of the relationship table:

<srcSchema name="rcpGrpRel" namespace="cus"> <element name="rcpGrpRel"> <key internal="true" name="id"> <keyfield xlink="rcpGroup"/> <keyfield xlink="recipient"/> </key>

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

The schema generated is as follows:

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

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

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

<dbindex name="rcpGroupId"> <keyfield xpath="@rcpGroup-id"/> </dbindex> <dbindex name="recipientId"> <keyfield xpath="@recipient-id"/> </dbindex>

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

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

76

</element></schema>


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


Editing schemas

78

Table of ContentsIdentifying a form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79Editing forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80Form structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

Formatting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82Containers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83Editing a link . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85List of links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86Memory list controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87Non-editable fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89Radio button . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90Checkbox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90Navigation hierarchy edit . . . . . . . . . . . . . . . . . . . . . . . . . . 90Expression field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90Context of forms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91Wizards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

An input form lets you edit an instance associated with a data schema from the Adobe Campaign 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 (':') (forexample: "cus:contact").


CHAPTER 3

Input forms

Editing forms

The input form creation and configuration screen is accessible from the Administration > Configuration > Inputforms folder of the Adobe Campaign client console:

The editing zone lets you enter the XML content of the input form:

80

The preview generates a display of the input form:

Form structure

The description of a form is a structured XML document that observes the grammar of the form schema xtk:form.

The XML document of the input form must contain the <form> root element with the name and namespace attributesto 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 witha 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 input form based on the example schema:

<form name="recipient" namespace="cus"> <input xpath="@gender"/> <input xpath="@birthDate"/>


Input forms

<input xpath="@email"/></form>

The description of the edit controls starts from the <form> root element.

An edit control is entered in an <input> element with the xpath attribute containing the path of the field in its schema.

The edit control automatically adapts to the corresponding data type and uses the label defined in the schema.

Note:

You can overload the label defined in its data schema by adding the label attribute to the <input element:

<input xpath="@name" label="E-mail address"/>

By default, each field is displayed on a single line and occupies all available space depending on the type of data.

FormattingThe layout of the controls looks like the layout used in HTML tables, with the possibility of dividing a control intoseveral columns, interlacing elements, or specifying the occupation of available space. Remember, however, thatformatting 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:

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

The <container> element with the colcount attribute lets you force the display of child controls onto two columns.

The colspan attribute on a control extends the control by the number of columns entered in its value:

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

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

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

82

</container></form>

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

<form name="recipient" namespace="cus"> <static type="separator" colspan="2" label="General"/> <input xpath="@gender"/> <input xpath="@birthDate"/> <input xpath="@email" colspan="2"/> <static type="help" label="General information about recipient with date of birth, gender, and e-mail address." colspan="2"/></form>

The <static> tag with the separator type lets you add a separator bar with a label contained in the 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.

ContainersContainers let you group a set of controls. They are represented by the <container> element. They were used aboveto format controls over several columns.

The xpath attribute on a <container lets you simplify the referencing of child controls. The referencing of controls isthen relative to the parent <container parent.

Example of a container without "xpath":

<container colcount="2"> <input xpath="location/@zipCode"/> <input xpath="location/@city"/></container>

Example with the addition of "xpath" to the element called "location":

<container colcount="2" xpath="location"> <input xpath="@zipCode"/> <input xpath="@city"/></container>

Types of 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>


Input forms

The main container is defined by the type="notebook" attribute. Tabs are declared in the child containers, and thelabel 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. Thisfeature is optional.

<container type="notebook" style="down"> ...</container>

Icon list

This container displays a vertical icon bar that lets you select the pages to be displayed.

<container type="iconbox"> <container colcount="2" label="General" img="xtk:properties.png"> <input xpath="@gender"/> <input xpath="@birthDate"/> <input xpath="@email" colspan="2"/> </container> <container colcount="2" label="Location" img="nms:msgfolder.png"> ... </container></container>

The main container is defined by the type="iconbox" attribute. The pages associated with the icons are declared inthe 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 imagecorresponding 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 visibilitycondition.

Examples of condition syntax:

n visibleIf="@email='[email protected]'": tests equality on string-type data. Thecomparison value must be in quotes.

n visibleIf="@gender >= 1 and @gender != 2": condition on a numeric value.

n visibleIf="@boolean1==true or @boolean2==false": test on Boolean fields.

84

Enabling container

This container lets you enable or disable a set of data from a dynamic condition. Disabling a control prevents it frombeing 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 theactivation condition.

Editing a linkRemember that a link is declared in the data schema as follows:

<element label="Company" name="company" target="cus:company" type="link"/>

The edit control of the link in its input form is as follows:

<input xpath="company"/>

Target selection is accessible via the edit field. Entry is assisted by type-ahead so that a target element can easily befound from the first few characters entered. The search is then based on the Compute string defined in the targetedschema. If the schema does not exist after validation in the control, a confirmation message of on-the-fly targetcreation 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 onthe 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 inputform:

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


Input forms

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 linksA link entered in the data schema as a collection element (unbound="true") must go through a list in order to viewall the elements associated with it.

The principle consists in displaying the list of linked elements with optimized data loading (downloading by databatch, execution of the list only if it is visible).

Example of a collection link in a schema:

<element label="Events" name="rcpEvent" target="cus:event" type="link" unbound="true">...</element>

The list in its input form:

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

List control is defined by the type="linklist" attribute. The list path must refer to the collection link.

The columns are declared via the <input> elements of the list. The xpath attribute refers to the path of the field inthe 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 elementlaunches 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 thelist: 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 thetwo tables.

Adding an element to the list should therefore let you complete a list from one of the two links in the relationshiptable.

86

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 associationswith subscriptions to services and must allow you to add a subscription by selecting an existing service.

<input type="linklist" xpath="subscription" xpathChoiceTarget="service" xpathEditTarget="service" zoom="true"> <input xpath="recipient"/> <input xpath="service"/></input>

The xpathChoiceTarget attribute lets you launch a selection form from the link entered. Creating the relationshiptable 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


n zoom: adds the Zoom button to edit the targeted element

n xpathEditTarget: sets editing on the link entered

n xpathChoiceTarget: for addition, launches the selection form on the link entered

Memory list controlsMemory lists let you edit the collection elements using list data preloading. This list cannot be filtered or configured.

These lists are used on XML mapped collection elements or on low-volume links.


Input forms

Column list

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

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

The list control must be filled in with the type="list" attribute, and the path of the list must refer to the collectionelement.

The columns are declared in the child <input> tags of the list. Column label and size can be forced with the labeland colSize attributes.

Note:

Sort-order arrows are added automatically when the ordered="true" attribute is added to the collection elementin the data schema.

The toolbar buttons can be aligned horizontally:

<input nolabel="true" toolbarCaption="List of events" type="list" xpath="rcpEvent" zoom="true"> <input xpath="@label"/> <input xpath="@date"/></input>

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

88

Zoom in a list

Insertion and editing of the data in a list can be entered in a separate edit form.

<input nolabel="true" toolbarCaption="List of events" type="list" xpath="rcpEvent" zoom="true" zoomOnAdd="true"> <input xpath="@label"/> <input xpath="@date"/>

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

The edit form is completed from the <form> element under list definition. Its structure is identical to that of an inputform.

The Detail button is added automatically when the zoom="true" attribute is completed on the <input> tag of thelist. This attribute lets you launch the edit form of the selected line.

Note:

Adding the zoomOnAdd="true" attribute forces the edit form to be called up when a list element is inserted.

List properties

n noToolbar: hides the toolbar (with value "true")

n toolbarCaption: overloads the toolbar label

n toolbarAlign: modifies the positioning of the toolbar (possible values: "vertical"|"horizontal")

n img: displays the image associated with the list


n zoom: adds the Zoom button to edit the targeted element

n zoomOnAdd: launches the edit form on the addition

n xpathChoiceTarget: for addition, launches the selection form on the link entered

Non-editable fieldsTo display a field and prevent it from being edited, use the <value> tag or complete the readOnly="true" attributeon the <input> tag.

Example on the "Gender" field:

<value value="@gender"/><input xpath="@gender" readOnly="true"/>


Input forms

Radio buttonA radio button lets you choose from several options. The <input> tags are used to list the possible options, and thecheckedValue attribute specifies the value associated with the choice.

Example on the "Gender" field:

<input type="RadioButton" xpath="@gender" checkedValue="0" label="Choice 1"/><input type="RadioButton" xpath="@gender" checkedValue="1" label="Choice 2"/><input type="RadioButton" xpath="@gender" checkedValue="2" label="Choice 3"/>

CheckboxA checkbox reflects a Boolean state (selected or not). By default, this control is used by "Boolean" (true/false) fields.A variable taking a default value of 0 or 1 can be associated with this button. This value can be overloaded via thecheckValue attributes.

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

Navigation hierarchy editThis control builds a tree on a set of fields to be edited.

The controls to be edited are grouped in a <container> entered under the <input> tag of the tree control:

<input nolabel="true" type="treeEdit"> <container label="Text fields"> <input xpath="@text1"/> <input xpath="@text2"/> </container> <container label="Boolean fields"> <input xpath="@boolean1"/> <input xpath="@boolean2"/> </container></input>

Expression fieldAn expression field updates a field dynamically from an expression; the <input> tag is used with an xpath attributeto enter the path of the field to be updated and an expr attribute containing the update expression.

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

90

Context of formsThe execution of an input form initializes an XML document containing the data of the entity being edited. Thisdocument represents the context of the form, and can be used as a workspace.

Updating the context

To modify the context of the form, use the <set xpath="<field>" expr="<value>"/> tag, where <field>is the destination field, and <value> is the update expression or value.

Examples of use of the <set> tag:

n <set xpath="/tmp/@test" expr="'Test'"/: positions the 'Test' value at temporary location/tmp/@test1

n <set xpath="@lastName" expr="'Test'"/: updates the entity on the "lastName" attribute with the'Test' value

n <set xpath="@boolean1" expr="true"/: sets the value of the "boolean1" field to "true"

n <set xpath="/tmp/@test" expr="@lastName"/: updates with the content of the "lastName" attribute

The context of the form can be updated when initializing and closing the form via the <enter> and <leave> tags.

<form name="recipient" namespace="cus"> <enter> <set... </enter> ... <leave> <set... </leave></form>

Note:

The <enter> and <leave> tags can be used on the <container> of pages ("notebook" and "iconbox" types).

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

<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 formand displays an error message if the condition is not satisfied:

<leave><check expr="/tmp/@test != ''"><error>You must populate the 'Test' field!</error>

</check></leave>

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


Input forms

...</form>

The presence of the type="wizard" attribute on the <form> element lets you define the wizard mode in theconstruction of the form.

The pages are completed from <container elements, which are children of the <form> element. The <containerelement of a page is populated with the title attributes for the title and desc to display the description under thepage 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>

92

Table of ContentsAbout web services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94

Definition of Adobe Campaign APIs . . . . . . . . . . . . . . . . . . . . . . . 94Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94Using Adobe Campaign APIs . . . . . . . . . . . . . . . . . . . . . . . . . 94SOAP calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94Resources and exchanges . . . . . . . . . . . . . . . . . . . . . . . . . . 95Example of a SOAP message on the 'ExecuteQuery' method . . . . . . . . . . . . . . . 95Error management . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96URL of Web service server (or EndPoint) . . . . . . . . . . . . . . . . . . . . . 97

Web service calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97General information . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97Definition of Web services . . . . . . . . . . . . . . . . . . . . . . . . . . 97Web service description: WSDL . . . . . . . . . . . . . . . . . . . . . . . . 98Connectivity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

Data oriented APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101Overview of the datamodel . . . . . . . . . . . . . . . . . . . . . . . . . 102Description of the model . . . . . . . . . . . . . . . . . . . . . . . . . . 102Query and Writer . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102ExecuteQuery (xtk:queryDef) . . . . . . . . . . . . . . . . . . . . . . . . . 103Write / WriteCollection (xtk:session) . . . . . . . . . . . . . . . . . . . . . . 110

Business oriented APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112Subscribe (nms:subscription) . . . . . . . . . . . . . . . . . . . . . . . . . 113Unsubscribe (nms:subscription) . . . . . . . . . . . . . . . . . . . . . . . . 114SubmitDelivery (nms:delivery) . . . . . . . . . . . . . . . . . . . . . . . . 115

Implementing SOAP methods . . . . . . . . . . . . . . . . . . . . . . . . . 116Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116Defining a method library . . . . . . . . . . . . . . . . . . . . . . . . . . 116

SOAP methods in JavaScript . . . . . . . . . . . . . . . . . . . . . . . . . . 117Static methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117Non-static methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

Adding additional SQL functions . . . . . . . . . . . . . . . . . . . . . . . . . 118Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118General structure of package to import . . . . . . . . . . . . . . . . . . . . . 119Function descriptor <function> . . . . . . . . . . . . . . . . . . . . . . . . 120'Pass-through' function descriptor . . . . . . . . . . . . . . . . . . . . . . . 121Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121


CHAPTER 4

API

About web services

Definition of Adobe Campaign APIsThe Adobe Campaign application server was designed for openness and easy integration with increasingly diverseand complex company information systems.

Adobe Campaign APIs are used in JavaScript within the application and in SOAP outside of it. They make up a libraryof generic functions that can be enriched. For further information, refer to Implementing SOAP methods [page 116].

Warning:

The Adobe Campaign APIs are optional and under license. A list of all the APIs including their full description isavailable in a dedicated document - JSAPI.CHM. Check your license contract.

PrerequisitesBefore using the Adobe Campaign APIs, you need to be familliar with the following topics:

n Javascript

n SOAP protocol

n Adobe Campaign datamodel

Using Adobe Campaign APIsAdobe Campaign uses two types of APIs:

n Generic data acces APIs for querying the datamodel data. Refer to Data oriented APIs [page 101].

n Business specific APIs that let you act on each object: deliveries, workflows, subscriptions, etc. Refer to Businessoriented APIs [page 112].

In order to develop APIs and interact with Adobe Campaign, you need to be familiar with your datamodel. AdobeCampaign lets you generate a complete description of the base. Refer to Description of the model [page 102].

SOAP callsThe SOAP protocol lets you invoke API methods, via the rich client, third-party applications using webservices, orJSP using these methods natively.

Figure 4.1. Adobe Campaign architecture

The structure of a SOAP message is as follows:

n an envelope which defines the structure of the message,

n an optional header,

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

94

n error management that defines the error condition.

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

Example of a SOAP message on the 'ExecuteQuery' methodIn this example, a SOAP query invokes the "ExecuteQuery" method, which takes a character string as a parameterfor authentication (session token) and an XML content for the description of the query to be executed.

For further information, refer to ExecuteQuery (xtk:queryDef) [page 103].

Note:

The WSDL description of this service is completed in the example shown here: Web service description: WSDL[page 98].

SOAP query

<?xml version='1.0' encoding='ISO-8859-1'?> <SOAP-ENV:Envelope xmlns:xsd='http://www.w3.org/2001/XMLSchema' xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' xmlns:ns='http://xml.apache.org/xml-soap' xmlns:SOAP-ENV='http://schemas.xmlsoap.org/soap/envelope/'> <SOAP-ENV:Body> <ExecuteQuery xmlns='urn:xtk:queryDef' SOAP-ENV:encodingStyle='http://schemas.xmlsoap.org/soap/encoding/'> <__sessiontoken xsi:type='xsd:string'/> <entity xsi:type='ns:Element' SOAP-ENV:encodingStyle='http://xml.apache.org/xml-soap/literalxml'> <queryDef firstRows="true" lineCount="200" operation="select" schema="nms:rcpGrpRel" startLine="0" startPath="/" xtkschema="xtk:queryDef"> ... </queryDef> </entity> </ExecuteQuery> </SOAP-ENV:Body></SOAP-ENV:Envelope>

The <SOAP-ENV:Envelope> element is the first element of the message representing the SOAP envelope.


API

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 theauthentication chain, the second parameter is the XML description of the query from the <queryDef> element.

SOAP response

<?xml version='1.0' encoding='ISO-8859-1'?> <SOAP-ENV:Envelope xmlns:xsd='http://www.w3.org/2001/XMLSchema' xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' xmlns:ns='http://xml.apache.org/xml-soap' xmlns:SOAP-ENV='http://schemas.xmlsoap.org/soap/envelope/'> <SOAP-ENV:Body> <ExecuteQueryResponse xmlns='urn:xtk:queryDef' SOAP-ENV:encodingStyle='http://schemas.xmlsoap.org/soap/encoding/'> <pdomOutput xsi:type='ns:Element' SOAP-ENV:encodingStyle='http://xml.apache.org/xml-soap/literalxml'> <rcpGrpRel-collection><rcpGrpRel group-id="1872" recipient-id="1362"></rcpGrpRel></rcpGrpRel-collection> </pdomOutput> </ExecuteQueryResponse> </SOAP-ENV:Body></SOAP-ENV:Envelope>

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

Error managementExample SOAP error response:

<?xml version='1.0' encoding='ISO-8859-1'?><SOAP-ENV:Envelope xmlns:SOAP-ENV='http://schemas.xmlsoap.org/soap/envelope/'> <SOAP-ENV:Body> <SOAP-ENV:Fault> <faultcode>SOAP-ENV:Server</faultcode> <faultstring>Error while executing 'Write' of the 'xtk:persist'.</faultstring> service

<detail>ODBC error: [Microsoft][ODBC SQL Server Driver][SQL Server]Cannot insert duplicate key row in object 'XtkOption' with unique index 'XtkOption_name'. SQLSTate: 23000ODBC error: [Microsoft][ODBC SQL Server Driver][SQL Server]The statement has been terminated. SQLSTate: 01000 Cannot save the 'Options (xtk:option)' document </detail> </SOAP-ENV:Fault> </SOAP-ENV:Body></SOAP-ENV:Envelope>

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

96

Important:

All Adobe Campaign Web services handle errors. It is therefore strongly recommended to test each call in order tohandle returned errors.

Example of error handling in C#:

try {// Invocation of method...

}catch (SoapException e){System.Console.WriteLine("Soap exception: " + e.Message); if (e.Detail != null)System.Console.WriteLine(e.Detail.InnerText);

}

URL of Web service server (or EndPoint)To submit the Web service, the Adobe Campaign server that implements the corresponding service method mustbe contacted.

The server URL is as follows:

http://<server>/nl/jsp/soaprouter.jsp

With <server> the Adobe Campaign application server (nlserver web).

Web service calls

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

n Development of special interfaces with simplified functionality (Web interfaces, etc.),

n Feeding and lookup of data in the database while observing trade rules and remaining isolated from the underlyingphysical model.

Definition of Web servicesThe definition of the Web services implemented on the Adobe Campaign application server is available from thedata schemas.

A Web service is described in the grammar of the data schemas and is available from the <methods> element.

<methods> <method name="GenerateForm" static="true"> <help>Generates the form in Mail or Web mode</help> <parameters> <param name="formName" type="string" desc="Name of form"/> <param name="mailMode" type="boolean" desc="Generate a form of type Mail"/> <param name="result" type="string" inout="out" desc="Result "/> </parameters> </method></methods>

Here we have an example of the definition of the method called GenerateForm.

The description of the service starts with the <method> element. The list of parameters of the method is completedfrom the <parameters> element. Each parameter is specified by a name, a type (Boolean, string, DOMElement, etc.)


API

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

and a description. The "inout" attribute with the "out" value lets you specify that the "result" parameter is at the SOAPcall output.

The presence of the "static" attribute (with the value "true") describes this method as static, which means that allparameters 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 an Adobe Campaign schema is available in the "Schema references"chapter under <method> element [page 44].

Example of the "const"-type "ExecuteQuery" method from the "xtk:queryDef" schema:

<method name="ExecuteQuery" const="true"> <help>Retrieve data from a query</help> <parameters> <param desc="Output xml document" name="output" type="DOMDocument" inout="out"/> </parameters></method>

The input parameter of this method is an XML document in the format of the "xtk:queryDef" schema.

Web service description: WSDLA WSDL (Web Service Description Library) file is available for each service. This XML file uses a metalanguage todescribe the service and to specify the available methods, parameters, and the server to contact for executing theservice.

WSDL file generation

To generate a WSDL file, you must enter the following URL from a Web browser:

https://<server>/nl/jsp/schemawsdl.jsp?schema=<schema>

With:

n <server>: the Adobe Campaign application server (nlserver web)

n <schema>: schema identification key (namespace:schema_name)

Example on the 'ExecuteQuery' method of schema 'xtk:queryDef'

The WSDL file is generated from the URL:

https://localhost/nl/jsp/schemawsdl.jsp?schema=xtk:queryDef

A WSDL description starts by defining the types used to form messages, associated in "ports", connected to a protocolby "bindings" forming Web services.

Types

Type definitions are based on XML schemas. In our example, the "ExecuteQuery" method takes an "s:string" stringand 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/>

98

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

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

</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 passas 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") generatinga response ("output").

<portType name="queryDefMethodsSoap"> <operation name="ExecuteQuery"> <input message="tns:ExecuteQueryIn"/> <output message="tns:ExecuteQueryOut"/> </operation></portType>

Binding

The <binding> part specifies the SOAP communication protocol (<soap:binding>), data transport in HTTP (value ofthe "transport" attribute) and the data format for the "ExecuteQuery" operation. The body of the SOAP envelopecontains 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 Adobe Campaign applicationserver.

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

ConnectivityAdobe Campaign has increased security for authentication mechanisms by introducing security zones (refer to theDefining security zones chapter in the Installation guide) as well as session management settings.

There are two authentication modes available:

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

or


API

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

n via the Adobe Campaign login + password that creates a session token. The session token automatically expiresafter a set period. This mode is not recommended and requires reducing the application security settings forsome zone settings (allowUserPassword="true" and sessionTokenOnly="true").

Session token characteristics

The session token has the following characteristics:

n a X hour life cycle (the life cycle is configurable in the 'serverConf.xml' file, the default period is 24 hours)

n a random construction (it no longer contains the user login and password)

n when accessed via the Web:

n the session token becomes a permanent token, it is not destroyed once the browser closes

n it is placed in an HTTP-ONLY cookie (cookies must be activated for operators)

Security token characteristics

The security token has the following characteristics:

n it is generated from the session token

n it has a 24 hour life cycle (configurable in the 'serverConf.xml' file, the default period is 24 hours)

n it is stored in the Adobe Campaign console

n when accessed via the Web:

n it is stored in a document.__securityToken property

n the page URLs are updated to update the security token

n the forms are also updated via a hidden field containing the token

Security token movement

When accessed via console, it is:

n transmitted in the logon response (in the HTTP header)

n used in each query (in the HTTP header)

From a POST and GET HTTP:

n the server completes the links with the token

n the server adds a hidden field to forms

From an SOAP call:

n it is added to call headers

Call examples

n Using HttpSoapConnection/SoapService:

var cnx = new HttpSoapConnection("https://serverURL/nl/jsp/soaprouter.jsp");var session = new SoapService(cnx, 'urn:xtk:session');session.addMethod("Logon", "xtk:session#Logon", ["sessiontoken", "string", "Login", "string", "Password", "string", "Parameters", "NLElement"], ["sessionToken", "string", "sessionInfo", "NLElement", "securityToken", "string"]);

var res = session.Logon("", "admin", "pwd", <param/>);var sessionToken = res[0];var securityToken = res[2];

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

var queryRes = query.ExecuteQuery("", <queryDef operation="select" schema="nms:recipient"> <select> <node expr="@email"/> <node expr="@lastName"/> <node expr="@firstName"/>

100

</select> <where> <condition expr="@email = '[email protected]'"/> </where> </queryDef>);logInfo(queryRes[0].toXMLString())

n Using HttpServletRequest:

Logon execution():

var req = new HttpClientRequest("http://domain.org/nl/jsp/soaprouter.jsp");req.header["Content-Type"] = "text/xml; charset=utf-8";req.header["SOAPAction"] = "xtk:session#Logon";req.method = "POST";

req.body = '<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:xtk:session">' + '<soapenv:Header/><soapenv:Body><urn:Logon>' + '<urn:sessiontoken/> <urn:strLogin>admin</urn:strLogin> <urn:strPassword>pwd</urn:strPassword> <urn:elemParameters/>' + '</urn:Logon></soapenv:Body></soapenv:Envelope>';req.execute();

var resp = req.response;var xmlRes = new XML(String(resp.body).replace("<?xml version='1.0'?>",""));var sessionToken = String(xmlRes..*::pstrSessionToken);;var securityToken = String(xmlRes..*::pstrSecurityToken);

Query execution:

var req2 = new HttpClientRequest("http://serverURL/nl/jsp/soaprouter.jsp");req2.header["Content-Type"] = "text/xml; charset=utf-8";req2.header["SOAPAction"] = "xtk:queryDef#ExecuteQuery";

req2.header["X-Security-Token"] = securityToken;req2.header["cookie"] = "__sessiontoken="+sessionToken;req2.method = "POST";

req2.body = '<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:xtk:queryDef">' +

'<soapenv:Header/><soapenv:Body><urn:ExecuteQuery><urn:sessiontoken/><urn:entity>' + '<queryDef operation="select" schema="nms:recipient">' + '<select><node expr="@email"/><node expr="@lastName"/><node expr="@firstName"/></select>' + '<where><condition expr="@email = \'[email protected]\'"/></where>' + '</queryDef>' + '</urn:entity></urn:ExecuteQuery></soapenv:Body></soapenv:Envelope>';

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

Data oriented APIs

Data oriented APIs let you address the entire datamodel.


API

Overview of the datamodelAdobe Campaign does not offer a dedicated read API per entity (no getRecipient or getDelivery function, etc.). Usethe QUERY & WRITER data read and modification methods to access the data of the model.

Adobe Campaign lets you manage collections: queries enable you to recover a set of information collected throughoutthe base. Unlike access in SQL mode, Adobe Campaign APIs return an XML tree instead of data columns. AdobeCampaign thus creates composite documents with all the collected data.

This operating mode does not offer one-to-one mapping between the attributes and elements of the XML documentsand the columns of the tables in the database.

XML documents are stored in MEMO type fields of the database.

Description of the modelYou must be familiar with the Adobe Campaign data model to be able to address the fields of the database in yourscripts.

For a presentation of the data model, refer to the Adobe Campaign Data template chapter in this guide.

In order to generate its structure, use the following process:

1 Import the datakit\nms\eng\package\optional\dbdBuilder.xml package.

2 Launch the following command on your Adobe Campaign instance: nlserver javascript-instance:<instance> cus:build-dbd.js

The database-description.odt file is generated in the Adobe Campaign installation folder and contains adescription of the Adobe Campaign tables. This file can be edited with LibreOffice and/or converted to PDFformat if necessary.

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

ExecuteQuery

For columns and conditions, you can use Queries.

This lets you isolate the underlying SQL. The query language does not depend on the underlying engine: somefunctions 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 98].

The ExecuteQuery method is presented in ExecuteQuery (xtk:queryDef) [page 103].

Write

Write commands let you write simple or complex documents, with entries in one or more tables of the base.

102

Transactional APIs let you manage reconciliations via the updateOrInsert command: one command lets you createor update data. You can also configure modification merging (merge): this operating mode lets you authorize partialupdates.

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

ExecuteQuery (xtk:queryDef)This method lets you perform queries from data associated with a schema. It takes an authentication string (mustbe logged in) and an XML document describing the query to be submitted as parameters. The return parameter isan XML document containing the result of the query in the format of the schema to which the query refers.

Definition of the "ExecuteQuery" method in the "xtk:queryDef" schema:

<method name="ExecuteQuery" const="true"> <parameters> <param desc="Output XML document" name="output" type="DOMDocument" inout="out"/> </parameters></method>

Note:

This is a "const" method. The input parameters are included in an XML document in the format of the "xtk:queryDef"schema.

Format of the XML document of the input query

The structure of the XML document of the query is described in the "xtk:queryDef " schema. This document describesthe clauses of a SQL query: "select", "where", "order by", "group by", "having".

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

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

Example of a <subQuery>:

<condition setOperator="NOT IN" expr="@id" enabledIf="$(/ignored/@ownerType)=1"> <subQuery schema="xtk:operatorGroup"> <select> <node expr="[@operator-id]" /> </select> <where> <condition expr="[@group-id]=$long(../@owner-id)"/>


API

</where> </subQuery></condition>

A query must reference a start schema from the schema attribute.

The type of operation desired is entered in the operation attribute and contains one of the following values:

n get: retrieves a record from the table and returns an error if the data does not exist,

n getIfExists: retrieves a record from the table and returns an empty document if the data does not exist,

n select: creates a cursor to return several records and returns an empty document if there is no data,

n count: returns a data count.

The XPath syntax is used to locate data based on the input schema. For further information about XPaths, refer toEditing schemas [page 59].

Example with the 'get' operation

Retrieves the last name and first name of a recipient ("nms:recipient" schema) with a filter on the e-mail.

<queryDef schema="nms:recipient" operation="get">  <select> <node expr="@firstName"/> <node expr="@lastName"/> </select>

 <where> <condition expr="@email= '[email protected]'"/> </where></queryDef>

Example with the 'select' operation

Returns the list of recipients filtered on a folder and the e-mail domain with a sort in descending order on date ofbirth.

<queryDef schema="nms:recipient" operation="select"> <select> <node expr="@email"/>  <node expr="@lastName+'-'+@firstName"/>  <node expr="Year(@birthDate)"/> </select>

<where> <condition expr="[@folder-id] = 1234 and @domain like 'Adobe%'"/> </where>

 <orderBy> <node expr="@birthDate" sortDesc="true"/>  </orderBy></queryDef>

Expressions can be simple fields or complex expressions such as arithmetic operations or the concatenation of strings.

To limit the number of records to be returned, add the lineCount attribute to the <queryDef element.

To limit the number of records returned by the query to 100:

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

To retrieve the next 100 records, run the same query again, adding the startLine attribute.

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

Example with the 'count' operation

To count the number of records on a query:

104

<queryDef schema="nms:recipient" operation="count"">  <where> <condition expr="[@folder-id] = 1234" and @domain like 'Adobe%'"/> </where></queryDef>

Note:

Again we use the condition from the previous example. The <select> and <orderBy> clauses are not used.

Data grouping

To retrieve e-mail addresses referenced more than once:

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

 <groupby> <node expr="@email"/> </groupby>

 <having> <condition expr="count(@email) > 1"/> </having>

</queryDef>

The query can be simplified by adding the groupBy attribute directly to the field to be grouped:

<select> <node expr="@email" groupBy="true"/></select>

Note:

It is no longer necessary to populate the <groupBy> element.

Bracketing in conditions

Here are two examples of bracketing on the same condition.

n The simple version in a single expression:

<where> <condition expr="(@age > 15 or @age <= 45) and (@city = 'Newton' or @city = 'Culver City') "/></where>

n The structured version with <condition> elements:

<where> <condition bool-operator="AND"> <condition expr="@age > 15" bool-operator="OR"/> <condition expr="@age <= 45"/> </condition> <condition> <condition expr="@city = 'Newton'" bool-operator="OR"/> <condition expr="@city = 'Culver City'"/> </condition></where>

It is possible to replace the 'OR' operator with the 'IN' operation when several conditions apply to the same field:

<where> <condition>


API

<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 tablecan be filtered or retrieved directly.

Example of a filter on the folder label:

<where> <condition expr="[folder/@label] like 'Segment%'"/></where>

To retrieve the fields of the folder from the "nms:recipient" schema:

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

n Collection links (1N): the filtering on the fields of a collection table must be performed via the EXISTS or NOTEXISTS 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 queryreturns a cardinal product. It is used only when the linked table contains only one record (example <nodeexpr="").

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 XPathsof 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 therecipient subscribes:

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

 <node expr="subscription"> <node expr="[service/@label]"/>  <where> <condition expr="@expirationDate >= GetDate()"/> </where> <orderBy> <node expr="@expirationDate"/> </orderBy> </node> </select> </queryDef>

106

Binding the parameters of the 'where' and 'select' clause

The binding of parameters lets the engine set the values of the parameters used in the query. This is very useful,since the engine is in charge of the escaping of values, and there is the additional benefit of a cache for the parametersto be retrieved.

When a query is constructed, the "bound" values are replaced by a character (? in ODBC, #[index]# in postgres...) inthe body of the SQL query.

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

To avoid binding a parameter, the "noSqlBind" attribute must be populated with the value 'true'.

Important:

If the query includes "order-by" or "group-by" instructions, the database engines will not be able to "bind" values.You must place the @noSqlBind="true" attribute on the "select" and/or "where" instructions of the query.

Query-building tip:

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

1 Select the data to be retrieved:


API

2 Define the filter condition:

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

Output document format

The return parameter is an XML document in the format of the schema associated with the query.

Example of a return from the "nms:recipient" schema on a "get" operation:

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

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

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

108

<recipient...</recipient-collection>

Example of a document returned for "count" type operation:

<recipient count="3"/>

Alias

An alias lets you modify the location of data in the output document. The alias attribute must specify an XPath onthe corresponding field.

<queryDef schema="nms:recipient" operation="get"> <select> <node expr="@firstName" alias="@firstName"/> <node expr="@lastName"/> <node expr="[folder/@label]" alias="@My_folder"/> </select> </queryDef>

Returns:

<recipient My_folder="Recipients" First name ="John" lastName="Doe"/>

Instead of:

<recipient firstName="John" lastName="Doe"> <folder label="Recipients"/></recipient>

Example of SOAP messages

n Query:

<?xml version='1.0' encoding='ISO-8859-1'?><SOAP-ENV:Envelope xmlns:xsd='http://www.w3.org/2001/XMLSchema' xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' xmlns:ns='http://xml.apache.org/xml-soap' xmlns:SOAP-ENV='http://schemas.xmlsoap.org/soap/envelope/'> <SOAP-ENV:Body> <ExecuteQuery xmlns='urn:xtk:queryDef' SOAP-ENV:encodingStyle='http://schemas.xmlsoap.org/soap/encoding/'> <__sessiontoken xsi:type='xsd:string'/> <entity xsi:type='ns:Element' SOAP-ENV:encodingStyle='http://xml.apache.org/xml-soap/literalxml'> <queryDef operation="get" schema="nms:recipient" xtkschema="xtk:queryDef"> <select> <node expr="@email"/> <node expr="@lastName"/> <node expr="@firstName"/> </select> <where> <condition expr="@id = 3599"/> </where> </queryDef> </entity> </ExecuteQuery> </SOAP-ENV:Body></SOAP-ENV:Envelope>

n Response:

<?xml version='1.0' encoding='ISO-8859-1'?><SOAP-ENV:Envelope xmlns:xsd='http://www.w3.org/2001/XMLSchema' xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' xmlns:ns='http://xml.apache.org/xml-soap' xmlns:SOAP-ENV='http://schemas.xmlsoap.org/soap/envelope/'> <SOAP-ENV:Body> <ExecuteQueryResponse xmlns='urn:xtk:queryDef' SOAP-ENV:encodingStyle='http://schemas.xmlsoap.org/soap/encoding/'> <pdomOutput xsi:type='ns:Element' SOAP-ENV:encodingStyle='http://xml.apache.org/xml-soap/literalxml'> <recipient email="[email protected]" lastName"Doe" firstName="John"/> </pdomOutput> </ExecuteQueryResponse>


API

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

Write / WriteCollection (xtk:session)These services are used to insert, update, or delete an entity ("Write" method) or a collection of entities("WriteCollection" method).

The entities to be updated are associated with a data schema. The input parameters are an authentication string(must be logged in) and an XML document containing the data to be updated.

This document is supplemented by instructions for configuring the write procedures.

The call does not return any data, except errors.

Definition of the "Write" and "WriteCollection" methods in the "xtk:session" schema:

<method name="Write" static="true"> <parameters> <param name="doc" type="DOMDocument" desc="Difference document"/> </parameters></method><method name="WriteCollection" static="true"> <parameters> <param name="doc" type="DOMDocument" desc="Difference collection document"/> </parameters></method>

Note:

This is a "static" method. The input parameters are included in an XML document in the format of the schema to beupdated.

Overview

Data reconciliation operates based on the definition of the keys entered in the associated schema. The write procedurelooks for the first eligible key based on the data entered in the input document. The entity is inserted or updatedbased 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 thekey (separated by commas).

It is possible to force the type of operation by populating the _operation attribute with the following values:

n insert: forces the insertion of the record (the reconciliation key is not used),

n insertOrUpdate: updates or inserts the record depending on the reconciliation key (default mode),

n update: updates the record; does nothing if the data does not exist,

n delete: deletes the records,

n none: used only for link reconciliation, without update or insertion.

Example with the 'Write' method

Updating or inserting a recipient (implicit "insertOrUpdate" operation) with e-mail address, date of birth and town:

<recipient xtkschema="nms:recipient" email="[email protected]" birthDate="1956/05/04" folder-id=1203 _key="@email, [@folder-id]"> <location city="Newton"/></recipient>

Deleting a recipient:

<recipient xtkschema="nms:recipient" _operation="delete" email="[email protected]" folder-id=1203 _key="@email, [@folder-id]"/>

Note:

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

110

Example with the 'WriteCollection' method

Update or insertion for several recipients:

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

Example on links

Example 1

Associating the folder with a recipient based on its internal name (@name).

<recipient _key="[folder/@name], @email" email="[email protected]" lastName="Doe" firstName="John" xtkschema="nms:recipient"> <folder name="Folder2" _operation="none"/></recipient>

The "_key" and "_operation" attributes can be entered on a linked element. The behavior on this element is thesame 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="[email protected]" lastName="Doe" firstName="John" xtkschema="nms:recipient"> <company name="adobe" code="ERT12T" _key="@name" _operation="update"/></recipient>

Example 3

Adding a recipient to a group with the group relation table ("nms:rcpGrpRel"):

<recipient _key="@email" email="[email protected]" xtkschema="nms:recipient"> <rcpGrpRel _key="[rcpGroup/@name]"> <rcpGroup name="GRP1"/> </rcpGrpRel></recipient>

Note:

The definition of the key is not entered in the <rcpGroup> element because an implicit key based on the group nameis defined in the "nms:group" schema.

XML collection elements

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


n Query:

<?xml version='1.0' encoding='ISO-8859-1'?><SOAP-ENV:Envelope xmlns:xsd='http://www.w3.org/2001/XMLSchema' xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' xmlns:ns='http://xml.apache.org/xml-soap' xmlns:SOAP-ENV='http://schemas.xmlsoap.org/soap/envelope/'>


API

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

n Response:

<?xml version='1.0' encoding='ISO-8859-1'?><SOAP-ENV:Envelope xmlns:xsd='http://www.w3.org/2001/XMLSchema' xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' xmlns:ns='http://xml.apache.org/xml-soap' xmlns:SOAP-ENV='http://schemas.xmlsoap.org/soap/envelope/'> <SOAP-ENV:Body> <WriteResponse xmlns='urn:' SOAP-ENV:encodingStyle='http://schemas.xmlsoap.org/soap/encoding/'> </WriteResponse> </SOAP-ENV:Body></SOAP-ENV:Envelope>

Return with error:

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

Business oriented APIs

Business API are specific to each type of object. They have an effect on:

n Deliveries, for:

n Creating a delivery action, refer to SubmitDelivery (nms:delivery) [page 115],

n sending a campaign (start, pause, stop, send proof),

n recovering delivery logs,

n Workflows:

n starting a workflow,

n verifying processes, etc.

Refer to SOAP methods in JavaScript [page 117].

n Content management

n Subscription management, refer to Subscribe (nms:subscription) [page 113] and Unsubscribe (nms:subscription)[page 114].

n Data processes: imports, exports.

This section details the use of the "Subscribe", "Unsubscribe" and "SubmitDelivery" services.

112

Important:

The JSAPI.chm document (under license) contains additional information on SOAP calls and using Javascript inAdobe Campaign, as well as a full reference to all methods and functions used in the application.

Subscribe (nms:subscription)This service lets you subscribe a recipient to an information service and update the recipient profile.

The following parameters are required in order to call the service:

n an authentication,

n internal name of the subscription service,

n an XML document containing the recipient information (from the "nms:recipient" schema),

n a Boolean for recipient creation if there isn't already one.

Description of the "subscribe" method in the "nms:subscription" schema:

<method name="Subscribe" static="true"> <parameters> <param name="serviceName" type="string" desc="List of information service names (comma separated)"/> <param name="recipient" type="DOMElement" desc="Recipient"/> <param name="create" type="Boolean" desc="Create recipient if it does not exist"/> </parameters></method>

The definition of the reconciliation key must be entered via the _key attribute on the <recipient element of the XMLdocument. 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 theemail address and the definition of the key on this field.

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

Updating the recipient as well as the subscription.

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


n Query:

<?xml version='1.0' encoding='ISO-8859-1'?><SOAP-ENV:Envelope xmlns:xsd='http://www.w3.org/2001/XMLSchema' xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' xmlns:SOAP-ENV='http://schemas.xmlsoap.org/soap/envelope/'> <SOAP-ENV:Body> <m:Subscribe xmlns:m='urn:nms:subscription' SOAP-ENV:encodingStyle='http://schemas.xmlsoap.org/soap/encoding/'> <sessiontoken xsi:type='xsd:string'/> <service xsi:type='xsd:string'>SVC1</service> <content xsi:type='' SOAP-ENV:encodingStyle='http://xml.apache.org/xml-soap/literalxml'> <recipient _key="@email" email= "[email protected]/> </content> <create xsi:type='xsd:boolean'>true</create> </m:Subscribe> </SOAP-ENV:Body></SOAP-ENV:Envelope></SOAP-ENV:Envelope>

n Response:

<?xml version='1.0' encoding='ISO-8859-1'?><SOAP-ENV:Envelope xmlns:xsd='http://www.w3.org/2001/XMLSchema' xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'


API

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.



n Internal name of the service to unsubscribe from,

n an XML document containing the recipient information (from the "nms:recipient" schema),

Description of the "Unsubscribe" method in the "nms:subscription" schema:

<method name="Unsubscribe" static="true"> <parameters> <param name="serviceName" type="string" desc="List of information service names (comma separated)"/> <param name="recipient" type="DOMElement" desc="Recipient"/> </parameters></method>

The definition of the reconciliation key must be entered via the _key attribute on the <recipient element of the XMLdocument. 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 serviceperforms no action and does not generate an error.

Note:

If the service name is not specified as a parameter, the recipient is then automatically blacklisted (@blackList="1").



Query:

<?xml version='1.0' encoding='ISO-8859-1'?><SOAP-ENV:Envelope xmlns:xsd='http://www.w3.org/2001/XMLSchema' xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' xmlns:SOAP-ENV='http://schemas.xmlsoap.org/soap/envelope/'> <SOAP-ENV:Body> <m:Unsubscribe xmlns:m='urn:nms:subscription' SOAP-ENV:encodingStyle='http://schemas.xmlsoap.org/soap/encoding/'> <sessiontoken xsi:type='xsd:string'/> <service xsi:type='xsd:string'>SVC1</service> <content xsi:type='' SOAP-ENV:encodingStyle='http://xml.apache.org/xml-soap/literalxml'>

<recipient _key="@email" email= "[email protected]/> </content> </m:Unsubscribe></SOAP-ENV:Body>

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>

114

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

SubmitDelivery (nms:delivery)This service lets you create and submit a delivery action.



n internal name of the delivery template,

n an optional XML document containing additional delivery data.

Warning:

This API should not be called in volume as you may encounter of performance issues.

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 Adobe Campaign client console. It contains the parameters commonto all deliveries (sender address or duration of validity of the message).

The input XML document is a delivery template fragment that obeys the structure of the "nms:delivery" schema. Itwill contain all additional data that could not be defined statically in the delivery template (e.g., list of recipients totarget).


XML document example

This example is based on a custom delivery template from an external data source (a file in this case). The configurationis fully described in the delivery template, so all that remains to be sent when the call occurs is the content of thefile from the <externalSource> element.

<delivery> <targets fromExternalSource="true"> <externalSource> MsgId|ClientId|Title|Name|FirstName| Mobile|Email| Market_segment|Product_affinity1 |Product_affinity2|Product_affinity3| Product_affinity4| Support_Number|Amount|Threshold1|000001234|M.| Doe|John|0650201020| [email protected]|1| A1|A2|A3|A4|E12|120000|100000 </externalSource> </target></delivery>

If you do not have a delivery template, you can use the following sample:

<delivery><targets fromExternalSource="true" targetMode="1" noReconciliation="true" addressField="Email" > <fileFormat active="true"> <source format="text" type="text"> <dataSourceConfig > <dataSourceColumn label="Email" name="Email" type="string"/> </dataSourceConfig> </source> <destination type="xtkDataStore"/> </fileFormat> <externalSource><![CDATA[[email protected]]]></externalSource> </targets> </delivery>


API

Implementing SOAP methods

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

Defining a method libraryCreating a method library involves two stages:

n The SOAP method declaration,

n Definition (or implementation) in JavaScript.

Declaration

Start by declaring the methods in the schemas. Their declaration is similar to that of native methods, except that youneed 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 wherethe 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 definedin 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.

116

Specific cases:

n non-static methods: the function must include an additional argument first, coinciding with the XML entitypassed 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 passedin 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 declaredwithout any of the 'static', 'key only' or 'const' attributes, the first returned value must coincide with the modifiedentity. It is possible to return a new object or to return the first modified parameter.

For example:

function nms_recipient_setLastName(self, name) { self.@lastName = name return self }

When several values are to be returned, they must be displayed in a table.

Example:

function nms_recipient_getKey(self) { return [self.@firstName, self.@lastName] }

SOAP methods in JavaScript

This is the JavaScript executed on the Adobe Campaign server.

Static methodsStatic SOAP methods are accessed by invoking a method on the object representing the schema. Schemas areproperties of 'namespace' objects. These namespaces are global variables, thus, for example, xtk or nms variablesrepresent the corresponding namespaces

The following example invokes the static PostEvent method of the xtk:workflow schema:

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

Non-static methodsTo use non-static SOAP methods, it is necessary first to retrieve an entity using the "get" or "create" methods on thecorresponding schemas.

The following example invokes the ExecuteQuery method of the "xtk:queryDef" schema:

var query = xtk.queryDef.create( <queryDef schema="xtk:workflow" operation="select"> <select> <node expr="@internalName"/> </select> </queryDef>)

var res = query.ExecuteQuery()

for each (var w in res.workflow) logInfo(w.@internalName)

Examples

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

var query = xtk.queryDef.create( <queryDef schema="nms:recipient" operation="get">


API

<select> <node expr="@firstName"/> <node expr="@lastName"/> <node expr="@email"/> </select> <where> <condition expr="@email = '[email protected]'"/> </where> </queryDef>)

var recipient = query.ExecuteQuery()

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

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

var query = xtk.queryDef.create( <queryDef schema="nms:recipient" operation="select"> <select> <node expr="@email"/> <node expr="@lastName"/> <node expr="@firstName"/> </select> <where> <condition expr="@age > 25"/> </where> </queryDef>)

var res = query.ExecuteQuery()

for each (var recipient in res.recipient) { logInfo(recipient.@email) logInfo(recipient.@firstName) logInfo(recipient.@lastName)}

n Writing data to the recipient table:

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

Adding additional SQL functions

IntroductionAdobe Campaign allows the user to define their own functions that can access SQL functions, both those offeredby the database and those which are not already available in the console. This is useful for aggregate functions(average, maximum, sum) for example, which can only be calculated on the server or when the database providesan easier way to implement certain functions, rather than "manually" write the expression in the console (e.g. datemanagement).

This mechanism can also be used if you wanted to use a recent or uncommon database engine SQL function, whichis not yet offered by the Adobe Campaign console.

Once these functions have been added, they will appear in the expression editor just like other predefined functions.

Warning:

SQL function calls in the console are no longer naturally sent to the server. The mechanism described here thereforebecomes the only way to call on the unplanned SQL function server.

InstallationThe function(s) to add are in a "package" file in XML format, whose structure is detailed in the following paragraph.

118

To install it from the console, select the Tools/Advanced/Import package options from the menu, then theInstall from file, and follow the instructions in the import wizard.

Warning:

Warning: even if the list of imported functions appears in the function editor straight away, they will not be usableuntil Adobe Campaign has been restarted.

General structure of package to importThe function(s) to be added can be found in the "package" file in XML format. Here is an example:

<?xml version="1.0" encoding='ISO-8859-1' ?>

<packagenamespace = "nms"name = "package-additional-funclist"label = "Additional functions"buildVersion= "6.1"buildNumber = "10000">

<entities schema="xtk:funcList"><funcList name="myList" namespace="cus"><group name="date" label="Personalized date"><function name="relativeMaturity" type="long" args="(<Âge>)" help="Returns

the difference between a date and 18 years"minArgs="1" maxArgs="1" display="Relative maturity of the person born

on the date $1"><providerPart provider="MSSQL,Sybase,PostgreSQL" body="extract(year from

age($1))-18"/></function>

</group></funcList>

</entities></package>

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

n The buildVersion and buildNumber fields are mandatory. They must correspond to the server number to whichthe console is connected. This information can be found in the "Help/About" box.

n The following blocks, entities and funclist are mandatory. In funcList, the fields "name" and "namespace" aremandatory, but their name is left up to the user to decide, and they uniquely designate the function list.

This means that if another list of functions with the same namespace/name pair (here "cus::myList") is imported,the previously imported functions will be deleted. Conversely, if you change this namespace/name pair, the newseries of imported functions will be added to the previous one.

n The group element lets you specify the function group in which the imported function(s) will appear in thefunction editor. The @name attribute can either be a name that already exists (in which case the functions willbe added to the considered group) or a new name (in which case it will appear in a new group).

n Reminder: possible values for the @name attribute in the <group> element are:

name="aggregate" ( label="Aggregates" ) name="string" ( label="String" ) name="date" ( label="Date" ) name="numeric" ( label="Numeric" ) name="geomarketing" ( label="Geomarketing" ) name="other" ( label="Others" ) name="window" ( label="Windowing functions" )


API

Warning:

Make sure to complete the @label attribute: this is the name that will be displayed in the list of available functions.If you do not enter anything, the group will not have a name. However, if you enter a name other than the existingname, the name of the entire group will change.

If you wish to add functions to several different groups, you can make several <group> elements become trackedin the same list.

Finally, a <group> element can contain the definition of one or several functions, that is the purpose of the packagefile. The <function> element is detailed in the following paragraph.

Function descriptor <function>The case presented here is a general case whereby we wish to provide the function implementation.

Below is an example of a "relative maturity" function which, using an age, indicates for how many years the personhas been considered mature.

<function name="relativeMaturity" type="long" args="(<Âge>)" help="Returns the difference between a date and 18 years" minArgs="1" maxArgs="1" display="Relative maturity of the person born on the date $1"> <providerPart provider="PostgreSQL" body="extract(year from age($1))-18"/> <providerPart provider="MSSQL,Sybase,Teradata" body="[Other implementation]"/> </function>

The @name field refers the name of the function, and "args" is the list of parameters that will be displayed in thedescription. In this case, the function will appear as "relativeMaturity (<Age>)" in the function selection window.

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

n @display is an informative message.

Note:

In the @help and @display attributes, the string "$1" represents the name that was given in the first functionparameter (here, "Age"). $2, $3... would represent the following parameters. In the @body attribute detailedbelow, $1 designates the argument value passed to the function during the call.

Note:

The description must be a string of valid XML characters: please note the use of '<' and '>' instead of < and >.

n @type is the function return type and is a standard value (long, string, byte, datetime...). If it is omitted, the serverdetermines the best type among the available types within the expression implementing the function.

n @minArgs and maxArgs designates the number of parameters (minimum and maximum) for a parameter. Forexample, for a function with 2 parameters, minArgs and maxArgs will be 2 and 2. For 3 parameters, plus 1optional, they will be 3 and 4 respectively.

n Finally, the providerPart element provides the function implementation.

n The provider attribute is mandatory, it specifies the database systems for which the implementation isprovided. As shown in the example, when expression syntaxes or underlying functions differ, alternativeimplementations can be provided according to the database.

n The @body attribute contains the function implementation. Please note: this implementation must be anexpression, in database language (not a block of code). Depending on the databases, expressions can besub-queries ("(select column from table where...)") returning only a single value. For example, this is the casein Oracle (the query must be written in brackets).

120

Note:

If only one or two databases are likely to be queried by the function defined, we can always provide only thedefinitions corresponding to these databases.

'Pass-through' function descriptorA special function descriptor is the <body> "pass-through" block, with an unspecified "provider" database system.In this case, "body" implementation can only contain a single function call with a syntax that is not dependent onthe database used. Meanwhile, the "ProviderPart" block is unique.

<function name="CountAll" args="()" help="Counts the values returned (all fields together)" type="long" minArgs="0" maxArgs="0"> <providerPart body="Count(*)"/> </function>

In this case, adding a function only serves to make a database function that would not have been available by default,now visible to the client.

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


API

122

Table of ContentsOverview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124

Global commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125Folder type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126

Edition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

Overview

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


CHAPTER 5

Navigation hierarchy

The view displayed is a list associated with a schema and an input form to edit the selected line.

Figure 5.1. Adobe Campaign Browser

To add a new folder to the tree, right-click the folder in the branch where you wish to insert a folder, and select Addnew 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 thextk:navtree schema.

The XML document is structured as follows:

<navtree name="name" namespace="name_space">  <commands> ... </commands>

124

 <model name="<name>" label="<Label>">  <nodeModel> ... </nodeModel><model name="<name>" label="<Sub model>"> ... </model> </model> </navtree>

The XML document contains the <navtree> root element with the name and namespace attributes to specify thedocument 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 commandsA global command lets you launch an action. This action can be an input form or a SOAP call.

Global commands are accessible from the main Tools menu.

The command configuration structure is as follows:

<commands>  <command name="<name>" label="<label>" desc="<Description>" form="<form>" rights="<rights>"> <soapCall name="<name>" service="<schema>"> <param type="<type>" exprIn="<xpath>"/> ... </soapCall> <enter> ... </enter> </command>  <command label="-" name="<name>"/>  <command name="<name>" label="<Label>"> <command... </command></commands>

The description of a global command is entered in the <command> element with the following properties:

n name: internal name of the command: the name must be entered and unique

n label: label of the command.

n desc: description visible from the status bar of the main screen.

n form: form to be launched: the value to be entered is the identification key of the input form (e.g. "cus:recipient")

n rights: list of named rights (separated by a comma) allowing access to this command. The list of available rightsis 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 asub-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 containedin the command label.

The optional presence of the <soapCall> tag with its input parameters defines the call of a SOAP method to beexecuted. 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 tothe documentation on input forms.

Example:

n Declaration of a global command to launch the "xtk:import" form:



<command desc="Start the data import wizard" form="xtk:import" label="&Data import..." name="import" rights="import,recipientImport"/>

A keyboard shortcut is declared on the 'I' character by the presence of & in the command label.

n Example of a sub-menu with a separator:

<command label="Administration" name="admin"> <command name="cmd1" label="Example 1" form="cus:example1"/> <command name="sep" label="-"/> <command name="cmd1" label="Example 2" form="cus:example2"> <enter> <set xpath="@type" expr="1"/> </enter> </command></command>

n Execution of a SOAP method:

<command name="cmd3" label="Example 3" promptLabel="Do you really want to execute the command?"> <soapCall name="Execute" service="xtk:sql"/></command>

Folder typeA folder type lets you give access to the data of a schema. The view associated with the folder consists of a list andan input form.

The folder type configuration structure is as follows:

<model name="name" label="Labelled">  <nodeModel name="<name>" label="<Labelled>" img="<image>"> <view name="<name>" schema="<schema>" type="<listdet|list|form|editForm>"> <columns> <node xpath="<field1>"/> ... </columns> </view> </nodeModel> <model name="<name>" label="<Sous modèle>"> ... </model></model>

The folder type declaration must be entered under a <model> element. This element lets you define a hierarchicalorganization visible from the Add new folder menu. A <model> element must contain <nodeModel> elementsand other <model> elements.

The name and label attributes populate the internal name of the element and the label displayed in the Add newfolder 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".

n newFolderShortCuts: list of shortcuts on models (<nodeModel> separated by a comma) in folder creation.

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

The <view> element under the <nodeModel> element contains the configuration of the list associated with theview. The schema of the list is entered in the schema attribute of the <view> element.

126

To edit the records of the list, the input form with the same name as the list schema is implicitly used. The typeattribute on the <view> element affects the display of the form. Possible values are:

n listdet: displays the form at the bottom of the list.

n list: displays the list alone. The form is launched by double-clicking or via the "Open" in the menu on selectingthe list.

n form: displays a read-only form.

n editForm: displays a form in edit mode.

Note:

The name of the input form can be overloaded by entering the form attribute in the <view> element.

The default configuration of the list columns is entered via the <columns> element. A column is declared on a<node> element containing the xpath attribute with the field to be referenced in its schema as its value.

Example: declaration of a folder type on the "nms:recipient" schema.

<model label="Profiles and targets" name="nmsProfiles"> <nodeModel deleteRight="folderDelete" editRight="folderEdit" folderLink="folder" img="nms:folder.png" insertRight="folderInsert" label="Recipients" name="nmsFolder"> <view name="listdet" schema="nms:recipient" type="listdet"> <columns> <node xpath="@firstName"/> <node xpath="@lastName"/> <node xpath="@email"/> <node xpath="@account"/> </columns> </view> </nodeModel> <nodeModel name="nmsGroup" label="Groups"...</model>

The corresponding folder insertion menu:

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

<view name="listdet" schema="nms:recipient" type="listdet"> <columns> ... </columns>

<orderBy> <node expr="@lastName" desc="true"/></orderBy> <sysFilter> <condition expr="@type = 1"/> </sysFilter></view>

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 rightsis 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 asub-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 containedin the command label.

The optional presence of the <soapCall> tag with its input parameters defines the call of a SOAP method to beexecuted. 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, referto 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 filteringentered 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 containsthe name of the link on the folder configured in the data schema.

Example of declaration of a linked folder in the data schema:

<element default="DefaultFolder('nmsFolder')" label="Folder" name="folder" revDesc="Recipients in the folder" revIntegrity="own" revLabel="Recipients" target="xtk:folder" type="link"/>

The configuration of the <nodeModel> on the link of the folder named "folder" is as follows:

<nodeModel deleteRight="folderDelete" editRight="folderEdit" folderLink="folder" img="nms:folder.png" insertRight="folderInsert" label="Recipients" name="nmsFolder">...</nodeModel>

128

Edition

The screen for creating and configuring the navigation hierarchy configuration documents is accessible via theAdministration/Configuration/Navigation hierarchies node:

The navigation hierarchy configuration is divided over several XML documents. It operates on a similar principle toschema 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:

130

Table of ContentsIntroduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131Precisions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132Recommendations and limitations . . . . . . . . . . . . . . . . . . . . . . . 132

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132The view attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133Names of tables and columns . . . . . . . . . . . . . . . . . . . . . . . . 133Indexed fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133

Target mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134Creating and configuring schemas linked to the custom table . . . . . . . . . . . . . . 134Using target mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . 137

Configuring the interface . . . . . . . . . . . . . . . . . . . . . . . . . . . 137Creating a new form . . . . . . . . . . . . . . . . . . . . . . . . . . . 138Creating a new type of folder in the navigation hierarchy . . . . . . . . . . . . . . . . 138

Seed addresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139

Creating filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140Creating lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141Managing workflows . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143Managing reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144

Introduction

OverviewThis section details the principles for using a non-standard recipient table. By default, Adobe Campaign offers astandard recipient table to which out-of-the-box functions and processes are linked. The standard recipient tablehas a number of predefined fields and tables that can be easily extended using an extension table. If this extensionmethod offers good flexibility to extend a table, it does not allow the number of fields or links in it to be reduced.Using a non-standard table, or 'external recipient table', allows for a greater flexibility but requires certain precautionswhen implementing it.


CHAPTER 6

Use a custom recipient table

PrecisionsThis functionality allows Adobe Campaign to process data from an external database: this data will be used as a setof profiles for deliveries. Implementing this process involves several precisions that may be relevant according tothe client's needs. Such as:

n No update stream to and from the Adobe Campaign database: data from this table can be updated directly viathe database engine that hosts it.

n No changes in the processes operating on the existing database.

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

n No changes or maintenance required when updating the Adobe Campaign database.

n The standard recipient table is useless if you do not need most of the table fields or if the database template isnot centered on the recipients.

n In order to be efficient, a table with few fields is needed if you have a significant number of profiles. The standardrecipient table has too many fields for this specific case.

Note:

We recommend using an external recipient table if the size of the data set is more than ten million profiles or if youuse a lot of specific fields.

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

Recommendations and limitationsUsing an external recipient table has the following limitations:

n You cannot use the standard Services and Subscriptions offered in the product.

This means the overall operation detailed in the Delivery guide is not applicable.

n The link with the visitor table does not work.

Thus, to use the Social Marketing module you must configure the storage step to reference the correct table.

Similarly, when using referral functions, the standard initial message transfer template must be adapted.

n You cannot manually add profiles in a list.

Therefore, the procedure detailed in the Platform Guide is not applicable without an additional configuration.

Note:

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

We also recommend checking the default values used in the different out-of-the-box configurations: depending onthe functionalities used, several adaptations must be carried out.

For example:

n Certain standard reports, particularly those offered by Interaction and the Mobile Applications must beredeveloped. Refer to the Managing reports [page 144] section.

n The default configurations for certain workflow activities reference the standard recipients table (nms:recipient):these configurations must be changed when used for an external recipients table. Refer to the Managing workflows[page 143] section.

n The standard Unsubscription link personalization block must be adapted.

n The target mapping of the standard delivery templates must be modified.

n V4 forms are not compatible for use with an external recipients table: you must use Web applications.

Overview

The characteristics of a schema that references an existing table are as follows:

132

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

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

n Adobe Campaign 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.

Warning:

Do not delete fields in the standard recipient table, even if they are useless. This may cause behavioural errors in theAdobe Campaign database.

The view attributeSource schemas accept the view attribute for the srcSchema root element. It must be used when Adobe Campaignis manipulated in custom tables. The view="true" attribute tells the database structure update wizard to ignore thisschema. The application is therefore prohibited from synchronizing the table, its columns and its indexes with thecorresponding schema.

When this attribute is set to true, the schema is used only to generate SQL queries to access the data of this table.

Names of tables and columnsWhen tables are created by the table update wizard, the names of tables and columns are generated automaticallybased on the names of the respective schemas and attributes. It is however possible to force the SQL names to beused by entering the following attributes:

n sqltable within the main element of the schema, to specify the table,

n sqlname within each attribute, to specify the columns.

Example:

<element label="Individual" name="individual" sqltable="individual"> <key internal="true" name="id"> <keyfield xpath="@id"/> </key> <attribute name="id" type="long" length="32" /> <attribute name="lastName" type="string" length="100" sqlname="Last_Name"/> <attribute name="firstName" type="string" length="100" sqlname="First_Name"/> <attribute name="email" type="string" length="100"/> <attribute name="mobile" type="string" length="100"/></element>

In this example, if the names of the tables and columns had not been explicitly specified, the application would haveused 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 notbe user-accessible.

Indexed fieldsWhen sorting the records of a list from the client console, better performance is obtained by sorting on indexedfields. Declaring an index in a schema makes the console display the indexed fields with a red line under the sort-orderarrow to the left of the column label, as shown below:

In a schema, an index is defined as follows:

<dbindex name="name_of_index" unique="true/false" <keyfield xpath="xpath_1st_field"/ <keyfield xpath="xpath_2nd_field"/ ...</dbindex



That's why it is important to declare existing indexes of the custom table in the matching schema.

An index is implicitly declared for each key and link declaration of the source schema. Index declaration can beprevented by specifying the noDbIndex="true" attribute:

Example:

<key internal="true" name="customer" noDbIndex="true"> <keyfield xpath="@customerId"/></key>

Target mapping

Target mapping creation is necessary in two cases:

n if you use a recipient table other than the one provided by Adobe Campaign,

n if you configure a filtering dimension which is different from the standard targeting dimension on the targetmapping screen.

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

Creating and configuring schemas linked to the custom tableBefore you create a target mapping, several configurations are necessary in order for Adobe Campaign to operatewith a new recipient data schema.

To do this, apply the following steps:

1 Create a new data schema which integrates the fields of the custom table that you want to use.

Note:

For further information, refer to Schema reference (xtk:srcSchema).

In our example, we will create a customer schema, a very simple table containing the following fields: ID, firstname, last name, email address, mobile phone number. The aim is to be able to send e-mail or SMS alerts tothe 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 133].

<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/@line2])" name="line2"/> <attribute expr="Upper([../address/@line])" name="line3"/>

134

configuration-v6.1-en.pdf#nameddest=CST-14174

<attribute expr="Upper([../address/@line])" name="line4"/> <attribute expr="Upper([../address/@line])" name="line5"/> <attribute expr="Upper([../address/@line])" 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/@line], [../infos/@name])" name="addrDefined"/> </element>

4 Click the Administration>Campaign management>Target mappings node.

5 Click the New button to open the target mapping creation wizard.

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 schemasfrom the out-of-the-box schemas provided by Adobe Campaign.

Click Define new additional fields to select the dimension you want to target in your delivery.



By default, exclusion management is stored in the same tables as messages. Check the Generate a storageschema 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 that you want to generate (the list of available schemasdepends on the modules installed on the Adobe Campaign platform).

10 Click the Save button to close the wizard.

136

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

Using target mappingThere are two ways of using the new schema as the target of a delivery:

n Create one or more delivery templates based on mapping

n Select mapping directly during target selection when creating a delivery, as shown below:

Configuring the interface

To view and dialog with the new recipient table in the Adobe Campaign interface, apply the following steps:

n Create a new form to edit the content of the new recipient table.

n Enter a new type in the folder of the explorer tree.

n Create a new web application to access the custom table via the Adobe Campaign home page.

Adobe Campaign uses a "Nms_DefaultRcpSchema" global variable to dialog with the default recipient database(nms:recipient). This variable therefore needs to be altered.

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



2 Change the value of the Nms_DefaultRcpSchema variable with the name of the schema which matches theexternal recipient table (in this case: cus:individual).

3 Save changes.

Creating a new formCreating a new form will enable you to view and edit the data of the external recipient table.

Important:

The name of the form must be identical to the name of the schema which it concerns.

1 Go to the Administration>Configuration>Input forms node of the explorer.

2 Create a new xtk:form type form file.

3 Describe all the monitorings and fields which you need depending on your table template.

Note:

To find out more about form type files, refer to the Navigation hierarchy chapter.

In our current example, the form file must be based on the cus:individual schema and therefore have thefollowing layout:

<container colspan="2"> <input xpath="@id"/> <static type="separator"/></container><container colcount="2"> <input xpath="@lastName"/> <input xpath="@firstName"/> <input xpath="@email"/> <input xpath="@mobile"/></container>

4 Save the creation.

Creating a new type of folder in the navigation hierarchy

1 Go to the Administration>Configuration>Navigation hierarchies node.

2 Create a new xtk:navtree type navtree document.

3 Describe all the monitorings and fields which you need depending on your table template.

Note:

For more on navtree type files, refer to the Navigation hierarchy chapter.

In the current example, the navtree file must be based on the cus:individual schema and therefore have thefollowing 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>

138

configuration-v6.1-en.pdf#nameddest=ACY-4258

configuration-v6.1-en.pdf#nameddest=CST-3068

</view> </nodeModel></model>

4 Save the creation.

Seed addresses

If the recipient table is an custom table, additional configurations are required. The nms:seedMember schema mustbe extended. An additional tab is added to the seed addresses for defining the adequate fields, as shown below:

For more on using seed addresses, refer to the "Seed addresses" section of the Delivery guide.

ImplementationThe nms:seedMember schema and the linked form which come out-of-the-box are meant to be extended forcustomer configuration, to reference all necessary fields. The schema definition contains comments detailing itsconfiguration mode.

Definition of the recipients table extended schema:

<srcSchema label="Person" name="person" namespace="cus"> <element autopk="true" label="Person" name="person"> <attribute label="LastName" name="lastname" type="string"/> <attribute label="FirstName" name="firstname" type="string"/> <element label="Address" name="address"> <attribute label="Email" name="addrEnv" type="string"/> </element> <attribute label="Code Offer" name="codeOffer" type="string"/> </element></srcSchema>

Apply the following steps:

1 Create an extension of the nms:seedMember schema. For more on this, refer to Extending a schema [page 65].

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



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

name="custom_customNamespace_customSchema"

This element must contain the fields required to export the campaigns. These fields should have the same nameas the corresponding fields in the external schema. For example, if the schema is cus:person, thenms:seedMember schema should be extended as follows:

<srcSchema extendedSchema="nms:seedMember" label="Seed addresses" labelSingular="Seed address" name="seedMember" namespace="cus"> <element name="common"> <element name="custom_cus_person"> <attribute name="lastname" template="cus:person:person/@lastname"/> <attribute name="firstname" template="cus:person:person/@firstname"/> <attribute name="email" sqlname="myEmailField" template="cus:person:person/address/@addrEnv" xml="false"/> </element> </element> <element name="seedMember"> <element aggregate="cus:seedMember:common"/> </element></srcSchema>

Note:

The extension of the nms:seedMember schema must comply with the structures of a campaign and a deliveryin Adobe Campaign.

Warning:

n During the extension, you must specify an SQL name (@sqlname) for the 'email' field. The SQL name mustdiffer from the 'sEmail' that is reserved for the recipient schema.

n You must update the database structure with the schema created when extending nms:seedMember.

n In the nms:seedMember extension, the field containing the email address must have name="email" as anattribute. The SQL name must be different from 'sEmail' which is already used for the recipient schema. Thisattribute must be immediately declared under the <element name="custom_cus_person"> element.

3 Modify the seedMember form accordingly to define a new "Internal recipient" tab in the Seed addresses window.For more on this, refer to Form structure [page 81].

<container colcount="2" label="Internal recipient" name="internal" xpath="custom_cus_person"> <input colspan="2" editable="true" nolabel="true" type="treeEdit"> <container label="Recipient (cus:person)"> <input xpath="@last name"/> <input xpath="@first name"/> <input xpath="@email"/> </container> </input> </container>

If all attributes of the seed address aren't entered, Adobe Campaign automatically substitutes the profiles: they willbe entered automatically during personalization using data from an existing profile.

Creating filters

Just like the out-of-the-box recipient table provided with Adobe Campaign, the new recipient table may receive abatch of predefined filters.

These filters will be available in the target selection window with the same functionalities as segments for recipients(using parameter input forms, folders, etc.).

1 Go to the Administration>Configuration>Predefined filters node.

140

2 Create a new filter.

3 Enter the Label of the filter, then select the schema which matches the external recipient table in the Documenttype field.

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

5 Save the filter.

Creating lists

Note:

This use case can also be found in the form of a video. For more on this, refer to the Creating a list of recipients video.

To create a list based on the new recipient table, you need to create a targeting workflow which will generate thelist.

1 Go to the Profiles and Targets >Jobs>Targeting workflows node of the explorer.

2 Create a new targeting workflow.

3 Place a Query activity followed by a List update activity.



https://docs.campaign.adobe.com/doc/AC6.1/en/Videos/Videos.html

4 Double-click the Query activity, then click Edit the query to choose a targeting dimension based on the schemaof the new recipient table (in our example: Individual).

5 Approve this configuration.

6 Double-click the List update activity, then select the Created if necessary (Calculated name) radio button.

7 Select the creation folder for the new list.

8 Execute the workflow to create the list.

9 View the result in the node of the tree which you selected during the List update activity.

142

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

Managing workflows

By default, your new workflows are based on a workflow template that is been pre-configured and based on arecipient table (nms:recipient). In order for them to be automatically based on the custom table of recipients referencedin the Nms_DefaultRcpSchema option (see Configuring the interface [page 137] section), you must create a newworkflow template.

Create a new template via the Resources > Templates > Workflow templates node. In the template's properties,the dimensions provided match your external recipients table.

By basing your new workflows on a recently created template, your personalized table will be selected by defaultfor the workflow's global targeting and filtering dimensions.

All the activities used in your workflow will thus use your custom table without needing any additional manualconfiguration.



For more information on workflows, refer to the Workflows guide.

Managing reports

Reports based on a schema that is specific to the default Adobe Campaign recipients (nm:recipient or schema linked)must be re-developed in order to take into account the data from the custom table and its tables linked via the targetmapping (see the Target mapping [page 134] section).

To create new reports, refer to the Reporting guide.

In some cases, you must also put new cubes that are specific to these tables into place. Cubes are detailed in theReporting guide.

The following reports are concerned:

n Recent proposition tracking (recentPropositions): real-time proposition tracking.

n Breakdown of opens (opensByUserAgent): opens broken down according to user software.

n Statistics of the sharing activities (forwardActivities): analysis of sharing activities, opens and subscriptions pertime period.

n Tracking indicators (mobileAppDeliveryFeedback): tracking indicators for a delivery on a mobile application.

n Offer analysis (offerAnalysis): offer analysis per date and channel.

n Reactivity rate (mobileAppDistribution): reactivity rate for the latest deliveries.

n Breakdown of subscriptions (mobileAppDistribution): breakdown of active subscriptions per mobile application.

144

workflow-v6.1-en.pdf#nameddest=ACY-7262

reporting#ACY-49791

reporting#CST-52743

Table of ContentsOverview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145Web tracking mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146Web tracking tag: definition . . . . . . . . . . . . . . . . . . . . . . . . . . 148

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

Setup stages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149Additional parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150

Definition of parameters . . . . . . . . . . . . . . . . . . . . . . . . . . 150Redirection server configuration . . . . . . . . . . . . . . . . . . . . . . . . 150

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

Inserting tags in your site . . . . . . . . . . . . . . . . . . . . . . . . . . . 153Simple method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153Optimum method . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154

Collecting all visits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156Server configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156Configuring a default matching campaign . . . . . . . . . . . . . . . . . . . . . 156

Anonymous tracking . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156

In addition to standard tracking that shows the behavior of an internet user clicking on a link in an e-mail message,the Adobe Campaign platform lets you collect information on how internet users browse your website. This datacollection 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 depositsa session cookie containing the broadlog identifier (broadlogId) and the delivery identifier (deliveryId).

The web client then sends this cookie to the server each time the user visits a page containing a web tracking tag.This continues throughout the session, i.e. until the web client is closed.

The redirection server collects the following data in this way:

n URL of the page viewed, via an identifier sent as a parameter,

n the delivery from which the web page was visited, via the session cookie,

n identifier of the internet user who clicked, via the session cookie,

n additional information such as the business volume generated.


CHAPTER 7

Setting up web tracking

The following diagram shows the stages of the dialog between the client and the various servers.

Figure 7.1. Client/web server/redirection server exchanges

Web tracking mode

Adobe Campaign lets you select a web tracking mode which defines the way in which tracking logs are processedin the application.

There are three available Web tracking modes: "Session tracking", "Permanent tracking" and "Anonymoustracking".

146

Each mode has specific characteristics. The "permanent" Web tracking mode includes the characteristics of the"session" Web tracking mode, while the "anonymous" mode includes the characteristics of the "permanent" and"session" modes.

Important:

The "anonymous" Web tracking mode is enabled by default if the "Leads" package is enabled. In all other cases, the"session" Web tracking mode is enabled by default.

At any time, the default mode can be changed in the instance deployment wizard.

Warning:

If you are using the permanent web or anonymous tracking mode, you must add an index to the "sourceID" column(uuid230) in the tracking tables (trackingLogXXX):

1 Identify the tracking table(s) concerned by permanent tracking.

2 Extend the schemas that match these tables by adding the following lines:

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

Permanent and Anonymous Web tracking modes include two options: Forced delivery and Last delivery.

The Forced delivery option enables you to specify the identifier of the delivery (@jobid) during tracking.

The Last delivery option lets you link the current tracking log to the last tracked delivery.

Characteristics of session Web tracking:

This mode creates a tracking log for people with a session cookie. These are people who clicked a URL in an emailsent by Adobe Campaign, thus enabling us to track the following information:

n Delivery ID

n Contact ID

n delivery log

n permanent cookie (uuid230)

n Tracking URL

n date of the tracking log

With this Web tracking mode, if part of the information is missing, no tracking log will be created in the application.

This mode is economical in terms of volume (limited number of records in the trackingLog table) and calculation(no reconciliation).

Characteristics of the permanent Web tracking mode:

This Web tracking mode lets you create a tracking log based on the presence of the permanent uuid230 cookie. Ifa visitor closes their session, Adobe Campaign uses the permanent cookie to recover information on them fromprevious tracking logs. Adobe Campaign re-inserts a tracking log if the uuid230 of the current session has the samevalue as a uuid230 already stored in the tracking table.

This means that the visitor needs to have been previously identified in Adobe Campaign (via a delivery) to enablereconciliation on uuid230 values.

By default, searches in previous tracking logs are performed in the "trackingLog" table. If the Leads package is enabled,before searching the "trackingLog" table, Adobe Campaign will search the "incomingLead" table for previous trackinglog records.

This mode is costly in terms of calculation during log reconciliation.

Characteristics of the anonymous Web tracking mode:

This Web tracking mode lets you retrieve a tracking log linked to anonymous browsing in Adobe Campaign. Atracking log is created automatically for each click on a tracked URL. This log only has the value of the uuid230.



During a marketing campaign, a tracking log is created automatically with all identification information (refer tosession tracking). Adobe Campaign will automatically search previous logs for a "uuid230" value equal to the valuefrom the tracking log for this marketing campaign. If identical values are found, all previous tracking logs are enteredwith all the information from the marketing campaign tracking log.

This mode is the most costly in terms of calculation and volume.

Note:

If the Leads package is installed, you need to do the same for the activity table (crm:incomingLead)

The following schema sums up the functionalities of all three Web tracking modes:

Example of Permanent web tracking based on the last delivery:

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

Web tracking tag: definition

A web tracking tag is simply a URL constructed with the appropriate parameters, sent to the redirection server viaan HTTP query.

148

Format of the data to be sentThe format of a web-tracking URL is as follows:http://<name_of_redirection_server:<port/r/<random_number?<parameters

Note:

The random number added to the URL avoids problems caused by browsers caching web pages.

The following table gives a list of special parameters supported by the redirection server.

DescriptionTypeName

Delivery identifier and recipient identifier.Session cookieID

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

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

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

URL parameterjobid

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 paramet-er takes priority over the identifier contained in the session cookie.

URL parameterrcpid

A few web tracking URLs

n Visit to a 'home' identifier page

http://myserver.adobe.com/r/9862?tagid=home

n Collecting business volume data

http://myserver.adobe.com/r/4567?tagid=command&amount=100&article=2l

n Specifying a field to find the recipient

http://myserver.adobe.com/r/2353?tagid=home&rcpid=saccount%3D10

A recipient whose account number is 10 is sent to the home page.

n Using a default delivery

http://myserver.adobe.com/r/2456?tagid=home&jobid=e6

A recipient is sent to the home page. This information will be stored in the delivery with identifier 230 (e6 indatabase 16) unless a session cookie containing a delivery identifier is sent with this query.

Note:

All values sent to the redirection server via URL parameters must be URL encoded. In the examples given, note thatthe characters '=' and '|' are encoded as '%3D' and '%7C' respectively.

Data transmission methodsThe following methods are possible:

n Inserting the URL in the "src" attribute of an HTML <img> tag incorporated in the web page you wish to track.

n Direct call to the redirection server when the web page you wish to track is generated.

Setup stages

The basic principle is the insertion of web tracking tags in certain pages of your website.

There are two types of tags:

n WEB: this tag tells you if the page has been visited,

n TRANSACTION: operates like a Web tag, but with the possibility of adding information on the business volumegenerated, 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 withthe description of this information. By default, this schema can store the transaction amounts and number ofitems 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 Adobe Campaign platform, then generate and extractthe associated web-tracking tags (from the Campaign execution>Resources>Web tracking tags node ofthe client console).

n Create the web-tracking tags yourself in "on-the-fly creation" mode: the URLs corresponding to these pageswill be automatically inserted in your Adobe Campaign 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 oradded dynamically in order to contain the additional information (amount, items, etc.).

Example:

<script type="text/javascript">var _f = "nmsWebTracking"var _t = window.location.href.match(/.*:\/\/[^\/]*(\/[^\?\#\&]*)/)[1] + "|w|" + _fdocument.write("<img height='0' width='0' alt='' src='" +window.location.protocol + "//tsupport/r/" +Math.random().toString() + "?tagid=" + escape(_t) + "'/>")</script>

Additional parameters

Definition of parametersYour Adobe Campaign platform offers two TRANSACTION-type web-tracking parameters as a standard:

n amount: represents the amount of a transaction,

n article: represents the number of items in a transaction.

These parameters are defined in the nms:webTrackingLog schema, and are some of the indicators seen in reporting.

To define additional parameters, you must extend this schema.

Example:

<srcSchema extendedSchema="nms:webTrackingLog" label="Web Tracking" mappingType="sql" name="webTrackingLog" namespace="cus" xtkschema="xtk:srcSchema">

<element name="webTrackingLog"> <attribute desc="Payment method" label="Payment method" length="10" name="mode" type="string"/> <attribute desc="Offer code" label="Offer code" length="5" name="code" type="string"/>

</element></srcSchema>

You can display the values of these parameters by configuring the tracking log list (of a delivery or recipient).

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

150

Warning:

Increasing the maximum number of characters to be taken into account can impact the web tracking performanceof your platform.

To do this, modify the webTrackingParamSize attribute of the <trackinglogd> element in the serverConf.xmlfile. This file is saved in the conf subdirectory of the Adobe Campaign installation directory.

Example:

The default value is 64 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 schemaexample, you can modify the configuration to take 100 characters into account("amount=xxxxxxxx&article=xxxxxxxx&mode=xxxxxxxxxx&code=xxxxx").

<trackinglogd args="" autoStart="false" initScript="" maxCreateFileRetry="5" maxLogsSizeOnDiskMb="500"maxProcessMemoryAlertMb="1800" maxProcessMemoryWarningMb="1600" maxSharedLogs="25000"processRestartTime="06:00:00" purgeLogsPeriod="50000" runLevel="10"webTrackingParamSize="64"/>

When the configuration has been modified, you must:

n Stop the web server that hosts the redirection module (Apache, IIS, etc.),

n Stop the Adobe Campaign server: net stop nlserver6 in Windows, /etc/init.d/nlserver6 stopin Linux,

n In Linux, delete the shared memory segments using the ipcrm command,

n Restart the Adobe Campaign server: net start nlserver6 in Windows, /etc/init.d/nlserver6start in Linux,

n Restart the web server.

Example: taking into account the configuration under Linux.

adobe@selma:~$ /etc/init.d/nlserver6 stopadobe@selma:~$ /etc/init.d/apache stopadobe@selma:~$ ipcs shm

------ Shared Memory Segments --------key shmid owner perms bytes nattch status 0x52020679 2097153 adobe 666 93608 8

------ Semaphore Arrays --------key semid owner perms nsems 0x52020678 4227081 adobe 666 1

------ Message Queues --------key msqid owner perms used-bytes messages

adobe@selma:~$ ipcrm shm 2097153 1 resource(s) deletedadobe@selma:~$ /etc/init.d/nlserver6 startadobe@selma:~$ /etc/init.d/apache start

Note:

For Linux, if you increase the size of the webTrackingParamSize or maxSharedLogs parameters, you may need toincrease the size of the shared memory (SHM).

Creating web tracking tags

Each page of the site that you wish to track must be referenced in your Adobe Campaign platform. This referencingcan be performed in two ways:

1 Manual definition of URLs to be tracked,



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

Defining the URLs to be tracked in the applicationThis method lets you manually define the pages to be tracked and then generate an example of the associated webtracking tag. This operation is defined in the Campaign execution>Resources>Web tracking tags node of the clientconsole.

To generate the HTML code to be inserted in the page:

n Enter the label of the tag: it will be shown in the tracking logs,

n Indicate the source URL: this field is for information purposes and lets you indicate the tracked page (optional),

n If needed, enter a validity period,

n Click Generate HTML code.

Then copy the generated code and paste it into the page to be tracked.

On-the-fly creation of URLs to be trackedYou can create the web tracking URLs on the fly by adding information to the value of the tagid parameter:

n Type of page tracked: 'w' for WEB or 't' for TRANSACTION,

n The internal name of the folder where the URL must be created.

These two pieces of information must be concatenated with the identifier of the tracked page by adding the character'|':

tagid=<identifier>|<type>|<foldername>

Warning:

Remember to encode the value of the tagid parameter when it is used as a URL parameter.

Example: creation of a transaction-type web tracking URL.

http://myserver.adobe.com/r/a?tagid=home%7Ct%7CMyFolder

152

Inserting tags in your site

Simple methodThis method consists of sending an HTTP call to the redirection server by inserting an <IMG>HTML tag in the HTMLsource code of the web page you wish to track.

Warning:

This method uses the cookies sent by the web browser to identify the recipient, and is not 100% reliable.

Example:

<img height='0' width='0' alt='' src='http://localhost/r/12343?tagid=home'

The inserted tag contacts the redirection server.

Figure 7.2. Client/redirection server/web server exchanges

When you define a page to be tracked in the console, you can generate a sample web tracking tag to copy and pasteinto 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 insertthe transaction information (amount, number of items) and any information defined by an extension schema.

Static insertion of tags

To perform static tag insertion, simply copy and paste the tags generated by the console or constructed manuallyinto the source of your web page.

Example: insertion of a web tracking tag on a page displaying a form.

<html> <...> <body> <script> document.write("<img height='0' width='0' alt='' src='http://localhost/r/" + Math.random().toString() + "?tagid=home'>"); </script> <noscript> <img height='0' width='0' alt='' src='http://localhost/r/?tagid=home'> </noscript> <h1>My site</h1> <form action="http://localhost/amount.html"> Quantity: <input type="text" name="quantity"/><br/><br/> Amount: <input type="text" name="amount"/><br/><br/> <input value="Save" type="submit"> </form> </body></html>

Insertion of a TRANSACTION-type web tracking tag in the confirmation page ("amount.html").

<html><body><script>



function getURLparam(name) {

var m = location.search.match new RegExp("[?&]" + name + "=([^&]+)"));return m ? unescape(m[1]) : "";

}

var params = "http://localhost/r/" + Math.random().toString() + "?tagid=amount&amount="

+getURLparam("amount")+"&article="+getURLparam("quantity");document.write("<img height='0' width='0' src='"+params+"'/>");

</script>

<h1>Approval confirmation</h1></body>

</html>

Dynamic generation of web tracking tags

When your web pages are generated dynamically, you can add the web tracking tag at page generation time.

Example: Web tracking added to JSPs.

<%@page import="java.util.Random" %><html> <body> <img height='0' width='0' alt='' src='http://localhost/r/<%=new Random().nextInt()%>?tagid=home'> <h1>My site</h1> <form action="http://localhost/amount.html"> Quantity: <input type="text" name="quantity"/><br/><br/> Amount: <input type="text" name="amount"/><br/><br/> <input value="Save" type="submit"> </form> </body></html>

<%@page import="java.util.Random" %><html> <body> <% String strParams = new Random().nextInt() + "?tagid=amount"; strParams += "&amount="+request.getParameter("amount"); strParams += "&article="+request.getParameter("quantity"); %> <img height='0' width='0' alt='' src='http://localhost/r/<%=strParams%>'> <h1>Approval confirmation</h1> </body></html>

Optimum methodIf you wish to control the information sent to the redirection server, the most reliable way is to perform the HTTPquery synchronously yourself using a page generating language.

154

The URL you construct must obey the syntax rules defined in Web tracking tag: definition [page 148].

Figure 7.3. Client/redirection server/web server exchanges

Note:

Redirection and web tracking use cookies, and it is important that the web server performing the synchronous HTTPcall be in the same domain as the redirection server. The various HTTP exchanges must convey the 'id', 'uuid', and'uuid230' cookies.

Example: Dynamic generation in Java, with recipient authentication using their account number.

[...]// Recipient account, amount and articlesString strAccount = request.getParameter("account");String strAmount = request.getParameter("amount");String strArticle = request.getParameter("article");

StringBuffer strCookies = new StringBuffer();String strSetCookie = null;

// Get cookies from client requestCookie[] cookies = request.getCookies();for(int i=0; i< cookies.length; i++ ){Cookie c = cookies[i];String strName = c.getName();if( strName.equals("id") || strName.equals("uuid") || strName.equals("uuid230") )// Helper function to add cookies in stringAddCookie(strCookies, c);

}// Now perform a synchronous HTTP request to inform redirection server// Add a tagid in auto-discover mode, and a default jobId to use (in hexa)StringBuffer strURL = new

StringBuffer("http://www.adobe.com/r/a?tagid=cmd_page%7Ct&jobid=27EE");if( strAccount != null )AddParameter(strURL, "rcpid", "saccount="+strAccount);

if( strAmount != null )AddParameter(strURL, "amount", strAmount);

if( strArticle != null )AddParameter(strURL, "article", strArticle);

URL url = new URL(strURL.toString());HttpURLConnection connection = (HttpURLConnection)url.openConnection();// Add the client cookies



if( strCookies.length() > 0 )connection.setRequestProperty("Cookie", strCookies.toString());

int errcode = connection.getResponseCode();

// Now add the Adobe Campaign cookies if the server returned one :if( errcode == 200 ){strSetCookie = connection.getHeaderField("Set-Cookie");if( strSetCookie != null && strSetCookie.length() > 0 )response.addHeader("Set-Cookie", strSetCookie);

}[...]

Collecting all visits

The web tracking module supplied by Adobe Campaign lets you collect the visits to certain pages of the site performedby a recipient in the context of site tracking following a click in a message.

You can, however, configure your platform so that it collects all visits to pages with a web tracking tag by a userknown to the platform.

A user known to the platform is a recipient who has already been targeted by a delivery and who has clicked in areceived message at least once. A permanent cookie is used to identify this recipient.

Warning:

The Adobe Campaign platform is not intended for use as a website tracking tool beyond the context of visiting thesite following a click in a message. When this option is enabled, it can cause very high use of resources on themachines hosting your servers (redirection, application, and database). You are advised to ensure that your hardwarearchitecture can support this load, and to avoid placing web tracking tags in the most frequently visited pages, suchas the home page.

Server configurationThe servers are configured by overloading certain elements of the serverConf.xml file. These files are saved in theconf subdirectory of the Adobe Campaign installation directory.

Redirection server

For the redirection server, set the trackWebVisitors attribute of the redirection element to true.

<redirection P3PCompactPolicy="CAO DSP COR CURa DEVa TAIa OUR BUS IND UNI COM NAV"databaseId="" defLogCount="30" expirationURL="" maxJobsInCache="100"startRedirection="true" startRedirectionInModule="true" trackWebVisitors="true"trackingPassword=""

Configuring a default matching campaignTo view tracking information via your client console, you must:

n Create a dummy delivery (the delivery mapping must be identical to the mapping of the target schema),

n Enter the internal name of this delivery in the NmsTracking_WebTrackingDelivery option.

All site tracking information not directly subsequent to a click in an e-mail can be viewed in the dummy deliverycreated.

Anonymous tracking

Adobe Campaign lets you link collected Web tracking information to a recipient when they browse your siteanonymously. When a user browses the tagged pages of your website this browsing information is collected, so thatonce they click in an email sent by Adobe Campaign, they are identified and the information is automatically linkedto them.

156

Warning:

Setting up anonymous tracking on a website can trigger the collection of a significant amount of tracking logs, therebyimpacting database operation. Configure it with care.

Tracking logs are saved in the database until the tracking data is purged. Use the deployment wizard to configurethe 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 trackingserver must be set to 'true', to place a permanent cookie (uuid230) in the browsers of unknown internet userswho visit the site.

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



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

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

158

Documents

Adobe Campaign v6.1 - Configuration Guide Campaign v6.1 - Configuration Guide | 9 ... The name of the element should be concise, preferably in English, and include only authorized