LiveCycle ES2.5 Services
bc
LiveCycle® ES2.5 Services
Adobe® LiveCycle® ES2.5
September 24, 2010
Version 9.5
© 2010 Adobe Systems Incorporated and its licensors. All rights reserved.
Adobe® LiveCycle® ES2.5 Services
September 24, 2010
This reference document is licensed for use under the terms of the Creative Commons Attribution Non-Commercial 3.0 License. This
License allows users to copy, distribute, and transmit the document for noncommercial purposes only so long as (1) proper attribution to
Adobe is given as the owner of the document; and (2) any reuse or distribution of the document contains a notice that use of the document
is governed by these terms. The best way to provide notice is to include the following link. To view a copy of this license, visit http://creativecommons.org/licenses/by-nc-sa/3.0/.
Adobe, the Adobe logo, Adobe Reader, Acrobat, Distiller, Flash, Flex Builder, FrameMaker, LiveCycle, PageMaker, Photoshop, and
PostScript 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 and AIX are trademarks of International Business Machines Corporation in the United States, other
countries, or both. Red Hat 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, OpenType, SharePoint, Windows, and Windows Server are either registered trademarks or trademarks of
Microsoft Corporation in the United States and/or other countries. Oracle, Sun, Solaris, and Java are trademarks or registered trademarks
of Oracle and/or its affiliates. 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.
Adobe Systems Incorporated, 345 Park Avenue, San Jose, California 95110, USA.
3
Contents
3. About This Document
What’s in this document? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Who should read this document?
Additional information
..............................................................................................................7
........................................................................................................................7
1. Introducing LiveCycle ES2.5 Services
Determining which services belong to a module
How developers interact with services
...............................................................................................8
.........................................................................................................8
How administrators interact with services
......................................................................................................8
2. Assembler Service
About DDX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Using the Assembler service
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Considerations for the Assembler service
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
3. Barcoded Forms Service
Using the service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Considerations for the service
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
4. Connector Services for ECM
Using the ECM connector services
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
5. Central Migration Bridge Service
Using the service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Considerations for the service
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
6. Convert PDF Service
Using the Convert PDF service
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
7. Decision Point Service
Using the Decision Point service
8. Distiller Service
Using the Distiller service
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Using the PDFG Network Printer to invoke Distiller
9. DocConverter Service
Using the DocConverter service
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .32
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
10. Document Management Service
Using the Document Management service
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Considerations for LiveCycle Contentspace ES2.5
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
4
11. Email Service
Using the Email service
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
12. Encryption Service
Using the Encryption service
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Considerations for the Encryption service
13. Execute Script Service
Using the Execute Script service
14. FTP Service
Using the FTP service
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Considerations for the FTP service
15. File Utilities Service
Using the File Utilities service
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Considerations for the File Utilities service
16. Form Augmenter Service
Using the Form Augmenter service
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
17. Form Data Integration Service
Using the Form Data Integration service
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
18. Forms Service
About form types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
How the Forms service processes requests
Using the Forms service
Forms service options
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Considerations for the Forms service
19. Generate PDF Service
Using the Generate PDF service
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Submitting conversion jobs to the Generate PDF service
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Verifying system readiness of the Generate PDF service
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
20. Generate 3D PDF Service
Using the Generate 3D PDF service
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Invoking the Generate 3D PDF service
21. JDBC Service
Using the JDBC service
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Considerations for the JDBC service
22. JMS Service
Using the JMS service
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .78
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
Considerations for the JMS service
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
5
23. LCCPLM Service
Using the service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Considerations for the service
24. LDAP Service
Using the LDAP service
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Considerations for the LDAP service
25. Output Service
Using the Output service
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .84
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Considerations for the Output service
26. PDF Utilities Service
Using the PDF Utilities service
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .104
27. Reader Extensions Service
Using the Reader Extensions service
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .106
Considerations for the Reader Extensions service
28. Repository Service
Using the Repository service
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .108
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .110
29. Rights Management Service
About policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .112
About policy sets
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .112
Security methods and technology
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .112
Using the Rights Management service
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .117
Considerations for the Rights Management service
30. Set Value Service
Using the Set Value service
31. Signature Service
About digital signatures
About signature fields
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .122
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .123
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .124
About the Signature service and form types
About digital signature technology
Supported technologies and standards
Using the Signature service
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .124
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .125
Integrating with a security infrastructure
Best practices
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .120
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .126
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .127
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .127
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .130
32. Stall Service
Using the Stall service
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .132
33. User Service
Using the User service
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .133
Interacting with tasks
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .134
6
34. Variable Logger Service
Using the Variable Logger service
35. Wait Point Service
Using the Wait Point service
36. Web Service Service
Using the Web Service service
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .136
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .137
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .138
37. XMP Utilities Service
About XMP metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .139
About metadata in PDF documents
Using the XMP Utilities service
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .139
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .140
38. \XSLT Transformation Service
Using the XSLT Transformation service
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .141
7
3. About This Document
This document describes the services that developers can use to create Adobe® LiveCycle® ES2.5 applications.
What’s in this document?
This document provides introductory information about services in LiveCycle ES2.5 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. It is intended for developers
who want to build client applications that programmatically interact with services. The document also includes information of interest to
administrators who manage LiveCycle ES2.5 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 ES2.5 modules
LiveCycle ES2.5 Overview
The programming interfaces licensed for use with each LiveCycle
ES2.5 module
Programming Interfaces for LiveCycle ES2.5 Modules
Using a service in a process map
LiveCycle Workbench 9.5 Help
Using a service’s API
Programming with LiveCycle ES2.5
Administering a service
LiveCycle ES2.5 Administration Help
8
1. Introducing LiveCycle ES2.5 Services
Each LiveCycle ES2.5 module uses 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 ES2.5 applications.
Determining which services belong to a module
Each service is licensed for use with one or more LiveCycle ES2.5 modules in a production environment. The LiveCycle Foundation services
are licensed for use with all LiveCycle ES2.5 modules. (See the LiveCycle ES2.5 Overview.)
How developers interact with services
When a service or application is deployed within LiveCycle ES2.5, it can be invoked by a client application by 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 that uses the service.
•
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.
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.
A service can also be invoked by using email and watched folders. Additionally, some services can automatically invoke other services. The
Assembler service can invoke other services that are specified in the DDX file it processes. The Generate PDF service can invoke other
services that are specified by the PDFG Internet Printer feature.
For more information about the different ways to programatically invoke services, see “Invoking LiveCycle ES2.5” in Programming with
LiveCycle ES2.5.
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 ES2.5 archive (LCA) files.
Set up watched folders and email providers for non-programmatic process invocation.
Administer module properties and server settings such as port numbers and log files.
9
2. Assembler Service
The Assembler service lets you combine, rearrange, and augment PDF and XDP documents and obtain information about PDF documents.
Each job submitted to the Assembler service includes a Document Description XML (DDX) document, source documents, and external
resources (strings and graphics). The DDX document provides instructions on how to use the source documents to produce a set of resultant
documents.
About DDX
When using the Assembler service, 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
documents, XDP documents, XDP form fragments, and other elements such as comments, bookmarks, and styled text.
DDX document can specify resultant documents with these characteristics:
•
•
•
•
•
•
•
PDF document that is assembled from multiple PDF documents
Multiple PDF documents that are broken apart from a single PDF document
PDF Portfolio that includes a self-contained user interface and multiple PDF and non-PDF documents
XDP document that is assembled from multiple XDP documents
XDP document that contains XML fragments that are dynamically inserted into an XDP document
PDF document that packages an XDP document
XML files that report on the characteristics of a PDF document. The reported characteristics include text, comments, form data, file
attachments, files used in PDF Portfolios, bookmarks, and PDF properties. PDF properties include form properties, page rotation, and
document author.
You can use DDX to augment PDF documents as part of 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.
• Removes the structure and navigational capabilities of a PDF Package or PDF Portfolio. The result is a single PDF file.
• Renumber page labels. Page labels are typically used for page numbering.
• Import metadata from another source document.
• Add or remove file attachments, bookmarks, links, comments, and JavaScript.
• 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.
• Change the size of selected pages.
• Merge data with a PDF that is XFA-based.
You can use a simple input map to specify the locations of source and resultant documents. You can also use the following external data URL
types:
•
•
Application
Contentspace
ADOBE LIVECYCLE ES2.5
Assembler Service
10
LiveCycle ES2.5 Services
• File
• FTP
• HTTP/HTTPS
• Inputmap
• Process
• Repository (deprecated for use in the Assembler service)
For details about DDX, see Assembler Service and DDX Reference.
Using the Assembler service
For information about developing processes that use this service, see LiveCycle Workbench 9.5. For information about developing client
applications that programmatically interact with this service, see Programming with LiveCycle ES2.5.
Assemble PDF documents
You can use the Assembler service to assemble two or more PDF documents into a single PDF document or PDF Portfolio. You can also
apply features to the PDF document that aid navigation or enhance security. Here are some of the ways you can assemble PDF documents:
•
•
•
•
•
“Assemble a simple PDF document” on page 10
“Create a PDF Portfolio” on page 11
“Assemble encrypted documents” on page 11
“Assemble documents using Bates numbering” on page 11
“Flatten and assemble documents” on page 12
Assemble a simple PDF document
The following illustration shows three source documents being merged into a single resultant document.
ADOBE LIVECYCLE ES2.5
Assembler Service
11
LiveCycle ES2.5 Services
The following example is a simple DDX document used to assemble the document. It specifies the names of the source documents used to
produce the resultant document, as well as the name of the resultant document:
<PDF result="Doc4">
<PDF source="Doc1"/>
<PDF source="Doc2"/>
<PDF source="Doc3"/>
</PDF>
Document assembly produces a resultant document that contains the following content and characteristics:
•
•
•
•
All or part of each source document
All or part of the bookmarks from each source document, normalized for the assembled resultant document
Other characteristics adopted from the base document (Doc1), including metadata, page labels, and page size
Optionally, the resultant document includes a table of contents constructed from the bookmarks in the source documents
Create a PDF Portfolio
The Assembler service can create PDF Portfolios that contain a collection of documents and a self-contained user interface. The interface is
called a PDF Portfolio Layout or a PDF Portfolio navigator (navigator). PDF Portfolios extend the capability of PDF packages by adding a
navigator, folders, and welcome pages. The interface can enhance the user experience by taking advantage of localized text string, custom
color schemes, and graphic resources. The PDF Portfolio can also include folders for organizing the files in the portfolio.
When the Assembler service interprets the following DDX document, it assembles a PDF Portfolio that includes a PDF Portfolio navigator
and a package of two files. The service obtains the navigator from the location specified by the myNavigator source. It changes the
navigator’s default color scheme to the pinkScheme color scheme.
<DDX xmlns="http://ns.adobe.com/DDX/1.0/">
<PDF result="Untitled 1">
<Portfolio>
<Navigator source="myNavigator"/>
<ColorScheme scheme="pinkScheme"/>
</Portfolio>
<PackageFiles>
<PDF source="sourcePDF1"/>
<PDF source="sourcePDF2"/>
</PackageFiles>
</PDF>
</DDX>
Assemble 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 or Acrobat. 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 ES2 installation to encrypt a PDF document with a password.
If one or more of the input documents is encrypted, provide a password to open the document as part of the DDX.
Assemble 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 called a bates pattern.
ADOBE LIVECYCLE ES2.5
Assembler Service
12
LiveCycle ES2.5 Services
The following illustration shows a PDF document that contains a unique identifier located in the document’s header.
Flatten and assemble documents
You can use the Assembler service to transform an interactive PDF document (for example, a form) 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.
When you create a PDF document that is assembled from interactive PDF documents, the Assembler service flattens those forms before
assembling them into the resultant document.
Note: The Assembler service uses the Output service to flatten dynamic XFA forms. If the Assembler service processes a DDX that requires it to
flatten an XFA dynamic form and the Output service is unavailable, an exception is thrown. The Assembler service can flatten an Acrobat form
or a static XFA form without using the Output service.
Assemble XDP documents
You can use the Assembler service to assemble multiple XDP documents into a single XDP document or into a PDF document. For source
XDP files that include insertion points, you can specify the fragments to insert. Here are some of the ways you can assemble XDP documents:
•
•
•
“Assemble a simple XDP document” on page 13
“Dynamically insert form fragments into an XFA form” on page 13
“Package an XDP document as PDF” on page 14
ADOBE LIVECYCLE ES2.5
Assembler Service
13
LiveCycle ES2.5 Services
Assemble a simple XDP document
The following illustration shows three source XDP documents being assembled into a single resultant XDP document. The resultant XDP
document contains the three source XDP documents including their associated data. The resultant document obtains basic attributes from
the base document, which is the first source XDP document.
Here is a DDX document that produces the result illustrated above.
<DDX xmlns="http://ns.adobe.com/DDX/1.0/">
<XDP result="MyXDPResult">
<XDP source="sourceXDP1"/>
<XDP source="sourceXDP2"/>
<XDP source="sourceXDP3"/>
</XDP>
</DDX>
Dynamically insert form fragments into an XFA form
You can use the Assembler service to create an XFA form that is created from another XFA form that fragments are inserted into. Using this
feature, you can use fragments to create multiple forms.
Support for dynamic insertion of form fragments supports single-source control. You maintain a single source of commonly used components. For example, you can create a fragment for your company banner. If the banner changes, you only have to modify the fragment. The
other forms that include the fragment are unchanged.
Form designers use Designer ES2.5 to create form fragments. These fragments are uniquely named subforms within an XFA form. The form
designers also use Designer ES2.5 to create XFA forms that have uniquely named insertion points. You (the programmer) write DDX
documents that specify how fragments are inserted into the XFA form.
ADOBE LIVECYCLE ES2.5
Assembler Service
LiveCycle ES2.5 Services
The following illustration shows two XML forms (XFA templates). The form on the left contains an insertion point named
myInsertionPoint. The form on the right contains a fragment named myFragment.
When the Assembler service interprets the following DDX document, it creates an XML form that contains another XML form. The
myFragment subform from the myFragmentSource document is inserted at the myInsertionPoint in the myFormSource document.
<DDX xmlns="http://ns.adobe.com/DDX/1.0/">
<XDP result="myFormResult">
<XDP source="myFormSource">
<XDPContent fragment="myFragment" insertionPoint="myInsertionPoint" source="myFragmentSource"/>
</XDP>
</XDP>
</DDX>
Package an XDP document as PDF
You can use the Assembler service to package an XDP document as a PDF document, as shown in this DDX document.
<DDX xmlns="http://ns.adobe.com/DDX/1.0/">
<PDF result="Untitled 1" encryption="passEncProfile1">
<XDP>
<XDP source="sourceXDP3"/>
<XDP source="sourceXDP4"/>
</XDP>
</PDF>
</DDX>
Disassemble PDF documents
You can use the Assembler service to disassemble a PDF document. The service can extract pages from the source document or divide a
source document based on bookmarks. Typically, this task is useful if the PDF document was originally created from many individual
documents, such as a collection of statements.
14
ADOBE LIVECYCLE ES2.5
Assembler Service
15
LiveCycle ES2.5 Services
Extract pages from a source document
In the following illustration, pages 1-3 are extracted from the source document and placed in a new resultant document.
Source documents
Doc2
Pages 1-100
Result document
Doc4
Pages 1-3
The following example is a DDX document used to disassemble the document.
<PDF result="Doc4">
<PDF source="Doc2" pages="1-3"/>
</PDF>
Divide a source document based on bookmarks
In the following illustration, DocA is divided into multiple resultant documents. The first level 1 bookmark on a page identifies the start of
a new resultant document.
Source documents
DocA
Result document
A.000001.Bkmk1.pdf
A.000002.Bkmk2.pdf
A.000003.Bkmk3.pdf
The following example is a DDX document that uses bookmarks to disassemble a source document.
ADOBE LIVECYCLE ES2.5
Assembler Service
16
LiveCycle ES2.5 Services
<PDFsFromBookmarks prefix="A">
<PDF source="DocA"/>
</PDFsFromBookmarks>
Determine 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 longterm 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).
Obtain information about a PDF document
You can use the Assembler service to obtain the following information about a PDF document:
•
•
•
•
Text information.
• Words on each page of the document
• Position of each word on each page of the document
• Sentences in each paragraph of each page of the document
Bookmarks, including the page number, title, destination, and appearance. You can export this data from a PDF document and import
it into a PDF document.
File attachments, including file information. For page-level attachments, it also includes the location of the file attachment annotation.
You can export this data from a PDF document and import it into a PDF document.
Package files, including file information, folders, package, schema, and field data. You can export this data from a PDF document and
import it into a PDF document.
Validate 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, validation ensures that your DDX document is valid.
Call other LiveCycle ES2.5 services
You can use DDX documents that cause the Assembler service to call the following LiveCycle ES2.5 services. The Assembler service can call
only those services installed with LiveCycle.
Reader Extensions service: Enables Adobe Reader users to digitally sign the resultant PDF document.
Forms service: Merges an XDP file and XML data file to produce a PDF document that contains the filled interactive form.
Output service: Converts a dynamic XML form to a PDF document that contains a non-interactive form (flattens the form). (The
Assembler service flattens static XML forms and Acrobat forms without calling the Output service.)
DocConverter service: Converts a PDF document to a PDF/A document.
Generate PDF service: Converts native file formats to PDF. Examples of native file formats are Word, Excel, and HTML.
Generate 3D PDF service: Converts CAD file formats to PDF.
Distiller service: Converts a PostScript document to a PDF document.
ADOBE LIVECYCLE ES2.5
Assembler Service
17
LiveCycle ES2.5 Services
DDX documents describe the characteristics of the resultant PDF documents. They do not provide explicit calls to LiveCycle ES2.5 services.
When the Assembler service interprets certain DDX elements, it determines whether to call other LiveCycle ES2.5 services to achieve the
result specified by the DDX document. For example, when the Assembler service interprets a PDF source file that specifies a non-PDF file,
it calls the Generate PDF service to convert that file to PDF. When the Assembler service interprets a PDF source file that contains an XML
form (XFA form) and separate XML form data, it calls the Forms service to merge the data into the XML form.
The following DDX example combines two PDF documents and enables Adobe Reader users to digitally sign the resultant PDF document.
The ReaderRights element inside the PDF result element enables the Adobe Reader usage rights.
<?xml version="1.0" encoding="UTF-8"?>
<DDX xmlns="http://ns.adobe.com/DDX/1.0/">
<PDF result=”outDoc”>
<PDF source=”doc1”/>
<PDF source=”doc2”/>
<ReaderRights
credentialAlias="LCESCred"
digitalSignatures=”true”/>
</PDF>
</DDX>
Using DDX and the Assembler service to call other LiveCycle ES2.5 services can simplify your process diagram. It can even reduce the effort
you spend customizing your workflows. (See also Assembler Service and DDX Reference.)
Use Assembler IVS to check DDX documents
Assembler Installation and Verification Sample (Assembler IVS) is a sample application for checking DDX documents without having to
modify a LiveCycle Workbench process. It provides an editor for creating and editing DDX documents (in XML format) and for creating a
preview of the result the DDX document represents. Assembler IVS also includes these examples that illustrate different DDX concepts:
• Assembling a document
• Disassembling a document by bookmarks and pages
• Converting a PDF document to PDF/A
• Creating a PDF package
• Obtaining the metadata or content from a PDF document
Assembler IVS uses the Invoke DDX service of the Assembler service.
Note: The Document Builder perspective in Workbench is a better way to create and test DDX documents. Document Builder provides an
intuitive user interface for creating DDX documents. You can create and check DDX documents without having to work directly in XML.
Assembler IVS must be deployed before you can use it. Administrators can use LiveCycle Configuration Manager to deploy Assembler IVS.
They can also manually deploy it. (See the LiveCycle ES2 installation documents, such as Installing and Deploying LiveCycle ES2 for JBoss.)
To start the Assembler IVS application, navigate to http://[server_name:port_number]/Assembler.
ADOBE LIVECYCLE ES2.5
Assembler Service
18
LiveCycle ES2.5 Services
Here is an illustration of the Assembler IVS user interface.
Here are the general steps for testing a DDX document:
1
Specify the DDX by copying your DDX document into the large window. Or, you can use one of the DDX documents that are available
by clicking DDX or Demos at the top of the window.
2
Specify the input files by clicking the plus sign (+) button near the Collateral panel. The interface presents a field that lets you browse
for the file. Click this button for each file being used as collateral.
3
Specify the input map by clicking the plus sign (+) button near the Input Map panel. If necessary, modify the names of the map entries
to match source names in your DDX document. Click this button for each entry in the document map.
4
Associate the input files with map entries by dragging files down onto one of the input map entries. You can use the same file multiple
times with different input map entries. You can also place multiple input files in the same input map entry.
5
Invoke Assembler IVS by clicking Invoke.
If Assembler IVS succeeds in creating a resulting PDF document, it displays the result in a new browser window. If it is unsuccessful, it
provides feedback on the error.
Considerations for the Assembler service
Assembling and applying content to large PDF documents can use so much memory that the Assembler service is terminated with an out
of memory (OOM) exception. You can use operation checkpoints to avoid triggering such exceptions. See the Assembler Service and DDX
Reference.
19
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 various ways, including XML, delimited string, or
any custom format created with JavaScript.
The Barcoded Forms service supports the following two-dimensional (2D) symbologies supplied as scanned TIFF or PDF documents:
• PDF417
• Data Matrix
• QR Code
The service also supports the following one-dimensional symbologies supplied as scanned TIFF or PDF documents:
•
•
•
•
•
Codabar
Code128
Code 3 of 9
EAN13
EAN8
Caution: You must consider the following limitations when using the Barcoded Forms service:
•
The service fully supports AcroForms and static forms containing 2D barcodes that are simply saved using Adobe Reader or
Acrobat. However, for 1D barcodes, you must either flatten the form or supply it as scanned PDF or TIFF document.
•
Dynamic XFA forms are not fully supported. For the service to properly decode 1D and 2D barcodes in a dynamic form, you must
either flatten the form or supply it as scanned PDF or TIFF document.
In addition, barcodes need not originate from forms. The service can decode any barcode that uses supported symbology provided that the
above limitations are observed.
For more information on how to create interactive barcoded forms, see LiveCycle Designer ES2.5 Help.
Using the service
You can accomplish the following tasks by 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 ES2.5 services.
For information about developing processes that use this service, see LiveCycle Workbench 9.5 Help. For information about developing
client applications that programmatically interact with this service, see Programming with LiveCycle ES2.5.
You can use the Applications and Services pages within LiveCycle Administration Console to configure default properties for this service.
(See Barcoded Forms service settings in LiveCycle ES2.5 Administration Help.)
ADOBE LIVECYCLE ES2.5
Barcoded Forms Service
20
LiveCycle ES2.5 Services
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 element of an XML document. For example, the following scanned TIFF
image of a form contains two barcodes:
ADOBE LIVECYCLE ES2.5
Barcoded Forms Service
21
LiveCycle ES2.5 Services
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>
Considerations for the service
Workflows that use barcoded forms
Form authors create interactive barcoded forms by using LiveCycle Designer ES2.5. (See LiveCycle Designer ES2.5 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 converting data that exists on paper to 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 service for
decoding.
ADOBE LIVECYCLE ES2.5
Barcoded Forms Service
22
LiveCycle ES2.5 Services
Recommended 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 ES2.5 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, specify the character that is 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 by using Designer ES2.5, 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 that the form author specified when the form was designed.
23
4. Connector Services for ECM
Adobe LiveCycle ES2 Connector for EMC Documentum, Adobe LiveCycle ES2 Connector for IBM Content Manager, Adobe LiveCycle ES2
Connector for IBM FileNet, and Adobe LiveCycle ES2.5 Connector for Microsoft SharePoint provide the following services:
A content repository connector service: These are independent services usable as operations in a process created in a LiveCycle ES2.5
process:
• Content Repository Connector for EMC Documentum
• Content Repository Connector for IBM Content Manager
• Content Repository Connector for IBM FileNet
• Content Repository Connector for Microsoft SharePoint
LiveCycle Workbench developers can use these services in a process to store content 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.
If you have installed the Adobe LiveCycle ES2.5 Connector for Microsoft SharePoint, you can enable SharePoint site users to invoke
LiveCycle processes such as converting documents in the SharePoint repository to Adobe PDF format, applying additional usage rights on
Adobe PDF documents, and securing documents with Adobe Policy. In addition, SharePoint users can create and initiate workflows that
use services available on the connected LiveCycle server.
Consider the example of a financial institution automating an account opening process. The process must let applicants 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. The LiveCycle ES2.5 application that the
financial institution develops for this process includes content-repository connector-service operations. These operations are used for the
following purposes:
•
•
Storing the completed forms in a customer-defined content object type in the ECM repository.
Retrieving the content, which can be generated from other ECM applications or assembled from the ECM repository.
Process Engine Connector for IBM FileNet for IBM FileNet service: Workbench developers can use the Process Engine Connector for
IBM FileNet service for the following purposes:
• Creating processes that set and retrieve IBM FileNet Workflow Step parameters
• Dispatching a workflow step in IBM FileNet.
At runtime, 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 ES2.5, 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.
For more information about the content repository connectors services and the Process Engine Connector for IBM FileNet, see LiveCycle
Workbench 9.5 Help.
Note: In previous releases of LiveCycle, assets could be stored in an ECM repository. In LiveCycle ES2.5, assets are stored in the LiveCycle ES2.5
native repository, and the repository provider services have been deprecated. The migration of assets from an ECM repository to the LiveCycle
ES2.5 repository is done when you perform an update to LiveCycle ES2.5. For more information, see the LiveCycle ES2.5 Upgrade document for
your application server.
ADOBE LIVECYCLE ES2.5
Connector Services for ECM
24
LiveCycle ES2.5 Services
Using the ECM connector services
To access an ECM from Resource View in Workbench or programmatically using the Repository Service API, administrators must select
the appropriate ECM repository service provider. They must select the repository service provider in LiveCycle Administration Console
instead of the default provided with LiveCycle ES2.5. For information about setting up the ECM connector services, see the LiveCycle ES2
installation documents, such as Installing and Deploying LiveCycle ES2 for JBoss.
You can access an ECM content repository by using the Form Design perspective in Workbench. You are 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.
You must have the appropriate credentials to access the content repository. Each time you use Workbench, 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. You can share the content repository from Workbench with other developers.
Note: You cannot use Connector for EMC Documentum to create documents in Docbase root. Instead, create documents in a Docbase cabinet.
This restriction is due to a Documentum limitation.
When developing a process that uses a repository provider service, you can specify the resource URL to the ECM content repository. The
URL Is specified in the properties associated with a service, such as the Forms service. You can also specify the resource URL by 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 by 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 the repository provider uses)
•
(Adobe LiveCycle ES2 Connector for Microsoft SharePoint only) Create and initiate SharePoint workflows that use services in LiveCycle
ES2.5
•
(LiveCycle ES2 Connector for Microsoft SharePoint only) Convert documents to Adobe PDF format, apply usage rights, and enable
additional features in Adobe Reader
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
The LiveCycle ES2 Connector for Microsoft SharePoint provides the following features:
• Allows users to invoke LiveCycle ES2.5 processes, such as an approval process from within SharePoint
• Allows users to convert documents to Adobe PDF and manage the rights on a file in PDF or native formats
• Provides the ability to create and initiate SharePoint workflows that use services in LiveCycle ES2.5
• Enables users to apply usage rights to PDF files to enable additional features in Adobe Reader
• Allows automation of running LiveCycle ES2.5 processes from within SharePoint workflows
• Enables users to manage assigned LiveCycle tasks and claim new tasks from within SharePoint 2010
• Allows integration of LiveCycle forms with SharePoint Server 2010 and effectively use SharePoint as the repository for form data
For information about developing processes that use these services, see LiveCycle Workbench 9.5 Help. For information about developing
client applications that programmatically interact with these services, see Programming with LiveCycle ES2.5. For information about
configuring SharePoint sites to invoke LiveCycle ES2.5 processes and perform LiveCycle ES2.5 actions, see the LiveCycle ES2 Installation
documents, such as Installing and Deploying LiveCycle ES2 for JBoss.
ADOBE LIVECYCLE ES2.5
Connector Services for ECM
LiveCycle ES2.5 Services
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 Connect to a content management system in LiveCycle ES2.5 Administration Help.)
25
26
5. Central Migration Bridge Service
The Central Migration Bridge service is provided for existing Adobe Output Server clients to assist in migrating to Adobe LiveCycle Output
ES2.5. The Adobe Output Server family (Central) includes the following products:
• Adobe Output Designer
• Adobe Central Output Server
• Adobe Central Pro Output Server
• Adobe Web Output Pak
These products provide features that are similar to LiveCycle Output ES2.5; however, they are based on more mature Adobe technology.
The Central Migration Bridge service allows you to use a core set of Central Server functions in the LiveCycle ES2.5 environment. You will
continue using your existing assets (such as MDF output templates and TDF files) with LiveCycle ES2.5.
The Central Migration Bridge service is not intended for general Output ES2.5 customer use. It is targeted at customers that have a Central
Output Server implementation and are migrating to LiveCycle ES2.5. To use the Central Migration Bridge service, you must have a valid
license for Central Pro Output Server 5.7 or an executed Central Pro Output Server 5.7 migration agreement. Contact your Adobe representative for more information regarding a migration agreement.
Using the service
The Central Migration Bridge service uses a subset of Adobe Central Pro Output Server functionality. This subset duplicates the functionality provided by the Central Print Agent, Central Transformation Agent, and Central XML Import Agent. With this subset, you can
continue using the following Central assets:
• Template design (*.ifd)
• Output templates (*.mdf)
• Data files (*.dat files), including the Central field-nominated format
• Preamble files (*.pre files)
• Data transformation definition files (*.tdf)
To use the Central Migration Bridge service, you must have proper access rights to the Central installation directory.
For information about developing processes that use this service, see LiveCycle Workbench 9.5 Help. For information about developing
client applications that programmatically interact with this service, see Programming with LiveCycle ES2.5.
Central Merge operation
The Central Merge operation merges data with output templates. It returns the result in a format supported by Central, such as IPL, ZPL,
PDF, PS, or PCL. This operation can use an external preamble file.
For example, you have a field-nominated data file that contains customer information, such as the name, address, and invoice number. Your
application can use the Central Merge operation to merge the data file with an Invoice output template design. Your application can then
use the following LiveCycle ES2.5 services to email, save to disk, or print the output file:
•
•
•
Email service
File Utilities service
Output service’s sendToPriner operation
ADOBE LIVECYCLE ES2.5
Central Migration Bridge Service
27
LiveCycle ES2.5 Services
In addition to the primary input parameters (data file and template), this operation accepts a string representing command-line options
passed to the Central JFMERGE command. You can use these options to specify all standard options that you use in your current Central
job management database (JMD).
The Central Merge operation can produce a trace file. To enable this feature, specify the trace file option. You can use the trace file to achieve
a page 1 of n page numbering scheme on generated documents by performing these tasks:
1
Run Central Merge once to obtain a trace file.
2
Pass the resultant trace file to a second run of Central Merge to format the page numbering.
The Central Merge operation runs the Central JFMERGE command (Central Print Agent). This operation uses the jfmerge.ini file in the
same way that Central Pro uses it.
Central Transformation operation
The Central Transformation operation converts structured text and overlay text to acceptable formatted data. The resultant data can then
be used with the Central Merge operation. The Central Transformation operation converts data created in ASCII format, including fixed
length, character-delimited, overlay, XML, and Central-proprietary field-nominated format. It converts such data to XML or fieldnominated format.
This operation also provides a scripting capability that you can use to modify an existing data file. Here are some applications for this
scripting capability:
• Modify the data into a format that you can merge with a form design.
• Transform existing data, such as dates, from MM-DD-YYYY to DD-MM-YYYY format.
In addition to the primary input parameters (data file and TDF file), this operation accepts a string representing command-line options that
are passed to the Central JFTRANS command.
The Central Transformation operation runs the Central JFTRANS command (Central Transformation Agent). This operation uses the
jfmerge.ini file in the same way that Central Pro uses it.
Central XML Import operation
The Central XML Import operation transforms well-formed XML data into field-nominated format.
In addition to the primary input parameters (XML file), this operation accepts a string representing command-line options that are passed
to the Central XMLIMPORT command.
The Central XML Import operation runs the Central XMLIMPORT command. This operation uses the xmlimport.ini file in the same way
that Central Pro uses it.
Central Data Access operation
The Central Data Access operation provides access to certain elements of a field-nominated data file (DAT file) within a LiveCycle ES2.5
process. It extracts the ^field, ^global, ^form, and ^job commands from the data file and transforms them into an intermediate XML
document. Your process can use XPath expressions to access the values of specific entries within that XML file. It can use the accessed values
to make decisions, and it can pass the intermediate XML file to other LiveCycle ES2.5 services.
LiveCycle Workbench provides an XPath builder dialog box that simplifies the task of creating XPath expressions.
Note: The Central Data Access operation does not fully convert field-nominated data files into an equivalent XML representation. Instead, it
converts specific elements into an intermediate XML representation.
The Central Data Access operation makes it easier to integrate existing Central Pro applications into LiveCycle ES2.5. Here is an example
that uses this operation to determine the values of specific field-nominated commands in the data file:
ADOBE LIVECYCLE ES2.5
Central Migration Bridge Service
28
LiveCycle ES2.5 Services
1
Invoke the Central Data Access operation to obtain the intermediate XML representation of the commands from the data file.
2
Use an XPath expression to get the value of the ^job field-nominated command (the job value).
3
Use the job value to determine which template to use with the data.
4
Invoke the Central Merge operation to merge the selected template with the original data file and to produce a PDF document.
5
Use an XPath expression to get the value of the ^field EMAILADDRESS from the intermediate XML representation.
6
Invoke the Email service to send the PDF file to the job originator through email.
The Central Data Access operation does not run a Central command.
Considerations for the service
You can use the Central Migration Bridge service to gradually migrate aspects of your existing Adobe Output Server assets and implementation. LiveCycle ES2.5 and Central Migration Bridge treats log results differently than Adobe Central Pro Output Server treats them.
Migrating
Migrating libraries of templates and modifying related data sources can be the largest part of any migration effort. Using the Central
Migration Bridge service, you can migrate an application from Central to Output ES2.5 in stages.
Initial stage: Move the invocation and run-time aspects from the Central environment to the LiveCycle ES2.5 environment. You can
continue to use existing Central templates and data assets. If you use Central Job Management Database (JMD), replace it with LiveCycle
ES2.5 processes. Output ES2.5 does not support JMD, and it does not provide tools for converting JMD.
If your existing Central templates were saved with a version of Output Designer earlier than 5.7, they may work as is. However, in some
instances (especially with pre-5.4 templates), you may need to migrate your existing Central templates by using Output Designer 5.7. When
you use that application to open and save a template, it automatically migrates the template. Use Output Designer 5.7 to test migrated
templates to ensure that they work as expected.
Subsequent stages: Over time, convert templates and non-XML data assets for use with Output ES2.5. You can simultaneously use new
and converted processes on the same LiveCycle ES2.5 server. Over time you can convert all of your assets and become independent of the
Central Migration Bridge service.
You can use LiveCycle Designer ES2.5 to import Output Designer templates. To enable this feature, install Output Designer with Designer
ES2.5. To use this feature, open a file of type Adobe Output Designer template (*.ifd). Designer ES2.5 performs a basic conversion. The
degree of completeness of the conversion depends on the complexity of the incoming form. Use Designer ES2.5 to complete the conversion
process. (See LiveCycle Designer ES2.5 Help and Designing Forms for LiveCycle Output ES2.)
Log results
How you obtain logs that Central produces differs from how you obtain log files that the Central Migration Bridge service produces. Central
creates a centralized log file; the Central Migration Bridge service returns the log to the application or process that initiated the operation.
To save the log that the Central Migration Bridge service returned, write the returned log document to a file system. Saving the log is
especially useful for debugging.
To adjust the amount of content in the log file, set values in the standard .ini files.
ADOBE LIVECYCLE ES2.5
Central Migration Bridge Service
LiveCycle ES2.5 Services
Requirements
The Central Migration Bridge service requires that you install Adobe Central Pro Output Server 5.7 on the same computer that is hosting
LiveCycle ES2.5. The Central Migration Bridge service does not support earlier versions of Adobe Central Pro Output Server. (See the
LiveCycle ES2 installation documents, such as Installing and Deploying LiveCycle ES2 for JBoss.)
Central Migration Bridge supports the same platforms that LiveCycle ES2.5 supports.
Samples
LiveCycle ES2.5 provides samples that demonstrate how to use the Central Migration Bridge service. (See LiveCycle ES2 Samples.)
29
30
6. 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 by using the Convert PDF service:
•
Convert PDF documents to PostScript. When converting to PostScript, you can use the conversion operation 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 non-interactive.
•
Convert PDF documents to JPEG, JPEG 2000, PNG, and TIFF image formats. When converting to any of these image formats, you can
use the conversion operation to specify the source document and an image options specification. The specification contains various
preferences, such as image conversion format, image resolution, and color conversion.
•
(Deprecated) Extract files from an archive file to a directory.
Note: The operation to extract files from an archive was deprecated in LiveCycle ES 8.2; however, you can continue using it in LiveCycle
ES2.5.
For information about developing processes that use this service, see LiveCycle Workbench 9.5 Help. For information about developing
client applications that programmatically interact with this service, see Programming with LiveCycle ES2.5.
Use the Applications and Services pages of LiveCycle Administration Console to configure default properties for this service. (See Convert
PDF service settings in LiveCycle ES2.5 Administration Help.)
31
7. Decision Point Service
The Decision Point service is used in Workbench processes for a branching decisions.
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 someone submits a form, and form data determines the first action to execute in
the Workbench process. For example, a customer can fill an invoice dispute form through your corporate website. The monetary value
claimed by 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 must 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, where the branching is not part of another
operation in the process. 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 9.5 Help.
32
8. Distiller Service
The Distiller® service converts PostScript, Encapsulated PostScript (EPS), and printer text files (PRN) to PDF files. 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.
Note: 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.
Using the Distiller service
When converting a PostScript, Encapsulated PostScript, or PRN file to a PDF file, you can use the conversion operation to specify several
options to apply to the resultant PDF document. Here are the parameters you can use to specify these options:
•
PDF settings: This parameter provides the name of the Adobe PDF settings to use for the conversion. The named settings are defined
on the LiveCycle Administration Console. The console is pre-configured with several Adobe PDF settings. The names of these settings
are locale-specific. On English installations, these names include High Quality Print, PDFA1b 2005 CMYK, and Press Quality.
If the Input Settings Document parameter provides a value, this parameter is ignored. If this parameter and the Input Settings Document
parameter are both null, this operation uses the default file type settings instance that is defined on the LiveCycle ES2.5 server.
•
Security settings: This parameter provides the name of the security settings to use for the conversion. The named settings are defined
on the LiveCycle Administration Console. On English installations, the console is pre-configured with only the No Security security
settings.
If the Input Settings Document parameter provides a value, this parameter is ignored. If this parameter and the Input Settings Document
parameter are both null, this operation uses the default file type settings instance that is defined on the LiveCycle ES2.5 server.
•
Input Settings Document: An XML file containing conversion settings, including Adobe PDF settings and security settings. The Input
Settings Document can contain multiple sets of settings. This operation uses only the default sets. (See LiveCycle ES2.5 Generate PDF
Conversion Settings Reference.)
•
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, visit the main XMP page on the Adobe website.
For information about developing processes that use this service, see LiveCycle Workbench 9.5 Help. For information about developing
client applications that programmatically interact with this service, see Programming with LiveCycle ES2.5.
In LiveCycle Administration Console, you can use the Applications and Services pages to configure default properties of the Distiller service.
(See Distiller service settings in LiveCycle ES2.5 Administration Help.) You can also use the LiveCycle PDF Generator ES2.5 page to specify
default PDF settings and security settings to apply when converting to PDF. (See Configuring PDF Generator ES2.5 and PDF Generator 3D
ES2.5 in LiveCycle ES2.5 Administration Help.)
Using the PDFG Network Printer to invoke Distiller
You can invoke the Distiller service CreatePFD2 operation by using any of the techniques described in “How developers interact with
services” on page 8”. You can also submit conversion jobs to that operation by using the PDFG Network Printer (IPP printer).
PDFG Network Printer driver is installed like any other print driver on the desktop. Users can take advantage of the centralized PDF generation that the PDF Generator ES2.5 module provides from any application on their desktop.
ADOBE LIVECYCLE ES2.5
Distiller Service
33
LiveCycle ES2.5 Services
Use of the PDFG Network Printer involves the following general steps:
1
Users print documents to the PDFG Network Printer.
2
The PDFG Network Printer converts the submitted file to a PostScript stream and uses the Internet Printing Protocol (IPP) to send the
stream to the Distiller service.
3
The Distiller service converts the stream to PDF. The conversion uses the Adobe PDF settings specified by the PDFG Network Printer
configuration.
4
The Distiller service sends the conversion results back to the requestor through email. It can also submit the conversion results to
another LiveCycle ES2.5 service or process. This feature effectively makes the PDFG Network Printer another LiveCycle ES2.5 endpoint.
Before a user can print to the PDFG Network Printer, an administrator configures the user’s system with the client interface for the PDFG
Network Printer. For information about installing the print driver, see the Installing and Deploying LiveCycle ES2 documents. For information about configuring this feature, see Setting up a PDFG Network Printer in LiveCycle ES2.5 Administration Help.
34
9. DocConverter Service
The DocConverter service transforms signed or unsigned PDF documents, XML forms (typically created in LiveCycle Designer ES2.5), and
Acrobat forms to PDF/A-compliant documents. You can also use this service to validate whether PDF documents are compliant with
PDF/A, which is primarily used for archiving.
The DocConverter service is included with the following LiveCycle ES2.5 modules:
• Adobe LiveCycle PDF Generator ES2.5
• Adobe LiveCycle PDF Generator 3D ES2.5
• Adobe LiveCycle Output ES2.5
To use the DocConverter service with XML forms, you must have Output ES2.5. To use the DocConverter service with documents that
contain signed or unsigned signature fields, you must have LiveCycle Digital Signatures ES2.5.
Using the DocConverter service
You can accomplish the following tasks by using the DocConverter service:
• “Validating whether PDF documents are compliant with PDF/A” on page 34
• “Converting PDF documents to PDF/A” on page 34
For information about developing processes that use this service, see LiveCycle Workbench 9.5 Help. For information about developing
client applications that programmatically interact with this service, see Programming with LiveCycle ES2.5.
Validating whether PDF documents are compliant with PDF/A
You can use the DocConverter service to validate whether a PDF document is compliant with the PDF/A-1b standard (ISO 19005-1b).
Converting PDF documents to PDF/A
You can use the DocConverter service to transform the following types of files to PDF documents that are compliant with PDF/A-1b:
• Signed or unsigned PDF documents
• XML forms (typically created in Designer ES2.5)
• Acrobat forms
PDF/A-1b is the ISO standard for long-term archiving of PDF-based documents. Because long-term preservation is the goal, the document
contains only the information to guarantee a consistent understanding and rendering of the content, including these items:
• Associated metadata to aid in understanding the content.
• Schema for any custom metadata.
• Fonts. All fonts are embedded. As a result, a PDF/A document is typically larger than a standard PDF document.
PDF/A documents cannot contain or use the following items:
•
•
•
Audio and video content and scripts
Encryption
Scripts
ADOBE LIVECYCLE ES2.5
DocConverter Service
35
LiveCycle ES2.5 Services
The PDF/A-1 standard has restrictions that affect conversion of signatures and forms. When the DocConverter service converts files to
PDF/A-1b, it modifies the file to comply with PDF/A-1b standards. (See “Signatures” on page 35, “Adobe XML forms” on page 35 and
“Acrobat forms” on page 35.)
If the DocConverter service cannot completely convert a file to PDF/A, it partially converts the file. In addition to the converted file, the
DocConverter service also creates a conversion report. The report indicates fixes that were applied to the file and violations that could not
be fixed.
Although PDF/A is the standard for archiving PDF documents, you are not required to use PDF/A for archiving. Standard PDF documents
may satisfy your company’s requirements. The purpose of the PDF/A standard is to establish a PDF file for long-term archiving and
document-preservation needs. (See also PDF as a Standard for Archiving and Processing PDF/A Documents.)
Signatures
By default, the DocConverter service removes all but the last signature from a PDF file. The service captures information about the removed
signatures in metadata. It also records the appearance of the removed signatures by adding an equivalent image to the PDF file. The removed
signatures cannot be verified.
Users can sign PDF/A documents.
Adobe XML forms
A PDF/A file cannot contain an XML form templates (XFA forms).
The DocConverter service flattens XML form templates that appear in a PDF file, including XML signatures. The service captures information about the removed signatures in metadata. It also records the appearance of the removed signatures into the document by adding
an equivalent image to the PDF file. The flattened signatures cannot be verified.
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. Also, the data in the form cannot be extracted by
using standard tools; however, the data is still present in the PDF/A.
Acrobat forms
A PDF/A file can contain any type of interactive Acrobat form field, provided those fields are visible. The fields can contain data, but they
cannot contain scripts.
36
10. Document Management Service
The Document Management service enables processes to use the content management functionality provided by Adobe LiveCycle Content
Services ES2.5. For information about LiveCycle Content Services ES2.5, see LiveCycle ES2.5 Overview.
Using the Document Management service
For information about developing processes that use this service, see LiveCycle Workbench 9.5 Help. For information about developing
client applications that programmatically interact with this service, see Programming with LiveCycle ES2.5.
You can use the Applications and Services pages in LiveCycle Administration Console to configure default properties for this service. (See
LiveCycle ES2.5 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 ES2.5 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 ES2.5.
Create a space from an existing space or template: Create a space in Content Services ES2.5, 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.
View contents of a specified space: Retrieve a list of files and spaces that are present in the specified space.
Delete content or a space: Delete specified content or a space and its related metadata. When you delete a space, all of its contents are also
deleted. 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 of its contents are also copied.
If the target location already contains a space with the same name, the new space is named Copy of [space name].
Store content: Store or update content and its metadata in the Content Services ES2.5 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 also moved.
Retrieve content: Retrieve specified content and its related metadata.
Import content: Add content that is stored in a ZIP file or an ACP file into the repository. An ACP file is created when you export content
from Adobe LiveCycle Contentspace ES2.5. The original hierarchical structure of content is preserved in the new location.
Working with associations
An association is a way to tie together two or more content items in the repository. The following types of associations are available in
LiveCycle Workbench:
ADOBE LIVECYCLE ES2.5
Document Management Service
37
LiveCycle ES2.5 Services
• 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 by 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 that are 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.
Remove aspects from content: Delete specific aspects from content. Aspects are the attribute collections that are applied to content.
Manage access permissions for content: Maintain a list of users and groups that have access to content.
Review access permissions for content: Get a list of access permissions for the specified content. For each user and group, the list specifies
the type of access permission and the access status.
Considerations for LiveCycle Contentspace ES2.5
Users can open and fill forms from within LiveCycle Contentspace ES2.5 by executing these steps:
1
Browsing to the space where the form is located.
2
Viewing the details for the file
3
Clicking Fill Form.
When the user submits the form, the data is extracted and saved as an XML file. When using LiveCycle Designer ES2.5 to design an XDP
form that will be accessed in this way, do not include a Submit URL on the form. If you include it, the submitted form data will not be
available within Contentspace ES2.5 because the Submit URL will not be overridden.
38
11. 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.
The action 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 to identify a unique message
from others in the inbox. 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 ES2.5 that uses the service. You can accomplish the following
tasks by using the Email service:
•
Configure the Email service with default properties for connecting to an SMTP server for sending email messages. Also configure the
connection 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 9.5 Help.
You can also use the Applications and Services pages of LiveCycle Administration Console to configure default properties for this service.
(See Email service settings in LiveCycle ES2.5 Administration Help.)
39
12. 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 its 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. If a PDF document is
encrypted with a certificate, the user must decrypt the PDF document with a private key (certificate) he/she owns. The private key used to
decrypt the PDF document must correspond to the public key used to encrypt it.
Using the Encryption service
For information about developing processes that use this service, see LiveCycle Workbench 9.5 Help. For information about developing
client applications that programmatically interact with this service, see Programming with LiveCycle ES2.5.
You can use the Applications and Services pages of LiveCycle Administration Console to configure default properties for this service. (See
Encryption service settings in LiveCycle ES2.5 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 must 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 tasks that the users who receive the document
can do. For example, you can specify whether they can sign and fill, edit, or print the PDF document.
A password-encrypted PDF document must be unlocked before another LiveCycle ES2.5 operation, such as digitally signing the PDF
document, can be performed on it. (See “Unlocking encrypted PDF documents” on page 40.)
Note: It is recommended that you do not encrypt a document prior to uploading it to the repository. If you upload an encrypted PDF document
to the 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. Then users can open the PDF document
in Adobe Reader or Acrobat without specifying 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.
ADOBE LIVECYCLE ES2.5
Encryption Service
40
LiveCycle ES2.5 Services
• A private key, which you do not share with others.
Documents are encrypted by 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). A CA 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. Certificate authorities publish
CRLs periodically. 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 tasks that 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 ES2.5.
Note: It is recommended that you do not encrypt a document prior to uploading it to the repository. If you upload an encrypted PDF document
to the repository, it cannot decrypt the PDF document and extract the XDP content.
A password-encrypted PDF document must be unlocked before another LiveCycle ES2.5 operation, such as digitally signing the PDF
document, can be performed on it. (See “Unlocking encrypted PDF documents” on page 40.)
Removing certificate-based encryption
You can use the Encryption service to remove certificate-based encryption from a PDF document. Then 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. Attempting to perform a
LiveCycle ES2.5 operation on an encrypted PDF document generates an exception. After you unlock an encrypted PDF document, you can
perform one or more operations on it, such as digitally signing it by 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. (See “Rights Management Service” on
page 111.)
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
ADOBE LIVECYCLE ES2.5
Encryption Service
41
LiveCycle ES2.5 Services
Considerations for the Encryption service
Any combination of encrypting, certifying, and applying usage rights to the same document must occur in the following order. These
services must be invoked within a short-lived process:
1
Apply encryption (Encryption service) or 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.
2
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, therefore removing the usage rights from the document.
3
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.
Also, 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.
42
13. 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 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 that is gathered as a result of executing a script and transfer data to the LiveCycle ES2.5 server
• Provide all context data for use during the execution of a script
For information about developing processes that use this service, see LiveCycle Workbench 9.5 Help.
You can use the Applications and Services pages of LiveCycle Administration Console to configure default properties for this service. (See
LiveCycle ES2.5 Administration Help.)
43
14. FTP Service
The FTP service enables processes to interact with an FTP server. FTP service operations can retrieve files from the FTP server, place 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 that uses the service. You can accomplish the
following tasks by 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 ES2.5 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 ES2.5 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 9.5 Help.
You can use the Applications and Services pages of LiveCycle Administration Console to configure default properties for this service. (See
FTP service settings in LiveCycle ES2.5 Administration Help.)
Considerations for the FTP service
Consider these factors when developing processes that use this service:
•
If you specify local paths to files or directories for operation properties, the paths are interpreted as being on the file system of the
LiveCycle ES2.5 server.
•
The user account used to run the LiveCycle ES2.5 server must have the required permissions to interact with the files and file locations
that service’s operations target.
44
15. File Utilities Service
The File Utilities service enables processes to interact with the file system of the LiveCycle ES2.5 server or other file systems that the server
can access.
Files are commonly used to integrate with various systems. A process can use the File Utilities service to read or write files in different
formats, such as XML, comma-delimited text, and PDF. A process can also use this 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 that uses the service. You can accomplish
the following tasks by using the File Utilities service:
•
•
•
•
•
•
•
•
•
Delete a file
Determine whether a file exists
Find files and directories in the file system
Determine whether a path is absolute
Determine whether a path represents a directory or a file
Determine whether a path represents a hidden file
Creates a directory or a directory tree
Save data as files on the file system
Read information from files and save it in one of these process data formats:
• Document
• String
• XML document
• Write information from these process data formats to files:
• Document
• String
• XML document
• Manipulate directories and files on the file system
For information about developing processes that use this service, see LiveCycle Workbench 9.5 Help.
Considerations for the File Utilities service
Consider these factors when developing processes that use this service:
ADOBE LIVECYCLE ES2.5
File Utilities Service
45
LiveCycle ES2.5 Services
•
If you specify local paths to files or directories for operation properties, the paths are interpreted as being on the file system of the
LiveCycle ES2.5 server.
•
The user account used to run the LiveCycle ES2.5 server must have the required permissions to interact with the files and file locations
that the service’s operations target.
46
16. Form Augmenter Service
The Form Augmenter service enables a PDF form or Acrobat form to function within LiveCycle Workspace ES2.5. For example, the Form
Augmenter service operations are useful in custom render and submit services for Form, Document Form, or xfaForm variables.
A form that is enabled for Workspace ES2.5 has the following characteristics:
•
Buttons will appear hidden when displayed in Workspace ES2.5. 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 ES2.5, which acts as an intermediary between the LiveCycle ES2.5 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 ES2.5. The PDF form must be created in LiveCycle Designer ES2.5 or Acrobat 7.0.5 or
later.
•
Enable a PDF form for offline use in Workspace ES2.5. The PDF form must be created in Designer ES2.5. You cannot specify an Acrobat
form.
•
Add data fields to the form data, which enables a PDF form created in Designer ES2.5 to be used offline in Workspace ES2.5. You cannot
specify an Acrobat form.
• Retrieve a value from a field on a form. The PDF form must be created within Designer ES2.5 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 9.5 Help.
47
17. 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 ES2.5) 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 can also contain form field data and an embedded PDF file.
An XDP file that is generated by Designer ES2.5 can be used only if it carries an embedded base-64-encoded PDF document.
Using the Form Data Integration service
You can import and export data by using XFDF (Acrobat forms only) or XDP (XML forms only). For example, to import data into a form
created in Designer ES2.5, create a valid XDP XML data source. Consider the following example mortgage application form.
ADOBE LIVECYCLE ES2.5
Form Data Integration Service
48
LiveCycle ES2.5 Services
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 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 9.5 Help. For information about developing
client applications that programmatically interact with this service, see Programming with LiveCycle ES2.5.
You can use the Applications and Services pages of LiveCycle Administration Console to configure default properties for this service. (See
LiveCycle ES2.5 Administration Help.)
49
18. 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 ES2.5. Form authors develop a single form design that the Forms service renders as PDF, HTML, or
as Guides in a variety of browser environments that support Adobe Flash Player.
The Forms service renders interactive PDF 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.
When an end user requests a form, a client application such as a Java servlet sends the request to the Forms service. The Forms service
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. It 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, 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 resultant 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, SWF, 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. However, a PDF form delivers all the pages at once. In Designer ES2.5, the form
author can script the current page number in the form design. The Forms service can merge one page of data that is submitted at a time
or merge only the single page into the form design.
•
Supports subforms created in Designer ES2.5. The Forms service adds extra fields and boilerplate as a result of merging the form design
with data or as a result of scripting. With HTML, the added subforms can grow to unlimited page lengths. With PDF, the added subforms
paginate at the page lengths that are 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 fragment. When a form author updates a fragment, all forms that contain a reference to the fragment
reflect the changes (when the form is rerendered).
•
•
•
Validates data entry by performing calculations, accessing databases, or enforcing business rules on field-level data.
•
Maintains the state of any pass-through data that the application passed in. 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 ES2.5 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.
Renders forms with file attachments. Also, 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.
For information about initially setting up this service, see Configuring LiveCycle Forms ES2.5 in LiveCycle ES2.5 Administration Help.
ADOBE LIVECYCLE ES2.5
Forms Service
50
LiveCycle ES2.5 Services
About form types
Before you start working with the Forms service, it is recommended that you understand the various form types that the Forms service uses.
This section describes these form types.
Forms that have a flowable layout
A form that has a flowable layout changes based on data prepopulation or through user interaction. A form design that adjusts to accommodate data specifies a set of layout, presentation, and data capture rules. Such a form design includes 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.
A form that has a flowable layout is 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. When a form/form design with a flowable layout is rendered as a PDF form, intelligent page
breaks are generated.
Forms that have a fixed layout
A form that have a fixed layout 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 the form contains more data than it can hold, it cannot expand to accommodate the excess data.
Server-side forms
A server-side form can be a data-driven 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. This causes the field to dynamically replicate so that each data
value is displayed within the form.
Fields that are dynamically added to a form are contained in structures called subforms, which are located within the form design. An
example of a server-side 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 forms
A client-side form is typically used to collect data from end users by having them 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 LiveCycle ES2.5. An example of a client-side form is one that contains fields that where users can 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).
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.
ADOBE LIVECYCLE ES2.5
Forms Service
51
LiveCycle ES2.5 Services
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
Forms service operation. This 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.
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 it to the client No action
web browser.
Internet Explorer, Mozilla, Netscape Navigator, and Opera
browsers perform these actions:
No action
No action
No action
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
Note: These actions occur only if the form is rendered as
HTML.
Views the form as either PDF or 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.
ADOBE LIVECYCLE ES2.5
Forms Service
52
LiveCycle ES2.5 Services
Buttons are the most common way to initiate logic contained in form design scripts. Placing a button on a form design in Designer ES2.5
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 an invalid value into a field, they may
have to correct the value before the data can be submitted A form can also contain a calculate button. A calculate button can perform calculations on data and update the form.
Submit button
A button can submit form data as 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 submits only URL-encoded namevalue 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 ES2.5.
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.
This 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
A user enters data into form fields and clicks a submit No action
button. This action initiates a submit operation.
Forms service actions
No action
Client validations marked run on client are executed.
Browser performs an HTTP post to the target URL.
(This value is defined either in Designer ES2.5 or by
the targetURL parameter used during the rendition call to the Forms service).
No action
No action
No action
Creates a FormServiceClient object, invokes the processNo action
FormSubmission method, and passes 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.
No action
Verifies that the Forms service returned a processing state No action
value of Validate. In this situation, the result is returned
to the client browser so that the user can correct the
mistake.
ADOBE LIVECYCLE ES2.5
Forms Service
53
LiveCycle ES2.5 Services
User actions
Client application actions
Forms service actions
For forms that are displayed as HTML, end users see
the form that contains the same data, calculations,
and list of errors to correct before resubmitting.
No action
No action
No action
No action
If the validation process succeeds, the processing
state value is set to Submit.
No action
Verifies that the Forms service returns a processing state
value of Submit.
No action
For Guides, end users see the form that contains 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.
Acknowledges that all form processing is complete.
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. For example, a new
form can be displayed.
No action
No action
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 located
in the form design. The result is rendered back to the web browser with the results displayed in the form. (See “Calculating form data” on
page 63).
This table summarizes the interaction between a client application and the Forms service when a user 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
No action
Creates a FormsServiceClient object and
invokes the processFormSubmission
method.
No action
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.
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 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.
ADOBE LIVECYCLE ES2.5
Forms Service
54
LiveCycle ES2.5 Services
User actions
Client application actions
Forms service actions
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
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
returned 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 it to the client
web browser.
No action
Views calculation results that are displayed in the form.
No action
No action
Using the Forms service
For information about developing processes that use this service, see LiveCycle Workbench 9.5 Help. For information about developing
client applications that programmatically interact with this service, see Programming with LiveCycle ES2.5.
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 to send information back to the Forms service. Adobe Reader® or Acrobat
must be installed on the computer hosting the client web browser for an interactive PDF form to be visible.
1
Before you can render a form using the Forms service, you must create a form design. Typically, a form design is created in Designer ES2.5
and is saved as an XDP file.
ADOBE LIVECYCLE ES2.5
Forms Service
55
LiveCycle ES2.5 Services
Note: In LiveCycle 7.x releases, the Forms service created non-tagged PDF files by default. In LiveCycle ES2.5, the Forms service creates tagged
PDF files by default.
Rendering forms at the client
Use the client-side rendering capability of Acrobat or Adobe Reader to optimize the PDF content delivery and improve the Forms service’s
ability to handle network load 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.
Use the client-side rendering capability of Acrobat or Adobe Reader to optimize the PDF content delivery and improve the Forms service’s
ability to handle network load
Rendering Guides
Guides are based on Adobe Flash® technology and provide a visually engaging and streamlined method for capturing data from a user.
Guides can reduce data entry errors through improved usability by logically grouping or simplifying information presented to a user at a
given time.
In LiveCycle ES2.5, the Forms service can only render legacy form designs created in LiveCycle Designer ES (version 8.x) to form guides.
The Forms service is not used to render LiveCycle ES2.5 guides, which you create in Workbench using Guide Builder. For information on
how to create and render LiveCycle ES2.5 guides, see Getting Started with Guides.
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. Rendering a form as HTML is beneficial. The reason is that the computer that the client web browser is located
on does not require Adobe Reader, Acrobat, or Flash Player (for 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.
For a form design, it is recommended that the guidelines for layout considerations for HTML forms be followed. This action overcomes text
shift issues in a rendered HTML form. (See Using LiveCycle Designer ES2.5 > Creating Forms for LiveCycle Forms ES2.5 > Creating HTML
forms > Layout considerations for HTML forms in LiveCycle Designer ES2.5 Help.)
ADOBE LIVECYCLE ES2.5
Forms Service
56
LiveCycle ES2.5 Services
Using Forms IVS to test forms with their intended data sets
The Forms Installation and Verification Sample (Forms IVS) is a sample application for testing your forms with their intended data sets.
Forms IVS uses the renderPDFForm, renderHTMLForm, and processFormSubmission operations that the Forms service exposes.
Forms IVS must be deployed before you can use it. Administrators can use LiveCycle Configuration Manager to deploy Forms IVS. They
can also manually deploy it. (See the LiveCycle ES2 installation guides, such as Installing and Deploying LiveCycle ES2 for JBoss.)
To open the Forms IVS application, navigate to http://[server_name:port_number]/FormsIVS.
To specify characteristics about your job and to submit your job, click the Test Forms link on the Adobe LiveCycle Forms ES2.5 banner. Here
are some of the settings you can specify from the Test Forms window:
• Form to test
• Data file to merge with the form
• Output format
• Performance test selection
To change settings that Forms IVS uses, click the Preferences link on the Adobe LiveCycle Forms ES2.5 banner. Here are some of the settings
you can specify from the Preferences window:
•
•
Options passed to the Forms ES2.5 service
Locations that Forms IVS obtains form, data, XDC, and companion files from. The locations can be URLs, a repository location, or an
absolute reference from a folder on the computer that hosts LiveCycle ES2.5. Repository locations can be specified as repository:/ or
repository:///.
• Application root and endpoints
• Administrator credentials
• Options for rendering the form
To view or delete files in the root directory, click the Maintenance link on the Adobe LiveCycle Forms ES2.5 banner. You can delete only the
files you added to Forms IVS. You cannot delete files that were installed with Forms IVS.
To see the complete Help for Forms IVS, click the Help link on the Adobe LiveCycle Forms ES2.5 banner.
Forms service options
Rendering forms based on fragments
The Forms service can render forms that are based on fragments that you create using Designer ES2.5. 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 can include an address
block or legal text.
Using fragments simplifies and speeds the creation and maintenance of large numbers of forms. When creating a form, 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 ES2.5 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. Use conditional statements to determine which subform from within the set appears in the
delivered form. For example, each subform in a set can include information for a particular geographic location. Also, the subform that is
displayed can be determined based on the location of the user.
ADOBE LIVECYCLE ES2.5
Forms Service
57
LiveCycle ES2.5 Services
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 in
Designer ES2.5. Fragments cannot be created from scripts that are properties of other objects, such as event scripts like validate, calculate,
or initialize.
Here are advantages of using fragments:
Content reuse: You can use fragments to reuse content in multiple form designs. 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. All XDP forms that reference the fragment will reflect the changes.
For example, a common element across many forms may be an address block that includes a drop-down list object for the country. 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, resave the form in Designer ES2.5.
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 ES2.5 can develop and share fragments that take advantage of scripting and dynamic
properties. Form authors can use the fragments to lay out form designs and to ensure that all parts of a form have a consistent appearance
and functionality across multiple forms multiple people designed.
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 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.
To apply usage rights to a form, the Reader Extensions service must be part of your LiveCycle installation. Also, you must have a valid
credential that permits 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 106.)
Note: To render a form that contains usage rights, use an XDP file as input, not a PDF file. If you use a PDF file as input, the form is still rendered;
however, it will not be a rights-enabled form.
ADOBE LIVECYCLE ES2.5
Forms Service
58
LiveCycle ES2.5 Services
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 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 perform the following tasks:
• 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
Form data is submitted to the Forms service as either XML or PDF data. This option is set in Designer ES2.5. A form that is submitted as
XML lets you 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 it 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 ES2.5
Forms Service
59
LiveCycle ES2.5 Services
The following illustration shows corresponding XML data that is retrieved by using the Forms service.
The form design must be configured correctly in Designer ES2.5 in order for data to be submitted as XML data. To properly configure it to
submit XML data, ensure that the Submit button on the form design is set to submit XML data. (See LiveCycle Designer ES2.5 Help.)
Also, you must specify the correct content type to handle XML data. For example, specify application/vnd.adobe.xdp+xml. The content
type must match the submitted form data. You can also specify multiple content type values, such as the following value, 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 browser, the
user fills an interactive form and submits it back as PDF data. When the Forms service receives the PDF data, the service can send it 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.
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 the form is then rendered to the user. As a result, the user can 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 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).
ADOBE LIVECYCLE ES2.5
Forms Service
60
LiveCycle ES2.5 Services
• An arbitrary XML data source that contains name/value pairs matching the form’s field names.
An XML element must exist for every form field 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 that the XML elements are displayed in if all XML elements are specified.
When you prepopulate a form that already contains data, specify the data that is already displayed within the XML data source. Assume that
a form containing 10 fields has data in 4 fields. Next, assume that you want to prepopulate the remaining 6 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 6 elements, the original 4 fields
are empty.
For example, to prepopulate a confirmation form, you must create an XML data source containing three XML elements that match the three
form fields. 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 in the form design. This step is shown in the following XML code.
<Untitled>
<FirstName>
<LastName>
<Amount>
</Untitled>
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>
After you prepopulate the confirmation form with this XML data source and render the form, data values that you assigned to the XML
elements are displayed. The displayed data values are shown in this illustration.
Prepopulating forms with a flowable layout
Forms with a flowable layout are useful to display an undetermined amount of data to users. The layout of the form adjusts automatically to
the amount of data that is merged. Therefore, predetermining a number of pages is not required as with a form with a fixed layout.
A form with a flowable layout is typically populated with data that is obtained during run time. As a result, you can prepopulate a form by
creating an in-memory XML data source and placing the data directly into the data source.
ADOBE LIVECYCLE ES2.5
Forms Service
61
LiveCycle ES2.5 Services
The following illustration shows an example of a purchase order form with a flowable layout.
A. Represents the dynamic portion of the form. B. Represents the form’s header data.
Note: Forms can be prepopulated with data from other sources, such as an enterprise database or external applications.
Understanding data subgroups
An XML data source is used to prepopulate a form. An XML data source that is used to prepopulate a form with a flowable layout contains
repeating data subgroups. The following XML code shows the XML data source used to prepopulate the 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>
ADOBE LIVECYCLE ES2.5
Forms Service
62
LiveCycle ES2.5 Services
<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>
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 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 located
in the form design that the purchase order form is based on. If the name of the data subgroup’s parent XML element and the subform do not
match, a server-side form is not prepopulated.
Each data subgroup must contain XML elements that match the field names in the subform. The detail subform in the form design
contains the following fields:
•
•
•
•
txtPartNum
txtDescription
numQty
numUnitPrice
ADOBE LIVECYCLE ES2.5
Forms Service
63
LiveCycle ES2.5 Services
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, 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 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 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 lets a user calculate data:
•
The user accesses an HTML page named StartLoan 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 fields and clicks the Calculate button. The form is sent to the CalculateData Java Servlet where
the script is executed. The form is returned 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. (See “Handling submitted forms” on page 58.)
The following illustration shows the application’s logic flow.
The steps in the diagram are as follows:
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. Rendering a form
containing a script that is configured to run on the server differs from rendering a form that does not contain a script. The difference is
that you must specify the target location that is 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.
ADOBE LIVECYCLE ES2.5
Forms Service
64
LiveCycle ES2.5 Services
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.
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. The script adds values that a user enters into the first two
fields and displays the result in the third field.
A. A field named NumericField1 B. A field named NumericField2 C. A field named NumericField3
The syntax of the script 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 and clicks the Calculate button, 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 ES2.5 Help.
Considerations for the Forms service
When working with the Forms service, certain considerations are 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
Ensuring fonts are available to LiveCycle ES2.5
ADOBE LIVECYCLE ES2.5
Forms Service
65
LiveCycle ES2.5 Services
Planning your form design
Creating application logic by using the Forms service is only one aspect of creating a client application. The Forms service requires form
designs that are typically created in Designer ES2.5 (forms can be created in Acrobat as well). Form designs are XML templates that are saved
as either XDP files or PDF files. Depending on the type of input, the Forms service outputs forms that are displayed as PDF or HTML forms.
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
Input
PDF
A form design saved as an .xdp file
Output
A form displayed as PDF
Forms service
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
The first step in planning your application is to determine the output format of the forms. Save the form design in one of the following ways:
•
•
As an XDP file to have the Forms service output a form displayed as PDF or HTML.
As a PDF or XDP to have the Forms service output PDF only.
Creating form designs for the Forms service
Behavioral differences exist between form designs that are used to render PDF and HTML. Form designs rendered as PDF are viewed using
Acrobat or Adobe Reader.
If you are rendering a form as HTML, some client devices (for example, older browsers) do not provide the same support level for individual
object properties. To create a single form design that reduces these limitations, follow this process:
1
To determine how objects behave in a particular client device, see the Transformation Reference.
2
If you are designing a form with a fixed layout and want to output the form as HTML, enable transformation caching. (See
LiveCycle Designer ES2.5 Help.)
3
When creating a form design, try to work around 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.
ADOBE LIVECYCLE ES2.5
Forms Service
66
LiveCycle ES2.5 Services
5
Read "Creating Accessible Forms" in LiveCycle Designer ES2.5 Help 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 you include in a form design must
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 available only 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 by using Designer ES2.5 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 located on the form design. The caption that is displayed on a
command button label indicates the function of the button to the end user. When a user clicks a button, the form-related processing is
prompted by the script that is associated with the button. Typically, a button initiates either a submit operation or a calculate operation.
Buttons are the most common way to initiate logic that is contained in form design scripts. Placing a button on a form design in Designer
ES2.5 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 an incorrect value, the user
may have to correct the value before the form data can be submitted. 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 before a submit operation.
Rendering forms that contain images
When rendering forms with data that contains references to images, the images may not be displayed properly 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.
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 Forms IVS application to render a form that contains a secured image, an exception may occur.
To resolve this issue, ensure that the J2EE application server is started with the same operating system user name and password values used
to add the client side. After you perform this task, the Forms service can access the credential that is 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 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, rights-enabled PDF form, or 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 or
renderPDFFormWithUsageRights operations within in a process created in Workbench, create a variable of type PDFFormRenderSpec.
Then, using the setValue operation, set /process_data/pdfFormRenderSpecVar/object/@debugEnabled to true. Similarly, for the
renderHTMLForm operation, use a variable of type HTMLRenderSpec.
ADOBE LIVECYCLE ES2.5
Forms Service
67
LiveCycle ES2.5 Services
Verifying fonts are available to LiveCycle ES2.5
Ensure that fonts that are available within a form are available for use on the server hosting LiveCycle ES2.5. For example, consider the
following scenario. A form author adds a font to the font directory that Designer ES2.5 uses and creates a form on a separate computer. For
the Forms service to use that font, ensure that the font is deployed on the J2EE application server that LiveCycle is installed on. Otherwise,
the font cannot be used. You can use LiveCycle Administration Console to deploy fonts.
Note: For information about setting up fonts for the Output service, see Specifying fonts to embed in LiveCycle ES2.5 Administration Help.
68
19. Generate PDF Service
The Generate PDF service converts native file formats to PDF. It also converts PDF to other file formats and optimizes the size of PDF
documents.
The Generate PDF service uses native applications to convert the following file formats to PDF. Unless otherwise indicated, only the
German, French, English, and Japanese versions of these applications are supported. Windows only indicates support for only Windows
Server® 2003 and Windows Server 2008.
•
Microsoft Office 2003 and 2007 to convert DOC, DOCX, RTF, TXT, XLS, XLSX, PPT, PPTX, VSD, MPP, MPPX, XPS, and PUB
(Windows only)
Note: Acrobat® 9.2 or later is required to convert Microsoft XPS format to PDF.
•
•
•
Autodesk AutoCAD 2005, 2006, 2007, 2008, and 2009 to convert DWF, DWG, and DXW (English only)
Corel WordPerfect 12 and X4 to convert WPD, QPW, SHW (English only)
OpenOffice 2.0, 2.4, 3.0.1, and 3.1 to convert ODT, ODS, ODP, ODG, ODF, SXW, SXI, SXC, SXD, DOC, DOCX, RTF, TXT, XLS, XLSX,
PPT, PPTX, VSD, MPP, MPPX, and PUB
Note: The Generate PDF service does not support the 64-bit versions of OpenOffice.
•
Adobe Photoshop® CS2 to convert PSD (Windows only)
Note: Photoshop CS3 and CS4 are not supported because they do not support Windows Server 2003 or Windows Server 2008.
• Adobe FrameMaker® 7.2 and 8 to convert FM (Windows only)
• Adobe PageMaker® 7.0 to convert PMD, PM6, P65, and PM (Windows only)
• Native formats supported by third-party applications (requires development of setup files specific for the application) (Windows only)
The Generate PDF service converts the following standards-based file formats to PDF.
• Video formats: SWF, FLV (Windows only)
• Image formats: JPEG, JPG, JP2, J2Kì, JPC, J2C, GIF, BMP, TIFF, TIF, PNG, JPF
• HTML (Windows, Sun™ Solaris™, and Linux®)
The Generate PDF service converts PDF to the following file formats (Windows only):
• Encapsulated PostScript (EPS)
• HTML 3.2
• HTML 4.01 with CSS 1.0
• DOC (Microsoft Word format)
• RTF
• Text (both accessible and plain)
• XML
• PDF/A-1a that uses only the DeviceRGB color space
• PDF/A-1b that uses only the DeviceRGB color space
• PDF/E-1 that uses only the DeviceRGB color space
The Generate PDF service requires that you perform these administrative tasks:
•
•
•
Install required native applications on the computer hosting LiveCycle ES2.5
Install Adobe Acrobat Professional or Acrobat Pro Extended 9.2 on the computer hosting LiveCycle ES2.5
Perform post-installation setup tasks
ADOBE LIVECYCLE ES2.5
Generate PDF Service
69
LiveCycle ES2.5 Services
These tasks are described in Installing and Deploying LiveCycle ES2 Using JBoss Turnkey.
Using the Generate PDF service
When converting to PDF and other types of files, you can specify the settings to apply to the resulting document. Here are the parameters
you can use to specify these options:
•
PDF settings: This parameter provides the name of the Adobe PDF settings to use for the conversion. The named settings are defined
on the LiveCycle Administration Console. The console is pre-configured with several Adobe PDF settings. The names of these settings
are locale-specific. On English installations, these names include High Quality Print, PDFA1b 2005 CMYK, and Press Quality.
If the Input Settings Document parameter provides a value, this parameter is ignored. If this parameter and the Input Settings Document
parameter are both null, this operation uses the default file type settings instance that is defined on the LiveCycle ES2.5 server.
•
Security settings: This parameter provides the name of the security settings to use for the conversion. The named settings are defined
on the LiveCycle Administration Console. On English installations, the console is pre-configured with only the No Security security
settings.
If the Input Settings Document parameter provides a value, this parameter is ignored. If this parameter and the Input Settings Document
parameter are both null, this operation uses the default security settings instance that is defined on the LiveCycle ES2.5 server.
•
File type settings: This parameter provides the name of the file type settings instance that specifies how to convert specific types of file
formats. You can create custom versions of these settings by using the LiveCycle Administration Console.
If the Input Settings Document parameter provides a value, this parameter is ignored. If this parameter and the Input Settings Document
parameter are both null, this operation uses the default file type settings instance that is defined on the LiveCycle ES2.5 server.
•
Input Settings Document: An XML file containing conversion settings, including Adobe PDF settings and security settings. The Input
Settings Document can contain multiple sets of settings. This operation uses only the default sets. (See LiveCycle ES2.5 Generate PDF
Conversion Settings Reference.)
•
Metadata information to embed in the generated PDF document. Metadata contains information such as the author of the document,
the subject, and keywords to associate with the document. Only UTF-8 encoded Adobe Extensible Metadata Platform (XMP) metadata
is supported. For information about the format and specifications, see the Extensible Metadata Platform (XMP) page at the Adobe
website.
On the LiveCycle PDF Generator ES2.5 web pages in the LiveCycle Administration Console, you can designate one instance of each type of
settings as the default. (See LiveCycle ES2.5 Administration Help.)
The Generate PDF service supports multi-threaded file conversion using Microsoft Office or OpenOffice. To configure your system to use
this feature, click the User Accounts link to provide the user credentials for these applications. (See Enabling multi-threaded file conversions
for OpenOffice, Word, and PowerPoint documents in LiveCycle ES2.5 Administration Help.)
For information about developing processes that use the Generate PDF service, see LiveCycle Workbench 9.5 Help. For information about
developing client applications that programmatically interact with this service, see Programming with LiveCycle ES2.5.
Note: The PDFG Network Printer (IPP printer) is a feature of the Distiller service. You can use PDFG Network Printer to submit PostScript,
EPS, or PRN conversion jobs to the Distiller service (see “Distiller Service” on page 32). You cannot use the PDFG Network Printer to submit
conversion jobs to any of the Generate PDF services.
Converting native file formats to PDF
The Generate PDF service’s CreatePDF2 operation uses applications to convert native file formats to PDF:
•
•
“Using Microsoft Office to convert file formats to PDF” on page 70
“Using OpenOffice to convert file formats to PDF” on page 70
ADOBE LIVECYCLE ES2.5
Generate PDF Service
•
•
70
LiveCycle ES2.5 Services
“Using other applications to convert file formats to PDF” on page 71
“Adding support for other applications to convert native file formats to PDF” on page 71
Using Microsoft Office to convert file formats to PDF
The Generate PDF service’s CreatePDF2 operation can use the following Microsoft Office applications to convert Microsoft Office file
formats to PDF:
• Office Word (DOC, DOCX, RTF, TXT)
• Office Excel (XLS, XLSX)
• Office PowerPoint (PPT, PPTX)
• Office Visio (VSD)
• Project (MPP, MPPX)
• Office Publisher (PUB)
• Office Document Writer (XPS)
File type settings specify how each type of Microsoft Office file format is converted to PDF. Here are examples of those settings:
• Excel settings include fitting worksheets to a single page and running macros automatically.
• PowerPoint settings include converting footnote and endnote link, and converting displayed comments to notes in PDF.
• AutoCAD settings include flattening layers in PDF and creating PDF/E-1 compliance.
Here are examples of settings that apply to Microsoft Office applications:
•
Option of using OpenOffice as a fallback converter. If the Generate PDF service cannot successfully convert the file using the corresponding Microsoft Office application, it converts the file using OpenOffice.
• Conversion to PDF/A-1a compliance.
The Generate PDF service can use multiple instances of Microsoft Office to convert Microsoft Office files. This capability is called multithreaded conversion. Compared to using a single instance of Microsoft Office applications, multi-threaded conversion can significantly
increase the rate at which this service converts Microsoft files. Support for multi-threaded conversion using Microsoft Office requires the
post-installation setup tasks described in Installing and Deploying LiveCycle ES2 Using Turnkey.
Note: The Generate PDF service does not support multi-threaded conversion using Microsoft Excel, Microsoft Publisher, Microsoft Visio, or
Microsoft Project. This constraint is caused by limitations in Microsoft Office and Microsoft Project.
Support for fallback conversion is available even when multi-threaded conversion is enabled. If fallback conversion is enabled, the Generate
PDF service uses OpenOffice to convert Microsoft Office files. If OpenOffice fails, the Generate PDF service uses PDFMaker to convert
those files.
Note: When the Generate PDF service uses Microsoft Office 2003 on a 64-bit operating system to convert native files, that service cannot successfully use PDFMaker for fallback conversion.
Using OpenOffice to convert file formats to PDF
The Generate PDF service’s CreatePDF2 operation can use OpenOffice to convert many types of native file formats to PDF. It supports these
OpenOffice file formats: ODT, ODS, ODP, ODG, ODF, SXW, SXI, SXC, SXD. To support fallback conversion using Microsoft Office file
formats, this service also converts these types of files: BMP, GIF, JPEG, JPG, TIF, TIFF, PNG, JPF, JPX, JP2, J2K, J2C, JPC, HTML, HTM,
XLS, XLSX, PPT, PPTX, DOC, DOCX, RTF, TXT, WPD, PSD.
File type settings specify how each supported file format is converted to PDF. The conversion settings used with OpenOffice are not as
specific as settings used with Microsoft Office. Here are examples of the OpenOffice settings:
•
•
Lossless compression
Tagged PDF
ADOBE LIVECYCLE ES2.5
Generate PDF Service
71
LiveCycle ES2.5 Services
• Use transition effects
The file type settings can also specify that PDFMaker for Microsoft Word is used as a fallback converter. If the Generate PDF service cannot
successfully convert the file using OpenOffice, it converts it using PDFMaker for Microsoft Word.
The Generate PDF service can use multiple instances of OpenOffice to convert files. This is called multi-threaded conversion. Compared to
using a single instance of OpenOffice, multi-threaded conversion can significantly increase the rate at which this service converts
OpenOffice files. Support for multi-threaded conversion using OpenOffice requires post-installation setup tasks described in Installing and
Deploying LiveCycle ES2 Using Turnkey.
Support for fallback conversion is available even when multi-threaded conversion is enabled.
Using other applications to convert file formats to PDF
The Generate PDF service’s CreatePDF2 operation can use the following applications to convert other supported native file formats to PDF:
•
•
•
•
•
Autodesk AutoCAD (DWF, DWG, DXW)
Corel WordPerfect (WPD, QPW, SHW)
Adobe Photoshop (PSD)
Adobe FrameMaker (FM)
Adobe PageMaker (PMD, PM6, P65, PM)
Adding support for other applications to convert native file formats to PDF
You can add support for other native file formats that are not currently supported. Adding such support involves the following general steps:
•
•
•
Identifying an application that supports the native file format
Installing that application on the computer hosting LiveCycle
Creating setup files and environment variables that specify how the Generate PDF service interacts with the application to print the
native format files
For information about adding support for other native file formats, see Programming with LiveCycle ES2.5.
Converting video, images, and HTML file formats to PDF
The Generate PDF service’s CreatePDF2 operation converts video, image, and HTML file formats to PDF.
Converting video file formats to PDF
The Generate PDF service’s CreatePDF2 operation can convert SWF and FLV files to PDF files. These types of files are videos created with
Adobe Flash technology or applications created with Flex Builder. The result of this operation is a PDF document that contains a media
annotation containing the video. If you open the resulting file with Acrobat 8 or later, you can play the video.
This feature cannot be used to create PDF Portfolios Layouts. Such a layout includes a customizable ActionScript® user interface for
navigating the files in a PDF Portfolio (PDF package). For information about PDF Portfolios, see the The PDF Developer Junkie Blog on the
Adobe website.
Converting image file formats to PDF
The Generate PDF service’s CreatePDF2 operation can convert many types of image file formats to PDF. For a list of supported image
formats, see “Generate PDF Service” on page 68”.
Converting HTML to PDF
The Generate PDF service provides two operations for converting HTML files to PDF documents:
ADOBE LIVECYCLE ES2.5
Generate PDF Service
72
LiveCycle ES2.5 Services
• HtmlToPDF2 operation converts an HTML file located at a given URL.
• HtmlFileToPDF operation converts an HTML file or a ZIP file that contains HTML files and images.
You can specify how the HTML file is converted to PDF, including the following characteristics:
•
•
•
Spidering settings that specify inclusion of other HTML content referenced by the original HTML file
Page conversion settings that specify page size and margins, page orientation, header and footer content, and initial view
Document display options that specify the viewing characteristics when the PDF document is opened in a viewing application such as
Acrobat
Note: The HTML-to-PDF conversion capability requires post-deployment specification of system font folders. In particular, the primary system
font folder must contain all fonts that are used for such conversions. Alternatively, your system administrator can use LiveCycle Configuration
Manager to specify the locations of font folders. (See Installing and Deploying LiveCycle ES2 Using Turnkey.)
Converting PDF to other file formats (Windows only)
The Generate PDF service’s ExportPDF2 operation converts PDF to the many file formats. For a list of supported export file formats, see
“Generate PDF Service” on page 68”.
For information about the archive document types, see the ISO 19005-1:2005, Document management -- Electronic document file format
for long-term preservation specification, the Acrobat Developer Center, or the Adobe Acrobat Dusting Off Archives tutorial.
Note: The Generate PDF and DocConverter services both convert PDF to PDF/A-1B. For information about the DocConverter service, see
“DocConverter Service” on page 34.
Optimizing PDF files
The Generate PDF service’s OptimizePDF operation optimizes PDF files by reducing their size. The result of this conversion is PDF files
that may be smaller than their original versions. This operation also converts PDF documents to the PDF version specified in the optimization parameters.
Optimization settings specify how files are optimized. Here are example settings:
• Target PDF version
• Discarding objects such as JavaScript actions and embedded page thumbnails
• Discarding user data such as comments and file attachments
• Discarding invalid or unused settings
• Compressing uncompressed data or using more efficient compression algorithms
Optimization does not use Adobe PDF settings.
Submitting conversion jobs to the Generate PDF service
You can submit conversion jobs to the Generate PDF service by using any of the techniques described in “How developers interact with
services” on page 8”. You can also submit conversion jobs by clicking one of these links on the LiveCycle PDF Generator ES2.5 web page in
the LiveCycle Administration Console:
•
•
•
Create PDF
HTML to PDF
Optimize PDF
ADOBE LIVECYCLE ES2.5
Generate PDF Service
73
LiveCycle ES2.5 Services
You can use the web page to submit conversion jobs even if you have only non-administrative privileges on LiveCycle ES2.5. Non-administrators can access the PDF Generator ES2.5 web pages at http://server:port/pdfgui. These web pages allow only submission of conversion
jobs. (See LiveCycle ES2.5 Administration Help.)
Verifying system readiness of the Generate PDF service
The Generate PDF service provides a stand-alone system readiness tool that you can use to verify correct configuration of the service. You
can use this tool any time after initially configuring that service.
The Generate PDF service makes use of other applications, some of which require user names and passwords. As a result, configuring the
Generate PDF service is more complex than configuring other LiveCycle ES2.5 services. (See Installing and Deploying LiveCycle ES2 Using
Turnkey.)
74
20. Generate 3D PDF Service
The Generate 3D PDF service converts various 3D file formats to 3D PDF. It can also convert those 3D file formats to other 3D and 2D file
formats. Additionally, this service can reuse the results of previous conversions by supporting product lifecycle management (PLM) systems
and using cached conversion results.
Note: The Generate 3D PDF service is for Microsoft Windows® operating systems only. Acrobat Pro Extended 9.1 must be installed on the server
that is hosting LiveCycle ES2.5. No CAD applications are required to support conversion.
The Generate 3D PDF service supports 3D files produced by the following CAD applications. It can convert the supported file types to 3D
PDF or to an export file format. The file name extensions for the supported file types are shown in parentheses.
• 3DXML (3DXML)
• ACIS (SAT, SAB)
• Acrobat 3D PDF (PDF)
• Autodesk 3D Studio (3DS)
• Autodesk Inventor up to 12.x, 2009 (IPT, IAM)
• CADDS (PD, _PD, CADDS)
• CGR (CGR)
• COLLADA (DAE)
• Hewlett-Packard Graphics Library (HP, HGL, HPL, HPGL, PLT)
• Industry Foundation Classes (IFC)
• Initial Graphics Exchange Specification (IGES, IGES)
• JTOpen up to JT 9.1 (JT)
• KMZ (KMZ)
• Lattice XVL (XV3, XV0)
• OneSpace Designer V3 UP TO V2008 (PKG, SDP, SDPC, SDW, SDWC, SDA, SDAC, SDS,SDSC, SES, BDL)
• Parasolid up to 19 (X_T, X_B)
• Pro/ENGINEER (PRT, XPR, ASM, XAS, NEU)
• Siemens I-deas (MF1, ARC, UNV, PKG)
• Siemens NX up to NX 6, 2D (PRT)
• Solid Edge V19, V20, ST (ASM, PAR, PWD, PSM)
• SolidWorks up to 2009 (SLDASM, SLDPRT)
• STEP Exchange AP 203, AP 214 (STP, STEP)
• Stereo Lithography (STL)
• TTF PRC (PRC, PRD)
• UG NX
• UG NX drawings
• Universal 3D ECMA 1, ECMA 3 (U3)
• Virtual Reality Modeling Language (VRML) Worlds V1.0, V2.0 (WRL, VRML)
• Wavefront Object (OBJ)
The Generate 3D PDF service can also convert 3D PDF and supported 3D CAD files to the following 3D formats. For example, it can convert
Wavefront Object files to VRML.
ADOBE LIVECYCLE ES2.5
Generate 3D PDF Service
75
LiveCycle ES2.5 Services
• 3D PDF
• PDF/E-1
• IGES
• Parasolid
• STEP
• STL
• Universal 3D
• VRML
The Generate 3D PDF service can convert 3D PDF and 3D CAD files to these 2D formats:
• DXF
• EMF
The Generate 3D PDF service can also convert 2D CAD files to these formats:
•
•
PostScript
EMF
Using the Generate 3D PDF service
You can use this service’s operations to specify the CAD file to convert in one of these forms:
•
•
Single CAD file.
•
XML file that represents the assembly and that references the part files that are used in the 3D object. Those referenced part files can be
in native format or in PDF. PDF is a convenient cached form. The Generate 3D PDF service operations that support XML assembly
structure files can obtain the referenced parts from these locations:
CAD assembly file that references other files containing the subassemblies and parts that are used in the 3D object. Supply those other
files (all in their native format) in an array of supporting files.
• Array of supporting files supplied as an argument
• File location.
When converting to 3D PDF and other types of files, you can specify the settings to apply to the resulting document. Here are the ways you
can specify the settings to use for a conversion:
•
•
Provide the name of predefined settings on the LiveCycle PDF Generator 3D ES2.5 web page in LiveCycle Administration Console.
Provide an XML file that represents the settings. This file can represent every setting available through the PDF Generator 3D ES2.5 web
page in LiveCycle Administration Console.
One of the properties of these settings is the location of a template PDF document that contains one or more 3D annotations. When
converting 3D files to 3D PDF, the Generate 3D PDF service uses a copy of the template PDF file as a destination for the conversion results.
The service converts the 3D object into PRC format and then places the PRC object in one of the 3D annotation in the destination PDF file.
For information about developing processes that use this service, see LiveCycle Workbench 9.5 Help. For information about developing
client applications that programmatically interact with this service, see Programming with LiveCycle ES2.5.
Creating a 3D PDF using 3D conversion settings from the server
The Generate 3D PDF service’s Create3dPDF operation converts a CAD file to a 3D PDF document based on 3D conversion settings
configured on the LiveCycle ES2.5 server. For information about configuring the 3D conversion settings, see Configuring Adobe 3D PDF
Settings in LiveCycle ES2.5 Administration Help.
ADOBE LIVECYCLE ES2.5
Generate 3D PDF Service
76
LiveCycle ES2.5 Services
Creating a 3D PDF using 3D conversion settings from an XML file
The Generate 3D PDF service’s Create3dPDFCustom operation converts a CAD file to a 3D PDF document using custom 3D conversion
settings specified in an XML file. The XML file must conform to the pdfg3d_per_jobsettings.xsd schema for 3D conversion settings. (See
LiveCycle ES2.5 Generate 3D PDF Conversion Settings Reference.) If you do not specify an XML file, the default conversion setting specified
on the LiveCycle ES2.5 server is used.
Converting a 3D PDF file to PDF/E-1
You can use the Generate 3D PDF service to convert a 3D PDF document to the PDF/E-1 format or to verify that a 3D PDF document
complies with the PDF/E-1 format.
Converting a CAD file to 3D PDF or to other 3D or 2D file formats
The Generate 3D PDF service’s Convert3d operation converts a CAD file or 3D PDF document to another 3D or 2D file that uses another
format. You can specify 3D conversion settings defined on the server, or you can provide an XML file that provides 3D conversion settings.
Using cached 3D content to convert a CAD file
To expedite conversion of 3D files to PDF or to other file formats, you can use cached conversion results. The cache is 3D PDF files created
for the parts that make up the 3D assembly. This conversion is similar to “Converting a CAD file to 3D PDF or to other 3D or 2D file formats”
on page 76 except that the conversion uses cached 3D content from 3D PDF files.
Using cached 3D content use to convert a CAD file requires your application to perform the following general steps:
1
Use the Generate 3D PDF service’s Explore3D operation to explore a particular 3D object. The result is an XML file that describes the
structure in a CAD assembly. The XML file conforms to the Adobe LiveCycle Generate 3D PDF Assembly Structure Reference. This
examination does not produce a converted result.
2
Determine whether any of the files listed in the XML file are already converted to 3D PDF. If they are converted, add the paths of those
3D PDF files to the XML file.
3
Use the Generate 3D PDFservice’s Convert3dWithCache operation to convert the 3D object to 3D PDF or to another file format. The
primary input to this operation is the XML file.
Using an XML assembly structure to convert a CAD file
The Generate 3D PDF service’s Convert3dFromXML operation is similar to “Converting a CAD file to 3D PDF or to other 3D or 2D file
formats” on page 76. The exception is that the conversion uses an XML file that contains an assembly structure to determine the files to
convert. Product lifecycle management (PLM) systems are typically used to create such XML files. The PLM updates the XML file to
reference parts that are already converted to 3D output format. The XML file conforms to the Adobe LiveCycle Generate 3D PDF Assembly
Structure Reference.
Using cached 3D content and an XML assembly structure to convert a CAD file
The Generate 3D PDF service’s Convert3dWithPlm operation converts a CAD file represented by an XML file for an assembly structure and
cached 3D content. This capability is a combination of “Using cached 3D content to convert a CAD file” on page 76 and “Using an XML
assembly structure to convert a CAD file” on page 76.
Using custom functionality with 3D conversion
When you use the Generate 3D PDF service to convert CAD files, you can supply an XML file that the 3D conversion engine uses to interact
with a custom plug-in (add-in). The XML file identifies the plug-in to use and provides custom parameters that the plug-in consumes.
ADOBE LIVECYCLE ES2.5
Generate 3D PDF Service
77
LiveCycle ES2.5 Services
Here are some examples of the functionality such plug-ins can add:
• Support for additional 3D file formats
• Special information to the objects that make up the 3D file
For information about 3D conversion engine plug-ins, see your Adobe representative.
Invoking the Generate 3D PDF service
You can invoke the operations in this service by using any of the techniques described in “How developers interact with services” on page 8.
If you use watched folders to invoke this service for a 3D document that consists of a hierarchy of files (an assembly structure), submit those
files as a folder. The folder can include subfolders to represent the structure of the assembly.
You can also invoke some of the operations in this service by using the LiveCycle PDF Generator ES2.5 web pages in LiveCycle Administration Console. This use of the web pages is for demonstration and testing purposes. Using the PDF Generator ES2.5 web pages to perform
3D conversion tasks requires administrative privileges. (See LiveCycle ES2.5 Administration Help.)
78
21. 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 a stored procedure that populates the database already exists, 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 can 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 that uses the service. You can accomplish the
following tasks by 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 9.5 Help.
You can use the Applications and Services pages in LiveCycle Administration Console to configure default properties for this service. (See
JDBC service settings in LiveCycle ES2.5 Administration Help.)
Considerations for the JDBC service
The data source that is used to connect to the data server must be defined on the application server that hosts the LiveCycle ES2.5 server.
The default value is the JNDI name of the data source for the LiveCycle ES2.5 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.
79
22. JMS Service
The JMS service enables interaction with Java Message Service (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 that uses the service. You can accomplish the
following tasks by 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 9.5 Help.
You can use the Applications and Services pages in LiveCycle Administration Console to configure default properties for this service. (See
JMS service settings in LiveCycle ES2.5 Administration Help.)
Considerations for the JMS service
Consider these factors 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.
•
The JMS service must be configured 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.
Change these values if you are using a different application server to host LiveCycle ES2.5.
80
23. LCCPLM Service
The LiveCycle Connector for PLM (LCCPLM) service enables processes and applications to interact with a product lifecycle management
(PLM) system. PLM systems are designed to manage a product through its entire life cycle and integrate people, data, processes, and business
systems. A PLM object includes all data for an engineering project, including Microsoft Word documents, images, 2D drawings, and 3D
designs.
The LCCPLM service invokes corresponding methods in a PLM component, which is packaged as a service container. Install a PLM
component that interacts with your PLM system:
PLM component installed with LiveCycle ES2.5: By default the LCCPLM service interacts with a stub PLM component.
Sample PLM component: Adobe provides a sample implementation of a PLM component that uses the file system as the PLM. This
sample is not installed with the LiveCycle ES2.5 samples. Contact your Adobe representative for information:
Third-party PLM components: Contact your Adobe representative for information.
Using the service
Get data and metadata descriptor
This operation retrieves data and metadata for a specified PLM object by using its identifier. Metadata can include any field for the PLM
object that can be extracted from the PLM system. The metadata is unrelated to metadata from other sources. That is, it does not include
PDF metadata or Word metadata.
Save comments from a document
This operation saves data and comments that are associated with a PLM object. This operation consumes the data and comments as an XDP
document. The PLM client implementation can store the data and comments in the PLM system with the PLM object.
XDP is an XML grammar that provides a mechanism for packaging XFA components within a surrounding XML container. Such XFA
components can include a PDF document, comments, and XFA form data.
Form designers can create XML forms that automatically generate an XDP document when the user clicks a submit button on the form.
(See“Submit from an XDP document or from an XFA-based PDF document” on page 81.)
Save comments from string
This operation saves comments that are associated with a PLM object. This operation consumes the data and comments as an XFDF string.
The PLM client implementation can store the data and comments in the PLM system with the PLM object.
XFDF (XML Forms Data Format) is an XML grammar for representing forms data and comments that are extracted from a PDF document.
Form designers can apply submit buttons to PDF documents that automatically generate an XFDF stream. (See“Submit from a PDF
document” on page 82.)
Store PDF
This operation checks into the PLM system the PDF that was generated using a PLM object.
ADOBE LIVECYCLE ES2.5
LCCPLM Service
81
LiveCycle ES2.5 Services
Considerations for the service
Scenarios
Here is an example of a LiveCycle ES2.5 workflow that you can develop by using your PLM system with a LiveCycle ES2.5 process:
1
Obtain the files for a PLM object.
2
Create a PDF document for an entire PLM object.
3
Policy-protect the PDF document to restrict its distribution.
4
Save the PDF document with the PLM object.
5
Obtain the PDF from the PLM object.
6
Populate the PDF with metadata retrieved from the PLM.
7
Submit the PDF document to specific individuals. Those reviewers can apply comments to the PDF file.
Reviewers can use desktop tools such as Acrobat Pro Extended to compare documents and to analyze sections of the data. You can use
Acrobat Pro Extended to measure, cross-section, and calculate physical properties or three-dimensional (3D) PDF documents.
8
Save the comments with the PLM object.
Submit data and comments
The format of your review document affects how you submit data and comments. You can use these formats for your review:
•
•
•
XDP that contains an XML form (an XFA template). This format supports XFA form fields.
XFA-based PDF. This format supports XFA form fields.
PDF. This format supports only Acrobat form fields.
Submit from an XDP document or from an XFA-based PDF document
Form developers can use LiveCycle Designer ES2 to create XFA forms that automatically produce an XDP document that this method can
consume. Such forms have these characteristics:
•
Submit button that when activated sends an XDP stream to the specified destination. By default, the stream contains a datasets packet.
To also include the XFDF packet in the submitted stream, form developers specify that comments are included in the XDP stream.
•
Fields that can be populated with data supplied by another source. For example, applications can populate the fields with data obtained
from the getDataAndMetaData operation.
Here is an example of XDP data created when the user clicks the submit button that sends the XDP document.
<?xml version="1.0" encoding="UTF-8"?>
<xdp:xdp xmlns:xdp="http://ns.adobe.com/xdp/" timeStamp="2009-01-22T16:39:34Z"
uuid="361e12df-196c-4ec2-b57a-08156b2f6393">
<xfa:datasets xmlns:xfa="http://www.xfa.org/schema/xfa-data/1.0/">
<xfa:data>
<lccplmsubmitform>
<lccplmsubmitpage>
<livecycleService>http://mylcserver:8080/SubmitPdfServlet</livecycleService>
<objectId>1898.21382.38578.43955</objectId>
<myplmhost>http://myserver:7001/myplm</myplmhost>
<myplmpassword/>
<lclogin>administrator</lclogin>
<lcpassword>password</lcpassword>
<fileName>myFile.pdf</fileName>
</lccplmsubmitpage>
</lccplmsubmitform>
</xfa:data>
ADOBE LIVECYCLE ES2.5
LCCPLM Service
82
LiveCycle ES2.5 Services
</xfa:datasets>
<pdf xmlns="http://ns.adobe.com/xdp/pdf/"
href="http://myreposserver:7001/LCCPLMViewer/ViewPfServlet"/>
<xfdf xmlns="http://ns.adobe.com/xfdf/" xml:space="preserve">
<annots>
<text color="#FFFF00" creationdate="D:20090427183422+02'00'" date="D:20090427185514+02'00'"
flags="print,nozoom,norotate" icon="Comment"
name="017b34e3-d1a3-4a32-8907-b4cdd1a4879b" page="1"
rect="49.698502,32.301498,69.698502,50.301498" subject="Sticky Note" title="myUserName">
<contents-richtext>
<body xmlns="http://www.w3.org/1999/xhtml"
xmlns:xfa="http://www.xfa.org/schema/xfa-data/1.0/"
xfa:APIVersion="Acrobat:9.1.0" xfa:spec="2.0.2">
<p dir="ltr">
<span dir="ltr" style="font-size:10.0pt;text-align:left;color:#000000;fontweight:normal;font-style:normal">modified again</span>
</p>
</body>
</contents-richtext>
<popup flags="print,nozoom,norotate" open="yes" page="1"
rect="100.10701,-16.941605,280.106995,102.839996"/>
</text>
</annots>
</xfdf>
</xdp:xdp>
For more information, refer to LiveCycle Designer ES2 Help and the XDP specification within the XML Forms Architecture (XFA) Specification
Submit from a PDF document
Form developers can use Acrobat to add a Regular button to a PDF document. The button can have a script that is triggered by the click
event. The script calls the exportAsXFDFStr method to extract the data and comments from the file. It can also use the SOAP and web
services to submit the string to a URL.
When the user clicks the button, the method generates an XFDF string and invokes the server with this string.
Here is an example of the decoded string for XFDF stream. The XFDF string is base64-encoded. This stream is created when the user clicks
the submit button.
<?xml version="1.0" encoding="UTF-8"?>
<xfdf xmlns="http://ns.adobe.com/xfdf/" xml:space="preserve" >
<annots >
<text color="#FFFF00" creationdate="D:20090326165627+01'00'" flags="print,nozoom,norotate"
date="D:20090326165715+01'00'" name="3e792ddf-43a3-4194-b610-50b4486e3a64" icon="Comment"
page="1" rect="395.789001,172.511002,415.789001,190.511002" subject="Sticky Note"
title="myUserName" >
<contents-richtext >
<body xmlns="http://www.w3.org/1999/xhtml"
xmlns:xfa="http://www.xfa.org/schema/xfa-data/1.0/"
xfa:APIVersion="Acrobat:9.1.0" xfa:spec="2.0.2" >
<p dir="ltr" >
<span dir="ltr" style="font-size:10.0pt;text-align:left;color:#000000;fontweight:normal;font-style:normal" >ffddsd&#xD;&#xD;dffd&#xD;sd&#xD;&#xD;dd&#xD;</span >
</p >
</body >
</contents-richtext >
<popup flags="print,nozoom,norotate" open="yes" page="1" rect="792,70.510803,972,190.511002" />
</text >
ADOBE LIVECYCLE ES2.5
LCCPLM Service
LiveCycle ES2.5 Services
</annots >
<f href="http://myreposserver:7001/LCCPLMViewer/ViewPfServlet" />
<fields >
<field name="lccplmsubmitform[0]" >
<field name="lccplmsubmitpage[0]" >
<field name="fileName[0]" >
<value >mycadfile.CATProduct</value >
</field >
<field name="lclogin[0]" >
<value >administrator</value >
</field >
<field name="lcpassword[0]" >
<value >password</value >
</field >
<field name="livecycleService[0]" >
<value >http://mylcserver:8080/SubmitPdfServlet</value >
</field >
<field name="myplmhost[0]" >
<value >http://myserver:7001/myplm</value >
</field >
<field name="myplmuser[0]" >
<value >myUserName</value >
</field >
<field name="objectId[0]" >
<value >1898.21382.59476.64247</value >
</field >
</field >
</field >
</fields >
<ids original="1D9C55A458905E42A88ECB572F7E8C0C" modified="210B8FF4CE1B8AFFCD2E91DC39D884FF" />
</xfdf >
For more information, refer to the XML Forms Data Format Specification and the Developing Acrobat Applications Using JavaScript
83
84
24. 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 can use 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 that uses the service. You can accomplish the
following tasks by 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 9.5 Help.
You can use the Applications and Services pages in LiveCycle Administration Console to configure default properties for this service. (See
LDAP service settings in LiveCycle ES2.5 Administration Help.)
Considerations for the LDAP service
Consider these factors when developing processes that use this service:
•
•
You must configure the properties that are used to connect to the LDAP server before using the LDAP service operations.
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. Consult with your LDAP administrator for information about the directory that you are querying.
85
25. Output Service
The Output service lets you create documents in different formats, including PDF, PDF/A, laser printer formats, and label printer formats.
Laser printer formats are PostScript and Printer Control Language (PCL). The following list specifies label printer formats:
• Zebra (ZPL)
• Intermec (IPL)
• Datamax (DPL)
• TecToshiba (TPCL)
A document can be sent to a network printer, a local printer, or a file located on the file system. The Output service merges XML form data
with a form design to generate a document. The Output service can generate a document without merging XML form data into the
document. However, the primary workflow is merging data into the document. (See “Form data” on page 94.)
Note: A form design is typically created by using LiveCycle Designer ES2.5. For information about creating form designs for the Output service,
see Designing Forms for LiveCycle Output ES2.
When using the Output service to merge XML data with a form design, the result is a non-interactive PDF document. A non-interactive
PDF document does not let users enter data into its fields. In contrast, you can use the Forms service to create an interactive PDF form that
lets users enter data into its fields. (See “Forms Service” on page 49.)
The following four Output service operations are available for use within LiveCycle Workbench:
generatePDFOuput2: Merges a form design with data to generate a PDF document
generatePrintedOutput: Merges a form design with form data to generate a document to send to either a laser or a label network printer
sendToPrinter: Prints a document at the specified printer
transformPDF: Converts an interactive PDF form to a non-interactive PDF document
Note: By default, depreciated methods are not displayed in Workbench. Enable the respective option to see deprecated methods.
In addition to using Workbench, you can programmatically interact with the Output service by using the Output Service API. (See
Programming with LiveCycle ES2.5.)
Using the Output service
For information about developing processes that use this service, see LiveCycle Workbench Help. For information about invoking this
service using watched folders or email invocation, see LiveCycle ES2.5 Overview.
For information about initially setting up this service, see LiveCycle ES2.5 Administration Help.
ADOBE LIVECYCLE ES2.5
Output Service
86
LiveCycle ES2.5 Services
Creating PDF documents
You can use the Output service to create PDF document that is based on a form design and XML form data. The PDF document is a noninteractive PDF document. That is, users cannot enter or modify form data. A basic Output workflow is to merge XML form data with a
form design to create a PDF document. The following illustration shows the Output service merging a form design and XML form data to
produce a PDF document.
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. Also, 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 it to create a PDF/A document.
The PDF/A-1 specification has two levels of conformance: a and b. The difference between the two levels is that logical structure (accessibility) support is required for conformance level a but not for level b. Regardless of the conformance level, PDF/A-1 dictates that all fonts
are embedded into the generated PDF/A document.
Although PDF/A is the standard for archiving PDF documents, you can store a PDF document if it meets your business requirements.
However, a PDF document can contain content that becomes outdated. For example, a URL that references a website can become outdated
in the future. The purpose of the PDF/A standard is to establish a PDF file that has the potential for long-term endurance.
ADOBE LIVECYCLE ES2.5
Output Service
87
LiveCycle ES2.5 Services
The following illustration shows the Output service merging a form design and XML form data to produce a PDF/A document.
Note: The AIIM website has a PDF/A FAQ section at http://www.aiim.org/documents/standards/19005-1_FAQ.pdf.
Sending documents to printers
You can use the Output service to send laser print formats and label print formats to a printer. For a list of supported formats, see “Output
Service” on page 85.
Note: Label printer manufactures have devices that use different print languages. Not all Zebra printers use ZPL; therefore, ensure that your
device can support the specific print language.
The following illustration shows the Output service sending documents to network printers.
The Output service supports the following printing access mechanisms:
Direct accessible printer: A printer that is installed on the same computer is called 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.
ADOBE LIVECYCLE ES2.5
Output Service
88
LiveCycle ES2.5 Services
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 document to an LPD URI when the network has
an LPD running. This mechanism lets you route the document to any printer that is connected to the network that has an LPD running.
When using this method to send a document 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. The print server accepts print requests from client applications, processes them, and sends them to
configured printers. On the IBM 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. Print queues are
not required.
LPD: A printing protocol named Line Printer Daemon protocol or Line Printer Remote (LPR) protocol. This protocol 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 protocol does not
work if the Generate PDF service is installed and LiveCycle ES2.5 is installed on the Windows Server® 2008 operating system. This issue is
applicable only for the Windows Server 2008 operating system. In this situation, use a different printer protocol.
CIFS: The Output service supports the Common Internet File System (CIFS) printing protocol. (See “Improving the performance of the
Output service” on page 103.)
The following table lists various input values, 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.
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.
CIFS
Valid
Null
Successful print job.
ADOBE LIVECYCLE ES2.5
Output Service
89
LiveCycle ES2.5 Services
Access mechanism
Print server URI
Printer name
Result
CIFS
Invalid
Any
Output service throws an unknown error while printing using CIFS.
CIFS
Null
Any
Output service throws an exception stating that the required argument
sPrintServerUri cannot be null.
Note: To print on remote network printers on Windows, it is easier to use the CIFS protocol than a shared printer. The CIFS protocol can be used
with remote Windows print servers. (See “Improving the performance of the Output service” on page 103.)
Running a service on Windows
If you install LiveCycle ES2 by using the turnkey installation for JBoss on Windows, JBoss runs 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. If you use the Output Installation Verification Sample (Output IVS) to send a document to a network printer, the following error
message is displayed:
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. Specify a valid user name and password.
Note: This issue is applicable only when using the SharedPrinter access mechanism.
Sending the document to a network printer
You can send a document to a line printer daemon (LPD) URI when the network has an LP daemon running. You can route the document
to any printer that is connected to the network. This printer can exist on a separate computer.
After you reference XML form data and set print run-time options, you can invoke the Output service. The Output service sends the
document to a network printer. It is 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 does not print correctly. To correct this issue, 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. Read your printer’s documentation to learn how to configure your printer to handle custom sizes.
When you send a document 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).
•
You can retrieve the value for PrinterName by using 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 can occur when printing with a SharedPrinter is that the login identifier is not correct. (See “Running a service
on Windows” on page 89.)
Processing batch data to create multiple documents
The Output service can create separate documents for each record within an XML batch data source. The Output service can also create a
single document that contains all records (this functionality is the default). Assume that an XML data source contains ten records and you
instruct the Output service to create a separate document for each record (for example, PDF documents). As a result, the Output service
generates ten PDF documents.
ADOBE LIVECYCLE ES2.5
Output Service
90
LiveCycle ES2.5 Services
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.
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>
ADOBE LIVECYCLE ES2.5
Output Service
91
LiveCycle ES2.5 Services
<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>
<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.
Set PDF run-time options
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 multiple files exist, the file names are Loan0001.pdf, Loan0002.pdf, Loan0003.pdf, and so on. The documents are placed on
the server hosting LiveCycle ES2.5, not the client computer.
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, the XML element that separates data records is called LoanRecord. (Instead of setting the Record Name run-time
option, you can set Record Level by assigning it a numeric value that indicates the element level containing data records. However, you can
set only the Record Name or the Record Level; you cannot set both values. In the above XML, the record level to create multiple documents
is 2.
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 is 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 89.)
You can control whether the Output service performs incremental loading by using the PDFOutputOptionsSpec or the
PrintedOutputOptionSpec object’s setLazyLoading option. You can specify the value false, which turns off incremental loading.
ADOBE LIVECYCLE ES2.5
Output Service
92
LiveCycle ES2.5 Services
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 ES2.5:
* 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. This behavior can have
a detrimental effect on the performance of the Output service. (See “Improving the performance of the Output service” on page 103.)
Creating search rules
You can create pattern matching rules that result in the Output service examining input data and using different form designs based on the
data content. 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. The following illustration shows the Output service generating a PDF file by processing an XML data file and using one of
many form designs.
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 comprised 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, 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.
ADOBE LIVECYCLE ES2.5
Output Service
93
LiveCycle ES2.5 Services
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 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 LiveCycle Designer ES2.5 (that contain XFA streams).
• Acrobat PDF forms
If you attempt to flatten a non-interactive PDF document, an exception occurs.
Assembling custom form designs for Output
You can use the Output and Assembler services together to create a highly customized document. The Assembler service assembles an XDP
document (a form design) that is made up of multiple XDP forms and inserted fragments located in multiple XDP files. The assembled XDP
document is passed to the Output service, which creates a PDF document. The following illustration shows this workflow.
For information about creating a form design from fragments, see Guidelines for Dynamically Assembling Customized Forms and Documents.
Using Output IVS to check your Printer Description file (PDL)
Output IVS is a sample application for testing the Output service. Using this sample application, you can generate documents and test form
designs and data sets. You can also print documents by using laser and label printers.
Administrators can use LiveCycle Configuration Manager to deploy Output IVS. They can also manually deploy it. (See the LiveCycle ES2
installation guides, such as Installing and Deploying LiveCycle ES2 for JBoss.)
To open the Output IVS application, navigate to http://[server_name:port_number]/OutputIVS.
To change settings that Output IVS uses, click the Preferences link on the Adobe LiveCycle Output ES2.5 banner. Here are some of the
settings you can specify from the Preferences window:
•
Locations that Output IVS obtains form, data, XDC, and companion files from. The locations can be URLs, a repository, or an absolute
reference from a folder on the computer that hosts LiveCycle ES2.5. Repository locations can be specified as either repository:/ or repository:///.
•
•
•
Common format and options, such as whether Output IVS creates a single output stream or includes metadata.
Print options, such as duplex and number of copies.
Administrator credentials.
ADOBE LIVECYCLE ES2.5
Output Service
94
LiveCycle ES2.5 Services
To specify characteristics about your job and to submit your job, click the Test Output link on the Adobe LiveCycle Output ES2.5 banner.
Here are some of the settings you can specify from the Test Output window:
•
•
Output format, such as PDF, PDFA-1/a, and ZPL 300 DPI
File selection specifies the form, data, XDC, and companion files to use in the test. Use the companion file for these settings:
• Pattern-matching rules for mapping data elements to different templates
• Batch settings for initializing lazy loading
• Many of the other settings you can specify by using the Preferences window
• Output location information such as server file or printer name
• Issue request sends the request to the Output service
To view or delete files used by Output IVS, click the Maintenance link on the Adobe LiveCycle Output ES2.5 banner. You can delete only
the files that you added to Output IVS. You cannot delete files that are installed with Output IVS. The Maintenance window lists the form,
data, XDC, and companion files in the locations that are specified using the Preferences window. You can also use the Browse buttons to
upload files from your own computer
To see the complete Help for Output IVS, click the Help link on the Adobe LiveCycle Output ES2.5 banner.
Considerations for the Output service
Form data
The Output service accepts both a form design that is typically created in Designer ES2.5 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 in which the XML elements are displayed. The important factor is that the XML
elements are specified with corresponding values.
ADOBE LIVECYCLE ES2.5
Output Service
95
LiveCycle ES2.5 Services
Consider the following example loan application form.
To merge data into this form design, create an XML data source that corresponds to the form. The following XML represents an 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>
ADOBE LIVECYCLE ES2.5
Output Service
96
LiveCycle ES2.5 Services
</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. The Output service can render
PDF documents with XFA streams (that is, forms created in Designer ES2.5) into laser and label formats. If the PDF document is signed,
certified, or contains usage rights (applied using the Reader Extensions service), it cannot be rendered to these print formats.
•
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.
Signature fields
If a form design contains a signature field and you set the renderAtClient run-time option to true, an unsigned signature field is not
retained in the resultant PDF document. However, if this run-time option is set to false, an unsigned signature field is retained in the
resultant PDF document.
Flattening a digitally signed PDF document
If you try to flatten an interactive XFA PDF document that contains a signed signature field and set the renderAtClient run-time option
to true, the resultant PDF document is not flattened. That is, the document remains interactive and 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 that uses the Email service. A process represents a business process that you
are automating. (See LiveCycle Workbench 9.5 Help.)
Maximizing throughput
LiveCycle Output ES2.5 can process large XML data files that contain many records. You can instruct the Output service to create an output
file for each record or a single output file that contains all records. (See “Processing batch data to create multiple documents” on page 89.)
Throughput limitations are not discreet and vary depending of the complexity of the form design, available memory, options chosen, and
other activity. Errors that are generated when such a limitation is reached can identify lack of memory as being the problem. Be aware of
this limitation, and use the Output service within number guidelines for safe page generation.
For a medium complexity form 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 ES2.5
Output Service
97
LiveCycle ES2.5 Services
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
Select tagging for PDF only if it is required; tagged files are substantially larger than non-tagged files and take longer to render. PDF/A-1a
is always tagged and PDF/A-1b is not tagged. For PCL printing, the use of Microsoft 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, 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 the memory is available to the Java application server
heap. For information about changing the time-out value, see LiveCycle ES2.5 Administration Help.
When processing a large record or one large document case, throughput is 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 in this manner:
<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 from label size to label size.
It is recommended that you keep the 0.25-inch margin or reduce it. However, it is recommended that you do not increase the nonprintable
margin. Otherwise, information in the printable area does not print properly.
Always ensure that you use the correct XDC file for the printer. For example, avoid choosing an XDC file for a 300-dpi printer and sending
the document 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 ES2.5 Help.
Working with fonts
The following topics discuss how the Output service handles fonts within a generated document:
•
•
•
Ensuring that fonts are available to LiveCycle ES2.5
Using printer-resident fonts
Font mapping
ADOBE LIVECYCLE ES2.5
Output Service
98
LiveCycle ES2.5 Services
Ensuring that fonts are available to LiveCycle ES2.5
Ensure that a font used within a form is available for use on the J2EE application server hosting LiveCycle ES2.5. For example, consider the
following scenario. A form designer adds a font to the font directory that Designer ES2.5 uses and creates a form that uses that font on a
separate computer.
In order for the Output service to use the font, place it in the Customer fonts directory. Specify the location of the Customer fonts directory
by using LiveCycle Administration Console. If the Customer fonts directory does not exist, create a directory on the J2EE application server
hosting LiveCycle ES2.5. Place the font in the new Customer fonts directory.
Specify the location of the Customer fonts directory
1
In LiveCycle Administration Console, click Settings > Core System Settings.
2
In the Core System view, click Configurations.
3
Specify the location of the Customer fonts directory in the Location of the Customer Fonts directory text input box.
4
Click OK.
5
Restart the J2EE application server on which LiveCycle ES2.5 is installed.
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 by using
LiveCycle ES2.5 XDC Editor. (See LiveCycle ES2.5 XDC Editor Help.)
printer-resident fonts are stored inside a printer, either in a special hardware cartridge or built in 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 or PCL) and make the appropriate changes to the XDC file.
4
Test the output.
Note: For information about performing these tasks, see LiveCycle ES2.5 XDC Editor Help.
Font mapping
If a font is installed on a client computer, it is available in the drop-down list in Designer ES2.5. If the font is not installed, it is necessary to
specify the font name manually. The “Permanently replace unavailable fonts” option in Designer ES2.5 can be off. Otherwise, when the XDP
file is saved in Designer ES2.5, the substitution font name is written to the XDP file. This means that the printer-resident font is not used.
To design a form that uses printer-resident fonts, choose a typeface name in Designer ES2.5 that matches the 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 example, in a
PostScript scenario, references to the Arial font can be mapped to the printer-resident Helvetica typeface.
Two types of OpenType fonts exist. One type is a TrueType OpenType font that PCL supports. The other is CFF OpenType. PDF and
PostScript output supports embedded Type-1, TrueType, and OpenType fonts. PCL output supports embedded TrueType fonts.
Type-1 and OpenType fonts are not embedded in PCL output. Content that is formatted with Type-1 and OpenType fonts is rasterized and
generated as a bitmap image that can be large and slower to generate.
ADOBE LIVECYCLE ES2.5
Output Service
99
LiveCycle ES2.5 Services
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 Designing Forms for LiveCycle Output ES2.
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 or 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 ES2.5 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 ES2.5 administrator must
register them by using LiveCycle ES2.5 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 ES2.5 administrator registers \\print-server.domain.name.com\printer as a profile in the LiveCycle ES2.5
trust store. In this situation, the Output service searches for the credentials of a printer by looking up aliases in the Trust Store in the
following order:
\\print-server.domain.name.com\printer
\\print-server.domain.name.com
\\domain.name.com
\\name.com
\\com
\\
The Output service sends the print job to the first matching entry.
Note: LiveCycle ES2.5 supports NTLM v2 in CIFS. Kerberos5 is not supported.
Assume that a LiveCycle ES2.5 user invokes the sendToPrinter operation, 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 ES2.5 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).
After authentication, the print job is sent to the printer.
Working with device profile files (XDC file)
A device profile (XDC file) is a printer description file in XML format. This file enables the Output service to output documents as laser or
label printer formats. The Output service uses the XDC files including these:
•
•
•
•
•
•
•
hppcl5c.xdc
hppcl5e.xdc
ps_plain_level3.xdc
ps_plain_mt.xdc
ps_plain.xdc
zpl203.xdc
zpl300.xdc
ADOBE LIVECYCLE ES2.5
Output Service
100
LiveCycle ES2.5 Services
• zpl600.xdc
It is not necessary to modify these files for the Output service to create documents. However, you can modify them to meet your business
requirements. (See LiveCycle ES2.5 XDC Editor Help.)
Note: See XDC Editor Help for a complete listing of XDC files.
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.
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 ES2.5 distinguishes
between paper (page) size and which input tray on the printer provides the requested paper. This functionality accommodates scenarios
where a printer has different types of a particular paper size loaded into different input trays. This functionality allows a document to select
paper from individual trays on a per-page basis.
Designer ES2.5 does not expose paper size and input tray selection as two distinct properties. Instead, a Designer ES2.5 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 99.)
Designer ES2.5 provides duplicates of common paper types for Letter and Legal paper sizes, specifically to accommodate paper tray
selection. The XDC Editor within Workbench is used to map or assign a physical input tray to a paper type. The names provided in Designer
ES2.5 covers most tray-selection needs. The deployed device profile can be modified so that the Letter Color paper type causes the printer
to select paper loaded into a secondary 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. Only the deployed device profile is modified to ensure the appropriate input tray selection.
Although the provided paper types are adequate, it is possible to create additional paper types. Additional paper types can be used in the
XDC Editor by creating a paper type name. However, it must exist in Designer ES2.5 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 required.
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
the size is found, a manual feed is requested.
For PCL documents, each master page in the XDP file (the form design created in Designer ES2.5) 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 Designer ES2.5 may turn the literal that
you view in the paper type list into a slightly different literal. 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
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. 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 nonsecured 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.
ADOBE LIVECYCLE ES2.5
Output Service
101
LiveCycle ES2.5 Services
Note: A PostScript file that is created from a form design that contains a custom page may not print. In this situation, 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 ES2.5 exposes control over duplex printing in two ways depending on whether the form is used to generate a PDF document and
printed from Adobe Reader or Acrobat. Or whether the form is printed directly to a PCL or PostScript device.
When the form is intended to generate a PDF document, settings that relate to how the PDF document is printed can be configured from
the Form Properties dialog box within Designer ES2.5. 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.
Duplexing can also be specified by using the pagination property of the Output service operations that are available within Workbench.
Duplexing can also be specified by using the Output service Java and web service API. Additional capabilities are available in Designer ES2.5
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. Different master pages can be
designed for the front and back pages. The Output service automatically selects the appropriate master page, depending on whether it is
currently printing on the front or back of the page. A common use case is to create master pages that place the page count on the left side or
right side of the page. Assign the master pages as odd or even to ensure that the page count is always on the inside or outside of a duplexprinted document.
Working with the XCI configuration file
The Output service uses an XCI configuration file to perform tasks, such as embedding a font into a document. Although this file contains
settings that can be set, it is not typical to modify this value. The default.xci file is located in the svcdata\XMLFormService folder.
For example, assuming that LiveCycle ES2.5 is installed on JBoss, the full path is as follows:
[Install location]\Adobe\LiveCycle ES2\jboss\server\lc_turnkey\svcdata\XMLFormService
You can pass a modified XCI file while performing an Output service operation. When doing so, create a copy of the default file, change only
the values that requires modification to meet your business requirements, and use the modified XCI file.
The Output service starts with the default XCI file (or the modified file). Then it applies values that are specified in Workbench property
sheets or specified by using the Output Service API. These values override XCI settings. For example, values specified in a Workbench
property sheet overrides XCI values.
ADOBE LIVECYCLE ES2.5
Output Service
LiveCycle ES2.5 Services
The following table specifies XCI options.
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 use when generating a PDF document.
config/present/pdf/fontInfo/embed
Controls font embedding in the output document. (See “Embedding fonts” on page 103.)
config/present/pdf/scriptModel
Controls whether XFA-specific information is included in the output PDF document.
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 perform upon opening the document in an interactive client.
config/present/output/type
Specifies either the type of compression to apply to a file or the type of output to produce.
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 ES2.5 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 ES2.5 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/present/pdf/fontInfo/alwaysEmbed
Specifies a font that is embedded into the output document.
config/present/pdf/fontInfo/neverEmbed
Specifies a font that must never be embedded into the output document.
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 document to generate
102
ADOBE LIVECYCLE ES2.5
Output Service
103
LiveCycle ES2.5 Services
Embedding fonts
To demonstrate how to work with an XCI file, an XCI file is used to embed a font into a PDF document that the Output service generates.
Embedding a font is relevant only for PDF output. For PCL and PostScript output, the font is automatically embedded if it is not resident on
the printer. This setting reduces the PDF file size by having the global embed setting off but providing 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 ES2.5 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 an 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 or by using Output Service API.
Improving the performance of the Output service
The following list specifies performance factors to consider when working with the Output service:
•
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 ES2.5 database, resulting in a performance cost.
•
As of LiveCycle 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, therefore improving the performance of a given operation.
•
Changing the caching option of the LiveCycle ES2.5 repository to manual optimizes performance. The default setting results in lower
performance because the Output service assumes that a form (or fragments) have changed since the last time it was used.
•
•
Forms that contain justified fields decrease performance; that is, justification degrades performance.
•
•
When working with batch processing and when possible, use incremental loading. (See “Incremental loading” on page 91.)
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 89.)
When designing a form, use fonts that support a particular language to improve performance.
Note: For information about processing large XML data files that contain many records., see “Maximizing throughput” on page 96.
104
26. PDF Utilities Service
Use the PDF Utilities service 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 by using this service:
Clone PDF: This feature is available only in LiveCycle Workbench. It 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.
Also, any future modification of either value is not reflected in the other object.
Multiple Clone of PDF: This feature is available only in Workbench. It 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 the PDF document is saved in. Also,
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
ADOBE LIVECYCLE ES2.5
PDF Utilities Service
•
•
105
LiveCycle ES2.5 Services
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 the PDF document is saved in. Also, 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 9.5 Help. For information about developing
client applications that programmatically interact with this service, see Programming with LiveCycle ES2.5.
106
27. 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. This action activates 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
•
•
•
Submit completed or annotated PDF documents electronically
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
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. These tools include electronic
sticky notes, stamps, highlights, and text strikethrough. The same functions are available in Acrobat.
• Support barcoded forms decoding.
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 again disabled in Adobe Reader. They remain disabled 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 106
“Considerations for the Reader Extensions service” on page 108
Using the Reader Extensions service
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 functionality includes 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: A message prompting users to fill the form is displayed to users of Adobe Reader 7. 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, also enable the Database and Web Service Connectivity usage
right or the Embedded File Attachments usage right (depending on the usage rights required).
ADOBE LIVECYCLE ES2.5
Reader Extensions Service
107
LiveCycle ES2.5 Services
Submit outside web browser: Users can submit form data by email or offline. If you select this feature, Basic Form Fill-In is also automat-
ically 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 that are 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 LiveCycle Reader Extensions ES2.5 web application. (See LiveCycle Reader Extensions ES2.5 Help.)
Use processes that you develop by using LiveCycle Workbench. (See LiveCycle Workbench 9.5 Help.)
Use the Reader Extensions Service API. (See Programming with LiveCycle ES2.5.)
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 rightsenabled PDF document is also necessary in order to perform other LiveCycle ES2.5 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, do these tasks:
•
•
•
remove usage rights from the PDF document
perform the other operations such as digitally signing the document
reapply usage rights to the document
Methods for removing usage rights
•
•
Use processes that you develop by using Workbench. (See LiveCycle Workbench 9.5 Help.)
Use the Reader Extensions Service API. (See Programming with LiveCycle ES2.5.)
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.
ADOBE LIVECYCLE ES2.5
Reader Extensions Service
108
LiveCycle ES2.5 Services
Methods for getting credential information rights
•
•
Use the Reader Extensions Service API. (See Programming with LiveCycle ES2.5.)
Use processes that you develop by using Workbench. (See LiveCycle Workbench 9.5 Help.)
Considerations for the Reader Extensions service
Consider the following factors 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 ES2.5. For information about configuring a credential, see Configuring credentials for use with Reader Extensions ES2.5 in
LiveCycle ES2.5 Administration Help or consult your application server administrator.
Order of operations
Any combination of encrypting, certifying, and applying usage rights to the same document must occur in the following order. These
services must be invoked within a short-lived process:
1
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.
2
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, therefore removing the usage rights from the document.
3
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.
Also, you cannot encrypt a PDF document and apply a policy to the same PDF document, and 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 ES2.5. For example, you created an interactive form by using Designer ES2.5 and you want to use a form script to
reference a data connection SOAP endpoint where form data is retrieved. Then 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
ES2.5) 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, 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
ADOBE LIVECYCLE ES2.5
Reader Extensions Service
109
LiveCycle ES2.5 Services
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 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 indicating 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.
110
28. 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 repository can contain the following assets:
• XML forms
• PDF forms (including Acrobat forms)
• form fragments
• images
• processes
• profiles
• policies
• SWF files
• DDX files
• XML schemas
• WSDL files
• test data.
The repository tracks the version of each asset in a LiveCycle ES2.5 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 the Repository 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 by using the Repository Service API.
For information about developing a process that uses this service, see LiveCycle Workbench 9.5 Help. For information about developing a
client application that programmatically interacts with this service, see Programming with LiveCycle ES2.5.
You can use the Applications and Services pages in LiveCycle Administration Console to configure default properties for this service. (See
LiveCycle ES2.5 Administration Help.)
111
29. Rights Management Service
Using the Rights Management service, you can 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 revoke access to the document.
The Rights Management service protects PDF files and other file types such as these:
• FLV and F4V
• Microsoft Word, Excel, and PowerPoint
• Parametric Technology Corporation (PTC) Pro/ENGINEER Wildfire 4.0
Policies can be applied to PDF documents programatically using the Rights Management Service API, or as part of a process. Policies can
also be applied to documents by 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 LiveCycle Rights
Management ES2.5 Extension Help for the application. You can download the LiveCycle Rights Management ES2.5 Extension for Microsoft
Office from the Adobe website.
Note: Rights Management ES2.5 requires authentication over SSL connections. (See Configuring SSL in LiveCycle ES2.5 Administration Help.)
Administrators use the Rights Management ES2.5 web pages to do the following tasks (see LiveCycle ES2.5 Administration Help):
• Configure various Rights Management service settings
• Manage policy-protected documents
• Create and manage policy sets and the policies that they contain
• Monitor events that Rights Management ES2.5 records
• Manage invited and local users
You can use LiveCycle Workbench to develop processes to do the following tasks (see LiveCycle Workbench 9.5 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
• Get all policy set names or all policy names within a policy set
• Get policy by policy identifier
• Inspect a protected document
• Unlock policy-protected PDF documents
You can use the Rights Management Service API to develop client applications to do the following tasks (see Programming with LiveCycle
ES2.5):
•
•
•
•
•
•
•
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
Open policy-protected documents in batch mode
Retrieve information about policy-protected documents
ADOBE LIVECYCLE ES2.5
Rights Management Service
112
LiveCycle ES2.5 Services
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. Users can also be people external to your organization who registered with Rights Management ES2.5 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 that are appropriate for different situations and users.
Using Rights Management ES2.5, you can 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 by using Portable Document Rights Language (PDRL).
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 perform the following
actions:
• view events related to the policy set
• manage documents
• manage other policy set coordinators
Policy sets are created and deleted in the Rights Management ES2.5 administration web pages by policy set administrators who have the
appropriate permission.
When Rights Management ES2.5 is installed, a default policy set is created called Global Policy Set. Policy set administrators can administer
this policy set.
Security methods and technology
To ensure the confidentiality of documents that are protected by policies, Rights Management ES2.5 implements three layers of security.
Authentication
All users are required to log in to interact with Rights Management ES2.5. Users must log in before performing the following tasks:
•
•
•
Opening the Rights Management ES2.5 web application in a web browser
Securing documents with policies in a supported client application
Opening policy-protected documents
ADOBE LIVECYCLE ES2.5
Rights Management Service
113
LiveCycle ES2.5 Services
When creating a policy, you can allow anonymous users to open policy-protected documents if that setting is enabled in the Rights
Management ES2.5 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 ES2.5 or use other policy-protected documents.
Methods of authentication
Rights Management ES2.5 supports these 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 by
using a smart card.
Internal users have corresponding user records in your organizational user directory, and those records are synchronized with the User
Management database. Rights Management ES2.5 authenticates internal users against the User Management database. Rights Management
ES2.5 also stores external user accounts in the database and uses the accounts to authenticate external users. For information about
managing users, see Adding and configuring users in LiveCycle ES2.5 Administration Help.
SAML authentication assertions
After users are initially authenticated and when Rights Management ES2.5 receives subsequent messages from clients, Rights Management
ES2.5 uses SAML authentication assertions to verify the identity of the message sender. Security Assertion Markup Language (SAML)
authentication assertions are used for authentication until the assertion expires or users terminate their session.
When users are initially authenticated by using their user name and password, Rights Management ES2.5 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 ES2.5 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 ES2.5 does not support third-party
SAML assertions.
Logging in through Acrobat and other client applications
When Rights Management ES2.5 authenticates a user through Acrobat or another client application, such as Microsoft Office, the server
returns the SAML authentication assertion to the client application.
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 ES2.5 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 through the User
Management web pages. The role information is stored in the User Management database. For information about the roles used by Rights
Management ES2.5, see About LiveCycle Rights Management ES2.5 users in LiveCycle ES2.5 Administration Help. For information about
assigning roles, see Managing Roles in LiveCycle ES2.5 Administration Help.
ADOBE LIVECYCLE ES2.5
Rights Management Service
114
LiveCycle ES2.5 Services
Document confidentiality
Rights Management ES2.5 uses several technologies to protect documents and to provide access to them. In general, Rights Management
ES2.5 uses a symmetric cryptographic key system for encryption. Client applications such as Acrobat perform document encryption.
Documents are never sent to Rights Management ES2.5 when they are secured using client applications. However, 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. (See “Policy-protecting documents for online use” on page 114 and “Policy-protecting documents for offline use”
on page 116.)
When you apply a policy to a PDF document, the information that the document contains, including files that you save in the document, is
protected by the confidentiality settings specified in the policy.
Note: Document confidentiality settings applied through a policy replace 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 LiveCycle Rights Management ES2.5 to open protected documents. Securing
documents for online use employs a straightforward process for encrypting the document and providing access only to authenticated and
authorized users.
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 by 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 ES2.5 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.
ADOBE LIVECYCLE ES2.5
Rights Management Service
115
LiveCycle ES2.5 Services
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 are logged, the client software sends event information to the server for logging as soon as the
user opens the document. For information about the audit log, see Monitoring events in LiveCycle ES2.5 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 ES2.5 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 ES2.5 extension installed.
When a user attempts to open a policy-protected document, Acrobat, Adobe Reader, or Rights Management ES2.5 Extension connects to
Rights Management ES2.5 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 ES2.5 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.
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.
ADOBE LIVECYCLE ES2.5
Rights Management Service
116
LiveCycle ES2.5 Services
If the policy specifies that document events are logged, the client software sends event information to the server for logging as soon as the
user opens the document. For information about the audit log, see Monitoring events in LiveCycle ES2.5 Administration Help.
If the user saves a copy of a policy-protected document, 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 ES2.5.
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 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 ES2.5 server synchronizes data with the client that is required 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 is encrypted. It 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. The synchronization updates
the MicroSafe with 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. (See Configuring offline security in LiveCycle ES2.5 Administration Help.)
Security standards and technology
The following table provides details about the methods that Rights Management ES2.5 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
Implementation used is the RSA BSafe Crypto-C (in Acrobat) or Crypto-J (in Rights Management ES2.5) 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.
ADOBE LIVECYCLE ES2.5
Rights Management Service
117
LiveCycle ES2.5 Services
Using the Rights Management service
Creating policies
You can create any number of policies by using security settings that are 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 ES2.5 SDK or the Rights
Management ES2.5 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.
A validity period can be set to one of these options:
• A set number of days that the document is accessible from the time it 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 only 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. The text that is displayed in the watermark can be any of these:
•
User name: The name of the user who opened the document
•
User ID: The ID of the user who opened the document
•
Policy name: The name of the policy that is assigned to the document
•
Current date: The date the document was opened
•
Custom text: Text, such as the word Confidential
After a watermark is created, you can include it as part of a policy. After a policy that contains a watermark is applied to a PDF document,
the watermark appears on each page of 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 lets a group view a document only while online and prohibits recipients from copying it
• Attach the policy entry to the policy
• Use the policy to secure a document
As a result of these actions, recipients can view the document only online and cannot copy it. The document remains secure until security
is removed from it.
Methods for creating policies
•
Users and administrators can use the Rights Management ES2.5 web pages. (See "Creating and editing policies" in LiveCycle Rights
Management ES2.5 Help or LiveCycle ES2.5 Administration Help.)
•
Use Workbench to create a policy from an existing policy. When you create a policy in Workbench, there are fewer properties to
configure. (See LiveCycle Workbench 9.5 Help.)
•
Use the Rights Management Service API. (See Programming with LiveCycle ES2.5.)
ADOBE LIVECYCLE ES2.5
Rights Management Service
118
LiveCycle ES2.5 Services
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 attributes in the
Unchangeable Advanced Settings section. In Workbench, you also cannot modify the policy name and the validity time. For example, to
change the policy’s offline lease period, you can modify the value of the policy’s offline lease period attribute.
Changes to policies that are protecting documents are updated the next time that the policy-protected document is synchronized with the
Rights Management service.
Methods for modifying policies
•
Users and administrators can use the Rights Management ES2.5 web pages. (See "Creating and editing policies" in LiveCycle Rights
Management ES2.5 Help or LiveCycle ES2.5 Administration Help.)
•
•
Use Workbench. (See LiveCycle Workbench 9.5 Help.)
Use the Rights Management Service API. (See Programming with LiveCycle ES2.5.)
Deleting policies
You can delete an existing policy when it is no longer required. After a policy is deleted, it cannot 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 that the policy belongs to. The user whose settings are used to invoke
LiveCycle ES2.5 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 ES2.5 web pages. (See "Delete a policy" in LiveCycle Rights Management ES2.5
Help or LiveCycle ES2.5 Administration Help.)
•
Use the Rights Management Service API. (See Programming with LiveCycle ES2.5.)
Applying policies to documents
You can apply a policy to a document to secure the document. Applying a policy to a document restricts access to the document and applies
confidentiality settings to it.
To apply a policy to a PDF document by using the LiveCycle ES2.5 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 ES2.5 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
•
•
•
•
Use Acrobat Professional and Acrobat Pro Extended to apply policies to PDF documents. (See Acrobat Help.)
Use LiveCycle Rights Management ES2.5 Extension for Microsoft Office to apply policies to Microsoft Office documents. (See
LiveCycle Rights Management ES2 Extension Help for Microsoft 2003 or LiveCycle Rights Management ES2 Extension Help for
Microsoft 2007.)
Use Workbench. (See LiveCycle Workbench 9.5 Help.)
Use the Rights Management Service API. (See Programming with LiveCycle ES2.5.)
ADOBE LIVECYCLE ES2.5
Rights Management Service
119
LiveCycle ES2.5 Services
Removing policies from documents
You can remove a policy from a policy-protected document to remove security from the document. To update a policy-protected document
with a newer policy, it is more efficient to switch the policy than to remove it and add the updated policy.
Methods for removing policies
•
•
•
•
Use Acrobat® Professional and Acrobat Pro Extended to remove policies from PDF documents. (See Acrobat Help.)
Use LiveCycle Rights Management ES2.5 Extension for Microsoft Office to remove policies from Microsoft Office documents. (See
LiveCycle Rights Management ES2 Extension Help for Microsoft 2003 or LiveCycle Rights Management ES2 Extension Help for
Microsoft 2007.)
Use Workbench. (See LiveCycle Workbench 9.5 Help.)
Use the Rights Management Service API. (See Programming with LiveCycle ES2.5.)
Switching the policy applied to a document
To update a policy-protected document with a newer policy, it is more efficient to switch the policy than to remove it and add the updated
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 ES2.5 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, the change is applied the next time the user synchronizes with Rights Management ES2.5 by opening a policyprotected 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 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 ES2.5 web pages. (See "Switch a policy that is applied to a document" in
LiveCycle Rights Management ES2.5 Help or LiveCycle ES2.5 Administration Help.)
•
•
Use Workbench. (See LiveCycle Workbench 9.5 Help.)
Use the Rights Management Service API. (See Programming with LiveCycle ES2.5.)
Revoking access to policy-protected documents
You can revoke access to a policy-protected document. The result of this action is that all copies of the document are no longer accessible 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 opens 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 no one can
view the document unless access is reinstated.
Reinstating access to documents
You can reinstate (unrevoke) access to a revoked document. The result is that all copies of the revoked document are accessible to users.
Methods for revoking access to documents
•
Users and administrators can use the Rights Management ES2.5 web pages. (See "Revoking and reinstating access to documents" in
LiveCycle Rights Management ES2.5 Help or LiveCycle ES2.5 Administration Help.)
ADOBE LIVECYCLE ES2.5
Rights Management Service
•
•
120
LiveCycle ES2.5 Services
Use Workbench. (See LiveCycle Workbench 9.5 Help.)
Use the Rights Management Service API. (See Programming with LiveCycle ES2.5.)
Monitoring events
The Rights Management service can track specific actions related to the policy-protected document as they occur. This tracking happens
when the auditing capability is enabled and the policy used to protect a document has auditing enabled. Events include activities such as
applying a policy to a document and 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 ES2.5 web pages to
search and view audited events. Users can view audited events for their policy-protected documents and for 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 log in using an incorrect user name or password.
Policies can allow anonymous user access. If the administrator later turns off anonymous access, 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 ES2.5 web pages. (See "Monitoring events" in LiveCycle Rights Management
ES2.5 Help or LiveCycle ES2.5 Administration Help.)
•
Use the Rights Management Service API. (See Programming with LiveCycle ES2.5.)
Considerations for the Rights Management service
Order of operations
Any combination of encrypting, certifying, and applying usage rights to the same document must occur in the following order. These
services must be invoked within a short-lived process:
1
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.
2
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, therefore removing the usage rights from the document.
3
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.
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.
ADOBE LIVECYCLE ES2.5
Rights Management Service
LiveCycle ES2.5 Services
121
122
30. 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 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 XML Path
Language (XPath) specification.
For information about developing processes that use this service, see LiveCycle Workbench 9.5 Help.
123
31. Signature Service
The Signature service lets you work with digital signatures and documents on the LiveCycle ES2.5 server. You can use this service from
processes that are created in LiveCycle Workbench or Java or web service clients that are created using the LiveCycle ES2.5 SDK. For
example, the Signature service is typically used in the following situations:
• The LiveCycle ES2.5 server certifies a form before it is sent to a user to open by using Acrobat or Adobe Reader.
• The LiveCycle ES2.5 server validates a signature that was added to a form by using Acrobat or Adobe Reader.
• The LiveCycle ES2.5 server signs a form on behalf of a public notary.
The Signature service accesses certificates and credentials that are stored in the trust store. (See Managing certificates and credentials in
LiveCycle ES2.5 Administration Help.
This section includes the following topics that provide background information about digital signatures and the Signature service:
• “About digital signatures” on page 123
• “About signature fields” on page 124
• “About the Signature service and form types” on page 124
• “About digital signature technology” on page 125
• “Integrating with a security infrastructure” on page 126
• “Supported technologies and standards” on page 127
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 127
“Best practices” on page 130
About digital signatures
Digital signatures are blocks of information that are added to electronic documents. You can use them to authenticate the identity of the
signer and verify the integrity of the document or part of the document:
•
Signatures contain information that lets you 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:
•
The Signature service can create PDF signatures for all PDF documents, such as PDF documents created by using LiveCycle Designer
ES2.5 or Acrobat.
•
The Signature service can validate XML signatures for XFA-based PDF documents, such as PDF documents that are created by using
Designer ES2.5 or by the Forms service.
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.
ADOBE LIVECYCLE ES2.5
Signature Service
124
LiveCycle ES2.5 Services
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 to sign the document. Users can fill the form and sign the document. However, if users 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. After the
signature is added, the associated fields are locked. These types of signatures are known as MDP+ signatures. To use this feature with PDF
forms and XML forms, users must use Acrobat or Adobe Reader 8.0 and later 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 ES2.5 to add signature fields at design time. (See LiveCycle Designer ES2.5 Help.)
Use the Signature service to add signature fields at run time. (See “Adding, modifying, and removing signature fields” on page 129.)
About the Signature service and form types
LiveCycle ES2.5 supports several types of PDF forms. Although Acrobat or Adobe Reader users notice no apparent difference between the
form types, the way the PDF form is constructed can be different. For example, forms can be rendered to PDF by the Forms service on the
LiveCycle ES2.5 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 PDF
form in Acrobat, digitally signs it, and saves it. Then the user sends the file to a colleague in an email message. When the colleague opens
the form, Acrobat renders the form to PDF, which invalidates the digital signature.
To use the Signature service, identify 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 by using Designer ES2.5. 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. The next time the
form is opened, it is not rerendered.
•
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 by using Acrobat or Adobe Reader.
For more information about the static and dynamic Adobe PDF forms, see Using Designer ES2.5 > Working with Form Designs > Guidelines
for creating PDF forms in LiveCycle Designer ES2.5 Help.
ADOBE LIVECYCLE ES2.5
Signature Service
125
LiveCycle ES2.5 Services
Adobe XML form: XDP files that are created by using Designer ES2.5. Adobe XML forms are prepared for opening in Acrobat or Adobe
Reader by using the Forms service. The Forms service can be configured so that the PDF form is rendered by any of these agents:
•
•
•
Forms service (on the LiveCycle ES2.5 server) before being sent to the client
Acrobat
Adobe Reader.
Non-interactive PDF forms: PDF forms 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 ES2.5, see “Requirements for form design and
Workspace ES2.5” on page 131.
About digital signature technology
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.
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 to. 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. Certificates 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.
ADOBE LIVECYCLE ES2.5
Signature Service
126
LiveCycle ES2.5 Services
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 by using a hashing algorithm. The digest is unique for the
document, and the document cannot be reconstructed by using the digest. The digest is encrypted by using the signer’s private key to create
the signature.
The signature and the certificate that corresponds with the private key that is used to create the signature are typically bundled with the
document.
Signatures can include timestamps. 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 timestamp 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.
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 Managing HSM credentials in
LiveCycle ES2.5 Administration 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 OCSP servers.
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.
Integrating with external service providers for retrieving credentials and verifying certificates.
ADOBE LIVECYCLE ES2.5
Signature Service
127
LiveCycle ES2.5 Services
Supported technologies and standards
The following table provides a summary of the technologies and industry standards that LiveCycle Digital Signatures ES2.5 supports.
Item
Supported technology or standards
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.
Using the Signature service
For information about developing processes that use this service, see LiveCycle Workbench 9.5 Help. For information about developing
client applications that programmatically interact with this service, see Programming with LiveCycle ES2.5.
You can use the Applications and Services pages on LiveCycle Administration Console to configure default properties for this service. (See
Signature service settings in LiveCycle ES2.5 Administration Help.)
Signing and certifying documents
You can use the Signature service to sign and certify PDF documents by using any credential that the service can access. When signing or
certifying, specify the signature field to use.
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 9 compatibility. The
form can only be viewed using Acrobat or Adobe Reader 9.
Note: For all types of forms, Acrobat or Adobe Reader users can delete signatures that the Signature service added.
When signing or certifying forms, 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.
ADOBE LIVECYCLE ES2.5
Signature Service
128
LiveCycle ES2.5 Services
Revocation information: Whether to embed revocation information in the signature to use for validating the signer’s certificate. The infor-
mation enables OCSP-checking and CRL-checking.
Time stamp information: Whether to create a timestamp for the signature and the information required to perform the timestamp trans-
action with the timestamp provider.
Appearance: Properties that affect the appearance of the signature when it is viewed using Acrobat or Adobe Reader. These properties can
be the reason for signing, the contact information of the signer, a legal attestation, and the icons to use.
Validating document integrity and authenticity
You can use the Signature service to validate signatures that are added to PDF forms. To validate signatures, the certificate can be checked
for revocation, the timestamp of the signature can be checked, and the document digest is verified. You can validate signatures individually
or validate all the signatures on a PDF document.
The following limitations apply to validating digital signatures by 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 signatures, 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 is revoked. You can specify information to enable OCSP and CRL types
of checking.
Time stamp checking: How to verify the timestamp of the signature.
Path validation: Information that enables the verification of the certificates in the certificate chain that the signer’s certificate includes.
The validity status messages displayed depend on whether the Process Documents With Acrobat 9 Compatibility option is selected for
Signature service. (See Signature service settings in LiveCycle ES2.5 Administration Help.)
The following table describes the situations that cause the different signature-validity states when the option is selected.
Values
Signature status
DynamicFormSignatureUnknown
Status Unknown
DocumentSignatureUnknown
The integrity of the document or dynamic PDF form has not been verified.
CertifiedDynamicFormSignatureTamper
Tamper
SignedDynamicFormSignatureTamper
The document or dynamic form has been altered or corrupted since the signature was applied.
CertifiedDocumentSignatureTamper
SignedDocumentSignatureTamper
SignatureFormatError
Invalid
The signature is invalid because its formatting or the information it contains has errors.
DynamicFormSigNoChanges
Signed with no changes
DocumentSigNoChanges
The document or dynamic form has not been modified since the signature was applied.
DynamicFormCertificationSigNoChanges
Certified with no changes
DocumentCertificationSigNoChanges
The document or dynamic form has not been modified since it was certified.
ADOBE LIVECYCLE ES2.5
Signature Service
129
LiveCycle ES2.5 Services
Values
Signature status
DocSigWithChanges
Signed with changes
The revision of the document that this signature covered has not been changed; however, subsequent changes were
made to the document.
CertifiedDocSigWithChanges
Signed with allowed changes
The document has been changed since the signature was applied. However, the changes are permitted by the document
certifying party and do not invalidate the signature.
CertificationSignWithChanges
Certified with changes
The document has been changed since it was certified. However, the changes are permitted by the document certifying
party and do not invalidate the signature
The following table describes the situations that cause the different signature-validity states when the option is not selected.
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; however, subsequent changes were made to the document.
ValidUnmodified
Signature valid and document unmodified
The revision of the document that is covered by the signature was not modified. No subsequent changes were made to the document.
When validating signatures, you must 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.
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.
ADOBE LIVECYCLE ES2.5
Signature Service
•
•
•
The fields to lock when the signature is added.
•
Whether the field can be used only for certifying the document.
130
LiveCycle ES2.5 Services
The signature handler that validates signatures.
Information about the signature (for example, whether to include revocation information, a list of signing reasons that users can select
from, and server URLs used for validating signatures).
Caution: The Signature service cannot add or modify signature fields on a dynamic Adobe PDF form.
Best practices
The following characteristics of LiveCycle ES2.5 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 enforce field-locking (MDP+) signature rules for Adobe PDF forms and Adobe XML forms.
Generally, you must decide whether the use of dynamic PDF 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 130.)
•
If you need to use dynamic PDF 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 131.)
•
Before you use the form with the Signature service, ensure that the form is not a dynamic Adobe PDF form. (See “Checking the form
type” on page 131.)
Also, to use digital signatures on forms that users open in Workspace ES2.5, your form must conform to specific design criteria. (See XREF).
Order of operations
Any combination of encrypting, certifying, and applying usage rights to the same document must occur in the following order. These
services must be invoked within a short-lived process:
1
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.
2
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, therefore removing the usage rights from the document.
3
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.
Ensuring that no rendering occurs after signing
When a form is rendered to PDF, any digital signatures that it contains are invalidated. 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 ES2.5 to create static Adobe PDF forms so that rendering occurs only the first time they are opened in Acrobat or Adobe
Reader.
ADOBE LIVECYCLE ES2.5
Signature Service
131
LiveCycle ES2.5 Services
If you are using the Forms service to merge data with the form, prevent the service from converting the form to a dynamic PDF form. Use
Designer ES2.5 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 ES2.5 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 9.5 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 and the Signature service, 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 ES2.5. However, you can attach non-interactive forms to the Workspace
ES2.5 tasks by using the User service. You can also distribute the forms through email messages.
Use the Output service to convert dynamic PDF 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.
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 lets
you 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 ES2.5
If you are using digital signatures on a PDF form that users open in Workspace ES2.5, you must 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 ES2.5.
When the Process Objects object is included on a form, the LiveCycle ES2.5 server changes the appearance of the submit button that the
object provides. Digital signatures that are added before the form is submitted indicate that a change has occurred. A yellow triangle alerts
the user to the change.
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 ES2.5 to add invisible submit buttons at design time. (See LiveCycle Designer ES2.5 Help.)
132
32. 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 that it belongs to.
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 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 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 9.5 Help.
133
33. User Service
The User service enables processes to create and assign tasks to LiveCycle Workspace ES2.5 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 133
“Interacting with tasks” on page 134
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 ES2.5
or by using email. You can also use the Assign Task operation to configure task features that are exposed to Workspace ES2.5 users.
Assigning tasks
Assign tasks to users or groups to add the task to their To Do list in Workspace ES2.5. 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 must log in to Workspace ES2.5 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. (See LiveCycle Workbench 9.5 Help.)
Use the Task Manager Service APIs. (See Programming with LiveCycle ES2.5.)
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 ES2.5 users and the form data to include in the form. Also specify
where to save the form data that is submitted when the task is completed.
Instructions: Provide instructions to Workspace ES2.5 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 done.
Reminders, deadlines, and escalations: Configure these mechanisms to ensure that the process progresses within time constraints.
ADOBE LIVECYCLE ES2.5
User Service
134
LiveCycle ES2.5 Services
Methods for configuring task features
•
Use Workbench. (See LiveCycle Workbench 9.5 Help.)
Configuring email notifications
Notification email messages can be sent to Workspace ES2.5 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 LiveCycle Workbench to override the default messages for a task, or
disable notifications for the task.
Messages that are configured using Workbench can also include XPath expressions so that you can include text-based process data in the message.
Methods for configuring email notifications
•
•
Use LiveCycle Administration Console. (See Configuring notifications for users and groups in LiveCycle ES2.5 Administration Help.)
Use Workbench. (See LiveCycle Workbench 9.5 Help.)
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. (See LiveCycle Workbench 9.5 Help.)
Interacting with tasks
This section describes how to interact with tasks after they are created. Workbench, LiveCycle Administration Console, and LiveCycle ES2.5
SDK provide tools for interacting with tasks.
Note: For information about how to interact with tasks by using Workspace ES2.5, see LiveCycle Workbench 9.5 Help.
Reacting to task events
LiveCycle Process Management ES2.5 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.
ADOBE LIVECYCLE ES2.5
User Service
135
LiveCycle ES2.5 Services
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. (See LiveCycle Workbench 9.5 Help.)
Retrieving task information
You can retrieve tasks assigned to specific users and then retrieve information about the task, such as the task identification, status, and name
of the process it belongs to. You can also retrieve a history of the task.
Methods for retrieving task information
•
•
Use the Process Management ES2.5 pages in LiveCycle Administration Console. (See LiveCycle ES2.5 Administration Help.)
Use the Task Manager Service API. (See Programming with LiveCycle ES2.5.)
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 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 ES2.5 pages in LiveCycle Administration Console. (See LiveCycle ES2.5 Administration Help.)
Use the Task Manager Service API. (See Programming with LiveCycle ES2.5.)
136
34. Variable Logger Service
The Variable Logger service enables processes to send messages about variable values to the system log or to log files on the file system of
the LiveCycle ES2.5 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 that uses the service. When using this
service in a process, you can specify the following options:
•
•
•
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 file name and path of the log file or an XPath expression to a process variable that contains the file name and path when 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 9.5 Help.
137
35. Wait Point Service
The Wait Point service lets you 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 that uses the service. When you use this service
in a process to delay the execution of the next operation in the process, specify the amount of time to wait by using either calendar days or
business calendar days:
Calendar days: When you use calendar days, provide values for the number of days, hours, minutes, and seconds to wait.
Business calendar days: When you use business calendar days, 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 ES2.5 skips non-business days when calculating the
amount of time to wait.
For information about developing processes that use this service, see LiveCycle Workbench 9.5 Help.
138
36. 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 and passes through values for each of its parameters. It then 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,
MTOM, and SwaRef attachments with SOAP messages by using the WS-Attachment protocol. The Web Service service interactions are
compatible with SAP systems and .NET web services.
Using the Web Service service
You can interact with the Web Service service by developing a process in LiveCycle Workbench that uses the service. You can accomplish
the following tasks by 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 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. The Web Service service supports the Table data type, which
SAP web services can require. An SAP table is similar to a database table composed of columns, where each row in the table represents
a record.
• 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 9.5 Help.
139
37. 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, see the main XMP page on the Adobe website.
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. Users can also add custom properties with a unique name and value.
•
In the Metadata dictionary of the document catalog. This dictionary contains metadata that is 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 that contain associated XMP metadata. However,
the XMP Utilities service does not provide the ability to manipulate such component-level metadata.
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.
ADOBE LIVECYCLE ES2.5
XMP Utilities Service
•
140
LiveCycle ES2.5 Services
Properties in the Info dictionary that are not listed in “Document Information Dictionary” in 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, values you specify will be overridden.
Using the XMP Utilities service
You can accomplish the following tasks by 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: Available only in LiveCycle Workbench. 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: Available only in Workbench. 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 9.5 Help. For information about developing
client applications that programmatically interact with this service, see Programming with LiveCycle ES2.5.
141
38. \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 that uses the service. You can
accomplish the following tasks by using this service:
•
Configure the 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 by using an XSLT script that is stored as process data. The XML document is also stored as process data.
Transform an XML document by 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 view the result.
• Save the resultant XML document as process data.
For information about developing processes that use this service, see LiveCycle Workbench 9.5 Help.
You can use the Applications and Services pages in LiveCycle Administration Console to configure default properties for this service. (See
XSLT Transformation service settings in LiveCycle ES2.5 Administration Help.)
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