The Communications feature is in beta.
Communications APIs help you combine XDP templates, XDP-based PDF documents, and Acrobat Forms (AcroForm) with XML data to generate print documents in various formats and enable you to create applications that let you:
Generate documents by populating template files with XML data.
Generate forms in various formats, including non-interactive PDF print streams.
Generate print PDFs from XFA form PDFs.
Generate PDF, PostScript, PCL, and ZPL documents in bulk by merging multiple sets of data with source templates.
Consider a scenario where you have one or more templates and multiple records of XML data for each template. You can use Communications APIs to generate a print document for each record. The result is a non-interactive PDF document. A non-interactive PDF document does not let users enter data into its fields.
The API reference documentation provides detailed information about all the APIs, parameters, authentication methods, and various services provided by APIs. The API reference documentation is also available in the .yaml format. You can download the .yaml for Batch APIs or non-Batch API.yaml file and upload it to postman to check functionality of APIs.
Uploading Communication APIs .yaml file to postman to check functionality of APIs.
Only members of forms-users group can access Communications APIs.
To enable Communications for your Forms as a Cloud Service environment:
Login to Cloud Manager and open your AEM Forms as a Cloud Service Instance.
Open the Edit Program option, go to the Solutions & Add-ons tab, and select the Forms - Communications option.
Run the build pipeline.
After the build pipleine succeeds, Communication APIs are enabled for your environment.
Typically, you create a template using Designer and use communications APIs to:
Then, the output document is stored to a file. You can design custom workflows to send the file to a network printer, a local printer, or to a storage system for archival. A typical out of the box and custom workflows look like the following:
You can use the generatePDFOutput API to create PDF document that is based on a form design and XML form data. The output is a non-interactive PDF document. That is, users cannot enter or modify form data. A basic workflow is to merge XML form data with a form design to create a PDF document. The following illustration shows the merging of a form design and XML form data to produce a PDF document.
You can use Communications APIs to create PostScript (PS), Printer Command Language (PCL), and Zebra Printing Language (ZPL) document that are based on a XDP form design or PDF document. The generatePrintedOutput API merges a form design with form data to generate a document. You can save the document to a file and develop a custom process to send it to a printer.
You can create separate documents for each record within an XML batch data source. You can generate documents in bulk and asynchronous mode. You can configure various parameters for the conversion and then start the batch process.
You can use the Communications APIs 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 Designer (that contain XFA streams).
Acrobat PDF forms
If you attempt to flatten a non-interactive PDF document, an exception occurs.
An interactive PDF document contains various elements that constitute a form. These elements may include fields (to accept or display data), buttons (to trigger events), and scripts (commands to perform a specific action). Clicking a button may trigger an event that changes the state of a field. For example, choosing a gender option may change the color of a field or the appearance of the form. This is an example of a manual event causing the form state to change.
When such an interactive PDF document is flattened using the Communications APIs, the state of the form is not retained. To ensure that the state of the form is retained even after the form is flattened, set the Boolean value retainFormState to True to save and retain the state of the form.
Communications APIs accepts both a form design that is typically created in Designer 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.
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>JJohnson@NoMailServer.com</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 complete access to the rendering capabilities of the Communications APIs, 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:
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.
A form design that is used with the Communications APIs 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 Designer Help.
If a font is installed on a client computer, it is available in the drop-down list in Designer. If the font is not installed, it is necessary to specify the font name manually. The “Permanently replace unavailable fonts” option in Designer can be off. Otherwise, when the XDP file is saved in Designer, 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 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.
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.
A device profile (XDC file) is a printer description file in XML format. This file enables the Communications APIs to output documents as laser or label printer formats. Communications APIs use the XDC files including these:
It is not necessary to modify these files to create documents. However, you can modify them to meet your business requirements.
These 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.
Communications APIs use an XCI configuration file to perform tasks, such as controlling whether the output is a single panel or paginated. Although this file contains settings that can be set, it is not typical to modify this value.
You can pass a modified XCI file while using a Communications API. 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.
Communications APIs start with the default XCI file (or the modified file). Then it applies values that are specified using the Communications APIs. These values override XCI settings.
The following table specifies XCI options.
|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/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 to AEM Forms server/Communications APIs 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 AEM Forms 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/version||Specifies the version of PDF document to generate.|
Ensure that the size of the template and XCI configuration files is larger than 16KB.
Ensure that the data xml file does not contain the XML declaration header. For example,
<?xml version="1.0" encoding="UTF-8"?>
For a batch configuration, only one instance of combination of values of OutputType(PDF, PRINT) and RenderType(PostScript, PCL, IPL, ZPL, etc.) is allowed.
Do not modify the Data Source USC Configuration/Azure Cloud Configuration used in a batch configuration while the batch is being run. Even after execution, if any update is required, create a copy of configuration instead of updating the one used in an existing batch configuration.