How to write and use custom Robot Framework Python RPA libraries

Quick recap on Robot Framework libraries and keywords

Robot Framework works in a modular way: you can easily add more keywords to your robots by adding libraries. Robot Framework includes a set of standard libraries, and you can get more libraries byinstalling additional packages.

For example, by adding the rpaframework package, you get all the keywords included in it.

Once you have added a library to your script, you can use the keywords that the library includes. For example, in this script, we are adding the RPA.Browser.Selenium library, and we are using the Open Available Browser and Capture Page Screenshot keywords that it provides:

*** Settings ***
Documentation     A simple example of using a library.
Library           RPA.Browser.Selenium

*** Tasks ***
Take a screenshot of the Robocorp frontpage
    Open Available Browser    https://www.robocorp.com
    Capture Page Screenshot

Sometimes your use case might have some specific requirements that you feel cannot be achieved with readily available libraries. Or, you might be more comfortable coding in a "lower-level" language than Robot Framework. If that's the case, a great way to still get all the Robot Framework (and the Robocorp ecosystem) benefits but get more control over the code is to add your custom libraries and keywords using Python!

Custom Robot Framework Python library examples

These examples use the default robot structure.

The simplest custom Robot Framework Python library: a single Python function

In our example use case, based on RobotSpareBin Industries Inc., our favorite fictional company, we have some sales representatives that have a weekly sales goal. We want to show each sales representative a feedback message based on their actual sales results for the week as part of a software robot.

Sounds like an interesting use case? It happens to be the story of our Beginners' course. Go and take it if you haven't already! Completing the course will grant you the Robocorp Level I certificate!

The feedback message depends on a bit of calculation, so we decide that the best approach is to have the logic in a custom Python library, which we choose to call PerformanceFeedback. So:

We add a file called PerformanceFeedback.py in the root of our package.
We add this code to it:

def get_sales_performance_feedback(sales_result, sales_target):
    ratio = int(sales_result) / int(sales_target)
    if ratio >= 1:
        return "A great result!"
    elif ratio > 0.75:
        return "You did not quite make it, but not too bad."
    elif ratio >= 0.5:
        return "Well, at least you tried"
    else:
        return "The boss wants to see you..."

NOTE: You can also decide to create a different directory in your package for your library, and put your library Python file there. For this to work, you will need to add the subdirectory to the PYTHONPATH section of your robot.yaml file.

This function expects two arguments: the actual sales result for the week and a sales target, which is different for each sales representative. We make sure that the function is operating on numbers, then we compare the sales result and the sales target, and we return a feedback message.

Now, we can import and use the library in our .robot file, like in this simple example:

*** Settings ***
Documentation     How to use a custom Python library.
Library           PerformanceFeedback

*** Variables ***
&{SALES_REP_NATHAN}=    salesResult=502    salesTarget=1000
&{SALES_REP_PAMELA}=    salesResult=112    salesTarget=100

*** Tasks ***
Calculate the performance for some example sales reps
    ${performance_nathan}=    Get Sales Performance Feedback
    ...    ${SALES_REP_NATHAN}[salesResult]
    ...    ${SALES_REP_NATHAN}[salesTarget]
    ${performance_pamela}=    Get Sales Performance Feedback
    ...    ${SALES_REP_PAMELA}[salesResult]
    ...    ${SALES_REP_PAMELA}[salesTarget]

We added the name of the library in the *** Settings *** section.
Our library contains a function called get_sales_performance_feedback: this gives us a keyword called Get Sales Performance Feedback.
The Get Sales Performance Feedback keyword requires two arguments like the function that it comes from, so we can call it with the sales results and targets for our two hypothetical sales representatives.

Executing our robot will now produce this log output:

Log output of robot with simple custom library

We now have a basic Python library that we can use in our robot script. We can add as many new functions to the library as we need and use them as keywords.

Use a class as your custom library

You can also organize the code in your library in a class. In this case, the class and the filename of the library have to match, and the class methods become available as keywords.

As an example, to get a keyword called Get Current Date, you could add this code in a file called ExampleLibrary.py:

from datetime import date


class ExampleLibrary:
    def get_current_date(self):
        return date.today()

Remember: the file name and the class name must match. Otherwise, your library won't work! 🤯

Using `rpaframework` in your custom Python library

Having your custom library does not mean that you have to code everything from scratch. It is very easy to import other libraries and packages and integrate them into your code. For example, you can use the RPA Framework both in Robot Framework and in Python directly.

As an example, consider the Orders library that we created as part of the Web store order robot:

from RPA.Excel.Files import Files
from RPA.Tables import Tables


class Orders:
    def get_orders(self, excel):
        files = Files()
        workbook = files.open_workbook(excel)
        rows = workbook.read_worksheet(header=True)

        tables = Tables()
        table = tables.create_table(rows)
        tables.filter_empty_rows(table)

        orders = []
        for row in table:
            first_name, last_name = row["Name"].split()
            order = {
                "item": row["Item"],
                "zip": int(row["Zip"]),
                "first_name": first_name,
                "last_name": last_name
            }
            orders.append(order)

        return orders

Here we are creating a new class called Orders, with one method called get_orders, which accepts an argument excel, containing the path to an Excel file. We are importing the Files and Tables classes from the RPA.Tables and RPA.Excel.Files modules, and using their methods in our Python code. This code resides in a file called Orders.py in the libraries subdirectory in our robot.

Adding the Orders library to our .robot code, we are then able to use the Get Orders keyword in our own keyword like this:

*** Keywords ***
Collect orders
    ${orders}=    Get orders    ${EXCEL_FILE_PATH}
    [Return]    ${orders}

Summary

Libraries add new functionalities to your robot scripts. You can add existing libraries using available Python packages such as rpaframework or create your own using Python code. You need to follow a set of simple conventions so that your Python methods are recognized as Robot Framework keywords. You can use rpaframework either in Robot Framework or import its modules into your custom Python libraries.

Learn more about Robot Framework and Python

Robot Framework User Guide - Learn how to use custom Robot Framework Python libraries

Robot Framework User Guide - Creating test libraries

Robot Framework learning resources

Python learning resources

Recommended Python learning resources

Python robot examples

August 18, 2021

Webinar