Xerox FreeFlow VI eCompose Dispatch SDK User Guide

Version 16.0.3.0 December 2020 702P08481

Xerox

FreeFlow Dispatch SDK User Guide

VI eCompose

, FreeFlow Process Manager®, VIPP®, and GlossMark®are trademarks of Xerox

Corporation in the United States and/or other countries. Other company trademarks are acknowledged as follows:

Adobe PostScript

, the Adobe logo, Acrobat®, the Acrobat logo, Acrobat Reader®, Distiller®, Adobe PDF JobReady™, InDesign®,

, and the PostScript logo are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States and/or other countries. All instances of the name PostScript in the text are references to the PostScript language as defined by Adobe Systems Incorporated unless otherwise stated. The name PostScript also is used as a product trademark for Adobe Systems’ implementation of the PostScript language interpreter, and other Adobe products. Copyright 1987 - 2020 Adobe Systems Incorporated and its licensors. All rights reserved. Includes

Adobe

Intel

PDF Libraries and Adobe Normalizer technology.

, Pentium®, Centrino®, and Xeon®are registered trademarks of Intel Corporation. Intel Core™Duo is a trademark

of Intel Corporation.

Intelligent Mail

Macintosh

is a registered trademark of the United States Postal Service.

, Mac®, and Mac OS®are registered trademarks of Apple, Inc., registered in the United States and other countries. Elements of Apple's Technical User Documentation used by permission from Apple, Inc.

Novell

and NetWare®are registered trademarks of Novell, Inc. in the United States and other countries. Oracle®is a

registered trademark of Oracle Corporation Redwood City, California.

PANTONE

QR Code

™

is a trademark of Denso Wave Incorporated in Japan and/or other countries. TIFF®is a registered trademark of Aldus Corporation.

The Graphics Interchange Format© is the Copyright property of CompuServe Incorporated. GIFSM is a Service Mark of CompuServe Incorporated.

Windows Internet Explorer are trademarks of Microsoft Corporation; Microsoft

, Windows®10, Windows Server®2012, Windows Server®2016, Windows Server®2019, OneDrive®, and

and MS-DOS®are registered trademarks of

Microsoft Corporation.

All other product names and services mentioned in this publication are trademarks or registered trademarks of their respective companies. They are used throughout this publication for the benefit of those companies, and are not intended to convey endorsement or other affiliation with the publication.

Companies, names, and data used in examples herein are fictitious unless otherwise noted.

While every care has been taken in the preparation of this material, no liability will be accepted by Xerox Corporation arising out of any inaccuracies or omissions.

Changes are periodically made to this document. Changes, technical inaccuracies, and typographical errors will be corrected in subsequent editions.

Produced in the United States of America.

Table of Contents

1 Introduction...............................................................................................................................5

VI Suite Customer Forum ....... ..... ........... ........... ........... ...... ..... ...... ..... ...... ........... ........... .......... 6

What is the VIeCD Software Development Kit? .. ...... ..... ...... ..... ...... ........... ........... ........... ......... 7

Where to begin.... ..... ...... ........... ...... ..... ...... ..... ...... ..... ...... ..... ...... ..... ...... ...... ..... ...... ..... ...... ..... 8

Documentation Overview..... ..... ...... ..... ...... ........... ........... ........... ........... ...... ..... ...... ..... ...... ...... 9

2 Background ..............................................................................................................................11

VIeCD Data Flow ..... ..... ...... ..... ...... ...... ..... ...... ..... ........... ........... ...... ..... ...... ..... ...... ........... ..... 13

VIeCD IncomingFolders Filters ... ..... ...... ...... ..... ...... ..... ...... ..... ........... ...... ..... ...... ..... ...... ...... ... 14

Eligibility: CommandTemplates, RuleVars, and the DispatchRule FieldName .. ..... ...... ..... ...... ... 15

Index File......... ........... ........... ........... ...... ..... ...... ..... ...... ........... ........... ........... ...... ..... ...... . 15

RuleVars ..... ..... ...... ..... ...... ...... ..... ...... ..... ........... ........... ...... ..... ...... ..... ...... ........... ........... . 16

Reserved Index File Field Name......... ........... ........... ...... ..... ...... ..... ...... ..... ...... ........... ....... 16

AutoRun Filters ... ...... ..... ...... ........... ........... ........... ...... ..... ...... ..... ...... ..... ...... ........... ........... .... 17

Processing.... ...... ..... ...... ........... ........... ........... ........... ...... ..... ...... ..... ...... ........... ........... ........... 18

VIeCD Job Lifecycle .... ........... ...... ..... ...... ..... ...... ..... ...... ........... ..... ...... ..... ...... ...... ..... ...... ..... .. 19

Ineligible ....... ...... ..... ...... ..... ...... ........... ........... ..... ...... ..... ...... ...... ..... ...... ..... ...... ..... ...... ... 20

Rule Conflict ......... ...... ..... ...... ..... ...... ........... ........... ........... ...... ..... ...... ..... ...... ..... ...... ....... 21

Eligible...... ........... ........... ........... ...... ..... ...... ..... ...... ........... ........... ........... ........... ...... ..... ... 21

Pending ... ...... ..... ...... ..... ........... ...... ..... ...... ..... ...... ........... ........... ........... ........... ...... ..... .... 21

Current ......... ........... ........... ...... ..... ...... ..... ...... ........... ........... ........... ........... ...... ..... ...... .... 21

Held........... ........... ........... ...... ..... ...... ..... ...... ........... ........... ..... ...... ..... ...... ...... ..... ...... ..... .. 21

Complete... ........... ........... ..... ...... ..... ...... ...... ..... ...... ..... ...... ..... ........... ...... ..... ...... ..... ...... .. 22

3 Examples, Libraries, and Utilities .........................................................................................23

Examples ....... ...... ..... ...... ..... ........... ........... ...... ..... ...... ..... ...... ........... ........... ........... ...... ..... .... 24

Forward .. ...... ..... ...... ........... ........... ........... ........... ...... ..... ...... ..... ...... ........... ..... ...... ..... ..... 24

Client.. ........... ...... ..... ...... ..... ...... ........... ........... ..... ...... ..... ...... ...... ..... ...... ..... ...... ..... ...... ... 25

Server ... ...... ..... ...... ...... ..... ...... ..... ...... ..... ........... ...... ..... ...... ..... ...... ...... ..... ........... ........... . 25

Server2 ... ...... ..... ...... ..... ...... ........... ........... ..... ...... ........... ...... ..... ...... ..... ...... ..... ...... ..... ..... 25

Olsend ... ...... ..... ...... ........... ........... ........... ........... ...... ..... ...... ..... ...... ........... ........... ........... 26

Olsession ... ........... ........... ...... ..... ...... ..... ...... ........... ........... ..... ...... ..... ...... ...... ..... ...... ..... .. 26

Wrap ..... ...... ........... ........... ........... ........... ...... ..... ...... ..... ...... ........... ........... ........... ........... 26

Libraries........ ........... ...... ..... ...... ..... ...... ........... ..... ...... ..... ...... ...... ..... ...... ..... ...... ..... ........... ..... 28

vtpdwrap ... ..... ...... ........... ..... ...... ..... ...... ..... ...... ...... ..... ...... ..... ........... ...... ..... ...... ..... ...... .. 28

vtpdsession... ...... ...... ..... ........... ........... ........... ...... ..... ...... ..... ...... ........... ........... ........... .... 28

Utilities..... ........... ..... ...... ..... ...... ..... ...... ...... ..... ...... ..... ...... ..... ...... ..... ...... ..... ...... ........... ...... ... 29

4 VIeC Dispatch In-Circuit Emulator......................................................................................31

Xerox®FreeFlow®VI eCompose Dispatch SDK

User Guide

Table of Contents

Using VIeCDICE... ...... ........... ........... ........... ........... ...... ..... ...... ..... ...... ........... ........... ..... ...... ... 32

Use Case 1......... ...... ..... ...... ..... ...... ........... ..... ...... ..... ...... ........... ...... ..... ...... ..... ........... ..... 32

Use Case 2......... ...... ..... ...... ..... ...... ........... ..... ...... ..... ...... ........... ...... ..... ...... ..... ........... ..... 33

Use Case 3......... ...... ..... ...... ..... ...... ........... ..... ...... ..... ...... ........... ...... ..... ...... ..... ........... ..... 34

Use Case 4......... ...... ..... ...... ..... ...... ........... ..... ...... ..... ...... ........... ...... ..... ...... ..... ........... ..... 36

Using VIeCDICE in Batch Mode ....... ..... ...... ..... ...... ..... ...... ..... ...... ..... ...... ..... ...... ...... ..... ...... ... 37

Xerox®FreeFlow®VI eCompose Dispatch SDK User Guide

Introduction

This chapter contains:

• VI Suite Customer Forum ... ..... ...... ........... ........... ..... ...... ..... ...... ...... ..... ...... ..... ...... ..... ...... ..... ...... . 6

• What is the VIeCD Software Development Kit? .... ........... ...... ..... ........... ........... ...... ..... ...... ..... ...... 7

• Where to begin ...... ..... ...... ..... ...... ........... ........... ........... ........... ...... ..... ...... ..... ...... ........... ........... .. 8

• Documentation Overview. ........... ...... ..... ...... ..... ........... ...... ..... ...... ..... ...... ........... ........... ........... ... 9

This guide is for software developers who use the FreeFlow Development Kit (SDK) to integrate post-processing applications with the VI eCompose (VIeC) software. To use the VI eCompose software, it is recommended that you are familiar with the following software or platforms:

• VIPP

• VIeC Dispatch software

• C, C++ programming language, or the platform applications

It is recommended that users have experience with the VIeC Dispatch software. Refer to the example in the FreeFlow

An overview of VIeC internals, which includes a description of VIeCD data flow and state, is presented in this document. This information is intended to supplement the VIeCD example application and reference material contained in the FreeFlow

Language

VI eCompose User Guide and the VI eCompose Workshop.

VI eCompose User Guide.

Note: All modules in the FreeFlow®VI Suite software product names have changed since the

FreeFlow VI Suite 10.0 Release.

Legacy product name New product name

FreeFlow VI Interpreter FreeFlow VI Compose

FreeFlow VI Interpreter Open Edition FreeFlow VI Compose Open Edition

FreeFlow VI Designer FreeFlow VI Design Pro

VI eCompose Dispatch (VIeCD) Software

FreeFlow VI PDF Originator FreeFlow VI eCompose

FreeFlow VIPP

All other products not mentioned in the list keep the same name used in the previous FreeFlow VI Suite Release.

References to the VIPP unchanged.

Pro Publisher FreeFlow VI Design Express

language, commands, and variable information format remain

Xerox®FreeFlow®VI eCompose Dispatch SDK

User Guide

Introduction

VI Suite Customer Forum

Xerox hosts a Community Support Forum. The VI Suite Customer forum is now part of this larger support forum, allowing you to post and review information about Xerox products and services all from one location. Please take a minute to log into this customer forum community: http://

vippsupport.xerox.com.

Xerox®FreeFlow®VI eCompose Dispatch SDK User Guide

Introduction

What is the VIeCD Software Development Kit?

The VIeCD SDK consists of a collection of examples and starting points, such as source code, utilities, and libraries, which can be used to integrate VIeCD with other workflows. Most of the code provided is in C (with the single exception of the olsession example, which is in C++). One API (Application Programmer's Interface), the dispatch rule wrapper library (vtpdwrap), is presented in the class definition in the file vtpdwrap.h.

Reference documentation in HTML and Adobe PDF format is also provided. Documents in HTML format were extracted from the VIeCD SDK source code, then cross-referenced and indexed, and can be found in the /vipodsdk/docs directory of the VIeCD SDK distribution media. In addition to the PDF file you are reading, PDF documents in the form of readme files can be found in each /vipodsdk/apps subdirectory, these PDF files provide instructions for using the example applications.

Xerox

FreeFlow®VI eCompose Dispatch SDK

User Guide

Introduction

Where to begin

To use the VIeCD SDK, browse to /vipodsdk/docs/index.html. This file provides the basic information you need to get started, such as:

• A brief introduction to the SDK

• Licensing information

• Where to get support, and the platforms which support the VIeCD SDK

• Building the SDK

• Assumptions about the environment and file locations

• Background about VIeCD SDK design decisions

• How the VIeCD SDK is implemented

• Descriptions of the documents and files to review to get started

• A brief description of the contents of the VIeCD SDK, including:

– Utilities

– Libraries

– Example Code

– Example VIPP

Applications

– Win32 File Layout

Additionally, the main page, /vipodsdk/docs/index.html, contains the following links:

Data Structures A page that contains a list of the data structures provided and a brief

description of each data structure. To view complete descriptions of each structure, click the hypertext on this page.

File List A page that contains a list of all documented files and a brief description of

each file. To view complete descriptions of each file, clicking the hypertext on this page.

Data Fields An indexed page that contains a list of all documented struct and union fields,

and links to the structures and unions to which the fields belong.

Globals A list of all documented functions, variables, defines, enums, and typedefs with

links to their related documentation.

Examples A list of the examples provided with the SDK, and links to the source code for

each.

After you review these files, use this document for background information about, and explanations of, the files and utilities that make up the VIeCD SDK.

Xerox®FreeFlow®VI eCompose Dispatch SDK User Guide

Introduction

Documentation Overview

This user guide provides background information on the VIeCD SDK and the VIeCD In-Circuit Emulator (VIeCDICE). The guide is organized as follows:

Background Provides background information on VIeCD and the VIeCD SDK. This

chapter supplements the information in the FreeFlow VI eCompose User Guide, and adds information specific to the VIeCD SDK. The chapter provides an overview of VIeCD and the following topics:

VIeCD data flow

VIeCD IncomingFolders Filters

Eligibility: CommandTemplates, RuleVars and the DispatchRule fieldname

VIeCD job lifecycle

Examples, libraries, and utilities Provides descriptions of the files and utilities provided with the VIeCD

SDK, and examples of how to use them.

VIeC Dispatch In-Circuit Emulator Provides an expanded description of the VIeCDICE utility, and

includes these sections:

Using VIeCDICE

Using VIeCDICE in batch mode

For more information about the VIPP®Language, VI Compose, and related modules, refer to the FreeFlow

Variable Information Suite Documentation. The documentation includes the following

guides:

• FreeFlow

and use VIPP software, the resources necessary to build VIPP

• VIPP

VI Compose User Guide: Provides the background information required to understand

and applications. The guide describes the files and utilities provided with the

Language Reference Manual: Documents the VIPP®commands, VIPP®programming tips,

jobs, and the basics of printing with VIPP®.

and error messages.

• FreeFlow

VI eCompose User Guide: Contains information about how to use the VI eCompose

software to create and dispatch Adobe PDF documents, and administer VIeC Web servers remotely.

• FreeFlow

• VIPP

• FreeFlow

For information about VIPP

VI Design Pro User Guide

Manage User Guide

VI Explorer User Guide

Variable Information Suite Documentation Glossary and Quick Reference

training, contact a Xerox representative.

Xerox

FreeFlow®VI eCompose Dispatch SDK

User Guide

Introduction

Xerox®FreeFlow®VI eCompose Dispatch SDK User Guide

Background

This chapter contains:

• VIeCD Data Flow . ........... ...... ..... ...... ..... ...... ........... ........... ........... ..... ...... ...... ..... ...... ..... ...... ....... 13

• VIeCD IncomingFolders Filters ..... ..... ...... ..... ...... ........... ........... ........... ........... ...... ..... ...... ..... ...... 14

• Eligibility: CommandTemplates, RuleVars, and the DispatchRule FieldName ... ...... ........... ........... 15

• AutoRun Filters ..... ...... ..... ...... ..... ...... ..... ...... ..... ...... ..... ...... ........... ...... ..... ...... ..... ........... ...... ..... . 17

• Processing...... ...... ..... ...... ..... ...... ..... ...... ..... ...... ..... ...... ..... ...... ...... ..... ........... ........... ...... ..... ...... .. 18

• VIeCD Job Lifecycle..... ........... ........... ..... ...... ...... ..... ...... ..... ...... ..... ...... ..... ...... ..... ...... ..... ...... ...... 19

VIeC Dispatch software provides a generic dispatch mechanism, which initiates, then monitors VIeC job post-processing by a customer-specified backend process such as email, fax, or a document repository. In this role, VIeC Dispatch software is considered middleware, as it mediates between completed VIeC jobs and the specified backend post-processing software.

To embed parameters and other data specific to post processing into the VIeC job, use the VIPP BOOKMARK command.

• Parameters and other data are extracted from the field names and values of the index file generated by VIeC.

• VIeC Dispatch software transfers the parameters and other data to the specified backend software.

• Index files for each job contain the extension .csv.

VIeCD supports workflows that require human intervention, or a hands-off workflow, using the AutoRun feature and user filters. For example:

• Backends interface with email-disbursement systems that require:

– Human verification or signoff of the VIeC output before the dispatch

– Limitations on the users allowed to initiate the dispatch of such jobs

• Backends interface with a document repository that requires a hands-off workflow. The VIeC-toVIeCD process runs without human intervention.

When VIeCD invokes a backend program, the parameters are extracted from a VIeC job index file on a line-by-line basis. The process spawns a new instance of the backend program as a new subprocess for each invocation. VIeCD does not allow any direct interaction with the backend program over stdin/stdout during that invocation. The limitation of the invocation may not be suitable for interfacing with all types of backend programs. Potential incompatibilities between the VIeC postprocessing and VIeCD include:

• Programs that require some form of user or programmatic interaction in the normal mode of operation, such as a Yes or No response to a file being overwritten.

• Programs that require some form of session state over a set of transactions, such as logging in to a Microsoft Exchange server to perform email transmissions.

Xerox®FreeFlow®VI eCompose Dispatch SDK

User Guide

Background

• Backend solutions that involve more than one discrete operation, requiring the invocation of multiple, discrete post-processing operations. Examples of the operations are concatenation or other combinations of the files specified in the DataFile Template before submission to one or more backend programs.

VIeCD SDK software contains example code and libraries that can provide the basis for building a shim, wrapper, proxy, or facade to resolve integration issues. The primary focus of the VIeCD SDK examples is centered on a separate server application. The server application acts as a session bridge between a simple client shim that is invoked by VIeCD on an index file line-by-line basis, and the backend program. The backend program can require human interaction or intervention, session state, or multiple post-processing operations.

An alternative to the client-server approach, for backend programs that do not require session state over a set of transactions, is to interpose a proxy program between VIeCD and the backend programs. Backend programs are invoked once for each line in the index file. The proxy assumes the responsibility for interacting with the user if necessary, and acts in the role of a facade for a collective of discrete backend programs if multiple post-processing steps are required. The proxy communicates with VIeCD through documented interfaces (retval, stdin/stdout), and with the backend programs performing the post processing. There are no explicit examples provided with the VIeCD SDK, however, you can configure the VIeCDICE utility to act as a proxy between VIeCD and an otherwise VIeCD-compatible backend program. It is recommended that you review the VIeCDICE source for possible proxy program implementation information.

For more information, refer to these sections of the FreeFlow VI eCompose Dispatch SDK User Guide:

• Examples

• Libraries

• Utilities

• Using VIeCDICE

• Using VIeCDICE in batch mode

Xerox®FreeFlow®VI eCompose Dispatch SDK User Guide

+ 28 hidden pages