HubSoft APIs

Drive your web site from your HubSoft portal

HubSoft Web Site API Overview

The HubSoft portal provides connectivity and content management controls so that manufacturers using the HubSoft portal can easily manage their external corporate web site. Product catalogs, dealer locators and more can all be easily implemented using HubSoft’s API’s and web service connections to power any other web site. Once connected, the HubSoft portal provides all the controls necessary to manage the content on the web site in real-time and often as a seamless part of managing the products on the portal as well.

This article describes the HubSoft API interface and the portal controls used to administer this access.

Portal Controls

The HubSoft portal contains the access controls to the web API connections. This can be found in the ‘Setup’ section of the administrator’s view in HubSoft. Before describing these configuration screens, its important to understand some of the other portal controls that are used to pass data through this interface.

Classifications

Classifications are how the manufacturer groups their products’ As an example, products could be organized into ‘Mens” or “Womens” classifications. HubSoft supports any depth of classification hierarchy which will be provided through the interface with its ‘parent’ record. The top of the classification tree is the company name. This control is used to display products based on their desired grouping, such as ‘Mens’ products, by requesting a product list by classification.

Seasons

Products are also grouped into ‘Seasons’ so that manufacturers can manage the seasonality of their products and how they are introduced to the market. The administrator can select the season(s) that are displayed on their web site. This in turn determines the products and size options that are provided through the service interface. This means that requests for products by classification will only return the products in ‘displayed seasons’ rather than all the products in the classification tree.

This approach allows the organization of the web site to function from the classifications while making it simple for the manufacturer to change their site as they launch their new Seasons.

Note: HubSoft is configurable and the ‘Classification’ or ‘Season’ are both constructs that can be redefined, such as different ‘Product Lines’. So this document describes the typical configuration and the developer should be aware if they have reconfigured HubSoft in a way that changes the service interfaces.

Store Types

The ‘Store Type’ and how it is configured in the ‘Web Site’ section determine what is displayed in the store locator. The “Store Type” is a value in HubSoft that characterizes the type of store for the account. This could be a ‘Distribution Center’, a ‘Retail Store’ or ‘eCommerce site’. These values are defined by the administrator and added to the store records when they are created in HubSoft. This control is also used to determine which stores should display on the external web site and how they should be displayed. The options are as a ‘Retail Store’ or ‘online eCommerce’ store for purposes of the store or dealer locator interface. This allows administrators to quickly change the web display controls for large groups of stores rather than managing them on an individual basis. There is a store-level override control on the store detail screen in the ‘Store Locator’ section.

News

The ‘News’ section are news stories managed by the administrator to display to portal users or web users. The web site connectivity only returns news stories that are indicated as ‘Publish to web’. The ‘Brief Description’ is content that allows the user to view a short description or synopsis of the story. There is also the long description of the news story as well. Content for the brief and long descriptions will be passed in HTML format to allow the administrator to manage the content in the HubSoft editor.

The ‘News’ stories are grouped by categories, for example ‘Industry’, or ‘company’ news. These categories are defined by the administrator and can be retrieved through the web service interface.

Events

The ‘Events’ works the same way as the news section where the service only returns events indicated to ‘Publish to web’. The event will contain a brief and long description that is provided in an HTML format. Events also have their own category list which is accessible through the web service interface.

Web Service Access

The administrator has a setup screen where they can view the unique web service access key for their site. This key is used to authenticate any web service requests that are received. This screen also allows the administrator to turn on and off any specific web service requests to provide greater security. If the web service is requested and the administrator has not enables the particular service, it will be rejected.

Web Site API Methods

HubSoft will generate a unique key that will be used to identify the company in any web service request. This key will persist for the company and be the only mechanism used to ‘authenticate’ the request. This key will be different than the key used to identify the company on the HubSoft servers and will be part of the request to all web services. In addition to this key, each web service will need to be enabled by the administrator. The default setting is that all services are disabled.

getNewsCategories

This request will return the list of news categories. This will enable the web site display to provide a filter as to the types of news stories that are displayed.

Input Parameters
accessKey	Unique reference key

Response Values
News Category UID	A unique numeric value reference used to request ‘filtered’ lists of news stories.
News Category Name	User entered description for the news category.

getNews

This request will return the brief overviews of the news story associated with category passed. Only the news stories configured in HubSoft to ‘Display on the web’ will be included.

Input Parameters
accessKey	Unique reference key
News Category UID	This value should default to ‘0’ to return all news stories. If a specific category UID is provided, the only the news stories to that category UID will be returned.

Response Values
News Story UID	A unique, numeric value used to identify the news story.
News Story Name	The user entered name for the news story.
News Story Date	The user provided date for the news story.
News Story Brief Description	A brief description returned in HTML format.
News Category UID	The category UID for the news story.

getNewsDetail

This request is to display the long description for the news story.. This is separate as the amount of information returned will be larger. This will be accessed using the company code and the news UID.

Input Parameters
accessKey	Unique reference key
News Story UID	A unique, numeric value used to identify the news story.

Response Values
News Story UID	A unique, numeric value used to identify the news story.
News Story Name	The user entered name for the news story.
News Story Date	The user provided date for the news story.
News Story Long Description	A long description returned in HTML format.
News Category UID	The category UID for the news story.

getEventCategories

This request will return the list of event categories. This allows the events to be filtered on the web site.

Input Parameters
accessKey	Unique reference key

Response Values
Event Category UID	This is a unique numeric value that identifies the event category.
Event Category Name	This is the user entered description of the event category.

getEvents

This request will return the brief overviews of the events associated with category passed. Only the events configured in HubSoft to ‘Display on the web’ will be included.

Input Parameters
accessKey	Unique reference key
Event Category UID	This value should default to ‘0’ to return all events. If a specific category UID is provided, the only the events to that category UID will be returned.

Response Values
Event UID	Unique numeric identifier for the event.
Event Name	User provided event name
Event Date	User provided event date.
Event Brief Description	This is the HTML content for the event’s brief description.
Event Category UID	Event Category UID.

getEventDetail

This request is to display the detail text from the Event. This is separate as the amount of information returned will be larger. This will be accessed using the company code and the Event UID.

Input Parameters
accessKey	Unique reference key
Event UID	A unique, numeric value used to identify the news story.

Response Values
Event UID	A unique, numeric value used to identify the event.
Event Name	The user entered name for the event.
Event Date	The user provided date for the event.
Event Long Description	A long description of the event returned in HTML format.
Event Category UID	The category UID for the event.

getSeasons

This returns a list of the Seasons that are enabled by the administrator in the HubSoft portal. This is used to determine the products and sizes that should be displayed on the web site.

Input Parameters
accessKey	Unique reference key

Response Values
Season UID	This is a unique numeric value that identifies the season. There may be more than one value returned.
Season Name	This is the user entered description for the Season. There may be more than one value returned.

getSeason

This returns the user entered name for the season UID.

Input Parameters
accessKey	Unique reference key
Season UID	This is the unique numeric identifier for the season.

Response Values
Season UID	This is a unique numeric value that identifies the season.
Season Name	This is the user entered description for the Season that was requested.

getClassifications

This request returns a list of all the classifications in the portal. This is a hierarchical structure so the parent unique identifier is also provided. The top-most parent is the company name.

Input Parameters
accessKey	Unique reference key

Response Values
Classification UID	This is a unique numeric value that identifies the classification. This returns one to many records.
Classification Name	This is the user entered description for the classification. This returns one to many records.
Classification Parent UID	This is the unique numeric value of the parent to this classification. The top-most parent is the company name. This returns one to many records.

getClassification

This request is to retrieve the detail for a specific classification.

Input Parameters
accessKey	Unique reference key
Classification UID	Unique numeric reference for the classification.

Response Values
Classification UID	This is a unique numeric value that identifies the classification.
Classification Name	This is the user entered description for the classification.
Classification Parent UID	This is the unique numeric value of the parent to this classification. The top-most parent is the company name.

getStores

This will return all the stores within a country and state that are of a store type that indicates they should be displayed on the web site and that there are no overrides. This will return all of the stores.

For US stores only, this will display all the stores where the zip code is equal to the zip code entered plus an additional 5 stores where the zip code is ‘close’ to the search zip code. This will not display stores were the zip codes are too separate, just mathematically within ‘100’ in the zip code sequence. The response can be 0 to many records.

Input Parameters
accessKey	Unique reference key
Country Code	Two character country code defined in the ISO standard. http://www.iso.org/iso/country_codes/iso_3166_code_lists /english_country_names_and_code_elements.htm
State Code	If no value is passed this will return all the stores in the provided country code. This is the two character postal state code. http://www.usps.com/ncsc/lookups/abbr_state.txt
Zip Code	If this is blank, all the stores in the provided state code will be returned. If this is provided, it should be in a ‘#####’ format.

Response Values
Store Name	User entered store name.
Store URL	Store URL from Store Locator section of the store detail screen.
Phone Number	Store phone from store locator section of the store detail screen.
Store Street	Store street from store locator section of the store detail screen.
Store City	Store city from store locator section of the store detail screen.
Store State	Store state from store locator section of the store detail screen.
Store ZIP	Store ZIP from store locator section of the store detail screen.
Store Country	Store country code from store locator section of the store detail screen.
Store Locator Notes	Store notes from store locator section of the store detail screen.

getOnlineStores

This will return all stores that are of a store type that indicates they should be displayed as ‘eCommerce’ stores with no overrides. This will return all of the stores without respect to the account status.

Input Parameters
accessKey	Unique reference key
How Many	A number that indicates how many online store links should be returned. ‘0’ will cause all the stores to be returned.

Response Values
Store Name	User entered store name.
Store URL	Store URL from Store Locator section of the store detail screen. This will include the ‘http://’ in the return.

getProducts

This request returns all the products in the Season provided assuming that the Season was enabled by the portal administrator. All the products in the specified classification and any products that are a child below the classification will also be returned.

Input Parameters
accessKey