Using Assembler to Create PDF Portfolios (PDF Packages)

You can use the Assembler service to combine multiple documents into a PDF Portfolio that specifies how a viewer application’s user interface presents collections of file attachments. When your process or application invokes Assembler, it provides a Document Description XML (DDX) that describes the PDF Portfolio you want to produce. This article describes different types of PDF Portfolios and the DDX expressions you can use to produce them.

This article addresses the following types of PDF Portfolios:

    Simple: A collection of files, each of which is defined only by the basic information in the file specification (for example, file name, size, MIME type, and creation date). Adobe® Reader® 8.0 and Adobe Acrobat® 8.0 introduced support for this feature. (See Creating a simple PDF Portfolio .)

    Augmented file descriptions: Same as a simple PDF Portfolio with the addition that each file is described with additional information.Viewing applications can use the additional information to sort or identify the files in the portfolio.The syntax of the addition information is specified in a schema that is included in the PDF Portfolio. Adobe Reader 8.0 and Acrobat 8.0 introduced support for this feature.(See Creating a PDF Portfolio with augmented file descriptions .)

    Aggregated PDF Portfolios: A collection of files that are assembled from other PDF Portfolios that omit layouts (self-contained user interface for navigating the file sin the collection). The files in those source PDF Portfolios are included with their augmented file descriptions (if present). (See Creating PDF Portfolios aggregated from other PDF Portfolios.)

    Contains its own user interface: A more complex or dynamic PDF Portfolio can include a PDF Portfolio Layout (a self-contained user interface for navigating the files in the collection). Adobe Reader 9.0 and Acrobat 9.0 introduced support for this feature. Assembler cannot yet create PDF Portfolios that include PDF Portfolio Layouts, nor can it create PDF Packages that group the collection contents into a folder hierarchy; however, it can add files to existing PDF Portfolio with these characteristics. (See Creating a PDF Portfolio that contains its own user interface.)

For a definition of the terms PDF Package, PDF Portfolio, and PDF Portfolio Layout, see PDF Packages vs. PDF Portfolios, which is located in the December 2008 archive of this blog. For information about the attributes that comprise a PDF Portfolio, see ISO 32000-1:2008 – Document management — Portable document format.

Creating a simple PDF Portfolio

Here is a DDX example that creates a PDF Portfolio that contains a cover sheet and two component files. If the cover sheet is not a PDF file, Assembler attempts to convert the file to PDF. You can omit the cover sheet, in which case Assembler provides a default cover sheet for you.

This DDX example omits a schema, which means that (assuming doc2 is not a PDF Portfolio) the component files are described by only the standard file specification information (file name, creation date, MIME type, and size). Although the PDF files in a PDF Collection may contain metadata (for example Author, Title, Keyword, and Creating Application), the Acrobat user interface for PDF Collections does not use this information to describe component files.

<DDX xmlns="http://ns.adobe.com/DDX/1.0/"><PDF result="outDoc" ><PDF source="doc1" bookmarkTitle="Cover"/><PackageFiles source="doc2" required="false"><File filename="MyFirstFile.pdf"mimetype="application/pdf"/></PackageFiles><PackageFiles source="doc3" required="false"><File filename="MySecondFile.txt"mimetype="text/plain"/></PackageFiles><PackageFiles source="doc4" required="false"><File filename="MyCollection.pdf"mimetype="application/pdf"/></PackageFiles></PDF></DDX>

The files specified in the PackageFiles elements can be ordinary PDF documents, other PDF Portfolios, or other file formats:

  • PDF files. When the result PDF Portfolio is viewed in the Acrobat list layout, users see a thumbnail of these files. Any of the component PDF Portfolios can be opened in a separate window.
  • PDF Portfolios. Same as ordinary PDF files except users see a thumbnail of the cover sheets for the component PDF Portfolios. These files can be opened in a separate window.
  • Other file formats. Assembler does not convert non-PDF documents into PDF. Rather it leaves such files in their unaltered state. These files can be opened in a separate window provided an application is available that supports the file format.

The following screen shot shows the Acrobat list layout for the resulting PDF Portfolio.

Acrobat layout view of a simple PDF Portfolio

Creating a PDF Portfolio with augmented file descriptions

Here is a DDX example that creates a PDF Portfolio that contains a cover sheet, two files that contain augmented descriptions, and a schema that describes the non-standard attributes that can be associated with each file in the portfolio. (The standard attributes are those specified in the file specification.) In addition, the package specification can include elements that specify display order, sort order, and target locale, as described in the DDX Reference.

<DDX xmlns="http://ns.adobe.com/DDX/1.0/"><PDF result="outDoc" initialView="firstPage"><Package><Schema><Field name="Name" type="Text"/><Field name="Animal" type="Text"/><Field name="Breed" type="Text"/><Field name="Color" type="Text"/><Field name="Gender" type="Text"/><Field name="Age" type="Number"/><Field name="Altered" type="Text"/><Field name="Location" type="Number"/><Field name="File Name" type="Filename"/></Schema></Package><PDF source="cover" bookmarkTitle="Cover"/><PackageFiles source="shasta" required="false"><File filename="Shasta.pdf" mimetype="application/pdf"/><FieldData name="Name">Shasta</FieldData><FieldData name="Animal">Dog</FieldData><FieldData name="Breed">Keeshond</FieldData><FieldData name="Color">Grey</FieldData><FieldData name="Gender">Male</FieldData><FieldData name="Age">10</FieldData><FieldData name="Altered">Yes</FieldData><FieldData name="Location">95070</FieldData></PackageFiles><PackageFiles source="sam" required="false"><File filename="Sam.pdf" mimetype="application/pdf"/><FieldData name="Name">Sam</FieldData><FieldData name="Animal">Dog</FieldData><FieldData name="Breed">Grayhound</FieldData><FieldData name="Color">Grey</FieldData><FieldData name="Gender">Male</FieldData><FieldData name="Age">8</FieldData><FieldData name="Altered">Yes</FieldData><FieldData name="Location">95070</FieldData></PackageFiles></PDF><InitialViewProfile name="firstPage" openToPage="1"show="BookmarksPanel" magnification="FitPage" /></DDX>

The following screen shot shows the appearance of the schema information in the Acrobat 9 list view of the PDF Portfolio produced by the above DDX example. Notice that each entry in the schema is presented with a column for corresponding values created by the PackageFiles element.

Screen shot of the collection created with the above DDX example

Notice that the Filename field appears in the schema but that the files’ PackageFile element do not provide a corresponding value. That’s because Acrobat obtains the values for this field from the file specifications for the component files. Including Filename in the schema ensures that file name appears in the Acrobat list view.

PDF documents contain PDF metadata such as Author, Title, Keyword, and Creating Application. Currently, Assembly does not provide any mechanism for accessing this data, not even as process data. This means that it is not possible to use DDX to create a PDF Portfolio that includes the PDF document’s metadata in the user interface; however, you may be able to use JavaScript to generate a DDX file that creates such a PDF Portfolio.

Creating a PDF Portfolio aggregated from other PDF Portfolios

Here is a DDX example that creates a PDF Portfolio assembled from a cover sheet and two PDF source elements. If either of the source elements contains a PDF Portfolio, Assembler adds the following items from those portfolios to the resulting PDF Portfolio:

  • Component files
  • Schemas (if present) aggregated into a new schema.

Assembler removes any PDF Portfolio Layouts contained in the PackageFiles.

<DDX xmlns="http://ns.adobe.com/DDX/1.0/"><PDF result="outDoc" initialView="firstPage"><PDF source="cover" bookmarkTitle="Cover"/><PackageFiles><PDF source="collection1" required="false" /><PDF source="collection2" required="false" /></PackageFiles></PDF><InitialViewProfile name="firstPage" openToPage="1"show="BookmarksPanel" magnification="FitPage" /></DDX>

For example, if collection1 is a PDF Portfolio that specifies the following schema definition:

<Package><Schema><Field name="Name" type="Text"/><Field name="Animal" type="Text"/><Field name="Breed" type="Text"/><Field name="Color" type="Text"/><Field name="Gender" type="Text"/><Field name="Age" type="Number"/></Schema></Package>

And collection2 is also a PDF Portfolio that specifies the following schema definition:

<Package><Schema><Field name="Name" type="Text"/><Field name="Animal" type="Text"/><Field name="Altered" type="Text"/><Field name="Location" type="Number"/><Field name="File Name" type="Filename"/></Schema></Package>

Then the schema in the resulting PDF Portfolio will be:

<Package><Schema><Field name="Name" type="Text"/><Field name="Animal" type="Text"/><Field name="Breed" type="Text"/><Field name="Color" type="Text"/><Field name="Gender" type="Text"/><Field name="Age" type="Number"/><Field name="Altered" type="Text"/><Field name="Location" type="Number"/><Field name="File Name" type="Filename"/></Schema></Package>

The screen shot shows the appearance of the resulting PDF Portfolio when viewed in Acrobat list view. Notice that the view shows fields that indicate the schemas from both component PDF Portfolio are combined. Also notice that the cover page in the result is a 3-page document that includes the cover page from the cover document and the cover pages from collection1 and collection2.

Acrobat list view of a PDF Portfolio assembled from other portfolios that contains different schemas

Creating a PDF Portfolio that contains its own user interface

Assembler can add component files and schemas to a PDF Portfolio that already includes a PDF Portfolio Layouts, but it cannot create original PDF Portfolios that include such layouts.

Here is a DDX example that adds a new document to the PDF Portfolio provided in the PDF source element. If the PDF source element contains a PDF Portfolio that includes a PDF Portfolio Layout, then the result also contains the PDF Portfolio Layout.

<DDX xmlns="http://ns.adobe.com/DDX/1.0/"><PDF result="outDoc" ><PDF source="myPortfolioWithLayout"/><PackageFiles source="doc2" required="false"><File filename="MySecondFile.txt" mimetype="text/plain"/></PackageFiles></PDF></DDX>

If the layout in the PDF source document supports schemas (augmented file descriptions), the files you add should specify values for those fields, as shown in this DDX example:

<DDX xmlns="http://ns.adobe.com/DDX/1.0/"><PDF result="outDoc" ><PDF source="myPortfolioWithLayout"/><PackageFiles source="harry" required="false"><File filename="Harry.jpg" mimetype="image/jpeg"/><FieldData name="Name">Harry</FieldData><FieldData name="Animal">Dog</FieldData><FieldData name="Breed">Saint Bernard</FieldData><FieldData name="Color">Tan and white</FieldData><FieldData name="Gender">Male</FieldData><FieldData name="Age">8</FieldData><FieldData name="Altered">Yes</FieldData><FieldData name="Location">44202</FieldData></PackageFiles></PDF></DDX>

Using the following DDX example with PDF Portfolios that contain layouts yields unpredictable results.

<DDX xmlns="http://ns.adobe.com/DDX/1.0/"><PDF result="outDoc" initialView="firstPage"><PDF source="myPortfolioWithLayout" /><PackageFiles><PDF source="collection1" required="false" /><PDF source="collection2" required="false" /></PackageFiles></PDF><InitialViewProfile name="firstPage" openToPage="1"show="BookmarksPanel" magnification="FitPage" /></DDX>

For more information

For a complete description on DDX, see DDX Reference.

For instructions on creating a certified PDF Portfolio, see Certifying PDF Portfolios, which is located in the December 2008 archive of this blog.

For an introduction to PDF Portfolios, see the PDFDevJunkie blog on the Adobe Acrobat Developer site.

VN:F [1.9.22_1171]
Was this helpful? Please rate the content.
Rating: 0.0/10 (0 votes cast)

One Response to Using Assembler to Create PDF Portfolios (PDF Packages)

  1. Murat Kuru says:

    Thank for this helpful information. In my case I use AssemblerService/Invoke DDX to create portfolios. But I have to circulate the portfolio among people in a long lived process. Do you have any suggestion how to do that? How can I add submit button to portfolio to use in workspace?