-
-
-
REST API Cookbook with Working Examples Version 2021.1 Last Revision: 2021-05-19 Objectif Lune, Inc. 2030 Pie-IX, Suite 500 Montréal, QC, Canada, H1V 2C8 +1 (514) 875-5863 www.objectiflune.com All trademarks displayed are the property of their respective owners.
-
© Objectif Lune, Inc. 1994-2021. All rights reserved. No part of this documentation may be reproduced, transmitted or distributed outside of Objectif Lune Inc. by any means whatsoever without the express written permission of Objectif Lune Inc. Objectif Lune Inc. disclaims responsibility for any errors and omissions in this documentation and accepts no responsibility for damages arising from such inconsistencies or their further consequences of any kind. Objectif Lune Inc.
-
Table of Contents Table of Contents 5 Welcome to the PlanetPress Connect REST API Cookbook 12 Technical Overview 13 Workflow & Workflow Processes Data Mapping Content Creation Job Creation Output Creation All-In-One Input Files Data Entities Data Set & Data Record Entities Content Set & Content Item Entities Job Set & Job Entities Workflow Operations Asynchronous Operations Synchronous Operations JSON Structures Common Structures Specific Structures Working Examples Getting Started Requirements & Inst
-
Uploading a Job Creation Preset to the File Store Uploading an Output Creation Preset to the File Store Working with the Entity Services Finding Specific Data Entities in the Server Finding all the Data Sets in the Server Finding the Data Records in a Data Set Finding all the Content Sets in the Server Finding the Content Items in a Content Set Finding all the Job Sets in the Server Finding the Jobs in a Job Set Working with the Workflow Services Running a Data Mapping Operation Running a Data Mapping Opera
-
All-In-One Service Cancel an Operation Get All Operations Get Managed Result of Operation Get Progress of Operation Get Result of Operation Get Result of Operation (as Text) Process All-In-One (JSON) Process All-In-One (Adhoc Data) Service Handshake Service Version Authentication Service Authenticate/Login to Server Service Handshake Service Version Content Creation (Email) Service Cancel an Operation Get All Operations Get Progress of Operation Get Result of Operation Process Content Creation (By Data) (JS
-
Create Preview PDF (By Data Record) Create Preview PDF (By Data) Create Preview PDF (By Data) (JSON) Create Preview Image (By Data Record) (JSON) Create Preview Image (By Data) (JSON) Get All Operations Get Progress of Operation Get Result of Operation Get Managed Result of Operation Cancel an Operation Service Version Content Item Entity Service Get Content Item Properties Get Data Record for Content Item Service Handshake Service Version Update Content Item Properties Update Multiple Content Item Properti
-
Process Data Mapping (PDF/VT to Content Set) Process Data Mapping (PDF/VT to Data Set) Service Handshake Service Version Data Record Entity Service Add Data Records Get Data Record Properties Get Data Record Values Get Multiple Data Record Values Get Multiple Data Record Values (JSON) Service Handshake Service Version Update Data Record Properties Update Data Record Values Update Multiple Data Record Properties Update Multiple Data Record Values Data Set Entity Service Service Handshake Delete Data Set Enti
-
Service Handshake Service Version File Store Service Service Handshake Download Managed File or Directory Download Contents of Managed Directory Delete Managed File or Directory Get Report List Resources Upload Data File Upload Data Mapping Configuration Upload Template Upload Job Creation Preset Upload Output Creation Preset Service Version Job Creation Service Cancel an Operation Get All Operations Get Progress of Operation Get Result of Operation Process Job Creation Process Job Creation (By Content Set)
-
Get Document Sets for Job Segment Get Job Segment Metadata Properties Service Handshake Service Version Update Job Segment Metadata Properties Job Set Entity Service Service Handshake Delete Job Set Entity Get All Job Sets Get Job Set Metadata Properties Get Job Set Properties Get Jobs for Job Set Service Version Update Job Set Metadata Properties Update Job Set Properties Output Creation Service Service Handshake Process Output Creation (By Job Set) Process Output Creation (By Job Set) (JSON) Process Outpu
-
Welcome to the PlanetPress Connect REST API Cookbook This guide is aimed at technically experienced users who wish to learn and use the REST API available in PlanetPress Connect version 2021.1. The PlanetPress Connect REST API consists of many services that expose access to a number of areas including workflow, data entity management and file store operations.
-
Technical Overview This section provides an overview of the concepts and structures used within PlanetPress Connect and the REST API.
-
Workflow & Workflow Processes The primary workflow in PlanetPress Connect consists of four major processes that each require a number of inputs, and once executed, produce a particular form of output. These processes are: data mapping, content creation, job creation and output creation. There is an additional workflow process, named All-In-One, which embodies all four major workflow processes in a singular process.
-
Data Mapping The data mapping process involves taking a data file or source, applying a data mapping configuration to it, and producing a structured set of data or data records (a data set). This process can also produce a data set or content set from a PDF/VT file using its internal meta data instead of a data mapping configuration.
-
The following diagram illustrates the alternative workflow for the data mapping process when using PDF/VT data files specifically: Page 16
-
Content Creation The content creation process involves taking either a data set or one or more data records (from a data set), combining them with a suitable template, and producing one or more sets of content (content sets). If the content is for the Email or Web context then output can be produced at this stage.
-
The following diagram illustrates the workflow for content creation by Data Record: Page 18
-
The following diagram illustrates the workflow for content creation by JSON Data: Page 19
-
The following diagram illustrates the workflow for content creation of Preview Image, by Data Record: Page 20
-
The following diagram illustrates the workflow for content creation of Preview Image, by JSON Data: Page 21
-
The following diagram illustrates the workflow for content creation of Preview PDF, by Data Mapping: Page 22
-
The following diagram illustrates the workflow for content creation of Preview PDF, by Data Record: Page 23
-
The following diagram illustrates the workflow for content creation of Preview PDF,by JSON Data: Page 24
-
Job Creation The job creation process involves taking one or more content sets and applying a job creation preset for organizing, sorting and grouping them into a set of logical jobs (a job set). This includes the application of data filtering and finishing options.
-
Output Creation The output creation process involves taking either a job set or one or more jobs (from a job set), applying an output creation preset, and producing the print output (Print context).
-
All-In-One The All-In-One process embodies all four major workflow processes (data mapping, content creation, job creation and output creation) in a singular process. It can be configured to run one or more of the four processes, as long as the processes specified result in a logical sequence or workflow. Depending on it's configuration, the All-In-One process can produce either a data set, content sets, a job set or print output (Print context).
-
The following table lists the available processes, input combinations and expected outputs for the All-In-One process: Processes Input Combination Expected Output Data Mapping Only Data File + Data Mapping Configuration Data Set Data Mapping + Content Creation Data File + Data Mapping Configuration + Template Content Set(s) Content Creation Only Data Records + Template Content Set(s) Data Mapping + Content Creation + Job Creation Data File + Data Mapping Configuration + Template Job Set Data
-
Processes Input Combination Expected Output Content Creation + Job Creation + Output Creation Data Records + Template + Output Creation Preset Print Output Content Creation + Job Creation + Output Creation Data Records + Template + Job Creation Preset + Output Creation Preset Print Output Output Creation Only Jobs + Output Creation Preset Print Output Page 29
-
Input Files Input files are used as input to a specific workflow process. The following table lists the types of input files used in the PlanetPress Connect workflow: Name Relevant Workflow Process Data File Data Mapping Data Mapping Configuration l Promo-EN-10.csv l Promo-EN-10000.csv (& Content Creation for PDF Preview) l PDFVT-Data.
-
Data Entities There are many data entity types used by PlanetPress Connect, but not all data entities can be accessed through the REST API. The main data entities to be aware of when working with the API are: l Data Sets l Data Records l Content Sets l Content Items l Job Sets l Jobs Data Set & Data Record Entities The data set is the artefact produced by a data mapping operation. It holds the data that was mapped out of the input data file.
-
The data set and data record entities (shown above in blue) are accessible via the Data Set Entity and Data Record Entity services. Content Set & Content Item Entities The content set is the artefact produced by a content creation operation. It holds all the pages that were produced by the operation. A content creation operation produces one or more content sets, which contain as many content items as there were data records given at the start of the operation.
-
single content item. Hence, at the job creation level, a document may consist of one or more content items. The following diagram illustrates the basic relationship between these entities in the context of the job creation process: The job set and job entities (shown above in blue) are accessible via the Job Set Entity and Job Entity services.
-
In summary, the following diagram illustrates the basic relationship between all data entities in the overall context of the primary workflow in PlanetPress Connect: Page 34
-
Workflow Operations Each individual process in the overall workflow can potentially be a long running operation.
-
A request made to the cancel URI during processing will immediately cancel the operation. A request made to the result URI after processing has completed will return the final result of the operation. This is the default workflow operation type, and this approach is used across most workflow based services as demonstrated in the Working with the Workflow Services page of the Working Examples section.
-
JSON Structures The PlanetPress Connect REST API uses various JSON structures to describe certain inputs and outputs to resource methods.
-
-
Common Structures Common JSON structures used in the PlanetPress Connect REST API include the following: l "JSON Error" below l JSON Identifier l JSON Identifier List l JSON Name/Value List (Properties Only) l JSON Name/Value List l JSON Name/Value Lists JSON Error Describes an error response returned from the Connect server.
-
JSON Identifier Describes an identifier for a single data entity in PlanetPress Connect.
-
JSON Identifier List Describes a list of identifiers for multiple data entities in PlanetPress Connect.
-
JSON Name/Value List Describes a list of properties (each as a name/value pair) for a data entity of a specific ID.
-
JSON Name/Value List (Properties Only) Describes a list of properties (each as a name/value pair).
-
JSON Name/Value Lists Describes multiple lists of properties (as name/value pairs) for data entities of a specific ID. Structure The structure consists of an array of JSON Name/Value List structure objects.
-
Specific Structures Specific JSON structures used in the PlanetPress Connect REST API include the following: l JSON All-In-One Configuration l "JSON Bitmap Parameters" on page 51 l JSON Content Item Identifier List l JSON Data Mapping Validation Result l JSON Data Record Identifier l JSON Data Record Identifier List (with Parameters) l JSON Email Output List l JSON Email Parameters (with Runtime Parameters) l JSON HTML Parameters l JSON HTML Parameters (with Runtime Parameters) l "JSON
-
l JSON Record Content List (Fields Only) l JSON Record Content Lists l JSON Record Content Lists (Explicit Types) l JSON Record Content Lists (Fields Only) l JSON Record Data List l JSON Record Data List (with Email Parameters) l JSON Record Data List (with Image Parameters) l JSON Search Parameters Page 46
-
JSON All-In-One Configuration Describes the configuration of an All-In-One operation as a series of name/value pairs representing the processes (data mapping, content creation, job creation and output creation) to be completed as part of the overall operation. The value in each pair contains the parameters for that specific process.
-
l jobcreation – job creation configuration parameters, consisting of an object with the following name/value pairs: l l config – the managed file identifier (type of number) or named identifier (type of string) of the job creation preset (optional) parameters (optional) – a set of runtime parameter names and their corresponding values, consisting of an object with one or more name/value pairs: l l – the name (name) and the value of the runtime parameter (type of either string, number, or boole
-
{ "identifier": "Promo-EN-1000.csv", "config": "Promo-EN.OL-datamapper", "parameters": { "Gender": "Female" } }, "contentcreation": { "config": "letter-ol.OL-template", "parameters": { "InvoiceDueDate": "2020-03-10", } }, "jobcreation": { "config": "4567", "parameters": { "TrackingId": "20211" } }, "outputcreation": { "config": "5678", "createOnly": true }, "printRange": { "printRange": "1-3, 6, 10" } } { "contentcreation": { "identifiers": [ 34567, 34568 ], "config": "letter-ol.
-
{ "config": "5678", "createOnly": false } } { "datamining": { "identifier": "12345", "config": "23456" } } { "datamining": { "identifier": "Promo-EN-1000.csv", "config": "Promo-EN.OL-datamapper", "persistDataset": false }, "contentcreation": { "config": "letter-ol.OL-template" }, "jobcreation": {}, "outputcreation": { "config": "5678", "createOnly": false } } { "contentcreation": { "identifiers": [ 34567, 34568 ], "config": "letter-ol.
-
"parameters": { "FirstName": "Benjamin", "InvoiceDueAmount": 123.45, "InvoiceDueDate": "2020-03-10", "InvoiceOverdue": true } }, "outputcreation": { "config": "5678", "createOnly": false } } JSON Bitmap Parameters Describes a list of parameters used specifically in the rasterization of a PDF, PS, AFP or PCL file, defining which pages of the source file have to be converted to a bitmap and the properties of the resulting bitmap(s).
-
Specific to parameters with a type parameter specified to a value of jpg, the following optional name/value pair can be specified: l quality – the image quality of the preview (value ranging from 0-100) (type of number – Default value of 100) Example The following is an example of this structure: { "type": "png", "dpi": 150, "archive": true, "pages": "1,3,6-11" } { "type": "jpg", "quality": 90 } Page 52
-
JSON Content Item Identifier List Describes a list of content item/data record entity identifier pairs (as name/value pairs) for a specific content set or job entity.
-
JSON Data Mapping Validation Result Describes the result of a request to validate a data mapping operation, including a list of any errors that occurred (used specifically with the Data Mapping service).
-
JSON Data Record Identifier Describes a single data record entity identifier for a specific content item entity.
-
JSON Data Record Identifier List (with Parameters) Describes a list of identifiers for multiple data entities (specifically data record entities), along with additional parameters. It is used specifically with the Data Record Entity service as input to the Get Multiple Data Record Values (JSON) resource method. The value of the explicitTypes parameter determines if the result returned is either a JSON Record Content Lists or JSON Record Content Lists (Explicit Types) structure.
-
o subject – the subject of the email message (type of string) o to – the email addresses of the recipients in the email message (type of string) o body – the name of the HTML email body file in the email message output (type of string) o folder – the managed file ID for the output directory in the file store containing the email message output (type of number) o attachments – a list of the file attachments to the email message, consisting of an array of objects each with the following name/value p
-
l errors – a list of any errors that occurred during content creation, consisting of an array of objects each with the following name/value pairs: l o record –the data record index associated with the error (type of number) o message –the description of the error that occurred (type of string) contentSet – the content set entity identifier for the email output (type of number) Examples The following is an example of this structure: { "messages": [ { "attachments": [ { "name": "att97529c81-f882-4c21
-
"name": "att4c7f31d9-d512-42b6-b0a96e120c07701f.png", "disposition": "inline" }, { "name": "att80b0c7c4-6aaf-45b8-b559b5f0e3c4e378.png", "disposition": "inline" }, { "name": "att7d18e853-8013-46c3-819a2efdad883a10.png", "disposition": "inline" }, { "name": "John, gain complete control!.html", "disposition": "attachment" } ], "subject": "John, gain complete control!", "to": "k.snell@drupa.ol.com.com", "folder": 12345, "eml": "63cb15da-42be-4dd8-88e3-367e0f3c9fec.
-
"name": "att9eb5d506-f9ac-4df0-9b72e164f4dd1237.png", "disposition": "inline" }, { "name": "att357f4a10-047c-45a7-b2920862bd50979d.png", "disposition": "inline" }, { "name": "att335b33e2-4ca1-4d2f-a7ea06ca96c1544b.png", "disposition": "inline" }, { "name": "att48c026ef-0bdc-4709-ac71eea25ec5f137.png", "disposition": "inline" }, { "name": "att063ad47c-dc26-4105-b0139dacb4e47718.png", "disposition": "inline" }, { "name": "Kristopher, gain complete control!.
-
JSON Email Parameters (with Runtime Parameters) Describes runtime parameters and parameters used specifically in an content creation operation for email. This structure is variable, allowing specification for email output to either the File Store or directly to a SMTP mail server, with a number of additional parameters.
-
Specific to email output directly to a SMTP mail server with the useAuth parameter specified to a value of true, the following optional name/value pairs can be specified: l user – the user name to authenticate with (type of string) l password – the password to authenticate with (type of string) l useStartTLS – parameter to specify if Transport Layer Security (TLS) is to be opportunistically used when sending emails (type of boolean) Specific to email output to the File Store, an optional name/value pa
-
"user": "johns", "password": "password5", } { "identifiers": [ 12345, 23456, 34567 ], "attachWebPage": true, "sender": "jane.smith@company.
-
JSON HTML Parameters Describes a list of parameters used specifically in the creation of web content.
-
l parameters – a set of runtime parameter names (defined in the template) and their corresponding values, consisting of an object with one or more name/value pairs: l – the name (name) and the value of the runtime parameter (type of either string, number, or boolean) Example The following are examples of this structure: { "section": "Section 1", "inline": "ALL" } { "section": "Section 2", "cssSelector": "#salutation" } JSON Identifier (for Content Creation) Describes an identifier for a data mapp
-
Example The following is an example of this structure: { "identifier": 12345, "defaults": { "duplex": "true", "tumble": "true" } } Page 66
-
JSON Identifier (Managed File) Describes an identifier or named identifier for a single managed file in PlanetPress Connect. Structure The structure consists of an object with a single name/value pair: l identifier – the managed file identifier (type of number) or named identifier (type of string) Example The following are examples of this structure: { "identifier": 12345 } { "identifier": "Promo-EN-1000.
-
JSON Identifier (with Output Parameters) Describes an identifier for a single job set entity, along with additional parameters used specifically in an output creation operation.
-
{ "identifiers": [ 12345, 23456, 34567 ], "parameters": { "FirstName": "Benjamin", "InvoiceDueAmount": 123.
-
JSON Identifier List (with Email Parameters) Describes a list of identifiers for multiple data entities (specifically data record entities), along with additional parameters used specifically in an content creation operation for email. This structure is variable, allowing specification for email output to either the File Store or directly to a SMTP mail server, with a number of additional parameters.
-
l useAuth – parameter to specify if authentication is to be used with the mail server (type of boolean) Specific to email output directly to a SMTP mail server with the useAuth parameter specified to a value of true, the following optional name/value pairs can be specified: l user – the user name to authenticate with (type of string) l password – the password to authenticate with (type of string) l useStartTLS – parameter to specify if Transport Layer Security (TLS) is to be opportunistically used wh
-
"sender": "john.smith@company.com", "useSender": true, "host": "mail.company.com", "useAuth": true, "user": "johns", "password": "password5", } { "identifiers": [ 12345, 23456, 34567 ], "attachWebPage": true, "sender": "jane.smith@company.
-
JSON Identifier List (with Output Parameters) Describes a list of identifiers for multiple job entities, along with additional parameters used specifically in an output creation operation.
-
Example The following is an example of this structure: { "identifiers": [ 12345, 23456, 34567 ] } Page 74
-
JSON Identifier Lists (with Sort Key) Describes a set of search results as a list of one or more sub lists, each containing a list of data entity identifiers along with a sorting key value for each entry. Used specifically with the Entity service as the output from the Find Data Entity resource method, this structure groups the data entity identifiers returned into sortable sub lists of entries.
-
{ "identifier": 1121, "sortkey": "SK|Rachel" } ] ] JSON Image Parameters Describes a list of parameters used specifically in the creation of a preview image of content for print, email or web. This structure is used specifically by the Content Creation service when creating preview images.
-
Specific to parameters with a context parameter specified to a value of print, the following optional name/value pair can be specified: l l bleed – whether to include the bleed area in the preview (type of boolean – Default value of false) pages – the page range to be output in the preview (type of string – Default value is determined by the value of the archive parameter. If the archive parameter is specified to false, then the default value will be 1.
-
"quality": 90 } Page 78
-
JSON Job Set Structure Describes a job set entity structure including the arrangement of job, job segment, document set, document and content item entities (including the specification of content item identifiers). Used specifically in a job creation operation.
-
}, { "contentitem": 2345 } ] }, { "documentpages": [ { "contentitem": 3456 } ] } ] } ] } ] }, { "segments": [ { "documentsets": [ { "documents": [ { "documentpages": [ { "contentitem": 4567 } ] } ] } ] } ] } ] } Page 80
-
JSON New Record List Describes a list of new data records (and their data field values (as name/value pairs)) to be added as data record entities to either an existing data set or data record entity of a specific ID.
-
{ "name": "Gender", "value": "M.
-
{ "name": "ItemNumber", "value": "PSM002" }, { "name": "ItemDesc", "value": "PSM Production (unlimited)" }, { "name": "ItemUnitPrice", "value": "495.00" }, { "name": "ItemOrdered", "value": "2" }, { "name": "ItemTotal", "value": "990.00" } ] }, { "fields": [ { "name": "ItemNumber", "value": "PSM005" }, { "name": "ItemDesc", "value": "Upgrade (Starter to Web)" }, { "name": "ItemUnitPrice", "value": "495.00" }, { "name": "ItemOrdered", "value": "1" }, { "name": "ItemTotal", "value": "495.
-
} ] } ] } Page 84
-
JSON New Record Lists Describes multiple lists of new data records (and their data field values (as name/value pairs)) to be added as data record entities to either existing data set or data record entities of a specific ID. Structure The structure consists of an array of JSON New Record List structure objects. Example The following is an example of this structure: [ { "datasetid": 12345, "records": [ { "fields": [ { "name": "ID", "value": "CU00048376" }, { "name": "Gender", "value": "M.
-
"value": "CU01499303" }, { "name": "Gender", "value": "Miss" }, { "name": "FirstName", "value": "Dianne" }, { "name": "LastName", "value": "Straka" } ] } ] }, { "recordid": 12345, "table": "detail", "records": [ { "fields": [ { "name": "ItemNumber", "value": "PSM002" }, { "name": "ItemDesc", "value": "PSM Production (unlimited)" }, { "name": "ItemUnitPrice", "value": "495.00" }, { "name": "ItemOrdered", "value": "2" }, { "name": "ItemTotal", "value": "990.
-
} ] }, { "fields": [ { "name": "ItemNumber", "value": "PSM005" }, { "name": "ItemDesc", "value": "Upgrade (Starter to Web)" }, { "name": "ItemUnitPrice", "value": "495.00" }, { "name": "ItemOrdered", "value": "1" }, { "name": "ItemTotal", "value": "495.
-
JSON Operations List Describes a list of workflow operations (specifically asynchronous workflow operations) actively running on the server, each containing various properties including the type of workflow operation, it's starting time and it's current progress value. This structure is used specifically with workflow based services including the Data Mapping, Content Creation, Content Creation (Email), Job Creation, Output Creation and All-In-One services.
-
[ { "id": "1281ef9d-7a74-4448-9adf-175a0166f32e", "type": "DataMiningRestService", "subTask": "Extracting data 25%", "startTime": 1482367446908, "progress": 100 }, { "id": "b72e2da5-39ea-48de-85cf-a2be321a71bd", "type": "ContentCreationRestService", "subTask": "Content Creation", "startTime": 1482367988332, "progress": 12, "template": "business-card-ol" }, { "id": "134f55a5-85f5-41d5-a0d3-e033eda45cb5", "type": "EmailExportRestService", "startTime": 1482368638197, "progress": 5 }, { "id": "d52cf2b6-9ca7-44e
-
} ] Page 90
-
JSON Page Details List Describes a list of the page details and identifiers for each content item contained within a specific content set entity. Page details include the number of pages per media type, along with media specific properties including the name, size, width and height. Used specifically with the Content Set Entity service.
-
}, { "count": 1, "media": { "name": "Plain Letter Paper", "size": "Letter", "width": "8.5in", "height": "11in" } } ] }, { "id": 23456, "pages": [ { "count": 2, "media": { "name": "Plain A4 Paper", "size": "A4", "width": "210mm", "height": "297mm" } }, { "count": 2, "media": { "name": "Plain Letter Paper", "size": "Letter", "width": "8.
-
JSON Page Details Summary Describes a summary of the page details for a specific content set entity. Page details include the number of pages per media type, along with media specific properties including the name, size, width and height. Used specifically with the Content Set Entity service.
-
"name": "Plain Letter Paper", "size": "Letter", "width": "8.5in", "height": "11in" } } ] } JSON Parameters Describes a list of parameters used specifically in the creation of content.
-
JSON Record Content List Describes a list of data fields (as name/value pairs), nested data records (if any), along with a number of additional properties for a data record entity of a specific ID. Tip A data record entity (in the root or master data table) can contain one or more data tables that each contain one or more data record entities (nested data record entities).
-
l name – the name of the data field (type of string) l value – the value of the data field (type of string) Specific to data record entities that are children of a data set entity (data record entities in the root or master data table), two additional name/value pairs are included: l table – the data record entity data table name (value of record) (type of string) l datasetid – the data set entity identifier of parent entity (type of number) If a data record entity contains boundary information (set
-
}, { "name": "FirstName", "value": "Benjamin" }, { "name": "LastName", "value": "Verret" } ] } { "id": 45678, "table": "detail", "parentrecordid": 23456, "fields": [ { "name": "ItemNumber", "value": "PSM002" }, { "name": "ItemDesc", "value": "PSM Production (unlimited)" }, { "name": "ItemUnitPrice", "value": "495.00" }, { "name": "ItemOrdered", "value": "2" }, { "name": "ItemTotal", "value": "990.
-
"datasetid": 12345, "fields": [ { "name": "ID", "value": "CU00048376" }, { "name": "Date", "value": "2012-03-29T13:00Z" }, { "name": "DueDate", "value": "2012-04-28T14:00Z" }, { "name": "InvNumber", "value": "INV9441991" }, { "name": "Gender", "value": "M." }, { "name": "FirstName", "value": "Benjamin" }, { "name": "LastName", "value": "Verret" } { "name": "TotalOrdered", "value": "3" }, { "name": "InvSubTotal", "value": "1485.00" }, { "name": "InvTaxTotal", "value": "111.
-
"name": "InvTotal", "value": "1596.38" } ], "records": [ { "id": 45678, "table": "detail", "parentrecordid": 23456, "fields": [ { "name": "ItemNumber", "value": "PSM002" }, { "name": "ItemDesc", "value": "PSM Production (unlimited)" }, { "name": "ItemUnitPrice", "value": "495.00" }, { "name": "ItemOrdered", "value": "2" }, { "name": "ItemTotal", "value": "990.
-
"value": "Upgrade (Starter to Web)" }, { "name": "ItemUnitPrice", "value": "495.00" }, { "name": "ItemOrdered", "value": "1" } { "name": "ItemTotal", "value": "495.00" } ] } ] } { "id": 12345, "table": "record", "boundaries": { "start": 0, "end": 4 }, "datasetid": 34567, "fields": [ { "name": "ID", "value": "CU00048376" }, { "name": "Gender", "value": "M.
-
} ] } Page 101
-
JSON Record Content List (Explicit Types) Describes a list of data fields (as name/value pairs), a data table schema, nested data records (if any), along with a number of additional properties for a data record entity of a specific ID. Unlike a JSON Record Content List structure, this structure includes a data table schema (of data column/field data types) and uses specific JSON types to represent the value of data fields in the data record.
-
l tables – a list of any nested data tables in the data record entity, consisting of an object with one or more name/value pairs: l – the name (name) of the data table and the data table schema for the data record entities it contains, consisting of an object with the following name/value pair: l columns – a list of the data columns/fields in the data table schema and their corresponding data types, consisting of an object with one or more name/value pairs: l l – the name (name) and dat
-
l boundaries – the boundaries for the data record, consisting of an object with the following name/value pairs: l start – the starting boundary value for the data record (type of number) l end – the ending boundary value for the data record (type of number) Example The following are examples of this structure: { "schema": { "columns": { "ID": "STRING", "Gender": "STRING", "FirstName": "STRING", "LastName": "STRING", "ExtraData": "STRING" } }, "id": 12345, "datasetid": 34567, "fields": { "ID": "CU00048
-
"id": 45678, "fields": { "ItemNumber": "PSM002", "ItemDesc": "PSM Production (unlimited)", "ItemUnitPrice": "495.00", "ItemOrdered": 2, "ItemTotal": "990.
-
"ID": "CU00048376", "Date": 1332594000000, "DueDate": 1335189600000, "InvNumber": "INV9441991", "Gender": "M.", "FirstName": "Benjamin", "LastName": "Verret", "TotalOrdered": 3, "InvSubTotal": "1485.00", "InvTaxTotal": "111.38", "InvTotal": "1596.38", "ExtraData": "" }, "tables": { "detail": [ { "id": 45678, "fields": { "ItemNumber": "PSM002", "ItemDesc": "PSM Production (unlimited)", "ItemUnitPrice": "495.00", "ItemOrdered": 2, "ItemTotal": "990.
-
"columns": { "ID": "STRING", "Gender": "STRING", "FirstName": "STRING", "LastName": "STRING", "ExtraData": "STRING" } }, "id": 12345, "datasetid": 34567, "boundaries": { "start": 0, "end": 4 }, "fields": { "ID": "CU00048376", "Gender": "M.
-
JSON Record Content List (Fields Only) Describes a list of data field values (as name/value pairs) for a data record, used to update an existing data record entity of a specific ID.
-
JSON Record Content Lists Describes multiple lists of data field values (as name/value pairs), nested data records (if any), along with a number of additional properties for data record entities of a specific ID. Structure The structure consists of an array of JSON Record Content List structure objects.
-
"table": "detail", "parentrecordid": 23456, "fields": [ { "name": "ItemNumber", "value": "PSM005" }, { "name": "ItemDesc", "value": "Upgrade (Starter to Web)" }, { "name": "ItemUnitPrice", "value": "495.00" }, { "name": "ItemOrdered", "value": "1" } { "name": "ItemTotal", "value": "495.
-
JSON Record Content Lists (Explicit Types) Describes multiple lists of data field values (as name/value pairs), a data table schema, nested data records (if any), along with a number of additional properties for data record entities of a specific ID. Structure The structure consists of an array of JSON Record Content List (Explicit Types) structure objects.
-
"ItemUnitPrice": "CURRENCY", "ItemOrdered": "INTEGER", "ItemTotal": "CURRENCY", "ExtraData": "STRING" } }, "id": 45679, "fields": { "ItemNumber": "PSM005", "ItemDesc": "Upgrade (Starter to Web)", "ItemUnitPrice": "495.00", "ItemOrdered": 1, "ItemTotal": "495.
-
JSON Record Content Lists (Fields Only) Describes multiple lists of data field values (as name/value pairs) for a data record, used to update existing data record entities of a specific ID. Structure The structure consists of an array of JSON Record Content List (Fields Only) structure objects.
-
JSON Record Data List Describes a list of data fields (as name/value pairs), a data table schema and nested data records (if any) for one or more data records. This structure is used specifically by the Content Creation and Content Creation (HTML) services when creating content directly without the prerequisite of the data mapping process.
-
l tables – a list of any nested data tables in the data record, consisting of an object with one or more name/value pairs: l – the name (name) of the data table and a list the data records it contains, consisting of an array of objects each with the following name/value pairs: l l id – a required/default fixed value of 0 for all data records (type of number) fields – a list of the data fields in the data record and their corresponding data values, consisting of an object with one or more name/
-
"LastName": "Verret" } } } { "data": { "schema": { "columns": { "ID": "STRING", "Date": "DATETIME", "DueDate": "DATETIME", "InvNumber": "STRING", "Gender": "STRING", "FirstName": "STRING", "LastName": "STRING", "TotalOrdered": "INTEGER", "InvSubTotal": "CURRENCY", "InvTaxTotal": "CURRENCY", "InvTotal": "CURRENCY" }, "tables": { "detail": { "columns": { "ItemNumber": "STRING", "ItemDesc": "STRING", "ItemUnitPrice": "CURRENCY", "ItemOrdered": "INTEGER", "ItemTotal": "CURRENCY" } } } }, "fields": { "ID": "CU00
-
"InvTaxTotal": "111.38", "InvTotal": "1596.38" }, "tables": { "detail": [ { "id": 0, "fields": { "ItemNumber": "PSM002", "ItemDesc": "PSM Production (unlimited)", "ItemUnitPrice": "495.00", "ItemOrdered": 2, "ItemTotal": "990.00" } }, { "id": 0, "fields": { "ItemNumber": "PSM005", "ItemDesc": "Upgrade (Starter to Web)", "ItemUnitPrice": "495.00", "ItemOrdered": 1, "ItemTotal": "495.
-
"Gender": "M.
-
JSON Record Data List (with Email Parameters) Describes a list of data fields (as name/value pairs), a data table schema and nested data records (if any) for one or more data records, along with additional parameters used specifically in an content creation operation for email. This structure is variable, allowing specification for email output to either the file store or directly to a SMTP mail server, with a number of additional parameters.
-
l fields – a list of the data fields in the data record and their corresponding data values, consisting of an object with one or more name/value pairs: l l – the name (name) and data value of the data field (type of either string, number or boolean) tables – a list of any nested data tables in the data record, consisting of an object with one or more name/value pairs: l – the name (name) of the data table and a list the data records it contains, consisting of an array of objects each w
-
l host – the network address or name of the SMTP mail server through which emails will be sent.
-
{ "data": { "schema": { "columns": { "ID": "STRING", "Gender": "STRING", "FirstName": "STRING", "LastName": "STRING", "Email": "STRING" } }, "fields": { "ID": "CU00048376", "Gender": "M.", "FirstName": "Benjamin", "LastName": "Verret", "Email": "b.verret@drupa.ol.com.com" } }, "attachPdfPage": true, "attachWebPage": true, "sender": "john.smith@company.com", "useSender": true, "host": "mail.company.
-
"Gender": "M.", "FirstName": "Benjamin", "LastName": "Verret", "Email": "b.verret@drupa.ol.com.com" } }, { "schema": { "columns": { "ID": "STRING", "Gender": "STRING", "FirstName": "STRING", "LastName": "STRING", "Email": "STRING" } }, "fields": { "ID": "CU01499303", "Gender": "Miss", "FirstName": "Dianne", "LastName": "Straka", "Email": "d.straka@drupa.ol.com.com" } } ], "attachWebPage": true, "sender": "jane.smith@company.
-
"ID": "CU01499303", "Gender": "Miss", "FirstName": "Dianne", "LastName": "Straka", "Email": "d.straka@drupa.ol.com.com" } }, "attachPdfPage": false, "attachWebPage": true } JSON Record Data List (with Image Parameters) Describes a list of data fields (as name/value pairs), a data table schema and nested data records (if any) for one or more data records, along with additional parameters used specifically in the creation of a preview image of content for print, email or web.
-
l columns – a list of the data columns/fields in the data table schema and their corresponding data types, consisting of an object with one or more name/value pairs: l l fields – a list of the data fields in the data record and their corresponding data values, consisting of an object with one or more name/value pairs: l l – the name (name) and data type of the data field (value of either BOOLEAN, STRING, HTMLSTRING, INTEGER, FLOAT, DATETIME or CURRENCY) (type of string) – the name (name
-
l l context – the context to be used in the creation of the preview (value of either print, email or web) (type of string – Default value is determined by the first context in the template) section – the section to be used within the context specified (as either the context parameter, or else the default context of the template) (type of string – Default value is determined by the context specified. For the Print context this will be all enabled sections.
-
Examples The following is an example of this structure: { "data": { "schema": { "columns": { "ID": "STRING", "Gender": "STRING", "FirstName": "STRING", "LastName": "STRING" } }, "fields": { "ID": "CU00048376", "Gender": "M.
-
"InvTotal": "CURRENCY" }, "tables": { "detail": { "columns": { "ItemNumber": "STRING", "ItemDesc": "STRING", "ItemUnitPrice": "CURRENCY", "ItemOrdered": "INTEGER", "ItemTotal": "CURRENCY" } } } }, "fields": { "ID": "CU00048376", "Date": 1332594000000, "DueDate": 1335189600000, "InvNumber": "INV9441991", "Gender": "M.", "FirstName": "Benjamin", "LastName": "Verret", "TotalOrdered": 3, "InvSubTotal": "1485.00", "InvTaxTotal": "111.38", "InvTotal": "1596.
-
"ItemDesc": "Upgrade (Starter to Web)", "ItemUnitPrice": "495.00", "ItemOrdered": 1, "ItemTotal": "495.00" } } ] } }, "context": "web", "section": "Section 1", "type": "jpeg", "viewPortWidth": 1024 } { "data": [ { "schema": { "columns": { "ID": "STRING", "Gender": "STRING", "FirstName": "STRING", "LastName": "STRING" } }, "fields": { "ID": "CU00048376", "Gender": "M.
-
JSON Search Parameters Describes a set of complex search criteria broken into search, sorting and grouping rules. This structure is used specifically with the Entity service as input to the Find Data Entity resource method. Search rules can be added to a search rules list and can be used to match data entities based on specific criteria. This rules list also specifies an operator which determines whether all rules or only one rule in the list is required to be matched.
-
Structure The structure consists of an object with the following name/value pairs: l l entity – the data entity type (value of either DATARECORDS, DATASETS, CONTENTITEMS, CONTENTSETS, JOBS or JOBSETS) search – search criteria, consisting of an object with the following name/value pairs: l ruleType – the topmost RULESET l condition – the logic rule for this RULESET (value of ALL, ANY, NOTALL or NOTANY) l rules – a base list of search rules, consisting of an array of objects each with a specific rule
-
Data Value search – Search for data entities based on the value of a data record field.
-
l ruleType – VALUEIN l field – the field name (type of string) l dataType – the data type to search (value of either FIELD or PROPERTY) l condition – the comparison condition (value of either IN or NOT_IN) l values – the list of data entities (type of string, or array of strings ID In search – search for the ID values contained within a list.
-
LOCATION,or ANGLE) l condition – the comparison condition (value of either CONTAINS or NOT_CONTAINS) The comparison value.
-
Template search – searches based on the name of the template used during Content Creation. Comprises objects containing the following name/value pairs: l ruleType – TEMPLATE l condition – the comparison condition (value of either EQ (=) or NE (!=)) l name – the comparison value (type of string) Rule Set searches – construct a set of rules that are evaluated collectively.
-
"ruleType": "DOCMEDIA", "attribute": "NAME", "condition": "CONTAINS", "name": "Impact" }, { "ruleType": "DOCMEDIA", "attribute": "FRONT_COATING", "condition": "CONTAINS", "coating": "HIGH_GLOSS" }, { "ruleType": "DOCMEDIA", "attribute": "BACK_COATING", "condition": "CONTAINS", "coating": "SEMI_GLOSS" } ] }, { "ruleType": "RULESET", "condition": "ALL", "rules": [ { "ruleType": "DOCBINDING", "attribute": "STYLE", "condition": "CONTAINS", "bindingStyle": "STAPLED" }, { "ruleType": "DOCBINDING", "attribute": "S
-
"attribute": "ANGLE", "condition": "CONTAINS", "bindingAngle": "ANGLE" } ] }, { "ruleType": "RULESET", "condition": "ALL", "rules": [ { "ruleType": "DOCSIZE", "entity": "PAGE", "condition": "GT", "value": 4 }, { "ruleType": "DOCSIZE", "entity": "SHEET", "condition": "GT", "value": 2 }, { "ruleType": "DOCSIZE", "entity": "SECTION", "condition": "GT", "value": 1 } ] } ] }, "sort": [ { "type": "value", "name": "LastName", "numeric": false, "order": "ASC" } ], "group": [ { "type": "value", Page 137
-
"name": "Gender", "numeric": false, "order": "ASC" } ] } Page 138
-
Working Examples This section provides a number of working examples that demonstrate the use of the various resources and methods available in the PlanetPress Connect REST API. For help on getting started with the PlanetPress Connect REST API Cookbook and the working examples, see the Getting Started page.
-
Getting Started This guide provides many working examples to help illustrate the correct use of a given API/method. To achieve this, the guide uses HTML5 & JavaScript/jQuery syntax, and thus, some basic experience and knowledge of these technologies is assumed. l HTML5: https://www.w3schools.com/html/ l JavaScript: https://www.w3schools.com/js/ l jQuery: https://jquery.
-
Requirements & Installation Requirements To use the PlanetPress Connect REST API Cookbook with Working Examples source you will require the following: 1. A working installation of PlanetPress Connect 2. Any modern web browser able to display HTML51 Warning If using Internet Explorer, you may find issues when using the working examples with PlanetPress Connect's Server Security Settings set to enabled.
-
Any recent version of Mozilla Firefox, Google Chrome, or Microsoft Edge with support for HTML5 should be suitable for running the working examples contained in this guide. Microsoft Internet Explorer 11 may also be suitable in some cases. Installation The working examples source comes pre-installed with PlanetPress Connect and can be located in a sub-directory of your existing PlanetPress Connect installation directory. To locate the source on Windows: 1.
-
Structure of the Working Examples The working examples are designed to be complete examples, and will generally consists of one HTML5 file paired with a JavaScript/jQuery module which can be found in the examples//js/ sub-directory. Where any frequent or boilerplate functionality is commonly used across the examples, this has been moved to the common/js/common.js JavaScript/jQuery module.
-
The examples also make use of some simple CSS classes as defined in common/css/styles.css and HTML snippets for the presentation of output results.
-
HTML Input Placeholders & Multiple Value Fields In the working examples, HTML input elements make use of the placeholder attribute to help provide some indication of the type and format of the value expected to be entered / specified.
-
HTML Expected Type Example Values Date Value l 22/02/2020 Numerical Range l 1, 2, 3 l 1-5 l 1, 2, 3-5, 6 l john.smith@contoso.com l smtp.contoso.com l smtp.contoso.com:587 l 192.168.88.
-
Display of Working Example Results When a working example is run, any results will be displayed in a Results area that will appear below the working example existing HTML interface. For example: Note In some examples the same result will displayed in both plain and JSON structure based formats. This is to assist ease-of-use when working with outputs of one example that will be needed as an input to another example.
-
Using the Working Examples with Server Security If you have the Server Security Settings set to enabled in your PlanetPress Connect Server Preferences, then you may see the following dialog box initially display when working with the examples: In the event of this dialog box, just follow the instructions and either refresh the page or reauthenticate by running the Authenticating with the Server (Authenticate/Login to Server) working example covered under the Server Security & Authentication section.
-
Server Security & Authentication This section consists of a number of pages covering various useful working examples: 1. Authenticating with the Server See the Authentication Service page of the REST API Reference section for further detail. Note A complete listing including these examples can be found in the index.html file located at the root of the working example source code which contains links to all working examples.
-
Authenticating with the Server Problem Your PlanetPress Connect Server is configured to use server security, and you want to authenticate with the server to obtain the correct access to make future requests. Solution The solution is to create a request using the following URI and method type to authenticate with the server via the Authentication REST service: Authenticate/Login to Server /rest/serverengine/authentication/login POST Example HTML5 auth-login-server.
-
