Keywords

Think of keywords in Robot Framework as functions in other programming languages.

To see a list of keyword libraries that are available on the Robocorp platform, check out the Robocorp Keyword Libraries documentation.

Consider this example script:

*** Settings ***
Documentation       Example robot that downloads a remote Excel file and opens it.

Library             RPA.Excel.Files
Library             RPA.HTTP


*** Tasks ***
Download an Excel file, open it, and close it
    Download    https://robotsparebinindustries.com/SalesData.xlsx    overwrite=True
    Open Workbook    Data.xlsx
    Close Workbook

This script has one Task that we called Download an Excel file, open it, and close it.

To accomplish the task, we call three keywords: Download, Open Workbook, and Close Workbook.

Note that keywords within tasks need to be indented with spaces.

Keyword arguments

Keywords can accept zero or more arguments. You can read each keyword's documentation to find out which arguments it supports.

*** Tasks ***
Download an Excel file, open it, and close it
    # This task executes these three keywords:
    Download    https://robotsparebinindustries.com/SalesData.xlsx    overwrite=True
    Open Workbook    Data.xlsx
    Close Workbook

In our example task, when we call the Download keyword, we are passing two arguments:

https://robotsparebinindustries.com/SalesData.xlsx: the URL to download the file from.
overwrite=True : we are telling the keyword to overwrite the file if it exists already.

The Open Workbook keyword needs one argument (the path of the Excel file to open).

The Close Workbook one does not accept any arguments.

The keyword and each of the arguments need to be separated by spaces.

Positional arguments, named arguments, and default values

The Download keyword, part of the RPA.HTTP library, supports these arguments:

url: str,
target_file: str = None,
verify: Union[bool, str] = True,
force_new_session: bool = False,
overwrite: bool = False,
stream: bool = False

The arguments target_file, verify, force_new_session, overwrite and stream all have a default value, represented by the value after the = sign. For example, the keyword, by default, will not overwrite an existing file (overwrite: bool=False). The url argument does not have a default value, so it is required.

For each argument, we are also told which type of data it accepts (string values, boolean values).

In our example, we are interested in the url and the overwrite arguments. We want to make sure that the file is overwritten each time, so we have to override the default value (False), with our own value (True).

The order in which these arguments appear matters. We can call the keyword without specifying the name of the first argument (url) like this:

*** Tasks ***
Download an Excel file
    Download    https://robotsparebinindustries.com/SalesData.xlsx

And it will work since it is the first one on the list.

The arguments can also be called explicitly by name (named arguments). In this case, the order in which they appear does not matter:

*** Tasks ***
Download an Excel file
    # These keyword calls are equivalent:
    Download
    ...    url=https://robotsparebinindustries.com/SalesData.xlsx
    ...    overwrite=True
    Download
    ...    overwrite=True
    ...    url=https://robotsparebinindustries.com/SalesData.xlsx

The two styles are often combined. For example, here we are passing the first argument by position (url), and the overwrite argument by name, which allows us to leave all other arguments to their default values.

*** Tasks ***
Download an Excel file
    # Combining positional and named arguments:
    Download
    ...    https://robotsparebinindustries.com/SalesData.xlsx
    ...    overwrite=True

Variable number of arguments

It is also possible for a keyword to accept any number of arguments. These arguments, called varargs, can be combined with mandatory arguments and arguments with default values, but they are always given after them. In the keyword documentation, they are marked with an asterisk.

For example, the Remove Files and Join Paths keywords from the OperatingSystem library have the arguments *paths and base, *parts, respectively. The former can be used with any number of arguments, but the latter requires at least one argument.

Example
    Remove Files    ${TEMPDIR}/f1.txt    ${TEMPDIR}/f2.txt    ${TEMPDIR}/f3.txt
    @{paths} =    Join Paths    ${TEMPDIR}    f1.txt    f2.txt    f3.txt    f4.txt

Adding keywords to your robot script

You can add keywords to your script in two ways:

Library keywords: Importing a library by adding it to your *** Settings *** section will allow you to use all keywords contained in the library. You can also create your own custom library.
User keywords: You can write your own keywords in a *** Keywords *** section in your script.

Creating user keywords

You can create a user keyword by combining existing keywords.

Create a *** Keywords *** section in your script, choose a name for your keyword, and call any existing keywords you need in it:

*** Keywords ***
Take a screenshot of the login page
    Open Available Browser    https://robotsparebinindustries.com/
    Capture Page Screenshot

You can then call your keyword inside a task or another keyword.

User keywords with arguments

To make the keyword more reusable, you can pass arguments to it by adding the [Arguments] setting to the keyword:

*** Keywords ***
Take a screenshot of a web page
    [Arguments]    ${url}
    Open Available Browser    ${url}
    Capture Page Screenshot

You can then call your keyword inside a task, or another keyword:

*** Tasks ***
Take screenshots
    Take a screenshot of web page    https://www.google.com
    Take a screenshot of web page    https://www.robocorp.com

You can also specify more than one argument, and default values:

*** Keywords ***
Perform a search on a search engine
    [Arguments]    ${search_url}=https://google.com/?q=    ${search_term}=robocorp
    Open Available Browser    ${search_url}${search_term}

You could then call this keyword in your task like this:

*** Tasks ***
Search using different search engines
    # No arguments passed, use the default, searching on Google for "robocorp":
    Perform a search on a search engine
    # Search for "rpa" on "duckduckgo":
    Perform a search on a search engine    https://duckduckgo.com/?q    rpa

User keywords with return values

Just like library keywords, user keywords can have return values.

Add your return value after the RETURN setting:

*** Keywords ***
Get page title of a web page
    [Arguments]    ${url}
    Open Available Browser    ${url}
    ${page_title}=    Get Title
    RETURN    ${page_title}

Note that we are assigning the result of the Get Title keyword to a variable, and then returning the variable.

You would then call the keyword in your task or another keyword like this:

*** Tasks ***
Get page titles
    ${title1}=    Get page title of a web page    https://www.google.com
    ${title2}=    Get page title of a web page    https://www.robocorp.com

User keywords documentation

Using the [Documentation] setting, you can add a description of what the keyword does:

*** Keywords ***
Get page title of a web page
    [Documentation]    Returns the title of the webpage found at the given URL.
    [Arguments]    ${url}
    Open Available Browser    ${url}
    ${page_title}=    Get Title
    RETURN    ${page_title}