Ancillary Data Feeds
The following are specifications for sending data outside of ONIX to Above the Treeline through an FTP delivered data feed.
Feed format
All ancillary feeds should be sent as DOS-formatted tab delimited text (strongly preferred) or as Excel files with the first row of data being a header row representing the names of each column of data. The field names for each data element are defined in each feed’s spec below, and all prescribed field names/columns must be present in that feed, even if they are not required and you’re not providing any values for them.
The names of the feeds should be standardized with the Feed Name (see below for names) followed by the “_” character and a date stamp in MMDDYY format. Lastly, a sequence number should be appended to the filename. If only one file is sent in a given day for a given type, the sequence number will be “_1”. This number should be incremented if additional files are sent. The file extension for all feeds is “.txt” for delimited files and “.xls” for Excel files.
In summary the feed file requirements are:
- File format: TEXT in DOS format (strongly preferred), or Excel (2007 or earlier) saved as a tab-delimited .txt file. If text files are sent, they need to be in the DOS file type. Be sure to use ASCII mode to transmit over FTP if you are saving the file in MacOS or Linux.
- File Delimiter: Tab (\t)
- File Name Format:
[FEED_NAME]_[YYYYMMDD]_[SEQUENCE]].txt- (e.g.
Product_Description_20190329_1.txt)
- (e.g.
- Excel files should be named with the format above but with a .xls extension.
- First Row: Header representing column names. Column names must match the field names defined in the spec.
- File Size: Each file should not include more than 8,000 rows of data
Transmission and Processing
All ancillary feeds need to be pushed to the Edelweiss FTP server at ftp.abovethetreeline.com. Please contact Above the Treeline if you need an account setup for this, as well as if/whenever you post a brand new type of ancillary feed; our technical support team needs to configure your account in order to auto-process all new types of feeds.
Feeds need to be placed in the /edelweiss/import_data/ folder. This folder
will be monitored by an automated process and feeds will typically be processed
within an hour of receiving them, though this processing window is subject to
change and may be delayed if the volume of feeds needing to be processed is
especially high.
Processed feeds will be moved to the /edelweiss/import_data/processed folder
and kept there for 3 months. The individual at your organization responsible
for posting ancillary feeds may also be set up to receive the automatic alert
email that lets them know if their file was successfully processed. Contact
support@abovethetreeline.com if you need to add or update this feed recipient
list or are posting a new type of ancillary feed for the first time.
In summary the key information for feed processing is:
- Feed Transmission Protocol: FTP
- FTP Server: ftp.abovethetreeline.com
- FTP Drop Folder: /edelweiss/import_data/
- Processed Files Folder: /edelweiss/import_data/processed File
- Retention: 3 months
If you would like to post a particular feed to update an Edelweiss market that is not your default market, contact support@abovethetreeline.com to ask for a new market-specific subfolder to be created within your import_data folder. For example, if you are a US publisher but would like to supply unique title content for the UK market, we will create a UK subfolder within your import_data folder, and that’s where you’ll post all UK-specific ancillary feeds.
Available Feeds
| Feed Name | Type |
|---|---|
| Product Descriptions | Ancillary |
| Related Products | Ancillary |
| Product Links | Ancillary |
| Contributor | Ancillary |
| Price | Ancillary |
| Subrights | Ancillary |
| Burst | Ancillary |
| Honors | Ancillary |
| PrintRun | Ancillary |
| Document Builder | Ancillary |
| Catalog Summary | Catalog Maintenance |
| Catalog Items | Catalog Maintenance |
| Marketing Collections | Catalog Maintenance |
Product Descriptions
Description
This feed consists of product descriptions and relates by Product_SKU to the Product Feed. Multiple descriptions may be sent per SKU but must be differentiated via the Description_Type field. Only one record should be sent for each unique SKU/Type. If multiple records are sent, only the first record will be used. The data in this feed may be sent via ONIX. Note: All field names, or column headers, must be included, even if/when there’s no data for them and they’re not required.
Feed File Name
Product_Descriptions_[YYYYMMDD]_[SEQUENCE].txt
Example: Product_Descriptions_20190329_1.txt
| Field Name | Data Type | Field Description | Required |
|---|---|---|---|
| Product_SKU | Text | ISBN13 or EAN used to identifiy the product | Yes |
| Description_Type | Text |
The value for this column must be one of the following:
|
Yes |
| Description | Text | Text of the description. Blank descriptions will be ignored. In order to delete a record the description field must contain the value: *DELETE* | Yes |
| Sequence | Numeric | Order in which items of the same type with the same SKU should be sorted | No |
| Market | Text |
The market for which this descriptive content should be used. Valid values are:
Note also that Trade, Christian, and Academic here only refer to the US region/market. |
No |
Related Products
Description
This feed consists of comparison/comparable products for a parent product and relates by Product_SKU to the Product Feed. Multiple comparison products may be sent per SKU.
When sending comp titles, all Related_SKUs for a Product_SKU must be sent in each feed. The feed processor will delete any/all comp titles that currently exist in the system for the Product_SKUs that are sent in that feed. The equence that the comps appear in the feed will determine their sequence in Edelweiss.
When sending related products, all records with the same Product_SKU and Relationship_Type must be sent in each feed. The feed processor will initially delete any related products for each SKU/Type combination sent before ingesting the new related products.
The only Related Product Relationship Type (see spec below) that will end up as an Edelweiss Comp Title is the Comparison type. All others, e.g. Backlist, Display, etc., will display in Edelweiss in the Related Products section.
As of April 2014, select Related Products that appear in your ONIX feeds may be used in lieu of being sent through a Related_Products feed. These include relation codes 03 (Replaces) as Previous Edition Comp titles, 06 (Alternative format) as Other Format Related Products, 15 (Epub) as Ebook Related Products, and 23 (Similar product) as Also Available Related Product or Comp. Contact support@abovethetreeline.com if you’d like us to start processing your ONIX Related Product data or would like a current list of RPs that can be processed via ONIX.
Note: All fields/columns listed below must be included, even if/when there’s no data for them and they’re not required. This includes the field names/column headers.
Feed File Name
Related_Products_[YYYYMMDD]_[SEQUENCE].txt- (e.g.)
Related_Products_20190329_1.txt
Record Specification
| Field Name | Data Type | Field Description | Required |
|---|---|---|---|
| Product_SKU | Text | ISBN13 or EAN used to identifiy the product | Yes |
| Related_SKU | Text | EAN used to identify the related product | Yes |
| Relationship_Type | Text |
The value for this column must be one of the following:
Note: Any value in this field other than 'Comparison' will show as a Related Product rather than a Comp. |
Yes |
| Relationship_Subtype | Text |
If Relationship_Type is Comparison, this field must be one of the
following values otherwise 'Publisher_Derived' will be assumed:
|
No |
If you need to do a mass delete of any Related Products that were previously
posted in one of these feeds, use the value *DELETE* in the RelationshipType
of RelationshipSubType fields. If you post *DELETE* in the RelationshipType
field, this will delete all Related Products of any type that match that ISBN
pairing. If you put it in the RelationshipSubType field, it will only delete it
for the record with that specific RelationshipType.
Product Links Feed
Description
This feed consists of web links associated with a product and relates by Product_SKU to the Product Feed. Multiple links may be sent per SKU. Each link must be sent in an individual row. Multiple links cannot be sent in the same Link cell.
Links from this feed are imported as Title links in Edelweiss. When adding
additional manual links via the title interface, be sure to add them as
Generic links, as Title links will be automaticaly replaced
by the links in this ancillary feed.
Note: All field names, or column headers, must be included, even if/when there’s no data for them and they’re not required.
Feed File Name
Product_Links_[YYYYMMDD]_[SEQUENCE].txt
(e.g.) Product_Links_20190329_1.txt
Record Specification
| Field Name | Data Type | Field Description | Required |
|---|---|---|---|
| Product_SKU | Text | ISBN13 or EAN used to identifiy the product | Yes |
| Link_Description | Text | EAN used to identify the related product | Yes |
| Link | Text |
URI for the web page If you need to delete one or more previously fed links, use the value *DELETE* here to remove all links associated with that SKU |
Yes |
| Sequence | Numeric | The sequence that should be used to sort the links (if more than one) for a particular SKU | No |
| Upload | Boolean | Values can either be True or False. Default is False. This indicates whether the link will be uploaded content. Uploaded content should be dropped in the supplemental folder. In the case that Upload is true, the Link should be the name of the uploaded file. | No |
| Video | Boolean |
Values can be either True or False. Default is False. Indicates whether
the link should be embedded in the videos section of the site with an
in-browser player. Currently only YouTube and Vimeo are supported. YouTube links should be in the embed format: http://www.youtube.com/embed/8bL2BCiFkTk Vimeo links should be in the following formay: https://player.vimeo.com/video/141340323 |
Yes |
Contributor Feed
Description
This feed is used to send information about a contributor’s hometown or current residence. The feed is tied to an ISBN/SKU, and it is expected redundant data will be sent for an author of multiple books.
Each ISBN/SKU must be unique within a file for the feed. Any file with duplicated ISBNs/SKUs will not be accepted and will result in a failure to ingest any data.
An ISBN/SKU with multiple contributors can be separated by semicolons. See the examples in the following table for additional details and examples.
Feed File Name
Contributor_[YYYYMMDD]_[SEQUENCE].txt
(e.g.) Contributor_20190329_1.txt
Record Specification
| Field Name | Data Type | Field Description | Required |
|---|---|---|---|
| Product_SKU | Text | ISBN13 or EAN used to identify the product | Yes |
| Hometown | Text | Name of hometown/other location. Use a semicolon to separate multiple contributor hometowns or multiple locations.
See the following examples for reference.
|
Yes |
Price Feed
Description
This feed is used to send price information about products in different currencies. Multiple currencies can be sent for each SKU/ISBN by including multiple lines.
Feed File Name
Price_[YYYYMMDD]_[SEQUENCE].txt
(e.g.) Price_20190329_1.txt
Record Specification
| Field Name | Data Type | Field Description | Required |
|---|---|---|---|
| Product_SKU | Text | ISBN13 or EAN used to identifiy the product | Yes |
| Price | Decimal |
Price of the product, up to two decimal places. Example: 24.99 |
Yes |
| Currency | Text |
Currency code of the price, as per ISO 4217 standard. Example: USD, CAD, EUR, GBP, AUD Country specfic currency codes available include EUR-AT (Austria) EUR-DE (Germany) EUR-FR (France) |
Yes |
Subrights Feed
Description
The Subrights feed imports subrights data into Edelweiss. This data should represent the various types of subrights that are available to be purchased. The feed also provides are optional fields to represent rights that have been sold, option publishers and agent contact information. Please note this feed is not for sending territorial rights similar to those in an ONIX file.
Note: All field names, or column headers, must be included, even if/when there’s no data for them and they’re not required.
Each record should represent a single type of right for a single product.
Feed File Name
Subrights_[YYYYMMDD]_[SEQUENCE].txt
(e.g.) Subrights_20190329_1.txt
Record Specification
| Field Name | Data Type | Field Description | Required |
|---|---|---|---|
| Product_SKU | Text | ISBN13 or EAN used to identifiy the product | Yes |
| Content | Text |
Optional field used only when the right is defined by a subset of
content within the work in question. Most rights will not have a value
for this field. Two examples of content are:
|
No |
| Type | Text |
The type of right associated with this record. Types are publisher
derived but should be consistent across all records using this “type”
for search and filtering purposes. The values for types sent here will
be displayed within Edelweiss. These types are not fixed within
Edelweiss and can be defined by the publisher. Examples of some types
are:
|
Yes |
| Right_Available | Text | Must contain either a value of “Yes” or “No”. Blank values will be interpreted as “Yes”. | No |
| Description | Text | Reserved for future use. | No |
| Territory | Text | This field should be populated only if the right applies to a specific country or territory. Otherwise it should be left blank. | No |
| Language | Text | Only used if the right Type is “Translation”. May contain multiple, comma separated values. | No |
| Rights_Holder | Text | Name (and optionally contact information) for the rights holder. If left blank this will default to the publisher name unless a record with a blank type for this SKU is sent. In that case the Rights_Holder will default to the Rights_Holder in that blank record. | No |
| Market | Text | Reserved for future use. | No |
| Format | Text | Reserved for future use. | No |
| Sales_Channel | Text | Reserved for future use. | No |
| Duration_Type | Text | Reserved for future use. | No |
| Limitation | Text | Reserved for future use. | No |
Burst Feed
Description
The Burst Feed allows for a single line “burst” of text to be attributed to and displayed for a title. Bursts types are pre-defined but the list may be expanded upon request of the publisher. A title may have more than one burst and each burst will appear in a comma separated list.
Note: All field names, or column headers, must be included, even if/when there’s no data for them and they’re not required.
Future functionality to allow for browsing by and filtering of bursts is planned on Edelweiss.
Feed File Name
Product_Burst_[YYYYMMDD]_[SEQUENCE].txt
(e.g.) Product_Burst_20190329_1.txt
Record Specification
| Field Name | Data Type | Field Description | Required |
|---|---|---|---|
| Product_SKU | Text | ISBN13 or EAN used to identifiy the product | Yes |
| Attribute | Text |
The burst attribute to be assigned to this title. Valid attributes are:
|
Yes |
| Display_Value | Text | By default, the displayed text for the burst will be the same as the Attribute. This can be overridden by sending a Display Value in this field. The Display Value can be any string of text under 100 characters. | No |
Honors Feed
Description
The Honors/Awards Feed updates the various awards and honors for a title. Many honors are automatically populated, but the honors feed allows for publishers to push additional data to Edelweiss.
The Award_ID column rows should only include an award's numeric identifier, not the numeric identifier and name. Only one numeric idenitfier should be included in each row. ISBNs/SKUs can be duplicated to submit multiple awards for the same title.
Note: All field names, or column headers, must be included, even if/when there’s no data for them and they’re not required.
Feed File Name
Product_Awards_[YYYYMMDD]_[SEQUENCE].txt
(e.g.) Product_Awards_20190329_1.txt
Record Specification
| Field Name | Data Type | Field Description | Required |
|---|---|---|---|
| Product_SKU | Text | ISBN13 or EAN used to identifiy the product | Yes |
| Award_ID | Numeric |
The internal Edelweiss ID for the award.
Current valid IDs are:
|
Yes |
| Display_Value | Text | By default, the displayed text for the burst will be the same as the Attribute. This can be overridden by sending a Display Value in this field. The Display Value can be any string of text under 100 characters. | No |
Product Rights Feed
Description
The Product Rights Feed can be used to send us Sales Rights information that can be exported from Edelweiss via Custom Exports, PDF/print exports, and Template Builder. While Sales Rights information processed from ONIX appears on your titles in Edelweiss, it is currently not used in any of these exports, as the data is often not as structured or short as required by our export specs.
Data from the Product Rights Feed will not be visible in Edelweiss. This information is only for use in exports.
Feed File Name
Product_Rights_[YYYYMMDD]_[SEQUENCE].txt
(e.g.) Product_Rights_20190329_1.txt
Record Specification
| Field Name | Data Type | Field Description | Required |
|---|---|---|---|
| Product_SKU | Text | ISBN13 or EAN used to identifiy the product | Yes |
| Rights_Description | Text |
Country or region this item may be sold in. Must be 100 characters or less |
Yes |
Product PrintRun Feed
Description
The PrintRun Feed can be used to send us Announced First Print Run, aka Initial Print Run, information that can either be displayed publicly or privately – just to your internal publisher users – on your titles in Edelweiss. It may also be exported from Edelweiss via Custom Exports, PDF/print exports, and Document Builder.
Note that we can also process this information using the InitialPrintRun ONIX
node <k167> from ONIX; when we do, this will always be displayed publically.
Feed File Name
Product_PrintRun_[YYYYMMDD]_[SEQUENCE].txt
(e.g.) Product_PrintRun_20190329_1.txt
Record Specification
| Field Name | Data Type | Field Description | Required |
|---|---|---|---|
| Product_SKU | Text | ISBN13 or EAN used to identifiy the product | Yes |
| AFP | Text | Announced First Print. Examples: 500 or 25,000 | Yes |
Document Builder Feed
Description
The Document Builder Feed can be used to post unique title content that will be used exclusively within the Edelweiss Document Builder for the purposes of exporting to PDF, PowerPoint, Word, Excel, or Email using Document Builder’s Custom Templates. Title content loaded here does not impact the display of your title information on Edelweiss. This feed is unique in that any number of title attributes may be included. The primary requirement is that, aside from the first SKU or ISBN column, each column header, or field name, simply has to match an existing Document Builder Custom Data Element for that organization in order to be imported.
A Document Builder Admin or User may also directly import the contents of this file from the Document Builder Home page in the Custom Data Elements section.
Note that this feed is auto-processed every hour.
Feed File Name
CustomDataElements_[YYYYMMDD]_[SEQUENCE].txt
(e.g.) CustomDataElements_20190329_1.txt
Record Specification
| Field Name | Data Type | Field Description | Required |
|---|---|---|---|
| Product_SKU | Text | ISBN13 or EAN used to identifiy the product | Yes |
| [Name of Custom Data Element] | Text, Number, or Data Element | The value for that specific Document Builder Custom Data Element | Yes |
Catalog Maintenance Feeds
The following feeds may be used by publishers who want to automate the creation and maintenance of the basic catalog data within Edelweiss. These feeds define which catalogs exist and which products appear in those catalogs. They can also be used to update the status of catalogs.
Catalogs also can be created and updated via the admin interfaces in Edelweiss. Publishers using the admin interface may choose to not send these feeds.
Catalog Summary Feed
Description
This feed is made up of single or multi-record data representing a unique catalog or catalogs. There should be a matching Catalog Items Feed for each record in this feed.
Feed File Name
Catalog_Summary_[YYYYMMDD]_[SEQUENCE].txt
(e.g.) Catalog_Summary_20190329_1.txt
Record Specification
| Field Name | Data Type | Field Description | Required |
|---|---|---|---|
| Catalog_Name | Text | Name of the catalog | Yes |
| Catalog_Description | Text | Description of the catalog | No |
| Publisher_Name | Text | Name of publisher or imprint associated with this catalog. | No |
| Catalog_PDF | Text | Name of the PDF file representing the "print" catalog. This feature is currently unavailable. | No |
| Status | Text |
Status of the catalog. Current statuses are:
|
No |
| Sequence | Numeric | Order in which catalogs should be sorted within a single folder. | No |
| Visibility | Text |
Visibility of the catalog. Current visibility options are:
|
No |
| PDF_Page_Offset | Numeric | A numerical value that represents how to adjust the page numbering in the PDF so that it matches the printed page numbers. This is used to ensure that PDF pages are linked properly to the page numbers as they are labeled in the catalog. This value defaults to zero if left empty in the feed. | No |
| Cat_Pages_Per_PDF_Page | Numeric | The default number of catalog pages that are represented in a single page of the PDF. This value defaults to one if left empty in the feed. | No |
| CPPPP_Exceptions | Text | A comma separated list of numerical values representing page numbers that are exceptions to the Cat_Pages_Per_PDF_Page override. Any pages in this list will be assumed to have one catalog page per PDF page. | No |
Catalog Items Feed
Description
This feed represents all products within a catalog or a marketing collection. The data consists of a single record for each product in a catalog. The feed may contain data from more than one catalog or collection. A recommended practice would be to include all catalogs for a season (or some active time period) in this feed and in the corresponding Catalog Summary feed.
Feed File Name
Catalog_Items_[YYYYMMDD]_[SEQUENCE].txt
(e.g.) Catalog_Items_20190329_1.txt
Record Specification
| Field Name | Data Type | Field Description | Required |
|---|---|---|---|
| Catalog_Name | Text | Name of Catalog this SKU is in. Must match the Catalog_Name in the Catalog_Summary feed or the Collection_Name in the Marketing_Collections feed. | Yes |
| SKU | Text | ISBN13 or EAN used to identify the Product | Yes |
| Page_Number | Numeric |
Actual page number where this product appears in the printed version of
the catalog. This is not used for marketing collections. |
No |
| Catalog_Sequence | Numeric |
Sort order for this product within a page of a catalog. This may be
specified by using a sort for all products across the catalog or by
only specifying a sequence when items exist on the same page. If more
than one product never exists on a single catalog page, sending this
data is unnecessary. For collections, this determines the order of products within the collection itself. |
No |
| Page_Span | Numeric |
The number of catalog pages that this product spans. Not used for collections. |
No |
Marketing Collections Feed
Description
This feed is used to create “collections” of titles that can be used within a catalog for promotional or organizational purposes. The collection itself is essentially a catalog embedded in another catalog along with additional descriptive content that is displayed. All titles in a collection may also exist in the catalog to which the collection is related but they are not required to be present. Whether or not they do exist may depend on the display logic used for the template (more info regarding this to come soon).
Catalogs with collections will default to be sorted in the publisher preferred order. This will allow for collections to be seen in the way there were intended. End users can override the default sort which will have varying effects on the display of the collection depending on the template used.
Feed File Name
Marketing_Collections_[YYYYMMDD]_[SEQUENCE].txt
(e.g.) Marketing_Collections_20190329_1.txt
Record Specification
| Field Name | Data Type | Field Description | Required |
|---|---|---|---|
| Catalog_Name | Text | Unique string used to identify the catalog in which this collection will reside. This catalog must have been previously created using the Catalog_Summary feed. | Yes |
| Collection_Name | Text | This field is a short string (less than 150 characters) of text used to label this collection. The name will be displayed as a header in the default catalog sort but will not appear in any other sorting options. | Yes |
| Collection_Description | Text | Long summary text used to describe the collection. This description will only be displayed in the default catalog sort. | Yes |
| Location | Text | The EAN or SKU that this collection should precede or follow in the catalog. The collection will always be displayed along with this SKU regardless of the sorting options used by the end user. Whether the collection precedes or follows the Location is determined by the Location_Type field. | Yes |
| Status | Text |
Status of the collection. Current statuses are:
|
No |
| Visibility | Text |
Visibility of the collection. Current visibility options are:
|
Yes |
| TemplateName | Text |
The name of the collection template to use. Collections may be
displayed in a number of different ways based on the template that is
chosen. Current valid templates are:
|
Yes |