Objectif Lune PlanetPress Connect - 2019.1 Instruction Manual
REST API Cookbook with
Working Examples
Version:2019.1
REST API Cookbook with Working Examples
Version 2019.1
Last Revision:2019-05-21
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-2019. 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 12
Technical Overview 13
Workflow & Workflow Processes 14
Data Mapping 15
Content Creation 16
Job Creation 17
Output Creation 18
All-In-One 19
Input Files 21
Data Entities 22
Data Set & Data Record Entities 22
Content Set & Content Item Entities 23
Job Set & Job Entities 24
Workflow Operations 26
Asynchronous Operations 26
Synchronous Operations 27
JSON Structures 28
Common Structures 29
Specific Structures 35
Working Examples 102
Getting Started 103
Requirements & Installation 104
Structure of the Working Examples 106
HTML Input Placeholders & Multiple Value Fields 108
Display of Working Example Results 109
Using the Working Examples with Server Security 110
Server Security & Authentication 111
Authenticating with the Server 112
Working with the File Store 117
Uploading a Data File to the File Store 118
Uploading a Data Mapping Configuration to the File Store 123
Uploading a Design Template to the File Store 129
Page 5
Uploading a Job Creation Preset to the File Store 135
Uploading an Output Creation Preset to the File Store 141
Working with the Entity Services 147
Finding Specific Data Entities in the Server 148
Finding all the Data Sets in the Server 180
Finding the Data Records in a Data Set 183
Finding all the Content Sets in the Server 187
Finding the Content Items in a Content Set 190
Finding all the Job Sets in the Server 195
Finding the Jobs in a Job Set 198
Working with the Workflow Services 201
Running a Data Mapping Operation 202
Running a Data Mapping Operation (Using JSON) 209
Running a Data Mapping Operation for PDF/VT File (to Data Set) 216
Running a Data Mapping Operation for PDF/VT File (to Content Set) 222
Running a Content Creation Operation for Print 228
Running a Content Creation Operation for Print By Data Record (Using JSON) 234
Running a Content Creation Operation for Email By Data Record (Using JSON) 241
Creating Content for Web By Data Record 251
Creating Content for Web By Data Record (Using JSON) 257
Running a Job Creation Operation (Using JSON) 263
Running an Output Creation Operation 269
Running an Output Creation Operation (Using JSON) 276
Running an Output Creation Operation By Job (Using JSON) 284
Running an All-In-One Operation (Using JSON) 292
REST API Reference 308
Authentication Service 318
Service Handshake 319
Authenticate/Login to Server 320
Service Version 322
Content Creation Service 323
Service Handshake 325
Process Content Creation 326
Process Content Creation (By Data Record) (JSON) 328
Process Content Creation (By Data) (JSON) 330
Create Preview PDF 332
Create Preview PDF (By Data Record) 334
Page 6
Create Preview PDF (By Data) (JSON) 336
Get All Operations 338
Get Progress of Operation 339
Get Result of Operation 341
Cancel an Operation 343
Service Version 344
Content Item Entity Service 345
Service Handshake 346
Get Data Record for Content Item 347
Get Content Item Properties 349
Update Content Item Properties 351
Update Multiple Content Item Properties 353
Service Version 355
Content Set Entity Service 356
Get All Content Sets 357
Get Content Items for Content Set 358
Get Page Details for Content Set 360
Delete Content Set Entity 362
Get Content Set Properties 364
Update Content Set Properties 366
Service Version 368
Data Record Entity Service 369
Service Handshake 370
Add Data Records 371
Get Data Record Values 373
Update Data Record Values 375
Get Data Record Properties 377
Update Data Record Properties 379
Get Multiple Data Record Values 381
Get Multiple Data Record Values (JSON) 383
Update Multiple Data Record Values 385
Update Multiple Data Record Properties 387
Service Version 389
Data Set Entity Service 390
Get All Data Sets 391
Get Data Records for Data Set 392
Delete Data Set Entity 393
Page 7
Get Data Set Properties 395
Update Data Set Properties 397
Service Version 399
Data Mapping Service 400
Service Handshake 401
Process Data Mapping 402
Process Data Mapping (JSON) 404
Process Data Mapping (PDF/VT to Data Set) 407
Process Data Mapping (PDF/VT to Content Set) 409
Get All Operations 411
Get Progress of Operation 412
Get Result of Operation 414
Cancel an Operation 416
Service Version 417
Document Entity Service 418
Service Handshake 419
Get Document Metadata Properties 420
Update Document Metadata Properties 422
Service Version 424
Document Set Entity Service 425
Service Handshake 426
Get Documents for Document Set 427
Get Document Set Metadata Properties 429
Update Document Set Metadata Properties 431
Service Version 433
Content Creation (Email) Service 434
Service Handshake 435
Process Content Creation (By Data Record) (JSON) 436
Process Content Creation (By Data) (JSON) 438
Get All Operations 440
Get Progress of Operation 441
Get Result of Operation 443
Cancel an Operation 445
Service Version 447
Entity Service 448
Service Handshake 449
Find Data Entity 450
Page 8
Service Version 452
File Store Service 453
Service Handshake 454
Download Managed File or Directory 455
Delete Managed File or Directory 457
Upload Data Mapping Configuration 459
Upload Job Creation Preset 461
Upload Data File 463
Upload Design Template 465
Upload Output Creation Preset 467
Service Version 469
Content Creation (HTML) Service 470
Service Handshake 471
Process Content Creation (By Data Record) 472
Process Content Creation (By Data Record) (JSON) 474
Process Content Creation (By Data) (JSON) 476
Process Content Creation (No Data) 478
Get Template Resource 480
Service Version 482
Job Creation Service 483
Service Handshake 484
Process Job Creation 485
Process Job Creation (JSON) 487
Process Job Creation (JSON Job Set Structure) 489
Get All Operations 491
Get Progress of Operation 492
Get Result of Operation 494
Cancel an Operation 496
Service Version 497
Job Entity Service 498
Service Handshake 499
Get Content Items for Job 500
Get Job Segments for Job 502
Get Job Metadata Properties 503
Update Job Metadata Properties 505
Get Job Properties 507
Update Job Properties 509
Page 9
Update Multiple Job Properties 511
Service Version 512
Job Segment Entity Service 513
Service Handshake 514
Get Document Sets for Job Segment 515
Get Job Segment Metadata Properties 517
Update Job Segment Metadata Properties 519
Service Version 521
Job Set Entity Service 522
Get All Job Sets 523
Get Jobs for Job Set 524
Delete Job Set Entity 525
Get Job Set Metadata Properties 527
Update Job Set Metadata Properties 529
Get Job Set Properties 531
Update Job Set Properties 533
Service Version 535
Output Creation Service 536
Service Handshake 537
Process Output Creation 538
Process Output Creation (JSON) 540
Process Output Creation (By Job) (JSON) 542
Run +PReS Enhance Workflow Configuration 544
Get All Operations 546
Get Progress of Operation 547
Get Result of Operation 549
Get Result of Operation (as Text) 551
Cancel an Operation 553
Service Version 554
All-In-One Service 555
Service Handshake 556
Process All-In-One (JSON) 557
Process All-In-One (Adhoc Data) 559
Get All Operations 563
Get Progress of Operation 564
Get Result of Operation 566
Get Result of Operation (as Text) 568
Page 10
Cancel an Operation 570
Service Version 571
Copyright Information 572
Legal Notices and Acknowledgements 573
Page 11
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 2019.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 and manage data files, data mapping configurations and design templates in the
file store
l Create, manage and find data entities internal to the PlanetPress Connect server
l Create and 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 and
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 12
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 13
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 14
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 15
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 16
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 17
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 18
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 19
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 20
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 21
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 22
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 23
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 24
the overall context of the primary workflow in PlanetPress Connect:
Page 25
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 26
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 27
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 – JSON structures that are commonly used throughout the REST API
l Specific Structures – JSON structures that are used by a specific resource method or
service in the REST API
Page 28
Common Structures
Common JSON structures used in the PlanetPress Connect REST API include the following:
l JSON Identifier
l JSON Identifier List
l JSON Name/Value List (Properties Only)
l JSON Name/Value List
l JSON Name/Value Lists
Page 29
JSON Identifier
Describes an identifier for a single data entity in PlanetPress Connect.
Structure
The structure consists of an object with a single name/value pair:
l identifier – the data entity identifier (type of number)
Example
The following is an example of this structure:
{
"identifier": 12345
}
Page 30
Loading...