How To: Create a PDF file using the PDF Converter in an Advanced SmartObject

This article illustrates one method for converting an existing web page into a PDF file. This conversion applies to a single web page. For instructions on how to save a SmartForm and its content to a PDF format, see Save as PDF Control. See Using the PDF Converter for more information about the PDF Converter and considerations.

A PDF file created from a web page
PDF File Generated by Workflow

Scenario

You work for a company with a global presence. Each month, you must submit an expense claim for travel costs you incurred. Since you travel out of the country, you must convert expenses to US dollars. Your company requires you to provide proof of currency exchange rates. To accomplish this, you have created a workflow that saves a currency exchange rate web page to a PDF format, which you attach to your expense claim.

Steps

In this scenario, you create two data sources: one to perform the PDF conversion and one to store the converted file. You create a workflow that ties the conversion steps together and sends the PDF file as an email attachment.

Setup Steps

The following steps set up the scenario from start to finish. If you want to skip the setup steps and view the topic step, go to Configure a SmartObject Method Step with the Create PDF from URL Method.

  1. In K2 Designer, create a new SmartBox SmartObject called PDFFile. In addition to the default ID property, add a new property called File with a data type of File. This SmartObject stores the PDF files. (Optional: create categories in K2 Designer for this demonstration. How To > Convert to PDF)
    1. Launch K2 Designer.
      If you do not know how to access K2 Designer, see Accessing K2 Sites.
    2. Click Browse. To keep your work organized, create the following categories: How To > Convert to PDF. To create the first category, right-click the All Items heading and select New Category.
      Create Categories
    3. Right-click the Convert to PDF category and select New SmartObject.
    4. Name the SmartObject
      PDFFile
      and confirm the SmartBox option is selected. Click Create.
      Create PDFFile SmartObject
    5. Add one property called
      File
      then change the data type to File. Click OK.
      PDFFile Properties

      6. Your PDFFile SmartObject properties should look like the image below.
      PDFFile SmartObject

    6. Click Finish (near the upper right corner of your screen) to save and exit.
  2. Create an Advanced SmartObject called PDF Converter. From the Service Object Explorer, add the PDF Converter > PDF Converter > Create PDF from URL method to the new SmartObject. Create All properties.

    The second SmartObject is an advanced data source that uses an existing method from the PDF Converter Service Object. This method creates a PDF file from a web page URL, then saves the file to the PDFFile SmartObject.

    1. Right-click the PDF Converter category and select New SmartObject.
    2. Name the SmartObject
      PDF Converter
      then select the Advanced SmartObject option. Click Create.
      Advanced SmartObject Option

      3. For this SmartObject, you do not add properties. Instead, you use the properties and methods from a system service object. Methods are protocols for interacting with data. For example, create, update, and delete are common methods used in SmartObjects. For this demonstration, you use a method that converts a web page to a PDF file, then saves the file to a SmartObject. This method already exists in K2 and is ready to use.

    3. From the ServiceObject Explorer on the left side of your screen, locate PDF Converter. Expand the node, then expand the second PDF Converter node. Drag the Create PDF from URL method onto the design canvas.
      Add Create PDF from URL Method
    4. The Add Method > Details screen opens. Keep the default settings and click Next.
      Add Method Details Screen
    5. You are now on the Inputs & Outputs screen. Click Create All. This action creates the existing service object properties in your new SmartObject. Click Next.
      Notice the Return Property, ID Property Value. K2 creates the PDF file and saves it to the PDFFile SmartObject. While configuring the workflow, you save the ID of this SmartObject record to a variable. This way, you can use the ID to locate the correct file to attach to an email. Notice, however, the return property is a text data type, whereas record IDs are usually integers. You convert this text value to an integer so K2 can use it to locate the correct record.
      Create All Properties
    6. On the ServiceObject Methods screen, you see the new method created in your SmartObject. Click Finish.
      New ServiceObject Method
    7. Your SmartObject (Methods) should look like the image below. Click Finish to save and exit.
      Completed PDF Converter SmartObject
  3. From the Convert to PDF category, add a new workflow named Convert URL to PDF.
    1. You are ready to create and configure the workflow. Right-click the Convert to PDF category and select New Workflow.
    2. Name the workflow
      Convert URL to PDF
      then click Create.
      Create New Workflow

      3. You see a Welcome screen with an interactive panel. You can click the right and left arrows to learn more about the workflow designer. Click Close to proceed to the design canvas.
      Welcome Screen

Configure a SmartObject Method Step with the Create PDF from URL Method

The following steps demonstrate adding and configuring a SmartObject Method step using the Create PDF from URL method. You also learn how to add and configure a Send Email step with the generated PDF file as an attachment.

  1. Add a SmartObject Method step to the empty placeholder. For the SmartObject, select PDF Converter. For the Method, select Create PDF from URL. Use the table below as a guide for Input Mappings, Variables, and Output Mappings. Rename the step Convert to PDF.
    PropertyValueNotes
    Input Mappings
    URL String*https://www.x-rates.com/historical/?from=USD
    &amount=1    		*Enter the sample exchange rate URL. This web page displays a table of currency rates for the current date. If you copy and paste the sample URL, make sure it pastes exactly as shown. In some cases, the ampersand (&) passes as (&). Leaving it in this format causes the workflow to fail.
    SmartObject NamePDFFileThis is the SmartObject that stores generated PDF files.
    SmartObject MethodCreateYou are using the create method to add a new PDF file.
    SmartObject File Property NamePDFThis is the property in the PDFFile SmartObject that contains the saved file.
    ID Property NameID The SmartObject auto-number for each record.
    File NamePDFRateExchangeThis is the name of the PDF file as it's saved to the SmartObject. This entry can be any value you want, it is not bound to K2 settings.
    Page SizeA4K2 has reference page sizes. A4 refers to 8.5 x 11. For information on page sizing, see the Considerations section in the Save as PDF Control user guide.
    Page OrientationPortrait
    Variables (Expand the Context Browser for this setting)
    Add newIDStringYou return the ID of the current record to this variable. You reference it in the next step.
    Output Mappings
    Map to Data FieldsSelected
    ID Property ValueIDStringYou are saving the ID of the current PDF Files SmartObject record to the IDString variable. You use this variable to attach the PDF file to the email.
    1. From the Toolbox > Basic node, drag a SmartObject Method step into the empty placeholder below the Start step.
      Add SmartObject Method Step
      2. Notice the red warning badge on the SmartObject Method step. This badge indicates there are required settings in the Configuration Panel. When you expand the panel, you see the same badge next to the required settings.
      Required Settings
    2. Select the SmartObject Method step, then expand the Configuration Panel.
    3. For the SmartObject, click the Select SmartObject bar, then click Browse. Navigate to and select the PDF Converter SmartObject. In the image below, the PDF Converter SmartObject is found in the How To > Convert to PDF category. Your screen may be different depending on where you saved your SmartObjects. Click OK.
      Select SmartObject
    4. For the Method, select Create PDF from URL.
      Select Method

      5. After you select the method, you see a series of required properties for Input Mappings. You must provide values for each property.

    5. Complete the Input Mappings > Properties using the table below as a guide. There is a reference image below the table.
      PropertyValueNotes
      Input Mappings
      URL String*https://www.x-rates.com/historical/?from=USD
      &amount=1      		*Enter the sample exchange rate URL. This web page displays a table of currency rates for the current date. If you copy and paste the sample URL, make sure it pastes exactly as shown. In some cases, the ampersand (&) passes as (&). Leaving it in this format causes the workflow to fail.
      SmartObject NamePDFFileThis is the SmartObject that stores generated PDF files.
      SmartObject MethodCreateYou are using the create method to add a new PDF file.
      SmartObject File Property NameFileThis is the property in the PDFFile SmartObject that contains the saved file.
      ID Property NameID The SmartObject auto-number for each record.
      File NamePDFRateExchangeThis is the name of the PDF file as it's saved to the SmartObject. This entry can be any value you want, it is not bound to K2 settings.
      Page SizeA4K2 has reference page sizes. A4 refers to 8.5 x 11.. For information on page sizing, see the Considerations section in the Save as PDF Control user guide.
      Page OrientationPortrait
      Input Mappings

      6. Next, you create a new variable that stores the ID of the record just created in the PDFFile SmartObject. You need this ID to locate the correct file when you attach it to an email.

    6. Expand the Context Browser.
      The Context Browser contains references, variables, functions, and SmartObject properties. At runtime, K2 replaces references and variables with live data. For example, K2 replaces the ID reference with the ID of the current record.
      Expand Context Browser
    7. In the Variables section, click Add. Name the variable
      IDString.
      Click the canvas to set the value. Collapse the Context Browser by clicking the slider once again.
      Add Variable
    8. Scroll down to the Output Mappings section. Select Map to Data Fields, then click the Add(+) icon. Check the box for ID Property Value. (Recall when setting up the PDF Converter SmartObject, this is the property for the return value.)
      Output Mappings
    9. Click the down arrow for the value box. Select IDString. You have mapped the ID of the record just created to a variable. You use this variable later to attach the file to an email.
      Map to Data Fields
    10. Select the Properties tab. Change the step name to
      Convert to PDF
      then collapse the Configuration Panel.
      Change Step Name
  2. Add a Send Email step and connect it to the Convert to PDF step. Enter content for the Subject line and message Body. For the Attachment, add the File property from the PDFFile SmartObject > Load method. Use the To Integer function to convert the IDString variable to an integer for the SmartField ID value.

    For convenience, you attach the new PDF file to an email and send it to the person who started the workflow. This way, they do not have to download and save the file.

    1. From the Toolbox > Basic node, drag a Send Email step below the Convert to PDF step. Connect the two steps.
      2. To return to the main Toolbox menu, click the Toolbox icon in the breadcrumb bar.
      Toolbox Icon
      To connect steps, hover over the border of the first step until you see a handle. Click and drag the handle into the second step. Click the canvas to set the line.
      Connect Two Steps
    2. Select the Send Email step and expand the Configuration Panel.
    3. Keep the To value as Originator. This sends the email to the person who submits the form (you!). For the Subject line, enter
      PDF Exchange Rate Attached
      then for the message Body, enter
      Attached is today's currency exchange rate.
      Email Subject and Body
    4. On this same screen, scroll down until you see the Attachment section. Click the Add Attachment link.
      Attachment Section
    5. The Attachment bar becomes active. Expand the Context Browser.
    6. You begin by adding a variable that references the saved PDF file. At runtime, K2 replaces the variable with the file from the current PDFFile record. Click the SmartObjects tab.
      SmartObjects Tab
    7. Navigate to the PDFFile SmartObject. Your menu structure may not match the image below, depending on where you created and saved your SmartObjects.
      PDFFile SmartObject
    8. Expand the SmartObject, then expand the Load node. Drag the File property into the Attachment box.
      Add File Property
    9. The Edit SmartField screen opens.
      You've added the File property, but you must tell K2 which file to add; you want the file for the current record. Remember that the ID of the current record is saved in the IDString variable. However, the value in the IDString variable is a text data type and you need it to be an integer, as SmartObject record IDs are integers. The solution is to convert the IDString text value to an integer.

    10. Click the Functions tab. Expand the Conversion node, then drag the To Integer function into the ID text box.
      Add To Integer Function

    11. Click the Fields tab. Drag the IDString variable into the To Integer > Value text box.
      Add IDString Variable
    12. Exit the SmartField editor by clicking the Exit icon (X).
      Exit SmartField Editor
    13. Collapse the Configuration Panel. You have completed the configurations for this demonstration. In the next steps, you deploy the workflow, then test your work!
  3. Deploy the Convert URL to PDF workflow.

    Before you can use the workflow, you must deploy it to the K2 server. Deploying a workflow publishes it and makes it available for use. If you make any changes to the workflow, you must deploy it again so that the K2 server can register the changes.

    1. Click File > Deploy. When you see the success dialog, click File > Close to return to the K2 Designer. (Since this is a demonstration, you do not need to configure permissions.)
      Deploy Workflow
  4. To test the application, open the K2 Management site and start a new instance of the Convert URL to PDF workflow. Confirm you receive an email with the PDFRateExchange file attached. The attachment should reflect today's exchange rate.
    1. In a separate browser tab, launch the K2 Management site.
      If you do not know how to access the K2 Management site, see Accessing K2 Sites.
    2. From the menu, expand the Workflow Server > Workflows node. Navigate to the Convert URL to PDF workflow. The image below reflects the Convert to PDF category; your screen may be different, depending on where you saved your workflow.
      Workflow Server Workflows
    3. Select Convert URL to PDF. In the central pane, click the Start New icon.
      Start New Workflow Instance
    4. On the Start Options screen, click Start (near the bottom of the screen.) Click OK when you see the confirmation dialog.
    5. Open your email client. Confirm you see an email with the PDF file attached.
      Email with PDF Attached
    6. Open the attachment. You should see the rate exchange web page in PDF format.
      PDF File Attachment
Review

There are many uses for converting a web page to a static PDF file, such as providing backup documentation, capturing a page on a specific date, and for archival storage. PDF Converter methods allow you to save web pages as PDF files on demand. You can incorporate these methods in a workflow, then configure a rule to start the workflow at the click of a button. Expanding on this concept, you might include the URL as a variable instead of hardcoding it in the SmartObject Method properties. Finally, you learned how to attach a saved file using a conversion function to retrieve the current record.

For instructions on how to save a SmartForm and its content to a PDF format, see Save as PDF Control.