Objectif Lune PlanetPress Connect - 1.7 Instruction Manual
REST API Cookbook with
Working Examples
Version:1.7.1
REST API Cookbook with Working Examples
Version 1.7.1
Last Revision:2017-10-30
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-2017. 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. reserves the right to alter the information contained in this documentation
without notice.
Page 4
Table of Contents
Table of Contents 5
Welcome to the PlanetPress Connect REST API Cookbook 11
Technical Overview 12
Workflow & Workflow Processes 13
Data Mapping 14
Content Creation 15
Job Creation 16
Output Creation 17
All-In-One 18
Input Files 20
Data Entities 21
Data Set & Data Record Entities 21
Content Set & Content Item Entities 22
Job Set & Job Entities 23
Workflow Operations 25
Asynchronous Operations 25
Synchronous Operations 26
JSON Structures 27
Common Structures 27
Specific Structures 30
Working Examples 65
Getting Started 66
Requirements & Installation 67
Structure of the Working Examples 69
HTML Input Placeholders & Multiple Value Fields 71
Display of Working Example Results 72
Using the Working Examples with Server Security 74
Server Security & Authentication 75
Authenticating with the Server 76
Working with the File Store 80
Uploading a Data File to the File Store 81
Uploading a Data Mapping Configuration to the File Store 87
Uploading a Design Template to the File Store 93
Page 5
Uploading a Job Creation Preset to the File Store 99
Uploading an Output Creation Preset to the File Store 105
Working with the Entity Services 111
Finding Specific Data Entities in the Server 112
Finding all the Data Sets in the Server 144
Finding the Data Records in a Data Set 147
Finding all the Content Sets in the Server 151
Finding the Content Items in a Content Set 154
Finding all the Job Sets in the Server 158
Finding the Jobs in a Job Set 161
Working with the Workflow Services 164
Running a Data Mapping Operation 165
Running a Data Mapping Operation (Using JSON) 172
Running a Data Mapping Operation for PDF/VT File (to Data Set) 179
Running a Data Mapping Operation for PDF/VT File (to Content Set) 186
Running a Content Creation Operation for Print 193
Running a Content Creation Operation for Print By Data Record (Using JSON) 200
Running a Content Creation Operation for Email By Data Record (Using JSON) 207
Creating Content for Web By Data Record 218
Creating Content for Web By Data Record (Using JSON) 224
Running a Job Creation Operation (Using JSON) 230
Running an Output Creation Operation 237
Running an Output Creation Operation (Using JSON) 245
Running an Output Creation Operation By Job (Using JSON) 253
Running an All-In-One Operation (Using JSON) 261
REST API Reference 277
Authentication Service 282
Service Handshake 283
Authenticate/Login to Server 284
Service Version 286
Content Creation Service 287
Service Handshake 288
Process Content Creation 289
Process Content Creation (By Data Record) (JSON) 291
Create Preview PDF 293
Create Preview PDF (JSON) 295
Create Preview PDF (By Data Record) 297
Page 6
Get All Operations 299
Get Progress of Operation 300
Get Result of Operation 302
Cancel an Operation 304
Service Version 305
Content Item Entity Service 306
Service Handshake 307
Get Data Record for Content Item 308
Get Content Item Properties 310
Update Content Item Properties 312
Update Multiple Content Item Properties 314
Service Version 316
Content Set Entity Service 317
Get All Content Set Entities 318
Get Content Items for Content Set 319
Get Page Details for Content Set 321
Delete Content Set Entity 323
Get Content Set Properties 325
Update Content Set Properties 327
Service Version 329
Data Record Entity Service 330
Service Handshake 331
Add Data Records 332
Get Data Record Values 334
Update Data Record Values 336
Get Data Record Properties 338
Update Data Record Properties 340
Get Multiple Data Record Values 342
Update Multiple Data Record Values 344
Update Multiple Data Record Properties 346
Service Version 348
Data Set Entity Service 349
Get All Data Set Entities 350
Get Data Records for Data Set 351
Delete Data Set Entity 352
Get Data Set Properties 354
Update Data Set Properties 356
Page 7
Service Version 358
Data Mapping Service 359
Service Handshake 360
Process Data Mapping 361
Process Data Mapping (JSON) 363
Process Data Mapping (PDF/VT to Data Set) 366
Process Data Mapping (PDF/VT to Content Set) 368
Get All Operations 370
Get Progress of Operation 371
Get Result of Operation 373
Cancel an Operation 375
Service Version 376
Document Entity Service 377
Service Handshake 378
Get Document Metadata Properties 379
Update Document Metadata Properties 381
Service Version 383
Document Set Entity Service 384
Service Handshake 385
Get Documents for Document Set 386
Get Document Set Metadata Properties 388
Update Document Set Metadata Properties 390
Service Version 392
Content Creation (Email) Service 393
Service Handshake 394
Process Content Creation (By Data Record) (JSON) 395
Get All Operations 397
Get Progress of Operation 398
Get Result of Operation 400
Cancel an Operation 402
Service Version 404
Entity Service 405
Service Handshake 406
Find Data Entity 407
Service Version 409
File Store Service 410
Service Handshake 411
Page 8
Download Managed File or Directory 412
Delete Managed File or Directory 414
Upload Data Mapping Configuration 416
Upload Job Creation Preset 418
Upload Data File 420
Upload Design Template 422
Upload Output Creation Preset 424
Service Version 426
Content Creation (HTML) Service 427
Service Handshake 428
Process Content Creation (By Data Record) 429
Process Content Creation (By Data Record) (JSON) 431
Get Template Resource 433
Service Version 435
Job Creation Service 436
Service Handshake 437
Process Job Creation 438
Process Job Creation (JSON) 440
Process Job Creation (JSON Job Set Structure) 442
Get All Operations 444
Get Progress of Operation 445
Get Result of Operation 447
Cancel an Operation 449
Service Version 450
Job Entity Service 451
Service Handshake 452
Get Content Items for Job 453
Get Job Segments for Job 455
Get Job Metadata Properties 456
Update Job Metadata Properties 458
Get Job Properties 460
Update Job Properties 462
Update Multiple Job Properties 464
Service Version 465
Job Segment Entity Service 466
Service Handshake 467
Get Document Sets for Job Segment 468
Page 9
Get Job Segment Metadata Properties 470
Update Job Segment Metadata Properties 472
Service Version 474
Job Set Entity Service 475
Get All Job Set Entities 476
Get Jobs for Job Set 477
Delete Job Set Entity 478
Get Job Set Metadata Properties 480
Update Job Set Metadata Properties 482
Get Job Set Properties 484
Update Job Set Properties 486
Service Version 488
Output Creation Service 489
Service Handshake 490
Process Output Creation 491
Process Output Creation (JSON) 493
Process Output Creation (By Job) (JSON) 495
Get All Operations 497
Get Progress of Operation 498
Get Result of Operation 500
Get Result of Operation (as Text) 502
Cancel an Operation 504
Service Version 505
All-In-One Service 506
Service Handshake 507
Process All-In-One (JSON) 508
Process All-In-One (Adhoc Data) 510
Get All Operations 514
Get Progress of Operation 515
Get Result of Operation 517
Get Result of Operation (as Text) 519
Cancel an Operation 521
Service Version 522
Copyright Information 523
Legal Notices and Acknowledgments 524
Page 10
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 1.7.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.
These services can be used to perform various interactions with the PlanetPress Connect
server such as:
l Upload & Manage Data Files, Data Mapping Configurations & Design Templates in File
Store
l Create, Manage & Find Data Entities internal to the PlanetPress Connect Server
l Create & Monitor Processing Operations within the Workflow
The REST API also supports added security to restrict unauthorized access to the services.
This guide is broken down into three sections:
l Technical Overview - Overview of the concepts and structures used in PlanetPress
Connect and the REST API
l Working Examples - Working examples of the PlanetPress Connect REST API in action
(HTML5 & JavaScript/jQuery)
l REST API Reference - A complete reference to the PlanetPress Connect REST API &
Services
It is recommended that the technical overview section be read first, followed by the working
examples, using the REST API reference for greater detail on implementing any specific
example.
Page 11
Technical Overview
This section provides an overview of the concepts and structures used within PlanetPress
Connect and the REST API.
l Workflow & Workflow Processes
l Input Files
l Data Entities
l Workflow Operations
l JSON Structures
Page 12
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.
The following diagram illustrates the primary workflow in PlanetPress Connect:
Typically an individual workflow process (shown above in blue) will take one or more input files
as input (shown above in green), and will produce either intermediary output in the form of a
data entity (shown above in red), or final output in the form of print, web, or email based content
(depending on the context of the content produced) (shown above in yellow).
Input files to a workflow process include files such as data files, data mapping configurations
and design templates. In most cases an input file needs to be uploaded to the server file store
before it can be used in a workflow process. A file that has been uploaded to the file store is
known as a managed file, and managed files can be referenced via a unique identifier or name.
A data entity is simply a structured data artefact, produced as a result of an instance of a
workflow process known as a workflow operation. Data entities are stored internally to the
server and can also be referenced via a unique identifier.
Where a certain process depends on the output of the process before it, the data entity or
entities produced by the earlier process are used as an input to that process.
Page 13
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/VTfile using its internal meta
data instead of a data mapping configuration.
The following diagram illustrates the default workflow for the data mapping process:
The following diagram illustrates the alternative workflow for the data mapping process when
using PDF/VT data files specifically:
Page 14
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 design 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 the content creation process:
Page 15
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.
The following diagram illustrates the workflow for the job creation process:
Page 16
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).
The following diagram illustrates the workflow for the output creation process:
Page 17
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 diagram illustrates the potential inputs, outputs and workflows for the All-In-One
process:
The following table lists the available processes, input combinations and expected outputs for
the All-In-One process:
Page 18
Processes Input Combination Expected
Output
Data Mapping Only Data File + Data Mapping Configuration Data Set
Data Mapping +
Content Creation
Content Creation Only Data Records + Design Template Content Set(s)
Data Mapping +
Content Creation + Job
Creation
Content Creation + Job
Creation
Content Creation + Job
Creation + Output
Creation
Output Creation Only Jobs + Output Creation Preset Print Output
Data File + Data Mapping Configuration +
Design Template
Data File + Data Mapping Configuration +
Design Template
Data Records + Design Template Job Set
Data Records + Design Template + Output
Creation Preset
Content Set(s)
Job Set
Print Output
Data Mapping +
Content Creation + Job
Creation + Output
Creation
Data Mapping +
Content Creation + Job
Creation + Output
Creation
Data File + Data Mapping Configuration +
Design Template + Output Creation Preset
Data File + Data Mapping Configuration +
Design Template + Job Creation Preset +
Output Creation Preset
Print Output
Print Output
Page 19
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
File Name Examples
Process
Data File Data Mapping l Promo-EN-10.csv
l Promo-EN-10000.csv
l PDFVT-Data.pdf
Data Mapping
Configuration
Data Mapping l Promo-EN.OL-datamapper
l Transact-EN.OL-
datamapper
Design Template Content Creation l letter-ol.OL-template
l invoice-ol-transpromo.OL-
template
Job Creation Preset Job Creation l Promo-EN-JC-Config.OL-
jobpreset
Output Creation Preset Output Creation l FX4112_Hold_Config.OL-
outputpreset
l Promo-EN-OC-Config.OL-
outputpreset
Page 20
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. A data mapping operation produces a single data set, which
contains as many data records as there are documents.
Each data record contains a collection of data values. The data records in the data set form the
master record, or document record, which typically contains document recipient information.
The master record can also contain a collection of data tables, which form the detail records
that hold data such as invoice line items.
Each data table contains a collection of data records, where each data record contains a
collection of data values and a collection of data tables, and so on.
Page 21
The following diagram illustrates the basic relationship between these entities in the context of
the data mapping process:
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.
Because the data records used may have different data set owners, a content set cannot be
linked to a single data set, but rather content items are linked to data records. A content item is
further divided into content sections and content pages.
The following diagram illustrates the basic relationship between these entities in the context of
the content creation process:
Page 22
The content set and content item entities (shown above in blue) are accessible via the Content
Set Entity and Content Item Entity services.
Job Set & Job Entities
The job set is the artefact produced by a job creation operation. It consists of a hierarchical
structure that divides documents into various structures and it basically decides which
documents are to be printed and in what order.
A job creation operation creates a single job set which contains a series of containers where
every level contains one or more of the next level down: jobs, job segments, document sets,
documents and document pages. The last level in the chain, the document pages, contains a
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. The job segment, document set and document entities (also shown above
in blue) are accessible via the Job Segment Entity, Document Set Entity and Document Entity
services.
In summary, the following diagram illustrates the basic relationship between all data entities in
Page 23
the overall context of the primary workflow in PlanetPress Connect:
Page 24
Workflow Operations
Each individual process in the overall workflow can potentially be a long running operation.
Accordingly, there are two types of workflow operations possible in the PlanetPress Connect
REST API:
l Asynchronous – the operation is initiated, monitored, and the result returned using
multiple requests (Default)
l Synchronous – the operation is initiated and the result returned using a single request
Asynchronous Operations
Asynchronous workflow operations require the submission of an initial HTTP request to initiate
the operation. Then additional requests are required to monitor progress and retrieve the final
result. All the required detail is included in the HTTP response headers of the initial request,
including the URIs that should be used for further processing.
A successful request will return a response that will include the headers listed in the following
table:
Header Description
operationId The unique id of the operation being processed
Link Contains multiple link headers which provide details on which URI to use to
retrieve further information on the operation:
l Header with rel="progress" - The URL to use to check the progress of
the operation
l Header with rel="result" - The URL to use to retrieve the result of the
operation
l Header with rel="cancel" - The URL to use to cancel the operation
A request made to the progress URI during processing will return a progress percentage value
of 0 to 100, and finally the value of ‘done’ once the operation has completed.
Page 25
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.
Synchronous Operations
Synchronous workflow operations initiate the operation and retrieve the final result in a single
request.
There are no additional operation related headers returned, and there is no option to either
monitor progress or cancel a running operation.
This approach is only used by specific methods found in the All-In-One workflow service.
Page 26
JSON Structures
The PlanetPress Connect REST API uses various JSON structures to describe certain inputs
and outputs to resource methods.
These structures can be broken down into the following categories:
l Common - Structures that are commonly used throughout the REST API
l Specific - Structures that are used by a specific resource method or service in the REST
API
Common Structures
Common JSON structures used in the PlanetPress Connect REST API include the following:
JSON Identifier
Describes an identifier for a single data entity or managed file in PlanetPress Connect.
The structure consists of an object with a single name/value pair:
l identifier - the data entity or managed file identifier (type of number)
Example:
{
"identifier": 12345
}
JSON Identifier (Named)
Describes a named identifier for a single managed file in PlanetPress Connect.
The structure consists of an object with a single name/value pair:
l identifier - the managed file named identifier (type of string)
Example:
{
"identifier": "Promo-EN-1000.csv"
Page 27
}
JSON Identifier List
Describes a list of identifiers for multiple data entities in PlanetPress Connect.
The structure consists of an object with a single name/value pair:
l identifiers - an array of data entity identifiers (type of number)
Example:
{
"identifiers": [ 12345, 23456, 34567 ]
}
JSON Name/Value List (Properties Only)
Describes a list of properties (each as a name/value pair).
The structure consists of an array of objects each with the following name/value pairs:
l name - the name of the property (type of string)
l value - the value of the property (type of string)
Example:
[
{
"name": "start",
"value": "2015-01-01 00:00:00T-0500"
},
{
"name": "end",
"value": "2015-12-31 23:59:59T-0500"
}
]
JSON Name/Value List
Describes a list of properties (each as a name/value pair) for a data entity of a specific ID.
The structure consists of an object with the following name/value pairs:
Page 28
l id - the data entity identifier (type of number)
l properties - the data entity properties, consisting of an array of objects each with the
following name/value pairs:
l name - the name of the property (type of string)
l value - the value of the property (type of string)
Example:
{
"id": 12345,
"properties": [
{
"name": "start",
"value": "2015-01-01 00:00:00T-0500"
},
{
"name": "end",
"value": "2015-12-31 23:59:59T-0500"
}
]
}
JSON Name/Value Lists
Describes multiple lists of properties (as name/value pairs) for data entities of a specific ID.
The structure consists of an array of JSON Name/Value List structure objects.
Example:
[
{
"id": 12345,
"properties": [
{
"name": "start",
"value": "2015-01-01 00:00:00T-0500"
},
{
"name": "end",
"value": "2015-12-31 23:59:59T-0500"
Page 29
}
]
},
{
"id": 23456,
"properties": [
{
"name": "start",
"value": "2015-01-01 00:00:00T-0500"
},
{
"name": "end",
"value": "2015-12-31 23:59:59T-0500"
}
]
}
]
Specific Structures
Specific JSON structures used in the PlanetPress Connect REST API include the following:
JSON Identifier (with createOnly flag)
Describes an identifier for a single job set entity, along with additional parameters used
specifically in an output creation operation.
The structure consists of an object with the following name/value pairs:
l identifier - the job set entity identifier (type of number)
l createOnly - flag to specify if output is to be only created in the server and not sent to it's
final destination (type of boolean)
Example:
{
"identifier": 12345,
"createOnly": true
}
Page 30
Loading...