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 "]
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"]
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"]
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
| |||||||||||||
<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