Creating a Specification

Create a new specification if the new book cannot be specified with any existing specification. 

For example, if none of the existing specifications specify the new book’s width and height, a new specification is required.

The procedure for adding a new specification is comprised of three main steps:

  • Getting a boilerplate specification/component
  • Creating the components
  • Creating the specification

Follow the steps below to create a specification:

  1. GET an existing specification as a boilerplate for the new specification and components.
  2. POST the cover and text components.
  3. Edit each component from the base specification to match the new specification’s parameters. The following parameters must be changed:
    • Remove Id and other information that is specific to the original specification.
    • Modify width, height, and any other parameter requiring change.
  4. Save {{coverCompId}} and {{textCompId}} of the newly created components for later use.
  5. POST the new specification to Piazza after making the changes required in the specification and embedding {{coverCompId}} and {{textCompId}} in the specification.
  6. Save {{specId}} of the newly created specification for later use.

Uploading Files

The automated linking of assets to Specification and Metadata is dependent on file names. The file name must be the same as the sourceProductId (ISBN). 

  • Cover file names are structured as follows: {{sourceProductId}}_cover.pdf
  • Text file names are structured as follows: {{sourceProductId}}_text.pdf

Follow the steps below to upload the cover component and PDF file for the text component:

Note: The API calls used in the uploading of assets can be found in the Asset Locker API documentation:

  1. GET a signed S3 URL.
    Note: Save the signed s3Path for the next step.
  2. Upload the associated asset.
    Note: Alternatively, the files can be bulk uploaded within the Piazza UI. 


Creating a Book

The process of creating a new book involves setting the new book properties (title name, author, pages, etc.), linking the book metadata with the cover and text files, calculating spine bulk according to the number of pages in the book, preflighting, and checking. Fixes to artwork and book properties may be required after preflight and spec check.

  1. GET book metadata as boilerplate for the new book.
  2. Add a query for a specific Title that is live.
    Note: For example, ?query={“properties.isbn”: 9782359731659”, “status”: “live”}
  3. Update the template with the {{coverCompId}}, {{textCompId}} and {{specId}}.
  4. POST the new book.
  5. Save {{bookId}} of the newly created book for later use.
  6. Use {{coverCompId}}, {{coverFileId}}, {{textCompId}}, {{textFileId}} and {{bookId}} to link the files to the components in the book.
    Note: Use the PATCH call.

Updating the Spine Bulk

Calculate the spine bulk according to the number of pages in the book. Follow the steps below to update the spine bulk:

  1. Calculate the spine bulk according to the number of pages in the book.
  2. Initiate the preflight and spec check on the book.
    Spec Check:
  3. Fix any errors in the title that do not pass the preflight and spec check. The book can be published only after preflight and spec check pass. 
  4. Update the component thumbnails.

Note: In addition to API response payloads, triggers can be configured within the Piazza UI for Title created, Title updated, Title Print Ready, Title Published, Title unpublished, Title deleted and Title Error states.

Publishing a Book

Set the book as live (Published) and available for ordering.

Unpublishing a Book

Unpublish the book to make changes to its metadata.

Additional Documentation

Piazza API documentation

Asset Locker API documentation