Using the PDF Converter

The PDF Converter is available for use when the Save as PDF control is not present on a view or form or the designer don't want to use the Save as PDF control. The Broker also allows added functionality as you can specify dynamic URL’s and HTML and you are not limited to taking a snapshot of what is currently reflected on the screen. A snapshot can be taken for example of http://www.google.com.

When using the PDF Converter, the following should be considered:

  • Authorization inheritance will be broken by default on the SmartObject in order to prevent unauthorized use of this SmartObject in solutions. Security Administrators can grant view permissions on the SmartObject to specific users that are aware of the risks of using it in their solutions.

  • Since the PDF Converter relies heavily on manual input, the outcome can not be controlled and debugging might be required if the behavior does not conform to the intended use. It is important to ensure the correctness of what is captured before continuing with the process.
  • It is highly recommended to rather use the Save as PDF control as all of the above is built into the logic behind the control.
  • It is important to use a valid SSL certificate in environments with an HTTPS URL. If the certificate is invalid or self-signed, the PDF may fail to convert the view or form, CSS style files may not be included, and images may not render in the PDF.
  • Other scenarios where the PDF converter may fail are when there are various security restrictions on the computer or network, like the firewall blocking access to the Certificate Revocation List.
  • See PDF Converter Server-Side Request Forgery Prevention Configuration for information about security settings you can configure to restrict which hosts and IP addresses it is allowed to load any type of resource from.
See the following resources for more information:

The PDF Converter has three methods:

  • Create PDF from HTML (Raw HTML to PDF Format)
  • Create PDF from URL (Captures a URL to PDF Format)
  • Create PDF from HTML or URL

HTML - Creates a PDF file from HTML extracted from a page at a certain point in time
URL - Creates a PDF file after the page is loaded and after the conversion delay (See the diagram illustrating the different stages of the PDF conversion for more information)
HTML or URL - Detects if the content is HTML or URL and runs the appropriate method above

These methods are available in the ServiceObject Explorer when creating an Advanced SmartObject.

The URL option in the Create PDF from URL and Create PDF from HTML or URL methods of the PDF Converter only support Windows and Anonymous authentication. Any authentication that requires entering user credentials are not supported by these methods and may not behave as expected. It is advised to rather use the Save as PDF control in these cases.

The table below describe the options for successfully using the URL methods in your environment.

Authentication Description
Windows authentication (preferred configuration)
  • Default option is to use Forms authentication on the SmartForms runtime site in Internet Information Services (IIS) with Windows STS as the Issuers. The Windows STS must be the only Linked Issuer selected for the Realm. See Issuers for more information about adding an issuer.

    • or

  • Enable Windows authentication and disable Forms authentication on the SmartForms runtime site in Internet Information Services (IIS).
Anonymous authentication
  • Set each SmartForm that you are trying to convert to use Anonymous access, see Anonymous Views and Forms.

    • or

  • Enable Anonymous authentication and disable Windows and Forms authentication on the SmartForms runtime site in Internet Information Services (IIS).

Secondary SmartForms runtime site

If your current runtime site doesn’t match these requirements, you can also use another site that is not publicly available but is accessible by the PDF Converter service. Start by creating a secondary runtime site. See Configuring a Secondary SmartForms Runtime Site for more information. Apply authentication as shown above.

You can also create a new realm for the secondary site and set the Linked Issuers to only include Windows STS as above. Search for "realm" in the web.config file of the site and set it to use the new realm.

When using these methods, the following properties are applicable:

The values of the properties in Runtime should be provided as follows:

Properties Description
HTML string This must be an HTML value, and could be something as follows:
Copy

HTML string

<html>
<body>
<h1>My First Heading</h1>
<p>My first paragraph.</p>
</body>
</html>
This property applies to the HTML method
URL string This is the entire URL that you are attempting to access, for example: http://www.google.com. This property applies to the URL method
SmartObject Name The name of the storage SmartObject. This SmartObject is used to store the PDF that is created. The out of the box PDF SmartObject is called PDFFile. You can create your own SmartObject and save it in a separate folder in the category tree. See Debugging the PDF Converter and How To: Create a PDF file using the PDF Converter in an Advanced SmartObject for more information
SmartObject Method The method to execute that saves the PDF output in the storage SmartObject. Type Create
SmartObject File Property Name The property in the storage SmartObject where the PDF is stored. The property must be of type File. Type PDF
ID Property Name The property name that is queried to populate ID Property Value once a PDF is saved to the storage SmartObject. You can use this property to lookup the PDF that is saved in the storage SmartObject. Type ID
File Name This is the name that is used for the file saved in the storage SmartObject. This name shows when you try to reload or download the PDF. Type a name for the PDF file
Page Size Type a Page Size, see the Save as PDF control topic for Page sizes
Page Orientation Type the Page Orientation, see the Save as PDF control topic for Page Orientation options
URL Base The base value of your URL consisting of the scheme, hostname, and path. It is used to load the JS and CSS from the references inside the HTML and CSS. If the URL you’re aiming at contains any parameters, they should be included in the above “URL string” value, but excluded from the value provided here. As such, this value will also be something like: http://www.google.com. This property applies to the HTML method.
Conversion Delay The delay to wait after the BrowserLoadTimeout, and is applied before the SmartFormsReadyCheck and BrowserPrintPdfTimeout. See PDF Converter Logging for information about this property and a diagram illustrating the different stages of the PDF conversion. This property applies to the URL method
Clean iFrames

Set to True by default. Definitions:

  • True - The broker ensures that it can ping each Content control URL and if unsuccessful replaces it with a non-crashing URL that renders to be displayed on the PDF created and inform the user that the page could not load. When using many Content controls on a Form, setting it to true might have a performance impact.
  • False - The broker will try and render the content of Content controls. If the URL cannot be located as a result of no internet connectivity for example the PDF document will not be created. Typically it would be set to false if it can be guaranteed that all Content controls will render when the PDF document is rendered

This property applies to the HTML method.
Left Margin

Sets the left margin of the generated PDF in points. Points: 1pt = 1/72 of an inch. The default is 72pt. Specify numeric (1in) or point (72pt) values
Right Margin

Sets the right margin of the generated PDF in points. Points: 1pt = 1/72 of 1 inch. The default is 72pt. Specify numeric (1in) or point (72pt) values
Top Margin

Sets the top margin of the generated PDF in points. Points: 1pt = 1/72 of 1 inch. The default is 72pt. Specify numeric (1in) or point (72pt) values
Bottom Margin

Sets the bottom margin of the generated PDF in points. Points: 1pt = 1/72 of 1 inch. The default is 72pt. Specify numeric (1in) or point (72pt) values
ID Property Value The value of the record ID of the SmartObject that was executed. Select the property name in the “ID Property Name” field. The value of this property populates the PDF Control value after an execution was successfully done. Can be used in a workflow to load the saved PDF file
  • When running the PDF Converter as the Service Account, the PDF document will contain all data that the Service Account can see for the specific execution request. For example: If collateral is hidden or if the user does not have rights, the service account user won't see or have access to the view or form that they're trying to convert. It will only access data that the Service Account can see.
  • FormsSTS or any authentication that requires a user typing a user name and password is not supported.
  • When using the SmartObject created using the Service Object in a view, a button and rule are automatically added to execute the specific method when clicked.
  • Once the PDF file is created, the File can be accessed by creating a List View of the PDFFile SmartObject or the SmartObject created for this purpose, see the Save as PDF control topic.

Use any of the 3 PDF Converter SmartObject methods as part of a workflow to create a PDF. The properties are configurable as mentioned above.

You can enable logging to debug the PDF conversion, and then use the logs to create a support ticket if required. See PDF Converter Logging for settings available for logging and Debugging the PDF Converter for steps on debugging. For more information on SmartForms debugging, see the topic Debugging Forms.

  • Issue: When there are invalid or self-signed SSL certificates on the same environment as the PDF Converter service and trying to generate a PDF, the PDF may fail to convert the view or form, CSS style files may not be included, and images may not render in the PDF.
    Resolution: Use a valid SSL certificate in environments with an HTTPS URL.