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
See the following resources for more information:

The PDF Converter has three functions:

  • 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 at a certain point in time
URL - Creates a PDF file upon load of the page

These functions 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 functions, 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>
URL string This is the entire URL that you are attempting to access, for example: http://www.google.com
SmartObject Name The SmartObject used to create the PDF file. The default PDF SmartObject is called PDFFile. If another SmartObject was created with the correct properties as mentioned in the Save as PDF control topic, this name can be used
SmartObject Method Type Create
SmartObject File Property Name Type PDF
ID Property Name Type ID
File Name 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. 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
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.
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 executed 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 Forms Authentication is set to true, the execution request will return a login screen, which will reflect in the PDF
  • 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 SmartObjects as part of a workflow to create a PDF. The properties are configurable as mentioned above.

  • Issue: When you generate a PDF file on a mobile device, details on the PDF may be cut off and a scrollbar is visible.
    Resolution: Install the latest fix pack and set the removeMobileStyling key of the PDF Converter service instance to False. To see the setting after installing the fix pack you need to refresh the service instance. Edit the PDF Converter service instance (make no changes) and save. Edit the service instance again and the setting is available. Make the change and save, then restart the K2 server.
  • 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.