bb c LiveCycle ES Services
bc
LiveCycle® ES Services
Adobe® LiveCycle® ES
October 2008
Update 1
© 2008 Adobe Systems Incorporated. All rights reserved.
Adobe® LiveCycle® ES Update 1 (8.2) LiveCycle ES Services for Microsoft® Windows®, Linux®, UNIX®
Edition 2.2, October 2008
If this guide is distributed with software that includes an end user agreement, this guide, as well as the software described in it, is furnished
under license and may be used or copied only in accordance with the terms of such license. Except as permitted by any such license, no part
of this guide may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, electronic, mechanical, recording,
or otherwise, without the prior written permission of Adobe Systems Incorporated. Please note that the content in this guide is protected
under copyright law even if it is not distributed with software that includes an end user license agreement.
The content of this guide is furnished for informational use only, is subject to change without notice, and should not be construed as a
commitment by Adobe Systems Incorporated. Adobe Systems Incorporated assumes no responsibility or liability for any errors or
inaccuracies that may appear in the informational content contained in this guide.
Please remember that existing artwork or images that you may want to include in your project may be protected under copyright law. The
unauthorized incorporation of such material into your new work could be a violation of the rights of the copyright owner. Please be sure to
obtain any permission required from the copyright owner.
Any references to company names, company logos and user names in sample material or sample forms included in this documentation
and/or software are for demonstration purposes only and are not intended to refer to any actual organization or persons.
Adobe, the Adobe logo, Acrobat, Distiller, Flash, Flex Builder, LiveCycle, PostScript, and Reader are either registered trademarks or trademarks
of Adobe Systems Incorporated in the United States and/or other countries.
EMC and Documentum are registered trademarks of EMC Corporation in the United States and around the world. Copyright 1994-2007 EMC
Corporation, all rights reserved.
IBM is a trademark of International Business Machines Corporation in the United States, other countries, or both.
JBoss is a trademark or registered trademark of Red Hat, Inc. in the United States and other countries.
Linux is the registered trademark of Linus Torvalds in the U.S. and other countries.
Mac OS is a trademark of Apple Inc., registered in the United States and other countries.
Microsoft and Windows are either registered trademarks or a trademarks of Microsoft Corporation in the United States and/or other
countries.
Sun and Java are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries.
UNIX is a registered trademark of The Open Group in the US and other countries.
All other trademarks are the property of their respective owners.
This product contains either BSAFE and/or TIPEM software by RSA Security, Inc.
This product includes software developed by the Apache Software Foundation (http://www.apache.org/).
This product includes software developed by the IronSmith Project (http://www.ironsmith.org/).
This product includes software developed by the OpenSymphony Group (http://www.opensymphony.com/).
This product includes software developed by the Indiana University Extreme! Lab (http://www.extreme.indiana.edu/).
This product includes copyrighted software developed by E. Wray Johnson for use and distribution by the Object Data Management Group
(http://www.odmg.org/).
Portions © Eastman Kodak Company, 199- and used under license. All rights reserved. Kodak is a registered trademark and Photo CD is a
trademark of Eastman Kodak Company.
Powered by Celequest. Copyright 2005-2008 Adobe Systems Incorporated. All rights reserved. Contains technology distributed under license
from Celequest Corporation. Copyright 2005 Celequest Corporation. All rights reserved.
Single sign-on, extending Active Directory to Adobe LiveCycle ES provided by Quest Software “www.quest.comlidentity-management” in a
subsequent minor release that is not a bug fix (i.e., version 1.1 to 1.2 but not 1.1.1 to 1.1.2) of the Licensee Product that incorporates the
Licensed Product.
The Spelling portion of this product is based on Proximity Linguistic Technology.
©Copyright 1989, 2004 All Rights Reserved Proximity Technology A Division of Franklin Electronic Publishers, Inc. Burlington, New Jersey
USA.
© Copyright 1990 Merriam-Webster Inc. © Copyright 1990 All Rights Reserved Proximity Technology A Division of Franklin Electronic
Publishers, Inc. Burlington, New Jersey USA.
© Copyright 2003 Franklin Electronic Publishers Inc. © Copyright 2003 All Rights Reserved Proximity Technology A Division of Franklin
Electronic Publishers, Inc. Burlington, New Jersey USA.
© Copyright 2004 Franklin Electronic Publishers, Inc. © Copyright 2004 All Rights Reserved Proximity Technology A Division of Franklin
Electronic Publishers, Inc. Burlington, New Jersey USA.
© Copyright 1991 Dr.Lluis de Yzaguirre I Maura © Copyright 1991 All Rights Reserved Proximity Technology A Division of Franklin Electronic
Publishers, Inc. Burlington, New Jersey USA.
© Copyright 1990 Munksgaard International Publishers Ltd. © Copyright 1990 All Rights Reserved Proximity Technology A Division of Franklin
Electronic Publishers, Inc. Burlington, New Jersey USA.
© Copyright 1995 Van Dale Lexicografie bv © Copyright 1996 All Rights Reserved Proximity Technology A Division of Franklin Electronic
Publishers, Inc. Burlington, New Jersey USA.
© Copyright 1990 IDE a.s. © Copyright 1990 All Rights Reserved Proximity Technology A Division of Franklin Electronic Publishers, Inc.
Burlington, New Jersey USA.
© Copyright 2004 Franklin Electronics Publishers, Inc. © Copyright 2004 All Rights Reserved Proximity Technology A Division of Franklin
Electronic Publishers, Inc. Burlington, New Jersey USA.
© Copyright 1992 Hachette/Franklin Electronic Publishers, Inc. © Copyright 2004 All Rights Reserved Proximity Technology A Division of
Franklin Electronic Publishers, Inc. Burlington, New Jersey USA.
© Copyright 2004 Bertelsmann Lexikon Verlag © Copyright 2004 All Rights Reserved Proximity Technology A Division of Franklin Electronic
Publishers, Inc. Burlington, New Jersey USA.
© Copyright 2004 MorphoLogic Inc. © Copyright 2004 All Rights Reserved Proximity Technology A Division of Franklin Electronic Publishers,
Inc. Burlington, New Jersey USA.
© Copyright 1990 Williams Collins Sons & Co. Ltd. © Copyright 1990 All Rights Reserved Proximity Technology A Division of Franklin Electronic
Publishers, Inc. Burlington, New Jersey USA. © Copyright 1993-95 Russicon Company Ltd.
© Copyright 1995 All Rights Reserved Proximity Technology A Division of Franklin Electronic Publishers, Inc. Burlington, New Jersey USA.
© Copyright 2004 IDE a.s. © Copyright 2004 All Rights Reserved Proximity Technology A Division of Franklin Electronic Publishers, Inc.
Burlington, New Jersey USA.
Adobe Systems Incorporated, 345 Park Avenue, San Jose, California 95110, USA.
Notice to U.S. Government End Users. The Software and Documentation are “Commercial Items,” as that term is defined at 48 C.F.R. §2.101,
consisting of “Commercial Computer Software” and “Commercial Computer Software Documentation,” as such terms are used in 48 C.F.R.
§12.212 or 48 C.F.R. §227.7202, as applicable. Consistent with 48 C.F.R. §12.212 or 48 C.F.R. §§227.7202-1 through 227.7202-4, as applicable,
the Commercial Computer Software and Commercial Computer Software Documentation are being licensed to U.S. Government end users
(a) only as Commercial Items and (b) with only those rights as are granted to all other end users pursuant to the terms and conditions herein.
Unpublished-rights reserved under the copyright laws of the United States. Adobe Systems Incorporated, 345 Park Avenue, San Jose, CA
95110-2704, USA. For U.S. Government End Users, Adobe agrees to comply with all applicable equal opportunity laws including, if
appropriate, the provisions of Executive Order 11246, as amended, Section 402 of the Vietnam Era Veterans Readjustment Assistance Act of
1974 (38 USC 4212), and Section 503 of the Rehabilitation Act of 1973, as amended, and the regulations at 41 CFR Parts 60-1 through 60-60,
60-250, and 60-741. The affirmative action clause and regulations contained in the preceding sentence shall be incorporated by reference.
Contents
About This Document.................................................................................................................. 9
What’s in this document?............................................................................................................................................................ 9
Who should read this document? ............................................................................................................................................ 9
Additional information................................................................................................................................................................. 9
1
Introducing LiveCycle ES Services............................................................................................ 10
Determining which services belong to a solution component...................................................................................10
How developers interact with services.................................................................................................................................10
How administrators interact with services..........................................................................................................................10
2
Assembler Service...................................................................................................................... 11
About DDX......................................................................................................................................................................................11
Using the Assembler service ....................................................................................................................................................12
Assembling PDF documents..............................................................................................................................................12
Assembling encrypted documents...........................................................................................................................13
Assembling documents using Bates numbering.................................................................................................13
Flattening and assembling documents...................................................................................................................13
Disassembling PDF documents ........................................................................................................................................14
Determining whether documents are PDF/A compliant ........................................................................................15
Validating DDX documents................................................................................................................................................15
Considerations for the Assembler service...........................................................................................................................16
3
Barcoded Forms Service............................................................................................................ 17
About barcoded forms ...............................................................................................................................................................17
About barcode data ....................................................................................................................................................................17
Using the Barcoded Forms service.........................................................................................................................................19
Encoding and decoding formats ............................................................................................................................................20
User-specified character sets ...................................................................................................................................................20
Supported symbologies.............................................................................................................................................................20
4
Connector Services for ECM ...................................................................................................... 21
Using the ECM connector services.........................................................................................................................................21
5
Convert PDF Service .................................................................................................................. 23
Using the Convert PDF service ................................................................................................................................................23
6
Decision Point Service ............................................................................................................... 24
Using the Decision Point service ............................................................................................................................................24
7
Distiller Service .......................................................................................................................... 25
Using the Distiller service ..........................................................................................................................................................25
8
DocConverter Service................................................................................................................ 26
Using the DocConverter service .............................................................................................................................................26
Validating whether PDF documents are compliant with the PDF/A format....................................................26
Converting PDF documents to PDF/A format .............................................................................................................26
9
Document Management Service .............................................................................................. 28
Using the Document Management service........................................................................................................................28
Working with contents and spaces .................................................................................................................................28
4
Adobe LiveCycle ES
Contents
LiveCycle ES Services
5
Working with associations..................................................................................................................................................29
Working with content attributes......................................................................................................................................29
Considerations for LiveCycle Contentspace ES .................................................................................................................29
10 Email Service .............................................................................................................................. 30
Using the Email service ..............................................................................................................................................................30
11 Encryption Service..................................................................................................................... 31
Using the Encryption service....................................................................................................................................................31
Encrypting PDF documents with a password..............................................................................................................31
Removing password encryption ......................................................................................................................................32
Encrypting PDF documents with certificates ..............................................................................................................32
Removing certificate-based encryption ........................................................................................................................33
Unlocking encrypted PDF documents ...........................................................................................................................33
Determining the encryption type....................................................................................................................................33
Considerations for the Encryption service ..........................................................................................................................33
12 Execute Script Service ............................................................................................................... 34
Using the Execute Script service.............................................................................................................................................34
13 FTP Service ................................................................................................................................. 35
Using the FTP service ..................................................................................................................................................................35
Considerations for the FTP service.........................................................................................................................................35
14 File Utilities Service ................................................................................................................... 36
Using the File Utilities service ..................................................................................................................................................36
Considerations for the File Utilities service.........................................................................................................................36
15 Form Augmenter Service .......................................................................................................... 37
Using the Form Augmenter service.......................................................................................................................................37
16 Form Data Integration Service ................................................................................................. 38
Using the Form Data Integration service.............................................................................................................................38
17 Forms Service............................................................................................................................. 40
About form types .........................................................................................................................................................................41
How the Forms service processes requests ........................................................................................................................42
Requesting a form .................................................................................................................................................................42
Using Form Design buttons ...............................................................................................................................................44
Submit button ..................................................................................................................................................................44
Calculate button ..............................................................................................................................................................47
Using the Forms service.............................................................................................................................................................48
Rendering interactive PDF forms .....................................................................................................................................48
Rendering form guides ........................................................................................................................................................49
Rendering forms as HTML...................................................................................................................................................50
Forms service options.................................................................................................................................................................50
Rendering forms based on fragments............................................................................................................................50
Rendering rights-enabled forms ......................................................................................................................................51
Handling submitted forms .................................................................................................................................................52
Prepopulating forms.............................................................................................................................................................54
Calculating form data...........................................................................................................................................................59
Optimizing an application ..................................................................................................................................................61
Considerations for the Forms service....................................................................................................................................61
Planning your form design.................................................................................................................................................61
Creating form designs for the Forms service ...............................................................................................................62
Adobe LiveCycle ES
Contents
LiveCycle ES Services
6
Rendering forms that contain images............................................................................................................................63
Rendering a PDF form that includes a secured image .............................................................................................64
Changes to image fields using a script are not retained .........................................................................................64
Enabling debug options......................................................................................................................................................64
18 Generate PDF Service ................................................................................................................ 65
Using the Generate PDF service..............................................................................................................................................65
Converting various types of files to PDF documents................................................................................................65
Converting HTML files to PDF documents....................................................................................................................66
Converting PDF files to various types of documents................................................................................................66
19 Generate 3D PDF Service .......................................................................................................... 68
Using the Generate 3D PDF service.......................................................................................................................................69
Creating a 3D PDF using server settings........................................................................................................................69
Creating a 3D PDF using settings in an XML file.........................................................................................................69
20 JDBC Service............................................................................................................................... 70
Using the JDBC service ...............................................................................................................................................................70
Considerations for the JDBC service......................................................................................................................................70
21 JMS Service................................................................................................................................. 71
Using the JMS service .................................................................................................................................................................71
Considerations for the JMS service ........................................................................................................................................71
22 LDAP Service .............................................................................................................................. 72
Using the LDAP service ..............................................................................................................................................................72
Considerations for the LDAP service .....................................................................................................................................72
23 Output Service ........................................................................................................................... 73
Using the Output service...........................................................................................................................................................73
Creating PDF documents ....................................................................................................................................................73
Creating PDF/A documents ...............................................................................................................................................74
Sending print streams to printers ....................................................................................................................................74
Processing batch data to create multiple documents .............................................................................................77
Creating search rules ............................................................................................................................................................80
Flattening interactive PDF documents ..........................................................................................................................81
Considerations for the Output service .................................................................................................................................81
Form data..................................................................................................................................................................................82
Supported document types...............................................................................................................................................83
Signature fields .......................................................................................................................................................................84
Flattening a digitally signed PDF document ...............................................................................................................84
Email support ..........................................................................................................................................................................84
Maximizing throughput ......................................................................................................................................................84
Printable areas.........................................................................................................................................................................85
Scripts.........................................................................................................................................................................................85
Working with fonts................................................................................................................................................................86
Font mapping..........................................................................................................................................................................86
Coordinating fonts between Designer ES and the Output service......................................................................87
Working with device profile files (XDC file) ..................................................................................................................87
Setting up Zebra printers for RFID label printing.......................................................................................................88
Printer tray selection.............................................................................................................................................................88
Paper handling........................................................................................................................................................................89
Working with the XCI configuration file ........................................................................................................................90
Setting XCI configuration file options......................................................................................................................90
Adobe LiveCycle ES
Contents
LiveCycle ES Services
7
Embedding fonts .............................................................................................................................................................92
CIFS printing support ...........................................................................................................................................................92
Improving the performance of the Output service ...................................................................................................93
24 PDF Utilities Service .................................................................................................................. 94
Using the PDF Utilities service .................................................................................................................................................94
25 Reader Extensions Service ........................................................................................................ 96
Using the Reader Extensions service.....................................................................................................................................96
Applying usage rights to PDF documents ....................................................................................................................97
Removing usage rights from PDF documents ............................................................................................................98
Retrieving credential information....................................................................................................................................98
Considerations for the Reader Extensions service ...........................................................................................................98
Configuring the credential .................................................................................................................................................98
Order of operations...............................................................................................................................................................98
Adding usage rights to interactive forms .....................................................................................................................99
Adding usage rights to forms that populate fields with data................................................................................99
Opening rights-enabled PDF documents .....................................................................................................................99
26 Repository Service ...................................................................................................................100
Using the Repository service................................................................................................................................................. 100
27 Rights Management Service ...................................................................................................101
About policies............................................................................................................................................................................. 102
About policy sets ....................................................................................................................................................................... 102
Security methods and technology...................................................................................................................................... 102
Authentication ..................................................................................................................................................................... 103
Methods of authentication ....................................................................................................................................... 103
SAML authentication assertions.............................................................................................................................. 103
Role-based access control ............................................................................................................................................... 104
Document confidentiality................................................................................................................................................ 104
Policy-protecting documents for online use ...................................................................................................... 104
Accessing policy-protected documents online................................................................................................. 105
Policy-protecting documents for offline use...................................................................................................... 106
Security standards and technology.............................................................................................................................. 107
Using the Rights Management service.............................................................................................................................. 107
Creating policies.................................................................................................................................................................. 107
Modifying policies .............................................................................................................................................................. 108
Deleting policies.................................................................................................................................................................. 109
Applying policies to documents ................................................................................................................................... 109
Removing policies from documents............................................................................................................................ 109
Switching the policy applied to a document............................................................................................................ 110
Revoking access to policy-protected documents ................................................................................................... 110
Monitoring events .............................................................................................................................................................. 111
28 Set Value Service .....................................................................................................................112
Using the Set Value service.................................................................................................................................................... 112
29 Signature Service.....................................................................................................................113
About digital signatures ......................................................................................................................................................... 113
About signature fields ............................................................................................................................................................. 114
About the Signature service and form types .................................................................................................................. 114
About digital signature technology ................................................................................................................................... 115
Integrating with a security infrastructure......................................................................................................................... 117
Adobe LiveCycle ES
Contents
LiveCycle ES Services
8
Supported technologies and standards ........................................................................................................................... 117
Using the Signature service................................................................................................................................................... 118
Signing and certifying documents ............................................................................................................................... 118
Validating document integrity and authenticity..................................................................................................... 119
Removing signatures......................................................................................................................................................... 119
Retrieving signatures and signature fields ................................................................................................................ 120
Adding, modifying, and removing signature fields................................................................................................ 120
Best practices .............................................................................................................................................................................. 120
Ensuring that no rendering occurs after signing..................................................................................................... 121
Converting to non-interactive form............................................................................................................................. 121
Checking the form type .................................................................................................................................................... 122
Requirements for form design and Workspace ES ................................................................................................. 122
Order of operations .................................................................................................................................................................. 122
30 Stall Service ..............................................................................................................................123
Using the Stall service.............................................................................................................................................................. 123
31 User Service..............................................................................................................................124
Using the User service ............................................................................................................................................................. 124
Assigning tasks .................................................................................................................................................................... 124
Configuring task features................................................................................................................................................. 125
Configuring email notifications ..................................................................................................................................... 125
Saving information about completed tasks.............................................................................................................. 126
Interacting with tasks............................................................................................................................................................... 126
Reacting to task events..................................................................................................................................................... 126
Retrieving task information............................................................................................................................................. 126
Intervening in task status................................................................................................................................................. 127
32 Variable Logger Service ..........................................................................................................128
Using the Variable Logger service....................................................................................................................................... 128
33 Wait Point Service....................................................................................................................129
Using the Wait Point service.................................................................................................................................................. 129
34 Web Service Service.................................................................................................................130
Using the Web Service service.............................................................................................................................................. 130
35 XMP Utilities Service................................................................................................................131
About XMP metadata .............................................................................................................................................................. 131
About metadata in PDF documents................................................................................................................................... 131
Using the XMP Utilities service ............................................................................................................................................. 132
36 XSLT Transformation Service .................................................................................................133
Using the XSLT Transformation service............................................................................................................................. 133
About This Document
This document describes the services that developers can use to create Adobe® LiveCycle® ES
(Enterprise Suite) Update 1 applications.
What’s in this document?
This document provides introductory information about services in LiveCycle ES and how they can be
used to accomplish different tasks as part of a business process. It also includes information about
managing services and applications.
Who should read this document?
This document is primarily intended for people who are designing processes in
Adobe LiveCycle Workbench ES (8.2) or developers who want to build client applications that
programmatically interact with services. The document also includes information of interest to
administrators who manage LiveCycle ES servers and applications.
Additional information
In addition to this document, the resources in the table provide further information about the services.
For information about
See
LiveCycle ES solution components
LiveCycle ES Overview
The services licensed for use with each
LiveCycle ES solution component
Services for LiveCycle ES Solution Components
The programming interfaces licensed for use
with each LiveCycle ES solution component
Programming Interfaces for LiveCycle ES Solution
Components
Using a service in a process map
LiveCycle Workbench ES Help
Using a service’s API
Programming with LiveCycle ES
Administering a service
Administering LiveCycle ES
9
1
Introducing LiveCycle ES Services
Each LiveCycle ES solution component makes use of several services to accomplish different tasks as part
of a business process. This document describes the services that developers and programmers can use to
create LiveCycle ES applications.
Determining which services belong to a solution component
Each service is licensed for use with one or more LiveCycle ES solution components in a production
environment. The LiveCycle Foundation services are licensed for use with all LiveCycle ES solution
components. For details about which services are licensed for use with each solution component, see
Services for LiveCycle ES Solution Components.
How developers interact with services
When a service or application is deployed within LiveCycle ES, it can be invoked by a client application
using different mechanisms. From LiveCycle Administration Console, a service can be configured to be
exposed by one or more of these mechanisms.
You can interact with a service in any of the following ways:
●
Develop a process in LiveCycle Workbench ES that uses the service.
●
Develop a client application that uses the service’s API in Java™ or in an environment that permits you
to use its exposed WSDL, such as Microsoft® Visual Studio .NET. Most services provide public APIs.
●
Develop a client application in Adobe Flex® Builder™ that uses LiveCycle Remoting to interact with the
service. Most services can be invoked by using LiveCycle Remoting.
A service can also be invoked by using email and watched folders. For more information about the
different ways in which to invoke services, see “Invoking LiveCycle ES” in Programming with LiveCycle ES.
How administrators interact with services
You can use LiveCycle Administration Console to perform these tasks:
●
Configure and manage users, groups, and server authentication settings by using User Management.
●
Create and manage invocation endpoints and deploy LiveCycle ES archive (LCA) files.
●
Set up watched folders and email providers for non-programmatic process invocation.
●
Administer solution component properties and server settings such as port numbers and log files.
10
2
Assembler Service
The Assembler service enables you to combine multiple PDF documents into one PDF document or to
break apart one PDF document into multiple PDF documents. The Assembler service can manipulate
documents in various ways such as changing page size and rotating contents. It can insert additional
content such as headers, footers, and a table of contents. It can preserve, import, or export existing
content such as annotations, file attachments, and bookmarks.
Each job submitted to the Assembler service includes a Document Description XML (DDX) document and
a set of source PDF and XML documents. The DDX document provides instructions on how to use the
source documents to produce a set of result documents.
This section includes the following topics:
●
“About DDX” on page 11
●
“Using the Assembler service” on page 12
●
“Considerations for the Assembler service” on page 16
About DDX
When using the Assembler service, you use an XML-based language called Document Description XML
(DDX) to describe the output you want. DDX is a declarative markup language whose elements represent
building blocks of documents. These building blocks include PDF pages and other elements such as
comments, bookmarks, and styled text.
In addition to PDF documents, DDX can describe output formats that represent data extracted from PDF
documents (such as comments, text, form data, file attachments, and bookmarks) or provide information
about the properties of a PDF document.
You can use DDX to manipulate a document in conjunction with document assembly or disassembly. You
can specify any combination of the following effects:
●
Add or remove watermarks or backgrounds on selected pages.
●
Add or remove headers and footers on selected pages.
●
Create or flatten a PDF package.
●
Renumber page labels. Page labels are typically used for page numbering.
●
Import metadata from another source document.
●
Add or remove file attachments, bookmarks, links, and comments.
●
Set initial view characteristics and optimize for viewing on the web.
●
Set permissions for encrypted PDF.
●
Rotate pages or rotate and shift content on pages.
For details about DDX, see DDX Reference.
11
Adobe LiveCycle ES
LiveCycle ES Services
Assembler Service
Using the Assembler service
12
Using the Assembler service
You can accomplish the following tasks using the Assembler service:
●
“Assembling PDF documents” on page 12
●
“Disassembling PDF documents” on page 14
●
“Determining whether documents are PDF/A compliant” on page 15
●
“Validating DDX documents” on page 15
For information about developing processes that use this service, see LiveCycle Workbench ES Help. For
information about developing client applications that programmatically interact with this service, see
Programming with LiveCycle ES.
Assembling PDF documents
You can use the Assembler service to assemble two or more PDF documents into a single PDF document.
The following illustration shows three source documents being merged into a single result document.
The following example is a simple DDX expression used to assemble the document. It specifies the names
of the source documents used to produce the result document, as well as the name of the result
document:
<PDF result="Doc4">
<PDF source="Doc1"/>
<PDF source="Doc2"/>
<PDF source="Doc3"/>
</PDF>
Document assembly produces a result document that contains the following:
●
All or part of each source document
●
All or part of the bookmarks from each source document, normalized for the assembled result
document
Adobe LiveCycle ES
LiveCycle ES Services
Assembler Service
Assembling PDF documents
●
Other characteristics adopted from the base document (Doc1), including metadata, page labels, and
page size
●
Optionally, the result document may include a table of contents constructed from the bookmarks in
the result
13
Assembling encrypted documents
When you assemble a document, you can also encrypt the PDF document with a password. After a PDF
document is encrypted with a password, a user must specify the password to view the PDF document in
Adobe Reader, Adobe Acrobat Professional, or Acrobat Standard. To encrypt a PDF document with a
password, the DDX document must contain encryption element values that are required to encrypt a PDF
document.
The Encryption service does not have to be part of your LiveCycle ES installation to encrypt a PDF
document with a password.
If one or more of the input documents is encrypted, you must provide a password to open the document
as part of the DDX.
Assembling documents using Bates numbering
When you assemble a document, you can use Bates numbering to apply a unique page identifier to each
page. When you use Bates numbering, each page in the document (or set of documents) is assigned a
number that uniquely identifies the page. For example, manufacturing documents that contain bill of
material information and are associated with the production of an assembly can contain an identifier. A
Bates number contains a sequentially incremented numeric value and an optional prefix and suffix. The
prefix + numeric value + suffix is referred to as a bates pattern.
The following illustration shows a PDF document that contains a unique identifier located in the
document’s header.
Flattening and assembling documents
You can use the Assembler service to assemble and transform interactive PDF documents (for example,
forms) to a non-interactive PDF document. An interactive PDF document lets users enter or modify data
located in the PDF document fields. The process of transforming an interactive PDF document to a
non-interactive PDF document is called flattening. When a PDF document is flattened, form fields retain
their graphical appearance but are no longer interactive. One reason to flatten a PDF document is to
ensure that data cannot be modified. In addition, scripts associated with the fields no longer function.
Note: The Assembler service can assemble non-interactive PDF documents without the Output service
being part of your LiveCycle ES installation if the input PDF document is based on an Acrobat form
or a static XFA form. However, if the input PDF document is a dynamic XFA form, the Output service
Adobe LiveCycle ES
Assembler Service
LiveCycle ES Services
Disassembling PDF documents
14
must be part of your LiveCycle ES installation. If the Output service is not part of your LiveCycle ES
installation when a dynamic XFA form is assembled, an exception is thrown.
Disassembling PDF documents
You can use the Assembler service to disassemble a PDF document by extracting pages from the source
document or by breaking apart a source document based on bookmarks. Typically, this task is useful when
the PDF document was originally created from many individual documents, such as a collection of
statements.
Extracting pages from a source document
In the following illustration, pages 1 to 3 are extracted from the source document and placed in a new
result document.
Source documents
Doc2
Pages 1-100
Result document
Doc4
Pages 1-3
The following example is a DDX expression used to disassemble the document.
<PDF result="Doc4">
<PDF source="Doc2" pages="1-3"/>
</PDF>
Adobe LiveCycle ES
Assembler Service
LiveCycle ES Services
Determining whether documents are PDF/A compliant
15
Breaking apart a source document based on bookmarks
In the following illustration, DocA is split into multiple result documents, where the first level-1 bookmark
on a page identifies the start of a new result document.
Source documents
DocA
Result document
A.000001.Bkmk1.pdf
A.000002.Bkmk2.pdf
A.000003.Bkmk3.pdf
The following example is a DDX expression that uses bookmarks to disassemble a source document.
<PDFsFromBookmarks prefix="A">
<PDF source="DocA"/>
</PDFsFromBookmarks>
Determining whether documents are PDF/A compliant
You can use the Assembler service to determine whether a PDF document is PDF/A-compliant. PDF/A is an
archival format meant for long-term preservation of the document’s content. The fonts are embedded
within the document, and the file is uncompressed. As a result, a PDF/A document is typically larger than a
standard PDF document. Also, a PDF/A document does not contain audio and video content.
The PDF/A-1 specification consists of two levels of conformance, namely A and B. The major difference
between the two levels is the logical structure (accessibility) support, which is not required for
conformance level B. At this time, only PDF/A-1b is supported in validation (and conversion).
Validating DDX documents
You can use the Assembler service to determine whether a DDX document is valid. For example, if you
upgraded from a previous LiveCycle version and you want to ensure that your DDX document is valid, you
can validate it using the Assembler service.
Adobe LiveCycle ES
LiveCycle ES Services
Assembler Service
Considerations for the Assembler service
16
Considerations for the Assembler service
When you add headers and footers during the assembling of large documents, you may encounter an
OutOfMemory error and the files will not be assembled. To reduce the likelihood of this problem, add a
<DDXProcessorSetting> element to your DDX. For example:
<DDXProcessorSetting name="checkpoint" value="2000" />
You can add this element as a child of the <DDX> element or as a child of a <PDF result> element. The
default value for this setting is 0 (zero), which turns checkpointing off and the DDX behaves as if the
<DDXProcessorSetting> element is not present. If you have encountered an OutOfMemory error, you
may need to set the value to an integer, typically between 500 and 5000. A small checkpoint value results
in more frequent checkpointing, which reduces the memory needs but also slows down the assembly. For
details about DDX, see DDX Reference.
3
Barcoded Forms Service
The Barcoded Forms service extracts data from electronic images of barcodes. The service accepts TIFF
and PDF files that include one or more barcodes as input and extracts the barcode data. Barcode data can
be formatted in a variety of ways, including XML, delimited string, or any custom format created with
JavaScript.
This section provides information about barcoded forms and a brief overview about how to use them:
●
“About barcoded forms” on page 17
●
“About barcode data” on page 17
●
“Using the Barcoded Forms service” on page 19
●
“Encoding and decoding formats” on page 20
●
“User-specified character sets” on page 20
●
“Supported symbologies” on page 20
About barcoded forms
Form authors create interactive barcoded forms using Adobe LiveCycle Designer ES (8.2). (See LiveCycle
Designer ES Help.) When a user fills a barcoded form by using Adobe Reader or Acrobat, the barcode is
updated automatically to encode the form data.
The Barcoded Forms service is useful for moving data that exists on paper into electronic format. For
example, when a barcoded form is filled and printed, the printed copy can be scanned and used as input
to the Barcoded Forms service.
Watched folder endpoints are typically used to invoke applications that use the Barcoded Forms service.
For example, document scanners can save TIFF or PDF images of barcoded forms in a watched folder. The
watched folder endpoint passes the images to the LiveCycle ES service for decoding.
Note: Barcodes do not have to originate from forms. The Barcoded Forms service can decode any barcode
that uses supported symbology.
About barcode data
For each barcode in an image, the Barcoded Forms service locates the barcode, decodes it, and extracts
the data. The service returns the barcode data (using entity encoding where required) in a content
17
Adobe LiveCycle ES
Barcoded Forms Service
LiveCycle ES Services
About barcode data
element of an XML document. For example, the following scanned TIFF image of a form contains two
barcodes:
18
Adobe LiveCycle ES
LiveCycle ES Services
Barcoded Forms Service
Using the Barcoded Forms service
19
The Barcoded Forms service returns the following XML document after decoding the barcodes:
<?xml version="1.0" encoding="UTF-8" ?>
<xb:scanned_image xmlns:xb="http://decoder.barcodedforms.adobe.com/xmlbeans"
path="tiff" version="1.0">
<xb:decode>
<xb:date>2007-05-11T15:07:49.965-04:00</xb:date>
<xb:host_name>myhost.adobe.com</xb:host_name>
<xb:status type="success">
<xb:message />
</xb:status>
</xb:decode>
<xb:barcode id="1">
<xb:header symbology="pdf417">
<xb:location page_no="1">
<xb:coordinates>
<xb:point x="0.119526625" y="0.60945123" />
<xb:point x="0.44457594" y="0.60945123" />
<xb:point x="0.44457594" y="0.78445125" />
<xb:point x="0.119526625" y="0.78445125" />
</xb:coordinates>
</xb:location>
</xb:header>
<xb:body>
<xb:content encoding="utf-8">t_SID t_FirstName t_MiddleName t_LastName
t_nFirstName t_nMiddleName t_nLastName 90210 Patti Y Penne Patti P
Prosciutto</xb:content>
</xb:body>
</xb:barcode>
<xb:barcode id="2">
<xb:header symbology="pdf417">
<xb:location page_no="1">
<xb:coordinates>
<xb:point x="0.119526625" y="0.825" />
<xb:point x="0.44457594" y="0.825" />
<xb:point x="0.44457594" y="0.9167683" />
<xb:point x="0.119526625" y="0.9167683" />
</xb:coordinates>
</xb:location>
</xb:header>
<xb:body>
<xb:content encoding="utf-8">t_FormType t_FormVersion ChangeName
20061128</xb:content>
</xb:body>
</xb:barcode>
</xb:scanned_image>
Using the Barcoded Forms service
You can accomplish the following tasks using the Barcoded Forms service:
●
Extract barcode data from barcode images (TIFF or PDF). The data is stored as delimited text.
●
Convert delimited text data to XML (XDP or XFDF). XML data is easier to parse than delimited text. Also,
data in XDP or XFDF format can be used as input for other LiveCycle ES services.
Adobe LiveCycle ES
LiveCycle ES Services
Barcoded Forms Service
Encoding and decoding formats
20
For information about developing processes that use this service, see LiveCycle Workbench ES Help. For
information about developing client applications that programmatically interact with this service, see
Programming with LiveCycle ES.
You can use the Applications and Services pages of LiveCycle Administration Console to configure default
properties for this service. (See Applications and Services Administration Help.)
Encoding and decoding formats
Barcoded form authors are encouraged to use a simple, delimited format (such as tab-delimited) when
encoding data in barcodes and to avoid using Carriage Return as the field delimiter. Designer ES provides a
selection of delimited encodings that automatically generate JavaScript script to encode barcodes. The
decoded data has the field names on the first line and their values on the second line with tabs between
each field.
When decoding barcodes, you specify the character used to delimit fields. The character specified for
decoding must be the same character that was used for encoding the barcode. For example, when form
authors use the recommended tab-delimited format, the Extract to XML operation in processes should use
the default value of Tab for the field delimiter.
User-specified character sets
When form authors add barcode objects to their forms using Designer ES, they can specify a character
encoding. The recognized encodings are: UTF-8, ISO-8859-1, ISO-8859-2, ISO-8859-7, Shift-JIS, KSC-5601,
Big-Five, GB-2312, UTF-16. By default, all data is encoded in barcodes as UTF-8.
When decoding barcodes, you can specify the character set encoding to use. To guarantee that all data is
decoded correctly, specify the same character set as the one specified by the form author when the form
was designed.
Supported symbologies
The Barcoded Forms service supports the following two-dimensional symbologies:
●
PDF417
●
Data Matrix
●
QR Code
In addition, the service supports the following one-dimensional symbologies:
●
Codabar
●
Code128
●
Code 3 of 9
●
EAN13
●
EAN8
4
Connector Services for ECM
Adobe LiveCycle ES 8.2 Connector for EMC Documentum, Adobe LiveCycle ES 8.2
Connector for IBM Content Manager, and Adobe LiveCycle ES 8.2 Connector for IBM FileNet provide the
following services:
A repository provider service: The Repository Provider service for EMC Documentum and the
Repository Provider service for IBM FileNet provide storage and retrieval capabilities through the
Repository Service API. These services enable developers to access and manage assets stored in the
ECM content repository at design time.
When a developer designs a form, and creates an application in LiveCycle Workbench ES or using the
Repository Service API, the developer can use the assets in an ECM content repository instead of the
repository provided with LiveCycle ES. Such assets may include forms, PDF files, fragments, images,
XML schemas, and test data. Developers can create an application allowing LiveCycle ES services to
access these assets through the Repository Service API, process variables, and property sheets. Form
designers can access and store these assets directly in the ECM content repository within
Workbench ES.
A content repository connector service: The Content Repository Connector for EMC Documentum
service, the Content Repository Connector for IBM Content Manager service, and the
Content Repository Connector for IBM FileNet service are all independent and usable as operations in a
LiveCycle ES process. Workbench ES developers can use these services in a process to store content in
and retrieve content from custom content models in an ECM content repository. Each connector
service provides access to content objects and their metadata stored in the ECM content repository.
Take the example of a financial institution automating an account opening process. The process must
enable applicants to digitally sign application forms, archive the completed forms in the ECM
repository, retrieve the final declaration and other relevant documentation, assemble those documents
into a single PDF file, and deliver the PDF file to applicants through email or post. The LiveCycle ES
application that the financial institution develops for this process includes content repository
connector service operations to store the completed forms in a customer-defined content object type
in the ECM repository and to retrieve the documentation, which can be generated from other ECM
applications, for assembly from the ECM repository.
Process Engine Connector for IBM FileNet service: Workbench ES developers can also use the
Process Engine Connector for IBM FileNet service to create processes that set and retrieve IBM FileNet
Workflow Step parameters and dispatch a workflow step. (See LiveCycle Workbench ES Help.)
At run time, assets can be retrieved from the ECM content repository as part of completing a business
process. For example, end users can access forms and submit form data from
Adobe LiveCycle Workspace ES (8.2), EMC Documentum Webtop, IBM Content Manager client, or IBM
FileNet P8 Workplace. Alternatively, a client application can retrieve and store content as part of an
automated business process.
Using the ECM connector services
To access an ECM from Resource View in Workbench ES or programmatically using the
Repository Service API, administrators must select the appropriate ECM repository service provider in
LiveCycle Administration Console instead of the default repository provider service provided with
21
Adobe LiveCycle ES
LiveCycle ES Services
Connector Services for ECM
Using the ECM connector services
22
LiveCycle ES. For information about setting up the ECM connector services, see the LiveCycle ES
installation guides, such as Installing and Deploying LiveCycle ES for JBoss.
You can access an ECM content repository by using the LiveCycle Form Design perspective in
Workbench ES. You will be logged in to the default Documentum repository or FileNet object store. You
can also specify a Documentum or FileNet repository when you log in to Workbench ES. You must have the
appropriate credentials to access the content repository. Each time you use Workbench ES, a connection
to the selected content repository is made. The content repository is exposed as a hierarchical directory
structure (below a docbase or objectstore directory) in the Resources View in Workbench ES. You can share
the content repository from Workbench ES with other developers.
When developing a process that uses a Repository Provider service, you can specify the resource URL to
the ECM content repository in the properties associated with a service, such as the Forms service. You can
also specify the resource URL using the Forms Service API.
Note: Connector for IBM Content Manager does not currently support the Repository Provider service.
You can also access an ECM content repository using the Repository Service API to programmatically store
and retrieve information. For example, you can obtain a list of files or retrieve specific files stored in an ECM
content repository when a file is needed as part of processing an application.
You can use a content repository connector service in a process to interact with content objects in an ECM
content repository. When using this service in a process, you can accomplish tasks such as these:
●
Access a user-defined content repository (a repository other than the one used by the repository
provider).
●
Retrieve content and its attributes from the content repository that another service can consume in a
subsequent step in the process.
●
Store content and its attributes in the content repository that another service produced in a previous
step in the process.
●
Get a list of available custom data models from the content repository and map process variables to
content attributes in the content repository.
For information about developing processes that use these services, see LiveCycle Workbench ES Help. For
information about developing client applications that programmatically interact with these services, see
Programming with LiveCycle ES.
You configure the default connection to the ECM content repository, change the repository service
provider, and specify other ECM-specific default settings by using LiveCycle Administration Console. (See
Applications and Services Administration Help, Documentum Administration Help, IBM Content Manager
Administration Help, and FileNet Administration Help.)
5
Convert PDF Service
The Convert PDF service converts PDF documents to PostScript® or image files (JPEG, JPEG 2000, PNG, and
TIFF). Converting a PDF document to PostScript is useful for unattended server-based printing on any
PostScript printer. Converting a PDF document to a multipage TIFF file is practical when archiving
documents in content management systems that do not support PDF documents.
Using the Convert PDF service
You can accomplish the following tasks using the Convert PDF service:
●
Convert PDF documents to PostScript. When converting to PostScript, the conversion operation allows
you to specify the source document and whether to convert to PostScript level 2 or 3. The PDF
document you convert to a PostScript file must be a non-interactive PDF document.
●
Convert PDF documents to JPEG, JPEG 2000, PNG, and TIFF image formats. When converting to any of
these image formats, the conversion operation allows you to specify the source document and an
image options specification containing various preferences, such as image conversion format, image
resolution, and color conversion.
For information about developing processes that use this service, see LiveCycle Workbench ES Help. For
information about developing client applications that programmatically interact with this service, see
Programming with LiveCycle ES.
You use the Applications and Services pages of LiveCycle Administration Console to configure default
properties for this service. (See Applications and Services Administration Help.)
23
6
Decision Point Service
The Decision Point service provides the capability to identify a point in the process where a decision is
made that affects how the process progresses.
Several situations require the use of the Decision Point service:
●
Several routes need to be evaluated to determine the first operation to execute in a process.
This situation occurs when a process is initiated when a person submits a form, and form data
determines the first action to execute in the process map. For example, a customer can fill an invoice
dispute form through your corporate web site. The dollar amount of the invoice determines whether
the form is routed to a first-level manager for approval or to a credit representative for processing.
●
Several different routes in a process converge at a point where a set of rules are evaluated.
This situation can occur when the process loops to a step where a set of rules are re-evaluated. For
example, in a quality assurance process, an issue may have to go through a retesting process until it is
fixed and the process can proceed.
This situation can also occur if several branches converge after running in parallel. For example, in a
process for hiring new employees, when an applicant is hired, several subprocesses are initiated as part
of the hiring process. When each of the subprocesses completes, multiple rules based on the data of
each subprocess are evaluated to determine the next step.
Using the Decision Point service
You can use this service in a process when you need multiple routes to originate at an operation but there
is no single step in the business process that requires the evaluation of routes. The Decision Point service
acts as a node in the process that serves as the origin of many routes, but has no executable function itself.
For information about developing processes that use this service, see LiveCycle Workbench ES Help.
24
7
Distiller Service
The Distiller® service converts PostScript, Encapsulated PostScript (EPS), and printer text files (PRN) to
compact, reliable, and more secure PDF files over a network. The Distiller service is frequently used to
convert large volumes of print documents to electronic documents, such as invoices and statements.
Converting documents to PDF also allows enterprises to send their customers a paper version and an
electronic version of a document.
Using the Distiller service
When converting a PostScript, Encapsulated PostScript, or PRN file to a PDF file, the conversion operation
allows you to specify several options to apply to the resulting PDF document. For example, you can specify
the following options:
●
Adobe PDF settings, such as high quality print, oversized pages, and press quality. When this parameter
is not provided, the Distiller service will use the default PDF settings as configured using LiveCycle
Administration Console.
●
Job configuration settings to apply while generating the PDF document, such as optimizing for fast
web viewing. This optional parameter contains the file with settings to apply while generating the PDF
document (for example, optimization for web view) and settings to apply when the PDF document is
created (for example, initial view and security).
●
Metadata information to apply to the generated PDF document. This optional parameter contains the
file with metadata information to apply to the generated PDF document. Only UTF-8 encoded Adobe
Extensible Metadata Platform (XMP) metadata is supported. For details of the format and for the
specifications, please visit the main XMP page at the Adobe website.
For information about developing processes that use this service, see LiveCycle Workbench ES Help. For
information about developing client applications that programmatically interact with this service, see
Programming with LiveCycle ES.
In LiveCycle Administration Console, you can use the Applications and Services pages to configure default
properties of the Distiller service. (See Applications and Services Administration Help.) You can also use the
LiveCycle PDF Generator ES page to specify default PDF settings and security settings to apply when
converting to PDF. (See Generate PDF Administration Help.)
25
8
DocConverter Service
The DocConverter service transforms signed or unsigned PDF documents, XML forms (typically created in
LiveCycle Designer ES), and Acrobat forms to PDF/A-compliant documents. You can also use this service to
validate whether PDF documents are compliant with the PDF/A format, which is primarily used for
archiving.
The DocConverter service is included with the following solution components:
●
Adobe LiveCycle PDF Generator ES (8.2)
●
Adobe LiveCycle PDF Generator 3D ES (8.2)
●
Adobe LiveCycle Output ES (8.2)
To use the DocConverter service with XML forms, you must have Output ES. To use the DocConverter
service with documents that contain signed or unsigned signature fields, you must have Adobe LiveCycle
Digital Signatures ES (8.2).
Using the DocConverter service
You can accomplish the following tasks using the DocConverter service:
●
“Validating whether PDF documents are compliant with the PDF/A format” on page 26
●
“Converting PDF documents to PDF/A format” on page 26
For information about developing processes that use this service, see LiveCycle Workbench ES Help. For
information about developing client applications that programmatically interact with this service, see
Programming with LiveCycle ES.
Validating whether PDF documents are compliant with the PDF/A format
You can use the DocConverter service to validate whether a PDF document is compliant with the
PDF/A-1b format.
Converting PDF documents to PDF/A format
You can use the DocConverter service to transform signed or unsigned PDF documents, XML forms
(typically created in Designer ES), and Acrobat forms to PDF documents that are compliant with PDF/A-1b,
a format that is primarily used for archiving. Because long-term preservation is the goal, the document
contains only what is needed for opening and viewing throughout the intended life of the document. For
example, PDF/A-compliant documents contain only text, raster images, and vector objects; they do not
contain encryption and scripts. In addition, all fonts are embedded and the file is uncompressed so that
the documents can be opened and viewed as created. As a result, a PDF/A document is typically larger
than a standard PDF document. Also, a PDF/A document does not contain audio and video content.
If the DocConverter service cannot perform a complete conversion to PDF/A format for a particular file, it
partially converts the file. In addition to the converted file, the DocConverter service also creates a report
that indicates any fixes that were applied to the file and any violations that could not be fixed.
26
Adobe LiveCycle ES
LiveCycle ES Services
DocConverter Service
Converting PDF documents to PDF/A format
27
Although PDF/A is the standard for archiving PDF documents, it is not mandatory that PDF/A be used for
archiving if a standard PDF document meets your company’s requirements. The purpose of the PDF/A
standard is to establish a PDF file meant for long-term archiving and document preservation needs. For
more information about PDF/A, see PDF as a Standard for Archiving.
9
Document Management Service
The Document Management service enables processes to use the content management functionality
provided by Adobe LiveCycle Content Services ES (8.2). For information about Content Services ES, see
LiveCycle ES Overview.
Using the Document Management service
You can accomplish the following tasks using the Document Management service:
●
“Working with contents and spaces” on page 28
●
“Working with associations” on page 29
●
“Working with content attributes” on page 29
For information about developing processes that use this service, see LiveCycle Workbench ES Help. For
information about developing client applications that programmatically interact with this service, see
Programming with LiveCycle ES.
You can use the Applications and Services pages of LiveCycle Administration Console to configure default
properties for this service. (See Applications and Services Administration Help.)
Working with contents and spaces
Content is a file or document that consists of two main elements: the content itself and information about
the content (metadata). For example, the files can be documents, video, audio, images, XML, HTML, and so
on. Content can be added to or created in spaces within the Content Services ES repository and can be
classified and organized into categories.
A space is used to store and organize content items and other spaces. A space can hold any type of
content.
You can use the Document Management service operations to perform the following tasks:
Create a space: Create a space in Content Services ES.
Create a space from an existing space or template: Create a space in Content Services ES, based on
an existing space or a template. All the rules, contents, and users are copied to the new space from the
existing space or template.
Delete content or a space: Delete specified content or a space and its related metadata. When you
delete a space, all its contents are deleted too. When you delete content, all versions of that content are
deleted.
Copy a content item or space: Copy a specified content item or space and its related metadata from
one space to another. When you copy a space, all its contents are copied too.
Note: If the target location already contains a space with the same name, the new space is named
Copy of [space name].
28
Adobe LiveCycle ES
LiveCycle ES Services
Document Management Service
Working with associations
29
Store content: Store or update content and its metadata in the Content Services ES repository.
Move a content item or space: Move specified content or a space and its related metadata from one
location (space) to another. When you move a space, all of its contents are moved too.
Retrieve content: Retrieve specified content and its related metadata.
Working with associations
An association is a way to tie together two or more content items in the repository. Types of associations
available in LiveCycle Workbench ES include the following:
●
An association between an XML data file and an attachment
●
An association that links an XML data file and a PDF form
●
An association that links two PDF documents
You can also create your own custom associations. You can use the Document Management service
operations to perform the following tasks:
Create associations between content items: Create an association between two content items or
folders in the repository.
Get associated: Retrieve a list of IDs of content items that are associated with specified content using a
specified type of association.
Working with content attributes
Content attributes are the metadata for a content item. Metadata is stored in a database, separate from the
content item that it applies to. This structure allows for faster searching of the metadata.
You can use the Document Management service operations to perform the following tasks:
Get content attributes: Retrieve the attributes associated with specified content.
Set content attributes: Set metadata attributes for specified content without modifying the content.
The content is not versioned in this operation.
Considerations for LiveCycle Contentspace ES
Users can open and fill forms from within Adobe LiveCycle Contentspace ES (8.2) by browsing to the space
where the form is located, viewing the details for the file, and then clicking Fill Form. When the user
submits the form, the data is extracted and saved as an XML file. When using LiveCycle Designer ES to
design an XDP form that will be accessed in this way, do not include a Submit URL on the form. If you do,
the submitted form data will not be available inside Contentspace ES because the Submit URL will not be
overridden.
10
Email Service
Email is commonly used to distribute content or provide status information as part of an automated
process. The Email service enables processes to receive email messages from a POP3 or IMAP server, and
send email messages to an SMTP server.
For example, a process uses the Email service to send an email message with a PDF form attachment. The
Email service connects to an SMTP server to send the email message with the attachment. The PDF form is
designed to let the recipient click Submit after completing the form, which causes the form to be returned
as an attachment to the designated email server. The Email service retrieves the returned email message
and stores the completed form in a process data form variable.
When the Email service connects to a POP3 or IMAP server to retrieve an email message, it requires a way
of identifying a unique email message from several that may exist in the mailbox. Typically this
identification is done by embedding a unique identifier in the subject line, such as the process ID, or by
searching for a particular sender. The Email service provides the capability to customize the “from”, “to”,
“subject”, and “body” text of an email message. Developers can specify search criteria for a matching email
message, such as the sender or subject of the email message.
Using the Email service
You can interact with the Email service by developing a process in LiveCycle Workbench ES that uses the
service. You can accomplish the following tasks using the Email service:
●
Configure the Email component with default properties for connecting to an SMTP server for sending
email messages, and to either a POP3 or IMAP server for receiving messages
●
Receive email messages and attachments from either a POP3 or IMAP email server. You can save
metadata about the email, as well as the message content. You can also set filters for email messages,
and set properties about the email server and user account to use.
●
Send an email message that has one or more attachments to an SMTP server.
For information about developing processes that use this service, see LiveCycle Workbench ES Help.
You can also use the Applications and Services pages of LiveCycle Administration Console to configure
default properties for this service. (See Applications and Services Administration Help.)
30
11
Encryption Service
The Encryption service enables you to encrypt and decrypt documents. When a document is encrypted, its
contents become unreadable. You can encrypt the entire PDF document (including its content, metadata,
and attachments), everything other than its metadata, or only the attachments. An authorized user can
decrypt the document to obtain access to the contents. If a PDF document is encrypted with a password,
the user must specify the open password before the document can be viewed in Adobe Reader or Acrobat.
Likewise, if a PDF document is encrypted with a certificate, the user must decrypt the PDF document with
the public key (certificate) that corresponds to the private key that was used to encrypt the PDF document.
Using the Encryption service
You can accomplish the following tasks using the Encryption service:
●
“Encrypting PDF documents with a password” on page 31
●
“Removing password encryption” on page 32
●
“Encrypting PDF documents with certificates” on page 32
●
“Removing certificate-based encryption” on page 33
●
“Unlocking encrypted PDF documents” on page 33
●
“Determining the encryption type” on page 33
For information about developing processes that use this service, see LiveCycle Workbench ES Help. For
information about developing client applications that programmatically interact with this service, see
Programming with LiveCycle ES.
You can use the Applications and Services pages of LiveCycle Administration Console to configure default
properties for this service. (See Applications and Services Administration Help.)
Encrypting PDF documents with a password
You can use the Encryption service to encrypt PDF documents with a password. When you encrypt a PDF
document with a password, a user must specify the password to open the PDF document in Adobe Reader
or Acrobat. You can choose to encrypt the entire PDF document (content, metadata, and attachments),
encrypt everything other than its metadata, or encrypt only the attachments. If you encrypt only the
document’s attachments, users are prompted for a password only when they attempt to access the file
attachments.
When encrypting a PDF document with a password, you specify two separate passwords. One password is
used to encrypt and decrypt the PDF document. The other password is used to remove encryption from
the PDF document or to modify permissions.
When you use a password to encrypt a PDF document, you can add permissions that specify what the
users who receive the document can do with it. For example, you can specify whether they can sign and
fill, edit, or print the PDF document.
31
Adobe LiveCycle ES
LiveCycle ES Services
Encryption Service
Removing password encryption
32
Before another LiveCycle ES operation, such as digitally signing the PDF document, can be performed on
the document, a password-encrypted PDF document must be unlocked. (See “Unlocking encrypted PDF
documents” on page 33.)
Note: It is recommended that you do not encrypt a document prior to uploading it to the
LiveCycle ES repository. If you upload an encrypted PDF document to the LiveCycle ES repository, it
cannot decrypt the PDF document and extract the XDP content.
Removing password encryption
You can use the Encryption service to remove password-based encryption from a PDF document to that
users can open the PDF document in Adobe Reader or Acrobat without having to specify a password. After
password-based encryption is removed from a PDF document, the document is no longer secure.
Encrypting PDF documents with certificates
You can use the Encryption service to encrypt PDF documents with certificates. Certificate-based
encryption lets you use public-key cryptography to encrypt documents for specific recipients. Public-key
cryptography uses two types of keys:
●
A public key, which is stored inside a certificate that can be shared with other users. The public key
certificate is in X.509 format and contains a user’s public key and identifying information.
●
A private key, which you do not share with others
Documents are encrypted using the public keys (certificates) of the users who will receive the document.
When users receive an encrypted document, they use their private keys to decrypt it.
Certificates are typically issued and digitally signed by a certificate authority (CA), which is a recognized
entity that provides a measure of confidence in the validity of the certificate. Certificates have an
expiration date, after which they are no longer valid. In addition, certificate revocation lists (CRLs) provide
information about certificates that were revoked prior to their expiration date. CRLs are published
periodically by certificate authorities. The revocation status of a certificate can also be retrieved through
Online Certificate Status Protocol (OCSP) over the network.
When you use certificates to encrypt a PDF document, you can add permissions that specify what
individual users can do with the document. For example, you can specify whether they can sign and fill,
edit, or print the PDF document.
Before you can encrypt a PDF document with a certificate, you must use LiveCycle Administration Console
to add the certificate to LiveCycle ES.
Note: It is recommended that you do not encrypt a document prior to uploading it to the
LiveCycle ES repository. If you upload an encrypted PDF document to the LiveCycle ES repository, it
cannot decrypt the PDF document and extract the XDP content.
Before another LiveCycle ES operation, such as digitally signing the PDF document, can be performed on
the document, a certificate-encrypted PDF document must be unlocked. (See “Unlocking encrypted PDF
documents” on page 33.)
Adobe LiveCycle ES
LiveCycle ES Services
Encryption Service
Removing certificate-based encryption
33
Removing certificate-based encryption
You can use the Encryption service to remove certificate-based encryption from a PDF document so that
users can open the PDF document in Adobe Reader or Acrobat. To remove encryption from a PDF
document that is encrypted with a certificate, you must reference a public key. After encryption is
removed from a PDF document, it is no longer secure.
Unlocking encrypted PDF documents
You can use the Encryption service to unlock password-encrypted or certificate-encrypted PDF
documents. If you attempt to perform a LiveCycle ES operation on an encrypted PDF document, you will
generate an exception. After you unlock an encrypted PDF document, you can perform one or more
operations on it, such as digitally signing it using the Signature service.
Determining the encryption type
You can use the Encryption service to determine the type of encryption that is protecting a PDF
document. Sometimes it is necessary to dynamically determine whether a PDF document is encrypted
and, if so, the encryption type. For example, you can determine whether a PDF document is protected with
password-based encryption or a Rights Management policy. For information about the Rights
Management service, see “Rights Management Service” on page 101.
A PDF document can be protected by the following encryption types:
●
Password-based encryption
●
Certificate-based encryption
●
A policy that is created by the Rights Management service
●
Another encryption mechanism
Considerations for the Encryption service
If you are working with multiple services, it is important to perform service operations in the correct
sequence:
●
Apply encryption (Encryption service) or apply a policy (Rights Management service) to a document
before digitally signing the document (Signature service). A digital signature records the state of the
file at the time of signing. Encrypting the document or applying a policy after you apply a signature
changes the bytes in the file, causing the signature to appear invalid.
●
Certify a PDF document (Signature service) before you set usage rights (Reader Extensions service). If
you certify a document after you apply usage rights, it could invalidate the usage rights signature,
thereby removing the usage rights from the document.
●
Digitally sign a PDF document (Signature service) after you set usage rights. Signing a PDF document
after applying usage rights will not invalidate the usage rights signature.
In addition, you cannot encrypt a PDF document and apply a policy to the same PDF document. Likewise,
you cannot apply a policy to an encrypted PDF document.
12
Execute Script Service
The Execute Script service enables you to execute scripts in processes.
Using the Execute Script service
You can interact with the Execute Script service by developing a process in LiveCycle Workbench ES that
uses the service.
The Execute Script service supports BeanShell 1.3.0, a Java syntax compatible scripting language for the
Java platform. Implicit objects are available to the script. These objects perform the following tasks:
●
Provide access to the object manager, process manager, deployment properties, JNDI initial context,
and JNDI application context.
●
Store information gathered as a result of executing a script and transfer data to the LiveCycle ES server.
●
Provide all context data for use during execution of a script.
For information about developing processes that use this service, see LiveCycle Workbench ES Help.
You can use the Applications and Services pages of LiveCycle Administration Console to configure default
properties for this service. (See Applications and Services Administration Help.)
34
13
FTP Service
The FTP service enables processes to interact with an FTP server. FTP service operations can retrieve files
from the FTP server, put files on the FTP server, and delete files from the FTP server. For example,
documents such as reports generated from a process may be stored on an FTP server for distribution. Or
an external system may generate some files based on previous steps in a process. In a subsequent step in
the process, the files may be transferred to a remote location.
Using the FTP service
You can interact with the FTP service by developing a process in LiveCycle Workbench ES that uses the
service. You can accomplish the following tasks using the FTP service:
●
Specify the default host, port, and user credentials to connect to the FTP server.
●
Retrieve a list of files that reside in a directory on an FTP server.
●
Retrieve multiple files from the FTP server based on a file name pattern.
●
Retrieve a file from the FTP server and save it to the file system of the LiveCycle ES server.
●
Retrieve the contents of a file from the FTP server and save the contents as process data.
●
Upload process data to a directory on the FTP server and save the data as a file.
●
Upload one or more document values to the FTP server.
●
Upload a file from the file system of the LiveCycle ES server to a directory on the FTP server.
●
Delete a file from the FTP server.
For information about developing processes that use this service, see LiveCycle Workbench ES Help.
You can use the Applications and Services pages of LiveCycle Administration Console to configure default
properties for this service. (See Applications and Services Administration Help.)
Considerations for the FTP service
There are some factors to consider when developing processes that use this service:
●
If you specify local paths to files or directories for any operation properties, the paths are interpreted as
being on the file system of the LiveCycle ES server.
●
The user account that is used to run the LiveCycle ES server must have the required permissions to
interact with the files and file locations that the service’s operations target.
35
14
File Utilities Service
The File Utilities service enables processes to interact with the file system of the LiveCycle ES server or
other file systems that the server can access.
Files are commonly used to integrate with different systems. A process may need to output files in
different formats such as XML, comma-delimited text, and PDF in order for other systems to process the
data. A process can make use of the File Utilities service to create a file in a specified directory and set
permissions on the file.
The File Utilities service may also be part of a process that dynamically generates documents. For example,
a process is scheduled to run every night. This process dynamically generates sales reports in PDF and
places them in a directory. The directory is defined based on month and year.
Using the File Utilities service
You can interact with the File Utilities service by developing a process in LiveCycle Workbench ES that uses
the service. You can accomplish the following tasks using the File Utilities service:
●
Save data as files on the file system.
●
Retrieve information from files and save it as process data.
●
Manipulate directories and files on the file system.
For information about developing processes that use this service, see LiveCycle Workbench ES Help.
Considerations for the File Utilities service
There are some factors to consider when developing processes that use this service:
●
If you specify local paths to files or directories for any operation properties, the paths are interpreted as
being on the file system of the LiveCycle ES server.
●
The user account that is used to run the LiveCycle ES server must have the required permissions to
interact with the files and file locations that the service’s operations target.
36
15
Form Augmenter Service
The Form Augmenter service enables a PDF form or Acrobat form to function within LiveCycle
Workspace ES.
A form that is enabled for Workspace ES has the following characteristics:
●
Buttons will appear hidden when displayed in Workspace ES and the submission will be invoked on the
hidden submit button that was added to the form design as part of the Process Fields form object.
●
Submit requests are handled by Workspace ES, which acts as an intermediary between the LiveCycle ES
server and the form.
●
Forms can be used both offline and online.
Using the Form Augmenter service
You can use the Form Augmenter service operations when you create your custom render and submit
services for the Form, Document Form, or xfaForm variables.
With the Form Augmenter service operations, you can perform tasks such as these:
●
Enable a PDF form for online use in Workspace ES. The PDF form must be created in LiveCycle
Designer ES or Acrobat 7.0.5 or later.
●
Enable a PDF form for offline use in Workspace ES. The PDF form must be created in Designer ES. You
cannot specify an Acrobat form.
●
Add data fields to the form data, which enables a PDF form created in Designer ES to be used offline in
Workspace ES. You cannot specify an Acrobat form.
●
Retrieve a value from a field on a form. The PDF form must be created within Designer ES or Acrobat
7.0.5 or later.
●
Remove a set of data fields from the form data.
For information about developing processes that use this service, see LiveCycle Workbench ES Help.
37
16
Form Data Integration Service
The Form Data Integration service can import form data into a PDF form and export form data from a PDF
form. The import and export operations support two types of PDF forms:
●
An Acrobat form (created in Acrobat) is a PDF document that contains form fields.
●
An XML form (created in LiveCycle Designer ES) is a PDF document that conforms to the Adobe XML
Forms Architecture (XFA).
Form data can exist in one of the following formats depending on the type of PDF form:
●
An XFDF file, which is an XML version of the Acrobat form data format.
●
An XDP file, which is an XML file that contains form field definitions. It may also contain form field data
and an embedded PDF file. An XDP file generated by Designer ES can only be used if it carries an
embedded base-64-encoded PDF document.
Using the Form Data Integration service
You can import and export data using XFDF (Acrobat forms only) or XDP (XML forms only). For example, to
import data into a form created in Designer ES, you must create a valid XDP XML data source. Consider the
following example mortgage application form.
In order to import data values into this form, you must create an XDP XML data source that corresponds to
the form. You cannot use an arbitrary XML data source to import data into a form with the Form Data
38
Adobe LiveCycle ES
LiveCycle ES Services
Form Data Integration Service
Using the Form Data Integration service
39
Integration service. The difference between an arbitrary XML data source and an XDP data source is that an
XDP data source conforms to the XML Forms Architecture (XFA). The following XML represents an XDP
data source that corresponds to the example mortgage application form.
<?xml version="1.0" encoding="UTF-8" ?>
<xfa:datasets xmlns:xfa="http://www.xfa.org/schema/xfa-data/1.0/">
<xfa:data>
<data>
<Layer>
<closeDate>1/26/2007</closeDate>
<lastName>Johnson</lastName>
<firstName>Jerry</firstName>
<mailingAddress>[email protected]</mailingAddress>
<city>New York</city>
<zipCode>00501</zipCode>
<state>NY</state>
<dateBirth>26/08/1973</dateBirth>
<middleInitials>D</middleInitials>
<socialSecurityNumber>(555) 555-5555</socialSecurityNumber>
<phoneNumber>5555550000</phoneNumber>
</Layer>
<Mortgage>
<mortgageAmount>295000.00</mortgageAmount>
<monthlyMortgagePayment>1724.54</monthlyMortgagePayment>
<purchasePrice>300000</purchasePrice>
<downPayment>5000</downPayment>
<term>25</term>
<interestRate>5.00</interestRate>
</Mortgage>
</data>
</xfa:data>
</xfa:datasets>
For information about developing processes that use this service, see LiveCycle Workbench ES Help. For
information about developing client applications that programmatically interact with this service, see
Programming with LiveCycle ES.
You can use the Applications and Services pages of LiveCycle Administration Console to configure default
properties for this service. (See Applications and Services Administration Help.)
17
Forms Service
The Forms service enables you to create interactive data capture client applications that validate, process,
transform, and deliver forms typically created in LiveCycle Designer ES. Form authors develop a single
form design that the Forms service renders as PDF in Adobe Reader or in a browser, as HTML in a variety of
browser environments including a compliant XHTML 1.0 rendering, or as form guides in a variety of
browser environments that support Adobe Flash Player.
When an end user requests a form, a client application, such as a Java servlet, sends the request to the
Forms service, which returns the form in an appropriate format to the end user. When the Forms service
receives a request for a form, it uses a set of transformations to merge data with a form design and then
delivers the form in a format that best matches the presentation and form filling capabilities of the target
browser. For example, if the end user requests a PDF form, then the Forms service renders an interactive
PDF form.
The Forms service performs the following functions:
●
Provides server-side execution of the intelligence that is in the form design. The Forms service executes
the validations and calculations included in the form design and returns the resulting data to the
browser.
●
Detects whether form design scripts should run on the client or the server. For clients that support
client-side scripting such as Internet Explorer 5.0 and later, an appropriate scripting model is loaded
into the device so that the scripts can run directly on the client computer. For information about the
properties and methods supported in each transformation, see the Transformation Reference.
●
Dynamically generates PDF content, SWF content, or HTML content based the user's preference for a
specific form design with or without data. An HTML form can deliver multipage forms page by page. In
contrast, a PDF form delivers all the pages at once. In Designer ES, the form author can script the
current page number in the form design. The Forms service can merge one page of data submitted at a
time or merge only the single page into the form design.
●
Supports dynamic subforms created in Designer ES. The Forms service adds extra fields and boilerplate
as a result of merging the form design with data or as a result of scripting. In the case of HTML, the
added subforms can grow to unlimited page lengths. In the case of PDF, the added subforms paginate
at the page lengths specified in the form design.
●
Renders forms based on fragments. Fragments allow you to share form and script objects that are
external to form designs. You can design parts of a form once and reuse them when designing
collections of related forms. When creating a new form for the collection, you simply insert a reference
to the desired form fragment. When a form author updates a fragment, all forms that contain a
reference to the fragment will reflect the changes (when the form is rerendered).
●
Validates data entry by performing calculations, accessing databases, or enforcing business rules on
field-level data.
●
Renders forms with file attachments. Likewise, the Forms service can process form submissions that
contain file attachments.
●
Displays validation errors in different ways (split frame left, top, right, bottom; no frame left, top, right,
bottom; or no UI). This is all done without maintaining any state on the server. The validation errors are
also made available in the XML-based validation error document.
40
Adobe LiveCycle ES
LiveCycle ES Services
Forms Service
About form types
41
●
Maintains the state of any pass-through data that has been passed in by the application. Pass-through
data is data that does not have corresponding fields in the form design being processed. The
pass-through data is passed back to the calling application after the target device submits the data.
●
Enables a non-technical user to amend a form design by using Designer ES to meet ongoing business
requirements. In contrast, a web application that displays HTML pages may require a user to modify
HTML or XML source code to make changes to a web page.
For information about initially setting up this service, see Forms Administration Help.
This section includes the following topics:
●
“About form types” on page 41
●
“How the Forms service processes requests” on page 42
●
“Using the Forms service” on page 48
●
“Forms service options” on page 50
●
“Considerations for the Forms service” on page 61
About form types
Before you start working with the Forms service, it is recommended that you understand the different
form types that are used by the Forms service. This section describes these form types.
Interactive forms
An interactive form contains one or more fields for collecting information interactively from a user. An
interactive form design produces a form that can be filled online or (in the case of PDF forms) offline. Users
can open the form in Acrobat, Adobe Reader, or an HTML browser and enter information into the form’s
fields. An interactive form can include buttons or commands for common tasks, such as saving data to a
file or printing. It can also include drop-down lists, calculations, and validations.
Note: An interactive form can be dynamic or static.
Note: The Forms service only renders interactive forms.
Dynamic forms
A dynamic form has a layout that changes based on data prepopulation or through user interaction. A
dynamic form design specifies a set of layout, presentation, and data capture rules, including the ability to
calculate values based on user input. The rules are applied when a user enters data into the form or when
a server merges data into a form. Dynamic forms are usually rendered by the Forms service or Acrobat and
Adobe Reader. Dynamic forms are particularly useful when displaying an undetermined amount of data to
users. You do not need to predetermine a fixed layout or number of pages for the form, as is required by a
static form. When rendered as a PDF form, intelligent page breaks are generated.
Two types of dynamic forms exist: server-side and client-side dynamic forms. Both server-side and
client-side dynamic forms are based on form designs that are created in Designer ES.
Adobe LiveCycle ES
LiveCycle ES Services
Forms Service
How the Forms service processes requests
42
Server-side dynamic forms
A server-side dynamic form can be a data-driven dynamic form; that is, the form is populated with data
during rendering. The amount of data determines the form’s layout. Multiple data value instances can be
provided for a given field, causing the field to dynamically replicate so that each data value is displayed
within the form.
Fields that are dynamically added to a dynamic form are contained in structures called subforms, which
are located within the form design. An example of a server-side dynamic form is one that is part of a
custom application that queries a database and retrieves an unknown number of records. After retrieving
records from a database, the application merges data into the form. After the data is merged into the form,
the application renders the form to a user.
Client-side dynamic forms
A client-side dynamic form is typically used to collect data from end users by enabling them to click a
button (or another control) that produces a new field in which data is entered. The new field appears on
the form immediately and does not require a round trip to the server. That is, the form is not sent to the
J2EE application server hosting LiveCycle ES and then rendered back to the client web browser with the
new field. An example of a client-side dynamic form is one that contains fields that enable a user to enter
items to purchase and a button that enables the user to add new fields. Each time the user clicks the
button, a new subform is added to the form (a subform can contain a set of related fields).
Static forms
A static form has a fixed layout that does not change regardless of how much data is placed into the fields.
Any fields left unfilled are present in the form but empty. Conversely, if there is more data than the form
can hold, the form cannot expand to accommodate the excess data.
In the case of an interactive form, the end user cannot enter extra information beyond what the form fields
can hold. Similarly, excess data merged by the Forms service overruns the area bounded by the object and
the excess data is not displayed. As a result, when creating a static form, form authors position and size the
objects in such a way that the objects can accommodate the largest expected set of data.
Static PDF forms are created by Designer ES when a form design is saved as a PDF file, or they can be
rendered on the server by passing an XDP file to the Forms service. A static form can be generated from a
dynamic form design, but once rendered as PDF, the background is locked. Static forms are easily cached
on the server, so are quickly accessed when requested by a user.
How the Forms service processes requests
This section describes how the Forms service processes requests such as form requests, and specifies the
order in which events and scripts are executed.
Requesting a form
When a user requests a form from the Forms service (for example, by clicking a button located on an HTML
page), the request initiates a series of specific processes and interactions with the client application, the
Forms service, and the client device, typically a web browser. The following table summarizes the
interaction among a client device (for example, a web browser), a client application, and the Forms service
when a user requests a form.
Adobe LiveCycle ES
Forms Service
LiveCycle ES Services
Requesting a form
43
User actions
Client application actions
Forms service actions
A user requests a form from a
web page.
No action
No action
No action
Invokes an operation such as
renderPDFForm.
No action
No action
No action
Retrieves the form design that is
specified.
No action
No action
If data is passed to the Forms
service, it prepopulates the form
with the data.
No action
No action
Executes all form-wide field
initialize events.
No action
No action
Executes all form-wide page
initialize events.
No action
No action
Executes all form-wide field
calculate events.
No action
No action
Executes all form-wide page
calculate events.
No action
No action
Executes a page enter event.
No action
No action
Executes a form ready event.
No action
No action
Executes a page enter or exit event.
No action
No action
Transforms the form design into the
format specified.
No action
No action
Returns the form to the client
application.
No action
Verifies that an error was not
returned.
No action
No action
Creates a binary stream and sends No action
it to the client web browser.
Adobe LiveCycle ES
Forms Service
LiveCycle ES Services
Using Form Design buttons
User actions
Client application actions
Forms service actions
Internet Explorer, Mozilla,
Netscape Navigator, and Opera
browsers perform these
actions:
No action
No action
Views the form as either PDF or No action
HTML.
No action
●
Runs each field initialization
marked Run script on client.
●
Runs the page initialization
marked Run script on client.
●
Runs each field calculation
marked Run script on client.
●
Runs the page calculations
marked Run script on client.
44
Note: These actions only occur
if the form is rendered as HTML.
Using Form Design buttons
For the Forms service to retrieve form data, perform calculations, or validate field data, the form must
provide the mechanism to initiate the request. This initiation is typically accomplished through the use of
buttons that are located on the form. The caption displayed on a command button label indicates to the
end user the function of the button. When a user clicks a button, the form-related processing is prompted
by the script associated with the button. Typically, a button initiates either a submit or a calculate
operation.
Buttons are the most common way to initiate logic contained in form design scripts. Placing a button on a
form design in Designer ES and configuring its submit option implies a submit operation. The intent of a
submit button is to complete the form and submit data to the Forms service. However, validation
operations may interrupt this process. For example, if a user enters a wrong value into a field, the user may
have to correct the value before the form data can be submitted to the Forms service. Placing other button
types on the form implies a calculate operation. The intent of a calculate operation is to run calculations
and update the form prior to a submit operation.
Submit button
A button can submit form data as either XML, PDF, or URL-Encoded (for HTML submissions) data to the
Forms service. For example, assume a user fills an interactive form and then clicks a submit button. This
action results in the form data being submitted to the Forms service. A client application, such as a Java
servlet that is created by using the Forms Service API, can retrieve the data.
A PDF form can submit four types of data (XDP, XML, PDF, and URL-encoded data). An HTML form only
submits URL-encoded name-value pairs. By default, when the submission format is PDF, the Forms service
captures the PDF data and returns it back out without performing any calculations. You set the submit
type in Designer ES.
Adobe LiveCycle ES
Forms Service
LiveCycle ES Services
Using Form Design buttons
45
The content type of submitted PDF data is application/pdf. In contrast, the content type of submitted
XML data is text/xml. For XDP submissions, it is application/vnd.adobe.xdp+xml.
The following table summarizes the interaction among a client device (such as a web browser), a client
application, and the Forms service when a user clicks a button that initiates a submit operation.
User actions
Client application actions
Forms service actions
A user enters data into form
fields and clicks a submit
button. This action initiates a
submit operation.
No action
No action
Browser performs an HTTP post No action
to the target URL (this value is
defined either in Designer ES or
by the targetURL parameter
used during the rendition call
to the Forms service).
No action
No action
No action
Client validations marked run
on client are executed.
Creates a FormServiceClient
object and invokes the
processFormSubmission
method and passing the HTTP
request and headers.
No action
No action
The Forms service merges posted
data back into the form. (if
applicable).
No action
No action
Executes the field click event.
No action
No action
Executes the form-wide field
calculate events.
No action
No action
Executes the form-wide page
calculate events.
No action
No action
Executes the form-wide field
validation events.
No action
No action
Executes the page validation events
(which include validate,
formatTest, and nullTest).
No action
No action
Executes the Form’s Close event.
No action
No action
If this validation process fails, it
indicates that at least one error
exists. The returned processing
state value is Validate.
Adobe LiveCycle ES
Forms Service
LiveCycle ES Services
Using Form Design buttons
User actions
Client application actions
No action
Verifies that the Forms service
No action
returned a processing state value
of Validate. In this situation, the
result is sent back to the client
browser so that the user can
correct the mistake.
For forms that are displayed as No action
HTML, the end user sees the
form containing the same data,
calculations, and list of errors to
correct before resubmitting.
Forms service actions
No action
For form guides (displayed as
Adobe Flash), the end user sees
the form containing the same
data, calculations, and list of
errors to correct before
resubmitting.
For forms that are displayed as
PDF, a user interface is not
defined. Validation errors can
be retrieved by using the
FormsResult object’s
getValidationErrorsList
method.
No action
No action
If the validation process succeeds,
the processing state value is set to
Submit.
No action
Verifies that the Forms service
No action
returns a processing state value of
Submit.
Acknowledges that all form
processing is complete.
Any additional processing is
application specific. For example,
a wizard-style application can
request the next form panel, do
additional data investigations,
update the database, or initiate a
new workflow process.
The view is application-specific. No action
For example, a new form can be
displayed.
No action
46
Adobe LiveCycle ES
Forms Service
LiveCycle ES Services
Using Form Design buttons
47
Calculate button
A button can be used to execute a calculation operation. When a user clicks a button, the Forms service
executes a calculation script that is located in the form design and renders the form back to the web
browser with the results displayed in the form. (See Calculating form data).
The following table summarizes the interaction among a client device (such as a web browser), a client
application, and the Forms service when a user clicks a button that initiates a calculation operation.
User actions
Client application actions
Forms service actions
A user clicks a button that is
located on a form.
No action
No action
Creates a
No action
If the button’s Click event is
marked run on client, the form
is not submitted to the Forms
service. The script is executed
in a web browser, Acrobat, or
Adobe Reader.
A form guide implements an
XFASubset in ActionScript,
which runs in the Adobe
Flash® Player.
If the button’s Click event is
marked run on server, the form
is submitted to the Forms
service.
No action
FormsServiceClient object
and invokes the
processFormSubmission
method.
No action
No action
The Forms service merges new data
into the form design (if applicable).
No action
No action
Executes the field click event.
No action
No action
Executes the form-wide field
calculate events.
No action
No action
Executes the form-wide page
calculate events.
No action
No action
Executes a page enter or exit event.
No action
No action
Executes the form-wide field
validation events.
No action
No action
Executes the page validation event.
No action
No action
Executes the page exit event
Adobe LiveCycle ES
Forms Service
LiveCycle ES Services
Using the Forms service
48
User actions
Client application actions
Forms service actions
No action
No action
Returns the form to the client
application that invoked the Forms
service. The form’s format does not
change. If the form is submitted in
PDF, it is sent back to the client
browser in PDF.
No action
Verifies that the Forms service
does not return an error.
No action
No action
Creates a binary stream and sends No action
it to the client web browser.
Views calculation results that
are displayed in the form.
No action
No action
Using the Forms service
You can accomplish the following tasks using the Forms service:
●
“Rendering interactive PDF forms” on page 48
●
“Rendering form guides” on page 49
●
“Rendering forms as HTML” on page 50
For information about developing processes that use this service, see LiveCycle Workbench ES Help. For
information about developing client applications that programmatically interact with this service, see
Programming with LiveCycle ES.
Rendering interactive PDF forms
The Forms service renders interactive PDF forms or XDP files to client devices such as a web browser. After
an interactive form is rendered, a user can enter data into form fields and click a submit button located on
the form to send information back to the Forms service. Adobe Reader or Acrobat must be installed on the
computer hosting the client web browser in order for an interactive PDF form to be visible.
1
Adobe LiveCycle ES
LiveCycle ES Services
Forms Service
Rendering form guides
49
Before you can render a form using the Forms service, you must create a form design. Typically, a form
design is created in Designer ES and is saved as an XDP file.
Note: In Designer ES, a form guide and special form objects must be added to the form design before it
can be rendered as a form guide for use with LiveCycle Workspace ES. (See Using LiveCycle
Designer ES > Creating Forms for LiveCycle Process Management ES in LiveCycle Designer ES Help.)
Note: In LiveCycle 7.x releases, the Forms service created non-tagged PDF files by default. In LiveCycle ES,
the Forms service creates tagged PDF files by default.
Rendering forms at the client
You can optimize the delivery of PDF content and improve the Forms service’s ability to handle network
load by using the client-side rendering capability of Acrobat or Adobe Reader. This process is known as
rendering a form at the client. To render a form at the client, the client device (typically a web browser)
must use Acrobat 7.0 or Adobe Reader 7.0 or later.
Rendering form guides
Form guides are based on Adobe® Flash® technology and provide a visually engaging and streamlined
method for capturing data from a user. Form guides can reduce data entry errors through improved
usability by logically grouping or simplifying information presented to a user at a given time. When
rendering form guides, you can specify whether to render only SWF (Flash) content or both SWF and PDF
content. (By default, both SWF content and PDF content are rendered).
To render a form guide, you must create a form guide design. For information, see Getting Started with
Form Guides.
Note: For form guides to be displayed, Adobe Flash Player must be installed on the client computer. When
a form guide is delivered to the web browser as part of the form guide transformation, the web
browser determines whether Flash Player is installed. If Flash Player is not installed, the web browser
prompts the user to install it.
Note: In Designer ES, a form guide and special form objects must be added to the form design before it
can be rendered as a form guide for use with Workspace ES. (See Using LiveCycle Designer ES >
Creating Forms for LiveCycle Process Management ES in LiveCycle Designer ES Help.)
Adobe LiveCycle ES
LiveCycle ES Services
Forms Service
Rendering forms as HTML
50
Rendering forms as HTML
The Forms service renders forms as HTML by retrieving the specified form and transforming it to an HTML
form. You can select the type of HTML transformation that is created to support different HTML formats. A
benefit of rendering a form as HTML is that the computer on which the client web browser is located does
not require Adobe Reader, Acrobat, or Flash Player (for form guides).
To render a form as HTML, the form design must be saved as an XDP file. A form design that is saved as a
PDF file cannot be rendered as HTML.
Note: For a form design, it is recommended that the guidelines for layout considerations for HTML forms
be followed to overcome text shift issues in a rendered HTML form. (See Using LiveCycle
Designer ES > Creating Forms for LiveCycle Forms ES > Creating HTML forms > Layout
considerations for HTML forms in LiveCycle Designer ES Help.)
Note: In Designer ES, a form guide and special form objects must be added to the form design before it
can be rendered as a form guide for use with Workspace ES. (See Using LiveCycle Designer ES >
Creating Forms for LiveCycle Process Management ES in LiveCycle Designer ES Help.)
Forms service options
The Forms service can also perform the following optional tasks, depending on the type of task it is
performing:
●
“Rendering forms based on fragments” on page 50
●
“Rendering rights-enabled forms” on page 51
●
“Prepopulating forms” on page 54
●
“Calculating form data” on page 59
●
“Optimizing an application” on page 61
Rendering forms based on fragments
The Forms service can render forms that are based on fragments that you create using Designer ES. A
fragment is a reusable part of a form and is saved as a separate XDP file that can be inserted into multiple
form designs. For example, a fragment could include an address block or legal text.
Using fragments simplifies and speeds up the creation and maintenance of large numbers of forms. When
creating a new form, you insert a reference to the required fragment and the fragment appears in the form.
The fragment reference contains a subform that points to the physical XDP file. For information about
creating fragments, see LiveCycle Designer ES Help.
A fragment can include several subforms that are wrapped in a choice subform set. Choice subform sets
control the display of subforms based on the flow of data from a data connection. You use conditional
statements to determine which subform from within the set appears in the delivered form. For example,
each subform in a set could include information for a particular geographic location and the subform that
is displayed could be determined based on the location of the user.
A script fragment contains reusable JavaScript functions or values that are stored separately from any
particular object, such as a date parser or a web service invocation. These fragments include a single script
object that appears as a child of variables in the Hierarchy palette. Fragments cannot be created from
scripts that are properties of other objects, such as event scripts like validate, calculate, or initialize.
Adobe LiveCycle ES
LiveCycle ES Services
Forms Service
Rendering rights-enabled forms
51
Here are advantages of using fragments:
Content reuse: You can use fragments to reuse content in multiple form designs. When you need to
use some of the same content in multiple forms, it is faster and simpler to use a fragment than to copy
or re-create the content. Using fragments also ensures that the frequently used parts of a form design
have consistent content and appearance in all the referencing forms.
Global updates: You can use fragments to make global changes to multiple forms only once, in one
file. You can change the content, script objects, data bindings, layout, or styles in a fragment, and all
XDP forms that reference the fragment will reflect the changes.
For example, a common element across many forms might be an address block that includes a
drop-down list object for the country. If you need to update the values for the drop-down list object,
you must open many forms to make the changes. If you include the address block in a fragment, you
only need to open one fragment file to make the changes.
To update a fragment in a PDF form, you must resave the form in Designer ES.
Shared form creation: You can use fragments to share the creation of forms among several resources.
Form developers with expertise in scripting or other advanced features of Designer ES can develop and
share fragments that take advantage of scripting and dynamic properties. Form designers can use
those fragments to lay out form designs and to ensure that all parts of a form have a consistent
appearance and functionality across multiple forms designed by multiple people.
Rendering rights-enabled forms
The Forms service can render forms that have usage rights applied to them. Usage rights pertain to
functionality that is available by default in Acrobat but not in Adobe Reader, such as the ability to add
comments to a form or to fill in form fields and save the form. Forms that have usage rights applied to
them are called rights-enabled forms. A user who opens a rights-enabled form in Adobe Reader can
perform operations that are enabled for that form.
In order to apply usage rights to a form, the Reader Extensions service must be part of your LiveCycle ES
installation. Also, you must have a valid credential that enables you to apply usage rights to PDF
documents. That is, you must properly configure the Reader Extensions service before you can render a
rights-enabled form. (See “Reader Extensions Service” on page 96.)
Note: To render a form that contains usage rights, you must use an XDP file as input, not a PDF file. If you
use a PDF file as input, then the form is still rendered; however, it will not be a rights-enabled form.
Adobe LiveCycle ES
LiveCycle ES Services
Forms Service
Handling submitted forms
52
Note: You cannot prepopulate a form with XML data when you specify the following usage rights: Enable
Commenting, Enable Online Commenting, Enable Embedded Attachments, or Enable Digital
Signatures.
Handling submitted forms
Web-based applications that enable a user to fill in interactive forms require the data to be submitted back
to the server. Using the Forms service, you can retrieve the data that the user entered into an interactive
form. After you retrieve the data, you can process the data to meet your business requirements. For
example, you can store the data in a database, send the data to another application, send the data to
another service, merge the data in a form design, display the data in a web browser, and so on.
Form data is submitted to the Forms service as either XML or PDF data. This option is set in Designer ES. A
form that is submitted as XML enables you to extract individual field data values. That is, you can extract
the value of each form field that the user entered into the form. A form that is submitted as PDF data is
binary data, not XML data. As a result, you cannot extract field values. However, you can save the form as a
PDF file, or send the form to another service.
Handling submitted XML data
When form data is submitted as XML, you can retrieve XML data that represents the submitted data. All
form fields appear as nodes in an XML schema. The node values correspond to the values that the user
filled in. Consider a loan form where each field in the form appears as a node within the XML data. The
value of each node corresponds to the value that a user fills in. Assume a user fills the loan form with data
shown in the following form.
Adobe LiveCycle ES
LiveCycle ES Services
Forms Service
Handling submitted forms
53
The following illustration shows corresponding XML data that is retrieved by using the Forms service.
The form design must be configured correctly in Designer ES for data to be submitted as XML data. To
properly configure the form design to submit XML data, ensure that the Submit button that is located on
the form design is set to submit XML data. For information about setting the Submit button to submit XML
data, see LiveCycle Designer ES Help.
Also, you must specify the correct content type to handle XML data. For example, to handle XML data,
specify application/vnd.adobe.xdp+xml. The content type should must match the submitted form
data. You can also specify multiple content type values such as this one to ensure that various form
submissions can be used:
CONTENT_TYPE=application/pdf&CONTENT_TYPE=application/vnd.adobe.xdp+xml
Handling submitted PDF data
Consider a web application that invokes the Forms service. After the Forms service renders an interactive
PDF form to a client web browser, the user fills in an interactive form and submits the form back as PDF
data. When the Forms service receives the PDF data, it can send the PDF data to another service or save it
as a PDF file. To handle a submitted PDF form, ensure that you specify
CONTENT_TYPE=application/pdf as the content type.
Handling submitted form guide data
The Flash Player security specifies that a Flash application can only submit data to the URL location
(domain) from which it was served. When using the Forms service to render a form guide, this is not the
case. The URL location from where a form guide is served and the URL location to where the form data is
posted is different (that is typical Forms service functionality). For Flash Player to permit data to be posted.
Adobe LiveCycle ES
Forms Service
LiveCycle ES Services
Prepopulating forms
54
Prepopulating forms
Prepopulating forms displays data to users within a rendered form. For example, assume a user logs in to a
website with a user name and password. If authentication is successful, the custom application queries a
database for user information. The data is merged into the form and then the form is rendered to the user.
As a result, the user is able to view personalized data within the form.
Prepopulating a form has the following advantages:
●
Enables the user to view custom data in a form
●
Reduces the amount of typing the user does to fill in a form
●
Ensures data integrity by having control over where data is placed
The following two XML data sources can prepopulate a form:
●
An XDP data source, which is XML that conforms to XFA syntax (or XFDF data to prepopulate a form
created using Acrobat).
●
An arbitrary XML data source that contains name/value pairs matching the form’s field names (the
examples in this section use an arbitrary XML data source).
An XML element must exist for every form field that you want to prepopulate. The XML element name
must match the field name. An XML element is ignored if it does not correspond to a form field or if the
XML element name does not match the field name. It is not necessary to match the order in which the XML
elements are displayed, as long as all XML elements are specified.
When you prepopulate a form that already contains data, you must specify the data that is already
displayed within the XML data source. Assume that a form containing 10 fields has data in four fields. Next,
assume that you want to prepopulate the remaining six fields. In this situation, you must specify 10 XML
elements in the XML data source that is used to prepopulate the form. If you specify only six elements,
then the original four fields are empty.
For example, to prepopulate a confirmation form, you have to create an XML data source that contains
three XML elements that match the three fields in the form. This form contains the following three fields:
FirstName, LastName, and Amount. The first step is to create an XML data source that contains XML
elements that match the fields located in the form design, as shown in the following XML code.
<Untitled>
<FirstName>
<LastName>
<Amount>
</Untitled>
Corresponds to the FirstName field
Corresponds to the LastName field
Corresponds to the Amount field
The next step is to assign data values to the XML elements, as shown in the following XML code.
<Untitled>
<FirstName>Jerry</FirstName>
<LastName>Johnson</LastName>
<Amount>250000</Amount>
</Untitled>
Adobe LiveCycle ES
LiveCycle ES Services
Forms Service
Prepopulating forms
55
After you prepopulate the confirmation form with this XML data source and then render the form, the data
values that you assigned to the XML elements are displayed, as shown in the following illustration.
Prepopulating dynamic forms
Dynamic forms are useful to display an undetermined amount of data to users. Because the layout of a
dynamic form adjusts automatically to the amount of data that is merged, you do not need to
predetermine a fixed layout or number of pages for the form as you need to do with a static form.
A dynamic form is typically populated with data that is obtained during run time. As a result, you can
prepopulate a dynamic form by creating an in-memory XML data source and placing the data directly into
the in-memory XML data source.
Adobe LiveCycle ES
Forms Service
LiveCycle ES Services
Prepopulating forms
56
Consider a web-based application, such as an online store. After an online shopper finishes purchasing
items, all purchased items are placed into an in-memory XML data source that is used to prepopulate a
dynamic form. The following illustration shows this process, which is explained in the table below.
The following table describes the steps in this illustration.
Step
Description
1
A user purchases items from a web-based online store.
2
After the user finishes purchasing items and clicks the Submit button, an in-memory XML data
source is created. Purchased items and user information are placed into the in-memory XML
data source.
3
The XML data source is used to prepopulate a dynamic purchase order form (an example of this
form is shown following this table).
4
The dynamic purchase order form is rendered to the client web browser.
Adobe LiveCycle ES
LiveCycle ES Services
Forms Service
Prepopulating forms
57
The following illustration shows an example of a dynamic purchase order form.
Represents
the form’s
header
data.
Represents
the
dynamic
portion of
the form.
Note: Dynamic forms can be prepopulated with data from other sources such as an enterprise database or
external applications. A web-based application represents only one example of using dynamic
forms.
Dynamic form design considerations
Both server-side and client-side dynamic forms are based on form designs that are created in Designer ES.
A form design specifies a set of layout, presentation, and data capture rules, including calculating values
based on user input. The rules are applied when data is entered into a form. Fields that are dynamically
added to a dynamic form are subforms that are within the form design. For example, in the purchase order
form shown in the previous illustration, each line is a subform. For information about creating a form
design that contains subforms, see LiveCycle Designer ES Help.
Understanding data subgroups
An XML data source is used to prepopulate both static and dynamic forms. However, the difference is that
an XML data source that prepopulates a dynamic form contains repeating XML elements that are used to
prepopulate subforms that are repeated within the form. These repeating XML elements are called data
subgroups.
An XML data source that is used to prepopulate the dynamic form shown in the previous illustration
contains four repeating data subgroups. Each data subgroup corresponds to a purchased item. The
purchased items are a monitor, a desk lamp, a phone, and an address book.
Adobe LiveCycle ES
LiveCycle ES Services
Forms Service
Prepopulating forms
58
The following XML code shows the arbitrary XML data source that is used to prepopulate the dynamic
purchase order form.
<header>
<!-- XML elements used to prepopulate non-repeating fields such as address
<!and city
<txtPONum>8745236985</txtPONum>
<dtmDate>2004-02-08</dtmDate>
<txtOrderedByCompanyName>Any Company Name</txtOrderedByCompanyName>
<txtOrderedByAddress>555, Any Blvd.</txtOrderedByAddress>
<txtOrderedByCity>Any City</txtOrderedByCity>
<txtOrderedByStateProv>ST</txtOrderedByStateProv>
<txtOrderedByZipCode>12345</txtOrderedByZipCode>
<txtOrderedByCountry>Any Country</txtOrderedByCountry>
<txtOrderedByPhone>(123) 456-7890</txtOrderedByPhone>
<txtOrderedByFax>(123) 456-7899</txtOrderedByFax>
<txtOrderedByContactName>Contact Name</txtOrderedByContactName>
<txtDeliverToCompanyName>Any Company Name</txtDeliverToCompanyName>
<txtDeliverToAddress>7895, Any Street</txtDeliverToAddress>
<txtDeliverToCity>Any City</txtDeliverToCity>
<txtDeliverToStateProv>ST</txtDeliverToStateProv>
<txtDeliverToZipCode>12346</txtDeliverToZipCode>
<txtDeliverToCountry>Any Country</txtDeliverToCountry>
<txtDeliverToPhone>(123) 456-7891</txtDeliverToPhone>
<txtDeliverToFax>(123) 456-7899</txtDeliverToFax>
<txtDeliverToContactName>Contact Name</txtDeliverToContactName>
</header>
<detail>
<!-- A data subgroup that contains information about the monitor>
<txtPartNum>00010-100</txtPartNum>
<txtDescription>Monitor</txtDescription>
<numQty>1</numQty>
<numUnitPrice>350.00</numUnitPrice>
</detail>
<detail>
<!-- A data subgroup that contains information about the desk lamp>
<txtPartNum>00010-200</txtPartNum>
<txtDescription>Desk lamps</txtDescription>
<numQty>3</numQty>
<numUnitPrice>55.00</numUnitPrice>
</detail>
<detail>
<!-- A data subgroup that contains information about the Phone>
<txtPartNum>00025-275</txtPartNum>
<txtDescription>Phone</txtDescription>
<numQty>5</numQty>
<numUnitPrice>85.00</numUnitPrice>
</detail>
<detail>
<!-- A data subgroup that contains information about the address book>
<txtPartNum>00300-896</txtPartNum>
<txtDescription>Address book</txtDescription>
<numQty>2</numQty>
<numUnitPrice>15.00</numUnitPrice>
</detail>
Adobe LiveCycle ES
LiveCycle ES Services
Forms Service
Calculating form data
59
Notice that each data subgroup contains four XML elements that correspond to this information:
●
Items part number
●
Items description
●
Quantity of items
●
Unit price
The name of a data subgroup’s parent XML element must match the name of the subform that is located in
the form design. For example, in the previous illustration, notice that the name of the data subgroup’s
parent XML element is detail. This corresponds to the name of the subform that is located in the form
design on which the purchase order form is based. If the name of the data subgroup’s parent XML element
and the subform do not match, a server-side dynamic form is not prepopulated.
Each data subgroup must contain XML elements that match the field names in the subform. The detail
subform located in the form design contains the following fields:
●
txtPartNum
●
txtDescription
●
numQty
●
numUnitPrice
Calculating form data
The Forms service can calculate the values that a user enters into a form and display the results. To
calculate form data, you must perform two tasks. First, you create a form design script that calculates form
data. A form design supports three types of scripts. One script type runs on the client, another runs on the
server, and the third type runs on both the server and the client. The script type discussed in this topic runs
on the server. Server-side calculations are supported for HTML, PDF, and form guide transformations.
As part of the form design process, you can make use of calculations and scripts to provide a richer user
experience. Calculations and scripts can be added to most form fields and objects.
The user enters values into the form and clicks the Calculate button to view the results. The following
process describes an example application that enables a user to calculate data:
●
The user accesses an HTML page named StartLoan.html that acts as the web application’s start page.
This page invokes a Java Servlet named GetLoanForm.
●
The GetLoanForm servlet renders a loan form. This form contains a script, interactive fields, a calculate
button, and a submit button.
●
The user enters values into the form’s fields and clicks the Calculate button. The form is sent to the
CalculateData Java Servlet where the script is executed. The form is sent back to the user with the
calculation results displayed in the form.
●
The user continues entering and calculating values until a satisfactory result is displayed. When
satisfied, the user clicks the Submit button to process the form. The form is sent to another Java Servlet
named ProcessForm that is responsible for retrieving submitted data. For information, see “Handling
submitted forms” on page 52.
Adobe LiveCycle ES
Forms Service
LiveCycle ES Services
Calculating form data
60
The following illustration shows the application’s logic flow.
The following table describes the steps in this illustration.
Step
Description
1
The GetLoanForm Java Servlet is invoked from the HTML start page.
2
The GetLoanForm Java Servlet uses the Forms service Client API to render the loan form to
the client web browser. The difference between rendering a form that contains a script
configured to run on the server and rendering a form that does not contain a script is that you
must specify the target location used to execute the script. If a target location is not specified,
a script that is configured to run on the server is not executed. For example, consider the
application introduced in this section. The CalculateData Java Servlet is the target
location where the script is executed.
3
The user enters data into interactive fields and clicks the Calculate button. The form is sent to
the CalculateData Java Servlet, where the script is executed.
4
The form is rendered back to the web browser with the calculation results displayed in the
form.
5
The user clicks the Submit button when the values are satisfactory. The form is sent to
another Java Servlet named ProcessForm.
Typically, a form that is submitted as PDF content contains scripts that are executed on the client. However,
server-side calculations can also be executed. A Submit button cannot be used to calculate scripts. In this
situation, calculations are not executed because the Forms service considers the interaction to be
complete.
Adobe LiveCycle ES
LiveCycle ES Services
Forms Service
Optimizing an application
61
To illustrate the usage of a form design script, this section examines a simple interactive form that contains
a script that is configured to run on the server. The following illustration shows a form design containing a
script that adds values that a user enters into the first two fields and displays the result in the third field.
A field named NumericField1
A field named NumericField2
A field named NumericField3
The syntax of the script located in this form design is as follows:
NumericField3 = NumericField2 + NumericField1
In this form design, the Calculate button is a command button, and the script is located in this button’s
Click event. When a user enters values into the first two fields (NumericField1 and NumericField2) and
clicks the Calculate button, the form is sent to the Forms service, where the script is executed. The Forms
service renders the form back to the client device with the results of the calculation displayed in the
NumericField3 field.
For information about creating a form design script, see LiveCycle Designer ES Help.
Optimizing an application
When rendering a form, you can set run-time options that will optimize the performance of the Forms
service. Another task that you can perform to improve the performance of the Forms service is to store
XDP files in the repository.
Considerations for the Forms service
When working with the Forms service, there are considerations related to the following topics:
●
Planning your form design.
●
Creating form designs for the Forms service.
●
Rendering forms that contain images.
●
Rendering forms that include secured images.
●
Changes to image fields using a script are not retained.
Planning your form design
Creating application logic using the Forms service is only one aspect of creating a client application. The
Forms service requires form designs typically created using Designer ES (forms can be created in Acrobat
as well). Form designs are XML templates that are saved as either XDP or PDF files. The Forms service
Adobe LiveCycle ES
Forms Service
LiveCycle ES Services
Creating form designs for the Forms service
62
outputs forms that are displayed as PDF, form guides (SWF format), or HTML. The following illustration
shows the valid input and output of the Forms service.
Using a form design saved as an .xdp file
Output
A form displayed as HTML
PDF
Input
Output
A form design saved as an .xdp file
A form displayed as PDF
Output
Forms service
A form displayed as form guides (SWF)
Using a form design saved as a .pdf file
PDF
PDF
Output
Input
A form design saved as a .pdf file
A form displayed as PDF content
Forms service
As shown in the above illustration, if the form design is saved as an XDP file, the Forms service can output a
form that is displayed as either PDF, form guides (SWF format), or HTML. However, if the form design is
saved as a PDF file, the Forms service can only output a form that is displayed as PDF. That is, the Forms
service cannot output an HTML form if the form design is saved as a PDF file.
The first step in planning your application is to determine the output format of the forms. If you want the
Forms service to output PDF forms, form guides, or HTML forms, save your form designs as XDP files. If you
want the Forms service to only output forms as PDF, save your form designs as PDF or XDP files. Next, plan
the content of your form designs. Form design content varies from simplistic form designs that contain
text and text box fields to complex form designs that contain multiple pages, different controls (such as
radio buttons and drop-down lists), and scripts.
Creating form designs for the Forms service
Behavioral differences exist between form designs that are used to render PDF and HTML. Because form
designs that are rendered as PDF are viewed using Acrobat or Adobe Reader, the form supports a full
range of object properties that you define in the form design. If you want to render a form design as a form
guide, then the Adobe Flash® player must be installed on the client computer.
If you are rendering a form as HTML, some client devices (for example, older web browsers) do not provide
the same level of support for individual object properties. To create a single form design that reduces
these limitations, follow this process:
1. See the Transformation Reference to determine how objects behave in a particular client device.
Adobe LiveCycle ES
LiveCycle ES Services
Forms Service
Rendering forms that contain images
63
2. If you are designing a static form and want to output the form as HTML, you must enable
transformation caching. For information, see LiveCycle Designer ES Help.
3. When creating a form design, try to work around any limitations by finding ways to implement the
form without relying on unsupported object properties.
4. If required, include a layout that works for both PDF and HTML formats.
5. Read the section in LiveCycle Designer ES Help that discusses creating accessible forms and use the
guidelines to build accessibility into your form design.
6. Ask your form developer where scripts should run. By default, scripts run on the client. If the scripts that
you include in a form design should run on the server, or both the client and server, you may have to
change the default setting. For example, a form design may contain a script that extracts data from an
enterprise database that is only available on the server. In this situation, the default setting must be
modified so that the script runs at the server.
7. Periodically preview the form using Designer ES or the client device (for example, a web browser) to
troubleshoot problems early in the design process.
8. If the Forms service will be prepopulating forms with data, use test data to thoroughly test your form
design.
For the Forms service to retrieve form data, perform calculations, or validate field data, the form must
provide the mechanism to initiate the request. This is typically accomplished through the use of buttons
that are located on the form design. The caption displayed on a command button label indicates to the
end user the function of the button. When a user clicks a button, the form-related processing is prompted
by the script associated with the button. Typically, a button initiates either a submit or a calculate
operation.
Buttons are the most common way to initiate logic contained in form design scripts. Placing a button on a
form design in Designer ES and configuring its submit option implies a submit operation. The intent of a
submit button is to complete the form and submit data to the Forms service. However, validation
operations may interrupt this process. For example, if a user enters a wrong value into a field, the user may
have to correct the value before the form data can be submitted to the Forms service. Placing other button
types on the form implies a calculate operation. The intent of a calculate operation is to run calculations
and update the form prior to a submit operation.
Rendering forms that contain images
When rendering forms with data that contains references to images, the images may not be displayed
correctly in the rendered form. To ensure that the images are rendered successfully when rendering the
form on the client side, set the following run-time options:
●
PDFVersion=1.6 (or higher)
●
CacheEnabled=0
●
renderAtClient=Auto
To render the form with data on the server side, set the following run-time option: CacheEnabled=0.
Adobe LiveCycle ES
LiveCycle ES Services
Forms Service
Rendering a PDF form that includes a secured image
64
Rendering a PDF form that includes a secured image
You may encounter an exception when rendering an HTML form that contains an image that is secured by
a certificate. For example, if you use the FormsIVS application to render a form that contains a secured
image, an exception may occur.
To resolve this issue, you need to ensure that the J2EE application server is started with the same operating
system user name and password values that are used to add the client side and CA certificates to
operating system trust store. Once you perform this task, the Forms service can access the credential
required to obtain the image.
Changes to image fields using a script are not retained
Changes made to an image field located on a form design by using client-side script, such as JavaScript,
are not submitted and cannot be obtained by a client application. For example, changes made to an image
field by a script which is then followed by a next page or previous page action does not retain the change
made by the script. This is applicable to forms that are rendered as HTML.
Enabling debug options
You can enable debug options when rendering a PDF form, a rights-enabled PDF form, or a form guide.
When enabling the debug option, you can obtain additional information, such as the value of run-time
values. To set debug options for the renderPDFForm, renderPDFFormWithUsageRights, or
renderFormGuide operations within in a process created in LiveCycle Workbench ES, create a variable of
type PDFFormRenderSpec and using the setValue operation, set
/process_data/pdfFormRenderSpecVar/object/@debugEnabled to true. Similarly, for the
renderHTMLForm operation, use a variable of type HTMLRenderSpec.
18
Generate PDF Service
The Generate PDF service lets you convert many different file types to PDF documents. It also lets you
convert PDF documents to other document formats.
Using the Generate PDF service
You can accomplish the following tasks using the Generate PDF service:
●
“Converting various types of files to PDF documents” on page 65
●
“Converting HTML files to PDF documents” on page 66
●
“Converting PDF files to various types of documents” on page 66
When converting to PDF and other file formats, the conversion operation lets you specify several options
to apply to the resulting document. For example, you can specify the following options:
●
Preconfigured Adobe PDF settings, such as high quality print, oversized pages, and press quality. You
can create custom settings using LiveCycle Administration Console. (See Generate PDF Administration
Help.)
●
Preconfigured security settings for applying password-based encryption to the PDF document. You can
create custom settings using LiveCycle Administration Console.
●
Custom job configuration settings to apply while generating the PDF document, such as optimizing for
fast web viewing, and settings to apply when the PDF document is created, such as initial view and
security.
●
Preconfigured custom file type settings. You can create custom settings using LiveCycle Administration
Console.
●
Metadata information to embed in the generated PDF document. Metadata contains information such
as the author of the document, the subject, and any keywords to associate with the document. Only
UTF-8 encoded Adobe Extensible Metadata Platform (XMP) metadata is supported. For information
about the format and the specifications, see the main XMP page at the Adobe website.
For information about developing processes that use this service, see LiveCycle Workbench ES Help. For
information about developing client applications that programmatically interact with this service, see
Programming with LiveCycle ES.
For information about using the LiveCycle PDF Generator ES web pages to perform these tasks and about
specifying default settings, including default PDF and security settings, see Generate PDF Administration
Help and Applications and Services Administration Help.
Converting various types of files to PDF documents
You can convert many different file formats to PDF documents. The following file formats are supported:
●
Microsoft Office 2000, XP, 2003, or 2007 (DOC, DOCX, XLS, XLSX, PPT, PPTX, WPD, RTF, TXT, Microsoft
Office Open XML Formats)
●
Microsoft Office Visio 2003, 2007 (VSD)
●
Microsoft Project 2003 or 2007 (MPP, MPPX)
65
Adobe LiveCycle ES
LiveCycle ES Services
Generate PDF Service
Converting HTML files to PDF documents
●
AutoCAD 2005, 2006, 2007, 2008 (DWF, DWG, DXW)
●
Corel WordPerfect 12, English and French versions only (WPD)
●
Adobe Photoshop CS2 (PSD)
●
Adobe FrameMaker 7.2, 8 (FM)
●
Adobe PageMaker 7.0 (PMD, PM6, P65, PM)
●
OpenOffice 2.0, 2.4 (ODT, ODS, ODP, ODG, ODF, SXW, SXI, SXC, SXD)
●
Print files (PS, PRN, EPS)
●
Web files (HTML, HTM)
●
Image files (JPEG, JPG, JPEG2000, GIF, BMP, TIFF, TIF, PNG)
●
Any third-party generic application type for which you have a PDF generating application
66
Note: In order to convert PostScript files to PDF documents, either Acrobat 9 or Microsoft Visual C++ 2005
redistributable package must be installed on the server hosting LiveCycle ES.
Generating PDF documents using a client printer driver
LiveCycle ES also includes a print driver that prints to the Generate PDF service. This print driver is installed
like any other print driver on the desktop. Users can take advantage of the centralized PDF generation that
PDF Generator ES provides from any application on their desktop. For information about installing the
print driver, see the Installing and Deploying LiveCycle ES guides. For information about configuring this
feature, see Administering LiveCycle ES.
Converting HTML files to PDF documents
There are two ways that you can convert HTML files to PDF documents. You can create a PDF document
from an HTML file or ZIP file located on the file system, or you can create a PDF document from an HTML
file located at a given URL.
In addition to using LiveCycle Workbench ES or the Generate PDF Service API to convert HTML files to PDF
documents, you can also use the PDF Generator ES web pages. (See Generate PDF Administration Help.)
Converting PDF files to various types of documents
You can convert a PDF document to a different file type according to the supported applications, which
are based on the file name extensions.
You can generate the following types of files:
●
Encapsulated PostScript (EPS)
●
HTML
●
DOC (Microsoft Word format)
●
RTF
●
Text (both accessible and plain)
●
XML
Note: You can use the Convert PDF service to convert PDF documents to TIFF or PostScript files. (See
“Convert PDF Service” on page 23.)
Adobe LiveCycle ES
LiveCycle ES Services
Generate PDF Service
Converting PDF files to various types of documents
67
In addition to using Workbench ES or the Generate PDF Service API to convert PDF files to other document
types, you can also use the PDF Generator ES web pages. (See Generate PDF Administration Help.)
19
Generate 3D PDF Service
The Generate 3D PDF service converts files in a variety of formats to three-dimensional (3D) PDF
documents. These formats include files from Computer Aided Design (CAD) applications as well as formats
supported by the Generate PDF service. By converting these files into PDF documents, you can share the
file contents with anyone who has Adobe Reader installed.
Note: This service is for Microsoft Windows® only. To use this service, Acrobat Pro Extended version 9.0
must be installed on the computer that is hosting LiveCycle ES.
You can use the Generate 3D PDF service to convert a single file or to convert assemblies (a master file and
assemblies of parts) to a PDF file. You can also use the Generate 3D PDF service to combine a variety of file
types into one PDF file. For example, you can create a PDF file that contains a CAD drawing along with a
document that explains it.
The Generate 3D PDF service can convert the following file formats to a 3D PDF document:
●
Acrobat 3D
●
3D Studio
●
3DXML
●
ACIS
●
Autodesk Inventor
●
CADDS
●
CATIA V4
●
CATIA V5
●
CATIA V5 drawings
●
CGR
●
COLLADA
●
HP-GL
●
I-DEAS
●
IFC
●
IGES
●
JT Open
●
KMZ
●
Lattice XVL
●
OneSpace Designer
●
Parasolid
●
Pro/ENGINEER
●
Solid Edge
●
SolidWorks
●
STEP Exchange
68
Adobe LiveCycle ES
LiveCycle ES Services
●
Stereo Lithography
●
TTF PRC
●
UGS NX
●
UGS NX drawings
●
Universal 3D
●
VRML
●
Wavefront Object
Generate 3D PDF Service
Using the Generate 3D PDF service
69
Using the Generate 3D PDF service
You can do the following things using the Generate 3D PDF service:
●
“Creating a 3D PDF using server settings” on page 69.
●
“Creating a 3D PDF using settings in an XML file” on page 69.
For information about developing processes that use this service, see LiveCycle Workbench ES Help. For
information about developing client applications that programmatically interact with this service, see
Programming with LiveCycle ES. You can also use the LiveCycle PDF Generator ES web pages to perform the
tasks described in this section. ((See Programming with LiveCycle ES.)
For information about using the PDF Generator ES web pages to perform these tasks and about specifying
default settings, including default PDF and security settings, see Generate PDF Administration Help and
Applications and Services Administration Help.
Creating a 3D PDF using server settings
You can use the Generate 3D PDF service to create a PDF document based on conversion settings
configured on the LiveCycle ES server. For information about configuring the conversion settings, see
“Configuring Adobe 3D PDF Settings” in Generate PDF Administration Help.
Creating a 3D PDF using settings in an XML file
You can use the Generate 3D PDF service to create a PDF document using custom conversion settings
specified in an XML file. The XML file must conform to the XML Schema Definition (XSD) for conversion
settings. (See “Generate 3D PDF XML Schema Definitions” in LiveCycle Workbench ES Help.) If you do not
specify an XML file, the default conversion setting specified on the LiveCycle ES server is used.
20
JDBC Service
The JDBC service enables processes to interact with databases. For example, a process may require that
data submitted from a form populate an internal database or that data from a database prepopulate a
form. The process can contain application logic that binds data from the form fields to the underlying
database. Fields may be mapped to database columns. Separate line items in a filled form may also create
multiple rows in the database. If there is already a stored procedure that populates the database, a process
can use the stored procedure to update the data.
A process may also execute a business rule that is dependent on data stored in a database. For example, if
a customer is behind on payment, the order is not shipped, and the customer is sent an email reminder. A
process could query the database and look up the status based on the customer ID, and create a rule
based on this value.
Using the JDBC service
You can interact with the JDBC service by developing a process in LiveCycle Workbench ES that uses the
service. You can accomplish the following tasks using this service:
●
Specify the data source to use to connect to the database server.
●
Execute a stored procedure on the database.
●
Execute an SQL statement on a database server and return the number of rows that were affected.
●
Query the database using an SQL statement and return the result set as XML data.
●
Query the database using an SQL statement and save the first row of the result set.
For information about developing processes that use this service, see LiveCycle Workbench ES Help.
You can use the Applications and Services pages of LiveCycle Administration Console to configure default
properties for this service. (See Applications and Services Administration Help.)
Considerations for the JDBC service
The data source used to connect to the data server must be defined on the application server that hosts
the LiveCycle ES server. The default value is the JNDI name of the data source for the LiveCycle ES
database.
To call stored procedures or execute SQL statements, the database user account that is used to access the
database must have the required database permissions.
70
21
JMS Service
The JMS service enables interaction with Java Messaging System (JMS) providers that implement both
point-to-point messaging and publish/subscribe messaging.
The JMS service can receive a message from a designated message queue. For example, a process may be
initiated based on a message being placed in a queue when an order is created. The JMS service, in this
example, is used as the first step in the process to listen for the message and initiate the process.
The JMS service can also send a message to a designated message queue or publish a message to a topic.
For example, there may be a requirement to send a message in a queue that informs other systems to
“Create new customer profile” and pass the customer information. A process can leverage the JMS service
to send the message and pass the customer details as an XML document from a process variable.
Using the JMS service
You can interact with the JMS service by developing a process in LiveCycle Workbench ES that uses the
service. You can accomplish the following tasks using this service:
●
Publish a message to a topic on the JMS provider
●
Retrieve a message that is stored in a queue on the JMS provider
●
Send a message to a queue on the JMS provider
For information about developing processes that use this service, see LiveCycle Workbench ES Help.
You can use the Applications and Services pages of LiveCycle Administration Console to configure default
properties for this service. (See Applications and Services Administration Help.)
Considerations for the JMS service
There are factors to consider when developing processes that use this service:
●
Queues and topics must be configured on the JMS provider (by an administrator) before you can use
them. Typically, JMS applications use Java Naming and Directory Interface (JNDI) services for finding
the names of the topics and queues that are configured. After finding the name, the JMS client
connects to the JMS service to interact with the queues and topics.
●
You need to configure the JMS service with default properties so that the service operations can
connect and interact with a JMS provider and an associated JNDI service. The values of the service
properties are set to default values based on the JBoss® Application Server. You need to change these
values if you are using a different application server to host LiveCycle ES.
71
22
LDAP Service
The LDAP service provides operations for querying LDAP directories. LDAP directories are generally used
to store information about the people, groups, and services in an organization.
For example, LDAP directories typically store information about the business unit that a person belongs to,
information that identifies the person, and information about how to contact them, such as telephone
numbers and email addresses. A process could make use of the LDAP service to query the details based on
the user’s ID and map the details to a process variable in order to populate a form.
Using the LDAP service
You can interact with the LDAP service by developing a process in LiveCycle Workbench ES that uses the
service. You can accomplish the following tasks using this service:
●
Perform a search on the LDAP server and return the results which you can save as process data.
●
Perform a search on the LDAP server and return the results in an XML document, which you can save as
process data.
For information about developing processes that use this service, see LiveCycle Workbench ES Help.
You can use the Applications and Services pages of LiveCycle Administration Console to configure default
properties for this service. (See Applications and Services Administration Help.)
Considerations for the LDAP service
There are factors to consider when developing processes that use this service:
●
You must configure the properties used to connect to the LDAP server before using the operations of
the LDAP service.
●
LDAP directories use a tree structure as the data model. Different types of databases, such as Sun ONE
or Microsoft Active Directory, use different tree structures. LDAP administrators typically customize the
directory structure based on the requirements of their organization. You should consult with your
LDAP administrator for information about the directory that you are querying.
72
23
Output Service
The Output service lets you merge XML form data with a form design created in LiveCycle Designer ES to
create a document output stream in one of the following formats:
●
A PDF or PDF/A document output stream
●
An Adobe PostScript output stream
●
A Printer Control Language (PCL) output stream
●
A Zebra Programming Language (ZPL) output stream
The output stream can be sent to a network printer, a local printer, or a disk file. When you use the Output
service as part of a process created in LiveCycle Workbench ES, you can also send the output stream to an
email recipient as a file attachment.
Note: Although the Output service supports converting certain PDF documents to a PDF/A documents, it
is recommended that you use the DocConverter service to perform this task. The DocConverter
service is able to convert all PDF documents to PDF/A documents. For example, the DocConverter
service is able to convert a digitally signed PDF document to a PDF/A document while the Output
service is not able to convert a digitally signed PDF document.
This section includes the following topics:
●
“Using the Output service” on page 73
●
“Considerations for the Output service” on page 81
Using the Output service
You can accomplish the following tasks using the Output service:
●
“Creating PDF documents” on page 73
●
“Creating PDF/A documents” on page 74
●
“Sending print streams to printers” on page 74
●
“Processing batch data to create multiple documents” on page 77
●
“Creating search rules” on page 80
●
“Flattening interactive PDF documents” on page 81
For information about developing processes that use this service, see LiveCycle Workbench ES Help. For
information about developing client applications that programmatically interact with this service, see
Programming with LiveCycle ES. For information about invoking this service using watched folders or email
invocation, see LiveCycle ES Overview.
For information about initially setting up this service, see Output Administration Help.
Creating PDF documents
You can use the Output service to create a PDF document that is based on a form design and XML form
data that you provide. The PDF document that is created is not an interactive PDF document. That is, a user
73
Adobe LiveCycle ES
LiveCycle ES Services
Output Service
Creating PDF/A documents
74
cannot enter or modify form data. Also, the PDF document is not a PDF/A document that is meant for
long-term storage. The Output service is also able to create PDF/A documents. (See “Creating PDF/A
documents” on page 74.)
Creating PDF/A documents
You can use the Output service to create a PDF/A document. Because PDF/A is an archival format for
long-term preservation of the document’s content, all fonts are embedded and the file is uncompressed.
As a result, a PDF/A document is typically larger than a standard PDF document. In addition, a PDF/A
document cannot contain audio and video content. Like other Output service tasks, you provide both a
form design and data to merge with a form design to create a PDF/A document.
The PDF/A-1 specification has two levels of conformance: A and B. The major difference between the two
levels is that the logical structure (accessibility) support, which is required for conformance level A, is not
required for conformance level B. Regardless of the conformance level, PDF/A-1 dictates that all fonts are
embedded in the generated PDF/A document.
Although PDF/A is the standard for archiving PDF documents, it is not mandatory that PDF/A be used for
archiving if a standard PDF document meets your company’s needs. The purpose of the PDF/A standard is
to establish a PDF file that has the potential for long-term endurance.
Note: The AIIM website has a PDF/A FAQ section that you can access at
http://www.aiim.org/documents/standards/19005-1_FAQ.pdf.
Sending print streams to printers
You can use the Output service to send PostScript, Printer Control Language (PCL), and Zebra Printer
Language (ZPL) print streams to network printers. Using the Output service, you can merge XML data with
a form design and output the form as a print stream. For example, you can create a PostScript print stream
and send it to a network printer. The following illustration shows the Output service sending print streams
to network printers.
Adobe LiveCycle ES
Output Service
LiveCycle ES Services
Sending print streams to printers
75
The Output service supports the following printing access mechanisms:
Direct accessible printer: If a printer is installed on the same computer that it is being accessed from,
it is referred to as a direct accessible printer and the computer is named printer host. This type of printer
can be a local printer that is connected to the computer directly.
Indirect accessible printer: Technologies such as the common UNIX printing system (CUPS) and the
Line Printer Daemon (LPD) protocol are available. The printer that is installed on a print server is
accessed from other computers. To access an indirect accessible printer, the print server’s IP or host
name must be specified. Using this mechanism, you can send a print stream to an LPD URI when the
network has an LPD running. This lets you route the print stream to any printer that is connected to the
network that has a LPD running, without having the printer installed on the computer that the print job
is initialized from.
When using this method to send a print stream to a printer, specify one of these printing protocols:
CUPS: A printing protocol named common UNIX printing system. This protocol is used for UNIX
operating systems and enables a computer to function as a print server and to accept print requests
from client applications, process them, and send them to configured printers. On the AIX operating
system, usage of CUPS is not recommended.
DirectIP: A standard protocol for remote printing and managing print jobs. This protocol can be used
locally or remotely. Because this printing protocol is direct to the printer; no print queues are required.
LPD: A printing protocol named Line Printer Daemon protocol or Line Printer Remote (LPR) protocol that
provides network print server functionality for UNIX-based systems.
SharedPrinter: A printing protocol that enables a computer to use a printer that is configured for that
computer. This section discusses sending a print stream to a printer by using the shared printer
protocol.
CIFS: The Output service supports the Common Internet File System (CIFS) printing protocol. (See
“CIFS printing support” on page 92.)
The following table lists various input values and printing access mechanisms and the results.
Access mechanism
Print server URI
Printer name
Result
SharedPrinter
Any
Null
Exception: Required argument
sPrinterName cannot be null.
SharedPrinter
Any
Invalid
Output service throws an exception
stating that the printer cannot be found.
SharedPrinter
Any
Valid
Successful print job.
LPD
Null
Any
Output service throws an exception
stating that the required argument
sPrintServerUri cannot be null.
LPD
Invalid
Null
Output service throws an exception
stating that the required argument
sPrinterName cannot be null.
LPD
Invalid
Not null
Output service throws an exception
stating that sPrintServerUri is not
found.
Adobe LiveCycle ES
Output Service
LiveCycle ES Services
Sending print streams to printers
Access mechanism
Print server URI
Printer name
Result
LPD
Valid
Invalid
Output service throws an exception
stating that the printer cannot be found.
LPD
Valid
Valid
A successful print job.
CUPS
Null
Any
Output service throws an exception
stating that the required argument
sPrintServerUri cannot be null.
CUPS
Invalid
Any
Output service throws an exception
stating that the printer cannot be found.
CUPS
Valid
Any
Successful print job.
DirectIP
Null
Any
Output service throws an exception
stating that the required argument
sPrintServerUri cannot be null.
DirectIP
Invalid
Any
Output service throws an exception
stating that the printer cannot be found.
DirectIP
Valid
Any
Successful print job.
76
Tip: To print on remote network printers on Windows, it is easier to use the CIFS protocol than a shared
printer. The CIFS protocol is geared towards remote Windows print servers. (See “CIFS printing
support” on page 92.)
Running a service on Windows
If you deploy the Output service with LiveCycle ES that was installed by using the turnkey installation for
JBoss on Windows, the JBoss service is installed to run in the context of the Local System account. Services
that run in this context do not have access to network resources such as printers because the services are
not authenticated on the network. This means that network resources are not visible to the service. For
example, if you use the Output IVS installation verification sample to send a document to a network
printer, you will get an error message such as this one:
Printer \\server\queue not found
To solve this problem, enable JBoss to run in the context of a valid user. To perform this task, change the
properties of the JBoss service by clicking the Log On tab and selecting This Account. You must supply a
valid user name and password.
Note: This issue is only applicable when using the SharedPrinter access mechanism.
Sending the print stream to a network printer
Using the Output service, you can also send a print stream to a line printer daemon (LPD) URI when the
network has an LP daemon running. This method lets you route the print stream to any printer that is
connected to the network that has an LP daemon running without requiring the printer to be installed on
the computer from which the print job is initialized.
After you reference a valid XML data source that contains form data and set print run-time options, you
can invoke the Output service, which results in it sending a print stream to a network printer. It is
Adobe LiveCycle ES
LiveCycle ES Services
Output Service
Processing batch data to create multiple documents
77
recommended that you use the CIFS protocol when possible. A shared printer can be used when a printer
is locally installed.
A PostScript file created from a form design that contains a custom page size may not print. In this
situation, you must configure the printer to handle custom sizes. Each printer has its own way of handling
custom sizes. Some printers may allow you to configure the page size, media type, input trays, and so on.
Refer to your printer’s documentation to learn how to configure your printer to handle custom sizes. (See
“Printer tray selection” on page 88.)
When you send a print stream to a printer, consider the following factors:
●
Set PrinterProtocol to SharedPrinter, set ServerURI to a blank value, and set PrinterName
to a value that specifies the printer path (for example, \\server12r-nt\HP LaserJet 8150 PCL
6 Tower II Level 5).
●
The value for PrinterName is obtained by the path where the printer is installed. For example, assume
that the printer is on the server12r-nt server. To obtain the name of the printer, select Start, Printers
and Faxes, right-click the specific printer, and select Properties. On the General Tab, the text box
displays the printer name.
●
One reason that an issue may occur when printing with a SharedPrinter is that the login identifier may
not be correct. (See “Running a service on Windows” on page 76.)
Processing batch data to create multiple documents
The Output service can create separate documents for each record within an XML batch data source or a
single file that contains all records (this functionality is the default). For example, assume that ten records
are located within an XML data source and you instruct the Output service to create separate PDF
documents (or other types of output) for each record. As a result, the Output service generates ten PDF
documents. (Instead of creating documents, you can send multiple print streams to a printer.)
The following illustration also shows the Output service processing an XML data file that contains multiple
records. However, assume that you instruct the Output service to create a single PDF document that
contains all data records. In this situation, the Output service generates one document that contains all of
the records.
Adobe LiveCycle ES
LiveCycle ES Services
Output Service
Processing batch data to create multiple documents
The following illustration shows the Output service processing an XML data file that contains multiple
records. Assume that you instruct the Output service to create a separate PDF document for each data
record. In this situation, the Output service generates a separate PDF document for each data record.
The following XML data shows an example of a data file that contains three data records.
<?xml version="1.0" encoding="UTF-8"?>
<batch>
<LoanRecord>
<mortgageAmount>500000</mortgageAmount>
<lastName>Blue</lastName>
<firstName>Tony</firstName>
<SSN>555666777</SSN>
<PositionTitle>Product Manager</PositionTitle>
<Address>555 No Where Dr</Address>
<City>New York</City>
<StateProv>New York</StateProv>
<ZipCode>51256</ZipCode>
<Email>[email protected]</Email>
<PhoneNum>555-7418</PhoneNum>
<FaxNum>555-9981</FaxNum>
<Description>Buy a home</Description>
</LoanRecord>
<LoanRecord>
<mortgageAmount>300000</mortgageAmount>
<lastName>White</lastName>
<firstName>Sam</firstName>
<SSN>555666222</SSN>
<PositionTitle>Program Manager</PositionTitle>
<Address>557 No Where Dr</Address>
<City>New York</City>
<StateProv>New York</StateProv>
<ZipCode>51256</ZipCode>
<Email>[email protected]</Email>
<PhoneNum>555-7445</PhoneNum>
<FaxNum>555-9986</FaxNum>
<Description>Buy a home</Description>
</LoanRecord>
<LoanRecord>
<mortgageAmount>700000</mortgageAmount>
<lastName>Green</lastName>
<firstName>Steve</firstName>
<SSN>55566688</SSN>
<PositionTitle>Project Manager</PositionTitle>
78
Adobe LiveCycle ES
LiveCycle ES Services
Output Service
Processing batch data to create multiple documents
79
<Address>445 No Where Dr</Address>
<City>New York</City>
<StateProv>New York</StateProv>
<ZipCode>51256</ZipCode>
<Email>[email protected]</Email>
<PhoneNum>555-2211</PhoneNum>
<FaxNum>555-2221</FaxNum>
<Description>Buy a home</Description>
</LoanRecord>
</batch>
Note: Notice that the XML element that starts and ends each data record is LoanRecord. This XML
element is referenced by the application logic that generates multiple files.
Set PDF run-time options
You must set the following run-time options for the Output service to successfully process batch data and
create multiple files based on an XML data source:
Many Files: Specifies whether the Output service creates a single document or multiple documents.
You can specify true or false. To create a separate document for each data record in the XML data
source, specify true.
File URI: Specifies the location of the files that the Output service generates. For example, assume that
you specify C:\\Adobe\\forms\\Loan.pdf. In this situation, the Output service creates a file named
Loan.pdf and places the file in the C:\\Adobe\\forms folder. When there are multiple files, the file names
are Loan0001.pdf, Loan0002.pdf, Loan0003.pdf and so on.
Record Name: Specifies the XML element name in the data source that separates the data records. For
example, in the example XML data source that is shown earlier in this section, the XML element that
separates data records is called LoanRecord. (Instead of setting the Record Name run-time option,
you can set the Record Level by assigning it a numeric value that indicates the element level that
contains data records. However, you can set only the Record Name or the Record Level. You cannot set
both values.)
Incremental loading
When the Output service processes batch records, it reads data that contains multiple records in an
incremental manner. That is, the Output service reads the data into memory and releases the data as the
batch of records is processed. The Output service loads data in an incremental manner when either one of
two run-time options are set. If you set the Record Name run-time option, the Output service reads data in
an incremental manner. Likewise, if you set the Record Level run-time option to 2 or greater, the Output
service reads data in an incremental manner. (See “Processing batch data to create multiple documents”
on page 77.)
If the Output service cannot perform incremental data loading, the Output service writes the following
warning message in the log file of the J2EE application server hosting LiveCycle ES:
* 2007-11-01 11:51:23,215 WARN [com.adobe.document.XMLFormService]
$$$/com/adobe/document/xmlform/msg.XFA=Unable to perform an incremental
data load. Performing a full data load.
Note: If the Output service does not read data in an incremental manner, the entire batch data file is read
into memory, and this behavior may have a detrimental effect on the performance of the Output
service. (See “Improving the performance of the Output service” on page 93.)
Adobe LiveCycle ES
LiveCycle ES Services
Output Service
Creating search rules
80
Most XDP files (the form designs) contain an <xfa:datasets> node (for example, this node is present if
you create a form in Designer ES and bind form fields to a web service). When an <xfa:datasets> node
is present, the Output service does not read data in an incremental manner and instead reads the entire
batch file into memory. To use incremental loading, you can either remove the <xfa:datasets> node
from the XDP file or ensure that it is blank. (The XDP file is an XML file that you can edit within an XML
editor.) The following XML data is a blank <xfa:datasets> node.
<xfa:datasets xmlns:xfa="http://www.xfa.org/schema/xfa-data/1.0/">
</xfa:datasets>
However, when removing the <xfa:datasets> node (or leaving the node blank) from the XDP file,
schema validation cannot be performed, and you will also remove support for binding form fields to a web
service to obtain data. However, to retrieve multiple records from a web service in order to perform batch
processing, you can programmatically retrieve data from the web service and write the data to the XML
data source that is used to perform batch processing. That is, using a programming language like Java, you
can dynamically obtain records from a web service and create an XML data source. You can then use that
XML data source to perform batch processing by using the Output service.
Tip: Before modifying a form design by removing the <xfa:datasets> node, it is good practice to
create a backup XDP file.
Creating search rules
You can create pattern matching rules (also knows as search rules) that result in the Output service
examining input data and using different form designs based on the data content to generate output. For
example, if the text mortgage is located within the input data, the Output service can use a form design
named Mortgage.xdp. Likewise, if the text automobile is located in the input data, the Output service can
use a form design that is saved as AutomobileLoan.xdp. Although the Output service can generate
different output types, this section assumes that the Output service generates a PDF file. The following
illustration shows the Output service generating a PDF file by processing an XML data file and using one of
many form designs.
Adobe LiveCycle ES
LiveCycle ES Services
Output Service
Flattening interactive PDF documents
81
In addition, the Output service can generate document packages, where multiple records are provided in
the data set and each record is matched to a form design. The Output service generates a single document
made up of multiple form designs.
To define pattern matching rules, define one or more text pattern that the Output services searches for in
the input data. For each text pattern that you define, you must specify a corresponding form design that is
used if the text pattern is located within the data. If a text pattern is located, the Output service uses the
corresponding form design to generate the output. An example of a text pattern is mortgage.
Flattening interactive PDF documents
You can use the Output service to transform an interactive PDF document (for example, a form) to a
non-interactive PDF (a PDF document). An interactive PDF document lets users enter or modify data
located in the PDF document fields. The process of transforming an interactive PDF document to a
non-interactive PDF document is called flattening. When a PDF document is flattened, a user cannot
modify the data located in the document’s fields. One reason to flatten a PDF document is to ensure that
data cannot be modified.
You can flatten the following types of PDF documents:
●
Interactive PDF documents created in Designer ES (that contain XFA streams).
●
Acrobat PDF forms
If you attempt to flatten a PDF document that is a non-interactive PDF document, you will cause an
exception.
Considerations for the Output service
When working with the Output service, you must consider several factors. For example, decide whether
you want to use the Output service to generate document output as files, send documents to printers, or
email documents to email recipients as file attachments. Also, you must consider the format of the
document.
There are also considerations related to the following topics:
●
Form data (see page 82)
●
Supported document types (see page 83)
●
Signature fields (see page 84)
●
Flattening a digitally signed PDF document (see page 84)
Adobe LiveCycle ES
Output Service
LiveCycle ES Services
Form data
●
Email support (see page 84)
●
Maximizing throughput (see page 84)
●
Printable areas (see page 85)
●
Scripts (see page 85)
●
Working with fonts (see page 86)
●
Working with device profile files (XDC files) (see page 87)
●
Setting up Zebra printers for RFID label printing (see page 88)
●
Printer tray selection (see page 88)
●
Paper handling (see page 89)
●
Working with the XCI configuration file (see page 90)
●
CIFS printing support (see page 92)
●
Improving the performance of the Output service (see page 93)
82
Form data
The Output service accepts both a form design that is typically created in Designer ES and XML form data
as input. To populate a document with data, an XML element must exist in the XML form data for every
form field that you want to populate. The XML element name must match the field name. An XML element
is ignored if it does not correspond to a form field or if the XML element name does not match the field
name. It is not necessary to match the order that the XML elements are displayed in as long as all XML
elements are specified.
Consider the following example loan application form.
Adobe LiveCycle ES
LiveCycle ES Services
Output Service
Supported document types
83
To merge data into this form design, you must create an XML data source that corresponds to the form.
The following XML represents an XDP XML data source that corresponds to the example mortgage
application form.
<?xml version="1.0" encoding="UTF-8" ?>
- <xfa:datasets xmlns:xfa="http://www.xfa.org/schema/xfa-data/1.0/">
- <xfa:data>
- <data>
- <Layer>
<closeDate>1/26/2007</closeDate>
<lastName>Johnson</lastName>
<firstName>Jerry</firstName>
<mailingAddress>[email protected]</mailingAddress>
<city>New York</city>
<zipCode>00501</zipCode>
<state>NY</state>
<dateBirth>26/08/1973</dateBirth>
<middleInitials>D</middleInitials>
<socialSecurityNumber>(555) 555-5555</socialSecurityNumber>
<phoneNumber>5555550000</phoneNumber>
</Layer>
- <Mortgage>
<mortgageAmount>295000.00</mortgageAmount>
<monthlyMortgagePayment>1724.54</monthlyMortgagePayment>
<purchasePrice>300000</purchasePrice>
<downPayment>5000</downPayment>
<term>25</term>
<interestRate>5.00</interestRate>
</Mortgage>
</data>
</xfa:data>
</xfa:datasets>
Supported document types
For complete access to the rendering capabilities of the Output service, it is recommended that you use an
XDP file as input. In some cases, a PDF file can be used. However, using a PDF file as input has the following
limitations:
●
A PDF document that does not contain an XFA stream cannot be rendered as PostScript, PCL, or ZPL
formats. The Output service can render PDF documents with XFA streams (that is, forms created in
Designer ES) into PostScript, PCL, and ZPL formats. However, if the PDF document with XFA is signed,
certified, or contains usage rights (applied using the Reader Extensions service), it cannot be rendered
to these print formats.
●
If the input PDF file is based on a form created in Designer ES and it is signed or certified, data will not
be merged into the form.
●
Run-time options such as PDF version and tagged PDF are not supported for Acrobat forms. They are
valid for PDF forms that contain XFA streams; however, these forms cannot be signed or certified.
Typically, a PDF file is used as input when transforming an interactive PDF file to a non-interactive PDF file.
Adobe LiveCycle ES
Output Service
LiveCycle ES Services
Signature fields
84
Signature fields
When using the Output service to produce a PDF document using a form design that contains a signature
field, there is a limitation that you should consider. If a form design contains a signature field, and you set
the renderAtClient run-time option to true, then an unsigned signature field is not retained in the
resulting PDF document. However if this run-time option is set to false, then an unsigned signature field
is retained in the resulting PDF document.
Flattening a digitally signed PDF document
If you attempt to flatten an interactive XFA PDF document that contains a signed signature field and set
the renderAtClient run-time option to true, the result PDF document is not flattened and remains
interactive. That is, the fields within the PDF document let users enter and modify data. This behavior
occurs because the renderAtClient run-time option should be used when the input to an Output
service operation is a form design (an XDP file), not a PDF file. To successfully flatten a digitally signed PDF
document, set the renderAtClient run-time option to false.
Email support
For email functionality, you can create a process in Workbench ES that uses the Email service. A process
represents a business process that you are automating. You cannot programmatically send email
messages by using the Output Service API. For information about creating processes, see LiveCycle
Workbench ES Help.
Note: You can attach multiple PDF documents to a single email message that invokes the Output service.
For example, you can convert interactive PDF documents to non-interactive PDF documents by
sending an email message that contains PDF file attachments. For each file attachment, a separate
email message is returned to the email recipient who sent the message. Each email message
contains one file attachment and each file attachment has the same file name.
Maximizing throughput
LiveCycle Output ES can process large XML data files that contain many records. You can instruct the
Output service to either create an output file for each record or create a single output file that contains all
the data records. (See “Processing batch data to create multiple documents” on page 77.)
Throughput limitations are not discreet and will vary, depending of the complexity of the form design,
available memory, options chosen, and other activity on the application server. Errors that are generated
when such a limitation is reached may identify lack of memory as being the problem, but not always, and
may seem unrelated. Be aware of this limitation, and use the Output service within number guidelines for
safe page generation.
For a medium complexity form (the PO form in Output IVS; two-page records for batch case) on a typical
entry-level business server, the following approximate number guidelines for safe page generation were
observed.
Format
Batch records/many small
documents
Big record/one big
document
PDF (not tagged) and PDF/a-1b
10000 pages
500 pages
PDF (tagged) and PDF/a-1a
2500 pages
250 pages
Adobe LiveCycle ES
Output Service
LiveCycle ES Services
Printable areas
Format
Batch records/many small
documents
Big record/one big
document
PostScript
10000 pages
500 pages
PCL (using TrueType or printer resident
fonts)
10000 pages
500 pages
85
There are a few things you should notice to maximize throughput performance. Select tagging for PDF
only if it is required; tagged files are substantially larger than non-tagged files and take longer to render. Be
aware that PDF/A-1a is always tagged; PDF/A-1b is not tagged. For PCL printing, the use of OpenType fonts
in form designs formats properly but decreases throughput, generates a larger output file, and does not
deliver optimal performance. For increased performance, use or map properly licensed TrueType fonts or
use printer resident fonts.
When processing large data files or operating on a busy server, it may be necessary to increase the Output
service time-out; the default time-out is 180 seconds. To change the time-out value, ensure that hardware
servers have adequate memory and that the memory is available to the Java application server heap. For
information about changing the time-out value, see Applications and Services Administration Help.
When processing a big record/one big document case, throughput will be maximized when the XML data
is structured so that a recordLevel run-time option of 2 can be used. For example, instead of structuring
your data file as follows:
<datafile>
<field>123</field>…
</datafile>
Structure it this way, adding another level:
<datafile>
<record>
<field>123</field>
…
</record>
</datafile>
Printable areas
The default 0.25-inch nonprintable margin is not exact for label printers and varies from printer to printer
and label size to label size. It is recommended that you keep the 0.25-inch margin or reduce it. However, it
is strongly recommended that you do not increase the nonprintable margin. If you do, information in the
printable area may not print properly.
Always ensure that you use the correct XDC file for the printer. For example, avoid the mistake of choosing
an XDC file for a 300-dpi printer and sending the print stream to a 200-dpi printer.
Scripts
A form design that is used with the Output service can contain scripts that run on the server. Ensure that a
form design does not contain scripts that run on the client. For information about creating form design
scripts, see LiveCycle Designer ES Help.
Adobe LiveCycle ES
LiveCycle ES Services
Output Service
Working with fonts
86
Working with fonts
This section discusses, in the following topics, how the Output service handles fonts within a generated
document:
●
Using printer resident fonts
●
Font mapping
●
Coordinating fonts between Designer ES and the Output service
Using printer resident fonts
The Output service can generate documents that contain resident fonts. XDC files that are available with
the Output service have a common list of printer resident fonts defined. You do not need to edit an XDC
file to use these fonts. However, you can modify an XDC file using LiveCycle ES XDC Editor. (See LiveCycle ES
XDC Editor Help.)
Printer resident fonts are stored inside a printer either in a special hardware cartridge or built into the
printer's memory. For PostScript printers, only the name of the font is required. For PCL printers, it is
necessary to define an escape sequence of characters. Printer resident font names can be obtained from
the printer’s front panel or by using the printer's built in web server (if available).
To use printer resident fonts, you can perform these tasks:
1. Identify the name of the printer resident font to use.
2. Specify the printer resident font name in the form design.
3. Locate the most suitable XDC file to use for your printer based on the type of output to render
(PostScript, ZPL, or PCL) and make the appropriate changes to the XDC file.
4. Test the output.
Note: For information about performing these tasks, see LiveCycle ES XDC Editor Help.
Font mapping
If a font is installed on a client computer, it is available in the drop-down list in Designer ES. If the font is not
installed, it is necessary to specify the font name manually. The “Permanently replace unavailable fonts”
option in Designer ES should be off. Otherwise, when the XDP file is saved in Designer ES, the substitution
font name will be written to the XDP file. This means that the printer-resident font will not be used.
To design a form that uses printer-resident fonts, choose a typeface name in Designer ES that matches
those fonts that are available on the printer. A list of fonts that are supported for PCL or PostScript are
located in the corresponding device profiles (XDC files). Alternatively, font mapping can be created to map
nonprinter-resident fonts to printer-resident fonts of a different typeface name. For instance, in a
PostScript scenario, references to Arial can be mapped to the printer-resident Helvetica typeface.
There are two types of OpenType fonts. One type is a TrueType OpenType font that is supported by PCL,
and the other is CFF OpenType. PDF and PostScript output can support embedded Type-1, TrueType, and
OpenType fonts. PCL output can support embedded TrueType fonts. However, Type-1 and OpenType fonts
are not embedded in PCL output. Therefore, any content that is formatted with Type-1 and OpenType
fonts is rasterized and generated as a bitmap image that can be large, as well as slower to generate.
Adobe LiveCycle ES
LiveCycle ES Services
Output Service
Coordinating fonts between Designer ES and the Output service
87
Downloaded or embedded fonts are automatically substituted when generating PostScript, PCL, or PDF
output. This means that only the subset of the font glyphs that are required to properly render the
generated document is included in the generated output.
For information about creating form designs for the Output service, including handling fonts, see LiveCycle
Designer ES Help.
Coordinating fonts between Designer ES and the Output service
Adobe PostScript Type 1 is a well established standard for encoding digital fonts. It supports single-byte
character representations, which means that it can represent encoding for a maximum of 256 characters
(glyphs). To determine the encoding of a font, use Windows to open the folder that contains the font and
right-click the font. The encoding type appears in the File Type field of the General window.
Note: For information about setting up fonts for the Output service, see Administering LiveCycle ES.
Working with device profile files (XDC file)
A device profile (XDC file) is a printer description file in XML format that enables the Output service to
output documents as PostScript, PCL, and ZPL formats. The following XDC files are used by the Output
service and represent generic print description language support:
hppcl5c.xdc
hppcl5e.xdc
ps_plain_level3.xdc
ps_plain_mt.xdc
ps_plain.xdc
zpl203.xdc
zpl300.xdc
zpl600.xdc
It is not necessary to modify these files for the Output service to create print streams. However, you can
modify them to meet your business requirements. (See LiveCycle ES XDC Editor Help.)
After you modify an XDC file, reference it as part of developing a client application. (See Programming with
LiveCycle ES.)
In addition, the following files are sample XDC files that support the features of specific printers, such as
resident fonts, paper trays, and stapler. The purpose of these samples is to help you understand how to set
up your own printers by using device profiles. The samples are also a starting point for similar printers in
the same product line.
hp4350pcl5e.xdc: HP 4350 printer device profile using PCL5e (monochrome)
hp4350ps.xdc: HP 4350 printer device profile using PostScript (monochrome and color)
lmt644pcl5e.xdc: Lexmark T644 printer device profile using PCL5e (monochrome)
lmt644ps.xdc: Lexmark T644 printer device profile using PostScript (monochrome and color)
Adobe LiveCycle ES
LiveCycle ES Services
Output Service
Setting up Zebra printers for RFID label printing
88
Setting up Zebra printers for RFID label printing
Forms created in Designer ES can handle barcodes. As of LiveCycle ES 8.0.1, support for elementary radio
frequency identification (RFID), which is a method of identifying unique items by using radio waves, was
introduced and implemented as a barcode named rfid. You can place an RFID object on a label while
creating a form design using Designer ES.
To use RFID capability, you must set RFID settings on your RFID printer. The RFID capability is supported
only for Zebra label printers and not in PS/PCL or PDF.
Next, you must configure the RFID parameters in the XDC file based on the RFID printer configuration
settings. There are four options in the XDC file that you must configure:
rfidBlockRetries: Controls the number of times the printer attempts to write to a particular block of a
single RFID tag. The accepted values for this option is between 0 and 10. If you do not specify a value
for this setting, the printer uses the default value of 0.
rfidLabelRetries: The number of labels that are attempted in case of an encode or write failure. This
number is different from the rfidBlockRetries setting. The accepted values for this option is
between 0 and 10. If you do not specify a value for this setting, the printer uses the default value of 3.
rfidTagType: Controls the encoding type of the data in the RFID label. The RFID readers should have
the same tag type as the RFID printer. The accepted values for this option vary from printer to printer.
(See your printer documentation). Generally, this option uses values between 0 and 5.
rfidTransponderPosition: Represents the distance of the microchip on the label from the top. Specify
this value in dots. The accepted values are from 0 to length of the label. If the microchip is located at the
beginning of the label, set this option to 0.
When the setup is finished, supply the data that you want to encode into the microchip of the RFID.
Designer ES has an object named rfid that you can use. The text to be encoded must be specified by using
that object for RFID printing. The RFID printing using the Output service can be done only on the labels
that have only one microchip. You cannot use the preview in Designer ES for RFID objects because they are
printer-only objects and are not recognized by Designer ES.
Printer tray selection
When sending a document to a printer by using the Output service, you can specify the printer tray that is
used. Designer ES distinguishes between paper (page) size and which input tray on the printer should
provide the requested paper. This functionality accommodates scenarios where a printer may have
multiple different types of a particular paper size loaded into different input trays, so that a document can
select paper from individual trays on a per-page basis.
Designer ES does not expose paper size and input tray selection as two distinct properties. Instead, a
Designer ES master page can be associated with a paper type selected from a set of supported paper types
defined in the Designer.xdc device profile. Within the device profile, each paper type can be configured to
select paper from a particular input tray. (See “Working with device profile files (XDC file)” on page 87.)
Designer ES provides four duplicates of common paper types for Letter and Legal paper sizes, specifically
to accommodate paper tray selection. These duplicate paper types have the following names:
●
Letter Plain
●
Letter Letterhead
●
Letter Color
●
Legal Special
Adobe LiveCycle ES
LiveCycle ES Services
Output Service
Paper handling
89
The XDC Editor within Workbench ES is used to map or assign a physical input tray to a paper type; the four
names provided in Designer ES covers most tray-selection needs. For example, the deployed device profile
can be modified so that the Letter Color paper type causes the printer to select yellow paper loaded into a
secondary letter-sized input tray.
The Output service matches paper types that are used in the form, by name, against paper types that are
defined in the device profile deployed to the server; therefore, only the deployed device profile needs to
be modified to ensure the appropriate input tray selection.
Although the four provided paper types are usually adequate, it is possible to create additional paper
types. Additional paper types can be used in the XDC Editor by creating a new paper type name, but it
must exist in Designer ES to be used. To add paper types, the Designer.xdc file must be hand-edited,
copying an existing entry of the correct paper size and changing the name as desired.
The concept of printer trays is not applicable to PDF. That is, you cannot specify a particular printer tray
when printing a PDF document. The selection at the printer is based on page size, and the first
non-secured tray that matches the required page size is used. If no match to size is found, a manual feed is
requested.
For PCL documents, each master page in the XDP file (the form design created in Designer ES) is mapped
to a paper type. The paper type is, in turn, mapped to an entry in the XDC file. It is important that you use
caution because the literal that you view in the paper type list may get turned into a slightly different
literal by Designer ES. Check the XML source to get the precise literal that is used in the XDC file.
In the XDC file, the paper type appears in the stock column. You can modify the entry to show the tray
number that contains the paper type that you want to use. However, the tray number that you see on the
printer itself (for example, tray 1, tray 2, and so on) may not be the correct device number that the printer
understands. You need to review the printer reference manual to ensure that you have the tray number
correctly stated.
If the stated tray number is not valid or carries a page size that does not match the requested page size,
the printer reverts to the first non-secured tray that represents the correct paper size.
For PostScript documents, the printer tray selection process is the same as for PCL documents. To select
the tray by media type, keep the Input Tray Number column in the XDC file blank and enter the media type
in the Input Tray Type column. It is assumed that the printer is configured to recognize the media type.
Note: A PostScript file created from a form design that contains a custom page may not print. In this
situation, you must configure the printer to handle custom sizes. Each printer has its own way of
handling custom sizes. Some printers allow you to configure the page size, media type, input trays,
and so on. See your printer’s documentation to learn how to configure your printer to handle
custom sizes.
Paper handling
Designer ES exposes control over duplex printing in two ways, depending on whether the form is
intended to be generated as a PDF document and subsequently printed from Adobe Reader or Acrobat or
printed directly to a PCL or PostScript device.
When the form is intended to generate a PDF document, settings that are related to how the PDF
document should be printed can be configured from the Form Properties dialog box within Designer ES.
These settings include the number of copies to print and the duplexing setting. Subsequent printing of a
PDF document from Adobe Reader or Acrobat uses these settings.
Adobe LiveCycle ES
Output Service
LiveCycle ES Services
Working with the XCI configuration file
90
Duplexing can also be specified by using the pagination property of the Output service operations that
are available within Workbench ES and also from the Java API and web service API.
In addition to basic selection of simplex or duplex printing, additional capabilities are available in
Designer ES to design forms that adjust according to simplex and duplex printing scenarios.
Master pages can be assigned to odd-numbered (front side) or even-numbered (back side) printed pages.
Using this approach, slightly different master pages can be designed for the front and back pages, and the
Output service automatically selects the appropriate master page, depending on whether it is currently
printing on the front or back of the page. One common use case is to create similar master pages that
place the running page count on either the left side or the right side of the page, and assign the master
pages as odd or even to ensure that the page count is always on the inside or outside of a duplex-printed
document.
Working with the XCI configuration file
The Output service uses an XCI configuration file while performing various tasks, such as embedding a
font into a document. The default.xci file is in the following location:
svcdata\XMLFormService
For example, assuming that LiveCycle ES is installed on JBoss, the full path is as follows:
[Install location]\Adobe\LiveCycle8.2\jboss\server\all\svcdata\XMLFormService
Setting XCI configuration file options
This table specifies XCI options that the Output service uses.
XCI option
Description
config/present/pdf/creator
Identifies the document creator using the Creator entry in
the Document Information dictionary. For information
about this dictionary, see the PDF Reference guide.
config/present/pdf/producer
Identifies the document producer using the Producer
entry in the Document Information dictionary. For
information about this dictionary, see the PDF Reference
guide.
config/present/layout
Controls whether the output is a single panel or
paginated.
config/present/pdf/compression/level
Specifies the degree of compression to be used when
generating a PDF document.
config/present/pdf/fontInfo/embed
Controls font embedding in the output document. (See
“Embedding fonts” on page 92.)
config/present/pdf/scriptModel
Controls whether XFA-specific information is to be
included in the output PDF document.
config/present/pdf/interactive
Specifies whether a PDF form is generated as a
non-interactive form (for printing) or as an interactive
form for online use.
Adobe LiveCycle ES
Output Service
LiveCycle ES Services
Working with the XCI configuration file
91
XCI option
Description
config/present/common/data/adjustData
Controls whether the XFA application adjusts the data
after merging.
config/present/pdf/renderPolicy
Controls whether the generation of page content is done
on the server or deferred to the client.
config/present/common/locale
Specifies the default locale used in the output document.
config/present/destination
When contained by a present element, specifies the
output format. When contained by an openAction
element, specifies the action to be performed upon
opening the document in an interactive client.
config/present/output/type
Specifies either the type of compression to be applied to a
file or the type of output to be produced.
config/present/common/temp/uri
Specifies the Form URI.
config/present/common/template/base
Supplies a base location for URIs in the form design. When
this element is absent or empty, the location of the form
design is used as the base.
config/present/common/log/to
Controls the location that log data or output data is
written to.
config/present/output/to
Controls the location that log data or output data is
written to.
config/present/script/currentPage
Specifies the initial page when the document is opened.
config/present/script/exclude
Informs LiveCycle ES which events to ignore.
config/present/pdf/linearized
Controls whether the output PDF document is linearized.
config/present/script/runScripts
Controls which set of scripts LiveCycle ES executes.
config/present/pdf/tagged
Controls the inclusion of tags into the output PDF
document. Tags, in the context of PDF, are additional
information included in a document to expose the logical
structure of the document. Tags assist accessibility aids
and reformatting. For example a page number may be
tagged as an artifact so that a screen reader does not
enunciate it in the middle of the text. Although tags make
a document more useful, they also increase the size of the
document and the processing time to create it.
config/acrobat/acrobat7/dynamicRender
Controls whether the PDF document re-renders during
the session to show or hide objects, instantiate pages, and
so on.
config/present/pdf/fontInfo/alwaysEmbed
Specifies a font that is embedded in the output
document.
config/present/pdf/fontInfo/neverEmbed
Specifies a font that must never be embedded in the
output document.
Adobe LiveCycle ES
Output Service
LiveCycle ES Services
CIFS printing support
92
XCI option
Description
config/present/pdf/pdfa/part
Specifies the version number of the PDF/A specification
that the document conforms to.
config/present/pdf/pdfa/amd
Specifies the amendment level of the PDF/A specification.
config/present/pdf/pdfa/conformance
Specifies the conformance level with the PDF/A
specification.
config/present/pdf/version
Specifies the version of PDF that is to be generated.
config/present/submitUrl
Specifies the HTTP URL that form data is submitted to.
Embedding fonts
To demonstrate how to work with an XCI file, this section discusses how to use the XCI file to embed a font
into a resultant document (the document that the Output service generates). Embedding a font is only
relevant for PDF output. For PCL and PostScript output, the font is automatically embedded if it is not
resident on the printer. The idea of this setting is to reduce the PDF file size by having the global embed
setting off but provide a way to embed particular fonts into a document.
To embed a font into the resultant document, perform the following tasks:
1. Place the font into the windows\fonts folder that belongs to the computer that LiveCycle ES is
deployed on.
2. Copy the XCI file located in the folder that is specified in this section; paste the XCI file in a new location
and rename it custom.xci. For example, use the location C:\XCI\custom.xci.
3. Edit the custom.xci file by creating a new XML element named fontInfo (place it under the pdf
element). Within the fontInfo element, add the following XML data:
<alwaysEmbed>[name of the new font]</alwaysembed>
4. Modify the XCI URI option within Workbench ES or by using Output Service API.
CIFS printing support
The Output service supports Common Internet File System (CIFS) printing. A printer administrator must
make a printer accessible to the CIFS protocol. On computers running Windows, this step is done by
sharing the printer by using the net share command. On UNIX-like systems, this step is done by using the
Samba server.
If the printer is secured, the printer administrator may provide the LiveCycle ES administrator with the user
name and password that are required to print to the printer queue. To access the printer by using the user
name and password, the LiveCycle ES administrator has to register them by using LiveCycle ES Trust Store.
The Output service looks up the user name and password for a given UNC path by using it and its parent
components as the profile name.
Assume that the LiveCycle ES administrator registers \\mysvr-nt and \\mysvr-nt\specific-printer-1 as
profiles in LiveCycle ES Trust Store. In this situation, the print output maps to given paths to profile name
as follows.
Adobe LiveCycle ES
Output Service
LiveCycle ES Services
Improving the performance of the Output service
Printer path
Resolved Trust Store profile
\\mysvr-nt\printer1
\\mysvr-nt
\\mysvr-nt\specific-printer-1
\\mysvr-nt\specific-printer-1
\\other-server\printer1
null
93
Assume that a LiveCycle ES user invokes the sendToPrinter operation and passes the printer path as
the server name parameter, and leaves the printer name parameter blank. The required user name and
password values are resolved by using LiveCycle ES Trust Store profiles.
When using the CIFS protocol, the printer queue is shared as a resource by a server. To print a file, the
following tasks are performed:
●
The client authenticates itself to the server for the specific resource (for example, the shared printer
queue on server).
●
The client opens the printer queue by using the OPEN_PRINT_FILE packet. The client needs to
provide the printer job name. The printer job name is unique per client. On opening the printer queue,
the server creates a spool file and returns its handle to the client.
●
The client writes to the opened remote spool file by using the WRITE_PRINT_FILE packet.
●
The client closes the remote spool file by using the CLOSE_PRINT_FILE packet. On successfully
processing this packet, the server starts printing the document on the printer.
Improving the performance of the Output service
You can improve the performance of the Output service by making some adjustments while working with
this service by using either the Output Service API or Workbench ES. The following list specifies
performance factors to consider:
●
When invoking the Output service within a process, you can improve the performance by making the
process a short-lived process. A long-lived process persists data in the LiveCycle ES database, resulting
in a performance cost.
●
As of LiveCycle ES 8.2, you can turn off security for the Output service. By turning off security, the
Output service does not authenticate a user when it performs an operation, thereby improving the
performance of a given operation. For information about turning off security, see Programming with
LiveCycle ES.
●
Changing the caching option of the LiveCycle ES repository to manual optimizes performance (the
default setting results in low performance). (See Applications and Services Administration Help.)
●
Forms that contain justified fields decrease performance; that is, justification degrades performance.
●
Use of non-explicit data binding in form designs for batch processing results in decreased
performance. (See “Processing batch data to create multiple documents” on page 77.)
●
When working with batch processing and when possible, use incremental loading. (See “Incremental
loading” on page 79.)
●
When designing a form, fonts that support a particular language should be used to improve
performance. For example, choosing Myriad Pro as the font for a field which contains Japanese data
will decrease performance as opposed to using a font from the Kozuka Pro family.
Note: For information about processing large XML data files that contain many records., see “Maximizing
throughput” on page 84.
24
PDF Utilities Service
The PDF Utilities service enables you to convert documents between PDF and XDP file formats, set and
retrieve the save mode of PDF documents, and query information about a PDF document. For example,
you can determine whether a PDF document contains comments or attachments.
Using the PDF Utilities service
You can accomplish the following tasks using this service:
●
Clone PDF: This feature is available only in LiveCycle Workbench ES. Replicates a PDF document. The
resulting PDF document can be manipulated independently of the input PDF document. If a given PDF
document is passed to multiple services without cloning, the result may be difficult to use effectively.
For example, assume that a PDF document is passed to two services sequentially. When the first service
modifies and returns the PDF document as a document value, the next service to use the document
value detects modifications that the first service made.
After using the Clone PDF operation, you are assured that the input document value and the result
document value are identical but distinct, and that any future modification of either value will not be
reflected in the other object.
●
Multiple Clone of PDF: This feature is available only in Workbench ES. Clones a PDF document a
specified number of times. The resulting PDF documents are used independently of the input PDF
document.
●
Convert PDF documents to XDP documents: Converts a PDF document to an XDP file. For a PDF
document to be successfully converted to an XDP file, the PDF document must contain an XFA stream
in the dictionary.
●
Convert XDP documents to PDF documents: Converts an XDP file to a PDF file. To successfully
convert an XDP file to a PDF file, the XDP file must contain an encoded PDF packet.
●
Retrieve PDF document properties: Performs queries on the specified PDF document and returns the
results as a PDFPropertiesResult value. You can perform the following queries:
●
●
Is a PDF Document
●
Is a PDF Package
●
Get the PDF Version
●
Check for Attachments
●
Check for Comments
●
Recommended Acrobat Version
●
Form Type
●
Check for AcroForm
●
Has a Fillable Form
●
Is an XFA Document
●
Get the XFA Version
Get PDF Save Mode: Returns the save mode of a PDF document. The save mode represents the mode
in which the PDF document is saved. In addition, the save mode specifies whether the request is
94
Adobe LiveCycle ES
PDF Utilities Service
LiveCycle ES Services
Using the PDF Utilities service
95
considered a requirement or only a suggestion. Save mode values are not influenced by the PDF
document content. The following values are possible PDF save-mode values:
●
●
FAST_WEB_VIEW, which is used while viewing the PDF document online.
●
INCREMENTAL, which performs the save operation in the least amount of time.
●
FULL, which saves with fewer optimizations.
Set PDF Save Mode: Sets the save mode of a PDF document. The save mode represents the mode in
which the PDF document is saved. In addition, the save mode specifies whether the request is
considered a requirement or only a suggestion. Save mode values are not influenced by the PDF
document content.The following values are possible PDF save-mode values:
●
FAST_WEB_VIEW, which is used while viewing the PDF document online.
●
INCREMENTAL, which performs the save operation in the least amount of time.
●
FULL, which saves with fewer optimizations.
For information about developing processes that use this service, see LiveCycle Workbench ES Help. For
information about developing client applications that programmatically interact with this service, see
Programming with LiveCycle ES.
25
Reader Extensions Service
The Reader Extensions service enables your organization to easily share interactive PDF documents by
extending the functionality of Adobe Reader with additional usage rights. The Reader Extensions service
works with Adobe Reader 7.0 or later. The service adds usage rights to a PDF document, activating features
that are not usually available when a PDF document is opened using Adobe Reader, such as adding
comments to a document, filling forms, and saving the document. Third-party users do not require
additional software or plug-ins to work with rights-enabled documents.
When PDF documents have the appropriate usage rights added, recipients can do the following activities
from within Adobe Reader:
●
Complete PDF documents and forms online or offline, allowing recipients to save copies locally for
their records and still keep added information intact
●
Save PDF documents to a local hard drive to retain the original document and any additional
comments, data, or attachments
●
Attach files and media clips to PDF documents
●
Sign, certify, and authenticate PDF documents by applying digital signatures using industry-standard
public key infrastructure (PKI) technologies
●
Submit completed or annotated PDF documents electronically
●
Use PDF documents and forms as an intuitive development front end to internal databases and web
services
●
Share PDF documents with others so that reviewers can add comments by using intuitive markup
tools, such as electronic sticky notes, stamps, highlights, and text strikethrough (the same functions
that are available in Acrobat)
●
Support barcoded forms decoding when installed with Adobe LiveCycle Barcoded Forms ES (8.2)
licensing
These special user capabilities are automatically activated when a rights-enabled PDF document is
opened within Adobe Reader. When the user is finished working with a rights-enabled document, those
functions are once again disabled in Adobe Reader until the user receives another rights-enabled PDF
document.
The following topics provide information about the tasks that you can perform and how to achieve the
best results:
●
“Using the Reader Extensions service” on page 96
●
“Considerations for the Reader Extensions service” on page 98
Using the Reader Extensions service
This section includes the following topics that describe how you can use the Reader Extensions service:
●
“Applying usage rights to PDF documents” on page 97
●
“Removing usage rights from PDF documents” on page 98
●
“Retrieving credential information” on page 98
96
Adobe LiveCycle ES
LiveCycle ES Services
Reader Extensions Service
Applying usage rights to PDF documents
97
Applying usage rights to PDF documents
You can use the Reader Extensions service to apply usage rights to PDF documents. Usage rights pertain
to functionality that is available in Acrobat Professional and Acrobat Standard but not in Adobe Reader,
such as the ability to add comments to a document, fill forms, and save the document. PDF documents
that have usage rights added are called rights-enabled documents. A user who opens a rights-enabled PDF
document in Adobe Reader can perform the operations that are enabled for that document.
Here is a list of the usage rights and the actions that users can perform in Adobe Reader when each usage
right is enabled:
Basic form fill-in: Users can fill in form fields and save files locally.
Note: Users of Adobe Reader 7 see a message directing them to fill in the form. This message is not
displayed in Adobe Reader 8.
Import and export form data: Users can import and export form data as FDF, XFDF, XML, and XDP
files. If you select this feature, Basic Form Fill-In is also automatically selected. When you select this
usage right, you must also enable the Database and Web Service Connectivity usage right or the
Embedded File Attachments usage right (depending on the usage rights required).
Submit outside web browser: Users can submit form data by email or offline. If you select this feature,
Basic Form Fill-In is also automatically selected.
Database and web service connectivity: Users can access the database or call the web service that is
defined within the form. If you select this feature, Basic Form Fill-In is also automatically selected.
Add, delete, and change form fields: Users can add, delete, or modify fields on the form. If you select
this feature, Basic Form Fill-In is also automatically selected.
Create pages from templates: Users can spawn pages from the form template for forms created in
Acrobat. Users create pages from template pages within the same form. (Available in XFA documents
but when selected, the usage right is not applied to the final saved document.) If you select this feature,
Basic Form Fill-In is also automatically selected.
2D barcode decoding: Users can use 2D barcodes with third-party scan decode solutions. If you select
this feature, Basic Form Fill-In is also automatically selected.
Digital signatures: Users can digitally sign and save the PDF document. If this option is not selected,
users can still validate, view, and print the document that has a digital signature.
Commenting: Users can create, edit, delete, import, and export comments. Comments are stored with
and transmitted with the entire file. If this option is not selected, users can only review comments in the
PDF document.
Online commenting: Users can upload or download document comments from a server. If you select
this feature, Commenting is also automatically selected.
Embedded file attachments: Users can add, remove, modify, or export file attachments and files in a
PDF package (formerly known as a PDF portfolio).
Methods for applying usage rights
●
Use the Adobe LiveCycle Reader Extensions ES (8.2) web application. (See LiveCycle
Reader Extensions ES Help.)
●
Use LiveCycle Workbench ES. (See LiveCycle Workbench ES Help.)
●
Use the Reader Extensions Service API. (See Programming with LiveCycle ES.)
Adobe LiveCycle ES
LiveCycle ES Services
Reader Extensions Service
Removing usage rights from PDF documents
98
Removing usage rights from PDF documents
You can use the Reader Extensions service to remove usage rights from a rights-enabled document.
Removing usage rights from a rights-enabled PDF document is also necessary to perform other
LiveCycle ES operations on it. For example, you must digitally sign (or certify) a PDF document before you
set usage rights. Therefore, to perform operations on a rights-enabled document, you must remove usage
rights from the PDF document, perform the other operations such as digitally signing the document, and
then reapply usage rights to the document.
Methods for removing usage rights
●
Use Workbench ES. (See LiveCycle Workbench ES Help.)
●
Use the Reader Extensions Service API. (See Programming with LiveCycle ES.)
Retrieving credential information
You can use the Reader Extensions service to retrieve information about the credential that was used to
apply usage rights to a rights-enabled PDF document. By retrieving information about a credential, you
can obtain information such as the date after which the certificate is no longer valid.
Methods for getting credential information rights
●
Use the Reader Extensions Service API. (See Programming with LiveCycle ES.)
Considerations for the Reader Extensions service
There are a number of factors to consider when developing an application that uses the Reader Extensions
service.
Configuring the credential
To apply usage rights to PDF documents, you must have a valid credential. A credential may have been
configured during the installation of LiveCycle ES. For information about configuring a credential, see
Administering LiveCycle ES or consult with your application server administrator.
Order of operations
If you are working with multiple services, it is important to perform service operations in the correct
sequence:
●
Apply encryption (Encryption service) or apply a policy (Rights Management service) to a document
before you digitally sign the document (Signature service). A digital signature records the state of the
file at the time of signing. Encrypting the document or applying a policy after you apply a signature
changes the bytes in the file, causing the signature to appear invalid.
●
Certify a PDF document (Signature service) before you set usage rights (Reader Extensions service). If
you certify a document after you apply usage rights, it invalidates the usage rights signature, thereby
removing the usage rights from the document.
●
Digitally sign a PDF document (Signature service) after you set usage rights. Signing a PDF document
after applying usage rights does not invalidate the usage rights signature.
Adobe LiveCycle ES
LiveCycle ES Services
Reader Extensions Service
Adding usage rights to interactive forms
99
In addition, you cannot encrypt a PDF document and apply a policy to the same PDF document. Likewise,
you cannot apply a policy to an encrypted PDF document.
Adding usage rights to interactive forms
Sometimes it is necessary to add usage rights to a PDF document while working with interactive forms
that are created in LiveCycle Designer ES. For example, assume that you create an interactive form by using
Designer ES and you want to use a form script to reference a data connection SOAP endpoint where form
data is retrieved. Next, assume that you want Adobe Reader 8.0 to display the form.
Without usage rights, Adobe Reader fails to set the data connection SOAP endpoint, resulting in the
predefined endpoint (set in Designer ES) being used. To set the data connection SOAP endpoint by using a
form script, you must add the enableFormsOnline usage right to the interactive form.
Adding usage rights to forms that populate fields with data
When designing a form for use with Adobe Reader 7.0 where the form uses web services or database calls
to populate fields with data, you must apply additional usage rights to your form.
When designing forms for use with Adobe Reader 8.0, apply the following usage rights:
●
Basic form fill-in
●
Database and web service connectivity
●
Add, delete, and change form fields
When designing forms for use with Adobe Reader 7.0, apply the following usage rights:
●
Basic form fill-in
●
Import and export form data
●
Database and web service connectivity
●
Add, delete, and change form fields
Without the “Import and export form data” usage right, calls made to web services or a database will fail in
Adobe Reader 7.0.
Opening rights-enabled PDF documents
Users who attempt to open a rights-enabled PDF document in versions of Adobe Reader earlier than 7.0
may not be able to access certain features. These versions of Adobe Reader display a message that
indicates that users should upgrade to the latest version. For example, if a user applies usage rights to an
Acrobat 5.0-compatible PDF document, the PDF document is no longer compatible with that version of
Acrobat (or Adobe Reader). The PDF document is compatible only with Adobe Reader 7.0 or later.
26
Repository Service
The repository provides storage capabilities. When developers create applications, they can deploy the
assets in the repository instead of on a file system. The assets may consist of XML forms, PDF forms
(including Acrobat forms), form fragments, images, processes, profiles, policies, SWF files, DDX files, XML
schemas, WSDL files, and test data.
The repository tracks the version of each asset in a LiveCycle ES application. At run time, services can
retrieve assets from the repository as part of completing an automated business process.
Using the Repository service
You can use this service in a process to retrieve resources from the repository. The Repository Service API
provides a number of additional operations that you can use to store and retrieve information from the
repository. For example, you can obtain a list of files or retrieve specific files stored in the repository when
a file is needed as part of processing an application. You can also programmatically deploy application files
using the Repository Service API.
For information about developing a process that uses this service, see LiveCycle Workbench ESS Help. For
information about developing a client application that programmatically interacts with this service, see
Programming with LiveCycle ES.
You can use the Applications and Services pages of LiveCycle Administration Console to configure default
properties for this service. (See Applications and Services Administration Help.)
100
27
Rights Management Service
The Rights Management service lets you create policies and apply those policies to documents. A policy is
a collection of information that includes confidentiality settings and a list of authorized users. You can
specify who can open a document, limit how they can use it, and monitor the document after it is
distributed. You can also dynamically control access to a document and can even dynamically revoke
access to the document.
The Rights Management service protects Adobe PDF files and other file types such as these:
●
FLV and F4V files for Adobe Flash
●
Microsoft Word, Excel, and PowerPoint files
●
Dassault CATIA files
●
Parametric Technology Corporation (PTC) Pro/ENGINEER Wildfire 4.0 files
Policies can be applied to PDF documents programatically, using the Rights Management Service API, or
as part of a process. Additionally, policies can be applied to documents using a client application. The
procedures for how to apply policies to PDF documents are described in detail in Acrobat Help. Applying
policies by using other applications, such as Microsoft Office, is documented in the Rights Management ES
Extension Help for the application. You can download the Rights Management ES Extension for
Microsoft Office from the Adobe website.
Administrators use the Rights Management ES web pages to do the following (see Rights Management
Administration Help):
●
Configure various Rights Management settings
●
Manage policy-protected documents
●
Create and manage policies and policy sets
●
Monitor events that Adobe Rights Management ES (8.2) records
●
Manage invited and local users
You can use LiveCycle Workbench ES to develop processes that do the following (see LiveCycle
Workbench ES Help):
●
Create policies from templates or update existing policies
●
Apply policies to documents, switch policies, or remove policy security
●
Get license identifiers, revoke licenses, or unrevoke licenses
●
Unlock policy-protected PDF documents
You can use the Rights Management Service API to develop client applications that do the following (see
Programming with LiveCycle ES):
●
Create, modify, or delete policies
●
Apply policies to or remove policies from PDF documents
●
Revoke or reinstate access to PDF documents
●
Create watermarks
●
Search for events
71
Adobe LiveCycle ES
LiveCycle ES Services
Rights Management Service
Creating policies
80
About policies
A policy contains information about authorized users and the confidentiality settings to apply to
documents. Users can be any user in your organization, as well as people who are external to your
organization who registered with Rights Management ES or for whom the administrator created an
account. If the administrator enables the user invitation feature, you can add new invited users to policies.
When you add a new invited user, the Rights Management service sends a registration email inviting the
user to register.
The confidentiality settings you specify in a policy determine how the recipients can use the document.
For example, you can specify whether recipients can print or copy text, make changes, or add signatures
and comments to protected documents. The same policy can also specify different confidentiality settings
for different users.
You can create and save any number of policies, using security settings appropriate for different situations
and users.
Rights Management ES lets you dynamically change the permissions on a document. It gives the person
who secures the document the permission to change the confidentiality settings to revoke access to the
document or to switch the policy. After distributing the document, the person who secured it can monitor
how the document is being used and who is using it.
Policies are described using Portable Document Rights Language (PDRL). (See the PDRL Specification.)
About policy sets
Policy sets are used to group a set of policies that have a common business purpose. Policy sets are
generally made available to a limited number of users by specifying which users or groups within a
domain can use the policies from the policy set to protect documents.
Each policy set can have one or more associated policy set coordinators. The policy set coordinator is an
administrator or a user who has additional permissions. The policy set coordinator is typically a specialist
in the organization, one who can best author the policies in a particular policy set. Depending on the
permissions assigned to the policy set coordinator, they may also be able to view events related to the
policy set, manage documents, and manage other policy set coordinators.
Policy sets are created and deleted in the LiveCycle Rights Management ES administration web pages by
policy set administrators who have permission to do so.
When Rights Management ES is installed, a default policy set is created called Global Policy Set. Policy set
administrators can administer this policy set.
Security methods and technology
This section describes the security methods and technology that Rights Management ES implements. To
ensure the confidentiality of documents that are protected by policies, Rights Management ES
implements three layers of security:
●
Authentication
●
Authorization
●
Document confidentiality
Adobe LiveCycle ES
Rights Management Service
LiveCycle ES Services
Creating policies
80
Authentication
All users are required to log in to interact with Rights Management ES. Users must log in before
performing the following tasks:
●
Opening the Rights Management ES web application in a web browser
●
Securing documents with policies in a supported client application
●
Opening policy-protected documents
When creating a policy, you can allow anonymous users to open policy-protected documents if that
setting is enabled in the Rights Management configuration settings. When you allow anonymous user
access, users who do not have accounts can access the document, but they cannot log in to
Rights Management ES or use other policy-protected documents.
Methods of authentication
Rights Management ES supports two methods of authentication:
Username/Password: Users are prompted for their user name and password.
Kerberos (Acrobat on Microsoft® Windows® only): Enables Acrobat or Adobe Reader users on a
Windows platform to be transparently authenticated.
Smart card (Acrobat on Microsoft Windows only): Enables Acrobat or Adobe Reader users on a
Windows platform to be authenticated using a smart card.
Note: Rights Management ES requires authentication over SSL connections.
Users can be internal or external to your organization. Internal users have corresponding user records in
your organizational user directory. Rights Management ES authenticates internal users against that user
directory. Rights Management ES stores the external user accounts in the database and uses the accounts
to authenticate external users. User accounts for LiveCycle ES administrators are also stored in the
database. For information about managing users, see User Management Help.
SAML authentication assertions
After users are initially authenticated and when Rights Management ES receives subsequent messages
from clients, Rights Management ES uses Security Assertion Markup Language (SAML) authentication
assertions to verify the identity of the message sender. SAML authentication assertions are used for
authentication until the assertion expires or users terminate their session.
When users are initially authenticated using their user name and password, Rights Management ES
generates a SAML authentication assertion. SAML authentication assertions are embedded in the SOAP
header and returned to the client.
Subsequent messages sent to Rights Management ES have the SAML assertion in the message header in
accordance with the WS-Security standard.
Note: Although SAML assertions are used internally to provide session management,
Rights Management ES does not support third-party SAML assertions.
Logging in through Acrobat and other client applications
When Rights Management ES authenticates a user through Acrobat or another client application such as
Microsoft Office, the server returns the SAML authentication assertion to the client application.
Adobe LiveCycle ES
Rights Management Service
LiveCycle ES Services
Creating policies
80
After logging in through the client application, a SAML assertion provides SSO for accessing the web
application. If the client application opens the web application, users are authenticated with the assertion
and are not prompted for their user name and password.
Role-based access control
Rights Management ES uses a role-based model to control access to the web application features. Roles
also determine whether users can protect documents with policies through a supported client
application. You associate users and groups with roles using the User Management web pages. The role
information is stored in the User Management database. For information about the roles used by
Rights Management ES, see “About LiveCycle Rights Management ES users” in Rights Management
Administration Help. For information about assigning roles, see “Managing Roles” in User Management
Help.
Document confidentiality
Rights Management ES uses several technologies to protect documents and to provide access to them. In
general, Rights Management ES uses a symmetric cryptographic key system for encryption. Client
applications such as Acrobat perform document encryption. Documents are never sent to
Rights Management ES when secured using client applications, but they are sent to the server when
secured using the Rights Management Service API.
The method used to protect documents depends on whether the policy requires users to access
documents while online or whether the policy enables offline use.
When you apply a policy to a PDF document, the information that the document contains, including any
files (text, audio, or video) that you save in the document, is protected by the confidentiality settings
specified in the policy.
Note: Document confidentiality settings that are applied through a policy replace any settings applied to
the PDF document in Acrobat by using the password or certificate security options. (See Acrobat
Help.)
Policy-protecting documents for online use
Policies can be designed so that users must be logged in to Rights Management ES to open protected
documents. Securing documents for online use employs a straighforward process for encrypting the
document and providing access only to authenticated and authorized users.
2
1
Service request
Secures document with
policy that allows
online use
Document license, encrypted policy, and document key
Adobe Acrobat
Other Applications
3
Uses document key to encrypt document
Discards document key
Embeds document license and policy
Creates document license
Creates document keys
Encrypts policy
Adobe LiveCycle
Rights Management ES
Adobe LiveCycle ES
Rights Management Service
LiveCycle ES Services
Creating policies
80
The steps in the diagram are as follows:
1. The document owner or administrator decides to secure the document from a supported client
application with a policy that allows online use. Users can apply policies to documents using any
supported client application. Developers can also protect documents with policies by using the
Rights Management service in a process or programmatically by using the Rights Management
Service API.
2. Rights Management ES creates a document license and document keys, and encrypts the policy. The
document license, document key, and encrypted policy are returned to the client application.
The document license is an XML document that identifies the protected document, the policy, and the
identity of the server. The server digitally signs the license to ensure data integrity.
The document key is a symmetric key for encrypting the document. Each protected document has an
associated document key.
3. The client application uses the document key to encrypt the document, discards the document key,
and embeds the document license and policy. These tasks are performed in a web page or supported
client application.
If the policy specifies that document events should be logged, as the user opens and uses the document,
the client software immediately sends event information to the server for logging. For information about
the audit log, see “Monitoring Events” in Rights Management Administration Help.
Accessing policy-protected documents online
To open and use policy-protected documents, the policy must grant the user access to the document. The
document user also needs a valid Rights Management ES account and the appropriate client application.
For PDF documents, the user needs Acrobat or Adobe Reader. For other file types, the user needs the
appropriate application for the file with the Rights Management ES extension installed.
When a user attempts to open a policy-protected document, Acrobat, Adobe Reader, or the
Rights Management ES Extension connects to Rights Management ES to authenticate the user. Then, the
user can proceed to log in. If the document usage is being audited, a notification message appears. After
Rights Management ES determines which document permissions to grant, it manages the decryption of
the document. The user can then use the document according to the policy confidentiality settings.
2
1
Opens document
Provides user name
and password
document ID
voucher (document key, permissions)
Adobe
Acrobat
Adobe
Reader
Adobe Reader
Other Applications
3
Decrypts document with document key
Discards document key
Uses document according to permissions
Authenticates user
Checks policy for authorization
Creates voucher
Adobe LiveCycle
Rights Management ES
Adobe LiveCycle ES
LiveCycle ES Services
Rights Management Service
Creating policies
80
The steps in the diagram are as follows:
1. The document user opens the document in a supported client application and authenticates with the
server. This task is performed in the supported client application. The document identifier is sent to the
Rights Management service.
2. The Rights Management service authenticates the users, checks the policy for authorization, and
creates a voucher. The voucher, which contains the document key and permissions, is returned to the
client application.
3. The document is decrypted with the document key, and the document key is discarded. The document
can then be used according to the confidentiality settings of the policy. These tasks are performed in
the supported client application.
If the policy specifies that document events should be logged, as the user opens and uses the document,
the client software immediately sends event information to the server for logging. For information about
the audit log, see “Monitoring Events” in Rights Management Administration Help.
If the user saves a copy of a policy-protected document by using the Save or Save As command, the policy
is automatically applied and enforced for the new document. Events such as attempts to open the new
document are also audited and recorded for the original document.
The user can continue to use a document with the following time limits:
●
Indefinitely or for the validity period specified in the policy
●
Until the administrator or the person who applied the policy revokes the right to open the document
or changes the policy
Policy-protecting documents for offline use
Policies can be designed so that users can open documents when they do not have a network connection
to Rights Management ES.
Note: Documents protected with policies that allow only online use are generally more secure than
documents protected with policies that allow offline use.
The first time that users access an offline document, they are prompted to enable offline access. Users are
not prompted again when opening any offline documents unless they open them from a different
computer.
When a user enables offline access, the LiveCycle ES server synchronizes data with the client that is needed
to open documents offline. This data includes cryptographic keys and relevant updates to policies,
licenses, revocation information, and so on. This data is stored in a protected client database, called a
MicroSafe. The MicroSafe itself is encrypted and is protected by using a platform-specific data protection
API, such as the DPAPI for Windows and KeyChain for Mac OS®.
Each time a user opens a protected document while online, a background synchronization process is
started to update the MicroSafe with any incremental information since the last synchronization occurred.
The offline lease period specified in the policy determines how recently the user must have synchronized
to open documents offline.
Adobe LiveCycle ES
Rights Management Service
LiveCycle ES Services
Creating policies
80
Security standards and technology
The following table provides details about the methods that Rights Management ES uses to implement
security.
Action
Technology or method used
Creating document keys
Pseudo Random Number Generator (PRNG) generated in
accordance with ANSI X9.61.
Creating Initialization Vectors (IV) for
AES-128 or 256-bit encryption in CBC
mode
The implementation used is the RSA BSafe Crypto-C (in Acrobat)
or Crypto-J (in Rights Management ES) toolkits.
Encrypting PDF documents
AES-128 (or AES 256 with Acrobat 9.0) in accordance with
Federal Information Processing Standards (FIPS) Publication
197.
Creating message digests
Secure Hash Algorithm-1 (SHA-1) and Secure Hash Algorithm-2
(SHA-2), in accordance with FIPS Pub 180-2.
Validating the identity of message
senders
SAML authentication assertions are bound to SOAP messages.
SAML assertions are hashed using SHA-1. An HMAC-SHA-1
message authentication code is used to sign the SAML
assertion.
Using the Rights Management service
You can accomplish the following tasks using this service:
●
“Creating policies” on page 107
●
“Modifying policies” on page 108
●
“Deleting policies” on page 109
●
“Applying policies to documents” on page 109
●
“Removing policies from documents” on page 109
●
“Switching the policy applied to a document” on page 110
●
“Revoking access to policy-protected documents” on page 110
●
“Monitoring events” on page 111
Creating policies
You can create any number of policies, using security settings appropriate for different situations and
users.
Policy attributes
When creating a new policy, you set various policy attributes, such as the policy name. If you are using the
LiveCycle ES SDK or the Rights Management ES web pages to create the policy, you can also set a validity
period for the policy. A validity period is the time period during which a policy-protected document is
accessible to authorized recipients. If you do not set this attribute, the policy is always valid.
Adobe LiveCycle ES
Rights Management Service
LiveCycle ES Services
Creating policies
80
A validity period can be set to one of these options:
●
A set number of days that the document is accessible from the time that the document is published
●
An end date after which the document is not accessible
●
A specific date range for which the document is accessible
●
Always valid
You can specify just a start date, which results in the policy being valid after the start date. If you specify
just an end date, the policy is valid until the end date.
You can also create a policy that applies a watermark to PDF documents. Watermarks help ensure the
security of a PDF document by uniquely identifying the document and controlling copyright
infringement. For example, you can create and place a watermark that states Confidential on all pages of a
PDF document. After a watermark is created, you can include it as part of a policy. That is, you can set the
policy’s watermark attribute using the newly created watermark. After a policy that contains a watermark
is applied to a PDF document, the watermark appears in the policy-protected document.
Policy entry
A policy entry attaches principals, which are groups and users, and permissions to a policy. A policy must
have at least one policy entry. Assume, for example, that you perform these tasks:
●
Create a policy entry that enables a group to view a document only while online and prohibits
recipients from copying it.
●
Attach the policy entry to the policy.
●
Secure a document using the policy.
These actions result in recipients being able to view the document only online and not being able to copy
it. The document remains secure until security is removed from it.
Methods for creating policies
●
Users and administrators can use the Rights Management ES web pages. (See Rights Management
Administration Help.)
●
Use Workbench ES to create a policy from an existing template. When you create a policy in
Workbench, there are fewer properties to configure. (See LiveCycle Workbench ES Help.)
●
Use the Rights Management Service API. (See Programming with LiveCycle ES.)
Modifying policies
You can modify a policy when business requirements change and the policy no longer reflects these
requirements. Instead of creating a new policy, you can simply update an existing policy.
To modify a policy, you modify the value of policy attributes. The only policy attributes that you cannot
change are the name attribute and the attributes in the Unchangeable Advanced Settings section. For
example, to change the policy’s offline lease period, you can modify the value of the policy’s offline lease
period attribute. In Workbench, you also cannot modify the validity time.
Before the changes that you make to a policy take effect, you must update the policy using the
Rights Management service. Changes to policies that are protecting documents are updated the next time
that the policy-protected document is synchronized with the Rights Management service.
Adobe LiveCycle ES
Rights Management Service
LiveCycle ES Services
Creating policies
80
Methods for modifying policies
●
Users and administrators can use the Rights Management ES web pages. (See Rights Management
Administration Help.)
●
Use Workbench ES. (See LiveCycle Workbench ES Help.)
●
Use the Rights Management Service API. (See Programming with LiveCycle ES.)
Deleting policies
You can delete an existing policy when it is no longer required. After a policy is deleted, it can no longer be
used to protect documents. However, existing policy-protected documents that are using the policy are
still protected.
To delete a policy, you specify the policy to delete and the policy set to which the policy belongs. The user
whose settings are used to invoke LiveCycle ES must have permission to delete the policy; otherwise, an
exception occurs. Likewise, if you attempt to delete a policy that does not exist, an exception occurs.
Methods for deleting policies
●
Users and administrators can use the Rights Management ES web pages. (See Rights Management
Administration Help.)
●
Use the Rights Management Service API. (See Programming with LiveCycle ES.)
Applying policies to documents
You can apply a policy to a document to secure the document. By applying a policy to a document, you
restrict access to the document and apply confidentiality settings to it.
To apply a policy to a PDF document using the LiveCycle ES SDK, you must reference an existing policy and
specify which policy set the policy belongs to. The user account used to connect to Rights Management ES
requires access to the policy; otherwise, an exception occurs.
Only one policy at a time can be applied to a document.
Methods for applying policies
●
Users and administrators can use the Rights Management ES web pages. (See Rights Management
Administration Help.)
●
Use Workbench ES. (See LiveCycle Workbench ES Help.)
●
Use the Rights Management Service API. (See Programming with LiveCycle ES.)
Removing policies from documents
You can remove a policy from a policy-protected document to remove security from the document. If you
want to update a policy-protected document with a newer policy, instead of removing the policy and
adding the updated policy, it is more efficient to switch the policy.
Methods for removing policies
●
Users and administrators can use the Rights Management ES web pages. (See Rights Management
Administration Help.)
●
Use Workbench ES. (See LiveCycle Workbench ES Help.)
Adobe LiveCycle ES
Rights Management Service
LiveCycle ES Services
●
Creating policies
80
Use the Rights Management Service API. (See Programming with LiveCycle ES.)
Switching the policy applied to a document
If you want to update a policy-protected document using a newer policy, instead of removing the policy
and adding the updated policy, it is more efficient to switch the policy.
When you switch a policy, the new policy is enforced as follows:
●
If the document is online and closed, the change takes effect the next time the recipient synchronizes
with Rights Management ES by opening any policy-protected document online.
●
If the document is online and open, the change takes effect when the user closes the document.
●
If the document is offline (in use without an active Internet or network connection, such as on a
laptop), the change is applied the next time the user synchronizes with Rights Management ES by
opening a policy-protected document online.
Note: To permit anonymous access to a policy-protected document that currently does not have this
access, remove the existing policy in the client application and then apply a policy that permits
anonymous access. If you switch the policy, users still must log in to access the document.
Methods for switching policies
●
Users and administrators can use the Rights Management ES web pages. (See Rights Management
Administration Help.)
●
Use Workbench ES. (See LiveCycle Workbench ES Help.)
●
Use the Rights Management Service API. (See Programming with LiveCycle ES.)
Revoking access to policy-protected documents
You can revoke access to a policy-protected document. This results in all copies of the document being
inaccessible to users. When a user attempts to open a revoked document, they can be redirected to a
specified URL where a revised document can be viewed. When you revoke access to a document, the
change takes effect the next time the user synchronizes with the Rights Management service by opening
the policy-protected document online.
The ability to revoke access to a document provides additional security. For example, assume a newer
version of a document is available and you no longer want anyone viewing the outdated version. In this
situation, access to the older document can be revoked, and nobody can view the document unless access
is reinstated.
Reinstating access to documents
You can reinstate (unrevoke) access to a revoked document, resulting in all copies of the revoked
document being accessible to users.
Methods for revoking access to documents
●
Users and administrators can use the Rights Management ES web pages. (See Rights Management
Administration Help.)
●
Use Workbench ES. (See LiveCycle Workbench ES Help.)
●
Use the Rights Management Service API. (See Programming with LiveCycle ES.)
Adobe LiveCycle ES
Rights Management Service
LiveCycle ES Services
Creating policies
80
Monitoring events
When the auditing capability is enabled and the policy used to protect a document has auditing enabled,
the Rights Management service tracks specific actions related to the policy-protected document as they
occur. Events include activities such as applying a policy to a document or opening a policy-protected
document.
Events fall into one of the following categories:
●
Administrator events are actions related to an administrator, such as creating a new administrator
account.
●
Document events are actions related to a document, such as closing a policy-protected document.
●
Policy events are actions related to a policy, such as creating a new policy.
●
Service events are actions related to the Rights Management service, such as synchronizing with the
user directory.
You can use the Rights Management Service API to search for specific events. You can also use the
Rights Management ES web pages to search and view audited events. Users can view audited events for
their policy-protected documents and for any protected documents that they receive and use.
Administrators can view audited events that are related to all policy-protected documents and users.
Administrators can also track other types of events, including user, document, policy, and system events.
Events that are performed on a copy of a policy-protected document are also tracked as events with the
original protected document.
A failed event is recorded if an unauthorized user attempts to view a document or attempts to log in using
an incorrect user name or password.
If a policy allows anonymous user access but the administrator later turns off anonymous access for
Rights Management ES, anonymous access will fail for documents protected with the policy and the event
will not be logged.
Methods for monitoring events
●
Users and administrators can use the Rights Management ES web pages. (See Rights Management
Administration Help.)
●
Use the Rights Management Service API. (See Programming with LiveCycle ES.)
28
Set Value Service
The Set Value service sets the value of one or more data items in the process data model. For example, you
can set the value of a process variable, or you can set the value of a form field.
Using the Set Value service
You can interact with the Set Value service by developing a process in LiveCycle Workbench ES that uses
the service.
You can use XPath expressions to specify the data item and the value to set it to. For every data item that
you want to set the value of, you create a mapping. Variable data is persisted and available through the
entire process. For information about XPath, see the XMP Path Language (XPath) specification.
For information about developing processes that use this service, see LiveCycle Workbench ES Help.
112
29
Signature Service
The Signature service enables you to work with digital signatures and documents on the LiveCycle ES
server using processes created in LiveCycle Workbench ES, or using Java or web service clients created
using the LiveCycle ES SDK. For example, the Signature service is typically used in the following situations:
●
The LiveCycle ES server certifies a form before it is sent to a user to open using Acrobat or
Adobe Reader.
●
The LiveCycle ES server validates a signature that was added to a form using Acrobat or Adobe Reader.
●
The LiveCycle ES server signs a form on behalf of a public notary.
The Signature service accesses certificates and credentials that are stored in the trust store. For information
about managing certificates and credentials, see Trust Store Management Help.
This section includes the following topics that provide background information about digital signatures
and the Signature service:
●
“About digital signatures” on page 113
●
“About signature fields” on page 114
●
“About the Signature service and form types” on page 114
●
“About digital signature technology” on page 115
●
“Integrating with a security infrastructure” on page 117
●
“Supported technologies and standards” on page 117
The following topics provide information about the tasks that you can perform and how to achieve the
best results:
●
“Using the Signature service” on page 118
●
“Best practices” on page 120
●
“Order of operations” on page 122
About digital signatures
Digital signatures are blocks of information that are added to electronic documents for authenticating the
identity of the signer and verifying the integrity of the document or part of the document:
●
Signatures contain information that enables you to determine the owner of the signature. This
information is useful for verifying the identity of the originator of the document.
●
When a document is digitally signed, the signature can be used to determine whether the document
has changed since it was signed.
Credentials are used to create digital signatures. Certificates are used to validate digital signatures and
their owners.
Digital signatures and the Signature service
The Signature service supports PDF signatures and XML signatures:
113
Adobe LiveCycle ES
LiveCycle ES Services
Signature Service
About signature fields
114
●
PDF signatures can be created for all PDF documents, such as PDF documents created using
LiveCycle Designer ES or Acrobat.
●
XML signatures can be created only for XFA-based PDF documents, such as PDF documents that are
created using Designer ES, or that the Forms service created.
PDF signatures can be used for purposes beyond the basic authentication of signer’s identity and
validating document integrity:
Approval Signatures: Used for approving document content. For example, a user fills a form and then
signs the form to approve the form data.
Certifying signatures: Used for attesting to the document contents and specifying the types of
changes that are permitted for the document to remain certified. For example, a government agency
creates a form with signature fields. The agency certifies the document, allowing users to change only
form fields and sign the document. Users can fill in the form and sign the document, but if they remove
pages or add comments, the document does not retain its certified status.
Certifying signatures are also known as Modify Detection Prevention (MDP) signatures.
About signature fields
When a form is digitally signed, the signature is added to a signature field. Forms must include a signature
field before they can be signed.
Multiple signature fields can be added to a single form. Each signature field can be associated with a set of
fields on the form so that the signature that is added to that field applies only to the associated fields. After
adding the signature, the associated fields are locked. These types of signatures are known as MDP+
signatures. To use this feature with Adobe PDF forms and Adobe XML forms, users must use Acrobat or
Adobe Reader version 8.0 and above to open the forms.
Seed value dictionaries can be added to signature fields to configure how the field is used when the
document is signed. For example, a list of signing reasons can be provided, or the hashing algorithms that
can be used for creating the document digest can be specified.
You can add signature fields at design time or at run time:
●
Use Designer ES to add signature fields at design time. (See LiveCycle Designer ES Help.)
●
Use the Signature service to add signature fields at run time. (See “Adding, modifying, and removing
signature fields” on page 120.)
About the Signature service and form types
LiveCycle ES supports several types of PDF forms. Although Acrobat or Adobe Reader users notice no
apparent difference between the form types, the way in which the PDF form is constructed can be
different. For example, forms can be rendered to PDF by the Forms service on the LiveCycle ES server or by
Acrobat or Adobe Reader.
PDF forms that do not require rendering can be used with the Signature service in any situation. However,
PDF forms that require rendering can be problematic for digital signatures, depending on how they are
used.
When a PDF form that is digitally signed is rendered, the signature on the form is invalidated. For example,
a user opens a dynamic Adobe PDF form in Acrobat, digitally signs it, and saves and sends the file to a
Adobe LiveCycle ES
Signature Service
LiveCycle ES Services
About digital signature technology
115
colleague in an email message. When the colleague opens the form, Acrobat renders the form to PDF,
which invalidates the digital signature.
Before you use the Signature service, you must be aware of the type of form you are using.
Acrobat PDF form: PDF forms that are created using Acrobat (or a similar tool). These forms do not
require rendering after they are created.
Adobe PDF form: PDF forms that are created using Designer ES. These files are saved as static or
dynamic PDF forms:
●
The content of static PDF forms, except for field values, does not change. When the file is opened,
Acrobat or Adobe Reader use information in the file to render the PDF form. When the file is saved
for the first time, the PDF form is stored in the file and rendering is no longer required when it is
subsequently opened.
●
The content of dynamic PDF forms can change according to user input. For example, table rows or
subforms can be added as required. The PDF form is always rendered when it is opened using
Acrobat or Adobe Reader.
For more information about the static and dynamic Adobe PDF forms, see Understanding the
Differences Between Static and Dynamic PDF Forms.
Adobe XML form: XDP files that are created using Designer ES. Adobe XML forms are prepared for
opening in Acrobat or Adobe Reader using the Forms service. The Forms service can be configured so
that the PDF form is rendered by the Forms service on the LiveCycle ES server before being sent to the
client, or by Acrobat or Adobe Reader.
Non-interactive PDF forms: PDF files that users can view electronically or print. For example, files that
are converted to PDF from a different file format are non-interactive. These forms do not require
rendering after they are created.
For information about design requirements for forms that are used in LiveCycle Workspace ES, see
“Requirements for form design and Workspace ES” on page 122.
About digital signature technology
This section provides a brief overview of the technology used with digital signatures.
Public key cryptography
Digital signatures are based on public-key cryptography (or asymmetric cryptography), which involves
using public/private key pairs for encrypting and decrypting text:
●
The private key is used to encrypt text and documents. Private keys are kept safe.
●
The corresponding public key is used to decrypt the text that is encrypted by the private key. The
public key can decrypt only the text that is encrypted with the associated private key. Public keys are
distributed, sometimes widely.
For example, Tony Blue uses his private key to encrypt email messages before sending them to recipients.
The recipients require the public key to decrypt the messages and read them. Tony must provide the
recipients with the public key before they can read his email messages.
Adobe LiveCycle ES
LiveCycle ES Services
Signature Service
About digital signature technology
116
Digital certificates
Digital certificates can be used to verify the authenticity of digital signatures. Digital certificates bind a
public key with a person’s identity:
●
Certificates can be issued by certificate authorities (CA), a trusted third party. CAs verify the identities of
the people who they issue certificates. If you trust the CA, you trust the certificates they issue.
●
Certificates can also be self-signed. Self-signed certificates are typically generated by the certificate
owner and are useful when you are certain that you can trust the owner.
CAs publish certificate revocation lists (CRL) that contain the serial numbers of the certificates that are no
longer valid. CRLs have expiry dates, and are typically updated periodically.
Similar to using CRLs, Online Certificate Status Protocol (OCSP) is used for obtaining the status of X.509
certificates. OCSP enables certificate status to be updated and obtained more quickly than CRL systems.
CAs can delegate the authority to issue certificates to lower-level CAs. The result can be a hierarchy of CAs.
A certificate chain indicates the path in the hierarchy from a lower-level CA to the root CA. Certificates that
are issued by lower-level CAs include the certificate chain. The authenticity of each CA in the chain can be
verified.
Digital credentials
Credentials are used to digitally sign documents. A credential contains a user’s private key and other
identifying information, such as an alias. A password is required to access the contents of the credential.
Different standards define the content of a credential and the format. The following standards are two
examples:
●
Personal Information Exchange Syntax Standard (PKCS #12) defines a file format for storing the private
key and the corresponding digital certificate.
●
Cryptographic Token Interface (PKCS #11) defines an interface for retrieving credentials that are stored
in hardware.
Digital Signatures
Digital signatures are an encrypted digest of the document that is signed. The digest and the signer’s
certificate are used to validate the integrity of the document.
When a document is digitally signed, a digest of the document contents is created using a hashing
algorithm. The digest is unique for the document, and the document cannot be reconstructed using the
digest. The digest is encrypted using the signer’s private key to create the signature.
The signature and the certificate that corresponds with the private key used to create the signature are
typically bundled with the document.
Signatures can include time stamps. Time Stamp Protocol (TSP) is used to establish the time at which a
digital signature is created. This information is useful for verifying that a digital signature was created
before the associated certificate was revoked. A Time Stamp Authority (TSA) provides services for
obtaining and verifying time stamp information.
Validating document integrity
To validate the signature, the public key in the certificate is used to decrypt the digest. The digest is then
recalculated and compared with the decrypted digest. If the digests are identical, the document has not
been altered.
Adobe LiveCycle ES
Signature Service
LiveCycle ES Services
Integrating with a security infrastructure
117
Integrating with a security infrastructure
The Signature service accesses certificates, credentials, and revocation lists that are stored in Trust Store
Management. It can also use Trust Store Management to access credentials that are stored in Hardware
Security Module (HSM) devices. (See Trust Store Management Help.)
The Signature service also supports communicating with external resources for retrieving certificates and
validating signatures:
●
LDAP/LDAPs and HTTP/HTTPs queries for retrieving certificates for chain validation
●
Connecting to TSAs using HTTP and HTTPs
●
Retrieving CRLs using HTTP/HTTPs and LDAP/LDAPs. The Signature service also supports offline CRLs
that are stored using Trust Store Management.
●
Connecting to OCSP servers
●
Integrating with external service providers for retrieving credentials and verifying certificates
Supported technologies and standards
The following table provides a summary of the technologies and industry standards that are supported by
LiveCycle Digital Signatures ES:
Item
Supported technology or standard
One-way hash (for creating
document digests)
SHA-1, SHA-256, SHA-384, and SHA-512
MD5
RIPEMD160
Digital signatures
PKCS #1 and #7
RSA (up to 4096 bit)
DSA (up to 4096 bit)
XML signatures
Seed values (enforcement of certificate usage criteria)
Time stamping (using Time Stamp Providers)
Certificate validity
Certificate Revocation Lists (CRL)
Online Certificate Status Protocol (OCSP)
RFC 3280 compliant path validation
The Signature service enforces Federal Information Processing Standard (FIPS) compliance, and uses the
RSA BSAFE libraries.
Adobe LiveCycle ES
Signature Service
LiveCycle ES Services
Using the Signature service
118
Using the Signature service
This section includes the following topics that describe how you can use the Signature service:
●
“Signing and certifying documents” on page 118
●
“Validating document integrity and authenticity” on page 119
●
“Removing signatures” on page 119
●
“Retrieving signatures and signature fields” on page 120
●
“Adding, modifying, and removing signature fields” on page 120
For information about developing processes that use this service, see LiveCycle Workbench ES Help. For
information about developing client applications that programmatically interact with this service, see
Programming with LiveCycle ES.
You can use the Applications and Services pages of LiveCycle Administration Console to configure default
properties for this service. (See Applications and Services Administration Help.)
Signing and certifying documents
You can use the Signature service to sign and certify PDF documents using any credential that the service
can access. When signing or certifying, you specify the signature field to use.
Caution: The following limitations apply to dynamic Adobe PDF forms when used with the Signature
service:
●
You cannot sign a visible signature field.
●
You can certify invisible signature fields.
●
You can certify visible signature fields only if the Signature service is configured to process
documents with Acrobat version 9 compatibility. The form can only be viewed using Acrobat
or Adobe Reader version 9.
Note: For all types of forms, Acrobat or Adobe Reader users can delete signatures that the Signature
service added.
When signing or certifying, the following information can be specified:
Credential: The credential that contains the private key to use to create the digital signature.
Document MDP permissions: When certifying, the changes that users can perform on the document
without invalidating the certification.
Revocation information: Whether to embed revocation information in the signature to use for
validating the signer’s certificate. The information enables OCSP checking and CRL checking.
Time stamp information: Whether to create a time stamp for the signature, and the information
required to perform the time stamp transaction with the time stamp provider.
Appearance: Properties that affect the appearance of the signature when it is viewed using Acrobat or
Adobe Reader, such as the reason for signing, the contact information of the signer, a legal attestation,
and the icons to use.
Adobe LiveCycle ES
Signature Service
LiveCycle ES Services
Validating document integrity and authenticity
119
Validating document integrity and authenticity
You can use the Signature service to validate signatures that have been added to PDF forms. To validate
signatures, the certificate can be checked for revocation, the time stamp of the signature can be checked,
and the document digest is verified.
Caution: The following limitations apply to validating digital signatures using the Signature service:
●
The Signature service cannot accurately validate signatures on dynamic Adobe PDF forms.
●
The Signature service cannot ensure that field-locking rules for signature fields (MDP+ rules)
are enforced for Adobe PDF forms and Adobe XML forms.
When validating, the following information can be specified:
Signature field: The name of the signature field that holds the signature to verify.
Revocation checking: Whether to check that the signer’s certificate has been revoked. You can specify
information to enable OCSP and CRL types of checking.
Time stamp checking: How to verify the time stamp of the signature.
Path validation: Information that enables the verification of the certificates in the certificate chain that
the signer’s certificate includes.
The following table describes the situations that cause the different signature validity states.
Value
Signature status
Invalid
Signature Invalid
The revision of the document that is covered by the signature has been altered.
Unknown
Status Unknown
Signature validation on the signed contents was not performed.
ValidAndModified
Signature valid but document modified
The revision of the document that is covered by the signature was not modified,
but there were subsequent changes to the document.
ValidUnmodified
Signature valid and document unmodified
The revision of the document that is covered by the signature was not modified.
There were no subsequent changes to the document.
When validating signatures, you need to know whether you are validating a PDF signature or an XML
signature.
Removing signatures
You can use the Signature service to remove signatures from signature fields.
Adobe LiveCycle ES
LiveCycle ES Services
Signature Service
Retrieving signatures and signature fields
120
Retrieving signatures and signature fields
You can use the Signature service to retrieve the following items from forms:
●
Information about signature fields and certifying signature fields
●
Digital signatures and information about the signatures
●
The revision of the PDF form as it existed when a signature field was signed
Caution: You cannot retrieve the certifying signature field from forms that are rendered on the client.
Adding, modifying, and removing signature fields
You can use the Signature service to add, modify, and remove visible and invisible signature fields from
forms. When you add and modify signature fields, you can configure the following properties:
●
The field name and, for visible signature fields, the location.
●
The fields to lock when the signature is added.
●
The signature handler that validates signatures.
●
Information about the signature, such as whether to include revocation information, a list of signing
reasons that users can select from, and server URLs used for validating signatures.
●
Whether the field can be used only for certifying the document.
Caution: The Signature service cannot add or modify signature fields on a dynamic Adobe PDF form.
Best practices
The following characteristics of LiveCycle ES and the Signature service result in limitations to the way you
can use dynamic Adobe PDF forms:
●
Digital signatures are invalidated when a signed form is rendered to PDF.
●
The Signature service cannot detect changes that are made to forms through JavaScript.
●
The Signature service cannot enforce field-locking (MDP+) signature rules, or detect that field-locking
signature rules have been violated for Adobe PDF forms and Adobe XML forms.
Generally, you need to decide whether the use of dynamic forms or the use of digital signatures on the
server is more important for your solution:
●
If you need to use features of the Signature service that do not support dynamic Adobe PDF forms, use
a different type of form, and ensure that no rendering occurs in Acrobat or Adobe Reader. (See
“Ensuring that no rendering occurs after signing” on page 121.)
●
If you need to use dynamic forms, you can convert the form to a non-interactive form before using the
features of the Signature service on the form. (See “Converting to non-interactive form” on page 121.)
●
Before you use the form with the Signature service, you should ensure that the form is not a dynamic
Adobe PDF form. (See “Checking the form type” on page 122.)
Also, to use digital signatures on forms that users open in Workspace ES, your form needs to conform to
specific design criteria. (See XREF).
Adobe LiveCycle ES
LiveCycle ES Services
Signature Service
Ensuring that no rendering occurs after signing
121
Ensuring that no rendering occurs after signing
When a form is rendered to PDF, any digital signatures that it contains are invalidated. You need to ensure
that PDF forms are not rendered after they are digitally signed. You can prevent rendering when you use
static Adobe PDF forms or Adobe XML Forms.
Static Adobe PDF forms
Use Designer ES to create static Adobe PDF forms, so that rendering occurs only the first time they are
opened in Acrobat or Adobe Reader.
If you are using the Forms service to merge data with the form, prevent the service from converting the
form to a dynamic form. Use Designer ES to configure the following form properties:
Target Version: Specify Acrobat And Adobe Reader 8.0 or Later
PDF Render Format: Specify Static PDF Form
For information about setting form properties, see LiveCycle Designer ES Help.
If you are using the form with the User service in a process, use a Document Form variable to store the
form data and the form data. Configure the Document Form variable so that the render service is called
only once. (See LiveCycle Workbench ES Help.)
Adobe XML Forms
Adobe XML forms (XDP files) can be rendered to PDF by using the Forms service. To use the Signature
service with Adobe XML forms, the Forms service must be configured so that rendering occurs on the
server, and not on the client. When rendering occurs on the server, the rendered PDF form is embedded in
the XDP file and is not rendered again.
Converting to non-interactive form
To use dynamic Adobe PDF forms as well as the Signature service, you need to convert the forms to
non-interactive PDF forms.
This scenario typically involves the use of dynamic Adobe PDF forms for gathering data. After the
data-gathering activities are complete, the form is converted to a non-interactive PDF form that is used
with the Signature service:
●
Signature fields are added to the non-interactive form.
●
The Signature service can add a signature to the form.
●
The form can be sent to users to digitally sign, and then the Signature service can validate the
signatures.
You cannot display non-interactive forms to users in Workspace ES. However, you can attach
non-interactive forms to the Workspace ES tasks using the User service. You can also distribute the
forms using email messages.
Use the Output service to convert dynamic forms to non-interactive PDF forms.
Note: When forms that contain digital signatures are converted to non-interactive PDF forms, the digital
signatures are not preserved. Only the appearance of the digital signatures is preserved.
Adobe LiveCycle ES
LiveCycle ES Services
Signature Service
Checking the form type
122
Checking the form type
Before using the Signature service on a form, you can ensure that the form is not a dynamic Adobe PDF
form. The PDF Utilities service enables you to retrieve the properties of a PDF document. The results
include the form type, which must not equal the value Dynamic-XFA.
Requirements for form design and Workspace ES
If you are using digital signatures on a PDF form that users open in Workspace ES, you need to add an
invisible submit button to the form instead of the Process Fields object. The invisible submit button
ensures that digital signatures on the form remain valid when the form is submitted using Workspace ES.
When the Process Objects object is included on a form, the LiveCycle ES server changes the appearance of
the submit button that the object provides. Any digital signatures that have been added before the form is
submitted indicate that a change has occurred. A yellow triangle alerts the user to the change.
Tip: A submit button is a Button object with the Control Type property set to Submit. You do not have to
specify a target URL. After you add the submit button, change the Presence property to Invisible.
Use Designer ES to add invisible submit buttons at design time. (See LiveCycle Designer ES Help.)
Order of operations
If you are working with multiple services, it is important to perform service operations in the correct
sequence:
●
Apply encryption (Encryption service) or apply a policy (Rights Management service) to a document
before digitally signing the document. Encrypting the document or applying a policy after you apply a
signature changes the bytes in the file, causing the signature to appear invalid.
●
Certify a PDF document before you set usage rights (Reader Extensions service). If you certify a
document after you apply usage rights, it could invalidate the usage rights signature and remove the
usage rights from the document.
●
Digitally sign a PDF document after you set usage rights. Signing a PDF document after applying usage
rights will not invalidate the usage rights signature.
30
Stall Service
The Stall service is useful for preventing situational errors that you anticipate may occur. This service
provides the capability to stall the branch to which it belongs.
For example, processes can use data that is provided from an external resource, such as a partner's
database. An Execute Script action can be used to verify that the data is valid. If the data is not valid, a Stall
action can be executed that stalls the process instance while the data in the database is corrected.
Using the Stall service
You can interact with the Stall service by developing a process in LiveCycle Workbench ES that uses the
service.
If you are aware of a possible situational error in your process, you can add a route that leads to the Stall
service. You add a condition to the route that checks whether the situational error has occurred. When the
situation occurs, the branch is stalled so that you can fix the error and restart the process using LiveCycle
Administration Console.
Note: When used in transactional branches or short-lived processes, the execute operation throws an
exception instead of stalling the branch.
For information about developing processes that use this service, see LiveCycle Workbench ES Help.
123
31
User Service
The User service enables processes to create and assign tasks to LiveCycle Workspace ES users, or to send
tasks to users in email messages. You can also assign tasks programmatically by using the Task Manager
Service API. After a task is created, you can interact with the task by using processes, the Task Manager
Service API, and LiveCycle Administration Console.
This section includes the following topics:
●
“Using the User service” on page 124
●
“Interacting with tasks” on page 126
Using the User service
The User service provides the Assign Task operation that processes use to create tasks and assign them to
users either in Workspace ES or by using email. The Assign Task operation also enables you to configure
task features that are exposed to Workspace ES users:
●
“Assigning tasks” on page 124
●
“Configuring task features” on page 125
●
“Configuring email notifications” on page 125
●
“Saving information about completed tasks” on page 126
Assigning tasks
Assign tasks to users or groups to add the task to their To Do list in Workspace ES. You can assign tasks to
any user or group that exists in User Management:
●
You can assign a task to the same user or group for every instance of the process that is created. This
strategy can simplify testing during development. For example, if you assign all tasks to the same
person, you need to log on to Workspace ES only once to verify task creation.
●
You can assign tasks to a user or group identification that is stored in a process variable. This method is
more realistic for production environments because the user or group can change, depending on the
process instance. Prior to assigning the task, the user or group identification is obtained and stored.
Methods for assigning tasks
●
Use LiveCycle Workbench ES. (See LiveCycle Workbench ES Help.)
●
Use the Task Manager Service APIs. (See Programming with LiveCycle ES.)
124
Adobe LiveCycle ES
LiveCycle ES Services
User Service
Configuring task features
125
Configuring task features
When you create tasks, you can configure features that affect the user experience:
Forms and form data: Specify which form is presented to Workspace ES users and what form data to
include in the form. Also specify where to save the form data that is submitted when the task is
complete.
Instructions: Provide instructions to Workspace ES users that describe how to complete the task.
Task delegation and consultation: Specify whether users can delegate tasks to other users or consult
with other users about tasks.
Attachments and notes: Specify whether users can add file attachments and notes to tasks. You can
also add file attachments to tasks if they are relevant to the work that needs to be performed.
Reminders, deadlines, and escalations: Configure these mechanisms to ensure that the process
progresses within time constraints.
Methods for configuring task features
●
Use Workbench ES. (See LiveCycle Workbench ES Help.)
Configuring email notifications
Notification emails can be sent to Workspace ES users when the following events occur:
●
Users are assigned a task.
●
A reminder or deadline occurs for a task that they own.
●
An escalation occurs for a task that they own.
You can configure the message subject and body. The text can include parameters for task properties that
are updated at run time. Parameters enable messages to include data that changes for each task, such as
the task identification.
Default email messages can be authored by using LiveCycle Administration Console. The default messages
apply to all tasks that are created for all processes. You can configure the Assign Task operation by using
Workbench ES to override the default messages for a task, or disable notifications for the task.
Tip: Messages that are configured using Workbench ES can also include XPath expressions so that you can
include any text-based process data in the message.
Methods for configuring email notifications
●
Use the Adobe Process Management ES (8.2) pages in LiveCycle Administration Console. (See Process
Management Administration Help.)
●
Use Workbench ES. (See LiveCycle Workbench ES Help.)
Adobe LiveCycle ES
LiveCycle ES Services
User Service
Saving information about completed tasks
126
Saving information about completed tasks
When a task is complete, you can save information about the task. Configure the Assign Task operation to
store the following information in process variables:
Task identification: The unique identification of the task that was created.
User identification: The unique identification of the user who completed the task.
This information can be used later in the process if necessary. For example, you can save the user
identification to assign subsequent tasks in the process to the same user.
Methods for saving task information
●
Use Workbench ES. (See LiveCycle Workbench ES Help.)
Interacting with tasks
This section describes how to interact with tasks after they are created. Workbench ES, LiveCycle
Administration Console, and LiveCycle ES SDK provide tools for interacting with tasks:
●
“Reacting to task events” on page 126
●
“Retrieving task information” on page 126
●
“Intervening in task status” on page 127
Note: For information about how to interact with tasks by using Workspace ES, see LiveCycle Workspace ES
Help.
Reacting to task events
Process Management ES provides several asynchronous event types for use in processes. You can add
event receives or start points to your processes to react to events when they occur.
More than 20 event types are defined for task state changes, such as when a task is completed, or for other
changes such as when a file is attached to the task. For example, the TaskDeadlined event type is thrown
when a deadline occurs for a task. If a process uses the TaskDeadlined event as the start point, the process
can be invoked when the event is thrown.
Methods for reacting to events
●
Use Workbench ES. (See LiveCycle Workbench ES Help.)
Retrieving task information
You can retrieve tasks that are assigned to specific users and then retrieve information about the task, such
as the task identification, status, and the name of the process that it belongs to. You can also retrieve a
history of the task.
Methods for retrieving task information
●
Use the Process Management ES pages in LiveCycle Administration Console. (See Process Management
Administration Help.)
●
Use the Task Manager Service API. (See Programming with LiveCycle ES.)
Adobe LiveCycle ES
LiveCycle ES Services
User Service
Intervening in task status
127
Intervening in task status
You can intervene in the normal progression of a process to correct problems that unpredictable
circumstances cause:
●
Assign tasks to various users as required. For example, you can reassign a task that is assigned to a user
who has changed roles in the company.
●
Retry stalled tasks when the problem that caused the task to stall is fixed. For example, in an Assign
Task operation, the XPath expression that assigns the task to a user included a syntax error. The error
caused all tasks to stall. The error is corrected, and the tasks are retried.
●
Terminate tasks that are no longer needed.
Methods for intervening in task status
●
Use the Process Management ES pages in LiveCycle Administration Console. (See Process Management
Administration Help.)
●
Use the Task Manager Service API. (See Programming with LiveCycle ES.)
32
Variable Logger Service
The Variable Loggerservice enables processes to send messages about variable values to the system log or
to log files on the file system of the LiveCycle ES server. When a process stalls and is not functioning as
expected, this situation may be related to process variables that are not set correctly. The Variable Logger
service provides the capability to track the process variables and isolate the issue causing the failure.
Using the Variable Logger service
You can interact with the Variable Logger service by developing a process in LiveCycle Workbench ES that
uses the service. When using this service in a process, you can specify the following:
●
Whether to output log messages about process variables to system resources or save them to a file
●
The type of information that is logged in the case of system logging
●
The filename and path of the log file or an XPath expression to a process variable that contains the
filename and path in the case of logging to a file. You can specify whether to overwrite the log file if it
already exists, create a new log file, or append to an existing log file.
For information about developing processes that use this service, see LiveCycle Workbench ES Help.
128
33
Wait Point Service
The Wait Point service enables you to delay the progression of a process at a step in the process.
Using the Wait Point service
You can interact with the Wait Point service by developing a process in LiveCycle Workbench ES that uses
the service. When you use this service in a process to delay the execution of the next operation in the
process, you specify the amount of time to wait using either calendar days or business calendar days:
Calendar days: When you use calendar days, you provide values for the number of days, hours,
minutes, and seconds to wait.
Business calendar days: When you use business calendar days, you specify the name of the business
calendar to use and the number of business days to wait. Business calendars define business and
non-business days (for example, statutory holidays, weekends, and company shutdown days) for your
organization. When using business calendars, LiveCycle ES skips non-business days when calculating
the amount of time to wait.
For information about developing processes that use this service, see LiveCycle Workbench ES Help.
129
34
Web Service Service
The Web Service service enables processes to invoke web service operations. For example, an organization
may want to integrate a process to store and retrieve information such as contact and account details by
invoking a service provider’s exposed web services. The Web Service service invokes a specified web
service, passing through values for each of its parameters., and saves the return values from the operation
into a designated variable within a process.
The Web Service service interacts with web services by sending and receiving SOAP messages. The service
also supports sending MIME and MTOM attachments with SOAP messages using the WS-Attachment
protocol.
Using the Web Service service
You can interact with the Web Service service by developing a process in LiveCycle Workbench ES that
uses the service. You can accomplish the following tasks using this service:
●
Create the SOAP message to send to the web service for invoking a web service operation. After you
provide the URL to the web service definition, you can then select the web service operation to invoke.
Based on the operation that you select, a template of the SOAP request message is generated. You then
insert values into the message as required.
●
Test your invocation request by sending a test message and displaying the response message that the
web service sends.
●
Invoke a web service operation and save the response as process data, including attachments.
For information about developing processes that use this service, see LiveCycle Workbench ES Help.
130
35
XMP Utilities Service
PDF documents contain metadata, which is information about the document (as distinguished from the
contents of the document, such as text and graphics). The Adobe Extensible Metadata Platform (XMP) is a
standard for handling document metadata.
The XMP Utilities service can retrieve and save XMP metadata from PDF documents, and import XMP
metadata into PDF documents.
About XMP metadata
XMP provides a standard format for creating, processing, and exchanging metadata for a wide variety of
applications. XMP provides a model by which metadata is represented. XMP metadata is encoded as
XML-formatted text that uses the W3C standard Resource Description Language (RDF).
In XMP, metadata consists of a set of properties that are associated with a document. Metadata includes
properties such as the author, title, and modification date of a document.
Properties can sometimes be associated with components of a document, but the XMP Utilities service
does not provide the ability to manipulate component metadata.
Properties have names and values:
●
Names must be legal XML names.
●
Values may be simple values, such as numbers and strings, or arrays (also called containers). All values
are actually represented as Unicode strings.
For more information about XMP on the Adobe website, see the main XMP page.
About metadata in PDF documents
In a PDF file, metadata can be stored in two places:
●
In the Info dictionary of the file trailer dictionary. This dictionary contains information about the file,
such as title, author, and creation date. This information is stored as PDF objects such as strings and
dates, not in XML format.
The information in this dictionary is visible to Acrobat and Adobe Reader users through the document
properties. Users can set some of the properties, such as Title, Author, Subject, and Keywords. In
addition, users can add custom properties with a unique name and value.
●
In the Metadata dictionary of the document catalog. This dictionary contains metadata associated with
the entire document. This information is represented as XMP metadata.
Note: Individual streams in a document, such as images, may also have metadata entries containing
associated XMP metadata; however, the XMP Utilities service does not provide the ability to
manipulate such component-level metadata.
131
Adobe LiveCycle ES
LiveCycle ES Services
XMP Utilities Service
Using the XMP Utilities service
132
All metadata in the Info dictionary is also represented in the Metadata dictionary in the form of XMP
metadata properties. The standard properties, such as Title and Author, are represented in XMP as
properties from the PDF schema.
When the XMP Utilities service reads metadata from a PDF file, it resolves inconsistencies between values
in the Info dictionary and those in the XMP metadata:
●
If the Info dictionary is newer, the Info dictionary properties are used to update the XMP metadata.
●
If the XMP metadata is newer, the XMP properties are used to update the Info dictionary.
●
Properties in the Info dictionary that are not listed in the “Document Information Dictionary” section of
the PDF Reference are mapped to the pdfx namespace (“http://ns.adobe.com/pdfx/1.3/”). This
mapping is used when copying properties between the repositories in the situations described in the
first two points.
When a PDF document is saved, some metadata properties are automatically updated, specifically,
xmp:ModifyDate, xmp:MetadataDate, xapMM:InstanceID and if missing, xapMM:DocumentID. If
you attempt to modify these properties, any values you specify will be overridden.
Using the XMP Utilities service
You can accomplish the following tasks using this service:
●
Export Metadata: Exports the metadata from a specified PDF document that you can save as process
data. The PDF document you specify can be stored as process data or specified directly as a file from
the file system.
●
Import Metadata: Imports metadata from process data and replaces the existing metadata in a
specified PDF document.
●
Export XMP: This feature is available only in LiveCycle Workbench ES. Exports the metadata as XMP
data from a specified PDF document. You can save the metadata as a PDF document to process data or
a file to be reused.
●
Import XMP: This feature is available only in Workbench ES. Imports metadata from a document value
and replaces the existing metadata in a specified PDF document.
For information about developing processes that use this service, see LiveCycle Workbench ES Help. For
information about developing client applications that programmatically interact with this service, see
Programming with LiveCycle ES.
36
XSLT Transformation Service
The XSLT Transformation service enables processes to apply Extensible Stylesheet Language
Transformations (XSLT) on XML documents.
Using the XSLT Transformation service
You can interact with the XSLT Transformation service by developing a process in LiveCycle Workbench ES
that uses the service. You can accomplish the following tasks using this service:
●
Configure the XSLT Transformation service with the default Java class to use for performing the XSLT
transformation. The service operation properties can override the value that you provide in the service
configuration.
●
Transform an XML document using an XSLT script that is stored as process data. The XML document is
also stored as process data.
●
Transform an XML document using an XSLT script that is referenced using a URL. The XML document
that is transformed is stored as process data.
●
Test the transformation and see the result.
●
Save the resulting XML document as process data.
For information about developing processes that use this service, see LiveCycle Workbench ES Help.
You can use the Applications and Services pages of LiveCycle Administration Console to configure default
properties for this service. (See Applications and Services Administration Help.)
133
Was this manual useful for you? yes no
Thank you for your participation!

* Your assessment is very important for improving the work of artificial intelligence, which forms the content of this project

Download PDF

advertisement