Reports

All of the objects that you place into Cloud CMS can be operated against to produce exports that consist of consolidated or reported information. You can use this capability to generate reports in CSV (comma-separated value) format as well as merged PDFs and ZIP archives.

Exports are generated from collections of objects. These objects might be collected by hand or they might consist of results sets from a document list, search page or report record set. The Cloud CMS user interface provides methods for generating these collections and exporting them to a variety of formats.

Exported results can be downloaded, emailed or stored within Cloud CMS as a newly-created document.

An export essentially consists of the following steps:

Start the Export. When an export is started, it is given a configuration that describes what to export and how to package up the results. The export itself runs as a background job. An exportId is made available to identify the export in the future to determine it's availability.

Wait for the Export to Finish. Status checks are made using the exportId from the previous step.

Do something with the Export's files. Something acquires or operates against the results of the export. For example, you might fetch the resulting ZIP document using its exportId. Or you might email the contents to a friend as an email attachment.

Export Configuration

The export configuration tells the export process what to work on and how to package up the results.

Common Properties

name

type

required

description

references

array

true

an array of reference strings for objects to be exported

package

string

false

how to package results (either "CSV", "PDF", or "ZIP" - default is "ZIP")

includeMetadata

boolean

false

Whether to include JSON of objects in report generation

includeAttachments

boolean

false

Whether to include attachments of objects in report generation

includeAttachmentIds

array

false

The string IDs of any attachments to be included

fields

array

false

The dot-delimited string identifiers for any fields to include

The only required property is the references array which identifies which objects should be exported. Objects are specified as references which generally follow the format:

{type}://{platformId}/{datastoreId}/{objectId}

If includeAttachmentIds is not specified, the "default" attachment will be exported. Typically, this is what you will want. However, in some cases, you may want to export other attachment IDs or multiple attachments per document.

If fields is not specified, all JSON fields will be included in the export.

CSV Exports

For CSV exports, no additional properties are required. The CSV export will automatically parse the property IDs for each of the objects in your export and construct columns that are the union of properties across all objects. Object properties are then placed into rows within the CSV export.

CSV exports do not support attachments. Thus, the includeAttachments and includeAttachmentIds properties have no effect for this package type.

PDF Exports

For PDF exports, you can elect to have Cloud CMS auto-generate your PDFs using its built-in transformer subsystem or you can specify a PDF generation template to use to customize the PDF build. You can also elect to merge generated PDFs together (for multiple objects) into a single PDF output.

name

type

required

description

pdfTemplateRepositoryId

string

false

ID of the repository containing the PDF template

pdfTemplateBranchId

string

false

ID of the branch containing the PDF template

pdfTemplateNodeId

string

false

ID of the node for the PDF template

mergePdfs

boolean

false

Whether to merge PDF entries into a single PDF

To specify a PDF generation template, use the pdfTemplateRepositoryId, pdfTemplateBranchId and pdfTemplateNodeId properties to point to the Cloud CMS document (or node) that contains your PDF generation template.

You can specify PDF generation templates using Freemarker, Handlebars and/or Markdown. You can also use .docx files to generate PDFs using MERGE fields.

Use the mergePdfs property to tell the exporter to merge all of the generated PDFs together into a single document. In this case, if you're using a PDF generation template, it will be run once with the full object set for all objects at the same time.

ZIP Exports

For ZIP exports, you can have the exporter convert your ZIP entry files to PDF before zipping.

name

type

required

description

zipUsePdfEntries

boolean

false

whether to convert ZIP entries to PDF before zipping

By default, the entries of the ZIP file are not converted to PDF. The raw assets are zipped up, untouched.

Exporting

You can run an export like this:

// the platform
var platform = ...;
// assume we have a collection or result map of nodes
var nodes = ...;
// export a single PDF of all of the attachments
platform.runExport(nodes, {
"package": "PDF",
"mergePdfs": true,
"includeMetadata": false,
"includeAttachments": true
}, function(exportId, status) {
// we now have the exportId!
});

This kicks off the export and waits for it to complete. Once it completes, the exportId is given to you along with the status of the export.

Now that the export has completed, you can do things with the exported files.

For any of these calls, you can also specify the download to come at you with the "Content-Disposition" header flipped on. This allows the files to be saved instead of opened within the browser. Just add the following:

Let's generate a PDF for this content item. We can do so by creating another node (in this case, of type n:pdf_template. This node doesn't need to have anything on it in terms of JSON or metadata, but it should have an attachment which will hold our PDF template. Set the attachment mimetype to application/freemarker and enter the following:

The PDF template is given a model which consists of root-level objects. Each object is a node that we pass in to the PDF template processor.

Controlling the Merge Sequence

If you set mergePdfs to true, then all of the nodes will be passed into a single PDF generation process and a single PDF will be produced. If some of your nodes have attachments (such as Word documents or other PDF documents) that you'd like be included as part of the merge, you can do so by specifying the mergePdfsSequence.

The mergePdfsSequence array consists of string values which are references to nodes within Cloud CMS. Node references take the structure:

node://<platformId>/<repositoryId>/<branchId>/<nodeId>

You can also use the special marker pdf to indicate where the merged PDF should be inserted.

Here is an example where we generate a PDF and then merge two additional PDFs into it (one in the front and one in the back):