API: DemonstratorGauge Event Upload | CustomerGauge API: DemonstratorGauge Event Upload

Request Demo

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:

[caption id="attachment_1402" align="alignnone" width="400" caption="Example output from API "]Example output from API[/caption]

Validation - contents of successful report:

[caption id="attachment_1403" align="alignnone" width="400" caption="DGresultlist.csv: Successful result returning new Event IDs, and confirming Demonstrator and Venue ID"]Successful result returning new Event IDs, and confirming Demonstrator and Venue ID[/caption]


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:

[caption id="attachment_1404" align="alignnone" width="400" caption="DGErrorList.csv: Shows details of any uploading errors to help debugging"]DGErrorList.csv: Shows details of any uploading errors to help debugging[/caption]




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 1600x1600 (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


Next Up: The Hidden Churn Indicator - Absence of Signal

Get The Most Comprehensive B2B NPS and CX Benchmarks Report on The Planet

Get the eBook

Might we also interest you in...

Close Close
B2B

The Most Comprehensive B2B NPS & CX Benchmarks on the Planet

See how your experience program compares with over 24,000+ NPS & CX data points collected across 12 B2B industries.