Assembling multiple documents

You can create new PDF documents from other existing PDF documents by using the invokeDDX operation of the Assembler service. Typically, multiple existing documents are selected from a library and assembled as required at run time.

For more information about the Assembler service, see Services Reference for Adobe LiveCycle ES4.

The Assembler service requires the following items to assemble PDF documents:

  • A Document Description XML (DDX) document that provides instructions for assembling PDF documents

  • The PDF documents to be assembled

  • A location to store the resulting PDF document

For example, a business process assembles several existing PDF documents into a single PDF document, and adds a cover page to the document. The following illustration shows a portion of the process diagram that automates the process.

A Read Resource Content operation.

In this example, the DDX file that is used to assemble the documents is stored in the repository. At run time, the DDX file is retrieved and used as input data for the Assembler service. The documents to assemble are provided to the process when the process is invoked. Press F1 for more information.

    Prerequisites

    To use the invokeDDX operation, the following items need to be available to the process at run time:

    • The DDX document, in document data format.

    • The PDF documents to assemble, in document format.

    • The key words that are associated with the documents to assemble and the resulting PDF document. The keywords are defined in the DDX document.

    For the example process described above, the documents to assemble are provided as input values when the process is invoked, and the DDX document is retrieved from the repository by using the Repository service. The key words that are associated with the documents by the DDX document are known at design time.

    Configuration

    The invokeDDX operation of the Assembler service requires the following data items as input:

    • A document value that represents the DDX document, provided as the value of the DDX property of the operation.

    • A map value that holds the documents to be assembled, provided as the Input Document Map property of the operation. The keys for the map value are the key words that the DDX document defines. Each value in the map are either a document value that represents a single PDF document or a list of document values for representing multiple PDF documents.

    Typically, the PDF documents to assemble are available at run time as document values. In this case, a map value needs to be created and populated with the document values so that it can be used as the value of the Input Document Map property of the invokeDDX operation.

    The DDX document and the number of PDF documents to assemble determine whether the map value should contain document values or list values that hold document data items. For example, the following DDX document is used for the example process described above.

    <?xml version="1.0" encoding="UTF-8"?> 
<DDX xmlns="http://ns.adobe.com/DDX/1.0/"> 
    <PDF result="GeneratedDocument.pdf">  
        <PDF source="cover"/> 
        <PackageFiles>  
            <PDF source="attachments"/> 
            </PackageFiles>  
    </PDF> 
</DDX>

    The DDX document provides the following information about the documents to assemble:

    • The <PDF source="cover"/> element defines the cover key word, which is associated with the PDF document to use as the cover page.

    • The <PDF source="attachments"/> element defines the attachments key word, which is associated with several PDF documents to assemble.

    The map value must use cover and attachments as keys. The values for the keys must be list data items that hold document values:

    • Multiple PDF documents are associated with the attachments key word; therefore, the value for the attachments key needs to be a listdata item that holds the document values.

    • Data items in a map must be of the same type; therefore, although only one document is used as a cover page, the value for the cover key needs to be a list data item.

    Retrieving the DDX File

    In the example process diagram illustrated previously, the Read DDX File From Repository operation is a Read Resource Content operation that the Repository service provides:

    • The Resource URI property of the Input property group is used to specify the location of the DDX document in the repository.

    • The Result property is used to save the retrieved DDX document in a document variable.

    Assembling the document

    In the example process diagram illustrated previously, the invokeDDX operation needs to be configured so that it uses the DDX document that was retrieved from the repository and the PDF documents that are provided to the process as input data.

    • The value of the DDX property is specified as the value of the document variable that holds the DDX document.

    • The inputs property of the Input property group is used to identify the map variable that stores the documents to assemble:

      • The cover key is associated with a list variable that contains one document to use as the cover page of the assembled document.

      • The attachments key is associated with a list variable that contains all of the other documents that are to be assembled.

    • The value of the Result property of the Output property group is used to identify the map variable that stores the results of the invokeDDX operation. In this case, because only one document is assembled, the map includes one key/value pair. The key is result, as it was defined by the <PDF result="GeneratedDocument.pdf"> element in the DDX document. The value is a document value that represents the assembled PDF document.

    Other considerations

    This Quick Start uses a simple use case for describing how to use the Assembler service. However, the Assembler service can be used to manipulate PDF documents in many ways, such as extracting and inserting pages, disassembling documents based on bookmarks, and adding watermarks. Different combinations of document manipulations can also be performed.