Using the Portal UI

Last updated: 2022-09-16

Contents

Welcome to the Portal Submission Guide. This guide is intended to be the only resource you’ll need to upload your book and video content to the O’Reilly Learning platform with our upload user interface, the Portal. The information in this document is confidential and proprietary to O’Reilly Media, Inc. and is not to be disclosed by the publisher to any third party with the exception of a distribution agency pursuant to delivering content to O’Reilly Media, Inc. on the provider’s behalf. Exceptions require an appropriate, signed non-disclosure agreement.

Whether you’re a new content provider or a long-standing O’Reilly Learning partner, we will keep you informed of the latest updates to our title submission process in this documentation. In the constantly evolving technological landscape, we strive to adapt and update our processes to accommodate your workflows and toolchains and make it easier for you to get your content to a growing audience.

Logging In

To reach the Portal, go to https://upload.safaribooksonline.com/safari-portal and use your upload credentials to log in. If you don’t know your credentials, contact us at Content Team.

The Metadata Form

Some basic metadata items are required for any title being submitted to the O’Reilly Learning platform. Following are metadata fields available on the form and what they mean. Required fields are italicized.

Identifier - Also known as the FPID, or the Formal Public Identifier, is the official designation for the work. It’s typically the ISBN without hyphens (ebook ISBN-13 is preferred). For content that has no ISBN, the publisher must ensure that the intended FPID is not currently in use elsewhere on the platform. If you are unsure or need us to create FPIDs for you, email us at Content Team and we’ll be happy to help.

FPIDs must be at least 5 characters in length, begin with 5 leading digits, and contain a maximum of 19 characters. FPIDs should not begin with a zero (0) or contain hyphens. Any alphabetical characters must be uppercase.

Title - This is the full title, as you would like it to appear in the platform. Please don’t use all caps and don’t move words such as “A”, “An”, or “The” to the end of the titles. The system ignores these words in alphabetical sorts.

When the edition is second or greater, append the edition number to the end of the title, e.g., “O’Reilly Test Title, 3rd Edition”. First editions shouldn’t be labeled like this.

Publisher - Select the appropriate publisher name here. Don’t see yours? Contact Content Team to get it added.

Edition - Add the edition number of the title.

Language - Indicate the appropriate language.

Length - This is the page count of the print book, or total time in seconds for video content.

Length type - Specify if the length is pages (books) or seconds (video).

Rights - This must include the copyright symbol (©), year, and name of holders. Do not include trailing punctuation. This data is not displayed to platform users.

Copyright year

MSRP - Contains the publisher’s suggested retail price of the title, expressed in U.S. dollars, with two decimal places and without the dollar sign ($). (Use the retail price of the electronic version if there is no print version for sale.) The PSRP is the retail price and not the institutional/library price. This field can’t be left empty nor can it be set to 0.00. O’Reilly Learning doesn’t accept content that is freely available elsewhere in the market.

Hidden - Selecting this field will hide your title from users trying to search or directly link to it. We don’t recommend using this field.

Publication date - If only the publication month is available, use the first of the month. For example, March 2018 can display as 03/01/2018.

Roughcut - This applies only to titles currently in the Rough Cut program.

Format - The format is simply the type of content you are submitting. For the most part, you’ll use “book” or “video”. If you think your title falls into a different category, please email us at Content Team for assistance.

Classification - This is only for video works. If you are uploading a video, click "Add Safari Classification" and select one of course, conference, webcast, certification, or interview (the most common classification type is course).

Contributors - When there is more than one author, click Add Contributors and another Contributor field will appear. Note the order of display in Order field. For the “Type” please use “author”.

Identifiers - If your title has additional ISBNs or product IDs, add them here. You don’t need to worry about giving them a name or a relationship type.

Descriptions - This is your chance to explain what the user can expect to gain from your content. Sprinkle buzzy keywords throughout the text, but don’t include a list of keywords. You’ll note there is the ability to add more than one Description; this is relevant only for select foreign language titles and is not currently supported. Be sure to tell us what format the description is in by selecting “text/html”, “text/plain”, or “application/xhtml+xml” from the “Content type” drop down.

Please note that some HTML elements are reserved by the system and not allowed as part of HTML descriptions. Most notably, h1 and h2 elements cannot be used. However, h3 through h6 elements may be used to structure thorough descriptions if desired.

Links - Add supplemental links and note the type of link in the accompanying Description field. Here you can include links to companion material, your website, or errata pages.

Asset Files

Cover - We require a cover in .jpg or .png format with a minimum width of 400px. The height can vary but should maintain the aspect ratio of the original cover image. Both RGB and CMYK color spaces are accepted.

EPUB - EPUB sourced submissions create a better experience for users on mobile devices—the text and images reflow to fit the smaller screen size—which is why EPUB is O’Reilly’s preferred file format.

The ingestion process requires a valid EPUB 2.x or 3.x file for each title.
The submitted EPUB must be valid; in other words, it must pass a validation check by a utility such as epubcheck prior to uploading.
All navpoint IDs must be unique within a given EPUB.
There can be no missing or empty navPoint IDs.
All TOCs (including a toc.html that is a page in the EPUB) must reference content in the order it appears in the EPUB.
The TOC links should include only the name of the chapter or section, and should not include extraneous information, such as page numbers.
At minimum, the TOC must include chapter titles. The structure should be hierarchical, i.e., section titles must be nested within chapter titles.

You must also provide us with a reflowable EPUB file. Because our reader is not designed to support fixed layout EPUBs, they will not render properly on the platform and will be unusable to our readers.

CSS that attempts to duplicate functions already present in HTML (e.g., <p>, <span>, and <div>) may not render properly and should be omitted in favor of using the built-in HTML functions.

Clips - For each clip in your video work, clicking the Add Clips button will create a new clip element. The optimal input format is MP4. Please note that H264/AAC encoding is required. The preferred aspect ratio is 16:9, with the following specs:

1,280 pixels in width (if not exact, must be divisible by 16)
720 pixels in height (if not exact, must also be divisible by 16)
5,000 kbps Bitrate

For each clip, you must provide a title and a linkID. The description is optional but is helpful to explain what the user can expect to learn from the clip. Clip-level metadata will allow users to more easily discover the content, as the text is included in the platform search index. The video clip description has a maximum of 1,024 characters and no special encodings are supported (the element is ASCII). The preview checkbox is also optional; if checked, any given clip will show the full clip to users who are not logged into the site.

Submissions

New Titles

Once the metadata is complete and the asset files are attached, click the Submit to QA button in the lower right corner of the page. This will upload and verify the files—making sure the cover meets our specifications and run epubcheck on the EPUB file—and will validate the metadata form to ensure all of the required information is there as well as check for logic errors. When the page refreshes, you’ll be alerted to any errors. If there are no errors, you’ll see a confirmation page. Review the metadata to ensure everything is correct and then click Confirm Submission

If uploading a video, we recommend clicking the Save button before you click Submit to QA. Clicking the Save button will upload and validate the files (as above) but will also populate a click-and-drag Table of Contents tool. This tool will let you add H2 parts to your video’s table of contents so you can drag and drop the individual clip items into them.

Tips on how to use the ToC builder:

Drag and drop clips to change their order in the ToC.
Use the “Add Section” button to create a new section within the ToC.
Drag clips below a section and to the right to place them within a section.
Drag clips out of a section or to the left to remove them from a section.

Once the Table of Content is built, click the Submit to QA button to load the confirmation page for another chance to ensure the metadata is correct. Once you’ve verified the metadata, click Confirm Submission.

Updates

If you need to update a title that is already live, you need to create a new submission with the changes. However, to avoid having to enter all of the metadata again, we’ve added a “Fetch” feature to grab the metadata from the CMS and reload the form. Then you can edit the metadata as needed and/or upload the new asset files.

To use the “Fetch”, simply enter the FPID and publisher name and then click the “Fetch” button in the lower right hand corner of the page. When the page reloads, you can make edits. Once done, click to Submit to QA and confirm as you would with a new title submission.

Submission Statuses

When you log into the Portal, you will see a list of titles that you’ve submitted, along with their current status:

New: The submission is in progress and has not been submitted for ingestion. It can still be edited by the user.
In Auto QA: We are performing automated checks of the metadata and the submitted files. The submission can’t be edited by the user.
Failed QA: The submission failed automated QA checks and needs to be fixed and resubmitted. The user can edit the submission.
Submitted: The submission has passed QA and is preparing to be sent to the live products. It can no longer be edited.
Closed: The submission has not been successfully submitted within two weeks of creation. The submission can no longer be edited or submitted.