The XML Import For Businesses is a standard import format that will create an XML Import Parser to handle updates to a business in the Business Directory from third party entities.
The lookup mechanism for finding a Business Asset to modify is controlled by the following rules:
- If a business entry contains an id attribute, the system will use this value to lookup a business asset by the BLOX asset ID (a UUID).
- If a business entry contains a vendorid attribute, the system will use this value to lookup a business asset by finding a business with a key of providername from the vendor field. The parser will also support a special mode for checking for the ID in a comma-delimited list under that key (the default is an exact match).
- The system will use any ID mentioned in the <auxiliary> XML block to try and find the business.
- Lastly, the system will try to match on a combination of:
- phone, address1, address2, city, state
- phone, address1, city, state
If not found, after all that, the fallback is to create a new business entry. The following are the Import Operations that are allowed:
- Update: This operation will create the business if it does not exist or update. In update mode, any field not explicitly provided will not be changed or modified. This is the default operation if not specified, click here for an Example.
- Replace: This operation will create the business if it does not exist or replace it entirely if found. In the replace mode, any field not explicitly provided will be emptied.
- Delete: This operation will cause the associated business to be marked as deleted. Removal only eliminates the localized version.
Validate XML File
If you are having issues with your XML files validating you can check the W3C XML Validation Service. This service will show precise information about what, where and why the XML is having an issue.
Upload XML File
Data should be uploaded to each customer’s domain in the standard data/feeds directory. Each feed should be stored in a sub-directory of this location. The data should be uploaded using FTP or SFTP (preferred) which can be setup using theSettings / FTP Manager or by contacting Townnews.com Customer Service - (800) 293-9576 to setup credentials. If the feed is being uploaded directly by a third party not under the site's supervision - it is recommended to setup a separate FTP account for security reasons.
Basic XML File Structure
An upload comes in the form of one or more XML documents that contain the ad listings (see a complete example file). The general outline of the upload is:
- <?xml version="1.0"?>
- <business-directory xmlns:townnews="http://www.townnews.com/ns/business-directory-profile/1.0" >
- <vendor>
- <name>OwnLocal</name>
- <providername>print_ad</auxiliary>
- </vendor>
- <businesses>
- <business operation="update" vendorid="123456"> … </business>
- <business operation="delete" vendorid="abcdefg" />
- <business operation="update" vendorid="qwerty"> … </business>
- </businesses>
- </business-directory>
The starting element is <business-directory> and it should include the XML Namespace:
There are two main elements - the <vendor> and <businesses> sections.
- The <vendor> element provides information about the external system providing the export.
- The <businesses> element provides one or more <business> elements that will be loaded into the Business Directory web interface.
Each <business> element must contain the Operation Attribute.
All data will be stripped of all HTML elements, with one exception - the <description> block. Plain HTML is allowed in the <description> block but javascript will be stripped. Note that the HTML in a <description> block will need to be escaped with a CDATA element in order to preserve the tags.
Vendor
The <vendor> section is used to identify the remote system and provide information for troubleshooting. Vendor fields are intended to be employed by the third party system when they implement the export for their system. The supported elements within the <vendor> element are:
| Element | Type | Description |
|---|---|---|
| name | string | Required. The name of the organization such as Newscycle, APT, BrainWorks, etc. |
| providername | string | Required. The Auxiliary Provider Name that will be used with all businesses’ auxiliary ids. |
| version | string | The version of the frontend system exporting the data (if applicable). |
| notes | string | Any vendor or customer supplied notes that should be passed along with the export. This may be useful to convey something that may not follow the standard as written. |
Example:
- <vendor>
- <name>OwnLocal</name>
- <providername>print_ad</providername>
- <version>1.0</version>
- </vendor>
Business Element
The Business Element supports up to three attributes.
| Attribute | Description |
|---|---|
| operation | Required. [delete|replace|update]. Declares the purpose of the entry. delete: This operation will cause the associated business to be marked as deleted. Removal only eliminates the localized version. update: This operation will create the business if it does not exist or update. In update mode, any field not explicitly provided will not be changed or modified. This is the default operation if not specified. replace: This operation will create the business if it does not exist or replace it entirely if found. In the replace mode, any field not explicitly provided will be emptied. |
| vendorid | Required. The vendor’s id for this business. The <vendorid>, along with the <providername> set in the <vendor> element, is used to look up the business within the system. |
| id | If the Blox uuid or business id is known, it should be set here. |
Business
The following elements are supported in each <business> block.
| Field | Type | Description |
|---|---|---|
| auxiliary | list | A list of additional auxiliary id elements. See Auxiliary element, below. |
| branch | string | The local branch name for the business. |
| categories | list | A list of category elements. See Category element, below. |
| custom | list | A list of custom properties. See Custom element, below. |
| description | string | The full description of the business. |
| string | The business's public contact email. | |
| flags | list | A list of flags that should be enabled on the business. See Flags element, below. |
| keywords | list | A list of <keyword> blocks, each containing a single keyword tag to be added to the business. |
| location | complex | All of the data related to the business’s physical location. See Location element, below. |
| logo | string | The path and filename of the logo, relative to export file on the server. Alternatively, a full url to the image may be sent, and the file will be downloaded during import time. |
| name | string | Required. The name of the business. |
| payments | list | A list of supported payment types. See Payments element, below. |
| phone | complex | The data for contacting the business by phone/fax/cell/etc. See Phone element, below. |
| priority | integer | The featured priority that should be assigned to the business. Range is 0 to 32767. Default: 0. |
| schedule | complex | The hours of operation for the business. See Schedule element, below. |
| short-description | string | A short, one or two-line description |
| social | complex | Information on the business’s social media sites, including Facebook, Twitter, Google+ and others. See Social element, below. |
| storefront | boolean | If set to 1, this will enable storefront mode on the business. Default: 0. |
| tagline | string | The business's tagline. |
| website | string | The full URL to the business's main website. |
| year | string | The year the business was started. |
Auxiliary
The <auxiliary> element contains one or more <provider> blocks. This should be used in cases where the business requires additional Auxiliary ID's beyond the data in the vendorname and vendorid elements. Each <provider> block must contain the following attributes:
| Attribute | Description |
|---|---|
| name | Required. The auxiliary ID's name / descriptor. |
| calue | Required. The actual auxiliary ID. |
Example:
- <auxiliary>
- <provider name="ownlocal" value="ATA12312312HDY" />
- </auxiliary>
Categories
The element contains one or more blocks of our supported category types. Currently, the only supported type is bdc:
<bdc>category-code</bdc>
Example:
- <categories>
- <bdc>12010000</bdc>
- <bdc>12040200</bdc>
- </categories>
Custom
The <custom> element contains one or more property blocks. These properties can be accessed in Blox under the business’s. Each <property /> block must contain the following attributes:
| Attribute | Description |
|---|---|
| name | Required. The property name. Allowed characters: [a-z0-9_] Max length of 48 characters. |
| calue | Required. The property value. |
Example:
- <custom>
- <property name="canonical_url" value="http://townnews365.com/ATA1231231HDY/" />
- </custom>
Flags
The <flags> element contains one or more <flag> blocks. Supported flags are:
- 18-and-over
- 21-and-over
- accessible
- all-ages
- buy-local
- date-night
- editors-pick
- expert
- family-friendly
- featured
- for-kids
- for-teens
- free-wi-fi
- hot
- online-only
- paid-wi-fi
- popular
- promotion
- sponsored
- spotlight
Example:
- <flags>
- <flag>editors-pick</flag>
- <flag>popular</flag>
- <flag>family-friendly</flag>
- </flags>
Location
The <location> element contains the following blocks:
| Element | Type | Description |
|---|---|---|
| address1 | string | Main street address. |
| address2 | string | Example: Suite number. |
| city | string | City or Township. |
| state | string | Two character state appreviation or region code [A-Z]. |
| postal_code | string | Required. Supports five digit US code or six character Canadian code. |
| country | string | ISO 3166.1, Alpha-3 country standard. Currently only supports USA and CAN. |
| latitude | number | Lattitude in signed degrees format (DDD.dddd). |
| longitude | number | Longitude in signed degrees format (DDD.dddd). |
| directions | string | Single text field for directions to the busines location. |
Example:
- <location>
- <address1>1510 47th Ave</address1>
- <address2>Suite 200</address2>
- <city>Moline</city>
- <state>Illinois</state>
- <postal-code>61265</postal-code>
- <country>USA</country>
- <latitude>41.4906</latitude>
- <longitude>90.488</longitude>
- <directions>Take Exit 4B off I-74 South</directions>
- </location>
Payments
The <payments> element contains the one or more payment blocks, each indicating the payment types accepted by the business. Six payment types are automatically supported. Custom payment types may be added as well and are supplied as a string just like the standard types. Standard types include:
- Cash
- Check
- Visa
- MasterCard
- Discover
- American Express
Example:
- <payments>
- <payment>Cash</payment>
- <payment>Visa</payment>
- <payment>MasterCard</payment>
- <payment>American Express</payment>
- <payment>Discover</payment>
- </payments>
Phone Numbers
The <phone> element contains the following blocks:
| Element | Type | Description |
|---|---|---|
| primary | string | The main phone number of the business. Format: xxx-xxx-xxxx. |
| cell | string | Format: xxx-xxx-xxxx. |
| fax | string | Format: xxx-xxx-xxxx. |
| tollfree | string | Format: xxx-xxx-xxxx. |
Example:
- <phone>
- <primary>555-555-5555</primary>
- <cell>555-555-6666</cell>
- <fax>555-555-7777</fax>
- <tollfree>1-888-888-8888</tollfree>
- </payments>
Schedule
The <schedule> element contains all information related to the operating hours of the business. In addition to open and close times for each day, special and holiday hours may be defined. The following sub elements are supported:
| Element | Type | Description |
|---|---|---|
| hours | list | A list of hours for each day of the week. If all days are the same, ‘daily’ may be used for shorthand; Note that if daily is included, any other day of the week blocks will be ignored. See below for more. |
| holiday | string | A description of special holiday hours that are followed by the business. |
| special | string | A description of other special hours for the business. |
| timezone | string | String timezone descriptor. Timezones follow the http://www.iana.org/time-zones database. See http://php.net/manual/en/timezones.america.php for examples. |
Possible Substitute Elements:
- daily
- sunday
- monday
- tuesday
- wednesday
- thursday
- friday
- saturday
If <daily> sub element is used, all others will be ignored and all days will be set to the Open/Close values for daily. All <hours> sub elements all accept open and close attributes:
- Values should be in the form hh:mm in 24-hour notation, or one of 3 special values.
- If hours are less than 10, zero-padding should be used.
- Special values include:
- 24-7: indicates the business is open all day long
- closed: indicates the business is closed the entire day
- by-appt: indicated the business is open, but only by appointment
- Special values should be set in both the “open” and “close” attribute.
- If only 1 of “open” or “close” is left blank, unexpected results will occur. If both are left blank, the hours for that day will be cleared and assumed to be unknown.
Example 1 - Using a Custom Schedule Per Day:
- <schedule>
- <hours>
- <sunday open="closed" close="closed" />
- <monday open="08:00" close="17:00" />
- <ttuesday open="08:00" close="17:00"; />
- <wednesday open="08:00" close="17:00" />
- <thursday open="08:30" close="20:00" />
- <friday open="08:00" close="17:00" />
- <saturday open="by-appt" close="by-appt" />
- </hours>
- </schedule>
Example 2 - Using a Daily Schedule:
- <schedule>
- <hours>
- <daily open="08:00" close="17:00" />
- <holiday>Closed on Christmas & New Years</holiday>
- <special>Open at midnight on Black Friday</special>
- <timezone>America/Chicago</timezone>
- </hours>
- </schedule>
Social Fields
The <social> element contains the following blocks.
NOTE: The values should be simply the part [your-id], indicated in bold, as the frontend system will automatically construct the proper url.
| Element | Description |
|---|---|
| https://www.facebook.com/[your-id]/ | |
| flickr | https://www.flickr.com/photos/[your-id]/ |
| foursquare | https://foursquare.com/[your-id] |
| googleplus | https://plus.google.com/[your-id]/posts |
| https://www.instagram.com/[your-id]/ | |
| https://www.linkedin.com/company/[your-id] | |
| https://www.pinterest.com/[your-id] | |
| tumblr | http://[your-tumbler-url]/ |
| https://twitter.com/[your-id] | |
| youtube | https://www.youtube.com/user/[your-id] |
Example:
- <social>
- <facebook>TownNews.com=98681439791</facebook>
- <linkedin>townnews.com</linkedin>
- <twitter>townnews</twitter>
- <youtube>TownNewsTV</youtube>
- </social>