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 boilerplate for the new specification and components.
Appendix Get base Specification

2. Create the components using the following metadata:


{ simplex: Boolean,
binding: String,
lamination: {
type: String,
default: setDefaultFor(
'cover', 'none')
foiling: {type: String,
default: setDefaultFor(
'cover', 'none')
hdnaRequired: {
type: Boolean,
default: setDefaultFor(
'text', false)
colorProfile: {
type: String,
default: setDefaultFor(
'text', 'color85_economy_uncoated_v3_1'),
enum: [null, '',
'mono85_v3_1', 'color85_economy_uncoated_v3_1']

Finishing options 

"finishingOptions": {
"hdnaRequired": false,
"simplex": true,
"lamination": "gloss",
"foiling": "none"


{ type: Boolean }


"required": true

Table 2: Component fields

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

Cover Component Example

  "_id": "5afcdc8705bb930013af4ed1",
  "updatedAt": "2020-04-22T19:06:17.869Z",
  "createdAt": "2018-05-17T01:36:07.301Z",
  "code": "cover",
  "required": true,
  "width": 407,
  "height": 246,
  "bleed": 3,
  "includeSpine": true,
  "accountId": "5ac79ea7b0c3b91a004b7a2a",
  "finishingOptions": {
    "simplex": false,
    "lamination": "gloss",
    "foiling": "none"
  "preflightProfile": "piazza/PDFX-4-With-Image-Sampling.kfpx",
  "pages": {
  "method": "exact",
  "count": 2
  "paperSpec": {
    "gradeUnits": "microns",
    "type": "Book Board",
    "grade": 200
  "barcodes": [],
  "__v": 0
To create a cover component, see Appendix - Post cover component. Save {{coverCompId}} of the newly created component for later use
To create text component, see Appendix - Post text component. Save {{textCompId}} of the newly created component for later use

4. POST the new specification to Piazza after making the changes required in the specification and embedding {{coverCompId}} and {{textCompId}} in the specification.

For more information on how to POST Specifications, Appendix ‎- POST Specification.

5. Save {{specId}} of the newly created specification for later use.

Specification fields descriptions






{ type: ObjectId            }

Account ID



{ type: String }

PSP SKU Code associated with this specification

“UB 189x246 Soft”


[{ type: ObjectId,
     ref: 'Component' }]

Components associated with the specification. Usually cover and text components of a book

[ "5afcdc8705bb930013af4ed1",
   "5afcdc87d358b00012c0fd7f" ]


{ type: String }

Spec. description



{ type: String }

Type of spec.



{ type: String }


“Soft Case”


[{ type: String }]

Free text tags to easily identify and find the specification

[ “Demo” ]


{ type: Number }

Width of the final product



{ type: Number }

Height of the final product



{ type: ObjectId,
   ref: 'specTemplate' }

Default values to take if field is not specified in specification. This includes component IDs too


Table 1: Specification fields

Uploading Files

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

1. Capture {{coverS3UploadUrl}} and {{coverS3Path}} for late user in uploading the file.
Appendix Get a signed S3 URL

2. Upload the cover file in AWS-S3.
Appendix Put cover file

3. Include the cover file in Piazza Assets. 

Appendix Get a signed S3 URL 

To make the file accessible via Piazza UI, follow the steps described in Appendix 6.1.8 Create a record for the cover file. Then, save {{coverFileId}} for later use.

4. Capture {{textS3UploadUrl}} and {{textS3Path}} for later use in uploading the text file. 

5. Upload cover file in S3.
Appendix Put text file

6. Include text file in Piazza Assets. 

Follow the steps described in Appendix - Create a record for the text file. Then, save {{textFileId}} for later use.

The cover and text files are now accessible via (‘hp.demo’ account).

7. Generate cover file thumbnail and Capture its URL as {{bookThumbnailUrl}}.
Appendix Get cover thumbnail URL 

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 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.
Appendix Book query 

2. Use {{coverCompId}}, {{textCompId}} and {{specId}} to add a book.
Appendix Post book

3. Save {{bookId}} of the newly created book for later us.

4. Use {{coverCompId}}, {{coverFileId}}, {{textCompId}}, {{textFileId}} and {{bookId}} to link them all together.

Appendix Patch files into Book

Updating the Spine Bulk

Calculate the spine bulk according to the number of pages in the book as specified in Appendix - Post calculate spine bulk request.

1. Initiate Preflight and spec check to initiate the artwork preflight and spec check.
Appendix Start Pre-flight (and spec check)

2. Create a trigger for the preflight and spec check status. If an HTTP endpoint can be defined to trigger a preflight and spec check error fixing script, a trigger can be registered for it in Piazza:



The payload sent to the endpoint is like the one received when getting the book metadata.
Appendix Get book

3. Fix 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.

Publishing a Book

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

// Request
 // GET
GET {{piazza-base}}/api/books/{{bookId}}/publish

 // Response
     "_id": "5f842a76f418ea00128a7d9f",
    "status": "live",
     "tags": [
        "Title Ingestion"
     "errorStatuses": [],
     "catalogueIds": [],
     "actionIds": [],
     "sourceProductId": "9782348620548",
     "specificationId": "5f832e47e0f8bd0012100be3",
     "accountId": "5ac79ea7b0c3b91a004b7a2a",
     "components": [
             "preflightStatus": "success",
             "specCheckStatus": "success",
             "specCheckErrors": [],
             "status": "live",
             "_id": "5f84407de0f8bd0012118d1e",

Unpublishing a Book

Unpublish the book to make changes to its metadata.

// Request
 // GET
GET {{piazza-base}}/api/books/{{bookId}}/unpublish