Creating PDF/A Documents

You can use the Output service to create a PDF/A document. Because PDF/A is an archival format for long-term preservation of the document’s content, all fonts are embedded and the file is uncompressed. As a result, a PDF/A document is typically larger than a standard PDF document. In addition, a PDF/A document does not contain audio and video content. Like other Output service tasks, you provide both a form design and data to merge with a form design to create a PDF/A document.

The PDF/A-1 specification consists of two levels of conformance, namely a and b. The major difference between the two is regarding the logical structure (accessibility) support, which is not required for conformance level b. Regardless of the conformance level, PDF/A-1 dictates that all fonts are embedded in the generated PDF/A document.

Although PDF/A is the standard for archiving PDF documents, it is not mandatory that PDF/A be used for archiving if a standard PDF document meets your company’s needs. The purpose of the PDF/A standard is to establish a PDF file that can be stored for a long period of time as well as meet document preservation requirements. For example, a URL cannot be embedded in a PDF/A because over time the URL may become invalid.

Your organization must assess its own needs, the length of time you intend to keep the document, file size considerations, and determine your own archiving strategy. You can programmatically determine if a PDF document is PDF/A compliant by using the DocConverter service. (See Programmatically Determining PDF/A Compliancy.)

A PDF/A document must use the font that is specified in the form design and fonts cannot be substituted. As a result, if a font that is located within a PDF document is not available on the host operating system (OS), then an exception occurs.

When a PDF/A document is opened in Acrobat, a message is displayed that confirms that the document is a PDF/A document, as shown in the following illustration.

Remarque : The AIIM web site has a PDF/A FAQ section that you can access at http://www.aiim.org/documents/standards/19005-1_FAQ.pdf.
Remarque : For more information about the Output service, see Services Reference for LiveCycle.

Summary of steps

To create a PDF/A document, perform the following steps:

  1. Include project files.

  2. Create an Output Client object.

  3. Reference an XML data source.

  4. Set PDF/A run-time options.

  5. Set rendering run-time options.

  6. Generate a PDF/A document.

  7. Retrieve the results of the operation.

Include project files

Include necessary files in your development project. If you are creating a custom application by using Java, include the necessary JAR files. If you are using web services, make sure that you include the proxy files.

The following JAR files must be added to your project’s class path:

  • adobe-livecycle-client.jar

  • adobe-usermanager-client.jar

  • adobe-output-client.jar

  • adobe-utilities.jar (Required if LiveCycle is deployed on JBoss)

  • jbossall-client.jar (Required if LiveCycle is deployed on JBoss)

if LiveCycle is deployed on a supported J2EE application server that is not JBoss, you will need to replace the adobe-utilities.jar and jbossall-client.jar files with JAR files that are specific to the J2EE application server on which LiveCycle is deployed.

Create an Output Client object

Before you can programmatically perform an Output service operation, you must create an Output service client object. If you are using the Java API, create an OutputClient object. If you are using the Output web service API, create an OutputServiceService object.

Reference an XML data source

To merge data with the form design, you must reference an XML data source that contains data. An XML element must exist for every form field that you want to populate with data. 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 if all XML elements are specified.

Set PDF/A run-time options

You can set the File URI option when creating a PDF/A document. The URI is relative to the J2EE application server hosting LiveCycle. That is, if you set C:\Adobe, the file is written to the folder on the server, not the client computer. The URI specifies the name and location of the PDF/A file that the Output service generates.

Set rendering run-time options

You can set rendering run-time options when creating PDF/A documents. Two PDF/A related options that you can set are the PDFAConformance and PDFARevisionNumber values. The PDFAConformance value refers to how a PDF document adheres to requirements that specify how long-term electronic documents are preserved. Valid values for this option are A and B. For information about level a and b conformance, see the PDF/A-1 ISO specification that is titled ISO 19005-1 Document management.

The PDFARevisionNumber value refers to the revision number of a PDF/A document. For information about the revision number of a PDF/A document, see the PDF/A-1 ISO specification that is titled ISO 19005-1 Document management.

Remarque : You cannot set the tagged Adobe PDF option to false when creating a PDF/A 1A document. PDF/A 1A will always be a tagged PDF document. Also, you cannot set the tagged Adobe PDF option to true when creating a PDF/A 1B document. PDF/A 1B will always be an untagged PDF document.

Generate a PDF/A document

After you reference a valid XML data source that contains form data and you set run-time options, you can invoke the Output service, causing it to generate a PDF/A document.

Retrieve the results of the operation

After the Output service performs an operation, it returns various data items such as XML data that specifies whether the operation was successful.

Create a PDF/A document using the Java API

Create a PDF/A document by using the Output API (Java):

  1. Include project files.

    Include client JAR files, such as adobe-output-client.jar, in your Java project’s class path.

  2. Create an Output Client object.

    • Create a ServiceClientFactory object that contains connection properties.

    • Create an OutputClient object by using its constructor and passing the ServiceClientFactory object.

  3. Reference an XML data source.

    • Create a java.io.FileInputStream object that represents the XML data source that is used to populate the PDF/A document by using its constructor and passing a string value that specifies the location of the XML file.

    • Create a com.adobe.idp.Document object by using its constructor and passing the java.io.FileInputStream object.

  4. Set PDF/A run-time options.

    • Create a PDFOutputOptionsSpec object by using its constructor.

    • Set the File URI option by invoking the PDFOutputOptionsSpec object’s setFileURI method. Pass a string value that specifies the location of the PDF file that the Output service generates. The File URI option is relative to the J2EE application server hosting LiveCycle, not the client computer.

  5. Set rendering run-time options.

    • Create a RenderOptionsSpec object by using its constructor.

    • Set the PDFAConformance value by invoking the RenderOptionsSpec object’s setPDFAConformance method and passing a PDFAConformance enum value that specifies the conformance level. For example, to specify conformance level A, pass PDFAConformance.A.

    • Set the PDFARevisionNumber value by invoking the RenderOptionsSpec object’s setPDFARevisionNumber method and passing PDFARevisionNumber.Revision_1.

    Remarque : The PDF version of a PDF/A document is 1.4 regardless of which value you specify for the RenderOptionsSpec object’s setPdfVersionmethod.
  6. Generate a PDF/A document.

    Create a PDF/A document by invoking the OutputClient object’s generatePDFOutput method and passing the following values:

    • A TransformationFormat enumeration value. To generate a PDF/A document, specify TransformationFormat.PDFA.

    • A string value that specifies the name of the form design.

    • A string value that specifies the content root where the form design is located.

    • A PDFOutputOptionsSpec object that contains PDF run-time options.

    • A RenderOptionsSpec object that contains rendering run-time options.

    • The com.adobe.idp.Document object that contain the XML data source that contains data to merge with the form design.

    The generatePDFOutput method returns an OutputResult object that contains the results of the operation.

    Remarque : The OutputResult object’s getRecordLevelMetaDataList method returns null.
    Remarque : You can also create a PDF /A document by invoking the OutputClient object’s generatePDFOutput2 method. (See Passing Documents located in Content Services (deprecated) to the Output Service.)
  7. Retrieve the results of the operation.

    • Create a com.adobe.idp.Document object that represents the status of the generatePDFOutput method by invoking the OutputResult object’s getStatusDoc method.

    • Create a java.io.File object that will contain the results of the operation. Ensure that the file name extension is .xml.

    • Invoke the com.adobe.idp.Document object’s copyToFile method to copy the contents of the com.adobe.idp.Document object to the file (ensure that you use the com.adobe.idp.Document object that was returned by the getStatusDoc method).

    Remarque : Although the Output service writes the PDF/A document to the location specified by the argument that is passed to the PDFOutputOptionsSpec object’s setFileURI method, you can programmatically retrieve the PDF/A document by invoking the OutputResult object’s getGeneratedDoc method.

Create a PDF/A document using the web service API

Create a PDF/A document by using the Output API (web service):

  1. Include project files.

    Create a Microsoft .NET project that uses MTOM. Ensure that you use the following WSDL definition: http://localhost:8080/soap/services/OutputService?WSDL&lc_version=9.0.1.

    Remarque : Replace localhost with the IP address of the server hosting LiveCycle.
  2. Create an Output Client object.

    • Create an OutputServiceClient object by using its default constructor.

    • Create an OutputServiceClient.Endpoint.Address object by using the System.ServiceModel.EndpointAddress constructor. Pass a string value that specifies the WSDL to the LiveCycle service (for example, http://localhost:8080/soap/services/OutputService?blob=mtom.) You do not need to use the lc_version attribute. This attribute is used when you create a service reference. However, specify ?blob=mtom to use MTOM.

    • Create a System.ServiceModel.BasicHttpBinding object by getting the value of the OutputServiceClient.Endpoint.Binding field. Cast the return value to BasicHttpBinding.

    • Set the System.ServiceModel.BasicHttpBinding object’s MessageEncoding field to WSMessageEncoding.Mtom. This value ensures that MTOM is used.

    • Enable basic HTTP authentication by performing the following tasks:

      • Assign the LiveCycle user name to the field OutputServiceClient.ClientCredentials.UserName.UserName.

      • Assign the corresponding password value to the field OutputServiceClient.ClientCredentials.UserName.Password.

      • Assign the constant value HttpClientCredentialType.Basic to the field BasicHttpBindingSecurity.Transport.ClientCredentialType.

      • Assign the constant value BasicHttpSecurityMode.TransportCredentialOnly to the field BasicHttpBindingSecurity.Security.Mode.

  3. Reference an XML data source.

    • Create a BLOB object by using its constructor. The BLOB object is used to store data that will be merged with the PDF/A document.

    • Create a System.IO.FileStream object by invoking its constructor and passing a string value that represents the file location of the PDF document to encrypt and the mode in which to open the file.

    • Create a byte array that stores the content of the System.IO.FileStream object. You can determine the size of the byte array by getting the System.IO.FileStream object’s Length property.

    • Populate the byte array with stream data by invoking the System.IO.FileStream object’s Read method and passing the byte array, the starting position, and the stream length to read.

    • Populate the BLOB object by assigning its MTOM field with the byte array contents.

  4. Set PDF/A run-time options.

    • Create a PDFOutputOptionsSpec object by using its constructor.

    • Set the File URI option by assigning a string value that specifies the location of the PDF file that the Output service generates to the PDFOutputOptionsSpec object’s fileURI data member. The File URI option is relative to the J2EE application server hosting LiveCycle, not the client computer

  5. Set rendering run-time options.

    • Create a RenderOptionsSpec object by using its constructor.

    • Set the PDFAConformance value by assigning a PDFAConformance enum value to the RenderOptionsSpec object’s PDFAConformance data member. For example, to specify conformance level A, assign PDFAConformance.A to this data member.

    • Set the PDFARevisionNumber value by assigning a PDFARevisionNumber enum value to the RenderOptionsSpec object’s PDFARevisionNumber data member. Assign PDFARevisionNumber.Revision_1 to this data member.

    Remarque : The PDF version of a PDF/A document is 1.4 regardless of which value you specify.
  6. Generate a PDF/A document.

    Create a PDF document by invoking the OutputServiceService object’s generatePDFOutput method and passing the following values:

    • A TransformationFormat enumeration value. To generate a PDF document, specify TransformationFormat.PDFA.

    • A string value that specifies the name of the form design.

    • A string value that specifies the content root where the form design is located.

    • A PDFOutputOptionsSpec object that contains PDF run-time options.

    • A RenderOptionsSpec object that contains rendering run-time options.

    • The BLOB object that contains the XML data source that contains data to merge with the form design.

    • A BLOB object that is populated by the generatePDFOutput method. The generatePDFOutput method populates this object with generated metadata that describes the document. (This parameter value is required for web service invocation only.)

    • A BLOB object that is populated by the generatePDFOutput method. The generatePDFOutput method populates this object with result data. (This parameter value is required for web service invocation only.)

    • An OutputResult object that contains the results of the operation. (This parameter value is required for web service invocation only.)

    Remarque : You can also create a PDF /A document by invoking the OutputClient object’s generatePDFOutput2 method. (See Passing Documents located in Content Services (deprecated) to the Output Service.)
  7. Retrieve the results of the operation.

    • Create a System.IO.FileStream object by invoking its constructor and passing a string value that represents an XML file location that contains result data. Ensure that the file name extension is .xml.

    • Create a byte array that stores the data content of the BLOB object that was populated with result data by the OutputServiceService object’s generatePDFOutput method (the eighth parameter). Populate the byte array by getting the value of the BLOB object’s MTOM field.

    • Create a System.IO.BinaryWriter object by invoking its constructor and passing the System.IO.FileStream object.

    • Write the contents of the byte array to the XML file by invoking the System.IO.BinaryWriter object’s Write method and passing the byte array.