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 fileRPA.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
${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
).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 theRPA.Robocloud.Items
library.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_name | last_name | address | city | date | time |
---|---|---|---|---|---|
Reynard | Mouse | 4 Service Center | Toronto | 2019/07/03 | 10:00 PM |
Elisabeth | Kilfoyle | 197 Ronald Regan Drive | New York | 2019/05/03 | 10:20 PM |
Cyril | Blundon | 3554 Chive Circle | San Francisco | 2019/05/10 | 1:33 PM |
Vincenz | Paolazzi | 20533 6th Crossing | Milan | 2019/12/14 | 6:58 AM |
Jeannie | Charge | 9 Michigan Street | Kansas City | 2020/02/12 | 4:27 AM |
Alexio | Hellis | 8 Grim Trail | Lahore | 2019/05/05 | 5:04 PM |
Luca | Viel | 91764 Reindahl Park | New Dehli | 2019/12/17 | 8:37 AM |
Sly | Lammerts | 8077 Pennsylvania Drive | Helsinki | 2020/02/09 | 11:23 PM |
Leah | Mithun | 3619 Oxford Place | Stockholm | 2019/10/30 | 1:15 PM |
Maridel | Sneezum | 4 Cambridge Center | London | 2020/03/26 | 11: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 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 filesRPA.FileSystem
: to work with files and directoriesRPA.PDF
: to create our PDF filesRPA.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
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}
${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}
Looping over the invitations
FOR ${invitation} IN @{invitations} Run Keyword And Continue On Failure Create PDF file for invitation ${invitation} END
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 theRPA.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.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}
[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 theOperatingSystem
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