Listings on a Channel Integration

Listing in the External Channel Integration

When creating a listing on the External Channel Integration a developer needs to set up endpoints that allow the native Linnworks system to follow the process dictated above. This process uses the Generic Listing Tool (GLT) which allows different channels to manage listings without creation of channel specific UI. The endpoints functions are described below, full details on the request and response can be found in the external channel API documentation.

There are three main steps to this process:

• Enabling support for listings on the external channel
• Enabling configurators: Creating Setting, categories, and variations
• Processing templates: The process to create a listings on the external channel

Enabling Listing for an external channel

Not all external channel might support listing functionality, which is why only external channel that have the setting IsListingSupported set to True along with all the relevant listing endpoints filled. Once this is completed the user will see the configurator and listing screens.

• URL_GetConfiguratorSettings
• URL_GetCategories
• URL_GetAttributesByCategory
• URL_GetVariationsByCategory
• URL_ListingUpdate
• URL_ListingDelete
• URL_CheckFeed

Setting up configurators

GetConfiguratorSettingsEndpoint

GetConfiguratorSettingsEndpoint contains settings that are then used to determine the listing screen layout in Linnworks, how Linnworks processes and validates data provided by the customer and which customer settings are required to be filled out by the customer in order to create a successful listing.

Channel Properties

When the GLT configurator screen is loaded, we get a list of all the integrated GLT channels and all relevant external channels, along with their channel properties, retrieved from their respective factory. For External channels, an instance of the ExternalFactory is created for each external channel. In order to create the Externalfactory, we make a call to the endpoint URL_GetConfiguratorSettings, to get the channel and configurator settings. This is the only external endpoint that is not user specific as data returned should be the same for all customers using this channel and therefore AuthorisationToken is not provided in this call. This call contains details set by the external developer that can be used to set channel properties inside Externalfactory, so they are relevant to the specific external developer.

As some of these settings also affect the layout of the template, configurator and wizard screen, this endpoint is also called as part of the ExternalTemplateUiBuilder and ExternalConfiguratorUiBuilder.

Customer Channel Settings on Configurator Level

It is possible for an external developer to provide a list of configurator settings the customer should fill out. The developer will be able to decide which configurator window this setting should appear in (GroupName), under which sub title (Subtitle), which order the sub titles will have within the screen (SubTitleSortOrder) and which order the setting will be in under the specific sub title (ItemSortOrder). A tooltip with the description provided by the developer will appear next to every setting.

The developer will decide what kind of type the setting is. If a bool, a tick box will display. If a list, a list of all initialValues will display that the customer can select from. If ValueOptions is provided, a dropdown menu will appear for this setting. It is possible for the developer to set an initial value that will be the pre-set values for this setting.

If the setting is set as IsWizardOnly, then the setting will display in the wizard when a new configurator is added. The setting will display in the relevant window, but will be read only after. A setting should be set to IsWizardOnly if this setting affects attributes and/ or required variations list.

General Settings and Return window will only display on configurator level in the grid if the external developer has provided settings for this window.

As the UI of the template, configurator and wizard are dependant on the settings returned, we make a call to the endpoint URL_GetConfiguratorSettings to get the respective settings when the UI is created.

GetAttributesByCategoryEndpoint

This endpoint returns a list of required and optional attributes. This is used e.g. when configurator attribute window is opened. Request contains selected customer category ids and filled customer settings that can be used to determine the list of attributes to be returned.

As part of the call, we send the settings values for the General settings window as well as the list of selected categoryids. It is up to the external developer to decide if none, one or both are needed for the relevant channel to decide what Attributes are the correct attributes to return with the given information.

GetVariationsByCategoryEndpoint

Endpoint which returns a list of required variation options. This is used e.g. when configurator variation window is opened. Request contains selected customer category ids and filled customer settings that can be used to determine the list of required variations to be returned.

As part of the call, we send the settings values for the General settings window and the variation window as well as the list of selected categoryids. It is up to the external developer to decide if none, one or both are needed for the relevant channel to decide what Variations are the correct variations to return with the given information.

GetCategoriesEndpoint

Endpoint which returns a list of categories. This is called e.g. when configurator categories window is first opened, or when categories are refreshed by customer.

Just like with other GLT channels, these are then cached inside dynomodb using GLTStorage. The cache can be updated by the user selecting refresh categories in the configurator screen.

When selected categories are changed, we make a call to the endpoint: URL_GetAttributesByCategory URL_GetVariationsByCategory

Processing Templates (creating listings)

Once you have set up your configurators Linnworks native UI will take care of the rest. The user will be able to use the configurator to create templates and push them to a channel. If you are interested in how the process works we have documented it at External Channels Templates

Summary of Key Listing endpoints