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

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

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