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.
Given the following data file (in this case a CSV file)
Copy Code
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 using different data file inputs and obtain different results with different data binding each time.
Composition Features
The composition supports:
- Variable text
- Variable Images based on the image file name within the database
- Variable Barcodes based on text in the data file (Barcode Studio and IDAutomation)
- Variable Maps images based on the address text (locr maps)
- Variable auto-generated images using HP Mosaic and Collage.
- 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:
- Pack the images as part of the template file – HPD file
- 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 –
- FPP file for fast processing mode.
- The file is created by PrintOs under “Presets” section.
- JOBOPTIONS file for rich processing mode.
- 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
- Input Resources
- Template Resource – for HPD graphic VDP template.
- Data Resource – for VDP data input using CSV or TXT (tab delimiter)
- Imposition Template Resource – for IMPP Imposition template file
- Assets Library Resource – for zipping with variable images inside
- PDF preset Resource – for fpp or joboptions PDF presets files.
- PDF input Resource – for PDF input file
- Output Resources
- Sample Resource – by which a client can retrieve a single page\record or spread
- 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 |
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:
- Create Input Resources and upload their related files
- Create VDP Template Resource
- Upload and attach HPD file to it.
- Create Data Resource
- Upload and attach to it a CSV file or TXT file with tab delimiter
- Create Imposition Template (optional)
- Upload and attach to it an IMPP file
- Create Assets Library Resource (optional)
- Upload and attach a ZIP file to it with variable images
- Create PDF preset Resource (optional)
- Upload and attach a FPP or JOBOPTIONS file
- Create PDF input Resource (for imposition purposes)
- Upload and attach a PDF file
- Create VDP Template Resource
- Create Output Resources and download resulting files
- Create Sample Resource
- Reference appropriate resources (template, imposition template, data and assets library) for composition or (imposition template, PDF input) for imposition
- 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).
- Create PDF Resource
- Reference appropriate resources (template, imposition template, data and assets library) for composition or (imposition template, PDF input) for imposition
- Receive a Download Result URL of composed PDF.
- Create Sample Resource
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) |
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
{
"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 the server is placed under the output property object.
Copy Code
{
"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 – 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:
- createPresginedUploadUrls - Generates a pre-signed PUT (upload) URL by calling POST composer/sdk/v1/assets/put-urls
- Upload the file chunks (parts) to presigned URLs.
- uploadCompleted - Complete upload by calling POST composer/sdk/v1/assets/parts
Limits:
- Overall file size is limited to 6GB
- Total number of parts is limited to 10000.
- A part must be at least 5MB and no more than 5GB in size
- 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?
- Performance
- Uploading in parts enables faster upload of big files. The client can implement the upload using parallel parts upload, giving faster upload.
- Robustness
- Overcome network disconnection – in case a part upload fails, the client can attempt to upload it again, overcoming temporary network disconnections
- Better Experience
- 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
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.
- VDP Template Resource – finds number of pages and additional information required for internal server use.
- Data Resource – counts number of records
- 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
{
"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.
- VDP Template Resource
- 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.
- Rich – PDF result would be processed by Adobe InDesign Server using HP SMS Designer plugins – rich graphics.
- Fast – PDF result would be processed by HP’s proprietary VDP engine – faster PDF processing.
- embeddedImpositionExist – tells if the HPD template includes an embedded imposition template packed by Designer for InDesign
- 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.
- 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.
- Data Resource
- 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
{
"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 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.
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 |
|
.../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.
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
{
"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"
]
},
“engineMode”: “Fast”,
“PdfPresetResourceId: “fd78e4e1-30a3-4697-fd42-b4d5335fds34”,
"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 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:
|
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
{
"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"
]
},
“engineMode”: “Fast”,
“PdfPresetResourceId: “fd78e4e1-30a3-4697-fd42-b4d5335fds34”,
"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:
Copy Code
{
"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"
]
},
“engineMode”: “Fast”,
“PdfPresetResourceId: “fd78e4e1-30a3-4697-fd42-b4d5335fds34”,
"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.
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
{
" impositionTemplateResourceId ": "31caa24c-9605-4f8b-8666-7464da770621",
" pdfInputResourceId ": "4711c459-f9d3-4039-bf09-23f7cc668c03",
"outputPdfFile": "myImposedPdf.pdf",
}
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
{
"impositionTemplateResourceId": null,
" pdfInputResourceId ": "4711c459-f9d3-4039-bf09-23f7cc668c03",
"clientTimestampInMilliseconds": 1556111307123,
"sheetNumber": 1,
}
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.
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
{
"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 generates a new URL which is valid for 24 hours from the time of the API call. |
|
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. |
|
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
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 |
|
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
{
"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 counts together records usage composed of both the UI PrintOS Composer app and