CampaignDrive Help Center

Getting Started

Automate the Import of Data Sets/Content into Your CampaignDrive Content Database

This document explains the technical process of using Pica9's Content Importer to automatically create data items in your Content Database.

Overview

Dynamic content is a central concept in CampaignDrive that allows for the customization of documents and other creative artifacts. This document describes the format which enables clients to export data from their system into CampaignDrive’s ‘Content Database’. The Content Importer in CampaignDrive is responsible for importing this data.

Who Should Read This Document?

This document is primary directed at the development IT team or the implementation specialist who would format the XML file needed by the importer. Marketing personnel and project sponsors would also gain insight from reading this document; however some of the information is of technical nature and requires expert knowledge.

Who Should Use the Content Importer

The importer should be used by clients who need to export data from their systems into CampaignDrive. The data will be imported into one or more categories and will be stored in the Content Database. Once the data is in the Content Database it is available to use in creative material. (Categories are defined in CampaignDrive itself and the exact mechanism of defining them is outside the scope of this document. see 'Categories, Fields and Content Items' section below. )

Features

Automatically create new items that did not previously exist in the Content Database
Automatically update items when their data is changed
The client maintains full control of the data
Simple XML structure enables the quick export of content data
Ability to delete items (either explicitly or implicitly)
Automatically import content in predefined intervals

Implementation Requirements

In order to use the Content Importer, clients must

Be able to export the items data as an XML file (See description of the schema)
Post the XML file to an endpoint that can be retrieved programmatically. E.g. S/FTP, AWS S3, HTTP/S
If image data is to be imported, endpoints for images must be provided. Only SFTP and publicly accessible http/s protocols are supported.
All Categories with their respective Fields must already be defined in the Content Database prior to import.

Categories, Fields, and Content Items

One way of organizing content in CampaignDrive is by defining categories.

A category is simply a schema that describes the organization of data as a blueprint. A category is composed of one or more fields.
After a category is defined, items can be created in the category. An item represents a single, implicitly structured data element of the category. (In analogy to the relational database model: A category is similar to a ‘table’ and fields are the column names of the table. An item is akin to a `row` (‘tuple’). )
Items of a category are stored in the Content Database in CampaignDrive. The data in these items enable users to customize documents.

XML Schema Definition

This section describes the structural elements of the XML. The section describes all possible elements that can be passed. However, depending on the feed’s purpose, some elements (and attributes) may be omitted.

General Structure:

<?xml version='1.0' encoding='utf-8'?>

<name>Holiday Offers</name>

<items>

</items>

</categories>

Name	Description	Required
categories	Container for all categories Type: Container Attributes: version - 1.0 The attribute is required. timestamp - The date and time which the XML was generated. The attribute is optional.	Yes
category	A category Type: Container	Yes
name	The name of the category for which items are to be imported. Must match name (case sensitive) of category defined in CampaignDrive. Type: String	Yes
items	Container for all items Type: Container	Yes

Items:

<items>

<name>Thanksgiving Discount</name>

<location_identifiers>

</location_identifiers>

<location_group_identifiers>

</location_group_identifiers>

</fields>

</item>

<items>

Name	Description	Required
item	Container that holds item information. Type: Container Attributes: id - uniquely identify an item across all items in the category. The attribute is required. deleted - marks an item for deletion. This is a boolean type: “true” or “false”. The attribute is optional and the default value is “false”	Yes
name	A name for the item. This name will be used by CampaignDrive front-end users. Type: String	Yes
location_identifiers	Container that holds location identifiers. If location identifiers are passed, the item will be associated with these locations. Locations with these identifiers must exist in CampaignDrive prior to the import. Type: Container	No
location_group_identifiers	Container that holds location group identifiers. If location group identifiers are passed, the item will be associated with these location groups. Locations group identifiers must exist in CampaignDrive prior to the import. Type: Container	No
identifier	A string that identifies a location or location group. Type: String	Yes - if an item is associated with a location or location group

Fields:

The Content Importer supports importing 4 types of fields: “text”, “image”, "textArray", and "imageArray".

<name>Legal Information</name>

<value>Offer Valid until January 1, 2017.</value>

</field>

<name>Hero Image</name>

<value>https://sandbox.pica9.com/out/1340296.png</value>

</field>

<name>List Price</name>

</field>

<name>Listing Photo</name>

<value fingerprint="jf0ttn7wqaw0myygy6vxee2wy5i">https://sandbox.assetlocker.pica9.com/asset_locker/asset_pops/1515919.jpg</value>

<value fingerprint="b1er7k15zsjkm8e9135w0jhys6i">https://sandbox.assetlocker.pica9.com/asset_locker/asset_pops/1515918.jpg</value>

</field>

</fields>

Text Field

Name	Description	Required
field	Container that holds information about a field. See below for the field’s attributes Type: Container	Yes
name	The name of the field. The name must match the name of the field that was defined for the category in CampaignDrive. Type: String Type Constraints: '^[a-zA-Z0-9_]+(\s[a-zA-Z0-9_-]+)$' Type Reserved: _identifier name is reserved and should NOT be used.	Yes
value	The value of a field Type: String	Yes

TextArray Field

Name	Description	Required
field	See Text Field	See Text Field
name	See Text Field	See Text Field
value	Each value tag's value will be imported and presented as a Text (multiple) field option. When no value tag is present, the Text (multiple) field will have no options. Type: String	No

Image Field

Name	Description	Required
field	Container that holds information about a field. Type: Container Attributes: update - Whether an update of the image field should be done (for example, if the image has not changed since the last run, setting update=”false” would save on the import time) When update="true" the importer will check first if the asset exists (was prev' imported), and if it does, then it will update the value; if the assest does not exist it will be imported and associated to the item. Type: boolean. Value: “true” \| “false” Default Value: “true” The attribute is optional. fingerprint - A unique string that identifies a specific version of the image. If the Importer finds an image with that fingerprint in CampaignDrive, the image would not be uploaded again. Clients should always use the fingerprint attribute as it enables clients to keep the image URL while changing the content of the image. In addition, it enables the client to change the download URL. Note: If the fingerprint attribute is not provided, the field's value would be hashed and used as a 'fingerprint' for this asset. Type: String Type Constraints: '[a-zA-Z0-9]{3,}' The attribute is optional.	Yes
name	The name of the field. The name must match the name of the field that was defined for the category in CampaignDrive. Type: String	Yes
value	The value of a field Type: URL (sftp; http; https protocols are supported)	Yes

ImageArray Field

Name	Description	Required
field	See Image Field	See Image Field
name	See Image Field	See Image Field
value	Each image URL within a value tag will be downloaded, uploaded to media library and associated with the Image (multiple) field. When no value tag is present, the Image (multiple) field will have no image associated with it. Type: URL (sftp; http; https protocols are supported) Attributes: fingerprint - See Image Field field attribute fingerprint	No

Other

The Content Importer only supports importing one category per XML file. If multiple categories need to be imported, each category will be in its own file.
An item can be updated with a partial field list. I.e. not all fields need to be present when updating an item (only presented fields will be updated).
The Importer does not transform the values for text fields, and imports data as is. For example, if a field value is in all caps in the feed, it will be in all caps in the document in which it is used.
The client should validate their exported XML against the standard Content Import XSD (https://github.com/Pica9/content-importer/blob/master/content.xsd).
Support file compression. Since XML content files can get very large, we support passing a compressed XML file created with gzip utility program (gz compression)
The image asset imported from the URL provided in the XML will be uploaded to the Media Library with the value of the item's name tag as the title value of the asset.
When importing an item, if importing image(s) fails for an item, the item would be skipped. That is it would not be imported or updated.