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:

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:

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
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 Test The value for this column must be one of the following:
  • General
  • Keynote
  • Author_Bio
  • Quote
  • Excerpt
  • Marketing_Plans
  • Bookseller Review
  • Key_Selling_Point
  • Unpublished_Endorsement
  • Extended_Author_Info
  • Table_Of_Contents
 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:
  • Trade
  • Christian
  • Acadmeic
  • UK
'Trade' is the default value for market and will be used if no value is sent for this field.
Note also that Trade, Christian, and Academic here only refer to the US region/market. 		No

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

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
Description Text The value for this column must be one of the following:
  • Comparison
  • Keynote
  • Backlist
  • Display
  • Other_Format
  • Audio
  • Give_Away
  • Ebook
  • Also_Available
If this field is left blank, 'Comparison' will be used as the Relationship_Type 		Yes
Relationship_Subtype Text If Relationship_Type is Comparison, this field must be one of the following values otherwise 'Publisher_Derived' will be assumed:
  • Same_Author
  • Same_Title
  • Reissue
  • Genre
  • Audience
  • Publisher_Derived
For all other Relationship_Types, this value can be any string of text that will be used as a label within the application to describe the relationship. For example, products specified as 'Backlist' may have a more descriptive SubType as “Other products you may like…”. If no SubType is sent, the Type will be used as the descriptive label. 		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.

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.

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 home town or current residence. The feed is tied to an ISBN so it is expected that redundant data will be sent for an author of multiple books. Multiple authors may be sent per SKU. In the case where multiple authors contributed to a title, the name data is used to get a best match. Ideally, the name text in this feed will come from the same source that is used to populate contributor data in Edelweiss.

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 identifiy the product Yes
First_Name Text First name of the contributor. Not required but recommended to improve matching. No
Last_Name Text Last name of the contributor. Not required but recommended to improve matching. No
Full_Name Text Full name of the contributor Yes
Home_Town Text City considered to be the author’s home town or current residence. Yes
Home_State Text State of home town or current residence. Not required but recommended. No
Home_Country Text Country of home town or current residence. Not required but recommended. No

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.

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:
  • Text
  • Artwork
 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:
  • Audio
  • Translation
  • First Serial
  • Dramatic
This field may be left blank if sending only Agent Information which will be applied as “All Other” types of rights. The same type can only be sent once for each SKU (including blank types). 		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:
  • Export Edition
  • Paperback Original
  • Movie Tie-in
  • Reissue
  • Short Stories
  • Reading Group Selection
  • Now in Paperback
  • Forthcoming
  • Lead
  • New
  • Program
Additional attributes may be added to the spec but must be requested first 		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.

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:
  • 3 – Okra Pick
  • 4 – New England Book Award
  • 5 – National Book Award Finalist
  • 6 – National Book Award Winner
  • 7 - National Book Critics Circle Award Finalist
  • 8 - National Book Critics Circle Award Winner
  • 9 - Indie Next
  • 10 - ABC Best Books for Children
  • 11 - ABC New Voices
  • 12 - Pulitzer Prize
  • 13 - Man Booker Prize
  • 14 - Pulitzer Finalist
  • 15 - Man Booker Finalist
  • 16 - Caldecott Medal Winner
  • 17 - Caldecott Honor Book
  • 18 - Newbery Medal Winner
  • 19 - Newbery Honor Book
  • 20 - Printz Award Winner
  • 21 - Printz Award Honor Book
  • 22 - Alex Award Winner
  • 24 - Texas Bluebonnet Award Winner
  • 25 - Texas Bluebonnet Award Nominee
 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.

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 Status of the catalog.
Current statuses are:
  • Unavailable
  • Available
  • Archived
Feeds without a status will automatically be made “Available” which means that it is able to be viewed internally by publisher users only. External users will can see the catalog if the Visibility (see below) is set to “All”. 		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:
  • Internal
  • All
    • This option designates whether the catalog can be viewed only by publisher users (Internal) or by all Edelweiss users (All). If left blank, the default value for this field is “Internal”.
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 insure 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
Text Yes
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
Catalog_Name Text 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:
  • Unavailable
  • Available
  • Archived
Feeds without a status will automatically be made “Available” which means that it is able to be viewed by sales reps and stores. 		No
Visibility Text Visibility of the collection.
Current visibility options are:
  • Internal
  • All
This option designates whether the catalog can be viewed only by publisher users (Internal) or by all Edelweiss users (All). 		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:
  • Template 1
  • Template 2
 Yes
Location_Type Text Determines whether the collection precedes or follows the ISBN noted in the Location field.
Valid Location Types are:
  • Precedes
  • Follows
If the value is “Precedes” then the collection with be placed before the Location ISBN. 		Yes