Objectif Lune PlanetPress Connect - 1.6 Instruction Manual
REST API Cookbook with
Working Examples
Version:1.6
REST API Cookbook with Working Examples
Version 1.6
Last Revision:17/01/2017
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 7
Technical Overview 8
Workflow & Workflow Processes 9
Workflow Components 16
Workflow Operations 20
JSON Structures 21
Working Examples 33
Getting Started 34
Server Security & Authentication 43
Working with the File Store 48
Working with the Entity Services 78
Working with the Workflow Services 99
REST API Reference 211
Authentication Service 215
Content Creation Service 220
Content Item Entity Service 232
Page 5
Content Set Entity Service 243
Data Record Entity Service 256
Data Set Entity Service 271
Data Mapping Service 281
Content Creation (Email) Service 297
File Store Service 308
Content Creation (HTML) Service 329
Job Creation Service 338
Job Entity Service 352
Job Set Entity Service 362
Output Creation Service 372
All-In-One Service 388
Copyright Information 400
Legal Notices and Acknowledgments 401
Page 6
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.6.
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 7
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 Workflow Components
l Workflow Operations
l JSON Structures
Page 8
Workflow & Workflow Processes
In PlanetPress Connect there are four main workflow processes: Data Mapping, Content
Creation, Job Creation, and Output Creation.
There is also an additional workflow process, named All-In-One, which embodies all four other
workflow processes in a singular process.
The following flowchart illustrates the primary workflow in PlanetPress Connect:
Page 9
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 from a PDF/VTfile using its internal meta data instead of a
data mapping configuration.
The following flowchart illustrates the standard workflow for the Data Mapping process:
The following flowchart illustrates the alternative workflow for the Data Mapping process when
using PDF/VT data files specifically:
Page 10
Page 11
Content Creation
The Content Creation process involves taking a number of data records (from a Data Set)
combining it with a suitable design template, and producing a set or sets of content (Content
Sets). If the content is for the email or web context then output can be published at this stage.
The following flowchart illustrates the standard workflow for the Content Creation process:
Page 12
Job Creation
The Job Creation process involves taking one or more content sets and applying a preset for
organising/sorting/grouping them into sets of logical jobs (a Job Set). This includes data
filtering and finishing options.
The following flowchart illustrates the standard workflow for the Job Creation process:
Page 13
Output Creation
The Output Creation process involves taking a set of jobs, applying a preset and generating the
printed output.
The following flowchart illustrates the standard workflow for the Output Creation process:
Page 14
All-In-One
The following flowchart illustrates the potential inputs, outputs and workflows for the All-In-One
process:
Page 15
Workflow Components
Each process in the overall PlanetPress Connect workflow takes a series of inputs and
produces output. These can be divided into Input Components and Data Entities.
Page 16
Input Components
Input components are used as input to a specific workflow process. The following table lists the
types of input components 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 17
Data Entities
There are many data entity types used by PlanetPress Connect, but not all entities can be
accessed through the REST API. The main types to be aware of when working with the API are
Data Sets, Data Records, Content Sets, Content Items, Jobs Sets and Jobs. The following table
lists these entity types in greater detail:
Entity Description
Data
Set &
Data
Records
Content
Sets &
Content
Items
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.
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 in content sections and content pages.
Job Set
& Jobs
The job set is the artefact produced by a job creation operation. It consists in a
hierarchical structure that divides documents is various structures and basically
decides which documents are to be printed and in which order. A job creation
operation creates a single job set with 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.
Page 18
Data entities can be produced as output from a workflow process and can then be used as
input to another workflow process.
Page 19
Workflow Operations
Each individual process in the overall workflow process can potentially be a long running
operation.
Accordingly, an initial HTTP request is submitted to initiate the workflow 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.
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 approach is replicated across most workflow based services as demonstrated in the
Working with the Workflow Services page of the Working Examples section.
Page 20
JSON Structures
The following table lists the various JSON structures used by the PlanetPress Connect REST
API:
Name Example
JSON
Identifier
JSON
Identifier
(Named)
JSON
Identifier List
JSON
Identifier (with
createOnly
flag)
{
"identifier": 12345
}
{
"identifier": "Promo-EN-1000.csv"
}
{
"identifiers": [ 12345, 23456, 34567 ]
}
{
"identifier": 12345,
"createOnly": true
}
JSON
Identifier List
(with
createOnly
flag)
JSON
Name/Value
List
(Properties
Only)
{
"identifiers": [ 12345, 23456, 34567 ],
"createOnly": true
}
[
{
"name": "start",
"value": "2015-01-01 00:00:00T-0500"
},
{
Page 21
Name Example
}
]
"name": "end",
"value": "2015-12-31 23:59:59T-0500"
JSON
Name/Value
List
JSON
Name/Value
Lists
{
"id": 12345,
"properties": [
{
"name": "start",
"value": "2015-01-01 00:00:00T-0500"
},
{
"name": "end",
"value": "2015-12-31 23:59:59T-0500"
},
]
}
[
{
"id": 12345,
},
"properties": [
{
"name": "start",
"value": "2015-01-01 00:00:00T-0500"
},
{
"name": "end",
"value": "2015-12-31 23:59:59T-0500"
},
]
Page 22
Name Example
{
}
]
"id": 23456,
"properties": [
{
"name": "start",
"value": "2015-01-01 00:00:00T-0500"
},
{
"name": "end",
"value": "2015-12-31 23:59:59T-0500"
},
]
JSON Record
Content List
{
"id": 12345,
"table": "record",
"fields":[
{
"name": "ID",
"value": "CU00048376"
},
{
"name": "Gender",
"value": "M."
},
{
"name": "FirstName",
"value": "Benjamin"
},
{
"name": "LastName",
"value": "Verret"
Page 23
Name Example
]
}
}
JSON Record
Content Lists
[
{
"id": 12345,
"table": "record",
"fields":[
{
"name": "ID",
"value": "CU00048376"
},
{
"name": "Gender",
"value": "M."
},
{
"name": "FirstName",
"value": "Benjamin"
},
},
{
{
"name": "LastName",
"value": "Verret"
}
]
"id": 23456,
"table": "record",
"fields":[
{
"name": "ID",
"value": "CU01499303"
Page 24
Name Example
}
},
{
"name": "Gender",
"value": "Miss"
},
{
"name": "FirstName",
"value": "Dianne"
},
{
"name": "LastName",
"value": "Straka"
}
]
JSON Content
Item Identifier
List
]
{
"identifiers": [
{
"item": 12345,
"record": 54321
},
{
"item": 23456,
"record": 65432
},
{
"item": 34567,
"record": 76543
}
]
}
Page 25
Name Example
JSON Data
Record
Identifier
JSON
Identifier List
(with Email
Parameters)
{
"record": 12345
}
{
"identifiers": [
12345,
23456
],
"host": "mail.company.com",
"user": "johns",
"password": "password5",
"sender": "john.smith@company.com",
"useAuth": true,
"useStartTLS": false,
"useSender": true,
"attachWebPage": true,
JSON Job Set
Structure
"attachPdfPage": true
}
{
"jobs": [
{
// First Job in JobSet
"segments": [
{
// First JobSegment in first Job
"documentsets": [
{
// First DocumentSet in
first JobSegment in first Job
Page 26
Name Example
Document in first DocumentSet in first JobSegment in
first Job
[
DocumentPages in first Document in first DocumentSet
in first JobSegment in first Job
"contentitem": 111
"documents": [
{
// First
"documentpages":
{
// First
},
{
//
Second DocumentPages in first Document in first
DocumentSet in first JobSegment in first Job
"contentitem": 222
}
]
},
{
// Second
Document in first DocumentSet in first JobSegment in
first Job
"documentpages":
[
{
// First
DocumentPages in second Document in first
Page 27
Name Example
Job
first JobSegment in second Job
}
]
},
{
// Second Job in JobSet
"segments": [
{
// First JobSegment in second
"documentsets": [
{
// First DocumentSet in
"documents": [
{
// First
Document in first DocumentSet in first JobSegment in
second Job
"documentpages":
[
{
// First
DocumentPages in first Document in first DocumentSet
in first JobSegment in second Job
"contentitem": 789
}
]
}
]
}
]
}
]
Page 28
Name Example
JSON HTML
Parameters
List
JSON All-InOne
Configuration
{
"section": "Section 1",
"inline": "ALL"
}
{
"datamining":
{
"identifier": "Promo-EN-1000.csv",
"config": "Promo-EN.OL-datamapper"
},
"contentcreation":
{
"config": "letter-ol.OL-template"
},
"jobcreation":
{
JSON Page
Details
Summary
"config": "4567"
},
"outputcreation":
{
"config": "5678",
"createOnly": true
},
"printRange":
{
"printRange": "1-3, 6, 10"
}
}
{
Page 29
Name Example
"pages": [
{
"count": 200,
"media": {
"name": "Plain A4 Paper",
"size": "A4",
"width": "210mm",
"height": "297mm"
}
},
{
"count": 108,
"media": {
"name": "Plain Letter Paper",
"size": "Letter",
JSON Page
Details List
"width": "8.5in",
"height": "11in"
}
}
]
}
[
{
"id": 12345,
"pages": [
{
"count": 2,
"media": {
"name": "Plain A4 Paper",
"size": "A4",
"width": "210mm",
"height": "297mm"
Page 30
Loading...