Adding/Importing Venues to DemonstratorGauge

Single Venue

Adding a new venue to DemonstratorGauge is simple. Please check first that the venue you want to add is not already on the list. Go to Settings > Add/modify Venues. Fill in details – make sure you add Postcode. Select a Retail Chain to aid reporting.

Importing

If you have a long list of venues to add (50+), we are able to “bulk upload” the data. Please ensure all fields are correctly filled in (postcode, retail chain, Venue Name). Please contact us so we can arrange it.

You can download the DemonstratorGauge Venue Import excel template: Examplevenues.

Note that you can get a list of venues using the API – demonstratorgauge-data-download

A note about adding venues

It’s important that the venue list is as clean as possible, with no duplicates to confuse demonstrators. Before adding a venue, please check whether is already stored. We can modify venues, and merge them, but we are not able to delete venues as they are used for multiple purposes.

API: DemonstratorGauge Data Download

API Documentation – DemonstatorGauge Data Download 4 December 2009 – v0.1

What this API does:

SUMMARY: The objective is to provide the correct ID numbers for Demonstrators, Products and Venues in the DemonstratorGauge field marketing system. Using an HTML request, a remote call can be made to the DemonstratorGauge database to retrieve a list of:

• Demonstrators
• Products
• Venues

It is designed to be used in conjunction with the API: DemonstratorGauge Event Upload

Detail:

A correctly formed HTTP request will deliver a file in CSV format of fields from the tables containing demonstrators, products and venues.

Restrictions:

• You are restricted to 100 API calls (total) per day.
• You can only retrieve Venue data for your specified Country
• You can only retrieve Person data for your specified Agency AND country
• You need a valid API key – please request one from API@directness.net

Using the API

To get a list of venues in your country:

http://www.d1-gauge.com/canon/API/GetInfo.php?key=xxxxxxxxx&type=Venue

To get a list of products:

http://www.d1-gauge.com/canon/API/GetInfo.php?key=xxxxxxxxx&type=Product
To get a list of persons/demonstrators for your Agency Name:
http://www.d1-gauge.com/canon/API/GetInfo.php?key=xxxxxxxxx&type=Person

NB Replace xxxxxxxx with your API key.

Example Output WIth Person List (restricted to Agency Name)

Example Output with Venue List (restricted to Country)

Example Output with Product List

Example with PHP

<?

// DemonstatorGauge Data Download 4 December 2009 - v0.1

url = "http://www.d1-gauge.com/canon/API/GetInfo.php?key=xxxxxxxxx&type=Product";

// replace xxxxxxxxx with your API key

// type=Product

// type=Venue

// type=Person

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, $url);

curl_setopt($ch, CURLOPT_BINARYTRANSFER, 1);

curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0);

curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0);

$result = curl_exec($ch);

curl_close($ch);

print $result;

?>

Validation

A CSV (Comma Separated Variable) file can be downloaded.

Error messages:

API Key expired - please ask for a new key
API key not valid - please request key with your API 
Support

Please send comments to API@directness.net

API: DemonstratorGauge Event Upload

API Documentation – DemonstatorGauge Event Upload 8 December 2009 – v0.2

What this API does:

SUMMARY: Using a cURL command in a PHP file hosted on your server, you can upload multiple event information into DemonstratorGauge from a prepared XML file also hosted on your server.

Detail:

In the file clientCanon.php a cURL command uploads the XML file eventsCanon.xml to the DemonstratorGauge server.

The XML file can contain multiple events. Each event contains information on user, event, date etc. Up to 4 photos can be added. Any number of products sold or featured can be added.

Note: You must be able to enter correct IDs for the following:

• Demonstrator
• Venue
• Product

These can be retrieved from DemonstratorGauge as a user or using the API DemonstratorGauge Data Download

At this stage we do not have an API to add users or venues. These must be done manually in the system. Canon maintain the list of products manually – requests for products to be added must go to Canon.

Using the API

To use the API, upload clientCanon.php and eventsCanon.xml to your server. You will need a valid key. Requirements: PHP 5.

Insert the required information in the XML file. Then run client.php to call and upload the XML file.

On a successful upload, the system will return “X records  uploaded”

Validation

Successful upload: Upon completion, the page will display two download links:

DGResultList.csv -- Displays the successfully uploaded records today
DGErrorList.csv -- Displays the error(s) that occurred.

Typical result:

Validation – contents of successful report:

Error messages:

error1: Key Invalid
error2: API key needs renewing - out of date - please contact API@directness.net to reset
error3: Duplicate record(s) detected
error4: Product ID(s) is unrecognizable
error5: Venue ID(s) is unrecognizable
error6: record(s) has  Invalid Event Date
error7: record(s) has invalid PersonID

Error Notes:

• error3: Duplicate record detected: If demonstratorID AND venueID AND eventDate match a previously uploaded event (for 1 event)
• error5: VenueID will be invalid if system can NOT find VenueID in the database, or system can find VenueID in the database but Venue address dows not belong to Agency’s country.
• error6: Invalid Event Date: Date of event is in the future  ( EventDate > today) or incorrectly formatted

Example of Error result:

XML and contents:

Event details

	Mandatory?
<EventActivity> </EventActivity>		Place all event details inside these tags. Allows you to upload multiple events at one time.
<DemonstratorID>	Yes	Integer: The ID of the Demonstrator e.g. ‘10112’ (Adam J Dorrell) Source: Person Table. Agents can add themselves.
<VenueID>	Yes	Integer: ID of venue. E.g. ‘8290’ (Dixons Travel Heathrow Terminal 5) Source: Venue Table. Agents can add Venues.
<VenueCountry>	Yes	Two letter code: eg ‘DE’, ‘UK’
<SingleProductGroup>	Yes	Focus of the event. Text. Choose ONE from Video Compact Cameras Compact Photo Printers Inkjet PrintersMF Inkjet PrintersSF Digital SLR Other Laser DesktopColourFlatbedScanner Video Inkjet Consumables Scanner Digital SLR
<EventDate>	Yes	Date of event in YYYY-MM-DD
<NumberOfHours>	No	Decimal: Number of hours spent on site. Eg ‘3.5’ (3 hours 30 minutes)
<NumberOfContacts>	No	Integer: Number of contacts made on site, eg ‘34’
<Comments>	No	Free text description of what happened on site. Example: ‘Super Promo. Super Angebote: Cashback und 500D für 899, mit 18-200mm für 1319.-‘ Limit 1024 characters
<Photo1URL>	No	URL. The system will retrieve the photo from a remote system. Example ‘http://images-1.redbubble.net/img/art/size:large/view:main/1072108-2-vermont-autumn.jpg’ Please no larger than 4Mb. We resize to 1600×1600 (max) so higher resolution not needed.
<Photo1Caption>	No	Text describing photo: Example ‘Canon Booklet Info Display’ Limit 255 characters
<Photo2URL> <Photo3URL> <Photo4URL>	No	As Photo1. You can add up to 4 photos.
<Photo2Caption> <Photo3Caption> <Photo4Caption>	No	As <Photo1Caption>. You can add up to 4 captions.
<UploadRef>	No	Text. You can add your own event reference. Eg “Agent444, Event56”. 40chars.

Product section – you can add up to 100 product items focused per event

	Mandatory?
<ProductDetails> </ProductDetails>		You can add Products focused in this section
<ProductID>	Yes	Integer. Unique iD of product. Eg ‘47’ (Selphy ES1). Source: Product Table. This table maintained by Canon.
<NumberOfSales>	Yes	Integer: Number of units sold of this product. Eg ‘23’
<FocusProduct>	No	String. Was this product “focused” on the day? Example ‘Yes’. Choose from ‘Yes’ or NULL

Data: XML formatting Example

<EventActivityArray>

<EventActivity   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<DemonstratorID   xsi:type="xsd:integer">9</DemonstratorID>
<VenueID   xsi:type="xsd:integer" >120</VenueID>
<EventDate   xsi:type="xsd:string" >2009-10-01</EventDate>

<EventDetails>

<NumberOfHours   xsi:type="xsd:decimal" >3.5</NumberOfHours>

<NumberOfContacts   xsi:type="xsd:integer" >5</NumberOfContacts>

<Comments   xsi:type="xsd:string" >The event was very busy</Comments>

<SingleProductGroup  xsi:type="xsd:string">Video</SingleProductGroup>

<Photo1URL xsi:type="xsd:string" >images/1072108-2-vermont-autumn.jpg</Photo1URL>

<Photo1Caption   xsi:type="xsd:string" >Autumn</Photo1Caption>

<Photo2URL   xsi:type="xsd:string" ></Photo2URL>

<Photo2Caption   xsi:type="xsd:string" ></Photo2Caption>

<Photo3URL   xsi:type="xsd:string" ></Photo3URL>

<Photo3Caption   xsi:type="xsd:string" ></Photo3Caption>

<Photo4URL   xsi:type="xsd:string" ></Photo4URL>

<Photo4Caption   xsi:type="xsd:string" ></Photo4Caption>

</EventDetails>

   <ProductDetails>

      <Product>

         <ProductID   xsi:type="xsd:integer" >5</ProductID>

         <NumberOfSales   xsi:type="xsd:integer" >6</NumberOfSales>

         <FocusProduct   xsi:type="xsd:string" >Yes</FocusProduct>

      </Product>

      <Product>

         <ProductID   xsi:type="xsd:integer" >7</ProductID>

         <NumberOfSales   xsi:type="xsd:integer" >6</NumberOfSales>

         <FocusProduct   xsi:type="xsd:string" >Yes</FocusProduct>

      </Product>

   </ProductDetails>

</EventActivity>
</EventActivityArray>

PHP: clientCanon.php

<?php
$requestPath = "eventsCanon.xml";
// Calls the file name containing the data
$url = "http://www.d1-gauge.com/canon/API/my_server.php?key=a1";  
// fake key - obviously!

$request = file_get_contents($requestPath);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POSTFIELDS, $request);
// what to post
curl_setopt($ch, CURLOPT_BINARYTRANSFER, 1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0);
$result = curl_exec($ch);
curl_close($ch);

print $result;
?>

Files:

Download the files here:

DemonstratorGaugeUploadAPIv1-0.zip

Support

Please send comments to API@directness.net

The Perfect Event: Adding information and photos to DemonstratorGauge

In response to user feedback we upgraded our photo upload system for our field marketing measurement system, DemonstratorGauge. It now shows progress bars for uploading photos, with new maximum size of 6Mb. Adding captions is easy, and editing details is simpler with the new Event Summary Page.

Short tutorial video presentation here on how to use the new features to upload the “perfect event”. You can see how a demonstrator can log event details, time, comments, products sold, upload photos with captions.