PDF invites creator robot

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

Multi-task robot setup

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

These tasks are represented in the robot.yaml file for the robot:

tasks:
  1-From Excel to Work Item:
    command:
      - python
      - -m
      - robot
      - --report
      - NONE
      - -d
      - output
      - --logtitle
      - Task log
      - 01-excel-to-work-item.robot
  2-From Work Item to PDF:
    command:
      - python
      - -m
      - robot
      - --report
      - NONE
      - -d
      - output
      - --logtitle
      - Task log
      - 02-work-item-to-pdf.robot

condaConfigFile: conda.yaml
artifactsDir: output
ignoreFiles:
  - .gitignore
PATH:
  - .
PYTHONPATH:
  - .

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.

However, when developing our robot and running it locally, 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 in the devdata/env.json file 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.

Run the tasks

Once you have set up the Robocloud.Items library to run locally, the robot is ready to run.

This robot has two .robot files:

• Open the 01-excel-to-work-item.robot file and run it.
• Open the 02-work-item-to-pdf.robot file and run it.

Or, you can click on the Run Robot button on the top right, and select the task you want to run:

The first task prepares the stage for the second one, so make sure to run it first, at least once!

Let's now look at each task individually:

First task: Excel to Work Item

You will find this code in the 01-excel-to-work-item.robot file.

This robot task will:

• collect the data from a given Excel file.
• process the data into the correct format.
• add the data to the work item and exit.

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.Robocloud.Items

*** Variables ***
${EXCEL_FILE_PATH}=    ${CURDIR}${/}devdata${/}Data.xlsx

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

*** Tasks ***
Read invitations from Excel file and add them to the work item
    ${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.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.Excel.Files: to read the content of our Excel file
• RPA.Robocloud.Items: to manipulate the work item

*** Variables ***
${EXCEL_FILE_PATH}=    ${CURDIR}${/}devdata${/}Data.xlsx

In the *** Variables *** section, we add a variable to hold the path to the Data.xlsx file, that we added to the devdata folder.

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

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

1. ${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_PATH}
       ${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).

2. 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.

3. 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:

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 task 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 task: work item to PDF

You will find this code in the 02-work-item-to-pdf.robot file.

This task 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.

Robot script

*** Settings ***
Documentation     Invite creator robot. Creates PDF invitations to events based
...               on data it receives from the work item.
Library           RPA.FileSystem
Library           RPA.Archive
Library           RPA.PDF
Library           RPA.Robocloud.Items

*** Variables ***
${PDF_TEMP_OUTPUT_DIRECTORY}=    ${CURDIR}${/}temp
${OUTPUT_DIRECTORY}=    ${CURDIR}${/}output
${PDF_TEMPLATE_PATH}=    ${CURDIR}${/}devdata${/}invite.template

*** Keywords ***
Set up directories
    Create Directory    ${PDF_TEMP_OUTPUT_DIRECTORY}
    Create Directory    ${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
    Set up directories
    ${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

Robot script explained

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

*** Settings ***
Documentation     Invite creator robot. Creates PDF invitations to events based
...               on data it receives from the work item.
Library           RPA.FileSystem
Library           RPA.Archive
Library           RPA.PDF
Library           RPA.Robocloud.Items

In the Settings section, we declare the libraries we are going to use.

Our robot will use these libraries:

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

Then we added a Variables section, where we set up the variables we will need in our script. We set the path of a temporary directory where our intermediate files will be placed, we point to the output directory for the finished PDF zipped files, and we set the path of the template file.

*** Variables ***
${PDF_TEMP_OUTPUT_DIRECTORY}=    ${CURDIR}${/}temp
${OUTPUT_DIRECTORY}=    ${CURDIR}${/}output
${PDF_TEMPLATE_PATH}=    ${CURDIR}${/}devdata${/}invite.template

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

*** Tasks ***
Create PDF invitations
    Set up directories
    ${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. The Set up directories keyword will make sure that the directories we need are in place.

   *** 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}

   *** 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}
   

   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 task

After you run the task, 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 and using multiple tasks

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 task gets the work item from the previous task, 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 tasks provides these advantages:

• better separation of concerns
• the same smaller tasks can be reused in different contexts
• when run in Robocorp Cloud, each task 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 tasks, passing data between them 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