Save As PDF control

The Save as PDF control takes a snapshot of the View/Form at a particular point in time when an Event is executed, for example when a Button is clicked. The PDF snapshot is saved to a SmartObject and executed by using one of the Execute Control Method actions.

Internet Explorer is required to be installed on the K2 Host Server to render PDF documents

Follow the steps below to apply the Save as PDF control to a:

  • System generated SmartObject (Easy)
  • Newly created SmartBox SmartObject (Advanced)

Easy

  1. Add the Save as PDF control to a View or a Form
  2. Add a Rule to Execute the Control's Method (often on a Button click)
  3. Run the View or Form and execute the method 
  4. Create a List View linked to the SmartObject to view/access the PDF file

Advanced

  1. Create a SmartObject with an AutoNumber ID, and a File property
  2. Add the Save As PDF control to a View or a Form
  3. Set your SmartObject as the Data Source of the Save as PDF control 
    1. Click the ellipsis next to SmartObject in the Data Source panel
    2. Click the ellipsis next to SmartObject in the pop up dialog 
    3. Select your SmartObject
  4. Select a Page Size
  5. Select a Page Orientation
  6. Add a Rule to Execute the Control's Method (often on a Button click)
  7. Run the View or Form and execute the method
  8. Create a List View linked to the SmartObject to view/access the PDF file
  1. One of the following actions should be used to execute the Save PDF method:
    • Execute a control's method
    • Execute a subview control's method
    • Execute a View control's method that was opened in a subform
    • Execute a Form control's method that was opened in a subform
    • Execute a View control method
  2. When executing the control method, the value of the control is set to the record ID of the SmartObject that is used as the Data Source of the Save as PDF control. One example is where the control is mapped to a Data Field in a workflow and a Load method is executed on the SmartObject to attach the PDF File to an e-mail. Essentially it gives you a reference to the specific PDF document so you can load and use it in a subsequent step
  3. Only one PDF File is supported per one record ID
  4. Rules and Expressions can be used to set the Properties such as File Name if a unique name is required per PDF File
  5. When using tabs on a Form, all tabs are included as pages in the PDF document
  6. The PDF document is saved to the SmartObject selected as the Data Source in the properties section of the control
  7. The Save as PDF control should be dragged onto the View/Form for it to be available in the Execute Control Method Actions
  8. The Save as PDF control is available on View and Form level 
  9. When using a fixed Width such as 1024px for example on a Form containing a PDF control, the PDF created might contain scroll bars. To fix this, change the Page size of the control to a bigger size or adjust the Page Orientation. Following are calculations of the correct width to be used with the different Page sizes:
    Page SizePixel/inch (control)Pixels (Form Width)
    A033,13178
    A123,42246
    A216,51584
    A311,71123
    A48,3797
    A55,8557
    A64,1394
    A72,9278
    A82192
    A91,5144
    A10196
    ArchA9864
    ArchB121152
    ArchC181728
    ArchD222112
    ArchE343264
    B039,43782
    B127,82669
    B219,71891
    B313,91334
    B49,8941
    B56,9662
    Flsa1,5144
    HalfLetter8,5816
    Ledger171632
    Legal8,5816
    Letter8,5816
    11x17111056
    Note7,5720
  10. When using a List View with a fixed Width, the headers might not be properly aligned. The following variables could be considered when formatting the View or Form:
    • PDF Control: A2 Portrait
    • Form Dimensions:
      • Padding - (default) 12px
      • Themes - All themes
      • Border sizing - (default) 12px
      • Form Width - 1560px
  11. When using a Form with lots of Tabs or a List View with lots of columns, it is best to set the Orientation to Landscape and the Page Size to A3. This will render the PDF efficiently
  12. When using the default Out of the Box PDFFile SmartObject to store the PDF file, it is important to clean up unused PDF files on a regular basis to ensure that performance issues are not encountered when having to load PDF files. PDF files that are only required for the duration of the process can be subsequently removed for example
  13. Binding the Save as PDF control to a data source that is specifically used for document management can be useful when having to deal with large volumes of PDF files created. Microsoft SharePoint Document Libraries can be used for example to store the PDF files
  14. It is important to use a valid SSL Certificate on environments with a URL with a secure protocol. The third-party control will tend to fail to convert the web page and CSS style files and images will also not render in the PDF Document on environments with self-signed test SSL Certificates/Invalid SSL certificates
  15. Other scenarios where the PDF Converter might fail are when there are various security restrictions on the computer/network, like the firewall blocking access to the Certificate Revocation List
  16. Adobe Reader 5.0 and later versions are supported
  17. The Adobe Reader Application for Windows 8 tends to compress the PDF document. It is advised to rather use the Desktop Application

The Save as PDF control is available in the Export section of the Controls tab in the Toolbox.

Properties Description Can be set in runtime using Rules
Name A unique identifier for the selected control. This property is required No
SmartObject The SmartObject to be used when saving the PDF. The SmartObject should have a Create type function,  See Method, a File Property, a Number/Autonumber property, and a text property No
Method The method to be used to create the PDF. Only Create type functions are supported No
File The File type property is required for the SmartObject. The file type to be selected must always be PDF. No
Key Property The unique identifier of the SmartObject where the PDF file will be saved No
File Name The name of the PDF file created. This field is empty by default. If no name is specified, the default file is called PDFFile.pdf. Rules and Expressions can be used to set the File Name if a unique name is required per PDF File. Yes, see Control Properties Actions for more information
Append Date A Boolean value used to establish whether the date should be added to the end of the file or not. By default the option is selected which will then append the date. Yes, see Control Properties Actions for more information
Page Size A list of sizes available for the creation of the PDF document. The following sizes are available:
  • A0
  • A1
  • A2
  • A3
  • A4
  • A5
  • A6
  • A7
  • A8
  • A9
  • A10
  • ArchA
  • ArchB
  • ArchC
  • ArchD
  • ArchE
  • B0
  • B1
  • B2
  • B3
  • B4
  • B5
  • Flsa
  • HalfLetter
  • Ledger
  • Legal
  • Letter
  • 11x17
  • Note
 Yes, see Control Properties Actions for more information
Page Orientation

The following options are available:

  • Portrait
  • Landscape
 Yes, see Control Properties Actions for more information
Clean IFrames

Set to True by default. Definitions:

  • True - The control 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 control 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.
 Yes, see Control Properties Actions for more information

Configure SmartObject

When clicking on the ellipsis next to SmartObject in the Data Source section of the Properties, the Configure SmartObject screen opens. Configure the SmartObject to be used when creating the PDF. A system PDF File SmartObject is created and can be used to save all PDF's. In addition, a custom SmartObject can be created for this purpose.

Fields Description
SmartObject The SmartObject to be used when saving the PDF
Method The method to be used to create the PDF. This should be a Create method
File The File type property is required for the SmartObject. The file type to be selected must always be of File Type property.
Key Property The unique identifier of the SmartObject where the PDF will be saved

A Rule needs to be configured to execute a PDF method. The methods available for the Save as PDF control are discussed in the section below. One of the Execute Control Method actions can be used to execute these methods. Below is an example to show how a Rule is configured to execute a PDF method:

When executing the control method, the value of the control is set to the Key Property as selected in the SmartObject that is used as the Data Source of the Save as PDF control. One example is where the control's value is mapped to a Data Field in a workflow and a Load method is executed on the SmartObject to attach the PDF File to an e-mail. The Key Property is used as a way of identifying the SmartObject that hold the new PDF document. For good practice this should be generated during the execution of the SmartObject method and be unique, auto numbers work well. It is however possible that the Key Property value will not be unique if good practices were not followed.
The following methods are available:

  • SavePDF - This method executes synchronously. While executing the method, the browser is locked but the Key Property's value is immediately available. This method is useful when the Key Property's value is required in the same Rule.
  • SavePDFAsync - This method executes asynchronously. While executing the method, the Key Property's value is not available. After execution of the method, the When [Save as PDF] is Completed event is raised and the Key Property's value becomes available. This method is useful when you do not need the Key Property's value; do not want to lock up the browser and want to take advantage of the performance.  

 The following Events are available for both methods mentioned above:

  • When [Save as PDF] is Started - Raised when the PDF is being created. If you are changing values or the html of the page you should wait until this event is raised to prevent the changes from coming through to the PDF. For most users this will not be an issue and the event can be ignored.
  • When [Save as PDF] is Completed - Raised when the PDF has been created. This means the control is done executing one of its methods and its value is set to the new Key Property’s value. For users that want to get the Key Property’s value and are using the SavePDFAsyc method, they must wait for this event before it will be available.

These Events are available in the Rule Designer after using the SavePDF or SavePDFAsync methods. An Action can be configured to execute before or after the PDF is created. One example is where the SavePDFAsync method is used and you want to add a Label to the document before it is saved as a PDF to indicate that it's a copy of the original document. A Rule can be configured to show the Copy Label control before the PDF is saved. The Rules will look like this:
Event: When a control on the View raises and Event
Action: Execute a control's method

Event: When a control on the View raises and Event
Action: Show a control

See KB001378 - How to use the synchronous and asynchronous execution options of the Save as PDF control for detailed information about the application of the different execution types.

The PDF File created can be accessed by creating a List View of the PDF File SmartObject (system SmartObject) which can be found in the following location or alternatively in the location where the existing SmartObject was created:

The PDF File is displayed as a link in the List View

When clicking on the PDF link of the List View, the PDF File opens in Adobe Reader

An existing SmartObject can be used when saving the PDF File. The following SmartObject functions are required:

  • Create type function
  • See or List method
  • File property
  • Number/Autonumber property - Required to map into a Number in a workflow if required

This SmartObject can then be selected as the Data Source of the Save as PDF control. The PDF files will be saved to this SmartObject and a List View can be created of this SmartObject to view the PDF files created.

The system PDF File SmartObject is automatically available for use in a SmartForms workflow. If an existing SmartObject was used as the Data Source of the Save as PDF control, or if a new SmartObject was created for this purpose it should be workflow enabled before use in a SmartForms workflow. To enable workflow functionality for the specific SmartObject, select the Allow this SmartObject to be used in Workflows option on the details screen of the SmartObject Designer. The Get List method of this SmartObject can then be used to attach the PDF file for example to an e-mail.

The Save as PDF control can be used to attach the created PDF file to an E-mail in a workflow. In order to do this a Parameter can be used for example or mapping the value of the control in the context of the method being executed. In the example below we are using a Form Parameter and a Workflow Data Field for this purpose. It is important to note that the PDF value will not necessarily represent a Number value and the Parameter or mappings used must correlate to the PDF ID field type. The ID of the default PDF File SmartObject is of type Autonumber, but if a custom SmartObject was created for use with the PDF for example, the Unique property might be of another type.
See the following Knowledge Base articles:
KB001392 - How to attach a PDF file to an E-mail Event in a workflow
KB001394 - How to attach a PDF file to an E-mail Event in a workflow using a Form Parameter
 In the image below the Save as PDF control is used on a Form.

A Parameter is added to the Form to map the PDF details. This Data Type should correlate to the ID of the PDF SmartObject and the Data Field Type that will be used in the workflow to perform the mapping. 

Rules are configured to execute the Save as PDF control's method to create the PDF and then transfer the data from the PDF control to the Parameter.

Note that the PDF control is dragged to the Parameter field

When creating a Data Field in the Workflow, it is important to use the same Data Type as was used when creating the Parameter. The Parameter is then mapped to this Data Field in the Workflow.

The PDF Load method is used in the Attachments field of the E-mail event as shown below and the Workflow Data Field is in turn used in the mapping to the PDF Load method

The following scenarios are applicable when using the Save as PDF control:

Supported Want to use the Save as PDF control – Internet Explorer on the K2 Host Server is a prerequisite
Supported Do not want to use the Save as PDF control - Internet Explorer on the K2 Host Server is not required
Related Topics