Generate PDFs from HTML with Embedded Business Data (Adobe Integration)

Adobe PDF Services is an Adobe service that provides PDF generation and conversion via API. Questetra BPM Suite features an automated Step [Adobe: PDF Generation (HTML to PDF)] that calls Adobe PDF Services to generate PDF files from HTML files.

In this article, while building a Workflow App that generates a simple quote as a PDF, we will explain the preparation and settings required to use this Step. The basic method for creating HTML inserted with business data is the same as when integrating with DocRaptor. Please refer to the article Generating PDF files from HTML with inserted business data (integrated with DocRaptor). Notes specific to Adobe PDF Services are explained under “Preparing the Source HTML with Inserted Business Data”.

How the Step Works

[Adobe: PDF Generation (HTML to PDF)] operates in the following order:

1. Uploads the HTML file stored in the File-type Data Item to Adobe PDF Services
2. Requests conversion to PDF
3. Once conversion is complete, downloads the PDF file and saves it in the File-type Data Item

Conversion is performed asynchronously on the Adobe PDF Services side. The Case waits at this Step until conversion finishes.

Creating the Sample App

Because HTTP authorization settings are registered linked to a Workflow App (refer to “Registering HTTP Authorization Settings”), we first create the Workflow App, place the steps, and define the Data Items.

• [Start Event]
• “Data Entry” ([Human Task])
• “HTML File Generation” ([Text File Generator])
• “PDF Generation” ([Adobe: PDF Generation (HTML to PDF)])
• [End Event]

The Data Items are as follows:

Obtaining Adobe PDF Services Credentials

To call Adobe PDF Services, a Client ID and Client Secret are required. Create Credentials by following the Getting Started procedures for the Adobe PDF Services API on the Adobe Developer website. Signing in with an Adobe ID is required. Creation procedures are subject to change. Please check Adobe documentation for the latest steps.

Creating Credentials issues the following two items. Both are used in “Registering HTTP Authorization Settings”.

• Client ID
• Client Secret

Credentials created through this procedure are free, but there is a limit on the volume that can be processed. To increase the limit, enter into a paid contract with Adobe. For details, refer to Adobe documentation (Licensing and Usage Limits).

Preparing the Source HTML

In this article, HTML written with SpEL expressions where business data is inserted is referred to as “Source HTML”. Exporting the Source HTML to an HTML file using the automated Step [Text File Generator] produces an HTML file inserted with business data. This is passed to [Adobe: PDF Generation (HTML to PDF)]. For writing SpEL expressions and template editing, refer to “Preparing the Source HTML with Inserted Business Data” and “Editing Templates” in the DocRaptor integration article “Generating PDF files from HTML with inserted business data (integrated with DocRaptor)“.

Write CSS inside the HTML, and embed images into the HTML in data: format or reference them via URLs accessible over the internet. You cannot save CSS or images as separate files in the “HTML File” Data Item together (refer to the settings for the “PDF Generation” step described later). When referencing via URL, depending on the image host, Adobe PDF Services may fail to retrieve the image, resulting in it not being displayed in the PDF.

The Source HTML in the DocRaptor integration article contains CSS intended for DocRaptor’s conversion engine (such as -prince-float). Because the appearance may not be the same in Adobe PDF Services, if you use the Source HTML from the DocRaptor integration article as-is, verify the appearance in the generated PDF.

Settings for “HTML File Generation” Step

The setting items for the “HTML File Generation” step ([Text File Generator]) and the values to set in the sample App are as follows:

C6 of the “HTML File Generation” Step must be set to text/html. If unset, it will be saved as text/plain, causing an error during Content-Type verification in the “PDF Generation” Step.

The Source HTML to set in C4 of the “HTML File Generation” Step is as follows:

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<style>
  body { font-family: sans-serif; margin: 2cm; }
  h1 { font-size: 20pt; }
  table { width: 100%; border-collapse: collapse; margin-top: 1cm; }
  th, td { border: 1px solid #999; padding: 6px; }
  td.amount { text-align: right; }
</style>
</head>
<body>
  <h1>Quotation</h1>
  <p>To: #{#escaper.escapeHtml(#q_customer)}</p>
  <p>Quotation No.: #{processInstanceId}</p>
  <table>
    <tr><th>Item</th><th>Amount</th></tr>
    <tr><td>#{#escaper.escapeHtml(#q_item)}</td><td class="amount">$#{#q_amount}</td></tr>
  </table>
</body>
</html>

When the “HTML File Generation” Step is executed, SpEL expressions are replaced with Data Item values and Case IDs. The Recipient and Item Name are inserted after HTML escaping with #escaper.escapeHtml(), so even if inputs contain < or &, the HTML structure will not break.

Registering HTTP Authorization Settings

Open the settings screen for the “PDF Generation” step and click [Set up Setting] under “C1: OAuth2 Setting”. The “HTTP Authorization Setting Adobe: Generate PDF” screen will open in a separate window.

This screen is dedicated to Adobe PDF Services. “Auth Type” (OAuth2 Client Credentials), “Token Endpoint URL”, and “Scope” are predefined values displayed at the top of the screen. There are no operations to select or enter these. Because access tokens are retrieved during step execution using the Client ID and Client Secret, there is no operation to retrieve them at registration time.

HTTP authorization settings include App-specific settings held for each Workflow App, and settings shared by all workflow Apps, selectable from other Workflow Apps. Only System Administrators can edit settings shared across all Apps. In this article, we use App-specific settings. For details on types of HTTP authorization settings, refer to Understanding HTTP Authorization Settings.

Click [Add] under “App-specific Settings”, enter the following three items, and click [Save].

Saving returns to the list of HTTP authorization settings. Switch to the Step settings screen window. The registered name will be used as a selection choice for “C1: OAuth2 Setting” in the next section.

Settings for “PDF Generation” Step

The setting items for the “PDF Generation” step ([Adobe: PDF Generation (HTML to PDF)]) and the values to set in the sample App are as follows:

If the registered name does not appear in the choices for “C1: OAuth2 Setting”, reload the Step settings screen.

The C2 Data Item in the “PDF Generation” Step must store exactly one HTML file with a Content-Type of text/html. For errors when conditions are not met, refer to the table in “Verifying Operation”.

Verifying Operation

Click [Start Debug Case] in the properties of the Start Event on the workflow diagram, and click [Start Case] in “Case Debugging Execution”. Enter the Recipient, Item Name, and Amount in the “Data Entry” step and complete the task. When debugging execution finishes, open the PDF File on the Case details screen and verify that the entered values are inserted.

Because Adobe PDF Services is called even during debug execution, it counts toward your usage volume. If you revise the Source HTML repeatedly, pay attention to the limits explained in “Obtaining Adobe PDF Services Credentials”.

When a PDF is not generated, check the automated processing log for errors in the “PDF Generation” Step. Main error messages are as follows:

Related Articles & Reference

Related Articles

• Generating PDF files from HTML with inserted business data (integrated with DocRaptor)
• Understanding HTTP Auth Settings

Reference

• Adobe: PDF Generation (HTML to PDF)
• Text File Generator