PrintOS Composer Overview

Introduction to the PrintOS Composer API 

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

The client SW combines a graphic template and 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.

VDP Template

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

Copy Code

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

Composed PDF

 

The client can repeat the process each time using different data file inputs and obtain 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, Composer also enables applying imposition with records distribution or for PDF input file.

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 is in Excel, although 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.

PDF Input 

Composer also supports imposition for PDF input file. 

When imposing a PDF input file, Composer service will generate an output PDF with the PDF input pages distributed by the attached imposition (see imposition template)

Assets Library

As mentioned, a 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. 

PDF Preset

Composer supports PDF presets files that apply custom settings to the output PDF file such as PDF compatibility and optimization.

A PDF preset file can be attached separately, or it can be selected from a predefined list of preloaded preset. 

There are 2 types of PDF presets –

1. FPP file for fast processing mode. 
   1. The file is created by PrintOs under “Presets” section.
2. JOBOPTIONS file for rich processing mode.
   1. The file is created by Adobe InDesign app.

API Details

Authentication – HMAC

Composer Service authenticates the client using an HMAC Key and Secret. PrintOS supports SHA256

The HMAC Key and Secret should be generated by the 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 of the user. Users who have several organizations/accounts should pay attention to which organization/account is being used when generating the HMAC Key and Secret.

NOTE – PrintOS Composer manages tenants of the PrintOS Organization. For example, a Printshop is one organization/account in 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 they do not break existing behaviour 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
   5. PDF preset Resource – for fpp or joboptions PDF presets files.
   6. PDF input Resource – for PDF input file 
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 

 

Input Output Resources

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
PDF preset Resource	.../composer/sdk/v1/pdf-preset	Input
PDF Input Resource	.../imposer/sdk/v1/pdf-input	Input
Sample Resource	.../composer/sdk/v1/sample	Output
PDF Resource	.../composer/sdk/v1/pdf	Output
Imposed Sample Resource	.../imposer/sdk/v1/impose-sample	Output
Imposed PDF Resource	.../imposer/sdk/v1/impose-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 a CSV file or TXT file with tab delimiter
   3. Create Imposition Template (optional)
      1. Upload and attach to it an IMPP file
   4. Create Assets Library Resource (optional)
      1. Upload and attach a ZIP file to it with variable images
   5. Create PDF preset Resource (optional)
      1. Upload and attach a FPP or JOBOPTIONS file
   6. Create PDF input Resource (for imposition purposes) 
      1. Upload and attach a PDF file 
2. Create Output Resources and download resulting files
   1. Create Sample Resource
      1. Reference appropriate resources (template, imposition template, data and assets library) for composition or (imposition template, PDF input) for imposition
      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 template, data and assets library) for composition or (imposition template, PDF input) for imposition
      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 of importance.

 

Input Resources

The following sections will discuss Input Resources.

Input Resources Creation

The first step for every resource would be its creation. Creation is done using a POST method on the following URLs. More details can be found in 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)
PDF preset	.../composer/sdk/v1/pdf-preset	filename – the name of the PDF preset file
PDF input	.../imposer/sdk/v1/pdf-input	filename – the name of the input PDF file

 

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

Copy Code

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”.

00_ResourceCreated.png

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 the server is placed under the output property object.

Copy Code

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 – If the file is not supplied and fully uploaded within 24 hours from resource creation time, the resource will be deleted automatically.

The Composer API enables 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 a pre-signed PUT URLs, specify the overall file size and the desired part/chunk size for upload – the amount of pre-signed 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 fails, 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.

 

File Part Transfer

 

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

 

 

Input Resource Waiting and Processing

01_InputResourceWaitingandProcessing.png

Once a resource is created and its related file is uploaded, the resource status automatically changes 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 is 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 a 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.

Copy Code

Input Resource Ready

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

02_InputResourceReady.png

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:

Copy Code

Note – Input Resource can be in a Ready state for 7 days. Once 7 days pass, 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 it is automatically deleted.

03_InputResourceError.png

  

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 is 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 specific page/record or spread in case imposition is applied - outputs a PDF or JPEG per client choice
Imposed PDF	…/imposer/sdk/v1/impose-pdf	For a PDF with imposition
Imposed Sample	…/imposer/sdk/v1/impose-sample	For sample of imposed spread. The client can ask for specific spread - outputs a JPEG file

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.

00_OutputResourceWaiting.png

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)
engineMode	(Optional) Whether to use Fast or Rich processing mode
pdfPresetResourceId	(Optional) A reference to the PDF preset resource to be used for PDF creation
predefinedPdfPresetName	(Optional) A predefined PDF preset name to be used for PDF creation
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.
numberOfChunkedProcessing	(Optional) Enable client to specify whether to process the job in multiple parallel chunks for faster processing of the job. If given, the value must be a number between 2 and maximum of 100. Each chunk contains certain records range from the given data file, while all chunks together include all records. Note – Number of possible chunks processing takes imposition (if it exist) under consideration and for that, in some cases, while the client asks for certain number of chunks, the actual number of chunks may increase by 1. When processing of all chunks is complete, the final output is assembled to a single file – see property chunkedProcessingMergeFormat. There are performance considerations for parallel chunk processing – too many chunks for a smaller data file may result in performance degradation due to resulting merging process.
chunkedProcessingMergeFormat	(Optional) relevant in case numberOfChunkedProcessing is defined with some number. Using this property, the client can specify how to assemble the resulting chunks – there are two options to this property, either set to  “PDF” or “ZIP”. In case of PDF, the output is a single PDF file concatenating the chunks – output us the same result as in non-chunked processing. In case of “ZIP” the output includes a single ZIP file containing many PDF chunks. If numberOfChunkedProcessing is defined, and this property is not given, the “PDF” format will be used as default.

 

PDF Resource Creation Example:

Copy Code

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 processing of up to 3 PDFs in parallel, the client can achieve x3 the processing speed if receiving multiple PDF outputs at one time with different records is acceptable.

Another option of using the advantage of parallel processing is the use of Chunked Processing. Chunked processing makes it easier for client to process many different chunks of the data file without the need to create many PDF resources with different ranges for each one. Instead, the client may specify how many chunks are desired and the system will accordingly automate the chunking process. When all chunks are ready, the Service merges all chunks to either a single PDF (concatenating the chunks) or a ZIP file containing many PDF chunks.

Maintaining many chunks in a ZIP file may be an advantage in the case where overall RIP time is long when being sent as a single PDF. Using many smaller PDFs enables RIP while print.

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)
engineMode	(Optional) Whether to use Fast or Rich processing mode
pdfPresetResourceId	(Optional) A reference to the PDF preset resource to be used for PDF creation
predefinedPdfPresetName	(Optional) A predefined PDF preset name to be used for PDF creation
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: recordNumber - the record number from the data file to use 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 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:

Copy Code

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

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

Copy Code

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

 

 

Properties for Imposed PDF Resource Creation

Property Name	Description
impositionTemplateResourceId	A reference to the imposition template resource to be used for imposed PDF creation (UUID)
pdfInputResourceId	A reference to the PDF input resource to be used for imposed PDF creation (UUID)

 

PDF Resource Creation Example:

Copy Code

Properties for imposed Sample Resource Creation

Property Name	Description
impositionTemplateId	A reference to the imposition template resource to be used for Imposed sample creation (UUID)
pdfInputResourceId	A reference to the PDF input resource to be used for imposed sample creation (UUID)
sheetNumber	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 output metadata with information on the total number of sheets.  See queryMetadata
pdfFileName	When using imposition with text marks that include the file name, this will be used to set the file name.
fileName	The desired file name at the output (e.g. "myPageThumbnail.jpg")

 

Example – request for specified sheet:

Copy Code

 

Output Resource Processing

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

04_OutputResourceProcessing.png

Processing time can take no more than 6 hours. Once 6 hours have passed, the resource status goes to Error.

 

Output Resource Ready

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

05_OutputResourceReady.png

 

The Resource can stay in a Ready state for a 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.

Copy Code

 

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 generates a new URL which is valid for 24 hours from the time of the API call.
PDF	progress	PDF/ZIP processing progress in percentage. The progress may not be accurate and therefore time to completion should not be concluded from this parameter.
PDF	warningCsvReportUrl	While warningMessages output property may include a partial list of overall PDF/ZIP warnings, this property supplies the URL for downloading full warning report in CSV format.
Sample	duplex	Boolean value indicating if a 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

06_OutputResourceError.png

 

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 files might be created with no VDP channels.  Composer Service does not support templates of this type.
OutOfQuota	The quota of resources permitted during 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	Assets Library resource was unable to be found by the server.
PdfPresetResourceNotReady	PDF Preset resource was not ready at the time of processing
PdfPresetResourceNotFound	PDF Preset resource was unable to find by the server
PdfInputResourceNotReady	PDF input resource was not ready at the time of processing
PdfInputResourceNotFound	PDF input resource was unable to find 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.
FailCalculatingSplit	PDF with Chunked processing is unable to calculate splitting. Could be a temporary problem
FailToMerge	PDF with Chunked processing failed at merging stage - Could be a temporary problem.
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, PDF preset, Imposition Template, PDF input	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	10000
Data	10000
Imposition Template	10000
Assets Library	10000
PDF preset	10000
PDF input	10000
Sample	10000
PDF	10000

 

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

Copy Code

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 counts together records usage composed of 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.