PDF invites robot

This robot is included in our downloadable example robots. You can also find the code at the example robots repository.

Starting from an Excel file, this robot will generate a personalized PDF invitation for each participant to an event.

Excel worksheet to work item to PDF files

To demonstrate the use of the Robocloud.Items library, we will split our operations into two different robots: the first robot will read the data from the Excel file and add it to the work item. The second robot, based on the data in the work item, will then generate the PDF invitations.

First robot: Excel to Work Item

This robot will:

  • download and collect the data from an Excel file
  • process the data into the correct format
  • add the data to the work item and exit

Run this robot locally in Robocorp Lab

You can run this robot on your local machine using Robocorp Lab:

  1. Set up your development environment.
  2. Download the example robots.
  3. Open the excel-to-work-item example.
  4. Complete the Setup section below to configure the Robocloud.Items library to run locally!
  5. Open the tasks.robot file and run it.

Setup the Robocloud.Items library

When executing our robot in a cloud environment like Robocorp Cloud, the RPA.Robocloud.Items library will store the work item in the cloud environment, sharing its contents between robot steps defined in the same process, without any configuration needed.

When developing our robot and running it locally, however, we want the library to store the data in a JSON file, and provide the required parameters to simulate the cloud environment. You can learn more about the internals of the RPA.Robocloud.Items library here.

Create a new file called items.json on your file system, for example at /Users/<username>/items.json.

Paste this content into your items.json file, creating an empty but valid JSON file:

{}

Paste the following in devdata/env.json:

{
  "RPA_WORKITEMS_ADAPTER": "RPA.Robocloud.Items.FileAdapter",
  "RPA_WORKITEMS_PATH": "/Users/<username>/items.json",
  "RC_WORKSPACE_ID": 1,
  "RC_WORKITEM_ID": 1
}

Edit the RPA_WORKITEMS_PATH variable to point to the items.json file on your filesystem. On macOS / Linux, use normal file paths, for example, /Users/<username>/items.json. On Windows 10, you need to escape the path, for example, C:\\Users\\User\\items.json.

Robot script

*** Settings ***
Documentation     Excel reader robot. Reads information from a given Excel file and
...               adds it to the work item.
Library           RPA.Excel.Files
Library           RPA.HTTP
Library           RPA.Robocloud.Items

*** Variables ***
${EXCEL_FILE_NAME}=    Data.xlsx
${EXCEL_FILE_URL}=    https://github.com/robocorp/example-activities/raw/master/excel-to-work-item/devdata/${EXCEL_FILE_NAME}

*** Keywords ***
Collect invitations from the Excel file
    Open Workbook    ${EXCEL_FILE_NAME}
    ${invitations}=    Read Worksheet    header=True
    Close Workbook
    [Return]    ${invitations}

*** Tasks ***
Read invitations from Excel file and add them to the work item
    Download    ${EXCEL_FILE_URL}    overwrite=True
    ${invitations}=    Collect invitations from the Excel file
    Set Work Item Variables    invitations=${invitations}
    Save Work Item

Robot script explained

Let's look in detail at what we are telling our robot to do:

*** Settings ***
Documentation     Excel reader robot. Reads information from a given Excel file and
...               adds it to the work item.
Library           RPA.Excel.Files
Library           RPA.HTTP
Library           RPA.Robocloud.Items

In the Settings section we declare the libraries we are going to use, and we add a reference to our variables file.

Our robot will use these libraries:

  • RPA.HTTP: to download the excel file
  • RPA.Excel.Files: to read the content of our Excel file
  • RPA.Robocloud.Items: to manipulate the work item

Let's have a closer look at the Tasks section:

*** Tasks ***
Read invitations from Excel file and add them to the work item
    Download    ${EXCEL_FILE_URL}    overwrite=True
    ${invitations}=    Collect invitations from the Excel file
    Set Work Item Variables    invitations=${invitations}
    Save Work Item
  1. Download ${EXCEL_FILE_URL} overwrite=True: using the RPA.HTTP library, we can download a remote Excel file, taking the path from the variable defined in the *** Variables *** section.

  2. ${invitations}= Collect invitations from the Excel file

    Here we are creating a variable, and we are assigning to it the Excel data by using a new keyword Collect invitations from the Excel file:

    *** Keywords ***
    Collect invitations from the Excel file
        Open Workbook    ${EXCEL_FILE_NAME}
        ${invitations}=    Read Worksheet    header=True
        Close Workbook
        [Return]    ${invitations}
    

    We are using the RPA.Excel.Files library to manipulate the Excel file (Keywords: Open Workbook, Read Worksheet, Close Workbook).

  3. Set Work Item Variables invitations=${invitations}

    Here we are storing our invitation data in a new variable inside the work item, using the Set Work Item Variables keyword, provided by the RPA.Robocloud.Items library.

  4. Save Work Item

    Calling this keyword we are persisting the content of the work item.

Excel file

The event participation information is stored in an Excel file (Data.xlsx). The file is formatted as follows:

first_namelast_nameaddresscitydatetime
ReynardMouse4 Service CenterToronto2019/07/0310:00 PM
ElisabethKilfoyle197 Ronald Regan DriveNew York2019/05/0310:20 PM
CyrilBlundon3554 Chive CircleSan Francisco2019/05/101:33 PM
VincenzPaolazzi20533 6th CrossingMilan2019/12/146:58 AM
JeannieCharge9 Michigan StreetKansas City2020/02/124:27 AM
AlexioHellis8 Grim TrailLahore2019/05/055:04 PM
LucaViel91764 Reindahl ParkNew Dehli2019/12/178:37 AM
SlyLammerts8077 Pennsylvania DriveHelsinki2020/02/0911:23 PM
LeahMithun3619 Oxford PlaceStockholm2019/10/301:15 PM
MaridelSneezum4 Cambridge CenterLondon2020/03/2611:24 AM

Results of the first robot

After you run the robot, you will find that the items.json file in the directory you have specified in the env.json file will now contain a JSON representation of the data of the Excel file. Great! The first robot is complete!

{
  "1": {
    "1": {
      "variables": {
        "invitations": [
          {
            "first_name": "Reynard",
            "last_name": "Mouse",
            "address": "4 Service Center",
            "city": "Toronto",
            "date": "2019/07/03",
            "time": "10:00 PM"
          },
          {
            "first_name": "Elisabeth",
            "last_name": "Kilfoyle",
            "address": "197 Ronald Regan Drive",
            "city": "New York",
            "date": "2019/05/03",
            "time": "10:20 PM"
          }
          // ...
        ]
      }
    }
  }
}

Second robot: work item to PDF

This robot will:

  • retrieve the data from the work item
  • loop through the data and generate a personalized PDF for each event participant using a template into a temporary folder
  • collect all generated files into a zip archive in the output folder
  • write log files
  • clean up after itself by deleting the temporary folder

Run this robot locally in Robocorp Lab

Just like with the first robot, you can run this robot on your local machine using Robocorp Lab:

  1. Open the excel-to-work-item example.
  2. Complete the Setup section below to configure the Robocloud.Items library to run locally!
  3. Open the tasks.robot file and run it.

Setup the Robocloud.Items library

Just like we did in the first robot, we need to configure the Robocloud.Items library to work locally.

Paste the following in devdata/env.json:

{
  "RPA_WORKITEMS_ADAPTER": "RPA.Robocloud.Items.FileAdapter",
  "RPA_WORKITEMS_PATH": "/Users/<username>/items.json",
  "RC_WORKSPACE_ID": 1,
  "RC_WORKITEM_ID": 1
}

Edit the RPA_WORKITEMS_PATH variable to point to the items.json file on your filesystem. On macOS / Linux, use normal file paths, for example, /Users/<username>/items.json. On Windows 10, you need to escape the path, for example, C:\\Users\\User\\items.json.

By pointing to the same file that we used in the first robot and by specifying the same workspace and work item id, we are now effectively sharing data between the two robots. This way, we are simulating what happens in Robocorp Cloud when two robot steps are added to the same process.

Robot script

*** Settings ***
Documentation     Invite printer robot. Creates PDF invitations to events based on data it receives
...               from the work item.
Library           OperatingSystem
Library           RPA.Archive
Library           RPA.PDF
Library           RPA.Robocloud.Items
Variables         variables.py

*** Keywords ***
Process invitations
    Set up and validate
    ${invitations}=    Collect invitations from work item
    FOR    ${invitation}    IN    @{invitations}
        Run Keyword And Continue On Failure    Create PDF file for invitation    ${invitation}
    END
    Create ZIP package from PDF files
    [Teardown]    Cleanup temporary PDF directory

*** Keywords ***
Set up and validate
    File Should Exist    ${PDF_TEMPLATE_PATH}
    Create Directory    ${PDF_TEMP_OUTPUT_DIRECTORY}

*** Keywords ***
Collect invitations from work item
    ${invitations}=    Get Work Item Variable    invitations
    [Return]    ${invitations}

*** Keywords ***
Create PDF file for invitation
    [Arguments]    ${invitation}
    Template Html To Pdf    ${PDF_TEMPLATE_PATH}    ${PDF_TEMP_OUTPUT_DIRECTORY}/${invitation["first_name"]}_${invitation["last_name"]}.pdf    ${invitation}

*** Keywords ***
Create ZIP package from PDF files
    ${zip_file_name}=    Set Variable    ${OUTPUT_DIRECTORY}/PDFs.zip
    Archive Folder With Zip    ${PDF_TEMP_OUTPUT_DIRECTORY}    ${zip_file_name}

*** Keywords ***
Cleanup temporary PDF directory
    Remove Directory    ${PDF_TEMP_OUTPUT_DIRECTORY}    True

*** Tasks ***
Create PDF invitations
    Process invitations

Robot script explained

Let's look in detail at what we are telling our robot to do:

*** Settings ***
Documentation     Invite printer robot. Creates PDF invitations to events based on data it receives
...               from the work item.
Library           OperatingSystem
Library           RPA.Archive
Library           RPA.PDF
Library           RPA.Robocloud.Items
Variables         variables.py

In the Settings section we declare the libraries we are going to use, and a reference to our variables file.

Our robot will use these libraries:

  • RPA.Archive: to create the zipped file that will contain the generated PDF files
  • OperatingSystem: to work with files and directories
  • RPA.PDF: to create our PDF files
  • RPA.Robocloud.Items: to manipulate the work item

Let's have a closer look at the ***Tasks*** section:

*** Tasks ***
Create PDF invitations
    Set up and validate
    ${invitations}=    Collect invitations from work item
    FOR    ${invitation}    IN    @{invitations}
        Run Keyword And Continue On Failure    Create PDF file for invitation    ${invitation}
    END
    Create ZIP package from PDF files
    [Teardown]    Cleanup temporary PDF directory
  1. Set up and validate is a keyword that will check that the template file is in place, using the File Should Exist keyword, which is provided by the OperatingSystem library, and will create a directory where we will temporarily store the PDF files.

    *** Keywords ***
    Set up and validate
        File Should Exist    ${PDF_TEMPLATE_PATH}
        Create Directory    ${PDF_TEMP_OUTPUT_DIRECTORY}
    
  2. ${invitations}= Collect invitations from work item

    Here we are creating a variable, and we are assigning to it the data from the work item by using a new keyword Collect invitations from work item. Then we are returning that variable as the result of our keyword.

    *** Keywords ***
    Collect invitations from work item
         ${invitations}=    Get Work Item Variable    invitations
         [Return]    ${invitations}
    
  3. Looping over the invitations

        FOR     ${invitation}   IN  @{invitations}
            Run Keyword And Continue On Failure     Create PDF file for invitation  ${invitation}
        END
    
  4. Create PDF file for invitation ${invitation}

    Create PDF file for invitation
         [Arguments]    ${invitation}
         Template Html To Pdf    ${PDF_TEMPLATE_PATH}    ${PDF_TEMP_OUTPUT_DIRECTORY}/${invitation["first_name"]}_${invitation["last_name"]}.pdf    ${invitation}
    

    Here we are using the Template Html To Pdf keyword, provided by the RPA.PDF library to generate a PDF file based on an HTML template. The template contains placeholders that are replaced by our variables. The second argument we pass to the keyword allows us to specify the path and the name of the created PDF file. In our case, we are using the first and last name.

    The RPA.PDF library offers a variety of ways to create and interact with PDF files. Here we are using the template method.

  5. Create ZIP package from PDF files

    In this keyword we are using the RPA.Archive library to archive all generated PDF files into a file in the output directory:

    *** Keywords ***
    Create ZIP package from PDF files
        ${zip_file_name}=    Set Variable    ${OUTPUT_DIRECTORY}/PDFs.zip
        Archive Folder With Zip    ${PDF_TEMP_OUTPUT_DIRECTORY}    ${zip_file_name}
    
  6. [Teardown] Cleanup temporary PDF directory

    As the last step, we delete the directory we used to temporarily store the created PDFs:

    *** Keywords ***
    Cleanup temporary PDF directory
        Remove Directory    ${PDF_TEMP_OUTPUT_DIRECTORY}    True
    

    We are using the Remove Directory keyword from the OperatingSystem library.

    Note the True parameter, necessary to delete a non-empty directory.

PDF template file

The example includes a invite.template file in the devdata folder:

<h1>Event Invitation</h1>
<p>Dear <b>{{first_name}} {{last_name}}</b>,</p>

<p>You are invited to our event on <b>{{date}}</b> at <b>{{time}}</b>, at <b>{{address}}</b>, <b>{{city}}</b>.</p>

<p>Bring a friend, and don't be late!</p>

<p>Kind regards,</p>

<p>Robot Events Inc.</p>

Results of the second robot

After you run the robot, you will find a zip archive PDFs.zip file in the output directory. Extract it, and you will see the PDF invitations according to the data in the Excel file.

Advantages of using the Robocloud.Items library

By using the Robocloud.Items library, a complex workflow can be broken in multiple robots that share the same data, held by the work item. Each robot gets the work item from the previous robot, can add and remove data from it, and it passes it on to the next one in the same process.

Organizing a process into multiple robot provides these advantages:

  • better separation of concerns
  • the same smaller robots can be reused in different contexts
  • when run in Robocorp Cloud, each robot can be run in a different environment, for example combining part of the process running in the cloud and part of it in physical desktop machines in an intranet.

Summary

With this example, you learned some concepts and features of the Robot Framework and the RPA Framework:

  • Splitting a process into two robot steps, passing data between via the RPA.Robocloud.Items library
  • Using the work item library locally (items.json)
  • Validating task prerequisites (File Should Exist)
  • Reading Excel files and transforming to business entities (RPA.Excel)
  • Creating ZIP archives with the RPA.Archive library