PrintOS Composer Overview

Introduction to the PrintOS Composer API 

The PrintOS Composer service enables composition of PDFs with VDP (variable data printing).

The client SW combines a graphic template with variable data channels with a data file that includes variable data. The composer service binds the data and the template, generating a PDF with the variable data inside.

For example, the following is a business card template.


Given the following data file (in this case a CSV file)

Title,Name,Last Name,Address1,Address2,City,Zip,Country,Phone,Email
Ms,Marilyn,Jones,Database Administrator,5 Graceland Point,Brody,61727-338,Ukraine,380-(372)188-7182,mj@mjrdata.com
Mrs,Ryan,Pierce,Pharmacist,6 Crescent Oaks Plaza,Toliara,50181-003,Madagascar,261-(492)865-3125,rpi@megapharm.com
Rev,James,Henderson,Structural Analysis Engineer,4495 Graedel Drive,Karafao,40028-512,Indonesia,131(342)618-9274,jhenderson@skywayeng.org
Rev,Benjamin,Parker,Accountant IV,2675 Beilfuss Street,Liujia,64735-020,China,86-(598)904-6153,benparker@beckwayhawthorn.com
Mrs,Earl,Cooper,Assistant Manager,151 Tomscot Lane,Lutoryz,0264-7885,Poland,46-(232)389-6524,ecooper46@andj.com
Mrs,Carlos,Martin,Account Representative II,4617 North Road,Tarbagatay,0378-5525,Russia,7-(780)164-9029,cmartin5@jollytimes.com

The composer service would bind the data and output PDF with the following pages.

 

The client can repeat the process each time with different data file inputs and get different results with different data binding each time.

Composition Features

The composition supports:

  1. Variable text
  2. Variable Images based on the image file name within the database
  3. Variable Barcodes based on text in the data file (Barcode Studio and IDAutomation)
  4. Variable Maps images based on the address text (locr maps)
  5. Variable auto-generated images using HP Mosaic and Collage.
  6. Image or Text rules to generate variable data

In addition to VDP, the composer also enables applying imposition with records distribution.

HPD Graphic Template

Graphic templates can be created using the HP SMS Designer plugin, available for both InDesign and Illustrator.

Using Designer, a user can create an HPD file containing a template with the required assets packed inside.

Data File

The data file containing the variable data is a delimiter-separated values file. Composer Service supports CSV or TXT with tab-delimiters. The data file can be created by any OS with any end-of-line characters.

The easiest way to create a data file would be Excel, though any tool generating a delimiter-separated file can be used.

Imposition Template

Composer supports IMPP imposition template files. Such templates can be created by SMS Designer for InDesign.

The Imposition template can be packed as part of the VDP template (HPD file) or by attaching it to composition processing separately.

Either way, when imposition is available, Composer Service would apply the imposition to the generated PDF result per request.

Note – Only records-distribution imposition templates are supported. Attempting to use page distribution results in an error by the system.

Assets Library

As mentioned, VDP template may include variable images. In such cases, the data file should include references to the images by their file names. The image files themselves need to be available when the Composer Service creates the PDF. The client can supply the image files using one of two options:

  1. Pack the images as part of the template file – HPD file
  2. Zip the images in file and upload them separately.

Option 2 might be more convenient since it enables creating the HPD once and then processing it again with different images later.

Note – Use the 64-bit Archive Utility for Mac operating systems to avoid file count limitations. Win Zip does not have this issue.

API Details

Authentication – HMAC

Composer Service authenticate the client using an HMAC Key and Secret. PrintOS supports both SH1 and SHA256

The HMAC Key and Secret should be generated by PrintOS Marketplace.

Once generated, the Key and Secret should be used with every API call. The HMAC Key and Secret binds every API call with the organization\account the of the user. Users that have several organizations\accounts should pay attention which organization\account is being used when generating the HMAC Key and Secret.

NOTE – PrintOS Composer manages tenants of PrintOS Organization. For example, a Printshop is one organization\account at PrintOS. Any call will be handled under that organization. Enable access to data in that scope.

For additional steps on HMAC authentication visit the Authentication Page

URLs

Any URL mentioned at this document should be called with the following base URL https://printos.api.hp.com/composer-service

For example: POST …/composer/sdk/v1/pdf

Will have the full URL of https://printos.api.hp.com/composer-service/composer/sdk/v1/pdf  using with a POST method.

Limit the number of Calls per minute

The number of API calls is limited to 20 calls per minute.

Versioning and Changes

The SDK API is managed with versioning expressed by the API URLs

…/composer/sdk/v1

Note – the APIs may add error cases and new properties as long as it doesn’t break existing behavior concepts and existing properties.

Resources

The SDK is built from Resource objects. We can distinguish between Input and Output Resources as follows

  1. Input Resources
    1. Template Resource – for HPD graphic VDP template.
    2. Data Resource – for VDP data input using CSV or TXT (tab delimiter)
    3. Imposition Template Resource – for IMPP Imposition template file
    4. Assets Library Resource – for zipping with variable images inside
  2. Output Resources
    1. Sample Resource – by which a client can retrieve a single page\record or spread
    2. PDF Resource – by which a client can retrieve a PDF processed using all provided data 

 

The Output Resources reference Input Resources to be used when generating the Sample or full PDF composition.

Resource URLs

Resource Name URL Type
Template Resource .../composer/sdk/v1/template Input
Data Resource .../composer/sdk/v1/data Input
Imposition Template Resource .../composer/sdk/v1/imposition Input
Asset Library Resource .../composer/sdk/v1/assetlibrary Input
Sample Resource .../composer/sdk/v1/sample Output
PDF Resource .../composer/sdk/v1/pdf Output

 

Flow & Resources

The API expects the following flow:

  1. Create Input Resources and upload their related files
    1. Create VDP Template Resource
      1. Upload and attach HPD file to it.
    2. Create Data Resource –
      1. Upload and attach to it CSV file or TXT file with tab delimiter
    3. Create Imposition Template (optional)
      1. Upload and attach to it IMPP file
    4. Create Assets Library Resource (optional)
      1. Upload and attach a ZIP file to it with variable images
  2. Create Output Resources and download resulted files
    1. Create Sample Resource
      1. Reference appropriate resources (template, imposition, data and assets library)
      2. Receive a Download Result URL of a single page\record or spread for preview and audit purpose before making a full PDF (can be PDF or JPEG Thumbnail).
    2. Create PDF Resource
      1. Reference appropriate resources (template, imposition, data and assets library)
      2. Receive a Download Result URL of composed PDF.

Note – input Resources do not have dependencies and can be created in parallel and with no order importance.

 

Input Resources

The following sections will discuss Input Resources.

Input Resources Creation

First step for every resource would be its creation. Creation is done using a POST method on the following URLs. More detailed can be located on the API Documentation Page.

Resource URL Required properties at creation
Template .../composer/sdk/v1/template fileName - the name of the template file (i.e. myTemp.hpd)
Data .../composer/sdk/v1/data fileName - the name of the data file (i.e. myData.csv)
dataFormatDelimiter - a number representing the ASCII code of the delimiter (e.g. comma = 44, tab = 9)
Imposition Template .../composer/sdk/v1/imposition fileName - the name of the imposition template file (i.e. myImpo.impp)
Assets Library .../composer/sdk/v1/assetslibrary fileName - the name of the zip file with the assets inside (i.e. myLib.zip)

 

For example, Data Resource expect the following payload at creation call:

{
	"dataFormatDelimiter": 44,
	"fileName": "myData.csv"
}

The creation POST call returns the full resource structure payload. The document describes more about the resource properties in a later chapter.


At this point, it is important to mention the status property representing the state of the resource. Once created the resource status is set to “Created”.

Note – once a resource is created, it gets a unique Resource ID (UUID). When retrieving the resource, it will have the following structure. Any input values given by the client are placed at the root of the object while any value set by server is placed under output property object.

{
	"inputProp1": "value",
	"inputProp2": "value",
	"output": {
		"resourceId": "a68a055e-c192-4757-aced-64bb4b40cfd9",
		"status": "Created"
	}
}

The output contains many more properties becoming available in different states of the resource.

 

Input Resource File Uploading

Once an Input Resource is created, the Server expects the related resource file to be uploaded and files attached to it.

Note – in case the file was not supplied and fully uploaded within 24 hours from resource creation time, the resource will be deleted automatically.

The Composer API enable uploading file in parts with the following steps:

  1. createPresginedUploadUrls - Generates a pre-signed PUT (upload) URL by calling POST composer/sdk/v1/assets/put-urls
  2. Upload the file chunks (parts) to presigned URLs.
  3. uploadCompleted - Complete upload by calling POST composer/sdk/v1/assets/parts

Limits:

  1. Overall file size is limited to 6GB
  2. Total number of parts is limited to 10000.
  3. A part must be at least 5MB and no more than 5GB in size
    1. Except for the last part which can be less than 5MB in size, including when there is only 1 part to upload.

When a client requests to generate pre-signed PUT URLs, specify the overall file size and the desired part\chunk size for upload – the amount of presigned PUT URLS would be calculated and generated accordingly.

Resource URL Payload
createPresignedUploadUrls .../composer/sdk/v1/assets/put-urls

Request: presignedUploadUrlsRequest

Response: PresignedUploadUrlCollection

uploadCompleted .../composer/sdk/v1/assets/parts

Request: uploadCompleted

Response: no object returned

 

Per part upload, AWS S3 returns a response including “ETag” header. Once all parts are uploaded, the client should call uploadComplete with information including the collection of all ETags and their part number. Using that information, the system can combine the parts back to a single file at the server side.

Note – part number counting starts from 1.

Note - When uploading files to AWS S3 the HTTP Content-Type header should be set to "application/octet-stream"

Why upload in parts?

  1. Performance
    1. Uploading in parts enables faster upload of big files. The client can implement the upload using parallel parts upload, giving faster upload.
  2. Robustness
    1. Overcome network disconnection – in case a part upload failed, the client can attempt to upload it again, overcoming temporary network disconnections
  3. Better Experience
    1. Implement upload resume – upload can be stopped and resumed by continuing to upload parts that were not uploaded yet. Parts already uploaded are valid for 24 hours. This saves time for parts that were already uploaded – there is no need to upload them again.

 

 

For more information on exact message body, please visit the API Documentation Page

 

Input Resource Waiting and Processing


Once a resource is created and its related file is uploaded, the resource status automatically turns from Creating to Waiting state.

While in the Waiting state, the resource waits in a queue to begin processing. Different resources require processing.

  1. VDP Template Resource – finds number of pages and additional information required for internal server use.
  2. Data Resource – counts number of records
  3. Imposition Template Resource – currently no processing required

The number of parallel Input Resources processing at one time is limited. As such, any additional resource beyond the limit waits for its turn to be processed.

For example, if the maximum number of parallel processing for VDP Template is 3, and 3 resources are already in a Processing state, any addition template resource that completes uploading would get into a Waiting state.

Note that each resource type has its own queue, and its own limit of parallel processing. The parallel processing limit is calculated per PrintOS Organization account.

The resource processing order is based on upload completion time.

Input Resources may stay in the Waiting state for up to 7 days. If the waiting time of an Input Resource expires, the resource is automatically deleted.

Note – at the time of writing, an Imposition template does not require any processing before it can be used for composition. As such the Imposition Template resources jump immediately to Ready state. However, we reserve the option to add such processing in the future. The client code should consider the possibility of processing in the future.

Once processing starts, it is limited to up to 6 hours. If a resource passes its processing time limit, the resource state would change to Error.

{
	"inputProp1": "value",
	"inputProp2": "value",
	"output": {
		"resourceId": "a68a055e-c192-4757-aced-64bb4b40cfd9",
		"status": "Waiting"
	}
}

Input Resource Ready

Once the server completes the Input Resource processing, it automatically changes its state to Ready.

The client can query for the resource and get its state and output information.

GET …/composer/sdk/v1/{Resource Name}

The following are the unique output properties of each resource, though more general common output values are available for all resources, which will be discussed later in the document.

  1. VDP Template Resource
    1. richTemplate – true in case it is a rich template or false if it is fast – both SMS Designer for InDesign and Illustrator can create fast templates, while InDesign can create Rich templates.
      1. Rich – PDF result would be processed by Adobe InDesign Server using HP SMS Designer plugins – rich graphics.
      2. Fast – PDF result would be processed by HP’s proprietary VDP engine – faster PDF processing.
    2. embeddedImpositionExist – tells if the HPD template includes an embedded imposition template packed by Designer for InDesign
    3. numberOfPages – HPD template may include 1 or more pages, this property tells how many pages exist in the template – for example, a business card with front and back would have 2 pages.
  2. Data Resource
    1. numberOfRecords – the number of records in the data file.

The outputs of all resources would be located under output object in similar way. For example, a Template resource would include the following once it is ready:

{
	"output": {
		"resourceId": "a68a055e-c192-4757-aced-64bb4b40cfd9",
		"status": "Ready",
		"richTemplate": false,
		"embeddedImpositionExist": true,
		"numberOfPages": 2
	},
	"fileName": "myTemplate.hpd"
}

Note – Input Resource can be in a Ready state for 7 days. Once 7 days passed the resource is automatically deleted.

 

Input Resource Error

Input Resource can get to Error status from Waiting or Processing state. A resource can be in an Error state for up to 7 days and is then automatically deleted.


 

Output Resources

The following sections will discuss Output Resources.

Output Resource Creation – waiting state

Similar to Input Resources, the first step for an Output Resource would be its creation. Creation is done using the POST method on the following URLs. More detailed information is located on the API Documentation Page

 

Resource URL Purpose
PDF .../composer/sdk/v1/pdf For a PDF with embedded variable data inside taken from data file – output PDF
Sample  .../composer/sdk/v1/sample Enables getting a sampling of the output without having the entire PDF processed with the entire set of records.  The client can ask for specfic page/record or spread in case imposition is applied - outputs a PDF or JPEG per client choice

Once an Output Resource is created, it automatically moves to a Waiting state due to the limited number of parallel Output Resource processing – similar to Input Resources.

The number of parallel processing for PDFs is limited to 3. The number of parallel Sample Resource processing is limited to 1.

Note – A PDF resource can stay in the Waiting state for 7 days while a sample resource can wait for 24 hours. Once the time has passed, the resource is automatically deleted.

 

Properties for PDF Resource Creation
Property Name Description
templateResourceId A reference to the VDP template resource to be used for PDF creation (UUID)
dataResourceId

A reference to the data resource to be used for PDF creation (UUID)

impositionTemplateResourceId (Optional) A reference to the imposition template resource to be used for PDF creation (UUID)
assetsLibraryResourceIdCollection

(Optional) A collection of asset library references to be used for the PDF Creation - collection of objects with ID array (UUIDs)

applyImposition (Optional) Whether to apply imposition or not - can be used if VDP template has an embedded imposition or if an imposition resource is referenced
recordsRange

(Optional) Range object to indicate range from data file (e.g from record 5 to 10 will create a PDF with data file rows 5-10).  The Records range contains two properties: from and to.

If not supplied the PDF output will include the entire records set from the data file.

clientTimestampInMilliseconds (Optional) Client time in milliseconds.  For imposition with time text mark embedding, time of creation inside PDF graphics
skipRecords (Optional) amount of records to skip from the beginning of the data resource (i.e. Skip first header row)
fileName The desired output PDF file name.  This value is also used in case the imposition contains a text mark that includes the file name to embed file names inside the output PDF. 

 

PDF Resource Creation Example:

{
	"templateResourceId ": "31caa24c-9605-4f8b-8666-7464da770621",
	"dataResourceId": "4711c459-f9d3-4039-bf09-23f7cc668c03",
	"impositionTemplateResourceId": "3b7ce4e1-30a3-4697-815f-b4d5335f1134",
	"assetsLibraryResourceIdCollection": {
		"resourceIds": [
			"c9e800b3-7f73-46cf-b564-2f31477224f2",
			"8277794b-1ce1-44ea-a75d-48a2f0acec35"
		]
	},
	"applyImposition": true,
	"recordsRange": {
		"from": 5,
		"to": 10
	},
	"clientTimestampInMilliseconds": 1556111307123,
	"skipRecords": 1
}

Note – Records range can be used for performance purposes. The client can create the Input Resources once and then create multiple PDF Output Resources, each with different ranges from the data file. Since we enable up to 3 PDFs processing in parallel, the client can achieve x3 processing speed if receiving multiple PDF outputs at one time with different records is acceptable.

 

Properties for Sample Resource Creation
Property Name Description
templateResourceId A reference to VDP template resource to be used for PDF creation (UUID)
dataResourceId A reference to data resource to be used for PDF creation (UUID)
impositionTemplateId (Optional) A reference to imposition template resource to be used for PDF creation (UUID)
assetsLibraryResourceIdCollection (Optional) A collection of asset library references to be used for PDF Creation - collection ofject with ID array (UUIDs)
clientTimstampInMilliseconds (Optional) Client time in milliseconds.  For imposition with time text mark embedding time of creation inside PDF graphics
skipRecords (Optional) amount of records to skip from the beginning of a data resource (i.e. Skip first header row)
requiredObjectType Either 'ImposedSpread' or "NonImposedPageRecord'.  Imposed spread is available only in the case that there is an imposition template embedded or when an Imposition Template Resource is referenced.
requiredPageRecord

For non-imposed objects (requiredObjectType = 'NonImposedPageRecord'), this value will contain the number of requested pages and records to generate these pages.  This object contains the following properties:

  1. recordNumber - the record number from the data file to use
  2. pageNumber - the page number(s) from the VDP Template (can be more than one page when VDP template has multiple pages)
requiredSpreadNumber

In case the required sample is for an imposed spread, place the number of the required spread here - note that the number represents an imposed PDF usually containing many record pages on each spread.

To determine the number of imposed spreads to expect the sample Resource can ouptut metadata with information on the total number of sheets.  See queryMetadata

outputFormat Either 'JPEG' or 'PDF' 
pdfFileName When using imposition with text marks that include the file name, this will be be used to set the file name.
queryMetadata Boolean value indicating whether result should include information on overall number of sheets and whether job is duplex is or not. Relevant only in cases of imposed spread sample requests ("requiredObjectType": "ImposedSpread")
deviceScreenHeight When selecting JPEG as an output format, deviceScreen can be used to define the screen size (in pixels) to adjust the file size.
deviceScreenWidth When selecting JPEG as an output format, deviceScreen can be used to define the screen size (in pixels) to adjust the file size.
fileName The desired file name at the output (e.g. "myPageThumbnail.jpg")

 

Example – request for specified page\record with JPEG output format:

{
	"templateResourceId ": "31caa24c-9605-4f8b-8666-7464da770621",
	"dataResourceId": "4711c459-f9d3-4039-bf09-23f7cc668c03",
	"impositionTemplateResourceId": null,
	"assetsLibraryResourceIdCollection": {
		"resourceIds": [
			"c9e800b3-7f73-46cf-b564-2f31477224f2",
			"8277794b-1ce1-44ea-a75d-48a2f0acec35"
		]
	},
	"clientTimestampInMilliseconds": 1556111307123,
	"skipRecords": 1,
	"requiredObjectType": "NonImposedPageRecord",
	"requiredPageRecord": {
		"pageNumber": 1,
		"recordNumber": 30
	},
	"requiredSpreadNumber": null,
	"outputFormat": "JPEG",
	"deviceScreenHeight": 1920,
	"deviceScreenWidth": 1080,
	"pdfFileName": "myPdf.pdf",
	"fileName": "myThumbnail.jpg",
	"queryMetadata": null
}

Note - impositionTemplateResourceId and requiredSpreadNumber are not relevant for non-imposed JPEG output. 

Example – request for specified page\record with PDF output format:

{
	"templateResourceId": "31caa24c-9605-4f8b-8666-7464da770621",
	"dataResourceId": "4711c459-f9d3-4039-bf09-23f7cc668c03",
	"impositionTemplateResourceId": "d0a99cad-5ed8-42c7-8397-565c6273f8a0",
	"assetsLibraryResourceIdCollection": {
		"resourceIds": [
			"c9e800b3-7f73-46cf-b564-2f31477224f2",
			"8277794b-1ce1-44ea-a75d-48a2f0acec35"
		]
	},
	"clientTimestampInMilliseconds": 1556111307123,
	"skipRecords": 1,
	"requiredObjectType": "ImposedSpread",
	"requiredPageRecord": null,
	"requiredSpreadNumber": 5,
	"outputFormat": "PDF",
	"deviceScreenHeight": null,
	"deviceScreenWidth": null,
	"pdfFileName": "myPdf.pdf",
	"fileName": "myPdf.pdf",
	"queryMetadata": true
}

Note - requiredPageRecord, deviceScreenHeight and deviceScreenWeight are not relevant for imposed PDF output.

 

Output Resource Processing

Similar to Input Resources, once an Output Resource gets to its turn, the output PDF status is set to Processing.


Processing time can take no more than 6 hours. Once 6 hours reached, the resource status will go to Error.

 

Output Resource Ready

Once processing completes successfully and the result is ready, the status of the resource changes to a Ready state.

 

The Resource can stay in a Ready state for limited time. In case of Sample Resource – up to 24 hours and in case of PDF Resource up to 1 week.

Getting Output Resource and Downloading Result file

At any given time and state the client can get the resource and check its status.

GET …/composer/sdk/v1/{Resource Name}

The structure of the resource is similar to Input Resources. Any property defined by the client is located at the root, while any output value set by the server is placed under the output object.

{
	"inputProp1": "value",
	"inputProp2": "value",
	"output": {
		"resourceId": "a68a055e-c192-4757-aced-64bb4b40cfd9",
		"status": "Ready"
	}
}

 

Beyond common output properties, the following are special output properties given with Output Resources. The common output properties will be discussed later in this document.

Resource Property Name Description
Sample and PDF downloadUrl URL for downloading the processed file once the Resource is in a Ready status.  Each GET call would generate a new URL which is valid for 24 hours from the time of the API call.
Sample duplex

Boolen value indicating whether job is duplex. Value is provided when queryMetadata property is set to true when creating the resource.  Value is driven by imposition whether it is embedded or overriden.

Sample totalNumberOfSheets

For imposed spread sample if queryMetadata property is set to true then this value will include the total number of sheets after imposition.

Note - in the case of duplex jobs total number of spreads will be this number multiplied by 2.

 

Once the resource is available, the downloadUrl includes a URL address which can be used to download the output file.

 

Output Resource Error

 

Input Resources can get to an Error status from Waiting or Processing state. A PDF resource can be in an Error state for up to 7 days while a Sample Resource can be in an Error state up to 24 hours. Once the expiration time is reached, the resource is automatically deleted.

Common Output Properties

As described earlier in the document, all resources have output objects, including properties, set by the server. The following are the output properties commonly used for all resources.

Property Name Description Comments
resourceId Resource ID (UUID) Reference ID of the resource
status State of the Resource Values are: "Created, "Waiting", "Processing", "Ready", "Error"
errorType String containing possible error values See errorType values table below
expirationTime Resource expiration time (when resource will be automatically deleted).  Represented by Epoch time in Milliseconds Values determined by resource state.  See tables above for details
warningMessages Array of human-readable warning messages (English)

example: "template is missing font..."

Available for Template Sample and PDF resources.

errorMessages Array of human-readable error messages (English)

e.g. "mosaic missing seed..."

Available for Template, Sample and PDF resources.

startWaitingTime Time when Waiting state started.  Epoch time in Milliseconds Not relevant for Assets Library and Imposition Template resources
startProcessingTime Time when Processing state started.  Epoch time in Milliseconds Not relevant for Assets Library and Imposition Template resources
endProcessingTime Time when Processing state ended.  Epoch time in Milliseconds Not relevant for Assets Library and Imposition Template resources
resourceCreationTime Time when the resource was created.  Epoch time in Milliseconds  

 

errorType possible values

Note – the below table describes some of the possible error types. The values may be extended within the same API version.

Value Description
TimeoutByBackend Different components participate in processing PDF, Sample and Template Resources.  This value indicates the Composer Service has timed out during processing
NoChannels

Some HPD file smight be created with no VDP channels.  Composer Service does not support templates of this type.

OutOfQuota The quota of resources permitted in a given time period has been exceeded.  See eCommerce section for details on record processing limits.
TemplateResourceMissing A template resource needed to process this job is missing.  Relevant for Sample and PDF resources
TemplateResourceNotReady A resource referenced in the template resource is not in a Ready state.  Relevant for Sample and PDF resources.
TemplateUnableToLocateReference

Reference to template resource given in the template is not in a Ready state.  Relevant for Sample and PDF resources.

TemplateResourceNotFound A reference to a template resource cannot be located, possibly due to deletion.  Relevant for Sample and PDF resources.
ImpositionTemplateResourceNotReady Provided imposition template resource is not in a Ready state.  Relevant for Sample and PDF resources.
ImpositionTemplateResourceNotFound

Provided imposition template resource could not be found, possibly due to deletion.  Relevant for Sample and PDF resources.

DataResourceMissing A data resource is required and was not provided.  Relevant for Sample and PDF resources.
DataResourceNotReady A data resource is not in a Ready state.  Relevant for Sample and PDF resources.
DataResourceNotFound A data resource cannot be found, possibly due to deletion.  Relevant for Sample and PDF resources
SpreadIncorrectObjectRequestNoImposition Sample request made for a spread, but no imposition template was provided.  Invalid use case.
AssetsLibraryResourceNotReady Assets Library resource was not ready at time of processing
AssetsLibraryResourceNotFound Asslets Library resource was unable to be found by the server.
OutOfBoundRange The requested Spread, Page or Record was out of bounds for this document
RichTemplateWithImpositionSampleIsNotSupported Imposed Spreads are not supported for Rich templates.  This is an invalid request.
HpdExtractFailed Failed to extract the HPD file (unzip failed)
HpdExtractTimeout Extraction of the HPD file timed out (unzip)
ErrorHpdExtract Failed to properly extract the HPD file (unzip failed)
FailedToDownloadAssetsLibrary One or more Asset Libraries failed to download.
ErrorAssetsLibraryExtract Failed to extract Assets Library (unzip failed)

 

Lifespan

Each resource has a certain lifespan with a given expiration based on the state which changes and resets at the time of any state change. For example, a PDF in Processing state with 3H left until expiration that moves to Ready has a new expiration lifespan of 7D.

Resource State Lifespan
Template, PDF, Data, Asset Library, Imposition Template Created

24H

  Waiting 7D
  Processing 6H
  Ready 7D
  Error 7D
Sample Created 24H
  Waiting 24H
  Processing 6H
  Ready 24H
  Error 24H

 

Touch – extend lifespan

Clients can extend the lifespan of resource by calling the touch API on resource in Ready state only.

Once the touch API is called, the lifespan resets to the duration listed in the lifespan table for that resource.

POST …/composer/sdk/v1/{Resource Name}/lifespan

 

Presigned URL Lifespan

Any pre-signed upload or download URL is limited to 24 hours. A new URL with a 24 hour download timeframe is generated for Ready state PDF and Sample resources every time the client calls to the GET API.

Number of Resource Limitation

Number of overall resources is limited per resource type. Once the limit is reached, new resource creations are blocked.

Resource Limit
Template 500
Data 5000
Imposition Template 500
Assets Library 100
Sample 5000
PDF 5000

 

Delete

While servers clean up resources according to their lifespan, clients can clean up resources as well using the Delete API.

Clients might want to delete resources when they reach their resource limits (per resource type) in order to free up slots for new resources.

POST …/composer/sdk/v1/{Resource Name}/delete

{
	"resourceIds": [
		" 120acb03-1e9d-46b7-b2df-67342d0e1a77",
		" 120acb03-1e9d-46b7-b2df-67342d0e1a77"
	]
}

Note - deleting a PDF during processing aborts the server-side processing, and refunds the records to the monthly records quota – see eCommerce.

eCommerce

PrintOS Composer Service enables organizations to compose up to 10000 free records per month.

The organization account can purchase a subscription for more records quota per month from the PrintOS Marketplace app.

Note – Composer Service count together records usage composed from both the UI PrintOS Composer app and via the SDK.

The usage counting reduces the records quota once a PDF starts processing. If the processing ends with an error or is deleted before the PDF is ready, the quota is refunded according to the number of records given at the Data resource.

Resource Visibility at Composer App UI

Resources uploaded or generated by the SDK APIs do not appear in the PrintOS Composer application.