Table of Contents
RPA Framework is a collection of open-source libraries and tools for Robotic Process Automation (RPA), and it is designed to be used with both Robot Framework and Python. The goal is to offer well-documented and actively maintained core libraries for Software Robot Developers.
Learn more about RPA at Robocorp Documentation.
The project is:
- 100% Open Source
- Sponsored by Robocorp
- Optimized for Robocorp Control Room and Developer Tools
- Accepting external contributions
- Homepage: https://www.github.com/robocorp/rpaframework/
- Documentation: https://rpaframework.org/
- PyPI: https://pypi.org/project/rpaframework/
- Release notes: https://rpaframework.org/releasenotes.html
- RSS feed: https://rpaframework.org/releases.xml
From the above packages rpaframework-core and rpaframework-recognition are support packages, which themselves do not contain any libraries.
The RPA Framework project currently includes the following libraries:
The x
in the PACKAGE column means that library is included in the rpaframework package and for example. x,dialogs
means that RPA.Dialogs
library is provided in both the rpaframework and rpaframework-dialogs packages.
LIBRARY NAME | DESCRIPTION | PACKAGE |
Archive | Archiving TAR and ZIP files | x |
Browser.Selenium | Control browsers and automate the web | x |
Browser.Playwright | Newer way to control browsers | special (more below) |
Cloud.AWS | Use Amazon AWS services | x,aws |
Cloud.Azure | Use Microsoft Azure services | x |
Cloud.Google | Use Google Cloud services | |
Crypto | Common hashing and encryption operations | x |
Database | Interact with databases | x |
Desktop | Cross-platform desktop automation | x |
Desktop.Clipboard | Interact with the system clipboard | x |
Desktop.OperatingSystem | Read OS information and manipulate processes | x |
Desktop.Windows | Automate Windows desktop applications | x |
Dialogs | Request user input during executions | x,dialogs |
DocumentAI | Intelligent Document Processing wrapper | x |
DocumentAI.Base64AI | Intelligent Document Processing service | x |
DocumentAI.Nanonets | Intelligent Document Processing service | x |
Email.Exchange | E-Mail operations (Exchange protocol) | x |
Email.ImapSmtp | E-Mail operations (IMAP & SMTP) | x |
Excel.Application | Control the Excel desktop application | x |
Excel.Files | Manipulate Excel files directly | x |
FileSystem | Read and manipulate files and paths | x |
FTP | Interact with FTP servers | x |
HTTP | Interact directly with web APIs | x |
Hubspot | Access HubSpot CRM data objects | x |
Images | Manipulate images | x |
JavaAccessBridge | Control Java applications | x |
JSON | Manipulate JSON objects | x |
MFA | Authenticate using one-time passwords (OTP) | x |
Notifier | Notify messages using different services | x |
Outlook.Application | Control the Outlook desktop application | x |
Read and create PDF documents | x,pdf | |
Robocorp.Process | Use the Robocorp Process API | x |
Robocorp.WorkItems | Use the Robocorp Work Items API | x |
Robocorp.Vault | Use the Robocorp Secrets API | x |
Salesforce | Salesforce operations | x |
SAP | Control SAP GUI desktop client | x |
Tables | Manipulate, sort, and filter tabular data | x |
Tasks | Control task execution | x |
Twitter API interface | x | |
Windows | Alternative library for Windows automation | x,windows |
Word.Application | Control the Word desktop application | x |
The RPA.Browser.Playwright at the moment requires special installation, because of the package size and the post install step it needs to be fully installed.
Minimum required conda.yaml to install Playwright:
channels:
- conda-forge
dependencies:
- python=3.9.13
- pip=22.1.2
- nodejs=16.4.2
- pip:
- robotframework-browser==13.3.0
- rpaframework==17.0.1
rccPostInstall:
- rfbrowser init
Learn about installing Python packages at Installing Python Packages.
Default installation method with Robocorp Developer Tools using conda.yaml:
channels:
- conda-forge
dependencies:
- python=3.9.13
- pip=22.1.2
- pip:
- rpaframework==17.0.1
To install all extra packages (including Playwright dependencies), you can use:
channels:
- conda-forge
dependencies:
- python=3.9.13
- tesseract=4.1.1
- pip=22.1.2
- nodejs=16.14.2
- pip:
- robotframework-browser==13.3.0
- rpaframework==17.0.1 # rpaframework[aws]==13.0.0
- rpaframework-aws==5.0.0
- rpaframework-google==6.1.1
- rpaframework-recognition==5.0.0
rccPostInstall:
- rfbrowser init
Separate installation of AWS, Dialogs, PDF and Windows libraries without main rpaframework:
channels:
- conda-forge
dependencies:
- python=3.9.13
- pip=22.1.2
- pip:
- rpaframework-aws==5.0.0 # included in the rpaframework as an extra
- rpaframework-dialogs==4.0.0 # included in the rpaframework by default
- rpaframework-pdf==5.0.0 # included in the rpaframework by default
- rpaframework-windows==6.0.1 # included in the rpaframework by default
Note
Python 3.7 or higher is required
After installation the libraries can be directly imported inside Robot Framework:
*** Settings ***
Library RPA.Browser.Selenium
*** Tasks ***
Login as user
Open available browser https://example.com
Input text id:user-name ${USERNAME}
Input text id:password ${PASSWORD}
The libraries are also available inside Python:
from RPA.Browser.Selenium import Selenium
lib = Selenium()
lib.open_available_browser("https://example.com")
lib.input_text("id:user-name", username)
lib.input_text("id:password", password)
- rpaframework.org for library documentation
- Robocorp Documentation for guides and tutorials
- #rpaframework channel in Robot Framework Slack if you have open questions or want to contribute
- Robocorp Forum for discussions about RPA
- Communicate with your fellow Software Robot Developers and Robocorp experts at Robocorp Developers Slack
Found a bug? Missing a critical feature? Interested in contributing? Head over to the Contribution guide to see where to get started.
Repository development is Python based and requires at minimum Python version 3.7+ installed on the development machine. The default Python version used in the Robocorp Robot template is 3.7.5 so it is a good choice for the version to install. Not recommended versions are 3.7.6 and 3.8.1, because they have issues with some of the dependencies related to rpaframework. At the time the newer Python versions starting from 3.9 are also not recommended, because some of the dependencies might cause issues.
Repository development tooling is based on basically on poetry and invoke. Poetry is the underlying tool used for compiling, building and running the package. Invoke is used for scripting purposes for example for linting, testing and publishing tasks.
First steps to start developing:
- initial poetry configuration
poetry config virtualenvs.path null
poetry config virtualenvs.in-project true
poetry config repositories.devpi "https://devpi.robocorp.cloud/ci/test"
git clone the repository
create a new Git branch or switch to correct branch or stay in master branch
- some branch naming conventions feature/name-of-feature, hotfix/name-of-the-issue, release/number-of-release
poetry install
which install package with its dependencies into the .venv directory of the package, for example packages/main/.venvif testing against Robocorp Robot which is using devdata/env.json
- set environment variables
- or
poetry build
and use resulting .whl file (in the dist/ directory) in the Robot conda.yaml - or
poetry build
and push resulting .whl file (in the dist/ directory) into a repository and use raw url to include it in the Robot conda.yaml - another possibility for Robocorp internal development is to use Robocorp devpi instance, by
poetry publish --ci
and point conda.yaml to use rpaframework version in devpi
poetry run python -m robot <ROBOT_ARGS> <TARGET_ROBOT_FILE>
- common ROBOT_ARGS from Robocorp Robot template:
--report NONE --outputdir output --logtitle "Task log"
- common ROBOT_ARGS from Robocorp Robot template:
poetry run python <TARGET_PYTHON_FILE>
invoke lint
to make sure that code formatting is according to rpaframework repository guidelines. It is possible and likely that Github action will fail the if developer has not linted the code changes. Code formatting is based on black and flake8 and those are run with theinvoke lint
.the library documentation can be created in the repository root (so called "meta" package level). The documentation is built by the docgen tools using the locally installed version of the project, local changes for the main package will be reflected each time you generate the docs, but if you want to see local changes for optional packages, you must utilize
invoke install-local --package <package_name>
using the appropriate package name (e.g.,rpaframework-aws
). This will reinstall that package as a local editable version instead of from PyPI. Multiple such packages can be added by repeating the use of the--package
option. In order to reset this, useinvoke install --reset
.poetry update
and/orinvoke install-local --package <package name>
make docs
- open
docs/build/html/index.html
with the browser to view the changes or executemake local
and navigate tolocalhost:8000
to view docs as a live local webpage.
# Before [tool.poetry.dependencies] python = "^3.7" rpaframework = { path = "packages/main", extras = ["cv", "playwright", "aws"] } rpaframework-google = "^4.0.0" rpaframework-windows = "^4.0.0" # After [tool.poetry.dependencies] python = "^3.7" rpaframework = { path = "packages/main", extras = ["cv", "playwright"] } rpaframework-aws = { path = "packages/aws" } rpaframework-google = "^4.0.0" rpaframework-windows = "^4.0.0"
invoke test
(this will run both Python unittests and robotframework tests defined in the packages tests/ directory)- to run specific Python test:
poetry run pytest path/to/test.py::test_function
- to run specific Robotframework test:
inv testrobot -r <robot_name> -t <task_name>
- to run specific Python test:
git commit changes
git push changes to remote
create pull request from the branch describing changes included in the description
update docs/source/releasenotes.rst with changes (commit and push)
Packaging and publishing are done after changes have been merged into master branch. All the following steps should be done within master branch.
- git pull latest changes into master branch
- in the package directory containing changes execute
invoke lint
andinvoke test
- update pyproject.toml with new version according to semantic versioning
- update docs/source/releasenotes.rst with changes
- in the repository root (so called "meta" package level) run command
poetry update
- git commit changed poetry.lock files (on meta and target package level), releasenotes.rst and pyproject.toml with message "PACKAGE. version x.y.z"
- git push
invoke publish
after Github action on master branch is all green
Some recommended tools for development
Visual Studio Code as a code editor with following extensions:
GitHub Desktop will make version management less prone to errors
This project is open-source and licensed under the terms of the Apache License 2.0.