Overview
A location is a central entity of CampaignDrive, and to create any content one or more locations must be present. This document describes the format in which clients can export location data from their system and import it into CampaignDrive. The Location Import Service is responsible for importing this data.
Who Should Read This Document?
This document is primarily directed at the development IT team or the implementation specialist who would format the XML file needed by the service. Marketing personnel and project sponsors would also gain insight from reading this document; however, some of the information is of a technical nature and requires expert knowledge.
Who Should Use the Location Import Service
The service should be used by clients who need to export location data from their systems and import it into CampaignDrive. Once the locations have been imported to CampaignDrive they are available to be used. For example, users can be associated with them, and access to creative material may be driven by them.
Features
- Automatically create new locations
- Automatically and selectively update locations when their data changes (See 'Other' section)
- Simple XML structure enables quick export locations data
- Automatically import in predefined intervals
Implementation Requirements
In order to use the Location Import Service, clients must
- Be able to export the location 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
- Manually add all Brands, Regions, and Additional Attributes to CampaignDrive prior to import
- Services can be created and updated on the fly. Location Groups can be created on the fly.
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 purpose, some elements (and attributes) may be omitted.
General Structure:
<?xml version='1.0' encoding='utf-8'?>
<Locations version='1.0' timestamp="2017-10-05T13:14:57+00:00">
<Location>
<UniqueIdentifier>XX98-FA-US</UniqueIdentifier>
<Name>Unity Mall</Name>
<AddressLine1>1 Main street</AddressLine1>
<AddressLine2 />
<City>Los Angeles</City>
<State>1 Main street</State>
<PostalCode>10010</PostalCode>
<Region>Global</Region>
<Country>United States</Country>
<Phone>212.665.8888</Phone>
<Fax>212.888.9999</Fax>
<!-- See Location Association below -->
</Location>
<Location>
</Locations>
The following table explains the above elements.
Name |
Description |
Required |
|
Locations |
Container for all locations Type: Container Attributes: version - 1.0. The attribute is required. timestamp - The date and time on which the XML was generated. The attribute is optional. |
Yes |
|
Location |
A location Type: Container |
Yes |
|
UniqueIdentifier |
A unique string that is associated with a single location. The identifier makes it possible to address the location record and create or update it. Type: String |
Yes |
|
Name |
The name of the location Type: String |
Yes |
|
AddressLine1 |
An address Type: String |
Yes |
|
AddressLine2 |
An address Type: String |
No |
|
City |
A city Type: String |
Yes |
|
State |
A state Type: String |
Yes |
|
PostalCode |
A Postal Code Type: String |
Yes |
|
Country |
A country Type: String |
Yes |
|
Phone |
A phone number Type: String |
No |
|
Fax |
A fax number Type: String |
No |
Location Association:
In addition to the above location elements, locations can also be associated with other entities of CampaignDrive. This section describes these associations. Note, these associations are additive. The service does not remove the associations.
Region
A region defined in CampaignDrive. Prior to import, the region must exist in CampaignDrive.
<Location>
<RegionIdentifier>NorthWest</RegionIdentifier>
<Location>
|
Name |
Description |
Required |
|
RegionIdentifier |
A region defined in CampaignDrive. All locations must be associated with exactly one region. If the element is not passed the location will be associated with the ‘Global’ region (which is the default). The region must exist in CampaignDrive prior to import. Type: String |
No |
Brands
The brand or brands that are associated with the location. At least one brand must be associated with a location.
<Location>
<BrandIdentifiers>
<UniqueIdentifier>MyBrand</UniqueIdentifier>
</BrandIdentifiers>
<Location>
|
Name |
Description |
Required |
|
BrandIdentifiers |
Container of brand identifiers. Each location can be associated with one or more brands. If the system has only one brand, this element can be omitted. (The location will be associated to the client’s brand by default.) Type: Container |
No |
|
UniqueIdentifier |
An identifier of the brand. The brand must be predefined in CampaignDrive. Type: String |
Yes - if the BrandIdentifiers element is used
|
Note: Brands must be created in CampaignDrive prior to import. Unique Identifier for the brand(s) are supplied by Pica9.
Additional Attributes
Locations may have additional attributes. These attributes add more information about a location and can be used in templates (for example, an ‘Operating Hours’ attribute). Additional attributes must be created in CampaignDrive before adding additional attributes in the feed. (Creating the additional attributes in CD is done by a Pica9 representative).
<Location>
<AdditionalAttributes>
<OpenAt>9.00</OpenAt>
<CloseAt>20.30</CloseAt>
</AdditionalAttributes>
<Location>
|
Name |
Description |
Required |
|
AdditionalAttributes |
Container for additional attributes elements Type: Container |
No |
|
AdditionalAttributeName |
One or more additional attributes. These can hold any additional data for the location. The list of additional attributes will need to be agreed upon with Pica9 IT team prior to the import. Type: String |
Yes - if the AdditionalAttributes element is used
|
Services
The service or services that are associated with a location.
Any non-existent service by the identifier will be created.
Any service with an existing identifier will be updated with the latest name.
<Location>
<Services>
<Service>
<UniqueIdentifier>Ice-srvs</UniqueIdentifier>
<Name>Ice</Name>
</Service>
</Services>
<Location>
|
Name |
Description |
Required |
|
Services |
Container for services. Type: Container |
No |
|
Service |
A particular service to associate with the locations. Type: String |
Yes |
|
UniqueIdentifier |
A unique string that is associated with a single service. The identifier makes it possible to address the service record. Type: String |
Yes |
|
Name |
The name of the service. Type: String |
Yes |
Location Groups
The group or groups that are associated with a location. (Location groups that are not in CampaignDrive will be created; but not updated.)
<Location>
<LocationGroups>
<Group>
<UniqueIdentifier>XX-OO-HH</UniqueIdentifier>
<Name>Support</Name>
</Group>
</LocationGroups>
<Location>
|
Name |
Description |
Required |
|
LocationGroups |
Container for groups. Type: Container |
No |
|
Group |
A particular group to associate with the locations. Type: String |
Yes |
|
UniqueIdentifier |
A unique string that is associated with a single group. The identifier makes it possible to address the group record. Type: String |
Yes |
|
Name |
The name of the group. Type: String |
Yes |
Notes
- The service overwrites any updates to a location/s that are made directly in the user interface (Admin area) in CampaignDrive.
For location updates (vs newly created location)
- The service can be configured to not update a particular location field(s). For example, turning off updating 'Region' field for all locations.
- The service can be configured to not update services association.
- The service does not transform the values for text fields and imports text as is. For example, if text is all caps in the feed, it will be imported in all caps.
- Client should validate their exported XML against the standard Location Import Service XSD (the location XSD document).
- Support file compression. Since the XML location file can get very large, we support passing a compressed XML file created by the gzip utility program (gz compression).
Data Flow Diagram
